ZNC setup guide: the classic IRC bouncer, step by step

ZNC is the bouncer most people mean when they say bouncer: nearly two decades old, packaged everywhere, and thoroughly documented. This guide takes you from a bare VPS to clients connecting through ZNC with history replay.

1. Install and generate a config #

sudo apt install znc        # Debian/Ubuntu; packages exist everywhere
znc --makeconf

--makeconf interviews you: a listening port (pick something memorable, e.g. 6698), SSL yes, an admin username and password, and your first IRC network (e.g. Libera.Chat, irc.libera.chat +6697 — the + means TLS towards the network). Say yes to the webadmin module; you will do everything else from the browser.

2. The web admin #

Browse to https://your-vps:6698 (accept the self-signed certificate, or install a real one later), log in, and you get the full configuration UI: networks, channels, modules, users. Under your network, add the channels you want ZNC to sit in — it stays in them whether or not any client is attached.

3. Connect your clients #

Every client connects to ZNC, not to the network:

• Server: your-vps, port 6698, TLS on.
• Username: youruser/networkname (the slash selects the network).
• Password: your ZNC password — sent as the server password, or for clients that prefer it, via SASL PLAIN towards ZNC.

Multiple clients can attach simultaneously; phone and desktop share one presence on the network.

4. Authentication towards the network #

Give ZNC your NickServ credentials so it identifies for you: enable the sasl module for the network and set your account name and password:

/msg *sasl SET youraccount yourpassword

(ZNC's internal modules are talked to as *modulename.)

5. Modules worth enabling #

• sasl — as above; non-negotiable on modern networks.
• chansaver — remembers channels you join/part across restarts.
• keepnick — fights to reclaim your nick after a ghost.
• clearbufferonmsg / playback settings — by default ZNC replays the buffer on attach; tune buffer size per channel in webadmin. Clients with IRCv3 server-time place replayed lines at their true timestamps — enable that in your client if it is optional.
• log — plain-text logs on the server, if you want them.

Troubleshooting quickies #

Wrong password errors usually mean the password went as NickServ auth instead of ZNC auth — check the username carries the /network suffix. Channels missing on attach: ZNC only replays channels it is in; check webadmin. And if you want history that feels native instead of replayed, that is the cue to read about soju, the modern alternative.