Rocket/docs/guide/10-configuration.md

+++ summary = "overview and customization of Rocket application configuration" +++

Configuration

Rocket's configuration system is flexible. Based on Figment, it allows you to configure your application the way you want while also providing a sensible set of defaults.

Overview

Rocket's configuration system is based on Figment's Providers, types which provide configuration data. Rocket's Config and Config::figment(), as well as Figment's Toml and Json, are some examples of providers. Providers can be combined into a single Figment provider from which any configuration structure that implements Deserialize can be extracted.

Rocket expects to be able to extract a Config structure from the provider it is configured with. This means that no matter which configuration provider Rocket is asked to use, it must be able to read the following configuration values:

key	kind	description	debug/release default
address	IpAddr	IP address to serve on.	127.0.0.1
port	u16	Port to serve on.	8000
workers*	usize	Number of threads to use for executing futures.	cpu core count
max_blocking*	usize	Limit on threads to start for blocking tasks.	512
ident	string, false	If and how to identify via the Server header.	"Rocket"
ip_header	string, false	IP header to inspect to get client's real IP.	"X-Real-IP"
proxy_proto_header	string, false	Header identifying client to proxy protocol.	None
keep_alive	u32	Keep-alive timeout seconds; disabled when 0.	5
log_level	LogLevel	Max level to log. (off/normal/debug/critical)	normal/critical
cli_colors	CliColors	Whether to use colors and emoji when logging.	"auto"
secret_key	SecretKey	Secret key for signing and encrypting values.	None
tls	TlsConfig	TLS configuration, if any.	None
limits	Limits	Streaming read size limits.	Limits::default()
limits.$name	&str/uint	Read limit for $name.	form = "32KiB"
ctrlc	bool	Whether ctrl-c initiates a server shutdown.	true
shutdown*	ShutdownConfig	Graceful shutdown configuration.	ShutdownConfig::default()

* Note: the workers, max_blocking, and shutdown.force configuration parameters are only read from the default provider.

Profiles

Configurations can be arbitrarily namespaced by Profiles. Rocket's Config and Config::figment() providers automatically set the configuration profile to "debug" when compiled in "debug" mode and "release" when compiled in release mode, but you can arbitrarily name and set profiles to your desire. For example, with the default provider, you can set the selected profile via ROCKET_PROFILE. This results in Rocket preferring the values in the ROCKET_PROFILE profile.

In addition to any profiles you declare, there are two meta-profiles, default and global, which can be used to provide values that apply to all profiles. Values provided in a default profile are used as fall-back values when the selected profile doesn't contain a requested value, while values in the global profile supplant any values with the same name in any profile.

Default Provider

Rocket's default configuration provider is Config::figment(); this is the provider that's used when calling rocket::build().

The default figment reads from and merges, at a per-key level, the following sources in ascending priority order:

1. Config::default(), which provides default values for all parameters.
2. Rocket.toml or TOML file path in ROCKET_CONFIG environment variable.
3. ROCKET_ prefixed environment variables.

The selected profile is the value of the ROCKET_PROFILE environment variable, or if it is not set, "debug" when compiled in debug mode and "release" when compiled in release mode. With the exception of log_level, which changes from normal in debug to critical in release, all of the default configuration values are the same in all profiles. What's more, all configuration values have defaults, so no configuration is needed to get started.

As a result of Config::figment(), without any effort, Rocket can be configured via a Rocket.toml file and/or via environment variables, the latter of which take precedence over the former.

Rocket.toml

Rocket searches for Rocket.toml or the filename in a ROCKET_CONFIG environment variable starting at the current working directory. If it is not found, the parent directory, its parent, and so on, are searched until the file is found or the root is reached. If the path set in ROCKET_CONFIG is absolute, no such search occurs and the set path is used directly.

The file is assumed to be nested, so each top-level key declares a profile and its values the value for the profile. The following is an example of what such a file might look like:

## defaults for _all_ profiles
[default]
address = "0.0.0.0"
limits = { form = "64 kB", json = "1 MiB" }

## set only when compiled in debug mode, i.e, `cargo build`
[debug]
port = 8000
## only the `json` key from `default` will be overridden; `form` will remain
limits = { json = "10MiB" }

## set only when the `nyc` profile is selected
[nyc]
port = 9001

## set only when compiled in release mode, i.e, `cargo build --release`
[release]
port = 9999
ip_header = false
proxy_proto_header = "X-Forwarded-Proto"
# NOTE: Don't (!) use this key! Generate your own and keep it private!
#       e.g. via `head -c64 /dev/urandom | base64`
secret_key = "hPrYyЭRiMyµ5sBB1π+CMæ1køFsåqKvBiQJxBVHQk="

The following is a Rocket.toml file with all configuration options set for demonstration purposes. You do not and should not set a value for configuration options needlessly, preferring to use the default value when sensible.

[default]
address = "127.0.0.1"
port = 8000
workers = 16
max_blocking = 512
keep_alive = 5
ident = "Rocket"
ip_header = "X-Real-IP" # set to `false` to disable
proxy_proto_header = false # set to `false` (the default) to disable
log_level = "normal"
temp_dir = "/tmp"
cli_colors = true
# NOTE: Don't (!) use this key! Generate your own and keep it private!
#       e.g. via `head -c64 /dev/urandom | base64`
secret_key = "hPrYyЭRiMyµ5sBB1π+CMæ1køFsåqKvBiQJxBVHQk="

[default.limits]
form = "64 kB"
json = "1 MiB"
msgpack = "2 MiB"
"file/jpg" = "5 MiB"

[default.tls]
certs = "path/to/cert-chain.pem"
key = "path/to/key.pem"

[default.shutdown]
ctrlc = true
signals = ["term", "hup"]
grace = 5
mercy = 5

Environment Variables

Rocket reads all environment variable names prefixed with ROCKET_ using the string after the _ as the name of a configuration value as the value of the parameter as the value itself. Environment variables take precedence over values in Rocket.toml. Values are parsed as loose form of TOML syntax. Consider the following examples:

ROCKET_FLOAT=3.14
ROCKET_ARRAY=[1,"b",3.14]
ROCKET_STRING=Hello
ROCKET_STRING="Hello There"

ROCKET_KEEP_ALIVE=1
ROCKET_IDENT=Rocket
ROCKET_IDENT="Hello Rocket"
ROCKET_IDENT=false
ROCKET_TLS={certs="abc",key="foo/bar"}
ROCKET_LIMITS={form="64 KiB"}

Configuration Parameters

Secret Key

The secret_key parameter configures a cryptographic key to use when encrypting application values. In particular, the key is used to encrypt private cookies, which are available only when the secrets crate feature is enabled.

Generating a string suitable for use as a secret_key configuration value is usually done through tools like openssl. Using openssl, a 256-bit base64 key can be generated with the command openssl rand -base64 32.

When compiled in debug mode, a fresh key is generated automatically. In release mode, Rocket requires you to set a secret key if the secrets feature is enabled. Failure to do so results in a hard error at launch time. The value of the parameter may either be a 256-bit base64 or hex string or a slice of 32 bytes.

Limits

The limits parameter configures the maximum amount of data Rocket will accept for a given data type. The value is expected to be a dictionary table where each key corresponds to a data type and each value corresponds to the maximum size in bytes Rocket should accept for that type. Rocket can parse both integers (32768) or SI unit based strings ("32KiB") as limits.

By default, Rocket specifies a 32 KiB limit for incoming forms. Since Rocket requires specifying a read limit whenever data is read, external data guards may also choose to have a configure limit via the limits parameter. The Json type, for instance, uses the limits.json parameter.

TLS

Rocket includes built-in, native support for TLS >= 1.2 (Transport Layer Security). To enable TLS support:

1. Enable the tls crate feature in Cargo.toml:

[dependencies]
rocket = { version = "0.6.0-dev", features = ["tls"] }

2. Configure a TLS certificate chain and private key via the tls.key and tls.certs configuration parameters. With the default provider, this can be done via Rocket.toml as:

[default.tls]
key = "path/to/key.pem"     # Path or bytes to DER-encoded ASN.1 PKCS#1/#8 or SEC1 key.
certs = "path/to/certs.pem" # Path or bytes to DER-encoded X.509 TLS cert chain.

The tls parameter is expected to be a dictionary that deserializes into a TlsConfig structure:

key	required	type
key	yes	Path or bytes to DER-encoded ASN.1 PKCS#1/#8 or SEC1 key.
certs	yes	Path or bytes to DER-encoded X.509 TLS cert chain.
ciphers	no	Array of CipherSuites to enable.
prefer_server_cipher_order	no	Boolean for whether to prefer server cipher suites.
mutual	no	A map with mutual TLS configuration.

When specified via TOML or other serialized formats, each CipherSuite is written as a string representation of the respective variant. For example, CipherSuite::TLS_AES_256_GCM_SHA384 is "TLS_AES_256_GCM_SHA384". In TOML, the defaults (with an arbitrary certs and key) are written:

[default.tls]
certs = "/ssl/cert.pem"
key = "/ssl/key.pem"
prefer_server_cipher_order = false
ciphers = [
    "TLS_CHACHA20_POLY1305_SHA256",
    "TLS_AES_256_GCM_SHA384",
    "TLS_AES_128_GCM_SHA256",
    "TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256",
    "TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256",
    "TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384",
    "TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256",
    "TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384",
    "TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256",
]

Mutual TLS

Rocket supports mutual TLS client authentication. Configuration works in concert with the mtls module, which provides a request guard to validate, verify, and retrieve client certificates in routes.

By default, mutual TLS is disabled and client certificates are not required, validated or verified. To enable mutual TLS, the mtls feature must be enabled and support configured via the tls.mutual config parameter:

1. Enable the mtls crate feature in Cargo.toml:

[dependencies]
rocket = { version = "0.6.0-dev", features = ["mtls"] }

This implicitly enables the tls feature.

2. Configure a CA certificate chain via the tls.mutual.ca_certs configuration parameter. With the default provider, this can be done via Rocket.toml as:

[default.tls.mutual]
ca_certs = "path/to/ca_certs.pem" # Path or bytes to DER-encoded X.509 TLS cert chain.
mandatory = true                  # when absent, defaults to false

The tls.mutual parameter is expected to be a dictionary that deserializes into a [MutualTls] structure:

key	required	type
ca_certs	yes	Path or bytes to DER-encoded X.509 TLS cert chain.
mandatory	no	Boolean controlling whether the client must authenticate.

Rocket reports if TLS and/or mTLS are enabled at launch time:

🔧 Configured for debug.
   ...
   >> tls: enabled w/mtls

Once mutual TLS is properly enabled, the mtls::Certificate request guard can be used to retrieve validated, verified client certificates:

# #[macro_use] extern crate rocket;
use rocket::mtls::Certificate;

#[get("/auth")]
fn auth(cert: Certificate<'_>) {
    // This handler only runs when a valid certificate was presented.
}

The TLS example illustrates a fully configured TLS server with mutual TLS.

! warning: Rocket's built-in TLS supports only TLS 1.2 and 1.3.

This may not be suitable for production use requiring legacy support.

Proxied TLS

The proxy_proto_header configuration parameter allows Rocket applications to determine when and if a client's initial connection was likely made in a secure context by examining the header with the configured name. The header's value is parsed into a ProxyProto, retrievable via Request::proxy_proto().

That value is in-turn inspected to determine if the initial connection was secure (i.e, made over TLS) and the outcome made available via Request::context_is_likely_secure(). The value returned by this method influences cookie defaults. In particular, if the method returns true (i.e, the request context is likely secure), the Secure cookie flag is set by default when a cookie is added to a CookieJar.

To enable this behaviour, configure the header as set by your reverse proxy or forwarding entity. For example, to set the header name to X-Forwarded-Proto via a TOML file:

proxy_proto_header = "X-Forwarded-Proto"

Crypto Providers

Rocket's TLS support, provided by rustls, allows replacing the underlying CryptoProvider for cryptographic operations. By default, Rocket uses ring as its CryptoProvider, but applications can change the default by installing a different CryptoProvider before Rocket launches.

For example, to use aws-lc-rs instead of ring, first depend on rustls directly with the aws_lc_rs feature enabled:

[dependencies]
rustls = { version = "0.23", features = ["aws_lc_rs"] }

Then, before the application starts, install the provider as the default:

# #[macro_use] extern crate rocket;

#[launch]
fn rocket() -> _ {
    let _ = rustls::crypto::aws_lc_rs::default_provider().install_default();
    rocket::build()
}

Rocket will use the installed default whenever TLS is operational.

Workers

The workers parameter sets the number of threads used for parallel task execution; there is no limit to the number of concurrent tasks. Due to a limitation in upstream async executers, unlike other values, the workers configuration value cannot be reconfigured or be configured from sources other than those provided by Config::figment(). In other words, only the values set by the ROCKET_WORKERS environment variable or in the workers property of Rocket.toml will be considered - all other workers values are ignored.

The max_blocking parameter sets an upper limit on the number of threads the underlying async runtime will spawn to execute potentially blocking, synchronous tasks via spawn_blocking or equivalent. Similar to the workers parameter, max_blocking cannot be reconfigured or be configured from sources other than those provided by Config::figment(). Unlike workers, threads corresponding to max_blocking are not always active and will exit if idling. In general, the default value of 512 should not be changed unless physical or virtual resources are scarce. Rocket only executes work on blocking threads when required such as when performing file system I/O via TempFile or wrapping synchronous work via rocket_sync_db_pools.

Extracting Values

Your application can extract any configuration that implements Deserialize from the configured provider, which is exposed via Rocket::figment():

# #[macro_use] extern crate rocket;

use rocket::serde::Deserialize;

#[launch]
fn rocket() -> _ {
    let rocket = rocket::build();
    let figment = rocket.figment();

    #[derive(Deserialize)]
    #[serde(crate = "rocket::serde")]
    struct Config {
        port: u16,
        custom: Vec<String>,
    }

    // extract the entire config any `Deserialize` value
    let config: Config = figment.extract().expect("config");

    // or a piece of it into any `Deserialize` value
    let custom: Vec<String> = figment.extract_inner("custom").expect("custom");

    rocket
}

Both values recognized by Rocket and values not recognized by Rocket can be extracted. This means you can configure values recognized by your application in Rocket's configuration sources directly. The next section describes how you can customize configuration sources by supplying your own Provider.

Because it is common to store configuration in managed state, Rocket provides an AdHoc fairing that 1) extracts a configuration from the configured provider, 2) pretty prints any errors, and 3) stores the value in managed state:

# #[macro_use] extern crate rocket;
# use rocket::serde::Deserialize;
# #[derive(Deserialize)]
# #[serde(crate = "rocket::serde")]
# struct Config {
#     port: u16,
#     custom: Vec<String>,
# }

use rocket::{State, fairing::AdHoc};

#[get("/custom")]
fn custom(config: &State<Config>) -> String {
    config.custom.get(0).cloned().unwrap_or("default".into())
}

#[launch]
fn rocket() -> _ {
    rocket::build()
        .mount("/", routes![custom])
        .attach(AdHoc::config::<Config>())
}

Custom Providers

A custom provider can be set via rocket::custom(), which replaces calls to rocket::build(). The configured provider can be built on top of Config::figment(), Config::default(), both, or neither. The Figment documentation has full details on instantiating existing providers like Toml and Json as well as creating custom providers for more complex cases.

! note: You may need to depend on figment and serde directly.

Rocket reexports figment and serde from its crate root, so you can refer to figment types via rocket::figment and serde types via rocket::serde. However, Rocket does not enable all features from either crate. As such, you may need to import crates directly:

figment = { version = "0.10", features = ["env", "toml", "json"] }

As a first example, we override configuration values at runtime by merging figment's tuple providers with Rocket's default provider:

# #[macro_use] extern crate rocket;

use rocket::data::{Limits, ToByteUnit};

#[launch]
fn rocket() -> _ {
    let figment = rocket::Config::figment()
        .merge(("port", 1111))
        .merge(("limits", Limits::new().limit("json", 2.mebibytes())));

    rocket::custom(figment).mount("/", routes![/* .. */])
}

More involved, consider an application that wants to use Rocket's defaults for Config, but not its configuration sources, while allowing the application to be configured via an App.toml file that uses top-level keys as profiles (.nested()), APP_ environment variables as global overrides (.global()), and APP_PROFILE to configure the selected profile:

# #[macro_use] extern crate rocket;

use rocket::serde::{Serialize, Deserialize};
use rocket::fairing::AdHoc;

use figment::{Figment, Profile, providers::{Format, Toml, Serialized, Env}};

#[derive(Debug, Deserialize, Serialize)]
#[serde(crate = "rocket::serde")]
struct Config {
    app_value: usize,
    /* and so on.. */
}

impl Default for Config {
    fn default() -> Config {
        Config { app_value: 3, }
    }
}

#[launch]
fn rocket() -> _ {
    let figment = Figment::from(rocket::Config::default())
        .merge(Serialized::defaults(Config::default()))
        .merge(Toml::file("App.toml").nested())
        .merge(Env::prefixed("APP_").global())
        .select(Profile::from_env_or("APP_PROFILE", "default"));

    rocket::custom(figment)
        .mount("/", routes![/* .. */])
        .attach(AdHoc::config::<Config>())
}

Rocket will extract its configuration from the configured provider. This means that if values like port and address are configured in Config, App.toml or APP_ environment variables, Rocket will make use of them. The application can also extract its configuration, done here via the Adhoc::config() fairing.