Site logo image
[Home Page]

[RSS Feeds]

[IRC Server]

Return to IRC guides

Print Page mail icon

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
  • Configuring ZNC
  • Setup ZNC service account and SystemD startup script.
  • Enable Service
  • Protect ZNC webadmin frontend with Fail2Ban (optional)
  • Notes

  • 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.

    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/
    SSLDHParamFile = /etc/letsencrypt/live/
    SSLKeyFile = /etc/letsencrypt/live/
    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.

    Description=ZNC, an advanced IRC bouncer

    ExecStart=/usr/bin/znc -f


    [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 "" 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

    before = common.conf

    _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
    # 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.

    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]


    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]

    Last modified date: 2021-08-24

    nationality icon

    Copyright © 2020-2022 All Rights Reserved.