#1 2013-10-10 07:49:44

Trusted Member
Registered: 2013-07-20
Posts: 42

How to Setup ZNC

How to Setup ZNC

What is ZNC

ZNC is an IRC network bouncer or BNC. It can detach the client from the actual IRC server, and also from selected channels. Multiple clients from different locations can connect to a single ZNC account simultaneously and therefore appear under the same nickname on IRC. It supports SSL secured connections and IPv6.

What is IRC?

IRC is a decades old protocol. It has proven itself to be reliable, low latency, and capable in several situations around the world. During the Soviet Coup in 1991, it was used to report during a media blackout. It has been used to conference, and for general chat, across the world from Monaco to North Korea. Even though this technology is old and slowly decaying, it continues to be widely used across the world for communication and chatting.

IRC is one of the very pinnacles of how the Internet was built, and by far, one of the most influential developments in the history of the internet.

So what am I supposed to do?

In this tutorial, we will be assuming you will be running the Debian 7 x32 Minimal template, which you can install by pressing this neat little button on your SolusVM control panel:


From there, choose the "Debian 7 32 bit Minimal" template, as shown here. And then press that neato little reinstall button.


From there, using the words of Mihko (Source Post).

mikho (Adapted by darknyan) wrote:

1) Connect via the serial console and set your ssh port to one that is assigned to you. (via editing /etc/ssh/sshd_config) and changing the Port 22 entry to a port that is assigned to you.
2) Using this thread, obtain your IPv4 Address.

So we've gone this far. Let's start on ZNC.

Login as the root user, (or if you're security conscious, login as a normal user, and then su)

Run the following commands:

Updating repository:

apt-get update

Updating software packages:

apt-get upgrade

You can install ZNC using the following options.

1. Via Source Tarball

If you have the knowledge necessary to setup ZNC or a similar package from source, you can obtain a newer version with better stability and added features.

2. Installing ZNC:

apt-get install znc

The ZNC in the Wheezy Repository, is somewhat outdated, but it generally is easier to install, and maintain.

Now, you can't run ZNC as a root user. It just isn't possible because security is actually a factor in ZNC.
So you'll need to create a new user called ZNC.

adduser znc

Creating this user, you will be presented with a set of questions.
Simply enter in the desired password twice, and Enter through everything else (unless you wish to set the details for a reason).

Login as znc, assuming you are still root.

login znc

And enter into the shell as usual, by submitting your password.

Unfortunately, ZNC doesn't come with a set of default configuration files, so you'll need to generate that now.

So run:

znc --makeconf

From there, it will ask you a series of questions. For the most part, this should be self-explanatory, but we will create some input for certain questions.

What port would you like ZNC to listen on? (1025 to 65535)

You should set this to a IPv4 port, that you are assigned.

Would you like ZNC to listen using SSL? (yes/no) [no]: yes

Although the default is no, you generally want to be able to connect via SSL, for security reasons. So respond with yes.

Would you like to create a new pem file now? (yes/no) [yes]

Enter here, or signify yes with a response.

Would you like ZNC to listen using ipv6? (yes/no) [yes]:yes

You definitely want this, since LowEndSpirit revolves around IPv6.

Listen Host (Blank for all ips)

This should be blank, if possible, unless you want to connect only via a certain IPv6 address.

From this point, you should be presented with a 2 global modules. Choose them at your discretion, using this index of modules as reference.
The general rule of thumb, don't enable things you don't need since they have the potential to waste your resources. But I recommend enabling webadmin, which is the second entry.

You will then be presented with the option to create your first username. Do the standard procedure, then respond with yes, to make this user an administrator.


Everything after that will include nicknames, real names, buffer (I recommend 200, assuming you aren't joining every channel on Freenode) e.g.
You should also have been given a prompt to enable the admin module, which allows you to operate the ZNC Bouncer via the IRC interface. There will be a number of other modules as well, to choose to enable, and as always, use this index of modules to help you decide.

Note that these modules are not global. They apply solely to your user, and your user only. Later on, via the webadmin interface, you can easily disable and enable modules with parameters without issue.

You will then be directed to add your first IRC server.

It's generally far more easier to conduct everything in the webadmin, which should now be running in the same port as your ZNC bouncer.
Unfortunately, for some odd reason, Webadmin binds itself to the IPv6 interface of your LowEndSprit VPS, when regular IRC does not discriminate.

At this point, you have two options.

1) You operate it by webadmin panel (we will touch upon that in this tutorial)

2) You operate the ZNC server entirely via the IPv4 IRC interface. (admin module)

In order to reach into either options, you will need to now connect to your ZNC Bouncer with an IRC Client. I recommend HexChat, which is derived from the popular IRC client on Linux, XChat.

If you use HexChat, add the ZNC Bouncer to your Network List.


In this prompt, check "Use SSL for all server on this network" and "Accept Invalid SSL Certificate."
As well, if you wish, uncheck "Use Global User Information," replacing the username box with the username you have created within ZNC setup.
Also, in the bottom portion of the prompt, put in your "Server Password," which will be the password that you use with your ZNC account that you have created.

Now that you have entered your bouncer, type in

/msg *status help

You will have received a message back as following, ensuring that the admin module works:


| Command                | Arguments               | Description                                    |
| Version                |                         | Print which version of ZNC this is             |
| ListMods               |                         | List all loaded modules                        |
| ListAvailMods          |                         | List all available modules                     |
| ListNicks              | <#chan>                 | List all nicks on a channel                    |
| ListServers            |                         | List all servers                               |
| AddServer              | <host> [[+]port] [pass] | Add a server to the list                       |
| RemServer              | <host> [port] [pass]    | Remove a server from the list                  |
| Enablechan             | <#chan>                 | Enable the channel                             |
| Detach                 | <#chan>                 | Detach from the channel                        |
| Topics                 |                         | Show topics in all your channels               |
| PlayBuffer             | <#chan>                 | Play back the buffer for a given channel       |
| ClearBuffer            | <#chan>                 | Clear the buffer for a given channel           |
| ClearAllChannelBuffers |                         | Clear the channel buffers                      |
| SetBuffer              | <#chan> [linecount]     | Set the buffer count for a channel             |
| AddBindHost            | <host (IP preferred)>   | Adds a bind host for normal users to use       |
| RemBindHost            | <host>                  | Removes a bind host from the list              |
| ListBindHosts          |                         | Shows the configured list of bind hosts        |
| SetBindHost            | <host (IP preferred)>   | Set the bind host for this connection          |
| ClearBindHost          |                         | Clear the bind host for this connection        |
| Jump [server]          |                         | Jump to the next or the specified server       |
| Disconnect             | [message]               | Disconnect from IRC                            |
| Connect                |                         | Reconnect to IRC                               |
| Uptime                 |                         | Show for how long ZNC has been running         |
| LoadMod                | <module>                | Load a module                                  |
| UnloadMod              | <module>                | Unload a module                                |
| ReloadMod              | <module>                | Reload a module                                |
| UpdateMod              | <module>                | Reload a module on all users                   |
| ShowMOTD               |                         | Show ZNC's message of the day                  |
| SetMOTD                | <Message>               | Set ZNC's message of the day                   |
| AddMOTD                | <Message>               | Append <Message> to ZNC's MOTD                 |
| ClearMOTD              |                         | Clear ZNC's MOTD                               |
| ListPorts              |                         | Show all active listeners                      |
| AddPort                | <arguments>             | Add another port for ZNC to listen on          |
| DelPort                | <arguments>             | Remove a port from ZNC                         |
| Rehash                 |                         | Reload znc.conf from disk                      |
| SaveConfig             |                         | Save the current settings to disk              |
| ListUsers              |                         | List all ZNC users and their connection status |
| ListChans              | [User]                  | List all channels                              |
| ListClients            | [User]                  | List all connected clients                     |
| Traffic                |                         | Show basic traffic stats for all ZNC users     |
| Broadcast              | [message]               | Broadcast a message to all ZNC users           |
| Shutdown               | [message]               | Shut down ZNC completely                       |
| Restart                | [message]               | Restart ZNC                                    |

You will now be able to access your ZNC webadmin interface at:

If you do not add the https, you will not be able to gain access.

Everything from this point on is self-explanatory. You can add users, change servers, e.g.

PS Please be aware, in order to start your ZNC server in the future, log into your ZNC account and type in


Last edited by darknyan (2013-10-10 15:49:41)


#2 2013-10-10 07:51:44

Low End Boss
From: ~/
Registered: 2013-02-13
Posts: 3,500

Re: How to Setup ZNC

Pure Gold!

Stuck to top.

Please feel free to order a LES VPS and do not pay the invoice, I will take care of the rest.


http://LittleHappyCloud.net KVM VPS with 1TB Bandwidth for €3.00


#3 2013-10-10 07:53:50

Trusted Member
Registered: 2013-07-20
Posts: 42

Re: How to Setup ZNC

Backtogeek wrote:

Pure Gold!

Stuck to top.

Please feel free to order a LES VPS and do not pay the invoice, I will take care of the rest.


Quick response, I was just banned a moment ago. smile

I'll improve on the tutorial tomorrow, seeing as I'm sure I left a small detail out. I assume most LES users can figure it out, since it's very straightforward.


#4 2013-10-10 08:12:36

Trusted Member
Registered: 2013-07-20
Posts: 42

Re: How to Setup ZNC

Backtogeek wrote:

Pure Gold!

Stuck to top.

Please feel free to order a LES VPS and do not pay the invoice, I will take care of the rest.


I'll take you up on your offer

You're a really cool guy Anthony. big_smile


#5 2013-10-10 10:11:26

Low End Mod
From: Hell and gore == Sweden
Registered: 2013-03-02
Posts: 1,298

Re: How to Setup ZNC

Would you like to write these kind of tutorials for lowendguide.com ?
Contact me if interested. It is paid work, not much per article but it is something smile


#6 2013-10-10 11:59:03

Trusted Member
Registered: 2013-10-06
Posts: 131

Re: How to Setup ZNC

mikho wrote:

Would you like to write these kind of tutorials for lowendguide.com ?
Contact me if interested. It is paid work, not much per article but it is something smile

If I may ask, is there a possibility of multiple positions? I would also be interested to write for a bit of money.

What's this? Torn: Soon to become the best blogging platform ever created!


#7 2013-10-10 13:43:08

Trusted Member
Registered: 2013-06-30
Posts: 62

Re: How to Setup ZNC

Nice tutorial!
By the way, I totally suggest building ZNC from source. The version in the repository is kinda old (at least, the one in Debian 6), and doesn't support clearbufferonmsg (Pretty much it makes ZNC usable from more than a single device for me. It clean the message buffer when you write a message, so you can leave a client connected all the time, connect a second client and still get all the messages you didn't read).

I haven't compiled ZNC from source in a while, but it should be something like this:

echo "deb-src http://ftp.nl.debian.org/debian/ squeeze main contrib non-free" >> /etc/apt/sources.list
apt-get build-dep znc
wget http://znc.in/releases/znc-1.0.tar.gz
tar -xzvf znc*.*gz
cd znc-1.0
make install
cd ..
rm -r znc-1.0

With this, ZNC should end up installed in /usr/local/bin.

I also use cron to start up ZNC at every reboot (I like to call it "the poor man starting daemon"). Just "crontab -e" and add something like

@reboot /usr/local/bin/znc


#8 2013-10-10 18:38:42

Trusted Member
Registered: 2013-03-04
Posts: 335

Re: How to Setup ZNC

Really nice tutorial for dummies, dude.


#9 2017-09-19 15:28:55

Trusted Member
Registered: 2016-09-18
Posts: 17

Re: How to Setup ZNC

Given the recent problems with IRC and ddos, maybe update this sticky with some information about potential problems.  I believe on some nodes IRC is banned completely.  It would be nice to document that.


Board footer