nmon/deploy/ansible

Deploying nmon with Ansible

Installs nmon as a systemd service on one Linux host (amd64 or arm64). Tested against Debian 13.

Quick start

cd deploy/ansible
cp inventory.example.ini inventory.ini   # your host
cp vars.example.yml vars.yml             # no sign-in set = the setup wizard runs on first open
ansible-playbook site.yml -e @vars.yml

The first play builds the release binary on your machine (make build build-arm64: needs Go, Node and network). Pass -e nmon_build=false to reuse an existing ./nmon. The second play installs it on the hosts in group nmon:

• /usr/local/bin/nmon, user nmon, data in /var/lib/nmon, key and TLS files in /etc/nmon, backups in /var/backups/nmon
• the MIB sidecar in /usr/share/nmon/mibs, used only by nmon profile new --mib
• optionally the IEEE vendor registry CSVs in /usr/share/nmon/oui, loaded with nmon oui import (nmon_oui_download, nmon_oui_csv_dir; by default nmon fetches the registry itself)
• config.yaml rendered from your vars, and a hardened systemd unit (systemctl reload nmon sends SIGHUP to reload config and certificates)
• net.ipv4.ping_group_range opened so nmon can ping without root

Then open https://<host>:8443/. With no sign-in in vars, nmon starts in install mode and the setup wizard asks for one (anyone who can reach the port can run it until it is done). Otherwise, without OIDC you are sent to /auth/breakglass.

TLS (nmon_tls_mode)

Mode	What it does
selfsigned (default)	Generates a cert on the host. Good for trying it out; browsers will warn.
files	Copies nmon_tls_cert_src / nmon_tls_key_src from the control machine.
acme	Let's Encrypt for nmon_server_name; port 80 must reach the host.
insecure	Plain HTTP. With no sign-in configured, nmon runs in dev-open mode where everyone is admin. Never expose this.

Reverse proxy: nmon can sit behind one. Keep the proxy-to-nmon hop on HTTPS (selfsigned is fine there), set nmon_trusted_proxies to the proxy's addresses, and set the OIDC redirect_url to the public URL. Traps (UDP 162) and Graphite (TCP 2003) go to nmon directly, not through the HTTP proxy.

Sign-in

• Setup wizard: leave nmon_breakglass_password and nmon_oidc unset. The play then writes config.yaml only if it is missing, so later runs keep the sign-in the wizard saved (and ignore other config vars; edit those in the UI).
• OIDC: set nmon_oidc (issuer, client_id, client_secret, admin_group). The secret is stored encrypted with nmon secret set and never written to config.yaml. Browsers go straight to the IdP; there is no login page.
• Break-glass: nmon_breakglass_password is bcrypt-hashed on the host. Use it when the IdP is down. Five wrong attempts lock the source IP for 15 min; run nmon unlock all --data-dir /var/lib/nmon to clear.

After installing

• Back up /etc/nmon/secret.key somewhere safe. Without it, a restore has no SNMP credentials.
• Add devices in the UI or with POST /api/v1/devices, and mint API or push tokens under Settings.
• The playbook owns config.yaml: edits made in the UI are overwritten on the next run, so put lasting settings in vars.
• More: docs/operations.md.