What is ZNC (and, BNC)?

ZNC, is an advanced IRC bouncer that is left connected so an IRC client can disconnect/reconnect without losing the chat session. A BNC (short for Bounced Network Connection) is a piece of software that is used to relay traffic and connections in computer networks, much like a proxy. Basically, ZNC will act as a bridge between a client and the IRC server.

This is how ZNC works.

ZNC offers some strong features, listed below:

  1. Modules - Modules are used to extend and modify the way ZNC functions. Modules can be perl, C++ or python scripts. They can be added on global, per-network or per-user basis.
  2. Multiple Users, Networks and Clients - That’s pretty self-explanatory. Interestingly, an admin can limit the max no. of networks that an user can connects with.
  3. Playback Buffers - When a client attaches to ZNC, ZNC playbacks all the conversations that took place while the client was detached. It also remembers which channels the user joined and left, all of this is also reflected in other clients.
  4. SSL Support - Always needed.

How do we setup ZNC?

This needs to occur in four steps:

  1. Install znc on a server. The word ‘server’ is very important here. ZNC needs to be installed on a machine that is always running and always connected to the internet. Once the ZNC service has started, no changes should be made in znc.conf, manually.
  2. Generate an initial config file using znc --makeconf and configure it.
  3. Configure which networks and channels to connect to using the znc webadmin.
  4. Configure the IRC client to connect to ZNC.

Step 1: Install ZNC on your server.

In my own setup, I use a VM (Compute Engine) running on Google Cloud Platform. Free credits can be obtained by applying for the GitHub Student Developer Pack. They provide AWS credits, Digital Ocean credits and much more.

ZNC should be operated on a seperate port. A new firewall rule has to be created to enable that port.

You can find the firewall settings in the VCP Networks submenu.

In my setup, I use port 5999.

To do so in GCP you will need to create a new firewall rule. Also, you will need to enable both HTTP and HTTPS protocols on your VM. After, enabling the port, we will have to install znc and znc-dev. We need znc-dev in order to install and build modules.

sudo add-apt-repository ppa:teward/znc
sudo apt-get update
sudo apt-get install znc znc-dev

Step 2: Setup the initial ZNC config.

ZNC can be configured in two ways, using the znc.conf or using the webadmin interface. However, to perform the initial configuration ZNC has the --makeconf option. It will ask you to create a ZNC username and password, which will enable you to access the webadmin interface. The initial configuration process generates global, user, network and channel settings.

 ~ > znc --makeconf
 [ .. ] Checking for list of available modules...
 [ » ] ok
 [ ** ]
 [ ** ] -- Global settings --
 [ ** ]
 [ ?? ] Listen on port (1025 to 65534): 5999
 [ ?? ] Listen using SSL (yes/no) [no]: yes
 [ ?? ] Listen using both IPv4 and IPv6 (yes/no) [yes]: yes
 [ .. ] Verifying the listener...
 [ » ] ok
 [ ** ] Unable to locate pem file: [/home/xxxxx/.znc/znc.pem], creating it
 [ .. ] Writing Pem file [/home/xxxxx/.znc/znc.pem]...
 [ » ] ok
 [ ** ] Enabled global modules [webadmin]
 [ ** ]
 [ ** ] -- Admin user settings --
 [ ** ]
 [ ?? ] Username (alphanumeric): tejas
 [ ?? ] Enter password:
 [ ?? ] Confirm password:
 [ ?? ] Nick [whereistejas]:
 [ ?? ] Alternate nick [whereistejas_]:
 [ ?? ] Ident [tejassanap]:
 [ ?? ] Real name [Got ZNC?]: Tejas Sanap
 [ ?? ] Bind host (optional):
 [ ** ] Enabled user modules [chansaver, controlpanel]
 [ ** ]

Next, you will be asked to set up an IRC network. You don’t have to say yes since, this can also be done through the webadmin interface.

 [ ?? ] Set up a network? (yes/no) [yes]: yes
 [ ** ]
 [ ** ] -- Network settings --
 [ ** ]
 [ ?? ] Name [freenode]:
 [ ?? ] Server host [chat.freenode.net]:
 [ ?? ] Server uses SSL? (yes/no) [yes]: yes
 [ ?? ] Server port (1 to 65535) [6697]:
 [ ?? ] Server password (probably empty):
 [ ?? ] Initial channels: #freenode
 [ ** ] Enabled network modules [simple_away]
 [ ** ]
 [ .. ] Writing config [/home/xxxxx/.znc/configs/znc.conf]...
 [ » ] ok
 [ ** ]
 [ ** ] To connect to this ZNC you need to connect to it as your IRC server
 [ ** ] using the port that you supplied.  You have to supply your login info
 [ ** ] as the IRC server password like this: user/network:pass.
 [ ** ]
 [ ** ] Try something like this in your IRC client...
 [ ** ] /server <znc_server_ip> +5099 tejassanap:<pass>
 [ ** ]
 [ ** ] To manage settings, users and networks, point your web browser to
 [ ** ] https://<znc_server_ip>:5099/
 [ ** ]
 [ ?? ] Launch ZNC now? (yes/no) [yes]: yes
 [ .. ] Opening config [/home/xxxxx/.znc/configs/znc.conf]...
 [ » ] ok
 [ .. ] Loading global module [webadmin]...
 [ » ] [/usr/lib/znc/webadmin.so]
 [ .. ] Binding to port [+5099]...
 [ » ] ok
 [ ** ] Loading user [tejassanap]
 [ ** ] Loading network [freenode]
 [ .. ] Loading network module [simple_away]...
 [ » ] [/usr/lib/znc/simple_away.so]
 [ .. ] Adding server [chat.freenode.net +6697 ]...
 [ » ] ok
 [ .. ] Loading user module [chansaver]...
 [ » ] ok
 [ .. ] Loading user module [controlpanel]...
 [ » ] ok
 [ .. ] Forking into the background...
 [ » ] [pid: 27630]
 [ ** ] ZNC 1.6.6+deb1ubuntu0.2 - http://znc.in

After this process, we have a running ZNC process. To confirm that the process is running you can run znc command in the terminal. It should produce the following output

 ~ > znc
 [ .. ] Checking for list of available modules...
 [ » ] ok
 [ .. ] Opening config [/home/xxxxx/.znc/configs/znc.conf]...
 [ !! ] ZNC is already running on this config.
 [ ** ] Unrecoverable config error.

Step 3: Configure your ZNC setup using the webadmin UI.

With a running ZNC process, the best way to make changes is through the webadmin UI. To open the webadmin UI, open up an internet browser and type in https://<server-IP-address>:<port>. In my case it is, This opens up the login screen.

We need to use username and password created in the previous step.

This brings us to the landing page. ZNC configuration is divided into two sections:

  1. Global Module settings - These settings are only visible to users with admin privileges.
  2. User Module settings - These are user-specific settings. In a multi-user setting, an admin would see different settings for different users.

This particular article will focus on a very simple setup. We will connect to the Freenode network on the chat.freenode.net server and join #freenode channel. Click on the Your settings option under User Modules.

The landing page contains links to various global and user settings.

On the Your Settings page we can see that the first three sections are the same as the first three sections in znc --makeconf.

The user settings page.

All the important changes are listed below (match the color of the box with the color of the bullet) :

  • Add network - Look in the next section.
  • Buffer size - Any arbitrary number is fine.
  • Auto Clear Chan Buffer - This checks if channel buffers are automatically cleared after playback. When disabled, messages are buffered even while clients are attached, and already seen messages may be repeated each time clients connect. This is important when multiple clients are connected.
  • Auto Clear Query Buffer -This checks if query buffers are automatically cleared after playback. When disabled, messages are buffered even while clients are attached, and already seen messages may be repeated each time clients connect. This is important when multiple clients are connected.
  • Timezone - Set the appropriate timezone.
  • Client Encoding - Try to use UTF-8 encoding, wherever possible.

Add network and channel

In this section of the webadmin UI, we see the third type of modules, network modules. One of the many attractive features of ZNC is the network-wise configuration, it allows us to do.

The network settings page.
  • Enable flood protection - Flooding is when a lot of messages are sent in quick succession. Normally, bots and servers are configured to kick users that spam a channel.
  • Flood protection rate - The number seconds per line before the flood rate kick in.
  • Flood protection burst - The number of lines that can be sent instantly.
  • Add channel - Look in the next paragraph.
  • route_replies module - When using multiple clients, connecting to ZNC can sometimes send a lot of /who's. This module prevents that from happening.
  • sasl module - Enable SASL authentication instead of using the nickserv module.
  • simple_away module - Turns you "away" when you are disconnected from the IRC.

The only puzzling part of network settings is where to put in the password for nickserv. This needs to be done using the nickserv module. On networks supporting SASL, ZNC can also use SASL. The process of enabling SASL requires us to configure the client first. Thus, use the following only after you have connected the client to ZNC:

/msg *sasl Mechanism PLAIN
/msg *sasl RequireAuth yes
/msg *sasl Set <username> [<password>]

The channel settings page.

Then we insert the name of the channel and save the configuration. We are finished with configuring ZNC.

Connecting the client with ZNC.

The irssi client can be connected to znc using the following commands:

/network add freenode-znc
/server add -net freenode-znc -auto -ssl 5999 tejas/freenode:password
/connect freenode-znc

The irssi statusbar shows that I have connected to my ZNC server.


There are still a lot of empty spaces. Knowing how to how to install third-party modules, is important. We will cover that in the next post. In the making of this blog, I heavily relied on #znc on Freenode and ZNC. I highly recommend both the resources to anyone who uses ZNC.