Skip to main content

Libvirt

@bad-at-naming/libvirtv2026.10.25.10· MIT AND Apache-2.0· 27d agoBEHAVIORS
01README

Comprehensive libvirt/virsh management — VMs, networks, storage pools, volumes, snapshots, and host info — over SSH OR locally via a connection URI.

Connection modes (per model instance):

  • SSH mode: set host (+ optional user) and virsh runs on the remote hypervisor over ssh. No local libvirt client needed.
  • Local/URI mode: omit host and virsh runs on the swamp host against uri (default qemu:///system; supports qemu+ssh://, qemu+tls://, qemu:///session, etc.).

Models:

  • @bad-at-naming/libvirt/vm — domain lifecycle, tuning, monitoring, snapshots, guest agent, provisioning from cloud images (cloud-init seed built in TypeScript, no virt-install), connection facts, and a desired-state plan/sync reconciler
  • @bad-at-naming/libvirt/network — virtual network lifecycle + DHCP leases
  • @bad-at-naming/libvirt/storage — storage pool and volume management
  • @bad-at-naming/libvirt/host — hypervisor host info, capabilities, node stats

Local/URI connection support is merged from @evrardjp's fork (github.com/evrardjp/swamp-local-libvirt) — see README for credit.

02Release Notes

2026.10.25.10

  • Repo-wide republish; no functional change.
03Behaviors4
@bad-at-naming/libvirt/vmv2026.10.25.10extensions/models/libvirt_vm.ts

Global Arguments

ArgumentTypeDescription
host?stringSSH host/IP of the libvirt hypervisor. If set, virsh runs there over SSH. Omit for local/URI mode.
user?stringSSH username (SSH mode only; default: root)
uri?stringLibvirt connection URI. Local mode (no host) defaults to qemu:///system; in SSH mode it is passed to the remote virsh via -c when set.
fn list()
List all VMs with state, vCPUs, memory, and autostart
fn get(name: string)
Get detailed VM info including disks, NICs, and graphics
ArgumentTypeDescription
namestringVM name
fn dumpxml(name: string)
Get raw XML definition of a VM
ArgumentTypeDescription
namestringVM name
fn start(name: string)
Start a VM. Idempotent — succeeds if already running.
ArgumentTypeDescription
namestringVM name
fn stop(name: string)
Gracefully shut down a VM (ACPI) and wait until it is actually shut off before returning. Idempotent — succeeds if already stopped.
ArgumentTypeDescription
namestringVM name
fn forceStop(name: string)
Force stop a VM (pull the power cord). Idempotent — succeeds if already stopped.
ArgumentTypeDescription
namestringVM name
fn restart(name: string)
Reboot a running VM
ArgumentTypeDescription
namestringVM name
fn reset(name: string)
Hard reset a VM (no ACPI, immediate reset)
ArgumentTypeDescription
namestringVM name
fn suspend(name: string)
Suspend (pause) a running VM
ArgumentTypeDescription
namestringVM name
fn resume(name: string)
Resume a suspended (paused) VM
ArgumentTypeDescription
namestringVM name
fn autostart(name: string, enabled: boolean)
Enable or disable autostart for a VM
ArgumentTypeDescription
namestringVM name
enabledbooleantrue to enable, false to disable
fn define(xml: string)
Define a VM from XML. Idempotent: undefines an existing domain of the same name first, then redefines.
ArgumentTypeDescription
xmlstringFull libvirt domain XML definition
fn undefine(name: string, removeStorage?: boolean, snapshotsMetadata?: boolean, nvram?: boolean)
Undefine a VM (remove its persistent configuration)
ArgumentTypeDescription
namestringVM name
removeStorage?booleanAlso remove all associated storage volumes
snapshotsMetadata?booleanAlso remove snapshot metadata
nvram?booleanAlso remove NVRAM file (required for UEFI VMs)
fn rename(name: string, newName: string)
Rename a VM (must be shut off)
ArgumentTypeDescription
namestringCurrent VM name
newNamestringNew VM name
fn save(name: string, file: string)
Save VM state to a file (like hibernate)
ArgumentTypeDescription
namestringVM name
filestringPath on hypervisor to save state to
fn restore(file: string)
Restore a VM from a saved state file
ArgumentTypeDescription
filestringPath on hypervisor to restore from
fn setVcpus(name: string, count: number, maximum?: boolean, config?: boolean, live?: boolean)
Change the number of virtual CPUs
ArgumentTypeDescription
namestringVM name
countnumberNumber of vCPUs
maximum?booleanSet maximum vCPU count instead of current
config?booleanApply to persistent config (next boot)
live?booleanApply to running VM (hotplug)
fn setMemory(name: string, sizeMB: number, maximum?: boolean, config?: boolean, live?: boolean)
Change memory allocation (in MiB)
ArgumentTypeDescription
namestringVM name
sizeMBnumberMemory in MiB
maximum?booleanSet maximum memory instead of current
config?booleanApply to persistent config
live?booleanApply to running VM
fn attachDisk(name: string, source: string, target: string, driver?: enum, cache?: enum, persistent?: boolean, config?: boolean)
Attach a disk device to a VM
ArgumentTypeDescription
namestringVM name
sourcestringDisk source path (image file or block device)
targetstringTarget device name (e.g. vdb, sdb)
driver?enumDisk driver/format
cache?enumCache mode
persistent?booleanMake change persistent across reboots (running VMs)
config?booleanApply to persistent config only (stopped VMs)
fn detachDisk(name: string, target: string, persistent?: boolean, config?: boolean)
Detach a disk device from a VM. Idempotent: succeeds if disk not found.
ArgumentTypeDescription
namestringVM name
targetstringTarget device name to detach (e.g. vdb)
persistent?booleanMake change persistent (running VMs)
config?booleanApply to persistent config only (stopped VMs)
fn attachInterface(name: string, type: enum, source: string, model?: string, persistent?: boolean)
Attach a network interface to a VM
ArgumentTypeDescription
namestringVM name
typeenumInterface type
sourcestringSource bridge/network name (e.g. br0, default)
model?stringNIC model (virtio, e1000, rtl8139)
persistent?booleanMake change persistent
fn detachInterface(name: string, type: enum, mac: string, persistent?: boolean)
Detach a network interface from a VM by MAC address
ArgumentTypeDescription
namestringVM name
typeenumInterface type
macstringMAC address of the interface to detach
persistent?booleanMake change persistent
fn changeMedia(name: string, target: string, source?: string)
Change CD/DVD media for a VM
ArgumentTypeDescription
namestringVM name
targetstringTarget device (e.g. hda, sda)
source?stringNew ISO path (omit to eject)
fn blockList(name: string)
List all block devices for a VM
ArgumentTypeDescription
namestringVM name
fn interfaceList(name: string)
List all network interfaces for a VM
ArgumentTypeDescription
namestringVM name
fn interfaceAddresses(name: string, source?: enum)
Get IP addresses of a VM's interfaces
ArgumentTypeDescription
namestringVM name
source?enumAddress source: lease (DHCP), agent (guest-agent), arp
fn blockStats(name: string, device?: string)
Get block device I/O statistics for a VM
ArgumentTypeDescription
namestringVM name
device?stringSpecific block device (e.g. vda). Omit for all.
fn interfaceStats(name: string, interface: string)
Get network interface statistics for a VM
ArgumentTypeDescription
namestringVM name
interfacestringInterface device name (e.g. vnet0)
fn memoryStats(name: string)
Get memory statistics for a VM
ArgumentTypeDescription
namestringVM name
fn cpuStats(name: string)
Get CPU statistics for a VM
ArgumentTypeDescription
namestringVM name
fn domstats(name: string)
Get comprehensive statistics for a VM (state, CPU, balloon, vCPU, net, block)
ArgumentTypeDescription
namestringVM name
fn snapshotList(name: string)
List all snapshots for a VM
ArgumentTypeDescription
namestringVM name
fn snapshotCreate(name: string, snapshotName: string, description?: string, quiesce?: boolean, diskOnly?: boolean)
Create a snapshot of a VM
ArgumentTypeDescription
namestringVM name
snapshotNamestringName for the snapshot
description?stringSnapshot description
quiesce?booleanQuiesce guest filesystem (requires guest agent)
diskOnly?booleanDisk-only snapshot (no memory)
fn snapshotInfo(name: string, snapshotName: string)
Get info about a specific snapshot
ArgumentTypeDescription
namestringVM name
snapshotNamestringSnapshot name
fn snapshotRevert(name: string, snapshotName: string, running?: boolean, paused?: boolean)
Revert a VM to a snapshot
ArgumentTypeDescription
namestringVM name
snapshotNamestringSnapshot name to revert to
running?booleanStart VM after revert
paused?booleanLeave VM paused after revert
fn snapshotDelete(name: string, snapshotName: string, children?: boolean)
Delete a snapshot
ArgumentTypeDescription
namestringVM name
snapshotNamestringSnapshot name to delete
children?booleanAlso delete child snapshots
fn snapshotDumpxml(name: string, snapshotName: string)
Get raw XML of a snapshot
ArgumentTypeDescription
namestringVM name
snapshotNamestringSnapshot name
fn provision()
Create a VM from a cloud image: download + verify the image (cached), copy or overlay it into <storageDir>/<name>/, build the cloud-init NoCloud seed ISO, define the domain (swamp-marked) and start it, then wait for its address. Idempotent: an existing domain is never rebuilt, only started. Needs qemu-img, curl, sha256sum/sha512sum and sh on the hypervisor; no virt-install, ISO tool or storage pool.
fn connection(name: string, sources?: array, sshUser?: string)
Read a VM's addresses (guest agent, then DHCP lease) and store them as connection facts (ip, mac, sshUser) for later workflow steps.
ArgumentTypeDescription
namestringVM name
sources?arrayAddress sources, in order
sshUser?stringSSH user to record (e.g. the cloudInit.user the VM was provisioned with)
fn plan(vms: array)
Compare a desired VM list (running / stopped / absent) with the hypervisor and store the actions vm.sync would take: create, start, stop, delete, refuse (not swamp-created) or none, plus memory/vCPU drift. Changes nothing.
ArgumentTypeDescription
vmsarrayDesired VMs: provision fields plus state (running | stopped | absent)
fn sync(vms: array)
Apply the vm.plan actions for a desired VM list: provision missing VMs, start/stop to the desired state, and (only with allowDelete) destroy + undefine swamp-created VMs that should be absent. Drift is reported, not fixed. Every VM is attempted; the stored plan records each result and the method fails at the end if any failed.
ArgumentTypeDescription
vmsarrayDesired VMs: provision fields plus state (running | stopped | absent)
fn consoleCapture()
Capture a domain's serial console for a bounded time, read-only (sends no input), and store the text with terminal control sequences stripped. Runs \`virsh console [--devname] [--force]\` under \`script\` for a pty; SSH mode needs \`timeout\` (coreutils) and \`script\` (util-linux) on the hypervisor. The captured text is stored as a sensitive field. Keeps the last ${CONSOLE_MAX_BYTES} bytes.
fn guestInfo(name: string, types?: string)
Query guest information via QEMU guest agent (hostname, OS, IPs, filesystems, etc.)
ArgumentTypeDescription
namestringVM name
types?stringComma-separated types: users, os, timezone, hostname, filesystem, disk, interface (omit for all)
fn setUserPassword(name: string, username: string, password: string, encrypted?: boolean)
Set a user password inside the guest (requires guest agent). NOTE: the password is passed as a virsh argument and is visible in the hypervisor's process list while running — see README limitations.
ArgumentTypeDescription
namestringVM name
usernamestringUsername inside the guest
passwordstringNew password
encrypted?booleanPassword is already encrypted/hashed

Resources

vm(infinite)— VM list or detail
actionResult(1h)— Result of a VM action (start, stop, etc.)
snapshot(infinite)— Snapshot list or detail
stats(1h)— VM statistics (block, interface, memory, CPU)
console(infinite)— Serial console text captured by consoleCapture (text is sensitive)
connection(infinite)— Connection facts for a VM (ip, mac, addresses, sshUser), from vm.provision / vm.connection / vm.sync
plan(infinite)— vm.plan / vm.sync result: one item per desired VM
@bad-at-naming/libvirt/networkv2026.10.25.10extensions/models/libvirt_network.ts

Global Arguments

ArgumentTypeDescription
host?stringSSH host/IP of the libvirt hypervisor. If set, virsh runs there over SSH. Omit for local/URI mode.
user?stringSSH username (SSH mode only; default: root)
uri?stringLibvirt connection URI. Local mode (no host) defaults to qemu:///system; in SSH mode it is passed to the remote virsh via -c when set.
fn list()
List all virtual networks
fn get(name: string)
Get detailed info for a virtual network including XML config
ArgumentTypeDescription
namestringNetwork name
fn dumpxml(name: string)
Get raw XML definition of a network
ArgumentTypeDescription
namestringNetwork name
fn start(name: string)
Start (activate) a virtual network. Idempotent — succeeds if already active.
ArgumentTypeDescription
namestringNetwork name
fn stop(name: string)
Stop (deactivate) a virtual network. Idempotent — succeeds if already inactive.
ArgumentTypeDescription
namestringNetwork name
fn define(xml: string)
Define a virtual network from XML (does not start it)
ArgumentTypeDescription
xmlstringFull libvirt network XML definition
fn undefine(name: string)
Undefine a virtual network (remove persistent config)
ArgumentTypeDescription
namestringNetwork name
fn autostart(name: string, enabled: boolean)
Enable or disable autostart for a virtual network
ArgumentTypeDescription
namestringNetwork name
enabledbooleantrue to enable, false to disable
fn dhcpLeases(name: string)
List DHCP leases for a virtual network
ArgumentTypeDescription
namestringNetwork name

Resources

network(infinite)— Virtual network list or detail
dhcpLeases(1h)— DHCP leases for a network
actionResult(1h)— Result of a network action
@bad-at-naming/libvirt/storagev2026.10.25.10extensions/models/libvirt_storage.ts

Global Arguments

ArgumentTypeDescription
host?stringSSH host/IP of the libvirt hypervisor. If set, virsh runs there over SSH. Omit for local/URI mode.
user?stringSSH username (SSH mode only; default: root)
uri?stringLibvirt connection URI. Local mode (no host) defaults to qemu:///system; in SSH mode it is passed to the remote virsh via -c when set.
fn poolList()
List all storage pools
fn poolGet(name: string)
Get detailed info for a storage pool including XML
ArgumentTypeDescription
namestringPool name
fn poolStart(name: string)
Start (activate) a storage pool. Idempotent: succeeds if already active.
ArgumentTypeDescription
namestringPool name
fn poolBuild(name: string)
Build a storage pool (creates target directory for dir pools)
ArgumentTypeDescription
namestringPool name
fn poolStop(name: string)
Stop (deactivate) a storage pool
ArgumentTypeDescription
namestringPool name
fn poolDefine(name: string, type: enum, target?: string, sourceHost?: string, sourcePath?: string, sourceFormat?: string)
Define a storage pool from parameters. Idempotent: succeeds if pool already exists.
ArgumentTypeDescription
namestringPool name
typeenumPool type
target?stringTarget path (e.g. /var/lib/libvirt/images)
sourceHost?stringSource host for network pools
sourcePath?stringSource path/name
sourceFormat?stringSource format (e.g. nfs, cifs, auto)
fn poolUndefine(name: string)
Undefine a storage pool (remove persistent config)
ArgumentTypeDescription
namestringPool name
fn poolAutostart(name: string, enabled: boolean)
Enable or disable autostart for a storage pool
ArgumentTypeDescription
namestringPool name
enabledbooleantrue to enable, false to disable
fn poolRefresh(name: string)
Refresh a storage pool to discover new volumes
ArgumentTypeDescription
namestringPool name
fn volList(pool: string)
List all volumes in a storage pool
ArgumentTypeDescription
poolstringPool name
fn volGet(name: string, pool: string)
Get detailed info for a storage volume including XML
ArgumentTypeDescription
namestringVolume name
poolstringPool name
fn volCreate(pool: string, name: string, capacity: string, format?: enum, allocation?: string)
Create a new storage volume. Idempotent: succeeds if volume already exists.
ArgumentTypeDescription
poolstringPool name
namestringVolume name
capacitystringCapacity with unit (e.g. 10G, 500M, 1T)
format?enumVolume format
allocation?stringInitial allocation with unit (for thin provisioning, e.g. 0)
fn volDelete(name: string, pool: string)
Delete a storage volume
ArgumentTypeDescription
namestringVolume name
poolstringPool name
fn volResize(name: string, pool: string, capacity: string, shrink?: boolean)
Resize a storage volume
ArgumentTypeDescription
namestringVolume name
poolstringPool name
capacitystringNew capacity with unit (e.g. 20G)
shrink?booleanAllow shrinking (data loss risk)
fn volClone(name: string, pool: string, newName: string)
Clone a storage volume. Idempotent by target name: succeeds as a no-op if newName already exists in the pool (never clones over it). Records the target's format and byte capacity from vol-dumpxml.
ArgumentTypeDescription
namestringSource volume name
poolstringPool name
newNamestringNew cloned volume name

Resources

pool(infinite)— Storage pool list or detail
volume(infinite)— Storage volume list or detail
actionResult(1h)— Result of a storage action
@bad-at-naming/libvirt/hostv2026.10.25.10extensions/models/libvirt_host.ts

Global Arguments

ArgumentTypeDescription
host?stringSSH host/IP of the libvirt hypervisor. If set, virsh runs there over SSH. Omit for local/URI mode.
user?stringSSH username (SSH mode only; default: root)
uri?stringLibvirt connection URI. Local mode (no host) defaults to qemu:///system; in SSH mode it is passed to the remote virsh via -c when set.
fn info()
Get hypervisor host info (CPU, memory, versions)
fn capabilities()
Get hypervisor capabilities XML
fn sysinfo()
Get host system information (SMBIOS/DMI data)
fn cpuStats()
Get host CPU usage statistics
fn memStats()
Get host memory statistics
fn deviceList(cap?: string)
List node devices (PCI, USB, network, storage controllers, etc.)
ArgumentTypeDescription
cap?stringFilter by capability: system, pci, usb, usb_device, net, scsi_host, scsi, storage, drm
fn addRoute(destination: string, gateway: string, replace?: boolean)
Add a static route on the hypervisor host (SSH host mode only; runs `ip route` over SSH)
ArgumentTypeDescription
destinationstringDestination CIDR (e.g., 10.244.0.0/16)
gatewaystringGateway IP address
replace?booleanUse 'replace' instead of 'add' to be idempotent

Resources

info(infinite)— Hypervisor host information
stats(1h)— Host statistics (CPU, memory)
devices(infinite)— Node device list
04Previous Versions19
2026.10.25.5MIT AND Apache-2.0(was MIT)

2026.10.25.5

Added

  • vm.provision: create a VM from a cloud image with only qemu-img, curl, sha256sum/sha512sum and sh on the hypervisor (no virt-install, ISO tool or storage pool; works on Unraid). It downloads and verifies the image (pinned checksum, or SHA256SUMS/SHA512SUMS) into a cache, copies or overlays it into <storageDir>/<name>/, builds the cloud-init NoCloud seed ISO in TypeScript, defines a q35 domain with swamp metadata and a name-derived MAC, starts it, and waits for the guest agent's address. Idempotent; never overwrites a leftover disk; cleans up its own files if a step fails.
  • Review fixes before release: storage delete removes only the two files the domain's XML names (then rmdir, never rm -rf); an atomic mkdir claim of the VM folder blocks concurrent or leftover provisions; images with a backing file or the wrong format are refused; the cache file is 0444; disk size below the image size is refused; http sources need a pinned checksum; local mode with a remote uri is refused for file steps; paused is resumed; provision refuses a same-named non-swamp domain; sync gains forceStopAfterWait and undefines with --snapshots-metadata.
  • vm.connection and the connection resource: ip, mac, addresses, source (agent/lease/arp/none), sshUser and hostname for later steps.
  • vm.plan / vm.sync and the plan resource: a desired VM list (running / stopped / absent) is turned into create / start / stop / delete / refuse / none actions. Delete needs allowDelete and applies only to domains with swamp metadata; memory/vCPU drift is reported, not changed.
  • runOnHost (SSH or local) with text or byte stdin, used for the file steps.

Notes

  • Found in the live test on Unraid: the seed must be a virtio disk, not a SATA CD-ROM. Ubuntu's minimal cloud images boot linux-kvm, which has no CD-ROM driver, so cloud-init never saw the seed.
  • Found in the live test too: a DHCP lease from an earlier boot with the same MAC named the wrong address (.244 while the guest had .245). With the guest agent enabled, only the agent is trusted while waiting; the lease is a logged fallback at the deadline.
  • makeNoCloudIso is adapted from @evrardjp/cloud-init-nocloud (Apache License 2.0); see LICENSE.md and LICENSE-APACHE-2.0.txt. The plan/sync shape follows @evrardjp/libvirt-vm-pool, and the checksum handling follows @taylor/libvirt (ideas only).

Modified 1 behaviors

2026.10.25.4MIT

2026.10.25.4

Added

  • SSH connection sharing: multiplex (default true) runs ssh with ControlMaster=auto and ControlPersist=30, so a run's virsh calls reuse one connection. Measured against Unraid: about 300 ms per call without it, about 50 ms with it. Sockets are in a per-process 0700 directory under /tmp (removed at exit). Each is named by 16 hex chars of a SHA-256 over the target (user, host, port, jump host) and the security settings (host-key policy, pinned keys, identity file, sshConfig), so a strict call never reuses an accept-new master. ssh's %C is not used: with the 17-char suffix ssh adds while binding, it overflows the ~104-byte socket path limit on macOS. If the path would still be too long, sharing is skipped.
  • SSH settings port (-p), identityFile (-i, IdentitiesOnly=yes), jumpHost (-J; no hop may start with -), sshConfig (extra -o Key=Value from an allowlist of connection-tuning keys; see README) and become (default false: remote commands run under sudo -n). They apply in SSH mode only; setting one in local mode throws before any process starts.
  • With multiplex, ServerAliveInterval=5 and ServerAliveCountMax=2 (after sshConfig, so a user value wins): a reused connection skips ConnectTimeout, so keepalives bound a call on a dead master to ~10 s. The socket directory is checked (owner, 0700, not a symlink) before every call and replaced if the check fails.
  • SshConnectionError: ssh exit 255 now throws, naming user@host and ssh's stderr, from virshTry, virsh, runSshRaw, defineXml and vm.consoleCapture. Before, virshTry returned the result, and a caller matching virsh stderr for idempotency could act on a transport failure.

Changed

  • host and user may not start with - or contain whitespace, @ or control characters, and ssh gets -- before the destination (a user such as -oProxyCommand=… used to reach ssh as an option).
  • buildInvocation, buildSshRaw, sshOptions and buildConsoleInvocation take an SshCallContext ({ knownHostsFile?, controlPath? }) in place of the bare knownHostsFile string. withHostKeys is now withSsh.

Ideas from @taylor/libvirt (connection sharing, the ssh settings and the exit-255 rule); no code was copied (it is AGPL-3.0).

2026.10.25.3MIT

2026.10.25.3

Added

  • vm.consoleCapture (#262): a bounded, read-only capture of a domain's serial console, for diagnosing guests that hang before they reach the network.
    • Arguments: name, optional device (--devname, for domains with more than one console), required timeoutSeconds (1-300), and force (default true: passes --force, which disconnects an existing console session).
    • SSH mode runs env SHELL=/bin/sh timeout -k 5 <n> script -qec '<virsh console …>' /dev/null on the hypervisor (needs coreutils timeout and util-linux script there), with a Deno-side kill timer on the ssh process as a backstop. Local mode runs script on the swamp host (-qec on Linux, script -q /dev/null … on macOS/BSD) under a Deno-side kill timer (SIGTERM at the deadline, SIGKILL 3 s later).
    • Read-only: the process's stdin is held open and never written, so no input reaches the guest console.
    • Terminal control sequences are stripped. The last 256 KiB of text is kept (truncated flags a cut).
    • Stored in the new console resource (instance <name> or <name>-<device>) with ended: deadline | exited, bytes, and text. text is marked sensitive (.meta({ sensitive: true })), so swamp stores it in a vault. It is never logged. A virsh/ssh failure throws with only the error: lines and stderr, never console content.
    • Domain names may not start with - or contain control characters. Device aliases must match [A-Za-z0-9][A-Za-z0-9_.-]*. In SSH mode the inner command is shell-quoted for both shells it passes through.

Modified 1 behaviors

2026.10.25.1MIT

2026.10.25.1

Changed

  • storage.volClone is now idempotent by target name (#261). It first checks the target with virsh vol-info <newName> --pool <pool>; if the volume already exists the call is a no-op success (message: "<pool>/<newName> already exists (idempotent)") and vol-clone is never issued, so a re-run never clones over an existing volume (run volDelete first for a fresh copy). A target that appears between the check and the clone is caught by the shared alreadyExists matcher. Works for any pool driver, including zfs pools whose golden image is a zvol.

Added

  • storage.volClone's actionResult now records idempotent (true when the target already existed) and, read best-effort from vol-dumpxml, the target's format and capacityBytes. The fields are optional on the shared actionResult schema, so existing records stay valid.
2026.10.15.9MIT

2026.10.15.9

Changed

  • Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.10.15.8MIT

2026.10.15.8

Changed

  • Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.10.15.6MIT

2026.10.15.6

Changed

  • Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.10.15.5MIT

2026.10.15.5

Changed

  • Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.10.15.4MIT

2026.10.15.4

Changed

  • Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.10.15.3MIT

2026.10.15.3

Changed

  • Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.10.15.2MIT

2026.10.15.2

Changed

  • Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.10.15.1MIT

2026.10.15.1

Changed

  • Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.10.14.2MIT(was none)

2026.10.14.2

Changed

  • Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.09.19.2

2026.09.19.2

Changed

  • Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.09.17.1

2026.09.17.1

Changed

  • Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.08.19.1
2026.08.01.1

2026.08.01.1 — vm.stop wait-for-shutdown guard + test-backfill to the five-suite quality standard

Fixed

  • @bad-at-naming/libvirt/vm stop (HIGH, data-loss): stop now waits for the domain to actually reach shut off before returning, instead of reporting state immediately after issuing virsh shutdown. A new bounded waitSeconds argument (min(0), max(3600), default 120; 0 = fire-and-forget) polls every 3s; if the domain is still not shut off when waitSeconds elapses, stop now throws instead of returning a data-losing false-success. This closes the same class of race that caused the 2026-07-13 qemu-img-live-resize incident (a dependent operation ran against a qcow2 image before the owning domain had actually released it). The fix was proven in the homelab dev copy (vm v2026.07.13.1) and is ported here adapted to this package's conn abstraction (SSH + local/URI) via getDomDetail(conn, name) — the dev copy is SSH-only and could not be copied verbatim. Tracked as the local swamp issue-lifecycle model libvirt-port-stop-wait-guard (never filed upstream as a Lab issue — @bad-at-naming/libvirt is not a @swamp/* package).
  • Two existing vm.stop characterization tests (libvirt_methods_test.ts, libvirt_coverage_test.ts) are flipped from mocking dominfo as "in shutdown" to "shut off", matching the new wait-then-return contract; the shutdown-verb and never-destroy assertions are unaffected. Three new wait-guard tests and one schema-boundary test are added (libvirt_methods_test.ts), using deno.land/std@0.224.0/testing/time.ts FakeTime to virtualize the 3s poll interval so the suite stays instant.
  • forceStop (immediate virsh destroy) is unchanged — the wait guard only applies to the graceful path.

Internal

  • @bad-at-naming/libvirt/network, /storage, and /host model versions are bumped to 2026.08.01.1 in lockstep with /vm and manifest.yaml (version only — no behavior change) to satisfy this repo's CI invariant that every model's embedded version matches the manifest version.

Wave-1 gap-check child of ext-quality-test-backfill, following the pihole PR #66 recipe, landed in this same release.

Added

  • extensions/models/libvirt_methods_test.ts — drives all 69 vm/network/ storage/host methods' success and failure/idempotent paths against a stubbed Deno.Command subprocess boundary (no real virsh/ssh call).
  • extensions/models/libvirt_adversarial_test.ts — hostile-input coverage: command-injection through the methods, the setUserPassword secret-leak guard, dumpxml/snapshotDumpxml log-redact-vs-store-raw pinning, and malformed-output handling.
  • extensions/models/libvirt_coverage_test.ts — reviewer-guard regressions on the destructive lifecycle paths (VM stop-vs-destroy, define's destroy/undefine gating, undefine's three default-false flags, snapshotDelete --children, the storage/network destroy-verb mapping, host.addRoute), each paired with a positive control.
  • extensions/models/libvirt_property_test.ts — fast-check-based invariants for shellQuote, buildInvocation, redactSecrets, isIdempotent, and the parseVmList/parseKV parsers, gated by FC_NUM_RUNS (deno task test:soak runs a 10000-iteration nightly soak).
  • quality.yaml: all five required suites now present; docs.readme and docs.changelog present, docs.skill na (no bundled Claude skill); ratchet baseline set to the measured 100% (Grade A, rubric v3).
  • libvirt removed from the repo-root quality-allowlist.txt in this same change.

Unchanged

  • The three pre-existing test files (libvirt_parse_test.ts, libvirt_connection_test.ts, libvirt_idempotency_test.ts) are byte-for-byte unchanged — they remain the contract-fixture anchor.
  • lib/connection.ts and lib/parse.ts runtime source is untouched.

Added 4, removed 1 behaviors

2026.05.25.1

2026.05.25.1 — idempotent network start/stop

Fixes umag/swamp-workspace#1. @bad-at-naming/libvirt/network start no longer throws when the network is already active, and stop no longer throws when it is already inactive — both mirror the VM model via virshTry + isIdempotent against new anchored networkAlreadyActive / networkNotActive IDEMPOTENT_ERRORS sets. A genuine failure (e.g. a non-existent network) still throws.

2026.05.20.1
05Stats
A
100 / 100
Downloads
59
Archive size
104.1 KB
  • Has README or module doc2/2earned
  • README has a code example1/1earned
  • README is substantive1/1earned
  • Most symbols documented1/1earned
  • No slow types (deprecated)1/1earned
  • Dependencies pass trust audit2/2earned
  • Docs keep secrets in a vault1/1earned
  • Has description1/1earned
  • Platform support declared (or universal)2/2earned
  • License2/2earned
  • Verified public repository2/2earned
06Platforms
07Labels