Configuration

Ferro Sentry reads configuration from environment variables or a config.toml file. Environment variables always take priority over the config file.

Environment variables

VariableRequiredDefaultDescription
FERROSENTRY_TOKENYes—Agent authentication token
FERROSENTRY_ENDPOINTNo127.0.0.1:4317Local Nexus Agent gRPC endpoint
FERROSENTRY_AUDIT_INTERVALNo300Posture audit interval in seconds
FERROSENTRY_LOG_LEVELNoinfoLog verbosity: trace, debug, info, warn, error
FERROSENTRY_BUFFER_PATHNo/var/lib/ferrosentry/bufferLocal offline buffer directory
FERROSENTRY_RULES_DIRNo/etc/ferrosentry/rulesCustom YAML rules directory

Config file

Alternatively, place a config.toml file at one of the following locations:

  • /etc/ferrosentry/config.toml (Linux, system-wide)
  • ~/.config/ferrosentry/config.toml (Linux, user-level)
  • C:\ProgramData\ferro-sentry\config.toml (Windows)
config.toml
# config.toml
token          = "fs_live_xxxxxxxxxxxx"
endpoint       = "127.0.0.1:4317"
audit_interval = 300
log_level      = "info"
buffer_path    = "/var/lib/ferrosentry/buffer"
Never commit config.tomlto version control — it contains your security token. The installer's default .gitignore excludes it, but double-check before pushing to a public repository.

Priority order

Configuration is resolved in this order (highest priority first):

  1. Environment variables
  2. config.toml file
  3. Built-in defaults

Setting via systemd

To set environment variables without modifying the config file, use a systemd override:

systemd override
# Create override directory
mkdir -p /etc/systemd/system/ferrosentry.service.d

# Create override file
cat > /etc/systemd/system/ferrosentry.service.d/override.conf << EOF
[Service]
Environment="FERROSENTRY_LOG_LEVEL=debug"
Environment="FERROSENTRY_AUDIT_INTERVAL=60"
EOF

systemctl daemon-reload && systemctl restart ferrosentry