Struct ServerConf 

pub struct ServerConf {

    pub version: usize,
    pub daemon: bool,
    pub error_log: Option<String>,
    pub pid_file: String,
    pub upgrade_sock: String,
    pub user: Option<String>,
    pub group: Option<String>,
    pub working_directory: Option<PathBuf>,
    pub threads: usize,
    pub listener_tasks_per_fd: usize,
    pub work_stealing: bool,
    pub runtime_enable_alt_timer: bool,
    pub ca_file: Option<String>,
    pub grace_period_seconds: Option<u64>,
    pub graceful_shutdown_timeout_seconds: Option<u64>,
    pub client_bind_to_ipv4: Vec<String>,
    pub client_bind_to_ipv6: Vec<String>,
    pub upstream_keepalive_pool_size: usize,
    pub upstream_connect_offload_threadpools: Option<usize>,
    pub upstream_connect_offload_thread_per_pool: Option<usize>,
    pub downstream_tls_offload_threadpools: Option<usize>,
    pub downstream_tls_offload_thread_per_pool: Option<usize>,
    pub upstream_debug_ssl_keylog: bool,
    pub max_retries: usize,
    pub upgrade_sock_connect_accept_max_retries: Option<usize>,
    pub max_blocking_threads: Option<usize>,
    pub blocking_threads_ttl_seconds: Option<u64>,
    pub fast_timeout_to_tokio_threshold_seconds: Option<u64>,
    pub runtime_metrics_poll_time_histogram: bool,
    pub runtime_metrics_poll_time_histogram_scale: Option<RuntimeMetricsPollTimeHistogramScale>,
    pub runtime_metrics_poll_time_histogram_resolution_micros: Option<u64>,
    pub runtime_metrics_poll_time_histogram_buckets: Option<usize>,
    pub daemon_wait_for_ready: bool,
    pub daemon_ready_timeout_seconds: Option<NonZeroU64>,
    pub daemon_notify_timeout_seconds: Option<NonZeroU64>,
}

The configuration file

Pingora configuration files are by default YAML files, but any key value format can potentially be used.

Extension

New keys can be added to the configuration files which this configuration object will ignore. Then, users can parse these key-values to pass to their code to use.

Fields

version: usize

Version

daemon: bool

Whether to run this process in the background.

error_log: Option<String>

When configured and daemon setting is true, error log will be written to the given file. Otherwise StdErr will be used.

pid_file: String

The pid (process ID) file of this server to be created when running in background

upgrade_sock: String

the path to the upgrade socket

In order to perform zero downtime restart, both the new and old process need to agree on the path to this sock in order to coordinate the upgrade.

user: Option<String>

If configured, after daemonization, this process will switch to the given user before starting to serve traffic.

group: Option<String>

Similar to user, the group this process should switch to.

working_directory: Option<PathBuf>

Working directory for the daemonized process.

Only applied when daemon is true; set this to start the daemon from a known cwd.

threads: usize

How many threads each service should get. The threads are not shared across services.

listener_tasks_per_fd: usize

Number of listener tasks to use per fd. This allows for parallel accepts.

work_stealing: bool

Allow work stealing between threads of the same service. Default true.

runtime_enable_alt_timer: bool

Enable Tokio’s experimental alternative timer on work-stealing service runtimes.

Requires building with --cfg tokio_unstable. Ignored when Self::work_stealing is disabled.

ca_file: Option<String>

The path to CA file the SSL library should use. If empty, the default trust store location defined by the SSL library will be used.

grace_period_seconds: Option<u64>

Grace period in seconds before starting the final step of the graceful shutdown after signaling shutdown.

graceful_shutdown_timeout_seconds: Option<u64>

Timeout in seconds of the final step for the graceful shutdown.

client_bind_to_ipv4: Vec<String>

IPv4 addresses for a client connector to bind to. See ConnectorOptions. Note: this is an unstable field that may be renamed or removed in the future.

client_bind_to_ipv6: Vec<String>

IPv6 addresses for a client connector to bind to. See ConnectorOptions. Note: this is an unstable field that may be renamed or removed in the future.

upstream_keepalive_pool_size: usize

Keepalive pool size for client connections to upstream. See ConnectorOptions. Note: this is an unstable field that may be renamed or removed in the future.

upstream_connect_offload_threadpools: Option<usize>

Number of dedicated thread pools to use for upstream connection establishment. See ConnectorOptions. Note: this is an unstable field that may be renamed or removed in the future.

upstream_connect_offload_thread_per_pool: Option<usize>

Number of threads per dedicated upstream connection establishment pool. See ConnectorOptions. Note: this is an unstable field that may be renamed or removed in the future.

downstream_tls_offload_threadpools: Option<usize>

Number of dedicated thread pools to use for downstream TLS handshakes. See TlsSettings::set_offload_threadpool_from_server_conf. Note: this is an unstable field that may be renamed or removed in the future.

downstream_tls_offload_thread_per_pool: Option<usize>

Number of threads per dedicated downstream TLS handshake pool. See TlsSettings::set_offload_threadpool_from_server_conf. Note: this is an unstable field that may be renamed or removed in the future.

upstream_debug_ssl_keylog: bool

When enabled allows TLS keys to be written to a file specified by the SSLKEYLOG env variable. This can be used by tools like Wireshark to decrypt upstream traffic for debugging purposes. Note: this is an unstable field that may be renamed or removed in the future.

max_retries: usize

The maximum number of retries that will be attempted when an error is retry-able (e.retry() == true) when proxying to upstream.

This setting is a fail-safe and defaults to 16.

upgrade_sock_connect_accept_max_retries: Option<usize>

Maximum number of retries for upgrade socket connect and accept operations. This controls how many times send_fds_to will retry connecting and how many times get_fds_from will retry accepting during graceful upgrades. The retry interval is 1 second between attempts. If not set, defaults to 5 retries.

max_blocking_threads: Option<usize>

The maximum number of threads in each runtime’s blocking thread pool.

The blocking pool handles tokio::task::spawn_blocking tasks. When not set, the tokio default (512) is used.

blocking_threads_ttl_seconds: Option<u64>

How long, in seconds, idle blocking threads are kept alive before being shut down.

When not set, the tokio default (10 seconds) is used.

fast_timeout_to_tokio_threshold_seconds: Option<u64>

Timeout durations greater than this threshold use Tokio’s native timeout instead of Pingora’s fast timeout.

This avoids retaining long-duration cancelled timers in Pingora’s shared timer map until their original deadline. When not set, defaults to 900 seconds (15 minutes). Set to null to disable the Tokio fallback.

runtime_metrics_poll_time_histogram: bool

Enable Tokio’s poll-time histogram on runtimes created by this server.

This adds two timestamp reads to every task poll, so it should be enabled deliberately when investigating runtime latency. Requires building with --cfg tokio_unstable.

runtime_metrics_poll_time_histogram_scale: Option<RuntimeMetricsPollTimeHistogramScale>

Bucket scale for Tokio’s poll-time histogram.

Ignored unless Self::runtime_metrics_poll_time_histogram is enabled.

runtime_metrics_poll_time_histogram_resolution_micros: Option<u64>

Width of the first Tokio poll-time histogram bucket in microseconds.

Ignored unless Self::runtime_metrics_poll_time_histogram is enabled.

runtime_metrics_poll_time_histogram_buckets: Option<usize>

Number of Tokio poll-time histogram buckets.

Ignored unless Self::runtime_metrics_poll_time_histogram is enabled. Memory usage scales with runtimes × workers × buckets, so values above 1024 are rejected.

daemon_wait_for_ready: bool

When daemon is true, controls whether the parent process of the daemon fork waits for the child to signal readiness before exiting.

When false (default), the parent exits immediately after the daemon fork, matching the traditional daemonization behavior. Systemd will consider the service started as soon as the parent exits, which may be before the child has finished bootstrapping.

When true, the parent waits (up to Self::daemon_ready_timeout_seconds) for the child to send SIGUSR1 after bootstrap completes. This causes systemd to delay any subsequent steps (such as sending SIGQUIT to the old process) until the new instance is fully ready to serve traffic. If the child does not signal in time, the parent exits with a non-zero exit code, causing systemd to abort the reload.

daemon_ready_timeout_seconds: Option<NonZeroU64>

Timeout in seconds for the parent process to wait for the child to signal readiness during daemonization when Self::daemon_wait_for_ready is true.

If the child does not send SIGUSR1 within this timeout, the parent exits with a non-zero exit code.

Defaults to 600 seconds (10 minutes).

daemon_notify_timeout_seconds: Option<NonZeroU64>

How long the child process will keep retrying SIGUSR1 to the parent when the signal fails with a permission error (EPERM) during daemonization.

After the daemon fork, the parent always drops its credentials to the configured user and group (see Self::user, Self::group). Because the privilege drop happens after the fork, there is a small window where the child may attempt to signal the parent before the parent has finished changing its credentials. During this window the kernel will reject the signal with EPERM because the child and parent are running as different users. The child retries every 100 ms until this timeout elapses.

In practice this window is very small, so the default of 60 seconds is far more than enough to account for it.

Only retries on EPERM; any other error (e.g. ESRCH — parent no longer exists) is treated as fatal and logged without retrying.

Defaults to 60 seconds.

Implementations

impl ServerConf

pub fn load_from_yaml<P>(path: P) -> Result<Self>

where P: AsRef<Path> + Display,

pub fn load_yaml_with_opt_override(opt: &Opt) -> Result<Self>

pub fn new() -> Option<Self>

pub fn new_with_opt_override(opt: &Opt) -> Option<Self>

pub fn from_yaml(conf_str: &str) -> Result<Self>

pub fn to_yaml(&self) -> String

pub fn validate(self) -> Result<Self>

pub fn upstream_connect_offload_threadpool(&self) -> Option<(usize, usize)>

Return the upstream connection offload setting from this configuration.

Both upstream_connect_offload_threadpools and upstream_connect_offload_thread_per_pool must be set and greater than zero. Otherwise, upstream connection offload remains disabled.

pub fn downstream_tls_offload_threadpool(&self) -> Option<(usize, usize)>

Return the downstream TLS handshake offload setting from this configuration.

Both downstream_tls_offload_threadpools and downstream_tls_offload_thread_per_pool must be set and greater than zero. Otherwise, downstream TLS handshake offload remains disabled.

pub fn runtime_opts(&self) -> RuntimeOpts

Build the default runtime options derived from this server configuration.

pub fn merge_with_opt(&mut self, opt: &Opt)

Trait Implementations

impl Debug for ServerConf

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for ServerConf

fn default() -> Self

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for ServerConf

where ServerConf: Default,

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Eq for ServerConf

impl PartialEq for ServerConf

fn eq(&self, other: &ServerConf) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl Serialize for ServerConf

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for ServerConf