Files
vmmngr/README.md
T

66 lines
2.5 KiB
Markdown

# 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.
Status: **0.1.0-preview — read-only**. The dashboard lists and inspects existing
machines. Mutating actions arrive with the job engine in 1.0.
## 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
```
## 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**.
## XigmaNAS specifics worth knowing
- **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
```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
```
## Uninstall
```sh
./vmm-init -r --yes # removes links only; VMs and datastores stay
```