Files
vmmngr/README.md
T

2.5 KiB

VM Manager for XigmaNAS (vmmngr)

A OneButton-style extension that manages bhyve guests through vm-bhyve from the XigmaNAS web GUI: list, inspect, start/stop, create, images, templates, switches.

Status: 0.1.0-preview — read-only. The dashboard lists and inspects existing machines. Mutating actions arrive with the job engine in 1.0.

Layout

vmm-init                     installer / updater / self-heal / uninstaller
bin/vmm-ctl                  single write path to vm-bhyve (PHP CLI)
bin/vmm-lib.php              shared library (provider resolution, parsers)
gui/                         PHP pages, symlinked into /usr/local/www
gui/ext/vmmngr/menu.inc      Extensions menu entry
vendor/                      bundled binaries for embedded systems (optional)
state/ log/ backup/          runtime data, never touched by updates

Install

mkdir -p -m 0750 /mnt/Daten/extensions/vmmngr && cd /mnt/Daten/extensions/vmmngr
fetch https://git.familie-berner.de/Xigmanas/vmmngr/raw/branch/main/vmm-init
chmod +x vmm-init && ./vmm-init -o

Then open Extensions → VM Manager.

XigmaNAS specifics worth knowing

  • Every POST needs an authtoken. auth.inc rejects POSTs without a valid authtoken field with 401 and destroys the session. Always include 'formend.inc'; inside a form - it emits the hidden field.
  • /etc/rc.conf is generated from /conf/config.xml at boot; sysrc changes do not survive. Persist via rc params in the config.
  • PHP runs as root (lighttpd spawns php-cgi), so the code must be strict about input handling - all vm calls go through vmm-ctl.
  • Embedded platforms keep / in RAM: binaries belong in vendor/, only symlinks go into the system, repaired by vmm-init -p at boot.

Design rules

  • Never overlay. An existing system installation always wins; the bundle only fills gaps (embedded systems). vm_source = auto | system | bundle.
  • One write path. The GUI never calls vm directly, only vmm-ctl.
  • vm-bhyve files are the truth. No second database of VMs.
  • Symlinks, no mounts. Only missing targets are linked; -p repairs them at boot.
  • Long operations become jobs with per-VM locks (1.0).

Commands

vmm-ctl selfcheck          # environment, providers, firmware, modules
vmm-ctl list               # all guests
vmm-ctl info <vm>          # parsed details
vmm-ctl --json selfcheck   # same as JSON

Uninstall

./vmm-init -r --yes        # removes links only; VMs and datastores stay