docs: rewrite README and add CHANGELOG; build: package script and Gitea release workflow pushing to registry.familie-berner.de
This commit is contained in:
1 parent
9feb3fba86
commit
d8bf6ff475
5 files changed
+321
-41
No files matched your search
@@ -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.
|
||||
Reference in new issue
Block a user