Reference
Server configuration
Environment variables, profiles, ports, data directory, TLS, regions and fixed values of a Sovrain server.
How a Sovrain server is configured. This matters only to people who run Sovrain themselves; organizations on
sovrain.net change nothing here. Steps: Run Sovrain with Docker.
The server reads its configuration from environment variables at start. A variable set to an empty value counts as
not set. With the profiles qa and prod, the server refuses to start when a required value is missing and names
it.
Profiles
SPRING_PROFILES_ACTIVE is a comma-separated list. Only local, qa and prod have an effect.
| none | local | qa | prod | |
|---|---|---|---|---|
| Purpose | Development | Development with developer pages | Staging | Production |
| HTTPS with automatic certificates | no, plain HTTP | no, plain HTTP | yes, ClouDNS only | yes, ClouDNS or OVH |
Secure cookies | no | no | yes | yes |
IDP_MEK, IDP_CSRF_SECRET, SMTP | built-in defaults | built-in defaults | required | required |
| Developer pages, diagnostics | no | yes | no | no |
| Loopback addresses for back-channel logout and SCIM | no | yes | no | no |
| Data directory default | ~/.idp | ~/.idp | /data | /data |
| written to the log, without the body | written to the log, with the body | sent | sent |
There is no profile for running behind a reverse proxy that terminates TLS: qa and prod always run their own
HTTPS listener with certificates from ACME.
Environment variables
Core
| Variable | Default | Notes |
|---|---|---|
SPRING_PROFILES_ACTIVE | none | See Profiles |
SERVER_PORT | 8080 | Plain HTTP listener |
IDP_DATABASE_DIRECTORY | /data in qa and prod, ~/.idp otherwise | Data directory. HOME must be set when it is not. |
IDP_MEK | built-in development key; required in qa and prod | Master encryption key: Base64 of 32 bytes. The data directory is tied to it by the file mek-fingerprint; a different key refuses to start. Sovrain has no way to re-encrypt the data under another key. |
IDP_CSRF_SECRET | random at each start; required in qa and prod | Key for CSRF tokens and signed markers |
IDP_BASE_URL | http://idp.localhost:8080; ignored in qa; required in prod | The landing address, for example https://sovrain.net. Organizations are at https://<slug>.<host>. |
IDP_PREFIX | empty | Text before every browser tab title, for example [TEST]. At most 20 characters. |
IDP_RATE_LIMIT_TRUST_PROXY | false | true: rate limits use the first X-Forwarded-For address as the client. Set it only behind a proxy that overwrites that header. |
RUST_LOG | info | Log filter |
| Variable | Default | Notes |
|---|---|---|
IDP_SMTP_HOST | none; required in qa and prod | Mail relay |
IDP_SMTP_USERNAME | none; required in qa and prod | |
IDP_SMTP_PASSWORD | none; required in qa and prod | |
IDP_SMTP_PORT | 465 | |
IDP_SMTP_SSL | true | true: TLS from the start of the connection (implicit TLS). false: plain SMTP without any TLS; STARTTLS is not used. |
IDP_MAIL_FROM | the SMTP user name in qa and prod; noreply@sovrain.local otherwise | Sender address |
Mail is sent with a 5-second connect timeout and 20 seconds for the whole message. Each email is sent while the request that caused it waits, except delegation notices, which are queued. When the relay cannot be reached or does not answer in time, sending fails at once for the next 30 seconds; a relay that refuses an email does not start this pause. A failed email does not undo the action that caused it. Which emails are sent and their limits: Emails. Steps: Configure outgoing mail.
TLS and DNS
Certificates come from an ACME server with the DNS-01 challenge, through the API of a DNS provider.
| Variable | Default | Notes |
|---|---|---|
IDP_TLS_ACME_DIRECTORY | Let’s Encrypt production | ACME directory URL |
IDP_TLS_DNS_PROVIDER | cloudns | cloudns or ovh. Always cloudns in qa. |
IDP_TLS_DNS_ZONE | empty in prod (the landing host) | The DNS zone that holds the landing and region hosts |
IDP_TLS_DNS_SETTLE_DELAY | 60s | Wait before the challenge is answered; whole seconds with s |
IDP_TLS_DNS_SERVER | not set | <ip>:<port> of a DNS server to ask instead of the normal resolvers. For test setups. |
IDP_TLS_CLOUDNS_ENDPOINT | https://api.cloudns.net | |
IDP_TLS_CLOUDNS_AUTH_KIND | SUB_AUTH_ID | SUB_AUTH_ID or AUTH_ID |
IDP_TLS_CLOUDNS_AUTH_ID, IDP_TLS_CLOUDNS_PASSWORD | none | Required when the provider is cloudns |
IDP_TLS_OVH_ENDPOINT | https://eu.api.ovh.com/1.0 | |
IDP_TLS_OVH_APP_KEY, IDP_TLS_OVH_APP_SECRET, IDP_TLS_OVH_CONSUMER_KEY | none | Required when the provider is ovh |
The credentials of the chosen provider must not be empty, or the server does not start.
Steps: Set up TLS with DNS.
Nodes and regions
| Variable | Default | Notes |
|---|---|---|
IDP_NODE_PEERS_FILE | /etc/paas/peers | The list of nodes; see Peers file |
IDP_NODE_REGION | local | This node’s region, used only when there is no peers file |
IDP_NODE_LANDING | true | Whether this node is the landing node, used only when there is no peers file |
PAAS_APP, PAAS_NODE | empty | The node’s identity in the peers file |
Registration
| Variable | Default | Range | Notes |
|---|---|---|---|
IDP_REGISTRATION_POW_MEMORY_MIB | 32 | 8 to 4096 | Memory of the proof of work the browser solves when an organization is registered (Argon2id) |
IDP_REGISTRATION_POW_ZERO_BITS | 10 | 1 to 32 | Difficulty |
IDP_REGISTRATION_POW_TTL | 20m | 5m to 20m | How long a challenge is valid, in whole minutes |
Request ids
| Variable | Default | Notes |
|---|---|---|
IDP_ACCESS_RAY_ID_PREFIX | rid- | Prefix of the id given to each request in the access log |
IDP_ACCESS_RAY_ID_HASH_LENGTH | 6 | |
IDP_ACCESS_RAY_ID_RANDOM_LENGTH | 10 | The whole id must fit in 64 characters |
Password manager storage
| Variable | Default | Notes |
|---|---|---|
IDP_VAULT_BLOBS_BLOB_LIMIT | about 8 MiB | Largest encrypted file the server stores (an 8 MiB attachment plus its encryption overhead). Bytes, or with B, KB, MB, GB. 1 KB to 256 MB. The browser refuses attachments over 8 MiB whatever this is, so a higher value does not allow larger attachments. |
IDP_VAULT_BLOBS_ORG_QUOTA | 1GB | Attachment storage per organization |
IDP_VAULT_BLOBS_UNREFERENCED_GRACE | P1D | How long an attachment nobody refers to is kept: P1D, PT12H, or a number with ms, s, m, h, d; at most 30 days |
These three are read when first needed, not at start: a wrong value makes attachment requests fail, not the start.
Fixed values
| Item | Value |
|---|---|
| HTTPS port | 8443 |
| ACME account contact | Set in the code |
| Password hashing | bcrypt, cost 12 |
| Backup code hashing | scrypt, N = 2^14 |
| Open organizations kept in memory | 256, each closed after 30 minutes unused |
Ports
| Port | Protocol | Use |
|---|---|---|
8080 (SERVER_PORT) | HTTP | Health check /ready and the internal paths between nodes (/internal/*). Not meant to be published. |
| 8443 | HTTPS | Everything else. Published as 443. |
There is no listener on port 80.
| Item | Value |
|---|---|
| TLS versions | 1.2 and 1.3 |
| ALPN | h2, http/1.1 |
| Client certificates | Not supported |
| HSTS | max-age=31536000; includeSubDomains, on the HTTPS listener |
| TLS handshake timeout | 10 seconds |
| Time for the first byte and the request head | 20 seconds; also closes idle keep-alive connections |
| HTTP/2 ping | Every 20 seconds; the connection closes after 20 more seconds of silence |
| Graceful shutdown | 30 seconds |
GET /ready on port 8080:
| Profile | Answer |
|---|---|
none, local | 200 with {"ready":true} |
qa, prod | 200 once the certificate is loaded or while the first certificate is being requested, 503 once that request has failed. The body has ready, nodeCertificate (the certificate is loaded), issuing (a request is in progress) and, after a failure, error. |
Certificates
| Item | Value |
|---|---|
| Names | *.<landing host> on every node; also the bare landing host on the landing node |
| Key | ECDSA P-256, stored encrypted under the master key |
| Challenge record | TXT _acme-challenge.<landing host>, TTL 60 seconds |
| DNS check | The zone’s own nameservers are asked until they serve the record: 24 tries, 5 seconds apart, 3-second DNS timeout. Then IDP_TLS_DNS_SETTLE_DELAY passes before the challenge is answered. |
| Renewal | When less than 30 days are left; checked every 6 hours |
| Retry after a failure | After 5 minutes, then at doubling intervals up to 1 hour |
| Storage | node.sqlite on the data volume, so a restart does not request a new certificate |
| Custom domains | One certificate per organization’s custom domain, requested and renewed the same way. The organization’s admin points _acme-challenge.<their domain> as a CNAME to <slug>._acme-delegation.<landing host>, and Sovrain answers the challenge there, in your zone. |
Data directory
| Path | Content |
|---|---|
orgs/<slug>.db | One SQLite database per organization |
orgs/<slug>.db.blobs/ | The organization’s password manager attachments (encrypted) |
orgs/<slug>.db.pre-import | The database before the last import (one generation) |
orgs/<slug>.scim, orgs/<slug>.delegations | Empty markers: the organization uses provisioning or delegation |
node.sqlite | Custom-domain index, certificates, ACME account, reserved organization addresses |
mek-fingerprint | Ties the directory to IDP_MEK |
user-deletions.log | One line for each account deleted by its owner (mode 0600) |
The SQLite files are not encrypted. Secrets inside them are: SAML and OpenID Connect private keys, SCIM tokens,
authenticator secrets, the import key and TLS keys are encrypted under keys derived from IDP_MEK.
Steps: Back up the data volume, Restore a node from a backup.
Schema updates
| Item | Behavior |
|---|---|
node.sqlite | Updated at start, before the node serves anything. If the update fails, the node does not start. |
| Organization databases | Each is updated the first time it is opened after the start, by a request or a background job. One whose update fails cannot be opened; the others keep working. |
| Changed history | A database that records a schema change this version has with different content is refused. |
| Lock | One process updates a database at a time. Another waits up to 30 seconds, then fails with the changelog lock stayed taken for 30 s, held by …. |
| Going back | Schema changes are not undone. An older version is not made to run on a database a newer version has changed. |
Steps: Upgrade Sovrain.
Peers file
Each line describes one node:
<app> <node> <mesh-ip> <tags>
| Rule | Detail |
|---|---|
| Region tag | Exactly one region:<name> per node; <name> matches [a-z][a-z0-9]{0,15} |
| Landing tag | At most one node carries landing; a node refuses to start when two do. With none, no node offers registration. |
| Hosts | Landing node: <base>. Region node: <region>.<base>. Organization: <slug>.<base>, whatever its region. |
| Registration | Only on the landing node. It reserves the address, creates <slug>.<base> CNAME <region>.<base> (TTL 300 seconds, waits up to 90 seconds for it to resolve) and asks the region node to create the organization. |
| Internal paths | /internal/* answer 404 to any address that is not a known node |
| Capacity | One node per region; no failover between nodes. Why: About running Sovrain yourself |
Steps: Add a region.