docs: rewrite README and add CHANGELOG; build: package script and Gitea release workflow pushing to registry.familie-berner.de

This commit is contained in:
Claw committed 2026-11-17 21:21:46 +01:00
1 parent 9feb3fba86
commit d8bf6ff475
5 files changed
+321 -41

No files matched your search

+115 -41
View File
@@ -1,22 +1,39 @@
# VM Manager for XigmaNAS (vmmngr)
A OneButton-style extension that manages bhyve guests through **vm-bhyve** from the
XigmaNAS web GUI: list, inspect, start/stop, create, images, templates, switches.
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.1.0-preview — read-only**. The dashboard lists and inspects existing
machines. Mutating actions arrive with the job engine in 1.0.
Status: **0.10.1** – feature-complete for daily use on a single node.
## Layout
---
```
vmm-init installer / updater / self-heal / uninstaller
bin/vmm-ctl single write path to vm-bhyve (PHP CLI)
bin/vmm-lib.php shared library (provider resolution, parsers)
gui/ PHP pages, symlinked into /usr/local/www
gui/ext/vmmngr/menu.inc Extensions menu entry
vendor/ bundled binaries for embedded systems (optional)
state/ log/ backup/ runtime data, never touched by updates
```
## 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 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
@@ -26,40 +43,97 @@ 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**.
Then open **Extensions → VM Manager → Setup** and follow the wizard.
## XigmaNAS specifics worth knowing
### From the registry (packaged build)
- **Every POST needs an authtoken.** `auth.inc` rejects POSTs without a valid
`authtoken` field with `401` *and destroys the session*. Always
`include 'formend.inc';` inside a form - it emits the hidden field.
- **`/etc/rc.conf` is generated from `/conf/config.xml`** at boot; `sysrc`
changes do not survive. Persist via rc params in the config.
- **PHP runs as root** (lighttpd spawns php-cgi), so the code must be strict
about input handling - all `vm` calls go through `vmm-ctl`.
- **Embedded platforms** keep `/` in RAM: binaries belong in `vendor/`, only
symlinks go into the system, repaired by `vmm-init -p` at boot.
## Design rules
- **Never overlay.** An existing system installation always wins; the bundle only
fills gaps (embedded systems). `vm_source = auto | system | bundle`.
- **One write path.** The GUI never calls `vm` directly, only `vmm-ctl`.
- **vm-bhyve files are the truth.** No second database of VMs.
- **Symlinks, no mounts.** Only missing targets are linked; `-p` repairs them at boot.
- **Long operations become jobs** with per-VM locks (1.0).
## Commands
The release workflow publishes the tarball as an OCI artifact:
```sh
vmm-ctl selfcheck # environment, providers, firmware, modules
vmm-ctl list # all guests
vmm-ctl info <vm> # parsed details
vmm-ctl --json selfcheck # same as JSON
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
./vmm-init -r --yes # removes links only; VMs and datastores stay
cd /mnt/Daten/extensions/vmmngr && ./vmm-init -r --yes
```
Removes symlinks and the directory; VMs, images and datastores are untouched.