How To Install ZNC, an IRC bouncer, on an Ubuntu VPS

Status: Deprecated

This article covers a version of Ubuntu that is no longer supported. If you are currently operate a server running Ubuntu 12.04, we highly recommend upgrading or migrating to a supported version of Ubuntu:

• Upgrade to Ubuntu 14.04.
• Upgrade from Ubuntu 14.04 to Ubuntu 16.04
• Migrate the server data to a supported version

Reason: Ubuntu 12.04 reached end of life (EOL) on April 28, 2017 and no longer receives security patches or updates. This guide is no longer maintained.

See Instead:
This guide might still be useful as a reference, but may not work on other Ubuntu releases. If available, we strongly recommend using a guide written for the version of Ubuntu you are using. You can use the search functionality at the top of the page to find a more recent version.

Introduction

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.

Installation

In this tutorial, we'll be using Ubuntu 12.04 LTS as our distribution. However, this tutorial should still work in the most recent Ubuntu versions or be very similar. Now, let's get started!

First, we want to update our sources:

sudo apt-get update

Next, we need to grab some dependencies needed to compile ZNC from source:

sudo apt-get install build-essential libssl-dev libperl-dev pkg-config

Grab the latest ZNC source tar ball:

cd /usr/local/src; sudo wget http://znc.in/releases/znc-latest.tar.gz

Extract the tarball, then enter the directory containing the source for ZNC:

sudo tar -xzvf znc-latest.tar.gz; cd znc*

Now we can configure the source in order to compile ZNC. You can use '--prefix=$HOME/znc' ( './configure --prefix=$HOME/znc' instead of './configure') if you don't want a system wide installation or don't have root access. For now, we will just install ZNC system wide:

./configure

Lastly, lets compile ZNC:

sudo make; sudo make install

This may take a few minutes...

If you have finished all of the above steps, you have successfully installed ZNC on Ubuntu Linux!

Configuration

First, we will add a new user for ZNC to run under:

adduser znc-admin

Switch to our new user, then cd into home directory:

su znc-admin; cd ~

Now we will create our configuration file:

/usr/local/bin/znc --makeconf

Now, ZNC will ask us some questions in order to create the configuration file. The first question will ask what port to run ZNC on, the port can be anything from 1025 to 65535. Note which port you have told ZNC to use because you will connect to ZNC through that port.

I pick 5000, but you can choose whichever you like:

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

Next would be regarding SSL listening, this allows you to connect to ZNC with SSL and HTTPS. I recommend entering yes for this, however you can press ENTER to use defaults.

I have chosen yes:

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

It may say '"Unable to locate pem file: [/home/znc-admin/.znc/znc.pem]"' if you've chosen to use SSL. Simply answer yes to the next question to create the pem file:

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

It will now ask if you would like ZNC to listen using ipv6, currently DigitalOcean does not support IPv6 so we will answer no:

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

It will ask you for a listen host, you can enter your VPS' IP here or leave blank to listen on all IPs:

Listen Host (Blank for all ips): 

Now, we will load some global modules of ZNC:

Load global module ? (yes/no) [no]: yes
Load global module ? (yes/no) [no]: yes

The 'partyline' module allows us to communicate with ZNC from your IRC client. The 'webadmin' module allows us to control ZNC from the web interface that was explained in the introduction.

We will now be creating our first ZNC user.

Enter your desired username that you will use to log in to ZNC:

Username (AlphaNumeric): FirstUser

Enter your desired password for that user:

Enter Password: ************

Re-enter your desired password again to confirm:

Confirm Password: ************

Now we will enable this user to have the right to administrate ZNC:

Would you like this user to be an admin? (yes/no) [yes]: yes

Now, we will start configuring our IRC network options.

First we will set our IRC nickname:

Nick [FirstUser]: IRCNickname

Enter your alternate nickname in case your primary nickname conflicts when connecting to an IRC network:

Alt Nick [IRCNickname_]: IRCNickname_

Enter your ident:

Ident [IRCNickname]: IRCIdent

Enter a real name that you wish to use:

Real Name [Got ZNC?]: John Doe

It will now ask us about our bind host, this is what IP address or hostname we will use to connect to the IRC network with.

I will just select defaults by leaving this blank, however you can put your servers hostname here to use that.

Bind Host (optional): 

We will set the lines to buffer (lines of history to play back when re-attaching your client) per channel.

Number of lines to buffer per channel [50]: 50

Set ZNC to clear the channel buffers after replay:

Would you like to clear channel buffers after replay? (yes/no) [yes]: yes

Set our default channel modes for IRC networks:

Default channel modes [+stn]: +stn

We will now load some user modules of ZNC:

Load module <chansaver>? (yes/no) [no]: yes

Load module <controlpanel>? (yes/no) [no]: yes
Load module <perform>? (yes/no) [no]: yes

The 'chansaver' module keeps our ZNC config up to date with channels you parted/joined so that you don't have to add them manually.

The 'controlpanel' module allows editing of the ZNC configuration through your IRC client.

The 'perform' module allows us to keep a list of commands to be executed when ZNC connects to an IRC network.

Now, we can set up our first IRC network that ZNC will connect to.

Would you like to set up a network? (yes/no) [no]: yes

For this tutorial I will be freenode as the network and connect to the #digitalocean channel.

Network (e.g. 'freenode' or 'efnet'): freenode

Now enable some network modules for this network. Take note of the description for each network module that is displayed for information on what they do to decide if you want them enabled or not. More information on each module over here.

Load module ? (yes/no) [no]: yes

Load module <keepnick>? (yes/no) [no]: no
Load module <kickrejoin>? (yes/no) [no]: yes
Load module <nickserv>? (yes/no) [no]: yes
Load module <perform>? (yes/no) [no]: yes
Load module <simple_away>? (yes/no) [no]: yes

Now we will set which IRC server that we want to connect to:

IRC server (host only): irc.freenode.net

Set which port we connect to for that server:

[irc.freenode.net] Port (1 to 65535) [6667]: 6667

Set a password (if required) that allows for connection to this server. I have left blank because this server does not require a password:

[irc.freenode.net] Password (probably empty):

Set ZNC to connect via SSL if you are using a SSL compatible port.

I have selected a non-SSL port so I choose no:

Does this server use SSL? (yes/no) [no]: no

Now, it will ask if you want to add another server for this IRC network. This is useful if you want to connect to specific IRC servers in the network.

I choose no because I don't require this:

Would you like to add another server for this IRC network? (yes/no) [no]: no

Now we will set our channels that we connect to for this network:

Would you like to add a channel for ZNC to automatically join? (yes/no) [yes]: yes

Channel name: #digitalocean

I don't want to set another channel at this time so I will choose no:

Would you like to add another channel? (yes/no) [no]: no

I don't want to connect to another network at this time so I will choose no:

Would you like to set up another network? (yes/no) [no]: no

I don't want to set up another user at this time so I will choose no:

Would you like to set up another user? (yes/no) [no]: no

Now it will ask you if you would like to launch ZNC. Enter yes to launch ZNC:

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

You have successfully configured ZNC for usage. ZNC is now running!

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.

sudo add-apt-repository ppa:teward/znc-staging-trusty+
# follow some instructions to import the PPA key
sudo apt-get install znc

tcp        0      0 0.0.0.0:5000            0.0.0.0:*               LISTEN      25407/znc