Skip to content

Basics

Sections of a virtfile

Minimal-ish example virtfile.yml

default:
  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 an identifier ('default' above), source and image defined, a "customize" section and a "machine" section.

Identifier

In the above example (and many others in the docs), "default" is used as the machine identifier. Any reasonable identifier can be used, but nvirt will look for the machine with the id of "default" by default.

If a different identifier is used, you will need to use the -m/--machine option to specify which one nvirt should use.

See multi-machine docs for more info.

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

default:
  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

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

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

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.