# 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..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 `-nix-`; 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.`, `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.