The Pug Automatic

Using the "ZNC" IRC bouncer with OS X and iPhone

Written February 16, 2009. Tagged OS X, Colloquy, iPhone, IRC.

An IRC bouncer is basically a proxy server that you connect to IRC through.

This offers various benefits and possibilities; the major one for me is that I appear constantly connected and will see a scrollback of missed messages when I reconnect my client. This means no more connecting in the middle of something and not having context. With iPhone IRC clients, it's especially useful, since third-party iPhone applications don't maintain their connection when you switch away from them. I can also share a single apparent IRC connection between my home computer, my work computer and my phone.


I wanted a bouncer that I could run off my OS X home server. I looked at a few, but they were all severely underdocumented and/or didn't work as expected. I eventually found one I liked, on the advice of @colloquyapp on Twitter: ZNC.

I like about ZNC that it works well with very little fuss, and that it's fairly well documented.


I compiled from source according to the wiki instructions. You need the OS X developer tools or equivalent for this.

After downloading the tar file from this page, unpacking it and changing into that directory, I did

./configure --prefix=/usr/local
sudo make install

Ensure /usr/local/bin is in your PATH. There's no need to mess with --with-openssl; OS X has that covered.

With those settings, it compiled without a hitch for me.


Run znc --makeconf from the command line to interactively create a configuration file. Later, you can modify it by hand (it'll be somewhere like ~/.znc/configs/znc.conf), or even from IRC (/msg *status help).

The README that came with the source, and the ZNC wiki, do a pretty good job of explaining the options. Some things that may not be obvious: "y" or "n" is enough when answering the "yes"/"no" setup questions, or just hit Return to go with the default. After setting the port, don't forget to forward it in your router or firewall. You should activate SSL for encryption; it's no hassle. The hostname of your shell is what you'll connect to from the outside, e.g. "".

I didn't activate any global modules.

"Number of lines to buffer per channel" means that each time you connect, you'll see that many lines of channel log from just before you connected. The default is plenty; I've turned it down to 30. Answering "yes" to "Would you like to keep buffers after replay?" will mean that if you connect from your computer and get to see what you missed, connecting later from your iPhone will show those same messages (no matter that they're already been replayed). That means you are likely to see the same stuff several times, but also that you will always have context. I answered "yes".

As for user modules, I went with: chansaver, so ZNC remembers what channels I join and part; keepnick, to keep trying for my primary nick; nickserv to auth me with NickServ; away to set me away when I detach (disconnect my clients) and save private messages, I think (documentation is unclear); awaynick to change my nick when I go away, to make it more obvious I'm not present. See the wiki for more information on modules.

If you add channels for ZNC to join automatically, don't forget the initial "#"; it's required.


It's very easy to make sure ZNC keeps running, e.g. if you reboot your server or ZNC crashes (it hasn't for me, so far). The wiki describes that you can just set up a cron job; if ZNC is already running with a given config, starting it again will have no effect.

I went with launchd instead of cron. This .plist will launch ZNC when OS X starts, as well as every 5 minutes (and after waking from sleep, if 5 minutes passed during that time). launchd has facilities for keeping an application always running, but that has some complications (pidfile management); starting every 5 minutes is good enough for me.

You can load my launchd task with these commands:

cd ~/Library/LaunchAgents
curl > name.henriknyh.znc.plist
launchctl load name.henriknyh.znc.plist

This will also start ZNC at that time if it isn't already running.


When you're all done, connect your IRC client to the bouncer on the hostname and port you configured, e.g. "". When you connect to the bouncer, the configured username and password should be put in the server password field (yes, server password field) separated by a colon, like: myusername:mypassword.

And that should be it. When you're done chatting, quit your IRC client; don't actually part room by room, since that will part the bouncer from them as well. When you reconnect, the bouncer will let you know what you missed.

I'm using this successfully with LimeChat for full-size Macs and Mobile Colloquy on the iPhone.