Tutorial

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

Published on September 18, 2013
Default avatar

By Victor Lane

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:

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.

Thanks for learning with the DigitalOcean Community. Check out our offerings for compute, storage, networking, and managed databases.

Learn more about us


About the authors
Default avatar
Victor Lane

author

Still looking for an answer?

Ask a questionSearch for more help

Was this helpful?
 
10 Comments


This textbox defaults to using Markdown to format your answer.

You can type !ref in this text area to quickly search our full set of tutorials, documentation & marketplace offerings and insert the link!

I am facing ‘Connection timed out’ error every time I open the client. Any heads up?

So much abuse of root in this article…

<Ehtesh>: It’s probably better to set it up using a PPA, that way when the upstream version of ZNC updates, so will your local version through a sudo apt-get upgrade.

There’s a PPA set up here: https://launchpad.net/~teward/+archive/ubuntu/znc-staging-trusty+

A short idea of how to run:

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

And then follow the rest of the tutorial as is.

I’m having the same issue as koer and ali, where I cannot access the web admin console in a browser. I tried netstat -tulpn, which shows a listening port on 5000, but https://<my ip>:5000 only gives me a page timeout. How can I fix this?

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

what is the reason to compile from source, rather than just “sudo apt-get install znc” ?

ok nvm, i figured it out.

how can i force znc to use custom vhost? when i connect to znc with my irc client, vps ip is always used as the hostmask. i tried to specify bindhost in znc webadmin panel the same as the hostname i used when i set up my droplet but it didn’t work. i also tried to add domain with correspondent A record in digitalocean web panel to no purpose.

I made new installation and now it works with port 5000 but what i dont understand now is when i started znc on my ssh i dont joined any network i set as before. I though when start znc on ssh my name appear on channel i set. But this doesnt happened. Also i tried use kvirc client and join /server myip port name:pass and it doesnt work. Any help could be appreciated. Thank you.

Kamal Nasser
DigitalOcean Employee
DigitalOcean Employee badge
May 27, 2014

@capko: What’s the output of <pre>sudo netstat -plutn | grep znc</pre>? It should show the port znc is listening on, try connecting to it instead of 6667.

I tried this manual, i tried join quakenet network and if i connect wth different irc client i see my name there. But if i want connect on my VPS it doesnt work. I tried http://188.226.181.12:6667/ do i something wrong? THx for help.

Try DigitalOcean for free

Click below to sign up and get $200 of credit to try our products over 60 days!

Sign up

Join the Tech Talk
Success! Thank you! Please check your email for further details.

Please complete your information!

Get our biweekly newsletter

Sign up for Infrastructure as a Newsletter.

Hollie's Hub for Good

Working on improving health and education, reducing inequality, and spurring economic growth? We'd like to help.

Become a contributor

Get paid to write technical tutorials and select a tech-focused charity to receive a matching donation.

Welcome to the developer cloud

DigitalOcean makes it simple to launch in the cloud and scale up as you grow — whether you're running one virtual machine or ten thousand.

Learn more
DigitalOcean Cloud Control Panel