Site logo image
[Home Page]
[Blog]
[Contact]
[About]

[Guides]
[News]
[Reviews]
[RSS Feeds]

[IRC Server]
[Links]

Return to IRC guides

Print Page mail icon

ZNC IRC Bouncer Setup Guide for Debian

Date: 2021-08-24



  In this guide we'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 we begin with installing any additional packages, let's go ahead and make sure that the system is up-to-date. I recommend rebooting the server after the fact to apply any kernal updates.

    apt update
    apt upgrade

    With the updates out of the way let's install znc.

    apt install znc

    Now let's configure a directory where our ZNC configurations will live. Personally I prefer /var/lib/znc since that was the prescribed location on CentOS, but you can place it wherever you want, just make note of where.

    mkdir -p /var/lib/znc

    We'll also need a service account that will be dedicated for executing ZNC. We don't want it running under the root user.

    Note
    For now the service account will require a login shell so that we can make some initial configurations. We will change this later though.

    useradd --system --comment "Account for ZNC to run as" --shell /bin/bash --home-dir /var/lib/znc znc

    Set our ZNC service account as the owner of the directory we 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 let’s change directory into .znc/config and point the config to our TLS certificate. In this guide I am using Let's Encrypt.

    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.

    Let's 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 we 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 let's 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. We can enhance this with Fail2Ban!

    We 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 we 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]

    Last modified date: 2021-08-24

    nationality icon

    Copyright © 2020-2021 emhmki.org All Rights Reserved.