Enable/disable ACPI.
-`agent`: `[enabled=]<1|0> [,fstrim_cloned_disks=<1|0>] [,type=<virtio|isa>]` ::
+`affinity`: `<string>` ::
-Enable/disable communication with the Qemu Guest Agent and its properties.
+List of host cores used to execute guest processes, for example: 0,5,8-11
+
+`agent`: `[enabled=]<1|0> [,freeze-fs-on-backup=<1|0>] [,fstrim_cloned_disks=<1|0>] [,type=<virtio|isa>]` ::
+
+Enable/disable communication with the QEMU Guest Agent and its properties.
`enabled`=`<boolean>` ('default =' `0`);;
-Enable/disable communication with a Qemu Guest Agent (QGA) running in the VM.
+Enable/disable communication with a QEMU Guest Agent (QGA) running in the VM.
+
+`freeze-fs-on-backup`=`<boolean>` ('default =' `1`);;
+
+Freeze/thaw guest filesystems on backup for consistency.
`fstrim_cloned_disks`=`<boolean>` ('default =' `0`);;
Arbitrary arguments passed to kvm, for example:
+
-args: -no-reboot -no-hpet
+args: -no-reboot -smbios 'type=0,vendor=FOO'
+
NOTE: this option is for experts only.
`balloon`: `<integer> (0 - N)` ::
-Amount of target RAM for the VM in MB. Using zero disables the ballon driver.
+Amount of target RAM for the VM in MiB. Using zero disables the ballon driver.
`bios`: `<ovmf | seabios>` ('default =' `seabios`)::
`network`=`<volume>` ;;
-Specify a custom file containing all network data passed to the VM via cloud-init.
+To pass a custom file containing all network data to the VM via cloud-init.
`user`=`<volume>` ;;
-Specify a custom file containing all user data passed to the VM via cloud-init.
+To pass a custom file containing all user data to the VM via cloud-init.
`vendor`=`<volume>` ;;
-Specify a custom file containing all vendor data passed to the VM via cloud-init.
+To pass a custom file containing all vendor data to the VM via cloud-init.
`cipassword`: `<string>` ::
Specifies the cloud-init configuration format. The default depends on the configured operating system type (`ostype`. We use the `nocloud` format for Linux, and `configdrive2` for windows.
+`ciupgrade`: `<boolean>` ('default =' `1`)::
+
+cloud-init: do an automatic package upgrade after the first boot.
+
`ciuser`: `<string>` ::
cloud-init: User name to change ssh keys and password for instead of the image's configured default user.
The physical memory address bits that are reported to the guest OS. Should be smaller or equal to the host's. Set to 'host' to use value from host CPU, but note that doing so will break live migration to CPUs with other values.
-`reported-model`=`<486 | Broadwell | Broadwell-IBRS | Broadwell-noTSX | Broadwell-noTSX-IBRS | Cascadelake-Server | Cascadelake-Server-noTSX | Conroe | EPYC | EPYC-IBPB | EPYC-Rome | Haswell | Haswell-IBRS | Haswell-noTSX | Haswell-noTSX-IBRS | Icelake-Client | Icelake-Client-noTSX | Icelake-Server | Icelake-Server-noTSX | IvyBridge | IvyBridge-IBRS | KnightsMill | Nehalem | Nehalem-IBRS | Opteron_G1 | Opteron_G2 | Opteron_G3 | Opteron_G4 | Opteron_G5 | Penryn | SandyBridge | SandyBridge-IBRS | Skylake-Client | Skylake-Client-IBRS | Skylake-Client-noTSX-IBRS | Skylake-Server | Skylake-Server-IBRS | Skylake-Server-noTSX-IBRS | Westmere | Westmere-IBRS | athlon | core2duo | coreduo | host | kvm32 | kvm64 | max | pentium | pentium2 | pentium3 | phenom | qemu32 | qemu64>` ('default =' `kvm64`);;
+`reported-model`=`<486 | Broadwell | Broadwell-IBRS | Broadwell-noTSX | Broadwell-noTSX-IBRS | Cascadelake-Server | Cascadelake-Server-noTSX | Cascadelake-Server-v2 | Cascadelake-Server-v4 | Cascadelake-Server-v5 | Conroe | Cooperlake | Cooperlake-v2 | EPYC | EPYC-IBPB | EPYC-Milan | EPYC-Rome | EPYC-Rome-v2 | EPYC-v3 | Haswell | Haswell-IBRS | Haswell-noTSX | Haswell-noTSX-IBRS | Icelake-Client | Icelake-Client-noTSX | Icelake-Server | Icelake-Server-noTSX | Icelake-Server-v3 | Icelake-Server-v4 | Icelake-Server-v5 | Icelake-Server-v6 | IvyBridge | IvyBridge-IBRS | KnightsMill | Nehalem | Nehalem-IBRS | Opteron_G1 | Opteron_G2 | Opteron_G3 | Opteron_G4 | Opteron_G5 | Penryn | SandyBridge | SandyBridge-IBRS | SapphireRapids | Skylake-Client | Skylake-Client-IBRS | Skylake-Client-noTSX-IBRS | Skylake-Client-v4 | Skylake-Server | Skylake-Server-IBRS | Skylake-Server-noTSX-IBRS | Skylake-Server-v4 | Skylake-Server-v5 | Westmere | Westmere-IBRS | athlon | core2duo | coreduo | host | kvm32 | kvm64 | max | pentium | pentium2 | pentium3 | phenom | qemu32 | qemu64>` ('default =' `kvm64`);;
CPU model and vendor to report to the guest. Must be a QEMU/KVM supported model. Only valid for custom CPU model definitions, default models will always report themselves to the guest OS.
+
NOTE: If the computer has 2 CPUs, it has total of '2' CPU time. Value '0' indicates no CPU limit.
-`affinity`: `<string>`::
-
-Set of CPU cores to pin the virtual machine processes to. This is a comma sepparated list of numbers or ranges in list format as defined by the Linux man page for cpuset. ( e.g `0,4-6,9` )
-
`cpuunits`: `<integer> (1 - 262144)` ('default =' `cgroup v1: 1024, cgroup v2: 100`)::
CPU weight for a VM. Argument is used in the kernel fair scheduler. The larger the number is, the more CPU time this VM gets. Number is relative to weights of all the other running VMs.
`efidisk0`: `[file=]<volume> [,efitype=<2m|4m>] [,format=<enum>] [,pre-enrolled-keys=<1|0>] [,size=<DiskSize>]` ::
-Configure a Disk for storing EFI vars.
+Configure a disk for storing EFI vars.
`efitype`=`<2m | 4m>` ('default =' `2m`);;
-Size and type of the OVMF EFI vars. '4m' is newer and recommended, and required for Secure Boot. For backwards compatibility, '2m' is used if not otherwise specified.
+Size and type of the OVMF EFI vars. '4m' is newer and recommended, and required for Secure Boot. For backwards compatibility, '2m' is used if not otherwise specified. Ignored for VMs with arch=aarch64 (ARM).
`file`=`<volume>` ;;
Script that will be executed during various steps in the vms lifetime.
-`hostpci[n]`: `[host=]<HOSTPCIID[;HOSTPCIID2...]> [,device-id=<hex id>] [,legacy-igd=<1|0>] [,mdev=<string>] [,pcie=<1|0>] [,rombar=<1|0>] [,romfile=<string>] [,sub-device-id=<hex id>] [,sub-vendor-id=<hex id>] [,vendor-id=<hex id>] [,x-vga=<1|0>]` ::
+`hostpci[n]`: `[[host=]<HOSTPCIID[;HOSTPCIID2...]>] [,device-id=<hex id>] [,legacy-igd=<1|0>] [,mapping=<mapping-id>] [,mdev=<string>] [,pcie=<1|0>] [,rombar=<1|0>] [,romfile=<string>] [,sub-device-id=<hex id>] [,sub-vendor-id=<hex id>] [,vendor-id=<hex id>] [,x-vga=<1|0>]` ::
Map host PCI devices into guest.
+
'bus:dev.func' (hexadecimal numbers)
+
You can us the 'lspci' command to list existing PCI devices.
++
+Either this or the 'mapping' key must be set.
`legacy-igd`=`<boolean>` ('default =' `0`);;
Pass this device in legacy IGD mode, making it the primary and exclusive graphics device in the VM. Requires 'pc-i440fx' machine type and VGA set to 'none'.
+`mapping`=`<mapping-id>` ;;
+
+The ID of a cluster wide mapping. Either this or the default-key 'host' must be set.
+
`mdev`=`<string>` ;;
The type of mediated device to use.
`hotplug`: `<string>` ('default =' `network,disk,usb`)::
-Selectively enable hotplug features. This is a comma separated list of hotplug features: 'network', 'disk', 'cpu', 'memory' and 'usb'. Use '0' to disable hotplug completely. Using '1' as value is an alias for the default `network,disk,usb`.
+Selectively enable hotplug features. This is a comma separated list of hotplug features: 'network', 'disk', 'cpu', 'memory', 'usb' and 'cloudinit'. Use '0' to disable hotplug completely. Using '1' as value is an alias for the default `network,disk,usb`. USB hotplugging is possible for guests with machine version >= 7.1 and ostype l26 or windows > 7.
`hugepages`: `<1024 | 2 | any>` ::
`machine`: `(pc|pc(-i440fx)?-\d+(\.\d+)+(\+pve\d+)?(\.pxe)?|q35|pc-q35-\d+(\.\d+)+(\+pve\d+)?(\.pxe)?|virt(?:-\d+(\.\d+)+)?(\+pve\d+)?)` ::
-Specifies the Qemu machine type.
+Specifies the QEMU machine type.
+
+`memory`: `[current=]<integer>` ::
-`memory`: `<integer> (16 - N)` ('default =' `512`)::
+Memory properties.
-Amount of RAM for the VM in MB. This is the maximum available memory when you use the balloon device.
+`current`=`<integer> (16 - N)` ('default =' `512`);;
+
+Current amount of online RAM for the VM in MiB. This is the maximum available memory when you use the balloon device.
`migrate_downtime`: `<number> (0 - N)` ('default =' `0.1`)::
`nameserver`: `<string>` ::
-cloud-init: Sets DNS server IP address for a container. Create will'
- .' automatically use the setting from the host if neither searchdomain nor nameserver'
- .' are set.
+cloud-init: Sets DNS server IP address for a container. Create will automatically use the setting from the host if neither searchdomain nor nameserver are set.
`net[n]`: `[model=]<enum> [,bridge=<bridge>] [,firewall=<1|0>] [,link_down=<1|0>] [,macaddr=<XX:XX:XX:XX:XX:XX>] [,mtu=<integer>] [,queues=<integer>] [,rate=<number>] [,tag=<integer>] [,trunks=<vlanid[;vlanid...]>] [,<model>=<macaddr>]` ::
Force MTU, for VirtIO only. Set to '1' to use the bridge MTU
-`queues`=`<integer> (0 - 16)` ;;
+`queues`=`<integer> (0 - 64)` ;;
Number of packet queues to be used on the device.
win10;; Microsoft Windows 10/2016/2019
win11;; Microsoft Windows 11/2022
l24;; Linux 2.4 Kernel
-l26;; Linux 2.6 - 5.X Kernel
+l26;; Linux 2.6 - 6.X Kernel
solaris;; Solaris/OpenSolaris/OpenIndiania kernel
`parallel[n]`: `/dev/parport\d+|/dev/usb/lp\d+` ::
`searchdomain`: `<string>` ::
-cloud-init: Sets DNS search domains for a container. Create will'
- .' automatically use the setting from the host if neither searchdomain nor nameserver'
- .' are set.
+cloud-init: Sets DNS search domains for a container. Create will automatically use the setting from the host if neither searchdomain nor nameserver are set.
`serial[n]`: `(/dev/.+|socket)` ::
The drive's backing volume.
-`usb[n]`: `[host=]<HOSTUSBDEVICE|spice> [,usb3=<1|0>]` ::
+`usb[n]`: `[[host=]<HOSTUSBDEVICE|spice>] [,mapping=<mapping-id>] [,usb3=<1|0>]` ::
-Configure an USB device (n is 0 to 4).
+Configure an USB device (n is 0 to 4, for machine version >= 7.1 and ostype l26 or windows > 7, n can be up to 14).
`host`=`<HOSTUSBDEVICE|spice>` ;;
machines - use with special care.
+
The value 'spice' can be used to add a usb redirection devices for spice.
++
+Either this or the 'mapping' key must be set.
+
+`mapping`=`<mapping-id>` ;;
+
+The ID of a cluster wide mapping. Either this or the default-key 'host' must be set.
`usb3`=`<boolean>` ('default =' `0`);;
-Specifies whether if given host option is a USB3 device or port.
+Specifies whether if given host option is a USB3 device or port. For modern guests (machine version >= 7.1 and ostype l26 and windows > 7), this flag is irrelevant (all devices are plugged into a xhci controller).
`vcpus`: `<integer> (1 - N)` ('default =' `0`)::
Number of hotplugged vcpus.
-`vga`: `[[type=]<enum>] [,memory=<integer>]` ::
+`vga`: `[[type=]<enum>] [,clipboard=<vnc>] [,memory=<integer>]` ::
Configure the VGA Hardware. If you want to use high resolution modes (>= 1280x1024x16) you may need to increase the vga memory option. Since QEMU 2.9 the default VGA display type is 'std' for all OS types besides some Windows versions (XP and older) which use 'cirrus'. The 'qxl' option enables the SPICE display server. For win* OS you can select how many independent displays you want, Linux guests can add displays them self.
You can also run without any graphic card, using a serial device as terminal.
+`clipboard`=`<vnc>` ;;
+
+Enable a specific clipboard. If not set, depending on the display type the SPICE one will be added.
+
`memory`=`<integer> (4 - 512)` ;;
Sets the VGA memory (in MiB). Has no effect with serial display.