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