5.9 KiB
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 |
| Config | provider selection (auto/system/bundle), after-action behaviour, boot integration check |
Requirements
- XigmaNAS 14.x (amd64), PHP 8.1+, web GUI reachable
vm-bhyve1.6+ — either installed in the system or supplied invendor/vm-bhyvevmm.koandnmdm.ko- optional:
pkg install novnc py312-websockifyfor the graphical browser console - optional:
ttydfor 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:
- Check – vm-bhyve, kernel modules, host bridges
- Datastore – pick a mounted dataset below
/mntor create one; writesvm_dirandvm_enabletoconfig.xml, applies them to the running system and runsvm init - Switch – create the first
manualswitch 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
vmdirectly – everything goes throughbin/vmm-ctl, mutations run as jobs inbin/vmm-jobd. - vm-bhyve files are the truth. No second inventory of machines.
- Config lives in
config.xml./etc/rc.confand/boot/loader.conf.localare generated from it at boot – direct edits do not survive. - Symlinks, no mounts. Only missing targets are linked;
vmm-init -prepairs them at every boot (postinit hook).
XigmaNAS traps this addon handles
- Every POST needs
authtoken.auth.incanswers401and destroys the session without it. All forms includeformend.inc, which emits the field. vmreturns rc=0 on refusal. Jobs therefore verify the resulting state (start→running,stop→stopped,destroy→absent) instead of trusting the exit code.vm list -rlists running guests only. Usevm list.- Transient states. A booting guest reports
bootloader/lockedfor 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.0is 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:
- builds the tarball
- uploads it as a workflow artifact
- pushes it as OCI artifact to
registry.familie-berner.de/xigmanas/vmmngr:<version>and:latestusingoras
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)
Uninstall
cd /mnt/Daten/extensions/vmmngr && ./vmm-init -r --yes
Removes symlinks and the directory; VMs, images and datastores are untouched.