Module config

Expand description

parse TOML config and generate requests from it

§Sōzu’s configuration

This module is responsible for parsing the config.toml provided by the flag --config when starting Sōzu.

Here is the workflow for generating a working config:

    config.toml   ->   FileConfig    ->  ConfigBuilder   ->  Config

config.toml is parsed to FileConfig, a structure that itself contains a lot of substructures whose names start with File- and end with -Config, like FileHttpFrontendConfig for instance.

The instance of FileConfig is then passed to a ConfigBuilder that populates a final Config with listeners and clusters.

To illustrate:

use sozu_command_lib::config::{FileConfig, ConfigBuilder};

let file_config = FileConfig::load_from_path("../config.toml")
    .expect("Could not load config.toml");

let config = ConfigBuilder::new(file_config, "../assets/config.toml")
    .into_config()
    .expect("Could not build config");

Note that the path to config.toml is used twice: the first time, to parse the file, the second time, to keep the path in the config for later use.

However, there is a simpler way that combines all this:

use sozu_command_lib::config::Config;

let config = Config::load_from_path("../assets/config.toml")
    .expect("Could not build config from the path");

§How values are chosen

Values are chosen in this order of priority:

values defined in a section of the TOML file, for instance, timeouts for a specific listener
values defined globally in the TOML file, like timeouts or buffer size
if a variable has not been set in the TOML file, it will be set to a default defined here

Structs§

BackendConfig
Config: Sōzu configuration, populated with clusters and listeners.
ConfigBuilder: A builder that converts FileConfig to Config
FileClusterConfig
FileClusterFrontendConfig
FileConfig: Parsed from the TOML config provided by the user.
FileHealthCheckConfig
FileHstsConfig: HSTS (HTTP Strict Transport Security, RFC 6797) policy as serialised under [https.listeners.default.hsts] (listener default) or [clusters.<id>.frontends.hsts] (per-frontend override).
FileUdpClusterConfig: UDP-specific cluster knobs, parsed from a [clusters.<id>.udp] block.
FileUdpHealthConfig: UDP backend health-check configuration, parsed from [clusters.<id>.udp.health].
HeaderEditConfig: A single header mutation as serialised under [[clusters.<id>.frontends.headers]]. Maps to the proto Header message at request-build time.
HttpClusterConfig
HttpFrontendConfig
ListenerBuilder: An HTTP, HTTPS or TCP listener as parsed from the Listeners section in the toml
MetricsConfig
TcpClusterConfig
TcpFrontendConfig

Enums§

ClientAuthConfig: Config-facing mutual-TLS (client certificate authentication) mode, parsed from the client_auth key of an HTTPS listener’s TOML section. Serializes as lowercase ("none" / "optional" / "required") so operators write the documented values rather than the protobuf enum’s SCREAMING_SNAKE_CASE. Maps to the wire ClientAuthMode in ListenerBuilder::to_tls.
ClusterConfig
ConfigError
FileClusterProtocolConfig
ForwardedHeadersMode: The forwarding header family an HTTP or HTTPS listener adds to every forwarded request, as spelled in the TOML configuration (forwarded_headers = "both"). The wire form is ForwardedHeaders.
IncompatibilityKind
ListenerProtocol
MetricDetailLevel: Cardinality knob for metrics labels in the StatsD network drain.
MissingKind
PathRuleType

Constants§

DEFAULT_ACCEPT_QUEUE_TIMEOUT: timeout to accept connection events in the accept queue (60 seconds)
DEFAULT_ALPN_PROTOCOLS: Default ALPN protocols advertised by HTTPS listeners. Both HTTP/2 and HTTP/1.1 are enabled, allowing clients to negotiate either.
DEFAULT_AUTOMATIC_STATE_SAVE: wether to save the state automatically (false)
DEFAULT_BACK_TIMEOUT: maximum time of inactivity for a backend socket (30 seconds)
DEFAULT_BUFFER_SIZE: size of the buffers, in bytes (16 KB)
DEFAULT_CIPHER_LIST: Authoritative list of default cipher suites for all rustls-based TLS providers.
DEFAULT_COMMAND_BUFFER_SIZE: size of the buffer for the channels, in bytes. Must be bigger than the size of the data received. (1 MB)
DEFAULT_COMMAND_SOCKET_MODE: permission bits given to the unix command socket when command_socket_mode is absent: owner read/write only, the mode Sōzu has always used
DEFAULT_CONNECT_TIMEOUT: maximum time to connect to a backend server (3 seconds)
DEFAULT_DISABLE_CLUSTER_METRICS: wether to avoid register cluster metrics in the local drain
DEFAULT_EVICT_ON_QUEUE_FULL: whether to evict least-recently-active sessions when the accept queue is saturated (false). Defaults to false because during a DDoS the existing connections are more likely to be legitimate clients than the queued ones; evicting them would serve the attacker. Enable when overload is dominated by normal traffic spikes rather than attacks.
DEFAULT_FRONT_TIMEOUT: maximum time of inactivity for a frontend socket (60 seconds)
DEFAULT_GROUPS_LIST
DEFAULT_HSTS_MAX_AGE: Default Strict-Transport-Security: max-age value (1 year, 31_536_000 seconds) substituted at config-load when an [hsts] block sets enabled = true but omits max_age. Matches the HSTS preload list minimum (https://hstspreload.org/) and the Caddy / Nginx community recommendation. Operators can override with any u32; max_age = 0 is the RFC 6797 §11.4 kill switch and is allowed silently.
DEFAULT_LOG_TARGET: for both logs and access logs
DEFAULT_MAX_BUFFERS: maximum number of buffers (1 000)
DEFAULT_MAX_COMMAND_BUFFER_SIZE: maximum size of the buffer for the channels, in bytes. (2 MB)
DEFAULT_MAX_CONNECTIONS: maximum number of simultaneous connections (10 000)
DEFAULT_MAX_CONNECTIONS_PER_IP: Default per-(cluster, source-IP) connection limit. 0 means unlimited. Counts are kept per (cluster_id, source_ip) so two clusters never share a counter even from the same IP. Per-cluster overrides on the Cluster message take precedence.
DEFAULT_MAX_CONNECTIONS_PER_SUBNET: Default per-(cluster, source-SUBNET) connection limit. 0 means unlimited, which disables the subnet limiter entirely and leaves the pre-existing per-IP behaviour strictly unchanged. This is a SECOND, independent counter beside DEFAULT_MAX_CONNECTIONS_PER_IP, not a replacement: the per-IP cap serves the API-gateway case, the per-subnet cap the denial-of-service case where an attacker holding a routed prefix takes a fresh address per connection (sozu-proxy/sozu#1270). Both gates are consulted and both must admit.
DEFAULT_MAX_CONNECTION_ATTEMPTS: Default backend connection attempt budget of a request: how many backend connections it may try, the first included, before it is answered 503 (HTTP) or closed (TCP). Every failed connection counts — refused, timed out on connect_timeout, or reporting a socket error. Replaces the hard-coded CONN_RETRIES = 3 of sozu-lib; the default rose to 5 with sozu-proxy/sozu#1800, so a request survives more dead backends in a row.
DEFAULT_MIN_BUFFERS: minimum number of buffers (1)
DEFAULT_REQUEST_TIMEOUT: maximum time to receive a request since the connection started (10 seconds)
DEFAULT_RETRY_AFTER: Default Retry-After header value (seconds) on HTTP 429 responses emitted when a per-(cluster, source-IP) connection limit is hit. 0 omits the header — Retry-After: 0 invites an immediate retry that defeats the limit. TCP rejections do not emit this value (no HTTP envelope), but the field is accepted for symmetry.
DEFAULT_SEND_TLS_13_TICKETS: Number of TLS 1.3 tickets to send to a client when establishing a connection. The tickets allow the client to resume a session. This protects the client agains session tracking. Increases the number of getrandom syscalls, with little influence on performance. Defaults to 4.
DEFAULT_SHARD_MIN_BACKENDS: Default shard_min_backends: the reference fleet of Workload isolation using shuffle sharding (Colm MacCárthaigh, Amazon Builders’ Library, 2019), eight workers in shards of two. Below it the combinations are too few to isolate anything: with four backends in shards of two, six shards exist and nearly every pair of clients overlaps.
DEFAULT_SIGNATURE_ALGORITHMS
DEFAULT_SNI_PREREAD_MAX_BYTES: maximum number of bytes buffered while prereading the TLS ClientHello looking for the SNI extension on a TCP listener (16 KB — matches the H2 frame ceiling used elsewhere in this file). Only relevant when at least one SNI-scoped TcpFrontendConfig targets the listener; clamped by the global buffer_size (see ConfigError::SniPrereadMaxBytesExceedsBufferSize). Must match the proto default on TcpListenerConfig.sni_preread_max_bytes.
DEFAULT_SNI_PREREAD_TIMEOUT: maximum time allowed to receive enough bytes of the TLS ClientHello to read the SNI extension on a TCP listener (5 seconds). Only relevant when at least one SNI-scoped TcpFrontendConfig targets the listener. Must match the proto default on TcpListenerConfig.sni_preread_timeout.
DEFAULT_STICKY_NAME: a name applied to sticky sessions (“SOZUBALANCEID”)
DEFAULT_SUBNET_IPV4_PREFIX: Default IPv4 prefix length (bits) used to derive the subnet key. 32 masks nothing, so enabling only max_connections_per_subnet yields a per-address counter rather than a surprising aggregation. /24 is the recommended starting point; see doc/configure.md.
DEFAULT_SUBNET_IPV6_PREFIX: Default IPv6 prefix length (bits) used to derive the subnet key. 128 masks nothing. /56 is the recommended starting point; see doc/configure.md.
DEFAULT_UDP_BACK_TIMEOUT: upstream flow idle timeout for a UDP listener (30 seconds)
DEFAULT_UDP_FRONT_TIMEOUT: client/upstream flow idle timeout for a UDP listener (30 seconds)
DEFAULT_UDP_MAX_FLOWS: maximum number of concurrent UDP flows per listener. 0 selects the runtime auto policy (~70% of the soft RLIMIT_NOFILE).
DEFAULT_UDP_MAX_RX_DATAGRAM_SIZE: maximum received datagram size for a UDP listener, in bytes (1500 = a typical Ethernet MTU). Capped at the effective buffer_size at runtime.
DEFAULT_WORKER_AUTOMATIC_RESTART: wether a worker is automatically restarted when it crashes (true)
DEFAULT_WORKER_COUNT: number of workers, i.e. Sōzu processes that scale horizontally (2)
DEFAULT_WORKER_TIMEOUT: maximum time to wait for a worker to respond, until it is deemed NotAnswering (10 seconds)
DEFAULT_ZOMBIE_CHECK_INTERVAL: Interval between checking for zombie sessions, (30 minutes)
H2_MIN_BUFFER_SIZE: minimum buffer size required when any HTTPS listener advertises H2 ALPN.
HTTP_STATUS_MAX
HTTP_STATUS_MIN: Lowest and highest valid HTTP status codes: RFC 9110 §15 calls values outside 100..=599 invalid.
MAX_COMMAND_SOCKET_MODE: every permission bit command_socket_mode may set. setuid, setgid and the sticky bit mean nothing on a socket and are refused.
MAX_CONNECTION_ATTEMPTS_UPPER_BOUND: Inclusive upper bound of max_connection_attempts, global or per cluster: the attempt counters are u8.
MAX_LOOP_ITERATIONS
MAX_SUBNET_IPV4_PREFIX: Inclusive upper bound for DEFAULT_SUBNET_IPV4_PREFIX and the subnet_ipv4_prefix config key. A value above this is a config error, never silently clamped.
MAX_SUBNET_IPV6_PREFIX: Inclusive upper bound for DEFAULT_SUBNET_IPV6_PREFIX and the subnet_ipv6_prefix config key. A value above this is a config error, never silently clamped.
MIN_SNI_PREREAD_MAX_BYTES: minimum allowed sni_preread_max_bytes on a TCP listener targeted by an SNI frontend (5 bytes — a full TLS record header: 1-byte ContentType + 2-byte ProtocolVersion + 2-byte length, RFC 8446 §5.1). 0 (and every value below this floor) makes the preread shell issue reads that can never accumulate enough bytes to parse even the outer record framing, spinning until the event-loop iteration guard (MAX_LOOP_ITERATIONS) trips instead of ever reaching a routing decision. See ConfigError::SniPrereadMaxBytesTooSmall.

Functions§

default_sticky_name
load_answers: Load every per-status template referenced by answers.
parse_command_socket_mode: Parse command_socket_mode: one to four octal digits, a leading 0 allowed ("0660" and "660" are the same mode), no 0o prefix and no sign. The value must not exceed MAX_COMMAND_SOCKET_MODE, which refuses setuid, setgid and the sticky bit, and must keep the owner’s read and write bits: without them the proxy’s own user could no longer connect to run status, reload or upgrade.
parse_http_status_range: Parse one accepted_statuses entry of the TOML file or the CLI:
resolve_answer_source: Resolve a single answers map entry into the literal template body the proto layer expects.
validate_affinity_key: Validate a cluster’s client affinity key source, affinity_header or affinity_cookie.
validate_health_check_config: Validate a HealthCheckConfig for the rules every layer relies on: a known probe mode, strict positive thresholds, a URI that cannot smuggle a second HTTP message on the wire (RFC 9110 §5.1 — request-target; the leading / is only required in HTTP mode, the only one that sends it), accepted status ranges within 100..=599, at most one of expected_status / accepted_statuses, and neither in TCP mode, which judges no status. Used by the CLI request builder and the worker SetHealthCheck handler so off-channel inputs (TOML reload, third-party clients) are constrained the same way as sozu cluster health-check set.
validate_max_connection_attempts: Validate a max_connection_attempts value, global or per cluster: at least one attempt, at most MAX_CONNECTION_ATTEMPTS_UPPER_BOUND. Called at config load, on every AddCluster and on SetMaxConnectionAttempts.
validate_shuffle_sharding: Validate a cluster’s shuffle-sharding knobs (sozu-proxy/sozu#524).
validate_sni_pattern: Validates and normalizes a TCP frontend’s SNI pattern (sozu-proxy/sozu#1279): either an exact hostname or a single leading *. wildcard label. Rejects an embedded * anywhere else (so *.*.example.com and foo.*.com are both invalid), a bare *, any empty label (leading/trailing/consecutive dots), and any non-ASCII character (ConfigError::NonAsciiSniPattern) — on-wire SNI is always an ASCII A-label (RFC 6066 §3 / IDNA), so a Unicode U-label would load fine but never match at runtime, a silent routing failure. Full IDNA/ punycode transformation at config-load is intentionally out of scope (no idna dependency in this crate); operators write the A-label form directly, consistent with what the HTTP router produces via idna::domain_to_ascii in lib/src/router/mod.rs. ASCII-lowercases the accepted pattern for case-insensitive comparison.

Module config

Module config Copy item path

§Sōzu’s configuration

§How values are chosen

Structs§

Enums§

Constants§

Functions§

Module config