Server configuration reference

Generated from the server’s configuration code (src/config.rs). Keys in [server] may also be written at the top level of the file, and sub-tables work either way ([server.acme] or [acme]).

[server]

Key	Type	Default	Meaning and rules
bind_addr	socket address	"0.0.0.0:8443"	Listen address. Use "0.0.0.0:443" (or "[::]:443") for direct deployment with ACME. Overridden by --bind.
websocket_path	string	"/"	The only request path on which WebSocket upgrades reach the relay; everything else gets the decoy. Must start with / and be ASCII with no ?, #, spaces or control characters. The default gives no protection against probing; set a long random path. A path containing CHANGE-ME (the template’s placeholder) is refused.
public_port	integer	unset	The port clients dial, for --print-invite only, when it differs from bind_addr (NAT, a pf rdr rule, a jail). 443 is left out of the invite. Unset: 443 with proxy_protocol, else the port of bind_addr. 1–65535; --public-port overrides it.
relay_identity_path	path	relay_identity.key next to the config file	The relay’s long-term identity key: 32 bytes, mode 0600 or narrower, owned by the service user. Create it with --init-relay-identity. A relay run from a config file refuses to start without it. See Relay identity.
dev_origin	string	none	Development only. Required with --no-tls, ignored with TLS. The lowercase scheme://host:port clients dial, e.g. "ws://127.0.0.1:18443".
max_connections	integer	10000	Simultaneous connections, counted from accept(). At least 1.
max_connections_per_ip	integer	64	Simultaneous connections per IPv4 address or IPv6 /64. 0 disables it, which is required behind a TCP front end. Must not exceed max_connections.
max_connections_per_ipv6_48	integer	256	Total simultaneous connections from one IPv6 /48. 0 disables it. Must not exceed max_connections. IPv4 is unaffected.
proxy_protocol	bool	false	Behind a TCP (layer-4) front end on the same host: every connection must start with a PROXY protocol v2 header, whose source address is used for the per-source fair shares only. Requires a loopback bind_addr and both per-address caps at 0. Non-loopback peers and connections without a valid v2 header are refused. See Behind a TCP front end.
rate_limit_bps	integer	1048576	Inbound bytes per second per connection (token bucket; throttles rather than disconnects). At least 1024.
max_message_bytes	integer	4194304	Largest WebSocket message or frame from a client. 65536 to 67108864.
connection_timeout_secs	integer	300	Close a connection that has sent nothing for this long. 60 to 86400.
identification_timeout_secs	integer	15	A new connection must complete a signed key publish within this time, or it is closed. 1 to 300, and not more than connection_timeout_secs.
max_pending_circuit_targets	integer	10000	Most distinct targets with pending conversation requests, relay-wide. When full, a lighter source evicts the heaviest source’s oldest request. Blinded requests fill most of it on a busy relay; see sizing. 1 to 1000000.
max_pending_per_connection	integer	32	Most distinct targets one connection may have pending within 10 minutes, named requests only. Re-sending to the same target is free. 1 to max_pending_circuit_targets.
max_pending_blind_per_connection	integer	1024	Most blinded requests (pair tokens) one connection may have pending within 10 minutes, counted apart from named requests. 1 to max_pending_circuit_targets; when unset, 1024 or max_pending_circuit_targets if lower.
max_pending_per_source	integer	1024	Most pending named requests from one source (an IPv4 address or IPv6 /48). 1 to max_pending_circuit_targets. Off behind a front end unless proxy_protocol = true.
max_pending_blind_per_source	integer	4096	Most pending blinded requests from one source, counted apart from named requests. 1 to max_pending_circuit_targets; when unset, 4096 or max_pending_circuit_targets if lower. Off like max_pending_per_source.
max_circuits_per_connection	integer	256	Most circuits one connection may have created and still have open, and most circuits one identity may be a member of across reconnects. 1 to 65536.
max_circuits	integer	200000	Most circuit routing entries in the whole server (two per pair). When full, a lighter source’s new pair tears down the heaviest source’s newest pair. 2 to 10000000.
max_circuits_per_source	integer	max_circuits / 64	Most circuit sides held by identities that asked from one source. 2 to max_circuits. Off behind a front end unless proxy_protocol = true.
offline_queue_max_total_bytes	integer	268435456	Total bytes of queued messages. At least offline_queue_max_bytes_per_recipient.
offline_queue_max_bytes_per_recipient	integer	16777216	Queued bytes per recipient. At least max_message_bytes.
outbound_budget_bytes	integer	1073741824	Bytes queued for sending across all connections. When spent, the heaviest connection of the heaviest source is closed. 16 MiB to 64 GiB. On a 2 GB host use about 256 MiB.
buffer_budget_bytes	integer	536870912	WebSocket buffer bytes across all connections, shed the same way. max_message_bytes to 64 GiB. On a 2 GB host use about 128 MiB.
tls_handshake_timeout_secs	integer	10	Time a client gets to finish the TLS handshake. 1 to 120.
circuit_ttl_secs	integer	none	Accepted but ignored, with a startup warning. Circuits end when either endpoint disconnects or closes them.
redis_url	string	none	Accepted, but not used by the current server.

Removed keys. message_queue_persist_path and trusted_proxy are refused at startup with a message that explains the replacement ([server.offline_queue] and proxy_protocol).

[server.offline_queue]

Messages and message requests for recipients who are not connected. See Offline queue.

Key	Type	Default	Meaning and rules
ttl_secs	integer	259200 (72 h)	Lifetime of a queued message. 3600 to 259200: 72 hours is also the maximum, and a larger value is a startup error. Message requests live at most 72 hours.
knock_budget_bytes	integer	16777216	Bytes of queued message requests (5120 bytes each, so 16 MiB holds about 3,276), separate from messages. One source may hold at most 1/16.
persist	bool	false	Keep queued items across restarts, encrypted. With false, nothing is written to disk.
persist_path	path	none	Encrypted queue file. Required when persist = true.
persist_key_path	path	none	32-byte key file. Must be on a memory filesystem (tmpfs, ramfs or mfs), on a different filesystem and directory from persist_path, owned by the service user, mode 0600 or narrower. Required when persist = true.
allow_persistent_key	bool	false	Skip the memory-filesystem check (development or exception only; logs a warning).

[server.acme]

Built-in Let’s Encrypt with TLS-ALPN-01 on port 443. Unknown keys are refused. Mutually exclusive with [server.tls].

Key	Type	Default	Meaning and rules
enabled	bool	false	Turn ACME on.
domains	list of strings	[]	Required when enabled. Lowercase fully qualified names; no wildcards, IP addresses, scheme, port or path; at most 253 characters.
contacts	list of strings	[]	Optional email addresses; mailto: is added if missing; other schemes are refused.
cache_dir	path	"/var/lib/rchat/acme"	Account key and certificate store. Must be absolute and not a symlink. Created 0700; files written 0600.
staging	bool	false	Use the Let’s Encrypt staging directory (untrusted certificates).

[server.tls]

Static certificate, and the TLS resumption setting. Unknown keys are refused; min_version and tls13_only are refused with an explanation. A static certificate is mutually exclusive with [server.acme]; a [server.tls] table holding only session_tickets may sit beside [server.acme].

Key	Type	Default	Meaning
cert_path	path	none	PEM certificate chain, leaf first. Set together with key_path for a static certificate, or leave both out with [server.acme].
key_path	path	none	PEM private key (PKCS#8, PKCS#1 or SEC1). Must match the certificate.
session_tickets	bool	true	Issue TLS 1.3 resumption tickets (2 per handshake), for static and ACME certificates alike. Ticket keys live in memory only and rotate every 6 hours; there is never 0-RTT. Every connection still proves its identity over its own TLS session. See TLS and certificates.

Both files are re-read on SIGHUP.

[server.decoy]

Key	Type	Default	Meaning and rules
enabled	bool	true	Serve a decoy website to non-relay requests. With false, they get a plain 404.
root	path	none	Absolute path to a static site, for example one written by --render-decoy. Must exist and be a directory at startup. Without it, a built-in page is served that varies with host.
host	string	first [server.acme] domain	The relay’s public host name. Seeds the built-in page and --render-decoy, together with the relay’s secret identity key, and gives --print-invite its host. Never shown on the page.
server_header	string	"nginx/1.24.0"	Server response header. Non-empty printable ASCII.
write_timeout_secs	integer	30	Time limit for writing one decoy response. Greater than 0.

[logging]

Key	Type	Default	Meaning
log_client_ips	bool	false	Add client IP addresses to debug log lines. Never affects info, warn or error.
format	string	"json"	Accepted, but not used. Logs are plain text on standard output.
output	string	"stdout"	Accepted, but not used.

[metrics]

Key	Type	Default	Meaning
enabled	bool	true	Serve Prometheus metrics over HTTP.
bind_addr	socket address	"127.0.0.1:9090"	Metrics listen address. The endpoint has no authentication. If it cannot bind, the error is logged and the relay keeps running.
allow_public	bool	false	Permit a non-loopback bind_addr. Without it, a non-loopback address stops the relay at startup. Firewall the endpoint if you set it.

Things to know

• Unknown keys are refused in every table, so a misspelt or obsolete key (such as udp_bind or [decoy] randomization_strength) stops the server at startup.
• Exactly one of [server.acme] (with enabled = true) or [server.tls] is required unless --no-tls is given.
• TLS must terminate at the relay. Key authentication binds to the relay’s own TLS session.
• Validation runs at startup. Any failure stops the server with a message naming the key.

Example

[server]
bind_addr = "0.0.0.0:443"
websocket_path = "/Zk3q-replace-with-32-random-url-safe-chars"
relay_identity_path = "/var/lib/rchat/relay_identity.key"
max_connections = 10000
max_connections_per_ip = 64
rate_limit_bps = 1048576
max_message_bytes = 4194304
connection_timeout_secs = 300
tls_handshake_timeout_secs = 10

[server.offline_queue]
ttl_secs = 259200
persist = false

[server.acme]
enabled   = true
domains   = ["chat.example.com"]
contacts  = ["mailto:[email protected]"]
cache_dir = "/var/lib/rchat/acme"
staging   = false

[server.decoy]
enabled = true
server_header = "nginx/1.24.0"

[logging]
log_client_ips = false

[metrics]
bind_addr = "127.0.0.1:9090"