Files
skyg-linux-tracker/docs/configuration.md
T
2026-10-21 00:12:33 -04:00

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:

  1. Built-in defaults
  2. Config file: --config <file>, or SKYG_CONFIG, or /etc/skyg-linux-tracker.toml if it exists
  3. Environment variables: SKYG_ plus the key path in capitals, with __ between levels
  4. 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 = false with a non-loopback server.bind;
  • server.port = 0, any limits.* = 0, or otel.metrics_interval_secs = 0;
  • server.tls.enabled = true without both cert_file and key_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 an EnvironmentFile= (NixOS: environmentFile).
  • TLS key: a file readable only by the service user, or a systemd credential (NixOS: tls.keyFile).
  • Peer tokens: token_file paths only; the file holds the token (NixOS: peers.peers.<name>.tokenFile).
  • API tokens are never in the config; they live hashed in the database.