Configuration reference

Every configuration knob the Pingora Server reads. The schema is defined in pingora-core/src/server/configuration/mod.rs and documented narratively in docs/user_guide/conf.md.

Configuration has two surfaces:

1. CLI options (Opt) — parsed by clap, passed to Server::new(Some(Opt::parse_args())).
2. YAML config file (ServerConf) — read from the path given by -c/--conf.

Unknown YAML keys are silently ignored, which lets you embed application-specific config in the same file.

CLI options

Flag	Description
-c PATH / --conf PATH	Load YAML configuration from PATH
-d / --daemon	Run in background (daemonize)
-u / --upgrade	Take over from a running instance via the upgrade socket
-t / --test	Test the config file syntax and exit
-h / --help	Print help (clap-generated)

YAML keys

The full schema. Defaults are documented in the linked source.

Process and lifecycle

Key	Type	Description
version	number	Schema version. Currently always 1.
pid_file	string	Where to write the PID file
daemon	bool	Run in background. Same effect as -d.
error_log	string	Path to error log. STDERR if unset.
upgrade_sock	string	Path to the Unix-domain socket used for graceful FD handoff
user	string	Drop privileges to this user after binding
group	string	Drop privileges to this group
daemon_wait_for_ready	bool	When daemonized, parent waits for child's SIGUSR1 ready signal. Default false.
daemon_ready_timeout_seconds	number	Parent's max wait for ready signal. Default 600.
daemon_notify_timeout_seconds	number	Child's max retry budget for sending SIGUSR1. Default 60.

Threading and runtime

Key	Type	Description
threads	number	Worker threads per service runtime
work_stealing	bool	Use tokio's multi-threaded work-stealing scheduler. Default true. If false, runs N isolated current-thread runtimes.
tokio.blocking_threads (sub-options)	object	Tokio blocking-pool tuning (added in b994854, Mar 2026). Configures spawn_blocking pool size, keep-alive, stack size.

Networking

Key	Type	Description
client_bind_to_ipv4	list of string	Source IPv4 addresses for outbound connections
client_bind_to_ipv6	list of string	Source IPv6 addresses
upstream_keepalive_pool_size	number	Max idle connections in the upstream pool
ca_file	string	Path to a PEM bundle of CA certificates (for upstream TLS verification)

TLS backend specifics

Key	Type	Description
s2n_config_cache_size	number	s2n-tls only. Max unique s2n_config objects to cache. 0 disables. Default 10.

Sentry

Key	Type	Description
sentry.dsn	string	Sentry DSN. Only used when the sentry cargo feature is on.

Programmatic overrides

Several knobs live on Rust types rather than YAML:

• HTTP/2 stream/connection windows. Configurable on HttpProxy since 2114056 (Apr 2026).
• Per-session h2 options. HttpProxy::h2_options.
• HttpServerOptions — per-service, e.g. enable CONNECT proxying.
• max_weight on MissFinishType::Appended — cache machinery (0.7.0).

These don't have YAML representations; you set them in code.

User-defined configuration

Pattern: define your own struct with serde::Deserialize, parse the same YAML file separately:

#[derive(Deserialize)]
struct MyConf {
    upstream_addrs: Vec<String>,
    rate_limit_qps: u32,
}

let f = std::fs::File::open(path)?;
let my_conf: MyConf = serde_yaml::from_reader(f)?;

Pingora's ServerConf parses with #[serde(default)] on most fields and ignores unknown keys, so coexisting in the same file is fine.

See also

• docs/user_guide/conf.md — narrative version
• pingora-core/src/server/configuration/mod.rs — the canonical struct
• Deployment — example production config