Domain

References a libvirt domain by name and connection URI.

Domains returned by create carry connection metadata used by with.

Constructor

`Domain impl`

DomainImpl is module-private, so nothing outside this module can produce one to pass: checking it here is what makes this constructor private.

Fields

connect_uri @ Str: The libvirt connection URI the domain is defined on.
name @ Str: The libvirt domain name.

Methods

`destroy()`

Force-stops the domain without undefining it.

`download source destination`

Copies one file from the domain to the local VFS.

Parameters

Name	Type	Description
`source`	`(Str \| fs.Path)`	Guest file to copy.
`destination`	`(Str \| fs.Path)`	Local path to write.

`export destination … -> fs.Path`

Exports the shut-off domain as a bundle: its flattened disk, the firmware variable store and vTPM state of a guest that has them, and the configuration needed to define an equivalent domain again — none of which the disk image alone carries.

Parameters

Name	Type	Description
`destination`	`(Str \| fs.Path)`	Bundle to write; `.dolvm` is the conventional extension.
`:compress?`	`Compress`	qcow2 compression.
`:force?`	`Bool`	Export a domain that did not shut down cleanly.

Errors

Error	Condition
`StateError`	The domain is not shut off, or did not shut down cleanly and `force:` was not given
`ValueError`	The domain has no `dolang:vm` metadata, does not have exactly one file-backed disk, or the destination is unusable

Example

domain.shutdown()
domain.export ./freebsd-gold.dolvm
domain.undefine()

`export_disk destination … -> fs.Path`

Flattens the shut-off domain's file-backed disk into a standalone qcow2, returning the path written.

Parameters

Name	Type	Description
`destination`	`(Str \| fs.Path)`	Image to write.
`:compress?`	`Compress`	qcow2 compression.

`reboot()`

Asks the guest to reboot, without waiting for it to come back: what "back" means is the caller's probe, not the domain's state, which never leaves :RUNNING: across a reboot.

`shutdown()`

Requests a graceful shutdown and waits until the domain is shut off.

`start()`

Starts the domain.

`state() -> (DomainState | Str)`

Returns the domain's state. A state this module does not know is returned as libvirt reports it.

`undefine()`

Undefines the domain and removes a validated managed overlay.

`upload source destination …`

Copies one local file into the domain.

Parameters

Name	Type	Description
`source`	`(Str \| fs.Path)`	Local file to copy.
`destination`	`(Str \| fs.Path)`	Guest path to write.
`:chmod?`	`(Int \| fs.unix.Mode)`	Mode to set on the destination, in the same VFS session as the copy.

`with[R] block … -> R`

Runs block in the domain's VFS context.

Parameters

Name	Type	Description
`block`	`(() -> R)`	Block to run in the guest.
`:cd?`	`(Str \| fs.Path)`	Initial guest working directory.
`:env?`	`Dict[Str \| Sym, Value]`	Environment overrides for the block. `nil` unsets a variable, and `:INHERIT:` copies it from the calling context.

Errors

Error	Condition
`ValueError`	The domain is not running

Example

domain.with cd: /usr/src env: {MAKEOBJDIRPREFIX: "/tmp/obj"} do
  run make buildworld