fedserv/echoIRCd
1
1
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: document the block config format + mkpasswd/checkconfig/rehash CLIs in README and configuration.md

Browse source
This commit is contained in:
Jean Chevronnet 2026-08-24 19:13:45 +00:00
parent 8d48900ae3
commit f066fa0b5a
No known key found for this signature in database
GPG key ID: 439666D63A9477E4
2 changed files with 58 additions and 13 deletions
Download patch file Download diff file Expand all files Collapse all files

34
README.md
View file

@ -57,8 +57,10 @@ operational limit exposed as a config key.
```sh
git clone https://git.devtronic.pro/fedserv/echoIRCd
cd echoIRCd
cp echoircd.conf.example echoircd.conf # edit: oper pass, cloak_key, TLS paths
cargo run --release # reads ./echoircd.conf
cargo build --release
cp echoircd.conf.example echoircd.conf # edit: servername, cloak_key, TLS paths
printf '%s' 'my-oper-pass' | ./target/release/echoircd mkpasswd # → bcrypt hash for the oper block
./target/release/echoircd # start (reads ./echoircd.conf)
```
Then point a client at it: `/server 127.0.0.1 6667` (or `6697` for TLS once a
@ -75,13 +77,27 @@ The full manual lives in [`docs/`](docs/):
## Configuration
Configuration is a plain `key = value` file; see
[`echoircd.conf.example`](echoircd.conf.example) for the full, annotated set of
keys. Every operational limit is a config key with a built-in default, and most
settings apply on `REHASH` without a restart. Your live `echoircd.conf` is
gitignored — it holds secrets (oper password, cloak key, link password), so never
commit it. Generate a TLS certificate into `tls/` with the one-liner in the example
config.
Configuration is a single file (default `./echoircd.conf`) in a **brace/block
format** — or the original flat `key = value` form; both are accepted and the
parser auto-detects which one a file uses:
```text
server { name "irc.example.net"; network "ExampleNet"; }
listen { ip "*"; port 6697; tls yes; }
oper { name "admin"; password "$2b$…"; type netadmin; }
```
See [`echoircd.conf.example`](echoircd.conf.example) for the full, annotated set of
keys — every operational limit is a config key with a built-in default, and most
settings apply on `REHASH` without a restart. Three helper subcommands round it out:
- `echoircd mkpasswd` — read a password from stdin, print a bcrypt hash for an `oper` block.
- `echoircd checkconfig [file]` — parse a config and dump its keys, to validate one or diff two.
- `echoircd rehash` — signal the running server to reload its config in place.
Your live `echoircd.conf` is gitignored — it holds secrets (oper password, cloak
key, link password), so never commit it. Generate a TLS certificate into `tls/`
with the one-liner in the example config.
## Architecture

37
docs/configuration.md
View file

@ -1,8 +1,10 @@
# Configuration
The config is a plain `key = value` text file (default `./echoircd.conf`). Some
keys repeat to build a list (`motd`, `oper`, `link`, `connectclass`, `dnsbl`,
`securitygroup`, …). Comments start with `#`.
echoircd reads a single config file (default `./echoircd.conf`), written in a
brace/block format (below); the original flat `key = value` form also works and is
auto-detected. Some keys repeat to build a list (`motd`, `oper`, `link`,
`connectclass`, `dnsbl`, `securitygroup`, …). Comments start with `#` (also `//`
and `/* */`).
The shipped [`echoircd.conf.example`](../echoircd.conf.example) is the fully
annotated master reference — every key with its default. This page organizes those
@ -12,6 +14,33 @@ Most settings apply on `REHASH` without a restart.
> `echoircd.conf` is gitignored because it holds secrets (oper password, cloak
> key, link password). Never commit your live config.
## File format
Structural entities and grouped settings go in `{ }` blocks; values end with `;`,
booleans are `yes`/`no`:
```text
server { name "irc.example.net"; network "ExampleNet"; sid "0AA"; }
listen { ip "*"; port 6667; }
listen { ip "*"; port 6697; tls yes; }
oper { name "admin"; password "$2b$…"; type netadmin; }
link { name "hub.example.net"; ip 10.0.0.1; port 7000; password "…"; services yes; }
```
Structural blocks — `server`, `listen`, `tls`, `oper`, `opertype`, `class`,
`link`, `cloak`, `webirc`, `motd`, `opermotd` — take the short field names shown
throughout this page. Any other block name (`set`, `limits`, `modules`, …) is just
a group whose fields are the flat keys documented below, so the scalar settings can
be organized however you like. The flat and block forms are equivalent.
Three subcommands help manage a config:
| Command | Purpose |
|---------|---------|
| `echoircd mkpasswd [cost]` | Read a password from stdin, print a bcrypt hash for an `oper` block. |
| `echoircd checkconfig [file]` | Parse a config and print a sorted key/value dump — validate one, or diff two. |
| `echoircd rehash [file]` | Signal the running server (found via its `pidfile`) to reload config in place. |
## Server identity
| Key | Meaning |
@ -93,7 +122,7 @@ connectclass_required = yes # refuse clients matching no allow class (default
| Key | Meaning |
|-----|---------|
| `oper = <name> <password> [level]` | An oper account; the password may be hashed (see `MKPASSWD`). Optional numeric [oper level](operators.md). |
| `oper { name; password; type; fingerprint; level }` | An oper account. `password` takes plaintext, `sha256:<hex>`, `pbkdf2:…` or a bcrypt `$2b$` hash (make one with `echoircd mkpasswd`, or `MKPASSWD` in-band); `fingerprint` requires a matching TLS client-cert SHA-256 (with, or instead of, a password); `type` names an [opertype](operators.md); `level` is a numeric [oper level](operators.md). |
| `opermotd` | A line shown to opers via `/OPERMOTD` (repeatable). |
| `operprefix` | Give every oper a `!` prefix in their channels. |
| `ojoin` / `ojoin_op` | Enable `/OJOIN` (join as staff, with op unless `ojoin_op = no`). |