diff --git a/.gitea/workflows/release.yaml b/.gitea/workflows/release.yaml new file mode 100644 index 0000000..9c17a51 --- /dev/null +++ b/.gitea/workflows/release.yaml @@ -0,0 +1,69 @@ +name: release + +on: + push: + tags: + - 'v*' + workflow_dispatch: + +jobs: + build-and-push: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Build package + run: | + chmod +x tools/build-package.sh + ./tools/build-package.sh + cat version.txt + + - name: Upload workflow artifact + uses: actions/upload-artifact@v4 + with: + name: vmmngr-package + path: dist/ + + - name: Install oras + run: | + curl -sSL -o /tmp/oras.tgz \ + https://github.com/oras-project/oras/releases/download/v1.2.0/oras_1.2.0_linux_amd64.tar.gz + tar -xzf /tmp/oras.tgz -C /tmp oras + sudo install -m 0755 /tmp/oras /usr/local/bin/oras + oras version + + - name: Push to registry + env: + REGISTRY: registry.familie-berner.de + REGISTRY_USER: ${{ secrets.REGISTRY_USER }} + REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }} + run: | + set -eu + VERSION=$(cat version.txt | tr -d '\n') + PKG=$(ls dist/vmmngr-*.tar.gz | head -1) + PKG_SUM="${PKG}.sha256" + MEDIA="application/vnd.xigmanas.vmmngr.layer.v1.tar+gzip" + + echo "$REGISTRY_TOKEN" | oras login "$REGISTRY" -u "$REGISTRY_USER" --password-stdin + + for TAG in "$VERSION" latest; do + echo "pushing $REGISTRY/xigmanas/vmmngr:$TAG" + oras push "$REGISTRY/xigmanas/vmmngr:$TAG" \ + --artifact-type application/vnd.xigmanas.extension.v1 \ + "$PKG:$MEDIA" \ + "$PKG_SUM:application/vnd.xigmanas.sha256" \ + --annotation "org.opencontainers.image.version=$VERSION" \ + --annotation "org.opencontainers.image.title=vmmngr" + done + + - name: Summary + run: | + VERSION=$(cat version.txt | tr -d '\n') + { + echo "### vmmngr ${VERSION}" + echo "" + echo "Package: \`dist/vmmngr-${VERSION}.tar.gz\`" + echo "" + echo "Pull: \`oras pull registry.familie-berner.de/xigmanas/vmmngr:${VERSION}\`" + } >> "$GITHUB_STEP_SUMMARY" diff --git a/.gitignore b/.gitignore index 33cc6b3..cf8bc96 100644 --- a/.gitignore +++ b/.gitignore @@ -3,3 +3,4 @@ state/* backup/* vendor/*/* !vendor/.gitkeep +dist/ diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..2c4f79e --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,80 @@ +# Changelog + +All notable changes to the VM Manager extension. + +## 0.10.1 +- Create wizard: pick an ISO from `.iso`, download one inline by URL, optional + "start right after create" (ISO is attached as CD before boot). + +## 0.10.0 +- Guided setup wizard (`Setup`): prerequisite check, default datastore + (`vm_dir`/`vm_enable` written to config.xml + `vm init`), first switch. +- Dashboard shows a hint while the setup is incomplete. + +## 0.9.0 +- Switch editor: list/add/remove `manual` switches on existing host bridges, + shows interface and IP, refuses removal while VMs use the switch. + +## 0.8.1 +- Create wizard: switch dropdown shows type, interface and IP; the chosen + switch is written into the new VM config (previously ignored). + +## 0.8.0 +- Datastore management: add/remove, usage column, default protected. + +## 0.7.2 +- Boot integration reads/writes loader.conf entries under `` + (they were reported as missing). + +## 0.7.1 +- Dashboard tab stays clickable on the VM detail page. + +## 0.7.0 +- Setting `after_action`: stay on the page with a job status line (default) or + jump to the job log; settings saved from the Configuration page. + +## 0.6.1 +- Serial web console uses a random base path token instead of basic auth, so the + embedded frame no longer triggers a browser login dialog. + +## 0.6.0 +- noVNC support: websockify serves the VM's VNC screen in the browser, with an + embedded frame; stopped together with the guest. + +## 0.5.0 +- Serial web console per VM via ttyd on `/dev/nmdm-.1B`, auto-stopped with + the guest. + +## 0.4.3 +- VNC connect target derived from the VM's bridge IP instead of the host name. + +## 0.4.1 +- Detail page POSTs keep the VM name (actions no longer bounced to the dashboard). + +## 0.4.0 +- ISO install: attach boot ISO and optional virtio-win driver ISO as CD devices, + eject again; virtio-win download preset. + +## 0.3.3 +- Jobs may carry their own argv (create), zero timeouts fixed, graceful stop + waits for ACPI, template name without `.conf`. + +## 0.3.0 +- Clickable breadcrumb plus tab navigation. +- Images page (download/delete), templates page (CRUD + editor), create wizard. + +## 0.2.3 +- Forms include `formend.inc` (XigmaNAS requires `authtoken` on POST, otherwise + 401 + session loss). + +## 0.2.1 +- Jobs spawn the CLI PHP binary; API errors are logged; ZFS holds are released + before destroy. + +## 0.2.0 +- Job engine with per-VM locks, logs and recovery. +- VM actions: start, stop, restart, reset, power-off, destroy. +- Theme-aware styling (no hardcoded dark panels). + +## 0.1.0 +- Read-only preview: dashboard, VM details, environment self-check. diff --git a/README.md b/README.md index bd37144..d610504 100644 --- a/README.md +++ b/README.md @@ -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 # 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-.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:` + 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. diff --git a/tools/build-package.sh b/tools/build-package.sh new file mode 100755 index 0000000..c73ed85 --- /dev/null +++ b/tools/build-package.sh @@ -0,0 +1,56 @@ +#!/bin/sh +# build-package.sh - create the distributable extension tarball. +# +# Usage: tools/build-package.sh [--version ] +# Output: dist/vmmngr-.tar.gz (+ .sha256) + +set -eu + +ROOT=$(cd "$(dirname "$0")/.." && pwd -P) +cd "${ROOT}" + +VERSION=$(cat version.txt 2>/dev/null | tr -d '\n') +if [ "${1:-}" = "--version" ]; then + VERSION="$2" +fi +[ -n "${VERSION}" ] || { echo "version.txt missing or empty" >&2; exit 1; } + +NAME="vmmngr-${VERSION}" +STAGE="dist/${NAME}" + +rm -rf "${STAGE}" +mkdir -p "${STAGE}" dist + +# code and metadata (state/log/backup are runtime data and never shipped) +cp -R bin gui templates "${STAGE}/" +cp vmm-init version.txt README.md CHANGELOG.md "${STAGE}/" 2>/dev/null || true +[ -f LICENSE ] && cp LICENSE "${STAGE}/" + +# bundled binaries (only when present) +if [ -d vendor ]; then + mkdir -p "${STAGE}/vendor" + for d in vendor/*/; do + [ -d "$d" ] || continue + cp -R "$d" "${STAGE}/vendor/" + done + find "${STAGE}/vendor" -name '.gitkeep' -delete +fi + +find "${STAGE}" -name '.gitignore' -delete +find "${STAGE}" -name '.DS_Store' -delete + +chmod 0755 "${STAGE}" 2>/dev/null || true +chmod 0555 "${STAGE}/vmm-init" 2>/dev/null || true +find "${STAGE}/bin" -type f -exec chmod 0555 {} \; 2>/dev/null || true + +tar -czf "dist/${NAME}.tar.gz" -C dist "${NAME}" +rm -rf "${STAGE}" + +if command -v sha256sum >/dev/null 2>&1; then + (cd dist && sha256sum "${NAME}.tar.gz" > "${NAME}.tar.gz.sha256") +elif command -v shasum >/dev/null 2>&1; then + (cd dist && shasum -a 256 "${NAME}.tar.gz" > "${NAME}.tar.gz.sha256") +fi + +echo "built dist/${NAME}.tar.gz" +ls -l "dist/${NAME}.tar.gz"