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
@@ -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"
|
||||
@@ -3,3 +3,4 @@ state/*
|
||||
backup/*
|
||||
vendor/*/*
|
||||
!vendor/.gitkeep
|
||||
dist/
|
||||
@@ -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 `<system><loaderconf>`
|
||||
(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-<vm>.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.
|
||||
@@ -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.
|
||||
Executable
+56
@@ -0,0 +1,56 @@
|
||||
#!/bin/sh
|
||||
# build-package.sh - create the distributable extension tarball.
|
||||
#
|
||||
# Usage: tools/build-package.sh [--version <ver>]
|
||||
# Output: dist/vmmngr-<version>.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"
|
||||
Reference in new issue
Block a user