Mandatory Configuration Items

name="NAME"

Specifies the name of the domain. Names of domains existing on a single host must be unique.

Selecting Guest Type

type="pv"

Specifies that this is to be a PV domain, suitable for hosting Xen-aware guest operating systems. This is the default on x86.

type="pvh"

Specifies that this is to be an PVH domain. That is a lightweight HVM-like guest without a device model and without many of the emulated devices available to HVM guests. Note that this mode requires a PVH aware kernel on x86. This is the default on Arm.

type="hvm"

Specifies that this is to be an HVM domain. That is, a fully virtualised computer with emulated BIOS, disk and network peripherals, etc.

Deprecated guest type selection

Note that the builder option is being deprecated in favor of the type option.

builder="generic"

Specifies that this is to be a PV domain, suitable for hosting Xen-aware guest operating systems. This is the default.

builder="hvm"

Specifies that this is to be an HVM domain. That is, a fully virtualised computer with emulated BIOS, disk and network peripherals, etc.

General Options

CPU Allocation

pool="CPUPOOLNAME"

Put the guest's vCPUs into the named CPU pool.

vcpus=N

Start the guest with N vCPUs initially online.

maxvcpus=M

Allow the guest to bring up a maximum of M vCPUs. When starting the guest, if vcpus=N is less than maxvcpus=M then the first N vCPUs will be created online and the remainder will be created offline.

cpus="CPULIST"

List of host CPUs the guest is allowed to use. Default is no pinning at all (more on this below). A "CPULIST" may be specified as follows:

cpus_soft="CPULIST"

Exactly as cpus=, but specifies soft affinity, rather than pinning (hard affinity). When using the credit scheduler, this means what CPUs the vCPUs of the domain prefer.

A "CPULIST" is specified exactly as for cpus=, detailed earlier in the manual.

If this option is not specified, the vCPUs of the guest will not have any preference regarding host CPUs. If this option is specified, the intersection of the soft affinity mask, provided here, and the vCPU pinning, if provided via cpus=, is utilized to compute the domain node-affinity for driving memory allocations.

If this option is not specified (and cpus= is not specified either), libxl automatically tries to place the guest on the least possible number of nodes. A heuristic approach is used for choosing the best node (or set of nodes), with the goal of maximizing performance for the guest and, at the same time, achieving efficient utilization of host CPUs and memory. In that case, the soft affinity of all the vCPUs of the domain will be set to host CPUs belonging to NUMA nodes chosen during placement.

For more details, see xl-numa-placement(7).

CPU Scheduling

cpu_weight=WEIGHT

A domain with a weight of 512 will get twice as much CPU as a domain with a weight of 256 on a contended host. Legal weights range from 1 to 65535 and the default is 256. Honoured by the credit and credit2 schedulers.

cap=N

The cap optionally fixes the maximum amount of CPU a domain will be able to consume, even if the host system has idle CPU cycles. The cap is expressed as a percentage of one physical CPU: 100 is 1 physical CPU, 50 is half a CPU, 400 is 4 CPUs, etc. The default, 0, means there is no cap. Honoured by the credit and credit2 schedulers.

NOTE: Many systems have features that will scale down the computing power of a CPU that is not 100% utilized. This can be done in the operating system, but can also sometimes be done below the operating system, in the BIOS. If you set a cap such that individual cores are running at less than 100%, this may have an impact on the performance of your workload over and above the impact of the cap. For example, if your processor runs at 2GHz, and you cap a VM at 50%, the power management system may also reduce the clock speed to 1GHz; the effect will be that your VM gets 25% of the available power (50% of 1GHz) rather than 50% (50% of 2GHz). If you are not getting the performance you expect, look at performance and CPU frequency options in your operating system and your BIOS.

Memory Allocation

memory=MBYTES

Start the guest with MBYTES megabytes of RAM.

maxmem=MBYTES

Specifies the maximum amount of memory a guest can ever see. The value of maxmem= must be equal to or greater than that of memory=.

In combination with memory= it will start the guest "pre-ballooned", if the values of memory= and maxmem= differ. A "pre-ballooned" HVM guest needs a balloon driver, without a balloon driver it will crash.

NOTE: Because of the way ballooning works, the guest has to allocate memory to keep track of maxmem pages, regardless of how much memory it actually has available to it. A guest with maxmem=262144 and memory=8096 will report significantly less memory available for use than a system with maxmem=8096 memory=8096 due to the memory overhead of having to track the unused pages.

Guest Virtual NUMA Configuration

vnuma=[ VNODE_SPEC, VNODE_SPEC, ... ]

Specify virtual NUMA configuration with positional arguments. The nth VNODE_SPEC in the list specifies the configuration of the nth virtual node.

Note that virtual NUMA is not supported for PV guests yet, because there is an issue with the CPUID instruction handling that affects PV virtual NUMA. Furthermore, guests with virtual NUMA cannot be saved or migrated because the migration stream does not preserve node information.

Each VNODE_SPEC is a list, which has a form of "[VNODE_CONFIG_OPTION, VNODE_CONFIG_OPTION, ... ]" (without the quotes).

For example, vnuma = [ ["pnode=0","size=512","vcpus=0-4","vdistances=10,20"] ] means vnode 0 is mapped to pnode 0, has 512MB ram, has vcpus 0 to 4, the distance to itself is 10 and the distance to vnode 1 is 20.

Each VNODE_CONFIG_OPTION is a quoted "KEY=VALUE" pair. Supported VNODE_CONFIG_OPTIONs are (they are all mandatory at the moment):

Event Actions

on_poweroff="ACTION"

Specifies what should be done with the domain if it shuts itself down. The ACTIONs are:

on_reboot="ACTION"

Action to take if the domain shuts down with a reason code requesting a reboot. Default is restart.

on_watchdog="ACTION"

Action to take if the domain shuts down due to a Xen watchdog timeout. Default is destroy.

on_crash="ACTION"

Action to take if the domain crashes. Default is destroy.

on_soft_reset="ACTION"

Action to take if the domain performs a 'soft reset' (e.g. does kexec). Default is soft-reset.

Direct Kernel Boot

Direct kernel boot allows booting guests with a kernel and an initrd stored on a filesystem available to the host physical machine, allowing command line arguments to be passed directly. PV guest direct kernel boot is supported. HVM guest direct kernel boot is supported with some limitations (it's supported when using qemu-xen and the default BIOS 'seabios', but not supported in case of using stubdom-dm and the old 'rombios'.)

kernel="PATHNAME"

Load the specified file as the kernel image.

ramdisk="PATHNAME"

Load the specified file as the ramdisk.

cmdline="STRING"

Append STRING to the kernel command line. (Note: the meaning of this is guest specific). It can replace root="STRING" along with extra="STRING" and is preferred. When cmdline="STRING" is set, root="STRING" and extra="STRING" will be ignored.

root="STRING"

Append root=STRING to the kernel command line (Note: the meaning of this is guest specific).

extra="STRING"

Append STRING to the kernel command line. (Note: the meaning of this is guest specific).

Non direct Kernel Boot

Non direct kernel boot allows booting guests with a firmware. This can be used by all types of guests, although the selection of options is different depending on the guest type.

This option provides the flexibly of letting the guest decide which kernel they want to boot, while preventing having to poke at the guest file system form the toolstack domain.

PV guest options

firmware="pvgrub32|pvgrub64"

Boots a guest using a para-virtualized version of grub that runs inside of the guest. The bitness of the guest needs to be know, so that the right version of pvgrub can be selected.

Note that xl expects to find the pvgrub32.bin and pvgrub64.bin binaries in /usr/local/lib/xen/boot.

HVM guest options

firmware="bios"

Boot the guest using the default BIOS firmware, which depends on the chosen device model.

firmware="uefi"

Boot the guest using the default UEFI firmware, currently OVMF.

firmware="seabios"

Boot the guest using the SeaBIOS BIOS firmware.

firmware="rombios"

Boot the guest using the ROMBIOS BIOS firmware.

firmware="ovmf"

Boot the guest using the OVMF UEFI firmware.

firmware="PATH"

Load the specified file as firmware for the guest.

PVH guest options

Currently there's no firmware available for PVH guests, they should be booted using the Direct Kernel Boot method or the bootloader option.

pvshim=BOOLEAN

Whether to boot this guest as a PV guest within a PVH container. Ie, the guest will experience a PV environment, but processor hardware extensions are used to separate its address space to mitigate the Meltdown attack (CVE-2017-5754).

Default is false.

pvshim_path="PATH"

The PV shim is a specially-built firmware-like executable constructed from the hypervisor source tree. This option specifies to use a non-default shim. Ignored if pvhsim is false.

pvshim_cmdline="STRING"

Command line for the shim. Default is "pv-shim console=xen,pv". Ignored if pvhsim is false.

pvshim_extra="STRING"

Extra command line arguments for the shim. If supplied, appended to the value for pvshim_cmdline. Default is empty. Ignored if pvhsim is false.

Other Options

uuid="UUID"

Specifies the UUID of the domain. If not specified, a fresh unique UUID will be generated.

seclabel="LABEL"

Assign an XSM security label to this domain.

init_seclabel="LABEL"

Specify an XSM security label used for this domain temporarily during its build. The domain's XSM label will be changed to the execution seclabel (specified by seclabel) once the build is complete, prior to unpausing the domain. With a properly constructed security policy (such as nomigrate_t in the example policy), this can be used to build a domain whose memory is not accessible to the toolstack domain.

max_grant_frames=NUMBER

Specify the maximum number of grant frames the domain is allowed to have. This value controls how many pages the domain is able to grant access to for other domains, needed e.g. for the operation of paravirtualized devices. The default is settable via xl.conf(5).

max_maptrack_frames=NUMBER

Specify the maximum number of grant maptrack frames the domain is allowed to have. This value controls how many pages of foreign domains can be accessed via the grant mechanism by this domain. The default value is settable via xl.conf(5).

max_grant_version=NUMBER

Specify the maximum grant table version the domain is allowed to use. The default value is settable via xl.conf(5).

nomigrate=BOOLEAN

Disable migration of this domain. This enables certain other features which are incompatible with migration. Currently this is limited to enabling the invariant TSC feature flag in CPUID results when TSC is not emulated.

driver_domain=BOOLEAN

Specify that this domain is a driver domain. This enables certain features needed in order to run a driver domain.

device_tree=PATH

Specify a partial device tree (compiled via the Device Tree Compiler). Everything under the node "/passthrough" will be copied into the guest device tree. For convenience, the node "/aliases" is also copied to allow the user to define aliases which can be used by the guest kernel.

Given the complexity of verifying the validity of a device tree, this option should only be used with a trusted device tree.

Note that the partial device tree should avoid using the phandle 65000 which is reserved by the toolstack.

passthrough="STRING"

Specify whether IOMMU mappings are enabled for the domain and hence whether it will be enabled for passthrough hardware. Valid values for this option are:

xend_suspend_evtchn_compat=BOOLEAN

If this option is true the xenstore path for the domain's suspend event channel will not be created. Instead the old xend behaviour of making the whole xenstore device sub-tree writable by the domain will be re-instated.

The existence of the suspend event channel path can cause problems with certain PV drivers running in the guest (e.g. old Red Hat PV drivers for Windows).

If this option is not specified then it will default to false.

vmtrace_buf_kb=KBYTES

Specifies the size of vmtrace buffer that would be allocated for each vCPU belonging to this domain. Disabled (i.e. vmtrace_buf_kb=0) by default.

NOTE: Acceptable values are platform specific. For Intel Processor Trace, this value must be a power of 2 between 4k and 16M.

vpmu=BOOLEAN

Currently ARM only.

Specifies whether to enable the access to PMU registers by disabling the PMU traps.

The PMU registers are not virtualized and the physical registers are directly accessible when this parameter is enabled. There is no interrupt support and Xen will not save/restore the register values on context switches.

vPMU, by design and purpose, exposes system level performance information to the guest. Only to be used by sufficiently privileged domains. This feature is currently in experimental state.

If this option is not specified then it will default to false.

Devices

disk=[ "DISK_SPEC_STRING", "DISK_SPEC_STRING", ...]

Specifies the disks (both emulated disks and Xen virtual block devices) which are to be provided to the guest, and what objects on the host they should map to. See xl-disk-configuration(5) for more details.

vif=[ "NET_SPEC_STRING", "NET_SPEC_STRING", ...]

Specifies the network interfaces (both emulated network adapters, and Xen virtual interfaces) which are to be provided to the guest. See xl-network-configuration(5) for more details.

vtpm=[ "VTPM_SPEC_STRING", "VTPM_SPEC_STRING", ...]

Specifies the Virtual Trusted Platform module to be provided to the guest. See xen-vtpm(7) for more details.

Each VTPM_SPEC_STRING is a comma-separated list of "KEY=VALUE" settings from the following list:

p9=[ "9PFS_SPEC_STRING", "9PFS_SPEC_STRING", ...]

Creates a Xen 9pfs connection to share a filesystem from the backend to the frontend.

Each 9PFS_SPEC_STRING is a comma-separated list of "KEY=VALUE" settings, from the following list:

pvcalls=[ "backend=domain-id", ... ]

Creates a Xen pvcalls connection to handle pvcalls requests from frontend to backend. It can be used as an alternative networking model. For more information about the protocol, see https://xenbits.xenproject.org/docs/unstable/misc/pvcalls.html.

vfb=[ "VFB_SPEC_STRING", "VFB_SPEC_STRING", ...]

Specifies the paravirtual framebuffer devices which should be supplied to the domain.

This option does not control the emulated graphics card presented to an HVM guest. See Emulated VGA Graphics Device below for how to configure the emulated device. If Emulated VGA Graphics Device options are used in a PV guest configuration, xl will pick up vnc, vnclisten, vncpasswd, vncdisplay, vncunused, sdl, opengl and keymap to construct the paravirtual framebuffer device for the guest.

Each VFB_SPEC_STRING is a comma-separated list of "KEY=VALUE" settings, from the following list:

channel=[ "CHANNEL_SPEC_STRING", "CHANNEL_SPEC_STRING", ...]

Specifies the virtual channels to be provided to the guest. A channel is a low-bandwidth, bidirectional byte stream, which resembles a serial link. Typical uses for channels include transmitting VM configuration after boot and signalling to in-guest agents. Please see xen-pv-channel(7) for more details.

Each CHANNEL_SPEC_STRING is a comma-separated list of "KEY=VALUE" settings. Leading and trailing whitespace is ignored in both KEY and VALUE. Neither KEY nor VALUE may contain ',', '=' or '"'. Defined values are:

rdm="RDM_RESERVATION_STRING"

HVM/x86 only! Specifies information about Reserved Device Memory (RDM), which is necessary to enable robust device passthrough. One example of RDM is reporting through the ACPI Reserved Memory Region Reporting (RMRR) structure on the x86 platform.

RDM_RESERVATION_STRING is a comma separated list of "KEY=VALUE" settings, from the following list:

usbctrl=[ "USBCTRL_SPEC_STRING", "USBCTRL_SPEC_STRING", ...]

Specifies the USB controllers created for this guest.

Each USBCTRL_SPEC_STRING is a comma-separated list of "KEY=VALUE" settings, from the following list:

usbdev=[ "USBDEV_SPEC_STRING", "USBDEV_SPEC_STRING", ...]

Specifies the USB devices to be attached to the guest at boot.

Each USBDEV_SPEC_STRING is a comma-separated list of "KEY=VALUE" settings, from the following list:

pci=[ "PCI_SPEC_STRING", "PCI_SPEC_STRING", ...]

Specifies the host PCI devices to passthrough to this guest. See xl-pci-configuration(5) for more details.

pci_permissive=BOOLEAN

Changes the default value of permissive for all PCI devices passed through to this VM. See permissive above.

pci_msitranslate=BOOLEAN

Changes the default value of msitranslate for all PCI devices passed through to this VM. See msitranslate above.

pci_seize=BOOLEAN

Changes the default value of seize for all PCI devices passed through to this VM. See seize above.

pci_power_mgmt=BOOLEAN

(HVM only) Changes the default value of power_mgmt for all PCI devices passed through to this VM. See power_mgmt above.

gfx_passthru=BOOLEAN|"STRING"

Enable graphics device PCI passthrough. This option makes an assigned PCI graphics card become the primary graphics card in the VM. The QEMU emulated graphics adapter is disabled and the VNC console for the VM will not have any graphics output. All graphics output, including boot time QEMU BIOS messages from the VM, will go to the physical outputs of the passed through physical graphics card.

The graphics card PCI device to pass through is chosen with the pci option, in exactly the same way a normal Xen PCI device passthrough/assignment is done. Note that gfx_passthru does not do any kind of sharing of the GPU, so you can assign the GPU to only one single VM at a time.

gfx_passthru also enables various legacy VGA memory ranges, BARs, MMIOs, and ioports to be passed through to the VM, since those are required for correct operation of things like VGA BIOS, text mode, VBE, etc.

Enabling the gfx_passthru option also copies the physical graphics card video BIOS to the guest memory, and executes the VBIOS in the guest to initialize the graphics card.

Most graphics adapters require vendor specific tweaks for properly working graphics passthrough. See the XenVGAPassthroughTestedAdapters <https://wiki.xenproject.org/wiki/XenVGAPassthroughTestedAdapters> wiki page for graphics cards currently supported by gfx_passthru.

gfx_passthru is currently supported both with the qemu-xen-traditional device-model and upstream qemu-xen device-model.

When given as a boolean the gfx_passthru option either disables graphics card passthrough or enables autodetection.

When given as a string the gfx_passthru option describes the type of device to enable. Note that this behavior is only supported with the upstream qemu-xen device-model. With qemu-xen-traditional IGD (Intel Graphics Device) is always assumed and options other than autodetect or explicit IGD will result in an error.

Currently, valid values for the option are:

rdm_mem_boundary=MBYTES

Number of megabytes to set for a boundary when checking for RDM conflicts.

When RDM conflicts with RAM, RDM is probably scattered over the whole RAM space. Having multiple RDM entries would worsen this and lead to a complicated memory layout. Here we're trying to figure out a simple solution to avoid breaking the existing layout. When a conflict occurs,

    #1. Above a predefined boundary
        - move lowmem_end below the reserved region to solve the conflict;

    #2. Below a predefined boundary
        - Check if the policy is strict or relaxed.
        A "strict" policy leads to a fail in libxl.
        Note that when both policies are specified on a given region,
        "strict" is always preferred.
        The "relaxed" policy issues a warning message and also masks this
        entry INVALID to indicate we shouldn't expose this entry to
        hvmloader.
    

The default value is 2048.

dtdev=[ "DTDEV_PATH", "DTDEV_PATH", ...]

Specifies the host device tree nodes to passt hrough to this guest. Each DTDEV_PATH is an absolute path in the device tree.

ioports=[ "IOPORT_RANGE", "IOPORT_RANGE", ...]

Allow the guest to access specific legacy I/O ports. Each IOPORT_RANGE is given in hexadecimal format and may either be a range, e.g. "2f8-2ff" (inclusive), or a single I/O port, e.g. "2f8".

It is recommended to only use this option for trusted VMs under administrator's control.

iomem=[ "IOMEM_START,NUM_PAGES[@GFN]", "IOMEM_START,NUM_PAGES[@GFN]", ...]

Allow auto-translated domains to access specific hardware I/O memory pages.

IOMEM_START is a physical page number. NUM_PAGES is the number of pages, beginning with START_PAGE, to allow access to. GFN specifies the guest frame number where the mapping will start in the guest's address space. If GFN is not specified, the mapping will be performed using IOMEM_START as a start in the guest's address space, therefore performing a 1:1 mapping by default. All of these values must be given in hexadecimal format.

Note that the IOMMU won't be updated with the mappings specified with this option. This option therefore should not be used to pass through any IOMMU-protected devices.

It is recommended to only use this option for trusted VMs under administrator's control.

irqs=[ NUMBER, NUMBER, ...]

Allow a guest to access specific physical IRQs.

It is recommended to only use this option for trusted VMs under administrator's control.

If vuart console is enabled then irq 32 is reserved for it. See "vuart="uart"" to know how to enable vuart console.

max_event_channels=N

Limit the guest to using at most N event channels (PV interrupts). Guests use hypervisor resources for each event channel they use.

The default of 1023 should be sufficient for typical guests. The maximum value depends on what the guest supports. Guests supporting the FIFO-based event channel ABI support up to 131,071 event channels. Other guests are limited to 4095 (64-bit x86 and ARM) or 1023 (32-bit x86).

vdispl=[ "VDISPL_SPEC_STRING", "VDISPL_SPEC_STRING", ...]

Specifies the virtual display devices to be provided to the guest.

Each VDISPL_SPEC_STRING is a comma-separated list of "KEY=VALUE" settings, from the following list:

dm_restrict=BOOLEAN

Restrict the device model after startup, to limit the consequencese of security vulnerabilities in qemu.

See docs/features/qemu-depriv.pandoc for more information on Linux and QEMU version requirements, device model user setup, and current limitations.

This feature is a technology preview. See SUPPORT.md for a security support statement.

device_model_user=USERNAME

When running dm_restrict, run the device model as this user.

NOTE: Each domain MUST have a SEPARATE username.

See docs/features/qemu-depriv.pandoc for more information.

vsnd=[ VCARD_SPEC, VCARD_SPEC, ... ]

Specifies the virtual sound cards to be provided to the guest. Each VCARD_SPEC is a list, which has a form of "[VSND_ITEM_SPEC, VSND_ITEM_SPEC, ... ]" (without the quotes). The virtual sound card has hierarchical structure. Every card has a set of PCM devices and streams, each could be individually configured.

VSND_ITEM_SPEC describes individual item parameters. VSND_ITEM_SPEC is a string of comma separated item parameters headed by item identifier. Each item parameter is "KEY=VALUE" pair:

    vsnd = [
        ['CARD, short-name=Main, sample-formats=s16_le;s8;u32_be',
            'PCM, name=Main',
                'STREAM, id=0, type=p',
                'STREAM, id=1, type=c, channels-max=2'
        ],
        ['CARD, short-name=Second',
            'PCM, name=Second, buffer-size=1024',
                'STREAM, id=2, type=p',
                'STREAM, id=3, type=c'
        ]
    ]

vkb=[ "VKB_SPEC_STRING", "VKB_SPEC_STRING", ...]

Specifies the virtual keyboard device to be provided to the guest.

Each VKB_SPEC_STRING is a comma-separated list of "KEY=VALUE" settings from the following list:

tee="STRING"

Arm only. Set TEE type for the guest. TEE is a Trusted Execution Environment -- separate secure OS found on some platforms. STRING can be one of the:

Paravirtualised (PV) Guest Specific Options

bootloader="PROGRAM"

Run "PROGRAM" to find the kernel image and ramdisk to use. Normally "PROGRAM" would be "pygrub", which is an emulation of grub/grub2/syslinux. Either kernel or bootloader must be specified for PV guests.

bootloader_args=[ "ARG", "ARG", ...]

Append ARGs to the arguments to the bootloader program. Alternatively if the argument is a simple string then it will be split into words at whitespace (this second option is deprecated).

e820_host=BOOLEAN

Selects whether to expose the host e820 (memory map) to the guest via the virtual e820. When this option is false (0) the guest pseudo-physical address space consists of a single contiguous RAM region. When this option is specified the virtual e820 instead reflects the host e820 and contains the same PCI holes. The total amount of RAM represented by the memory map is always the same, this option configures only how it is laid out.

Exposing the host e820 to the guest gives the guest kernel the opportunity to set aside the required part of its pseudo-physical address space in order to provide address space to map passedthrough PCI devices. It is guest Operating System dependent whether this option is required, specifically it is required when using a mainline Linux ("pvops") kernel. This option defaults to true (1) if any PCI passthrough devices are configured and false (0) otherwise. If you do not configure any passthrough devices at domain creation time but expect to hotplug devices later then you should set this option. Conversely if your particular guest kernel does not require this behaviour then it is safe to allow this to be enabled but you may wish to disable it anyway.

Fully-virtualised (HVM) Guest Specific Options

Boot Device

boot="STRING"

Specifies the emulated virtual device to boot from.

Possible values are:

Emulated disk controller type

hdtype=STRING

Specifies the hard disk type.

Possible values are:

Paging

The following options control the mechanisms used to virtualise guest memory. The defaults are selected to give the best results for the common cases so you should normally leave these options unspecified.

hap=BOOLEAN

Turns "hardware assisted paging" (the use of the hardware nested page table feature) on or off. This feature is called EPT (Extended Page Tables) by Intel and NPT (Nested Page Tables) or RVI (Rapid Virtualisation Indexing) by AMD. If turned off, Xen will run the guest in "shadow page table" mode where the guest's page table updates and/or TLB flushes etc. will be emulated. Use of HAP is the default when available.

oos=BOOLEAN

Turns "out of sync pagetables" on or off. When running in shadow page table mode, the guest's page table updates may be deferred as specified in the Intel/AMD architecture manuals. However, this may expose unexpected bugs in the guest, or find bugs in Xen, so it is possible to disable this feature. Use of out of sync page tables, when Xen thinks it appropriate, is the default.

shadow_memory=MBYTES

Number of megabytes to set aside for shadowing guest pagetable pages (effectively acting as a cache of translated pages) or to use for HAP state. By default this is 1MB per guest vCPU plus 8KB per MB of guest RAM. You should not normally need to adjust this value. However, if you are not using hardware assisted paging (i.e. you are using shadow mode) and your guest workload consists of a very large number of similar processes then increasing this value may improve performance.

Processor and Platform Features

The following options allow various processor and platform level features to be hidden or exposed from the guest's point of view. This can be useful when running older guest Operating Systems which may misbehave when faced with more modern features. In general, you should accept the defaults for these options wherever possible.

bios="STRING"

Select the virtual firmware that is exposed to the guest. By default, a guess is made based on the device model, but sometimes it may be useful to request a different one, like UEFI.

bios_path_override="PATH"

Override the path to the blob to be used as BIOS. The blob provided here MUST be consistent with the bios= which you have specified. You should not normally need to specify this option.

This option does not have any effect if using bios="rombios" or device_model_version="qemu-xen-traditional".

pae=BOOLEAN

Hide or expose the IA32 Physical Address Extensions. These extensions make it possible for a 32 bit guest Operating System to access more than 4GB of RAM. Enabling PAE also enabled other features such as NX. PAE is required if you wish to run a 64-bit guest Operating System. In general, you should leave this enabled and allow the guest Operating System to choose whether or not to use PAE. (X86 only)

acpi=BOOLEAN

Expose ACPI (Advanced Configuration and Power Interface) tables from the virtual firmware to the guest Operating System. ACPI is required by most modern guest Operating Systems. This option is enabled by default and usually you should omit it. However, it may be necessary to disable ACPI for compatibility with some guest Operating Systems. This option is true for x86 while it's false for ARM by default.

acpi_s3=BOOLEAN

Include the S3 (suspend-to-ram) power state in the virtual firmware ACPI table. True (1) by default.

acpi_s4=BOOLEAN

Include S4 (suspend-to-disk) power state in the virtual firmware ACPI table. True (1) by default.

acpi_laptop_slate=BOOLEAN

Include the Windows laptop/slate mode switch device in the virtual firmware ACPI table. False (0) by default.

apic=BOOLEAN

(x86 only) Include information regarding APIC (Advanced Programmable Interrupt Controller) in the firmware/BIOS tables on a single processor guest. This causes the MP (multiprocessor) and PIR (PCI Interrupt Routing) tables to be exported by the virtual firmware. This option has no effect on a guest with multiple virtual CPUs as they must always include these tables. This option is enabled by default and you should usually omit it but it may be necessary to disable these firmware tables when using certain older guest Operating Systems. These tables have been superseded by newer constructs within the ACPI tables.

nx=BOOLEAN

(x86 only) Hides or exposes the No-eXecute capability. This allows a guest Operating System to map pages in such a way that they cannot be executed which can enhance security. This options requires that PAE also be enabled.

hpet=BOOLEAN

(x86 only) Enables or disables HPET (High Precision Event Timer). This option is enabled by default and you should usually omit it. It may be necessary to disable the HPET in order to improve compatibility with guest Operating Systems.

altp2m="MODE"

(x86 only) Specifies the access mode to the alternate-p2m capability. Alternate-p2m allows a guest to manage multiple p2m guest physical "memory views" (as opposed to a single p2m). You may want this option if you want to access-control/isolate access to specific guest physical memory pages accessed by the guest, e.g. for domain memory introspection or for isolation/access-control of memory between components within a single guest domain. This option is disabled by default.

The valid values are as follows:

altp2mhvm=BOOLEAN

Enables or disables HVM guest access to alternate-p2m capability. Alternate-p2m allows a guest to manage multiple p2m guest physical "memory views" (as opposed to a single p2m). This option is disabled by default and is available only to HVM domains. You may want this option if you want to access-control/isolate access to specific guest physical memory pages accessed by the guest, e.g. for HVM domain memory introspection or for isolation/access-control of memory between components within a single guest HVM domain. This option is deprecated, use the option "altp2m" instead.

Note: While the option "altp2mhvm" is deprecated, legacy applications for x86 systems will continue to work using it.

nestedhvm=BOOLEAN

Enable or disables guest access to hardware virtualisation features, e.g. it allows a guest Operating System to also function as a hypervisor. You may want this option if you want to run another hypervisor (including another copy of Xen) within a Xen guest or to support a guest Operating System which uses hardware virtualisation extensions (e.g. Windows XP compatibility mode on more modern Windows OS). This option is disabled by default.

cpuid="LIBXL_STRING" or cpuid=[ "XEND_STRING", "XEND_STRING" ]

Configure the value returned when a guest executes the CPUID instruction. Two versions of config syntax are recognized: libxl and xend.

Both formats use a common notation for specifying a single feature bit. Possible values are: '1' -> force the corresponding bit to 1 '0' -> force to 0 'x' -> Get a safe value (pass through and mask with the default policy) 'k' -> pass through the host bit value (at boot only - value preserved on migrate) 's' -> legacy alias for 'k'

Libxl format:

acpi_firmware="STRING"

Specifies a path to a file that contains extra ACPI firmware tables to pass into a guest. The file can contain several tables in their binary AML form concatenated together. Each table self describes its length so no additional information is needed. These tables will be added to the ACPI table set in the guest. Note that existing tables cannot be overridden by this feature. For example, this cannot be used to override tables like DSDT, FADT, etc.

smbios_firmware="STRING"

Specifies a path to a file that contains extra SMBIOS firmware structures to pass into a guest. The file can contain a set of DMTF predefined structures which will override the internal defaults. Not all predefined structures can be overridden, only the following types: 0, 1, 2, 3, 11, 22, 39. The file can also contain any number of vendor defined SMBIOS structures (type 128 - 255). Since SMBIOS structures do not present their overall size, each entry in the file must be preceded by a 32b integer indicating the size of the following structure.

ms_vm_genid="OPTION"

Provide a VM generation ID to the guest.

The VM generation ID is a 128-bit random number that a guest may use to determine if the guest has been restored from an earlier snapshot or cloned.

This is required for Microsoft Windows Server 2012 (and later) domain controllers.

Valid options are:

Guest Virtual Time Controls

tsc_mode="MODE"

(x86 only) Specifies how the TSC (Time Stamp Counter) should be provided to the guest. Specifying this option as a number is deprecated.

Options are:

localtime=BOOLEAN

Set the real time clock to local time or to UTC. False (0) by default, i.e. set to UTC.

rtc_timeoffset=SECONDS

Set the real time clock offset in seconds. No offset (0) by default.

vpt_align=BOOLEAN

Specifies that periodic Virtual Platform Timers should be aligned to reduce guest interrupts. Enabling this option can reduce power consumption, especially when a guest uses a high timer interrupt frequency (HZ) values. The default is true (1).

timer_mode="MODE"

Specifies the mode for Virtual Timers. The valid values are as follows:

Memory layout

mmio_hole=MBYTES

Specifies the size the MMIO hole below 4GiB will be. Only valid for device_model_version="qemu-xen".

Cannot be smaller than 256. Cannot be larger than 3840.

Known good large value is 3072.

Support for Paravirtualisation of HVM Guests

The following options allow Paravirtualised features (such as devices) to be exposed to the guest Operating System in an HVM guest. Utilising these features requires specific guest support but when available they will result in improved performance.

xen_platform_pci=BOOLEAN

Enable or disable the Xen platform PCI device. The presence of this virtual device enables a guest Operating System (subject to the availability of suitable drivers) to make use of paravirtualisation features such as disk and network devices etc. Enabling these drivers improves performance and is strongly recommended when available. PV drivers are available for various Operating Systems including HVM Linux (out-of-the-box) and Microsoft Windows <https://xenproject.org/windows-pv-drivers/>.

Setting xen_platform_pci=0 with the default device_model "qemu-xen" requires at least QEMU 1.6.

viridian=[ "GROUP", "GROUP", ...] or viridian=BOOLEAN

The groups of Microsoft Hyper-V (AKA viridian) compatible enlightenments exposed to the guest. The following groups of enlightenments may be specified:

Emulated VGA Graphics Device

The following options control the features of the emulated graphics device. Many of these options behave similarly to the equivalent key in the VFB_SPEC_STRING for configuring virtual frame buffer devices (see above).

videoram=MBYTES

Sets the amount of RAM which the emulated video card will contain, which in turn limits the resolutions and bit depths which will be available.

When using the qemu-xen-traditional device-model, the default as well as minimum amount of video RAM for stdvga is 8 MB, which is sufficient for e.g. 1600x1200 at 32bpp. For the upstream qemu-xen device-model, the default and minimum is 16 MB.

When using the emulated Cirrus graphics card (vga="cirrus") and the qemu-xen-traditional device-model, the amount of video RAM is fixed at 4 MB, which is sufficient for 1024x768 at 32 bpp. For the upstream qemu-xen device-model, the default and minimum is 8 MB.

For QXL vga, both the default and minimal are 128MB. If videoram is set less than 128MB, an error will be triggered.

stdvga=BOOLEAN

Specifies a standard VGA card with VBE (VESA BIOS Extensions) as the emulated graphics device. If your guest supports VBE 2.0 or later (e.g. Windows XP onwards) then you should enable this. stdvga supports more video ram and bigger resolutions than Cirrus. The default is false (0) which means to emulate a Cirrus Logic GD5446 VGA card. This option is deprecated, use vga="stdvga" instead.

vga="STRING"

Selects the emulated video card. Options are: none, stdvga, cirrus and qxl. The default is cirrus.

In general, QXL should work with the Spice remote display protocol for acceleration, and a QXL driver is necessary in the guest in that case. QXL can also work with the VNC protocol, but it will be like a standard VGA card without acceleration.

vnc=BOOLEAN

Allow access to the display via the VNC protocol. This enables the other VNC-related settings. The default is (1) enabled.

vnclisten="ADDRESS[:DISPLAYNUM]"

Specifies the IP address and, optionally, the VNC display number to use.

vncdisplay=DISPLAYNUM

Specifies the VNC display number to use. The actual TCP port number will be DISPLAYNUM+5900.

vncunused=BOOLEAN

Requests that the VNC display setup searches for a free TCP port to use. The actual display used can be accessed with xl vncviewer.

vncpasswd="PASSWORD"

Specifies the password for the VNC server. If the password is set to an empty string, authentication on the VNC server will be disabled allowing any user to connect.

keymap="LANG"

Configure the keymap to use for the keyboard associated with this display. If the input method does not easily support raw keycodes (e.g. this is often the case when using VNC) then this allows us to correctly map the input keys into keycodes seen by the guest. The specific values which are accepted are defined by the version of the device-model which you are using. See Keymaps below or consult the qemu(1) manpage. The default is en-us.

sdl=BOOLEAN

Specifies that the display should be presented via an X window (using Simple DirectMedia Layer). The default is (0) not enabled.

opengl=BOOLEAN

Enable OpenGL acceleration of the SDL display. Only effects machines using device_model_version="qemu-xen-traditional" and only if the device-model was compiled with OpenGL support. Default is (0) false.

nographic=BOOLEAN

Enable or disable the virtual graphics device. The default is to provide a VGA graphics device but this option can be used to disable it.

Spice Graphics Support

The following options control the features of SPICE.

spice=BOOLEAN

Allow access to the display via the SPICE protocol. This enables the other SPICE-related settings.

spicehost="ADDRESS"

Specifies the interface address to listen on if given, otherwise any interface.

spiceport=NUMBER

Specifies the port to listen on by the SPICE server if SPICE is enabled.

spicetls_port=NUMBER

Specifies the secure port to listen on by the SPICE server if SPICE is enabled. At least one of spiceport or spicetls_port must be given if SPICE is enabled.

Note: the options depending on spicetls_port have not been supported.

spicedisable_ticketing=BOOLEAN

Enable clients to connect without specifying a password. When disabled, spicepasswd must be set. The default is (0) false.

spicepasswd="PASSWORD"

Specify the password which is used by clients for establishing a connection.

spiceagent_mouse=BOOLEAN

Whether SPICE agent is used for client mouse mode. The default is (1) true.

spicevdagent=BOOLEAN

Enables the SPICE vdagent. The SPICE vdagent is an optional component for enhancing user experience and performing guest-oriented management tasks. Its features include: client mouse mode (no need to grab the mouse by the client, no mouse lag), automatic adjustment of screen resolution, copy and paste (text and image) between the client and the guest. It also requires the vdagent service installed on the guest OS to work. The default is (0) disabled.

spice_clipboard_sharing=BOOLEAN

Enables SPICE clipboard sharing (copy/paste). It requires that spicevdagent is enabled. The default is (0) false.

spiceusbredirection=NUMBER

Enables SPICE USB redirection. Creates a NUMBER of USB redirection channels for redirecting up to 4 USB devices from the SPICE client to the guest's QEMU. It requires an USB controller and, if not defined, it will automatically add an USB2.0 controller. The default is (0) disabled.

spice_image_compression="COMPRESSION"

Specifies what image compression is to be used by SPICE (if given), otherwise the QEMU default will be used. Please see the documentation of your QEMU version for more details.

Available options are: auto_glz, auto_lz, quic, glz, lz, off.

spice_streaming_video="VIDEO"

Specifies what streaming video setting is to be used by SPICE (if given), otherwise the QEMU default will be used.

Available options are: filter, all, off.

Miscellaneous Emulated Hardware

serial=[ "DEVICE", "DEVICE", ...]

Redirect virtual serial ports to DEVICEs. Please see the -serial option in the qemu(1) manpage for details of the valid DEVICE options. Default is vc when in graphical mode and stdio if nographic=1 is used.

The form serial=DEVICE is also accepted for backwards compatibility.

soundhw="DEVICE"

Select the virtual sound card to expose to the guest. The valid devices are defined by the device model configuration, please see the qemu(1) manpage for details. The default is not to export any sound device.

vkb_device=BOOLEAN

Specifies that the HVM guest gets a vkdb. The default is true (1).

usb=BOOLEAN

Enables or disables an emulated USB bus in the guest.

usbversion=NUMBER

Specifies the type of an emulated USB bus in the guest, values 1 for USB1.1, 2 for USB2.0 and 3 for USB3.0. It is available only with an upstream QEMU. Due to implementation limitations this is not compatible with the usb and usbdevice parameters. Default is (0) no USB controller defined.

usbdevice=[ "DEVICE", "DEVICE", ...]

Adds DEVICEs to the emulated USB bus. The USB bus must also be enabled using usb=1. The most common use for this option is usbdevice=['tablet'] which adds a pointer device using absolute coordinates. Such devices function better than relative coordinate devices (such as a standard mouse) since many methods of exporting guest graphics (such as VNC) work better in this mode. Note that this is independent of the actual pointer device you are using on the host/client side.

Host devices can also be passed through in this way, by specifying host:USBID, where USBID is of the form xxxx:yyyy. The USBID can typically be found by using lsusb(1) or usb-devices(1).

If you wish to use the "host:bus.addr" format, remove any leading '0' from the bus and addr. For example, for the USB device on bus 008 dev 002, you should write "host:8.2".

The form usbdevice=DEVICE is also accepted for backwards compatibility.

More valid options can be found in the "usbdevice" section of the QEMU documentation.

vendor_device="VENDOR_DEVICE"

Selects which variant of the QEMU xen-pvdevice should be used for this guest. Valid values are:

PVH Guest Specific Options

nestedhvm=BOOLEAN

Enable or disables guest access to hardware virtualisation features, e.g. it allows a guest Operating System to also function as a hypervisor. You may want this option if you want to run another hypervisor (including another copy of Xen) within a Xen guest or to support a guest Operating System which uses hardware virtualisation extensions (e.g. Windows XP compatibility mode on more modern Windows OS).

This option is disabled by default.

bootloader="PROGRAM"

Run "PROGRAM" to find the kernel image and ramdisk to use. Normally "PROGRAM" would be "pygrub", which is an emulation of grub/grub2/syslinux. Either kernel or bootloader must be specified for PV guests.

bootloader_args=[ "ARG", "ARG", ...]

Append ARGs to the arguments to the bootloader program. Alternatively if the argument is a simple string then it will be split into words at whitespace (this second option is deprecated).

timer_mode="MODE"

Specifies the mode for Virtual Timers. The valid values are as follows:

Paging

The following options control the mechanisms used to virtualise guest memory. The defaults are selected to give the best results for the common cases so you should normally leave these options unspecified.

hap=BOOLEAN

Turns "hardware assisted paging" (the use of the hardware nested page table feature) on or off. This feature is called EPT (Extended Page Tables) by Intel and NPT (Nested Page Tables) or RVI (Rapid Virtualisation Indexing) by AMD. If turned off, Xen will run the guest in "shadow page table" mode where the guest's page table updates and/or TLB flushes etc. will be emulated. Use of HAP is the default when available.

oos=BOOLEAN

Turns "out of sync pagetables" on or off. When running in shadow page table mode, the guest's page table updates may be deferred as specified in the Intel/AMD architecture manuals. However, this may expose unexpected bugs in the guest, or find bugs in Xen, so it is possible to disable this feature. Use of out of sync page tables, when Xen thinks it appropriate, is the default.

shadow_memory=MBYTES

Number of megabytes to set aside for shadowing guest pagetable pages (effectively acting as a cache of translated pages) or to use for HAP state. By default this is 1MB per guest vCPU plus 8KB per MB of guest RAM. You should not normally need to adjust this value. However, if you are not using hardware assisted paging (i.e. you are using shadow mode) and your guest workload consists of a very large number of similar processes then increasing this value may improve performance.

Device-Model Options

device_model_version="DEVICE-MODEL"

Selects which variant of the device-model should be used for this guest.

Valid values are:

device_model_override="PATH"

Override the path to the binary to be used as the device-model running in toolstack domain. The binary provided here MUST be consistent with the device_model_version which you have specified. You should not normally need to specify this option.

stubdomain_kernel="PATH"

Override the path to the kernel image used as device-model stubdomain. The binary provided here MUST be consistent with the device_model_version which you have specified. In case of qemu-xen-traditional it is expected to be MiniOS-based stubdomain image, in case of qemu-xen it is expected to be Linux-based stubdomain kernel.

stubdomain_cmdline="STRING"

Set the device-model stubdomain kernel command line to STRING.

stubdomain_ramdisk="PATH"

Override the path to the ramdisk image used as device-model stubdomain. The binary provided here is to be used by a kernel pointed by stubdomain_kernel. It is known to be used only by Linux-based stubdomain kernel.

stubdomain_memory=MBYTES

Start the stubdomain with MBYTES megabytes of RAM. Default is 128.

device_model_stubdomain_override=BOOLEAN

Override the use of stubdomain based device-model. Normally this will be automatically selected based upon the other features and options you have selected.

device_model_stubdomain_seclabel="LABEL"

Assign an XSM security label to the device-model stubdomain.

device_model_args=[ "ARG", "ARG", ...]

Pass additional arbitrary options on the device-model command line. Each element in the list is passed as an option to the device-model.

device_model_args_pv=[ "ARG", "ARG", ...]

Pass additional arbitrary options on the device-model command line for a PV device model only. Each element in the list is passed as an option to the device-model.

device_model_args_hvm=[ "ARG", "ARG", ...]

Pass additional arbitrary options on the device-model command line for an HVM device model only. Each element in the list is passed as an option to the device-model.

Keymaps

        ar  de-ch  es  fo     fr-ca  hu  ja  mk     no  pt-br  sv
        da  en-gb  et  fr     fr-ch  is  lt  nl     pl  ru     th
        de  en-us  fi  fr-be  hr     it  lv  nl-be  pt  sl     tr

The default is en-us.

See qemu(1) for more information.

Architecture Specific options

gic_version="vN"

Version of the GIC emulated for the guest.

Currently, the following versions are supported:

vuart="uart"

To enable vuart console, user must specify the following option in the VM config file:

vuart = "sbsa_uart"

Currently, only the "sbsa_uart" model is supported for ARM.

x86

mca_caps=[ "CAP", "CAP", ... ]

(HVM only) Enable MCA capabilities besides default ones enabled by Xen hypervisor for the HVM domain. "CAP" can be one in the following list:

msr_relaxed=BOOLEAN

The "msr_relaxed" boolean is an interim option, and defaults to false.

In Xen 4.15, the default behaviour for unhandled MSRs has been changed, to avoid leaking host data into guests, and to avoid breaking guest logic which uses #GP probing to identify the availability of MSRs.

However, this new stricter behaviour has the possibility to break guests, and a more 4.14-like behaviour can be selected by setting this option.

If using this option is necessary to fix an issue, please report a bug.