18 KiB
Configuration reference
Every configuration block and field echoIRCd understands. For the format itself and a quick start,
see Configuration. Most options re-apply on echoircd rehash (SIGHUP) with
no restart; the TLS certificate is re-read on rehash too.
Format
echoIRCd config files use a block format: section { field value; field value; … }.
- One field per
;terminator; a block may span multiple lines. - Comments:
#and//for line comments,/* … */for block comments. An inline#on an active line is treated as part of the value unless the value is quoted — quote values that contain#. - Booleans are
yes/no. A bare field with no value (e.g.operprefix;) enables it. - Quoting: quote any value containing spaces or
#. - A legacy flat
key = valueformat is also accepted; blocks are translated to flat keys internally, so the two are exactly equivalent.
Structural blocks (server, listen, tls, cloak, brand, oper, opertype, class,
link, webirc, motd, opermotd) map their fields to specific keys. Grouping blocks
(limits, timeouts, flood, connections, channels, users, opers, logging, modules,
dns, antiabuse, restrictions, accounts, verification, reputation, securitygroups,
websocket, sts, services, dnsbl, …) are cosmetic — each field inside is simply a flat key,
so you could equally place it at top level.
Password fields accept plaintext, sha256:<hex>, pbkdf2:…, or a bcrypt $2b$ hash. Generate one
with printf '%s' 'pw' | ./echoircd mkpasswd.
server
Server identity (not repeatable).
| Field | Description |
|---|---|
name |
This server's unique name on the network |
network |
Network name shown to clients |
sid |
3-char server ID for S2S (a digit + two alphanumerics) |
description (desc) |
Shown in LINKS / WHOIS 312 |
pidfile |
PID file so echoircd rehash / kill -HUP can find the process (omit to disable) |
listen
A bound socket. Repeatable. ip "*" / "[::]" binds IPv4+IPv6 dual-stack.
| Field | Description |
|---|---|
ip |
Bind address (0.0.0.0, [::], *, 127.0.0.1, …) |
port |
Bind port |
type |
client (default) or server (S2S) |
tls |
yes = direct-TLS listener |
wss |
yes = WebSocket-over-TLS (browser clients) |
ws |
yes = plaintext WebSocket |
tls
TLS certificate (re-read on rehash).
| Field | Description |
|---|---|
cert |
Path to the certificate PEM |
key |
Path to the private-key PEM |
backend |
openssl (default) or rustls (pure-Rust, no system OpenSSL) |
sni |
Per-host cert "<hostname> <cert-path> <key-path>" — repeatable |
handshake_timeout |
Seconds before a stalled TLS handshake is dropped |
brand
Per-SNI branding — one daemon presenting multiple identities. A client that connected via this TLS
SNI host sees this servername/network (welcome burst, ISUPPORT NETWORK=, numeric source)
instead of the globals. Needs TLS+SNI. Repeatable.
| Field | Description |
|---|---|
host |
The TLS SNI hostname this brand applies to |
servername |
Server name shown on this host |
network |
Network name shown on this host |
motd / opermotd
Lines of the MOTD (shown on connect) and the oper MOTD (/OPERMOTD). Each quoted line is one
entry; repeatable.
oper
An oper account. Repeatable. A block with neither password nor fingerprint is refused.
| Field | Description |
|---|---|
name |
Oper account name |
password |
Auth secret (plaintext / sha256: / pbkdf2: / bcrypt) |
fingerprint (fp, certfp) |
Require this TLS client-cert SHA-256 fingerprint (2FA, or alone) |
type |
References an opertype (role); no type = full access |
level |
Operlevel (KILL-protection tier) |
class
A reusable capability class that opertypes compose. Repeatable.
| Field | Description |
|---|---|
name |
Class name |
commands |
Commands granted (* = all, -TOKEN removes one) |
privs |
Privileges granted (* = all, -token removes one) |
snomasks |
Snomask letters granted |
usermodes |
Oper-only user modes the type may set (letters, or *) |
chanmodes |
Oper-only channel modes the type may set (letters, or *) |
opertype
A named oper role (WHOIS "is a <title>"). Repeatable. Ships five: helpop, globop, admin,
servadmin, netadmin (only netadmin holds every privilege).
| Field | Description |
|---|---|
name |
Opertype name (referenced by oper.type) |
classes |
Space-separated capability classes to compose |
modes |
User modes auto-applied on oper-up |
title |
WHOIS title |
level |
Operlevel for this type |
link
A trusted S2S peer. Repeatable.
| Field | Description |
|---|---|
name |
Peer server name |
ip |
Peer address |
port |
Peer port |
password |
Shared link secret |
autoconnect |
Dial the peer on boot / after a netsplit (no default) |
services (uline) |
Mark the peer as a U-lined services server |
services
The linked server that handles SASL (client AUTHENTICATE is relayed to it). Unset = SASL disabled.
| Field | Description |
|---|---|
sasl_server |
Server name that handles SASL |
webirc
Trusted web gateways (kiwiirc / CGI:IRC) that send WEBIRC with the real client's host+ip.
Repeatable.
| Field | Description |
|---|---|
password |
Shared WEBIRC secret |
name (gateway) |
Gateway name |
mask (ipmask) |
Restrict which source IP may use the password |
cloak
Host cloaking for user mode +x.
| Field | Description |
|---|---|
key |
Long random hex secret (keep private; changing it re-cloaks everyone) |
method |
hmac-sha256 (default) / account / fingerprint / static — ordered, first match wins |
account_prefix |
Prefix for the account method (default account) |
cert_prefix |
Prefix for the fingerprint method (default cert) |
static_host (static) |
Host shown for the static method |
dns
Reverse-DNS and ident behaviour.
| Field | Description |
|---|---|
resolve_hosts |
Reverse-DNS on connect (default yes; no = bare IP) |
use_resolved_host |
Use a resolved name in the hostmask (default yes) |
useident |
Look up every client's ident (RFC 1413) |
requireident |
Refuse clients whose ident can't be confirmed |
ident_timeout |
Seconds to wait for the ident reply (default 5) |
dnsbl
A DNS blocklist checked on connect. Repeatable.
| Field | Description |
|---|---|
dnsbl |
Blocklist zone, or a full per-list string "domain=<zone> name=<label> action=<a> duration=<d> reason=<r>" |
dnsbl_action |
mark (default) / kill / kline / gline / zline |
dnsbl_reason |
Reason string |
dnsbl_duration |
Ban seconds for a *line action (default 86400) |
limits
Advertised in ISUPPORT and enforced.
| Field | Default | Description |
|---|---|---|
maxnick |
30 | Nick length (NICKLEN) |
maxchannel |
50 | Channels a user may join |
maxbans |
100 | Ban-list entries per channel |
maxinvites |
100 | Pending invites per user |
modes |
20 | Mode changes per MODE line |
max_line |
16384 | Max bytes per line / recvq |
max_sendq |
1048576 | Queued output before a slow client is dropped |
whowas_maxentries |
256 | Historical nick records retained |
maxwatch |
128 | WATCH entries per user |
maxmonitor |
128 | MONITOR entries per user |
maxsilence |
32 | SILENCE entries per user |
maxaccept |
64 | /ACCEPT (caller-id) entries per user |
maxsignore |
64 | Server-ignore entries per user |
metadata_maxkeys |
32 | IRCv3 METADATA keys per target |
metadata_maxvalue |
512 | METADATA value length |
multiline_maxbytes |
4096 | draft/multiline max bytes |
multiline_maxlines |
24 | draft/multiline max lines |
chathistory_limit |
256 | CHATHISTORY messages kept per conversation |
chathistory_maxage |
604800 | Max age (s) a client may request |
event_playback |
yes | Record JOIN/PART/QUIT/NICK/MODE/TOPIC/KICK into history |
webpush |
yes | draft/webpush master switch (RFC 8291/8292) |
webpush_away_only |
yes | Only push to away users |
webpush_ttl |
259200 | Push TTL (s) |
dccallow_maxentries |
20 | /DCCALLOW entries per user |
http_max_concurrent |
32 | In-flight outbound HTTP requests (API modules) |
webpush_sub, webpush_vapid_file, webpush_database tune the Web Push key/store paths.
timeouts
| Field | Default | Description |
|---|---|---|
registration_timeout |
60 | Drop clients that never register |
ping_frequency |
90 | Idle time before a PING is sent |
ping_timeout |
60 | Then drop if no PONG within this long |
slow_command_ms |
200 | Snotice when one core event takes ≥ this (0 = off) |
flood
| Field | Default | Description |
|---|---|---|
flood_messages |
8 | Messages per window before dropping (opers exempt) |
flood_seconds |
4 | The flood window |
joinflood_duration |
60 | +j default window |
nickflood_duration |
60 | +F default window |
connflood |
"5 10" | Refuse > N connections per S seconds from one IP |
blockamsg |
yes | Block mass /amsg and /ame |
blockamsg_delay |
3 | Same text to a different target list within N s = block |
blockamsg_action |
block | block / kill / gline / kline / zline |
blockamsg_duration |
900 | Ban seconds for a *line action |
connections
| Field | Default | Description |
|---|---|---|
conn_waitpong |
yes | Hold registration until the client echoes a PING cookie |
conn_waitpong_killonbadreply |
yes | Drop on a wrong pong |
conn_waitpong_exempt_localhost4/6 |
yes | Exempt loopback |
connectban |
yes | Z-line an IP range that opens too many connections |
connectban_threshold |
10 | Connections from a range before it's banned |
connectban_duration |
21600 | Ban seconds |
connectban_bootwait |
120 | Grace after startup (reconnect storm) |
connectban_ipv4cidr / connectban_ipv6cidr |
32 / 128 | Range width for counting |
connectban_exempt |
— | Never ban this glob/CIDR (repeatable) |
accept_rate / accept_burst |
0 | Max new connections/sec per source IP at the accept edge |
proxy |
— | Trust the PROXY header from these sources (repeatable) |
classes
Per-class connection policy. connectclass is repeatable; each is a single quoted string
(first match wins).
Tokens: allow=<mask[,mask]>, deny=yes, parent=<name>, requiressl=yes|trusted,
password=<pw>, hash=<algo>, port=<p[,p]>, asn=<n[,n]>, localmax=<n>, globalmax=<n>,
limit=<n>, maxchans=<n>, pingfreq=<s>, timeout=<s>, modes=<+modes>, recvq=<bytes>,
softsendq=<bytes>, hardsendq=<bytes>, fakelag=no, penaltythreshold=<n>, commandrate=<s>,
useident=yes, requireident=yes, resolvehostnames=no, maxconnwarn=yes. connectclass_required yes refuses clients that match no allow class.
sts
Strict Transport Security. Off unless sts_duration > 0.
| Field | Description |
|---|---|
sts_duration |
Seconds clients should stick to TLS (0 = off) |
sts_port |
The TLS port to upgrade to |
sts_preload |
Advertise preload eligibility |
opers
| Field | Default | Description |
|---|---|---|
operprefix |
yes | Give every oper a ! prefix (mode y, above owner) |
ojoin / ojoin_op |
yes | /OJOIN as network staff, optionally opped |
oper_svslogin |
yes | Allow services to SVSLOGIN opers |
maphide |
yes | Hide LINKS / MAP from non-opers |
hideservices |
yes | Hide U-lined services from MAP/LINKS/STATS |
hidewhois |
yes | Hide sensitive WHOIS lines from ordinary users |
hidewhois_* sub-keys tune exactly which WHOIS lines (server, idle, secure) are hidden and whether
opers/self see everything.
channelvis
Restrict who sees a mode change or list mode, by rank. Repeatable.
| Field | Description |
|---|---|
hidemode |
Hide a mode change below a rank: "<mode> <rank>" |
hidelist |
Only this rank+ may view a list mode: "<mode> <rank>" |
channels
| Field | Description |
|---|---|
announce_channels (chancreate) |
Snotice opers when a new channel is created |
channames_deny |
Forbid these chars in new channel names |
permchannels_database |
+P permanent-channel store path |
markread_database |
draft/read-marker store path |
restrictchans |
Only opers may create channels |
restrictchan |
Glob whitelist ordinary users may create (repeatable) |
badchan |
Forbid joining a glob: "<glob> reason=… redirect=… allowopers=yes" |
goodchan |
Whitelist back out of a broad badchan (repeatable) |
users
On-connect behaviour.
| Field | Description |
|---|---|
connbanner |
NOTICE sent at connect (repeatable) |
conn_umodes (autoumodes) |
User modes auto-set on every client |
autojoin (conn_join) |
Channels every client auto-joins (repeatable) |
seenicks |
Snotice opers on every nick change |
opermodes (oper_umodes) |
Extra user modes set on oper-up |
operjoin |
Channels an oper auto-joins on oper-up (repeatable) |
vhost |
Self-service vhost: "<user> <pass> <host>" (repeatable) |
accounts
Bridges IRCv3 draft/account-registration to an HTTP backend.
| Field | Description |
|---|---|
account_registration |
Master switch (default no) |
acctregister_registerurl / acctregister_verifyurl |
REGISTER / VERIFY endpoints |
acctregister_apikey |
Sent as X-API-Key |
acctregister_autologin / acctregister_beforeconnect / acctregister_emailrequired / acctregister_requiretls |
Policy toggles |
acctregister_ratecount / acctregister_ratetime |
Rate limit per IP |
verification
Anti-bot gates (reCAPTCHA / Cloudflare challenge). Keys: recaptcha, recaptcha_secret,
recaptcha_url, recaptcha_issuer, recaptcha_ttl, recaptcha_message,
recaptcha_whitelistports (repeatable) — and the matching cloudflare_* set.
antiabuse
| Field | Description |
|---|---|
antirandom |
Score random-looking nick/ident/realname (drones) |
antirandom_threshold / antirandom_checkfull / antirandom_action / antirandom_duration / antirandom_reason / antirandom_showfailed |
Tuning + action |
hashident / hashident_key |
Replace ident with a stable opaque per-IP token (HMAC key) |
locale / locale_dir |
Server-wide language (en default; fr/es ship); rehash to switch |
solvemsg |
Unvouched users answer one arithmetic question before PMs deliver |
antimixedutf8 / amu_threshold / amu_minlen / amu_action / amu_target / amu_reason |
Block look-alike mixed-script spam |
badword |
+G censor word "<find> [replacement]" (repeatable) |
restrictions
| Field | Description |
|---|---|
restrictmsg |
Only opers/services may be PM'd by ordinary users |
disabled_commands |
Refuse these commands to ordinary users (repeatable) |
restrictcommand |
Per-command: "<CMD> connectdelay=<s> exemptidentified=yes exempttls=no reason=…" |
securelist + securelist_* |
Delay /LIST for new connections (defeats list-spam bots) |
autodrop_commands |
Silently drop a pre-registration client that sends any of these (HTTP scanners) |
reputation
Per-address scoring plus the y: score extban.
| Field | Description |
|---|---|
reputation_database |
Store path |
reputation_minchanmembers |
Only bump if in a channel this big |
reputation_scorecap |
Maximum score |
reputation_whois |
Who sees the score: all / opers / self / none |
reputationexpire |
Decay rule "<score> <age>" (repeatable) |
securitygroups
Named groups usable as an extban (+b g:<name>). securitygroup is repeatable, each a quoted
string: "<name> <criteria…>" where criteria include public, tls, insecure, account,
unregistered, oper, exclude-oper, bot, webirc, mask=<glob>, exclude=<glob>,
scoremin=<n>, scoremax=<n>, asn=<n[,n]>.
logging
| Field | Description |
|---|---|
syslog / syslog_target / syslog_facility / syslog_tag |
Mirror the log stream to syslog (Unix socket or host:port UDP) |
log_json |
Append the log stream to a file as JSONL |
snoop_stderr |
Also echo server-notices to stderr |
metrics_bind |
OpenMetrics/Prometheus scrape endpoint (bind privately), e.g. "127.0.0.1:9109" |
chanlog |
Mirror oper snotices into a channel, optionally filtered by snomask letters (repeatable) |
modules
Extra features toggled here.
| Field | Description |
|---|---|
abbreviation |
A unique command prefix resolves to its command (WHOI→WHOIS) |
alias |
Command alias "<ALIAS> <target>", e.g. "NS NickServ" (repeatable) |
customprefix |
Reconfigure or add channel-prefix tiers |
customtitle |
/TITLE <name> <pass> grants a WHOIS title (+ optional vhost) |
randquote |
Greet each connecting user with a random line (repeatable) |
showfile |
Serve a text file as its own command: "<CMD> <path>" |
filter_engine |
Oper /FILTER pattern engine: glob (default) or regex |
geoip_database / geoip_asn_database |
MaxMind .mmdb for country/city and ASN (enables G:/asn= and WHOIS geo) |
network_icon |
Advertise a network icon (draft/ICON) |
relaymsg_separators / relaymsg_ident / relaymsg_host |
draft/relaymsg (/RELAYMSG) for bridges |
extjwt_secret / extjwt_duration / extjwt_chunk / extjwt_service |
/EXTJWT token issuance |
filehost_* |
Advertise a file-upload service + issue upload tokens |
dccallow_blockfile / dccallow_blockchat |
Block unwanted DCC unless /DCCALLOW +<nick> |
http_tls_verify |
Verify upstream TLS certs for the HTTP client (API modules) |
websocket
Relevant only with a ws/wss listener.
| Field | Default | Description |
|---|---|---|
ws_origin |
— | Allowed Origin globs (repeatable; empty = any) |
ws_proxyranges |
— | Proxies whose X-Real-IP/XFF we trust (repeatable) |
ws_trust_proxy |
no | Trust those headers from ANY peer |
ws_allowmissingorigin |
yes | Allow clients that send no Origin |
ws_defaultmode |
text | Frame mode with no subprotocol: text / binary / reject |
ws_nativeping |
yes | Liveness via WebSocket pings (else IRC PING) |
ws_handshake_timeout |
10 | Seconds to complete the HTTP Upgrade |
ws_ping_interval |
60 | Seconds between keepalive pings |
ws_timeout |
120 | Drop after this many seconds of silence |