Set up

Terminal and networks

An SSH shell on your Proxmox guests from your iPhone, without an SSH key on the phone, and the devices on your networks with their open ports.

The terminal

The board makes the SSH connection with its own key and passes it to the app over a WebSocket. The phone holds no SSH key and needs no route to your hosts. You pick the hosts with a Proxmox tag.

You need the Proxmox connection first.

1. Name the admins and the tag

Only members of oidc.groups.admins may open a terminal; without that group the terminal stays off.

oidc:
  groups:
    admins: admins
connections:
  proxmox:
    url: https://pve.example.com:8006
    token_file: /secrets/proxmox_token
    terminal_tag: terminal

2. Get the board's public key

Restart the board. On its first start with the terminal on, it makes an ed25519 key in data/alertboard/ssh_key and logs the public half:

docker compose restart alertboard
docker compose logs alertboard | grep public_key

The app shows it too, under More › Terminal, with a Copy button. The key stays the same across restarts and updates.

3. Let the board in on each host

Create the user the board logs in as, pidashboard, and allow the board's key, from the board's address only:

useradd -m -s /bin/bash pidashboard
install -d -m 700 -o pidashboard -g pidashboard ~pidashboard/.ssh
echo 'restrict,pty,from="<board address>" ssh-ed25519 AAAA… pidashboard' > ~pidashboard/.ssh/authorized_keys
chown pidashboard: ~pidashboard/.ssh/authorized_keys && chmod 600 ~pidashboard/.ssh/authorized_keys

Give pidashboard only the rights an admin's shell should have there. sudo, if any, is your choice per host.

4. Tag the guest in Proxmox

Give the VM or container the tag (any existing tag works). Within 10 minutes the app lists it by its Proxmox name, at:

• a VM: the address its QEMU guest agent reports, when the board may read it (below); else its cloud-init ipconfigN address;
• a container: its configured ip=, else the address it has now.

An address counts only inside a network the board knows (below), so a guest can't point the board somewhere else. A host listed as “no address in a scanned network” reported an address outside them: add its network under scan.networks or in the app.

Guest agent addresses on Proxmox 9 (optional): a role with only VM.GuestAgent.Audit, per tagged VM, lets the board use the address the agent reports. The board never asks for rights that can read files or run commands in a guest.

pveum role add PidashboardAgent --privs VM.GuestAgent.Audit
pveum acl modify /vms/<vmid> --users pidashboard@pve --roles PidashboardAgent

5. Confirm the host's key

The first time, the app shows the SHA256 fingerprint of the host key the board scanned. Compare it on the host's own console:

ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub                       # a VM
pct exec <vmid> -- ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub     # a container, on its node

If they match, tap Confirm key (Face ID). The host is refused until then, and refused again if its key changes later, until an admin confirms the new one.

Using it

More › Terminal, pick a host and pass Face ID. You get a full terminal with xterm colours and a key row with Esc, Tab, Ctrl, the arrows, Paste and Copy. A session ends when the app goes to the background, after 15 idle minutes or after 2 hours. Opening one needs a login of at most 5 minutes.

Networks

The board finds what is on your networks and the app lists the devices under More › Networks: address, name, open ports (SSH, web UI, Proxmox, Home Assistant, a NAS, …) and whether the last scan saw them. Tap a web port to open it. It scans, in this order:

1. the networks under scan.networks in config.yaml;
2. the networks an admin added in the app (More › Networks, +);
3. with a Proxmox connection, the IPv4 subnets of the nodes' bridges and SDN vnets, plus the guests' own.

scan:
  networks:                  # scanned besides the ones from Proxmox
    - name: servers
      cidr: 192.168.50.0/24  # IPv4, /22 or smaller, the network address
  exclude:                   # found in Proxmox, but not scanned
    - 192.168.99.0/24

• Each network is /22 or smaller, and at most sixteen /24s' worth are scanned. Past that the last ones in the order above are skipped, so a network you added by hand is never the one left out.
• Each is scanned every 10 minutes on 12 common homelab ports. Pull down in the app to scan again.
• A VLAN on a trunk bridge without an address of its own is not found in Proxmox: add it under scan.networks or in the app.
• In the app, admins may add private ranges only; list any other in config.yaml. Networks from config.yaml can't be changed in the app.
• A device that drops every connection (a strict firewall) stays unseen. A device unseen for 7 days is dropped.