104 lines
3.1 KiB
Markdown
104 lines
3.1 KiB
Markdown
# Agent Install (per Proxmox host)
|
|
|
|
## Prerequisites on the Proxmox host
|
|
|
|
- Proxmox VE 8.3+ (OpenZFS 2.3+ for the `-j` flags on `zpool`/`zfs`)
|
|
- Root SSH access
|
|
- Outbound HTTPS to the monitor server
|
|
|
|
No Erlang or Elixir needed — the Burrito binary ships its own runtime.
|
|
|
|
## 1. Build the binary (operator workstation)
|
|
|
|
```bash
|
|
cd proxmox_monitor/agent
|
|
./scripts/build-linux.sh # requires Docker
|
|
ls dist/
|
|
# proxmox-monitor-agent_linux_amd64
|
|
# proxmox-monitor-agent_linux_arm64
|
|
```
|
|
|
|
## 2. Register the host in the dashboard
|
|
|
|
From the dashboard at `https://monitor.example.com/admin/hosts`:
|
|
|
|
1. "Register a new host" → enter the short name (e.g. `pve-host-01`).
|
|
2. Copy the one-time token shown.
|
|
|
|
## 3. Copy files to the Proxmox host
|
|
|
|
```bash
|
|
HOST=pve-host-01
|
|
scp dist/proxmox-monitor-agent_linux_amd64 \
|
|
root@$HOST:/usr/local/bin/proxmox-monitor-agent
|
|
ssh root@$HOST 'chmod 0755 /usr/local/bin/proxmox-monitor-agent'
|
|
|
|
# systemd unit (included in the repo)
|
|
scp rel/proxmox-monitor-agent.service \
|
|
root@$HOST:/etc/systemd/system/
|
|
```
|
|
|
|
## 4. Write the config
|
|
|
|
On the Proxmox host:
|
|
|
|
```bash
|
|
install -d -m 0700 /etc/proxmox-monitor
|
|
cat > /etc/proxmox-monitor/agent.toml <<EOF
|
|
server_url = "wss://monitor.example.com/socket/websocket"
|
|
token = "<paste-token-from-dashboard>"
|
|
host_id = "pve-host-01"
|
|
|
|
[intervals]
|
|
fast_seconds = 30
|
|
medium_seconds = 300
|
|
slow_seconds = 1800
|
|
EOF
|
|
chmod 0600 /etc/proxmox-monitor/agent.toml
|
|
```
|
|
|
|
## 5. Enable the service
|
|
|
|
```bash
|
|
install -d -m 0700 /var/cache/proxmox-monitor-agent
|
|
systemctl daemon-reload
|
|
systemctl enable --now proxmox-monitor-agent
|
|
journalctl -u proxmox-monitor-agent -f
|
|
```
|
|
|
|
Expected within ~10s:
|
|
```
|
|
agent: starting with host_id=pve-host-01
|
|
reporter: connected, joining host:pve-host-01
|
|
reporter: joined host:pve-host-01
|
|
```
|
|
|
|
The host's card on the dashboard should flip to `online`.
|
|
|
|
## 6. Token rotation
|
|
|
|
If a token leaks: dashboard → Admin → "Rotate". Copy the new token, update
|
|
`/etc/proxmox-monitor/agent.toml` on the affected host, `systemctl restart
|
|
proxmox-monitor-agent`. Old token is invalidated immediately.
|
|
|
|
## 7. Upgrade flow
|
|
|
|
```bash
|
|
# operator
|
|
./scripts/build-linux.sh
|
|
scp dist/proxmox-monitor-agent_linux_amd64 root@$HOST:/usr/local/bin/proxmox-monitor-agent.new
|
|
|
|
# on the host
|
|
mv /usr/local/bin/proxmox-monitor-agent{.new,}
|
|
systemctl restart proxmox-monitor-agent
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
| Symptom | Check |
|
|
|------------------------------------------|-----------------------------------------------------------------|
|
|
| `enoent` errors for `zpool`/`pvesh` | You're not on a Proxmox host, or binaries aren't in `$PATH`. |
|
|
| `handshake_failed: :nxdomain` | DNS for the monitor hostname fails from this host. |
|
|
| `unknown_host` rejection on join | Host name in `agent.toml` doesn't match the dashboard entry. |
|
|
| `invalid_token` rejection | Token was rotated; paste the new one. |
|
|
| Agent reconnects every 30s | Server's WebSocket timeout hit — check Caddy `read_timeout 90s`.|
|