# 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 ```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` 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: ```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) ``` ## 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`](THIRD-PARTY.md). ## Uninstall ```sh cd /mnt/Daten/extensions/vmmngr && ./vmm-init -r --yes ``` Removes symlinks and the directory; VMs, images and datastores are untouched.