1xl.cfg(5) Xen xl.cfg(5)
2
6 xl.cfg - xl domain configuration file syntax
7
9 /etc/xen/xldomain
10
12 Creating a VM (a domain in Xen terminology, sometimes called a guest)
13 with xl requires the provision of a domain configuration file.
14 Typically, these live in /etc/xen/DOMAIN.cfg, where DOMAIN is the name
15 of the domain.
16
18 A domain configuration file consists of a series of options, specified
19 by using "KEY=VALUE" pairs.
20 Some "KEY"s are mandatory, some are general options which apply to any
22 guest type, while others relate only to specific guest types (e.g. PV
23 or HVM guests).
24 A "VALUE" can be one of:
26 "STRING"
28 A string, surrounded by either single or double quotes. But if the
29 STRING is part of a SPEC_STRING, the quotes should be omitted.
30 NUMBER
32 A number, in either decimal, octal (using a 0 prefix) or
33 hexadecimal (using a "0x" prefix) format.
34 BOOLEAN
36 A "NUMBER" interpreted as "False" (0) or "True" (any other value).
37 [ VALUE, VALUE, ... ]
39 A list of "VALUE"s of the above types. Lists can be heterogeneous
40 and nested.
41 The semantics of each "KEY" defines which type of "VALUE" is required.
43 Pairs may be separated either by a newline or a semicolon. Both of the
45 following are valid:
46 name="h0"
48 type="hvm"
49 name="h0"; type="hvm"
51
53 Mandatory Configuration Items
54 The following key is mandatory for any guest type.
55 name="NAME"
57 Specifies the name of the domain. Names of domains existing on a
58 single host must be unique.
59 Selecting Guest Type
61 type="pv"
62 Specifies that this is to be a PV domain, suitable for hosting Xen-
63 aware guest operating systems. This is the default on x86.
64 type="pvh"
66 Specifies that this is to be an PVH domain. That is a lightweight
67 HVM-like guest without a device model and without many of the
68 emulated devices available to HVM guests. Note that this mode
69 requires a PVH aware kernel on x86. This is the default on Arm.
70 type="hvm"
72 Specifies that this is to be an HVM domain. That is, a fully
73 virtualised computer with emulated BIOS, disk and network
74 peripherals, etc.
75 Deprecated guest type selection
77 Note that the builder option is being deprecated in favor of the type
79 option.
80 builder="generic"
82 Specifies that this is to be a PV domain, suitable for hosting Xen-
83 aware guest operating systems. This is the default.
84 builder="hvm"
86 Specifies that this is to be an HVM domain. That is, a fully
87 virtualised computer with emulated BIOS, disk and network
88 peripherals, etc.
89 General Options
91 The following options apply to guests of any type.
92 CPU Allocation
94 pool="CPUPOOLNAME"
96 Put the guest's vCPUs into the named CPU pool.
97 vcpus=N
99 Start the guest with N vCPUs initially online.
100 maxvcpus=M
102 Allow the guest to bring up a maximum of M vCPUs. When starting the
103 guest, if vcpus=N is less than maxvcpus=M then the first N vCPUs
104 will be created online and the remainder will be created offline.
105 cpus="CPULIST"
107 List of host CPUs the guest is allowed to use. Default is no
108 pinning at all (more on this below). A "CPULIST" may be specified
109 as follows:
110 "all"
112 To allow all the vCPUs of the guest to run on all the CPUs on
113 the host.
114 "0-3,5,^1"
116 To allow all the vCPUs of the guest to run on CPUs 0,2,3,5. It
117 is possible to combine this with "all", meaning "all,^7"
118 results in all the vCPUs of the guest being allowed to run on
119 all the CPUs of the host except CPU 7.
120 "nodes:0-3,^node:2"
122 To allow all the vCPUs of the guest to run on the CPUs from
123 NUMA nodes 0,1,3 of the host. So, if CPUs 0-3 belong to node 0,
124 CPUs 4-7 belong to node 1, CPUs 8-11 to node 2 and CPUs 12-15
125 to node 3, the above would mean all the vCPUs of the guest
126 would be allowed to run on CPUs 0-7,12-15.
127 Combining this notation with the one above is possible. For
129 instance, "1,node:1,^6", means all the vCPUs of the guest will
130 run on CPU 1 and on all the CPUs of NUMA node 1, but not on CPU
131 6. Following the same example as above, that would be CPUs
132 1,4,5,7.
133 Combining this with "all" is also possible, meaning
135 "all,^node:1" results in all the vCPUs of the guest running on
136 all the CPUs on the host, except for the CPUs belonging to the
137 host NUMA node 1.
138 ["2", "3-8,^5"]
140 To ask for specific vCPU mapping. That means (in this example),
141 vCPU 0 of the guest will run on CPU 2 of the host and vCPU 1 of
142 the guest will run on CPUs 3,4,6,7,8 of the host (excluding CPU
143 5).
144 More complex notation can be also used, exactly as described
146 above. So "all,^5-8", or just "all", or
147 "node:0,node:2,^9-11,18-20" are all legal, for each element of
148 the list.
149 If this option is not specified, no vCPU to CPU pinning is
151 established, and the vCPUs of the guest can run on all the CPUs of
152 the host. If this option is specified, the intersection of the vCPU
153 pinning mask, provided here, and the soft affinity mask, if
154 provided via cpus_soft=, is utilized to compute the domain node-
155 affinity for driving memory allocations.
156 cpus_soft="CPULIST"
158 Exactly as cpus=, but specifies soft affinity, rather than pinning
159 (hard affinity). When using the credit scheduler, this means what
160 CPUs the vCPUs of the domain prefer.
161 A "CPULIST" is specified exactly as for cpus=, detailed earlier in
163 the manual.
164 If this option is not specified, the vCPUs of the guest will not
166 have any preference regarding host CPUs. If this option is
167 specified, the intersection of the soft affinity mask, provided
168 here, and the vCPU pinning, if provided via cpus=, is utilized to
169 compute the domain node-affinity for driving memory allocations.
170 If this option is not specified (and cpus= is not specified
172 either), libxl automatically tries to place the guest on the least
173 possible number of nodes. A heuristic approach is used for choosing
174 the best node (or set of nodes), with the goal of maximizing
175 performance for the guest and, at the same time, achieving
176 efficient utilization of host CPUs and memory. In that case, the
177 soft affinity of all the vCPUs of the domain will be set to host
178 CPUs belonging to NUMA nodes chosen during placement.
179 For more details, see xl-numa-placement(7).
181 CPU Scheduling
183 cpu_weight=WEIGHT
185 A domain with a weight of 512 will get twice as much CPU as a
186 domain with a weight of 256 on a contended host. Legal weights
187 range from 1 to 65535 and the default is 256. Honoured by the
188 credit and credit2 schedulers.
189 cap=N
191 The cap optionally fixes the maximum amount of CPU a domain will be
192 able to consume, even if the host system has idle CPU cycles. The
193 cap is expressed as a percentage of one physical CPU: 100 is 1
194 physical CPU, 50 is half a CPU, 400 is 4 CPUs, etc. The default,
195 0, means there is no cap. Honoured by the credit and credit2
196 schedulers.
197 NOTE: Many systems have features that will scale down the computing
199 power of a CPU that is not 100% utilized. This can be done in the
200 operating system, but can also sometimes be done below the
201 operating system, in the BIOS. If you set a cap such that
202 individual cores are running at less than 100%, this may have an
203 impact on the performance of your workload over and above the
204 impact of the cap. For example, if your processor runs at 2GHz, and
205 you cap a VM at 50%, the power management system may also reduce
206 the clock speed to 1GHz; the effect will be that your VM gets 25%
207 of the available power (50% of 1GHz) rather than 50% (50% of 2GHz).
208 If you are not getting the performance you expect, look at
209 performance and CPU frequency options in your operating system and
210 your BIOS.
211 Memory Allocation
213 memory=MBYTES
215 Start the guest with MBYTES megabytes of RAM.
216 maxmem=MBYTES
218 Specifies the maximum amount of memory a guest can ever see. The
219 value of maxmem= must be equal to or greater than that of memory=.
220 In combination with memory= it will start the guest "pre-
222 ballooned", if the values of memory= and maxmem= differ. A "pre-
223 ballooned" HVM guest needs a balloon driver, without a balloon
224 driver it will crash.
225 NOTE: Because of the way ballooning works, the guest has to
227 allocate memory to keep track of maxmem pages, regardless of how
228 much memory it actually has available to it. A guest with
229 maxmem=262144 and memory=8096 will report significantly less memory
230 available for use than a system with maxmem=8096 memory=8096 due to
231 the memory overhead of having to track the unused pages.
232 Guest Virtual NUMA Configuration
234 vnuma=[ VNODE_SPEC, VNODE_SPEC, ... ]
236 Specify virtual NUMA configuration with positional arguments. The
237 nth VNODE_SPEC in the list specifies the configuration of the nth
238 virtual node.
239 Note that virtual NUMA is not supported for PV guests yet, because
241 there is an issue with the CPUID instruction handling that affects
242 PV virtual NUMA. Furthermore, guests with virtual NUMA cannot be
243 saved or migrated because the migration stream does not preserve
244 node information.
245 Each VNODE_SPEC is a list, which has a form of
247 "[VNODE_CONFIG_OPTION, VNODE_CONFIG_OPTION, ... ]" (without the
248 quotes).
249 For example, vnuma = [
251 ["pnode=0","size=512","vcpus=0-4","vdistances=10,20"] ] means vnode
252 0 is mapped to pnode 0, has 512MB ram, has vcpus 0 to 4, the
253 distance to itself is 10 and the distance to vnode 1 is 20.
254 Each VNODE_CONFIG_OPTION is a quoted "KEY=VALUE" pair. Supported
256 VNODE_CONFIG_OPTIONs are (they are all mandatory at the moment):
257 pnode=NUMBER
259 Specifies which physical node this virtual node maps to.
260 size=MBYTES
262 Specifies the size of this virtual node. The sum of memory
263 sizes of all vnodes will become maxmem=. If maxmem= is
264 specified separately, a check is performed to make sure the sum
265 of all vnode memory matches maxmem=.
266 vcpus="CPUSTRING"
268 Specifies which vCPUs belong to this node. "CPUSTRING" is a
269 string of numerical values separated by a comma. You can
270 specify a range and/or a single CPU. An example would be
271 "vcpus=0-5,8", which means you specified vCPU 0 to vCPU 5, and
272 vCPU 8.
273 vdistances=NUMBER, NUMBER, ...
275 Specifies the virtual distance from this node to all nodes
276 (including itself) with positional arguments. For example,
277 "vdistance=10,20" for vnode 0 means the distance from vnode 0
278 to vnode 0 is 10, from vnode 0 to vnode 1 is 20. The number of
279 arguments supplied must match the total number of vnodes.
280 Normally you can use the values from xl info -n or numactl
282 --hardware to fill the vdistances list.
283 Event Actions
285 on_poweroff="ACTION"
287 Specifies what should be done with the domain if it shuts itself
288 down. The ACTIONs are:
289 destroy
291 destroy the domain
292 restart
294 destroy the domain and immediately create a new domain with the
295 same configuration
296 rename-restart
298 rename the domain which terminated, and then immediately create
299 a new domain with the same configuration as the original
300 preserve
302 keep the domain. It can be examined, and later destroyed with
303 xl destroy.
304 coredump-destroy
306 write a "coredump" of the domain to /var/lib/xen/dump/NAME and
307 then destroy the domain.
308 coredump-restart
310 write a "coredump" of the domain to /var/lib/xen/dump/NAME and
311 then restart the domain.
312 soft-reset
314 Reset all Xen specific interfaces for the Xen-aware HVM domain
315 allowing it to reestablish these interfaces and continue
316 executing the domain. PV and non-Xen-aware HVM guests are not
317 supported.
318 The default for on_poweroff is destroy.
320 on_reboot="ACTION"
322 Action to take if the domain shuts down with a reason code
323 requesting a reboot. Default is restart.
324 on_watchdog="ACTION"
326 Action to take if the domain shuts down due to a Xen watchdog
327 timeout. Default is destroy.
328 on_crash="ACTION"
330 Action to take if the domain crashes. Default is destroy.
331 on_soft_reset="ACTION"
333 Action to take if the domain performs a 'soft reset' (e.g. does
334 kexec). Default is soft-reset.
335 Direct Kernel Boot
337 Direct kernel boot allows booting guests with a kernel and an initrd
339 stored on a filesystem available to the host physical machine, allowing
340 command line arguments to be passed directly. PV guest direct kernel
341 boot is supported. HVM guest direct kernel boot is supported with some
342 limitations (it's supported when using qemu-xen and the default BIOS
343 'seabios', but not supported in case of using stubdom-dm and the old
344 'rombios'.)
345 kernel="PATHNAME"
347 Load the specified file as the kernel image.
348 ramdisk="PATHNAME"
350 Load the specified file as the ramdisk.
351 cmdline="STRING"
353 Append STRING to the kernel command line. (Note: the meaning of
354 this is guest specific). It can replace root="STRING" along with
355 extra="STRING" and is preferred. When cmdline="STRING" is set,
356 root="STRING" and extra="STRING" will be ignored.
357 root="STRING"
359 Append root=STRING to the kernel command line (Note: the meaning of
360 this is guest specific).
361 extra="STRING"
363 Append STRING to the kernel command line. (Note: the meaning of
364 this is guest specific).
365 Non direct Kernel Boot
367 Non direct kernel boot allows booting guests with a firmware. This can
369 be used by all types of guests, although the selection of options is
370 different depending on the guest type.
371 This option provides the flexibly of letting the guest decide which
373 kernel they want to boot, while preventing having to poke at the guest
374 file system form the toolstack domain.
375 PV guest options
377 firmware="pvgrub32|pvgrub64"
379 Boots a guest using a para-virtualized version of grub that runs
380 inside of the guest. The bitness of the guest needs to be know, so
381 that the right version of pvgrub can be selected.
382 Note that xl expects to find the pvgrub32.bin and pvgrub64.bin
384 binaries in /usr/libexec/xen/boot.
385 HVM guest options
387 firmware="bios"
389 Boot the guest using the default BIOS firmware, which depends on
390 the chosen device model.
391 firmware="uefi"
393 Boot the guest using the default UEFI firmware, currently OVMF.
394 firmware="seabios"
396 Boot the guest using the SeaBIOS BIOS firmware.
397 firmware="rombios"
399 Boot the guest using the ROMBIOS BIOS firmware.
400 firmware="ovmf"
402 Boot the guest using the OVMF UEFI firmware.
403 firmware="PATH"
405 Load the specified file as firmware for the guest.
406 PVH guest options
408 Currently there's no firmware available for PVH guests, they should be
410 booted using the Direct Kernel Boot method or the bootloader option.
411 pvshim=BOOLEAN
413 Whether to boot this guest as a PV guest within a PVH container.
414 Ie, the guest will experience a PV environment, but processor
415 hardware extensions are used to separate its address space to
416 mitigate the Meltdown attack (CVE-2017-5754).
417 Default is false.
419 pvshim_path="PATH"
421 The PV shim is a specially-built firmware-like executable
422 constructed from the hypervisor source tree. This option specifies
423 to use a non-default shim. Ignored if pvhsim is false.
424 pvshim_cmdline="STRING"
426 Command line for the shim. Default is "pv-shim console=xen,pv".
427 Ignored if pvhsim is false.
428 pvshim_extra="STRING"
430 Extra command line arguments for the shim. If supplied, appended
431 to the value for pvshim_cmdline. Default is empty. Ignored if
432 pvhsim is false.
433 Other Options
435 uuid="UUID"
437 Specifies the UUID of the domain. If not specified, a fresh unique
438 UUID will be generated.
439 seclabel="LABEL"
441 Assign an XSM security label to this domain.
442 init_seclabel="LABEL"
444 Specify an XSM security label used for this domain temporarily
445 during its build. The domain's XSM label will be changed to the
446 execution seclabel (specified by seclabel) once the build is
447 complete, prior to unpausing the domain. With a properly
448 constructed security policy (such as nomigrate_t in the example
449 policy), this can be used to build a domain whose memory is not
450 accessible to the toolstack domain.
451 max_grant_frames=NUMBER
453 Specify the maximum number of grant frames the domain is allowed to
454 have. This value controls how many pages the domain is able to
455 grant access to for other domains, needed e.g. for the operation of
456 paravirtualized devices. The default is settable via xl.conf(5).
457 max_maptrack_frames=NUMBER
459 Specify the maximum number of grant maptrack frames the domain is
460 allowed to have. This value controls how many pages of foreign
461 domains can be accessed via the grant mechanism by this domain. The
462 default value is settable via xl.conf(5).
463 max_grant_version=NUMBER
465 Specify the maximum grant table version the domain is allowed to
466 use. The default value is settable via xl.conf(5).
467 nomigrate=BOOLEAN
469 Disable migration of this domain. This enables certain other
470 features which are incompatible with migration. Currently this is
471 limited to enabling the invariant TSC feature flag in CPUID results
472 when TSC is not emulated.
473 driver_domain=BOOLEAN
475 Specify that this domain is a driver domain. This enables certain
476 features needed in order to run a driver domain.
477 device_tree=PATH
479 Specify a partial device tree (compiled via the Device Tree
480 Compiler). Everything under the node "/passthrough" will be copied
481 into the guest device tree. For convenience, the node "/aliases" is
482 also copied to allow the user to define aliases which can be used
483 by the guest kernel.
484 Given the complexity of verifying the validity of a device tree,
486 this option should only be used with a trusted device tree.
487 Note that the partial device tree should avoid using the phandle
489 65000 which is reserved by the toolstack.
490 passthrough="STRING"
492 Specify whether IOMMU mappings are enabled for the domain and hence
493 whether it will be enabled for passthrough hardware. Valid values
494 for this option are:
495 disabled
497 IOMMU mappings are disabled for the domain and so hardware may
498 not be passed through.
499 This option is the default if no passthrough hardware is
501 specified in the domain's configuration.
502 enabled
504 This option enables IOMMU mappings and selects an appropriate
505 default operating mode (see below for details of the operating
506 modes). For HVM/PVH domains running on platforms where the
507 option is available, this is equivalent to share_pt. Otherwise,
508 and also for PV domains, this option is equivalent to sync_pt.
509 This option is the default if passthrough hardware is specified
511 in the domain's configuration.
512 sync_pt
514 This option means that IOMMU mappings will be synchronized with
515 the domain's P2M table as follows:
516 For a PV domain, all writable pages assigned to the domain are
518 identity mapped by MFN in the IOMMU page table. Thus a device
519 driver running in the domain may program passthrough hardware
520 for DMA using MFN values (i.e. host/machine frame numbers)
521 looked up in its P2M.
522 For an HVM/PVH domain, all non-foreign RAM pages present in its
524 P2M will be mapped by GFN in the IOMMU page table. Thus a
525 device driver running in the domain may program passthrough
526 hardware using GFN values (i.e. guest physical frame numbers)
527 without any further translation.
528 This option is not currently available on Arm.
530 share_pt
532 This option is unavailable for a PV domain. For an HVM/PVH
533 domain, this option means that the IOMMU will be programmed to
534 directly reference the domain's P2M table as its page table.
535 From the point of view of a device driver running in the domain
536 this is functionally equivalent to sync_pt but places less load
537 on the hypervisor and so should generally be selected in
538 preference. However, the availability of this option is
539 hardware specific. If xl info reports virt_caps containing
540 iommu_hap_pt_share then this option may be used.
541 default
543 The default, which chooses between disabled and enabled
544 according to whether passthrough devices are enabled in the
545 config file.
546 xend_suspend_evtchn_compat=BOOLEAN
548 If this option is true the xenstore path for the domain's suspend
549 event channel will not be created. Instead the old xend behaviour
550 of making the whole xenstore device sub-tree writable by the domain
551 will be re-instated.
552 The existence of the suspend event channel path can cause problems
554 with certain PV drivers running in the guest (e.g. old Red Hat PV
555 drivers for Windows).
556 If this option is not specified then it will default to false.
558 vmtrace_buf_kb=KBYTES
560 Specifies the size of vmtrace buffer that would be allocated for
561 each vCPU belonging to this domain. Disabled (i.e.
562 vmtrace_buf_kb=0) by default.
563 NOTE: Acceptable values are platform specific. For Intel Processor
565 Trace, this value must be a power of 2 between 4k and 16M.
566 vpmu=BOOLEAN
568 Currently ARM only.
569 Specifies whether to enable the access to PMU registers by
571 disabling the PMU traps.
572 The PMU registers are not virtualized and the physical registers
574 are directly accessible when this parameter is enabled. There is no
575 interrupt support and Xen will not save/restore the register values
576 on context switches.
577 vPMU, by design and purpose, exposes system level performance
579 information to the guest. Only to be used by sufficiently
580 privileged domains. This feature is currently in experimental
581 state.
582 If this option is not specified then it will default to false.
584 Devices
586 The following options define the paravirtual, emulated and physical
587 devices which the guest will contain.
588 disk=[ "DISK_SPEC_STRING", "DISK_SPEC_STRING", ...]
590 Specifies the disks (both emulated disks and Xen virtual block
591 devices) which are to be provided to the guest, and what objects on
592 the host they should map to. See xl-disk-configuration(5) for more
593 details.
594 vif=[ "NET_SPEC_STRING", "NET_SPEC_STRING", ...]
596 Specifies the network interfaces (both emulated network adapters,
597 and Xen virtual interfaces) which are to be provided to the guest.
598 See xl-network-configuration(5) for more details.
599 vtpm=[ "VTPM_SPEC_STRING", "VTPM_SPEC_STRING", ...]
601 Specifies the Virtual Trusted Platform module to be provided to the
602 guest. See xen-vtpm(7) for more details.
603 Each VTPM_SPEC_STRING is a comma-separated list of "KEY=VALUE"
605 settings from the following list:
606 backend=domain-id
608 Specifies the backend domain name or id. This value is
609 required! If this domain is a guest, the backend should be set
610 to the vTPM domain name. If this domain is a vTPM, the backend
611 should be set to the vTPM manager domain name.
612 uuid=UUID
614 Specifies the UUID of this vTPM device. The UUID is used to
615 uniquely identify the vTPM device. You can create one using the
616 uuidgen(1) program on unix systems. If left unspecified, a new
617 UUID will be randomly generated every time the domain boots.
618 If this is a vTPM domain, you should specify a value. The value
619 is optional if this is a guest domain.
620 p9=[ "9PFS_SPEC_STRING", "9PFS_SPEC_STRING", ...]
622 Creates a Xen 9pfs connection to share a filesystem from the
623 backend to the frontend.
624 Each 9PFS_SPEC_STRING is a comma-separated list of "KEY=VALUE"
626 settings, from the following list:
627 tag=STRING
629 9pfs tag to identify the filesystem share. The tag is needed on
630 the guest side to mount it.
631 security_model="none"
633 Only "none" is supported today, which means that the files are
634 stored using the same credentials as those they have in the
635 guest (no user ownership squash or remap).
636 path=STRING
638 Filesystem path on the backend to export.
639 backend=domain-id
641 Specify the backend domain name or id, defaults to dom0.
642 pvcalls=[ "backend=domain-id", ... ]
644 Creates a Xen pvcalls connection to handle pvcalls requests from
645 frontend to backend. It can be used as an alternative networking
646 model. For more information about the protocol, see
647 https://xenbits.xenproject.org/docs/unstable/misc/pvcalls.html.
648 vfb=[ "VFB_SPEC_STRING", "VFB_SPEC_STRING", ...]
650 Specifies the paravirtual framebuffer devices which should be
651 supplied to the domain.
652 This option does not control the emulated graphics card presented
654 to an HVM guest. See Emulated VGA Graphics Device below for how to
655 configure the emulated device. If Emulated VGA Graphics Device
656 options are used in a PV guest configuration, xl will pick up vnc,
657 vnclisten, vncpasswd, vncdisplay, vncunused, sdl, opengl and keymap
658 to construct the paravirtual framebuffer device for the guest.
659 Each VFB_SPEC_STRING is a comma-separated list of "KEY=VALUE"
661 settings, from the following list:
662 vnc=BOOLEAN
664 Allow access to the display via the VNC protocol. This enables
665 the other VNC-related settings. Default is 1 (enabled).
666 vnclisten=ADDRESS[:DISPLAYNUM]
668 Specifies the IP address, and optionally the VNC display
669 number, to use.
670 Note: if you specify the display number here, you should not
672 use the vncdisplay option.
673 vncdisplay=DISPLAYNUM
675 Specifies the VNC display number to use. The actual TCP port
676 number will be DISPLAYNUM+5900.
677 Note: you should not use this option if you set the DISPLAYNUM
679 in the vnclisten option.
680 vncunused=BOOLEAN
682 Requests that the VNC display setup searches for a free TCP
683 port to use. The actual display used can be accessed with xl
684 vncviewer.
685 vncpasswd=PASSWORD
687 Specifies the password for the VNC server. If the password is
688 set to an empty string, authentication on the VNC server will
689 be disabled, allowing any user to connect.
690 sdl=BOOLEAN
692 Specifies that the display should be presented via an X window
693 (using Simple DirectMedia Layer). The default is 0 (not
694 enabled).
695 display=DISPLAY
697 Specifies the X Window display that should be used when the sdl
698 option is used.
699 xauthority=XAUTHORITY
701 Specifies the path to the X authority file that should be used
702 to connect to the X server when the sdl option is used.
703 opengl=BOOLEAN
705 Enable OpenGL acceleration of the SDL display. Only effects
706 machines using device_model_version="qemu-xen-traditional" and
707 only if the device-model was compiled with OpenGL support. The
708 default is 0 (disabled).
709 keymap=LANG
711 Configure the keymap to use for the keyboard associated with
712 this display. If the input method does not easily support raw
713 keycodes (e.g. this is often the case when using VNC) then this
714 allows us to correctly map the input keys into keycodes seen by
715 the guest. The specific values which are accepted are defined
716 by the version of the device-model which you are using. See
717 Keymaps below or consult the qemu(1) manpage. The default is
718 en-us.
719 channel=[ "CHANNEL_SPEC_STRING", "CHANNEL_SPEC_STRING", ...]
721 Specifies the virtual channels to be provided to the guest. A
722 channel is a low-bandwidth, bidirectional byte stream, which
723 resembles a serial link. Typical uses for channels include
724 transmitting VM configuration after boot and signalling to in-guest
725 agents. Please see xen-pv-channel(7) for more details.
726 Each CHANNEL_SPEC_STRING is a comma-separated list of "KEY=VALUE"
728 settings. Leading and trailing whitespace is ignored in both KEY
729 and VALUE. Neither KEY nor VALUE may contain ',', '=' or '"'.
730 Defined values are:
731 backend=domain-id
733 Specifies the backend domain name or id. This parameter is
734 optional. If this parameter is omitted then the toolstack
735 domain will be assumed.
736 name=NAME
738 Specifies the name for this device. This parameter is
739 mandatory! This should be a well-known name for a specific
740 application (e.g. guest agent) and should be used by the
741 frontend to connect the application to the right channel
742 device. There is no formal registry of channel names, so
743 application authors are encouraged to make their names unique
744 by including the domain name and a version number in the string
745 (e.g. org.mydomain.guestagent.1).
746 connection=CONNECTION
748 Specifies how the backend will be implemented. The following
749 options are available:
750 SOCKET
752 The backend will bind a Unix domain socket (at the path
753 given by path=PATH), listen for and accept connections. The
754 backend will proxy data between the channel and the
755 connected socket.
756 PTY The backend will create a pty and proxy data between the
758 channel and the master device. The command xl channel-list
759 can be used to discover the assigned slave device.
760 rdm="RDM_RESERVATION_STRING"
762 HVM/x86 only! Specifies information about Reserved Device Memory
763 (RDM), which is necessary to enable robust device passthrough. One
764 example of RDM is reporting through the ACPI Reserved Memory Region
765 Reporting (RMRR) structure on the x86 platform.
766 RDM_RESERVATION_STRING is a comma separated list of "KEY=VALUE"
768 settings, from the following list:
769 strategy=STRING
771 Currently there is only one valid type, and that is "host".
772 host
774 If set to "host" it means all reserved device memory on
775 this platform should be checked to reserve regions in this
776 VM's address space. This global RDM parameter allows the
777 user to specify reserved regions explicitly, and using
778 "host" includes all reserved regions reported on this
779 platform, which is useful when doing hotplug.
780 By default this isn't set so we don't check all RDMs.
782 Instead, we just check the RDM specific to a given device
783 if we're assigning this kind of a device.
784 Note: this option is not recommended unless you can make
786 sure that no conflicts exist.
787 For example, you're trying to set "memory = 2800" to
789 allocate memory to one given VM but the platform owns two
790 RDM regions like:
791 Device A [sbdf_A]: RMRR region_A: base_addr ac6d3000
793 end_address ac6e6fff
794 Device B [sbdf_B]: RMRR region_B: base_addr ad800000
796 end_address afffffff
797 In this conflict case,
799 #1. If strategy is set to "host", for example:
801 rdm = "strategy=host,policy=strict" or rdm =
803 "strategy=host,policy=relaxed"
804 it means all conflicts will be handled according to the
806 policy introduced by policy as described below.
807 #2. If strategy is not set at all, but
809 pci = [ 'sbdf_A, rdm_policy=xxxxx' ]
811 it means only one conflict of region_A will be handled
813 according to the policy introduced by rdm_policy=STRING as
814 described inside pci options.
815 policy=STRING
817 Specifies how to deal with conflicts when reserving already
818 reserved device memory in the guest address space.
819 strict
821 Specifies that in case of an unresolved conflict the VM
822 can't be created, or the associated device can't be
823 attached in the case of hotplug.
824 relaxed
826 Specifies that in case of an unresolved conflict the VM is
827 allowed to be created but may cause the VM to crash if a
828 pass-through device accesses RDM. For example, the Windows
829 IGD GFX driver always accesses RDM regions so it leads to a
830 VM crash.
831 Note: this may be overridden by the rdm_policy option in
833 the pci device configuration.
834 usbctrl=[ "USBCTRL_SPEC_STRING", "USBCTRL_SPEC_STRING", ...]
836 Specifies the USB controllers created for this guest.
837 Each USBCTRL_SPEC_STRING is a comma-separated list of "KEY=VALUE"
839 settings, from the following list:
840 type=TYPE
842 Specifies the usb controller type.
843 pv Specifies a kernel based PVUSB backend.
845 qusb
847 Specifies a QEMU based PVUSB backend.
848 devicemodel
850 Specifies a USB controller emulated by QEMU. It will show
851 up as a PCI-device in the guest.
852 auto
854 Determines whether a kernel based backend is installed. If
855 this is the case, pv is used, otherwise qusb will be used.
856 For HVM domains devicemodel will be selected.
857 This option is the default.
859 version=VERSION
861 Specifies the usb controller version. Possible values include
862 1 (USB1.1), 2 (USB2.0) and 3 (USB3.0). Default is 2 (USB2.0).
863 Value 3 (USB3.0) is available for the devicemodel type only.
864 ports=PORTS
866 Specifies the total number of ports of the usb controller. The
867 maximum number is 31. The default is 8. With the type
868 devicemodel the number of ports is more limited: a USB1.1
869 controller always has 2 ports, a USB2.0 controller always has 6
870 ports and a USB3.0 controller can have up to 15 ports.
871 USB controller ids start from 0. In line with the USB
873 specification, however, ports on a controller start from 1.
874 EXAMPLE
876 usbctrl=["version=1,ports=4", "version=2,ports=8"]
878 The first controller is USB1.1 and has:
880 controller id = 0, and ports 1,2,3,4.
882 The second controller is USB2.0 and has:
884 controller id = 1, and ports 1,2,3,4,5,6,7,8.
886 usbdev=[ "USBDEV_SPEC_STRING", "USBDEV_SPEC_STRING", ...]
888 Specifies the USB devices to be attached to the guest at boot.
889 Each USBDEV_SPEC_STRING is a comma-separated list of "KEY=VALUE"
891 settings, from the following list:
892 type=hostdev
894 Specifies USB device type. Currently only "hostdev" is
895 supported.
896 hostbus=busnum
898 Specifies busnum of the USB device from the host perspective.
899 hostaddr=devnum
901 Specifies devnum of the USB device from the host perspective.
902 controller=CONTROLLER
904 Specifies the USB controller id, to which controller the USB
905 device is attached.
906 If no controller is specified, an available controller:port
908 combination will be used. If there are no available
909 controller:port combinations, a new controller will be created.
910 port=PORT
912 Specifies the USB port to which the USB device is attached. The
913 port option is valid only when the controller option is
914 specified.
915 pci=[ "PCI_SPEC_STRING", "PCI_SPEC_STRING", ...]
917 Specifies the host PCI devices to passthrough to this guest. See
918 xl-pci-configuration(5) for more details.
919 pci_permissive=BOOLEAN
921 Changes the default value of permissive for all PCI devices passed
922 through to this VM. See permissive above.
923 pci_msitranslate=BOOLEAN
925 Changes the default value of msitranslate for all PCI devices
926 passed through to this VM. See msitranslate above.
927 pci_seize=BOOLEAN
929 Changes the default value of seize for all PCI devices passed
930 through to this VM. See seize above.
931 pci_power_mgmt=BOOLEAN
933 (HVM only) Changes the default value of power_mgmt for all PCI
934 devices passed through to this VM. See power_mgmt above.
935 gfx_passthru=BOOLEAN|"STRING"
937 Enable graphics device PCI passthrough. This option makes an
938 assigned PCI graphics card become the primary graphics card in the
939 VM. The QEMU emulated graphics adapter is disabled and the VNC
940 console for the VM will not have any graphics output. All graphics
941 output, including boot time QEMU BIOS messages from the VM, will go
942 to the physical outputs of the passed through physical graphics
943 card.
944 The graphics card PCI device to pass through is chosen with the pci
946 option, in exactly the same way a normal Xen PCI device
947 passthrough/assignment is done. Note that gfx_passthru does not do
948 any kind of sharing of the GPU, so you can assign the GPU to only
949 one single VM at a time.
950 gfx_passthru also enables various legacy VGA memory ranges, BARs,
952 MMIOs, and ioports to be passed through to the VM, since those are
953 required for correct operation of things like VGA BIOS, text mode,
954 VBE, etc.
955 Enabling the gfx_passthru option also copies the physical graphics
957 card video BIOS to the guest memory, and executes the VBIOS in the
958 guest to initialize the graphics card.
959 Most graphics adapters require vendor specific tweaks for properly
961 working graphics passthrough. See the
962 XenVGAPassthroughTestedAdapters
963 <https://wiki.xenproject.org/wiki/XenVGAPassthroughTestedAdapters>
964 wiki page for graphics cards currently supported by gfx_passthru.
965 gfx_passthru is currently supported both with the qemu-xen-
967 traditional device-model and upstream qemu-xen device-model.
968 When given as a boolean the gfx_passthru option either disables
970 graphics card passthrough or enables autodetection.
971 When given as a string the gfx_passthru option describes the type
973 of device to enable. Note that this behavior is only supported with
974 the upstream qemu-xen device-model. With qemu-xen-traditional IGD
975 (Intel Graphics Device) is always assumed and options other than
976 autodetect or explicit IGD will result in an error.
977 Currently, valid values for the option are:
979 0 Disables graphics device PCI passthrough.
981 1, "default"
983 Enables graphics device PCI passthrough and autodetects the
984 type of device which is being used.
985 "igd"
987 Enables graphics device PCI passthrough but forcing the type of
988 device to Intel Graphics Device.
989 Note that some graphics cards (AMD/ATI cards, for example) do not
991 necessarily require the gfx_passthru option, so you can use the
992 normal Xen PCI passthrough to assign the graphics card as a
993 secondary graphics card to the VM. The QEMU-emulated graphics card
994 remains the primary graphics card, and VNC output is available from
995 the QEMU-emulated primary adapter.
996 More information about the Xen gfx_passthru feature is available on
998 the XenVGAPassthrough
999 <https://wiki.xenproject.org/wiki/XenVGAPassthrough> wiki page.
1000 rdm_mem_boundary=MBYTES
1002 Number of megabytes to set for a boundary when checking for RDM
1003 conflicts.
1004 When RDM conflicts with RAM, RDM is probably scattered over the
1006 whole RAM space. Having multiple RDM entries would worsen this and
1007 lead to a complicated memory layout. Here we're trying to figure
1008 out a simple solution to avoid breaking the existing layout. When a
1009 conflict occurs,
1010 #1. Above a predefined boundary
1012 - move lowmem_end below the reserved region to solve the conflict;
1013 #2. Below a predefined boundary
1015 - Check if the policy is strict or relaxed.
1016 A "strict" policy leads to a fail in libxl.
1017 Note that when both policies are specified on a given region,
1018 "strict" is always preferred.
1019 The "relaxed" policy issues a warning message and also masks this
1020 entry INVALID to indicate we shouldn't expose this entry to
1021 hvmloader.
1022 The default value is 2048.
1024 dtdev=[ "DTDEV_PATH", "DTDEV_PATH", ...]
1026 Specifies the host device tree nodes to passt hrough to this guest.
1027 Each DTDEV_PATH is an absolute path in the device tree.
1028 ioports=[ "IOPORT_RANGE", "IOPORT_RANGE", ...]
1030 Allow the guest to access specific legacy I/O ports. Each
1031 IOPORT_RANGE is given in hexadecimal format and may either be a
1032 range, e.g. "2f8-2ff" (inclusive), or a single I/O port, e.g.
1033 "2f8".
1034 It is recommended to only use this option for trusted VMs under
1036 administrator's control.
1037 iomem=[ "IOMEM_START,NUM_PAGES[@GFN]", "IOMEM_START,NUM_PAGES[@GFN]",
1039 ...]
1040 Allow auto-translated domains to access specific hardware I/O
1041 memory pages.
1042 IOMEM_START is a physical page number. NUM_PAGES is the number of
1044 pages, beginning with START_PAGE, to allow access to. GFN specifies
1045 the guest frame number where the mapping will start in the guest's
1046 address space. If GFN is not specified, the mapping will be
1047 performed using IOMEM_START as a start in the guest's address
1048 space, therefore performing a 1:1 mapping by default. All of these
1049 values must be given in hexadecimal format.
1050 Note that the IOMMU won't be updated with the mappings specified
1052 with this option. This option therefore should not be used to pass
1053 through any IOMMU-protected devices.
1054 It is recommended to only use this option for trusted VMs under
1056 administrator's control.
1057 irqs=[ NUMBER, NUMBER, ...]
1059 Allow a guest to access specific physical IRQs.
1060 It is recommended to only use this option for trusted VMs under
1062 administrator's control.
1063 If vuart console is enabled then irq 32 is reserved for it. See
1065 "vuart="uart"" to know how to enable vuart console.
1066 max_event_channels=N
1068 Limit the guest to using at most N event channels (PV interrupts).
1069 Guests use hypervisor resources for each event channel they use.
1070 The default of 1023 should be sufficient for typical guests. The
1072 maximum value depends on what the guest supports. Guests
1073 supporting the FIFO-based event channel ABI support up to 131,071
1074 event channels. Other guests are limited to 4095 (64-bit x86 and
1075 ARM) or 1023 (32-bit x86).
1076 vdispl=[ "VDISPL_SPEC_STRING", "VDISPL_SPEC_STRING", ...]
1078 Specifies the virtual display devices to be provided to the guest.
1079 Each VDISPL_SPEC_STRING is a comma-separated list of "KEY=VALUE"
1081 settings, from the following list:
1082 "backend=DOMAIN"
1084 Specifies the backend domain name or id. If not specified
1085 Domain-0 is used.
1086 "be-alloc=BOOLEAN"
1088 Indicates if backend can be a buffer provider/allocator for
1089 this domain. See display protocol for details.
1090 "connectors=CONNECTORS"
1092 Specifies virtual connectors for the device in following format
1093 <id>:<W>x<H>;<id>:<W>x<H>... where:
1094 "id"
1096 String connector unique id. Space, comma symbols are not
1097 allowed.
1098 "W" Connector width in pixels.
1100 "H" Connector height in pixels.
1102 EXAMPLE
1104 connectors=id0:1920x1080;id1:800x600;id2:640x480
1106 dm_restrict=BOOLEAN
1108 Restrict the device model after startup, to limit the consequencese
1109 of security vulnerabilities in qemu.
1110 See docs/features/qemu-depriv.pandoc for more information on Linux
1112 and QEMU version requirements, device model user setup, and current
1113 limitations.
1114 This feature is a technology preview. See SUPPORT.md for a
1116 security support statement.
1117 device_model_user=USERNAME
1119 When running dm_restrict, run the device model as this user.
1120 NOTE: Each domain MUST have a SEPARATE username.
1122 See docs/features/qemu-depriv.pandoc for more information.
1124 vsnd=[ VCARD_SPEC, VCARD_SPEC, ... ]
1126 Specifies the virtual sound cards to be provided to the guest.
1127 Each VCARD_SPEC is a list, which has a form of "[VSND_ITEM_SPEC,
1128 VSND_ITEM_SPEC, ... ]" (without the quotes). The virtual sound
1129 card has hierarchical structure. Every card has a set of PCM
1130 devices and streams, each could be individually configured.
1131 VSND_ITEM_SPEC describes individual item parameters.
1133 VSND_ITEM_SPEC is a string of comma separated item parameters
1134 headed by item identifier. Each item parameter is "KEY=VALUE" pair:
1135 "identifier, param = value, ...".
1137 Identifier shall be one of following values: "CARD", "PCM",
1139 "STREAM". The child item treated as belonging to the previously
1140 defined parent item.
1141 All parameters are optional.
1143 There are group of parameters which are common for all items. This
1145 group can be defined at higher level of the hierarchy and be fully
1146 or partially re-used by the underlying layers. These parameters
1147 are:
1148 * number of channels (min/max)
1150 * supported sample rates
1152 * supported sample formats
1154 E.g. one can define these values for the whole card, device or
1156 stream. Every underlying layer in turn can re-define some or all
1157 of them to better fit its needs. For example, card may define
1158 number of channels to be in [1; 8] range, and some particular
1159 stream may be limited to [1; 2] only. The rule is that the
1160 underlying layer must be a subset of the upper layer range.
1161 COMMON parameters:
1163 sample-rates=RATES
1165 List of integer values separated by semicolon:
1166 sample-rates=8000;22050;44100
1167 sample-formats=FORMATS
1169 List of string values separated by semicolon:
1170 sample-formats=s16_le;s8;u32_be
1171 Supported formats: s8, u8, s16_le, s16_be, u16_le, u16_be,
1173 s24_le, s24_be, u24_le, u24_be, s32_le, s32_be, u32_le,
1174 u32_be, float_le, float_be, float64_le, float64_be,
1175 iec958_subframe_le, iec958_subframe_be, mu_law, a_law,
1176 ima_adpcm, mpeg, gsm
1177 channels-min=NUMBER
1179 The minimum amount of channels.
1180 channels-max=NUMBER
1182 The maximum amount of channels.
1183 buffer-size=NUMBER
1185 The maximum size in octets of the buffer to allocate per
1186 stream.
1187 CARD specification:
1189 backend=domain-id
1191 Specify the backend domain name or id, defaults to dom0.
1192 short-name=STRING
1194 Short name of the virtual sound card.
1195 long-name=STRING
1197 Long name of the virtual sound card.
1198 PCM specification:
1200 name=STRING
1202 Name of the PCM sound device within the virtual sound card.
1203 STREAM specification:
1205 unique-id=STRING
1207 Unique stream identifier.
1208 type=TYPE
1210 Stream type: "p" - playback stream, "c" - capture stream.
1211 EXAMPLE:
1213 vsnd = [
1215 ['CARD, short-name=Main, sample-formats=s16_le;s8;u32_be',
1216 'PCM, name=Main',
1217 'STREAM, id=0, type=p',
1218 'STREAM, id=1, type=c, channels-max=2'
1219 ],
1220 ['CARD, short-name=Second',
1221 'PCM, name=Second, buffer-size=1024',
1222 'STREAM, id=2, type=p',
1223 'STREAM, id=3, type=c'
1224 ]
1225 ]
1226 vkb=[ "VKB_SPEC_STRING", "VKB_SPEC_STRING", ...]
1228 Specifies the virtual keyboard device to be provided to the guest.
1229 Each VKB_SPEC_STRING is a comma-separated list of "KEY=VALUE"
1231 settings from the following list:
1232 unique-id=STRING
1234 Specifies the unique input device id.
1235 backend=domain-id
1237 Specifies the backend domain name or id.
1238 backend-type=type
1240 Specifies the backend type: qemu - for QEMU backend or linux -
1241 for Linux PV domain.
1242 feature-disable-keyboard=BOOLEAN
1244 Indicates if keyboard device is disabled.
1245 feature-disable-pointer=BOOLEAN
1247 Indicates if pointer device is disabled.
1248 feature-abs-pointer=BOOLEAN
1250 Indicates if pointer device can return absolute coordinates.
1251 feature-raw-pointer=BOOLEAN
1253 Indicates if pointer device can return raw (unscaled) absolute
1254 coordinates.
1255 feature-multi-touch=BOOLEAN
1257 Indicates if input device supports multi touch.
1258 multi-touch-width=MULTI_TOUCH_WIDTH
1260 Set maximum width for multi touch device.
1261 multi-touch-height=MULTI_TOUCH_HEIGHT
1263 Set maximum height for multi touch device.
1264 multi-touch-num-contacts=MULTI_TOUCH_NUM_CONTACTS
1266 Set maximum contacts number for multi touch device.
1267 width=WIDTH
1269 Set maximum width for pointer device.
1270 height=HEIGHT
1272 Set maximum height for pointer device.
1273 tee="STRING"
1275 Arm only. Set TEE type for the guest. TEE is a Trusted Execution
1276 Environment -- separate secure OS found on some platforms. STRING
1277 can be one of the:
1278 none
1280 "Don't allow the guest to use TEE if present on the platform.
1281 This is the default value.
1282 optee
1284 Allow a guest to access the host OP-TEE OS. Xen will mediate
1285 the access to OP-TEE and the resource isolation will be
1286 provided directly by OP-TEE. OP-TEE itself may limit the number
1287 of guests that can concurrently use it. This requires a
1288 virtualization-aware OP-TEE for this to work.
1289 You can refer to OP-TEE documentation
1291 <https://optee.readthedocs.io/en/latest/architecture/virtualization.html>
1292 for more information about how to enable and configure
1293 virtualization support in OP-TEE.
1294 This feature is a technology preview.
1296 Paravirtualised (PV) Guest Specific Options
1298 The following options apply only to Paravirtual (PV) guests.
1299 bootloader="PROGRAM"
1301 Run "PROGRAM" to find the kernel image and ramdisk to use.
1302 Normally "PROGRAM" would be "pygrub", which is an emulation of
1303 grub/grub2/syslinux. Either kernel or bootloader must be specified
1304 for PV guests.
1305 bootloader_args=[ "ARG", "ARG", ...]
1307 Append ARGs to the arguments to the bootloader program.
1308 Alternatively if the argument is a simple string then it will be
1309 split into words at whitespace (this second option is deprecated).
1310 e820_host=BOOLEAN
1312 Selects whether to expose the host e820 (memory map) to the guest
1313 via the virtual e820. When this option is false (0) the guest
1314 pseudo-physical address space consists of a single contiguous RAM
1315 region. When this option is specified the virtual e820 instead
1316 reflects the host e820 and contains the same PCI holes. The total
1317 amount of RAM represented by the memory map is always the same,
1318 this option configures only how it is laid out.
1319 Exposing the host e820 to the guest gives the guest kernel the
1321 opportunity to set aside the required part of its pseudo-physical
1322 address space in order to provide address space to map
1323 passedthrough PCI devices. It is guest Operating System dependent
1324 whether this option is required, specifically it is required when
1325 using a mainline Linux ("pvops") kernel. This option defaults to
1326 true (1) if any PCI passthrough devices are configured and false
1327 (0) otherwise. If you do not configure any passthrough devices at
1328 domain creation time but expect to hotplug devices later then you
1329 should set this option. Conversely if your particular guest kernel
1330 does not require this behaviour then it is safe to allow this to be
1331 enabled but you may wish to disable it anyway.
1332 Fully-virtualised (HVM) Guest Specific Options
1334 The following options apply only to Fully-virtualised (HVM) guests.
1335 Boot Device
1337 boot="STRING"
1339 Specifies the emulated virtual device to boot from.
1340 Possible values are:
1342 c Hard disk.
1344 d CD-ROM.
1346 n Network / PXE.
1348 Note: multiple options can be given and will be attempted in the
1350 order they are given, e.g. to boot from CD-ROM but fall back to the
1351 hard disk you can specify it as dc.
1352 The default is cd, meaning try booting from the hard disk first,
1354 but fall back to the CD-ROM.
1355 Emulated disk controller type
1357 hdtype=STRING
1359 Specifies the hard disk type.
1360 Possible values are:
1362 ide If thise mode is specified xl adds an emulated IDE controller,
1364 which is suitable even for older operation systems.
1365 ahci
1367 If this mode is specified, xl adds an ich9 disk controller in
1368 AHCI mode and uses it with upstream QEMU to emulate disks
1369 instead of IDE. It decreases boot time but may not be supported
1370 by default in older operating systems, e.g. Windows XP.
1371 The default is ide.
1373 Paging
1375 The following options control the mechanisms used to virtualise guest
1377 memory. The defaults are selected to give the best results for the
1378 common cases so you should normally leave these options unspecified.
1379 hap=BOOLEAN
1381 Turns "hardware assisted paging" (the use of the hardware nested
1382 page table feature) on or off. This feature is called EPT
1383 (Extended Page Tables) by Intel and NPT (Nested Page Tables) or RVI
1384 (Rapid Virtualisation Indexing) by AMD. If turned off, Xen will run
1385 the guest in "shadow page table" mode where the guest's page table
1386 updates and/or TLB flushes etc. will be emulated. Use of HAP is
1387 the default when available.
1388 oos=BOOLEAN
1390 Turns "out of sync pagetables" on or off. When running in shadow
1391 page table mode, the guest's page table updates may be deferred as
1392 specified in the Intel/AMD architecture manuals. However, this may
1393 expose unexpected bugs in the guest, or find bugs in Xen, so it is
1394 possible to disable this feature. Use of out of sync page tables,
1395 when Xen thinks it appropriate, is the default.
1396 shadow_memory=MBYTES
1398 Number of megabytes to set aside for shadowing guest pagetable
1399 pages (effectively acting as a cache of translated pages) or to use
1400 for HAP state. By default this is 1MB per guest vCPU plus 8KB per
1401 MB of guest RAM. You should not normally need to adjust this value.
1402 However, if you are not using hardware assisted paging (i.e. you
1403 are using shadow mode) and your guest workload consists of a very
1404 large number of similar processes then increasing this value may
1405 improve performance.
1406 Processor and Platform Features
1408 The following options allow various processor and platform level
1410 features to be hidden or exposed from the guest's point of view. This
1411 can be useful when running older guest Operating Systems which may
1412 misbehave when faced with more modern features. In general, you should
1413 accept the defaults for these options wherever possible.
1414 bios="STRING"
1416 Select the virtual firmware that is exposed to the guest. By
1417 default, a guess is made based on the device model, but sometimes
1418 it may be useful to request a different one, like UEFI.
1419 rombios
1421 Loads ROMBIOS, a 16-bit x86 compatible BIOS. This is used by
1422 default when device_model_version=qemu-xen-traditional. This is
1423 the only BIOS option supported when
1424 device_model_version=qemu-xen-traditional. This is the BIOS
1425 used by all previous Xen versions.
1426 seabios
1428 Loads SeaBIOS, a 16-bit x86 compatible BIOS. This is used by
1429 default with device_model_version=qemu-xen.
1430 ovmf
1432 Loads OVMF, a standard UEFI firmware by Tianocore project.
1433 Requires device_model_version=qemu-xen.
1434 bios_path_override="PATH"
1436 Override the path to the blob to be used as BIOS. The blob provided
1437 here MUST be consistent with the bios= which you have specified.
1438 You should not normally need to specify this option.
1439 This option does not have any effect if using bios="rombios" or
1441 device_model_version="qemu-xen-traditional".
1442 pae=BOOLEAN
1444 Hide or expose the IA32 Physical Address Extensions. These
1445 extensions make it possible for a 32 bit guest Operating System to
1446 access more than 4GB of RAM. Enabling PAE also enabled other
1447 features such as NX. PAE is required if you wish to run a 64-bit
1448 guest Operating System. In general, you should leave this enabled
1449 and allow the guest Operating System to choose whether or not to
1450 use PAE. (X86 only)
1451 acpi=BOOLEAN
1453 Expose ACPI (Advanced Configuration and Power Interface) tables
1454 from the virtual firmware to the guest Operating System. ACPI is
1455 required by most modern guest Operating Systems. This option is
1456 enabled by default and usually you should omit it. However, it may
1457 be necessary to disable ACPI for compatibility with some guest
1458 Operating Systems. This option is true for x86 while it's false
1459 for ARM by default.
1460 acpi_s3=BOOLEAN
1462 Include the S3 (suspend-to-ram) power state in the virtual firmware
1463 ACPI table. True (1) by default.
1464 acpi_s4=BOOLEAN
1466 Include S4 (suspend-to-disk) power state in the virtual firmware
1467 ACPI table. True (1) by default.
1468 acpi_laptop_slate=BOOLEAN
1470 Include the Windows laptop/slate mode switch device in the virtual
1471 firmware ACPI table. False (0) by default.
1472 apic=BOOLEAN
1474 (x86 only) Include information regarding APIC (Advanced
1475 Programmable Interrupt Controller) in the firmware/BIOS tables on a
1476 single processor guest. This causes the MP (multiprocessor) and PIR
1477 (PCI Interrupt Routing) tables to be exported by the virtual
1478 firmware. This option has no effect on a guest with multiple
1479 virtual CPUs as they must always include these tables. This option
1480 is enabled by default and you should usually omit it but it may be
1481 necessary to disable these firmware tables when using certain older
1482 guest Operating Systems. These tables have been superseded by newer
1483 constructs within the ACPI tables.
1484 nx=BOOLEAN
1486 (x86 only) Hides or exposes the No-eXecute capability. This allows
1487 a guest Operating System to map pages in such a way that they
1488 cannot be executed which can enhance security. This options
1489 requires that PAE also be enabled.
1490 hpet=BOOLEAN
1492 (x86 only) Enables or disables HPET (High Precision Event Timer).
1493 This option is enabled by default and you should usually omit it.
1494 It may be necessary to disable the HPET in order to improve
1495 compatibility with guest Operating Systems.
1496 altp2m="MODE"
1498 (x86 only) Specifies the access mode to the alternate-p2m
1499 capability. Alternate-p2m allows a guest to manage multiple p2m
1500 guest physical "memory views" (as opposed to a single p2m). You
1501 may want this option if you want to access-control/isolate access
1502 to specific guest physical memory pages accessed by the guest, e.g.
1503 for domain memory introspection or for isolation/access-control of
1504 memory between components within a single guest domain. This option
1505 is disabled by default.
1506 The valid values are as follows:
1508 disabled
1510 Altp2m is disabled for the domain (default).
1511 mixed
1513 The mixed mode allows access to the altp2m interface for both
1514 in-guest and external tools as well.
1515 external
1517 Enables access to the alternate-p2m capability by external
1518 privileged tools.
1519 limited
1521 Enables limited access to the alternate-p2m capability, ie.
1522 giving the guest access only to enable/disable the VMFUNC and
1523 #VE features.
1524 altp2mhvm=BOOLEAN
1526 Enables or disables HVM guest access to alternate-p2m capability.
1527 Alternate-p2m allows a guest to manage multiple p2m guest physical
1528 "memory views" (as opposed to a single p2m). This option is
1529 disabled by default and is available only to HVM domains. You may
1530 want this option if you want to access-control/isolate access to
1531 specific guest physical memory pages accessed by the guest, e.g.
1532 for HVM domain memory introspection or for isolation/access-control
1533 of memory between components within a single guest HVM domain. This
1534 option is deprecated, use the option "altp2m" instead.
1535 Note: While the option "altp2mhvm" is deprecated, legacy
1537 applications for x86 systems will continue to work using it.
1538 nestedhvm=BOOLEAN
1540 Enable or disables guest access to hardware virtualisation
1541 features, e.g. it allows a guest Operating System to also function
1542 as a hypervisor. You may want this option if you want to run
1543 another hypervisor (including another copy of Xen) within a Xen
1544 guest or to support a guest Operating System which uses hardware
1545 virtualisation extensions (e.g. Windows XP compatibility mode on
1546 more modern Windows OS). This option is disabled by default.
1547 cpuid="LIBXL_STRING" or cpuid=[ "XEND_STRING", "XEND_STRING" ]
1549 Configure the value returned when a guest executes the CPUID
1550 instruction. Two versions of config syntax are recognized: libxl
1551 and xend.
1552 Both formats use a common notation for specifying a single feature
1554 bit. Possible values are:
1555 '1' -> force the corresponding bit to 1
1556 '0' -> force to 0
1557 'x' -> Get a safe value (pass through and mask with the default
1558 policy)
1559 'k' -> pass through the host bit value (at boot only - value
1560 preserved on migrate)
1561 's' -> legacy alias for 'k'
1562 Libxl format:
1564 The libxl format is a single string, starting with the word
1566 "host", and followed by a comma separated list of key=value
1567 pairs. A few keys take a numerical value, all others take a
1568 single character which describes what to do with the feature
1569 bit. e.g.:
1570 cpuid="host,tm=0,sse3=0"
1572 List of keys taking a value:
1574 apicidsize brandid clflush family localapicid maxleaf
1576 maxhvleaf model nc proccount procpkg stepping
1577 List of keys taking a character:
1579 3dnow 3dnowext 3dnowprefetch abm acpi adx aes altmovcr8
1581 apic arat avx avx2 avx512-4fmaps avx512-4vnniw avx512bw
1582 avx512cd avx512dq avx512er avx512f avx512ifma avx512pf
1583 avx512vbmi avx512vl bmi1 bmi2 clflushopt clfsh clwb cmov
1584 cmplegacy cmpxchg16 cmpxchg8 cmt cntxid dca de ds dscpl
1585 dtes64 erms est extapic f16c ffxsr fma fma4 fpu fsgsbase
1586 fxsr hle htt hypervisor ia64 ibs invpcid invtsc lahfsahf lm
1587 lwp mca mce misalignsse mmx mmxext monitor movbe mpx msr
1588 mtrr nodeid nx ospke osvw osxsave pae page1gb pat pbe pcid
1589 pclmulqdq pdcm perfctr_core perfctr_nb pge pku popcnt pse
1590 pse36 psn rdrand rdseed rdtscp rtm sha skinit smap smep smx
1591 ss sse sse2 sse3 sse4.1 sse4.2 sse4_1 sse4_2 sse4a ssse3
1592 svm svm_decode svm_lbrv svm_npt svm_nrips svm_pausefilt
1593 svm_tscrate svm_vmcbclean syscall sysenter tbm tm tm2
1594 topoext tsc tsc-deadline tsc_adjust umip vme vmx wdt x2apic
1595 xop xsave xtpr
1596 Xend format:
1598 Xend format consists of an array of one or more strings of the
1600 form "leaf:reg=bitstring,...". e.g. (matching the libxl
1601 example above):
1602 cpuid=["1:ecx=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx0,edx=xx0xxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
1604 ...]
1605 "leaf" is an integer, either decimal or hex with a "0x" prefix.
1607 e.g. to specify something in the AMD feature leaves, use
1608 "0x80000001:ecx=...".
1609 Some leaves have subleaves which can be specified as
1611 "leaf,subleaf". e.g. for the Intel structured feature leaf,
1612 use "7,0:ebx=..."
1613 The bitstring represents all bits in the register, its length
1615 must be 32 chars. Each successive character represent a
1616 lesser-significant bit.
1617 Note: when specifying cpuid for hypervisor leaves (0x4000xxxx major
1619 group) only the lowest 8 bits of leaf's 0x4000xx00 EAX register are
1620 processed, the rest are ignored (these 8 bits signify maximum
1621 number of hypervisor leaves).
1622 More info about the CPUID instruction can be found in the processor
1624 manuals, and on Wikipedia: <https://en.wikipedia.org/wiki/CPUID>
1625 acpi_firmware="STRING"
1627 Specifies a path to a file that contains extra ACPI firmware tables
1628 to pass into a guest. The file can contain several tables in their
1629 binary AML form concatenated together. Each table self describes
1630 its length so no additional information is needed. These tables
1631 will be added to the ACPI table set in the guest. Note that
1632 existing tables cannot be overridden by this feature. For example,
1633 this cannot be used to override tables like DSDT, FADT, etc.
1634 smbios_firmware="STRING"
1636 Specifies a path to a file that contains extra SMBIOS firmware
1637 structures to pass into a guest. The file can contain a set of DMTF
1638 predefined structures which will override the internal defaults.
1639 Not all predefined structures can be overridden, only the following
1640 types: 0, 1, 2, 3, 11, 22, 39. The file can also contain any number
1641 of vendor defined SMBIOS structures (type 128 - 255). Since SMBIOS
1642 structures do not present their overall size, each entry in the
1643 file must be preceded by a 32b integer indicating the size of the
1644 following structure.
1645 ms_vm_genid="OPTION"
1647 Provide a VM generation ID to the guest.
1648 The VM generation ID is a 128-bit random number that a guest may
1650 use to determine if the guest has been restored from an earlier
1651 snapshot or cloned.
1652 This is required for Microsoft Windows Server 2012 (and later)
1654 domain controllers.
1655 Valid options are:
1657 generate
1659 Generate a random VM generation ID every time the domain is
1660 created or restored.
1661 none
1663 Do not provide a VM generation ID.
1664 See also "Virtual Machine Generation ID" by Microsoft:
1666 <https://docs.microsoft.com/en-us/windows/win32/hyperv_v2/virtual-machine-generation-identifier>
1667 Guest Virtual Time Controls
1669 tsc_mode="MODE"
1671 (x86 only) Specifies how the TSC (Time Stamp Counter) should be
1672 provided to the guest. Specifying this option as a number is
1673 deprecated.
1674 Options are:
1676 default
1678 Guest rdtsc/p is executed natively when monotonicity can be
1679 guaranteed and emulated otherwise (with frequency scaled if
1680 necessary).
1681 If a HVM container in default TSC mode is created on a host
1683 that provides constant host TSC, its guest TSC frequency will
1684 be the same as the host. If it is later migrated to another
1685 host that provide constant host TSC and supports Intel VMX TSC
1686 scaling/AMD SVM TSC ratio, its guest TSC frequency will be the
1687 same before and after migration, and guest rdtsc/p will be
1688 executed natively after migration as well
1689 always_emulate
1691 Guest rdtsc/p is always emulated and the virtual TSC will
1692 appear to increment (kernel and user) at a fixed 1GHz rate,
1693 regardless of the pCPU HZ rate or power state. Although there
1694 is an overhead associated with emulation, this will NOT affect
1695 underlying CPU performance.
1696 native
1698 Guest rdtsc/p is always executed natively (no
1699 monotonicity/frequency guarantees). Guest rdtsc/p is emulated
1700 at native frequency if unsupported by h/w, else executed
1701 natively.
1702 native_paravirt
1704 This mode has been removed.
1705 Please see xen-tscmode(7) for more information on this option.
1707 localtime=BOOLEAN
1709 Set the real time clock to local time or to UTC. False (0) by
1710 default, i.e. set to UTC.
1711 rtc_timeoffset=SECONDS
1713 Set the real time clock offset in seconds. No offset (0) by
1714 default.
1715 vpt_align=BOOLEAN
1717 Specifies that periodic Virtual Platform Timers should be aligned
1718 to reduce guest interrupts. Enabling this option can reduce power
1719 consumption, especially when a guest uses a high timer interrupt
1720 frequency (HZ) values. The default is true (1).
1721 timer_mode="MODE"
1723 Specifies the mode for Virtual Timers. The valid values are as
1724 follows:
1725 delay_for_missed_ticks
1727 Delay for missed ticks. Do not advance a vCPU's time beyond the
1728 correct delivery time for interrupts that have been missed due
1729 to preemption. Deliver missed interrupts when the vCPU is
1730 rescheduled and advance the vCPU's virtual time stepwise for
1731 each one.
1732 no_delay_for_missed_ticks
1734 No delay for missed ticks. As above, missed interrupts are
1735 delivered, but guest time always tracks wallclock (i.e., real)
1736 time while doing so. This is the default.
1737 no_missed_ticks_pending
1739 No missed interrupts are held pending. Instead, to ensure ticks
1740 are delivered at some non-zero rate, if we detect missed ticks
1741 then the internal tick alarm is not disabled if the vCPU is
1742 preempted during the next tick period.
1743 one_missed_tick_pending
1745 One missed tick pending. Missed interrupts are collapsed
1746 together and delivered as one 'late tick'. Guest time always
1747 tracks wallclock (i.e., real) time.
1748 Memory layout
1750 mmio_hole=MBYTES
1752 Specifies the size the MMIO hole below 4GiB will be. Only valid
1753 for device_model_version="qemu-xen".
1754 Cannot be smaller than 256. Cannot be larger than 3840.
1756 Known good large value is 3072.
1758 Support for Paravirtualisation of HVM Guests
1760 The following options allow Paravirtualised features (such as devices)
1762 to be exposed to the guest Operating System in an HVM guest. Utilising
1763 these features requires specific guest support but when available they
1764 will result in improved performance.
1765 xen_platform_pci=BOOLEAN
1767 Enable or disable the Xen platform PCI device. The presence of
1768 this virtual device enables a guest Operating System (subject to
1769 the availability of suitable drivers) to make use of
1770 paravirtualisation features such as disk and network devices etc.
1771 Enabling these drivers improves performance and is strongly
1772 recommended when available. PV drivers are available for various
1773 Operating Systems including HVM Linux (out-of-the-box) and
1774 Microsoft Windows <https://xenproject.org/windows-pv-drivers/>.
1775 Setting xen_platform_pci=0 with the default device_model "qemu-xen"
1777 requires at least QEMU 1.6.
1778 viridian=[ "GROUP", "GROUP", ...] or viridian=BOOLEAN
1780 The groups of Microsoft Hyper-V (AKA viridian) compatible
1781 enlightenments exposed to the guest. The following groups of
1782 enlightenments may be specified:
1783 base
1785 This group incorporates the Hypercall MSRs, Virtual processor
1786 index MSR, and APIC access MSRs. These enlightenments can
1787 improve performance of Windows Vista and Windows Server 2008
1788 onwards and setting this option for such guests is strongly
1789 recommended. This group is also a pre-requisite for all
1790 others. If it is disabled then it is an error to attempt to
1791 enable any other group.
1792 freq
1794 This group incorporates the TSC and APIC frequency MSRs. These
1795 enlightenments can improve performance of Windows 7 and Windows
1796 Server 2008 R2 onwards.
1797 time_ref_count
1799 This group incorporates Partition Time Reference Counter MSR.
1800 This enlightenment can improve performance of Windows 8 and
1801 Windows Server 2012 onwards.
1802 reference_tsc
1804 This set incorporates the Partition Reference TSC MSR. This
1805 enlightenment can improve performance of Windows 7 and Windows
1806 Server 2008 R2 onwards.
1807 hcall_remote_tlb_flush
1809 This set incorporates use of hypercalls for remote TLB
1810 flushing. This enlightenment may improve performance of
1811 Windows guests running on hosts with higher levels of
1812 (physical) CPU contention.
1813 apic_assist
1815 This set incorporates use of the APIC assist page to avoid EOI
1816 of the local APIC. This enlightenment may improve performance
1817 of guests that make use of per-vCPU event channel upcall
1818 vectors. Note that this enlightenment will have no effect if
1819 the guest is using APICv posted interrupts.
1820 crash_ctl
1822 This group incorporates the crash control MSRs. These
1823 enlightenments allow Windows to write crash information such
1824 that it can be logged by Xen.
1825 stimer
1827 This set incorporates the SynIC and synthetic timer MSRs.
1828 Windows will use synthetic timers in preference to emulated
1829 HPET for a source of ticks and hence enabling this group will
1830 ensure that ticks will be consistent with use of an enlightened
1831 time source (time_ref_count or reference_tsc).
1832 hcall_ipi
1834 This set incorporates use of a hypercall for interprocessor
1835 interrupts. This enlightenment may improve performance of
1836 Windows guests with multiple virtual CPUs.
1837 ex_processor_masks
1839 This set enables new hypercall variants taking a variably-sized
1840 sparse Virtual Processor Set as an argument, rather than a
1841 simple 64-bit mask. Hence this enlightenment must be specified
1842 for guests with more than 64 vCPUs if hcall_remote_tlb_flush
1843 and/or hcall_ipi are also specified.
1844 no_vp_limit
1846 This group when set indicates to a guest that the hypervisor
1847 does not explicitly have any limits on the number of Virtual
1848 processors a guest is allowed to bring up. It is strongly
1849 recommended to keep this enabled for guests with more than 64
1850 vCPUs.
1851 cpu_hotplug
1853 This set enables dynamic changes to Virtual processor states in
1854 Windows guests effectively allowing vCPU hotplug.
1855 defaults
1857 This is a special value that enables the default set of groups,
1858 which is currently the base, freq, time_ref_count, apic_assist,
1859 crash_ctl, stimer, no_vp_limit and cpu_hotplug groups.
1860 all This is a special value that enables all available groups.
1862 Groups can be disabled by prefixing the name with '!'. So, for
1864 example, to enable all groups except freq, specify:
1865 viridian=[ "all", "!freq" ]
1867 For details of the enlightenments see the latest version of
1869 Microsoft's Hypervisor Top-Level Functional Specification.
1870 The enlightenments should be harmless for other versions of Windows
1872 (although they will not give any benefit) and the majority of other
1873 non-Windows OSes. However it is known that they are incompatible
1874 with some other Operating Systems and in some circumstance can
1875 prevent Xen's own paravirtualisation interfaces for HVM guests from
1876 being used.
1877 The viridian option can be specified as a boolean. A value of true
1879 (1) is equivalent to the list [ "defaults" ], and a value of false
1880 (0) is equivalent to an empty list.
1881 Emulated VGA Graphics Device
1883 The following options control the features of the emulated graphics
1885 device. Many of these options behave similarly to the equivalent key
1886 in the VFB_SPEC_STRING for configuring virtual frame buffer devices
1887 (see above).
1888 videoram=MBYTES
1890 Sets the amount of RAM which the emulated video card will contain,
1891 which in turn limits the resolutions and bit depths which will be
1892 available.
1893 When using the qemu-xen-traditional device-model, the default as
1895 well as minimum amount of video RAM for stdvga is 8 MB, which is
1896 sufficient for e.g. 1600x1200 at 32bpp. For the upstream qemu-xen
1897 device-model, the default and minimum is 16 MB.
1898 When using the emulated Cirrus graphics card (vga="cirrus") and the
1900 qemu-xen-traditional device-model, the amount of video RAM is fixed
1901 at 4 MB, which is sufficient for 1024x768 at 32 bpp. For the
1902 upstream qemu-xen device-model, the default and minimum is 8 MB.
1903 For QXL vga, both the default and minimal are 128MB. If videoram
1905 is set less than 128MB, an error will be triggered.
1906 stdvga=BOOLEAN
1908 Specifies a standard VGA card with VBE (VESA BIOS Extensions) as
1909 the emulated graphics device. If your guest supports VBE 2.0 or
1910 later (e.g. Windows XP onwards) then you should enable this.
1911 stdvga supports more video ram and bigger resolutions than Cirrus.
1912 The default is false (0) which means to emulate a Cirrus Logic
1913 GD5446 VGA card. This option is deprecated, use vga="stdvga"
1914 instead.
1915 vga="STRING"
1917 Selects the emulated video card. Options are: none, stdvga, cirrus
1918 and qxl. The default is cirrus.
1919 In general, QXL should work with the Spice remote display protocol
1921 for acceleration, and a QXL driver is necessary in the guest in
1922 that case. QXL can also work with the VNC protocol, but it will be
1923 like a standard VGA card without acceleration.
1924 vnc=BOOLEAN
1926 Allow access to the display via the VNC protocol. This enables the
1927 other VNC-related settings. The default is (1) enabled.
1928 vnclisten="ADDRESS[:DISPLAYNUM]"
1930 Specifies the IP address and, optionally, the VNC display number to
1931 use.
1932 vncdisplay=DISPLAYNUM
1934 Specifies the VNC display number to use. The actual TCP port number
1935 will be DISPLAYNUM+5900.
1936 vncunused=BOOLEAN
1938 Requests that the VNC display setup searches for a free TCP port to
1939 use. The actual display used can be accessed with xl vncviewer.
1940 vncpasswd="PASSWORD"
1942 Specifies the password for the VNC server. If the password is set
1943 to an empty string, authentication on the VNC server will be
1944 disabled allowing any user to connect.
1945 keymap="LANG"
1947 Configure the keymap to use for the keyboard associated with this
1948 display. If the input method does not easily support raw keycodes
1949 (e.g. this is often the case when using VNC) then this allows us to
1950 correctly map the input keys into keycodes seen by the guest. The
1951 specific values which are accepted are defined by the version of
1952 the device-model which you are using. See Keymaps below or consult
1953 the qemu(1) manpage. The default is en-us.
1954 sdl=BOOLEAN
1956 Specifies that the display should be presented via an X window
1957 (using Simple DirectMedia Layer). The default is (0) not enabled.
1958 opengl=BOOLEAN
1960 Enable OpenGL acceleration of the SDL display. Only effects
1961 machines using device_model_version="qemu-xen-traditional" and only
1962 if the device-model was compiled with OpenGL support. Default is
1963 (0) false.
1964 nographic=BOOLEAN
1966 Enable or disable the virtual graphics device. The default is to
1967 provide a VGA graphics device but this option can be used to
1968 disable it.
1969 Spice Graphics Support
1971 The following options control the features of SPICE.
1973 spice=BOOLEAN
1975 Allow access to the display via the SPICE protocol. This enables
1976 the other SPICE-related settings.
1977 spicehost="ADDRESS"
1979 Specifies the interface address to listen on if given, otherwise
1980 any interface.
1981 spiceport=NUMBER
1983 Specifies the port to listen on by the SPICE server if SPICE is
1984 enabled.
1985 spicetls_port=NUMBER
1987 Specifies the secure port to listen on by the SPICE server if SPICE
1988 is enabled. At least one of spiceport or spicetls_port must be
1989 given if SPICE is enabled.
1990 Note: the options depending on spicetls_port have not been
1992 supported.
1993 spicedisable_ticketing=BOOLEAN
1995 Enable clients to connect without specifying a password. When
1996 disabled, spicepasswd must be set. The default is (0) false.
1997 spicepasswd="PASSWORD"
1999 Specify the password which is used by clients for establishing a
2000 connection.
2001 spiceagent_mouse=BOOLEAN
2003 Whether SPICE agent is used for client mouse mode. The default is
2004 (1) true.
2005 spicevdagent=BOOLEAN
2007 Enables the SPICE vdagent. The SPICE vdagent is an optional
2008 component for enhancing user experience and performing guest-
2009 oriented management tasks. Its features include: client mouse mode
2010 (no need to grab the mouse by the client, no mouse lag), automatic
2011 adjustment of screen resolution, copy and paste (text and image)
2012 between the client and the guest. It also requires the vdagent
2013 service installed on the guest OS to work. The default is (0)
2014 disabled.
2015 spice_clipboard_sharing=BOOLEAN
2017 Enables SPICE clipboard sharing (copy/paste). It requires that
2018 spicevdagent is enabled. The default is (0) false.
2019 spiceusbredirection=NUMBER
2021 Enables SPICE USB redirection. Creates a NUMBER of USB redirection
2022 channels for redirecting up to 4 USB devices from the SPICE client
2023 to the guest's QEMU. It requires an USB controller and, if not
2024 defined, it will automatically add an USB2.0 controller. The
2025 default is (0) disabled.
2026 spice_image_compression="COMPRESSION"
2028 Specifies what image compression is to be used by SPICE (if given),
2029 otherwise the QEMU default will be used. Please see the
2030 documentation of your QEMU version for more details.
2031 Available options are: auto_glz, auto_lz, quic, glz, lz, off.
2033 spice_streaming_video="VIDEO"
2035 Specifies what streaming video setting is to be used by SPICE (if
2036 given), otherwise the QEMU default will be used.
2037 Available options are: filter, all, off.
2039 Miscellaneous Emulated Hardware
2041 serial=[ "DEVICE", "DEVICE", ...]
2043 Redirect virtual serial ports to DEVICEs. Please see the -serial
2044 option in the qemu(1) manpage for details of the valid DEVICE
2045 options. Default is vc when in graphical mode and stdio if
2046 nographic=1 is used.
2047 The form serial=DEVICE is also accepted for backwards
2049 compatibility.
2050 soundhw="DEVICE"
2052 Select the virtual sound card to expose to the guest. The valid
2053 devices are defined by the device model configuration, please see
2054 the qemu(1) manpage for details. The default is not to export any
2055 sound device.
2056 vkb_device=BOOLEAN
2058 Specifies that the HVM guest gets a vkdb. The default is true (1).
2059 usb=BOOLEAN
2061 Enables or disables an emulated USB bus in the guest.
2062 usbversion=NUMBER
2064 Specifies the type of an emulated USB bus in the guest, values 1
2065 for USB1.1, 2 for USB2.0 and 3 for USB3.0. It is available only
2066 with an upstream QEMU. Due to implementation limitations this is
2067 not compatible with the usb and usbdevice parameters. Default is
2068 (0) no USB controller defined.
2069 usbdevice=[ "DEVICE", "DEVICE", ...]
2071 Adds DEVICEs to the emulated USB bus. The USB bus must also be
2072 enabled using usb=1. The most common use for this option is
2073 usbdevice=['tablet'] which adds a pointer device using absolute
2074 coordinates. Such devices function better than relative coordinate
2075 devices (such as a standard mouse) since many methods of exporting
2076 guest graphics (such as VNC) work better in this mode. Note that
2077 this is independent of the actual pointer device you are using on
2078 the host/client side.
2079 Host devices can also be passed through in this way, by specifying
2081 host:USBID, where USBID is of the form xxxx:yyyy. The USBID can
2082 typically be found by using lsusb(1) or usb-devices(1).
2083 If you wish to use the "host:bus.addr" format, remove any leading
2085 '0' from the bus and addr. For example, for the USB device on bus
2086 008 dev 002, you should write "host:8.2".
2087 The form usbdevice=DEVICE is also accepted for backwards
2089 compatibility.
2090 More valid options can be found in the "usbdevice" section of the
2092 QEMU documentation.
2093 vendor_device="VENDOR_DEVICE"
2095 Selects which variant of the QEMU xen-pvdevice should be used for
2096 this guest. Valid values are:
2097 none
2099 The xen-pvdevice should be omitted. This is the default.
2100 xenserver
2102 The xenserver variant of the xen-pvdevice (device-id=C000) will
2103 be specified, enabling the use of XenServer PV drivers in the
2104 guest.
2105 This parameter only takes effect when
2107 device_model_version=qemu-xen. See xen-pci-device-reservations(7)
2108 for more information.
2109 PVH Guest Specific Options
2111 nestedhvm=BOOLEAN
2112 Enable or disables guest access to hardware virtualisation
2113 features, e.g. it allows a guest Operating System to also function
2114 as a hypervisor. You may want this option if you want to run
2115 another hypervisor (including another copy of Xen) within a Xen
2116 guest or to support a guest Operating System which uses hardware
2117 virtualisation extensions (e.g. Windows XP compatibility mode on
2118 more modern Windows OS).
2119 This option is disabled by default.
2121 bootloader="PROGRAM"
2123 Run "PROGRAM" to find the kernel image and ramdisk to use.
2124 Normally "PROGRAM" would be "pygrub", which is an emulation of
2125 grub/grub2/syslinux. Either kernel or bootloader must be specified
2126 for PV guests.
2127 bootloader_args=[ "ARG", "ARG", ...]
2129 Append ARGs to the arguments to the bootloader program.
2130 Alternatively if the argument is a simple string then it will be
2131 split into words at whitespace (this second option is deprecated).
2132 timer_mode="MODE"
2134 Specifies the mode for Virtual Timers. The valid values are as
2135 follows:
2136 delay_for_missed_ticks
2138 Delay for missed ticks. Do not advance a vCPU's time beyond the
2139 correct delivery time for interrupts that have been missed due
2140 to preemption. Deliver missed interrupts when the vCPU is
2141 rescheduled and advance the vCPU's virtual time stepwise for
2142 each one.
2143 no_delay_for_missed_ticks
2145 No delay for missed ticks. As above, missed interrupts are
2146 delivered, but guest time always tracks wallclock (i.e., real)
2147 time while doing so. This is the default.
2148 no_missed_ticks_pending
2150 No missed interrupts are held pending. Instead, to ensure ticks
2151 are delivered at some non-zero rate, if we detect missed ticks
2152 then the internal tick alarm is not disabled if the vCPU is
2153 preempted during the next tick period.
2154 one_missed_tick_pending
2156 One missed tick pending. Missed interrupts are collapsed
2157 together and delivered as one 'late tick'. Guest time always
2158 tracks wallclock (i.e., real) time.
2159 Paging
2161 The following options control the mechanisms used to virtualise guest
2163 memory. The defaults are selected to give the best results for the
2164 common cases so you should normally leave these options unspecified.
2165 hap=BOOLEAN
2167 Turns "hardware assisted paging" (the use of the hardware nested
2168 page table feature) on or off. This feature is called EPT
2169 (Extended Page Tables) by Intel and NPT (Nested Page Tables) or RVI
2170 (Rapid Virtualisation Indexing) by AMD. If turned off, Xen will run
2171 the guest in "shadow page table" mode where the guest's page table
2172 updates and/or TLB flushes etc. will be emulated. Use of HAP is
2173 the default when available.
2174 oos=BOOLEAN
2176 Turns "out of sync pagetables" on or off. When running in shadow
2177 page table mode, the guest's page table updates may be deferred as
2178 specified in the Intel/AMD architecture manuals. However, this may
2179 expose unexpected bugs in the guest, or find bugs in Xen, so it is
2180 possible to disable this feature. Use of out of sync page tables,
2181 when Xen thinks it appropriate, is the default.
2182 shadow_memory=MBYTES
2184 Number of megabytes to set aside for shadowing guest pagetable
2185 pages (effectively acting as a cache of translated pages) or to use
2186 for HAP state. By default this is 1MB per guest vCPU plus 8KB per
2187 MB of guest RAM. You should not normally need to adjust this value.
2188 However, if you are not using hardware assisted paging (i.e. you
2189 are using shadow mode) and your guest workload consists of a very
2190 large number of similar processes then increasing this value may
2191 improve performance.
2192 Device-Model Options
2194 The following options control the selection of the device-model. This
2195 is the component which provides emulation of the virtual devices to an
2196 HVM guest. For a PV guest a device-model is sometimes used to provide
2197 backends for certain PV devices (most usually a virtual framebuffer
2198 device).
2199 device_model_version="DEVICE-MODEL"
2201 Selects which variant of the device-model should be used for this
2202 guest.
2203 Valid values are:
2205 qemu-xen
2207 Use the device-model merged into the upstream QEMU project.
2208 This device-model is the default for Linux dom0.
2209 qemu-xen-traditional
2211 Use the device-model based upon the historical Xen fork of
2212 QEMU. This device-model is still the default for NetBSD dom0.
2213 It is recommended to accept the default value for new guests. If
2215 you have existing guests then, depending on the nature of the guest
2216 Operating System, you may wish to force them to use the device
2217 model which they were installed with.
2218 device_model_override="PATH"
2220 Override the path to the binary to be used as the device-model
2221 running in toolstack domain. The binary provided here MUST be
2222 consistent with the device_model_version which you have specified.
2223 You should not normally need to specify this option.
2224 stubdomain_kernel="PATH"
2226 Override the path to the kernel image used as device-model
2227 stubdomain. The binary provided here MUST be consistent with the
2228 device_model_version which you have specified. In case of qemu-
2229 xen-traditional it is expected to be MiniOS-based stubdomain image,
2230 in case of qemu-xen it is expected to be Linux-based stubdomain
2231 kernel.
2232 stubdomain_cmdline="STRING"
2234 Set the device-model stubdomain kernel command line to STRING.
2235 stubdomain_ramdisk="PATH"
2237 Override the path to the ramdisk image used as device-model
2238 stubdomain. The binary provided here is to be used by a kernel
2239 pointed by stubdomain_kernel. It is known to be used only by
2240 Linux-based stubdomain kernel.
2241 stubdomain_memory=MBYTES
2243 Start the stubdomain with MBYTES megabytes of RAM. Default is 128.
2244 device_model_stubdomain_override=BOOLEAN
2246 Override the use of stubdomain based device-model. Normally this
2247 will be automatically selected based upon the other features and
2248 options you have selected.
2249 device_model_stubdomain_seclabel="LABEL"
2251 Assign an XSM security label to the device-model stubdomain.
2252 device_model_args=[ "ARG", "ARG", ...]
2254 Pass additional arbitrary options on the device-model command line.
2255 Each element in the list is passed as an option to the device-
2256 model.
2257 device_model_args_pv=[ "ARG", "ARG", ...]
2259 Pass additional arbitrary options on the device-model command line
2260 for a PV device model only. Each element in the list is passed as
2261 an option to the device-model.
2262 device_model_args_hvm=[ "ARG", "ARG", ...]
2264 Pass additional arbitrary options on the device-model command line
2265 for an HVM device model only. Each element in the list is passed as
2266 an option to the device-model.
2267 Keymaps
2269 The keymaps available are defined by the device-model which you are
2270 using. Commonly this includes:
2271 ar de-ch es fo fr-ca hu ja mk no pt-br sv
2273 da en-gb et fr fr-ch is lt nl pl ru th
2274 de en-us fi fr-be hr it lv nl-be pt sl tr
2275 The default is en-us.
2277 See qemu(1) for more information.
2279 Architecture Specific options
2281 ARM
2282 gic_version="vN"
2284 Version of the GIC emulated for the guest.
2285 Currently, the following versions are supported:
2287 v2 Emulate a GICv2
2289 v3 Emulate a GICv3. Note that the emulated GIC does not support
2291 the GICv2 compatibility mode.
2292 default
2294 Emulate the same version as the native GIC hardware used by the
2295 host where the domain was created.
2296 This requires hardware compatibility with the requested version,
2298 either natively or via hardware backwards compatibility support.
2299 vuart="uart"
2301 To enable vuart console, user must specify the following option in
2302 the VM config file:
2303 vuart = "sbsa_uart"
2305 Currently, only the "sbsa_uart" model is supported for ARM.
2307 x86
2309 mca_caps=[ "CAP", "CAP", ... ]
2311 (HVM only) Enable MCA capabilities besides default ones enabled by
2312 Xen hypervisor for the HVM domain. "CAP" can be one in the
2313 following list:
2314 "lmce"
2316 Intel local MCE
2317 default
2319 No MCA capabilities in above list are enabled.
2320 msr_relaxed=BOOLEAN
2322 The "msr_relaxed" boolean is an interim option, and defaults to
2323 false.
2324 In Xen 4.15, the default behaviour for unhandled MSRs has been
2326 changed, to avoid leaking host data into guests, and to avoid
2327 breaking guest logic which uses #GP probing to identify the
2328 availability of MSRs.
2329 However, this new stricter behaviour has the possibility to break
2331 guests, and a more 4.14-like behaviour can be selected by setting
2332 this option.
2333 If using this option is necessary to fix an issue, please report a
2335 bug.
2336
2338 xl(1)
2339 xl.conf(5)
2340 xlcpupool.cfg(5)
2341 xl-disk-configuration(5)
2342 xl-network-configuration(5)
2343 xen-tscmode(7)
2344
2346 /etc/xen/NAME.cfg /var/lib/xen/dump/NAME
2347
2349 This document may contain items which require further documentation.
2350 Patches to improve incomplete items (or any other item) are gratefully
2351 received on the xen-devel@lists.xenproject.org mailing list. Please see
2352 <https://wiki.xenproject.org/wiki/Submitting_Xen_Project_Patches> for
2353 information on how to submit a patch to Xen.
23544.16.1 2022-07-12 xl.cfg(5)