How to install ZNC on Ubuntu 18.04

Overview

ZNC is an IRC (Internet Relay Chat) bouncer that acts as an intermediary between your IRC client and IRC networks. Key benefits include:

• Stay connected — Receive messages even when your client is disconnected
• Multiple clients — Connect from different devices simultaneously
• Message history — Replay messages when you reconnect
• Network bridging — Connect to multiple IRC networks through one server

This guide sets up ZNC as a systemd daemon on Ubuntu 18.04 for production use.

Prerequisites

• Ubuntu 18.04 LTS server
• Root or sudo access
• Static IP address (recommended for persistent connections)
• Network access to IRC servers (port 6697 for SSL, 6667 for plain)

Step 1: Update System and Install ZNC

First, update your system packages:

sudo apt update
sudo apt upgrade

Install ZNC and development files:

sudo apt install znc znc-dev

The znc-dev package is optional but recommended if you plan to install ZNC modules.

Step 2: Create ZNC System User

Create a dedicated system user to run ZNC (security best practice):

sudo useradd --create-home -d /var/lib/znc --system --shell /sbin/nologin --comment "User to run ZNC daemon" --user-group znc

This command:

• Creates a home directory at /var/lib/znc
• Sets it as a system account (no login shell)
• Creates a dedicated group for the user

Step 3: Generate ZNC Configuration

Generate the initial configuration interactively:

sudo -u znc /usr/bin/znc --datadir=/var/lib/znc --makeconf

The script will guide you through setup with prompts. Here’s what each section means:

Global Settings

1
[ ?? ] Listen on port (1025 to 65534): 6697
2
[ ?? ] Listen using SSL (yes/no) [no]: yes
3
[ ?? ] Listen using both IPv4 and IPv6 (yes/no) [yes]: yes

The script will generate an SSL certificate automatically.

Admin User

1
[ ?? ] Username (alphanumeric): adminuser
2
[ ?? ] Enter password: [enter a strong password]
3
[ ?? ] Confirm password: [repeat]
4
[ ?? ] Nick [adminuser]: yournick
5
[ ?? ] Alternate nick [yournick_]:
6
[ ?? ] Ident [adminuser]:
7
[ ?? ] Real name [Got ZNC?]: Your Real Name

Network Configuration

1
[ ?? ] Set up a network? (yes/no) [yes]: yes
2
[ ** ]
3
[ ** ] -- Network settings --
4
[ ** ]
5
[ ?? ] Name [freenode]: freenode
6
[ ?? ] Server host [chat.freenode.net]: irc.libera.chat
7
[ ?? ] Server uses SSL? (yes/no) [yes]: yes
8
[ ?? ] Server port (1 to 65535) [6697]: 6697
9
[ ?? ] Initial channels: #ubuntu,#linux,#help

Finish Configuration

When asked to launch ZNC immediately:

1
[ ?? ] Launch ZNC now? (yes/no) [yes]: no

Choose no — we’ll set up systemd first.

Step 4: Create Systemd Service File

Create a systemd unit file for ZNC:

sudo nano /etc/systemd/system/znc.service

Paste the following configuration:

1
[Unit]
2
Description=ZNC Service
3
After=network-online.target
4

5
[Service]
6
ExecStart=/usr/bin/znc -f --datadir=/var/lib/znc
7
User=znc
8
Group=znc
9
Restart=on-failure
10
RestartSec=10
11

12
[Install]
13
WantedBy=multi-user.target

Save the file (Ctrl+X, then Y, then Enter).

What Each Line Does

• ExecStart — Runs ZNC in foreground mode (-f flag)
• User=znc — Runs as the znc user we created
• Restart=on-failure — Automatically restarts if ZNC crashes
• WantedBy=multi-user.target — Starts at boot time

Step 5: Enable and Start ZNC Service

Enable ZNC to start at boot:

sudo systemctl enable znc

Start the ZNC service:

sudo systemctl start znc

Verify it’s running:

sudo systemctl status znc

You should see Active: active (running).

Step 6: Connect to Your ZNC Server

Via Web Admin Panel

Open your browser and visit:

1
https://your_server_ip:6697/

Login with the admin credentials you created earlier.

Via IRC Client

Configure your IRC client to connect to ZNC instead of direct IRC:

1
Server: your_server_ip
2
Port: 6697
3
Password: username/networkname:password
4
Nick: yournick

Example:

1
Server: 192.168.1.100
2
Port: 6697
3
Password: adminuser/freenode:mypassword
4
Nick: mynick

Troubleshooting

Check ZNC Logs

View recent ZNC activity:

sudo journalctl -u znc -n 20

Restart ZNC

If configuration changes fail to apply:

sudo systemctl restart znc

Permission Denied Errors

Ensure the znc user owns the config directory:

sudo chown -R znc:znc /var/lib/znc

Port Already in Use

Check if another process is using port 6697:

sudo netstat -tulpn | grep 6697

Summary

You have successfully installed and configured ZNC as a persistent IRC bouncer on Ubuntu 18.04. Your ZNC server will automatically:

• Start at system boot
• Reconnect to IRC networks
• Store offline messages for your clients
• Provide secure access via SSL

For additional configuration and module management, visit the web admin panel at https://your_server_ip:6697/ or consult the official ZNC documentation.