404
Page not found :(
The requested page could not be found.
Page not found :(
The requested page could not be found.
Vagrant-libvirt is a Vagrant plugin that adds a Libvirt provider to Vagrant, allowing Vagrant to control and provision machines via Libvirt toolkit.
Actual version is still a development one. Feedback is welcome and can help a lot :-)
You can find the source code for Vagrant Libvirt plugin at GitHub: https://github.com/vagrant-libvirt/vagrant-libvirt
You can find the source code for Vagrant Libvirt QA testing of install instructions at GitHub: https://github.com/vagrant-libvirt/vagrant-libvirt-qa
Creating issues can be done via GitHub: https://github.com/vagrant-libvirt/vagrant-libvirt/issues
To ask questions or discuss a problem ahead of logging an issue you can use:
up, destroy, suspend, resume, halt, ssh, reload, package and provision commands.rsync, nfs, 9p or virtiofs.Vagrant goes through steps below when creating new project:
Libvirt ready boxes can be downloaded at Vagrant Cloud.
It’s possible to also create custom boxes using existing boxes as the initial starting point.
config.ssh.insert_key = false in the original Vagrantfile as otherwise Vagrant will replace the default connection key-pair that is required on first boot with one specific to the machine and prevent the default key from working on the exported result. 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
+endvagrant-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
+To create a vagrant-libvirt box from a qcow2 image, run create_box.sh (located in the tools directory):
$ create_box.sh ubuntu14.qcow2
+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
+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:
box.imgmetadata.json file describing box image (provider, virtual_size, format)Vagrantfile that does default settings for the provider-specific configuration for this providerDue 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"
+}
+Although it should work without any configuration for most people, this provider exposes quite a few provider-specific configuration options.
The following options allow you to configure how vagrant-libvirt connects to Libvirt, and are used to generate the Libvirt connection URI:
driver - A hypervisor name to access. For now only KVM and QEMU are supportedhost - The name of the server, where Libvirtd is runningconnect_via_ssh - If use ssh tunnel to connect to Libvirt. Absolutely needed to access Libvirt on remote host. It will not be able to get the IP address of a started VM otherwise.username - Username and password to access Libvirtpassword - Password to access Libvirtid_ssh_key_file - If not nil, uses this ssh private key to access Libvirt. Default is $HOME/.ssh/id_rsa. Prepends $HOME/.ssh/ if no directorysocket - Path to the Libvirt unix socket (e.g. /var/run/libvirt/libvirt-sock)uri - For advanced usage. Directly specifies what Libvirt connection URI vagrant-libvirt should use. Overrides all above connection configuration optionsproxy_command - For advanced usage. When connecting to remote libvirt instances, if the default constructed proxy_command which uses -W %h:%p does not work, set this as needed. It performs interpolation using {key} and supports only {host}, {username}, and {id_ssh_key_file}. This is to try and avoid issues with escaping % and $ which might be necessary to the ssh command itself. e.g.: libvirt.proxy_command = "ssh {host} -l {username} -i {id_ssh_key_file} nc %h %p"In the event that none of these are set (excluding the driver option) the provider will attempt to retrieve the uri from the environment variable LIBVIRT_DEFAULT_URI similar to how virsh works. If any of them are set, it will ignore the environment variable. The reason the driver option is ignored is that it is not uncommon for this to be explicitly set on the box itself and there is no easily to determine whether it is being set by the user or the box packager.
Connection-independent options:
storage_pool_name - Libvirt storage pool name, where box image and instance snapshots (if snapshot_pool_name is not set) will be stored.snapshot_pool_name - Libvirt storage pool name. If set, the created snapshot of the instance will be stored at this location instead of storage_pool_name.Connection example:
Vagrant.configure("2") do |config|
+ config.vm.provider :libvirt do |libvirt|
+ libvirt.host = "example.com"
+ end
+end
+title - A short description of the domain.description - A human readable description of the virtual machine.random_hostname - To create a domain name with extra information on the end to prevent hostname conflicts.default_prefix - The default Libvirt guest name becomes a concatenation of the <current_directory>_<guest_name>. The current working directory is the default prefix to the guest name. The default_prefix options allow you to set the guest name prefix.disk_bus - The type of disk device to emulate. Defaults to virtio if not set. Possible values are documented in Libvirt’s description for target. NOTE: this option applies only to disks associated with a box image. To set the bus type on additional disks, see the Additional Disks section.disk_controller_model - the controller model to use. Ignored unless either disk_bus is set to scsi or disk_device starts with sd, which is a hint to use scsi. Defaults to virtio-scsi when it encounters either of the config values for disk_bus or disk_device. See libvirt controller models for other possible values. NOTE: this option applies only to the disks associated with a box image.disk_device - The disk device to emulate. Defaults to vda if not set, which should be fine for paravirtualized guests, but some fully virtualized guests may require hda. NOTE: this option also applies only to disks associated with a box image.disk_address_type - The address type of disk device to emulate. Libvirt uses a sensible default if not set, but some fully virtualized guests may need to override this (e.g. Debian on virt machine may need virtio-mmio). Possible values are documented in libvirt’s description for address.disk_driver - Extra options for the main disk driver (see Libvirt documentation). NOTE: this option also applies only to disks associated with a box image. In all cases, the value nil can be used to force the hypervisor default behaviour (e.g. to override settings defined in top-level Vagrantfiles). Supported options include: :cache - Controls the cache mechanism. Possible values are “default”, “none”, “writethrough”, “writeback”, “directsync” and “unsafe”.:io - Controls specific policies on I/O. Possible values are “threads” and “native”.:copy_on_read - Controls whether to copy read backing file into the image file. The value can be either “on” or “off”.:discard - Controls whether discard requests (also known as “trim” or “unmap”) are ignored or passed to the filesystem. Possible values are “unmap” or “ignore”. Note: for discard to work, you will likely also need to set disk_bus = 'scsi':detect_zeroes - Controls whether to detect zero write requests. The value can be “off”, “on” or “unmap”.address_type - Address type of disk device to emulate. If unspecified, Libvirt uses a sensible default.nic_model_type - parameter specifies the model of the network adapter when you create a domain value by default virtio KVM believe possible values, see the documentation for Libvirt.shares - Proportional weighted share for the domain relative to others. For more details see documentation.memory - Amount of memory in MBytes. Defaults to 512 if not set.cpus - Number of virtual cpus. Defaults to 1 if not set.cpuset - Physical cpus to which the vcpus can be pinned. For more details see documentation.cputopology - Number of CPU sockets, cores and threads running per core. All fields of :sockets, :cores and :threads are mandatory, cpus domain option must be present and must be equal to total count of sockets * cores * threads. For more details see documentation.
Vagrant.configure("2") do |config|
+ config.vm.provider :libvirt do |libvirt|
+ libvirt.cpus = 4
+ libvirt.cpuset = '1-4,^3,6'
+ libvirt.cputopology :sockets => '2', :cores => '2', :threads => '1'
+ end
+end
+cpuaffinitiy - Mapping of vCPUs to host CPUs. See vcpupin.
Vagrant.configure("2") do |config|
+ config.vm.provider :libvirt do |libvirt|
+ libvirt.cpus = 4
+ libvirt.cpuaffinitiy 0 => '0-4,^3', 1 => '5', 2 => '6,7'
+ end
+end
+nodeset - Physical NUMA nodes where virtual memory can be pinned. For more details see documentation.nested - Enable nested virtualization. Default is false.cpu_mode - CPU emulation mode. Defaults to ‘host-model’ if not set. Allowed values: host-model, host-passthrough, custom.cpu_model - CPU Model. Defaults to ‘qemu64’ if not set and cpu_mode is custom and to ‘’ otherwise. This can really only be used when setting cpu_mode to custom.cpu_fallback - Whether to allow Libvirt to fall back to a CPU model close to the specified model if features in the guest CPU are not supported on the host. Defaults to ‘allow’ if not set. Allowed values: allow, forbid.numa_nodes - Specify an array of NUMA nodes for the guest. The syntax is similar to what would be set in the domain XML. memory must be in MB. Symmetrical and asymmetrical topologies are supported but make sure your total count of defined CPUs adds up to v.cpus.
The sum of all the memory defined here will act as your total memory for your guest VM. This sum will override what is set in v.memory
v.cpus = 4
+v.numa_nodes = [
+ {:cpus => "0-1", :memory => "1024"},
+ {:cpus => "2-3", :memory => "4096"}
+]
+launchsecurity - Configure Secure Encryption Virtualization for the guest, requires additional components to be configured to work, see examples. For more information look at libvirt documentation. libvirt.launchsecurity :type => 'sev', :cbitpos => 47, :reducedPhysBits => 1, :policy => "0x0003"
+memtune - Configure the memtune settings for the guest, primarily exposed to facilitate enabling Secure Encryption Virtualization. Note that when configuring hard_limit that the value is in kB as opposed to libvirt.memory which is in Mb. Additionally it must be set to be higher than libvirt.memory, see libvirt documentation for details on why. libvirt.memtune :type => "hard_limit", :value => 2500000 # Note here the value in kB (not in Mb)
+loader - Sets path to custom UEFI loader.kernel - To launch the guest with a kernel residing on host filesystems. Equivalent to qemu -kernel.initrd - To specify the initramfs/initrd to use for the guest. Equivalent to qemu -initrd.cmd_line - Arguments passed on to the guest kernel initramfs or initrd to use. Equivalent to qemu -append, only possible to use in combination with initrd and kernel.graphics_type - Sets the protocol used to expose the guest display. Defaults to vnc. Possible values are “sdl”, “curses”, “none”, “gtk”, “vnc” or “spice”.graphics_port - Sets the port for the display protocol to bind to. Defaults to -1, which will be set automatically by libvirt.graphics_websocket - Sets the websocket port for the display protocol to bind to. Defaults to -1, which will be set automatically by libvirt. The autoport configuration has no effect on the websocket port due to security reasons.graphics_ip - Sets the IP for the display protocol to bind to. Defaults to “127.0.0.1”.graphics_passwd - Sets the password for the display protocol. Working for vnc and Spice. by default working without passsword.graphics_autoport - Sets autoport for graphics, Libvirt in this case ignores graphics_port value, Defaults to ‘yes’. Possible value are “yes” and “no”graphics_gl - Set to true to enable OpenGL. Defaults to true if video_accel3d is true.keymap - Set keymap for vm. default: en-uskvm_hidden - Hide the hypervisor from the guest. Useful for GPU passthrough on stubborn drivers. Default is false.video_type - Sets the graphics card type exposed to the guest. Defaults to “cirrus”. Possible values are “vga”, “cirrus”, “vmvga”, “xen”, “vbox”, or “qxl”.video_vram - Used by some graphics card types to vary the amount of RAM dedicated to video. Defaults to 16384.video_accel3d - Set to true to enable 3D acceleration. Defaults to false.sound_type - Set the virtual sound card Defaults to “ich6”.machine_type - Sets machine type. Equivalent to qemu -machine. Use qemu-system-x86_64 -machine help to get a list of supported machines.machine_arch - Sets machine architecture. This helps Libvirt to determine the correct emulator type. Possible values depend on your version of QEMU. For possible values, see which emulator executable qemu-system-* your system provides. Common examples are aarch64, alpha, arm, cris, i386, lm32, m68k, microblaze, microblazeel, mips, mips64, mips64el, mipsel, moxie, or32, ppc, ppc64, ppcemb, s390x, sh4, sh4eb, sparc, sparc64, tricore, unicore32, x86_64, xtensa, xtensaeb.machine_virtual_size - Sets the disk size in GB for the machine overriding the default specified in the box. Allows boxes to defined with a minimal size disk by default and to be grown to a larger size at creation time. Will ignore sizes smaller than the size specified by the box metadata. Note that currently there is no support for automatically resizing the filesystem to take advantage of the larger disk.emulator_path - Explicitly select which device model emulator to use by providing the path, e.g. /usr/bin/qemu-system-x86_64. This is especially useful on systems that fail to select it automatically based on machine_arch which then results in a capability error.boot - Change the boot order and enables the boot menu. Possible options are “hd”, “network”, “cdrom”. Defaults to “hd” with boot menu disabled. When “network” is set without “hd”, only all NICs will be tried; see below for more detail. Defining this in subsequent provider blocks or latter Vagrantfile’s (see Load Order and Merging) will result in the definition in the last block being used.nic_adapter_count - Defaults to ‘8’. Only use case for increasing this count is for VMs that virtualize switches such as Cumulus Linux. Max value for Cumulus Linux VMs is 33.uuid - Force a domain UUID. Defaults to autogenerated value by Libvirt if not set.suspend_mode - What is done on vagrant suspend. Possible values: ‘pause’, ‘managedsave’. Pause mode executes a la virsh suspend, which just pauses execution of a VM, not freeing resources. Managed save mode does a la virsh managedsave which frees resources suspending a domain.tpm_model - The model of the TPM to which you wish to connect.tpm_type - The type of TPM device to which you are connecting.tpm_path - The path to the TPM device on the host system.tpm_version - The TPM version to use.sysinfo - The SMBIOS System Information to use. This is a hash with key names aligning with the different section XML tags of bios, system, base board, chassis, and oem strings. Nested hashes then use entry attribute names as the keys for the values to assign, except for oem strings which is a simple array of strings.dtb - The device tree blob file, mostly used for non-x86 platforms. In case the device tree isn’t added in-line to the kernel, it can be manually specified here.autostart - Automatically start the domain when the host boots. Defaults to ‘false’.channel - Libvirt channels. Configure a private communication channel between the host and guest, e.g. for use by the QEMU guest agent and the Spice/QXL graphics type.mgmt_attach - Decide if VM has interface in mgmt network. If set to ‘false’ it is not possible to communicate with VM through vagrant ssh or run provisioning. Setting to ‘false’ is only possible when VM doesn’t use box or vagrant is told not to connect via ssh. Defaults set to ‘true’.serial - libvirt serial devices. Configure a serial/console port to communicate with the guest. Can be used to log to file boot time messages sent to ttyS0 console by the guest.Specific domain settings can be set for each domain separately in multi-VM environment. Example below shows a part of Vagrantfile, where specific options are set for dbserver domain.
Vagrant.configure("2") do |config|
+ config.vm.define :dbserver do |dbserver|
+ dbserver.vm.box = "centos64"
+ dbserver.vm.provider :libvirt do |domain|
+ domain.memory = 2048
+ domain.cpus = 2
+ domain.nested = true
+ domain.disk_driver :cache => 'none'
+ end
+ end
+
+ # ...
+The following example shows part of a Vagrantfile that enables the VM to boot from a network interface first and a hard disk second. This could be used to run VMs that are meant to be a PXE booted machines. Be aware that if hd is not specified as a boot option, it will never be tried.
Vagrant.configure("2") do |config|
+ config.vm.define :pxeclient do |pxeclient|
+ pxeclient.vm.box = "centos64"
+ pxeclient.vm.provider :libvirt do |domain|
+ domain.boot 'network'
+ domain.boot 'hd'
+ end
+ end
+
+ # ...
+On vagrant reload the following domain specific attributes are updated in defined domain:
disk_bus - Is updated only on disks. It skips CDROMsnic_model_type - Updatedmemory - Updatedcpus - Updatednested - Updatedcpu_mode - Updated. Pay attention that custom mode is not supportedgraphics_type - Updatedgraphics_port - Updatedgraphics_websocket - Updatedgraphics_ip - Updatedgraphics_passwd - Updatedgraphics_autoport - Updatedkeymap - Updatedvideo_type - Updatedvideo_vram - Updatedtpm_model - Updatedtpm_type - Updatedtpm_path - Updatedtpm_version - UpdatedNetworking features in the form of config.vm.network support private networks concept. It supports both the virtual network switch routing types and the point to point Guest OS to Guest OS setting using UDP/Mcast/TCP tunnel interfaces.
http://wiki.libvirt.org/page/VirtualNetworking
https://libvirt.org/formatdomain.html#tcp-tunnel
http://libvirt.org/formatdomain.html#multicast-tunnel
http://libvirt.org/formatdomain.html#udp-unicast-tunnel (in Libvirt v1.2.20 and higher)
Public Network interfaces are currently implemented using the macvtap driver. The macvtap driver is only available with the Linux Kernel version >= 2.6.24. See the following Libvirt documentation for the details of the macvtap usage.
http://www.libvirt.org/formatdomain.html#direct-attachment-to-physical-interface
An examples of network interface definitions:
# Private network using virtual network switching
+ config.vm.define :test_vm1 do |test_vm1|
+ test_vm1.vm.network :private_network, :ip => "10.20.30.40"
+ end
+
+ # Private network using DHCP and a custom network
+ config.vm.define :test_vm1 do |test_vm1|
+ test_vm1.vm.network :private_network,
+ :type => "dhcp",
+ :libvirt__network_address => '10.20.30.0'
+ end
+
+ # Private network (as above) using a domain name
+ config.vm.define :test_vm1 do |test_vm1|
+ test_vm1.vm.network :private_network,
+ :ip => "10.20.30.40",
+ :libvirt__domain_name => "test.local"
+ end
+
+ # Private network. Point to Point between 2 Guest OS using a TCP tunnel
+ # Guest 1
+ config.vm.define :test_vm1 do |test_vm1|
+ test_vm1.vm.network :private_network,
+ :libvirt__tunnel_type => 'server',
+ # default is 127.0.0.1 if omitted
+ # :libvirt__tunnel_ip => '127.0.0.1',
+ :libvirt__tunnel_port => '11111'
+ # network with ipv6 support
+ test_vm1.vm.network :private_network,
+ :ip => "10.20.5.42",
+ :libvirt__guest_ipv6 => "yes",
+ :libvirt__ipv6_address => "2001:db8:ca2:6::1",
+ :libvirt__ipv6_prefix => "64"
+
+ # Guest 2
+ config.vm.define :test_vm2 do |test_vm2|
+ test_vm2.vm.network :private_network,
+ :libvirt__tunnel_type => 'client',
+ # default is 127.0.0.1 if omitted
+ # :libvirt__tunnel_ip => '127.0.0.1',
+ :libvirt__tunnel_port => '11111'
+ # network with ipv6 support
+ test_vm2.vm.network :private_network,
+ :ip => "10.20.5.45",
+ :libvirt__guest_ipv6 => "yes",
+ :libvirt__ipv6_address => "2001:db8:ca2:6::1",
+ :libvirt__ipv6_prefix => "64"
+
+
+ # Public Network
+ config.vm.define :test_vm1 do |test_vm1|
+ test_vm1.vm.network :public_network,
+ :dev => "virbr0",
+ :mode => "bridge",
+ :type => "bridge"
+ end
+In example below, one network interface is configured for VM test_vm1. After you run vagrant up, VM will be accessible on IP address 10.20.30.40. So if you install a web server via provisioner, you will be able to access your testing server on http://10.20.30.40 URL. But beware that this address is private to Libvirt host only. It’s not visible outside of the hypervisor box.
If network 10.20.30.0/24 doesn’t exist, provider will create it. By default created networks are NATed to outside world, so your VM will be able to connect to the internet (if hypervisor can). And by default, DHCP is offering addresses on newly created networks.
The second interface is created and bridged into the physical device eth0. This mechanism uses the macvtap Kernel driver and therefore does not require an existing bridge device. This configuration assumes that DHCP and DNS services are being provided by the public network. This public interface should be reachable by anyone with access to the public network.
Note: These options are not applicable to public network interfaces.
There is a way to pass specific options for Libvirt provider when using config.vm.network to configure new network interface. Each parameter name starts with libvirt__ string. Here is a list of those options:
:libvirt__network_name - Name of Libvirt network to connect to. By default, network ‘default’ is used.:libvirt__netmask - Used only together with :ip option. Default is ‘255.255.255.0’.:libvirt__network_address - Used only when :type is set to dhcp. Only /24 subnet is supported. Default is 172.28.128.0.:libvirt__host_ip - Address to use for the host (not guest). Default is first possible address (after network address).:libvirt__domain_name - DNS domain of the DHCP server. Used only when creating new network.:libvirt__dhcp_enabled - If DHCP will offer addresses, or not. Used only when creating new network. Default is true.:libvirt__dhcp_start - First address given out via DHCP. Default is third address in range (after network name and gateway).:libvirt__dhcp_stop - Last address given out via DHCP. Default is last possible address in range (before broadcast address).:libvirt__dhcp_bootp_file - The file to be used for the boot image. Used only when dhcp is enabled.:libvirt__dhcp_bootp_server - The server that runs the DHCP server. Used only when dhcp is enabled.By default is the same host that runs the DHCP server.:libvirt__tftp_root - Path to the root directory served via TFTP.:libvirt__adapter - Number specifying sequence number of interface.:libvirt__forward_mode - Specify one of veryisolated, none, open, nat or route options. This option is used only when creating new network. Mode none will create isolated network without NATing or routing outside. You will want to use NATed forwarding typically to reach networks outside of hypervisor. Routed forwarding is typically useful to reach other networks within hypervisor. veryisolated described here. By default, option nat is used.:libvirt__forward_device - Name of interface/device, where network should be forwarded (NATed or routed). Used only when creating new network. By default, all physical interfaces are used.:libvirt__tunnel_type - Set to ‘udp’ if using UDP unicast tunnel mode (libvirt v1.2.20 or higher). Set this to either “server” or “client” for tcp tunneling. Set this to ‘mcast’ if using multicast tunneling. This configuration type uses tunnels to generate point to point connections between Guests. Useful for Switch VMs like Cumulus Linux. No virtual switch setting like libvirt__network_name applies with tunnel interfaces and will be ignored if configured.:libvirt__tunnel_ip - Sets the source IP of the Libvirt tunnel interface. By default this is 127.0.0.1 for TCP and UDP tunnels and 239.255.1.1 for Multicast tunnels. It populates the address field in the <source address="XXX"> of the interface xml configuration.:libvirt__tunnel_port - Sets the source port the tcp/udp/mcast tunnel with use. This port information is placed in the <source port=XXX/> section of interface xml configuration.:libvirt__tunnel_local_port - Sets the local port used by the udp tunnel interface type. It populates the port field in the <local port=XXX"> section of the interface xml configuration. (This feature only works in Libvirt 1.2.20 and higher):libvirt__tunnel_local_ip - Sets the local IP used by the udp tunnel interface type. It populates the ip entry of the <local address=XXX"> section of the interface xml configuration. (This feature only works in Libvirt 1.2.20 and higher):libvirt__guest_ipv6 - Enable or disable guest-to-guest IPv6 communication. See here, and here for for more information. Note: takes either ‘yes’ or ‘no’ for value:libvirt__ipv6_address - Define ipv6 address, require also prefix.:libvirt__ipv6_prefix - Define ipv6 prefix. generate string <ip family="ipv6" address="address" prefix="prefix" >:libvirt__iface_name - Define a name for the corresponding network interface created on the host. With this feature one can simulate physical link failures. Note that you cannot use names reserved for libvirt’s usage based on documentation.:mac - MAC address for the interface. Note: specify this in lowercase since Vagrant network scripts assume it will be!:libvirt__mtu - MTU size for the Libvirt network, if not defined, the created network will use the Libvirt default (1500). VMs still need to set the MTU accordingly.:model_type - parameter specifies the model of the network adapter when you create a domain value by default virtio KVM believe possible values, see the documentation for Libvirt:libvirt__driver_name - Define which network driver to use. More info:libvirt__driver_queues - Define a number of queues to be used for network interface. Set equal to number of vCPUs for best performance. More info:autostart - Automatic startup of network by the Libvirt daemon. If not specified the default is ‘false’.:bus - The bus of the PCI device. Both :bus and :slot have to be defined.:slot - The slot of the PCI device. Both :bus and :slot have to be defined.:libvirt__always_destroy - Allow domains that use but did not create a network to destroy it when the domain is destroyed (default: true). Set to false to only allow the domain that created the network to destroy it.When the option :libvirt__dhcp_enabled is to to ‘false’ it shouldn’t matter whether the virtual network contains a DHCP server or not and vagrant-libvirt should not fail on it. The only situation where vagrant-libvirt should fail is when DHCP is requested but isn’t configured on a matching already existing virtual network.
:dev - Physical device that the public interface should use. Default is ‘eth0’.:mode - The mode in which the public interface should operate in. Supported modes are available from the libvirt documentation. Default mode is ‘bridge’.:type - is type of interface.(<interface type="#{@type}">):mac - MAC address for the interface.:network_name - Name of Libvirt network to connect to.:portgroup - Name of Libvirt portgroup to connect to.:ovs - Support to connect to an Open vSwitch bridge device. Default is ‘false’.:trust_guest_rx_filters - Support trustGuestRxFilters attribute. Details are listed here. Default is ‘false’.:libvirt__iface_name - Define a name for the corresponding network interface that is created on the host connected to the bridge dev. This can be used to help attach VLAN tags to specific VMs by adjusting the pattern to match. Note that you cannot use names reserved for libvirt’s usage based on documentation.:libvirt__mtu - MTU size for the Libvirt interface, if not defined, the created network will use the Libvirt default (1500). VMs still need to configure their internal interface MTUs.Additionally for public networks, to facilitate validating if the device provided can be used, vagrant-libvirt will check both the host interfaces visible to libvirt and the existing networks for any existing bridge names. While some name patterns are automatically excluded as presumed incorrect, if this pattern list is incorrect it may be overridden by setting the option:
host_device_exclude_prefixes - ignore any device starting with any of these string patterns as a valid bridge device for a public network definition.vagrant-libvirt uses a private network to perform some management operations on VMs. All VMs will have an interface connected to this network and an IP address dynamically assigned by Libvirt unless you set :mgmt_attach to ‘false’. This is in addition to any networks you configure. The name and address used by this network are configurable at the provider level.
management_network_name - Name of Libvirt network to which all VMs will be connected. If not specified the default is ‘vagrant-libvirt’.management_network_address - Address of network to which all VMs will be connected. Must include the address and subnet mask. If not specified the default is ‘192.168.121.0/24’.management_network_mode - Network mode for the Libvirt management network. Specify one of veryisolated, none, open, nat or route options. Further documented under Private Networksmanagement_network_guest_ipv6 - Enable or disable guest-to-guest IPv6 communication. See here, and here for for more information.management_network_autostart - Automatic startup of mgmt network, if not specified the default is ‘false’.management_network_pci_bus - The bus of the PCI device.management_network_pci_slot - The slot of the PCI device.management_network_mac - MAC address of management network interface.management_network_domain - Domain name assigned to the management network.management_network_mtu - MTU size of management network. If not specified, the Libvirt default (1500) will be used.management_network_keep - Starting from version 0.7.0, always_destroy is set to true by default for any network. This option allows to change this behaviour for the management network.management_network_iface_name - Allow controlling of the network device name that appears on the host for the management network, same as :libvirt__iface_name for public and private network definitions. (unreleased).management_network_model_type - Model of the network adapter to use for the management interface. Default is ‘virtio’.You may wonder how vagrant-libvirt knows the IP address a VM received. Libvirt doesn’t provide a standard way to find out the IP address of a running domain. But we do know the MAC address of the virtual machine’s interface on the management network. Libvirt is closely connected with dnsmasq, which acts as a DHCP server. dnsmasq writes lease information in the /var/lib/libvirt/dnsmasq directory. Vagrant-libvirt looks for the MAC address in this file and extracts the corresponding IP address.
It is also possible to use the Qemu Agent to extract the management interface configuration from the booted virtual machine. This is helpful in libvirt environments where no local dnsmasq is used for automatic address assignment, but external dhcp services via bridged libvirt networks.
Prerequisite is to enable the qemu agent channel via (Libvirt communication channels) and the virtual machine image must have the agent pre-installed before deploy. The agent will start automatically if it detects an attached channel during boot.
qemu_use_agent - false by default, if set to true, attempt to extract configured ip address via qemu agent.By default if qemu_use_agent is set to true the code will automatically inject a suitable channel unless there already exists an entry with a :target_name matching 'org.qemu.guest_agent.'. Alternatively if setting qemu_use_agent but, needing to disable the addition of the channel, simply use a disabled flag as follows:
Vagrant.configure(2) do |config|
+ config.vm.provider :libvirt do |libvirt|
+ libvirt.channel :type => 'unix', :target_name => 'org.qemu.guest_agent.0', :disabled => true
+ end
+end
+To use the management network interface with an external dhcp service you need to setup a bridged host network manually and define it via management_network_name in your Vagrantfile.
You can create and attach additional disks to a VM via libvirt.storage :file. It has a number of options:
path - Location of the disk image. If unspecified, a path is automatically chosen in the same storage pool as the VMs primary disk.device - Name of the device node the disk image will have in the VM, e.g. vdb. If unspecified, the next available device is chosen.size - Size of the disk image. If unspecified, defaults to 10G.type - Type of disk image to create. Defaults to qcow2.bus - Type of bus to connect device to. Defaults to virtio.allow_existing - Set to true if you want to allow the VM to use a pre-existing disk. If the disk doesn’t exist it will be created. Disks with this option set to true need to be removed manually.shareable - Set to true if you want to simulate shared SAN storage.serial - Serial number of the disk device.wwn - WWN number of the disk device.The following disk performance options can also be configured (see the libvirt documentation for possible values or here for a fuller explanation). In all cases, the options use the hypervisor default if not specified, or if set to nil.
cache - Cache mode to use. Value may be default, none, writeback, writethrough, directsync or unsafe.io - Controls specific policies on I/O. Value may be threads or native.copy_on_read - Controls whether to copy read backing file into the image file. Value may be on or off.discard - Controls whether discard requests (also known as “trim” or “unmap”) are ignored or passed to the filesystem. Value may be unmap or ignore. Note: for discard to work, you will likely also need to set :bus => 'scsi'detect_zeroes - Controls whether to detect zero write requests. Value may be off, on or unmap.The following example creates two additional disks.
Vagrant.configure("2") do |config|
+ config.vm.provider :libvirt do |libvirt|
+ libvirt.storage :file, :size => '20G'
+ libvirt.storage :file, :size => '40G', :bus => 'scsi', :type => 'raw', :discard => 'unmap', :detect_zeroes => 'on'
+ end
+end
+For shared SAN storage to work the following example can be used:
Vagrant.configure("2") do |config|
+ config.vm.provider :libvirt do |libvirt|
+ libvirt.storage :file, :size => '20G', :path => 'my_shared_disk.img', :allow_existing => true, :shareable => true, :type => 'raw'
+ end
+end
+On vagrant reload the following additional disk attributes are updated in defined domain:
bus - Updated. Uses device as a search marker. It is not required to define device, but it’s recommended. If device is defined then the order of additional disk definition becomes irrelevant.You can attach up to four CDROMs to a VM via libvirt.storage :file, :device => :cdrom. Available options are:
path - The path to the iso to be used for the CDROM drive.dev - The device to use (hda, hdb, hdc, or hdd). This will be automatically determined if unspecified.bus - The bus to use for the CDROM drive. Defaults to ideThe following example creates three CDROM drives in the VM:
Vagrant.configure("2") do |config|
+ config.vm.provider :libvirt do |libvirt|
+ libvirt.storage :file, :device => :cdrom, :path => '/path/to/iso1.iso'
+ libvirt.storage :file, :device => :cdrom, :path => '/path/to/iso2.iso'
+ libvirt.storage :file, :device => :cdrom, :path => '/path/to/iso3.iso'
+ end
+end
+You can attach up to two floppies to a VM via libvirt.storage :file, :device => :floppy. Available options are:
path - The path to the vfd image to be used for the floppy drive.dev - The device to use (fda or fdb). This will be automatically determined if unspecified.The following example creates a floppy drive in the VM:
Vagrant.configure("2") do |config|
+ config.vm.provider :libvirt do |libvirt|
+ libvirt.storage :file, :device => :floppy, :path => '/path/to/floppy.vfs'
+ end
+end
+You can specify multiple inputs to the VM via libvirt.input. Available options are listed below. Note that both options are required:
type - The type of the inputbus - The bus of the inputVagrant.configure("2") do |config|
+ config.vm.provider :libvirt do |libvirt|
+ # this is the default
+ # libvirt.input :type => "mouse", :bus => "ps2"
+
+ # very useful when having mouse issues when viewing VM via VNC
+ libvirt.input :type => "tablet", :bus => "usb"
+ end
+end
+You can specify multiple PCI devices to passthrough to the VM via libvirt.pci. Available options are listed below. Note that all options are required, except domain, which defaults to 0x0000:
domain - The domain of the PCI devicebus - The bus of the PCI deviceslot - The slot of the PCI devicefunction - The function of the PCI deviceYou can extract that information from output of lspci command. First characters of each line are in format [<domain>]:[<bus>]:[<slot>].[<func>]. For example:
$ lspci| grep NVIDIA
+0000:03:00.0 VGA compatible controller: NVIDIA Corporation GK110B [GeForce GTX TITAN Black] (rev a1)
+In that case domain is 0x0000, bus is 0x03, slot is 0x00 and function is 0x0.
Vagrant.configure("2") do |config|
+ config.vm.provider :libvirt do |libvirt|
+ libvirt.pci :domain => '0x0000', :bus => '0x06', :slot => '0x12', :function => '0x5'
+
+ # Add another one if it is necessary
+ libvirt.pci :domain => '0x0000', :bus => '0x03', :slot => '0x00', :function => '0x0'
+ end
+end
+Note! Above options affect configuration only at domain creation. It won’t change VM behaviour on vagrant reload after domain was created.
Don’t forget to set kvm_hidden option to true especially if you are passthroughing NVIDIA GPUs. Otherwise GPU is visible from VM but cannot be operated.
There are several ways to pass a USB device through to a running instance:
libvirt.usb to attach a USB device at boot, with the device ID specified in the Vagrantfilevirt-viewer or virt-manager) to attach the device at runtime via USB redirectorsvirsh attach-device once the VM is running (however, this is outside the scope of this readme)In all cases, if you wish to use a high-speed USB device, you will need to use libvirt.usb_controller to specify a USB2 or USB3 controller, as the default configuration only exposes a USB1.1 controller.
The USB controller can be configured using libvirt.usb_controller, with the following options:
model - The USB controller device model to emulate. (mandatory)ports - The number of devices that can be connected to the controller.Vagrant.configure("2") do |config|
+ config.vm.provider :libvirt do |libvirt|
+ # Set up a USB3 controller
+ libvirt.usb_controller :model => "qemu-xhci"
+ end
+end
+See the libvirt documentation for a list of valid models.
If any USB devices are passed through by setting libvirt.usb or libvirt.redirdev, a default controller will be added using the model qemu-xhci in the absence of a user specified one. This should help ensure more devices work out of the box as the default configured by libvirt is pii3-uhci, which appears to only work for USB 1 devices and does not work as expected when connected via a USB 2 controller, while the xhci stack should work for all versions of USB.
You can specify multiple USB devices to passthrough to the VM via libvirt.usb. The device can be specified by the following options:
bus - The USB bus ID, e.g. “1”device - The USB device ID, e.g. “2”vendor - The USB devices vendor ID (VID), e.g. “0x1234”product - The USB devices product ID (PID), e.g. “0xabcd”At least one of these has to be specified, and bus and device may only be used together.
The example values above match the device from the following output of lsusb:
Bus 001 Device 002: ID 1234:abcd Example device
+Vagrant.configure("2") do |config|
+ config.vm.provider :libvirt do |libvirt|
+ # pass through specific device based on identifying it
+ libvirt.usb :vendor => '0x1234', :product => '0xabcd'
+ # pass through a host device where multiple of the same vendor/product exist
+ libvirt.usb :bus => '1', :device => '1'
+ end
+end
+Additionally, the following options can be used:
startupPolicy - Is passed through to Libvirt and controls if the device has to exist. Libvirt currently allows the following values: “mandatory”, “requisite”, “optional”.You can specify multiple redirect devices via libvirt.redirdev. There are two types, tcp and spicevmc supported, for forwarding USB-devices to the guest. Available options are listed below.
type - The type of the USB redirector device. (tcp or spicevmc)host - The host where the device is attached to. (mandatory for type tcp)port - The port where the device is listening. (mandatory for type tcp)Vagrant.configure("2") do |config|
+ config.vm.provider :libvirt do |libvirt|
+ # add two devices using spicevmc channel
+ (1..2).each do
+ libvirt.redirdev :type => "spicevmc"
+ end
+ # add device, provided by localhost:4000
+ libvirt.redirdev :type => "tcp", :host => "localhost", :port => "4000"
+ end
+end
+Note that in order to enable USB redirection with Spice clients, you may need to also set libvirt.graphics_type = "spice"
You can define filter for redirected devices. These filters can be positive or negative, by setting the mandatory option allow=yes or allow=no. All available options are listed below. Note the option allow is mandatory.
class - The device class of the USB device. A list of device classes is available on Wikipedia.vendor - The vendor of the USB device.product - The product id of the USB device.version - The version of the USB device. Note that this is the version of bcdDeviceallow - allow or disallow redirecting this device. (mandatory)You can extract that information from output of lsusb command. Every line contains the information in format Bus [<bus>] Device [<device>]: ID [<vendor>:[<product>]. The version can be extracted from the detailed output of the device using lsusb -D /dev/usb/[<bus>]/[<device>]. For example:
# get bcdDevice from
+$: lsusb
+Bus 001 Device 009: ID 08e6:3437 Gemalto (was Gemplus) GemPC Twin SmartCard Reader
+
+$: lsusb -D /dev/bus/usb/001/009 | grep bcdDevice
+ bcdDevice 2.00
+In this case, the USB device with class 0x0b, vendor 0x08e6, product 0x3437 and bcdDevice version 2.00 is allowed to be redirected to the guest. All other devices will be refused.
Vagrant.configure("2") do |config|
+ config.vm.provider :libvirt do |libvirt|
+ libvirt.redirdev :type => "spicevmc"
+ libvirt.redirfilter :class => "0x0b", :vendor => "0x08e6", :product => "0x3437", :version => "2.00", :allow => "yes"
+ libvirt.redirfilter :allow => "no"
+ end
+end
+You can define settings to redirect output from the serial console of any VM brought up with libvirt to a file or other devices that are listening. See libvirt documentation.
Currently only redirecting to a file is supported.
type - only value that has an effect is file, in the future support may be added for virtual console, pty, dev, pipe, tcp, udp, unix socket, spiceport & nmdm.source - options pertaining to how the connection attaches to the host, contains sub-settings dependent on type. source options for type file path - file on host to connect to the serial port to record all output. May be created by qemu system user causing some permissions issues.Vagrant.configure("2") do |config|
+ config.vm.define :test do |test|
+ test.vm.provider :libvirt do |domain|
+ domain.serial :type => "file", :source => {:path => "/var/log/vm_consoles/test.log"}
+ end
+ end
+end
+You can pass through /dev/random to your VM by configuring the domain like this:
Vagrant.configure("2") do |config|
+ config.vm.provider :libvirt do |libvirt|
+ # Pass through /dev/random from the host to the VM
+ libvirt.random :model => 'random'
+ end
+end
+At the moment only the random backend is supported.
A virtual hardware watchdog device can be added to the guest via the libvirt.watchdog element. The option model is mandatory and could have on of the following values.
i6300esb - the recommended device, emulating a PCI Intel 6300ESBdiag288 - emulating an S390 DIAG288 deviceThe optional action attribute describes what action to take when the watchdog expires. Valid values are specific to the underlying hypervisor. The default behavior is reset.
reset - default, forcefully reset the guestshutdown - gracefully shutdown the guest (not recommended)poweroff - forcefully power off the guestpause - pause the guestnone - do nothingdump - automatically dump the guestinject-nmi - inject a non-maskable interrupt into the guestVagrant.configure("2") do |config|
+ config.vm.provider :libvirt do |libvirt|
+ # Add Libvirt watchdog device model i6300esb
+ libvirt.watchdog :model => 'i6300esb', :action => 'reset'
+ end
+end
+A virtual smartcard device can be supplied to the guest via the libvirt.smartcard element. The option mode is mandatory and currently only value passthrough is supported. The value spicevmc for option type is default value and can be suppressed. On using type = tcp, the options source_mode, source_host and source_service are mandatory.
Vagrant.configure("2") do |config|
+ config.vm.provider :libvirt do |libvirt|
+ # Add smartcard device with type 'spicevmc'
+ libvirt.smartcard :mode => 'passthrough', :type => 'spicevmc'
+ end
+end
+Vagrant.configure("2") do |config|
+ config.vm.provider :libvirt do |libvirt|
+ # Add smartcard device with type 'tcp'
+ domain.smartcard :mode => 'passthrough', :type => 'tcp', :source_mode => 'bind', :source_host => '127.0.0.1', :source_service => '2001'
+ end
+end
+Hypervisor features can be specified via libvirt.features as a list. The default options that are enabled are acpi, apic and pae. If you define libvirt.features you overwrite the defaults, so keep that in mind.
An example:
Vagrant.configure("2") do |config|
+ config.vm.provider :libvirt do |libvirt|
+ # Specify the default hypervisor features
+ libvirt.features = ['acpi', 'apic', 'pae' ]
+ end
+end
+A different example for ARM boards:
Vagrant.configure("2") do |config|
+ config.vm.provider :libvirt do |libvirt|
+ # Specify the default hypervisor features
+ libvirt.features = ["apic", "gic version='2'" ]
+ end
+end
+You can also specify a special set of features that help improve the behavior of guests running Microsoft Windows.
You can specify HyperV features via libvirt.hyperv_feature. Available options are listed below. Note that both options are required:
name - The name of the feature Hypervisor feature (see Libvirt doc)state - The state for this feature which can be either on or off.Vagrant.configure("2") do |config|
+ config.vm.provider :libvirt do |libvirt|
+ # Relax constraints on timers
+ libvirt.hyperv_feature :name => 'relaxed', :state => 'on'
+ # Enable virtual APIC
+ libvirt.hyperv_feature :name => 'vapic', :state => 'on'
+ # Enable spinlocks (requires retries to be specified)
+ libvirt.hyperv_feature :name => 'spinlocks', :state => 'on', :retries => '8191'
+ end
+end
+The clock can be configured using one of the following methods:
libvirt.clock_offset to ‘utc’ or ‘localtime’ by assigning the respective values.libvirt.clock_timezone.libvirt.clock_absolute. The value format is that of an epoch timestamp.libvirt.clock_adjustment. Specify the offset adjustment in seconds. By default, the clock offset is relative to UTC, but this can be changed by setting libvirt.clock_basis to ‘localtime’.In addition to the above, timers can be specified via libvirt.clock_timer. Available options for timers are: name, track, tickpolicy, frequency, mode, present
Vagrant.configure("2") do |config|
+ config.vm.provider :libvirt do |libvirt|
+ # Set clock offset to localtime
+ libvirt.clock_offset = 'localtime'
+ # Timers ...
+ libvirt.clock_timer :name => 'rtc', :tickpolicy => 'catchup'
+ libvirt.clock_timer :name => 'pit', :tickpolicy => 'delay'
+ libvirt.clock_timer :name => 'hpet', :present => 'no'
+ libvirt.clock_timer :name => 'hypervclock', :present => 'yes'
+ end
+end
+You can specify CPU feature policies via libvirt.cpu_feature. Available options are listed below. Note that both options are required:
name - The name of the feature for the chosen CPU (see Libvirt’s cpu_map.xml)policy - The policy for this feature (one of force, require, optional, disable and forbid - see Libvirt documentation)Vagrant.configure("2") do |config|
+ config.vm.provider :libvirt do |libvirt|
+ # The feature will not be supported by virtual CPU.
+ libvirt.cpu_feature :name => 'hypervisor', :policy => 'disable'
+ # Guest creation will fail unless the feature is supported by host CPU.
+ libvirt.cpu_feature :name => 'vmx', :policy => 'require'
+ # The virtual CPU will claim the feature is supported regardless of it being supported by host CPU.
+ libvirt.cpu_feature :name => 'pdpe1gb', :policy => 'force'
+ end
+end
+You can specify memoryBacking options via libvirt.memorybacking. Available options are shown below. Full documentation is available at the libvirt memoryBacking section.
NOTE: The hugepages <page> element is not yet supported
Vagrant.configure("2") do |config|
+ config.vm.provider :libvirt do |libvirt|
+ libvirt.memorybacking :hugepages
+ libvirt.memorybacking :nosharepages
+ libvirt.memorybacking :locked
+ libvirt.memorybacking :source, :type => 'file'
+ libvirt.memorybacking :access, :mode => 'shared'
+ libvirt.memorybacking :allocation, :mode => 'immediate'
+ end
+end
+Examples of specific use cases, and/or in-depth configuration for special behaviour.
There is support for PXE booting VMs with no disks as well as PXE booting VMs with blank disks. There are some limitations:
vagrant halt will only work cleanly if the VM handles ACPI shutdown signalsIn short, VMs without a box can be created, halted and destroyed but all other functionality cannot be used.
An example for a PXE booted VM with no disks whatsoever:
Vagrant.configure("2") do |config|
+ config.vm.define :pxeclient do |pxeclient|
+ pxeclient.vm.provider :libvirt do |domain|
+ domain.boot 'network'
+ end
+ end
+end
+And an example for a PXE booted VM with no box but a blank disk which will boot from this HD if the NICs fail to PXE boot:
Vagrant.configure("2") do |config|
+ config.vm.define :pxeclient do |pxeclient|
+ pxeclient.vm.provider :libvirt do |domain|
+ domain.storage :file, :size => '100G', :type => 'qcow2'
+ domain.boot 'network'
+ domain.boot 'hd'
+ end
+ end
+end
+Example for vm with 2 networks and only 1 is bootable and has dhcp server in this subnet, for example foreman with dhcp server Name of network “foreman_managed” is key for define boot order
config.vm.define :pxeclient do |pxeclient|
+ pxeclient.vm.network :private_network,ip: '10.0.0.5',
+ libvirt__network_name: "foreman_managed",
+ libvirt__dhcp_enabled: false,
+ libvirt__host_ip: '10.0.0.1'
+
+ pxeclient.vm.provider :libvirt do |domain|
+ domain.memory = 1000
+ boot_network = {'network' => 'foreman_managed'}
+ domain.storage :file, :size => '100G', :type => 'qcow2'
+ domain.boot boot_network
+ domain.boot 'hd'
+ end
+ end
+An example VM that is PXE booted from the br1 device (which must already be configured in the host machine), and if that fails, is booted from the disk:
Vagrant.configure("2") do |config|
+ config.vm.define :pxeclient do |pxeclient|
+ pxeclient.vm.network :public_network,
+ dev: 'br1',
+ auto_config: false
+ pxeclient.vm.provider :libvirt do |domain|
+ boot_network = {'dev' => 'br1'}
+ domain.storage :file, :size => '100G'
+ domain.boot boot_network
+ domain.boot 'hd'
+ end
+ end
+end
+It’s possible to use a direct kernel boot to modify the kernel boot parameters used to boot the VM. This typically involves either downloading the kernel/initrd directly and placing somewhere locally for use, or making use of a tool such as virt-copy-out to extract the relevant files from a disk image file.
Looking at a generic/fedora35 image with the following contents of /boot and /boot/grub2, it should be possible to copy out the kernel, initrd, and the grub.cfg file (provides a starting cmdline).
BOX_DIR="${VAGRANT_HOME:-~/.vagrant.d}/boxes/generic-VAGRANTSLASH-fedora35/4.1.10/libvirt"
+virt-ls -a ${BOX_DIR}/box.img /boot/ /boot/grub2
+.vmlinuz-5.18.19-100.fc35.x86_64.hmac
+System.map-5.18.19-100.fc35.x86_64
+config-5.18.19-100.fc35.x86_64
+efi
+grub2
+initramfs-0-rescue-5cbe0655dcd04b46a88f5a424135fbb8.img
+initramfs-5.18.19-100.fc35.x86_64.img
+loader
+symvers-5.18.19-100.fc35.x86_64.gz
+vmlinuz-0-rescue-5cbe0655dcd04b46a88f5a424135fbb8
+vmlinuz-5.18.19-100.fc35.x86_64
+device.map
+fonts
+grub.cfg
+grubenv
+i386-pc
+locale
+Assuming you run something like the following:
BOX_DIR="${VAGRANT_HOME:-~/.vagrant.d}/boxes/generic-VAGRANTSLASH-fedora35/4.1.10/libvirt"
+virt-copy-out -a ${BOX_DIR}/box.img \
+ /boot/vmlinuz-5.18.19-100.fc35.x86_64 \
+ /boot/initramfs-5.18.19-100.fc35.x86_64.img \
+ /boot/grub2/grub.cfg \
+ .
+The final Vagrantfile should contain something like the following:
Vagrant.configure("2") do |config|
+ config.vm.box = "generic/fedora35"
+
+ config.vm.provider :libvirt do |libvirt|
+ libvirt.kernel = "#{Dir.pwd}/vmlinuz-5.18.19-100.fc35.x86_64"
+ libvirt.initrd = "#{Dir.pwd}/initramfs-5.18.19-100.fc35.x86_64.img"
+ # cmd_line is taken from the grub.cfg to ensure starting from a working value
+ libvirt.cmd_line = 'root=/dev/mapper/fedora-root ro biosdevname=0 no_timer_check ' +
+ 'resume=/dev/mapper/fedora-swap rd.lvm.lv=fedora/root rd.lvm.lv=fedora/swap net.ifnames=0'
+ end
+end
+vagrant-libvirt supports vagrant’s standard ssh settings.
vagrant-libvirt supports Forwarded Ports via ssh port forwarding. Please note that due to a well known limitation only the TCP protocol is supported. For each forwarded_port directive you specify in your Vagrantfile, vagrant-libvirt will maintain an active ssh process for the lifetime of the VM. If your VM should happen to be rebooted, the SSH session will need to be re-established by halting the VM and bringing it back up.
vagrant-libvirt supports an additional forwarded_port option gateway_ports which defaults to false, but can be set to true if you want the forwarded port to be accessible from outside the Vagrant host. In this case you should also set the host_ip option to '*' since it defaults to 'localhost'.
You can also provide a custom adapter to forward from by ‘adapter’ option. Default is eth0.
Internally Accessible Port Forward
config.vm.network :forwarded_port, guest: 80, host: 2000
Externally Accessible Port Forward
config.vm.network :forwarded_port, guest: 80, host: 2000, host_ip: "0.0.0.0"
Vagrant-libvirt now supports forwarding the standard ssh-port on port 2222 from the localhost to allow for consistent provisioning steps/ports to be used when defining across multiple providers.
To enable, set the following:
Vagrant.configure("2") do |config|
+ config.vm.provider :libvirt do |libvirt|
+ # Enable forwarding of forwarded_port with id 'ssh'.
+ libvirt.forward_ssh_port = true
+ end
+end
+Previously by default libvirt skipped the forwarding of the ssh-port because you can access the machine directly. In the future it is expected that this will be enabled by default once autocorrect support is added to handle port collisions for multi machine environments gracefully.
Vagrant automatically syncs the project folder on the host to /vagrant in the guest. You can also configure additional synced folders.
If the type is not specified, vagrant will attempt to select one based on the highest priority that is usable. This can mean that depending on whether you have the packages installed to support nfs and or rsync, you may experience different behaviour on different machines. Recommendation is to be explicit.
SECURITY NOTE: for remote Libvirt, nfs synced folders requires a bridged public network interface and you must connect to Libvirt via ssh.
NFS
vagrant-libvirt supports NFS as with bidirectional synced folders.
Example with NFS:
Vagrant.configure("2") do |config|
+ config.vm.synced_folder "./", "/vagrant", type: "nfs"
+end
+RSync
vagrant-libvirt supports rsync with unidirectional synced folders.
Example with rsync:
Vagrant.configure("2") do |config|
+ config.vm.synced_folder "./", "/vagrant", type: "rsync"
+end
+9P
vagrant-libvirt supports VirtFS (9p or Plan 9) with bidirectional synced folders.
Difference between NFS and 9p is explained here.
For 9p shares, a mount: false option allows to define synced folders without mounting them at boot.
Example for accessmode: "squash" with 9p:
Vagrant.configure("2") do |config|
+ config.vm.synced_folder "./", "/vagrant", type: "9p", disabled: false, accessmode: "squash", owner: "1000"
+end
+Example for accessmode: "mapped" with 9p:
Vagrant.configure("2") do |config|
+ config.vm.synced_folder "./", "/vagrant", type: "9p", disabled: false, accessmode: "mapped", mount: false
+end
+Further documentation on using 9p can be found in kernel docs and in QEMU wiki.
Please do note that 9p depends on support in the guest and not all distros come with the 9p module by default.
Virtio-fs
vagrant-libvirt supports Virtio-fs with bidirectional synced folders.
For virtiofs shares, a mount: false option allows to define synced folders without mounting them at boot.
So far, passthrough is the only supported access mode and it requires running the virtiofsd daemon as root.
QEMU needs to allocate the backing memory for all the guest RAM as shared memory, e.g. Use file-backed memory by enable memory_backing_dir option in /etc/libvirt/qemu.conf:
memory_backing_dir = "/dev/shm"
+Example for Libvirt >= 6.2.0 (e.g. Ubuntu 20.10 with Linux 5.8.0 + QEMU 5.0 + Libvirt 6.6.0, i.e. NUMA nodes required) with virtiofs:
Vagrant.configure("2") do |config|
+ config.vm.provider :libvirt do |libvirt|
+ libvirt.cpus = 2
+ libvirt.numa_nodes = [{ :cpus => "0-1", :memory => 8192, :memAccess => "shared" }]
+ libvirt.memorybacking :access, :mode => "shared"
+ end
+ config.vm.synced_folder "./", "/vagrant", type: "virtiofs"
+end
+Example for Libvirt >= 6.9.0 (e.g. Ubuntu 21.04 with Linux 5.11.0 + QEMU 5.2 + Libvirt 7.0.0, or Ubuntu 20.04 + PPA enabled) with virtiofs:
Vagrant.configure("2") do |config|
+ config.vm.provider :libvirt do |libvirt|
+ libvirt.cpus = 2
+ libvirt.memory = 8192
+ libvirt.memorybacking :access, :mode => "shared"
+ end
+ config.vm.synced_folder "./", "/vagrant", type: "virtiofs"
+end
+Further documentation on using virtiofs can be found in official HowTo and in Libvirt KB.
Please do note that virtiofs depends on:
vagrant-libvirt supports using QEMU user sessions to maintain Vagrant VMs. As the session connection does not have root access to the system features which require root will not work. Access to networks created by the system QEMU connection can be granted by using the QEMU bridge helper. The bridge helper is enabled by default on some distros but may need to be enabled/installed on others.
There must be a virbr network defined in the QEMU system session. The libvirt default network which comes by default, the vagrant vagrant-libvirt network which is generated if you run a Vagrantfile using the System session, or a manually defined network can be used. These networks can be set to autostart with sudo virsh net-autostart <net-name>, which’ll mean no further root access is required even after reboots.
The QEMU bridge helper is configured via /etc/qemu/bridge.conf. This file must include the virbr you wish to use (e.g. virbr0, virbr1, etc). You can find this out via sudo virsh net-dumpxml <net-name>.
allow virbr0
+An example configuration of a machine using the QEMU session connection:
Vagrant.configure("2") do |config|
+ config.vm.provider :libvirt do |libvirt|
+ # Use QEMU session instead of system connection
+ libvirt.qemu_use_session = true
+ # URI of QEMU session connection, default is as below
+ libvirt.uri = 'qemu:///session'
+ # URI of QEMU system connection, use to obtain IP address for management, default is below
+ libvirt.system_uri = 'qemu:///system'
+ # Path to store Libvirt images for the virtual machine, default is as ~/.local/share/libvirt/images
+ libvirt.storage_pool_path = '/home/user/.local/share/libvirt/images'
+ # Management network device, default is below
+ libvirt.management_network_device = 'virbr0'
+ end
+
+ # Public network configuration using existing network device
+ # Note: Private networks do not work with QEMU session enabled as root access is required to create new network devices
+ config.vm.network :public_network, :dev => "virbr1",
+ :mode => "bridge",
+ :type => "bridge"
+end
+vagrant-libvirt supports customizing the display and video settings of the managed guest. This is probably most useful for VNC-type displays with multiple guests. It lets you specify the exact port for each guest to use deterministically.
Here is an example of using custom display options:
Vagrant.configure("2") do |config|
+ config.vm.provider :libvirt do |libvirt|
+ libvirt.graphics_port = 5901
+ libvirt.graphics_ip = '0.0.0.0'
+ libvirt.video_type = 'qxl'
+ end
+end
+Modern versions of Libvirt support connecting to TPM devices on the host system. This allows you to enable Trusted Boot Extensions, among other features, on your guest VMs.
To passthrough a hardware TPM, you will generally only need to modify the tpm_path variable in your guest configuration. However, advanced usage, such as the application of a Software TPM, may require modifying the tpm_model, tpm_type and tpm_version variables.
The TPM options will only be used if you specify a TPM path or version. Declarations of any TPM options without specifying a path or version will result in those options being ignored.
Here is an example of using the TPM options:
Vagrant.configure("2") do |config|
+ config.vm.provider :libvirt do |libvirt|
+ libvirt.tpm_model = 'tpm-tis'
+ libvirt.tpm_type = 'passthrough'
+ libvirt.tpm_path = '/dev/tpm0'
+ end
+end
+It’s also possible for Libvirt to start an emulated TPM device on the host. Requires swtpm and swtpm-tools
Vagrant.configure("2") do |config|
+ config.vm.provider :libvirt do |libvirt|
+ libvirt.tpm_model = "tpm-crb"
+ libvirt.tpm_type = "emulator"
+ libvirt.tpm_version = "2.0"
+ end
+end
+Libvirt allows to specify SMBIOS System Information like a base board or chassis manufacturer or a system serial number.
Vagrant.configure("2") do |config|
+ config.vm.provider :libvirt do |libvirt|
+ libvirt.sysinfo = {
+ 'bios': {
+ 'vendor': 'Test Vendor',
+ 'version': '0.1.2',
+ },
+ 'system': {
+ 'manufacturer': 'Test Manufacturer',
+ 'version': '0.1.0',
+ 'serial': '',
+ },
+ 'base board': {
+ 'manufacturer': 'Test Manufacturer',
+ 'version': '1.2',
+ },
+ 'chassis': {
+ 'manufacturer': 'Test Manufacturer',
+ 'serial': 'AABBCCDDEE',
+ },
+ 'oem strings': [
+ 'app1: string1',
+ 'app1: string2',
+ 'app2: string1',
+ 'app2: string2',
+ ],
+ }
+ end
+end
+The configuration of the memory balloon device can be overridden. By default, libvirt will automatically attach a memory balloon; this behavior is preserved by not configuring any memballoon-related options. The memory balloon can be explicitly disabled by setting memballoon_enabled to false. Setting memballoon_enabled to true will allow additional configuration of memballoon-related options.
Here is an example of using the memballoon options:
Vagrant.configure("2") do |config|
+ config.vm.provider :libvirt do |libvirt|
+ libvirt.memballoon_enabled = true
+ libvirt.memballoon_model = 'virtio'
+ libvirt.memballoon_pci_bus = '0x00'
+ libvirt.memballoon_pci_slot = '0x0f'
+ end
+end
+Secure Encryption Virtualization is supported by libvirt and by the vagrant-libvirt provider but comes with several requirements.
This mode has only been tested with q35 types of machines, so you’ll need an UEFI boot
Vagrant.configure("2") do |config|
+ config.vm.provider :libvirt do |libvirt|
+ libvirt.loader = "/usr/share/OVMF/OVMF_CODE.fd"
+ libvirt.nvram = "/path/to/ovmf/OVMF_VARS.fd"
+ libvirt.machine_type = 'pc-q35-focal'
+ end
+end
+Read the libvirt documentaiton to understand what OVMF is and how to use it.
Next, you’ll want to call the following methods:
Vagrant.configure("2") do |config|
+ config.vm.provider :libvirt do |libvirt|
+ libvirt.launchsecurity :type => 'sev', :cbitpos => 47, :reducedPhysBits => 1, :policy => "0x0003"
+ libvirt.memtune :type => "hard_limit", :value => 2500000 # Note here the value in kB (not in Mb)
+ end
+end
+Note that the value provided in the memtune hard_limit is in Kb by default. It should be higher than the one given in libvirt.memory (which is in Mb, by the way) by some amount (again, check out the https://libvirt.org/kbase/launch_security_sev.html) to understand why.
It is also necessary to explicitly define the memballoon for it to accept the iommu flag.
Vagrant.configure("2") do |config|
+ config.vm.provider :libvirt do |libvirt|
+ libvirt.memballoon_enabled = true
+ libvirt.memballoon_model = 'virtio'
+ libvirt.memballoon_pci_bus = '0x07'
+ libvirt.memballoon_pci_slot = '0x00'
+ end
+end
+And finally, because the iommu flag has to be passed to the networks, you also need to set it explicitly:
Vagrant.configure("2") do |config|
+ config.vm.provider :libvirt do |libvirt|
+ # Management network only (the NAT'ed network provided by Vagrant)
+ libvirt.management_network_driver_iommu = true
+ end
+ # Example in defining a bridge
+ config.vm.network :public_network, :dev => "br0", :bridge => "br0", :mode => "bridge", :type => "bridge", :driver_iommu => true # <== Note here the additional flag
+end
+Don’t forget that you’ll need an UEFI base box.
For certain functionality to be available within a guest, a private communication channel must be established with the host. Two notable examples of this are the QEMU guest agent, and the Spice/QXL graphics type.
Below is a simple example which exposes a virtio serial channel to the guest. Note: in a multi-VM environment, the channel would be created for all VMs.
vagrant.configure(2) do |config|
+ config.vm.provider :libvirt do |libvirt|
+ libvirt.channel :type => 'unix', :target_name => 'org.qemu.guest_agent.0', :target_type => 'virtio'
+ end
+end
+Below is the syntax for creating a spicevmc channel for use by a qxl graphics card.
vagrant.configure(2) do |config|
+ config.vm.provider :libvirt do |libvirt|
+ libvirt.channel :type => 'spicevmc', :target_name => 'com.redhat.spice.0', :target_type => 'virtio'
+ end
+end
+These settings can be specified on a per-VM basis, however the per-guest settings will OVERRIDE any global ‘config’ setting. In the following example, we create 3 VMs with the following configuration:
/tmp/foo. Note: this device must be unique for each VM.For example:
Vagrant.configure(2) do |config|
+ config.vm.box = "fedora/32-cloud-base"
+ config.vm.provider :libvirt do |libvirt|
+ libvirt.channel :type => 'unix', :target_name => 'org.qemu.guest_agent.0', :target_type => 'virtio'
+ end
+
+ config.vm.define "controller" do |controller|
+ controller.vm.provider :libvirt do |domain|
+ domain.memory = 1024
+ end
+ end
+ config.vm.define "node1" do |node1|
+ node1.vm.provider :libvirt do |domain|
+ domain.channel :type => 'unix', :target_name => 'org.qemu.guest_agent.0', :target_type => 'virtio'
+ domain.channel :type => 'spicevmc', :target_name => 'com.redhat.spice.0', :target_type => 'virtio'
+ end
+ end
+ config.vm.define "node2" do |node2|
+ node2.vm.provider :libvirt do |domain|
+ domain.channel :type => 'unix', :target_name => 'org.qemu.guest_agent.0', :target_type => 'virtio'
+ domain.channel :type => 'unix', :target_type => 'guestfwd', :target_address => '192.0.2.42', :target_port => '4242',
+ :source_path => '/tmp/foo'
+ end
+ end
+end
+You can also specify multiple qemuargs arguments or qemuenv environment variables for qemu-system
value - ValueVagrant.configure("2") do |config|
+ config.vm.provider :libvirt do |libvirt|
+ libvirt.qemuargs :value => "-device"
+ libvirt.qemuargs :value => "intel-iommu"
+ libvirt.qemuenv QEMU_AUDIO_DRV: 'pa'
+ libvirt.qemuenv QEMU_AUDIO_TIMER_PERIOD: '150'
+ libvirt.qemuenv QEMU_PA_SAMPLES: '1024', QEMU_PA_SERVER: '/run/user/1000/pulse/native'
+ end
+end
+Vagrant-libvirt is a Vagrant plugin that adds a Libvirt provider to Vagrant, allowing Vagrant to control and provision machines via Libvirt toolkit.
Actual version is still a development one. Feedback is welcome and can help a lot :-)
Vagrant-libvirt requires the following:
Before you start using vagrant-libvirt, please make sure your Libvirt and QEMU installation is working correctly and you are able to create QEMU or KVM type virtual machines with virsh or virt-manager.
See Requirements for guides and details.
sudo apt-get purge vagrant-libvirt
+sudo apt-mark hold vagrant-libvirt
+sudo apt-get update && \
+ sudo apt-get install -y qemu libvirt-daemon-system ebtables libguestfs-tools \
+ vagrant ruby-fog-libvirt
+sudo dnf remove vagrant-libvirt
+sudo sed -i \
+ '/^\(exclude=.*\)/ {/vagrant-libvirt/! s//\1 vagrant-libvirt/;:a;n;ba;q}; $aexclude=vagrant-libvirt' \
+ /etc/dnf/dnf.conf
+vagrant_libvirt_deps=($(sudo dnf repoquery --disableexcludes main --depends vagrant-libvirt 2>/dev/null | cut -d' ' -f1))
+dependencies=$(sudo dnf repoquery --qf "%{name}" ${vagrant_libvirt_deps[@]/#/--whatprovides })
+sudo dnf install --assumeyes @virtualization ${dependencies}
+vagrant plugin install vagrant-libvirt
+If you encounter any errors during this process, check that you have installed all the prerequisites in Requirements. If you still have issues, see Troubleshooting.
Installation varies based on your operating system or use of upstream vagrant. See our guides for OS-specific instructions.
After installing the plugin (instructions above), the quickest way to get started is to add Libvirt box and specify all the details manually within a config.vm.provider block. So first, add Libvirt box using any name you want. You can find more Libvirt-ready boxes at Vagrant Cloud. For example:
vagrant init fedora/36-cloud-base
+Or make a Vagrantfile that looks like the following, filling in your information where necessary. For example:
Vagrant.configure("2") do |config|
+ config.vm.define :test_vm do |test_vm|
+ test_vm.vm.box = "fedora/36-cloud-base"
+ end
+end
+In prepared project directory, run following command:
$ vagrant up --provider=libvirt
+Vagrant needs to know that we want to use Libvirt and not default VirtualBox. That’s why there is --provider=libvirt option specified. Other way to tell Vagrant to use Libvirt provider is to setup environment variable
export VAGRANT_DEFAULT_PROVIDER=libvirt
+While we only test with upstream vagrant installed as a gem, we recommend that you install vagrant as provided by your distribution as installing vagrant-libvirt involves linking between libvirt (ruby-libvirt) and the ruby installation used by vagrant. Since upstream vagrant provides an embedded ruby, this typically causes issues with missing symbols between libraries included and what is expected by libvirt for the ruby bindings linking to work.
First, you should have both QEMU and Libvirt installed if you plan to run VMs on your local system. For instructions, refer to your Linux distribution’s documentation. Suggested packages are provided in our guides for as a quick reference
Before you start using vagrant-libvirt, please make sure your Libvirt and QEMU installation is working correctly and you are able to create QEMU or KVM type virtual machines with virsh or virt-manager.
Next, you must have Vagrant installed from your distribution packages. Vagrant-libvirt supports Vagrant 2.0, 2.1 & 2.2. It should also work with earlier releases from 1.5 onwards but they are not actively tested.
Check the unit tests for the current list of tested versions.
If there is no distribution package or you wish to use the upstream vagrant, you may wish to use the our QA installation script to install both vagrant and vagrant-libvirt Alternatively you may follow vagrant installation instructions along with the manual instructions for what packages to install where indicated for upstream vagrant below. In some cases the vagrant version for the distribution may be running with a sufficiently old ruby that it is difficult to install the required dependencies and you will need to use the upstream.
Due to the number of issues encountered around compatibility between the ruby runtime environment that is part of the upstream vagrant installation and the library dependencies of libvirt that this project requires to communicate with libvirt, there is a docker image built and published.
This should allow users to execute vagrant with vagrant-libvirt without needing to deal with the compatibility issues, though you may need to extend the image for your own needs should you make use of additional plugins.
The default image contains the full toolchain required to build and install vagrant-libvirt and it’s dependencies. There is also a smaller image published with the -slim suffix if you just need vagrant-libvirt and don’t need to install any additional plugins for your environment.
If you are connecting to a remote system libvirt, you may omit the -v /var/run/libvirt/:/var/run/libvirt/ mount bind. Some distributions patch the local vagrant environment to ensure vagrant-libvirt uses qemu:///session, which means you may need to set the environment variable LIBVIRT_DEFAULT_URI to the same value if looking to use this in place of your distribution provided installation.
To get the image with the most recent release:
docker pull vagrantlibvirt/vagrant-libvirt:latest
+edge tag instead.
+docker pull vagrantlibvirt/vagrant-libvirt:edge
+Running the image:
docker run -it --rm \
+ -e LIBVIRT_DEFAULT_URI \
+ -v /var/run/libvirt/:/var/run/libvirt/ \
+ -v ~/.vagrant.d:/.vagrant.d \
+ -v $(realpath "${PWD}"):${PWD} \
+ -w "${PWD}" \
+ --network host \
+ vagrantlibvirt/vagrant-libvirt:latest \
+ vagrant status
+It’s possible to define a function in ~/.bashrc, for example:
vagrant(){
+ docker run -it --rm \
+ -e LIBVIRT_DEFAULT_URI \
+ -v /var/run/libvirt/:/var/run/libvirt/ \
+ -v ~/.vagrant.d:/.vagrant.d \
+ -v $(realpath "${PWD}"):${PWD} \
+ -w "${PWD}" \
+ --network host \
+ vagrantlibvirt/vagrant-libvirt:latest \
+ vagrant $@
+}
+
+To run with Podman you need to include
--entrypoint /bin/bash \
+ --security-opt label=disable \
+for example:
vagrant(){
+ podman run -it --rm \
+ -e LIBVIRT_DEFAULT_URI \
+ -v /var/run/libvirt/:/var/run/libvirt/ \
+ -v ~/.vagrant.d:/.vagrant.d \
+ -v $(realpath "${PWD}"):${PWD} \
+ -w "${PWD}" \
+ --network host \
+ --entrypoint /bin/bash \
+ --security-opt label=disable \
+ docker.io/vagrantlibvirt/vagrant-libvirt:latest \
+ vagrant $@
+}
+Running Podman in rootless mode maps the root user inside the container to your host user so we need to bypass entrypoint.sh.
By default the image published and used contains the entire tool chain required to install the vagrant-libvirt plugin and it’s dependencies. This allows any plugin that requires native extensions to be installed and should be possible to use a simple FROM statement and ask vagrant to install additional plugins.
FROM vagrantlibvirt/vagrant-libvirt:latest
+
+RUN vagrant plugin install <plugin>
+Recently the image has now moved to bundling the plugin with the vagrant system plugins it should no longer attempt to reinstall each time. Eventually this will become the default so additional plugin installs will need to install any dependencies needed by them.
You may need to modify your sources.list to uncomment the deb-src entries where using build-dep commands below.
sudo apt-get purge vagrant-libvirt
+sudo apt-mark hold vagrant-libvirt
+sudo apt-get install -y qemu libvirt-daemon-system libvirt-dev ebtables libguestfs-tools
+sudo apt-get install -y vagrant ruby-fog-libvirt
+vagrant plugin install vagrant-libvirt
+curl -O https://raw.githubusercontent.com/vagrant-libvirt/vagrant-libvirt-qa/main/scripts/install.bash
+chmod a+x ./install.bash
+./install.bash
+curl -fsSL https://apt.releases.hashicorp.com/gpg | sudo tee /usr/share/keyrings/hashicorp-archive-keyring.asc
+echo "deb [ signed-by=/usr/share/keyrings/hashicorp-archive-keyring.asc ] https://apt.releases.hashicorp.com $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/hashicorp.list
+sudo apt-get update && sudo apt-get install vagrant
+And subsequently install remaining dependencies and plugin:
sudo apt-get build-dep vagrant ruby-libvirt
+sudo apt-get install -y qemu libvirt-daemon-system ebtables libguestfs-tools \
+ libxslt-dev libxml2-dev zlib1g-dev ruby-dev
+vagrant plugin install vagrant-libvirt
+This has been kept for historical reasons, however only Ubuntu 18.04 is supported due to LTS, please consider all other versions unsupported.
curl -O https://raw.githubusercontent.com/vagrant-libvirt/vagrant-libvirt-qa/main/scripts/install.bash
+chmod a+x ./install.bash
+./install.bash
+curl -fsSL https://apt.releases.hashicorp.com/gpg | sudo tee /usr/share/keyrings/hashicorp-archive-keyring.asc
+echo "deb [ signed-by=/usr/share/keyrings/hashicorp-archive-keyring.asc ] https://apt.releases.hashicorp.com $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/hashicorp.list
+sudo apt-get update && sudo apt-get install vagrant
+And subsequently install remaining dependencies and plugin:
sudo apt-get build-dep vagrant ruby-libvirt
+sudo apt-get install -y qemu libvirt-bin ebtables libguestfs-tools \
+ libxslt-dev libxml2-dev zlib1g-dev ruby-dev
+vagrant plugin install vagrant-libvirt
+sudo apt-get purge vagrant-libvirt
+sudo apt-mark hold vagrant-libvirt
+sudo apt-get install -y qemu libvirt-bin ebtables libguestfs-tools
+sudo apt-get install -y vagrant ruby-fog-libvirt
+vagrant plugin install vagrant-libvirt
+Unless you can can install a newer ruby on Debian 8, it is likely that the distro vagrant approach will not be straight forward as vagrant-libvirt requires a fog-core and fog-libvirt releases that depend on ruby 2.5 or newer.
Due to the involved nature of getting the linking to work correctly when using the upstream vagrant, it is strongly recommended to either use the distro packaged vagrant, or the install script from the vagrant-libvirt-qa approach.
sudo dnf remove vagrant-libvirt
+sudo sed -i \
+ '/^\(exclude=.*\)/ {/vagrant-libvirt/! s//\1 vagrant-libvirt/;:a;n;ba;q}; $aexclude=vagrant-libvirt' \
+ /etc/dnf/dnf.conf
+vagrant_libvirt_deps=($(sudo dnf repoquery --disableexcludes main --depends vagrant-libvirt 2>/dev/null | cut -d' ' -f1))
+dependencies=$(sudo dnf repoquery --qf "%{name}" ${vagrant_libvirt_deps[@]/#/--whatprovides })
+sudo dnf install --assumeyes @virtualization ${dependencies}
+The above sed command will add vagrant-libvirt to the list of packages to be excluded from being installed. This prevents it from being pulled in as a weak dependency when installing vagrant along with the @virtualization group. Unfortunately the dnf versionlock plugin can only lock to a specific version rather than exclude all versions.
curl -O https://raw.githubusercontent.com/vagrant-libvirt/vagrant-libvirt-qa/main/scripts/install.bash
+chmod a+x ./install.bash
+./install.bash
+sudo dnf install -y dnf-plugins-core
+sudo dnf config-manager --add-repo https://rpm.releases.hashicorp.com/fedora/hashicorp.repo
+sudo dnf -y install vagrant
+Subsequently install remaining dependencies:
sudo dnf install --assumeyes libvirt libguestfs-tools \
+ gcc libvirt-devel libxml2-devel make ruby-devel
+# additional deps to rebuild libraries in upstream vagrant package.
+sudo dnf install --assumeyes byacc cmake gcc-c++ wget zlib-devel
+Before installing the plugin it is necessary to compile some libraries to replace those shipped with the upstream vagrant to prevent the following errors from appearing when vagrant attempts to use vagrant-libvirt on recent Fedora releases.
libssh issue:
/opt/vagrant/embedded/lib/ruby/2.4.0/rubygems/core_ext/kernel_require.rb:55:in `require': /opt/vagrant/embedded/lib64/libcrypto.so.1.1: version `OPENSSL_1_1_1b' not found (required by /lib64/libssh.so.4) - /home/xxx/.vagrant.d/gems/2.4.6/gems/ruby-libvirt-0.7.1/lib/_libvirt.so (LoadError)
+Solution identified thanks to James Reynolds (see https://github.com/hashicorp/vagrant/issues/11020#issuecomment-540043472).
libk5crypto issue:
/opt/vagrant/embedded/lib/ruby/2.4.0/rubygems/core_ext/kernel_require.rb:55:in `require': /usr/lib64/libk5crypto.so.3: undefined symbol: EVP_KDF_ctrl, version OPENSSL_1_1_1b - /home/rbelgrave/.vagrant.d/gems/2.4.9/gems/ruby-libvirt-0.7.1/lib/_libvirt.so (LoadError)
+Solution identified thanks to Marco Bevc (see https://github.com/hashicorp/vagrant/issues/11020#issuecomment-625801983).
Compile libraries to replaced those bundled with Vagrant to allow linking ruby-libvirt against vagrant’s embedded ruby and the system libvirt (updated originals to be generic):
mkdir patches
+pushd patches
+
+mkdir libssh
+pushd libssh
+nvr=$(rpm -q --queryformat "libssh-%{version}-%{release}" libssh)
+nv=$(rpm -q --queryformat "libssh-%{version}" libssh)
+dnf download --source libssh
+rpm2cpio ${nvr}.src.rpm | cpio -imdV
+rm -rf ${nv}
+tar xf ${nv}.tar.*z
+
+mkdir libssh-build
+pushd libssh-build
+cmake ../${nv} -DOPENSSL_ROOT_DIR=/opt/vagrant/embedded/
+make
+sudo cp lib/libssh* /opt/vagrant/embedded/lib64
+popd
+popd
+
+mkdir krb5
+pushd krb5
+nvr=$(rpm -q --queryformat "krb5-%{version}-%{release}" krb5-libs)
+nv=$(rpm -q --queryformat "krb5-%{version}" krb5-libs)
+dnf download --source krb5-libs
+rpm2cpio ${nvr}.src.rpm | cpio -imdV
+tar xf ${nv}.tar.*z
+
+pushd ${nv}/src
+./configure
+make
+sudo cp -P lib/crypto/libk5crypto.* /opt/vagrant/embedded/lib64/
+popd
+popd
+
+popd
+Finally install the plugin:
vagrant plugin install vagrant-libvirt
+This has been kept for historical reasons given closeness to CentOS 6 & 7, however as Fedora no longer supports these, they can be considered unsupported as well.
curl -O https://raw.githubusercontent.com/vagrant-libvirt/vagrant-libvirt-qa/main/scripts/install.bash
+chmod a+x ./install.bash
+./install.bash
+sudo dnf install -y dnf-plugins-core
+sudo dnf config-manager --add-repo https://rpm.releases.hashicorp.com/fedora/hashicorp.repo
+sudo dnf -y install vagrant
+And subsequently install remaining dependencies and plugin:
sudo dnf install --assumeyes libvirt libguestfs-tools \
+ gcc libvirt-devel libxml2-devel make ruby-devel
+vagrant plugin install vagrant-libvirt
+curl -O https://raw.githubusercontent.com/vagrant-libvirt/vagrant-libvirt-qa/main/scripts/install.bash
+chmod a+x ./install.bash
+./install.bash
+sudo dnf install -y dnf-plugins-core
+sudo dnf config-manager --add-repo https://rpm.releases.hashicorp.com/RHEL/hashicorp.repo
+sudo dnf -y install vagrant
+Subsequent install remaining dependencies and plugin
sudo dnf config-manager --set-enabled crb
+sudo dnf install -y '@Virtualization Hypervisor' '@Virtualization Tools' \
+ '@Development Tools' 'libvirt-devel'
+vagrant plugin install vagrant-libvirt
+curl -O https://raw.githubusercontent.com/vagrant-libvirt/vagrant-libvirt-qa/main/scripts/install.bash
+chmod a+x ./install.bash
+./install.bash
+sudo dnf install -y dnf-plugins-core
+sudo dnf config-manager --add-repo https://rpm.releases.hashicorp.com/RHEL/hashicorp.repo
+sudo dnf -y install vagrant
+Subsequently install remaining dependencies:
sudo dnf install --assumeyes libvirt libguestfs-tools \
+ gcc libvirt-devel libxml2-devel make pkgconf-pkg-config ruby-devel
+# additional deps to rebuild libraries in upstream vagrant package.
+sudo dnf install --assumeyes byacc cmake gcc-c++ rpm-build wget zlib-devel
+Before installing the plugin it is necessary to compile some libraries to replace those shipped with the upstream vagrant to prevent the following errors from appearing when vagrant attempts to use vagrant-libvirt on recent CentOS releases.
libssh issue:
/opt/vagrant/embedded/lib/ruby/2.4.0/rubygems/core_ext/kernel_require.rb:55:in `require': /opt/vagrant/embedded/lib64/libcrypto.so.1.1: version `OPENSSL_1_1_1b' not found (required by /lib64/libssh.so.4) - /home/xxx/.vagrant.d/gems/2.4.6/gems/ruby-libvirt-0.7.1/lib/_libvirt.so (LoadError)
+Solution identified thanks to James Reynolds (see https://github.com/hashicorp/vagrant/issues/11020#issuecomment-540043472).
libk5crypto issue:
/opt/vagrant/embedded/lib/ruby/2.4.0/rubygems/core_ext/kernel_require.rb:55:in `require': /usr/lib64/libk5crypto.so.3: undefined symbol: EVP_KDF_ctrl, version OPENSSL_1_1_1b - /home/rbelgrave/.vagrant.d/gems/2.4.9/gems/ruby-libvirt-0.7.1/lib/_libvirt.so (LoadError)
+Solution identified thanks to Marco Bevc (see https://github.com/hashicorp/vagrant/issues/11020#issuecomment-625801983).
Compile libraries to replaced those bundled with Vagrant to allow linking ruby-libvirt against vagrant’s embedded ruby and the system libvirt (updated originals to be generic):
mkdir patches
+pushd patches
+
+[[ ! -d centos-git-common ]] && git clone https://git.centos.org/centos-git-common
+export PATH=$(readlink -f ./centos-git-common):$PATH
+chmod a+x ./centos-git-common/*.sh
+
+git clone https://git.centos.org/rpms/libssh
+pushd libssh
+nvr=$(rpm -q --queryformat "libssh-%{version}-%{release}" libssh)
+nv=$(rpm -q --queryformat "libssh-%{version}" libssh)
+git checkout $(git tag -l | grep "${nvr}\$" | tail -n1)
+into_srpm.sh -d c8s
+pushd BUILD
+tar xf ../SOURCES/${nv}.tar.*z
+
+mkdir libssh-build
+pushd libssh-build
+cmake ../${nv} -DOPENSSL_ROOT_DIR=/opt/vagrant/embedded/
+make
+sudo cp lib/libssh* /opt/vagrant/embedded/lib64
+popd
+popd
+
+popd
+
+git clone https://git.centos.org/rpms/krb5
+pushd krb5
+nvr=$(rpm -q --queryformat "krb5-%{version}-%{release}" krb5-libs)
+nv=$(rpm -q --queryformat "krb5-%{version}" krb5-libs)
+git checkout $(git tag -l | grep "${nvr}\$" | tail -n1)
+into_srpm.sh -d c8s
+pushd BUILD
+tar xf ../SOURCES/${nv}.tar.*z
+
+pushd ${nv}/src
+./configure
+make
+sudo cp -P lib/crypto/libk5crypto.* /opt/vagrant/embedded/lib64/
+popd
+popd
+
+popd
+
+popd
+Finally install the plugin:
vagrant plugin install vagrant-libvirt
+curl -O https://raw.githubusercontent.com/vagrant-libvirt/vagrant-libvirt-qa/main/scripts/install.bash
+chmod a+x ./install.bash
+./install.bash
+sudo yum install -y yum-utils
+sudo yum-config-manager --add-repo https://rpm.releases.hashicorp.com/RHEL/hashicorp.repo
+sudo yum -y install vagrant
+And subsequently install remaining dependencies and plugin:
sudo yum install --assumeyes qemu qemu-kvm libvirt libguestfs-tools \
+ gcc libvirt-devel make ruby-devel
+vagrant plugin install vagrant-libvirt
+As there is no official upstream repository for OpenSUSE, it is recommended that you stick with the distribution installation. OpenSUSE Leap appears to make the most recent vagrant available as an experimental package based on https://software.opensuse.org/package/vagrant.
sudo zypper refresh
+sudo zypper addlock vagrant-libvirt
+fog_libvirt_pkg="$(
+ sudo zypper --terse -n --quiet search --provides "rubygem(fog-libvirt)" | \
+ tail -n1 | cut -d' ' -f4)"
+sudo zypper install --no-confirm libvirt qemu-kvm libguestfs polkit vagrant ${fog_libvirt_pkg}
+vagrant plugin install vagrant-libvirt
+curl -O https://raw.githubusercontent.com/vagrant-libvirt/vagrant-libvirt-qa/main/scripts/install.bash
+chmod a+x ./install.bash
+./install.bash
+Alternatively install vagrant following https://www.vagrantup.com/downloads:
As there is no upstream repository this will not be kept up to date automatically.
version="$(
+ wget -qO - https://checkpoint-api.hashicorp.com/v1/check/vagrant 2>/dev/null | \
+ tr ',' '\n' | grep current_version | cut -d: -f2 | tr -d '"'
+)"
+wget --no-verbose -O vagrant.rpm \
+ https://releases.hashicorp.com/vagrant/${version}/vagrant_${version}_x86_64.rpm
+sudo zypper install --allow-unsigned-rpm --no-confirm vagrant.rpm
+Subsequently install remaining dependencies:
sudo zypper install --no-confirm libvirt qemu-kvm libguestfs \
+ gcc make libvirt-devel polkit ruby-devel
+# additional deps to rebuild libraries in upstream vagrant package.
+sudo zypper install --no-confirm byacc cmake gcc-++ libssh4 perl-XML-XPath wget zlib-devel
+Before installing the plugin it is necessary to compile some libraries to replace those shipped with the upstream vagrant to prevent the following errors from appearing when vagrant attempts to use vagrant-libvirt on recent OpenSUSE Leap releases.
libssh issue:
/opt/vagrant/embedded/lib/ruby/2.4.0/rubygems/core_ext/kernel_require.rb:55:in `require': /opt/vagrant/embedded/lib64/libcrypto.so.1.1: version `OPENSSL_1_1_1b' not found (required by /lib64/libssh.so.4) - /home/xxx/.vagrant.d/gems/2.4.6/gems/ruby-libvirt-0.7.1/lib/_libvirt.so (LoadError)
+Solution identified thanks to James Reynolds (see https://github.com/hashicorp/vagrant/issues/11020#issuecomment-540043472).
libk5crypto issue:
/opt/vagrant/embedded/lib/ruby/2.4.0/rubygems/core_ext/kernel_require.rb:55:in `require': /usr/lib64/libk5crypto.so.3: undefined symbol: EVP_KDF_ctrl, version OPENSSL_1_1_1b - /home/rbelgrave/.vagrant.d/gems/2.4.9/gems/ruby-libvirt-0.7.1/lib/_libvirt.so (LoadError)
+Solution identified thanks to Marco Bevc (see https://github.com/hashicorp/vagrant/issues/11020#issuecomment-625801983).
Compile libraries to replaced those bundled with Vagrant to allow linking ruby-libvirt against vagrant’s embedded ruby and the system libvirt (updated originals to be generic):
mkdir patches
+pushd patches
+
+mkdir libssh
+pushd libssh
+nvr=$(rpm -q --queryformat "libssh-%{version}-%{release}" libssh4)
+nv=$(rpm -q --queryformat "libssh-%{version}" libssh4)
+
+repository=$(zypper --quiet --no-refresh --xmlout search --type srcpackage --match-exact --details libssh | xpath -q -e 'string(//solvable/@repository)')
+url=$(zypper --quiet --xmlout repos | xpath -q -e "//repo[@name='${repository}']/url/text()")
+
+wget ${url}/src/${nvr}.src.rpm
+rpm2cpio ${nvr}.src.rpm | cpio -imdV
+rm -rf ${nv}
+tar xf ${nv}.tar.*z
+
+mkdir libssh-build
+pushd libssh-build
+cmake ../${nv} -DOPENSSL_ROOT_DIR=/opt/vagrant/embedded/
+make
+sudo cp lib/libssh* /opt/vagrant/embedded/lib64
+popd
+popd
+
+mkdir krb5
+pushd krb5
+nvr=$(rpm -q --queryformat "krb5-%{version}-%{release}\n" krb5 | uniq)
+nv=$(rpm -q --queryformat "krb5-%{version}\n" krb5 | uniq)
+repository=$(zypper --quiet --no-refresh --xmlout search --type srcpackage --match-exact --details krb5 | xpath -q -e 'string(//solvable/@repository)')
+url=$(zypper --quiet --xmlout repos | xpath -q -e "//repo[@name='${repository}']/url/text()")
+
+[[ ! -e ${nvr}.src.rpm ]] && wget ${url}/src/${nvr}.src.rpm
+rpm2cpio ${nvr}.src.rpm | cpio -imdV
+rm -rf ${nv}
+tar xf ${nv}.tar.*z
+
+pushd ${nv}/src
+./configure
+make
+sudo cp -P lib/crypto/libk5crypto.* /opt/vagrant/embedded/lib64/
+popd
+popd
+
+popd
+Finally install the plugin:
vagrant plugin install vagrant-libvirt
+Please read the related ArchWiki page.
As Arch is a rolling release, the version of vagrant available from the distribution should always be the most recent. Unfortunately it does not appear to be possible to install ruby-libvirt from AUR anymore, which would remove the need for the additional build tools.
sudo pacman --sync --sysupgrade --refresh
+sudo pacman --query --search 'iptables' | grep "local" | grep "iptables " && \
+ sudo pacman --remove --nodeps --nodeps --noconfirm iptables
+sudo pacman --sync --needed --noprogressbar --noconfirm \
+ iptables-nft libvirt qemu openbsd-netcat bridge-utils dnsmasq vagrant \
+ pkg-config gcc make ruby
+vagrant plugin install vagrant-libvirt
+Ensuring pkg-config or pkgconf is installed should be sufficient in most cases.
In some cases, you will need to specify CONFIGURE_ARGS variable before running running vagrant plugin install, e.g.:
export CONFIGURE_ARGS="with-libvirt-include=/usr/include/libvirt with-libvirt-lib=/usr/lib64"
+vagrant plugin install vagrant-libvirt
+If you have issues building ruby-libvirt, try the following (replace lib with lib64 as needed):
CONFIGURE_ARGS='with-ldflags=-L/opt/vagrant/embedded/lib with-libvirt-include=/usr/include/libvirt with-libvirt-lib=/usr/lib' \
+ GEM_HOME=~/.vagrant.d/gems \
+ GEM_PATH=$GEM_HOME:/opt/vagrant/embedded/gems \
+ PATH=/opt/vagrant/embedded/bin:$PATH \
+ vagrant plugin install vagrant-libvirt
+If have problem with installation - check your linker. It should be ld.gold:
sudo alternatives --set ld /usr/bin/ld.gold
+# OR
+sudo ln -fs /usr/bin/ld.gold /usr/bin/ld
+If you encounter the following load error when using the vagrant-libvirt plugin (note the required by libssh):
/opt/vagrant/embedded/lib/ruby/2.4.0/rubygems/core_ext/kernel_require.rb:55:in `require': /opt/vagrant/embedded/lib64/libcrypto.so.1.1: version `OPENSSL_1_1_1b' not found (required by /lib64/libssh.so.4) - /home/xxx/.vagrant.d/gems/2.4.6/gems/ruby-libvirt-0.7.1/lib/_libvirt.so (LoadError)
then the following steps have been found to resolve the problem. Thanks to James Reynolds (see https://github.com/hashicorp/vagrant/issues/11020#issuecomment-540043472). The specific version of libssh will change over time so references to the rpm in the commands below will need to be adjusted accordingly.
See distro specific instructions for variations on this that contain version independent steps.
# Fedora
+dnf download --source libssh
+
+# centos 8 stream, doesn't provide source RPMs, so you need to download like so
+git clone https://git.centos.org/centos-git-common
+# centos-git-common needs its tools in PATH
+export PATH=$(readlink -f ./centos-git-common):$PATH
+git clone https://git.centos.org/rpms/libssh
+cd libssh
+git checkout imports/c8s/libssh-0.9.4-1.el8
+into_srpm.sh -d c8s
+cd SRPMS
+
+# common commands (make sure to adjust version accordingly)
+rpm2cpio libssh-0.9.4-1c8s.src.rpm | cpio -imdV
+tar xf libssh-0.9.4.tar.xz
+mkdir build
+cmake ../libssh-0.9.4 -DOPENSSL_ROOT_DIR=/opt/vagrant/embedded/
+make
+sudo cp lib/libssh* /opt/vagrant/embedded/lib64
+If you encounter the following load error when using the vagrant-libvirt plugin (note the required by libk5crypto):
/opt/vagrant/embedded/lib/ruby/2.4.0/rubygems/core_ext/kernel_require.rb:55:in `require': /usr/lib64/libk5crypto.so.3: undefined symbol: EVP_KDF_ctrl, version OPENSSL_1_1_1b - /home/rbelgrave/.vagrant.d/gems/2.4.9/gems/ruby-libvirt-0.7.1/lib/_libvirt.so (LoadError)
then the following steps have been found to resolve the problem. After the steps below are complete, then reinstall the vagrant-libvirt plugin without setting the CONFIGURE_ARGS. Thanks to Marco Bevc (see https://github.com/hashicorp/vagrant/issues/11020#issuecomment-625801983):
# Fedora
+dnf download --source krb5-libs
+
+# centos 8 stream, doesn't provide source RPMs, so you need to download like so
+git clone https://git.centos.org/centos-git-common
+# make get_sources.sh executable as it is needed in krb5
+chmod +x centos-git-common/get_sources.sh
+# centos-git-common needs its tools in PATH
+export PATH=$(readlink -f ./centos-git-common):$PATH
+git clone https://git.centos.org/rpms/krb5
+cd krb5
+git checkout imports/c8s/krb5-1.18.2-8.el8
+get_sources.sh
+into_srpm.sh -d c8s
+cd SRPMS
+
+# common commands (make sure to adjust version accordingly)
+rpm2cpio krb5-1.18.2-8c8s.src.rpm | cpio -imdV
+tar xf krb5-1.18.2.tar.gz
+cd krb5-1.18.2/src
+./configure
+make
+sudo cp -P lib/crypto/libk5crypto.* /opt/vagrant/embedded/lib64/
+Packaging can be somewhat difficult to get right due to some of the specific requirements of this provider and of unexpected default behaviour of distributions. The root cause of most issues is typically related to the management network requirement. That is this provider requires that any box has the DHCP enabled for the first network device attached.
The most results where this requirement is not met are failure of the guest to get an IP address on boot or failure for SSH connections to be established.
This typically manifests with the following message appearing as part of a traceback
The specified wait_for timeout (2 seconds) was exceeded (Fog::Errors::TimeoutError)
The first step for troubleshooting a VM image that appears to not boot correctly, or hangs waiting to get an IP, is to check it with a VNC viewer. A key thing to remember is that if the VM doesn’t get an IP, then vagrant can’t communicate with it to configure anything, so a problem at this stage is likely to come from the VM, but we’ll outline the tools and common problems to help you troubleshoot that.
By default, when you create a new VM, a vnc server will listen on 127.0.0.1 on port TCP5900. If you connect with a vnc viewer you can see the boot process. If your VM isn’t listening on 5900 by default;
virsh dumpxml to find out which port it’s listening on, orgraphics_port and graphics_ip (see ‘Domain Specific Options’).Note: Connecting with the console (virsh console) requires additional config, so some VMs may not show anything on the console at all, instead displaying it in the VNC console. The issue with the text console is that you also need to build the image used to tell the kernel to output to the console during boot, and typically most do not have this built in.
Problems we’ve seen in the past include:
/etc/udev/rules.d/70-persistent-net.rules before packaging the VMIf you’re still confused, check the Github Issues for this repo for anything that looks similar to your problem.
Github Issue #1032 contains some historical troubleshooting for VMs that appeared to hang.
Did you hit a problem that you’d like to note here to save time in the future? Please do!