Libvirt
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(+ optionaluser) and virsh runs on the remote hypervisor over ssh. No local libvirt client needed. - Local/URI mode: omit
hostand virsh runs on the swamp host againsturi(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.
2026.10.25.10
- Repo-wide republish; no functional change.
Global Arguments
| Argument | Type | Description |
|---|---|---|
| host? | string | SSH host/IP of the libvirt hypervisor. If set, virsh runs there over SSH. Omit for local/URI mode. |
| user? | string | SSH username (SSH mode only; default: root) |
| uri? | string | Libvirt connection URI. Local mode (no host) defaults to qemu:///system; in SSH mode it is passed to the remote virsh via -c when set. |
| Argument | Type | Description |
|---|---|---|
| name | string | VM name |
| Argument | Type | Description |
|---|---|---|
| name | string | VM name |
| Argument | Type | Description |
|---|---|---|
| name | string | VM name |
| Argument | Type | Description |
|---|---|---|
| name | string | VM name |
| Argument | Type | Description |
|---|---|---|
| name | string | VM name |
| Argument | Type | Description |
|---|---|---|
| name | string | VM name |
| Argument | Type | Description |
|---|---|---|
| name | string | VM name |
| Argument | Type | Description |
|---|---|---|
| name | string | VM name |
| Argument | Type | Description |
|---|---|---|
| name | string | VM name |
| Argument | Type | Description |
|---|---|---|
| name | string | VM name |
| enabled | boolean | true to enable, false to disable |
| Argument | Type | Description |
|---|---|---|
| xml | string | Full libvirt domain XML definition |
| Argument | Type | Description |
|---|---|---|
| name | string | VM name |
| removeStorage? | boolean | Also remove all associated storage volumes |
| snapshotsMetadata? | boolean | Also remove snapshot metadata |
| nvram? | boolean | Also remove NVRAM file (required for UEFI VMs) |
| Argument | Type | Description |
|---|---|---|
| name | string | Current VM name |
| newName | string | New VM name |
| Argument | Type | Description |
|---|---|---|
| name | string | VM name |
| file | string | Path on hypervisor to save state to |
| Argument | Type | Description |
|---|---|---|
| file | string | Path on hypervisor to restore from |
| Argument | Type | Description |
|---|---|---|
| name | string | VM name |
| count | number | Number of vCPUs |
| maximum? | boolean | Set maximum vCPU count instead of current |
| config? | boolean | Apply to persistent config (next boot) |
| live? | boolean | Apply to running VM (hotplug) |
| Argument | Type | Description |
|---|---|---|
| name | string | VM name |
| sizeMB | number | Memory in MiB |
| maximum? | boolean | Set maximum memory instead of current |
| config? | boolean | Apply to persistent config |
| live? | boolean | Apply to running VM |
| Argument | Type | Description |
|---|---|---|
| name | string | VM name |
| source | string | Disk source path (image file or block device) |
| target | string | Target device name (e.g. vdb, sdb) |
| driver? | enum | Disk driver/format |
| cache? | enum | Cache mode |
| persistent? | boolean | Make change persistent across reboots (running VMs) |
| config? | boolean | Apply to persistent config only (stopped VMs) |
| Argument | Type | Description |
|---|---|---|
| name | string | VM name |
| target | string | Target device name to detach (e.g. vdb) |
| persistent? | boolean | Make change persistent (running VMs) |
| config? | boolean | Apply to persistent config only (stopped VMs) |
| Argument | Type | Description |
|---|---|---|
| name | string | VM name |
| type | enum | Interface type |
| source | string | Source bridge/network name (e.g. br0, default) |
| model? | string | NIC model (virtio, e1000, rtl8139) |
| persistent? | boolean | Make change persistent |
| Argument | Type | Description |
|---|---|---|
| name | string | VM name |
| type | enum | Interface type |
| mac | string | MAC address of the interface to detach |
| persistent? | boolean | Make change persistent |
| Argument | Type | Description |
|---|---|---|
| name | string | VM name |
| target | string | Target device (e.g. hda, sda) |
| source? | string | New ISO path (omit to eject) |
| Argument | Type | Description |
|---|---|---|
| name | string | VM name |
| Argument | Type | Description |
|---|---|---|
| name | string | VM name |
| Argument | Type | Description |
|---|---|---|
| name | string | VM name |
| source? | enum | Address source: lease (DHCP), agent (guest-agent), arp |
| Argument | Type | Description |
|---|---|---|
| name | string | VM name |
| device? | string | Specific block device (e.g. vda). Omit for all. |
| Argument | Type | Description |
|---|---|---|
| name | string | VM name |
| interface | string | Interface device name (e.g. vnet0) |
| Argument | Type | Description |
|---|---|---|
| name | string | VM name |
| Argument | Type | Description |
|---|---|---|
| name | string | VM name |
| Argument | Type | Description |
|---|---|---|
| name | string | VM name |
| Argument | Type | Description |
|---|---|---|
| name | string | VM name |
| Argument | Type | Description |
|---|---|---|
| name | string | VM name |
| snapshotName | string | Name for the snapshot |
| description? | string | Snapshot description |
| quiesce? | boolean | Quiesce guest filesystem (requires guest agent) |
| diskOnly? | boolean | Disk-only snapshot (no memory) |
| Argument | Type | Description |
|---|---|---|
| name | string | VM name |
| snapshotName | string | Snapshot name |
| Argument | Type | Description |
|---|---|---|
| name | string | VM name |
| snapshotName | string | Snapshot name to revert to |
| running? | boolean | Start VM after revert |
| paused? | boolean | Leave VM paused after revert |
| Argument | Type | Description |
|---|---|---|
| name | string | VM name |
| snapshotName | string | Snapshot name to delete |
| children? | boolean | Also delete child snapshots |
| Argument | Type | Description |
|---|---|---|
| name | string | VM name |
| snapshotName | string | Snapshot name |
| Argument | Type | Description |
|---|---|---|
| name | string | VM name |
| sources? | array | Address sources, in order |
| sshUser? | string | SSH user to record (e.g. the cloudInit.user the VM was provisioned with) |
| Argument | Type | Description |
|---|---|---|
| vms | array | Desired VMs: provision fields plus state (running | stopped | absent) |
| Argument | Type | Description |
|---|---|---|
| vms | array | Desired VMs: provision fields plus state (running | stopped | absent) |
| Argument | Type | Description |
|---|---|---|
| name | string | VM name |
| types? | string | Comma-separated types: users, os, timezone, hostname, filesystem, disk, interface (omit for all) |
| Argument | Type | Description |
|---|---|---|
| name | string | VM name |
| username | string | Username inside the guest |
| password | string | New password |
| encrypted? | boolean | Password is already encrypted/hashed |
Resources
Global Arguments
| Argument | Type | Description |
|---|---|---|
| host? | string | SSH host/IP of the libvirt hypervisor. If set, virsh runs there over SSH. Omit for local/URI mode. |
| user? | string | SSH username (SSH mode only; default: root) |
| uri? | string | Libvirt connection URI. Local mode (no host) defaults to qemu:///system; in SSH mode it is passed to the remote virsh via -c when set. |
| Argument | Type | Description |
|---|---|---|
| name | string | Network name |
| Argument | Type | Description |
|---|---|---|
| name | string | Network name |
| Argument | Type | Description |
|---|---|---|
| name | string | Network name |
| Argument | Type | Description |
|---|---|---|
| name | string | Network name |
| Argument | Type | Description |
|---|---|---|
| xml | string | Full libvirt network XML definition |
| Argument | Type | Description |
|---|---|---|
| name | string | Network name |
| Argument | Type | Description |
|---|---|---|
| name | string | Network name |
| enabled | boolean | true to enable, false to disable |
| Argument | Type | Description |
|---|---|---|
| name | string | Network name |
Resources
Global Arguments
| Argument | Type | Description |
|---|---|---|
| host? | string | SSH host/IP of the libvirt hypervisor. If set, virsh runs there over SSH. Omit for local/URI mode. |
| user? | string | SSH username (SSH mode only; default: root) |
| uri? | string | Libvirt connection URI. Local mode (no host) defaults to qemu:///system; in SSH mode it is passed to the remote virsh via -c when set. |
| Argument | Type | Description |
|---|---|---|
| name | string | Pool name |
| Argument | Type | Description |
|---|---|---|
| name | string | Pool name |
| Argument | Type | Description |
|---|---|---|
| name | string | Pool name |
| Argument | Type | Description |
|---|---|---|
| name | string | Pool name |
| Argument | Type | Description |
|---|---|---|
| name | string | Pool name |
| type | enum | Pool type |
| target? | string | Target path (e.g. /var/lib/libvirt/images) |
| sourceHost? | string | Source host for network pools |
| sourcePath? | string | Source path/name |
| sourceFormat? | string | Source format (e.g. nfs, cifs, auto) |
| Argument | Type | Description |
|---|---|---|
| name | string | Pool name |
| Argument | Type | Description |
|---|---|---|
| name | string | Pool name |
| enabled | boolean | true to enable, false to disable |
| Argument | Type | Description |
|---|---|---|
| name | string | Pool name |
| Argument | Type | Description |
|---|---|---|
| pool | string | Pool name |
| Argument | Type | Description |
|---|---|---|
| name | string | Volume name |
| pool | string | Pool name |
| Argument | Type | Description |
|---|---|---|
| pool | string | Pool name |
| name | string | Volume name |
| capacity | string | Capacity with unit (e.g. 10G, 500M, 1T) |
| format? | enum | Volume format |
| allocation? | string | Initial allocation with unit (for thin provisioning, e.g. 0) |
| Argument | Type | Description |
|---|---|---|
| name | string | Volume name |
| pool | string | Pool name |
| Argument | Type | Description |
|---|---|---|
| name | string | Volume name |
| pool | string | Pool name |
| capacity | string | New capacity with unit (e.g. 20G) |
| shrink? | boolean | Allow shrinking (data loss risk) |
| Argument | Type | Description |
|---|---|---|
| name | string | Source volume name |
| pool | string | Pool name |
| newName | string | New cloned volume name |
Resources
Global Arguments
| Argument | Type | Description |
|---|---|---|
| host? | string | SSH host/IP of the libvirt hypervisor. If set, virsh runs there over SSH. Omit for local/URI mode. |
| user? | string | SSH username (SSH mode only; default: root) |
| uri? | string | Libvirt connection URI. Local mode (no host) defaults to qemu:///system; in SSH mode it is passed to the remote virsh via -c when set. |
| Argument | Type | Description |
|---|---|---|
| cap? | string | Filter by capability: system, pci, usb, usb_device, net, scsi_host, scsi, storage, drm |
| Argument | Type | Description |
|---|---|---|
| destination | string | Destination CIDR (e.g., 10.244.0.0/16) |
| gateway | string | Gateway IP address |
| replace? | boolean | Use 'replace' instead of 'add' to be idempotent |
Resources
2026.10.25.5
Added
vm.provision: create a VM from a cloud image with onlyqemu-img,curl,sha256sum/sha512sumandshon the hypervisor (novirt-install, ISO tool or storage pool; works on Unraid). It downloads and verifies the image (pinnedchecksum, 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, neverrm -rf); an atomicmkdirclaim 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 remoteuriis refused for file steps;pausedis resumed; provision refuses a same-named non-swamp domain;syncgainsforceStopAfterWaitand undefines with--snapshots-metadata. vm.connectionand theconnectionresource: ip, mac, addresses, source (agent/lease/arp/none), sshUser and hostname for later steps.vm.plan/vm.syncand theplanresource: a desired VM list (running/stopped/absent) is turned into create / start / stop / delete / refuse / none actions. Delete needsallowDeleteand 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 (
.244while 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. makeNoCloudIsois 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.4
Added
- SSH connection sharing:
multiplex(defaulttrue) runs ssh withControlMaster=autoandControlPersist=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 astrictcall never reuses anaccept-newmaster. ssh's%Cis 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=Valuefrom an allowlist of connection-tuning keys; see README) andbecome(defaultfalse: remote commands run undersudo -n). They apply in SSH mode only; setting one in local mode throws before any process starts. - With
multiplex,ServerAliveInterval=5andServerAliveCountMax=2(aftersshConfig, so a user value wins): a reused connection skipsConnectTimeout, 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, naminguser@hostand ssh's stderr, fromvirshTry,virsh,runSshRaw,defineXmlandvm.consoleCapture. Before,virshTryreturned the result, and a caller matching virsh stderr for idempotency could act on a transport failure.
Changed
hostandusermay not start with-or contain whitespace,@or control characters, and ssh gets--before the destination (ausersuch as-oProxyCommand=…used to reach ssh as an option).buildInvocation,buildSshRaw,sshOptionsandbuildConsoleInvocationtake anSshCallContext({ knownHostsFile?, controlPath? }) in place of the bareknownHostsFilestring.withHostKeysis nowwithSsh.
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.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, optionaldevice(--devname, for domains with more than one console), requiredtimeoutSeconds(1-300), andforce(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/nullon the hypervisor (needs coreutilstimeoutand util-linuxscriptthere), with a Deno-side kill timer on the ssh process as a backstop. Local mode runsscripton the swamp host (-qecon 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
(
truncatedflags a cut). - Stored in the new
consoleresource (instance<name>or<name>-<device>) withended: deadline | exited,bytes, andtext.textis marked sensitive (.meta({ sensitive: true })), so swamp stores it in a vault. It is never logged. A virsh/ssh failure throws with only theerror: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.
- Arguments:
Modified 1 behaviors
2026.10.25.1
Changed
storage.volCloneis now idempotent by target name (#261). It first checks the target withvirsh vol-info <newName> --pool <pool>; if the volume already exists the call is a no-op success (message: "<pool>/<newName> already exists (idempotent)") andvol-cloneis never issued, so a re-run never clones over an existing volume (runvolDeletefirst for a fresh copy). A target that appears between the check and the clone is caught by the sharedalreadyExistsmatcher. Works for any pool driver, including zfs pools whose golden image is a zvol.
Added
storage.volClone'sactionResultnow recordsidempotent(true when the target already existed) and, read best-effort fromvol-dumpxml, the target'sformatandcapacityBytes. The fields are optional on the sharedactionResultschema, so existing records stay valid.
2026.10.15.9
Changed
- Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.10.15.8
Changed
- Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.10.15.6
Changed
- Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.10.15.5
Changed
- Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.10.15.4
Changed
- Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.10.15.3
Changed
- Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.10.15.2
Changed
- Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.10.15.1
Changed
- Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.10.14.2
Changed
- Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.09.19.2
Changed
- Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.09.17.1
Changed
- Repo-wide maintenance release: version bump to republish the current source. No schema change.
2026.08.01.1 — vm.stop wait-for-shutdown guard + test-backfill to the five-suite quality standard
Fixed
@bad-at-naming/libvirt/vmstop(HIGH, data-loss):stopnow waits for the domain to actually reachshut offbefore returning, instead of reporting state immediately after issuingvirsh shutdown. A new boundedwaitSecondsargument (min(0),max(3600), default120;0= fire-and-forget) polls every 3s; if the domain is still notshut offwhenwaitSecondselapses,stopnow throws instead of returning a data-losing false-success. This closes the same class of race that caused the 2026-07-13qemu-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 (vmv2026.07.13.1) and is ported here adapted to this package'sconnabstraction (SSH + local/URI) viagetDomDetail(conn, name)— the dev copy is SSH-only and could not be copied verbatim. Tracked as the local swamp issue-lifecycle modellibvirt-port-stop-wait-guard(never filed upstream as a Lab issue —@bad-at-naming/libvirtis not a@swamp/*package).- Two existing
vm.stopcharacterization tests (libvirt_methods_test.ts,libvirt_coverage_test.ts) are flipped from mockingdominfoas"in shutdown"to"shut off", matching the new wait-then-return contract; the shutdown-verb and never-destroyassertions are unaffected. Three new wait-guard tests and one schema-boundary test are added (libvirt_methods_test.ts), usingdeno.land/std@0.224.0/testing/time.tsFakeTimeto virtualize the 3s poll interval so the suite stays instant. forceStop(immediatevirsh destroy) is unchanged — the wait guard only applies to the graceful path.
Internal
@bad-at-naming/libvirt/network,/storage, and/hostmodel versions are bumped to2026.08.01.1in lockstep with/vmandmanifest.yaml(version only — no behavior change) to satisfy this repo's CI invariant that every model's embeddedversionmatches 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 stubbedDeno.Commandsubprocess boundary (no real virsh/ssh call).extensions/models/libvirt_adversarial_test.ts— hostile-input coverage: command-injection through the methods, thesetUserPasswordsecret-leak guard,dumpxml/snapshotDumpxmllog-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 forshellQuote,buildInvocation,redactSecrets,isIdempotent, and theparseVmList/parseKVparsers, gated byFC_NUM_RUNS(deno task test:soakruns a 10000-iteration nightly soak).quality.yaml: all five required suites nowpresent;docs.readmeanddocs.changelogpresent,docs.skillna(no bundled Claude skill); ratchet baseline set to the measured100%(Grade A, rubric v3).libvirtremoved from the repo-rootquality-allowlist.txtin 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 thecontract-fixtureanchor. lib/connection.tsandlib/parse.tsruntime source is untouched.
Added 4, removed 1 behaviors
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.
- 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