echo/website
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: full reference for the daemon and echo services (modes, extbans, snomasks, commands, config reference, privileges, CLI, metrics/rpc, per-service pages)

Browse source
This commit is contained in:
Jean Chevronnet 2026-08-30 21:00:58 +00:00
parent c4836c7dd1
commit d81c07ef01
No known key found for this signature in database
GPG key ID: 439666D63A9477E4
23 changed files with 1685 additions and 84 deletions
Download patch file Download diff file Expand all files Collapse all files

32
content/docs/botserv.md Normal file
View file

@ -0,0 +1,32 @@
# BotServ
Bot services — channel bots that speak, moderate, and auto-respond. Message it with
`/msg BotServ <command>`.
## Assigning & speaking
| Command | Syntax | Description |
| --- | --- | --- |
| ASSIGN | `ASSIGN <#channel> <bot>` | Put a bot in a channel |
| UNASSIGN | `UNASSIGN <#channel>` | Remove a channel's bot |
| INFO | `INFO <bot \| #channel>` | Show bot / channel settings |
| SAY | `SAY <#channel> <text>` | Speak through the bot |
| ACT | `ACT <#channel> <text>` | Action (`/me`) through the bot |
| BOTLIST | `BOTLIST` | List assignable bots |
## Behaviour
| Command | Syntax | Description |
| --- | --- | --- |
| SET | `SET <#channel> <GREET\|BANEXPIRE\|NOBOT\|VOTEKICK> <value>` · `SET <bot> PRIVATE <ON\|OFF>` | Configure bot behaviour |
| KICK | `KICK <#channel> <CAPS\|FLOOD\|REPEAT\|BADWORDS\|…> <ON\|OFF> [params]` · `KICK <#channel> TTB <n> \| TEST <message>` | Configure kickers |
| BADWORDS | `BADWORDS <#channel> ADD\|DEL\|LIST\|CLEAR [pattern]` | Manage badword patterns |
| TRIGGER | `TRIGGER <#channel> ADD <regex>\|<response>[.\|<cooldown>]` · `DEL <num>` · `LIST` · `CLEAR` | Manage auto-responses |
| COPY | `COPY <#source> <#dest>` | Clone bot settings |
## Operator
| Command | Syntax | Description |
| --- | --- | --- |
| AUTOASSIGN | `AUTOASSIGN <bot> \| OFF` | Default bot for new channels |
| BOT | `BOT ADD\|CHANGE\|DEL\|LIST` | Manage the bots themselves |

84
content/docs/channel-modes.md Normal file
View file

@ -0,0 +1,84 @@
# Channel modes
Set with `MODE <#channel> +<mode> [param]`. Modes are grouped by the four CHANMODES types the server
advertises in ISUPPORT: **A** (list modes, always take a parameter), **B** (always take a parameter),
**C** (parameter only when set), **D** (flag, no parameter). Membership **prefixes** are listed at
the end.
## Type A — list modes
Each takes a parameter; using it with no parameter queries the list.
| Mode | Name | Description |
| --- | --- | --- |
| `b` | ban | Ban a matching `nick!user@host` or [extban](/docs/extbans) from the channel |
| `e` | ban exception | Exempt a matching mask from bans |
| `I` | invite exception | A matching mask may join a `+i` channel without an invite |
| `g` | spamfilter | Per-channel message word/glob filters (matches message text) |
| `X` | exemptchanops | `<restriction>:<rankchar>` — exempt members at/above a rank from a named restriction |
| `w` | autoop | `<prefixchar>:<hostmask>` — auto-grant a status prefix on join |
## Type B — always take a parameter
| Mode | Name | Description |
| --- | --- | --- |
| `k` | key | Channel password required to join |
## Type C — parameter only when set
| Mode | Name | Param | Description |
| --- | --- | --- | --- |
| `l` | limit | `<n>` | Maximum member count |
| `f` | message flood | `[*]<lines>:<secs>` | Kick a user exceeding the rate; leading `*` also bans |
| `j` | join flood | `<joins>:<secs>` | Lock new joins for 60s after the threshold |
| `F` | nick flood | `<changes>:<secs>` | Block nick changes for 60s after the threshold |
| `L` | redirect | `<#target>` | Send joiners to another channel when `+l`-full |
| `H` | history | `<lines>[:<secs>]` | Replay recent messages to joiners |
| `B` | anticaps | `<1..100>` | Reject messages that are ≥ this % uppercase (ops exempt) |
| `J` | kicknorejoin | `<secs>` | Block rejoin for N seconds after a kick |
| `d` | delaymsg | `<secs>` | New members can't speak for N seconds (voiced+ exempt) |
| `K` | norepeat | `<n>` | Block a message identical to one of the sender's previous N lines |
## Type D — flag modes
| Mode | Name | Description |
| --- | --- | --- |
| `A` | allowinvite | Any member may use `INVITE` |
| `C` | noctcp | Block CTCPs to the channel |
| `D` | delayjoin | Hide joining members until they speak or gain a prefix |
| `G` | censor | Apply the network word censor to messages |
| `M` | regmoderated | Only registered (logged-in) users may speak |
| `N` | nonick | Block nick changes by members while in the channel |
| `O` | operonly | Only IRC operators may join (oper-set) |
| `P` | permanent | Channel persists with no members (oper-set) |
| `Q` | nokicks | Block `KICK` in the channel |
| `R` | regonly | Only registered users may join |
| `S` | stripcolor | Strip mIRC colour/formatting from messages |
| `T` | nonotice | Block `NOTICE`s to the channel |
| `U` | opmoderated | Messages from unprivileged users go only to ops |
| `c` | nocolor | Block messages containing colour/formatting |
| `i` | inviteonly | Require an invite (or `+I` match) to join |
| `m` | moderated | Only voiced+ may speak |
| `n` | noexternal | Block messages from users not in the channel |
| `p` | private | Private channel |
| `r` | registered | Registered channel — set only by services |
| `s` | secret | Secret channel (hidden from LIST/WHOIS) |
| `t` | topiclock | Only ops may change the topic |
| `z` | secureonly | Only TLS users may join (settable only when all members are on TLS) |
## Prefix / status modes
Take a nick parameter; ordered high → low rank. Sigils and the ranks required to grant/revoke are
configurable via `customprefix`.
| Mode | Prefix | Name | Rank |
| --- | --- | --- | --- |
| `y` | `!` | oper prefix (network staff) | 60 |
| `q` | `~` | owner / founder | 50 |
| `a` | `&` | admin / protected | 40 |
| `o` | `@` | op | 30 |
| `h` | `%` | halfop | 20 |
| `v` | `+` | voice | 10 |
The `!` oper prefix only exists when `operprefix` or `ojoin` is enabled. Granting or removing a prefix
requires out-ranking both the configured set/unset rank and the target's current top rank.

57
content/docs/chanserv.md Normal file
View file

@ -0,0 +1,57 @@
# ChanServ
Channel services — register and manage channels, their access lists, modes, and topics. Message it
with `/msg ChanServ <command>`.
## Registration & info
| Command | Syntax | Description |
| --- | --- | --- |
| REGISTER | `REGISTER <#channel>` | Register a channel |
| INFO | `INFO <#channel>` | Show channel information |
| LIST | `LIST` | List registered channels |
| DROP | `DROP <#channel>` | Delete the registration |
| SET | `SET <#channel> <option> <value>` | Founder / settings (`FOUNDER`, `DESC`, `URL`, `EMAIL`, `SUCCESSOR`, and the `SIGNKICK` / `PRIVATE` / `PEACE` / `SECUREOPS` / `SECUREVOICES` / `RESTRICTED` / `AUTOOP` / `KEEPTOPIC` / `TOPICLOCK` toggles) |
## Access
| Command | Syntax | Description |
| --- | --- | --- |
| ACCESS | `ACCESS <#channel> LIST` · `ADD <account\|!group> <sop\|op\|halfop\|voice>` · `DEL <account\|!group>` | Manage the access list |
| FLAGS | `FLAGS <#channel> [account [+/-flags]]` | Granular per-account flags |
| LEVELS | `LEVELS <#channel> [SET <capability> <tier> \| RESET <capability>]` | Tune which tier holds each capability |
| SOP / AOP / HOP / VOP | `<tier> <#channel> ADD\|DEL\|LIST <account>` | Tiered access shortcuts |
| STATUS | `STATUS <#channel> [nick]` | Show a user's access level |
## Status & moderation
| Command | Syntax | Description |
| --- | --- | --- |
| OP / DEOP / VOICE / DEVOICE | `<verb> <#channel> [nick]` | Give or take op / voice |
| OWNER / PROTECT / HALFOP | `<verb> <#channel> [nick]` (and `DE-` forms) | Give or take higher status |
| UP / DOWN | `UP\|DOWN <#channel>` | Apply or drop your own status |
| KICK | `KICK <#channel> <nick> [reason]` | Kick from the channel |
| BAN / UNBAN | `BAN <#channel> <nick> [reason]` · `UNBAN <#channel> [nick]` | Ban or unban |
| AKICK | `AKICK <#channel> ADD <mask> [reason]` · `DEL <mask>` · `LIST` · `CLEAR` | Auto-kick list |
| INVITE | `INVITE <#channel> [nick]` | Invite into the channel |
| ENFORCE / SYNC | `ENFORCE <#channel>` | Re-apply locks and access |
## Topic & modes
| Command | Syntax | Description |
| --- | --- | --- |
| TOPIC | `TOPIC <#channel> <text>` | Set the topic |
| ENTRYMSG | `ENTRYMSG <#channel> [CLEAR \| <text>]` | Message shown on join |
| MODE | `MODE <#channel> <modes>` | Set channel modes |
| MLOCK | `MLOCK <#channel> [modes]` | Lock channel modes |
| GETKEY | `GETKEY <#channel>` | Show the channel key |
## Utility & operator
| Command | Syntax | Description |
| --- | --- | --- |
| SEEN | `SEEN <nick>` | When a nick was last seen |
| CLONE | `CLONE <source> <target>` | Copy channel settings |
| RENAME | `RENAME <#channel> <#newname>` | Rename the channel |
| SUSPEND / UNSUSPEND | `SUSPEND <#channel> [+expiry] [reason]` · `UNSUSPEND <#channel>` | Suspend / unsuspend (operator) |
| NOEXPIRE | `NOEXPIRE <#channel> {ON\|OFF}` | Pin against expiry (operator) |

50
content/docs/cli.md Normal file
View file

@ -0,0 +1,50 @@
# CLI tools
The `echoircd` binary dispatches on its first argument. Any first argument that is not one of the
subcommands below is treated as the path to a config file to boot the server with.
## Boot the server
```sh
echoircd [config]
```
Loads the config (default `echoircd.conf`), binds the plaintext / TLS / S2S / WebSocket / RPC /
metrics listeners, and runs the single-threaded core.
## rehash
```sh
echoircd rehash [config]
```
Signal a **running** server to reload its configuration in place — it finds the process via the
pidfile (or a `/proc` scan) and sends `SIGHUP`, then exits without booting a new server. Most options
re-apply live, and the TLS certificate is re-read, with no restart and no disconnects.
## checkconfig
```sh
echoircd checkconfig [config]
```
Parse a config and print a deterministic, sorted dump of every key/value it produces — validate a
config before deploying it, or diff two configs (for example the block form against the legacy flat
form). Exits non-zero on an unreadable file or an empty `servername`.
## mkpasswd
```sh
echoircd mkpasswd [cost]
```
Read a password from **stdin** (never from the command line, to keep it out of `ps` and shell
history) and print its bcrypt hash — a config-ready value for an `oper` block's `password`. Takes an
optional bcrypt cost (default 11).
```sh
printf '%s' 'my-secret' | echoircd mkpasswd
```
> The in-daemon `MKPASSWD` **command** is separate from this CLI subcommand: the command supports
> md5/sha1/sha256/sha512/pbkdf2 for oper-issued credentials, while the CLI produces a bcrypt hash.

150
content/docs/commands.md Normal file
View file

@ -0,0 +1,150 @@
# Command reference
Every command echoIRCd implements. Client commands are available to all users; operator commands
require `+o` and may be further restricted by your oper type (see [Operators](/docs/operators)).
## Client commands
### Connection & session
| Command | Purpose |
| --- | --- |
| `NICK` | Set or change nickname |
| `USER` | Register username/realname during registration |
| `PASS` | Supply a connection password before registration |
| `PING` / `PONG` | Liveness keepalive |
| `QUIT` | Disconnect |
| `AWAY` | Set or clear away status |
| `CAP` | Negotiate IRCv3 capabilities |
| `AUTHENTICATE` | SASL authentication handshake |
| `SETNAME` | Change realname (IRCv3) |
| `VHOST` | Claim a configured self-service virtual host |
| `WEBIRC` | Gateway declares the real client host/IP |
### Channels
| Command | Purpose |
| --- | --- |
| `JOIN` / `PART` | Join / leave channels |
| `TOPIC` | View or set a channel topic |
| `KICK` / `REMOVE` | Remove a user (REMOVE shows as a PART); halfop+ |
| `INVITE` / `UNINVITE` | Invite or revoke a pending invite |
| `KNOCK` | Request an invite to an invite-only channel |
| `CYCLE` | Part and immediately rejoin |
| `RENAME` | Rename a channel (op+) |
| `TBAN` | Set a temporary, auto-expiring channel ban |
| `NAMES` | List channel members |
| `MODE` | Query or change channel/user modes |
| `PROP` | Set/query channel modes by long name instead of letter |
| `RMODE` | Bulk-remove list-mode entries (`+b`/`+e`/`+I`) by pattern |
### Messaging
| Command | Purpose |
| --- | --- |
| `PRIVMSG` / `NOTICE` | Message a channel or user |
| `TAGMSG` | Send client-only tags (typing, reactions) with no body |
| `CHATHISTORY` | Replay recent channel/DM history |
| `REDACT` | Delete a sent message (author, halfop+, or oper) |
| `MARKREAD` | Set/query a per-conversation read marker |
| `SILENCE` | Server-side ignore of incoming messages |
| `SIGNORE` | Mutual (two-way) server-side ignore |
| `ACCEPT` | Manage the caller-id (`+g`) allow-list |
| `DCCALLOW` | Manage nicks permitted to DCC you |
### Information
| Command | Purpose |
| --- | --- |
| `WHOIS` / `WHO` / `WHOWAS` | Look up users, current and historical |
| `LIST` | List channels with counts and topics |
| `LUSERS` | User/server counts |
| `VERSION` / `TIME` / `ADMIN` / `INFO` / `MOTD` | Server information |
| `HELP` | Built-in help topics |
| `LINKS` / `MAP` | Known servers / topology |
| `ISON` / `USERHOST` | Online status / host lookup |
| `SSLINFO` | TLS status + client-cert fingerprint (querying others needs oper) |
| `STATS` | Server statistics (`uptime` open to all; other letters oper-only) |
| `ISUPPORT` | Re-send the ISUPPORT (005) tokens |
| `WATCH` / `MONITOR` | Online/offline notify lists |
### IRCv3 & accounts
| Command | Purpose |
| --- | --- |
| `BATCH` | Client side of multiline |
| `METADATA` | GET/LIST/SET/CLEAR user/channel metadata |
| `WEBPUSH` | Register/unregister Web Push subscriptions |
| `EXTJWT` | Issue a server-signed JWT proving IRC identity |
| `FILEHOST` | Request a signed file-upload link |
| `SECURITYGROUPS` | List the security groups a user is in |
| `TITLE` | Claim a configured custom title/vhost |
| `REGISTER` / `VERIFY` | In-band account registration |
| `CAPTCHA` / `VERIFYCHALLENGE` | Present a human-verification token |
| `RELAYMSG` | Send a channel message under a spoofed relay nick (oper) |
## Operator commands
Commands marked *typed* are further gated by your oper type's command set; an untyped ("legacy")
oper has them all.
### Network bans (X-lines)
| Command | Purpose |
| --- | --- |
| `KILL` | Forcibly disconnect a user |
| `KLINE` / `GLINE` / `ZLINE` | Ban a `user@host` (this server / network-wide / by IP) |
| `QLINE` | Reserve/forbid a nick glob |
| `ELINE` | Exempt a mask from K/G/Z-lines |
| `RLINE` | Ban users matching a regular expression |
| `SHUN` | Let a user connect but silently drop their commands |
| `CBAN` | Forbid a channel-name glob |
| `TLINE` | Report how many users a would-be ban mask would match |
### Services / SA overrides
| Command | Purpose |
| --- | --- |
| `SAJOIN` / `SAPART` | Force a user in/out of a channel |
| `SANICK` | Force a nick change |
| `SAKICK` | Kick a user as the server |
| `SAMODE` | Apply a channel MODE with server authority |
| `SATOPIC` | Set a topic as the server |
| `SAQUIT` | Force a user to quit |
| `CLEARCHAN` | Kick everyone out of a channel |
| `SVSNICK` / `SVSJOIN` / `SVSPART` / `SVSMODE` | Services forcing nick/join/part/modes |
| `SVSLOGIN` / `SVSLOGOUT` | Services log a user in/out of an account |
| `NICKLOCK` / `NICKUNLOCK` | Force and lock a nick, or release it |
### Host / identity
| Command | Purpose |
| --- | --- |
| `CHGHOST` / `CHGIDENT` / `CHGNAME` | Change another user's host / ident / realname |
| `SETHOST` / `SETIDENT` / `SETIDLE` | Change your own host / ident / idle |
| `SWHOIS` | Attach an extra WHOIS line to a user |
### Broadcast & network
| Command | Purpose |
| --- | --- |
| `WALLOPS` | Message all users with `+w` |
| `GLOBOPS` | Message all operators |
| `CONNECT` / `SQUIT` | Dial / disconnect a server link |
| `DIE` / `RESTART` | Shut down / restart the server |
| `REHASH` | Reload the configuration |
| `OPER` | Authenticate as an operator |
### Oper tools
| Command | Purpose |
| --- | --- |
| `CHECK` | Diagnostic dump for a nick or channel |
| `MODULES` | List loaded modules |
| `MKPASSWD` | Hash a password into a config-ready credential |
| `FILTER` | Manage spam/word filters |
| `REPUTATION` | Show or set a masked address's reputation |
| `GEOIP` | Report the country of a user or IP |
| `OJOIN` | Join a channel as network staff |
| `ALLTIME` | Show the server time to opers |
| `OPERMOTD` | Show the operator MOTD |

438
content/docs/config-reference.md Normal file
View file

@ -0,0 +1,438 @@
# Configuration reference
Every configuration block and field echoIRCd understands. For the format itself and a quick start,
see [Configuration](/docs/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 = value` format 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 |

33
content/docs/extbans.md Normal file
View file

@ -0,0 +1,33 @@
# Extended bans
Extbans extend `+b` (and the `+e` / `+I` exceptions) beyond a plain `nick!user@host` mask. Use them
as `MODE <#channel> +b <letter>:<value>`. The server advertises `EXTBAN=,aGAbcgjmnrsy` and
`ACCOUNTEXTBAN=a`.
There are two kinds. **Matching** extbans decide whether a user matches (for a ban or an exception);
**acting** extbans restrict a specific action instead of blocking the join.
## Matching extbans
| Letter | Name | Matches |
| --- | --- | --- |
| `a` | account | A services account glob, e.g. `+b a:spammer` (a user with no account never matches) |
| `g` | securitygroup | Members of a named [security group](/docs/security), e.g. `+b g:<name>` |
| `y` | reputation | A reputation-score range, e.g. `+b y:<100`, `+b y:>500` |
| `r` | realname | A real-name (GECOS) glob, e.g. `+b r:*spammer*` |
| `j` | channel | Users also in another channel; an optional status prefix narrows by rank, e.g. `+b j:@#staff` |
| `s` | server | Users on a given server name, e.g. `+b s:irc.example.net` |
| `G` | geoip | A country code, e.g. `+b G:<cc>` (needs a GeoIP database) |
| `A` | asn | An origin AS number |
| `b` | banlist | Users caught by another channel's ban list, e.g. `+b b:#staff` (non-recursive) |
## Acting extbans
These gate an action for matching users rather than blocking their join. An `+e` exception with the
same `letter:value` cancels the restriction.
| Letter | Name | Restricts |
| --- | --- | --- |
| `m` | mute | Matching users below voice may not send channel messages |
| `c` | blockcolor | Matching users may not send messages containing colour/formatting |
| `n` | nonick | Matching users may not change nick while in the channel |

26
content/docs/hostserv.md Normal file
View file

@ -0,0 +1,26 @@
# HostServ
Host services — virtual host (vhost) requests, offers, and assignment. Message it with
`/msg HostServ <command>`.
## User commands
| Command | Syntax | Description |
| --- | --- | --- |
| ON | `ON` | Activate your vhost |
| OFF | `OFF` | Restore your normal host |
| REQUEST | `REQUEST <host>` | Request a vhost |
| OFFERLIST | `OFFERLIST` | Show the vhost menu |
| TAKE | `TAKE <number>` | Take a vhost from the menu |
## Operator commands
| Command | Syntax | Description |
| --- | --- | --- |
| SET | `SET <account> <host> [duration]` | Assign a vhost |
| DEL | `DEL <account>` | Remove a vhost |
| LIST | `LIST` | List vhosts |
| WAITING | `WAITING` | Pending requests |
| ACTIVATE / REJECT | `ACTIVATE\|REJECT <account>` | Approve or reject a request |
| OFFER / OFFERDEL | `OFFER <host>` · `OFFERDEL <number>` | Add / remove a menu vhost |
| FORBID / FORBIDDEL | `FORBID <regex>` · `FORBIDDEL <number>` | Forbid / un-forbid a vhost pattern |

64
content/docs/ircv3.md
View file

@ -1,28 +1,50 @@
# IRCv3 capabilities # IRCv3 capabilities
echoIRCd implements a broad set of IRCv3 capabilities. Clients negotiate them with `CAP LS` and Clients negotiate capabilities with `CAP LS` / `CAP REQ`. echoIRCd advertises the following.
`CAP REQ`. `draft/multiline`, `sasl`, and `draft/account-registration` carry `=`-value parameters (limits, the
SASL mechanism list, enabled sub-features) to CAP-302 clients.
## Advertised capabilities ## Ratified
```text | Capability | Meaning |
server-time message-tags account-tag account-notify | --- | --- |
extended-join chghost multi-prefix away-notify | `sasl` | SASL authentication (mechanism list attached for CAP 302) |
invite-notify setname echo-message userhost-in-names | `server-time` | A `time=` tag with each message's server timestamp |
batch labeled-response standard-replies extended-monitor | `message-tags` | Generic message-tag support, including relaying client `+` tags |
draft/chathistory draft/event-playback draft/message-redaction | `multi-prefix` | Show all of a member's status prefixes in NAMES/WHO |
draft/multiline draft/metadata-2 draft/read-marker draft/webpush | `away-notify` | Real-time AWAY / back notifications |
draft/account-registration sts | `account-notify` | Notify when a user logs in/out of an account |
``` | `extended-join` | JOIN carries the account name and realname |
| `chghost` | Real-time host/ident change notifications |
| `userhost-in-names` | Full `nick!user@host` in NAMES |
| `echo-message` | Echo the sender's own PRIVMSG/NOTICE back |
| `invite-notify` | Notify channel ops when a user is invited |
| `setname` | Real-time realname change notifications |
| `extended-monitor` | MONITOR reflects extended state changes |
| `account-tag` | An `account=` tag identifying the sender's account |
| `standard-replies` | Structured `FAIL` / `WARN` / `NOTE` replies |
| `labeled-response` | Correlate a command with its response via `label` |
| `batch` | Group related messages into a `BATCH` |
| `cap-notify` | Tell the client when caps are added/removed |
## Notable features ## Draft & vendor
- **CHATHISTORY** — replay recent conversation, with server-side storage. | Capability | Meaning |
- **labeled-response** + **batch** — correlate replies to the command that caused them. | --- | --- |
- **multiline** — send a message that spans lines as a single logical message. | `draft/chathistory` | Request replay of past channel/DM messages |
- **STS** — advertise a strict-transport-security policy so clients upgrade to TLS. | `draft/event-playback` | Include channel events (JOIN/PART/QUIT/NICK/MODE/TOPIC/KICK) in history |
- **draft/webpush** — RFC 8291 / 8292 Web Push notifications for supporting clients. | `draft/message-redaction` | `REDACT` a previously-sent message |
| `draft/pre-away` | Set AWAY during registration |
| `draft/metadata-2` | Per-user/channel arbitrary metadata |
| `draft/multiline` | Send one logical message across multiple lines |
| `draft/account-registration` | In-band account `REGISTER` / `VERIFY` |
| `draft/json-log` | Structured JSON tag on server notices (opers) |
| `draft/extended-isupport` | Re-request ISUPPORT (005) tokens on demand |
| `draft/relaymsg` | Send channel messages under a spoofed relay nick (bridges) |
| `draft/channel-rename` | Rename a channel in place (`RENAME`) |
| `draft/read-marker` | Per-conversation read-marker sync across devices |
| `draft/webpush` | Web Push subscription for backgrounded/away notifications |
| `draft/filehost` | Advertise an external file-host + signed upload links |
| `no-implicit-names` | Suppress the automatic NAMES burst on JOIN |
## SASL For SASL mechanisms, see [Accounts & SASL](/docs/accounts).
SASL is a capability too — see [Accounts & SASL](/docs/accounts) for the supported mechanisms.

24
content/docs/memoserv.md Normal file
View file

@ -0,0 +1,24 @@
# MemoServ
Memo services — leave and read offline messages between accounts. Message it with
`/msg MemoServ <command>`.
| Command | Syntax | Description |
| --- | --- | --- |
| SEND | `SEND <nick> <text>` | Leave a memo for an account |
| RSEND | `RSEND <nick> <text>` | Leave a memo and get a read receipt |
| LIST | `LIST` | List your memos |
| READ | `READ <num>\|NEW\|ALL` | Read a memo |
| DEL | `DEL <num>\|ALL` | Delete a memo (alias `DELETE`) |
| CANCEL | `CANCEL <nick>` | Recall a memo you sent |
| CHECK | `CHECK <nick>` | See if a memo you sent was read |
| INFO | `INFO` | Your mailbox summary |
| IGNORE | `IGNORE ADD\|DEL <nick>` · `LIST` | Block memos from an account |
| SET | `SET NOTIFY {ON\|OFF}` · `SET LIMIT <n>\|NONE` | Your memo preferences |
## Operator
| Command | Syntax | Description |
| --- | --- | --- |
| SENDALL | `SENDALL <text>` | Memo every account |
| STAFF | `STAFF <text>` | Memo every operator |

53
content/docs/metrics-rpc.md Normal file
View file

@ -0,0 +1,53 @@
# Metrics & RPC
echoIRCd exposes two machine interfaces for monitoring and control. Both bind privately by default —
keep them on loopback or behind a trusted proxy.
## Prometheus metrics
Enable an OpenMetrics/Prometheus scrape endpoint with a single config key:
```ini
metrics_bind "127.0.0.1:9109";
```
It answers any HTTP `GET` with the text-exposition format — no authentication, so bind it somewhere
private. Counters are bumped inline (lock-free atomics); the gauges are republished by the core each
tick.
| Metric | Type | Meaning |
| --- | --- | --- |
| `echoircd_commands_total` | counter | Commands dispatched |
| `echoircd_messages_total` | counter | PRIVMSG/NOTICE handled |
| `echoircd_connects_total` | counter | Client registrations completed |
| `echoircd_users` | gauge | Users online |
| `echoircd_channels` | gauge | Channels in existence |
| `echoircd_servers` | gauge | Servers known on the network |
| `echoircd_links` | gauge | Direct server links |
## JSON-RPC 2.0
A JSON-RPC 2.0 control interface lets admin tools introspect and drive the daemon. It is **off**
unless both `rpc = yes` and an `rpc_token` are set; it binds `rpc_bind` (default `127.0.0.1:8080`) and
every request must carry the token as HTTP Basic or Bearer auth (checked in constant time).
```ini
rpc = yes;
rpc_token "a-long-random-secret";
rpc_bind "127.0.0.1:8080";
```
Method families:
| Family | Methods |
| --- | --- |
| core | `rpc.methods`, `rpc.info`, `server.info`, `stats.get` |
| user | `user.list` / `get`, `user.kill` / `set_mode` / `set_vhost` / `set_nick` / `set_oper` |
| channel | `channel.list` / `get`, `channel.kick` / `set_topic` / `set_mode` |
| server | `server.list` / `rehash` / `connect` / `disconnect` |
| ban | `xline.list` / `add` / `del` (K/G/Z/E/SHUN/Q/CBAN) |
| message | `message.send_notice` (channel / user / all) |
| spamfilter | `spamfilter.list` / `add` / `del` |
| stats | `module.list`, `oper.list`, `security_group.list` |
| whowas | `whowas.get` |
| log | `log.tail`, `log.events` |

102
content/docs/modules.md Normal file
View file

@ -0,0 +1,102 @@
# Modules
echoIRCd is built module-per-file: each feature lives in its own source module, and most are toggled
through the [configuration](/docs/config-reference). This is the full set that ships in the tree.
## Anti-abuse & access control
| Module | Provides |
| --- | --- |
| `connclass` | Connection classes — match by IP/host/TLS/port, then apply reject / clone-caps / password / modes / queue / flood / ping policy |
| `connflood` | Refuse connections from an IP opening too many too fast |
| `connectban` | Z-line an IP range that opens too many connections |
| `conn_waitpong` | Hold registration until the client PONGs an exact server cookie |
| `flood` | Per-user message-rate limit (fakelag); opers exempt |
| `dnsbl` | DNS blocklist checks on connect |
| `reputation` | Per-address reputation scoring over time; `y:` extban |
| `securitygroups` | Named AND-ed user sets; `g:` extban |
| `antirandom` | Score drone-like random nick/ident/realname |
| `antimixedutf8` | Block mixed-Unicode-script look-alike spam |
| `filter` | Oper-configured spam/word glob filters |
| `blockamsg` | Block mass `/amsg` and `/ame` |
| `solvemsg` | Un-vouched user answers an arithmetic question before PMs deliver |
| `recaptcha` / `cloudflare_challenge` | Registration human-verification gates |
| `autodrop` | Silently drop HTTP-scanner connections |
| `restrictmsg` / `restrictcommands` / `restrictchans` / `denychans` / `channames` | Message/command/channel restrictions |
| `dccallow` | Gate DCC by filename unless the recipient allowed the sender |
| `hashident` | Replace ident with a stable per-IP HMAC token |
## Bans & extbans
| Module | Provides |
| --- | --- |
| `accountban` | `a:` extban (match by account) |
| `realnameban` | `r:` extban (match by realname) |
| `serverban` | `s:` extban (match by server) |
| `channelban` | `j:` extban (match by another channel) |
| `extbanbanlist` | `b:` extban (match another channel's ban list) |
| `banredirect` | `+b <mask>$<#channel>` bounces a banned user elsewhere |
| `geoip` | GeoIP + `G:` country extban, `GEOIP`, WHOIS geo |
| `asn` | ASN lookup feeding classes, groups, extbans, WHOIS |
## Channels & modes
| Module | Provides |
| --- | --- |
| `customprefix` | Reconfigure or add channel prefix tiers |
| `namedmodes` | `PROP` — set/query modes by long name |
| `permchannels` | Persist `+P` permanent channels across restarts |
| `autoop` | `+w` auto-grant a prefix on join |
| `rmode` | Bulk-remove list-mode entries |
| `hidemode` / `hidelist` | Hide mode changes / list entries below a rank |
## IRCv3 & client features
| Module | Provides |
| --- | --- |
| `chathistory` | `draft/chathistory` + `draft/message-redaction` |
| `event_playback` | `draft/event-playback` |
| `multiline` | Server side of `draft/multiline` |
| `metadata` | `draft/metadata-2` |
| `markread` | `draft/read-marker` |
| `webpush` | `draft/webpush` (RFC 8291/8292) |
| `account_registration` | `draft/account-registration` bridged to an HTTP backend |
| `extended_isupport` | `draft/extended-isupport` |
| `relaymsg` | `draft/relaymsg` |
| `filehost` | Advertise a file-host + signed upload links |
| `extjwt` | `EXTJWT` server-signed identity tokens |
| `irccloudtags` | Validate IRCCloud client-only tags |
## Operators & staff
| Module | Provides |
| --- | --- |
| `opertypes` | Oper classes + types (capability bundles) |
| `operlevels` | Numeric oper level (KILL protection tiers) |
| `operprefix` | The `!` oper channel prefix |
| `ojoin` | Join a channel as network staff |
| `password_hash` | Hashed oper passwords + `MKPASSWD` |
| `globops` | `GLOBOPS` broadcast |
| `maphide` / `hidewhois` / `hideservices` (opers) | Hide topology / WHOIS lines / services |
| `tline` | Gauge a would-be ban's blast radius |
| `customtitle` | `TITLE` — claim a WHOIS title/vhost |
## Cloaking, DNS & identity
| Module | Provides |
| --- | --- |
| `cloak` | Keyed host masking (`+x`) |
| `ident` | Optional RFC 1413 ident lookups |
| `jwt` | HS256 JWS/JWT signer shared by captcha / challenge / extjwt |
## Observability & integration
| Module | Provides |
| --- | --- |
| `metrics` | Prometheus/OpenMetrics endpoint |
| `rpc` | JSON-RPC 2.0 control interface (see [Metrics & RPC](/docs/metrics-rpc)) |
| `syslog` / `log_json` / `jsonlog` | Mirror the log stream to syslog / a JSONL file / per-oper JSON tags |
| `chanlog` | Mirror oper snotices into a channel |
| `whoisport` | Show an oper the port a user connected to |
| `showfile` / `randquote` / `network_icon` / `profilelink` | Serve a file as a command, greet quotes, network icon, WHOIS profile link |
| `securelist` | Hold `/LIST` for fresh connections |

52
content/docs/nickserv.md Normal file
View file

@ -0,0 +1,52 @@
# NickServ
Nickname services — register your nickname/account, log in, and manage account settings. Message it
with `/msg NickServ <command>`.
| Command | Syntax | Description |
| --- | --- | --- |
| REGISTER | `REGISTER <password> [email]` | Register your current nick as an account |
| IDENTIFY | `IDENTIFY [account] <password>` | Log in (alias `ID`) |
| LOGIN | `LOGIN <nick> <password>` | Log in and move onto that nick, freeing any session holding it |
| VOUCH | `VOUCH <nick>` | Confirm a pending member on an invite-only network |
| LOGOUT | `LOGOUT` | Log out to a guest nick (alias `LOGOFF`) |
| INFO | `INFO [account]` | Show account info (email shown only to the owner) |
| ALIST | `ALIST` | List channels you hold access on |
| SET | `SET <option> [value]` | Change account settings (see below) |
| GROUP | `GROUP <account> <password>` | Link your current nick to an account as an alias |
| GLIST | `GLIST` | List the nicks grouped to your account |
| UNGROUP | `UNGROUP [nick]` | Remove a grouped nick |
| GHOST | `GHOST <nick> [password]` | Rename off a session using a nick you own |
| RECOVER | `RECOVER <nick> [password]` | Free a nick you own and put yourself back onto it |
| RESETPASS | `RESETPASS <account>` then `RESETPASS <account> <code> <newpassword>` | Reset your password by email code |
| CONFIRM | `CONFIRM <code>` | Confirm the email on a newly registered account |
| DROP | `DROP <password>` | Delete your account and release founded channels |
| CERT | `CERT ADD\|DEL [password] <fingerprint>` · `CERT LIST [password]` | Manage TLS cert fingerprints for SASL EXTERNAL |
| AJOIN | `AJOIN ADD\|DEL <#channel>` · `AJOIN LIST` | Channels auto-joined when you identify |
| UPDATE | `UPDATE` | Re-apply auto-joins and vhost, re-check for memos |
## SET options
`SET <option> [value]`:
| Option | Sets |
| --- | --- |
| `PASSWORD <new>` | Account password |
| `EMAIL <address>` | Contact email |
| `PUBKEY [key]` | A NIST P-256 public key for `ECDSA-NIST256P-CHALLENGE` SASL (no value clears it) |
| `GREET [message]` | Your greet (shown by a channel bot on join) |
| `AVATAR` / `BIO` / `PRONOUNS` / `TIMEZONE` / `URL [value]` | Public profile fields (published as IRCv3 metadata) |
| `AUTOOP {ON\|OFF}` | Auto-op where you have channel access |
| `KILL {ON\|OFF}` | Nick protection |
| `HIDE STATUS {ON\|OFF}` | Hide your last-seen / online status |
## Operator commands
| Command | Syntax | Description |
| --- | --- | --- |
| SASET | `SASET <account> PASSWORD\|EMAIL\|GREET <value>` | Change another account's settings |
| SAREGISTER | `SAREGISTER <account> <password> [email]` | Create an account directly, active immediately |
| LIST | `LIST <pattern>` | List accounts matching a glob (auspex) |
| GETEMAIL | `GETEMAIL <email>` | List accounts by email (auspex) |
| SUSPEND / UNSUSPEND | `SUSPEND <account> [reason]` · `UNSUSPEND <account>` | Block / unblock an account from logging in |
| NOEXPIRE | `NOEXPIRE <account> {ON\|OFF}` | Pin an account against inactivity expiry |

115
content/docs/operators.md
View file

@ -1,55 +1,90 @@
# Operators # Operators
Server operators are defined by `oper` blocks and typed by `opertype` blocks. An oper's power is Server operators are defined by `oper` blocks and typed by `opertype` blocks. An oper's power is the
the sum of three allow-lists: the **commands** they may run, the named **privileges** they hold, sum of three allow-lists: the **commands** they may run, the named **privileges** they hold, and the
and the user/channel **modes** they may set. user/channel **modes** they may set. `class` blocks bundle those into reusable roles that opertypes
compose.
## Oper types
An `opertype` groups a set of powers so many opers can share one role.
```ini
opertype {
name "netadmin";
commands "*"; # every oper command
privs "*"; # every named privilege
usermodes "*";
chanmodes "*";
}
opertype {
name "helper";
commands "KILL SANICK";
privs "users/auspex channels/auspex";
usermodes "-*"; # no privileged usermodes
chanmodes "b";
}
```
Lists are space-separated tokens. `*` grants everything; a `-` prefix denies a specific token —
for example `* -KILL` means "everything except `KILL`".
## Oper accounts ## Oper accounts
An `oper` block ties a login to an `opertype`. Hash the password with the `mkpasswd` helper. An `oper` block ties a login to an `opertype`. Hash the password with `echoircd mkpasswd`. A block
with neither a password nor a fingerprint is refused.
```ini ```ini
oper { oper {
name "alice"; name "alice";
password "$argon2id$..."; # from: echoircd mkpasswd password "$2b$11$..."; # from: echoircd mkpasswd
type "netadmin"; fingerprint "AA:BB:..."; # optional TLS client-cert (2FA, or alone)
host "*@192.0.2.0/24"; type "netadmin";
host "*@192.0.2.0/24";
} }
``` ```
Then, as a client: Then, as a client: `/oper alice hunter2`.
```text ## Classes and types
/oper alice hunter2
A `class` is a reusable capability bundle; an `opertype` composes classes into a named WHOIS role.
```ini
class {
name "ban";
commands "KILL KLINE GLINE ZLINE";
privs "users/auspex channels/auspex";
snomasks "cdkx";
}
opertype {
name "helper";
classes "auspex";
modes "+ih";
title "Help Operator";
}
``` ```
## Privileges Command and privilege lists are space-separated tokens: `*` grants everything, a `-` prefix removes
one (`* -KILL` = everything except `KILL`). `usermodes` / `chanmodes` on a class limit which oper-only
modes the type may set.
Named privileges gate individual abilities — for example `users/auspex` (see hidden user ### Built-in classes
details), `channels/auspex`, `servers/rehash`, or `users/mass-message`. Assign them per
`opertype` through `privs`, and the daemon enforces them everywhere the ability is used. `announce` · `ban` · `override` · `host` · `services` · `server` · `auspex` — covering broadcast,
X-lines, SA-overrides, host/identity changes, the SVS commands, server control, and the auspex/bypass
privileges respectively.
### Built-in types
Five ship ready to use (only `netadmin` holds every privilege):
| Type | Title | Level |
| --- | --- | --- |
| `helpop` | Help Operator | 10 |
| `globop` | GlobOp | 20 |
| `admin` | Administrator | 50 |
| `servadmin` | Services Administrator | 70 |
| `netadmin` | Network Administrator | 100 |
## Named privileges
Privileges gate individual abilities. Assign them per class/type via `privs`; the daemon enforces
them everywhere the ability is used.
| Privilege | Grants |
| --- | --- |
| `users/auspex` | See a user's real host+IP and geo, and `+i` users you share no channel with |
| `channels/auspex` | See secret/private (`+s`/`+p`) channels in LIST / WHO / WHOIS |
| `servers/auspex` | See U-lined/services servers otherwise hidden by `hideservices` |
| `users/flood` | Exempt from message- and join-flood limits |
| `users/ignore-commonchans` | Message a `+c` user without sharing a common channel |
| `channels/override` | Join through `+k`/`+b`/`+i`/`+l`/`+z`/`+R`/`+J`, CBAN, and the channel cap |
| `channels/restricted-create` | Create a channel while `restrictchans` is on |
| `channels/ignore-nonicks` | Change nick while on a `+N` channel |
| `users/ignore-callerid` | Message a `+g` user without being on their ACCEPT list |
| `users/ignore-privdeaf` | Reach a `+D` (deaf) user with channel messages |
| `users/secret-whois` | WHOIS a `+W` user without notifying them |
| `users/ignore-restrictmsg` | Private-message anyone while `restrictmsg` is on |
| `servers/use-disabled-commands` | Use a command turned off by `disabled_commands` |
| `servers/ignore-securelist` | Bypass the `securelist` LIST hold |
| `servers/ignore-blockamsg` | Send multi-channel messages that `blockamsg` blocks |
An untyped ("legacy") oper — an `oper` block with no `type` — holds every command and privilege.

55
content/docs/operserv.md Normal file
View file

@ -0,0 +1,55 @@
# OperServ
Operator service — network administration, bans / X-lines, the SVS commands, and services control.
Operator-only. Message it with `/msg OperServ <command>`.
## Bans & X-lines
| Command | Syntax | Description |
| --- | --- | --- |
| AKILL | `AKILL ADD [+expiry] <user@host> <reason>` · `DEL <mask\|number>` · `LIST [pattern]` | Network-ban a `user@host` |
| SQLINE | `SQLINE ADD [+expiry] <nick> <reason>` · `DEL` · `LIST` | Ban a nick pattern |
| SNLINE | `SNLINE ADD [+expiry] <realname> <reason>` · `DEL` · `LIST` | Ban a realname pattern |
| SHUN | `SHUN ADD [+expiry] <mask> <reason>` · `DEL` · `LIST` | Silence a host |
| CBAN | `CBAN ADD [+expiry] <#channel> <reason>` · `DEL` · `LIST` | Ban a channel name |
| SPAMFILTER | `SPAMFILTER ADD <action> [+expiry] <regex> <reason>` · `DEL` · `LIST` | Content spam filter |
| FORBID | `FORBID ADD\|DEL <NICK\|CHAN\|EMAIL> <mask> <reason>` · `LIST` | Ban a nick/chan/email from registration |
| IGNORE | `IGNORE ADD [+expiry] <mask> [reason]` · `DEL <mask>` · `LIST` | Silence a user from services |
## Enforcement & moderation
| Command | Syntax | Description |
| --- | --- | --- |
| KILL | `KILL <nick> [reason]` | Disconnect a user |
| KICK | `KICK <#channel> <nick> [reason]` | Kick from a channel |
| MODE | `MODE <#channel> <modes> [params]` | Set channel modes |
| CHANKILL | `CHANKILL <#channel> [reason]` | Clear a channel |
| REDACT | `REDACT <#channel\|nick> <msgid> [reason]` | Delete a message by its id |
| GLOBAL | `GLOBAL <message>` | Announce to everyone |
| PROTECT | `PROTECT ALL \| <account> [ON\|OFF]` | Nick protection for accounts |
| SETALL | `SETALL <setting> <ON\|OFF>` | Apply a channel setting to every channel |
## SVS & staff
| Command | Syntax | Description |
| --- | --- | --- |
| SVSNICK | `SVSNICK <nick> <newnick>` | Force a nick change |
| SVSJOIN | `SVSJOIN <nick> <#channel> [key]` | Force a channel join |
| SVSPART | `SVSPART <nick> <#channel> [reason]` | Force a channel part |
| SWHOIS | `SWHOIS <account> [text]` | Extra WHOIS line on an account |
| OPER | `OPER ADD <account> <priv[,priv]> [+duration]` · `DEL <account>` · `LIST` | Manage runtime operators |
| INFO | `INFO <target>` · `ADD <target> <note>` · `DEL <target>` | Staff notes on a target |
| NOTIFY | `NOTIFY ADD +<expiry> <flags\|*> <mask> <reason>` · `DEL` · `LIST` · `VIEW` · `CLEAR` | Watch masks and log their events |
## Sessions, jupes & control
| Command | Syntax | Description |
| --- | --- | --- |
| SESSION | `SESSION LIST <min>` · `VIEW <ip>` | Inspect per-IP sessions |
| EXCEPTION | `EXCEPTION ADD <ip-mask> <limit> [reason]` · `DEL` · `LIST` | Session-limit exceptions |
| JUPE | `JUPE <server.name> [reason]` · `DEL <server.name>` · `LIST` | Jupe a server name |
| STATS | `STATS` | Enforcement overview |
| LOGSEARCH | `LOGSEARCH [pattern]` | Search the action log |
| DEFCON | `DEFCON [1-5]` | Network defence level |
| SET | `SET READONLY {ON\|OFF}` | Services-wide settings |
| SHUTDOWN / RESTART / REHASH | `SHUTDOWN [reason]` · `RESTART [reason]` · `REHASH` | Stop / restart / reload services |

100
content/docs/other-services.md Normal file
View file

@ -0,0 +1,100 @@
# Other services
The remaining services in the standard suite. Message each with `/msg <Service> <command>`.
## GroupServ
Named account groups (`!group`) usable in channel access lists.
| Command | Syntax | Description |
| --- | --- | --- |
| REGISTER / DROP | `REGISTER <!group>` · `DROP <!group>` | Create / delete a group you founded |
| INFO / LIST | `INFO <!group>` · `LIST` | Show a group / list your groups |
| ADD / DEL | `ADD\|DEL <!group> <account>` | Add / remove a member |
| FLAGS | `FLAGS <!group> [account [+/-flags]]` | View or change group flags |
## StatServ
Network and per-channel activity statistics.
| Command | Syntax | Description |
| --- | --- | --- |
| SERVER | `SERVER` | Network-wide counters (operator) |
| CHANNEL | `CHANNEL <#channel>` | A channel's activity statistics (founder) |
## InfoServ
Public and operator bulletins / news.
| Command | Syntax | Description |
| --- | --- | --- |
| POST / LIST / DEL | `POST <message>` · `LIST` · `DEL <number>` | Manage public bulletins |
| OPOST / OLIST / ODEL | `OPOST <message>` · `OLIST` · `ODEL <number>` | Manage oper-only bulletins |
## ReportServ
User abuse reports queued for staff.
| Command | Syntax | Description |
| --- | --- | --- |
| REPORT | `REPORT <nick\|#channel> <reason>` | File an abuse report |
| LIST / VIEW | `LIST [ALL]` · `VIEW <id>` | List / read reports |
| CLOSE / DEL | `CLOSE <id>` · `DEL <id>` | Resolve / delete a report |
## HelpServ
User help-desk ticket queue for staff.
| Command | Syntax | Description |
| --- | --- | --- |
| REQUEST / CANCEL | `REQUEST <message>` · `CANCEL` | Open / withdraw a ticket |
| LIST / VIEW | `LIST [ALL]` · `VIEW <id>` | List / read tickets |
| TAKE / NEXT / CLOSE | `TAKE <id>` · `NEXT` · `CLOSE <id>` | Claim / resolve tickets |
| EXTBANS | `EXTBANS` | Extended-ban reference |
## DiceServ
Dice-expression rolling and calculation.
| Command | Syntax | Description |
| --- | --- | --- |
| ROLL / CALC | `ROLL <expr>` · `CALC <expr>` | Roll dice (whole) / evaluate (decimals) |
| EXROLL / EXCALC | `EXROLL <expr>` · `EXCALC <expr>` | As above, showing each die |
## DictServ
DICT-protocol dictionary/thesaurus lookups. **Opt-in** — starts only when `[dictserv]` is configured.
| Command | Syntax | Description |
| --- | --- | --- |
| DICT / DEFINE | `DICT <word>` · `DEFINE <word>` | Define a word (WordNet / GCIDE) |
| THES | `THES <word>` | Thesaurus synonyms |
| LOOKUP | `LOOKUP` | List every lookup command (ELEMENT, ACRONYM, BIBLE, LAW, …) |
## GameServ
Turn-based games (tic-tac-toe, Connect Four, chess) with ranked stats.
| Command | Syntax | Description |
| --- | --- | --- |
| CHALLENGE | `CHALLENGE <nick> <ttt\|c4\|chess>` | Challenge someone |
| ACCEPT / DECLINE | `ACCEPT [id]` · `DECLINE [id]` | Answer a challenge |
| MOVE / RESIGN | `MOVE <id> <move>` · `RESIGN <id>` | Play / resign |
| GAMES / STATS / TOP | `GAMES` · `STATS [nick]` · `TOP [game]` | Your games / stats / leaderboard |
## ChanFix
Restores ops to a channel's trusted regulars based on tracked op-time.
| Command | Syntax | Description |
| --- | --- | --- |
| SCORES | `SCORES <#channel>` | Show op-time standings |
| CHANFIX | `CHANFIX <#channel>` | Reop the trusted regulars |
## DebugServ
Internal diagnostic feed of services activity.
| Command | Syntax | Description |
| --- | --- | --- |
| STATUS | `STATUS` | Show what DebugServ is reporting |

57
content/docs/security.md Normal file
View file

@ -0,0 +1,57 @@
# Security & anti-abuse
echoIRCd's anti-abuse is a **layered defence** rather than a single engine, applied at the cheapest
possible point in each case. (The behavioural DEFCON-style detection engine with a report-only mode
lives in [echo services](/docs/services-security), not in the daemon.)
## The layers
- **Upstream / provider** — volumetric floods (SYN/UDP/amplification) are handled before they reach
the host.
- **Kernel / firewall** — SYN cookies, per-IP connection-rate limits, conntrack caps.
- **echoIRCd** — abusive *sessions* and *content*, described below.
## Accept edge
Rejection before any per-connection state is allocated:
- **`accept_rate` / `accept_burst`** — a per-source-IP token bucket, shared across the plaintext and
TLS acceptors so one IP can't get a fresh budget per listener. Trusted proxies and server links are
exempt.
- **`connflood`** — refuse connections from an IP opening too many too fast.
- **`connectban`** — Z-line an IP range that opens too many connections, with a boot grace period,
garbage collection, and exemptions.
## Per connection
- **Clone caps** — connection classes cap concurrent per-IP connections (`localmax`, `globalmax`).
- **`registration_timeout`** — drop connections that never send NICK+USER.
- **`tls_handshake_timeout`** — reap sockets that open the TLS port but never negotiate.
- **`conn_waitpong`** — hold registration until the client echoes an exact PING cookie.
- **`recvq` / `softsendq` / `hardsendq`** — bound per-connection memory.
## Per message
- **Fakelag** — `flood_messages` per `flood_seconds` throttles a fast client (opers exempt); a class
may set `fakelag=no` to disconnect instead.
- Channel modes **`+f`** (message flood), **`+j`** (join flood), **`+F`** (nick-change flood).
## Screening & scoring
- **DNSBL** — check DNS blocklists on connect; action `mark` / `kill` / `kline` / `gline` / `zline`.
- **Reputation** — accrue a per-address score over time; surfaces the `y:` extban and WHOIS.
- **Security groups** — named AND-ed user sets usable as the `g:` extban.
## Content & behaviour
`antirandom` (drone nick/ident/realname scoring), `antimixedutf8` (look-alike mixed-script spam),
`filter` / `badword` (`+G` censor), `solvemsg` (arithmetic PM gate), `recaptcha` /
`cloudflare_challenge` (registration gates), `autodrop` (HTTP-scanner connections), and `blockamsg`
(mass `/amsg`). See [Modules](/docs/modules) and the [Configuration reference](/docs/config-reference)
for the keys.
## Network bans
Persistent `K` / `G` / `Z` / `E` (exempt) / `Q` (nick) / `CBAN` (channel) / `SHUN` / `RLINE`
(realname) bans; `TLINE <mask>` reports how many current users a would-be ban would match before you
set it.

79
content/docs/services-config.md Normal file
View file

@ -0,0 +1,79 @@
# Running & config
echo services reads a single `config.toml`. Only `[uplink]` and `[server]` are required; every other
section is optional and off when omitted. A few keys reload on OperServ `REHASH` (noted); the rest
need a service restart.
```sh
echo config.toml
```
## [uplink] — the ircd to link to (required)
| Key | Description |
| --- | --- |
| `host` / `port` | Uplink ircd address and S2S port |
| `password` | S2S link password |
| `tls` | Use TLS for the link; `true` pins the SPKI below |
| `spki_fingerprint` | Base64 SHA-256 of the uplink's SubjectPublicKeyInfo (when `tls=true`) |
## [server] — this node's identity (required)
| Key | Description |
| --- | --- |
| `name` / `sid` | Services server name and 3-char SID (unique) |
| `description` | Server description |
| `protocol` | InspIRCd link protocol (1206 = insp4, 1205 = insp3) |
| `scram_iterations` | PBKDF2 cost for new SCRAM verifiers (≥ 1000) |
| `guest_nick` | Nick prefix after `LOGOUT` |
| `service_host` | Host the pseudo-clients wear (empty = server name) |
| `service_modes` | User modes the service clients set (e.g. `iHkoB`) |
| `service_oper_type` | WHOIS "is a …" string |
| `services_channel` | Channel every pseudo-client joins |
| `standard_replies` | Use IRCv3 FAIL/WARN/NOTE instead of notices |
## [modules] — which services to start
`services` is a list of module names to bring up; omit the section for the full standard suite:
`nickserv`, `chanserv`, `botserv`, `hostserv`, `memoserv`, `operserv`, `statserv`, `groupserv`,
`infoserv`, `reportserv`, `helpserv`, `chanfix`, `diceserv`, `gameserv`, `debugserv`.
## [[oper]] — services operators (repeatable)
| Key | Description |
| --- | --- |
| `account` | Account granted operator access |
| `type` | Tier shortcut: `operator` < `administrator` < `root` |
| `privs` | Fine-grained privilege list (`auspex`, `oper`, `suspend`, `admin`, `root`) |
## Policy & lifecycle
| Section | Keys |
| --- | --- |
| `[register]` | `confusable_check`, `vouch` (REHASH-reloadable) |
| `[extban]` | `enabled` — which InspIRCd matching-extbans AKICK may use |
| `[auth]` | `external` — hand identity to an outside authority |
| `[expire]` | `accounts_days`, `channels_days`, `warn_days` (0 = never) |
| `[session]` | `default_limit` — per-IP connection limit |
| `[language]` | `default`, `dir`, `available` (ships en, fr, de, es, es-ar, pt, pt-br) |
| `[log]` | `channel`, `notify_exclude` |
## Email & web integration
| Section | Keys |
| --- | --- |
| `[email]` | `from`, `command` (mailer piped on stdin), `brand`, `accent`, `logo`, `confirm_url` |
| `[health]` | `bind` — `/health` + Prometheus `/metrics` (loopback, unauthenticated) |
| `[panel]` | `bind`, `brand` — self-contained web admin site (put behind a TLS proxy) |
| `[grpc]` | `bind`, `token`, `[grpc.tls]` — account/channel directory + Accounts API for a website |
| `[jsonrpc]` | `bind`, `token`, `origins`, `[jsonrpc.tls]` — HTTP JSON-RPC for the staff panel / stats |
| `[keycard]` | `url`, `api_key` — passwordless web login tokens |
| `[dictserv]` | `server` — DICT server for DictServ (opt-in) |
## Federation
`[gossip]` + `[[peer]]` provide node-to-node replication: `gossip.bind`, `gossip.secret`,
`[gossip.tls]` (mTLS), `[gossip.signing]` (Ed25519 per-origin signing + trusted-signer map), and one
`[[peer]]` per federated node.
See [Security & anti-abuse](/docs/services-security) for the `[security.*]` engine.

56
content/docs/services-security.md Normal file
View file

@ -0,0 +1,56 @@
# Security & anti-abuse (services)
echo services runs a native anti-abuse engine in its core. It observes network activity, scores it
against configurable detectors, and can act (kill / ban) — or, by default, only report. It is
separate from the daemon's [layered anti-abuse](/docs/security).
> **Arm it carefully.** `report_only` defaults to **true** (detect and alert only). Before setting it
> false, make sure `exempt_ips` covers loopback and your trusted hosts — otherwise an over-eager
> detector could ban your own services or bots.
## [security] — engine core
| Key | Description |
| --- | --- |
| `enabled` | Master switch |
| `report_only` | Detect & alert only, never kill/ban (default **true**) |
| `exempt_ips` | IP masks exempt from enforcement (defaults to loopback) |
| `exempt_opers` / `exempt_accounts` / `exempt_voice` | Exempt operators (default on) / logged-in accounts (off) / voiced users (on) |
| `announce_permit` / `announce_life` | Rate limit on abuse announcements |
| `cascade_permit` / `cascade_life` | Correlated-event (cascade) detection thresholds |
| `netsplit_grace` | Grace period after a netsplit before enforcing |
The OperServ [`DEFCON`](/docs/operserv) command raises the network defence level on top of this.
## [security.connect] — connection floods
`enabled`, `flood_permit` / `flood_life` (connects per source in a window), `range_permit` /
`range_life` (per IP range), `ban_duration`.
## [security.behavior] — behavioural abuse
Nick flooding, join/part cycling, mass-join, quit floods, and channel crawling:
`nick_permit`/`nick_life`, `cycle_permit`/`cycle_life`, `joinpart_permit`/`joinpart_life`/`joinpart_grace`,
`massjoin_permit`/`massjoin_life`, `quit_permit`/`quit_life`/`quit_reasons`, `crawl_permit`/`crawl_life`,
`ban_duration`.
## [security.content] — message content
Highlight spam, bad Unicode, and repeats:
`highlight_nicks`/`highlight_min_len`/`highlight_permit`/`highlight_life`,
`badunicode_score`/`badunicode_min`/`badunicode_permit`/`badunicode_life`,
`repeat_min`/`repeat_permit`/`repeat_life`, `ban_duration`.
## [security.auth] — auth abuse
Login and registration flooding, ban evasion: `fail_permit`/`fail_life`,
`register_permit`/`register_life`, `evade_ttl`, `ban_duration`.
## [[security.pattern]] — custom connect masks (repeatable)
`mask`, `field` (which connection field to match), `regex` (treat the mask as a regex), `reason`,
`ban` (duration).
## [security.mxbl] — email MX/IP blocklist
Screens registration email domains: `enabled`, `resolver`, `mx_globs`, `ip_cidrs`, `timeout_ms`.

55
content/docs/services.md
View file

@ -1,30 +1,49 @@
# Services # echo services
echo services is a suite of pseudo-clients that runs as its own program and links to the network **echo services** is a Rust services package that links to the echoIRCd daemon over the S2S protocol
as a services server. State is **event-sourced** — every change is an appended event, replayed to as a linked services server — it is *not* built into the daemon. State is **event-sourced**: every
rebuild the database. change is an appended event, replayed to rebuild the database.
## The services
| Service | Purpose |
| --- | --- |
| **NickServ** | account registration, grouped nicks, certificates, public keys, vhosts, profiles |
| **ChanServ** | channel founders and access, auto-op, akick, topic and mode locks |
| **OperServ** | network administration, akills, session control |
| **MemoServ** | offline messages between accounts |
## Running ## Running
echo services is configured from its own file and connects to the ircd over the server port: echo services is its own binary with its own configuration:
```sh ```sh
echo config.toml echo config.toml
``` ```
On the ircd side, the services server must be U-lined and named as the SASL server — see Only `[uplink]` and `[server]` are required; everything else is optional. The daemon must U-line the
[Server links](/docs/linking#services). services server and name it as the SASL server — see [Server links](/docs/linking#services). For the
full configuration, see [Running & config](/docs/services-config).
## The services
The standard suite comes up by default; the enabled set is controlled by `[modules] services`.
| Service | Role |
| --- | --- |
| **[NickServ](/docs/nickserv)** | Register and manage your nick/account; log in |
| **[ChanServ](/docs/chanserv)** | Register and manage channels, access, modes, topics |
| **[OperServ](/docs/operserv)** | Network administration, bans/X-lines, SVS commands (operator) |
| **[MemoServ](/docs/memoserv)** | Leave and read offline messages between accounts |
| **[HostServ](/docs/hostserv)** | Virtual host (vhost) requests, offers, and assignment |
| **[BotServ](/docs/botserv)** | Channel bots that speak, moderate, and auto-respond |
| GroupServ | Named account groups (`!group`) for access lists |
| StatServ | Network and per-channel activity statistics |
| InfoServ | Public and operator bulletins / news |
| ReportServ | User abuse reports queued for staff |
| HelpServ | User help-desk ticket queue |
| DiceServ | Dice-expression rolling and calculation |
| DictServ | DICT-protocol dictionary/thesaurus lookups (opt-in) |
| GameServ | Turn-based games (tic-tac-toe, Connect Four, chess) with ranked stats |
| ChanFix | Restore ops to a channel's trusted regulars |
| DebugServ | Internal diagnostic feed of services activity |
The last ten are covered on the [other services](/docs/other-services) page. echo services also runs a
native [anti-abuse engine](/docs/services-security).
## Accounts & SASL ## Accounts & SASL
Registration and login are covered in [Accounts & SASL](/docs/accounts). SASL is relayed from the Registration and login (including key-based ECDSA login) are covered in
daemon to services mechanism-agnostically, so new mechanisms work without daemon changes. [Accounts & SASL](/docs/accounts); SASL is relayed from the daemon to services
mechanism-agnostically, so new mechanisms work without daemon changes.

28
content/docs/snomasks.md Normal file
View file

@ -0,0 +1,28 @@
# Snomasks
Server-notice masks control which categories of server notice an operator receives. Set user mode
`+s` to subscribe, then narrow with e.g. `MODE <yournick> +s -c` to drop a category. Operators receive
all categories by default.
| Letter | Category | Notifies about |
| --- | --- | --- |
| `a` | announce | General announcements / global operator notices |
| `c` | connect | Client connections and disconnects |
| `d` | dnsbl | DNSBL hits |
| `f` | filter | Spam-filter matches |
| `g` | globops | `GLOBOPS` messages |
| `j` | chancreate | Channel creation |
| `k` | kill | KILLs |
| `l` | link | Server links / S2S events |
| `n` | nick | Nick changes |
| `o` | oper | Oper-up (OPER success/failure) |
| `q` | quit | Client quits |
| `r` | rehash | Config rehashes |
| `t` | stats | STATS access |
| `u` | acctreg | Account registrations |
| `v` | override | Operator overrides (using privileges to bypass restrictions) |
| `w` | gateway | WebIRC / gateway (spoofed-host) connections |
| `x` | xline | X-line (G/K/Z/…) ban activity |
The oper snotice stream can also be mirrored into a channel with the `chanlog` config option and to
the system logger with `syslog` — see the [Configuration reference](/docs/config-reference#logging).

28
content/docs/user-modes.md Normal file
View file

@ -0,0 +1,28 @@
# User modes
Modes set on a user with `MODE <yournick> +<mode>`. Some are settable by anyone; others may only be
*set* by an operator (anyone may clear them), and a few are managed only by the server or services.
| Mode | Name | Description | Notes |
| --- | --- | --- | --- |
| `i` | invisible | Hide from WHO/NAMES for users who share no channel with you | self |
| `w` | wallops | Receive WALLOPS / global operator notices | self |
| `o` | oper | IRC operator — granted only by `OPER`; you may `-o` yourself but never self-`+o` | via OPER |
| `x` | cloak | Show your computed host cloak; `-x` (revealing the real host) is oper-only | `-x` oper-only |
| `B` | bot | Marks you as a bot (WHOIS 335); advertised as `BOT=B` | self |
| `D` | deaf | Do not receive channel messages | self |
| `I` | hidechans | Hide your channel list in WHOIS | self |
| `H` | hideoper | Hide operator status in WHOIS | oper-set |
| `r` | registered | Logged into a services account — set/cleared only by services | services |
| `R` | regdeaf | Only accept private messages from logged-in users | self |
| `z` | secure PM | Only accept private messages from TLS users | self |
| `s` | snomask | Receive server notices; `+s <mask>` refines the categories (see [Snomasks](/docs/snomasks)) | oper-set |
| `g` | callerid | Only accept PMs from users on your `ACCEPT` list; advertised as `CALLERID=g` | self |
| `W` | showwhois | Get a notice whenever someone WHOISes you | oper-set |
| `h` | helpop | Marked available for help (shown in WHOIS) | oper-set |
| `c` | commonchans | Only accept PMs from users sharing a common channel | self |
| `k` | servprotect | Protected from KILL/KICK/SA-commands; set only by a server/services | server |
Modes `H`, `W`, `h`, and `s` may only be *set* by an operator (a non-oper attempt gets
`ERR_NOPRIVILEGES`); anyone may clear them. Which oper-only user modes a given operator may set is
further gated by their oper type's `usermodes` allow-list — see [Operators](/docs/operators).

31
src/docs.rs
View file

@ -27,17 +27,38 @@ pub static NAV: &[NavSection] = &[
p!("installation", "Installation"), p!("installation", "Installation"),
p!("connecting", "Connecting"), p!("connecting", "Connecting"),
]}, ]},
NavSection { title: "Administration", pages: &[ NavSection { title: "Configuration", pages: &[
p!("configuration", "Configuration"), p!("configuration", "Configuration"),
p!("config-reference", "Configuration reference"),
p!("operators", "Operators"), p!("operators", "Operators"),
p!("linking", "Server links"), p!("linking", "Server links"),
]}, ]},
NavSection { title: "Accounts", pages: &[
p!("accounts", "Accounts & SASL"),
p!("services", "Services"),
]},
NavSection { title: "Reference", pages: &[ NavSection { title: "Reference", pages: &[
p!("user-modes", "User modes"),
p!("channel-modes", "Channel modes"),
p!("extbans", "Extended bans"),
p!("snomasks", "Snomasks"),
p!("commands", "Command reference"),
p!("cli", "CLI tools"),
p!("ircv3", "IRCv3 capabilities"), p!("ircv3", "IRCv3 capabilities"),
p!("modules", "Modules"),
p!("metrics-rpc", "Metrics & RPC"),
p!("security", "Security & anti-abuse"),
]},
NavSection { title: "Accounts & SASL", pages: &[
p!("accounts", "Accounts & SASL"),
]},
NavSection { title: "echo services", pages: &[
p!("services", "Overview"),
p!("services-config", "Running & config"),
p!("nickserv", "NickServ"),
p!("chanserv", "ChanServ"),
p!("operserv", "OperServ"),
p!("memoserv", "MemoServ"),
p!("hostserv", "HostServ"),
p!("botserv", "BotServ"),
p!("other-services", "Other services"),
p!("services-security", "Security (services)"),
]}, ]},
]; ];