Files
vmmngr/README.md
T

168 lines
7.0 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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-<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:
```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.