Skip to content

Basics

Sections of a virtfile

Minimal-ish example virtfile

source: virt-builder
image: fedora-42

customize:
- size: 30G
- install: openssh
- run-command: systemctl enable sshd.service

machine:
- vcpu: 2
- memory: 2048

Every virtfile will typically have at least a source and image defined, a "customize" section and a "machine" section.

Source

The source section defines how to acquire the base of the virtual machine, and which tool to use for provisioning it (setting up initial configuration and SSH keys and such).

Currently there are two sources/provisioners:

  • Download and provision using virt-builder
  • Or download a disk image directly from a URL, and use virt-customize for provisioning.

Source: virt-builder

Example

source: virt-builder
image: fedora-42

customize:
  - size: 40G
  - ...

The available images are defined by virt builder's list of templates (see virt-builder --list). You can use the template images that already exist, or create your own images and repositories as per the sources of templates section in virt-builder's documentation.

The options in the customize section are passed directly to virt-builder. We have several examples available through the docs, but for a full list of options and commands available in the image section, see arguments for virt-builder.

Source: url

Example

source: url
url: https://example.com/os-image.qcow2
resize: 40G

customize:
  - install: cloud-guest-utils
  - run-command: growpart /dev/sda 1
  - ...

The options in the customize section are passed directly to virt-customize. We have several examples available through the docs, but for a full list of options and commands available in the image section, see arguments for virt-customize.

Differences when setting a disk size for the VM

For virt-builder, the size is passed directly to virt-builder in the customize section, and will resize the disk and filesystems according to virt-builder's own metadata.

For direct url sources, the size is defined in the top-level 'resize' option. This resizes the disk image only. Resizing partitions and filesystems is left to the VM or your own provisioning steps; the growpart tool can be very useful here. On Debian, this is provided by the cloud-guest-utils package; or on Fedora, the cloud-utils-growpart package.

Machine

The "machine" section defines the hardware and capabilities of the virtual machine in libvirt. These options are passed directly to virt-install. We have several examples available through the docs, but for a full list of options and commands available in the machine section, see arguments for virt-install.

Note

nvirt uses virt-install's "import" option, because we already have an OS installed on the virtual disk by the time it is used.

Because of this, some of virt-install's options aren't applicable (such as --install or --reinstall). Nvirt does not validate those options, so they will still be passed through if you specify them. Validation is left to the underlying tools, but you may get unexpected results.