Archived
beatzaplentyandClaude Sonnet 4.6
24c6469f10
Check NixOS configurations / eval-hosts (pull_request) Successful in 10m40s
Replace per-host host-token.nix imports with a single beszel-token secret in secrets/common.yaml, wired once in enable-agent.nix. Host files now only need services.beszel.agent.environment.KEY — no imports block required. Delete modules/beszel/host-token.nix (no longer referenced anywhere). Action needed: run `sops secrets/common.yaml` and add `beszel-token: <value>` from the beszel hub UI before deploying. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
156 lines
3.8 KiB
Markdown
156 lines
3.8 KiB
Markdown
# Beszel agent
|
|
|
|
[Beszel](https://github.com/henrygd/beszel) is the monitoring dashboard used
|
|
in this LAN. The hub runs as a Docker container on `docker.sweet.home` (port
|
|
`vars.ports.beszelHub`, 8090). Each monitored NixOS host runs a
|
|
`beszel-agent` that connects back to the hub.
|
|
|
|
---
|
|
|
|
## How it works
|
|
|
|
Everything is handled by a single module:
|
|
|
|
**`modules/beszel/enable-agent.nix`** — imported by a build type. It:
|
|
- Enables `beszel-agent`
|
|
- Sets `HUB_URL` to `docker.sweet.home:8090`
|
|
- Reads the universal `beszel-token` from `secrets/common.yaml` via sops and
|
|
passes it to the agent as `TOKEN` in an env file
|
|
- Fixes an upstream bug where the agent couldn't persist its hub-pairing
|
|
fingerprint across restarts (adds a real `StateDirectory`)
|
|
|
|
The only thing a host file ever needs to add is `KEY` — the hub's public key
|
|
for that agent slot, which comes from the beszel hub UI after first pairing.
|
|
|
|
---
|
|
|
|
## Adding beszel to a new build type
|
|
|
|
Add `../beszel/enable-agent.nix` to the `imports` list in
|
|
`modules/build-types/<type>.nix`:
|
|
|
|
```nix
|
|
imports = [
|
|
../beszel/enable-agent.nix
|
|
# ... other imports
|
|
];
|
|
```
|
|
|
|
That's the only build-type change required.
|
|
|
|
---
|
|
|
|
## Wiring the host file
|
|
|
|
No `imports` are needed in the host file. Just set `KEY` once you've paired
|
|
the agent with the hub:
|
|
|
|
```nix
|
|
services.beszel.agent.environment = {
|
|
KEY = "ssh-ed25519 AAAA...";
|
|
};
|
|
```
|
|
|
|
Leave `KEY` commented out until after the first pairing (see "Pairing with
|
|
the hub" below).
|
|
|
|
---
|
|
|
|
## One-time setup: add the token to `secrets/common.yaml`
|
|
|
|
The universal token is stored once in the common secrets file, shared by all
|
|
agents. You only need to do this once, not per-host:
|
|
|
|
```sh
|
|
sops secrets/common.yaml
|
|
```
|
|
|
|
Add:
|
|
```yaml
|
|
beszel-token: <token from the beszel hub UI>
|
|
```
|
|
|
|
The token is found in the beszel hub under **Settings → Keys** or in the
|
|
"Add system" flow.
|
|
|
|
`secrets/common.yaml` is already a sops recipient for every host via their
|
|
SSH host keys, so no additional sops recipient setup is needed for hosts that
|
|
are already provisioned.
|
|
|
|
---
|
|
|
|
## Optional: monitoring extra filesystems
|
|
|
|
To report disk usage for a mount beyond the root filesystem, add
|
|
`EXTRA_FILESYSTEMS` alongside `KEY` in the host file:
|
|
|
|
```nix
|
|
services.beszel.agent.environment = {
|
|
KEY = "ssh-ed25519 AAAA...";
|
|
EXTRA_FILESYSTEMS = "/mnt/data"; # colon-separated for multiple paths
|
|
};
|
|
```
|
|
|
|
The `server` host uses this to expose its ZFS data pool:
|
|
|
|
```nix
|
|
EXTRA_FILESYSTEMS = "${vars.storageRoot}/${vars.nfsShares.dockerVolumes.subpath}";
|
|
```
|
|
|
|
---
|
|
|
|
## Optional: monitoring Docker containers
|
|
|
|
`enable-agent.nix` has a commented-out line for Docker monitoring:
|
|
|
|
```nix
|
|
#DOCKER_HOST = "tcp://docker-socket-proxy:2375";
|
|
```
|
|
|
|
Uncomment it if the host runs docker-socket-proxy and you want per-container
|
|
stats. Hosts without Docker should leave it commented out.
|
|
|
|
---
|
|
|
|
## Pairing with the hub
|
|
|
|
1. Deploy the host with its build type importing `enable-agent.nix`. Leave
|
|
`KEY` unset (commented out) for now.
|
|
2. Open the beszel hub (`http://docker.sweet.home:8090`).
|
|
3. Go to **Systems → Add system**. The new host should appear as an unpaired
|
|
entry — copy the `KEY` value shown there.
|
|
4. In `hosts/<name>/host.nix`, set:
|
|
```nix
|
|
services.beszel.agent.environment.KEY = "<copied key>";
|
|
```
|
|
5. Rebuild and deploy the host. The agent will now pair permanently.
|
|
|
|
---
|
|
|
|
## Example: complete host file
|
|
|
|
Minimal case (`hosts/tor-relay/host.nix` — one filesystem, no Docker, LXC):
|
|
|
|
```nix
|
|
{ vars, ... }:
|
|
{
|
|
networking = { ... };
|
|
|
|
services.beszel.agent.environment = {
|
|
KEY = "ssh-ed25519 AAAA...";
|
|
};
|
|
|
|
system.stateVersion = "26.05";
|
|
}
|
|
```
|
|
|
|
Fuller case (`hosts/server/host.nix` — extra filesystem, debug logging):
|
|
|
|
```nix
|
|
services.beszel.agent.environment = {
|
|
KEY = "ssh-ed25519 AAAA...";
|
|
EXTRA_FILESYSTEMS = "${vars.storageRoot}/${vars.nfsShares.dockerVolumes.subpath}";
|
|
LOG_LEVEL = "debug";
|
|
};
|
|
```
|