Documentation Index
Fetch the complete documentation index at: https://docs.allthingslinux.org/llms.txt
Use this file to discover all available pages before exploring further.
The IRC stack is configured entirely through environment variables in .env and config templates processed by scripts/prepare-config.sh at startup — you never edit the generated config files directly.
How config templating works
UnrealIRCd and Atheme both use template files that contain ${VARIABLE} placeholders. When you run just init or just dev, the scripts/prepare-config.sh script runs envsubst to substitute your .env values into the templates, producing the final config files.
| Template | Output | Service |
|---|
apps/unrealircd/config/unrealircd.conf.template | apps/unrealircd/config/unrealircd.conf | UnrealIRCd |
apps/atheme/config/atheme.conf.template | apps/atheme/config/atheme.conf | Atheme |
.template file (not the generated .conf), add any new ${VARIABLES} to .env.example, and re-run scripts/prepare-config.sh (or just init).
Warning: Never edit the generated .conf files directly. They are overwritten on every just init or just dev run.
Environment variables
All IRC-related variables are defined in the IRC SERVICE section of .env.example. Copy .env.example to .env and customise before first run.
Network identity
| Variable | Description | Required | Default |
|---|
IRC_DOMAIN | Public hostname of the IRC server | Yes | irc.atl.chat |
IRC_ROOT_DOMAIN | Root domain for the network | Yes | atl.chat |
IRC_NETWORK_NAME | Human-readable network name shown to clients | Yes | All Things Linux IRC |
IRC_CLOAK_PREFIX | Prefix for cloaked hostnames (e.g. atl-ABC123.users.atl.chat) | Yes | atl |
Build versions
| Variable | Description | Required | Default |
|---|
UNREALIRCD_VERSION | UnrealIRCd Docker image git tag | Yes | 6.2.0.1 |
ATHEME_VERSION | Atheme Docker image git tag | Yes | master |
Ports
| Variable | Description | Required | Default |
|---|
IRC_TLS_PORT | Client TLS port | Yes | 6697 |
IRC_SERVER_PORT | Server-to-server TLS port | Yes | 6900 |
IRC_RPC_PORT | JSON-RPC API port (WebPanel) | Yes | 8600 |
IRC_WEBSOCKET_PORT | WebSocket port for web clients | Yes | 8000 |
Security secrets
| Variable | Description | Required | Default |
|---|
IRC_CLOAK_KEY_1 | First cloak key for IP masking | Yes | Example key (change for prod) |
IRC_CLOAK_KEY_2 | Second cloak key | Yes | Example key (change for prod) |
IRC_CLOAK_KEY_3 | Third cloak key | Yes | Example key (change for prod) |
IRC_OPER_PASSWORD | IRC operator password (argon2id hash) | Yes | change_me_irc_oper_password |
IRC_DRPASS | Password for /DIE and /RESTART commands | Yes | change_me_drpass |
IRC_SERVICES_PASSWORD | Atheme ↔ UnrealIRCd link password | Yes | change_me_secure_services_pass |
ATL_WEBIRC_PASSWORD | WEBIRC password for gateway proxy | Yes | change_me_webirc_password |
Warning: All change_me_* values must be replaced before any public deployment. See Security for generation instructions.
Admin info
| Variable | Description | Required | Default |
|---|
IRC_ADMIN_NAME | Admin name shown in /ADMIN | Yes | All Things Linux |
IRC_ADMIN_EMAIL | Admin email shown in ban messages | Yes | admin@allthingslinux.org |
IRC_STAFF_VHOST | Virtual host for IRC operators | Yes | allthingslinux.org |
STS (Strict Transport Security)
| Variable | Description | Required | Default |
|---|
IRC_STS_DURATION | STS cache duration (start low: 1m, increase to 180d) | Yes | 1m |
IRC_STS_PRELOAD | Enable STS preload in clients | Yes | no |
TLS certificate paths
| Variable | Description | Required | Default |
|---|
IRC_SSL_CERT_PATH | Path to fullchain.pem inside container | Yes | /home/unrealircd/unrealircd/certs/live/irc.atl.chat/fullchain.pem |
IRC_SSL_KEY_PATH | Path to privkey.pem inside container | Yes | /home/unrealircd/unrealircd/certs/live/irc.atl.chat/privkey.pem |
Atheme services link
| Variable | Description | Required | Default |
|---|
IRC_SERVICES_SERVER | Atheme server name in the IRC network | Yes | services.atl.chat |
ATHEME_SERVER_NAME | Atheme’s own server identity | Yes | services.atl.chat |
ATHEME_SERVER_DESC | Atheme server description | Yes | All Things Linux IRC Services |
ATHEME_UPLINK_HOST | Host Atheme connects to (localhost via network namespace) | Yes | 127.0.0.1 |
ATHEME_UPLINK_PORT | Port Atheme connects to on UnrealIRCd | Yes | 6901 |
ATHEME_NUMERIC | Atheme server numeric identifier | Yes | 00A |
ATHEME_RECONTIME | Reconnect interval in seconds | Yes | 10 |
ATHEME_HTTPD_PORT | Atheme JSON-RPC HTTP port | Yes | 8081 |
WebPanel
| Variable | Description | Required | Default |
|---|
WEBPANEL_PORT | WebPanel HTTP port | Yes | 8080 |
WEBPANEL_RPC_USER | RPC username for WebPanel → UnrealIRCd | Yes | adminpanel |
WEBPANEL_RPC_PASSWORD | RPC password | Yes | change_me_webpanel_password |
The Lounge
| Variable | Description | Required | Default |
|---|
THELOUNGE_PORT | The Lounge web client port | Yes | 9000 |
THELOUNGE_WEBIRC_PASSWORD | WEBIRC password for The Lounge → UnrealIRCd | Yes | change_me_thelounge_webirc |
THELOUNGE_DELETE_UPLOADS_AFTER_MINUTES | Auto-delete uploaded files after N minutes | No | 1440 |
Cloak keys
Cloak keys mask user IP addresses so that real IPs are never visible to other users. Three keys are required and must be identical across all servers in the network.
Generating cloak keys
Use the built-in generation command:
This runs scripts/gencloak-update-env.sh, which:
- Spins up a temporary UnrealIRCd container
- Runs the
gencloak command to generate three cryptographically random keys
- Updates
IRC_CLOAK_KEY_1, IRC_CLOAK_KEY_2, and IRC_CLOAK_KEY_3 in your .env file
- Re-runs
scripts/prepare-config.sh to apply the new keys to the config
After generating new keys, reload the config:
Warning: Changing cloak keys changes every user’s cloaked hostname. Existing channel bans based on cloaked hosts will stop matching. Coordinate key changes with your operator team.
Config template structure
The main template at apps/unrealircd/config/unrealircd.conf.template is organized into the following sections:
| Section | Lines | Contents |
|---|
| Third-party modules | 320–370 | cloak_sha256, metadata, react, redact, relaymsg-atl |
Server identity (me {}) | 370–380 | Server name, SID, network info |
| Proxy/WEBIRC blocks | 380–420 | NPM gateway, The Lounge, X-Forwarded-For trust |
| Listen blocks | 420–460 | Ports 6697, 6900, 6901, 8600, 8000, Unix sockets |
| TLS configuration | 460–540 | Protocols, ciphers, STS, plaintext/outdated policies |
| Link and allow blocks | 540–570 | Atheme services link, client allow rules |
| Ban nicks | 570–690 | Reserved nicknames (services, system names) |
| Blacklists (DNSBL) | 690–730 | DroneBL, EFnetRBL, Tornevall |
Network set {} block | 730–760 | Network name, cloak keys, hidden host prefix |
| Oper blocks | 760–800 | Admin oper, bridge oper, RPC user |
| Logging | 800–840 | Text log (100M), JSON log (250M) |
Server set {} block | 840–end | Modes, anti-flood, connthrottle, restrict-commands, history |
Audit findings and recommendations
The following findings from a configuration audit remain relevant to the current setup. They are informational — the defaults work for development, but you should address them before production deployment.
TLS configuration
The TLS setup is strong: TLS 1.2+ only, ECDHE-only ciphers with forward secrecy, and post-quantum hybrid key exchange (X25519MLKEM768) when OpenSSL 3.5.0+ is available. STS is enabled with a configurable phased rollout (IRC_STS_DURATION).
Oper block security
The admin oper block restricts connections to the Docker network (172.16.0.0/12) and requires a TLS connection (require-modes "z"). The oper password must be an argon2id hash — generate one with:
docker run --rm ghcr.io/allthingslinux/unrealircd \
./unrealircd mkpasswd argon2 'your-password-here'
Connection throttling
The connthrottle module is loaded and configured with exemptions for identified users and those with established reputation scores. For production, review the connect-flood rate (currently 5:60 — 5 connections per 60 seconds per IP).
DNSBL configuration
Three DNS blacklists are configured: DroneBL, EFnetRBL, and Tornevall. The Tornevall DNSBL has had historical reliability issues and uses a broad reply code range (1–16). Consider removing it or narrowing the reply codes if you experience false positives.
Missing spamfilter rules
The included spamfilter.conf contains rules from 2005 targeting obsolete malware. For production, either write modern rules targeting current spam patterns (crypto scams, phishing, mass-highlight floods) or rely on dynamic spamfilters via the /SPAMFILTER command.
Recommended third-party modules
Two additional modules from the third-party-modules.list are worth enabling for production:
third/block_masshighlight — blocks mass-highlighting (mentioning many nicks at once), a common harassment tacticthird/repeatprot — catches repeated messages that slip through rate limits
Related pages