joulenap/docs/CONFIG-WIZARD.md

Joulenap — Setup wizard & field discovery

How the first-run configuration works. The goal: ask the user as little as possible by discovering most values automatically. The app may ask for root credentials of PVE (and optionally of PBS) at setup; with those it can auto-create its own scoped tokens and install its SSH key, then discard the passwords.

Field discovery (in setup order)

For each field: auto = discovered/derived by the app; manual = must be entered.

1. PVE host/IP — manual (or LAN scan on :8006) — entry point; where to connect.
2. TLS verify on/off — auto — on first connection, if the cert is self-signed → set off.
3. PVE auth (token or user/pass) — manual root once → token auto-created — with root creds the app creates a minimal-privilege token and discards the password.
4. PVE node name — auto — from /nodes.
5. PVE storage id (PBS) — auto — from /storage filtered to type=pbs; user selects.
6. PBS host/IP — auto — read from the PVE storage config.
7. PBS port (8007) — auto — from the storage config (known default).
8. PBS datastore — auto — from the storage config (datastore).
9. PBS fingerprint — auto — from the storage config (fingerprint), or recomputed from the PBS TLS cert.
10. WoL broadcast interface — auto — the app NIC with the route to the PBS subnet (override allowed).
11. PBS MAC (WoL) — auto — with PBS powered on at setup: ping + read ARP on that interface ("Detect MAC" button).
12. PBS API token (GC/status) — in quick setup, auto-created from the PBS root creds and granted the built-in DatastoreAdmin role on the chosen datastore (GC + status) plus the built-in Audit role on /system (read-only node CPU/RAM/network for the dashboard). PBS has no API to create custom roles (unlike PVE), so built-ins are used; the ACL scope keeps them least-privilege. In token mode, entered manually. The password is used once and discarded.
13. PBS SSH host key — auto — before the poweroff key is installed/used, the wizard scans the PBS SSH host key and shows its fingerprint to confirm; on confirmation it's saved to data/known_hosts so every later SSH connection verifies against it.
14. SSH user + key (poweroff) — mixed — user default root; key generated by the app; installed automatically with PBS root, otherwise the user pastes the public key into the PBS authorized_keys.

Tighter PBS privileges (optional): quick setup grants the built-in DatastoreAdmin (PBS can't create custom roles over the API). For a truly minimal token, create a custom role on the PBS host once and bind a token to it, then use Manual setup (token) and paste that token:

proxmox-backup-manager role create Joulenap --privs "Datastore.Audit,Datastore.Modify"
proxmox-backup-manager user generate-token root@pam joulenap
proxmox-backup-manager acl update /datastore/<datastore> Joulenap --auth-id 'root@pam!joulenap'

Security

Transport security uses pinning and verification to protect credentials in transit:

• PBS API (TLS pinning): PBS API calls are pinned to the PBS certificate's fingerprint, captured during setup from the PVE storage config. If the PBS certificate is renewed, run PBS detection again in the wizard to store the new fingerprint; calls will fail with a clear "fingerprint changed" error until updated.
• PBS SSH (host-key verification): The PBS SSH host key is confirmed once during wizard setup and saved to data/known_hosts. All later SSH connections (power-off, GC over SSH) verify against the stored key.
• PVE setup (residual): The PVE root password used in quick-setup provisioning is protected by pve.verify_tls only — no fingerprint is stored. Enable pve.verify_tls if your PVE instance has a valid certificate, or keep the setup network segment trusted (isolated LAN/VPN).

If the user declines both root credentials

Everything above stays auto-discovered with a read token; only these become manual:

• On PVE: create an API token for Joulenap whose role has VM.Audit, VM.Backup, Datastore.Audit, Datastore.AllocateSpace, Datastore.Allocate (the last is required for vzdump's retention/prune, which deletes old backups); copy the secret.
• On PBS: create an API token with DatastoreAdmin on the datastore (status + start GC) and Audit on /system (node CPU/RAM for the dashboard); copy the secret. (The datastore/GC part is skippable if GC runs over SSH.)
• On PBS: install the app's generated SSH public key into /root/.ssh/authorized_keys.
• On PBS (always manual regardless): enable Wake-on-LAN in BIOS + arm it at the OS level (ethtool -s <nic> wol g, persistent).
• In Joulenap: paste the PVE token, paste the PBS token, click "Generate SSH key" + confirm installed, click "Detect MAC".