480 lines
29 KiB
Markdown
Executable File
480 lines
29 KiB
Markdown
Executable File
# SysDeck — Quick Start
|
||
|
||
Author: **Jeremy Anderson** · <info@dcos.net> · <https://dcos.net> · [github.com/dcosnet/SysDeck](https://github.com/dcosnet/SysDeck)
|
||
Version: **0.4.4**
|
||
|
||
Two five-minute paths, standalone first: run the web console with no Cockpit on the box at all (sections 1–3), or install the plugin suite into an existing Cockpit (sections 4–6). Either way every domain module also loads in the other front end — one catalog, two front ends.
|
||
|
||
---
|
||
|
||
## 1. The standalone web console (no Cockpit required)
|
||
|
||
The master tarball ships the **SysDeck web console** at `web/` — a standalone server-management console that signs you in with your Unix account (PAM, the same mechanism Cockpit uses), reads real host state through 31 bridge modules (`/proc`, `/sys`, lsblk, systemctl, the real package manager...), detects and loads every installed Cockpit module into its own navigation, and carries **Fester pre-integrated** (vendored at `web/mini-services/fester`, independent version 0.2.1). Every module in this console can equally be loaded inside Cockpit itself.
|
||
|
||
```bash
|
||
tar xjf sysdeck-0.4.4-master.tar.bz2
|
||
cd sysdeck-0.4.4-master
|
||
make web-dev # bun install + db:push + fester (:3010) + web console (:3000)
|
||
```
|
||
|
||
Manual equivalent:
|
||
|
||
```bash
|
||
make fester-start # terminal 1: fester on :3010
|
||
cd web && bun install && bun run db:push # terminal 2: console setup
|
||
bun run dev # web console on :3000
|
||
```
|
||
|
||
Prerequisites: **Bun ≥ 1.1** (`pacman -S bun`, or the installer from bun.sh; Node-only hosts work too — see §3), ~200 MB disk, ~512 MB RAM. **Not required:** Cockpit, systemd, Docker, root — the console runs as an unprivileged user on any Linux host. Open `http://localhost:3000` and sign in with a Unix account (see §2). Without the fester service running, the Fester panel says so — everything else works.
|
||
|
||
## 2. The console login (Unix accounts, cockpit-style)
|
||
|
||
SysDeck is a **LAN-side console** — loopback binding stays the outer boundary. The login itself signs you in with a **Unix account — the username and password are verified by the host's PAM stack**, exactly the mechanism Cockpit uses at its own login screen. The host decides; the console keeps no password data of its own.
|
||
|
||
- **PAM path:** `web/scripts/pam-auth.py` (stdlib-only ctypes client of `libpam`) runs the `pam_start` → `pam_authenticate` → `pam_acct_mgmt` sequence under the **`sysdeck`** service when `/etc/pam.d/sysdeck` exists, else the stock **`login`** stack. Credentials travel over stdin (never argv — `/proc` would leak them). Ship your own `/etc/pam.d/sysdeck` (e.g. `auth required pam_unix.so`, plus `pam_google_authenticator` for MFA if you want it) to tailor the stack — `SYSDECK_PAM_SERVICE` renames it.
|
||
- **Root, or pam+local:** pam_unix needs root to read `/etc/shadow` for *arbitrary* users (non-root processes only get the invoking uid via `unix_chkpwd` — a pam_unix guarantee). So the modes are `SYSDECK_AUTH_MODE=pam` (default; run the service as root, like cockpit-ws), `pam+local` (PAM first, then the `SdUser` scrypt table for installs that can't run privileged), or `local` (console accounts only). Manage the local table with `bun scripts/manage-users.mjs list|add|passwd|disable|enable|remove` from `web/`.
|
||
- **Session:** an HttpOnly, SameSite=Lax cookie (`sd_session`) holding an HMAC-SHA256-signed token **bound to the username** (`v2.<exp>.<userB64>.<hmac>`), **12h** expiry. The HMAC key is random per install and persists in the SQLite DB, so sessions survive restarts — including the 0.3.1 → 0.4.0 upgrade (old v1 tokens still verify as a legacy "operator" session until they age out).
|
||
- **Gate scope:** the page itself is server-rendered as the login screen until the cookie verifies, every `/api/*` route answers 401 until signed in, and the **fester service verifies the identical v2 token** on its REST + WebSocket surface — no unauthenticated path into the console's data.
|
||
- **Lockout:** wrong attempts are rate limited per-IP **and** per-username (5 per 60s each — the same shape the sshd stack applies). Wrong-user and wrong-password return the same generic answer; nothing enumerates accounts.
|
||
- **Identity in the shell:** the header carries an account menu — avatar, `user@host`, unix-account provenance (PAM vs local), the wheel/sudo "Administrative access" badge, and a live session-expiry countdown with a draining life bar; the status bar shows `user@host` next to the vitals. Login/logout are audited with the unix username as the actor.
|
||
- **TLS:** LAN deployments typically run plain http; front the console with TLS and set `SYSDECK_SESSION_SECURE=1` to add the `Secure` cookie flag. Sign out lives in the account menu (clears the cookie).
|
||
|
||
## 3. Standalone production build
|
||
|
||
The build emits a self-contained standalone server (`.next/standalone/` with static assets and `public/` folded in):
|
||
|
||
```bash
|
||
cd web
|
||
bun install
|
||
bun run build # next build + fold static/ & public/
|
||
PORT=3000 HOSTNAME=0.0.0.0 bun run start
|
||
|
||
# node-only hosts:
|
||
bun run build # or: npx next build
|
||
PORT=3000 HOSTNAME=0.0.0.0 node .next/standalone/server.js
|
||
```
|
||
|
||
Run `bun run db:push` once before the first production start — the SQLite file lives at `db/custom.db` (path from `DATABASE_URL` in `.env`). The complete runbook — the two systemd units (`sysdeck-web.service`, `sysdeck-fester.service`), the `.env` reference table, the Caddy/nginx reverse proxy with the `?XTransformPort=` websocket gateway, and a troubleshooting matrix — lives in two places, kept in sync:
|
||
|
||
- **`web/README.md`** in this tarball (plain markdown)
|
||
- the **"Run without Cockpit" panel** in the web console (system group, right under Overview) — every command block has a copy button
|
||
|
||
## 4. Install the Cockpit plugin suite (optional)
|
||
|
||
For hosts that already run Cockpit, the same 27 domain modules install as plugins.
|
||
|
||
Prerequisites:
|
||
|
||
| Component | Why | Install |
|
||
|-----------|-----|---------|
|
||
| `cockpit-bridge` ≥ 239 | The plugin runtime | `pacman -S cockpit` / `apt install cockpit` / `dnf install cockpit` |
|
||
| `python3` ≥ 3.9 | Bridge helpers | Universal on modern Linux |
|
||
| `polkit` | Privilege escalation (the cockpit way) | `pacman -S polkit` / `apt install policykit-1` / `dnf install polkit` |
|
||
| `appstream` (optional) | Cockpit Applications menu | `pacman -S appstream` / `apt install appstream` |
|
||
|
||
```bash
|
||
sudo make install
|
||
sudo systemctl restart cockpit.socket
|
||
```
|
||
|
||
`make install` does:
|
||
|
||
- Copies each `plugins/sysdeck-*/{manifest.json,index.html,*.js}` to `/usr/share/cockpit/sysdeck-*/` (27 plugins)
|
||
- Copies `shared/{manifest.json,bridge.js,sysdeck.css,sysdeck-web.css}` to `/usr/share/cockpit/sysdeck-common/`
|
||
- Copies each `bridge/*.py` (executable, 0755) to `/usr/lib/sysdeck/bridge/` (28 helpers)
|
||
- Copies `firewall/templates/*.sh` (executable, 0755) to `/usr/share/sysdeck/firewall/templates/` (7 topologies) + the cilium policy
|
||
- Copies the prometheus/grafana provisioning configs to `/usr/share/sysdeck/prometheus/`
|
||
- Installs the AppStream metainfo at `/usr/share/metainfo/sysdeck.metainfo.xml`
|
||
- Installs the polkit policies at `/usr/share/polkit-1/actions/org.sysdeck.policy` + `org.sysdeck.modules3p.policy`
|
||
- Reloads polkit and refreshes the AppStream cache
|
||
|
||
Cockpit itself is the only hard dependency of this path. SysDeck degrades gracefully when optional backends (podman, nftables, mkosi, bpftool, apparmor, …) are absent — each panel renders an install hint instead of crashing.
|
||
|
||
## 5. Verify the cockpit install
|
||
|
||
Open `https://<host>:9090` in your browser and authenticate as a wheel/sudo user. The Cockpit sidebar should now list **27** entries under the `SysDeck <Name>` prefix:
|
||
|
||
| # | Module | # | Module | # | Module |
|
||
|---|--------|---|--------|---|--------|
|
||
| 1 | Containers & VMs | 10 | Firmware | 19 | Databases |
|
||
| 2 | Firewall | 11 | Image Builder | 20 | Jellyfin |
|
||
| 3 | Integrity | 12 | Mining | 21 | Photos |
|
||
| 4 | Network Security | 13 | Themes | 22 | Remote FS |
|
||
| 5 | Service Mesh | 14 | Hardware Auth | 23 | Monitoring |
|
||
| 6 | Vault | 15 | Glances | 24 | 3rd-Party Modules |
|
||
| 7 | Fleet | 16 | Sensors | 25 | Service / Ports |
|
||
| 8 | Kata | 17 | Benchmark | 26 | AI Gateway |
|
||
| 9 | Fester | 18 | Packages | 27 | Policy |
|
||
|
||
If any are missing, run the diagnostic:
|
||
|
||
```bash
|
||
sudo /usr/share/sysdeck/sysdeck-diagnose.sh
|
||
```
|
||
|
||
It prints exactly what cockpit sees on your system — installed manifests, bridge helpers present, polkit actions loaded, and the cockpit-bridge version.
|
||
|
||
## 6. First-use walkthrough (cockpit panels)
|
||
|
||
### 6a. Firewall (the cockpit way)
|
||
|
||
Open **SysDeck Firewall**. The panel renders:
|
||
|
||
1. **Capability matrix** — confirms nftables is installed.
|
||
2. **Template selector** — pick `vps-webserver` (service-aware firewall that auto-detects SSH/Caddy/Varnish/Forgejo) or `no-services` (locked-down host with no public services except SSH).
|
||
3. **Detect Services** — runs the template's `detect` action and shows the OS, interface, IPv4/IPv6, and which services the template found.
|
||
4. **Apply Template** — cockpit prompts for the superuser password via polkit. The bridge runs the template's `start` action under the `org.sysdeck.firewall.modify` action.
|
||
5. **Banned IPs** — live `ssh_abuse` / `port_scanners` / `connlimit_abuse` ban sets, with per-IP **Unban** buttons and a **Clear All** button.
|
||
6. **Active Ruleset** — the live nftables rules table, refreshed after each operation.
|
||
|
||
To drop in your own template, copy a `*.sh` file into `/usr/share/sysdeck/firewall/templates/` — the panel's `templates` subcommand discovers it automatically. The script must implement `start / stop / restart / detect / status` subcommands (see the shipped templates for reference).
|
||
|
||
### 6b. Packages (the cockpit way)
|
||
|
||
Open **SysDeck Packages**. Click **Update All**. Cockpit prompts for the superuser password via polkit. The bridge runs `pacman -Syu` / `apt upgrade -y` / `dnf upgrade -y` directly via subprocess — no `sudo` shell-out from JS. Live stdout/stderr stream into the in-panel log. The **Preview Command** button shows the exact command that will be run before you confirm.
|
||
|
||
### 6c. Policy & Permissions
|
||
|
||
Open **SysDeck Policy**. The panel renders:
|
||
|
||
1. **LSM Stack** — a badge row in the header showing which LSMs the kernel has stacked (`/sys/kernel/security/lsm`), and a table of all 9 supported LSMs with their securityfs paths and active/inactive status.
|
||
2. **Capability Matrix** — confirms availability of ACLs, cgroups v2, VLANs, eBPF, namespaces, file caps, and each LSM. Absent concerns show a red "no" badge plus the install command.
|
||
3. **ACL Manager** — pick a path, type an entry like `group:www-data:rwx`, click `setfacl -m` (or `setfacl -x` to remove, `set default ACL` for directory inheritance).
|
||
4. **cgroups v2** — the unified hierarchy tree under `/sys/fs/cgroup/` with per-cgroup process counts and controllers. Use **Show** to inspect one cgroup's processes and control files; **mkdir** to create a new one; **move** to migrate a PID; **write** to set `memory.max`, `cpu.weight`, etc.
|
||
5. **VLANs** — list and create/delete 802.1Q VLANs via `ip link add ... type vlan id <vid>`.
|
||
6. **eBPF programs** — list loaded BPF programs via `bpftool prog show -j`, list maps, pin a program to `/sys/fs/bpf/...`.
|
||
7. **Namespaces** — `lsns -J` output as a table.
|
||
8. **File Capabilities** — `getcap -r /` enumeration with `setcap` / `getcap` / `setcap -r` controls.
|
||
9. **AppArmor** (optional) — if the kernel compiled AppArmor in, shows the enforcement mode and lets you switch profiles between `enforce` and `complain` modes. If absent, renders an install hint.
|
||
10. **Smack / TOMOYO / Yama / LoadPin / Lockdown / BPF-LSM / Landlock** — each has its own card with the live state and any management controls the LSM supports. Each card follows the same shape: if the LSM is not active, the card shows the kernel cmdline that enables it; if active, it shows the live state.
|
||
|
||
### 6d. Databases
|
||
|
||
Open **SysDeck Databases**. The panel auto-detects 32+ engines across SQL (PostgreSQL/MySQL/MariaDB/SQLite/CockroachDB/TiDB), NoSQL (MongoDB/CouchDB/RethinkDB/DynamoDB-local), Vector (Milvus/Qdrant/Weaviate/Chroma/pgvector), TimeSeries (InfluxDB/TimescaleDB/QuestDB/ClickHouse), Graph (Neo4j/ArangoDB/OrientDB), Embedded (Redis/KeyDB/ValKey/RocksDB/LMDB/BadgerDB), Cloud (Firestore-emulator/Supabase-local), and AI (LanceDB/DuckDB/Tile38). Each row has **Start / Stop / Restart / Status** buttons. The **Run SQL Query** card lets you execute read-only SQL against SQL-family engines via the engine's CLI client (`psql -tAc`, `mysql -e`, etc.).
|
||
|
||
## 7. Build from source
|
||
|
||
```bash
|
||
cd sysdeck-0.4.4-master
|
||
make check # 7 build-time guards + 267 parser unit tests
|
||
make dist # builds the cockpit tarball
|
||
make distcheck # extracts + runs make check inside the tarball tree
|
||
make master # rebuilds the master tarball (cockpit + web + fester + klanker-gate)
|
||
```
|
||
|
||
`make check` is a hard pre-flight: it cross-checks every `bridgeCmd("<module>", ["<sub>", ...])` call in `shared/bridge.js` against the `COMMANDS` dict declared in each `bridge/<module>.py`. If the JS calls a subcommand the Python helper doesn't implement, `make check` fails with a clear message naming the file, line, and missing subcommand.
|
||
|
||
## 8. Uninstall
|
||
|
||
```bash
|
||
sudo make uninstall
|
||
sudo systemctl restart cockpit.socket
|
||
```
|
||
|
||
`make uninstall` removes every trace of every prior version (the v0.0.9-v0.0.19 single-plugin `/usr/share/cockpit/sysdeck/` directory, the v0.0.20+ multi-plugin `/usr/share/cockpit/sysdeck-*/` directories, the Python bridge helpers, the diagnostic scripts, the firewall templates, the AppStream metainfo, the polkit policy, and any pacman-installed `sysdeck` package).
|
||
|
||
Or use the **quiet uninstaller** — same coverage, silent on success, idempotent, and it restarts cockpit.socket itself (so the sidebar flushes in one step):
|
||
|
||
```bash
|
||
sudo ./sysdeck-uninstall.sh # quiet; also handles the
|
||
# 0.3.0 branding skin (restores
|
||
# the distro branding.css backup)
|
||
# + dpkg/rpm copies + python
|
||
# site-packages links
|
||
sudo ./sysdeck-uninstall.sh -n # dry-run: list what would go
|
||
sudo ./sysdeck-uninstall.sh --purge-state # also drop /var/lib/sysdeck
|
||
# (builder artifacts — operator
|
||
# data, off by default)
|
||
sudo ./sysdeck-uninstall.sh --no-restart # skip the cockpit.socket restart
|
||
```
|
||
|
||
It prints nothing on success — including when nothing was installed — and leaves operator data alone (`/etc/sysdeck/`, `/var/lib/sysdeck/` unless `--purge-state`, `/etc/pam.d/sysdeck`, and any third-party cockpit modules). `make install` also drops the script at `/usr/share/sysdeck/sysdeck-uninstall.sh`, so it stays available on boxes that installed via package manager and no longer have the tarball.
|
||
|
||
## 9. Where to go next
|
||
|
||
- [README.md](./README.md) — full module catalog, architecture, coding standards.
|
||
- [BLOG.md](./BLOG.md) — the engineering essay: auth model, one catalog two front ends, the zero-demo contract.
|
||
- [docs/INSTALL.md](./docs/INSTALL.md) — the install matrix: standalone, Make, RPM, pip, staged overlay.
|
||
- [web/README.md](./web/README.md) — the complete standalone runbook.
|
||
- [QA.md](./QA.md) — QA notes per release.
|
||
- [worklog.md](./worklog.md) — per-task development log.
|
||
|
||
Every SysDeck plugin's `index.html` installs `window.addEventListener('error')` and `'unhandledrejection'` handlers that replace the "Loading…" placeholder with the actual error message on the page — no devtools required. The same page tells you whether `cockpit.js` itself loaded, whether `bridge.js` imported cleanly, and whether the panel's `mount()` threw.
|
||
|
||
## 10. The AI Gateway (master tarball, v0.3.0)
|
||
|
||
The master tarball also vendors **klanker-gate** — the Frosty Deno LLM gateway (independent version 0.9.0, Apache-2.0, **by TykoDev: https://github.com/TykoDev/klanker-gate — not SysDeck code**, see `klanker-gate/ATTRIBUTION.md`) — at `klanker-gate/`, with the **AI Gateway** module in both editions. On Arch Linux the whole gateway is one package away:
|
||
|
||
```bash
|
||
cd klanker-gate/arch
|
||
pacman -S --needed deno base-devel # deno is in [extra]
|
||
makepkg -si # /usr/share/klanker-gate + systemd unit
|
||
sudoedit /etc/klanker-gate/env # FROSTY_PG_URL + one provider key (+ token)
|
||
sudo systemctl enable --now klanker-gate
|
||
curl http://localhost:8080/healthz
|
||
```
|
||
|
||
Then point SysDeck at it (cockpit bridge env, or `web/.env` for the console, then restart):
|
||
|
||
```bash
|
||
KLANKER_URL=http://127.0.0.1:8080
|
||
KLANKER_ADMIN_TOKEN=<the FROSTY_ADMIN_TOKEN you set>
|
||
```
|
||
|
||
Both the cockpit AI Gateway panel and the console's AI Gateway panel flip from their offline state to live data automatically. The full runbook — postgres provisioning, multi-worker serving (`FROSTY_WORKERS`, an Arch bonus via `SO_REUSEPORT`), the optional control-UI build — is `klanker-gate/arch/INSTALL-ARCH.md`.
|
||
|
||
### 10.1 Running an all-local stack (ollama · llama.cpp · koboldcpp)
|
||
|
||
The gateway is **not SaaS-only** — no API key is required anywhere in this
|
||
setup. Five provider types are local-first upstream: `ollama`, `lmstudio`,
|
||
`sgl` (SGLang) natively, plus the generic `openai-compatible` type that
|
||
llama.cpp (llama-server), KoboldCpp, vLLM and TGI all speak:
|
||
|
||
| backend | provider type | base URL | auth |
|
||
|---|---|---|---|
|
||
| Ollama | `ollama` | `http://127.0.0.1:11434/v1` | none |
|
||
| llama.cpp (llama-server) | `openai-compatible` | `http://127.0.0.1:8081/v1` | optional |
|
||
| KoboldCpp | `openai-compatible` | `http://127.0.0.1:5001/v1` | optional |
|
||
| LM Studio | `lmstudio` | `http://127.0.0.1:1234/v1` | none |
|
||
| SGLang | `sgl` | `http://127.0.0.1:30000/v1` | none |
|
||
|
||
Env wiring (in `/etc/klanker-gate/env` or the gateway's `.env`):
|
||
|
||
```bash
|
||
OLLAMA_BASE_URL=http://127.0.0.1:11434/v1
|
||
OLLAMA_MODELS=qwen3:14b,llama3.1:8b,nomic-embed-text
|
||
LMSTUDIO_BASE_URL=http://127.0.0.1:1234/v1
|
||
OPENAI_COMPAT_BASE_URL=http://127.0.0.1:8081/v1 # ONE openai-wire server
|
||
```
|
||
|
||
Env registers one `openai-compatible` account — to run llama.cpp **and**
|
||
koboldcpp (and vLLM) side by side, register each via the admin API, then
|
||
auto-discover its catalog:
|
||
|
||
```bash
|
||
curl -s http://127.0.0.1:8080/api/providers -H 'Authorization: Bearer $FROSTY_ADMIN_TOKEN' \
|
||
-H 'content-type: application/json' \
|
||
-d '{"id":"llama-server","type":"openai-compatible","baseUrl":"http://127.0.0.1:8081/v1","enabled":true}'
|
||
curl -s -X POST http://127.0.0.1:8080/api/providers/llama-server/refresh-models \
|
||
-H 'Authorization: Bearer $FROSTY_ADMIN_TOKEN'
|
||
```
|
||
|
||
**Port note:** llama-server defaults to `:8080` — the same port the gateway
|
||
listens on. Run it on another port (`--port 8081`) or move the gateway.
|
||
|
||
Both editions ship a **Local stack wiring** card (in the AI Gateway panel)
|
||
that live-probes each backend's `/v1/models` from the host and shows these
|
||
recipes with copy buttons — `klanker localstack` at the bridge level.
|
||
|
||
### 10.2 Turning the AI Gateway off (module toggles)
|
||
|
||
Not using the gateway (or switched to a different assistant stack)?
|
||
Both editions let you remove it from the console without uninstalling
|
||
anything:
|
||
|
||
- **web console** — every sidebar module carries a power toggle (hover
|
||
a row → the power icon). Clicking it hides the module from the sidebar
|
||
AND the command palette; a **Disabled (N)** section appears at the
|
||
sidebar bottom with one-click re-enable (plus a restore-all). State is
|
||
persisted in SQLite (`shell.disabled` via the `shell` bridge module) and
|
||
survives restarts; Overview is protected. If you disable the module
|
||
you are viewing, the console jumps back to Overview.
|
||
- **cockpit edition** — plugins are discovered by directory: `sudo rm
|
||
-rf /usr/share/cockpit/sysdeck-klanker` removes the sidebar entry
|
||
(bridge helper stays at `/usr/lib/sysdeck/bridge/klanker.py` for
|
||
scripts); restore with `sudo make install`.
|
||
|
||
### 10.3 The security audits (both editions + the vendored gateway)
|
||
|
||
A full-codebase security review shipped with 0.3.0 — the cockpit bridge
|
||
helpers, the 27 plugin panels, the web console, and the vendored
|
||
klanker-gate tree. What changed:
|
||
|
||
- **bridge helpers fail closed now.** `cgroup-set` validates both the
|
||
cgroup path (must resolve under `/sys/fs/cgroup`) and the control-file
|
||
name (real controller knobs only); `artifacts-clear` /
|
||
`build-delete` / `build-log` / `artifacts` validate ids as single
|
||
path components before touching state/artifacts/logs dirs;
|
||
`profile-create` rejects names that aren't single components (was
|
||
directory traversal + config injection into root-executed build
|
||
configs); hwalert's `sudo sh -c` is gone (direct write, device path
|
||
validated under the scanned sysfs bases); `db start/stop/restart`
|
||
resolve engines through the registry; `db query` now actually
|
||
enforces the read-only promise (SELECT/WITH/SHOW/… only);
|
||
`themes set` rejects newlines (cockpit.conf section injection);
|
||
`packages install/remove/update` reject option-shaped names.
|
||
- **every plugin escapes its data.** The 8 oldest panels (packages,
|
||
benchmark, auth, sensors, vault, firmware, mesh, and the auth quick
|
||
actions) now escape every interpolated string — package metadata,
|
||
USB reader descriptors, fwupd device fields, sensor labels, spawn
|
||
errors — before it lands in `innerHTML`. All 27 manifests dropped
|
||
`unsafe-eval` from their CSP. Every external link carries
|
||
`rel="noopener noreferrer"`.
|
||
- **the web console binds loopback.** `bun run dev` → `127.0.0.1:3000`,
|
||
the fester service → `127.0.0.1:3010`, the production start script
|
||
pins `HOSTNAME=127.0.0.1`; the bridge endpoint gained a body-size
|
||
cap, a per-IP rate limit and generic error responses (details go to
|
||
the server log).
|
||
- **the vendored gateway got audited, not modified.** Findings live in
|
||
`klanker-gate/arch/SECURITY-UPSTREAM.md` (10 findings, 3 critical:
|
||
no-token admin mode, 0.0.0.0 default bind, open `/v1/*` until the
|
||
first virtual key exists). Upstream source stays byte-identical per
|
||
the attribution contract; the SysDeck `arch/` packaging layer
|
||
mitigates: the systemd unit refuses to start without
|
||
`FROSTY_ADMIN_TOKEN`, `INSTALL-ARCH.md` §9 carries the firewall +
|
||
first-vkey runbook.
|
||
|
||
### 10.4 Cockpit module detection in the web console (v0.4.1)
|
||
|
||
The console scans the host the same way the cockpit shell discovers
|
||
pages — every `/usr/share/cockpit/<pkg>/manifest.json` with a `menu`
|
||
entry is a module — and **loads each one into its own navigation**:
|
||
|
||
- a **Cockpit** sidebar group (with a LIVE/DEMO provenance badge) lists
|
||
every detected module — distro modules (`cockpit-machines`,
|
||
`cockpit-podman`, networking, storage, accounts, updates, SELinux,
|
||
PCP metrics, kdump, tuned...) and third-party addons alike;
|
||
- each module opens a detail view with its manifest identity, shipped
|
||
files, **live backend presence probes** (`virsh`/`podman`/`nmcli`/
|
||
`pkcon`/... — real `which()` checks), and a jump to the native
|
||
console panel covering the domain when one exists;
|
||
- `sysdeck-*` modules never duplicate (native panels already ship), and
|
||
menu-less chrome (`base1`, `shell`) is skipped — exactly the cockpit
|
||
shell's own rules;
|
||
- `SYSDECK_COCKPIT_SCAN` (colon-separated paths) adds extra scan roots
|
||
for staged trees; with no cockpit tree on the host, a clearly-badged
|
||
typical-distro set keeps the surface explorable;
|
||
- the **Cockpit Modules** hub panel (Integrations group) summarizes
|
||
detection: counts, backend availability, native coverage, and the
|
||
scan paths in play.
|
||
|
||
This is the piece that makes the console/host pair 100% compatible:
|
||
install a cockpit module on the box, and it shows up here — no cockpit
|
||
login required to browse it.
|
||
|
||
### 10.5 The zero-demo release (v0.4.2)
|
||
|
||
Every web-console module ships production implementations only — no
|
||
demo, mock, stub, or seeded data anywhere in the codebase:
|
||
|
||
- **Sensors** parse the real `sensors -j` (lm-sensors) JSON — the exact
|
||
source the cockpit edition reads — with raw sysfs collectors as the
|
||
fallback. No sensors → an honest empty panel.
|
||
- **Netsec bans enforce for real** — an atomic nftables batch (`table
|
||
inet sysdeck`, `blacklist` set, 30-day timeouts) or an iptables DROP
|
||
rule, privilege-gated like every mutation; the live fail2ban ban list
|
||
is merged when fail2ban runs, and fail2ban rows unban through the
|
||
real `fail2ban-client set <jail> unbanip`.
|
||
- **The firewall panel reads the host's actual kernel ruleset** (new
|
||
live-ruleset tab: `nft -j list ruleset` / `iptables-save`) and the
|
||
template catalog covers all seven shipped topologies.
|
||
- The bridge `DataSource` type no longer admits a `'demo'` value — the
|
||
compiler itself rejects the value at build time. Absent backends always
|
||
render honest empty inventories with install guidance.
|
||
|
||
### 10.6 The MoE QA pass (v0.4.3)
|
||
|
||
A multi-expert audit hardened every axis of the console:
|
||
|
||
- Privileged writes ride stdin and verify themselves (polkit rules
|
||
byte-for-byte post-write; `nft -f -` / `iptables-restore` piped
|
||
rulesets; PIN off argv; `mktemp` staging everywhere `/tmp` was
|
||
predictable).
|
||
- Mutating bridge commands require an admin session (wheel/sudo/adm);
|
||
reads stay open to every signed-in unix account. Set
|
||
`SYSDECK_MUTATIONS=any` for single-operator consoles.
|
||
- Dry-runs preview exactly what apply executes (the shipped template
|
||
script verbatim); unbans/applies report the firewall's real exit
|
||
code; rule comments are injection-guarded.
|
||
- `X-Forwarded-For` defines rate-limit identity only behind an opted-in
|
||
proxy (`SYSDECK_TRUST_PROXY=1`).
|
||
- The polling layer shares TTL + single-flight probes across panels —
|
||
one subprocess sweep per window, not a spawn storm per tick — and
|
||
the Python bridges match the web side's chains (sensors `sensors -j`
|
||
→ sysfs; dnf `check-update` rc 100 = updates exist; timeouts on
|
||
every spawn).
|
||
|
||
### 10.7 Ten package managers on both editions (v0.4.4)
|
||
|
||
The package module runs the same on every distro it touches — module
|
||
parity between the two frontends, not drift:
|
||
|
||
- **Cockpit edition** (`bridge/packages.py`): pacman (Arch) · emerge
|
||
(Gentoo/Portage) · lunar (Lunar Linux) · sorcery (SourceMage) ·
|
||
xbps (Void) · apk (Alpine) · zypper (openSUSE) · dnf / yum (RPM) ·
|
||
apt (Debian). Detection is a `shutil.which` step-down in a fixed
|
||
order, most specific first; `emerge` requires the `/var/db/pkg`
|
||
corroboration; Void is probed via `xbps-query` (no bare `xbps`
|
||
binary exists). Installs/removals/updates resolve from one
|
||
`MUTATION_CMDS` table — `pacman -S --noconfirm`, `emerge
|
||
--unmerge`, `cast`/`dispel`, `lin`/`lrm`, `xbps-install -y`,
|
||
`zypper --non-interactive` — and still ride the cockpit superuser
|
||
channel (polkit `org.sysdeck.packages.modify`).
|
||
- **Web console** (`web/src/lib/sysdeck/bridge/packages.ts`): the
|
||
identical step-down and now the identical parser fixes — zypper
|
||
tables parse by header-located columns, the emerge update preview
|
||
anchors its capture after the class bracket (the old capture
|
||
grabbed the bracket and silently dropped every row), and
|
||
`xbps-query -Rs` rows parse with or without a repository prefix.
|
||
- **Honest capability reporting**: lunar has no update-preview
|
||
subcommand, so its summary says so instead of reporting 0 updates;
|
||
lunar single-package update refuses with the real instruction.
|
||
Fixture tests for all of the above run in `make check`
|
||
(`tests/test_bridge_parsers.py::TestPackagesBackends`).
|
||
|
||
## 11. Run without Cockpit (the complete standalone runbook)
|
||
|
||
The web console needs **nothing from sections 4–6** — no cockpit, no Python
|
||
bridge, no systemd, no root. One Bun runtime serves the whole console:
|
||
|
||
```bash
|
||
tar xjf sysdeck-0.4.4-master.tar.bz2
|
||
cd sysdeck-0.4.4-master
|
||
make web-dev # bun install + db:push + fester + next dev :3000
|
||
```
|
||
|
||
Production path (standalone build, systemd on Arch, reverse proxy with the
|
||
`?XTransformPort=` websocket gateway, environment reference, troubleshooting):
|
||
|
||
```bash
|
||
cd web
|
||
bun run build # self-contained .next/standalone/
|
||
PORT=3000 HOSTNAME=0.0.0.0 bun run start # or: node .next/standalone/server.js
|
||
```
|
||
|
||
The complete runbook — with the two systemd units (web + fester), the
|
||
`.env` reference table, the Caddy/nginx websocket-gateway configs and a
|
||
troubleshooting matrix — lives in two places, kept in sync:
|
||
|
||
- **`web/README.md`** in this tarball (plain markdown)
|
||
- the **"Run without Cockpit" panel** in the web console (system group,
|
||
right under Overview) — every command block has a copy button
|
||
|
||
## 12. The web-edition skin for Cockpit (v0.3.0)
|
||
|
||
Since 0.3.0 the Cockpit plugin pages wear the **web-edition skin** by
|
||
default: every plugin's `index.html` links
|
||
`../sysdeck-common/sysdeck-web.css` after the base stylesheet, porting
|
||
the Next.js console's midnight/teal design (teal accent `#3fc9b0`,
|
||
soft-tinted badges, 10px radii, tabular numerals, thin teal-edged
|
||
scrollbars) onto the classic cockpit panels. Nothing else changes — the
|
||
class vocabulary, the bridge, and every module are untouched.
|
||
|
||
```bash
|
||
# switch the plugin pages back to the classic 0.1.x skin:
|
||
sudo rm /usr/share/cockpit/sysdeck-common/sysdeck-web.css
|
||
|
||
# also theme the Cockpit SHELL chrome (sidebar, header, login) to match:
|
||
sudo make install-branding # backs up any existing branding.css first
|
||
sudo make uninstall-branding # restore the backup
|
||
```
|
||
|
||
`install-branding` installs `shared/branding.css` as
|
||
`/usr/share/cockpit/branding.css` — Cockpit's documented override point
|
||
for the shell. It targets both PatternFly v5 (`pf-v5-*`, Cockpit ≥ 300)
|
||
and v4 (`pf-c-*`) selector generations, so unmatched rules simply no-op.
|
||
|
||
---
|
||
|
||
Author: **Jeremy Anderson** · <info@dcos.net> · <https://dcos.net> · [github.com/dcosnet/SysDeck](https://github.com/dcosnet/SysDeck)
|