Configuration
Every setting the server reads, its default and what it means — the server takes its whole configuration from the environment.
The server reads its configuration from the environment and nothing else. A required setting that is missing stops it at start, with the name of the setting in the message; there is no file to forget and no default credential.
The table is the server's own, copied from its repository rather than retold.
| Variable | Default | Meaning |
|---|---|---|
TESSARIDB_S3_ROOT_ACCESS_KEY | — (required) | the root credential's access key |
TESSARIDB_S3_ROOT_SECRET_KEY | — (required, ≥ 16 bytes) | the root credential's secret |
TESSARIDB_S3_LISTEN | 127.0.0.1:9100 | the address the S3 API listens on |
TESSARIDB_S3_REGION | us-east-1 | the region requests must be signed for |
TESSARIDB_S3_DOMAINS | empty | comma-separated endpoint domains for <bucket>.<domain> addressing; path-style always works |
TESSARIDB_S3_MAX_INFLIGHT | 1024 | requests served at once before new ones get 503 SlowDown |
TESSARIDB_S3_SHUTDOWN_GRACE_SECS | 30 | how long in-flight requests get after SIGTERM |
TESSARIDB_S3_META_ADDRESS | — (required) | the TessariDB nodes holding the metadata, host:port of each wire surface, comma-separated; a node that does not answer within 5 s is passed over for the next |
TESSARIDB_S3_META_REPLICATION | none for one node; required for several | copies the metadata cluster keeps of the namespace: a number, or none — a cluster refuses a namespace whose replication was never stated |
TESSARIDB_S3_META_USER / _PASSWORD | — (required) | the TessariDB user the server signs in as — its own account, an editor of its one database (DEFINE USER s3 ON s3.meta ROLE editor), never the owner |
TESSARIDB_S3_META_NAMESPACE / _DATABASE | s3 / meta | where the metadata lives; the database is created on start-up, the namespace only by an account allowed to (the operator declares it with the server's account) |
TESSARIDB_S3_META_CA | unset | a PEM certificate authority to verify the node's TLS against; unset speaks in the clear |
TESSARIDB_S3_META_MAX_CONNECTIONS | 32 | connections to the metadata store; at most 4 new ones sign in at once, because a node verifies at most 24 passwords at once for all its clients — a sign-in it still declines answers 503 SlowDown |
TESSARIDB_S3_META_STATEMENT_TIMEOUT_SECS | 30 | how long a metadata statement may wait for its answer; past it the request answers 503 and a write's data stays queued, because the statement may have committed |
TESSARIDB_S3_DATA_DIR | required | where every object's bytes are stored (<dir>/s3data/…); unset, the node refuses to start |
TESSARIDB_S3_RECLAIM_GRACE_SECS | 86400 | how long a replaced, deleted or abandoned data file is kept before the reclaimer removes it; recorded in the metadata store at start and applied to files queued from then on |
TESSARIDB_S3_RECLAIM_INTERVAL_SECS | 300 | time between reclamation passes |
TESSARIDB_S3_USAGE_INTERVAL_SECS | 60 | time between passes measuring each bucket's objects and bytes; every node runs one and one member measures per pass |
TESSARIDB_S3_MEDIA_WORKERS | 2 | image renditions this node makes at once, 0 to 64; 0 makes none here while other nodes still take the queue |
TESSARIDB_S3_FFMPEG | unset | the ffmpeg (with libx264, libvpx-vp9 and libopus) this node runs for video renditions and posters; unset, the node leaves those tasks to a node that has one. Originals are copied to the system temp directory while they are encoded. The published image carries no ffmpeg |
TESSARIDB_S3_UPLOAD_MAX_AGE_SECS | 604800 | how long a multipart upload may stay open (from its initiation) before the reaper aborts it; the reaper runs on the reclamation interval |
TESSARIDB_S3_ERASURE | unset (a node on its own) | the erasure code k+m this node's cluster writes objects with (k, m ≥ 1, k + m ≤ 16); setting it makes the node a cluster member and requires the four settings below and TESSARIDB_S3_DATA_DIR |
TESSARIDB_S3_NODE_ID | — | this node's name in the cluster: 1–63 lowercase letters, digits and inner hyphens |
TESSARIDB_S3_ZONE | unset (the node is a failure domain of its own) | the failure domain the node is in — a zone, a rack, a room: 1–32 lowercase letters, digits and inner hyphens, registered with the node. A layout never puts more of one object's shards in one zone than its parity can lose, so losing a whole zone leaves every object readable; the first layout takes the registered nodes in id order, passing over a node whose zone already holds m shards |
TESSARIDB_S3_INTERNAL_LISTEN | — | where the internal shard surface listens: the other nodes store, read and remove this node's shards there. A request is served only when the certificate it presents is issued for the node it names and that node is an admitted member; a removal reaches every node within 5 seconds |
TESSARIDB_S3_INTERNAL_ADVERTISE | — | host:port the other nodes reach that surface at; registered in the metadata on start-up |
TESSARIDB_S3_CLUSTER_SECRET | — | key objects are placed on the erasure sets by, at least 32 bytes, the same on every node |
TESSARIDB_S3_INTERNAL_TLS_CERT / _KEY / _CA | — | the internal surface over mutual TLS, required: this node's certificate chain (PEM, issued for <node id>.peer.tessari-s3), its private key, and the cluster's certificate authority. A node whose certificate is issued for another name does not start, and a call reaches another node only when its certificate is issued for the node dialled; TLS 1.2 and 1.3 only |
TESSARIDB_S3_FOUNDING_MEMBERS | unset | node ids, comma-separated, admitted at start where they have no membership record yet — how a new cluster begins; a removed node is never admitted again |
TESSARIDB_S3_JOIN_TOKEN | unset | a one-time token issued in the console for this node; offered at start, it binds this node's certificate. A node that is not an admitted member does not start |
TESSARIDB_S3_HEAL_INTERVAL_SECS | 60 | time between healing passes on a cluster member: each rewrites the missing or damaged shards of objects listed for healing |
TESSARIDB_S3_MOVE_BYTES_PER_SEC | 33554432 | bytes a second a cluster member copies when it moves objects onto a newly applied layout; 0 pauses moving |
TESSARIDB_S3_IAM_KEY | unset (no user keys) | 64 hexadecimal digits: the root from which each space's key for sealing users' access-key secrets is derived. Without it no key can be issued or resolved, so only the root credential signs in. Keep it like the root secret; a node that loses it can open no user's key |
TESSARIDB_S3_NOTIFY_TARGETS | unset (only the database's own topic) | Alternative destinations bucket notifications may name, separated by ;: <id>=kafka:<host:port>[,<host:port>…]/<topic> (the topic must exist) or <id>=webhook:<http(s) URL>. A bucket's configuration names one only by arn:tessaridb:sqs:::<id>, never by an address, so a bucket administrator cannot point the server at a host of their choosing; tessaridb is the built-in topic's id and cannot be declared |
TESSARIDB_S3_CONSOLE_LISTEN | unset (no console) | where the operator console listens, on its own address apart from the S3 API. Signing in takes an access key and its secret — the root key, or a key issued to a user — and gives a one-hour session cookie (HttpOnly, SameSite=Strict); every other console route needs it |
TESSARIDB_S3_CONSOLE_TLS_CERT / _KEY | unset (plain) | the console over TLS: its certificate chain and private key (PEM), both or neither. Without them a secret crosses the network in the clear when an operator signs in, so keep the console on a private address; the node says so when it starts |
TESSARIDB_S3_CONSOLE_SIGN_INS_PER_MINUTE | 10 | sign-in attempts accepted per client address per minute; the limit is checked before the credential |
TESSARIDB_S3_CONSOLE_REQUESTS_PER_MINUTE | 600 | console requests accepted per signed-in key per minute |
TESSARIDB_S3_CONSOLE_OIDC_ISSUER | unset (keys only) | an OpenID Connect provider people sign in to the console through, by its issuer URL (https, or http to this machine only). Its four companions are then required or defaulted; set without the issuer they are refused |
TESSARIDB_S3_CONSOLE_OIDC_CLIENT_ID / _CLIENT_SECRET | — | the console's client at the provider; the secret stays on the server (client_secret_basic) |
TESSARIDB_S3_CONSOLE_OIDC_REDIRECT_URI | — | the callback registered at the provider, exactly: the console's address followed by /api/v1/auth/oidc/callback |
TESSARIDB_S3_CONSOLE_OIDC_MFA_AMR | mfa | comma-separated amr values that prove a second factor; a sign-in whose ID token carries none of them is refused |
TESSARIDB_S3_CONSOLE_BREAK_GLASS_WEBHOOK | unset (no alert) | where a root sign-in to the console is announced as it happens: one JSON POST (event, key_id, reason, client, expires), over https or http to this machine. Needs TESSARIDB_S3_CONSOLE_OIDC_ISSUER |
TESSARIDB_S3_CONSOLE_KEY_SIGN_IN | all | which access keys open a console session beside an identity provider: all — any live key; root — people sign in through the provider only, a user's key is refused with key_sign_in_disabled (a session it opened earlier ends at its next request) and the root key stays as the emergency path. The S3 API is not affected. Needs TESSARIDB_S3_CONSOLE_OIDC_ISSUER |
What to set first
- The root key:
TESSARIDB_S3_ROOT_ACCESS_KEYandTESSARIDB_S3_ROOT_SECRET_KEY. It signs in to the S3 API and, beside an identity provider, is the console's break-glass path. - The metadata store:
TESSARIDB_S3_META_ADDRESS,TESSARIDB_S3_META_USERandTESSARIDB_S3_META_PASSWORD— the server's own account, an editor of one database, never the owner. - Where bytes go:
TESSARIDB_S3_DATA_DIR. - User keys:
TESSARIDB_S3_IAM_KEY. Without it no access key can be issued and only the root credential signs in.