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

250 lines
11 KiB
Markdown

# Install
Three ways to run `slinuxm`, from most to least managed:
| Path | Use when | Service user |
| --- | --- | --- |
| [NixOS module](#nixos-module) | the host runs NixOS | `skyg-linux-tracker` (created for you) |
| [Nix package, any distro](#nix-package-on-any-linux) | you have Nix but not NixOS | you choose |
| [From source, manual systemd](#from-source-with-a-manual-systemd-unit) | any systemd-based Linux | `skyg` in the example |
Whatever the path, the result is the same binary listening on `127.0.0.1:1984` with auth on. Read [How it works](how-it-works.md) first if you have not.
**Requirements on the host:** Linux with systemd (libsystemd is linked in). Docker is optional.
## Nix
The repository is a flake. It provides:
| Output | What it is |
| --- | --- |
| `packages.<system>.default` | the `slinuxm` binary (`x86_64-linux`, `aarch64-linux`) |
| `nixosModules.default` | the `services.skyg-linux-tracker` NixOS module, with the package preset |
The flake reference used below is the repository's git remote:
```text
git+ssh://gitea@gitea.app.internal/Hermenix/skyg-linux-tracker
```
From a local checkout, use `.` (or `path:/path/to/checkout`) instead.
### Nix package on any Linux
```sh
nix run git+ssh://gitea@gitea.app.internal/Hermenix/skyg-linux-tracker -- --version # try without installing
nix profile install git+ssh://gitea@gitea.app.internal/Hermenix/skyg-linux-tracker # slinuxm on your PATH
nix build # from a checkout: ./result/bin/slinuxm
```
That gives you the binary only. To run it as a service on a non-NixOS host, follow [From source](#from-source-with-a-manual-systemd-unit) from step 2, and point `ExecStart=` in the unit at the Nix-installed binary (for example `/nix/var/nix/profiles/default/bin/slinuxm`) instead of `/usr/local/bin/slinuxm`.
The Nix build stamps the version as `<commit date>-nix-<short sha>`; a flake cannot see the branch name, so the branch is always `nix`.
### NixOS module
#### 1. Add the flake input and the module
```nix
# flake.nix of your system configuration
{
inputs.skyg-linux-tracker.url = "git+ssh://gitea@gitea.app.internal/Hermenix/skyg-linux-tracker";
outputs = { nixpkgs, skyg-linux-tracker, ... }: {
nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {
system = "x86_64-linux";
modules = [
./configuration.nix
skyg-linux-tracker.nixosModules.default
];
};
};
}
```
```nix
# configuration.nix
{
services.skyg-linux-tracker.enable = true;
}
```
`nixos-rebuild switch`, and you have:
- a `skyg-linux-tracker` system user and group, in `systemd-journal`;
- a hardened `skyg-linux-tracker.service` listening on `127.0.0.1:1984`;
- the generated config at `/etc/skyg-linux-tracker.toml` (the path the CLI reads by default, so `slinuxm` commands and the service agree);
- the token database under `/var/lib/skyg-linux-tracker` (mode 0700);
- `slinuxm` on the system `PATH`.
#### 2. Create the first token
```sh
sudo -u skyg-linux-tracker slinuxm token create my-laptop
```
The token is printed once. Test it:
```sh
curl -s -H "Authorization: Bearer $TOKEN" 'http://127.0.0.1:1984/api/v1/systemd/units?state=failed'
```
#### 3. Options
All under `services.skyg-linux-tracker`:
| Option | Default | Meaning |
| --- | --- | --- |
| `enable` | `false` | Run the service. |
| `package` | this flake's package | The package that provides `slinuxm`. |
| `port` | `1984` | TCP port for REST and `/mcp`. |
| `bind` | `"127.0.0.1"` | Listen address. A non-loopback address requires auth (the default), checked at evaluation. |
| `openFirewall` | `false` | Open `port` on all interfaces. |
| `firewallInterfaces` | `[ ]` | Open `port` on these interfaces only (preferred on a LAN), e.g. `[ "enp3s0" ]`. |
| `allowedHosts` | `[ ]` | Extra `Host`/`Origin` names accepted on `/mcp`, e.g. `[ "monitor.lan:1984" ]`. The host's own name is added automatically. |
| `tls.enable` | `false` | Serve HTTPS. |
| `tls.certFile`, `tls.keyFile` | `null` | PEM chain and key, as **strings** (absolute paths outside the store). Delivered through `LoadCredential`, so the service user never reads the originals. |
| `docker.enable` | `false` | Add the service user to the `docker` group. Root-equivalent; requires `virtualisation.docker.enable`. See [Docker access](operations.md#docker-access). |
| `settings` | `{ }` | Any config file key, as Nix attributes, merged over the module defaults (see [configuration.md](configuration.md)). Never put secrets here. |
| `environmentFile` | `null` | systemd `EnvironmentFile` for secrets such as `SKYG_OTEL__HEADERS__AUTHORIZATION`. Kept out of the store. |
| `peers.enable`, `peers.peers.<name>`, `peers.settings` | off | Consolidator mode. See [consolidator.md](consolidator.md#nixos-with-agenix). |
#### 4. Common setups
Reachable from the LAN, with TLS from ACME:
```nix
services.skyg-linux-tracker = {
enable = true;
bind = "0.0.0.0";
firewallInterfaces = [ "enp3s0" ];
allowedHosts = [ "monitor.lan:1984" ];
tls = {
enable = true;
certFile = "/var/lib/acme/monitor.lan/fullchain.pem";
keyFile = "/var/lib/acme/monitor.lan/key.pem";
};
};
security.acme.certs."monitor.lan".reloadServices = [ "skyg-linux-tracker" ];
```
Exporting to an OpenTelemetry collector, with the collector's auth header kept out of the store:
```nix
services.skyg-linux-tracker = {
enable = true;
settings.otel = {
enabled = true;
endpoint = "http://otel.lan:4317";
export_logs = true;
};
environmentFile = "/run/secrets/skyg-linux-tracker.env"; # SKYG_OTEL__HEADERS__AUTHORIZATION=Bearer ...
};
```
Tighter limits, a Docker socket proxy:
```nix
services.skyg-linux-tracker = {
enable = true;
settings = {
limits.max_lines = 500;
sources.docker_socket = "/run/docker-proxy/docker.sock";
};
};
```
#### 5. What a `nixos-rebuild switch` does to a running service
The module decides between a reload and a restart for you:
- **Reload (SIGHUP)**, no dropped connections: a change to a peer's `url` or `caFile`, or to the peer intervals and timeouts. A renewed certificate at the same path is picked up by `systemctl reload skyg-linux-tracker` (or ACME's `reloadServices`).
- **Restart**: everything else, including `port`, `bind`, auth, `tls.*` paths, `settings.otel`, `settings.limits`, sources, `peers.enable`, and adding, removing or re-pointing the `tokenFile` of a peer.
### Nix checks
`nix flake check` builds the package (running the test suite), evaluates the module against a set of cases, and boots NixOS VM tests: a two-machine test (plain and TLS) and a three-machine consolidator test. The VM tests need `/dev/kvm`.
## From source, with a manual systemd unit
For any systemd-based distribution without Nix. The unit file in this repository, [`systemd/skyg-linux-tracker.service`](../systemd/skyg-linux-tracker.service), is an **example** of a hardened unit: copy it and adapt it to your host. The NixOS module generates its own equivalent; you do not need this file on NixOS.
### 1. Build
You need a Rust toolchain, `pkg-config`, the `lld` linker (the repository's `.cargo/config.toml` links with it) and the libsystemd development files (`libsystemd-dev` on Debian/Ubuntu, `systemd-devel` on Fedora). With [devenv](https://devenv.sh), `devenv shell` provides all of them.
```sh
cargo build --release # produces target/release/slinuxm
```
### 2. Install the binary, user and config
```sh
sudo install -m 0755 target/release/slinuxm /usr/local/bin/slinuxm
sudo useradd --system --no-create-home --shell /usr/sbin/nologin skyg
sudo install -m 0644 config.example.toml /etc/skyg-linux-tracker.toml
```
`config.example.toml` lists every key with its default, so the copied file already describes a working setup. Edit it as needed ([configuration.md](configuration.md)).
### 3. Install the example unit
```sh
sudo install -m 0644 systemd/skyg-linux-tracker.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now skyg-linux-tracker
```
What the example sets up, and what you may need to change:
| In the unit | Why | Adapt if |
| --- | --- | --- |
| `ExecStart=/usr/local/bin/slinuxm serve --config /etc/skyg-linux-tracker.toml` | runs the server with the installed config | the binary or config lives elsewhere |
| `ExecReload=` sends SIGHUP | `systemctl reload` rotates TLS certificates and reloads peers | |
| `User=skyg`, `Group=skyg` | a static user, so `sudo -u skyg slinuxm token ...` opens the same database as the service | you chose another user name |
| `SupplementaryGroups=systemd-journal` | read the whole journal | |
| `#SupplementaryGroups=docker` (commented out) | Docker access is root-equivalent | you accept that risk; prefer a socket proxy |
| `StateDirectory=skyg-linux-tracker`, mode 0700 | systemd creates `/var/lib/skyg-linux-tracker` owned by the service user | you move `auth.db_path`: then also add `ReadWritePaths=` for the new directory |
| `ProtectSystem=strict` and the rest of the hardening block | the process can write nothing but its state directory | rarely; `systemd-analyze security skyg-linux-tracker` scores it about 1.5 |
| `TimeoutStopSec=30` | room for the graceful drain and OTel flush | |
Override settings without editing the file using `systemctl edit skyg-linux-tracker` (a drop-in), for example to add `Environment=SKYG_SERVER__PORT=2000` or an `EnvironmentFile=` for secrets.
### 4. Create the first token
The service creates the state directory on first start, so start it first (step 3), then:
```sh
sudo -u skyg slinuxm token create my-laptop
```
## Without a service
Nothing requires systemd to manage the process. For a quick look on your own machine, with the token database in a temp directory and no root:
```sh
export SKYG_AUTH__DB_PATH=/tmp/slinuxm-demo/db.sqlite
TOKEN=$(slinuxm token create demo)
slinuxm serve # Ctrl-C to stop
```
As a normal user you see your own journal entries only, unless you are in `systemd-journal`.
## Verify an install
```sh
curl -s http://127.0.0.1:1984/healthz # {"status":"ok","version":"..."}
curl -s -H "Authorization: Bearer $TOKEN" http://127.0.0.1:1984/api/v1/ping
slinuxm --print-config # effective config, secrets redacted
journalctl -u skyg-linux-tracker -n 50 # the server's own log
ldd "$(command -v slinuxm)" # libc, libm, libgcc_s, libsystemd only
```
Then connect an MCP client: [operations.md](operations.md#connect-an-mcp-client).
## Upgrade and uninstall
- **NixOS:** update the flake input (`nix flake update skyg-linux-tracker`) and switch. The token database is kept.
- **Manual:** replace `/usr/local/bin/slinuxm` and `systemctl restart skyg-linux-tracker`. The database migrates itself on start.
- **Uninstall (manual):** `systemctl disable --now skyg-linux-tracker`, then remove the unit, the binary, `/etc/skyg-linux-tracker.toml`, `/var/lib/skyg-linux-tracker` and the `skyg` user.