ZNC IRC Bouncer
Advanced IRC bouncer that keeps you connected 24/7 with module support and a web admin panel
ZNC IRC Bouncer
ZNC is an advanced IRC network bouncer (BNC) that maintains persistent connections to IRC networks on your behalf. Unlike traditional IRC clients, ZNC acts as a proxy layer between you and IRC servers—staying connected 24/7, buffering messages when you’re offline, and allowing multiple clients to connect simultaneously while appearing as a single user on IRC.
What is ZNC?
ZNC is a lightweight, modular IRC bouncer that keeps you permanently connected to IRC networks. When you disconnect your IRC client, ZNC stays online and buffers all messages until you reconnect.
Always Connected
ZNC maintains persistent IRC connections 24/7, even when all your clients are offline
Message Buffering
Never miss a message—ZNC stores chat history and plays it back when you reconnect
Multiple Clients
Connect from desktop, laptop, and mobile simultaneously while appearing as one user
Module System
Extend functionality with modules for logging, notifications, SASL, and more
Web Administration
Configure networks, users, and modules through a built-in web interface
Secure Proxy
SSL/TLS support for both client connections and IRC server connections
ZNC is not an IRC client—it’s a bouncer that sits between your IRC client and the IRC network. You still need an IRC client (like irssi, WeeChat, or HexChat) to connect to ZNC, which then connects to IRC networks on your behalf.
Installation
Install from the Dashboard
Open App Dashboard → Package Management (/dashboard?mode=packages), find ZNC in the Communication category (or search), and click Install. ZNC has the richest install dialog of the IRC apps — you set it up entirely from the form:
- Connection — listening port, SSL on/off, and IPv4+IPv6 dual-stack
- Admin account — bouncer password, nick, alt nick, ident, and real name
- Network (optional) — pre-add a starter IRC network with its host, SSL, port, and auto-join channels (defaults to Libera.Chat), or skip it and add networks later from the web admin
The dashboard streams the install log live and ZNC appears in your Application Control panel when it finishes. Reinstall, Update, and Remove are on the same panel. ZNC is installed per user under /opt/<username>/ZNC, so each user has an independent bouncer.
What you see is gated by your account: admins manage any user’s apps, regular users manage their own. See App Management for the full flow.
Install from the CLI (automation)
The CLI runs the same script; the dialog fields above map to flags such as --port, --ssl, --nick, --network-name, and --channels:
qb install znc -u username
qb reinstall znc -u username
qb update znc -u username
qb remove znc -u usernameFull flag reference: CLI Reference.
Accessing ZNC
Web Administration
After installation, access the ZNC web admin through the QuickBox reverse proxy:
https://your-server/znc/The web interface allows you to:
- Add and configure IRC networks
- Manage user accounts and permissions
- Enable/disable modules
- View connection status and logs
Connecting IRC Clients
Configure your IRC client to connect to ZNC instead of directly to IRC networks:
| Setting | Value |
|---|---|
| Server | Your server hostname or IP |
| Port | Assigned during installation |
| Username | username/network (e.g., john/liberachat) |
| Password | Your ZNC password |
| SSL/TLS | Enabled (recommended) |
To connect to a specific network, use the format username/network as your IRC username. For example, john/liberachat connects through user “john” to the network named “liberachat”.
Service Management
ZNC runs as a per-user systemd service:
Basic Service Commands
Check service status:
systemctl status znc@usernameStart service:
systemctl start znc@usernameStop service:
systemctl stop znc@usernameRestart service:
systemctl restart znc@usernameView logs:
journalctl -u znc@username -fDirectory Structure
Troubleshooting
Common Issues
Service won’t start:
# Check service status and logs
systemctl status znc@username
journalctl -u znc@username -n 50
# Verify configuration directory exists
ls -la /home/username/.config/ZNC/Cannot access web admin:
# Check nginx configuration
nginx -t
systemctl reload nginx
# Verify ZNC is listening
ss -tlnp | grep zncClient cannot connect:
# Verify service is running
systemctl is-active znc@username
# Check assigned port
grep -i "port" /home/username/.config/ZNC/configs/znc.confThe installer returns exit code 2 when /opt/<username> is absent and 3 when /opt/<username>/ZNC is missing. Ensure the user exists and has proper home directory permissions.
Best Practices
Do
- Run ZNC as a non-root QuickBox user
- Enable SSL/TLS for both client and server connections
- Use SASL module for automatic NickServ authentication
- Configure buffer playback settings to avoid message floods
- Keep modules minimal to reduce attack surface
- Back up /home/<username>/.config/ZNC regularly
- Use the QuickBox nginx proxy for secure web admin access
Don't
- Don't run ZNC as root
- Don't expose ZNC ports directly without SSL
- Don't share ZNC credentials across multiple users
- Don't install untrusted third-party modules
- Don't disable the web admin SSL requirement
Additional Resources
Related Applications
IRC Solutions
Automation
Join the Community
Media server operators sharing configs, getting support, and shaping the future of QuickBox Pro.