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_TLS_CERT / _KEY | unset (plain) | the S3 API over TLS: its certificate chain and private key (PEM), both or neither; TLS 1.2 and 1.3 only |
TESSARIDB_S3_REGION | us-east-1 | the region requests must be signed for; its buckets' objects are kept in the database <database>_<region>, and a request for another region's bucket is answered 301 PermanentRedirect |
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 namespace (DEFINE USER s3 ON NAMESPACE s3 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_ADVERTISE | unset | the URL (http(s)://host[:port]) this node's S3 surface is reached at, recorded for its region as where replicas are sent |
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_KEYS_PASSPHRASE | unset (sealed until an operator unseals in the console) | the passphrase that unseals the keys objects asked for with x-amz-server-side-encryption: AES256 or aws:kms are sealed under, at least 15 characters; the unsealed keys live only in this process's memory |
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, and as many temporary-credential requests on the S3 listener; 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 |
TESSARIDB_S3_METRICS_LISTEN | unset (no metrics) | where the node serves GET /metrics in Prometheus text: requests by operation, status and error code, their duration by size class, requests shed under load, authentication refusals by reason, policy denials, the heal and replication backlogs and the cluster's members with those answering a probe (read at the scrape; s3_collect_up says whether each could be), and access-log records written, dropped and failed |
TESSARIDB_S3_AUDIT | on | on records every S3 request in the region's s3_access_log topic (kept 30 days) under its request id: operation, bucket, key, signing access key, status, error code, bytes, duration and client address — never a secret or a signature. A full queue drops the record and counts it, never the request; off records nothing |
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.