*`disk_driver` - Extra options for the main disk driver ([see Libvirt documentation](http://libvirt.org/formatdomain.html#elementsDisks)).
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".
*`shares` - Proportional weighted share for the domain relative to others. For more details see [documentation](https://libvirt.org/formatdomain.html#elementsCPUTuning).
*`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](https://libvirt.org/formatdomain.html#elementsCPUAllocation).
*`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](https://libvirt.org/formatdomain.html#elementsCPU).
*`nodeset` - Physical NUMA nodes where virtual memory can be pinned. For more details see [documentation](https://libvirt.org/formatdomain.html#elementsNUMATuning).
*`cpu_mode` - [CPU emulation mode](https://libvirt.org/formatdomain.html#elementsCPU). 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`**
*`launchsecurity` - Configure Secure Encryption Virtualization for the guest, requires additional components to be configured to work, see [examples](./examples.html#secure-encryption-virtualization). For more information look at [libvirt documentation](https://libvirt.org/kbase/launch_security_sev.html).
*`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](https://libvirt.org/kbase/launch_security_sev.html) for details on why.
```
libvirt.memtune :type => "hard_limit", :value => 2500000 # Note here the value in kB (not in Mb)
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](http://libvirt.org/formatdomain.html#elementsDisks)
or [here](https://www.suse.com/documentation/sles11/book_kvm/data/sect1_chapter_book_kvm.html) 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.
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](#domain-specific-options) `kvm_hidden` option to `true` especially if you are passthroughing NVIDIA GPUs. Otherwise GPU is visible from VM but cannot be operated.
## Using USB Devices
There are several ways to pass a USB device through to a running instance:
* Use `libvirt.usb` to [attach a USB device at boot](#usb-device-passthrough), with the device ID specified in the Vagrantfile
* Use a client (such as `virt-viewer` or `virt-manager`) to attach the device at runtime [via USB redirectors](#usb-redirector-devices)
* Use `virsh 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.
### USB Controller Configuration
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.
```ruby
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](https://libvirt.org/formatdomain.html#elementsControllers) 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.
### USB Device Passthrough
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
```
```ruby
Vagrant.configure("2") do |config|
config.vm.provider :libvirt do |libvirt|
# pass through specific device based on identifying it
# 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".
### USB Redirector Devices
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`)
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](https://en.wikipedia.org/wiki/USB#Device_classes).
*`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 `bcdDevice`
*`allow` - 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:
```shell
# 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.
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](https://libvirt.org/formatdomain.html#elementCharSerial).
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.
You can pass through `/dev/random` to your VM by configuring the domain like this:
```ruby
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.
## Watchdog device
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 6300ESB
* 'ib700` - emulating an ISA iBase IB700
*`diag288` - emulating an S390 DIAG288 device
The 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 guest
*`shutdown` - gracefully shutdown the guest (not recommended)
*`poweroff` - forcefully power off the guest
*`pause` - pause the guest
*`none` - do nothing
*`dump` - automatically dump the guest
*`inject-nmi` - inject a non-maskable interrupt into the guest
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.
You can specify memoryBacking options via `libvirt.memorybacking`. Available options are shown below. Full documentation is available at the [libvirt _memoryBacking_ section](https://libvirt.org/formatdomain.html#elementsMemoryBacking).
NOTE: The hugepages `<page>` element is not yet supported
