# 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) | | 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-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 ```sh 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: ```sh 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 ```sh ./tools/build-package.sh # -> dist/vmmngr-.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:` and `:latest` using `oras` Required repository secrets: | Secret | Purpose | |---|---| | `REGISTRY_USER` | registry account (needs write access to `xigmanas/vmmngr`) | | `REGISTRY_TOKEN` | password / access token for that account | Tagging a release: ```sh 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 ```sh cd /mnt/Daten/extensions/vmmngr && ./vmm-init -r --yes ``` Removes symlinks and the directory; VMs, images and datastores are untouched.