Checking a configuration
config check applies the startup validation to a file, without starting:
no port opened, no file created, no secret read, no network reached.
craft-file-gate config check /etc/craft-file-gate/config.toml
craft-file-gate config check config.toml --format json
craft-file-gate config schema > config.schema.json
craft-file-gate config explain sftp.ban.max_failures
craft-file-gate config effective /etc/craft-file-gate/config.toml
config check
| Option | Effect |
|---|---|
<file> | the configuration; its users_file, roles_file and trust files are read and judged as at startup |
--format text | default: one line per finding, <level> [<key>] <message> (see <link>) |
--format json | {"valid": ..., "findings": [{"level", "key", "message", "rule", "doc"}]} |
| Field | Meaning |
|---|---|
level | error: startup would refuse; warn: a startup WARN; info: a startup line, or a step left to startup, not checked offline: ... |
key | the key, written as in the reference (roles[].mounts[].backend) |
rule | the spec rule cited by the message |
doc | the key’s section in this guide |
| Exit | Meaning |
|---|---|
0 | no error, possibly some warn |
1 | an error, the first one, as at startup |
2 | unreadable file, or malformed command |
Environment variables count as at startup. A secret (host key, _FILE,
password_file, variable) is judged present, with its owner and mode; its
content is not read. Left to startup, reported as info: the JWKS, the
Kubernetes API, a storage probe, the upstream SFTP, the log files, the OTLP
exporter.
A CI job or an AI assistant writes the configuration, runs config check --format json, fixes each error with the help of key and doc, and
starts again until exit 0.
config schema
The JSON schema (draft 2020-12) of config.toml, users_file and
roles_file: types, defaults, bounds, allowed values, description of each
key, x-reload (hot reload), x-env (variables), x-doc (link). An
unknown key is refused; none is required.
A first line #:schema ./config.schema.json hands it to Taplo (Even
Better TOML): completion and underlining in the editor, as in
config.example.toml. The schema ships with each release and lives in the
images at /usr/share/craft-file-gate/config.schema.json;
config schema > config.schema.json writes it next to the configuration.
config explain <key>
One key: type, default, allowed values, hot reload (⟳), variables, effect,
spec, link to its section. --format json for a machine; an unknown key
exits with 2 and the closest ones.
config effective <file>
The configuration applied: the file, its linked files, the environment
variables, the defaults of the reference;
--format toml (default) or json. Every secret and every password hash
shows as ***, as does the identifier that goes with a secret
(access_key_id) and any value of a key named like a secret or under
headers. Offline like config check, which runs first: a refused
configuration exits with 1 and its finding.