You are here: Home > Psybnc > Znc

How To Install ZNC, an IRC bouncer, on Linux


ZNC is an IRC network bouncer software. ZNC comes with various modules and features that can cater to your usage requirements.

We will be compiling ZNC with the web interface enabled in this tutorial. In the web interface, you can create, edit, configure, and remove users from your ZNC instance.


If you want to compile ZNC with OpenSSL support, you need the OpenSSL development package. On Debian/Ubuntu this is called libssl-dev, on CentOS/Fedora/Red Hat it's openssl-devel.

If you want to compile ZNC with OpenSSL support, you need the OpenSSL development package. On Debian/Ubuntu this is called libssl-dev, on CentOS/Fedora/Red Hat it's openssl-devel, and on openSUSE it's libopenssl-devel. A good way to install this and other dependencies is the build dependency feature of package managers (apt-get build-dep / yum-builddep / zypper source-install --build-deps-only).

  1. Download the latest source tarball
  2. tar -xzvf znc-1.6.4.tar.gz
  3. cd znc-1.6.4
  4. ./configure
    (use --prefix="$HOME/.local" if you don't want a system wide installation or simply don't have root access; use --with-openssl=/path/to/openssl if you have a non-standard SSL path)
    (use --help to see other configure options)
  5. make
    (if you are on a dedicated server and your CPU has more than one core, you can use make -jX where X is the number of CPU cores to speed up compilation)
  6. make install

Please note that compiling can take 5-10 minutes or more.
If you get an error saying: No compiler with C++11 support was found
do this:
sudo apt-get install gcc-4.7 g++-4.7
and to start your ZNC, type: znc

Server Setup

The first thing youíll need is a server. If you donít already have one, I recommend setting up an Amazon EC2 micro-instance, which is free for a year. Mine is running Ubuntu 12.04 LTS. (An EC2 setup guide is outside the scope of this tutorial, but here is Amazonís documentation.)

Before you do anything else, pick a port for ZNC to listen on (I chose 6667) and make sure itís open. If youíre using Amazon EC2, go to the management console, click on Security Groups, and make a new inbound TCP rule with port 6667, leaving the default setting for source. If youíre using some other VPS host, the following commands should work:

$ iptables -I INPUT -p tcp --dport 6667 --syn -j ACCEPT
$ netstat -vatn

The netstat output should show something like this:

Proto Recv-Q Send-Q Local Address           Foreign Address         State      
tcp        0      0  *               LISTEN

You may also want to set your serverís timezone, so that the timestamps shown on your chat playback are accurate. Following the instructions in this Stack Overflow post, I used tzselect to find out that my timezone was ďAmerica/Los_AngelesĒ, got annoyed that it wasnít ďAmerica/San_FranciscoĒ, and then did the following:

$ echo "America/Los_Angeles" | sudo tee /etc/timezone
$ sudo dpkg-reconfigure --frontend noninteractive tzdata

Installing ZNC

Now itís time to install ZNC! At the time of writing, using IPV6 caused issues with ZNC Push notifications, so I chose to compile from source, using the following commands. [Update 9/4/13: Apparently thereís a branch that fixes this bug here; if you install it, donít pass the --disable-ipv6 flag to configure, obviously.]

$ wget
$ tar -xzvf znc-1.0.tar.gz
$ cd znc-1.0
$ ./configure --disable-ipv6
$ make
$ sudo make install

After installation completes, youíll want to start ZNC for the first time with the --makeconf flag to set up the initial configuration:

$ znc --makeconf

Here are the relevant settings that I used. You likely wonít need the partyline or webadmin global modules, but I enabled all the user modules it prompted me to load. If youíre enabling SSL, you may need to look up the appropriate port on your desired IRC serverís FAQ page. For Zemra, itís 6697.

[ ?? ] What port would you like ZNC to listen on? (1025 to 65535): 6667
[ ?? ] Would you like ZNC to listen using SSL? (yes/no) [no]: y
[ ?? ] Would you like ZNC to listen using ipv6? (yes/no) [yes]: n
[ ?? ] Listen Host (Blank for all ips):
[ ?? ] Would you like this user to be an admin? (yes/no) [yes]: y
[ ?? ] Would you like to keep buffers after replay? (yes/no) [no]: n
[ ?? ] IRC server (host only):
[ ?? ] [] Port (1 to 65535) [6667]: 6697
[ ?? ] [] Password (probably empty): 
[ ?? ] Does this server use SSL? (yes/no) [no]: y

ZNC was successfully installed.
You can use '/usr/local/bin/znc --makeconf'
to generate a config file.

If you need help with using ZNC, please visit our wiki at:

Connecting to ZNC

If everything has worked up until this point, ZNC should be running, and you should be able to use your chat client (e.g. Adium) to connect to the server hosting your IRC bouncer. In your chat client, make sure to enter the username and password you created during ZNC configuration under the nickname and password fields. The hostname field should contain the IP address of your personal server, not the IRC server you ultimately want to connect to. If you enabled SSL, donít forget to check that option.

Once youíve connected, try joining a channel. Stay in the channel, but quit your client and reopen it. You should see a convenient playback of the n (default 50) most recent lines, and you can ask a friend to help you confirm that your nick stayed connected even though your client disconnected from ZNC.

Loading ZNC Modules

If you need to edit your configuration file, you COULD do the following from the terminal:

$ pkill -SIGUSR1 znc
$ pkill znc
$ vim ~/.znc/configs/znc.conf
$ znc

ÖBUT the safest way is to use your chat client to send either of these commands and follow the given instructions:

/msg *status help
/msg *controlpanel help

If you plan to configure a custom hostname, remember this Ė weíll come back to it later. However, one variable that I recommend you set now is AutoClearChanBuffer, so that you donít come back to 50 lines of chat playback that youíve already seen if youíve only exited your client for a second or two:

/msg *controlpanel Set AutoClearChanBuffer $me true

ZNC Push

I installed ZNC Push so that I could receive push notifications on my phone whenever Iím pinged and I donít have a chat client actively connected to ZNC. The documentation here is very helpful, but Iíll list the steps I went through to set this up:

$ sudo apt-get install znc-dev
$ git clone
$ cd znc-push
$ make
$ cp ~/.znc/modules/

I decided to use Boxcar to receive push notifications on my phone. After downloading the app and creating an account, I sent the following commands in my chat client:

/msg *status LoadMod push
/msg *push set service boxcar
/msg *push set username [email protected]
/msg *push subscribe

I also set the following options so that any mentions or private messages would be pushed to my phone as soon as my chat client has disconnected from ZNC. (The first command shows the current settings.)

/msg *push get
/msg *push set idle 0
/msg *push set last_active 0
/msg *push set last_notification 0
/msg *push client_count_less_than 1

Custom Hostname

Finally, I wanted a vanity host to be displayed whenever I join a channel or someone performs a /whois lookup on me. I first purchased a domain (from Namecheap, you can use whichever domain registrar you prefer), and then I modified the domainís host records, setting an A record that points to the IP address of the server running ZNC.

After completing this step, I configured the reverse DNS of the ZNC server so that its IP address would resolve back to my custom domain. Disclaimer Ė I didnít end up using my Amazon EC2 micro-instance for ZNC, but if I did, these are the likely steps I would take to set up reverse DNS:

  1. In the management console, allocate an elastic IP address and associate it with your instance.
  2. Fill out the form mentioned here, specifying your custom domain as the reverse DNS record corresponding to your instanceís elastic IP. If youíre using a VPS that utilizes a management system like SolusVM, there may be a field where you can provide reverse DNS records under the network settings. If this step doesnít complete, and you only recently set your domainís A record, you might have to wait a little while longer for the changes to go through.

Once this was done, I went back to my chat client and sent the following commands (replace ďdomain.tldĒ with your own domain):

/msg *status AddBindHost domain.tld
/msg *status SetBindHost domain.tld
/msg *status SetUserBindHost domain.tld

Thatís it! I had fun spending a few hours Googling SO MANY THINGS, and I hope that documenting all of it in this post helps some of you who are inspired to set up ZNC for yourselves.

Basic Usage

Your ZNC web interface should be available at: http://<droplet_ip>:<specified_port> or if you used SSL https://<droplet_ip>:<specified_port>, you can sign in with your user and password to configure ZNC further. More help on configuring ZNC further can be found over here.

You can connect to your ZNC account via an IRC client of your choice by trying /server <droplet_ip> <specified_port> <user>:<pass> within your client, however this command is client dependent.