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 vs IRC Clients
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
Prerequisites
Before installing ZNC, ensure your environment meets these requirements:
Symptoms
- QuickBox Pro v3 installed and configured
- Valid user account with appropriate permissions
- Existing IRC client for connecting to ZNC
- Understanding of IRC network configuration
Resolution
- Install QuickBox Pro via standard installation process
- Create user account with qb adduser command
- Use any IRC client: irssi, WeeChat, HexChat, mIRC, etc.
- ZNC web admin simplifies network setup after installation
Install ZNC
Install ZNC for a specific user:
qb install znc -u usernamePer-User Installation
ZNC is installed per-user under /opt/<username>/ZNC. Each QuickBox user can have their own independent ZNC installation with separate configurations.
Automatic Installation Process
QuickBox performs comprehensive setup automatically:
- 📦 Compilation - Compiles ZNC from source into user-local prefix
- ⚙️ Configuration - Creates initial config with secure defaults
- 🔒 Service Setup - Configures per-user systemd service
- 🌐 Nginx Integration - Sets up reverse proxy for web administration
- 📁 Directory Structure - Creates config directories with proper permissions
- 💾 Automatic Backup - Creates initial configuration backup
CLI Commands
Basic Operations
| Command | Description |
|---|---|
qb install znc -u username | Install ZNC with automatic configuration |
qb reinstall znc -u username | Reinstall ZNC (preserves configuration) |
qb update znc -u username | Update to latest version |
qb remove znc -u username | Remove ZNC and clean up files |
Usage Examples
Install ZNC:
qb install znc -u myuserUpdate ZNC:
qb update znc -u myuserReinstall (fix corrupted installation while preserving data):
qb reinstall znc -u myuserRemove ZNC and clean up:
qb remove znc -u myuserAccessing 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) |
Multiple Networks
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.confExit Codes
The 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.