ZNC IRC Bouncer Setup Guide for Debian
Date: 2021-08-24
In this guide you're going setup a ZNC IRC bouncer daemon (server) for Debian 10.7 systems. It's expected of you to be familiar to some degree in how IRC functions and proficient in obtaining a domain name, a TLS certificate, and server hosting.
Installing ZNC
Before you begin with installing any additional packages, go ahead and make sure that the system is up-to-date. You should reboot the server after the fact to apply any kernal updates.
apt update
apt upgrade
With the updates out of the way, install znc.
apt install znc
Now configure a directory where the ZNC configurations will live. /var/lib/znc is a good place, but you can place it wherever you want, just make note of where.
mkdir -p /var/lib/znc
You'll also need a service account that will be dedicated for executing ZNC. You don't want it running under the root user.
| Note |
| For now the service account will require a login shell so that you can make some initial configurations. You will change this later though. |
useradd --system --comment "Account for ZNC to run as" --shell /bin/bash --home-dir /var/lib/znc znc
Set your ZNC service account as the owner of the directory you created previously
chmod "znc:znc" /var/lib/znc
[Return to top]
Configuring ZNC
Switch to your znc service account
su znc
Make sure that you are in the /var/lib/znc directory. From here you can run the following command to build the ZNC configuration.
znc --makeconf
Below is an example configuration.
Listen on port (1025 to 65534): 6698
Listen using SSL: yes
Listen using both IPv4 and IPv6: yes
Username (alphanumeric): type-any-username-here
Enter password: ****************
Confirm password: ****************
Nick [username]: you can press return here to accept default
Alternate nic [username_]: you can press return here to accept default
Ident [username]: you can press return here to accept default
Set up a network?: no
Launch ZNC now?: no
Now change directory into .znc/config and point the config to your TLS certificate. This guide is using Let's Encrypt for TLS certification.
vi /var/lib/znc/.znc/configs/znc.conf
You can add the following above the `Version` string like seen below
SSLCertFile = /etc/letsencrypt/live/irc.domain.com/fullchain.pem
SSLDHParamFile = /etc/letsencrypt/live/irc.domain.com/fullchain.pem
SSLKeyFile = /etc/letsencrypt/live/irc.domain.com/privkey.pem
Version = 1.8.2
[Return to top]
Setup ZNC service account and SystemD startup script.
Disable the login shell environment for the znc service account now.
chsh znc
Changing the login shell for znc
Enter the new value, or press ENTER for the default
Login Shell [/bin/bash]: /sbin/nologin
Next you will need a Systemd unit service file for running ZNC.
vi /usr/lib/systemd/system/znc.service
Add the following configuration to the file.
[Unit]
Description=ZNC, an advanced IRC bouncer
After=network.target
[Service]
ExecStart=/usr/bin/znc -f
User=znc
[Install]
WantedBy=multi-user.target
[Return to top]
Enable Service
Now that ZNC is installed and configured, enable its service.
systemctl enable znc
systemctl start znc
You can view the status of the service with the following command.
systemctl status znc
You should see similar output.
● znc.service - ZNC, an advanced IRC bouncer
Loaded: loaded (/etc/systemd/system/znc.service; enabled; vendor preset: enabled)
Active: active (running) since Thu 2021-08-19 01:32:54 UTC; 1h 58min ago
Verify that you can reach the webadmin console by opening a browser. The domain should be similar to "https://irc.domain.com:6698/" or whatever domain name you have assigned for your server
[Return to top]
Protect ZNC webadmin frontend with Fail2Ban (optional)
Since your ZNC webadmin may be left exposed to the public web, anyone could come along and attempt to sign into it. The webadmin does have some built in protection to mitigate brute force attempts by rate limiting a connection that fails to authenticate multiple time. You can enhance this with Fail2Ban!
You will first have to create a custom Fail2Ban filter to parse the znc webadmin log file.
vi /etc/fail2ban/filter.d/znc-webadmin.conf
Add the following to the file.
# Fail2Ban filter for znc-webadmin
[INCLUDES]
before = common.conf
[Definition]
_daemon = znc
failregex = ^%(__prefix_line)sfailed to login from \s*$
ignoreregex =
# DEV Notes:
#
# pattern : [2021-01-16 20:10:59] [zadmin] failed to login from 127.0.0.1
#
# Rule Author: EMH-Mark-I
Next you will have to create a Fail2Ban jail file.
vi /etc/fail2ban/jail.d/znc_custom.conf
Add the following to the file.
[znc-webadmin]
enabled = true
logpath = /var/lib/znc/.znc/moddata/adminlog/znc.log
port = 6698
Don't forget to reload the fail2ban service.
systemctl reload fail2ban.service.
[Return to top]
Notes
If you're using Let's Encrypt for SSL/TLS certificates, don't forget to include a renew_hook that will restart the znc service, otherwise it will fail to ingest any new certificate from the certbot auto-renewal feature.
renew_hook = systemctl restart znc
[Return to top]
