130 lines
6.4 KiB
Markdown
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.
|