System Crafters

ZNC Bouncer Server Setup

An IRC bouncer server stays connected to IRC at all times on your behalf so that when you connect to it you can read all the messages that were sent to your channels while you were offline. This allows you to disconnect your client from the IRC server without losing context for the conversation or missing potentially relevant messages. When you reconnect, the ZNC bouncer server provides a replay of the conversation you missed while you were gone.

Several members of the System Crafters community are running their own ZNC servers. Below is a tutorial for setting up a TLS/SSL enabled bouncer server using ZNC, Let's Encrypt, and CentOS. There has been some discussion about providing a multi-user server that members of the System Crafters community can use. Please contact #systemcrafters IRC users daviwil or nackjicholson if you would be interested in using a community bouncer server. The features of ZNC enable clearer and more fluid communication. We enjoy using IRC and want to know if a community ZNC bouncer server would be well utilized and beneficial for our communication.

External Resources

Tutorial: ZNC with SSL/TLS on CentOS

The following commands and configuration instructions will set up a secure ZNC server for personal use. You will need a CentOS 7 server or virtual machine, as well as a registered domain name. In the tutorial will be used as the target domain name, and the ZNC server will be configured to run on port 6697.


$ sudo yum update
$ sudo yum install certbot znc


Opening necessary ports for certbot and ZNC.

$ sudo firewall-cmd --zone=public --permanent --add-service=http
$ sudo firewall-cmd --zone=public --permanent --add-service=https
$ sudo firewall-cmd --add-port=6697/tcp
$ sudo firewall-cmd --runtime-to-permanent

Note: Some browsers, like Google Chrome block port 6697 (amongst others) by default because it's commonly used for IRC networks (and thus not HTTP). One can remedy that by either switching to another port (both in the firewall settings and the ZNC configuration) or by forcing Chrome to explicitly allow it:

chromium --explicitly-allowed-ports=6697

Use a Let's Encrypt Certificate with ZNC

Let's Encrypt is a service that enables people to use SSL encryption more easily on the internet. Signed and verified certificates can be acquired using a simple CLI tool called certbot. The certificates expire rather quickly, and this is why auto-renewal steps are also shown below.

$ sudo certbot certonly --standalone --preferred-challenges http --http-01-port 80 -d

In order to work over SSL, ZNC expects a combined cert file znc.pem to be accessible to it in the znc home path /var/lib/znc/.znc.

$ sudo cat /etc/letsencrypt/live/{privkey,fullchain}.pem > znc.pem
$ sudo mv znc.pem /var/lib/znc/.znc/
$ sudo chown znc:znc /var/lib/znc/.znc/znc.pem

Make a crontab and renewal script to automatically check Let's Encrypt for certificate updates, and trigger a change to znc.pem when certificates are renewed.

$ sudo touch /etc/letsencrypt/renewal-hooks/deploy/update-znc.pem
$ sudo chmod +x /etc/letsencrypt/renewal-hooks/deploy/update-znc.pem

Copy the following into the update-znc.pem file using a text editor i.e. sudo vi /etc/letsencrypt/renewal-hooks/deploy/update-znc.pem.


[[ $RENEWED_LINEAGE != "/etc/letsencrypt/live/$YOURDOMAIN" ]] && exit 0
echo "Updating certs"
cat /etc/letsencrypt/live/$YOURDOMAIN/{privkey,fullchain}.pem > /var/lib/znc/.znc/znc.pem

Add this to cron by running crontab -e. This will attempt renewal everyday at 3:15 a.m. you can change this time to any time you like.

15 3 * * * /usr/bin/certbot renew --quiet

Running ZNC.

$ sudo -u znc znc --makeconf

Fill in the subsequent prompts with details that make sense for yourself.

[ ?? ] Username (alphanumeric): willvaughn
[ ?? ] Enter password:
[ ?? ] Confirm password:
[ ?? ] Nick [willvaughn]: nackjicholson
[ ?? ] Alternate nick [nackjicholson_]:
[ ?? ] Ident [willvaughn]: nackjicholson
[ ?? ] Real name (optional): William Vaughn
[ ?? ] Bind host (optional):
[ ** ] Enabled user modules [chansaver, controlpanel]
[ ** ]
[ ?? ] Set up a network? (yes/no) [yes]:
[ ** ]
[ ** ] -- Network settings --
[ ** ]
[ ?? ] Name [freenode]: libera
[ ?? ] Server host (host only):
[ ?? ] Server uses SSL? (yes/no) [no]: yes
[ ?? ] Server port (1 to 65535) [6697]: 6697
[ ?? ] Server password (probably empty):
[ ?? ] Initial channels:

Run the ZNC systemd service.

$ sudo systemctl start znc
$ sudo systemctl enable znc

You should now be able to visit to use the ZNC web frontend. You can also connect to ZNC using erc-tls. If your browser blocks the 6697 port, read up on configuring settings to work around that on the znc wiki here.

(erc-tls :server "" :port 6697 :nick "nackjicholson" :password "willvaughn/libera:<my-znc-user-password>")

Tips, Tricks, and Troubleshooting

Please add your own timps and tricks by editing the wiki.

Fixing your nick

Occasionally, the ZNC server may log you in as your alternate name. Usually that will mean that your name will have a trailing _ on it. If you get stuck like that and it's not because your main nick is also logged in on another client, there is a trick to switching back to the main nick. By typing /nick <your-desired-name> in your client you can trigger the ZNC server to configure a different nickname for this session. Then quitting and reconnecting should use the changed nickname that is configured.