libvirt

Types

Type	Description
`NoDomainError`	Raised when a requested libvirt domain does not exist.
`Domain`	References a libvirt domain by name and connection URI.

Functions

`define source :connect_uri?`

Defines a domain from an XML string.

`attach name :connect_uri?`

Attaches to an existing domain.

`list :connect_uri?`

Lists every domain known to the connection.

`create :image? :name? :os? :arch? :app? :user? :dolang? :image_digest? :packages? :memory? :vcpus? :disk_size? :cache? :io? :connect_uri? :init? ...options`

Creates and starts a cloud-init domain.

Parameters

Name	type	Description
`image`	`Str`\|`Path`\|`Url`	Base disk image (may be `.gz`/`.xz`/`.zstd` compressed)
`name`	`Str`	Domain name; auto-generated if omitted
`os`	`Sym`	Guest OS, using `sys`'s symbol vocabulary
`arch`?	`Sym`	Guest CPU architecture, `sys` symbol; must be the host's, which is the default
`app`?	`Str`	Cache/data namespace; derived from `shell.program` by default
`user`?	`Str`	Guest user to create (default `"ci"`)
`dolang`?	See below	Installs Do into the guest — see `dolang:`
`image_digest`?	`Str`	`algorithm:hex` digest to verify a downloaded `image`
`packages`?	`Array`	Guest packages to install
`memory`?	`Int`	Guest memory in MiB (default `2048`)
`vcpus`?	`Int`	Guest vCPU count (default `2`)
`disk_size`?	`Str`	Disk size (default `"20G"`)
`cache`?	`Sym`	Disk host cache mode — see `cache:`
`io`?	`Sym`	Disk I/O submission mode — see `io:`
`connect_uri`?	`Str`	libvirt connection URI (default `"qemu:///session"`)
`init`?	`Dict`	Early boot provisioning — see `init:`
`add`*	`Dict`	Uploads a file — see `add:`
`run`*	`func`	Runs a block in VFS context

`dolang:`

Value	Behavior
`false`	Skip installation.
`true` (default)	Install matching release for target platform if available.
a version tag, e.g. `"v0.1.1"`	Install specific release version
a `Path` or `Url`	Install provided release archive
a `Dict`	Explicit form of the above — see below.

dolang:'s dict form:

Key	type	Description
`version`?	`Str`	Version tag; excludes `archive`
`archive`?	`Path`\|`Url`	Release archive; excludes `version`
`digest`?	`Str`	`algorithm:hex` digest for `archive`

`cache:`

Host cache mode for the domain disk. Defaults to the hypervisor's own default, which honors guest flushes.

Value	Behavior
`:NONE:`	`O_DIRECT`; no host page cache, guest flushes honored
`:WRITEBACK:`	Host page cache, guest flushes honored
`:WRITETHROUGH:`	Host page cache, every write flushed
`:DIRECTSYNC:`	`O_DIRECT` and every write flushed
`:UNSAFE:`	Host page cache, guest flushes ignored

:UNSAFE: loses the disk's contents if the host or the domain dies uncleanly, since nothing the guest wrote is guaranteed to have reached storage until the domain shuts down. That is a fair trade for a disposable build domain — dropping flushes removes them from the critical path, and files written and deleted within one run need never reach storage at all — but it is not a safe default for a domain whose disk matters.

`io:`

Disk I/O submission mode, defaulting to :IO_URING:.

Value	Behavior
`:IO_URING:`	`io_uring`; needs QEMU 6.0+ on a 5.1+ kernel
`:THREADS:`	Thread pool
`:NATIVE:`	Linux AIO; only asynchronous with `cache:` `:NONE:` or `:DIRECTSYNC:`

An older host fails at domain start rather than falling back, so select :THREADS: there.

:NATIVE: needs O_DIRECT to be asynchronous; paired with a cache mode that uses the host page cache it quietly degrades to blocking submission. :IO_URING: has no such pairing constraint.

`init:`

Key	type	Description
`add`*	`Dict`	Writes a file during early boot
`run`*	`Str`\|`Array`	Split with `shlex` if a `Str`. Run during early boot

`add:`

Key	type	Description
`target`	`Str`	Guest file path to write
`source`?	`Str`\|`Path`\|`Url`	Resolved and read; excludes `content`
`content`?	`Str`\|`Bin`	Embedded directly; excludes `source`
`chmod`?	`Int`	File mode, e.g. `0o644`

Returns

Domain

Errors

Error	Condition
`ValueError`	`image` or `os` is omitted, `arch` is not the host's, or a domain named `name` already exists
`RuntimeError`	No forwarded SSH port could be allocated
`TypeError`	Invalid argument type

Example

let domain = libvirt.create
  image: freebsd.qcow2.xz
  os: :FREEBSD:
  name: freebsd-build
  packages:
    - sqlite3
  init:
    add:
      target: /etc/example.conf
      content: |
        enabled=yes
  run: do
    run uname -a

echo $domain.name

`with block :image? :name? :os? :arch? :app? :user? :dolang? :image_digest? :packages? :memory? :vcpus? :disk_size? :cache? :io? :connect_uri? :init? ...options`

Creates a domain, runs block through its VFS, and tears it down — even if block throws.

Parameters

Takes the same keyword arguments as create, plus:

Name	type	Description
`block`	`func`	Block to run in the VFS

Returns

The result of block.

Example

libvirt.with
  image: freebsd.qcow2.xz
  os: :FREEBSD:
  do
    run uname -a