Relay config

tealhand-relay --config <file> reads one TOML file. Unknown keys are refused, so a typo is an error rather than a silent default. For a walk-through, see Run your own relay.

Keys

Key	Type	Required	Default	Meaning
relay_bind	IP and port, as a string	Yes	none	HTTPS listener of the relay itself (iroh relay)
roster_bind	IP and port	Yes	none	HTTPS listener for POST /tealhand/v1/roster. The phone’s “relay upload address” must point here
http_bind	IP and port	No	127.0.0.1 with a port the system picks	Plain-HTTP captive-portal probe. The relay always opens one; without this key it stays on loopback
quic_bind	IP and port	No	off	UDP listener for QUIC address discovery. Devices expect port 7842
allowed_owners	array of strings	Yes	none	Owner keys, each thhw: and 66 lowercase hex digits. An empty array allows nobody
data_dir	path	Yes	none	Where stored device lists live. Created with mode 0700 if missing
max_connections_per_endpoint	integer	No	4	Most relay connections one device key may hold at once. At least 1
client_bytes_per_second	integer	No	8000000	Receive rate limit per client connection, in bytes per second. At least 1
[tls] cert	path	Yes	none	Certificate chain, PEM
[tls] key	path	Yes	none	Private key, PEM. On Unix it must not be readable by group or others

Two intervals are fixed and not in the file: live connections are checked against the device lists every 15 seconds, and the TLS key’s mode is checked again every hour (every 15 seconds while it is refused). The certificate and key are re-read from disk once a day.

The certificate can be a normal one (a name, checked against the public roots) or a self-signed one that the phone and the computers pin. tealhand-relay fingerprint --config <file> prints the fingerprint of the certificate in [tls] cert, and the relay logs it at every start. See Install Tealhand Relay.

Example

relay_bind = "203.0.113.10:443"
roster_bind = "203.0.113.10:8443"
# http_bind = "203.0.113.10:80"
# quic_bind = "203.0.113.10:7842"
allowed_owners = ["thhw:REPLACE_WITH_THE_OWNER_KEY_66_HEX_DIGITS"]
data_dir = "/var/lib/tealhand-relay"
# max_connections_per_endpoint = 4
# client_bytes_per_second = 8000000

[tls]
cert = "/etc/tealhand-relay/fullchain.pem"
key = "/etc/tealhand-relay/privkey.pem"

Checks and their errors

Problem	Error
The file cannot be read	cannot read config file <path>: <reason>
Not valid TOML, a missing required key, a wrong type or an unknown key	config file is not valid: <details naming the key>
A listener on 0.0.0.0, :: or ::ffff:0.0.0.0	<key> = <addr> is an unspecified address (it would listen on every interface); write the public IP address of this machine
An owner key that does not parse	allowed_owners[<index>] is not a valid owner key (expected thhw:<66 hex digits>)
Two of relay_bind, roster_bind, http_bind on the same address (port 0 excepted)	<key> and <other> are both <addr>; each listener needs its own address
max_connections_per_endpoint = 0	max_connections_per_endpoint must be at least 1
client_bytes_per_second = 0	config file is not valid: ... (it must be at least 1)

These stop the start with exit code 2. A TLS key that group or others can read stops it with exit code 1: TLS: <path> is readable by group or others (mode <mode>); run: chmod 600 <path>.

What happens with allowed_owners

• An empty list starts the relay, logs “allowed_owners is empty: the relay will deny every endpoint”, and lets nobody through. The relay fails closed.
• A stored device list whose owner is no longer in the list is ignored at start, so removing an owner revokes all its devices.
• A stored file that does not verify stops the start. Delete it to let the owner upload again.