141 lines
5.6 KiB
Markdown
141 lines
5.6 KiB
Markdown
# 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-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-<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`
|
||
|
||
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.
|