homelab-monitor/docs/ssh-collector-key-setup.md

SSH collector key setup

SshHostCollector (apps/api/src/collectors/sshHost.ts) monitors boxes Proxmox can't see — currently omv (192.168.1.180) and ripper (192.168.1.171).

Key

Dedicated ed25519 keypair, generated on CT122 (not reused from any personal key): /opt/homelab-monitor/ssh/monitor_ed25519{,.pub}, mounted read-only into the api container at SSH_PRIVATE_KEY_PATH (see .env.example).

Forced command (defense in depth)

Each remote authorized_keys entry sets command="...",no-pty,no-port-forwarding,... so the server ignores whatever command the client requests and always runs a fixed read-only script instead. A leaked key can only ever produce these stats — not shell access, not other commands.

• omv:/root/.ssh/monitor-readonly.sh
• ripper:/home/jhodgkin/.ssh/monitor-readonly.sh

Each script emits NPROC=, LOAD1=, MEMLINE=total:used, UPTIME=, and one DISK_<label>=size:used line per monitored path.

This means diskPaths in config/hosts.yaml is descriptive, not authoritative — adding a new disk path there does nothing until the matching DISK_<label>=... line is added to the remote script too. Keep them in sync by hand; there are only two hosts, so this hasn't been worth automating yet.

Adding a new SSH-monitored host

1. Generate nothing new — reuse the existing monitor_ed25519 keypair.
2. On the target host, create ~/.ssh/monitor-readonly.sh (copy an existing one, adjust disk paths).
3. Append to that user's authorized_keys: command="/path/to/monitor-readonly.sh",no-port-forwarding,no-X11-forwarding,no-agent-forwarding,no-pty <pubkey>
4. Add an entry under sshHosts in config/hosts.yaml.