Skip to main content

tuwunel_core/config/
http.rs

1//! Configures incoming HTTP requests, listeners, and response compression.
2//!
3//! Listener settings select TCP addresses, ports, and UNIX sockets. Request
4//! limits, proxy address sources, and compression apply to inbound traffic.
5
6use std::{collections::BTreeSet, path::PathBuf};
7
8use either::Either::Left;
9use ipnet::IpNet;
10use serde::Deserialize;
11use tuwunel_macros::config_example_generator;
12
13use super::{
14	IpSource, deserialize_bytesize_usize,
15	net::{ListeningAddr, ListeningPort},
16};
17
18/// HTTP listener
19///
20/// Settings for the server's own HTTP listener, which serves clients and
21/// other homeservers alike: request size, timeouts, client address
22/// detection and CORS. Where it listens is set in `[global.http.listen]`,
23/// response compression in `[global.http.compression]`, and direct TLS in
24/// `[global.tls]`. Requests the server sends to other hosts are configured
25/// in `[global.network.http]` instead.
26///
27/// Tips:
28/// - `max_request_size` also caps requests from other homeservers, and a
29///   value under 10 MB (`10000000` bytes) fails startup. A reverse proxy in
30///   front needs a body limit at least as large, or big uploads fail there.
31/// - Behind a reverse proxy, set `ip_source` to the header that proxy
32///   writes. A reload that changes `ip_source` is rejected; restart
33///   instead.
34#[expect(rustdoc::broken_intra_doc_links, rustdoc::bare_urls)]
35#[derive(Clone, Debug, Deserialize)]
36#[config_example_generator(
37	filename = "tuwunel-example.toml",
38	section = "global.http",
39	group = "true",
40	ignore = "compression listen"
41)]
42pub struct Http {
43	/// Sets the maximum request size for file uploads.
44	///
45	/// Accepts an integer byte count or a string with an SI/IEC suffix such as
46	/// "24 MiB".
47	///
48	/// default: "24 MiB"
49	/// legacy: max_request_size
50	#[serde(
51		default = "default_max_request_size",
52		deserialize_with = "deserialize_bytesize_usize"
53	)]
54	pub max_request_size: usize,
55
56	/// Sets the maximum time in seconds to receive a client request.
57	///
58	/// default: 75
59	/// legacy: client_receive_timeout
60	#[serde(default = "default_receive_timeout")]
61	pub receive_timeout: u64,
62
63	/// Sets the maximum time in seconds to process a client request.
64	///
65	/// default: 240
66	/// legacy: client_request_timeout
67	#[serde(default = "default_request_timeout")]
68	pub request_timeout: u64,
69
70	/// Sets the maximum time in seconds to transmit a client response.
71	///
72	/// default: 120
73	/// legacy: client_response_timeout
74	#[serde(default = "default_response_timeout")]
75	pub response_timeout: u64,
76
77	/// Sets the grace period in seconds for clean shutdown of client requests.
78	///
79	/// reloadable: yes
80	/// default: 15
81	/// legacy: client_shutdown_timeout
82	#[serde(default = "default_shutdown_timeout")]
83	pub shutdown_timeout: u64,
84
85	/// Selects the client IP source for rate limiting, logging, and security
86	/// tooling.
87	///
88	/// Password login and password re-entry (UIAA) use the TCP peer address and
89	/// ignore forwarding headers unless a header source is configured, and that
90	/// peer is not limited per address when it is loopback (a local reverse
91	/// proxy or the Unix socket). For other uses, an unset source scans common
92	/// proxy headers in leftmost-IP mode (`X-Forwarded-For`, RFC 7239
93	/// `Forwarded`, `X-Real-IP`, `Fly-Client-IP`, `True-Client-IP`,
94	/// `CF-Connecting-IP`, `CloudFront-Viewer-Address`) before the TCP peer
95	/// address, letting a client spoof its address.
96	///
97	/// A configured source is used alone, taking the rightmost value of a
98	/// multi-valued header, the one only the proxy appends; password
99	/// authentication requires it even from loopback or trusted peers and
100	/// refuses when it is missing or invalid, and a header source still needs a
101	/// trusted reverse proxy in front of tuwunel. Supported values are
102	/// "connect_info" for direct TCP peers,
103	/// "rightmost_x_forwarded_for" for nginx or Caddy, "rightmost_forwarded"
104	/// for RFC 7239 proxies, "x_real_ip" for nginx `X-Real-IP`,
105	/// "cf_connecting_ip" for Cloudflare or cloudflared, "true_client_ip" for
106	/// Akamai or Cloudflare Enterprise, "fly_client_ip" for Fly.io, and
107	/// "cloudfront_viewer_address" for AWS CloudFront; behind a reverse proxy,
108	/// including one on the Unix socket, select the header it sets, and restart
109	/// the server after changing this setting.
110	///
111	/// default: unset
112	/// config-example: "connect_info"
113	/// legacy: ip_source
114	#[serde(default)]
115	pub ip_source: Option<IpSource>,
116
117	/// Selects TCP peer subnets that bypass the configured client IP source.
118	///
119	/// Matching peers use the insecure header scan and `ConnectInfo` fallback
120	/// used when `http.ip_source` is unset; entries require CIDR prefixes
121	/// (`/32` or `/128` for a single host), while loopback (`127.0.0.0/8`,
122	/// `::1/128`) bypasses extraction without being listed, except for password
123	/// login and password re-entry (UIAA), which require the selected source.
124	/// Use this for locally attached bridges or server-side clients on private
125	/// container or VPN subnets that cannot carry the configured proxy header,
126	/// such as a Docker bridge without `network_mode: host`.
127	///
128	/// Exclude the address receiving external traffic from your proxy: listing
129	/// a shared bridge subnet containing the proxy, such as a common Compose
130	/// network, also bypasses proxy traffic and defeats `http.ip_source`. Any
131	/// peer in these subnets can forge client IPs through request headers, so
132	/// include only subnets controlled end-to-end; changing this setting
133	/// requires a server restart.
134	///
135	/// default: []
136	/// config-example: ["172.18.0.0/16", "fd00::/8"]
137	/// legacy: ip_source_trusted_subnets
138	#[expect(
139		clippy::doc_link_with_quotes,
140		reason = "config-example directive emits literal quoted strings, not an intra-doc link"
141	)]
142	#[serde(default)]
143	pub ip_source_trusted_subnets: Vec<IpNet>,
144
145	/// Sets the `Access-Control-Allow-Origin` header included in all
146	/// responses.
147	///
148	/// Multiple values may be specified. The default empty list produces the
149	/// header value `*`. Configure this only for a specific purpose, because
150	/// incorrect values can degrade or disrupt clients.
151	///
152	/// default: []
153	/// legacy: access_control_allow_origin
154	#[serde(default)]
155	pub access_control_allow_origin: BTreeSet<String>,
156
157	/// Settings for http compression.
158	///
159	/// display: section
160	#[serde(default)]
161	pub compression: Compression,
162
163	/// Settings for http listen.
164	///
165	/// display: section
166	#[serde(default)]
167	pub listen: Listen,
168}
169
170/// Response compression
171///
172/// Compresses the server's own HTTP responses for clients that accept it.
173/// Every codec is off by default; a reverse proxy can compress instead.
174/// Outbound requests negotiate compression separately in
175/// `[global.network.http]`.
176#[expect(rustdoc::broken_intra_doc_links, rustdoc::bare_urls)]
177#[derive(Clone, Copy, Debug, Default, Deserialize)]
178#[config_example_generator(
179	filename = "tuwunel-example.toml",
180	section = "global.http.compression",
181	group = "true"
182)]
183pub struct Compression {
184	/// Compresses the server's HTTP response bodies with zstd.
185	///
186	/// This has no effect unless tuwunel was built with the `zstd_compression`
187	/// feature. Most users do not need it, and HTTP compression can weaken
188	/// TLS; review https://breachattack.com/ and
189	/// https://wikipedia.org/wiki/BREACH before enabling it.
190	///
191	/// legacy: zstd_compression
192	#[serde(default)]
193	pub zstd: bool,
194
195	/// Compresses the server's HTTP response bodies with gzip.
196	///
197	/// This has no effect unless tuwunel was built with the `gzip_compression`
198	/// feature. Most users do not need it, and HTTP compression can weaken
199	/// TLS; review https://breachattack.com/ and
200	/// https://wikipedia.org/wiki/BREACH before enabling it. Servers in many
201	/// rooms may need it to reduce very large response bodies.
202	///
203	/// legacy: gzip_compression
204	#[serde(default)]
205	pub gzip: bool,
206
207	/// Compresses the server's HTTP response bodies with brotli.
208	///
209	/// This has no effect unless tuwunel was built with the
210	/// `brotli_compression` feature. Most users do not need it, and HTTP
211	/// compression can weaken TLS; review https://breachattack.com/ and
212	/// https://wikipedia.org/wiki/BREACH before enabling it.
213	///
214	/// legacy: brotli_compression
215	#[serde(default)]
216	pub brotli: bool,
217}
218
219/// Listening addresses, ports and Unix socket
220///
221/// By default the server listens for plain HTTP on port 8008 at `127.0.0.1`
222/// and `::1`, reachable only from the same host, which suits a reverse proxy
223/// there. It binds every combination of `address` and `port`. Setting
224/// `unix_socket_path` adds a Unix socket; with `address` left unset, the
225/// socket replaces the default TCP listeners.
226///
227/// Tips:
228/// - Listener settings are read once at startup; a reload does not rebind.
229/// - Sockets passed in by systemd socket activation are served alongside
230///   these, as plain HTTP or TLS like the other TCP listeners.
231/// - Other homeservers connect to port 8448 of `server_name` unless
232///   `well_known.server` or a DNS SRV record delegates elsewhere, so a
233///   reverse proxy, or this listener with `[global.tls]`, must answer
234///   there.
235/// - The Unix socket always speaks plain HTTP, even with `[global.tls]`.
236#[expect(rustdoc::broken_intra_doc_links, rustdoc::bare_urls)]
237#[derive(Clone, Debug, Deserialize)]
238#[config_example_generator(
239	filename = "tuwunel-example.toml",
240	section = "global.http.listen",
241	group = "true"
242)]
243pub struct Listen {
244	/// Selects the IPv4 or IPv6 addresses on which tuwunel listens.
245	///
246	/// Docker or container NAT deployments require "0.0.0.0". To listen on
247	/// multiple addresses, use a vector such as ["127.0.0.1", "::1"]. Every
248	/// explicitly configured address must bind or startup fails. The default
249	/// only assumes both loopback families exist, so a default address that
250	/// cannot bind is logged and skipped.
251	///
252	/// default: ["127.0.0.1", "::1"]
253	/// legacy: address
254	#[allow(
255		clippy::doc_link_with_quotes,
256		clippy::allow_attributes,
257		reason = "configuration arrays contain literal quoted strings, not intra-doc links"
258	)]
259	#[serde(default)]
260	pub(super) address: Option<ListeningAddr>,
261
262	/// Selects the ports on which tuwunel listens.
263	///
264	/// For reverse proxy setup, see
265	/// https://tuwunel.chat/deploying/generic.html#setting-up-the-reverse-proxy.
266	/// Docker deployments should keep this value and map an external port to
267	/// it. To listen on multiple ports, use a vector such as [8080, 8448].
268	///
269	/// default: 8008
270	/// legacy: port
271	#[serde(default = "default_port")]
272	pub(super) port: ListeningPort,
273
274	/// Selects the UNIX socket on which tuwunel listens.
275	///
276	/// The reverse proxy must be able to access this socket file. Add the
277	/// proxy to the 'tuwunel' group or grant world read/write access with
278	/// `http.listen.unix_socket_perms` set to at least 666.
279	///
280	/// example: "/run/tuwunel/tuwunel.sock"
281	/// legacy: unix_socket_path
282	pub unix_socket_path: Option<PathBuf>,
283
284	/// Sets the default permissions, in octal, for creating the UNIX socket.
285	///
286	/// default: 660
287	/// legacy: unix_socket_perms
288	#[serde(default = "default_unix_socket_perms")]
289	pub unix_socket_perms: u32,
290}
291
292impl Default for Http {
293	fn default() -> Self {
294		Self {
295			max_request_size: default_max_request_size(),
296			receive_timeout: default_receive_timeout(),
297			request_timeout: default_request_timeout(),
298			response_timeout: default_response_timeout(),
299			shutdown_timeout: default_shutdown_timeout(),
300			ip_source: Default::default(),
301			ip_source_trusted_subnets: Default::default(),
302			access_control_allow_origin: Default::default(),
303			compression: Compression::default(),
304			listen: Listen::default(),
305		}
306	}
307}
308
309impl Default for Listen {
310	fn default() -> Self {
311		Self {
312			address: Default::default(),
313			port: default_port(),
314			unix_socket_path: None,
315			unix_socket_perms: default_unix_socket_perms(),
316		}
317	}
318}
319
320fn default_max_request_size() -> usize { 24 * 1024 * 1024 }
321
322fn default_receive_timeout() -> u64 { 75 }
323
324fn default_request_timeout() -> u64 { 240 }
325
326fn default_response_timeout() -> u64 { 120 }
327
328fn default_shutdown_timeout() -> u64 { 15 }
329
330fn default_port() -> ListeningPort { ListeningPort { ports: Left(8008) } }
331
332fn default_unix_socket_perms() -> u32 { 660 }