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 On Arm, this field is used to determine the size of the guest P2M
1408 pages pool, and the default value is 1MB per vCPU plus 4KB per MB
1409 of RAM for the P2M map and additional 512KB for extended regions.
1410 Users should adjust this value if bigger P2M pool size is needed.
1411 Processor and Platform Features
1413 The following options allow various processor and platform level
1415 features to be hidden or exposed from the guest's point of view. This
1416 can be useful when running older guest Operating Systems which may
1417 misbehave when faced with more modern features. In general, you should
1418 accept the defaults for these options wherever possible.
1419 bios="STRING"
1421 Select the virtual firmware that is exposed to the guest. By
1422 default, a guess is made based on the device model, but sometimes
1423 it may be useful to request a different one, like UEFI.
1424 rombios
1426 Loads ROMBIOS, a 16-bit x86 compatible BIOS. This is used by
1427 default when device_model_version=qemu-xen-traditional. This is
1428 the only BIOS option supported when
1429 device_model_version=qemu-xen-traditional. This is the BIOS
1430 used by all previous Xen versions.
1431 seabios
1433 Loads SeaBIOS, a 16-bit x86 compatible BIOS. This is used by
1434 default with device_model_version=qemu-xen.
1435 ovmf
1437 Loads OVMF, a standard UEFI firmware by Tianocore project.
1438 Requires device_model_version=qemu-xen.
1439 bios_path_override="PATH"
1441 Override the path to the blob to be used as BIOS. The blob provided
1442 here MUST be consistent with the bios= which you have specified.
1443 You should not normally need to specify this option.
1444 This option does not have any effect if using bios="rombios" or
1446 device_model_version="qemu-xen-traditional".
1447 pae=BOOLEAN
1449 Hide or expose the IA32 Physical Address Extensions. These
1450 extensions make it possible for a 32 bit guest Operating System to
1451 access more than 4GB of RAM. Enabling PAE also enabled other
1452 features such as NX. PAE is required if you wish to run a 64-bit
1453 guest Operating System. In general, you should leave this enabled
1454 and allow the guest Operating System to choose whether or not to
1455 use PAE. (X86 only)
1456 acpi=BOOLEAN
1458 Expose ACPI (Advanced Configuration and Power Interface) tables
1459 from the virtual firmware to the guest Operating System. ACPI is
1460 required by most modern guest Operating Systems. This option is
1461 enabled by default and usually you should omit it. However, it may
1462 be necessary to disable ACPI for compatibility with some guest
1463 Operating Systems. This option is true for x86 while it's false
1464 for ARM by default.
1465 acpi_s3=BOOLEAN
1467 Include the S3 (suspend-to-ram) power state in the virtual firmware
1468 ACPI table. True (1) by default.
1469 acpi_s4=BOOLEAN
1471 Include S4 (suspend-to-disk) power state in the virtual firmware
1472 ACPI table. True (1) by default.
1473 acpi_laptop_slate=BOOLEAN
1475 Include the Windows laptop/slate mode switch device in the virtual
1476 firmware ACPI table. False (0) by default.
1477 apic=BOOLEAN
1479 (x86 only) Include information regarding APIC (Advanced
1480 Programmable Interrupt Controller) in the firmware/BIOS tables on a
1481 single processor guest. This causes the MP (multiprocessor) and PIR
1482 (PCI Interrupt Routing) tables to be exported by the virtual
1483 firmware. This option has no effect on a guest with multiple
1484 virtual CPUs as they must always include these tables. This option
1485 is enabled by default and you should usually omit it but it may be
1486 necessary to disable these firmware tables when using certain older
1487 guest Operating Systems. These tables have been superseded by newer
1488 constructs within the ACPI tables.
1489 nx=BOOLEAN
1491 (x86 only) Hides or exposes the No-eXecute capability. This allows
1492 a guest Operating System to map pages in such a way that they
1493 cannot be executed which can enhance security. This options
1494 requires that PAE also be enabled.
1495 hpet=BOOLEAN
1497 (x86 only) Enables or disables HPET (High Precision Event Timer).
1498 This option is enabled by default and you should usually omit it.
1499 It may be necessary to disable the HPET in order to improve
1500 compatibility with guest Operating Systems.
1501 altp2m="MODE"
1503 (x86 only) Specifies the access mode to the alternate-p2m
1504 capability. Alternate-p2m allows a guest to manage multiple p2m
1505 guest physical "memory views" (as opposed to a single p2m). You
1506 may want this option if you want to access-control/isolate access
1507 to specific guest physical memory pages accessed by the guest, e.g.
1508 for domain memory introspection or for isolation/access-control of
1509 memory between components within a single guest domain. This option
1510 is disabled by default.
1511 The valid values are as follows:
1513 disabled
1515 Altp2m is disabled for the domain (default).
1516 mixed
1518 The mixed mode allows access to the altp2m interface for both
1519 in-guest and external tools as well.
1520 external
1522 Enables access to the alternate-p2m capability by external
1523 privileged tools.
1524 limited
1526 Enables limited access to the alternate-p2m capability, ie.
1527 giving the guest access only to enable/disable the VMFUNC and
1528 #VE features.
1529 altp2mhvm=BOOLEAN
1531 Enables or disables HVM guest access to alternate-p2m capability.
1532 Alternate-p2m allows a guest to manage multiple p2m guest physical
1533 "memory views" (as opposed to a single p2m). This option is
1534 disabled by default and is available only to HVM domains. You may
1535 want this option if you want to access-control/isolate access to
1536 specific guest physical memory pages accessed by the guest, e.g.
1537 for HVM domain memory introspection or for isolation/access-control
1538 of memory between components within a single guest HVM domain. This
1539 option is deprecated, use the option "altp2m" instead.
1540 Note: While the option "altp2mhvm" is deprecated, legacy
1542 applications for x86 systems will continue to work using it.
1543 nestedhvm=BOOLEAN
1545 Enable or disables guest access to hardware virtualisation
1546 features, e.g. it allows a guest Operating System to also function
1547 as a hypervisor. You may want this option if you want to run
1548 another hypervisor (including another copy of Xen) within a Xen
1549 guest or to support a guest Operating System which uses hardware
1550 virtualisation extensions (e.g. Windows XP compatibility mode on
1551 more modern Windows OS). This option is disabled by default.
1552 cpuid="LIBXL_STRING" or cpuid=[ "XEND_STRING", "XEND_STRING" ]
1554 Configure the value returned when a guest executes the CPUID
1555 instruction. Two versions of config syntax are recognized: libxl
1556 and xend.
1557 Both formats use a common notation for specifying a single feature
1559 bit. Possible values are:
1560 '1' -> force the corresponding bit to 1
1561 '0' -> force to 0
1562 'x' -> Get a safe value (pass through and mask with the default
1563 policy)
1564 'k' -> pass through the host bit value (at boot only - value
1565 preserved on migrate)
1566 's' -> legacy alias for 'k'
1567 Libxl format:
1569 The libxl format is a single string, starting with the word
1571 "host", and followed by a comma separated list of key=value
1572 pairs. A few keys take a numerical value, all others take a
1573 single character which describes what to do with the feature
1574 bit. e.g.:
1575 cpuid="host,tm=0,sse3=0"
1577 List of keys taking a value:
1579 apicidsize brandid clflush family localapicid maxleaf
1581 maxhvleaf model nc proccount procpkg stepping
1582 List of keys taking a character:
1584 3dnow 3dnowext 3dnowprefetch abm acpi adx aes altmovcr8
1586 apic arat avx avx2 avx512-4fmaps avx512-4vnniw avx512bw
1587 avx512cd avx512dq avx512er avx512f avx512ifma avx512pf
1588 avx512vbmi avx512vl bmi1 bmi2 clflushopt clfsh clwb cmov
1589 cmplegacy cmpxchg16 cmpxchg8 cmt cntxid dca de ds dscpl
1590 dtes64 erms est extapic f16c ffxsr fma fma4 fpu fsgsbase
1591 fxsr hle htt hypervisor ia64 ibs invpcid invtsc lahfsahf lm
1592 lwp mca mce misalignsse mmx mmxext monitor movbe mpx msr
1593 mtrr nodeid nx ospke osvw osxsave pae page1gb pat pbe pcid
1594 pclmulqdq pdcm perfctr_core perfctr_nb pge pku popcnt pse
1595 pse36 psn rdrand rdseed rdtscp rtm sha skinit smap smep smx
1596 ss sse sse2 sse3 sse4.1 sse4.2 sse4_1 sse4_2 sse4a ssse3
1597 svm svm_decode svm_lbrv svm_npt svm_nrips svm_pausefilt
1598 svm_tscrate svm_vmcbclean syscall sysenter tbm tm tm2
1599 topoext tsc tsc-deadline tsc_adjust umip vme vmx wdt x2apic
1600 xop xsave xtpr
1601 Xend format:
1603 Xend format consists of an array of one or more strings of the
1605 form "leaf:reg=bitstring,...". e.g. (matching the libxl
1606 example above):
1607 cpuid=["1:ecx=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx0,edx=xx0xxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
1609 ...]
1610 "leaf" is an integer, either decimal or hex with a "0x" prefix.
1612 e.g. to specify something in the AMD feature leaves, use
1613 "0x80000001:ecx=...".
1614 Some leaves have subleaves which can be specified as
1616 "leaf,subleaf". e.g. for the Intel structured feature leaf,
1617 use "7,0:ebx=..."
1618 The bitstring represents all bits in the register, its length
1620 must be 32 chars. Each successive character represent a
1621 lesser-significant bit.
1622 Note: when specifying cpuid for hypervisor leaves (0x4000xxxx major
1624 group) only the lowest 8 bits of leaf's 0x4000xx00 EAX register are
1625 processed, the rest are ignored (these 8 bits signify maximum
1626 number of hypervisor leaves).
1627 More info about the CPUID instruction can be found in the processor
1629 manuals, and on Wikipedia: <https://en.wikipedia.org/wiki/CPUID>
1630 acpi_firmware="STRING"
1632 Specifies a path to a file that contains extra ACPI firmware tables
1633 to pass into a guest. The file can contain several tables in their
1634 binary AML form concatenated together. Each table self describes
1635 its length so no additional information is needed. These tables
1636 will be added to the ACPI table set in the guest. Note that
1637 existing tables cannot be overridden by this feature. For example,
1638 this cannot be used to override tables like DSDT, FADT, etc.
1639 smbios_firmware="STRING"
1641 Specifies a path to a file that contains extra SMBIOS firmware
1642 structures to pass into a guest. The file can contain a set of DMTF
1643 predefined structures which will override the internal defaults.
1644 Not all predefined structures can be overridden, only the following
1645 types: 0, 1, 2, 3, 11, 22, 39. The file can also contain any number
1646 of vendor defined SMBIOS structures (type 128 - 255). Since SMBIOS
1647 structures do not present their overall size, each entry in the
1648 file must be preceded by a 32b integer indicating the size of the
1649 following structure.
1650 ms_vm_genid="OPTION"
1652 Provide a VM generation ID to the guest.
1653 The VM generation ID is a 128-bit random number that a guest may
1655 use to determine if the guest has been restored from an earlier
1656 snapshot or cloned.
1657 This is required for Microsoft Windows Server 2012 (and later)
1659 domain controllers.
1660 Valid options are:
1662 generate
1664 Generate a random VM generation ID every time the domain is
1665 created or restored.
1666 none
1668 Do not provide a VM generation ID.
1669 See also "Virtual Machine Generation ID" by Microsoft:
1671 <https://docs.microsoft.com/en-us/windows/win32/hyperv_v2/virtual-machine-generation-identifier>
1672 Guest Virtual Time Controls
1674 tsc_mode="MODE"
1676 (x86 only) Specifies how the TSC (Time Stamp Counter) should be
1677 provided to the guest. Specifying this option as a number is
1678 deprecated.
1679 Options are:
1681 default
1683 Guest rdtsc/p is executed natively when monotonicity can be
1684 guaranteed and emulated otherwise (with frequency scaled if
1685 necessary).
1686 If a HVM container in default TSC mode is created on a host
1688 that provides constant host TSC, its guest TSC frequency will
1689 be the same as the host. If it is later migrated to another
1690 host that provide constant host TSC and supports Intel VMX TSC
1691 scaling/AMD SVM TSC ratio, its guest TSC frequency will be the
1692 same before and after migration, and guest rdtsc/p will be
1693 executed natively after migration as well
1694 always_emulate
1696 Guest rdtsc/p is always emulated and the virtual TSC will
1697 appear to increment (kernel and user) at a fixed 1GHz rate,
1698 regardless of the pCPU HZ rate or power state. Although there
1699 is an overhead associated with emulation, this will NOT affect
1700 underlying CPU performance.
1701 native
1703 Guest rdtsc/p is always executed natively (no
1704 monotonicity/frequency guarantees). Guest rdtsc/p is emulated
1705 at native frequency if unsupported by h/w, else executed
1706 natively.
1707 native_paravirt
1709 This mode has been removed.
1710 Please see xen-tscmode(7) for more information on this option.
1712 localtime=BOOLEAN
1714 Set the real time clock to local time or to UTC. False (0) by
1715 default, i.e. set to UTC.
1716 rtc_timeoffset=SECONDS
1718 Set the real time clock offset in seconds. No offset (0) by
1719 default.
1720 vpt_align=BOOLEAN
1722 Specifies that periodic Virtual Platform Timers should be aligned
1723 to reduce guest interrupts. Enabling this option can reduce power
1724 consumption, especially when a guest uses a high timer interrupt
1725 frequency (HZ) values. The default is true (1).
1726 timer_mode="MODE"
1728 Specifies the mode for Virtual Timers. The valid values are as
1729 follows:
1730 delay_for_missed_ticks
1732 Delay for missed ticks. Do not advance a vCPU's time beyond the
1733 correct delivery time for interrupts that have been missed due
1734 to preemption. Deliver missed interrupts when the vCPU is
1735 rescheduled and advance the vCPU's virtual time stepwise for
1736 each one.
1737 no_delay_for_missed_ticks
1739 No delay for missed ticks. As above, missed interrupts are
1740 delivered, but guest time always tracks wallclock (i.e., real)
1741 time while doing so. This is the default.
1742 no_missed_ticks_pending
1744 No missed interrupts are held pending. Instead, to ensure ticks
1745 are delivered at some non-zero rate, if we detect missed ticks
1746 then the internal tick alarm is not disabled if the vCPU is
1747 preempted during the next tick period.
1748 one_missed_tick_pending
1750 One missed tick pending. Missed interrupts are collapsed
1751 together and delivered as one 'late tick'. Guest time always
1752 tracks wallclock (i.e., real) time.
1753 Memory layout
1755 mmio_hole=MBYTES
1757 Specifies the size the MMIO hole below 4GiB will be. Only valid
1758 for device_model_version="qemu-xen".
1759 Cannot be smaller than 256. Cannot be larger than 3840.
1761 Known good large value is 3072.
1763 Support for Paravirtualisation of HVM Guests
1765 The following options allow Paravirtualised features (such as devices)
1767 to be exposed to the guest Operating System in an HVM guest. Utilising
1768 these features requires specific guest support but when available they
1769 will result in improved performance.
1770 xen_platform_pci=BOOLEAN
1772 Enable or disable the Xen platform PCI device. The presence of
1773 this virtual device enables a guest Operating System (subject to
1774 the availability of suitable drivers) to make use of
1775 paravirtualisation features such as disk and network devices etc.
1776 Enabling these drivers improves performance and is strongly
1777 recommended when available. PV drivers are available for various
1778 Operating Systems including HVM Linux (out-of-the-box) and
1779 Microsoft Windows <https://xenproject.org/windows-pv-drivers/>.
1780 Setting xen_platform_pci=0 with the default device_model "qemu-xen"
1782 requires at least QEMU 1.6.
1783 viridian=[ "GROUP", "GROUP", ...] or viridian=BOOLEAN
1785 The groups of Microsoft Hyper-V (AKA viridian) compatible
1786 enlightenments exposed to the guest. The following groups of
1787 enlightenments may be specified:
1788 base
1790 This group incorporates the Hypercall MSRs, Virtual processor
1791 index MSR, and APIC access MSRs. These enlightenments can
1792 improve performance of Windows Vista and Windows Server 2008
1793 onwards and setting this option for such guests is strongly
1794 recommended. This group is also a pre-requisite for all
1795 others. If it is disabled then it is an error to attempt to
1796 enable any other group.
1797 freq
1799 This group incorporates the TSC and APIC frequency MSRs. These
1800 enlightenments can improve performance of Windows 7 and Windows
1801 Server 2008 R2 onwards.
1802 time_ref_count
1804 This group incorporates Partition Time Reference Counter MSR.
1805 This enlightenment can improve performance of Windows 8 and
1806 Windows Server 2012 onwards.
1807 reference_tsc
1809 This set incorporates the Partition Reference TSC MSR. This
1810 enlightenment can improve performance of Windows 7 and Windows
1811 Server 2008 R2 onwards.
1812 hcall_remote_tlb_flush
1814 This set incorporates use of hypercalls for remote TLB
1815 flushing. This enlightenment may improve performance of
1816 Windows guests running on hosts with higher levels of
1817 (physical) CPU contention.
1818 apic_assist
1820 This set incorporates use of the APIC assist page to avoid EOI
1821 of the local APIC. This enlightenment may improve performance
1822 of guests that make use of per-vCPU event channel upcall
1823 vectors. Note that this enlightenment will have no effect if
1824 the guest is using APICv posted interrupts.
1825 crash_ctl
1827 This group incorporates the crash control MSRs. These
1828 enlightenments allow Windows to write crash information such
1829 that it can be logged by Xen.
1830 stimer
1832 This set incorporates the SynIC and synthetic timer MSRs.
1833 Windows will use synthetic timers in preference to emulated
1834 HPET for a source of ticks and hence enabling this group will
1835 ensure that ticks will be consistent with use of an enlightened
1836 time source (time_ref_count or reference_tsc).
1837 hcall_ipi
1839 This set incorporates use of a hypercall for interprocessor
1840 interrupts. This enlightenment may improve performance of
1841 Windows guests with multiple virtual CPUs.
1842 ex_processor_masks
1844 This set enables new hypercall variants taking a variably-sized
1845 sparse Virtual Processor Set as an argument, rather than a
1846 simple 64-bit mask. Hence this enlightenment must be specified
1847 for guests with more than 64 vCPUs if hcall_remote_tlb_flush
1848 and/or hcall_ipi are also specified.
1849 no_vp_limit
1851 This group when set indicates to a guest that the hypervisor
1852 does not explicitly have any limits on the number of Virtual
1853 processors a guest is allowed to bring up. It is strongly
1854 recommended to keep this enabled for guests with more than 64
1855 vCPUs.
1856 cpu_hotplug
1858 This set enables dynamic changes to Virtual processor states in
1859 Windows guests effectively allowing vCPU hotplug.
1860 defaults
1862 This is a special value that enables the default set of groups,
1863 which is currently the base, freq, time_ref_count, apic_assist,
1864 crash_ctl, stimer, no_vp_limit and cpu_hotplug groups.
1865 all This is a special value that enables all available groups.
1867 Groups can be disabled by prefixing the name with '!'. So, for
1869 example, to enable all groups except freq, specify:
1870 viridian=[ "all", "!freq" ]
1872 For details of the enlightenments see the latest version of
1874 Microsoft's Hypervisor Top-Level Functional Specification.
1875 The enlightenments should be harmless for other versions of Windows
1877 (although they will not give any benefit) and the majority of other
1878 non-Windows OSes. However it is known that they are incompatible
1879 with some other Operating Systems and in some circumstance can
1880 prevent Xen's own paravirtualisation interfaces for HVM guests from
1881 being used.
1882 The viridian option can be specified as a boolean. A value of true
1884 (1) is equivalent to the list [ "defaults" ], and a value of false
1885 (0) is equivalent to an empty list.
1886 Emulated VGA Graphics Device
1888 The following options control the features of the emulated graphics
1890 device. Many of these options behave similarly to the equivalent key
1891 in the VFB_SPEC_STRING for configuring virtual frame buffer devices
1892 (see above).
1893 videoram=MBYTES
1895 Sets the amount of RAM which the emulated video card will contain,
1896 which in turn limits the resolutions and bit depths which will be
1897 available.
1898 When using the qemu-xen-traditional device-model, the default as
1900 well as minimum amount of video RAM for stdvga is 8 MB, which is
1901 sufficient for e.g. 1600x1200 at 32bpp. For the upstream qemu-xen
1902 device-model, the default and minimum is 16 MB.
1903 When using the emulated Cirrus graphics card (vga="cirrus") and the
1905 qemu-xen-traditional device-model, the amount of video RAM is fixed
1906 at 4 MB, which is sufficient for 1024x768 at 32 bpp. For the
1907 upstream qemu-xen device-model, the default and minimum is 8 MB.
1908 For QXL vga, both the default and minimal are 128MB. If videoram
1910 is set less than 128MB, an error will be triggered.
1911 stdvga=BOOLEAN
1913 Specifies a standard VGA card with VBE (VESA BIOS Extensions) as
1914 the emulated graphics device. If your guest supports VBE 2.0 or
1915 later (e.g. Windows XP onwards) then you should enable this.
1916 stdvga supports more video ram and bigger resolutions than Cirrus.
1917 The default is false (0) which means to emulate a Cirrus Logic
1918 GD5446 VGA card. This option is deprecated, use vga="stdvga"
1919 instead.
1920 vga="STRING"
1922 Selects the emulated video card. Options are: none, stdvga, cirrus
1923 and qxl. The default is cirrus.
1924 In general, QXL should work with the Spice remote display protocol
1926 for acceleration, and a QXL driver is necessary in the guest in
1927 that case. QXL can also work with the VNC protocol, but it will be
1928 like a standard VGA card without acceleration.
1929 vnc=BOOLEAN
1931 Allow access to the display via the VNC protocol. This enables the
1932 other VNC-related settings. The default is (1) enabled.
1933 vnclisten="ADDRESS[:DISPLAYNUM]"
1935 Specifies the IP address and, optionally, the VNC display number to
1936 use.
1937 vncdisplay=DISPLAYNUM
1939 Specifies the VNC display number to use. The actual TCP port number
1940 will be DISPLAYNUM+5900.
1941 vncunused=BOOLEAN
1943 Requests that the VNC display setup searches for a free TCP port to
1944 use. The actual display used can be accessed with xl vncviewer.
1945 vncpasswd="PASSWORD"
1947 Specifies the password for the VNC server. If the password is set
1948 to an empty string, authentication on the VNC server will be
1949 disabled allowing any user to connect.
1950 keymap="LANG"
1952 Configure the keymap to use for the keyboard associated with this
1953 display. If the input method does not easily support raw keycodes
1954 (e.g. this is often the case when using VNC) then this allows us to
1955 correctly map the input keys into keycodes seen by the guest. The
1956 specific values which are accepted are defined by the version of
1957 the device-model which you are using. See Keymaps below or consult
1958 the qemu(1) manpage. The default is en-us.
1959 sdl=BOOLEAN
1961 Specifies that the display should be presented via an X window
1962 (using Simple DirectMedia Layer). The default is (0) not enabled.
1963 opengl=BOOLEAN
1965 Enable OpenGL acceleration of the SDL display. Only effects
1966 machines using device_model_version="qemu-xen-traditional" and only
1967 if the device-model was compiled with OpenGL support. Default is
1968 (0) false.
1969 nographic=BOOLEAN
1971 Enable or disable the virtual graphics device. The default is to
1972 provide a VGA graphics device but this option can be used to
1973 disable it.
1974 Spice Graphics Support
1976 The following options control the features of SPICE.
1978 spice=BOOLEAN
1980 Allow access to the display via the SPICE protocol. This enables
1981 the other SPICE-related settings.
1982 spicehost="ADDRESS"
1984 Specifies the interface address to listen on if given, otherwise
1985 any interface.
1986 spiceport=NUMBER
1988 Specifies the port to listen on by the SPICE server if SPICE is
1989 enabled.
1990 spicetls_port=NUMBER
1992 Specifies the secure port to listen on by the SPICE server if SPICE
1993 is enabled. At least one of spiceport or spicetls_port must be
1994 given if SPICE is enabled.
1995 Note: the options depending on spicetls_port have not been
1997 supported.
1998 spicedisable_ticketing=BOOLEAN
2000 Enable clients to connect without specifying a password. When
2001 disabled, spicepasswd must be set. The default is (0) false.
2002 spicepasswd="PASSWORD"
2004 Specify the password which is used by clients for establishing a
2005 connection.
2006 spiceagent_mouse=BOOLEAN
2008 Whether SPICE agent is used for client mouse mode. The default is
2009 (1) true.
2010 spicevdagent=BOOLEAN
2012 Enables the SPICE vdagent. The SPICE vdagent is an optional
2013 component for enhancing user experience and performing guest-
2014 oriented management tasks. Its features include: client mouse mode
2015 (no need to grab the mouse by the client, no mouse lag), automatic
2016 adjustment of screen resolution, copy and paste (text and image)
2017 between the client and the guest. It also requires the vdagent
2018 service installed on the guest OS to work. The default is (0)
2019 disabled.
2020 spice_clipboard_sharing=BOOLEAN
2022 Enables SPICE clipboard sharing (copy/paste). It requires that
2023 spicevdagent is enabled. The default is (0) false.
2024 spiceusbredirection=NUMBER
2026 Enables SPICE USB redirection. Creates a NUMBER of USB redirection
2027 channels for redirecting up to 4 USB devices from the SPICE client
2028 to the guest's QEMU. It requires an USB controller and, if not
2029 defined, it will automatically add an USB2.0 controller. The
2030 default is (0) disabled.
2031 spice_image_compression="COMPRESSION"
2033 Specifies what image compression is to be used by SPICE (if given),
2034 otherwise the QEMU default will be used. Please see the
2035 documentation of your QEMU version for more details.
2036 Available options are: auto_glz, auto_lz, quic, glz, lz, off.
2038 spice_streaming_video="VIDEO"
2040 Specifies what streaming video setting is to be used by SPICE (if
2041 given), otherwise the QEMU default will be used.
2042 Available options are: filter, all, off.
2044 Miscellaneous Emulated Hardware
2046 serial=[ "DEVICE", "DEVICE", ...]
2048 Redirect virtual serial ports to DEVICEs. Please see the -serial
2049 option in the qemu(1) manpage for details of the valid DEVICE
2050 options. Default is vc when in graphical mode and stdio if
2051 nographic=1 is used.
2052 The form serial=DEVICE is also accepted for backwards
2054 compatibility.
2055 soundhw="DEVICE"
2057 Select the virtual sound card to expose to the guest. The valid
2058 devices are hda, ac97, es1370, adlib, cs4231a, gus, sb16 if there
2059 are available with the device model QEMU. The default is not to
2060 export any sound device.
2061 vkb_device=BOOLEAN
2063 Specifies that the HVM guest gets a vkdb. The default is true (1).
2064 usb=BOOLEAN
2066 Enables or disables an emulated USB bus in the guest.
2067 usbversion=NUMBER
2069 Specifies the type of an emulated USB bus in the guest, values 1
2070 for USB1.1, 2 for USB2.0 and 3 for USB3.0. It is available only
2071 with an upstream QEMU. Due to implementation limitations this is
2072 not compatible with the usb and usbdevice parameters. Default is
2073 (0) no USB controller defined.
2074 usbdevice=[ "DEVICE", "DEVICE", ...]
2076 Adds DEVICEs to the emulated USB bus. The USB bus must also be
2077 enabled using usb=1. The most common use for this option is
2078 usbdevice=['tablet'] which adds a pointer device using absolute
2079 coordinates. Such devices function better than relative coordinate
2080 devices (such as a standard mouse) since many methods of exporting
2081 guest graphics (such as VNC) work better in this mode. Note that
2082 this is independent of the actual pointer device you are using on
2083 the host/client side.
2084 Host devices can also be passed through in this way, by specifying
2086 host:USBID, where USBID is of the form xxxx:yyyy. The USBID can
2087 typically be found by using lsusb(1) or usb-devices(1).
2088 If you wish to use the "host:bus.addr" format, remove any leading
2090 '0' from the bus and addr. For example, for the USB device on bus
2091 008 dev 002, you should write "host:8.2".
2092 The form usbdevice=DEVICE is also accepted for backwards
2094 compatibility.
2095 More valid options can be found in the "usbdevice" section of the
2097 QEMU documentation.
2098 vendor_device="VENDOR_DEVICE"
2100 Selects which variant of the QEMU xen-pvdevice should be used for
2101 this guest. Valid values are:
2102 none
2104 The xen-pvdevice should be omitted. This is the default.
2105 xenserver
2107 The xenserver variant of the xen-pvdevice (device-id=C000) will
2108 be specified, enabling the use of XenServer PV drivers in the
2109 guest.
2110 This parameter only takes effect when
2112 device_model_version=qemu-xen. See xen-pci-device-reservations(7)
2113 for more information.
2114 PVH Guest Specific Options
2116 nestedhvm=BOOLEAN
2117 Enable or disables guest access to hardware virtualisation
2118 features, e.g. it allows a guest Operating System to also function
2119 as a hypervisor. You may want this option if you want to run
2120 another hypervisor (including another copy of Xen) within a Xen
2121 guest or to support a guest Operating System which uses hardware
2122 virtualisation extensions (e.g. Windows XP compatibility mode on
2123 more modern Windows OS).
2124 This option is disabled by default.
2126 bootloader="PROGRAM"
2128 Run "PROGRAM" to find the kernel image and ramdisk to use.
2129 Normally "PROGRAM" would be "pygrub", which is an emulation of
2130 grub/grub2/syslinux. Either kernel or bootloader must be specified
2131 for PV guests.
2132 bootloader_args=[ "ARG", "ARG", ...]
2134 Append ARGs to the arguments to the bootloader program.
2135 Alternatively if the argument is a simple string then it will be
2136 split into words at whitespace (this second option is deprecated).
2137 timer_mode="MODE"
2139 Specifies the mode for Virtual Timers. The valid values are as
2140 follows:
2141 delay_for_missed_ticks
2143 Delay for missed ticks. Do not advance a vCPU's time beyond the
2144 correct delivery time for interrupts that have been missed due
2145 to preemption. Deliver missed interrupts when the vCPU is
2146 rescheduled and advance the vCPU's virtual time stepwise for
2147 each one.
2148 no_delay_for_missed_ticks
2150 No delay for missed ticks. As above, missed interrupts are
2151 delivered, but guest time always tracks wallclock (i.e., real)
2152 time while doing so. This is the default.
2153 no_missed_ticks_pending
2155 No missed interrupts are held pending. Instead, to ensure ticks
2156 are delivered at some non-zero rate, if we detect missed ticks
2157 then the internal tick alarm is not disabled if the vCPU is
2158 preempted during the next tick period.
2159 one_missed_tick_pending
2161 One missed tick pending. Missed interrupts are collapsed
2162 together and delivered as one 'late tick'. Guest time always
2163 tracks wallclock (i.e., real) time.
2164 Paging
2166 The following options control the mechanisms used to virtualise guest
2168 memory. The defaults are selected to give the best results for the
2169 common cases so you should normally leave these options unspecified.
2170 hap=BOOLEAN
2172 Turns "hardware assisted paging" (the use of the hardware nested
2173 page table feature) on or off. This feature is called EPT
2174 (Extended Page Tables) by Intel and NPT (Nested Page Tables) or RVI
2175 (Rapid Virtualisation Indexing) by AMD. If turned off, Xen will run
2176 the guest in "shadow page table" mode where the guest's page table
2177 updates and/or TLB flushes etc. will be emulated. Use of HAP is
2178 the default when available.
2179 oos=BOOLEAN
2181 Turns "out of sync pagetables" on or off. When running in shadow
2182 page table mode, the guest's page table updates may be deferred as
2183 specified in the Intel/AMD architecture manuals. However, this may
2184 expose unexpected bugs in the guest, or find bugs in Xen, so it is
2185 possible to disable this feature. Use of out of sync page tables,
2186 when Xen thinks it appropriate, is the default.
2187 shadow_memory=MBYTES
2189 Number of megabytes to set aside for shadowing guest pagetable
2190 pages (effectively acting as a cache of translated pages) or to use
2191 for HAP state. By default this is 1MB per guest vCPU plus 8KB per
2192 MB of guest RAM. You should not normally need to adjust this value.
2193 However, if you are not using hardware assisted paging (i.e. you
2194 are using shadow mode) and your guest workload consists of a very
2195 large number of similar processes then increasing this value may
2196 improve performance.
2197 Device-Model Options
2199 The following options control the selection of the device-model. This
2200 is the component which provides emulation of the virtual devices to an
2201 HVM guest. For a PV guest a device-model is sometimes used to provide
2202 backends for certain PV devices (most usually a virtual framebuffer
2203 device).
2204 device_model_version="DEVICE-MODEL"
2206 Selects which variant of the device-model should be used for this
2207 guest.
2208 Valid values are:
2210 qemu-xen
2212 Use the device-model merged into the upstream QEMU project.
2213 This device-model is the default for Linux dom0.
2214 qemu-xen-traditional
2216 Use the device-model based upon the historical Xen fork of
2217 QEMU. This device-model is still the default for NetBSD dom0.
2218 It is recommended to accept the default value for new guests. If
2220 you have existing guests then, depending on the nature of the guest
2221 Operating System, you may wish to force them to use the device
2222 model which they were installed with.
2223 device_model_override="PATH"
2225 Override the path to the binary to be used as the device-model
2226 running in toolstack domain. The binary provided here MUST be
2227 consistent with the device_model_version which you have specified.
2228 You should not normally need to specify this option.
2229 stubdomain_kernel="PATH"
2231 Override the path to the kernel image used as device-model
2232 stubdomain. The binary provided here MUST be consistent with the
2233 device_model_version which you have specified. In case of qemu-
2234 xen-traditional it is expected to be MiniOS-based stubdomain image,
2235 in case of qemu-xen it is expected to be Linux-based stubdomain
2236 kernel.
2237 stubdomain_cmdline="STRING"
2239 Set the device-model stubdomain kernel command line to STRING.
2240 stubdomain_ramdisk="PATH"
2242 Override the path to the ramdisk image used as device-model
2243 stubdomain. The binary provided here is to be used by a kernel
2244 pointed by stubdomain_kernel. It is known to be used only by
2245 Linux-based stubdomain kernel.
2246 stubdomain_memory=MBYTES
2248 Start the stubdomain with MBYTES megabytes of RAM. Default is 128.
2249 device_model_stubdomain_override=BOOLEAN
2251 Override the use of stubdomain based device-model. Normally this
2252 will be automatically selected based upon the other features and
2253 options you have selected.
2254 device_model_stubdomain_seclabel="LABEL"
2256 Assign an XSM security label to the device-model stubdomain.
2257 device_model_args=[ "ARG", "ARG", ...]
2259 Pass additional arbitrary options on the device-model command line.
2260 Each element in the list is passed as an option to the device-
2261 model.
2262 device_model_args_pv=[ "ARG", "ARG", ...]
2264 Pass additional arbitrary options on the device-model command line
2265 for a PV device model only. Each element in the list is passed as
2266 an option to the device-model.
2267 device_model_args_hvm=[ "ARG", "ARG", ...]
2269 Pass additional arbitrary options on the device-model command line
2270 for an HVM device model only. Each element in the list is passed as
2271 an option to the device-model.
2272 Keymaps
2274 The keymaps available are defined by the device-model which you are
2275 using. Commonly this includes:
2276 ar de-ch es fo fr-ca hu ja mk no pt-br sv
2278 da en-gb et fr fr-ch is lt nl pl ru th
2279 de en-us fi fr-be hr it lv nl-be pt sl tr
2280 The default is en-us.
2282 See qemu(1) for more information.
2284 Architecture Specific options
2286 ARM
2287 gic_version="vN"
2289 Version of the GIC emulated for the guest.
2290 Currently, the following versions are supported:
2292 v2 Emulate a GICv2
2294 v3 Emulate a GICv3. Note that the emulated GIC does not support
2296 the GICv2 compatibility mode.
2297 default
2299 Emulate the same version as the native GIC hardware used by the
2300 host where the domain was created.
2301 This requires hardware compatibility with the requested version,
2303 either natively or via hardware backwards compatibility support.
2304 vuart="uart"
2306 To enable vuart console, user must specify the following option in
2307 the VM config file:
2308 vuart = "sbsa_uart"
2310 Currently, only the "sbsa_uart" model is supported for ARM.
2312 x86
2314 mca_caps=[ "CAP", "CAP", ... ]
2316 (HVM only) Enable MCA capabilities besides default ones enabled by
2317 Xen hypervisor for the HVM domain. "CAP" can be one in the
2318 following list:
2319 "lmce"
2321 Intel local MCE
2322 default
2324 No MCA capabilities in above list are enabled.
2325 msr_relaxed=BOOLEAN
2327 The "msr_relaxed" boolean is an interim option, and defaults to
2328 false.
2329 In Xen 4.15, the default behaviour for unhandled MSRs has been
2331 changed, to avoid leaking host data into guests, and to avoid
2332 breaking guest logic which uses #GP probing to identify the
2333 availability of MSRs.
2334 However, this new stricter behaviour has the possibility to break
2336 guests, and a more 4.14-like behaviour can be selected by setting
2337 this option.
2338 If using this option is necessary to fix an issue, please report a
2340 bug.
2341
2343 xl(1)
2344 xl.conf(5)
2345 xlcpupool.cfg(5)
2346 xl-disk-configuration(5)
2347 xl-network-configuration(5)
2348 xen-tscmode(7)
2349
2351 /etc/xen/NAME.cfg /var/lib/xen/dump/NAME
2352
2354 This document may contain items which require further documentation.
2355 Patches to improve incomplete items (or any other item) are gratefully
2356 received on the xen-devel@lists.xenproject.org mailing list. Please see
2357 <https://wiki.xenproject.org/wiki/Submitting_Xen_Project_Patches> for
2358 information on how to submit a patch to Xen.
23594.16.3 2022-12-19 xl.cfg(5)