Skip to main content

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}