# Configuration Every setting has a default, so `slinuxm serve` runs with no config file at all. [`config.example.toml`](../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 `, 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: ```sh 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](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](operations.md#opentelemetry). ### `[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](consolidator.md#configuration). ## 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](consolidator.md#configuration)). `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__` 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..tokenFile`). - API tokens are never in the config; they live hashed in the database.