Files

7.0 KiB
Raw Permalink Blame History

VM Manager for XigmaNAS (vmmngr)

A OneButton-style extension that puts bhyve / vm-bhyve under the XigmaNAS web GUI: list machines, start/stop them, create new ones, manage ISOs, templates, datastores and switches, and open a console or the graphical screen in the browser.

Status: 0.10.1 – feature-complete for daily use on a single node.


Features

Area What you get
Dashboard all guests with state, loader, vCPU, RAM, datastore, autostart; start/stop/restart inline
VM actions start, stop, restart, reset, power-off, destroy (typed name required, ZFS holds released first)
VM settings edit vCPU, memory, loader, graphics/VNC, network switch and autostart of a stopped VM
Create wizard template, datastore, vCPU/RAM/disk, switch, optional boot ISO, optional virtio-win driver ISO, optional start, optional cloud-init image
Images ISO/IMG inventory, HTTP(S) downloads as jobs, delete with typed confirmation, virtio-win preset
Templates list, edit, duplicate, delete, create from skeleton
Datastores add/remove vm-bhyve datastores, usage column, default cannot be removed
Switches add/remove manual switches on existing host bridges, shows interface and IP
Console serial web terminal (ttyd, token URL) and graphical screen via noVNC/websockify
Setup wizard guided first run: prerequisites, default datastore, first switch
Jobs every mutating action runs as a locked job with log; survives browser reloads; FIFO retention (default 100, clearable)
Config provider selection (auto/system/bundle), after-action behaviour, boot integration check

Requirements

  • XigmaNAS 14.x (amd64), PHP 8.1+, web GUI reachable
  • vm-bhyve 1.6+ — either installed in the system or supplied in vendor/vm-bhyve
  • vmm.ko and nmdm.ko
  • optional: pkg install novnc py312-websockify for the graphical browser console
  • optional: ttyd for the serial web terminal (bundled or from pkg)

The addon never installs or upgrades vm-bhyve itself. vm_source = auto prefers the system installation and only fills gaps from the bundled tree.

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 → Setup and follow the wizard.

From the registry (packaged build)

The release workflow publishes the tarball as an OCI artifact:

oras pull registry.familie-berner.de/xigmanas/vmmngr:latest
tar -xzf vmmngr-*.tar.gz -C /mnt/Daten/extensions/
cd /mnt/Daten/extensions/vmmngr && ./vmm-init -o

First run

Setup walks through three steps:

  1. Check – vm-bhyve, kernel modules, host bridges
  2. Datastore – pick a mounted dataset below /mnt or create one; writes vm_dir and vm_enable to config.xml, applies them to the running system and runs vm init
  3. Switch – create the first manual switch on an existing host bridge

How it works

  • Never overlays. Existing system binaries win; the bundle only fills gaps.
  • One write path. The GUI never calls vm directly – everything goes through bin/vmm-ctl, mutations run as jobs in bin/vmm-jobd.
  • vm-bhyve files are the truth. No second inventory of machines.
  • Config lives in config.xml. /etc/rc.conf and /boot/loader.conf.local are generated from it at boot – direct edits do not survive.
  • Symlinks, no mounts. Only missing targets are linked; vmm-init -p repairs them at every boot (postinit hook).

XigmaNAS traps this addon handles

  • Every POST needs authtoken. auth.inc answers 401 and destroys the session without it. All forms include formend.inc, which emits the field.
  • vm returns rc=0 on refusal. Jobs therefore verify the resulting state (start→running, stop→stopped, destroy→absent) instead of trusting the exit code.
  • vm list -r lists running guests only. Use vm list.
  • Transient states. A booting guest reports bootloader/locked for a while; jobs wait instead of failing.
  • Destroy needs free snapshots. ZFS holds (znapzend/zrepl) are released first and logged.
  • VNC bind 0.0.0.0 is not an address. The connect target is derived from the VM's bridge IP (ix0bridge → 172.16.1.50).

Build & release

./tools/build-package.sh      # -> dist/vmmngr-<version>.tar.gz (+ .sha256)

The Gitea workflow .gitea/workflows/release.yaml runs on tags v* or manually:

  1. builds the tarball
  2. uploads it as a workflow artifact
  3. pushes it as OCI artifact to registry.familie-berner.de/xigmanas/vmmngr:<version> and :latest using oras

Repository secrets (all optional except the credentials):

Secret Default Purpose
REGISTRY registry.familie-berner.de registry host
REGISTRY_REPO xigmanas/vmmngr image path inside the registry
REGISTRY_USER — (required) account with write access to the repository
REGISTRY_TOKEN — (required) password / access token for that account

Unset values fall back to the defaults, so only the two credentials must exist.

Tagging a release:

git tag -a v0.10.1 -m "vmmngr 0.10.1"
git push origin v0.10.1

Layout

vmm-init                 installer/updater/self-heal/uninstaller (-o -u -p -r -s)
bin/vmm-ctl              CLI, single write path (PHP)
bin/vmm-jobd             job runner
bin/vmm-lib.php          shared library (providers, parsers, jobs, console)
gui/                     PHP pages, symlinked into /usr/local/www
gui/ext/vmmngr/menu.inc  Extensions menu entry
vendor/                  bundled binaries for systems without vm-bhyve
tools/build-package.sh   packaging
state/ log/ backup/      runtime data (never shipped, never overwritten by updates)

Licences and attribution

Our code is BSD-2-Clause (LICENSE). The extension only drives third-party software; it does not ship it:

Component Licence bundled?
vm-bhyve BSD-2-Clause only if a vendor/ build is used
bhyve, nmdm BSD-2-Clause (FreeBSD base) no
noVNC MPL-2.0 no (pkg install novnc)
websockify LGPL-3.0 no (pkg install py312-websockify)
ttyd MIT only in a vendor/ build
edk2-bhyve BSD-3-Clause only in a vendor/ build
grub2-bhyve GPL-3.0 only in a vendor/ build — see THIRD-PARTY.md

The release package built by the workflow contains no third-party binaries, so there is nothing to redistribute. tools/build-package.sh --with-vendor exists for embedded systems and ships licence files alongside; using it means you are redistributing those binaries and must honour their terms (notably GPL-3.0 for grub2-bhyve: source or written offer).

Details and consequences: THIRD-PARTY.md.

Uninstall

cd /mnt/Daten/extensions/vmmngr && ./vmm-init -r --yes

Removes symlinks and the directory; VMs, images and datastores are untouched.