tuwunel_core/config/network.rs
1//! Configures outbound discovery, DNS, and HTTP clients.
2//!
3//! Discovery settings bound federation well-known requests. DNS settings
4//! control resolver behavior, while HTTP settings govern outbound clients.
5
6use regex::RegexSet;
7use serde::Deserialize;
8use tuwunel_macros::config_example_generator;
9
10use super::{deserialize_bytesize_usize, true_fn};
11
12/// Outbound networking
13///
14/// How the server reaches other hosts. `[global.network.dns]` configures
15/// the built-in resolver, `[global.network.discovery]` bounds well-known
16/// lookups of federation destinations, and `[global.network.http]` sets
17/// limits and address filtering for outbound HTTP requests. The server's
18/// own listener is configured under `[global.http]` instead.
19#[expect(rustdoc::broken_intra_doc_links, rustdoc::bare_urls)]
20#[derive(Clone, Debug, Default, Deserialize)]
21#[config_example_generator(
22 filename = "tuwunel-example.toml",
23 section = "global.network",
24 group = "true",
25 ignore = "discovery dns http"
26)]
27pub struct Network {
28 /// Settings for network discovery.
29 ///
30 /// display: section
31 #[serde(default)]
32 pub discovery: Discovery,
33
34 /// Settings for network dns.
35 ///
36 /// display: section
37 #[serde(default)]
38 pub dns: Dns,
39
40 /// Settings for network http.
41 ///
42 /// display: section
43 #[serde(default)]
44 pub http: Http,
45}
46
47/// Federation server discovery
48///
49/// Timeouts for fetching `https://<server>/.well-known/matrix/server` from
50/// other homeservers while working out where to send federation requests.
51#[expect(rustdoc::broken_intra_doc_links, rustdoc::bare_urls)]
52#[derive(Clone, Copy, Debug, Deserialize)]
53#[config_example_generator(
54 filename = "tuwunel-example.toml",
55 section = "global.network.discovery",
56 group = "true"
57)]
58pub struct Discovery {
59 /// Sets the federation well-known resolution connection timeout in
60 /// seconds.
61 ///
62 /// default: 6
63 /// legacy: well_known_conn_timeout
64 #[serde(default = "default_well_known_conn_timeout")]
65 pub conn_timeout: u64,
66
67 /// Sets the federation HTTP well-known resolution request timeout in
68 /// seconds.
69 ///
70 /// default: 10
71 /// legacy: well_known_timeout
72 #[serde(default = "default_well_known_timeout")]
73 pub timeout: u64,
74}
75
76/// DNS resolver
77///
78/// The server resolves host names for its outbound HTTP requests with its
79/// own resolver rather than the system library. With `servers` empty it
80/// takes its nameservers from `/etc/resolv.conf` at startup. Answers are
81/// kept for at least `min_ttl` (`min_ttl_nxdomain` for missing domains)
82/// whatever their TTL.
83///
84/// Tips:
85/// - `servers` entries must be IP addresses with an optional port; a host
86/// name fails startup.
87/// - `passthru_domains` entries are regular expressions; a plain dotted
88/// name logs a startup warning because each dot matches any character.
89/// - Only `passthru_domains` applies on reload; other changes need a
90/// restart.
91#[expect(rustdoc::broken_intra_doc_links, rustdoc::bare_urls)]
92#[derive(Clone, Debug, Deserialize)]
93#[config_example_generator(
94 filename = "tuwunel-example.toml",
95 section = "global.network.dns",
96 group = "true"
97)]
98pub struct Dns {
99 /// Selects custom DNS servers instead of the operating system resolvers.
100 ///
101 /// A non-empty list prevents reading `/etc/resolv.conf`. Each entry is an
102 /// IP address with an optional port, defaulting to 53. Servers are
103 /// expected to support both UDP and TCP on that port; enable
104 /// `network.dns.query_over_tcp_only` if any server supports only TCP.
105 ///
106 /// example: ["127.0.0.53", "1.1.1.1:5353", "[fd00::1]:53"]
107 ///
108 /// default: []
109 /// legacy: dns_servers
110 #[serde(default)]
111 pub servers: Vec<String>,
112
113 /// Sets the maximum DNS memory cache entries; increase cautiously because
114 /// entry sizes vary, and decrease only with an external DNS cache, excluding
115 /// systemd-resolved even when configured to cache.
116 ///
117 /// default: 32768
118 /// legacy: dns_cache_entries
119 #[serde(default = "default_cache_entries")]
120 pub cache_entries: u32,
121
122 /// Sets the minimum DNS cache lifetime in seconds, intentionally high by
123 /// default for federation with many servers whose domains have shorter TTLs;
124 /// an external cache merely shifts this load to a cache unaware of the
125 /// application's needs, where honoring low TTLs can increase load.
126 ///
127 /// default: 10800
128 /// legacy: dns_min_ttl
129 #[serde(default = "default_min_ttl")]
130 pub min_ttl: u64,
131
132 /// Sets the minimum cached NXDOMAIN lifetime in seconds, defaulting to three
133 /// days because false negatives are very rare and efficient federation
134 /// requires aggressively caching domains assumed not to return rather than
135 /// repeatedly checking them.
136 ///
137 /// default: 259200
138 /// legacy: dns_min_ttl_nxdomain
139 #[serde(default = "default_min_ttl_nxdomain")]
140 pub min_ttl_nxdomain: u64,
141
142 /// Sets the number of DNS nameserver retries after a timeout or error.
143 ///
144 /// default: 10
145 /// legacy: dns_attempts
146 #[serde(default = "default_attempts")]
147 pub attempts: u16,
148
149 /// Sets the DNS response timeout in seconds; recursive queries to some
150 /// domains can take several seconds, so avoid overly short timeouts,
151 /// especially with slower hardware or resolvers.
152 ///
153 /// default: 10
154 /// legacy: dns_timeout
155 #[serde(default = "default_timeout")]
156 pub timeout: u64,
157
158 /// Enables TCP fallback after DNS errors.
159 ///
160 /// Disable this if the nameserver does not support it.
161 ///
162 /// legacy: dns_tcp_fallback
163 #[serde(default = "true_fn")]
164 pub tcp_fallback: bool,
165
166 /// Enables querying all nameservers until the domain is found.
167 ///
168 /// Hickory resolver calls this "trust_negative_responses". It can avoid
169 /// unnecessary queries when the first nameserver returns NXDOMAIN or an
170 /// empty NOERROR response.
171 ///
172 /// legacy: query_all_nameservers
173 #[serde(default = "true_fn")]
174 pub query_all_nameservers: bool,
175
176 /// Queries configured nameservers using only TCP instead of UDP, as some
177 /// container deployments require (see [DNS
178 /// troubleshooting](https://tuwunel.chat/troubleshooting.html#potential-dns-issues-when-using-docker)).
179 ///
180 /// legacy: query_over_tcp_only
181 #[serde(default)]
182 pub query_over_tcp_only: bool,
183
184 /// Selects the DNS A/AAAA lookup strategy by number.
185 ///
186 /// Use 1 (Ipv4Only) to query only A records with no AAAA/IPv6, or 2
187 /// (Ipv6Only) to query only AAAA records with no A/IPv4. Use 3
188 /// (Ipv4AndIpv6) to query both in parallel and accept the first successful
189 /// response. Use 4 (Ipv6thenIpv4) to query AAAA then A on failure, or 5
190 /// (Ipv4thenIpv6) to query A then AAAA on failure. Without IPv6
191 /// networking, 1 can improve DNS performance because successful AAAA
192 /// results cannot be used.
193 ///
194 /// default: 5
195 /// legacy: ip_lookup_strategy
196 #[serde(default = "default_ip_lookup_strategy")]
197 pub ip_lookup_strategy: u8,
198
199 /// Selects domain patterns resolved through the alternative DNS path.
200 ///
201 /// This path has no persistent cache, a very small memory cache, and no
202 /// enforced TTL. It serves internal networks and application services that
203 /// require those properties, and does not support federation or general
204 /// use.
205 ///
206 /// reloadable: yes
207 /// example: ['\.dns\.podman$']
208 ///
209 /// default: []
210 /// legacy: dns_passthru_domains
211 #[serde(default, with = "serde_regex")]
212 pub passthru_domains: RegexSet,
213
214 /// Resolves application services through the alternative DNS path; when all
215 /// should match, prefer this to listing domains in
216 /// `network.dns.passthru_domains` to avoid regex matching overhead and
217 /// domain list maintenance.
218 ///
219 /// legacy: dns_passthru_appservices
220 #[serde(default)]
221 pub passthru_appservices: bool,
222
223 /// Randomizes DNS query case and requires matching answer case to mitigate
224 /// spoofing; occasional logged errors usually indicate DNS overload, it can
225 /// be disabled for servers lacking support, and the false default follows
226 /// reports about popular DNS caches whose possible fixes may allow a future
227 /// release to restore true.
228 ///
229 /// legacy: dns_case_randomization
230 #[serde(default)]
231 pub case_randomization: bool,
232}
233
234/// Outbound HTTP requests
235///
236/// Defaults for HTTP requests the server makes to other hosts: federation,
237/// remote media and URL previews, push gateways, appservices and identity
238/// providers. The server's own listener is configured in `[global.http]`
239/// instead. Some clients override the timeouts here:
240/// `[global.federation.transport]`, `[global.sending]`,
241/// `[global.appservice_client]`, `[global.push]` and
242/// `[global.network.discovery]`.
243///
244/// Tips:
245/// - The default `ip_range_denylist` refuses private, loopback and
246/// link-local addresses, including a push gateway or URL preview target
247/// on your LAN. Remove just the range you need rather than emptying
248/// the list. Appservice requests are not checked against it.
249/// - An `ip_range_denylist` entry that is not a valid CIDR range fails
250/// startup.
251/// - Outbound proxies are set with `proxy` (the `[global.proxy]` table) or,
252/// while `proxy` stays `"none"`, by the `HTTP_PROXY`, `HTTPS_PROXY` and
253/// `ALL_PROXY` environment variables.
254#[expect(rustdoc::broken_intra_doc_links, rustdoc::bare_urls)]
255#[derive(Clone, Debug, Deserialize)]
256#[config_example_generator(
257 filename = "tuwunel-example.toml",
258 section = "global.network.http",
259 group = "true",
260 hidden = "allow_invalid_tls_certificates"
261)]
262pub struct Http {
263 /// Limits the size of a response body buffered from a remote server.
264 ///
265 /// This applies to federation requests, push gateway and appservice
266 /// transactions, and remote media fetched for URL previews. Peers cannot
267 /// be trusted to honor requested limits, so the local bound protects
268 /// against a remote exhausting process memory. Accepts an integer byte
269 /// count or a string with an SI/IEC suffix such as "256 MiB".
270 ///
271 /// default: "256 MiB"
272 /// legacy: max_response_size
273 #[serde(
274 default = "default_max_response_size",
275 deserialize_with = "deserialize_bytesize_usize"
276 )]
277 pub max_response_size: usize,
278
279 /// Sets the default outbound HTTP connection timeout in seconds;
280 /// individual clients may override it.
281 ///
282 /// default: 10
283 /// legacy: request_conn_timeout
284 #[serde(default = "default_conn_timeout")]
285 pub conn_timeout: u64,
286
287 /// Sets the default outbound HTTP read timeout in seconds; individual
288 /// clients may override it.
289 ///
290 /// default: 35
291 /// legacy: request_timeout
292 #[serde(default = "default_request_timeout")]
293 pub timeout: u64,
294
295 /// Sets the default outbound HTTP whole-request timeout in seconds.
296 ///
297 /// Keep it high enough for healthy requests while retaining a timeout
298 /// backstop. Individual clients may override it.
299 ///
300 /// default: 320
301 /// legacy: request_total_timeout
302 #[serde(default = "default_total_timeout")]
303 pub total_timeout: u64,
304
305 /// Sets the default outbound HTTP idle connection pool timeout in seconds;
306 /// individual clients may override it.
307 ///
308 /// default: 5
309 /// legacy: request_idle_timeout
310 #[serde(default = "default_idle_timeout")]
311 pub idle_timeout: u64,
312
313 /// Sets the default maximum idle outbound HTTP connections per host;
314 /// individual clients may override it.
315 ///
316 /// default: 1
317 /// legacy: request_idle_per_host
318 #[serde(default = "default_idle_per_host")]
319 pub idle_per_host: u16,
320
321 /// Allows outbound HTTP clients to negotiate gzip response compression.
322 ///
323 /// Clients advertise gzip in `Accept-Encoding` and transparently
324 /// decompress responses for federation, media, and URL preview traffic.
325 /// This is separate from `http.compression.gzip`, which compresses
326 /// tuwunel's own responses. It is enabled by default; disabling it
327 /// prevents both requesting and decompressing gzip. It has no effect
328 /// unless tuwunel was built with the `gzip_compression` feature.
329 ///
330 /// default: true
331 /// legacy: request_gzip
332 #[serde(default = "true_fn")]
333 pub gzip: bool,
334
335 /// Allows outbound HTTP clients to negotiate brotli response compression.
336 ///
337 /// Clients advertise brotli in `Accept-Encoding` and transparently
338 /// decompress responses for federation, media, and URL preview traffic.
339 /// This is separate from `http.compression.brotli`, which compresses
340 /// tuwunel's own responses. It is enabled by default; disabling it
341 /// prevents both requesting and decompressing brotli. It has no effect
342 /// unless tuwunel was built with the `brotli_compression` feature.
343 ///
344 /// default: true
345 /// legacy: request_brotli
346 #[serde(default = "true_fn")]
347 pub brotli: bool,
348
349 /// Allows outbound HTTP clients to negotiate zstd response compression.
350 ///
351 /// Clients advertise zstd in `Accept-Encoding` and transparently
352 /// decompress responses for federation, media, and URL preview traffic.
353 /// This is separate from `http.compression.zstd`, which compresses
354 /// tuwunel's own responses. It is enabled by default; disabling it
355 /// prevents both requesting and decompressing zstd. It has no effect
356 /// unless tuwunel was built with the `zstd_compression` feature.
357 ///
358 /// default: true
359 /// legacy: request_zstd
360 #[serde(default = "true_fn")]
361 pub zstd: bool,
362
363 #[expect(clippy::doc_link_with_quotes)]
364 /// Blocks outbound requests to the listed IPv4 and IPv6 CIDR ranges.
365 ///
366 /// Entries are quoted strings; the defaults cover RFC1918, unroutable,
367 /// loopback, multicast, and testnet addresses for security, and an empty
368 /// vector (`[]`) disables this filter. Application filtering can have
369 /// bypasses, so enforce network boundaries with firewall zones rather than
370 /// treating this as a guarantee.
371 ///
372 /// Proxy endpoints selected through configuration or environment variables
373 /// are exempt so private forward proxies remain reachable, while direct
374 /// requests and locally resolving `socks4` or `socks5` proxies still
375 /// filter destination addresses. HTTP(S) forward proxies and `socks4a` or
376 /// `socks5h` resolve destinations remotely, so their egress policy must
377 /// enforce destination network boundaries instead.
378 ///
379 /// Defaults to:
380 /// ["127.0.0.0/8", "0.0.0.0/8", "10.0.0.0/8", "172.16.0.0/12",
381 /// "192.168.0.0/16", "100.64.0.0/10", "192.0.0.0/24", "169.254.0.0/16",
382 /// "192.88.99.0/24", "198.18.0.0/15", "192.0.2.0/24", "198.51.100.0/24",
383 /// "203.0.113.0/24", "224.0.0.0/4", "::1/128", "::/128", "fe80::/10",
384 /// "fc00::/7", "2001:db8::/32", "ff00::/8", "fec0::/10"]
385 /// legacy: ip_range_denylist
386 #[serde(default = "default_ip_range_denylist")]
387 pub ip_range_denylist: Vec<String>,
388
389 /// Disables TLS certificate validation.
390 ///
391 /// This hidden setting affects all requests, including URL previews and
392 /// federation. It is highly insecure and must not be used in production.
393 ///
394 /// legacy: allow_invalid_tls_certificates
395 #[serde(default)]
396 pub allow_invalid_tls_certificates: bool,
397}
398
399impl Default for Discovery {
400 fn default() -> Self {
401 Self {
402 conn_timeout: default_well_known_conn_timeout(),
403 timeout: default_well_known_timeout(),
404 }
405 }
406}
407
408impl Default for Dns {
409 fn default() -> Self {
410 Self {
411 servers: Default::default(),
412 cache_entries: default_cache_entries(),
413 min_ttl: default_min_ttl(),
414 min_ttl_nxdomain: default_min_ttl_nxdomain(),
415 attempts: default_attempts(),
416 timeout: default_timeout(),
417 tcp_fallback: true_fn(),
418 query_all_nameservers: true_fn(),
419 query_over_tcp_only: Default::default(),
420 ip_lookup_strategy: default_ip_lookup_strategy(),
421 passthru_domains: Default::default(),
422 passthru_appservices: Default::default(),
423 case_randomization: Default::default(),
424 }
425 }
426}
427
428impl Default for Http {
429 fn default() -> Self {
430 Self {
431 max_response_size: default_max_response_size(),
432 conn_timeout: default_conn_timeout(),
433 timeout: default_request_timeout(),
434 total_timeout: default_total_timeout(),
435 idle_timeout: default_idle_timeout(),
436 idle_per_host: default_idle_per_host(),
437 gzip: true_fn(),
438 brotli: true_fn(),
439 zstd: true_fn(),
440 ip_range_denylist: default_ip_range_denylist(),
441 allow_invalid_tls_certificates: Default::default(),
442 }
443 }
444}
445
446fn default_well_known_conn_timeout() -> u64 { 6 }
447
448fn default_well_known_timeout() -> u64 { 10 }
449
450fn default_cache_entries() -> u32 { 32768 }
451
452fn default_min_ttl() -> u64 { 60 * 180 }
453
454fn default_min_ttl_nxdomain() -> u64 { 60 * 60 * 24 * 3 }
455
456fn default_attempts() -> u16 { 10 }
457
458fn default_timeout() -> u64 { 10 }
459
460fn default_ip_lookup_strategy() -> u8 { 5 }
461
462fn default_max_response_size() -> usize { 256 * 1024 * 1024 }
463
464fn default_conn_timeout() -> u64 { 10 }
465
466fn default_request_timeout() -> u64 { 35 }
467
468fn default_total_timeout() -> u64 { 320 }
469
470fn default_idle_timeout() -> u64 { 5 }
471
472fn default_idle_per_host() -> u16 { 1 }
473
474fn default_ip_range_denylist() -> Vec<String> {
475 vec![
476 "127.0.0.0/8".to_owned(),
477 "0.0.0.0/8".to_owned(),
478 "10.0.0.0/8".to_owned(),
479 "172.16.0.0/12".to_owned(),
480 "192.168.0.0/16".to_owned(),
481 "100.64.0.0/10".to_owned(),
482 "192.0.0.0/24".to_owned(),
483 "169.254.0.0/16".to_owned(),
484 "192.88.99.0/24".to_owned(),
485 "198.18.0.0/15".to_owned(),
486 "192.0.2.0/24".to_owned(),
487 "198.51.100.0/24".to_owned(),
488 "203.0.113.0/24".to_owned(),
489 "224.0.0.0/4".to_owned(),
490 "::1/128".to_owned(),
491 "::/128".to_owned(),
492 "fe80::/10".to_owned(),
493 "fc00::/7".to_owned(),
494 "2001:db8::/32".to_owned(),
495 "ff00::/8".to_owned(),
496 "fec0::/10".to_owned(),
497 ]
498}