6.4 KiB
Configuration
Every setting has a default, so slinuxm serve runs with no config file at all. config.example.toml lists every key with its default and its environment variable; this page explains how the layers combine and what each section does.
Where settings come from
Four layers. A later layer wins over an earlier one, key by key:
- Built-in defaults
- Config file:
--config <file>, orSKYG_CONFIG, or/etc/skyg-linux-tracker.tomlif it exists - Environment variables:
SKYG_plus the key path in capitals, with__between levels - CLI flags:
--bind,--port,--auth-enabled,--db-path,--docker-socket,--journal-namespace,--otel-enabled,--otel-endpoint
So server.port can be set as port = 2000 under [server], as SKYG_SERVER__PORT=2000, or as --port 2000.
| Key | Environment variable |
|---|---|
server.port |
SKYG_SERVER__PORT |
server.tls.cert_file |
SKYG_SERVER__TLS__CERT_FILE |
otel.headers.authorization |
SKYG_OTEL__HEADERS__AUTHORIZATION |
otel.metrics.units (a list) |
SKYG_OTEL__METRICS__UNITS='["nginx.service"]' |
To see the result of all four layers:
slinuxm --print-config # secrets such as OTel headers are redacted
slinuxm --print-config --config ./test.toml
The CLI commands (token, peer) read the same layers, which is why they find the service's database without extra flags when run on the same host.
Sections
[server]: where it listens
| Key | Default | Meaning |
|---|---|---|
bind |
"127.0.0.1" |
Listen address. Use "0.0.0.0" (IPv4) or "::" (dual stack) to accept remote clients. |
port |
1984 |
Listen port. |
allowed_hosts |
[] |
Extra Host header values accepted on /mcp (loopback names and bind are always accepted), e.g. ["monitor.lan:1984"]. |
allowed_origins |
[] |
Extra browser Origin values accepted on /mcp, with scheme, e.g. ["https://app.example.com"]. |
/mcp checks Host and Origin to block DNS-rebinding attacks from browsers. If clients reach the server under a name, list that name in allowed_hosts.
[server.tls]: HTTPS
| Key | Default | Meaning |
|---|---|---|
enabled |
false |
Serve HTTPS only on the port. |
cert_file |
"" |
PEM certificate chain, leaf first. |
key_file |
"" |
PEM private key (PKCS#8, PKCS#1 or SEC1). |
Both files are re-read on SIGHUP. Details, self-signed example and rotation: tls.md.
[auth]: tokens
| Key | Default | Meaning |
|---|---|---|
enabled |
true |
Require a bearer token on /api/v1 and /mcp. false is allowed on a loopback bind only. |
db_path |
"/var/lib/skyg-linux-tracker/db.sqlite" |
The token database. Under the example systemd unit it must stay under /var/lib/skyg-linux-tracker. |
[sources]: what it reads
| Key | Default | Meaning |
|---|---|---|
docker_socket |
"/var/run/docker.sock" |
Docker Engine API socket. Point it at a read-only socket proxy for a hardened setup. |
journal_namespace |
"" |
A journald namespace to read; empty means the default journal. |
[limits]: request bounds
| Key | Default | Meaning |
|---|---|---|
max_lines |
1000 |
Most journal lines one request can return. |
max_tail |
1000 |
Most container log lines one request can return. |
max_follow_secs |
60 |
Longest bounded follow (the MCP tail_journal tool, and proxied follows). |
[otel]: OpenTelemetry export
| Key | Default | Meaning |
|---|---|---|
enabled |
false |
Master switch for OTLP export. |
endpoint |
"http://localhost:4317" |
Collector address. Port 4317 for gRPC, 4318 for HTTP. |
protocol |
"grpc" |
"grpc" or "http/protobuf". |
service_name |
"skyg-linux-tracker" |
The service.name resource attribute. |
export_unit_metrics |
true |
Export unit and container status as gauges (when enabled). |
export_logs |
false |
Forward journal and container logs as OTel logs. |
metrics_interval_secs |
30 |
How often the metrics are polled. |
[otel.headers] |
empty | Extra OTLP headers, e.g. authorization. Put secret values in the environment, not the file. |
[otel.logs] journal_units |
[] |
Units whose logs are exported; empty means all. |
[otel.logs] docker_containers |
[] |
Containers whose logs are exported; empty means all. |
[otel.metrics] units |
[] |
Glob allowlist of units; empty means *.service and *.timer only. |
[otel.metrics] containers |
[] |
Glob allowlist of containers; empty means all. |
What is exported: operations.md.
[peers]: consolidator mode
Off by default. When on, this instance health-checks other slinuxm instances declared as [[peers.peer]] entries and proxies read-only requests to them. All keys, validation rules and the credential model: consolidator.md.
Validation
Every command, --print-config included, refuses a configuration that is unsafe or cannot work, with a message naming the key:
auth.enabled = falsewith a non-loopbackserver.bind;server.port = 0, anylimits.*= 0, orotel.metrics_interval_secs = 0;server.tls.enabled = truewithout bothcert_fileandkey_file;- an invalid
[peers]section (see consolidator.md).
serve additionally refuses to start when the TLS files do not load or do not match, or when an enabled peer's token file is missing or readable by others.
A non-loopback bind without TLS is allowed but logs a warning: bearer tokens then travel in cleartext.
What applies without a restart
| Change | Applied by |
|---|---|
| New, revoked or rotated tokens | immediately; no signal needed |
| TLS certificate and key contents | SIGHUP (systemctl reload skyg-linux-tracker) |
[peers] entries, intervals, timeouts, fail_threshold |
SIGHUP |
| Everything else | restart |
Secrets
Keep secrets out of the config file, which is usually world-readable (/etc) or in the Nix store:
- OTel headers:
SKYG_OTEL__HEADERS__<NAME>in anEnvironmentFile=(NixOS:environmentFile). - TLS key: a file readable only by the service user, or a systemd credential (NixOS:
tls.keyFile). - Peer tokens:
token_filepaths only; the file holds the token (NixOS:peers.peers.<name>.tokenFile). - API tokens are never in the config; they live hashed in the database.