Configuration

Every rustle setting: its type, default value and whether a reload applies it. Generated from the proxy’s published reference.

rustle reads one TOML file. An unknown or misplaced key stops the startup, so a typo never goes unnoticed. The last column says what it takes to apply a change: rustle reload or a SIGHUP applies the reload settings to the running proxy, the restart ones need the proxy to be restarted.

`[server]`

Listeners, shards, health endpoint and control socket.

Settings of the [server] table
Key	Type	Default	Applied by	Description
listen	string	"0.0.0.0:8080"	restart	Plain port (HTTP + CONNECT), literal IP address.
workers	integer	1	restart	Number of shards (one thread each); `0` = one per CPU.
pin_cores	boolean	false	restart	Pin shard i to CPU i and steer each connection to the shard of the CPU that received it (Linux).
admin_listen	string	"127.0.0.1:8181"	restart	`GET /health`, no auth; `""` disables it.
control_socket	string	"auto"	restart	Unix socket (mode 0600) for `rustle reload`: `/run/rustle/rustle.sock` as root, else `$XDG_RUNTIME_DIR/rustle.sock`, else next to the user config; `""` disables it.
socket_buffer_bytes	integer	0	restart	`SO_SNDBUF`/`SO_RCVBUF` of relayed sockets; `0` = kernel autotuning. A fixed size (e.g. `1048576`) caps a 100 ms RTT link at ~80 Mbit/s and, on the loopback, can stall bulk flows for seconds.

`[auth]`

API keys, client allowlist and bans after wrong keys.

Settings of the [auth] table
Key	Type	Default	Applied by	Description
api_keys	string list	[]	reload	Accepted keys; empty = no authentication (open relay).
allow_clients	string list	[]	reload	IPs/CIDRs allowed to connect; empty = everyone. Others are closed at accept.
max_failures	integer	5	reload	Wrong keys tolerated per IP within the window; `0` = no ban. A request without credentials does not count.
failure_window	duration	"1m"	reload	Counting window.
ban_duration	duration	"15m"	reload	Ban duration.

`[limits]`

Connection and request-head limits.

Settings of the [limits] table
Key	Type	Default	Applied by	Description
max_connections	integer	10000	reload	Concurrent client connections (all shards); beyond: 503.
max_header_bytes	integer	65536	reload	Max request head size (431).

`[timeouts]`

Connect, idle and request-head timeouts.

Settings of the [timeouts] table
Key	Type	Default	Applied by	Description
connect	duration	"5s"	reload	Connection to the origin (504).
idle	duration	"1m"	reload	Inactivity on a connection or tunnel.
request_head	duration	"10s"	reload	Total time to receive a request head or SOCKS5 handshake.

`[http]`

Upstream connection pool, body limits and WebSocket upgrades.

Settings of the [http] table
Key	Type	Default	Applied by	Description
upstream_keepalive	boolean	true	restart	Reuse connections to origins.
max_idle_per_origin	integer	1024	restart	Idle connections kept per origin and per shard (16× that across all origins); a connection idle for over 15 s is closed instead of reused.
max_request_body_bytes	integer	0	reload	Max request body (413); `0` = unlimited.
max_response_body_bytes	integer	0	reload	Max response body (502 when declared, cut otherwise); `0` = unlimited.
allow_websocket	boolean	true	reload	Let `Upgrade: websocket` requests on the plain-HTTP path through (the connection becomes a tunnel once the origin answers 101); `false` refuses them with 403. `CONNECT` tunnels (`wss://`) are opaque and not affected: limit them with `[filter] allowed_ports`.

`[dns]`

Cache of resolved addresses.

Settings of the [dns] table
Key	Type	Default	Applied by	Description
ttl	duration	"1m"	reload	Lifetime of cached resolutions; `"0s"` disables the cache.
max_entries	integer	4096	reload	Cache size.

`[tls]`

HTTPS proxy and HTTP/2.

Settings of the [tls] table
Key	Type	Default	Applied by	Description
listen	string	""	restart	`"IP:port"` of the HTTPS port, e.g. `"0.0.0.0:8443"`; empty = disabled. Needs `cert` and `key`.
cert	string	""	reload	PEM certificate chain.
key	string	""	reload	PEM private key.
handshake_timeout	duration	"10s"	reload	Max duration of a TLS handshake.
http2	boolean	true	reload	Offer HTTP/2 through ALPN.
ktls	boolean	false	restart	Kernel TLS (Linux, `tls` module), opt-in. Software kernel TLS saves memory but is slower than rustls on throughput, tunnels included; see `benchmarks/documentation/RESULTS.md`.

`[filter]`

Destination policy.

Settings of the [filter] table
Key	Type	Default	Applied by	Description
block_private	boolean	true	reload	Refuse loopback, private, link-local, CGNAT, multicast and ULA destinations (403). Set `false` to reach your LAN.
deny	string list	[]	reload	Extra refused networks (CIDR).
allowed_ports	integer list	[]	reload	Allowed destination ports, e.g. `[80, 443]`; empty = all.

`[socks5]`

SOCKS5 listener (TCP CONNECT and UDP ASSOCIATE).

Settings of the [socks5] table
Key	Type	Default	Applied by	Description
listen	string	""	restart	`"IP:port"` of the SOCKS5 port, e.g. `"127.0.0.1:1080"`; empty = disabled. The password is one of the `api_keys`.

`[log]`

Access log.

Settings of the [log] table
Key	Type	Default	Applied by	Description
access	off \| errors \| all	"errors"	restart	`off`, `errors` (refusals and failures) or `all` (one line per request and tunnel).
output	file \| stdout	"file"	restart	`file` or `stdout`.
file	string	""	restart	Path when `output = "file"`; empty = no access log.
target	host \| url	"host"	restart	Log `host:port` or the full URL (`url`) of `http://` requests.