IRC Bouncer on a Pi

Internet Relay Chat is one of the original forms of social media. It was once the go-to destination for socializing with online communities. IRC has been around the 80’s and isn’t going to fade away any time soon.

The way IRC works is similar to a typical client-server model. IRC servers are hosted all around the globe by many universities, individuals and ISPs. These servers may be organised under ‘networks’. Each IRC network hosts many ‘channels’ which are chat rooms, groups, multi-user conferences, however you may put that. Users use their IRC clients to connect to one of the hundred IRC servers in the global pool with a unique nickname and then join a channel discussing a topic of interest. Some patience is all it needs to join the world of IRC.

Screenshot of a typical IRC channel conversation
Screenshot of a typical IRC channel conversation

The most popular IRC networks are Freenode, IRCnet, EFnet, UnderNet, Snoonet, Rizon, OFTC and DALnet. There are hundreds of networks apart from the ones mentioned above. Many of these networks date back to 90’s and are still well active, thanks to the awesome IRC community. Freenode is popular for open-source projects, while Snoonet is the destination for redditors.

It is assumed that you actually know how to remote into a Pi and are comfortable with terminals.

Getting an IRC Client

Clients exist for all major operating systems, there’s one for everyone. HexChat is available for Windows, in the App Store for OS X, in the repositories of most GNU/Linux distributions. YAAIC and Revolution IRC are some good clients available for Android. Irssi and WeeChat are the most popular terminal based clients. You can refer Elle K’s post on the Linux Academy for a list of the popular IRC clients.

Installation of the IRC client is to be done on the system on which you will read your messages on. This can be your laptop, netbook, desktop or smartphone. For this blog post, we will use HexChat, a free and open-source IRC client. To install HexChat on Windows, go to the official website of the project and head over to the Downloads section. Download the Windows 7+ version release and follow the instructions. In case using OS X, you can go with the Textual IRC Client which has good support for Macs.

On Debian, HexChat can be installed by executing the following command:

sudo apt install hexchat

On Arch Linux and Arch-based distributions using pacman, HexChat can be installed by executing the following command:

sudo pacman -S hexchat

The Flatpak version of HexChat can be installed from Flathub by executing the following command, as suggested by one of the HexChat developers:

sudo flatpak install

We do not necessarily need a client on the Pi, and we won’t actually need to install anything on the Pi until a few sections later. If you want to have a client on the Pi, I recommend installing a terminal-based client like WeeChat that you can access with SSH.

Installation of HexChat on Pop!_OS
Installation of HexChat on Pop!_OS

Configuring the Client

Upon opening HexChat, you will be presented with a dialog box asking you to enter your username and a list of nicknames in case the primary nickname is not available (we will use BlogMan as an example). Once you have filled in the said fields, select a network from the many options given. We will choose Freenode as an example for the sake of this blog post. You are free to choose any network you feel like, after you are aware of the philosophy of the said network. For instance, Freenode provides facilities to peer-directed project communities, including those of free and open source software.

HexChat Network List
HexChat Network List

Joining a Network

Developers of HexChat have made it easier to connect to a network by putting together a list of popular IRC networks along with their respective servers. You can view, as well as change what particular server is being used to connect to that network. To do this, click on the Edit button on the same dialog box.

Server Configuration in HexChat

In this case, we see that has been selected for us, and that is, the server we will be connecting to, in order to join the Freenode network. Note that we have not yet registered on this network, and therefore, we do not need to provide a password in the indicated field. If you are already registered, then you should enter your password and select the apt login method. For the sake of this post, we will be doing everything from scratch.

Once you are have checked out the various settings available in this window, close it by clicking on the Close button at the bottom.

To connect to this network, press on the Connect button on the previous dialog box. It shall open a new window with lots of text flying by. What actually happens is that the IRC server checks your IP address, and determines the machine’s hostname (by running a reverse DNS query) from which you are connecting from. You may / may not receive warnings like hostname not found, or couldn’t get ident response, which can be ignored at this point. You may also see a dialog box pop up, titled something along the lines of Connection Complete, which can be closed.

HexChat Main Window upon connecting to Freenode
HexChat Main Window upon connecting to Freenode

Most IRC servers have the policies and guidelines, or links to them configured to be displayed whenever a client connects to them, this is called Message of the Day (pink text above) and can be viewed by sending /motd to this window (referred to, as the server window). Commands to the IRC server or your IRC client usually start with a forward slash (/). They are to be typed in the text input field besides the nickname you had chosen during the initial configuration of the IRC client. If you wish to change your nickname after you have connected to the server, you may do so by sending /nick <your-new-nickname-goes-here> to the server window.

It is to be noted that the nickname that you just chose does not belong to you as of now, and can be used by anyone if you disconnect from the server. To restrict the nickname to your account, we have to register to the network. This is a necessary step if you have to join IRC channels which require the users to be registered to the network. It is totally optional for those who do not join those channels.

In order to register to Freenode, send /msg NickServ register <super-secret-password> <valid-e-mail-address> to the server window. Once, you send that message to the server, you might receive messages like the ones given below, indicating the dispersal of a confirmation mail.

-NickServ-: An email containing nickname activation instructions has been sent to [email protected]
-NickServ-: If you do not complete registration within one day, your nickname will expire.
-NickServ-: BlogMan is now registered to [email protected], with the password xxxxxxxxx.
-NickServ-: For frequently-asked questions about the network, please see the
-NickServ-: Knowledge Base page ( Should you need more
-NickServ-: help you can /join #freenode to find network staff.

Follow the instructions given in the mail that will be sent to you. Most probably, you will be given a message like /msg NickServ VERIFY REGISTER <nickname> <confirmation-code that you have to send to the server. Once you send this message to the server, you will receive messages like:

-NickServ-: BlogMan has now been verified.
-NickServ-: Thank you for verifying your e-mail address! You have taken steps in ensuring that your registrations are not exploited.

This message confirms your registration to the Freenode network. We can now edit our HexChat settings to reflect this. Go to HexChat > Network List and click on the Edit button in the dialog box that pops up. Change the Login Method to NickServ (/msg NickServ <password>) and enter your password in the Password field. Click on Close to save the settings and close the dialog box. Close the Network List and then quit HexChat.

Upon starting HexChat again, you should be automatically connected to the Freenode network and your server window may look like this:

Joining Freenode after registration
Joining Freenode after registration

The message to look out for, is You are now identified for <nickname>, which indicates we have logged into that network. You can view more information about your account by sending /msg NickServ info. So far, so good!

Curious about NickServ? It is a ‘service’ maintained by the IRC network to provide their users with an automated ‘bot’ and access to certain ‘features’. There are services like ChanServ and HostServ, availability of which, depends upon the network you are connecting to. Read more about IRC Services on Wikipedia.

Joining a Channel

In order to join a channel, send /join #<channelname> to the server window. Freenode maintains the #freenode channel as a general discussion and help platform. To join #freenode, send /join #freenode to the server window. A new tab will open up and you have, thus, joined an IRC channel, congratulations! All users in that channel will get a notification that you have joined. Practice good safety and privacy practices on IRC! Your attitude and the time of the day will determine the kind of response you will get from the community, trust me!

#freenode on the Freenode network
#freenode on the Freenode network

The HexChat layout is such that, you have the list of channels and servers you are connected to, on the very left hand side of the window. The list of users in that channel are listed on the extreme right. The users which have icons in front of their name are the channel ‘operators’ or are ‘voiced’ users. In the central part, the topic window is present on the top which shows the current topic of the channel, the message pane takes up the majority of the window and the bottom pane is divided into a small label showing the current nickname and the message/command field. Complete documentation for HexChat can be found on their website.

If you are not into setting up a Pi, or are just casually lurking on this blog, this is all it needs to get on to IRC. The next sections explain how to actually set up an IRC bouncer on the Pi.

Need for IRC Bouncers

If you don’t have a stable Internet connection, you will frequently get disconnected from the network. This will result in your client receiving none of the messages that were sent to the channel by the users. It can be heartbreaking if you sent an important message, are anticipating a reply and your connection drops. Not only you will curse your service provider, you will not be able to view the messages once you get connected, you will lose all the messages sent during that period. No, you will not be able to scroll up and wish that the messages appeared from nowhere. IRC is a simple protocol, messages are relayed only to the active clients during any point of time.

The most elegant solution to this problem is to use a bounced network connection wherein a daemon (not demon) keeps an active connection to the IRC server and ‘keeps you alive’ on the network. Instead of connecting directly to the IRC server, you would then connect to an instance of the server, which would be actually connected to the IRC server, providing you the service of a bounced network connection (henceforth called a bouncer). The clear advantage of such a setup is that in the situation of your client losing connection to the bouncer, the messages are stored on the bouncer as a buffer.

Whenever your client reconnects to the bouncer, the bouncer ‘replays’ the buffer to the client so you get to be a part of a meaningful line of conversation, and yes, you also get to view the reply you had been expecting earlier. For this reason, we are setting up the bouncer on a Pi which shall be connected to a stable Internet connection, if you don’t have that, you might look for a third-party, managed ZNC solution, some of them are free too. Refer ZNC’s wiki entry on Providers.

Bounced network connections are not as uncommon as you might think. Mail, FTP and VPN services also benefit from the concept of ‘bouncing’ apart from IRC. We are fanboys of free and open-source software, hence, our IRC bouncer also has to comply to our philosophy. There are many IRC bouncers available out there, but again, for the sake of this post, we will be flying ZNC on our Pi. The official ZNC wiki, provides an appropriate graphic depicting our situation.

Bounced IRC Connection Infographic


Installing ZNC on Pi

Assuming you run either Raspbian or Arch ARM, it is our pleasure that ZNC is already available in the official repositories. Once connected to your Pi over SSH, execute sudo apt install znc for Raspbian or sudo pacman -S znc for Arch ARM. Upon completion of ZNC, we have to perform some housekeeping before we configure our shiny new instance of ZNC. Though most instructions are for a Pi, this is applicable to any server running a GNU/Linux distribution. Things may change if you are using a BSD or Windows server. In that case, refer ZNC’s wiki entry on Installation.

The first task is to set up a reverse proxy to ZNC so that we can use our existing domain and setup a cool subdomain like Next, we would be generating Let’s Encrypt SSL certificates and deploy them to the reverse proxy as well as make them available to ZNC to allow us to access IRC over SSL. These are optional steps but are recommended for security reasons. Get NGINX and CertBot installed, if you haven’t installed them, by executing sudo apt install nginx certbot python3-certbot-nginx or sudo pacman -S nginx certbot certbot-nginx as your case may be.

We will be using NGINX as our reverse proxy and in order to do so, make a new file in /etc/nginx/sites-enabled (say /etc/nginx/sites-enabled/irc) and set up a virtual host in NGINX as shown below:

server {
    listen 80;
    listen [::]:80;

    location / {
        proxy_pass https://<local-ip-of-your-pi>:6697/;
        proxy_buffering off;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

Once you have set everything up, execute sudo systemctl enable --now nginx to run NGINX on startup. To generate the SSL certificates, execute sudo certbot and follow the prompts. The server configuration will be automatically updated with HTTP/2 support and SSL ports and certificates correctly configured. If you are using a firewall, don’t forget to allow ports 80, 443, and 6697. A reference is given below:

[[email protected]]:$ sudo certbot
Saving debug log to /var/log/letsencrypt/letsencrypt.log
Plugins selected: Authenticator nginx, Installer nginx
Enter email address (used for urgent renewal and security notices) (Enter 'c' to
cancel): [email protected]

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Please read the Terms of Service at You must
agree in order to register with the ACME server at
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
(A)gree/(C)ancel: A

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Would you be willing to share your email address with the Electronic Frontier
Foundation, a founding partner of the Let's Encrypt project and the non-profit
organization that develops Certbot? We'd like to send you email about our work
encrypting the web, EFF news, campaigns, and ways to support digital freedom.
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
(Y)es/(N)o: Y

Which names would you like to activate HTTPS for?
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Select the appropriate numbers separated by commas and/or spaces, or leave input
blank to select all options shown (Enter 'c' to cancel): 1
Obtaining a new certificate
Please choose whether or not to redirect HTTP traffic to HTTPS, removing HTTP access.
1: No redirect - Make no further changes to the webserver configuration.
2: Redirect - Make all requests redirect to secure HTTPS access. Choose this for
new sites, or if you're confident your site works on HTTPS. You can undo this
change by editing your web server's configuration.
Select the appropriate number [1-2] then [enter] (press 'c' to cancel): 2
 - Congratulations! Your certificate and chain have been saved at
   /etc/letsencrypt/live/ Your cert will
   expire on 2018-06-06. To obtain a new or tweaked version of this
   certificate in the future, simply run certbot again with the
   "certonly" option. To non-interactively renew *all* of your
   certificates, run "certbot renew"
 - Your account credentials have been saved in your Certbot
   configuration directory at /etc/letsencrypt. You should make a
   secure backup of this folder now. This configuration directory will
   also contain certificates and private keys obtained by Certbot so
   making regular backups of this folder is ideal.
 - If you like Certbot, please consider supporting our work by:

   Donating to ISRG / Let's Encrypt:
   Donating to EFF:          
[[email protected]]:$

Once you have successfully generated the certificates, execute sudo nginx -s reload to check if NGINX has been successfully configured or not. If everything goes fine, hopefully, make a new directory .znc in your home directory by executing mkdir ~/.znc and concatenate the certificate and the private key into a single file by executing the following command to make it available to ZNC later.

sudo cat /etc/letsencrypt/live/{fullchain,privkey}.pem > ~/.znc/znc.pem

In case you are curious, CertBot adds the following to our server configuration:

listen [::]:443 ssl ipv6only=on;
listen 443 ssl http2;
ssl_certificate /etc/letsencrypt/live/;
ssl_certificate_key /etc/letsencrypt/live/;
include /etc/letsencrypt/options-ssl-nginx.conf;
ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;

Do not forget to add the ‘A’ DNS record for the irc subdomain with your registrar or DNS service provider (e.g. Cloudflare). Also, don’t allow this subdomain to be proxied by a HTTP proxy such as the one Cloudflare provides. In case of Cloudflare, turn that orange cloud to a grey one.

Note that the SSL certificate has to be renewed every 75 days as Let’s Encrypt certificates are valid for only 90 days. In order to renew them, execute sudo certbot renew when the dates are near. You also have to re-concatenate the certificate and private key, and restart ZNC to make the renewed certificate available to it. Refer ZNC’s wiki entry on Signed SSL certificates to set up a CertBot ‘hook’ to automate the process.

Setting up a ZNC Server

Given that our NGINX and SSL certificates are ready, we are now ready to set up ZNC on our Pi. Execute znc --makeconf and answer the prompted questions aptly. Reference the sample below:

[[email protected]]:$ znc --makeconf
[ .. ] Checking for list of available modules...
[ ** ] 
[ ** ] -- Global settings --
[ ** ] 
[ ?? ] Listen on port (1025 to 65534): 6697
[ ?? ] Listen using SSL (yes/no) [no]: yes
[ ?? ] Listen using both IPv4 and IPv6 (yes/no) [yes]: yes
[ .. ] Verifying the listener...
[ ** ] Located pem file: [/home/pi/.znc/znc.pem]
[ ** ] Enabled global modules [webadmin]
[ ** ] 
[ ** ] -- Admin user settings --
[ ** ] 
[ ?? ] Username (alphanumeric): BlogMan
[ ?? ] Enter password: 
[ ?? ] Confirm password: 
[ ?? ] Nick [BlogMan]: 
[ ?? ] Alternate nick [BlogMan_]: 
[ ?? ] Ident [BlogMan]: 
[ ?? ] Real name (optional): Blog Man
[ ?? ] Bind host (optional): 
[ ** ] Enabled user modules [chansaver, controlpanel]
[ ** ] 
[ ?? ] Set up a network? (yes/no) [yes]: yes
[ ** ] 
[ ** ] -- Network settings --
[ ** ] 
[ ?? ] Name [freenode]: 
[ ?? ] Server host []:
[ ?? ] Server uses SSL? (yes/no) [yes]: yes
[ ?? ] Server port (1 to 65535) [6697]: 
[ ?? ] Server password (probably empty): xxxxxx
[ ?? ] Initial channels: 
[ ** ] Enabled network modules [simple_away]
[ ** ] 
[ .. ] Writing config [/home/pi/.znc/configs/znc.conf]...
[ ** ] 
[ ** ] To connect to this ZNC you need to connect to it as your IRC server
[ ** ] using the port that you supplied.  You have to supply your login info
[ ** ] as the IRC server password like this: user/network:pass.
[ ** ] 
[ ** ] Try something like this in your IRC client...
[ ** ] /server <znc_server_ip> +6697 BlogMan/<network-name>:<pass>
[ ** ] 
[ ** ] To manage settings, users and networks, point your web browser to
[ ** ] https://<znc_server_ip>:6697/
[ ** ] 
[ ?? ] Launch ZNC now? (yes/no) [yes]:    
[ .. ] Opening config [/home/sudipto/.znc/configs/znc.conf]...
[ .. ] Loading global module [webadmin]...
[ .. ] Binding to port [+6697]...
[ ** ] Loading user [BlogMan]
[ ** ] Loading network [freenode]
[ .. ] Loading network module [simple_away]...
[ >> ] [/usr/lib/znc/]
[ .. ] Adding server [ +6697 xxxxxx]...
[ .. ] Loading user module [chansaver]...
[ .. ] Loading user module [controlpanel]...
[ .. ] Forking into the background...
[ >> ] [pid: 29952]
[ ** ] ZNC 1.6.5+deb1+deb9u1 -
[[email protected]]:$

One more step is required, otherwise, you can get errors like ‘Your session is not allowed for this IP’. To deal with this add the following lines to ~/.znc/configs/znc.conf, kill the ZNC process by executing sudo pkill znc and start it again by executing znc.

TrustedProxy =
TrustedProxy = ::1

Fire up your web browser and navigate to You should be welcomed by the default ZNC welcome page. Sign in to ZNC with the admin username and password as you had set in the Admin user settings above. You will be presented with ZNC’s webadmin portal.

ZNC's webadmin portal
ZNC’s webadmin portal

You have now successfully set up ZNC if you get to this page. We will discuss how to add more networks to ZNC once we verify that the connection to ZNC actually works. You can now explore various other settings available on the portal. For more, refer ZNC’s wiki entry on webadmin.

Connecting to ZNC

Let’s move over to HexChat now. Go to the Network List (HexChat > Network List) and edit the network we are currently connected to, in this case, Freenode. We make sure that Connect to this network automatically is unchecked. Next, click on Close and close the HexChat Network List. Right click on the network’s server window entry (list on the extreme left hand side) in HexChat and click Close. This will quit HexChat.

Fire up HexChat one last time, seriously, trust me. Click on Add button while on the Network List, type a custom network name, say Ghosh Freenode and press enter/return. Now we’ll Edit this network and add ZNC as our server. Click on the selected server, most probably newserver/6667 and click on Edit, type out your server’s address and port in server-address/port format ( and press enter/return. Check the Use SSL for all servers on this network option. Uncheck Use global user information and fill out your nickname, a secondary choice, real name and username. Note that the username should be in <znc-admin-username>/<network-name> format (BlogMan/freenode). Select Server Password as the Login Method and enter your admin user password in the Password field. Optionally, check the Connect to this network automatically field.

Keep in mind, in case, you went with a self signed certificate or something else, do check that Accept invalid SSL certificates field. Don’t worry, if you used Let’s Encrypt certificates, this step is not necessary

Custom ZNC Server Setup in HexChat
Custom ZNC Server Setup in HexChat

When done, Close this window, select our custom My Freenode network and click on Connect. Hopefully, you will now be connected to Freenode and be logged in into your registered Freenode account. That was one long journey, no? It’s worth it, believe me!

HexChat connected to Freenode via ZNC
HexChat connected to Freenode via ZNC

You may want to have a few moments to yourself and stroll around in a garden after achieving this feat. And you know what, maybe even buy me a coffee 😂.

Final Touch-up

Changing ZNC Skins

Take my advice, switch over to your web browser which has the ZNC webadmin open and go to Your Settings > Skin (scroll down to the end), select a skin of your choice (I prefer dark-clouds), and click Save and Continue.

Adding IRC Networks

In Your Settings, scroll down to Networks and click on [Add]. Fill all the relevant information, add the servers for the network you want to add (most networks have either an official or unofficial server list that you can get by carefully going through the respective network’s website or by politely asking around in the main support channel of the network) and go through the relevant settings for that network. The server address must be added in the <irc-server-address> [+]<port> <password> in the respective field.

You might have to enable some modules in order to connect to some networks. For instance, certauth must be enabled for SSL certificate fingerprint based login and perform must be enabled for performing custom commands once connected to certain networks like UnderNet and QuakeNet. In order to use the newly added network, add a custom network in your IRC client with <znc-admin-username>/<network-name> as the username in your client.

Adding a network on ZNC
Adding a network on ZNC

Reconnecting ZNC to IRC

While connected to a network via ZNC on a client, send /msg *status jump to reconnect to the IRC server. It might take a while, and you may receive some disconnection warnings. This may indicate slower network or ping times, but are normal. It will eventually succeed, and you will receive Connected! from *status.

Configuring ZNC as a Service

We want our ZNC server to startup automatically after boot, and be able to restart it when we make manual changes to the configuration. To do these tasks, it is better to install a system service for ZNC. Starting off, make a new file called znc.service in the /etc/systemd/system/ directory with the following content:

Description=ZNC, an advanced IRC bouncer

ExecStart=/usr/bin/znc -f --datadir=/home/pi/.znc


Now, we kill any running instance of ZNC with sudo pkill znc and enable the system service we just created, by executing the sudo systemctl enable --now znc command. We then check the status of our service by executing sudo systemctl status znc, which in an ideal world, should give us the following output:

● znc.service - ZNC, an advanced IRC bouncer
   Loaded: loaded (/etc/systemd/system/znc.service; enabled; vendor preset: enabled)
   Active: active (running) since Tue 2019-03-12 06:57:21 IST; 3s ago
 Main PID: 12517 (znc)
    Tasks: 2 (limit: 2299)
   CGroup: /system.slice/znc.service
           └─12517 /usr/bin/znc -f --datadir=/home/pi/.znc

If it is running, congratulations! If not, verify if ZNC actually starts if you execute znc in the terminal.

Adding Additional Users

On ZNC webadmin, head over to the Manage Users tab under Global Modules. Then click on [Add] to be taken to a form wherein you are expected to set up the username, password and nicknames for your new user. It is okay to leave some the fields blank, in case you are comfortable going with defaults. Once done, Save and Continue to add the networks and enable the required modules for that user. That’s how to add users in a nutshell.

These users can login from their preffered clients either with <znc-username>/<network-name> as their username and <znc-password> as their password if their client supports server passwords, or with <znc-username> as their username and <znc-username>/<network-name>:<znc-password> as their password.

Setup CertFP Login (optional)

Some networks offer a slightly secure method of authenticating to the actual IRC server. On ZNC webadmin, go to Your Settings, scroll down to Modules, check the checkbox in front of the cert module and click on Save and Continue.

If you have a PEM certificate for yourself or your organisation, you have to concatenate the certificate and the key to a single file called user.pem and paste the entire contents of user.pem in the input field of the Certificate tab under User Modules and click on Update. Reconnect to the network by following the instructions above.

Once connected to the network, execute /msg NickServ cert add to add the certificate fingerprint to the account on that network. If you reconnect again, you shall see something along the lines of user has a client certificate fingerprint xxxxxxxxxxxxxxxxx if you execute /msg NickServ info (in case of Rizon and DALnet: /msg NickServ info <nickname> all).

CertFP accomplished!

Setup SASL Login (optional)

SASL authentication is more secure than the usual NickServ or perform based authentication methods. This is because you will be authenticated to the IRC server ‘before’ you are even ‘visible’ on the server. To start using SASL, first confirm with your network if they support SASL. Freenode, OFTC, Rizon, and Snoonet do support SASL.

Enable the sasl module in Your Settings similar to enabling cert in the previous section. Reconnect to ZNC by going to HexChat and selecting Server > Reconnect. Once reconnected to ZNC, execute /msg *sasl mechanism external plain and /msg *sasl requireauth yes in the server window.

In case you have setup CertFP above and your network supports both CertFP and SASL, you are done! If not, then execute /msg *sasl set <username> <password>. Reconnect ZNC to the IRC server by executing /msg *status jump.

SASL accomplished!

Authenticate using SSL Certificate (optional)

Head over to Global Settings on ZNC webadmin, enable the certauth module and Save and Return. If you have a PEM certificate for yourself or your organisation, you have to concatenate the certificate and the key to a single file called client.pem. Generate the SHA1 fingerprint for this certificate by executing openssl x509 -sha1 -noout -fingerprint -in client.pem | sed -e 's/^.*=//;s/://g;y/ABCDEF/abcdef/' in a terminal.

Switch to the certauth tab under Global Modules and paste the client fingerprint in the Key field and click on Add Key. Now, we have to configure our client to use this client certificate. In case of HexChat, copy this certificate-key combined PEM file renamed as client.pem to ~/.config/hexchat/certs/client.pem on GNU/Linux based distributions, and if using Windows, copy that to %APPDATA%\HexChat\certs\client.pem. If the certs folder does not exist, create that!

Relaunch HexChat and whistle away!

Accessing ZNC from Smartphones

Many IRC clients exist for Android, I would recommend Revolution IRC and YAAIC as I have personally tested them. Whichever client you prefer to use, add a server with the server address being the address of your ZNC server, and port being the port ZNC uses. Check any field that mentions SSL/TLS. Use the nickname, and ZNC username in the usual format (for e.g. znc-admin-username only, do not append /<network-name>). Use <znc-username>/<network-name>:<znc-password> as the password. In case using iOS, you can try Mutter IRC.


Let me summarize the idea of IRC again in this part of the post. Sure, it might seem difficult to appreciate IRC as a form of regular life in the modern day when we have neat user interfaces and tap-and-go alternatives, the simplicity of a text-based network lies in the fact that you feel humanely connected to the community, not attached to the platform itself. This is the biggest shock you will face if you are new to IRC, nothing more. Each community will have their own pace and style of conversation, and who knows, you may end up on awesome channels like #casualconversation on Snoonet where you get to meet to awesome souls like Ei8ht, bicycle, jacod1982, ViolentViola, A_Dragon, and salmonhatt who’ll cheer you up 😀 or you may come across the awesome grungy on #Rizon. In the end, I have only a final suggestion, you should try IRC once if you haven’t. Cheers!

If you have had any problem with setting up your IRC client or ZNC server, do check out the official documentations or comment below.

Further Reading


  1. You made typo in “sudo apt install nginx cerbot python3-certbot-nginx or sudo pacman -S nginx certbot certbot-nginx”
    It should be certbot not cerbot

  2. A very well written guide, but being new to the PI and Linux what I struggle with is to understand how the part is working. I do own a domain – no server with space attached, just the domain. I can go to the domain hoster and create a subdomain. But what after that to make it connect to the pie and be allowed to use as a reverse proxy?

    1. Use a web server like NGINX to use it as a reverse proxy, ZNC by itself runs on specific ports in which the IRC port needs to be open all the time, the other port is for the web administration dashboard for which you would use NGINX.

  3. Hey there,

    Brilliant tutorial. I already followed this one ( and managed to get my ZNC running on raspberry pi. I am having one little niggle, having purchased a domain name, I would like to link ZNC to my domain for nick whois purposes, so that my IP (or IP of my home ZNC/raspi server) remains hidden – and instead, upon whois people see my domain name. I have already modified A settings of my domain, but I still can’t seem to go about changing my IP to my domain name. Can you please help with that and include that in your tutorial, as that may help others as well.

    Thank you if you do, thank you if you don’t. But, if you do, please do it in layman’s terms.


    1. I answered it one of your other comments, for that to work, your reverse DNS has to be set up correctly so that your IP address uniquely identifies your domain name and vice versa.

  4. Hi Sudipto,

    Thank you for a great in-depth tutorial. I managed to install ZNC and it works too, but I cannot figure out how to mask my ZNC server’s IP address on IRC? I have a domain name and I would like the ZNC to show my whois IP to be that domain name. Any ideas?

    Many thanks!

    1. If you want the domain of your server to be shown as the mask on IRC, you have to configure the reverse DNS (rDNS) properly. Not all providers provide this facility. On some networks, you might have to request Host Masks.

Leave a reply