Files
skyg-linux-tracker/docs/install.md
T
2026-10-21 00:12:33 -04:00

11 KiB

Install

Three ways to run slinuxm, from most to least managed:

Path Use when Service user
NixOS module the host runs NixOS skyg-linux-tracker (created for you)
Nix package, any distro you have Nix but not NixOS you choose
From source, manual systemd 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 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:

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

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 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

# 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
      ];
    };
  };
}
# 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

sudo -u skyg-linux-tracker slinuxm token create my-laptop

The token is printed once. Test it:

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.
settings { } Any config file key, as Nix attributes, merged over the module defaults (see 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.

4. Common setups

Reachable from the LAN, with TLS from ACME:

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:

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:

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, 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, devenv shell provides all of them.

cargo build --release          # produces target/release/slinuxm

2. Install the binary, user and config

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).

3. Install the example unit

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:

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:

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

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.

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.