250 lines
11 KiB
Markdown
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.
|