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-trackersystem user and group, insystemd-journal; - a hardened
skyg-linux-tracker.servicelistening on127.0.0.1:1984; - the generated config at
/etc/skyg-linux-tracker.toml(the path the CLI reads by default, soslinuxmcommands and the service agree); - the token database under
/var/lib/skyg-linux-tracker(mode 0700); slinuxmon the systemPATH.
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
urlorcaFile, or to the peer intervals and timeouts. A renewed certificate at the same path is picked up bysystemctl reload skyg-linux-tracker(or ACME'sreloadServices). - Restart: everything else, including
port,bind, auth,tls.*paths,settings.otel,settings.limits, sources,peers.enable, and adding, removing or re-pointing thetokenFileof 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/slinuxmandsystemctl 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-trackerand theskyguser.