System Architecture

OpenNMC is split into a small set of cooperating services.

Main Pieces

Component Role
Buildroot Linux Base userspace and image creation
U-Boot Bootloader and boot slot selection
RAUC Verity-based A/B updates
NUT UPS driver, server, and monitoring stack
OpenNMC service stack Browser UI, HTTP API, root helper, and proxy integration
lighttpd Static frontend and API reverse proxy
ESP32 stack WiFi / Bluetooth transport and factory provisioning

Runtime Topology

  • lighttpd serves the frontend and proxies API requests
  • opennmc-web runs unprivileged as nmcsvc on 127.0.0.1:8080
  • opennmc-helper runs as root
  • the helper and web app communicate over /run/opennmc-helper.sock
  • the local NUT instance listens on the internal loopback path
  • an external NUT proxy listens on 3493 and forwards authenticated clients to the internal UPS daemon
  • NetworkManager handles the network profiles used by the web UI and nmtui
  • the OpenNMC service Buildroot external tree installs the frontend assets, backend code, helper wrapper, defaults, PAM policy, lighttpd config, and SysV init scripts
  • writable web data lives under /userdata/nmcdata
  • logs default to /var/log/opennmc-web.log and /var/log/opennmc-helper.log

Packaged Components

The standard image from the OpenNMC service Buildroot external tree installs:

  • frontend assets under /var/www and /var/www/static
  • the lighttpd config fragment under /etc/lighttpd/conf.d
  • launch wrappers under /usr/bin/opennmc-web and /usr/bin/opennmc-helper
  • backend application code under /usr/lib/opennmc
  • default environment files under /etc/default
  • PAM policy under /etc/pam.d/opennmc
  • SysV init scripts under /etc/init.d

Persistent Data

The image keeps long-lived data in userdata, including:

  • user home directories
  • history database files
  • uploads
  • selected configuration state copied forward during RAUC updates

Boot And Update Model

OpenNMC uses a dual-root layout with RAUC boot control.

  • rootA and rootB are the active application slots
  • bootloader state is stored in eMMC boot0
  • userdata is created on first boot and kept across updates
  • the current slot is marked good after successful boot

See Configuration for the operator-facing tabs and actions, and Firmware Trains for the update trust anchors.

Account Model

  • the bootstrap root account is for console recovery
  • the managed admin user is UID 1000
  • the web interface only accepts local users with UID >= 1000
  • administrator permissions come from membership in wheel