|
|
|
@@ -19,7 +19,7 @@ Functionality is organized into **modules**. Each module owns a slice of the
|
|
|
|
|
API and declares its own permission vocabulary.
|
|
|
|
|
|
|
|
|
|
- **System** - Dashboard overview (OS/kernel, CPU, memory, disks, load, uptime,
|
|
|
|
|
network interfaces, temperatures); get/set hostname; time, timezone, and NTP;
|
|
|
|
|
network interfaces, GPU, temperatures); get/set hostname; time, timezone, and NTP;
|
|
|
|
|
locale and console keymap; reboot and power off.
|
|
|
|
|
- **Services** - List and inspect systemd units; start / stop / restart / enable
|
|
|
|
|
/ disable; read service logs from the journal or an allowlisted file, as a
|
|
|
|
@@ -29,10 +29,11 @@ API and declares its own permission vocabulary.
|
|
|
|
|
- **Groups** - List, inspect, create, and delete local groups.
|
|
|
|
|
- **Packages** - List installed packages and available updates; install, remove,
|
|
|
|
|
and upgrade - streamed live over SSE. Auto-detects `dnf`, `apt`, or `pacman`.
|
|
|
|
|
- **Networking** - List network interfaces, routing tables, and DNS settings; configure IPv4 settings with temporary applying and safety auto-rollback; bring interfaces up or down.
|
|
|
|
|
- **Networking** - List network interfaces, routing tables, and DNS settings; configure IPv4 settings with temporary applying and safety auto-rollback; bring interfaces up or down; edit `/etc/hosts`.
|
|
|
|
|
- **Storage** - List active mounts and `/etc/fstab` entries; add, edit, and delete fstab entries; mount and unmount filesystems.
|
|
|
|
|
- **Audit** - Read-only trail of every privileged write (who, what, when, result).
|
|
|
|
|
- **Meta** - Self-description for clients: `/api/_modules`, `/api/whoami`,
|
|
|
|
|
`/api/health`.
|
|
|
|
|
`/api/health`; trigger a self-update via `POST /api/update`.
|
|
|
|
|
|
|
|
|
|
### Security model at a glance
|
|
|
|
|
|
|
|
|
@@ -159,14 +160,18 @@ assigns the admin role to the installing user.
|
|
|
|
|
|
|
|
|
|
| Command | Effect |
|
|
|
|
|
| ------------------------------------------------ | --------------------------------------------------------------------------- |
|
|
|
|
|
| `nadir [run] [-d]` | Start the server. `-d` / `--detach` runs it in the background. |
|
|
|
|
|
| `nadir --save-config` | Save the default configuration template to the target path and exit. |
|
|
|
|
|
| `nadir install` | Install + enable the systemd service (starts now and on boot). |
|
|
|
|
|
| `nadir uninstall` | Stop, disable, and remove the systemd service. |
|
|
|
|
|
| `nadir start` \| `stop` \| `restart` \| `status` | Control the running service. |
|
|
|
|
|
| `nadir enable` \| `disable` | Toggle start-on-boot without removing the unit. |
|
|
|
|
|
| `nadir logs` | Follow logs - journald if installed as a service, otherwise the detach log. |
|
|
|
|
|
| `nadir help` | Show usage. |
|
|
|
|
|
| `nadir [run] [-d]` | Start the server. `-d` / `--detach` runs it in the background. |
|
|
|
|
|
| `nadir --save-config` | Save the default configuration template to the target path and exit. |
|
|
|
|
|
| `nadir install` | Install + enable the systemd service (starts now and on boot). |
|
|
|
|
|
| `nadir uninstall` | Stop, disable, and remove the systemd service. |
|
|
|
|
|
| `nadir start` \| `stop` \| `restart` \| `status` | Control the running service. |
|
|
|
|
|
| `nadir enable` \| `disable` | Toggle start-on-boot without removing the unit. |
|
|
|
|
|
| `nadir logs` | Follow logs - journald if installed as a service, otherwise the detach log. |
|
|
|
|
|
| `nadir update [--check] [--force]` | Download and install the latest release (requires `server.release_repo` in config). `--check` reports the available version without downloading; `--force` re-downloads even when already current. |
|
|
|
|
|
| `nadir token add <name>` | Mint a machine API token (shown once, not stored in plain text). |
|
|
|
|
|
| `nadir token rm <name>` | Revoke a token immediately (no restart needed). |
|
|
|
|
|
| `nadir token ls` | List token names (not the raw keys). |
|
|
|
|
|
| `nadir help` | Show usage. |
|
|
|
|
|
|
|
|
|
|
Most commands need root.
|
|
|
|
|
|
|
|
|
@@ -187,6 +192,7 @@ server:
|
|
|
|
|
# tls_key: /etc/nadir/tls/key.pem
|
|
|
|
|
hostname: 100.64.0.189
|
|
|
|
|
port: 9999
|
|
|
|
|
# release_repo: https://gitea.example.com/owner/nadir # enables `nadir update`
|
|
|
|
|
|
|
|
|
|
# Quote "*" - bare * is YAML alias syntax and fails to parse.
|
|
|
|
|
roles:
|
|
|
|
@@ -216,6 +222,7 @@ log_files:
|
|
|
|
|
| `tls_cert`, `tls_key` | - | PEM paths. When both are set (and `trust_proxy` is off), nadir terminates TLS with this pair. |
|
|
|
|
|
| `hostname` | - | Address to bind. Use `127.0.0.1` for local-only, or an overlay/VPN address to expose nadir only on that interface. |
|
|
|
|
|
| `port` | - | TCP port to listen on. |
|
|
|
|
|
| `release_repo` | - | Gitea repo URL (`https://host/owner/repo`). When set, enables `nadir update` and `POST /api/update`. Must be `https://`. |
|
|
|
|
|
|
|
|
|
|
TLS selection is covered in [Deployment note 2](#2-tls-three-modes).
|
|
|
|
|
|
|
|
|
@@ -389,7 +396,27 @@ forwarded headers are trustworthy. Without step 1 you're trusting every peer on
|
|
|
|
|
the overlay - fine for a single-tenant network you fully control, risky on a
|
|
|
|
|
shared one.
|
|
|
|
|
|
|
|
|
|
### 4. Connecting a dashboard (machine clients)
|
|
|
|
|
### 4. Self-update
|
|
|
|
|
|
|
|
|
|
When `server.release_repo` points at a Gitea repo, nadir can update itself:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
sudo nadir update # download + install latest, restart service
|
|
|
|
|
sudo nadir update --check # report available version, do nothing
|
|
|
|
|
sudo nadir update --force # re-download even if already at latest
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
The updater:
|
|
|
|
|
1. Fetches the latest release from the Gitea API.
|
|
|
|
|
2. Downloads the binary for the host's architecture (`linux-amd64`, `linux-arm64`, …).
|
|
|
|
|
3. Verifies the release: checks the minisign signature on `sha256sums.txt`, then checks the binary's SHA-256 against it. Refuses to install if either check fails.
|
|
|
|
|
4. Atomically replaces the running binary (`os.Rename` on the same filesystem) and runs `systemctl restart nadir`.
|
|
|
|
|
|
|
|
|
|
The same flow is also reachable via `POST /api/update` (requires the admin wildcard role), which runs the updater detached and returns 202 immediately. Poll `GET /api/health` to confirm the new version is running after the restart drops in-flight connections.
|
|
|
|
|
|
|
|
|
|
`release_repo` must use `https://` — the update downloads and executes the binary, and a plaintext URL would expose the host to on-path replacement.
|
|
|
|
|
|
|
|
|
|
### 5. Connecting a dashboard (machine clients)
|
|
|
|
|
|
|
|
|
|
To manage one or more Nadir instances via a central dashboard or non-interactive client, authenticate requests using a static Bearer token rather than interactive PAM credentials.
|
|
|
|
|
|
|
|
|
@@ -439,22 +466,23 @@ To connect a browser-based dashboard hosted on a different origin, choose one of
|
|
|
|
|
## Layout
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
cmd/ process entry point + CLI (run / install / logs …), TLS, service wiring
|
|
|
|
|
internal/auth PAM auth, sessions, login/logout, login throttle, PAM service install
|
|
|
|
|
cmd/ process entry point + CLI (run / install / update / token / logs …), TLS, service wiring
|
|
|
|
|
internal/auth PAM auth, sessions, login/logout, login throttle, bearer tokens, PAM service install
|
|
|
|
|
internal/auditlog SQLite-backed audit log writer
|
|
|
|
|
internal/config config.yaml loader + startup validation
|
|
|
|
|
internal/meta /api/_modules, /api/whoami, /api/health discovery endpoints
|
|
|
|
|
internal/meta /api/_modules, /api/whoami, /api/health, /api/update discovery + update endpoints
|
|
|
|
|
internal/module the Module interface
|
|
|
|
|
internal/modules concrete modules:
|
|
|
|
|
system - info, hostname, time/timezone/NTP, locale/keymap, power
|
|
|
|
|
services - systemd unit control + journal/file logs (snapshot + SSE)
|
|
|
|
|
users - local accounts
|
|
|
|
|
groups - local groups
|
|
|
|
|
packages - dnf/apt/pacman install/remove/upgrade (streamed)
|
|
|
|
|
audit - read-only audit trail
|
|
|
|
|
networking - network interfaces, routing tables, DNS, and IP configurations
|
|
|
|
|
system - info, hostname, time/timezone/NTP, locale/keymap, power
|
|
|
|
|
services - systemd unit control + journal/file logs (snapshot + SSE)
|
|
|
|
|
users - local accounts
|
|
|
|
|
groups - local groups
|
|
|
|
|
packages - dnf/apt/pacman install/remove/upgrade (streamed)
|
|
|
|
|
networking - interfaces, routing tables, DNS, IP config, /etc/hosts
|
|
|
|
|
storage - active mounts, /etc/fstab read/write, mount/unmount
|
|
|
|
|
internal/mounts /proc/mounts parser (used by storage module)
|
|
|
|
|
internal/oscmd shared command runner (timeouts, stderr surfacing) + helpers
|
|
|
|
|
internal/rbac roles, permissions ("*" wildcards), HTTP middleware (RBAC + CSRF)
|
|
|
|
|
internal/audit SQLite-backed audit log writer
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## API docs
|
|
|
|
|
urania