1xl.cfg(5) Xen xl.cfg(5)
2
3
4
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
21 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
25 A "VALUE" can be one of:
26
27 "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
31 NUMBER
32 A number, in either decimal, octal (using a 0 prefix) or
33 hexadecimal (using a "0x" prefix) format.
34
35 BOOLEAN
36 A "NUMBER" interpreted as "False" (0) or "True" (any other value).
37
38 [ VALUE, VALUE, ... ]
39 A list of "VALUE"s of the above types. Lists can be heterogeneous
40 and nested.
41
42 The semantics of each "KEY" defines which type of "VALUE" is required.
43
44 Pairs may be separated either by a newline or a semicolon. Both of the
45 following are valid:
46
47 name="h0"
48 type="hvm"
49
50 name="h0"; type="hvm"
51
53 Mandatory Configuration Items
54 The following key is mandatory for any guest type.
55
56 name="NAME"
57 Specifies the name of the domain. Names of domains existing on a
58 single host must be unique.
59
60 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
65 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
71 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
76 Deprecated guest type selection
77
78 Note that the builder option is being deprecated in favor of the type
79 option.
80
81 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
85 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
90 General Options
91 The following options apply to guests of any type.
92
93 CPU Allocation
94
95 pool="CPUPOOLNAME"
96 Put the guest's vCPUs into the named CPU pool.
97
98 vcpus=N
99 Start the guest with N vCPUs initially online.
100
101 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
106 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
111 "all"
112 To allow all the vCPUs of the guest to run on all the CPUs on
113 the host.
114
115 "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
121 "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
128 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
134 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
139 ["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
145 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
150 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
157 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
162 A "CPULIST" is specified exactly as for cpus=, detailed earlier in
163 the manual.
164
165 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
171 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
180 For more details, see xl-numa-placement(7).
181
182 CPU Scheduling
183
184 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
190 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
198 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
212 Memory Allocation
213
214 memory=MBYTES
215 Start the guest with MBYTES megabytes of RAM.
216
217 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
221 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
226 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
233 Guest Virtual NUMA Configuration
234
235 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
240 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
246 Each VNODE_SPEC is a list, which has a form of
247 "[VNODE_CONFIG_OPTION, VNODE_CONFIG_OPTION, ... ]" (without the
248 quotes).
249
250 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
255 Each VNODE_CONFIG_OPTION is a quoted "KEY=VALUE" pair. Supported
256 VNODE_CONFIG_OPTIONs are (they are all mandatory at the moment):
257
258 pnode=NUMBER
259 Specifies which physical node this virtual node maps to.
260
261 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
267 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
274 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
281 Normally you can use the values from xl info -n or numactl
282 --hardware to fill the vdistances list.
283
284 Event Actions
285
286 on_poweroff="ACTION"
287 Specifies what should be done with the domain if it shuts itself
288 down. The ACTIONs are:
289
290 destroy
291 destroy the domain
292
293 restart
294 destroy the domain and immediately create a new domain with the
295 same configuration
296
297 rename-restart
298 rename the domain which terminated, and then immediately create
299 a new domain with the same configuration as the original
300
301 preserve
302 keep the domain. It can be examined, and later destroyed with
303 xl destroy.
304
305 coredump-destroy
306 write a "coredump" of the domain to /var/lib/xen/dump/NAME and
307 then destroy the domain.
308
309 coredump-restart
310 write a "coredump" of the domain to /var/lib/xen/dump/NAME and
311 then restart the domain.
312
313 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
319 The default for on_poweroff is destroy.
320
321 on_reboot="ACTION"
322 Action to take if the domain shuts down with a reason code
323 requesting a reboot. Default is restart.
324
325 on_watchdog="ACTION"
326 Action to take if the domain shuts down due to a Xen watchdog
327 timeout. Default is destroy.
328
329 on_crash="ACTION"
330 Action to take if the domain crashes. Default is destroy.
331
332 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
336 Direct Kernel Boot
337
338 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
346 kernel="PATHNAME"
347 Load the specified file as the kernel image.
348
349 ramdisk="PATHNAME"
350 Load the specified file as the ramdisk.
351
352 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
358 root="STRING"
359 Append root=STRING to the kernel command line (Note: the meaning of
360 this is guest specific).
361
362 extra="STRING"
363 Append STRING to the kernel command line. (Note: the meaning of
364 this is guest specific).
365
366 Non direct Kernel Boot
367
368 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
372 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
376 PV guest options
377
378 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
383 Note that xl expects to find the pvgrub32.bin and pvgrub64.bin
384 binaries in /usr/libexec/xen/boot.
385
386 HVM guest options
387
388 firmware="bios"
389 Boot the guest using the default BIOS firmware, which depends on
390 the chosen device model.
391
392 firmware="uefi"
393 Boot the guest using the default UEFI firmware, currently OVMF.
394
395 firmware="seabios"
396 Boot the guest using the SeaBIOS BIOS firmware.
397
398 firmware="rombios"
399 Boot the guest using the ROMBIOS BIOS firmware.
400
401 firmware="ovmf"
402 Boot the guest using the OVMF UEFI firmware.
403
404 firmware="PATH"
405 Load the specified file as firmware for the guest.
406
407 PVH guest options
408
409 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
412 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
418 Default is false.
419
420 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
425 pvshim_cmdline="STRING"
426 Command line for the shim. Default is "pv-shim console=xen,pv".
427 Ignored if pvhsim is false.
428
429 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
434 Other Options
435
436 uuid="UUID"
437 Specifies the UUID of the domain. If not specified, a fresh unique
438 UUID will be generated.
439
440 seclabel="LABEL"
441 Assign an XSM security label to this domain.
442
443 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
452 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
458 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
464 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
468 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
474 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
478 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
485 Given the complexity of verifying the validity of a device tree,
486 this option should only be used with a trusted device tree.
487
488 Note that the partial device tree should avoid using the phandle
489 65000 which is reserved by the toolstack.
490
491 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
496 disabled
497 IOMMU mappings are disabled for the domain and so hardware may
498 not be passed through.
499
500 This option is the default if no passthrough hardware is
501 specified in the domain's configuration.
502
503 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
510 This option is the default if passthrough hardware is specified
511 in the domain's configuration.
512
513 sync_pt
514 This option means that IOMMU mappings will be synchronized with
515 the domain's P2M table as follows:
516
517 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
523 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
529 This option is not currently available on Arm.
530
531 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
542 default
543 The default, which chooses between disabled and enabled
544 according to whether passthrough devices are enabled in the
545 config file.
546
547 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
553 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
557 If this option is not specified then it will default to false.
558
559 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
564 NOTE: Acceptable values are platform specific. For Intel Processor
565 Trace, this value must be a power of 2 between 4k and 16M.
566
567 vpmu=BOOLEAN
568 Currently ARM only.
569
570 Specifies whether to enable the access to PMU registers by
571 disabling the PMU traps.
572
573 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
578 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
583 If this option is not specified then it will default to false.
584
585 Devices
586 The following options define the paravirtual, emulated and physical
587 devices which the guest will contain.
588
589 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
595 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
600 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
604 Each VTPM_SPEC_STRING is a comma-separated list of "KEY=VALUE"
605 settings from the following list:
606
607 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
613 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
621 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
625 Each 9PFS_SPEC_STRING is a comma-separated list of "KEY=VALUE"
626 settings, from the following list:
627
628 tag=STRING
629 9pfs tag to identify the filesystem share. The tag is needed on
630 the guest side to mount it.
631
632 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
637 path=STRING
638 Filesystem path on the backend to export.
639
640 backend=domain-id
641 Specify the backend domain name or id, defaults to dom0.
642
643 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
649 vfb=[ "VFB_SPEC_STRING", "VFB_SPEC_STRING", ...]
650 Specifies the paravirtual framebuffer devices which should be
651 supplied to the domain.
652
653 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
660 Each VFB_SPEC_STRING is a comma-separated list of "KEY=VALUE"
661 settings, from the following list:
662
663 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
667 vnclisten=ADDRESS[:DISPLAYNUM]
668 Specifies the IP address, and optionally the VNC display
669 number, to use.
670
671 Note: if you specify the display number here, you should not
672 use the vncdisplay option.
673
674 vncdisplay=DISPLAYNUM
675 Specifies the VNC display number to use. The actual TCP port
676 number will be DISPLAYNUM+5900.
677
678 Note: you should not use this option if you set the DISPLAYNUM
679 in the vnclisten option.
680
681 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
686 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
691 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
696 display=DISPLAY
697 Specifies the X Window display that should be used when the sdl
698 option is used.
699
700 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
704 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
710 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
720 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
727 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
732 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
737 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
747 connection=CONNECTION
748 Specifies how the backend will be implemented. The following
749 options are available:
750
751 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
757 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
761 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
767 RDM_RESERVATION_STRING is a comma separated list of "KEY=VALUE"
768 settings, from the following list:
769
770 strategy=STRING
771 Currently there is only one valid type, and that is "host".
772
773 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
781 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
785 Note: this option is not recommended unless you can make
786 sure that no conflicts exist.
787
788 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
792 Device A [sbdf_A]: RMRR region_A: base_addr ac6d3000
793 end_address ac6e6fff
794
795 Device B [sbdf_B]: RMRR region_B: base_addr ad800000
796 end_address afffffff
797
798 In this conflict case,
799
800 #1. If strategy is set to "host", for example:
801
802 rdm = "strategy=host,policy=strict" or rdm =
803 "strategy=host,policy=relaxed"
804
805 it means all conflicts will be handled according to the
806 policy introduced by policy as described below.
807
808 #2. If strategy is not set at all, but
809
810 pci = [ 'sbdf_A, rdm_policy=xxxxx' ]
811
812 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
816 policy=STRING
817 Specifies how to deal with conflicts when reserving already
818 reserved device memory in the guest address space.
819
820 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
825 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
832 Note: this may be overridden by the rdm_policy option in
833 the pci device configuration.
834
835 usbctrl=[ "USBCTRL_SPEC_STRING", "USBCTRL_SPEC_STRING", ...]
836 Specifies the USB controllers created for this guest.
837
838 Each USBCTRL_SPEC_STRING is a comma-separated list of "KEY=VALUE"
839 settings, from the following list:
840
841 type=TYPE
842 Specifies the usb controller type.
843
844 pv Specifies a kernel based PVUSB backend.
845
846 qusb
847 Specifies a QEMU based PVUSB backend.
848
849 devicemodel
850 Specifies a USB controller emulated by QEMU. It will show
851 up as a PCI-device in the guest.
852
853 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
858 This option is the default.
859
860 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
865 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
872 USB controller ids start from 0. In line with the USB
873 specification, however, ports on a controller start from 1.
874
875 EXAMPLE
876
877 usbctrl=["version=1,ports=4", "version=2,ports=8"]
878
879 The first controller is USB1.1 and has:
880
881 controller id = 0, and ports 1,2,3,4.
882
883 The second controller is USB2.0 and has:
884
885 controller id = 1, and ports 1,2,3,4,5,6,7,8.
886
887 usbdev=[ "USBDEV_SPEC_STRING", "USBDEV_SPEC_STRING", ...]
888 Specifies the USB devices to be attached to the guest at boot.
889
890 Each USBDEV_SPEC_STRING is a comma-separated list of "KEY=VALUE"
891 settings, from the following list:
892
893 type=hostdev
894 Specifies USB device type. Currently only "hostdev" is
895 supported.
896
897 hostbus=busnum
898 Specifies busnum of the USB device from the host perspective.
899
900 hostaddr=devnum
901 Specifies devnum of the USB device from the host perspective.
902
903 controller=CONTROLLER
904 Specifies the USB controller id, to which controller the USB
905 device is attached.
906
907 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
911 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
916 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
920 pci_permissive=BOOLEAN
921 Changes the default value of permissive for all PCI devices passed
922 through to this VM. See permissive above.
923
924 pci_msitranslate=BOOLEAN
925 Changes the default value of msitranslate for all PCI devices
926 passed through to this VM. See msitranslate above.
927
928 pci_seize=BOOLEAN
929 Changes the default value of seize for all PCI devices passed
930 through to this VM. See seize above.
931
932 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
936 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
945 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
951 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
956 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
960 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
966 gfx_passthru is currently supported both with the qemu-xen-
967 traditional device-model and upstream qemu-xen device-model.
968
969 When given as a boolean the gfx_passthru option either disables
970 graphics card passthrough or enables autodetection.
971
972 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
978 Currently, valid values for the option are:
979
980 0 Disables graphics device PCI passthrough.
981
982 1, "default"
983 Enables graphics device PCI passthrough and autodetects the
984 type of device which is being used.
985
986 "igd"
987 Enables graphics device PCI passthrough but forcing the type of
988 device to Intel Graphics Device.
989
990 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
997 More information about the Xen gfx_passthru feature is available on
998 the XenVGAPassthrough
999 <https://wiki.xenproject.org/wiki/XenVGAPassthrough> wiki page.
1000
1001 rdm_mem_boundary=MBYTES
1002 Number of megabytes to set for a boundary when checking for RDM
1003 conflicts.
1004
1005 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
1011 #1. Above a predefined boundary
1012 - move lowmem_end below the reserved region to solve the conflict;
1013
1014 #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
1023 The default value is 2048.
1024
1025 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
1029 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
1035 It is recommended to only use this option for trusted VMs under
1036 administrator's control.
1037
1038 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
1043 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
1051 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
1055 It is recommended to only use this option for trusted VMs under
1056 administrator's control.
1057
1058 irqs=[ NUMBER, NUMBER, ...]
1059 Allow a guest to access specific physical IRQs.
1060
1061 It is recommended to only use this option for trusted VMs under
1062 administrator's control.
1063
1064 If vuart console is enabled then irq 32 is reserved for it. See
1065 "vuart="uart"" to know how to enable vuart console.
1066
1067 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
1071 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
1077 vdispl=[ "VDISPL_SPEC_STRING", "VDISPL_SPEC_STRING", ...]
1078 Specifies the virtual display devices to be provided to the guest.
1079
1080 Each VDISPL_SPEC_STRING is a comma-separated list of "KEY=VALUE"
1081 settings, from the following list:
1082
1083 "backend=DOMAIN"
1084 Specifies the backend domain name or id. If not specified
1085 Domain-0 is used.
1086
1087 "be-alloc=BOOLEAN"
1088 Indicates if backend can be a buffer provider/allocator for
1089 this domain. See display protocol for details.
1090
1091 "connectors=CONNECTORS"
1092 Specifies virtual connectors for the device in following format
1093 <id>:<W>x<H>;<id>:<W>x<H>... where:
1094
1095 "id"
1096 String connector unique id. Space, comma symbols are not
1097 allowed.
1098
1099 "W" Connector width in pixels.
1100
1101 "H" Connector height in pixels.
1102
1103 EXAMPLE
1104
1105 connectors=id0:1920x1080;id1:800x600;id2:640x480
1106
1107 dm_restrict=BOOLEAN
1108 Restrict the device model after startup, to limit the consequencese
1109 of security vulnerabilities in qemu.
1110
1111 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
1115 This feature is a technology preview. See SUPPORT.md for a
1116 security support statement.
1117
1118 device_model_user=USERNAME
1119 When running dm_restrict, run the device model as this user.
1120
1121 NOTE: Each domain MUST have a SEPARATE username.
1122
1123 See docs/features/qemu-depriv.pandoc for more information.
1124
1125 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
1132 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
1136 "identifier, param = value, ...".
1137
1138 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
1142 All parameters are optional.
1143
1144 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
1149 * number of channels (min/max)
1150
1151 * supported sample rates
1152
1153 * supported sample formats
1154
1155 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
1162 COMMON parameters:
1163
1164 sample-rates=RATES
1165 List of integer values separated by semicolon:
1166 sample-rates=8000;22050;44100
1167
1168 sample-formats=FORMATS
1169 List of string values separated by semicolon:
1170 sample-formats=s16_le;s8;u32_be
1171
1172 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
1178 channels-min=NUMBER
1179 The minimum amount of channels.
1180
1181 channels-max=NUMBER
1182 The maximum amount of channels.
1183
1184 buffer-size=NUMBER
1185 The maximum size in octets of the buffer to allocate per
1186 stream.
1187
1188 CARD specification:
1189
1190 backend=domain-id
1191 Specify the backend domain name or id, defaults to dom0.
1192
1193 short-name=STRING
1194 Short name of the virtual sound card.
1195
1196 long-name=STRING
1197 Long name of the virtual sound card.
1198
1199 PCM specification:
1200
1201 name=STRING
1202 Name of the PCM sound device within the virtual sound card.
1203
1204 STREAM specification:
1205
1206 unique-id=STRING
1207 Unique stream identifier.
1208
1209 type=TYPE
1210 Stream type: "p" - playback stream, "c" - capture stream.
1211
1212 EXAMPLE:
1213
1214 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
1227 vkb=[ "VKB_SPEC_STRING", "VKB_SPEC_STRING", ...]
1228 Specifies the virtual keyboard device to be provided to the guest.
1229
1230 Each VKB_SPEC_STRING is a comma-separated list of "KEY=VALUE"
1231 settings from the following list:
1232
1233 unique-id=STRING
1234 Specifies the unique input device id.
1235
1236 backend=domain-id
1237 Specifies the backend domain name or id.
1238
1239 backend-type=type
1240 Specifies the backend type: qemu - for QEMU backend or linux -
1241 for Linux PV domain.
1242
1243 feature-disable-keyboard=BOOLEAN
1244 Indicates if keyboard device is disabled.
1245
1246 feature-disable-pointer=BOOLEAN
1247 Indicates if pointer device is disabled.
1248
1249 feature-abs-pointer=BOOLEAN
1250 Indicates if pointer device can return absolute coordinates.
1251
1252 feature-raw-pointer=BOOLEAN
1253 Indicates if pointer device can return raw (unscaled) absolute
1254 coordinates.
1255
1256 feature-multi-touch=BOOLEAN
1257 Indicates if input device supports multi touch.
1258
1259 multi-touch-width=MULTI_TOUCH_WIDTH
1260 Set maximum width for multi touch device.
1261
1262 multi-touch-height=MULTI_TOUCH_HEIGHT
1263 Set maximum height for multi touch device.
1264
1265 multi-touch-num-contacts=MULTI_TOUCH_NUM_CONTACTS
1266 Set maximum contacts number for multi touch device.
1267
1268 width=WIDTH
1269 Set maximum width for pointer device.
1270
1271 height=HEIGHT
1272 Set maximum height for pointer device.
1273
1274 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
1279 none
1280 "Don't allow the guest to use TEE if present on the platform.
1281 This is the default value.
1282
1283 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
1290 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
1295 This feature is a technology preview.
1296
1297 Paravirtualised (PV) Guest Specific Options
1298 The following options apply only to Paravirtual (PV) guests.
1299
1300 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
1306 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
1311 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
1320 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
1333 Fully-virtualised (HVM) Guest Specific Options
1334 The following options apply only to Fully-virtualised (HVM) guests.
1335
1336 Boot Device
1337
1338 boot="STRING"
1339 Specifies the emulated virtual device to boot from.
1340
1341 Possible values are:
1342
1343 c Hard disk.
1344
1345 d CD-ROM.
1346
1347 n Network / PXE.
1348
1349 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
1353 The default is cd, meaning try booting from the hard disk first,
1354 but fall back to the CD-ROM.
1355
1356 Emulated disk controller type
1357
1358 hdtype=STRING
1359 Specifies the hard disk type.
1360
1361 Possible values are:
1362
1363 ide If thise mode is specified xl adds an emulated IDE controller,
1364 which is suitable even for older operation systems.
1365
1366 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
1372 The default is ide.
1373
1374 Paging
1375
1376 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
1380 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
1389 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
1397 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
1407 Processor and Platform Features
1408
1409 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
1415 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
1420 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
1427 seabios
1428 Loads SeaBIOS, a 16-bit x86 compatible BIOS. This is used by
1429 default with device_model_version=qemu-xen.
1430
1431 ovmf
1432 Loads OVMF, a standard UEFI firmware by Tianocore project.
1433 Requires device_model_version=qemu-xen.
1434
1435 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
1440 This option does not have any effect if using bios="rombios" or
1441 device_model_version="qemu-xen-traditional".
1442
1443 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
1452 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
1461 acpi_s3=BOOLEAN
1462 Include the S3 (suspend-to-ram) power state in the virtual firmware
1463 ACPI table. True (1) by default.
1464
1465 acpi_s4=BOOLEAN
1466 Include S4 (suspend-to-disk) power state in the virtual firmware
1467 ACPI table. True (1) by default.
1468
1469 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
1473 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
1485 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
1491 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
1497 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
1507 The valid values are as follows:
1508
1509 disabled
1510 Altp2m is disabled for the domain (default).
1511
1512 mixed
1513 The mixed mode allows access to the altp2m interface for both
1514 in-guest and external tools as well.
1515
1516 external
1517 Enables access to the alternate-p2m capability by external
1518 privileged tools.
1519
1520 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
1525 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
1536 Note: While the option "altp2mhvm" is deprecated, legacy
1537 applications for x86 systems will continue to work using it.
1538
1539 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
1548 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
1553 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
1563 Libxl format:
1564
1565 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
1571 cpuid="host,tm=0,sse3=0"
1572
1573 List of keys taking a value:
1574
1575 apicidsize brandid clflush family localapicid maxleaf
1576 maxhvleaf model nc proccount procpkg stepping
1577
1578 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
1583 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
1588 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
1593 Xend format:
1594
1595 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
1599 cpuid=["1:ecx=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx0,edx=xx0xxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
1600 ...]
1601
1602 "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
1606 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
1610 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
1614 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
1619 More info about the CPUID instruction can be found in the processor
1620 manuals, and on Wikipedia: <https://en.wikipedia.org/wiki/CPUID>
1621
1622 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
1631 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
1642 ms_vm_genid="OPTION"
1643 Provide a VM generation ID to the guest.
1644
1645 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
1649 This is required for Microsoft Windows Server 2012 (and later)
1650 domain controllers.
1651
1652 Valid options are:
1653
1654 generate
1655 Generate a random VM generation ID every time the domain is
1656 created or restored.
1657
1658 none
1659 Do not provide a VM generation ID.
1660
1661 See also "Virtual Machine Generation ID" by Microsoft:
1662 <https://docs.microsoft.com/en-us/windows/win32/hyperv_v2/virtual-machine-generation-identifier>
1663
1664 Guest Virtual Time Controls
1665
1666 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
1671 Options are:
1672
1673 default
1674 Guest rdtsc/p is executed natively when monotonicity can be
1675 guaranteed and emulated otherwise (with frequency scaled if
1676 necessary).
1677
1678 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
1686 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
1693 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
1699 native_paravirt
1700 This mode has been removed.
1701
1702 Please see xen-tscmode(7) for more information on this option.
1703
1704 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
1708 rtc_timeoffset=SECONDS
1709 Set the real time clock offset in seconds. No offset (0) by
1710 default.
1711
1712 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
1718 timer_mode="MODE"
1719 Specifies the mode for Virtual Timers. The valid values are as
1720 follows:
1721
1722 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
1729 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
1734 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
1740 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
1745 Memory layout
1746
1747 mmio_hole=MBYTES
1748 Specifies the size the MMIO hole below 4GiB will be. Only valid
1749 for device_model_version="qemu-xen".
1750
1751 Cannot be smaller than 256. Cannot be larger than 3840.
1752
1753 Known good large value is 3072.
1754
1755 Support for Paravirtualisation of HVM Guests
1756
1757 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
1762 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
1772 Setting xen_platform_pci=0 with the default device_model "qemu-xen"
1773 requires at least QEMU 1.6.
1774
1775 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
1780 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
1789 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
1794 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
1799 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
1804 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
1810 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
1817 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
1822 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
1829 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
1834 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
1841 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
1848 cpu_hotplug
1849 This set enables dynamic changes to Virtual processor states in
1850 Windows guests effectively allowing vCPU hotplug.
1851
1852 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
1857 all This is a special value that enables all available groups.
1858
1859 Groups can be disabled by prefixing the name with '!'. So, for
1860 example, to enable all groups except freq, specify:
1861
1862 viridian=[ "all", "!freq" ]
1863
1864 For details of the enlightenments see the latest version of
1865 Microsoft's Hypervisor Top-Level Functional Specification.
1866
1867 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
1874 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
1878 Emulated VGA Graphics Device
1879
1880 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
1885 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
1890 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
1895 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
1900 For QXL vga, both the default and minimal are 128MB. If videoram
1901 is set less than 128MB, an error will be triggered.
1902
1903 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
1912 vga="STRING"
1913 Selects the emulated video card. Options are: none, stdvga, cirrus
1914 and qxl. The default is cirrus.
1915
1916 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
1921 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
1925 vnclisten="ADDRESS[:DISPLAYNUM]"
1926 Specifies the IP address and, optionally, the VNC display number to
1927 use.
1928
1929 vncdisplay=DISPLAYNUM
1930 Specifies the VNC display number to use. The actual TCP port number
1931 will be DISPLAYNUM+5900.
1932
1933 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
1937 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
1942 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
1951 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
1955 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
1961 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
1966 Spice Graphics Support
1967
1968 The following options control the features of SPICE.
1969
1970 spice=BOOLEAN
1971 Allow access to the display via the SPICE protocol. This enables
1972 the other SPICE-related settings.
1973
1974 spicehost="ADDRESS"
1975 Specifies the interface address to listen on if given, otherwise
1976 any interface.
1977
1978 spiceport=NUMBER
1979 Specifies the port to listen on by the SPICE server if SPICE is
1980 enabled.
1981
1982 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
1987 Note: the options depending on spicetls_port have not been
1988 supported.
1989
1990 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
1994 spicepasswd="PASSWORD"
1995 Specify the password which is used by clients for establishing a
1996 connection.
1997
1998 spiceagent_mouse=BOOLEAN
1999 Whether SPICE agent is used for client mouse mode. The default is
2000 (1) true.
2001
2002 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
2012 spice_clipboard_sharing=BOOLEAN
2013 Enables SPICE clipboard sharing (copy/paste). It requires that
2014 spicevdagent is enabled. The default is (0) false.
2015
2016 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
2023 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
2028 Available options are: auto_glz, auto_lz, quic, glz, lz, off.
2029
2030 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
2034 Available options are: filter, all, off.
2035
2036 Miscellaneous Emulated Hardware
2037
2038 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
2044 The form serial=DEVICE is also accepted for backwards
2045 compatibility.
2046
2047 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
2053 vkb_device=BOOLEAN
2054 Specifies that the HVM guest gets a vkdb. The default is true (1).
2055
2056 usb=BOOLEAN
2057 Enables or disables an emulated USB bus in the guest.
2058
2059 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
2066 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
2076 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
2080 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
2084 The form usbdevice=DEVICE is also accepted for backwards
2085 compatibility.
2086
2087 More valid options can be found in the "usbdevice" section of the
2088 QEMU documentation.
2089
2090 vendor_device="VENDOR_DEVICE"
2091 Selects which variant of the QEMU xen-pvdevice should be used for
2092 this guest. Valid values are:
2093
2094 none
2095 The xen-pvdevice should be omitted. This is the default.
2096
2097 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
2102 This parameter only takes effect when
2103 device_model_version=qemu-xen. See xen-pci-device-reservations(7)
2104 for more information.
2105
2106 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
2116 This option is disabled by default.
2117
2118 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
2124 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
2129 timer_mode="MODE"
2130 Specifies the mode for Virtual Timers. The valid values are as
2131 follows:
2132
2133 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
2140 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
2145 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
2151 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
2156 Paging
2157
2158 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
2162 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
2171 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
2179 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
2189 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
2194 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
2201 device_model_version="DEVICE-MODEL"
2202 Selects which variant of the device-model should be used for this
2203 guest.
2204
2205 Valid values are:
2206
2207 qemu-xen
2208 Use the device-model merged into the upstream QEMU project.
2209 This device-model is the default for Linux dom0.
2210
2211 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
2215 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
2220 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
2226 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
2234 stubdomain_cmdline="STRING"
2235 Set the device-model stubdomain kernel command line to STRING.
2236
2237 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
2243 stubdomain_memory=MBYTES
2244 Start the stubdomain with MBYTES megabytes of RAM. Default is 128.
2245
2246 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
2251 device_model_stubdomain_seclabel="LABEL"
2252 Assign an XSM security label to the device-model stubdomain.
2253
2254 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
2259 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
2264 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
2269 Keymaps
2270 The keymaps available are defined by the device-model which you are
2271 using. Commonly this includes:
2272
2273 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
2277 The default is en-us.
2278
2279 See qemu(1) for more information.
2280
2281 Architecture Specific options
2282 ARM
2283
2284 gic_version="vN"
2285 Version of the GIC emulated for the guest.
2286
2287 Currently, the following versions are supported:
2288
2289 v2 Emulate a GICv2
2290
2291 v3 Emulate a GICv3. Note that the emulated GIC does not support
2292 the GICv2 compatibility mode.
2293
2294 default
2295 Emulate the same version as the native GIC hardware used by the
2296 host where the domain was created.
2297
2298 This requires hardware compatibility with the requested version,
2299 either natively or via hardware backwards compatibility support.
2300
2301 vuart="uart"
2302 To enable vuart console, user must specify the following option in
2303 the VM config file:
2304
2305 vuart = "sbsa_uart"
2306
2307 Currently, only the "sbsa_uart" model is supported for ARM.
2308
2309 x86
2310
2311 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
2316 "lmce"
2317 Intel local MCE
2318
2319 default
2320 No MCA capabilities in above list are enabled.
2321
2322 msr_relaxed=BOOLEAN
2323 The "msr_relaxed" boolean is an interim option, and defaults to
2324 false.
2325
2326 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
2331 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
2335 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.
2355
2356
2357
23584.17.2 2023-11-14 xl.cfg(5)