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