Raymii.org

Table of Contents

• Note about checkinstall and packages
• Install required packages
• Compile ZNC
• ZNC User
• Configuring ZNC
• Upstart script
• Example ZNC configuration
• Troubleshooting

This tutorial will show you how to install the latest (1.0) version of ZNC (an advanced IRC bouncer) on Ubuntu from source. Why from source? The package in the repositories is quite old and missing features like multiple IRC networks. It also includes an upstart script, and an example config for ZNC. ZNC is an advanced IRC bouncer that is left connected so an IRC client can disconnect/reconnect without losing the chat session.

Recently I removed all Google Ads from this site due to their invasive tracking, as well as Google Analytics. Please, if you found this content useful, consider a small donation using any of the options below:

I'm developing an open source monitoring app called Leaf Node Monitoring, for windows, linux & android. Go check it out!

Consider sponsoring me on Github. It means the world to me if you show your appreciation and you'll help pay the server costs.

You can also sponsor me by getting a Digital Ocean VPS. With this referral link you'll get $100 credit for 60 days.

This is tested on Ubuntu 12.04 and 13.10. It will probably work on debian, only you will have to use an init script instead of an upstart script.

Note about checkinstall and packages

We are using checkinstall here to create a debian package of the source we compile. I do this because it gives more flexibility in managing the software afterwards. Upgrading or uninstalling the packages is easier than removing all the things make install placed. Furthermore, it makes it more clear for other administrators which software is installed.

If you for example want to upgrade znc when it was installed via this tutorial with checkinstall, repeat the tutorial with only the version number changed.

Install required packages

We first need to make sure we have all the packages required to build ZNC. Install them via apt:

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

Compile ZNC

Now we are going to get and compile ZNC itself. First download the source code:

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

Extract it and move into the folder:

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

Start the actual compilation:

./configure
make
checkinstall

For checkinstall, the default answers to the questions are good.

ZNC User

Create a separate ZNC user so that ZNC does not need to run as root:

sudo groupadd znc
sudo adduser --system --home /var/lib/znc --group znc

Configuring ZNC

You can use the interactive wizard to configure ZNC. I advise you to do this, it helps a lot when creating the initial configuration file:

sudo -u znc /usr/local/bin/znc --datadir=/var/lib/znc --makeconf

You can find my example config at the bottom of the tutorial.

Upstart script

Place the following script in /etc/init/znc.conf to be able to start and stop znc as a system service:

# znc

description "IRC Bouncer"

start on runlevel [2345]

stop on runlevel [016]

respawn
respawn limit 10 5
setuid znc

script
  exec /usr/local/bin/znc --datadir=/var/lib/znc -f
end script

Save it, then you can start and stop znc like so:

sudo start znc
sudo stop znc

Example ZNC configuration

This is an example ZNC configuration file. You can place this in /var/lib/znc/configs/znc.conf. Make sure to stop ZNC first:

// WARNING
//
// Do NOT edit this file while ZNC is running!
// Use webadmin or *controlpanel instead.
//
// Buf if you feel risky, you might want to read help on /znc saveconfig and /znc rehash.
// Also check http://en.znc.in/wiki/Configuration

AnonIPLimit = 10
ConnectDelay = 5
LoadModule = partyline
MaxBufferSize = 500
ProtectWebSessions = true
SSLCertFile = /var/lib/znc/znc.pem
ServerThrottle = 30
Version = 1.0

<Listener listener0>
  AllowIRC = true
  AllowWeb = false
  IPv4 = true
  IPv6 = true
  Port = 6667
  SSL = true
</Listener>

<User Example>
  Admin = true
  AltNick = Example_
  AppendTimestamp = false
  AutoClearChanBuffer = false
  Buffer = 500
  ChanModes = +stn
  DenyLoadMod = false
  DenySetBindHost = false
  Ident = Example
  JoinTries = 10
  LoadModule = chansaver
  LoadModule = controlpanel
  LoadModule = perform
  MaxNetworks = 3
  MultiClients = true
  Nick = Example
  PrependTimestamp = true
  QuitMsg = So long and thanks for all the fish!
  RealName = Example
  StatusPrefix = *
  TimestampFormat = [%H:%M:%S]

  <Network freenode>
    FloodBurst = 4
    FloodRate = 1.00
    IRCConnectEnabled = true
    LoadModule = chansaver
    LoadModule = keepnick
    LoadModule = kickrejoin
    LoadModule = nickserv
    LoadModule = perform
    Server = irc.freenode.net 6667

    <Chan #ansible>
    </Chan>

    <Chan #digitalocean>
    </Chan>

    <Chan #logstash>
    </Chan>

    <Chan #lowendbox>
    </Chan>

    <Chan #raspberrypi>
    </Chan>

    <Chan #reddit-sysadmin>
    </Chan>

    <Chan #sixgun>
    </Chan>

    <Chan #ubuntu>
    </Chan>

    <Chan #vpsboard>
    </Chan>

    <Chan #wordpress>
    </Chan>

    <Chan #znc>
    </Chan>
  </Network>

</User>

With this config file set up, you can point your IRC client to the ZNC server's IP and port (6667) and automatically be connected to Freenode and a few channels.

Troubleshooting

If stuff doesn't work, try running ZNC like this:

sudo -u znc /usr/local/bin/znc --datadir=/var/lib/znc -f

It will give very clear and verbose errors about what is going wrong.

Tags: freenode , irc , irc-bouncer , source , tutorials , ubuntu , znc