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 nomigrate=BOOLEAN
465 Disable migration of this domain. This enables certain other
466 features which are incompatible with migration. Currently this is
467 limited to enabling the invariant TSC feature flag in CPUID results
468 when TSC is not emulated.
469 driver_domain=BOOLEAN
471 Specify that this domain is a driver domain. This enables certain
472 features needed in order to run a driver domain.
473 device_tree=PATH
475 Specify a partial device tree (compiled via the Device Tree
476 Compiler). Everything under the node "/passthrough" will be copied
477 into the guest device tree. For convenience, the node "/aliases" is
478 also copied to allow the user to define aliases which can be used
479 by the guest kernel.
480 Given the complexity of verifying the validity of a device tree,
482 this option should only be used with a trusted device tree.
483 Note that the partial device tree should avoid using the phandle
485 65000 which is reserved by the toolstack.
486 passthrough="STRING"
488 Specify whether IOMMU mappings are enabled for the domain and hence
489 whether it will be enabled for passthrough hardware. Valid values
490 for this option are:
491 disabled
493 IOMMU mappings are disabled for the domain and so hardware may
494 not be passed through.
495 This option is the default if no passthrough hardware is
497 specified in the domain's configuration.
498 enabled
500 This option enables IOMMU mappings and selects an appropriate
501 default operating mode (see below for details of the operating
502 modes). For HVM/PVH domains running on platforms where the
503 option is available, this is equivalent to share_pt. Otherwise,
504 and also for PV domains, this option is equivalent to sync_pt.
505 This option is the default if passthrough hardware is specified
507 in the domain's configuration.
508 sync_pt
510 This option means that IOMMU mappings will be synchronized with
511 the domain's P2M table as follows:
512 For a PV domain, all writable pages assigned to the domain are
514 identity mapped by MFN in the IOMMU page table. Thus a device
515 driver running in the domain may program passthrough hardware
516 for DMA using MFN values (i.e. host/machine frame numbers)
517 looked up in its P2M.
518 For an HVM/PVH domain, all non-foreign RAM pages present in its
520 P2M will be mapped by GFN in the IOMMU page table. Thus a
521 device driver running in the domain may program passthrough
522 hardware using GFN values (i.e. guest physical frame numbers)
523 without any further translation.
524 This option is not currently available on Arm.
526 share_pt
528 This option is unavailable for a PV domain. For an HVM/PVH
529 domain, this option means that the IOMMU will be programmed to
530 directly reference the domain's P2M table as its page table.
531 From the point of view of a device driver running in the domain
532 this is functionally equivalent to sync_pt but places less load
533 on the hypervisor and so should generally be selected in
534 preference. However, the availability of this option is
535 hardware specific. If xl info reports virt_caps containing
536 iommu_hap_pt_share then this option may be used.
537 default
539 The default, which chooses between disabled and enabled
540 according to whether passthrough devices are enabled in the
541 config file.
542 xend_suspend_evtchn_compat=BOOLEAN
544 If this option is true the xenstore path for the domain's suspend
545 event channel will not be created. Instead the old xend behaviour
546 of making the whole xenstore device sub-tree writable by the domain
547 will be re-instated.
548 The existence of the suspend event channel path can cause problems
550 with certain PV drivers running in the guest (e.g. old Red Hat PV
551 drivers for Windows).
552 If this option is not specified then it will default to false.
554 vmtrace_buf_kb=KBYTES
556 Specifies the size of vmtrace buffer that would be allocated for
557 each vCPU belonging to this domain. Disabled (i.e.
558 vmtrace_buf_kb=0) by default.
559 NOTE: Acceptable values are platform specific. For Intel Processor
561 Trace, this value must be a power of 2 between 4k and 16M.
562 Devices
564 The following options define the paravirtual, emulated and physical
565 devices which the guest will contain.
566 disk=[ "DISK_SPEC_STRING", "DISK_SPEC_STRING", ...]
568 Specifies the disks (both emulated disks and Xen virtual block
569 devices) which are to be provided to the guest, and what objects on
570 the host they should map to. See xl-disk-configuration(5) for more
571 details.
572 vif=[ "NET_SPEC_STRING", "NET_SPEC_STRING", ...]
574 Specifies the network interfaces (both emulated network adapters,
575 and Xen virtual interfaces) which are to be provided to the guest.
576 See xl-network-configuration(5) for more details.
577 vtpm=[ "VTPM_SPEC_STRING", "VTPM_SPEC_STRING", ...]
579 Specifies the Virtual Trusted Platform module to be provided to the
580 guest. See xen-vtpm(7) for more details.
581 Each VTPM_SPEC_STRING is a comma-separated list of "KEY=VALUE"
583 settings from the following list:
584 backend=domain-id
586 Specifies the backend domain name or id. This value is
587 required! If this domain is a guest, the backend should be set
588 to the vTPM domain name. If this domain is a vTPM, the backend
589 should be set to the vTPM manager domain name.
590 uuid=UUID
592 Specifies the UUID of this vTPM device. The UUID is used to
593 uniquely identify the vTPM device. You can create one using the
594 uuidgen(1) program on unix systems. If left unspecified, a new
595 UUID will be randomly generated every time the domain boots.
596 If this is a vTPM domain, you should specify a value. The value
597 is optional if this is a guest domain.
598 p9=[ "9PFS_SPEC_STRING", "9PFS_SPEC_STRING", ...]
600 Creates a Xen 9pfs connection to share a filesystem from the
601 backend to the frontend.
602 Each 9PFS_SPEC_STRING is a comma-separated list of "KEY=VALUE"
604 settings, from the following list:
605 tag=STRING
607 9pfs tag to identify the filesystem share. The tag is needed on
608 the guest side to mount it.
609 security_model="none"
611 Only "none" is supported today, which means that the files are
612 stored using the same credentials as those they have in the
613 guest (no user ownership squash or remap).
614 path=STRING
616 Filesystem path on the backend to export.
617 backend=domain-id
619 Specify the backend domain name or id, defaults to dom0.
620 pvcalls=[ "backend=domain-id", ... ]
622 Creates a Xen pvcalls connection to handle pvcalls requests from
623 frontend to backend. It can be used as an alternative networking
624 model. For more information about the protocol, see
625 https://xenbits.xenproject.org/docs/unstable/misc/pvcalls.html.
626 vfb=[ "VFB_SPEC_STRING", "VFB_SPEC_STRING", ...]
628 Specifies the paravirtual framebuffer devices which should be
629 supplied to the domain.
630 This option does not control the emulated graphics card presented
632 to an HVM guest. See Emulated VGA Graphics Device below for how to
633 configure the emulated device. If Emulated VGA Graphics Device
634 options are used in a PV guest configuration, xl will pick up vnc,
635 vnclisten, vncpasswd, vncdisplay, vncunused, sdl, opengl and keymap
636 to construct the paravirtual framebuffer device for the guest.
637 Each VFB_SPEC_STRING is a comma-separated list of "KEY=VALUE"
639 settings, from the following list:
640 vnc=BOOLEAN
642 Allow access to the display via the VNC protocol. This enables
643 the other VNC-related settings. Default is 1 (enabled).
644 vnclisten=ADDRESS[:DISPLAYNUM]
646 Specifies the IP address, and optionally the VNC display
647 number, to use.
648 Note: if you specify the display number here, you should not
650 use the vncdisplay option.
651 vncdisplay=DISPLAYNUM
653 Specifies the VNC display number to use. The actual TCP port
654 number will be DISPLAYNUM+5900.
655 Note: you should not use this option if you set the DISPLAYNUM
657 in the vnclisten option.
658 vncunused=BOOLEAN
660 Requests that the VNC display setup searches for a free TCP
661 port to use. The actual display used can be accessed with xl
662 vncviewer.
663 vncpasswd=PASSWORD
665 Specifies the password for the VNC server. If the password is
666 set to an empty string, authentication on the VNC server will
667 be disabled, allowing any user to connect.
668 sdl=BOOLEAN
670 Specifies that the display should be presented via an X window
671 (using Simple DirectMedia Layer). The default is 0 (not
672 enabled).
673 display=DISPLAY
675 Specifies the X Window display that should be used when the sdl
676 option is used.
677 xauthority=XAUTHORITY
679 Specifies the path to the X authority file that should be used
680 to connect to the X server when the sdl option is used.
681 opengl=BOOLEAN
683 Enable OpenGL acceleration of the SDL display. Only effects
684 machines using device_model_version="qemu-xen-traditional" and
685 only if the device-model was compiled with OpenGL support. The
686 default is 0 (disabled).
687 keymap=LANG
689 Configure the keymap to use for the keyboard associated with
690 this display. If the input method does not easily support raw
691 keycodes (e.g. this is often the case when using VNC) then this
692 allows us to correctly map the input keys into keycodes seen by
693 the guest. The specific values which are accepted are defined
694 by the version of the device-model which you are using. See
695 Keymaps below or consult the qemu(1) manpage. The default is
696 en-us.
697 channel=[ "CHANNEL_SPEC_STRING", "CHANNEL_SPEC_STRING", ...]
699 Specifies the virtual channels to be provided to the guest. A
700 channel is a low-bandwidth, bidirectional byte stream, which
701 resembles a serial link. Typical uses for channels include
702 transmitting VM configuration after boot and signalling to in-guest
703 agents. Please see xen-pv-channel(7) for more details.
704 Each CHANNEL_SPEC_STRING is a comma-separated list of "KEY=VALUE"
706 settings. Leading and trailing whitespace is ignored in both KEY
707 and VALUE. Neither KEY nor VALUE may contain ',', '=' or '"'.
708 Defined values are:
709 backend=domain-id
711 Specifies the backend domain name or id. This parameter is
712 optional. If this parameter is omitted then the toolstack
713 domain will be assumed.
714 name=NAME
716 Specifies the name for this device. This parameter is
717 mandatory! This should be a well-known name for a specific
718 application (e.g. guest agent) and should be used by the
719 frontend to connect the application to the right channel
720 device. There is no formal registry of channel names, so
721 application authors are encouraged to make their names unique
722 by including the domain name and a version number in the string
723 (e.g. org.mydomain.guestagent.1).
724 connection=CONNECTION
726 Specifies how the backend will be implemented. The following
727 options are available:
728 SOCKET
730 The backend will bind a Unix domain socket (at the path
731 given by path=PATH), listen for and accept connections. The
732 backend will proxy data between the channel and the
733 connected socket.
734 PTY The backend will create a pty and proxy data between the
736 channel and the master device. The command xl channel-list
737 can be used to discover the assigned slave device.
738 rdm="RDM_RESERVATION_STRING"
740 HVM/x86 only! Specifies information about Reserved Device Memory
741 (RDM), which is necessary to enable robust device passthrough. One
742 example of RDM is reporting through the ACPI Reserved Memory Region
743 Reporting (RMRR) structure on the x86 platform.
744 RDM_RESERVATION_STRING is a comma separated list of "KEY=VALUE"
746 settings, from the following list:
747 strategy=STRING
749 Currently there is only one valid type, and that is "host".
750 host
752 If set to "host" it means all reserved device memory on
753 this platform should be checked to reserve regions in this
754 VM's address space. This global RDM parameter allows the
755 user to specify reserved regions explicitly, and using
756 "host" includes all reserved regions reported on this
757 platform, which is useful when doing hotplug.
758 By default this isn't set so we don't check all RDMs.
760 Instead, we just check the RDM specific to a given device
761 if we're assigning this kind of a device.
762 Note: this option is not recommended unless you can make
764 sure that no conflicts exist.
765 For example, you're trying to set "memory = 2800" to
767 allocate memory to one given VM but the platform owns two
768 RDM regions like:
769 Device A [sbdf_A]: RMRR region_A: base_addr ac6d3000
771 end_address ac6e6fff
772 Device B [sbdf_B]: RMRR region_B: base_addr ad800000
774 end_address afffffff
775 In this conflict case,
777 #1. If strategy is set to "host", for example:
779 rdm = "strategy=host,policy=strict" or rdm =
781 "strategy=host,policy=relaxed"
782 it means all conflicts will be handled according to the
784 policy introduced by policy as described below.
785 #2. If strategy is not set at all, but
787 pci = [ 'sbdf_A, rdm_policy=xxxxx' ]
789 it means only one conflict of region_A will be handled
791 according to the policy introduced by rdm_policy=STRING as
792 described inside pci options.
793 policy=STRING
795 Specifies how to deal with conflicts when reserving already
796 reserved device memory in the guest address space.
797 strict
799 Specifies that in case of an unresolved conflict the VM
800 can't be created, or the associated device can't be
801 attached in the case of hotplug.
802 relaxed
804 Specifies that in case of an unresolved conflict the VM is
805 allowed to be created but may cause the VM to crash if a
806 pass-through device accesses RDM. For example, the Windows
807 IGD GFX driver always accesses RDM regions so it leads to a
808 VM crash.
809 Note: this may be overridden by the rdm_policy option in
811 the pci device configuration.
812 usbctrl=[ "USBCTRL_SPEC_STRING", "USBCTRL_SPEC_STRING", ...]
814 Specifies the USB controllers created for this guest.
815 Each USBCTRL_SPEC_STRING is a comma-separated list of "KEY=VALUE"
817 settings, from the following list:
818 type=TYPE
820 Specifies the usb controller type.
821 pv Specifies a kernel based PVUSB backend.
823 qusb
825 Specifies a QEMU based PVUSB backend.
826 devicemodel
828 Specifies a USB controller emulated by QEMU. It will show
829 up as a PCI-device in the guest.
830 auto
832 Determines whether a kernel based backend is installed. If
833 this is the case, pv is used, otherwise qusb will be used.
834 For HVM domains devicemodel will be selected.
835 This option is the default.
837 version=VERSION
839 Specifies the usb controller version. Possible values include
840 1 (USB1.1), 2 (USB2.0) and 3 (USB3.0). Default is 2 (USB2.0).
841 Value 3 (USB3.0) is available for the devicemodel type only.
842 ports=PORTS
844 Specifies the total number of ports of the usb controller. The
845 maximum number is 31. The default is 8. With the type
846 devicemodel the number of ports is more limited: a USB1.1
847 controller always has 2 ports, a USB2.0 controller always has 6
848 ports and a USB3.0 controller can have up to 15 ports.
849 USB controller ids start from 0. In line with the USB
851 specification, however, ports on a controller start from 1.
852 EXAMPLE
854 usbctrl=["version=1,ports=4", "version=2,ports=8"]
856 The first controller is USB1.1 and has:
858 controller id = 0, and ports 1,2,3,4.
860 The second controller is USB2.0 and has:
862 controller id = 1, and ports 1,2,3,4,5,6,7,8.
864 usbdev=[ "USBDEV_SPEC_STRING", "USBDEV_SPEC_STRING", ...]
866 Specifies the USB devices to be attached to the guest at boot.
867 Each USBDEV_SPEC_STRING is a comma-separated list of "KEY=VALUE"
869 settings, from the following list:
870 type=hostdev
872 Specifies USB device type. Currently only "hostdev" is
873 supported.
874 hostbus=busnum
876 Specifies busnum of the USB device from the host perspective.
877 hostaddr=devnum
879 Specifies devnum of the USB device from the host perspective.
880 controller=CONTROLLER
882 Specifies the USB controller id, to which controller the USB
883 device is attached.
884 If no controller is specified, an available controller:port
886 combination will be used. If there are no available
887 controller:port combinations, a new controller will be created.
888 port=PORT
890 Specifies the USB port to which the USB device is attached. The
891 port option is valid only when the controller option is
892 specified.
893 pci=[ "PCI_SPEC_STRING", "PCI_SPEC_STRING", ...]
895 Specifies the host PCI devices to passthrough to this guest. See
896 xl-pci-configuration(5) for more details.
897 pci_permissive=BOOLEAN
899 Changes the default value of permissive for all PCI devices passed
900 through to this VM. See permissive above.
901 pci_msitranslate=BOOLEAN
903 Changes the default value of msitranslate for all PCI devices
904 passed through to this VM. See msitranslate above.
905 pci_seize=BOOLEAN
907 Changes the default value of seize for all PCI devices passed
908 through to this VM. See seize above.
909 pci_power_mgmt=BOOLEAN
911 (HVM only) Changes the default value of power_mgmt for all PCI
912 devices passed through to this VM. See power_mgmt above.
913 gfx_passthru=BOOLEAN|"STRING"
915 Enable graphics device PCI passthrough. This option makes an
916 assigned PCI graphics card become the primary graphics card in the
917 VM. The QEMU emulated graphics adapter is disabled and the VNC
918 console for the VM will not have any graphics output. All graphics
919 output, including boot time QEMU BIOS messages from the VM, will go
920 to the physical outputs of the passed through physical graphics
921 card.
922 The graphics card PCI device to pass through is chosen with the pci
924 option, in exactly the same way a normal Xen PCI device
925 passthrough/assignment is done. Note that gfx_passthru does not do
926 any kind of sharing of the GPU, so you can assign the GPU to only
927 one single VM at a time.
928 gfx_passthru also enables various legacy VGA memory ranges, BARs,
930 MMIOs, and ioports to be passed through to the VM, since those are
931 required for correct operation of things like VGA BIOS, text mode,
932 VBE, etc.
933 Enabling the gfx_passthru option also copies the physical graphics
935 card video BIOS to the guest memory, and executes the VBIOS in the
936 guest to initialize the graphics card.
937 Most graphics adapters require vendor specific tweaks for properly
939 working graphics passthrough. See the
940 XenVGAPassthroughTestedAdapters
941 <https://wiki.xenproject.org/wiki/XenVGAPassthroughTestedAdapters>
942 wiki page for graphics cards currently supported by gfx_passthru.
943 gfx_passthru is currently supported both with the qemu-xen-
945 traditional device-model and upstream qemu-xen device-model.
946 When given as a boolean the gfx_passthru option either disables
948 graphics card passthrough or enables autodetection.
949 When given as a string the gfx_passthru option describes the type
951 of device to enable. Note that this behavior is only supported with
952 the upstream qemu-xen device-model. With qemu-xen-traditional IGD
953 (Intel Graphics Device) is always assumed and options other than
954 autodetect or explicit IGD will result in an error.
955 Currently, valid values for the option are:
957 0 Disables graphics device PCI passthrough.
959 1, "default"
961 Enables graphics device PCI passthrough and autodetects the
962 type of device which is being used.
963 "igd"
965 Enables graphics device PCI passthrough but forcing the type of
966 device to Intel Graphics Device.
967 Note that some graphics cards (AMD/ATI cards, for example) do not
969 necessarily require the gfx_passthru option, so you can use the
970 normal Xen PCI passthrough to assign the graphics card as a
971 secondary graphics card to the VM. The QEMU-emulated graphics card
972 remains the primary graphics card, and VNC output is available from
973 the QEMU-emulated primary adapter.
974 More information about the Xen gfx_passthru feature is available on
976 the XenVGAPassthrough
977 <https://wiki.xenproject.org/wiki/XenVGAPassthrough> wiki page.
978 rdm_mem_boundary=MBYTES
980 Number of megabytes to set for a boundary when checking for RDM
981 conflicts.
982 When RDM conflicts with RAM, RDM is probably scattered over the
984 whole RAM space. Having multiple RDM entries would worsen this and
985 lead to a complicated memory layout. Here we're trying to figure
986 out a simple solution to avoid breaking the existing layout. When a
987 conflict occurs,
988 #1. Above a predefined boundary
990 - move lowmem_end below the reserved region to solve the conflict;
991 #2. Below a predefined boundary
993 - Check if the policy is strict or relaxed.
994 A "strict" policy leads to a fail in libxl.
995 Note that when both policies are specified on a given region,
996 "strict" is always preferred.
997 The "relaxed" policy issues a warning message and also masks this
998 entry INVALID to indicate we shouldn't expose this entry to
999 hvmloader.
1000 The default value is 2048.
1002 dtdev=[ "DTDEV_PATH", "DTDEV_PATH", ...]
1004 Specifies the host device tree nodes to passt hrough to this guest.
1005 Each DTDEV_PATH is an absolute path in the device tree.
1006 ioports=[ "IOPORT_RANGE", "IOPORT_RANGE", ...]
1008 Allow the guest to access specific legacy I/O ports. Each
1009 IOPORT_RANGE is given in hexadecimal format and may either be a
1010 range, e.g. "2f8-2ff" (inclusive), or a single I/O port, e.g.
1011 "2f8".
1012 It is recommended to only use this option for trusted VMs under
1014 administrator's control.
1015 iomem=[ "IOMEM_START,NUM_PAGES[@GFN]", "IOMEM_START,NUM_PAGES[@GFN]",
1017 ...]
1018 Allow auto-translated domains to access specific hardware I/O
1019 memory pages.
1020 IOMEM_START is a physical page number. NUM_PAGES is the number of
1022 pages, beginning with START_PAGE, to allow access to. GFN specifies
1023 the guest frame number where the mapping will start in the guest's
1024 address space. If GFN is not specified, the mapping will be
1025 performed using IOMEM_START as a start in the guest's address
1026 space, therefore performing a 1:1 mapping by default. All of these
1027 values must be given in hexadecimal format.
1028 Note that the IOMMU won't be updated with the mappings specified
1030 with this option. This option therefore should not be used to pass
1031 through any IOMMU-protected devices.
1032 It is recommended to only use this option for trusted VMs under
1034 administrator's control.
1035 irqs=[ NUMBER, NUMBER, ...]
1037 Allow a guest to access specific physical IRQs.
1038 It is recommended to only use this option for trusted VMs under
1040 administrator's control.
1041 If vuart console is enabled then irq 32 is reserved for it. See
1043 "vuart="uart"" to know how to enable vuart console.
1044 max_event_channels=N
1046 Limit the guest to using at most N event channels (PV interrupts).
1047 Guests use hypervisor resources for each event channel they use.
1048 The default of 1023 should be sufficient for typical guests. The
1050 maximum value depends on what the guest supports. Guests
1051 supporting the FIFO-based event channel ABI support up to 131,071
1052 event channels. Other guests are limited to 4095 (64-bit x86 and
1053 ARM) or 1023 (32-bit x86).
1054 vdispl=[ "VDISPL_SPEC_STRING", "VDISPL_SPEC_STRING", ...]
1056 Specifies the virtual display devices to be provided to the guest.
1057 Each VDISPL_SPEC_STRING is a comma-separated list of "KEY=VALUE"
1059 settings, from the following list:
1060 "backend=DOMAIN"
1062 Specifies the backend domain name or id. If not specified
1063 Domain-0 is used.
1064 "be-alloc=BOOLEAN"
1066 Indicates if backend can be a buffer provider/allocator for
1067 this domain. See display protocol for details.
1068 "connectors=CONNECTORS"
1070 Specifies virtual connectors for the device in following format
1071 <id>:<W>x<H>;<id>:<W>x<H>... where:
1072 "id"
1074 String connector unique id. Space, comma symbols are not
1075 allowed.
1076 "W" Connector width in pixels.
1078 "H" Connector height in pixels.
1080 EXAMPLE
1082 connectors=id0:1920x1080;id1:800x600;id2:640x480
1084 dm_restrict=BOOLEAN
1086 Restrict the device model after startup, to limit the consequencese
1087 of security vulnerabilities in qemu.
1088 See docs/features/qemu-depriv.pandoc for more information on Linux
1090 and QEMU version requirements, device model user setup, and current
1091 limitations.
1092 This feature is a technology preview. See SUPPORT.md for a
1094 security support statement.
1095 device_model_user=USERNAME
1097 When running dm_restrict, run the device model as this user.
1098 NOTE: Each domain MUST have a SEPARATE username.
1100 See docs/features/qemu-depriv.pandoc for more information.
1102 vsnd=[ VCARD_SPEC, VCARD_SPEC, ... ]
1104 Specifies the virtual sound cards to be provided to the guest.
1105 Each VCARD_SPEC is a list, which has a form of "[VSND_ITEM_SPEC,
1106 VSND_ITEM_SPEC, ... ]" (without the quotes). The virtual sound
1107 card has hierarchical structure. Every card has a set of PCM
1108 devices and streams, each could be individually configured.
1109 VSND_ITEM_SPEC describes individual item parameters.
1111 VSND_ITEM_SPEC is a string of comma separated item parameters
1112 headed by item identifier. Each item parameter is "KEY=VALUE" pair:
1113 "identifier, param = value, ...".
1115 Identifier shall be one of following values: "CARD", "PCM",
1117 "STREAM". The child item treated as belonging to the previously
1118 defined parent item.
1119 All parameters are optional.
1121 There are group of parameters which are common for all items. This
1123 group can be defined at higher level of the hierarchy and be fully
1124 or partially re-used by the underlying layers. These parameters
1125 are:
1126 * number of channels (min/max)
1128 * supported sample rates
1130 * supported sample formats
1132 E.g. one can define these values for the whole card, device or
1134 stream. Every underlying layer in turn can re-define some or all
1135 of them to better fit its needs. For example, card may define
1136 number of channels to be in [1; 8] range, and some particular
1137 stream may be limited to [1; 2] only. The rule is that the
1138 underlying layer must be a subset of the upper layer range.
1139 COMMON parameters:
1141 sample-rates=RATES
1143 List of integer values separated by semicolon:
1144 sample-rates=8000;22050;44100
1145 sample-formats=FORMATS
1147 List of string values separated by semicolon:
1148 sample-formats=s16_le;s8;u32_be
1149 Supported formats: s8, u8, s16_le, s16_be, u16_le, u16_be,
1151 s24_le, s24_be, u24_le, u24_be, s32_le, s32_be, u32_le,
1152 u32_be, float_le, float_be, float64_le, float64_be,
1153 iec958_subframe_le, iec958_subframe_be, mu_law, a_law,
1154 ima_adpcm, mpeg, gsm
1155 channels-min=NUMBER
1157 The minimum amount of channels.
1158 channels-max=NUMBER
1160 The maximum amount of channels.
1161 buffer-size=NUMBER
1163 The maximum size in octets of the buffer to allocate per
1164 stream.
1165 CARD specification:
1167 backend=domain-id
1169 Specify the backend domain name or id, defaults to dom0.
1170 short-name=STRING
1172 Short name of the virtual sound card.
1173 long-name=STRING
1175 Long name of the virtual sound card.
1176 PCM specification:
1178 name=STRING
1180 Name of the PCM sound device within the virtual sound card.
1181 STREAM specification:
1183 unique-id=STRING
1185 Unique stream identifier.
1186 type=TYPE
1188 Stream type: "p" - playback stream, "c" - capture stream.
1189 EXAMPLE:
1191 vsnd = [
1193 ['CARD, short-name=Main, sample-formats=s16_le;s8;u32_be',
1194 'PCM, name=Main',
1195 'STREAM, id=0, type=p',
1196 'STREAM, id=1, type=c, channels-max=2'
1197 ],
1198 ['CARD, short-name=Second',
1199 'PCM, name=Second, buffer-size=1024',
1200 'STREAM, id=2, type=p',
1201 'STREAM, id=3, type=c'
1202 ]
1203 ]
1204 vkb=[ "VKB_SPEC_STRING", "VKB_SPEC_STRING", ...]
1206 Specifies the virtual keyboard device to be provided to the guest.
1207 Each VKB_SPEC_STRING is a comma-separated list of "KEY=VALUE"
1209 settings from the following list:
1210 unique-id=STRING
1212 Specifies the unique input device id.
1213 backend=domain-id
1215 Specifies the backend domain name or id.
1216 backend-type=type
1218 Specifies the backend type: qemu - for QEMU backend or linux -
1219 for Linux PV domain.
1220 feature-disable-keyboard=BOOLEAN
1222 Indicates if keyboard device is disabled.
1223 feature-disable-pointer=BOOLEAN
1225 Indicates if pointer device is disabled.
1226 feature-abs-pointer=BOOLEAN
1228 Indicates if pointer device can return absolute coordinates.
1229 feature-raw-pointer=BOOLEAN
1231 Indicates if pointer device can return raw (unscaled) absolute
1232 coordinates.
1233 feature-multi-touch=BOOLEAN
1235 Indicates if input device supports multi touch.
1236 multi-touch-width=MULTI_TOUCH_WIDTH
1238 Set maximum width for multi touch device.
1239 multi-touch-height=MULTI_TOUCH_HEIGHT
1241 Set maximum height for multi touch device.
1242 multi-touch-num-contacts=MULTI_TOUCH_NUM_CONTACTS
1244 Set maximum contacts number for multi touch device.
1245 width=WIDTH
1247 Set maximum width for pointer device.
1248 height=HEIGHT
1250 Set maximum height for pointer device.
1251 tee="STRING"
1253 Arm only. Set TEE type for the guest. TEE is a Trusted Execution
1254 Environment -- separate secure OS found on some platforms. STRING
1255 can be one of the:
1256 none
1258 "Don't allow the guest to use TEE if present on the platform.
1259 This is the default value.
1260 optee
1262 Allow a guest to access the host OP-TEE OS. Xen will mediate
1263 the access to OP-TEE and the resource isolation will be
1264 provided directly by OP-TEE. OP-TEE itself may limit the number
1265 of guests that can concurrently use it. This requires a
1266 virtualization-aware OP-TEE for this to work.
1267 You can refer to OP-TEE documentation
1269 <https://optee.readthedocs.io/en/latest/architecture/virtualization.html>
1270 for more information about how to enable and configure
1271 virtualization support in OP-TEE.
1272 This feature is a technology preview.
1274 Paravirtualised (PV) Guest Specific Options
1276 The following options apply only to Paravirtual (PV) guests.
1277 bootloader="PROGRAM"
1279 Run "PROGRAM" to find the kernel image and ramdisk to use.
1280 Normally "PROGRAM" would be "pygrub", which is an emulation of
1281 grub/grub2/syslinux. Either kernel or bootloader must be specified
1282 for PV guests.
1283 bootloader_args=[ "ARG", "ARG", ...]
1285 Append ARGs to the arguments to the bootloader program.
1286 Alternatively if the argument is a simple string then it will be
1287 split into words at whitespace (this second option is deprecated).
1288 e820_host=BOOLEAN
1290 Selects whether to expose the host e820 (memory map) to the guest
1291 via the virtual e820. When this option is false (0) the guest
1292 pseudo-physical address space consists of a single contiguous RAM
1293 region. When this option is specified the virtual e820 instead
1294 reflects the host e820 and contains the same PCI holes. The total
1295 amount of RAM represented by the memory map is always the same,
1296 this option configures only how it is laid out.
1297 Exposing the host e820 to the guest gives the guest kernel the
1299 opportunity to set aside the required part of its pseudo-physical
1300 address space in order to provide address space to map
1301 passedthrough PCI devices. It is guest Operating System dependent
1302 whether this option is required, specifically it is required when
1303 using a mainline Linux ("pvops") kernel. This option defaults to
1304 true (1) if any PCI passthrough devices are configured and false
1305 (0) otherwise. If you do not configure any passthrough devices at
1306 domain creation time but expect to hotplug devices later then you
1307 should set this option. Conversely if your particular guest kernel
1308 does not require this behaviour then it is safe to allow this to be
1309 enabled but you may wish to disable it anyway.
1310 Fully-virtualised (HVM) Guest Specific Options
1312 The following options apply only to Fully-virtualised (HVM) guests.
1313 Boot Device
1315 boot="STRING"
1317 Specifies the emulated virtual device to boot from.
1318 Possible values are:
1320 c Hard disk.
1322 d CD-ROM.
1324 n Network / PXE.
1326 Note: multiple options can be given and will be attempted in the
1328 order they are given, e.g. to boot from CD-ROM but fall back to the
1329 hard disk you can specify it as dc.
1330 The default is cd, meaning try booting from the hard disk first,
1332 but fall back to the CD-ROM.
1333 Emulated disk controller type
1335 hdtype=STRING
1337 Specifies the hard disk type.
1338 Possible values are:
1340 ide If thise mode is specified xl adds an emulated IDE controller,
1342 which is suitable even for older operation systems.
1343 ahci
1345 If this mode is specified, xl adds an ich9 disk controller in
1346 AHCI mode and uses it with upstream QEMU to emulate disks
1347 instead of IDE. It decreases boot time but may not be supported
1348 by default in older operating systems, e.g. Windows XP.
1349 The default is ide.
1351 Paging
1353 The following options control the mechanisms used to virtualise guest
1355 memory. The defaults are selected to give the best results for the
1356 common cases so you should normally leave these options unspecified.
1357 hap=BOOLEAN
1359 Turns "hardware assisted paging" (the use of the hardware nested
1360 page table feature) on or off. This feature is called EPT
1361 (Extended Page Tables) by Intel and NPT (Nested Page Tables) or RVI
1362 (Rapid Virtualisation Indexing) by AMD. If turned off, Xen will run
1363 the guest in "shadow page table" mode where the guest's page table
1364 updates and/or TLB flushes etc. will be emulated. Use of HAP is
1365 the default when available.
1366 oos=BOOLEAN
1368 Turns "out of sync pagetables" on or off. When running in shadow
1369 page table mode, the guest's page table updates may be deferred as
1370 specified in the Intel/AMD architecture manuals. However, this may
1371 expose unexpected bugs in the guest, or find bugs in Xen, so it is
1372 possible to disable this feature. Use of out of sync page tables,
1373 when Xen thinks it appropriate, is the default.
1374 shadow_memory=MBYTES
1376 Number of megabytes to set aside for shadowing guest pagetable
1377 pages (effectively acting as a cache of translated pages) or to use
1378 for HAP state. By default this is 1MB per guest vCPU plus 8KB per
1379 MB of guest RAM. You should not normally need to adjust this value.
1380 However, if you are not using hardware assisted paging (i.e. you
1381 are using shadow mode) and your guest workload consists of a very
1382 large number of similar processes then increasing this value may
1383 improve performance.
1384 Processor and Platform Features
1386 The following options allow various processor and platform level
1388 features to be hidden or exposed from the guest's point of view. This
1389 can be useful when running older guest Operating Systems which may
1390 misbehave when faced with more modern features. In general, you should
1391 accept the defaults for these options wherever possible.
1392 bios="STRING"
1394 Select the virtual firmware that is exposed to the guest. By
1395 default, a guess is made based on the device model, but sometimes
1396 it may be useful to request a different one, like UEFI.
1397 rombios
1399 Loads ROMBIOS, a 16-bit x86 compatible BIOS. This is used by
1400 default when device_model_version=qemu-xen-traditional. This is
1401 the only BIOS option supported when
1402 device_model_version=qemu-xen-traditional. This is the BIOS
1403 used by all previous Xen versions.
1404 seabios
1406 Loads SeaBIOS, a 16-bit x86 compatible BIOS. This is used by
1407 default with device_model_version=qemu-xen.
1408 ovmf
1410 Loads OVMF, a standard UEFI firmware by Tianocore project.
1411 Requires device_model_version=qemu-xen.
1412 bios_path_override="PATH"
1414 Override the path to the blob to be used as BIOS. The blob provided
1415 here MUST be consistent with the bios= which you have specified.
1416 You should not normally need to specify this option.
1417 This option does not have any effect if using bios="rombios" or
1419 device_model_version="qemu-xen-traditional".
1420 pae=BOOLEAN
1422 Hide or expose the IA32 Physical Address Extensions. These
1423 extensions make it possible for a 32 bit guest Operating System to
1424 access more than 4GB of RAM. Enabling PAE also enabled other
1425 features such as NX. PAE is required if you wish to run a 64-bit
1426 guest Operating System. In general, you should leave this enabled
1427 and allow the guest Operating System to choose whether or not to
1428 use PAE. (X86 only)
1429 acpi=BOOLEAN
1431 Expose ACPI (Advanced Configuration and Power Interface) tables
1432 from the virtual firmware to the guest Operating System. ACPI is
1433 required by most modern guest Operating Systems. This option is
1434 enabled by default and usually you should omit it. However, it may
1435 be necessary to disable ACPI for compatibility with some guest
1436 Operating Systems. This option is true for x86 while it's false
1437 for ARM by default.
1438 acpi_s3=BOOLEAN
1440 Include the S3 (suspend-to-ram) power state in the virtual firmware
1441 ACPI table. True (1) by default.
1442 acpi_s4=BOOLEAN
1444 Include S4 (suspend-to-disk) power state in the virtual firmware
1445 ACPI table. True (1) by default.
1446 acpi_laptop_slate=BOOLEAN
1448 Include the Windows laptop/slate mode switch device in the virtual
1449 firmware ACPI table. False (0) by default.
1450 apic=BOOLEAN
1452 (x86 only) Include information regarding APIC (Advanced
1453 Programmable Interrupt Controller) in the firmware/BIOS tables on a
1454 single processor guest. This causes the MP (multiprocessor) and PIR
1455 (PCI Interrupt Routing) tables to be exported by the virtual
1456 firmware. This option has no effect on a guest with multiple
1457 virtual CPUs as they must always include these tables. This option
1458 is enabled by default and you should usually omit it but it may be
1459 necessary to disable these firmware tables when using certain older
1460 guest Operating Systems. These tables have been superseded by newer
1461 constructs within the ACPI tables.
1462 nx=BOOLEAN
1464 (x86 only) Hides or exposes the No-eXecute capability. This allows
1465 a guest Operating System to map pages in such a way that they
1466 cannot be executed which can enhance security. This options
1467 requires that PAE also be enabled.
1468 hpet=BOOLEAN
1470 (x86 only) Enables or disables HPET (High Precision Event Timer).
1471 This option is enabled by default and you should usually omit it.
1472 It may be necessary to disable the HPET in order to improve
1473 compatibility with guest Operating Systems.
1474 altp2m="MODE"
1476 (x86 only) Specifies the access mode to the alternate-p2m
1477 capability. Alternate-p2m allows a guest to manage multiple p2m
1478 guest physical "memory views" (as opposed to a single p2m). You
1479 may want this option if you want to access-control/isolate access
1480 to specific guest physical memory pages accessed by the guest, e.g.
1481 for domain memory introspection or for isolation/access-control of
1482 memory between components within a single guest domain. This option
1483 is disabled by default.
1484 The valid values are as follows:
1486 disabled
1488 Altp2m is disabled for the domain (default).
1489 mixed
1491 The mixed mode allows access to the altp2m interface for both
1492 in-guest and external tools as well.
1493 external
1495 Enables access to the alternate-p2m capability by external
1496 privileged tools.
1497 limited
1499 Enables limited access to the alternate-p2m capability, ie.
1500 giving the guest access only to enable/disable the VMFUNC and
1501 #VE features.
1502 altp2mhvm=BOOLEAN
1504 Enables or disables HVM guest access to alternate-p2m capability.
1505 Alternate-p2m allows a guest to manage multiple p2m guest physical
1506 "memory views" (as opposed to a single p2m). This option is
1507 disabled by default and is available only to HVM domains. You may
1508 want this option if you want to access-control/isolate access to
1509 specific guest physical memory pages accessed by the guest, e.g.
1510 for HVM domain memory introspection or for isolation/access-control
1511 of memory between components within a single guest HVM domain. This
1512 option is deprecated, use the option "altp2m" instead.
1513 Note: While the option "altp2mhvm" is deprecated, legacy
1515 applications for x86 systems will continue to work using it.
1516 nestedhvm=BOOLEAN
1518 Enable or disables guest access to hardware virtualisation
1519 features, e.g. it allows a guest Operating System to also function
1520 as a hypervisor. You may want this option if you want to run
1521 another hypervisor (including another copy of Xen) within a Xen
1522 guest or to support a guest Operating System which uses hardware
1523 virtualisation extensions (e.g. Windows XP compatibility mode on
1524 more modern Windows OS). This option is disabled by default.
1525 cpuid="LIBXL_STRING" or cpuid=[ "XEND_STRING", "XEND_STRING" ]
1527 Configure the value returned when a guest executes the CPUID
1528 instruction. Two versions of config syntax are recognized: libxl
1529 and xend.
1530 Both formats use a common notation for specifying a single feature
1532 bit. Possible values are:
1533 '1' -> force the corresponding bit to 1
1534 '0' -> force to 0
1535 'x' -> Get a safe value (pass through and mask with the default
1536 policy)
1537 'k' -> pass through the host bit value (at boot only - value
1538 preserved on migrate)
1539 's' -> legacy alias for 'k'
1540 Libxl format:
1542 The libxl format is a single string, starting with the word
1544 "host", and followed by a comma separated list of key=value
1545 pairs. A few keys take a numerical value, all others take a
1546 single character which describes what to do with the feature
1547 bit. e.g.:
1548 cpuid="host,tm=0,sse3=0"
1550 List of keys taking a value:
1552 apicidsize brandid clflush family localapicid maxleaf
1554 maxhvleaf model nc proccount procpkg stepping
1555 List of keys taking a character:
1557 3dnow 3dnowext 3dnowprefetch abm acpi adx aes altmovcr8
1559 apic arat avx avx2 avx512-4fmaps avx512-4vnniw avx512bw
1560 avx512cd avx512dq avx512er avx512f avx512ifma avx512pf
1561 avx512vbmi avx512vl bmi1 bmi2 clflushopt clfsh clwb cmov
1562 cmplegacy cmpxchg16 cmpxchg8 cmt cntxid dca de ds dscpl
1563 dtes64 erms est extapic f16c ffxsr fma fma4 fpu fsgsbase
1564 fxsr hle htt hypervisor ia64 ibs invpcid invtsc lahfsahf lm
1565 lwp mca mce misalignsse mmx mmxext monitor movbe mpx msr
1566 mtrr nodeid nx ospke osvw osxsave pae page1gb pat pbe pcid
1567 pclmulqdq pdcm perfctr_core perfctr_nb pge pku popcnt pse
1568 pse36 psn rdrand rdseed rdtscp rtm sha skinit smap smep smx
1569 ss sse sse2 sse3 sse4.1 sse4.2 sse4_1 sse4_2 sse4a ssse3
1570 svm svm_decode svm_lbrv svm_npt svm_nrips svm_pausefilt
1571 svm_tscrate svm_vmcbclean syscall sysenter tbm tm tm2
1572 topoext tsc tsc-deadline tsc_adjust umip vme vmx wdt x2apic
1573 xop xsave xtpr
1574 Xend format:
1576 Xend format consists of an array of one or more strings of the
1578 form "leaf:reg=bitstring,...". e.g. (matching the libxl
1579 example above):
1580 cpuid=["1:ecx=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx0,edx=xx0xxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
1582 ...]
1583 "leaf" is an integer, either decimal or hex with a "0x" prefix.
1585 e.g. to specify something in the AMD feature leaves, use
1586 "0x80000001:ecx=...".
1587 Some leaves have subleaves which can be specified as
1589 "leaf,subleaf". e.g. for the Intel structured feature leaf,
1590 use "7,0:ebx=..."
1591 The bitstring represents all bits in the register, its length
1593 must be 32 chars. Each successive character represent a
1594 lesser-significant bit.
1595 Note: when specifying cpuid for hypervisor leaves (0x4000xxxx major
1597 group) only the lowest 8 bits of leaf's 0x4000xx00 EAX register are
1598 processed, the rest are ignored (these 8 bits signify maximum
1599 number of hypervisor leaves).
1600 More info about the CPUID instruction can be found in the processor
1602 manuals, and on Wikipedia: <https://en.wikipedia.org/wiki/CPUID>
1603 acpi_firmware="STRING"
1605 Specifies a path to a file that contains extra ACPI firmware tables
1606 to pass into a guest. The file can contain several tables in their
1607 binary AML form concatenated together. Each table self describes
1608 its length so no additional information is needed. These tables
1609 will be added to the ACPI table set in the guest. Note that
1610 existing tables cannot be overridden by this feature. For example,
1611 this cannot be used to override tables like DSDT, FADT, etc.
1612 smbios_firmware="STRING"
1614 Specifies a path to a file that contains extra SMBIOS firmware
1615 structures to pass into a guest. The file can contain a set of DMTF
1616 predefined structures which will override the internal defaults.
1617 Not all predefined structures can be overridden, only the following
1618 types: 0, 1, 2, 3, 11, 22, 39. The file can also contain any number
1619 of vendor defined SMBIOS structures (type 128 - 255). Since SMBIOS
1620 structures do not present their overall size, each entry in the
1621 file must be preceded by a 32b integer indicating the size of the
1622 following structure.
1623 ms_vm_genid="OPTION"
1625 Provide a VM generation ID to the guest.
1626 The VM generation ID is a 128-bit random number that a guest may
1628 use to determine if the guest has been restored from an earlier
1629 snapshot or cloned.
1630 This is required for Microsoft Windows Server 2012 (and later)
1632 domain controllers.
1633 Valid options are:
1635 generate
1637 Generate a random VM generation ID every time the domain is
1638 created or restored.
1639 none
1641 Do not provide a VM generation ID.
1642 See also "Virtual Machine Generation ID" by Microsoft:
1644 <https://docs.microsoft.com/en-us/windows/win32/hyperv_v2/virtual-machine-generation-identifier>
1645 Guest Virtual Time Controls
1647 tsc_mode="MODE"
1649 (x86 only) Specifies how the TSC (Time Stamp Counter) should be
1650 provided to the guest. Specifying this option as a number is
1651 deprecated.
1652 Options are:
1654 default
1656 Guest rdtsc/p is executed natively when monotonicity can be
1657 guaranteed and emulated otherwise (with frequency scaled if
1658 necessary).
1659 If a HVM container in default TSC mode is created on a host
1661 that provides constant host TSC, its guest TSC frequency will
1662 be the same as the host. If it is later migrated to another
1663 host that provide constant host TSC and supports Intel VMX TSC
1664 scaling/AMD SVM TSC ratio, its guest TSC frequency will be the
1665 same before and after migration, and guest rdtsc/p will be
1666 executed natively after migration as well
1667 always_emulate
1669 Guest rdtsc/p is always emulated and the virtual TSC will
1670 appear to increment (kernel and user) at a fixed 1GHz rate,
1671 regardless of the pCPU HZ rate or power state. Although there
1672 is an overhead associated with emulation, this will NOT affect
1673 underlying CPU performance.
1674 native
1676 Guest rdtsc/p is always executed natively (no
1677 monotonicity/frequency guarantees). Guest rdtsc/p is emulated
1678 at native frequency if unsupported by h/w, else executed
1679 natively.
1680 native_paravirt
1682 This mode has been removed.
1683 Please see xen-tscmode(7) for more information on this option.
1685 localtime=BOOLEAN
1687 Set the real time clock to local time or to UTC. False (0) by
1688 default, i.e. set to UTC.
1689 rtc_timeoffset=SECONDS
1691 Set the real time clock offset in seconds. No offset (0) by
1692 default.
1693 vpt_align=BOOLEAN
1695 Specifies that periodic Virtual Platform Timers should be aligned
1696 to reduce guest interrupts. Enabling this option can reduce power
1697 consumption, especially when a guest uses a high timer interrupt
1698 frequency (HZ) values. The default is true (1).
1699 timer_mode="MODE"
1701 Specifies the mode for Virtual Timers. The valid values are as
1702 follows:
1703 delay_for_missed_ticks
1705 Delay for missed ticks. Do not advance a vCPU's time beyond the
1706 correct delivery time for interrupts that have been missed due
1707 to preemption. Deliver missed interrupts when the vCPU is
1708 rescheduled and advance the vCPU's virtual time stepwise for
1709 each one.
1710 no_delay_for_missed_ticks
1712 No delay for missed ticks. As above, missed interrupts are
1713 delivered, but guest time always tracks wallclock (i.e., real)
1714 time while doing so. This is the default.
1715 no_missed_ticks_pending
1717 No missed interrupts are held pending. Instead, to ensure ticks
1718 are delivered at some non-zero rate, if we detect missed ticks
1719 then the internal tick alarm is not disabled if the vCPU is
1720 preempted during the next tick period.
1721 one_missed_tick_pending
1723 One missed tick pending. Missed interrupts are collapsed
1724 together and delivered as one 'late tick'. Guest time always
1725 tracks wallclock (i.e., real) time.
1726 Memory layout
1728 mmio_hole=MBYTES
1730 Specifies the size the MMIO hole below 4GiB will be. Only valid
1731 for device_model_version="qemu-xen".
1732 Cannot be smaller than 256. Cannot be larger than 3840.
1734 Known good large value is 3072.
1736 Support for Paravirtualisation of HVM Guests
1738 The following options allow Paravirtualised features (such as devices)
1740 to be exposed to the guest Operating System in an HVM guest. Utilising
1741 these features requires specific guest support but when available they
1742 will result in improved performance.
1743 xen_platform_pci=BOOLEAN
1745 Enable or disable the Xen platform PCI device. The presence of
1746 this virtual device enables a guest Operating System (subject to
1747 the availability of suitable drivers) to make use of
1748 paravirtualisation features such as disk and network devices etc.
1749 Enabling these drivers improves performance and is strongly
1750 recommended when available. PV drivers are available for various
1751 Operating Systems including HVM Linux (out-of-the-box) and
1752 Microsoft Windows <https://xenproject.org/windows-pv-drivers/>.
1753 Setting xen_platform_pci=0 with the default device_model "qemu-xen"
1755 requires at least QEMU 1.6.
1756 viridian=[ "GROUP", "GROUP", ...] or viridian=BOOLEAN
1758 The groups of Microsoft Hyper-V (AKA viridian) compatible
1759 enlightenments exposed to the guest. The following groups of
1760 enlightenments may be specified:
1761 base
1763 This group incorporates the Hypercall MSRs, Virtual processor
1764 index MSR, and APIC access MSRs. These enlightenments can
1765 improve performance of Windows Vista and Windows Server 2008
1766 onwards and setting this option for such guests is strongly
1767 recommended. This group is also a pre-requisite for all
1768 others. If it is disabled then it is an error to attempt to
1769 enable any other group.
1770 freq
1772 This group incorporates the TSC and APIC frequency MSRs. These
1773 enlightenments can improve performance of Windows 7 and Windows
1774 Server 2008 R2 onwards.
1775 time_ref_count
1777 This group incorporates Partition Time Reference Counter MSR.
1778 This enlightenment can improve performance of Windows 8 and
1779 Windows Server 2012 onwards.
1780 reference_tsc
1782 This set incorporates the Partition Reference TSC MSR. This
1783 enlightenment can improve performance of Windows 7 and Windows
1784 Server 2008 R2 onwards.
1785 hcall_remote_tlb_flush
1787 This set incorporates use of hypercalls for remote TLB
1788 flushing. This enlightenment may improve performance of
1789 Windows guests running on hosts with higher levels of
1790 (physical) CPU contention.
1791 apic_assist
1793 This set incorporates use of the APIC assist page to avoid EOI
1794 of the local APIC. This enlightenment may improve performance
1795 of guests that make use of per-vCPU event channel upcall
1796 vectors. Note that this enlightenment will have no effect if
1797 the guest is using APICv posted interrupts.
1798 crash_ctl
1800 This group incorporates the crash control MSRs. These
1801 enlightenments allow Windows to write crash information such
1802 that it can be logged by Xen.
1803 stimer
1805 This set incorporates the SynIC and synthetic timer MSRs.
1806 Windows will use synthetic timers in preference to emulated
1807 HPET for a source of ticks and hence enabling this group will
1808 ensure that ticks will be consistent with use of an enlightened
1809 time source (time_ref_count or reference_tsc).
1810 hcall_ipi
1812 This set incorporates use of a hypercall for interprocessor
1813 interrupts. This enlightenment may improve performance of
1814 Windows guests with multiple virtual CPUs.
1815 ex_processor_masks
1817 This set enables new hypercall variants taking a variably-sized
1818 sparse Virtual Processor Set as an argument, rather than a
1819 simple 64-bit mask. Hence this enlightenment must be specified
1820 for guests with more than 64 vCPUs if hcall_remote_tlb_flush
1821 and/or hcall_ipi are also specified.
1822 no_vp_limit
1824 This group when set indicates to a guest that the hypervisor
1825 does not explicitly have any limits on the number of Virtual
1826 processors a guest is allowed to bring up. It is strongly
1827 recommended to keep this enabled for guests with more than 64
1828 vCPUs.
1829 cpu_hotplug
1831 This set enables dynamic changes to Virtual processor states in
1832 Windows guests effectively allowing vCPU hotplug.
1833 defaults
1835 This is a special value that enables the default set of groups,
1836 which is currently the base, freq, time_ref_count, apic_assist,
1837 crash_ctl, stimer, no_vp_limit and cpu_hotplug groups.
1838 all This is a special value that enables all available groups.
1840 Groups can be disabled by prefixing the name with '!'. So, for
1842 example, to enable all groups except freq, specify:
1843 viridian=[ "all", "!freq" ]
1845 For details of the enlightenments see the latest version of
1847 Microsoft's Hypervisor Top-Level Functional Specification.
1848 The enlightenments should be harmless for other versions of Windows
1850 (although they will not give any benefit) and the majority of other
1851 non-Windows OSes. However it is known that they are incompatible
1852 with some other Operating Systems and in some circumstance can
1853 prevent Xen's own paravirtualisation interfaces for HVM guests from
1854 being used.
1855 The viridian option can be specified as a boolean. A value of true
1857 (1) is equivalent to the list [ "defaults" ], and a value of false
1858 (0) is equivalent to an empty list.
1859 Emulated VGA Graphics Device
1861 The following options control the features of the emulated graphics
1863 device. Many of these options behave similarly to the equivalent key
1864 in the VFB_SPEC_STRING for configuring virtual frame buffer devices
1865 (see above).
1866 videoram=MBYTES
1868 Sets the amount of RAM which the emulated video card will contain,
1869 which in turn limits the resolutions and bit depths which will be
1870 available.
1871 When using the qemu-xen-traditional device-model, the default as
1873 well as minimum amount of video RAM for stdvga is 8 MB, which is
1874 sufficient for e.g. 1600x1200 at 32bpp. For the upstream qemu-xen
1875 device-model, the default and minimum is 16 MB.
1876 When using the emulated Cirrus graphics card (vga="cirrus") and the
1878 qemu-xen-traditional device-model, the amount of video RAM is fixed
1879 at 4 MB, which is sufficient for 1024x768 at 32 bpp. For the
1880 upstream qemu-xen device-model, the default and minimum is 8 MB.
1881 For QXL vga, both the default and minimal are 128MB. If videoram
1883 is set less than 128MB, an error will be triggered.
1884 stdvga=BOOLEAN
1886 Specifies a standard VGA card with VBE (VESA BIOS Extensions) as
1887 the emulated graphics device. If your guest supports VBE 2.0 or
1888 later (e.g. Windows XP onwards) then you should enable this.
1889 stdvga supports more video ram and bigger resolutions than Cirrus.
1890 The default is false (0) which means to emulate a Cirrus Logic
1891 GD5446 VGA card. This option is deprecated, use vga="stdvga"
1892 instead.
1893 vga="STRING"
1895 Selects the emulated video card. Options are: none, stdvga, cirrus
1896 and qxl. The default is cirrus.
1897 In general, QXL should work with the Spice remote display protocol
1899 for acceleration, and a QXL driver is necessary in the guest in
1900 that case. QXL can also work with the VNC protocol, but it will be
1901 like a standard VGA card without acceleration.
1902 vnc=BOOLEAN
1904 Allow access to the display via the VNC protocol. This enables the
1905 other VNC-related settings. The default is (1) enabled.
1906 vnclisten="ADDRESS[:DISPLAYNUM]"
1908 Specifies the IP address and, optionally, the VNC display number to
1909 use.
1910 vncdisplay=DISPLAYNUM
1912 Specifies the VNC display number to use. The actual TCP port number
1913 will be DISPLAYNUM+5900.
1914 vncunused=BOOLEAN
1916 Requests that the VNC display setup searches for a free TCP port to
1917 use. The actual display used can be accessed with xl vncviewer.
1918 vncpasswd="PASSWORD"
1920 Specifies the password for the VNC server. If the password is set
1921 to an empty string, authentication on the VNC server will be
1922 disabled allowing any user to connect.
1923 keymap="LANG"
1925 Configure the keymap to use for the keyboard associated with this
1926 display. If the input method does not easily support raw keycodes
1927 (e.g. this is often the case when using VNC) then this allows us to
1928 correctly map the input keys into keycodes seen by the guest. The
1929 specific values which are accepted are defined by the version of
1930 the device-model which you are using. See Keymaps below or consult
1931 the qemu(1) manpage. The default is en-us.
1932 sdl=BOOLEAN
1934 Specifies that the display should be presented via an X window
1935 (using Simple DirectMedia Layer). The default is (0) not enabled.
1936 opengl=BOOLEAN
1938 Enable OpenGL acceleration of the SDL display. Only effects
1939 machines using device_model_version="qemu-xen-traditional" and only
1940 if the device-model was compiled with OpenGL support. Default is
1941 (0) false.
1942 nographic=BOOLEAN
1944 Enable or disable the virtual graphics device. The default is to
1945 provide a VGA graphics device but this option can be used to
1946 disable it.
1947 Spice Graphics Support
1949 The following options control the features of SPICE.
1951 spice=BOOLEAN
1953 Allow access to the display via the SPICE protocol. This enables
1954 the other SPICE-related settings.
1955 spicehost="ADDRESS"
1957 Specifies the interface address to listen on if given, otherwise
1958 any interface.
1959 spiceport=NUMBER
1961 Specifies the port to listen on by the SPICE server if SPICE is
1962 enabled.
1963 spicetls_port=NUMBER
1965 Specifies the secure port to listen on by the SPICE server if SPICE
1966 is enabled. At least one of spiceport or spicetls_port must be
1967 given if SPICE is enabled.
1968 Note: the options depending on spicetls_port have not been
1970 supported.
1971 spicedisable_ticketing=BOOLEAN
1973 Enable clients to connect without specifying a password. When
1974 disabled, spicepasswd must be set. The default is (0) false.
1975 spicepasswd="PASSWORD"
1977 Specify the password which is used by clients for establishing a
1978 connection.
1979 spiceagent_mouse=BOOLEAN
1981 Whether SPICE agent is used for client mouse mode. The default is
1982 (1) true.
1983 spicevdagent=BOOLEAN
1985 Enables the SPICE vdagent. The SPICE vdagent is an optional
1986 component for enhancing user experience and performing guest-
1987 oriented management tasks. Its features include: client mouse mode
1988 (no need to grab the mouse by the client, no mouse lag), automatic
1989 adjustment of screen resolution, copy and paste (text and image)
1990 between the client and the guest. It also requires the vdagent
1991 service installed on the guest OS to work. The default is (0)
1992 disabled.
1993 spice_clipboard_sharing=BOOLEAN
1995 Enables SPICE clipboard sharing (copy/paste). It requires that
1996 spicevdagent is enabled. The default is (0) false.
1997 spiceusbredirection=NUMBER
1999 Enables SPICE USB redirection. Creates a NUMBER of USB redirection
2000 channels for redirecting up to 4 USB devices from the SPICE client
2001 to the guest's QEMU. It requires an USB controller and, if not
2002 defined, it will automatically add an USB2.0 controller. The
2003 default is (0) disabled.
2004 spice_image_compression="COMPRESSION"
2006 Specifies what image compression is to be used by SPICE (if given),
2007 otherwise the QEMU default will be used. Please see the
2008 documentation of your QEMU version for more details.
2009 Available options are: auto_glz, auto_lz, quic, glz, lz, off.
2011 spice_streaming_video="VIDEO"
2013 Specifies what streaming video setting is to be used by SPICE (if
2014 given), otherwise the QEMU default will be used.
2015 Available options are: filter, all, off.
2017 Miscellaneous Emulated Hardware
2019 serial=[ "DEVICE", "DEVICE", ...]
2021 Redirect virtual serial ports to DEVICEs. Please see the -serial
2022 option in the qemu(1) manpage for details of the valid DEVICE
2023 options. Default is vc when in graphical mode and stdio if
2024 nographic=1 is used.
2025 The form serial=DEVICE is also accepted for backwards
2027 compatibility.
2028 soundhw="DEVICE"
2030 Select the virtual sound card to expose to the guest. The valid
2031 devices are defined by the device model configuration, please see
2032 the qemu(1) manpage for details. The default is not to export any
2033 sound device.
2034 vkb_device=BOOLEAN
2036 Specifies that the HVM guest gets a vkdb. The default is true (1).
2037 usb=BOOLEAN
2039 Enables or disables an emulated USB bus in the guest.
2040 usbversion=NUMBER
2042 Specifies the type of an emulated USB bus in the guest, values 1
2043 for USB1.1, 2 for USB2.0 and 3 for USB3.0. It is available only
2044 with an upstream QEMU. Due to implementation limitations this is
2045 not compatible with the usb and usbdevice parameters. Default is
2046 (0) no USB controller defined.
2047 usbdevice=[ "DEVICE", "DEVICE", ...]
2049 Adds DEVICEs to the emulated USB bus. The USB bus must also be
2050 enabled using usb=1. The most common use for this option is
2051 usbdevice=['tablet'] which adds a pointer device using absolute
2052 coordinates. Such devices function better than relative coordinate
2053 devices (such as a standard mouse) since many methods of exporting
2054 guest graphics (such as VNC) work better in this mode. Note that
2055 this is independent of the actual pointer device you are using on
2056 the host/client side.
2057 Host devices can also be passed through in this way, by specifying
2059 host:USBID, where USBID is of the form xxxx:yyyy. The USBID can
2060 typically be found by using lsusb(1) or usb-devices(1).
2061 If you wish to use the "host:bus.addr" format, remove any leading
2063 '0' from the bus and addr. For example, for the USB device on bus
2064 008 dev 002, you should write "host:8.2".
2065 The form usbdevice=DEVICE is also accepted for backwards
2067 compatibility.
2068 More valid options can be found in the "usbdevice" section of the
2070 QEMU documentation.
2071 vendor_device="VENDOR_DEVICE"
2073 Selects which variant of the QEMU xen-pvdevice should be used for
2074 this guest. Valid values are:
2075 none
2077 The xen-pvdevice should be omitted. This is the default.
2078 xenserver
2080 The xenserver variant of the xen-pvdevice (device-id=C000) will
2081 be specified, enabling the use of XenServer PV drivers in the
2082 guest.
2083 This parameter only takes effect when
2085 device_model_version=qemu-xen. See xen-pci-device-reservations(7)
2086 for more information.
2087 PVH Guest Specific Options
2089 nestedhvm=BOOLEAN
2090 Enable or disables guest access to hardware virtualisation
2091 features, e.g. it allows a guest Operating System to also function
2092 as a hypervisor. You may want this option if you want to run
2093 another hypervisor (including another copy of Xen) within a Xen
2094 guest or to support a guest Operating System which uses hardware
2095 virtualisation extensions (e.g. Windows XP compatibility mode on
2096 more modern Windows OS).
2097 This option is disabled by default.
2099 bootloader="PROGRAM"
2101 Run "PROGRAM" to find the kernel image and ramdisk to use.
2102 Normally "PROGRAM" would be "pygrub", which is an emulation of
2103 grub/grub2/syslinux. Either kernel or bootloader must be specified
2104 for PV guests.
2105 bootloader_args=[ "ARG", "ARG", ...]
2107 Append ARGs to the arguments to the bootloader program.
2108 Alternatively if the argument is a simple string then it will be
2109 split into words at whitespace (this second option is deprecated).
2110 timer_mode="MODE"
2112 Specifies the mode for Virtual Timers. The valid values are as
2113 follows:
2114 delay_for_missed_ticks
2116 Delay for missed ticks. Do not advance a vCPU's time beyond the
2117 correct delivery time for interrupts that have been missed due
2118 to preemption. Deliver missed interrupts when the vCPU is
2119 rescheduled and advance the vCPU's virtual time stepwise for
2120 each one.
2121 no_delay_for_missed_ticks
2123 No delay for missed ticks. As above, missed interrupts are
2124 delivered, but guest time always tracks wallclock (i.e., real)
2125 time while doing so. This is the default.
2126 no_missed_ticks_pending
2128 No missed interrupts are held pending. Instead, to ensure ticks
2129 are delivered at some non-zero rate, if we detect missed ticks
2130 then the internal tick alarm is not disabled if the vCPU is
2131 preempted during the next tick period.
2132 one_missed_tick_pending
2134 One missed tick pending. Missed interrupts are collapsed
2135 together and delivered as one 'late tick'. Guest time always
2136 tracks wallclock (i.e., real) time.
2137 Paging
2139 The following options control the mechanisms used to virtualise guest
2141 memory. The defaults are selected to give the best results for the
2142 common cases so you should normally leave these options unspecified.
2143 hap=BOOLEAN
2145 Turns "hardware assisted paging" (the use of the hardware nested
2146 page table feature) on or off. This feature is called EPT
2147 (Extended Page Tables) by Intel and NPT (Nested Page Tables) or RVI
2148 (Rapid Virtualisation Indexing) by AMD. If turned off, Xen will run
2149 the guest in "shadow page table" mode where the guest's page table
2150 updates and/or TLB flushes etc. will be emulated. Use of HAP is
2151 the default when available.
2152 oos=BOOLEAN
2154 Turns "out of sync pagetables" on or off. When running in shadow
2155 page table mode, the guest's page table updates may be deferred as
2156 specified in the Intel/AMD architecture manuals. However, this may
2157 expose unexpected bugs in the guest, or find bugs in Xen, so it is
2158 possible to disable this feature. Use of out of sync page tables,
2159 when Xen thinks it appropriate, is the default.
2160 shadow_memory=MBYTES
2162 Number of megabytes to set aside for shadowing guest pagetable
2163 pages (effectively acting as a cache of translated pages) or to use
2164 for HAP state. By default this is 1MB per guest vCPU plus 8KB per
2165 MB of guest RAM. You should not normally need to adjust this value.
2166 However, if you are not using hardware assisted paging (i.e. you
2167 are using shadow mode) and your guest workload consists of a very
2168 large number of similar processes then increasing this value may
2169 improve performance.
2170 Device-Model Options
2172 The following options control the selection of the device-model. This
2173 is the component which provides emulation of the virtual devices to an
2174 HVM guest. For a PV guest a device-model is sometimes used to provide
2175 backends for certain PV devices (most usually a virtual framebuffer
2176 device).
2177 device_model_version="DEVICE-MODEL"
2179 Selects which variant of the device-model should be used for this
2180 guest.
2181 Valid values are:
2183 qemu-xen
2185 Use the device-model merged into the upstream QEMU project.
2186 This device-model is the default for Linux dom0.
2187 qemu-xen-traditional
2189 Use the device-model based upon the historical Xen fork of
2190 QEMU. This device-model is still the default for NetBSD dom0.
2191 It is recommended to accept the default value for new guests. If
2193 you have existing guests then, depending on the nature of the guest
2194 Operating System, you may wish to force them to use the device
2195 model which they were installed with.
2196 device_model_override="PATH"
2198 Override the path to the binary to be used as the device-model
2199 running in toolstack domain. The binary provided here MUST be
2200 consistent with the device_model_version which you have specified.
2201 You should not normally need to specify this option.
2202 stubdomain_kernel="PATH"
2204 Override the path to the kernel image used as device-model
2205 stubdomain. The binary provided here MUST be consistent with the
2206 device_model_version which you have specified. In case of qemu-
2207 xen-traditional it is expected to be MiniOS-based stubdomain image,
2208 in case of qemu-xen it is expected to be Linux-based stubdomain
2209 kernel.
2210 stubdomain_ramdisk="PATH"
2212 Override the path to the ramdisk image used as device-model
2213 stubdomain. The binary provided here is to be used by a kernel
2214 pointed by stubdomain_kernel. It is known to be used only by
2215 Linux-based stubdomain kernel.
2216 stubdomain_memory=MBYTES
2218 Start the stubdomain with MBYTES megabytes of RAM. Default is 128.
2219 device_model_stubdomain_override=BOOLEAN
2221 Override the use of stubdomain based device-model. Normally this
2222 will be automatically selected based upon the other features and
2223 options you have selected.
2224 device_model_stubdomain_seclabel="LABEL"
2226 Assign an XSM security label to the device-model stubdomain.
2227 device_model_args=[ "ARG", "ARG", ...]
2229 Pass additional arbitrary options on the device-model command line.
2230 Each element in the list is passed as an option to the device-
2231 model.
2232 device_model_args_pv=[ "ARG", "ARG", ...]
2234 Pass additional arbitrary options on the device-model command line
2235 for a PV device model only. Each element in the list is passed as
2236 an option to the device-model.
2237 device_model_args_hvm=[ "ARG", "ARG", ...]
2239 Pass additional arbitrary options on the device-model command line
2240 for an HVM device model only. Each element in the list is passed as
2241 an option to the device-model.
2242 Keymaps
2244 The keymaps available are defined by the device-model which you are
2245 using. Commonly this includes:
2246 ar de-ch es fo fr-ca hu ja mk no pt-br sv
2248 da en-gb et fr fr-ch is lt nl pl ru th
2249 de en-us fi fr-be hr it lv nl-be pt sl tr
2250 The default is en-us.
2252 See qemu(1) for more information.
2254 Architecture Specific options
2256 ARM
2257 gic_version="vN"
2259 Version of the GIC emulated for the guest.
2260 Currently, the following versions are supported:
2262 v2 Emulate a GICv2
2264 v3 Emulate a GICv3. Note that the emulated GIC does not support
2266 the GICv2 compatibility mode.
2267 default
2269 Emulate the same version as the native GIC hardware used by the
2270 host where the domain was created.
2271 This requires hardware compatibility with the requested version,
2273 either natively or via hardware backwards compatibility support.
2274 vuart="uart"
2276 To enable vuart console, user must specify the following option in
2277 the VM config file:
2278 vuart = "sbsa_uart"
2280 Currently, only the "sbsa_uart" model is supported for ARM.
2282 x86
2284 mca_caps=[ "CAP", "CAP", ... ]
2286 (HVM only) Enable MCA capabilities besides default ones enabled by
2287 Xen hypervisor for the HVM domain. "CAP" can be one in the
2288 following list:
2289 "lmce"
2291 Intel local MCE
2292 default
2294 No MCA capabilities in above list are enabled.
2295 msr_relaxed=BOOLEAN
2297 The "msr_relaxed" boolean is an interim option, and defaults to
2298 false.
2299 In Xen 4.15, the default behaviour for unhandled MSRs has been
2301 changed, to avoid leaking host data into guests, and to avoid
2302 breaking guest logic which uses #GP probing to identify the
2303 availability of MSRs.
2304 However, this new stricter behaviour has the possibility to break
2306 guests, and a more 4.14-like behaviour can be selected by setting
2307 this option.
2308 If using this option is necessary to fix an issue, please report a
2310 bug.
2311
2313 xl(1)
2314 xl.conf(5)
2315 xlcpupool.cfg(5)
2316 xl-disk-configuration(5)
2317 xl-network-configuration(5)
2318 xen-tscmode(7)
2319
2321 /etc/xen/NAME.cfg /var/lib/xen/dump/NAME
2322
2324 This document may contain items which require further documentation.
2325 Patches to improve incomplete items (or any other item) are gratefully
2326 received on the xen-devel@lists.xenproject.org mailing list. Please see
2327 <https://wiki.xenproject.org/wiki/Submitting_Xen_Project_Patches> for
2328 information on how to submit a patch to Xen.
23294.15.1 2021-11-23 xl.cfg(5)