How to run ZNC


(last time edited: 2021-01-13)

tags: chat, services

ZNC is an advanced IRC bouncer that can establish such a permanent connection to several IRC networks and channels so your IRC client (or multiple clients) can disconnect/reconnect without losing the chat session, while appearing as a single user to other users.

Create a ZNC configuration file.

# su - znc -s /bin/sh -c "znc -c"

Enter the following info:

Listen on port: (1025 to 65534): 1025
Listen using SSL: (yes/no) [no]: no
Listen using both IPv4 and IPv6 (yes/no) [yes]: yes
Username (alphanumeric): your_username
Enter password: your_password
Confirm password: your_password
Nick: your_nickname
Alternate nick: your_nickname_
Ident: your_nickname
Real name (optional): your_nickname
Bind host (optional): leave empty
Set up a network? (yes/no) [yes]: no
Launch ZNC now? yes

Configure ZNC webadmin page for a subdomain using Nginx. Open the ZNC webadmin page by entering https://YOUR_SERVER_IP:1025 in your browser. Accept the certificate. Log in with your account. Go to global settings. We will maintain the Web separated from the IRC connections. Now let's make a listening port for the IRC connections. In Listen Ports(s) add:

Port: 6697
BindHost: *
SSL: on
IPv4: on
IPv6: off
IRC: on
HTTP: off
URIPrefix: /

Save, logout from the web browser and stop the ZNC service. Make sure all ZNC processes are dead.

Edit the ZNC configuration file znc.conf.

Listener0 is will function as Web listener (port 1025). Listener1 will function as the IRC listener (port 6697). Your configuration should look like this:

<Listener listener0>
    Allow IRC = false
    AllowWeb = true
    IPv4 = true
    IPv6 = false
    Port = 1025
    SSL = false
    URIPrefix = /

<Listener listener1>
    AllowIRC = true
    AllowWeb = false
    IPv4 = true
    IPv6 = false
    Port = 6697
    SSL = true
    URIPrefix = /

Start the ZNC service.

Install NGINX.

Create a configuration file in an NGINX conf.d directory separated from the main configuration files.

The file should look something like below:

server {
    listen 443 ssl;

    location / {
        proxy_pass http://localhost:1025;


If you prefer running ZNC's WebAdmin in a subdirectory instead of a subdomain; the URIPrefix for port 1025 should be /znc. And proxy_pass should be pointing to a /znc location in a main server NGINX block. For example like this:

server {
    listen 443 ssl;

    location /znc {
        proxy_pass https://localhost:1025;


Notice! Don't forget to include the custom .conf in /etc/nginx/nginx.conf

http {

    # ...

    include conf.d/yourconf.conf;

    # ...

If you want to redirect all web requests from irc subdomain to znc subdomain add this in NGINX:

server {
    listen 443 ssl;
    return 301;

If your webadmin ZNC bouncer is for your personal use only you can also create a second web login via NGINX using the HTTP Basic Authorization and make it more secure for brute-forcing.

    # ...

    auth_basic "stay away";
    auth_basic_user_file /etc/nginx/zncpass;
    proxy_set_header Authorization "";

    # ...

And create a password with htpasswd. This beautiful tool comes in the apache-htpasswd package.

# htpasswd -c /etc/nginx/zncpass <any_name>

Adding your own SSL certificates

It's very simple, if you already created SSL certificates using certbot for your domains/subdomains. Just concatenate the privkey and fullchain into a new file.

# cat /etc/letsencrypt/live/YOUR_DOMAIN/privkey.pem /etc/letsencrypt/live/YOUR_DOMAIN/fullchain.pem > /path/to/znc/.znc/znc.pem