Relay configuration
The relay reads one TOML file, relay.toml: /etc/easysync-relay/relay.toml unless another path is given with --config. Secrets are referenced by file name and are never part of the file, an argument or an environment variable. An unknown key or a value outside its range makes the relay refuse to start. Certificates, keys and token files are read at start; to change them, restart the relay.
Keys of relay.toml:
| Key | Type | Default | Required | Meaning |
|---|---|---|---|---|
listen | string, a socket address | "0.0.0.0:8443" | no | The listener for /relay/v1 (WSS, or plain WS with allow_plain_ws). |
tls_cert_file | string, a path | unset | no | PEM certificate chain. Set together with tls_key_file: the relay then terminates TLS. Exactly one of the two makes the relay refuse to start. |
tls_key_file | string, a path | unset | no | PEM private key for tls_cert_file. |
allow_plain_ws | bool | false | no | Without TLS files the relay refuses to start unless this is true; then it serves plain WS, for use behind a TLS-terminating reverse proxy, and logs a warning. No effect when TLS files are set. |
access_token_files | array of strings, paths | required | yes | Files that each hold one deployment access token as unpadded base64url text. The decoded token must be 16 to 64 bytes, otherwise the relay refuses to start. |
health_listen | string, a loopback socket address | "127.0.0.1:8081" | no | A plain-HTTP listener that serves only GET /healthz. The relay refuses to start if the address is not a loopback address. |
Keys of relay.toml, table limits:
| Key | Type | Default | Required | Meaning |
|---|---|---|---|---|
handshake_timeout_secs | integer, seconds | 15 | no | Time a listener has to answer an INCOMING before the dialer gets a timeout. |
session_lifetime_secs | integer, seconds | 3600 | no | Lifetime of a data pipe. |
idle_timeout_secs | integer, seconds | 30 | no | Idle timeout of a pipe. |
pair_register_per_min | integer | 5 | no | Pairing registrations per minute and source address. |
pair_join_per_min | integer | 20 | no | Pairing joins per minute and source address. |
dial_per_min | integer | 60 | no | Dial requests per minute and source address. |
listen_per_min | integer | 10 | no | Registrations per minute and control connection. |
max_tokens_per_control | integer | 192 | no | Registered rendezvous tokens per control connection (at most 1024). |
max_pending_per_listener | integer | 16 | no | Pending dials per listener. |
max_sessions | integer | 10000 | no | Pairing slots, pending dials and running pipes together. |
max_connections | integer | 20000 | no | Concurrent TCP connections in total. |
max_connections_per_ip | integer | 256 | no | Concurrent TCP connections per source address. |
max_pair_slots | integer | 10000 | no | Registered pairing slots. |
max_control_connections | integer | 10000 | no | Open control connections. |
pipe_buffer_bytes | integer, bytes | 262144 | no | Bytes buffered per direction of a pipe (at least 65536). |
bandwidth_bytes_per_sec | integer, bytes per second | unset | no | Per-pipe bandwidth limit, both directions together. Unset means unlimited. |
The optional table issue lets the relay issue access keys itself; it does so only with enabled = true.
Keys of relay.toml, table issue:
| Key | Type | Default | Required | Meaning |
|---|---|---|---|---|
enabled | bool | false | no | Issue access tokens through the HTTPS token API of the relay. Off means the token routes answer 404 and the relay opens no state file. |
state_file | string, a path | unset | no | Required when enabled: the file that holds the SHA-256 of every issued token with the day of creation and expiry. The relay needs a writable directory; a file it cannot read or parse is a start error. |
lifetime_days | integer, days | 90 | no | 2 to 730: an issued token that is not used for this long expires; a use moves the expiry. There is no maximum age. |
new_per_ip_per_day | integer | 5 | no | 1 to 1000: new tokens per source address (IPv6: per /64) in 24 hours. |
new_per_hour_total | integer | 600 | no | 1 to 100000: new tokens per hour in total, in fixed windows from the start of the relay. |
max_active | integer | 100000 | no | 1 to 1000000: issued tokens that exist at the same time. |
allowed_origins | array of strings | [] | no | Up to 16 exact origins for the CORS answers of the token routes (the origin of the web app). |
trusted_proxies | array of strings | [] | no | Up to 16 addresses or CIDR blocks of the reverse proxies whose X-Forwarded-For the token routes trust. Required (not empty) with allow_plain_ws. |
control_file | string, a path | unset | no | The operator-written control file: switch issuance off, revoke every issued token, block tokens by hash. Missing or unparsable at start is a start error. |
An example:
listen = "127.0.0.1:8443"
tls_cert_file = "/etc/easysync-relay/cert.pem"
tls_key_file = "/etc/easysync-relay/key.pem"
access_token_files = ["/etc/easysync-relay/token"]
health_listen = "127.0.0.1:8081"
[limits]
max_connections_per_ip = 256
bandwidth_bytes_per_sec = 1000000
[issue]
enabled = true
state_file = "/var/lib/easysync-relay/tokens.state"A relay forwards encrypted data. It does see IP addresses, timing and volume of the connections that use it: what the relay sees.