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