Log level and diagnostics
Changing the level at runtime
[log]
level = "debug"
Saving the file is enough: the level changes within moments, without a
restart, as for the users and roles files. On Unix, kill -HUP applies the
edit without waiting for the file watcher.
level | Effect |
|---|---|
trace, debug | more detail, for CraftFileGate only; dependencies (russh, hyper, the AWS SDK) stay at info |
info (default) | normal operation |
warn, error, off | fewer lines, for the whole process, dependencies included |
level takes a single value, not a directive string. The audit trail does
not depend on it: it stays at info.
In [log], only level, audit and the refusal_summary_* keys are
reloaded at runtime; the rest waits for a restart (see
Hot reload).
Who decides the level
| Source | Priority | At runtime |
|---|---|---|
RUST_LOG | the highest: replaces the whole filter | no: the level stays its own for the life of the process |
CRAFT_FILE_GATE_LOG_LEVEL | wins over the file | the file is no longer followed while it is set |
[log] level | the default | yes |
The first line of the log gives the filter in force and its source:
INFO log filter in force filter="info,craft_file_gate=info,audit=info,opentelemetry_sdk=off" source="config [log] level"
RUST_LOG, to go further
RUST_LOG gives the detail of a dependency, for example the russh trace.
It replaces the whole string, including the audit=info that the server
always adds: write it yourself.
RUST_LOG=warn,russh=trace,audit=info
| Directive | Target |
|---|---|
craft_file_gate=debug | the server (the crate name, with _) |
audit=info | the audit trail; audit=warn keeps only its refusals and errors |
russh=trace | the SSH protocol |
Understanding an authentication refusal
The audit line of a refused password does not say why: telling “unknown
user” from “wrong password” would reveal which accounts exist, and logs
travel far. The detail is at the debug level, for the operator only.
DEBUG local password authentication rejected username=alice reason="password does not match the stored hash"
DEBUG local password authentication rejected username=bob reason="no such user in the users file"
debug also gives the loaded accounts (local user store contents, field
usernames); info gives only their count (local user store loaded).
To check a hash without a server:
echo -n "mot-de-passe" | craft-file-gate verify-password '$argon2id$v=19$...'
Go back to info once the diagnosis is done. Other refusals carry their
cause in reason: Troubleshooting.
A runtime change writes INFO log level reloaded (level, source,
filter). Under level = "warn" or more severe, these announcements go to
stderr, prefixed craft-file-gate:: the announcement of a filter is never
silenced by it.