By Victor Lane
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.
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.
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.
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:
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!
First, we will add a new user for ZNC to run under:
Switch to our new user, then cd into home directory:
su znc-admin; cd ~
Now we will create our configuration file:
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
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.
? (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
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!
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.
Join our DigitalOcean community of over a million developers for free! Get help and share knowledge in our Questions & Answers section, find tutorials and tools that will help you grow as a developer and scale your project or business, and subscribe to topics of interest.Sign up now
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:
And then follow the rest of the tutorial as is.
I’m having the same issue as
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>:5000only gives me a page timeout. How can I fix this?
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.
@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.8.131.52:6667/ do i something wrong? THx for help.