Environment variables
Almost all of Stalwart’s configuration lives in its data store, but a few settings are needed before the data store can be read, or describe the environment the process runs in. Stalwart reads these from environment variables when it starts.
A normal installation needs none of them. They exist for specific situations: selecting the configuration file, switching to recovery mode, setting the public URL behind a proxy, identifying a cluster node and tuning the process. All of them are read only at startup, so a change takes effect after a restart.
Where the variables are set depends on how the server was installed. Installations made with the installation script read them from the environment file /etc/stalwart/stalwart.env, or /usr/local/etc/stalwart/stalwart.env on FreeBSD. That file lists the most common variables, commented out, as described in Linux and macOS. Containers receive the variables through the container environment, and Windows services through the service wrapper.
Reference
Section titled “Reference”The server reads the following variables:
| Variable | Default | Effect |
|---|---|---|
CONFIG_PATH | none | Path of the configuration file. When set, it is used instead of the command line, which is then not read at all. |
STALWART_RECOVERY_MODE | off | 1 or true starts the server in recovery mode. Any other value is ignored. |
STALWART_RECOVERY_MODE_PORT | 8080 | Port of the plain HTTP listener used in recovery and bootstrap mode. The listener always binds all interfaces, as explained in Protect the setup listener. |
STALWART_RECOVERY_MODE_LOG_LEVEL | info | Level of the console log in recovery and bootstrap mode. |
STALWART_RECOVERY_ADMIN | none | The recovery administrator, as username:password. Accepted in every mode while set. |
STALWART_PUBLIC_URL | built from the hostname | Base URL published in discovery documents; see Public URLs. |
STALWART_HTTPS_PORT | none | Port for the public URL when STALWART_PUBLIC_URL is not set; see Public URLs. |
STALWART_HOSTNAME | the machine’s host name | Name of the node, used for its cluster node id and proposed as server hostname by the setup wizard. |
STALWART_ROLE | none | The cluster role of the node, which selects the tasks and listeners it runs. Must name a role defined in the configuration. |
STALWART_PUSH_SHARD | 1 | The push notification shard the node serves in a cluster, counted from 1. |
RUN_AS_USER, RUN_AS_GROUP | none | User and group to switch to after the listeners are bound, for a server started as root; see Running as an unprivileged user. Not available on Windows. |
TOKIO_WORKER_THREADS | one per CPU | Number of worker threads that run the server’s network and protocol work. |
EXPORT_TYPES | all | With --export, the families of data to export, as a comma-separated list; see Backup and restore. |
STALWART_HEALTHCHECK_URL | https://127.0.0.1:443/healthz/live | Container image only: the URL probed by the image’s health check; see Docker. |
Recovery and bootstrap
Section titled “Recovery and bootstrap”Four variables control recovery mode and bootstrap mode: STALWART_RECOVERY_MODE, STALWART_RECOVERY_MODE_PORT, STALWART_RECOVERY_MODE_LOG_LEVEL and STALWART_RECOVERY_ADMIN.
One of them needs particular care. STALWART_RECOVERY_ADMIN is also accepted in normal operation, where it acts as a full-access credential. It must therefore be removed from the environment once it is no longer needed, as described in Retire the recovery administrator.
Clustering
Section titled “Clustering”In a cluster, every node reads the same configuration from the shared data store. What tells the nodes apart is set in the environment instead, through three variables.
STALWART_HOSTNAME gives a node a distinct identity where machine host names are not unique, as in containers. It does not change the published URLs. STALWART_ROLE selects the node’s role. STALWART_PUSH_SHARD selects the push notification shard the node serves, counted from 1.
Public URLs
Section titled “Public URLs”Clients find the server’s HTTP endpoints through the OAuth, OpenID Connect and JMAP discovery documents. These documents publish absolute URLs, all built from one base URL. The same URL also limits OAuth sign-in, which the server accepts only for its host and for the configured service host names.
The server takes the base URL from the first of these sources that is available:
STALWART_PUBLIC_URL, with a trailing slash removed, for examplehttps://mail.example.comorhttps://mail.example.com:8443.- When
STALWART_HTTPS_PORTis set,https://<host>:<port>, where the host isSTALWART_HOSTNAMEor the machine’s host name. https://followed by the host name of the JMAP entry inSystemSettings.serviceswhen it has one, or bySystemSettings.defaultHostname.
Set STALWART_PUBLIC_URL when clients reach the server at a URL other than https://<hostname>, for example through a reverse proxy or on another port. Reverse proxy explains the consequences.
The variable changes only the published URLs. The ports the server listens on are set by its listeners, and the server hostname keeps its other uses, such as the SMTP greeting and certificate requests.
Worker threads
Section titled “Worker threads”TOKIO_WORKER_THREADS sets the size of the thread pool that runs the server’s network connections and protocol processing. When the variable is unset, the pool has one thread per CPU. Disk operations are not part of this pool: the RocksDB and SQLite data stores run them on a separate pool, sized by their poolWorkers setting. Worker threads describes when changing the number of threads helps.