The configuration file
One file, named at launch
craft-file-gate --config /etc/craft-file-gate/config.toml
-c is the short form. Only [auth] is required, with at least one
role and one door: [sftp], or [api] with [admin]. All the keys: the
reference.
| Section | What it sets | Page |
|---|---|---|
[server] | what all doors share: shutdown, sessions per user, atomic writes, probe port | Shutdown, Uploads, Admin API and console |
[sftp] | the SSH door, its algorithms, its bans | SFTP door, Bans |
[auth] | who gets in, and under which name | Authentication |
[[users]], [[roles]] | local accounts, roles and their mounts | Users, roles and mounts |
[[backends]] | the storages | Backends |
[uploads], [tcp_keepalive] | the timeouts | Timeouts, Uploads |
[log], [telemetry] | logs, audit trail, traces | Logs, Telemetry |
[admin], [api] | the admin console, the admin API, the file API, their bans | Admin API and console, Bans |
[reload] | hot reload | Hot reload |
[security] | how trusted files are judged | Trusted files and TLS |
Splitting: users_file and roles_file
Users, roles and backends can live in separate files. These files are
reloaded at runtime; config.toml almost not.
[auth]
users_file = "users.toml" # the [[users]]
roles_file = "roles.toml" # the [[roles]] and the [[backends]]
| Where to write | Effect |
|---|---|
[[users]], [[roles]], [[backends]] at the root of config.toml | read at startup |
the same under [auth] ([[auth.users]], …) | same; the root wins if both exist |
auth.users_file, auth.roles_file | read again on every change to the file |
| none of these | users.toml and roles.toml next to config.toml are used if they exist |
users_file and inline [[users]] do not add up: when users_file is
given, only that file is read.
Relative paths
A relative path to a file the server reads (host_keys, users_file,
roles_file, public_key_file, the persist_file keys, the pair and the
directory of [admin.tls]) starts from the directory of config.toml,
not from the launch directory: a configuration and its files travel
together, including in a container. The other paths (root of a local
backend, log.dir, the files of a WebHDFS backend) start from the launch
directory: write them as absolute paths.
The environment
A CRAFT_FILE_GATE_* variable replaces the key it overrides, after the
file is read, at startup and on every reload: the list is in
Environment variables. For a secret,
prefer the _FILE form: a file read once, judged as a
trusted file.
The binary’s tools
hash-password and verify-password read neither the configuration nor
the secrets; healthcheck reads the listeners of --config, nothing else.
| Command | Effect |
|---|---|
craft-file-gate hash-password | reads a password on stdin, writes its argon2id hash; --user <name> writes a [[users]] block; --profile picks the cost (see Authentication) |
craft-file-gate verify-password '<hash>' | reads a password on stdin; exits 0 if it produces this hash, 1 otherwise, 2 if the hash is unreadable |
craft-file-gate config check <file>, config schema | check a configuration without starting, write its JSON schema: Checking a configuration |
craft-file-gate healthcheck | queries /livez where the configuration serves it: probes_listen (HTTP), else control_listen, else admin.listen (HTTPS under [admin.tls]), read from --config (default /config/config.toml) and the environment, a 0.0.0.0 address queried on loopback; without that file, http://localhost:8080/livez; --url for another address; exits 0 on 200; for an image’s HEALTHCHECK |
What you will see
| When | Line |
|---|---|
| a declared file is read | INFO auth source loaded, fields kind (roles, users) and path |
| an undeclared file is found next to it | INFO found next to the config and used; declare it explicitly to pin it |
| a variable replaces a key | INFO config override from env, fields env and value; (value hidden) for a secret |