Existing Boxes

Libvirt ready boxes can be downloaded at Vagrant Cloud.

Creating Boxes

It’s possible to also create custom boxes using existing boxes as the initial starting point.

Vagrant.configure("2") do |config|
  # this setting is only recommended if planning to export the
  # resulting machine
  config.ssh.insert_key = false

  config.vm.define :test_vm do |test_vm|
    test_vm.vm.box = "fedora/32-cloud-base"
  end
end

Using Vagrant Package

vagrant-libvirt has native support for vagrant package via libguestfs virt-sysprep. virt-sysprep operations can be customized via the VAGRANT_LIBVIRT_VIRT_SYSPREP_OPERATIONS environment variable; see the upstream documentation for further details especially on default sysprep operations enabled for your system.

Options to the virt-sysprep command call can be passed via VAGRANT_LIBVIRT_VIRT_SYSPREP_OPTIONS environment variable.

$ export VAGRANT_LIBVIRT_VIRT_SYSPREP_OPTIONS="--delete /etc/hostname"
$ vagrant package

For example, on Chef bento VMs that require SSH hostkeys already set (e.g. bento/debian-7) as well as leave existing LVM UUIDs untouched (e.g. bento/ubuntu-18.04), these can be packaged into vagrant-libvirt boxes like so:

$ export VAGRANT_LIBVIRT_VIRT_SYSPREP_OPERATIONS="defaults,-ssh-userdir,-ssh-hostkeys,-lvm-uuids"
$ vagrant package

From qcow2 Image

To create a vagrant-libvirt box from a qcow2 image, run create_box.sh (located in the tools directory):

$ create_box.sh ubuntu14.qcow2

Packer

You can also create a box by using Packer. Packer templates for use with vagrant-libvirt are available at https://github.com/jakobadam/packer-qemu-templates. After cloning that project you can build a vagrant-libvirt box by running:

$ cd packer-qemu-templates
$ packer build ubuntu-14.04-server-amd64-vagrant.json

Box Formats

Version 1

This is the original format that most boxes currently use.

You can view an example box in the example_box/directory. That directory also contains instructions on how to build a box.

The box is a tarball containing:

• qcow2 image file named box.img
• metadata.json file describing box image (provider, virtual_size, format)
• Vagrantfile that does default settings for the provider-specific configuration for this provider

Version 2 (Experimental)

Due to the limitation of only being able to handle a single disk with the version 1 format, a new format was added to support boxes that need to specify multiple disks. This is still currently experimental and as such is not the default format. Packaging support is in place and will automatically alert you if attempting to package a machine with additional disks attached. To enable the new format to verify ahead of it becoming the default, export the variable VAGRANT_LIBVIRT_BOX_FORMAT_VERSION=v2 before running vagrant package

Additionally there is a script in the tools folder (tools/create_box_with_two_disks.sh) that provides a guideline on how to create such a box from qcow2 images should it not be practical use a vagrant machine with additional storage as a starting point.

At it’s most basic, it expects an array of disks to allow a specific order to be presented. Disks will be attached in this order and as such assume device names base on this within the VM. The ‘path’ attribute is required, and is expected to be relative to the base of the box. This should allow placing the disk images within a nested directory within the box if it useful for those with a larger number of disks. The name allows overriding the target volume name that will be used in the libvirt storage pool. Note that vagrant-libvirt will still prefix the volume name with #{box_name}_vagrant_box_image_#{box_version}_ to avoid accidental clashes with other boxes.

Format and virtual size need no longer be specified as they are now retrieved directly from the provided image using qemu-img info ....

Example format:

{
  "disks": [
      {
          "path": "disk1.img"
      },
      {
          "path": "disk2.img",
          "name": "secondary_disk"
      },
      {
          "path": "disk3.img"
      }
  ],
  "provider": "libvirt"
}