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 }