Files
2026-10-21 00:12:33 -04:00

130 lines
6.4 KiB
Markdown

# 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 <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:
```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__<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.