This website was originally written in Ruby and hosted on the Raspberry Pi. It's now archived at GitHub for posterity!

Setting up the ZNC IRC Bouncer on the Raspberry Pi

Since setting up my Pi as an IRC bouncer, I've been using Shroud BNC. Much chatter on the subject of IRC bouncers, however, has convinced me that this may not be the best of the bunch. And with the name "znc" popping up so frequently, I couldn't resist giving it a try.

Getting ZNC up and running on the Pi is straight forward enough, but getting it installed as a service and running at boot should your Pi's power be interrupted is a little trickier. This guide will touch upon my experiences installing it on Raspbian.

Getting Started

To get started is simple, just "sudo apt-get install znc znc-extra". Once installed you should run "znc --makeconf" and follow the simple config setup steps.

ZNC will prompt you for a port and various other options, but you'll likely want to skip SSL and IPV6 and keep your listen host blank because your Pi probably only has one IP-address anyway.

You wont need to enable any ZNC Global Modules, the defaults are partyline and webadmin. Both of these are unecessary for a single-user bouncer setup. However, I have heard the webadmin is a great way for beginners to get a handle on ZNC configuration.

"makeconf" will also prompt you for a username and password. These will be used later for logging into the bouncer, and are nothing to do with any IRC servers or nicks you might have registered.

For the best experience opt for the user modules keepnick, kickrejoin and nickserv.

Finally, fi you're aiming to chat on the #raspberrypi channel you'll need to pick the host "". The default port will suffice.

Installing ZNC as a Service

That's the easy bit sorted, now for setting up ZNC as a service. You should more or less be able to punch in these commands:

sudo adduser --system --home /usr/lib/znc --group znc
sudo mkdir /usr/lib/znc/configs
sudo cp ~/.znc/configs/znc.conf /usr/lib/znc/configs/
sudo chown -R znc:znc /usr/lib/znc

You'll then need to fire up vim (or your editor of choice) and create an init script. You can do this with "sudo vim /etc/init.d/znc" and should paste in the script from here: Once you've done this, you'll need to replace all references to "/var/lib" with "/usr/lib" this can be trivially accomplished with a substitute in VIM: %s/var\/lib/usr\/lib/g

You'll also need to modify the permissions on the init script as follows:

sudo chmod 755 /etc/init.d/znc

Finally, ZNC needs to drop a pid file for the init script to know if it's running or not. Open up /usr/lib/znc/configs/znc.conf and paste "PidFile = /var/run/znc/" at the top.

Now you can start the service and set it to run on boot:

sudo service znc start
sudo chkconfig znc on

Getting Connected/Final Configuration

To connect to your shiny new bouncer fire up your IRC client and use: /server your-raspberry-pi-ip:port znc-username:znc-password

Once connected you can access a host of admin functions, for a list just msg help to the *admin user: "/msg *admin help"

One thing you should do is tell the nickserv module your nick password, this is easily done with: "/msg *nickserv set yourpassword" Note the asterisk before nickserv!

Now that you're all set, you can enjoy dropping in and out of IRC at your leisure while ZNC keeps an optional playback buffer to stop you missing interesting conversation. It's also great for using IRC across multiple computers.

« Back to index Posted on 2013-04-04 by