Configuration¶

Mini S3 is configured through a main TOML file, by default /etc/minis3/minis3.toml. Every key can also be set through an environment variable; environment variables always take precedence over the config file.

Command line¶

Flag	Short	Description
--config <path>	-c	Path to the main config file (default /etc/minis3/minis3.toml)
--daemon	-d	Send the server into the background after startup
--log-level <level>	-l	Minimum log level, overriding the config file
--help	-h	Display a usage summary

general.include¶

An array of filesystem glob patterns (resolved relative to the main config file's directory, unless absolute) naming additional TOML files to merge in. Matches are sorted lexicographically, and their raw file contents are appended after the main file's contents before the whole thing is parsed as one TOML document. This means [[bucket]] (and [[bucket.authentication]]) entries across files naturally accumulate; redefining a scalar key (like general.loglevel) in more than one file is a TOML parse error, the same as if you had pasted the files together by hand.

Env var: MINIS3_GENERAL_INCLUDE_0, MINIS3_GENERAL_INCLUDE_1, ... (a contiguous run starting at index 0; if present, replaces the file's list entirely).

[general]¶

Key	Env var	Description
general.loglevel	MINIS3_GENERAL_LOGLEVEL	Minimum log level: trace, debug, info, warn, error. Default info.
general.logfile	MINIS3_GENERAL_LOGFILE	Path to write logs to. If unset, logs go to stderr.

[metrics]¶

Key	Env var	Description
metrics.enabled	MINIS3_METRICS_ENABLED	Enable the Prometheus /metrics endpoint. Default off.
metrics.port	MINIS3_METRICS_PORT	Port for the metrics endpoint. Mandatory when enabled.

See Metrics for what is exported.

[network]¶

Key	Env var	Description
network.listen	MINIS3_NETWORK_LISTEN_0, _1, ...	[address]:[port] to listen on; port defaults to 443 (TLS enabled) or 80 (plain HTTP). At least one entry is required.
network.tls.certificate	MINIS3_NETWORK_TLS_CERTIFICATE	Path to a PEM file with the full certificate chain. Optional — see below.
network.tls.key	MINIS3_NETWORK_TLS_KEY	Path to the PEM certificate key. Optional — see below.

By default Mini S3 terminates TLS itself: set both network.tls.certificate and network.tls.key to serve HTTPS. Leaving both unset switches Mini S3 to plain HTTP, for running behind a TLS-terminating reverse proxy — see Deployment & Signals for why you'd want that and how to set it up. Setting only one of the two is a configuration error.

[[bucket]]¶

An array of tables, one per bucket.

Key	Env var	Description
name	MINIS3_BUCKET_<n>_NAME	Bucket name (mandatory).
path	MINIS3_BUCKET_<n>_PATH	Filesystem directory backing the bucket (mandatory). Created on startup if it doesn't exist.
webaccess	MINIS3_BUCKET_<n>_WEBACCESS	Allow unauthenticated GET/HEAD on objects in this bucket. Default off.

<n> is a zero-based index; indices must be contiguous starting from 0 (matching however many [[bucket]] entries the config file already has, if any — environment variables can add buckets beyond the ones in the file, or override fields of file-defined buckets at the same index).

[[bucket.authentication]]¶

Nested under each bucket; at least one entry is required for a bucket to be reachable at all.

Key	Env var	Description
mode	MINIS3_BUCKET_<n>_AUTHENTICATION_<m>_MODE	One of read-only, read-write, public (mandatory).
access_key_id	MINIS3_BUCKET_<n>_AUTHENTICATION_<m>_ACCESS_KEY_ID	Mandatory for read-only/read-write.
secret_access_key	MINIS3_BUCKET_<n>_AUTHENTICATION_<m>_SECRET_ACCESS_KEY	Mandatory for read-only/read-write.

public grants anonymous read access without any credential — equivalent in effect to webaccess = true, but expressed as an explicit auth entry instead of the bucket-level toggle.

Access key IDs must be unique across the entire configuration, not just within a bucket — a SigV4 request only carries an access key ID, not a bucket name, so Mini S3 needs a single global mapping from key to secret (this also makes ListBuckets well-defined: it returns every bucket the caller's key can access).

Example¶

See examples/minis3.toml for a complete example.

Signals¶

• SIGHUP: re-reads the configuration (buckets, credentials, log level, TLS certificate/key) without dropping connections; in-flight requests finish against the old configuration. The log file, if any, is closed and reopened, enabling external log rotation. Changing network.listen or metrics.port/metrics.enabled requires a full restart — these are logged as a warning if changed and otherwise ignored until restart.
• SIGTERM / SIGINT: graceful shutdown, letting in-flight requests finish (up to a 30 second grace period).