CONSFIGURATOR.PROPERTY.LIBVIRT

API reference

General

Property: LIBVIRT:INSTALLED

(libvirt:installed)

Install basic libvirt components.

Property: LIBVIRT:DEFAULT-NETWORK-STARTED

(libvirt:default-network-started)

Ensure that the default libvirt network is started.

Property: LIBVIRT:DEFAULT-NETWORK-AUTOSTARTED

(libvirt:default-network-autostarted)

Ensure that the default libvirt network is set to autostart, and start it. On Debian, it is not started by default after installation of libvirt.

Property: LIBVIRT:DEFINED-FOR

(libvirt:defined-for host &rest arguments)

Define a libvirt domain for HOST by providing ARGUMENTS to virt-install(1). With the current implementation, if ARGUMENTS changes, virt-install(1) will not be run again. You will need to either unapply and reapply this property, or use virt-xml(1) to perform a modification.

Unapplying this property when the domain is running will use the ‘undefine’ subcommand of virsh(1) to convert the running domain into a transient domain.

Property: LIBVIRT:STARTED

(libvirt:started host)

Ensure the libvirt domain for the host designated by HOST is started. (I.e., if HOST is a string, ensure the domain named HOST is started; if HOST is a HOST value, start the libvirt domain whose name is HOST’s hostname.)

Property: LIBVIRT:DESTROYED

(libvirt:destroyed host)

Ensure the libvirt domain for the host designated by HOST is destroyed.

Macro: LIBVIRT:WHEN-STARTED

(libvirt:when-started host &body propapps)

Apply PROPAPPS only when the libvirt domain for the host designated by HOST is already running. Useful to conditionalise a DEPLOYS property to do nothing unless the VM is already running, for a VM which is not always booted, e.g. on a laptop.

Property: LIBVIRT:KVM-BOOTS-CHROOT-FOR

(libvirt:kvm-boots-chroot-for options host &optional additional-properties)

Build a chroot for HOST and boot it as a libvirt KVM virtual machine. Virtio-FS and direct kernel boot are used to avoid the need for either a bootloader or an intermediary disk image. That makes this property suitable for both long-lived virtual machines and quickly bringing up fresh OS installs for testing.

OPTIONS is a plist of keyword parameters.

  • :VCPUS – corresponds to the –vcpus argument to virt-install(1). Defaults to 1.

  • :MEMORY – corresponds to the –memory argument to virt-install(1). Defaults to 1024.

  • :AUTOSTART – Lisp boolean corresponding to the –autostart argument to virt-install(1), and also determines whether applying this property attempts to start the VM. Defaults to nil.

  • :VIRT-OPTIONS – list of additional arguments to pass to virt-install(1).

  • :CHROOT-OPTIONS – passed on to CHROOT:OS-BOOTSTRAPPED-FOR, which see.

  • :ALWAYS-DEPLOYS – Thanks to Virtio-FS, the VM’s root filesystem is simultaneously accessible to both the hypervisor host and the VM. That means the chroot can be updated by Consfigurator even while the VM is running. If this parameter is true then each time this property is applied, the chroot will be updated to reflect any changes to HOST and ADDITIONAL-PROPERTIES, using DEPLOYS. This has the advantage that you do not need to arrange connecting to the VM to keep its configuration up-to-date.

It is not appropriate to set this for untrusted VMs because it could be
used to break out into the hypervisor.  However, even for VMs which will
handle untrusted data you could temporarily set this while incrementally
building up the list of properties the VM will need, before it has been
exposed to anything untrusted.

Some properties do nothing or do not have their full effect when applied
to a chroot, such as properties which start services.  If you have
properties like that, and/or the VM is untrusted, leave this parameter set
to nil, and arrange deploying the host by connecting to the running VM,
perhaps by adding a call to DEPLOYS to the definition of the hypervisor
host (see example below).

Defaults to nil.

- :KERNEL -- Path to the kernel, under the chroot if relative.  Defaults to
  "vmlinuz".

- :INITRD -- Path to the initrd, under the chroot if relative.  Defaults to
  "initrd.img".

- :APPEND -- String to append to the kernel command line.

If the :VCPUS, :MEMORY, :AUTOSTART or :VIRT-OPTIONS parameters change, virt-install(1) will not be rerun; see LIBVIRT:DEFINED-FOR.

Sample usage:

(defhost subbox.laptop.example.com ()
  (os:debian-stable "bullseye" :amd64)
  (apt:installed "linux-image-amd64")

  (hostname:configured)
  (network:static "ens4"
   "192.168.122.31" "192.168.122.1" "255.255.255.0")
  (file:has-content "/etc/resolv.conf" "...")

  (sshd:installed)
  (as "root" (ssh:authorized-keys "...")))

(defhost laptop.example.com ()
  ;; ...

  (file:contains-conf-tab "/etc/hosts"
                          "192.168.122.31" "subbox.laptop.example.com")
  (libvirt:kvm-boots-chroot-for. (:vcpus 2 :memory 2048)
      subbox.laptop.example.com
    ;; Apply TIMEZONE:CONFIGURED-FROM-PARENT here rather than in the
    ;; DEFHOST above because it can be applied only during a subdeployment
    ;; of laptop.example.com -- when we deploy subbox directly, there is
    ;; no parent host.
    (timezone:configured-from-parent))
  (libvirt:when-started subbox.laptop.example.com
    ;; Here we elide most of the configuration necessary to ensure that
    ;; root can SSH into the VM.  You can deploy a passwordless SSH key,
    ;; set up OpenSSH host-based authentication, or use SSH agent
    ;; forwarding across the connection chain by means of which you
    ;; deploy laptop.example.com.  This last option has the disadvantage
    ;; that you can't easily switch to deploying laptop.example.com with
    ;; other connection chains.
    ;;
    ;; For example, you can use (:sudo :sbcl) to deploy laptop.example.com
    ;; and also execute 'xhost +SI:localuser:root' to enable root's SSH
    ;; process to prompt you (the :SUDO connection type preserves
    ;; SSH_AUTH_SOCK when sudoing to root).  Another possibility is to use
    ;; :SETUID to switch back to the account which has your SSH agent in
    ;; the DEPLOYS propapp.
    (deploys ((:ssh :user "root") :sbcl) subbox.laptop.example.com)))

There’s repetition here, and you might like to use DEFPROPSPEC to establish your preferred VM networking setup and corresponding DEPLOYS propapp.

Property: LIBVIRT:KVM-BOOTS-CHROOT

(libvirt:kvm-boots-chroot options properties)

Like LIBVIRT:KVM-BOOTS-CHROOT-FOR but define a new host using PROPERTIES.

Property: LIBVIRT:KVM-BOOTS-LVM-LV-FOR

(libvirt:kvm-boots-lvm-lv-for options host &optional additional-properties)

Install HOST to an LVM LV and boot it as a libvirt KVM virtual machine.

OPTIONS is a plist of keyword parameters. :VCPUS, :MEMORY, :AUTOSTART, :VIRT-OPTIONS and :CHROOT-OPTIONS are as with LIBVIRT:KVM-BOOTS-CHROOT-FOR, which see. This property also accepts:

  • :VOLUME-GROUP – The LVM VG in which to create the LVM LV for HOST. Defaults to “vg_PARENT” where PARENT is the hypervisor’s short hostname.

  • :LOGICAL-VOLUME – The name of the LVM LV to create for HOST. Defaults to “lv_PARENT_CHILD” where PARENT is the hypervisor’s short hostname and CHILD is the short hostname of HOST. Must be unique!

**ANY EXISTING CONTENTS OF THE NAMED LOGICAL VOLUME WILL BE OVERWRITTEN.**

You will probably want to apply DISK:HOST-LOGICAL-VOLUMES-EXIST before
this property, to create the logical volume.  Unapplying this property
does not currently remove the logical volume.

- :VOLUME-SIZE -- The size of the LVM LV to create for HOST.
  Required to be specified.

HOST should have an application of DISK:HAS-VOLUMES specifying how it should be installed to the LVM logical volume. A minimal example for BIOS boot:

(libvirt:kvm-boots-lvm-lv. (:volume-size "5G")
  (os:debian-stable "bookworm" :amd64)
  (disk:has-volumes
   (physical-disk :boots-with '(grub:grub)
                  (partitioned-volume
                   ((partition :partition-typecode #xEF02 :volume-size 1)
                    (partition (ext4-filesystem :mount-point #P"/"))))))
  (hostname:configured "subbox")
  (installer:bootloader-binaries-installed)
  (apt:installed "linux-image-amd64"))

See also “Building disk images” in the Consfigurator user’s manual.

Property: LIBVIRT:KVM-BOOTS-LVM-LV

(libvirt:kvm-boots-lvm-lv options properties)

Like LIBVIRT:KVM-BOOTS-LVM-LV-FOR but define a new host using PROPERTIES.

Function: LIBVIRT:VIRSH-GET-COLUMNS

(libvirt:virsh-get-columns &rest arguments)

Run a virsh command that is expected to yield tabular output, with the given list of ARGUMENTS, and return the rows.