1xl.cfg(5) Xen xl.cfg(5)
2
6 xl.cfg - xl domain configuration file syntax
7
9 /etc/xen/xldomain
10
12 Creating a VM (a domain in Xen terminology, sometimes called a guest)
13 with xl requires the provision of a domain configuration file.
14 Typically, these live in /etc/xen/DOMAIN.cfg, where DOMAIN is the name
15 of the domain.
16
18 A domain configuration file consists of a series of options, specified
19 by using "KEY=VALUE" pairs.
20 Some "KEY"s are mandatory, some are general options which apply to any
22 guest type, while others relate only to specific guest types (e.g. PV
23 or HVM guests).
24 A "VALUE" can be one of:
26 "STRING"
28 A string, surrounded by either single or double quotes. But if the
29 STRING is part of a SPEC_STRING, the quotes should be omitted.
30 NUMBER
32 A number, in either decimal, octal (using a 0 prefix) or
33 hexadecimal (using a "0x" prefix) format.
34 BOOLEAN
36 A "NUMBER" interpreted as "False" (0) or "True" (any other value).
37 [ VALUE, VALUE, ... ]
39 A list of "VALUE"s of the above types. Lists can be heterogeneous
40 and nested.
41 The semantics of each "KEY" defines which type of "VALUE" is required.
43 Pairs may be separated either by a newline or a semicolon. Both of the
45 following are valid:
46 name="h0"
48 type="hvm"
49 name="h0"; type="hvm"
51
53 Mandatory Configuration Items
54 The following key is mandatory for any guest type.
55 name="NAME"
57 Specifies the name of the domain. Names of domains existing on a
58 single host must be unique.
59 Selecting Guest Type
61 type="pv"
62 Specifies that this is to be a PV domain, suitable for hosting Xen-
63 aware guest operating systems. This is the default on x86.
64 type="pvh"
66 Specifies that this is to be an PVH domain. That is a lightweight
67 HVM-like guest without a device model and without many of the
68 emulated devices available to HVM guests. Note that this mode
69 requires a PVH aware kernel on x86. This is the default on Arm.
70 type="hvm"
72 Specifies that this is to be an HVM domain. That is, a fully
73 virtualised computer with emulated BIOS, disk and network
74 peripherals, etc.
75 Deprecated guest type selection
77 Note that the builder option is being deprecated in favor of the type
79 option.
80 builder="generic"
82 Specifies that this is to be a PV domain, suitable for hosting Xen-
83 aware guest operating systems. This is the default.
84 builder="hvm"
86 Specifies that this is to be an HVM domain. That is, a fully
87 virtualised computer with emulated BIOS, disk and network
88 peripherals, etc.
89 General Options
91 The following options apply to guests of any type.
92 CPU Allocation
94 pool="CPUPOOLNAME"
96 Put the guest's vCPUs into the named CPU pool.
97 vcpus=N
99 Start the guest with N vCPUs initially online.
100 maxvcpus=M
102 Allow the guest to bring up a maximum of M vCPUs. When starting the
103 guest, if vcpus=N is less than maxvcpus=M then the first N vCPUs
104 will be created online and the remainder will be created offline.
105 cpus="CPULIST"
107 List of host CPUs the guest is allowed to use. Default is no
108 pinning at all (more on this below). A "CPULIST" may be specified
109 as follows:
110 "all"
112 To allow all the vCPUs of the guest to run on all the CPUs on
113 the host.
114 "0-3,5,^1"
116 To allow all the vCPUs of the guest to run on CPUs 0,2,3,5. It
117 is possible to combine this with "all", meaning "all,^7"
118 results in all the vCPUs of the guest being allowed to run on
119 all the CPUs of the host except CPU 7.
120 "nodes:0-3,^node:2"
122 To allow all the vCPUs of the guest to run on the CPUs from
123 NUMA nodes 0,1,3 of the host. So, if CPUs 0-3 belong to node 0,
124 CPUs 4-7 belong to node 1, CPUs 8-11 to node 2 and CPUs 12-15
125 to node 3, the above would mean all the vCPUs of the guest
126 would be allowed to run on CPUs 0-7,12-15.
127 Combining this notation with the one above is possible. For
129 instance, "1,node:1,^6", means all the vCPUs of the guest will
130 run on CPU 1 and on all the CPUs of NUMA node 1, but not on CPU
131 6. Following the same example as above, that would be CPUs
132 1,4,5,7.
133 Combining this with "all" is also possible, meaning
135 "all,^node:1" results in all the vCPUs of the guest running on
136 all the CPUs on the host, except for the CPUs belonging to the
137 host NUMA node 1.
138 ["2", "3-8,^5"]
140 To ask for specific vCPU mapping. That means (in this example),
141 vCPU 0 of the guest will run on CPU 2 of the host and vCPU 1 of
142 the guest will run on CPUs 3,4,6,7,8 of the host (excluding CPU
143 5).
144 More complex notation can be also used, exactly as described
146 above. So "all,^5-8", or just "all", or
147 "node:0,node:2,^9-11,18-20" are all legal, for each element of
148 the list.
149 If this option is not specified, no vCPU to CPU pinning is
151 established, and the vCPUs of the guest can run on all the CPUs of
152 the host. If this option is specified, the intersection of the vCPU
153 pinning mask, provided here, and the soft affinity mask, if
154 provided via cpus_soft=, is utilized to compute the domain node-
155 affinity for driving memory allocations.
156 cpus_soft="CPULIST"
158 Exactly as cpus=, but specifies soft affinity, rather than pinning
159 (hard affinity). When using the credit scheduler, this means what
160 CPUs the vCPUs of the domain prefer.
161 A "CPULIST" is specified exactly as for cpus=, detailed earlier in
163 the manual.
164 If this option is not specified, the vCPUs of the guest will not
166 have any preference regarding host CPUs. If this option is
167 specified, the intersection of the soft affinity mask, provided
168 here, and the vCPU pinning, if provided via cpus=, is utilized to
169 compute the domain node-affinity for driving memory allocations.
170 If this option is not specified (and cpus= is not specified
172 either), libxl automatically tries to place the guest on the least
173 possible number of nodes. A heuristic approach is used for choosing
174 the best node (or set of nodes), with the goal of maximizing
175 performance for the guest and, at the same time, achieving
176 efficient utilization of host CPUs and memory. In that case, the
177 soft affinity of all the vCPUs of the domain will be set to host
178 CPUs belonging to NUMA nodes chosen during placement.
179 For more details, see xl-numa-placement(7).
181 CPU Scheduling
183 cpu_weight=WEIGHT
185 A domain with a weight of 512 will get twice as much CPU as a
186 domain with a weight of 256 on a contended host. Legal weights
187 range from 1 to 65535 and the default is 256. Honoured by the
188 credit and credit2 schedulers.
189 cap=N
191 The cap optionally fixes the maximum amount of CPU a domain will be
192 able to consume, even if the host system has idle CPU cycles. The
193 cap is expressed as a percentage of one physical CPU: 100 is 1
194 physical CPU, 50 is half a CPU, 400 is 4 CPUs, etc. The default,
195 0, means there is no cap. Honoured by the credit and credit2
196 schedulers.
197 NOTE: Many systems have features that will scale down the computing
199 power of a CPU that is not 100% utilized. This can be done in the
200 operating system, but can also sometimes be done below the
201 operating system, in the BIOS. If you set a cap such that
202 individual cores are running at less than 100%, this may have an
203 impact on the performance of your workload over and above the
204 impact of the cap. For example, if your processor runs at 2GHz, and
205 you cap a VM at 50%, the power management system may also reduce
206 the clock speed to 1GHz; the effect will be that your VM gets 25%
207 of the available power (50% of 1GHz) rather than 50% (50% of 2GHz).
208 If you are not getting the performance you expect, look at
209 performance and CPU frequency options in your operating system and
210 your BIOS.
211 Memory Allocation
213 memory=MBYTES
215 Start the guest with MBYTES megabytes of RAM.
216 maxmem=MBYTES
218 Specifies the maximum amount of memory a guest can ever see. The
219 value of maxmem= must be equal to or greater than that of memory=.
220 In combination with memory= it will start the guest "pre-
222 ballooned", if the values of memory= and maxmem= differ. A "pre-
223 ballooned" HVM guest needs a balloon driver, without a balloon
224 driver it will crash.
225 NOTE: Because of the way ballooning works, the guest has to
227 allocate memory to keep track of maxmem pages, regardless of how
228 much memory it actually has available to it. A guest with
229 maxmem=262144 and memory=8096 will report significantly less memory
230 available for use than a system with maxmem=8096 memory=8096 due to
231 the memory overhead of having to track the unused pages.
232 Guest Virtual NUMA Configuration
234 vnuma=[ VNODE_SPEC, VNODE_SPEC, ... ]
236 Specify virtual NUMA configuration with positional arguments. The
237 nth VNODE_SPEC in the list specifies the configuration of the nth
238 virtual node.
239 Note that virtual NUMA is not supported for PV guests yet, because
241 there is an issue with the CPUID instruction handling that affects
242 PV virtual NUMA. Furthermore, guests with virtual NUMA cannot be
243 saved or migrated because the migration stream does not preserve
244 node information.
245 Each VNODE_SPEC is a list, which has a form of
247 "[VNODE_CONFIG_OPTION, VNODE_CONFIG_OPTION, ... ]" (without the
248 quotes).
249 For example, vnuma = [
251 ["pnode=0","size=512","vcpus=0-4","vdistances=10,20"] ] means vnode
252 0 is mapped to pnode 0, has 512MB ram, has vcpus 0 to 4, the
253 distance to itself is 10 and the distance to vnode 1 is 20.
254 Each VNODE_CONFIG_OPTION is a quoted "KEY=VALUE" pair. Supported
256 VNODE_CONFIG_OPTIONs are (they are all mandatory at the moment):
257 pnode=NUMBER
259 Specifies which physical node this virtual node maps to.
260 size=MBYTES
262 Specifies the size of this virtual node. The sum of memory
263 sizes of all vnodes will become maxmem=. If maxmem= is
264 specified separately, a check is performed to make sure the sum
265 of all vnode memory matches maxmem=.
266 vcpus="CPUSTRING"
268 Specifies which vCPUs belong to this node. "CPUSTRING" is a
269 string of numerical values separated by a comma. You can
270 specify a range and/or a single CPU. An example would be
271 "vcpus=0-5,8", which means you specified vCPU 0 to vCPU 5, and
272 vCPU 8.
273 vdistances=NUMBER, NUMBER, ...
275 Specifies the virtual distance from this node to all nodes
276 (including itself) with positional arguments. For example,
277 "vdistance=10,20" for vnode 0 means the distance from vnode 0
278 to vnode 0 is 10, from vnode 0 to vnode 1 is 20. The number of
279 arguments supplied must match the total number of vnodes.
280 Normally you can use the values from xl info -n or numactl
282 --hardware to fill the vdistances list.
283 Event Actions
285 on_poweroff="ACTION"
287 Specifies what should be done with the domain if it shuts itself
288 down. The ACTIONs are:
289 destroy
291 destroy the domain
292 restart
294 destroy the domain and immediately create a new domain with the
295 same configuration
296 rename-restart
298 rename the domain which terminated, and then immediately create
299 a new domain with the same configuration as the original
300 preserve
302 keep the domain. It can be examined, and later destroyed with
303 xl destroy.
304 coredump-destroy
306 write a "coredump" of the domain to /var/lib/xen/dump/NAME and
307 then destroy the domain.
308 coredump-restart
310 write a "coredump" of the domain to /var/lib/xen/dump/NAME and
311 then restart the domain.
312 soft-reset
314 Reset all Xen specific interfaces for the Xen-aware HVM domain
315 allowing it to reestablish these interfaces and continue
316 executing the domain. PV and non-Xen-aware HVM guests are not
317 supported.
318 The default for on_poweroff is destroy.
320 on_reboot="ACTION"
322 Action to take if the domain shuts down with a reason code
323 requesting a reboot. Default is restart.
324 on_watchdog="ACTION"
326 Action to take if the domain shuts down due to a Xen watchdog
327 timeout. Default is destroy.
328 on_crash="ACTION"
330 Action to take if the domain crashes. Default is destroy.
331 on_soft_reset="ACTION"
333 Action to take if the domain performs a 'soft reset' (e.g. does
334 kexec). Default is soft-reset.
335 Direct Kernel Boot
337 Direct kernel boot allows booting guests with a kernel and an initrd
339 stored on a filesystem available to the host physical machine, allowing
340 command line arguments to be passed directly. PV guest direct kernel
341 boot is supported. HVM guest direct kernel boot is supported with some
342 limitations (it's supported when using qemu-xen and the default BIOS
343 'seabios', but not supported in case of using stubdom-dm and the old
344 'rombios'.)
345 kernel="PATHNAME"
347 Load the specified file as the kernel image.
348 ramdisk="PATHNAME"
350 Load the specified file as the ramdisk.
351 cmdline="STRING"
353 Append STRING to the kernel command line. (Note: the meaning of
354 this is guest specific). It can replace root="STRING" along with
355 extra="STRING" and is preferred. When cmdline="STRING" is set,
356 root="STRING" and extra="STRING" will be ignored.
357 root="STRING"
359 Append root=STRING to the kernel command line (Note: the meaning of
360 this is guest specific).
361 extra="STRING"
363 Append STRING to the kernel command line. (Note: the meaning of
364 this is guest specific).
365 Non direct Kernel Boot
367 Non direct kernel boot allows booting guests with a firmware. This can
369 be used by all types of guests, although the selection of options is
370 different depending on the guest type.
371 This option provides the flexibly of letting the guest decide which
373 kernel they want to boot, while preventing having to poke at the guest
374 file system form the toolstack domain.
375 PV guest options
377 firmware="pvgrub32|pvgrub64"
379 Boots a guest using a para-virtualized version of grub that runs
380 inside of the guest. The bitness of the guest needs to be know, so
381 that the right version of pvgrub can be selected.
382 Note that xl expects to find the pvgrub32.bin and pvgrub64.bin
384 binaries in /usr/libexec/xen/boot.
385 HVM guest options
387 firmware="bios"
389 Boot the guest using the default BIOS firmware, which depends on
390 the chosen device model.
391 firmware="uefi"
393 Boot the guest using the default UEFI firmware, currently OVMF.
394 firmware="seabios"
396 Boot the guest using the SeaBIOS BIOS firmware.
397 firmware="rombios"
399 Boot the guest using the ROMBIOS BIOS firmware.
400 firmware="ovmf"
402 Boot the guest using the OVMF UEFI firmware.
403 firmware="PATH"
405 Load the specified file as firmware for the guest.
406 PVH guest options
408 Currently there's no firmware available for PVH guests, they should be
410 booted using the Direct Kernel Boot method or the bootloader option.
411 pvshim=BOOLEAN
413 Whether to boot this guest as a PV guest within a PVH container.
414 Ie, the guest will experience a PV environment, but processor
415 hardware extensions are used to separate its address space to
416 mitigate the Meltdown attack (CVE-2017-5754).
417 Default is false.
419 pvshim_path="PATH"
421 The PV shim is a specially-built firmware-like executable
422 constructed from the hypervisor source tree. This option specifies
423 to use a non-default shim. Ignored if pvhsim is false.
424 pvshim_cmdline="STRING"
426 Command line for the shim. Default is "pv-shim console=xen,pv".
427 Ignored if pvhsim is false.
428 pvshim_extra="STRING"
430 Extra command line arguments for the shim. If supplied, appended
431 to the value for pvshim_cmdline. Default is empty. Ignored if
432 pvhsim is false.
433 Other Options
435 uuid="UUID"
437 Specifies the UUID of the domain. If not specified, a fresh unique
438 UUID will be generated.
439 seclabel="LABEL"
441 Assign an XSM security label to this domain.
442 init_seclabel="LABEL"
444 Specify an XSM security label used for this domain temporarily
445 during its build. The domain's XSM label will be changed to the
446 execution seclabel (specified by seclabel) once the build is
447 complete, prior to unpausing the domain. With a properly
448 constructed security policy (such as nomigrate_t in the example
449 policy), this can be used to build a domain whose memory is not
450 accessible to the toolstack domain.
451 max_grant_frames=NUMBER
453 Specify the maximum number of grant frames the domain is allowed to
454 have. This value controls how many pages the domain is able to
455 grant access to for other domains, needed e.g. for the operation of
456 paravirtualized devices. The default is settable via xl.conf(5).
457 max_maptrack_frames=NUMBER
459 Specify the maximum number of grant maptrack frames the domain is
460 allowed to have. This value controls how many pages of foreign
461 domains can be accessed via the grant mechanism by this domain. The
462 default value is settable via xl.conf(5).
463 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 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 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 Given the complexity of verifying the validity of a device tree,
482 this option should only be used with a trusted device tree.
483 Note that the partial device tree should avoid using the phandle
485 65000 which is reserved by the toolstack.
486 Devices
488 The following options define the paravirtual, emulated and physical
489 devices which the guest will contain.
490 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 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 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 Each VTPM_SPEC_STRING is a comma-separated list of "KEY=VALUE"
507 settings from the following list:
508 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 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 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 Each 9PFS_SPEC_STRING is a comma-separated list of "KEY=VALUE"
528 settings, from the following list:
529 tag=STRING
531 9pfs tag to identify the filesystem share. The tag is needed on
532 the guest side to mount it.
533 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 path=STRING
540 Filesystem path on the backend to export.
541 backend=domain-id
543 Specify the backend domain name or id, defaults to dom0.
544 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 vfb=[ "VFB_SPEC_STRING", "VFB_SPEC_STRING", ...]
552 Specifies the paravirtual framebuffer devices which should be
553 supplied to the domain.
554 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 Each VFB_SPEC_STRING is a comma-separated list of "KEY=VALUE"
563 settings, from the following list:
564 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 vnclisten=ADDRESS[:DISPLAYNUM]
570 Specifies the IP address, and optionally the VNC display
571 number, to use.
572 Note: if you specify the display number here, you should not
574 use the vncdisplay option.
575 vncdisplay=DISPLAYNUM
577 Specifies the VNC display number to use. The actual TCP port
578 number will be DISPLAYNUM+5900.
579 Note: you should not use this option if you set the DISPLAYNUM
581 in the vnclisten option.
582 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 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 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 display=DISPLAY
599 Specifies the X Window display that should be used when the sdl
600 option is used.
601 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 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 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 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 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 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 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 connection=CONNECTION
650 Specifies how the backend will be implemented. The following
651 options are available:
652 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 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 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 RDM_RESERVATION_STRING is a comma separated list of "KEY=VALUE"
670 settings, from the following list:
671 strategy=STRING
673 Currently there is only one valid type, and that is "host".
674 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 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 Note: this option is not recommended unless you can make
688 sure that no conflicts exist.
689 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 Device A [sbdf_A]: RMRR region_A: base_addr ac6d3000
695 end_address ac6e6fff
696 Device B [sbdf_B]: RMRR region_B: base_addr ad800000
698 end_address afffffff
699 In this conflict case,
701 #1. If strategy is set to "host", for example:
703 rdm = "strategy=host,policy=strict" or rdm =
705 "strategy=host,policy=relaxed"
706 it means all conflicts will be handled according to the
708 policy introduced by policy as described below.
709 #2. If strategy is not set at all, but
711 pci = [ 'sbdf_A, rdm_policy=xxxxx' ]
713 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 policy=STRING
719 Specifies how to deal with conflicts when reserving already
720 reserved device memory in the guest address space.
721 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 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 Note: this may be overridden by the rdm_policy option in
735 the pci device configuration.
736 usbctrl=[ "USBCTRL_SPEC_STRING", "USBCTRL_SPEC_STRING", ...]
738 Specifies the USB controllers created for this guest.
739 Each USBCTRL_SPEC_STRING is a comma-separated list of "KEY=VALUE"
741 settings, from the following list:
742 type=TYPE
744 Specifies the usb controller type.
745 pv Specifies a kernel based PVUSB backend.
747 qusb
749 Specifies a QEMU based PVUSB backend.
750 devicemodel
752 Specifies a USB controller emulated by QEMU. It will show
753 up as a PCI-device in the guest.
754 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 This option is the default.
761 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 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 USB controller ids start from 0. In line with the USB
775 specification, however, ports on a controller start from 1.
776 EXAMPLE
778 usbctrl=["version=1,ports=4", "version=2,ports=8"]
780 The first controller is USB1.1 and has:
782 controller id = 0, and ports 1,2,3,4.
784 The second controller is USB2.0 and has:
786 controller id = 1, and ports 1,2,3,4,5,6,7,8.
788 usbdev=[ "USBDEV_SPEC_STRING", "USBDEV_SPEC_STRING", ...]
790 Specifies the USB devices to be attached to the guest at boot.
791 Each USBDEV_SPEC_STRING is a comma-separated list of "KEY=VALUE"
793 settings, from the following list:
794 type=hostdev
796 Specifies USB device type. Currently only "hostdev" is
797 supported.
798 hostbus=busnum
800 Specifies busnum of the USB device from the host perspective.
801 hostaddr=devnum
803 Specifies devnum of the USB device from the host perspective.
804 controller=CONTROLLER
806 Specifies the USB controller id, to which controller the USB
807 device is attached.
808 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 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 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 [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 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 @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 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 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 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 seize=BOOLEAN
862 Tells xl to automatically attempt to re-assign a device to
863 pciback if it is not already assigned.
864 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 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 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 Note: this would override global rdm option.
880 pci_permissive=BOOLEAN
882 Changes the default value of permissive for all PCI devices passed
883 through to this VM. See permissive above.
884 pci_msitranslate=BOOLEAN
886 Changes the default value of msitranslate for all PCI devices
887 passed through to this VM. See msitranslate above.
888 pci_seize=BOOLEAN
890 Changes the default value of seize for all PCI devices passed
891 through to this VM. See seize above.
892 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 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 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 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 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 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 gfx_passthru is currently supported both with the qemu-xen-
928 traditional device-model and upstream qemu-xen device-model.
929 When given as a boolean the gfx_passthru option either disables
931 graphics card passthrough or enables autodetection.
932 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 Currently, valid values for the option are:
940 0 Disables graphics device PCI passthrough.
942 1, "default"
944 Enables graphics device PCI passthrough and autodetects the
945 type of device which is being used.
946 "igd"
948 Enables graphics device PCI passthrough but forcing the type of
949 device to Intel Graphics Device.
950 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 More information about the Xen gfx_passthru feature is available on
959 the XenVGAPassthrough <http://wiki.xen.org/wiki/XenVGAPassthrough>
960 wiki page.
961 rdm_mem_boundary=MBYTES
963 Number of megabytes to set for a boundary when checking for RDM
964 conflicts.
965 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 #1. Above a predefined boundary
973 - move lowmem_end below the reserved region to solve the conflict;
974 #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 The default value is 2048.
985 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 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 It is recommended to only use this option for trusted VMs under
997 administrator's control.
998 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 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 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 It is recommended to only use this option for trusted VMs under
1017 administrator's control.
1018 irqs=[ NUMBER, NUMBER, ...]
1020 Allow a guest to access specific physical IRQs.
1021 It is recommended to only use this option for trusted VMs under
1023 administrator's control.
1024 If vuart console is enabled then irq 32 is reserved for it. See
1026 "vuart="uart"" to know how to enable vuart console.
1027 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 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 vdispl=[ "VDISPL_SPEC_STRING", "VDISPL_SPEC_STRING", ...]
1039 Specifies the virtual display devices to be provided to the guest.
1040 Each VDISPL_SPEC_STRING is a comma-separated list of "KEY=VALUE"
1042 settings, from the following list:
1043 "backend=DOMAIN"
1045 Specifies the backend domain name or id. If not specified
1046 Domain-0 is used.
1047 "be-alloc=BOOLEAN"
1049 Indicates if backend can be a buffer provider/allocator for
1050 this domain. See display protocol for details.
1051 "connectors=CONNECTORS"
1053 Specifies virtual connectors for the device in following format
1054 <id>:<W>x<H>;<id>:<W>x<H>... where:
1055 "id"
1057 String connector unique id. Space, comma symbols are not
1058 allowed.
1059 "W" Connector width in pixels.
1061 "H" Connector height in pixels.
1063 EXAMPLE
1065 connectors=id0:1920x1080;id1:800x600;id2:640x480
1067 dm_restrict=BOOLEAN
1069 Restrict the device model after startup, to limit the consequencese
1070 of security vulnerabilities in qemu.
1071 See docs/features/qemu-depriv.pandoc for more information on Linux
1073 and QEMU version requirements, device model user setup, and current
1074 limitations.
1075 This feature is a technology preview. See SUPPORT.md for a
1077 security support statement.
1078 device_model_user=USERNAME
1080 When running dm_restrict, run the device model as this user.
1081 NOTE: Each domain MUST have a SEPARATE username.
1083 See docs/features/qemu-depriv.pandoc for more information.
1085 vsnd=[ VCARD_SPEC, VCARD_SPEC, ... ]
1087 Specifies the virtual sound cards to be provided to the guest.
1088 Each VCARD_SPEC is a list, which has a form of "[VSND_ITEM_SPEC,
1089 VSND_ITEM_SPEC, ... ]" (without the quotes). The virtual sound
1090 card has hierarchical structure. Every card has a set of PCM
1091 devices and streams, each could be individually configured.
1092 VSND_ITEM_SPEC describes individual item parameters.
1094 VSND_ITEM_SPEC is a string of comma separated item parameters
1095 headed by item identifier. Each item parameter is "KEY=VALUE" pair:
1096 "identifier, param = value, ...".
1098 Identifier shall be one of following values: "CARD", "PCM",
1100 "STREAM". The child item treated as belonging to the previously
1101 defined parent item.
1102 All parameters are optional.
1104 There are group of parameters which are common for all items. This
1106 group can be defined at higher level of the hierarchy and be fully
1107 or partially re-used by the underlying layers. These parameters
1108 are:
1109 * number of channels (min/max)
1111 * supported sample rates
1113 * supported sample formats
1115 E.g. one can define these values for the whole card, device or
1117 stream. Every underlying layer in turn can re-define some or all
1118 of them to better fit its needs. For example, card may define
1119 number of channels to be in [1; 8] range, and some particular
1120 stream may be limited to [1; 2] only. The rule is that the
1121 underlying layer must be a subset of the upper layer range.
1122 COMMON parameters:
1124 sample-rates=RATES
1126 List of integer values separated by semicolon:
1127 sample-rates=8000;22050;44100
1128 sample-formats=FORMATS
1130 List of string values separated by semicolon:
1131 sample-formats=s16_le;s8;u32_be
1132 Supported formats: s8, u8, s16_le, s16_be, u16_le, u16_be,
1134 s24_le, s24_be, u24_le, u24_be, s32_le, s32_be, u32_le,
1135 u32_be, float_le, float_be, float64_le, float64_be,
1136 iec958_subframe_le, iec958_subframe_be, mu_law, a_law,
1137 ima_adpcm, mpeg, gsm
1138 channels-min=NUMBER
1140 The minimum amount of channels.
1141 channels-max=NUMBER
1143 The maximum amount of channels.
1144 buffer-size=NUMBER
1146 The maximum size in octets of the buffer to allocate per
1147 stream.
1148 CARD specification:
1150 backend=domain-id
1152 Specify the backend domain name or id, defaults to dom0.
1153 short-name=STRING
1155 Short name of the virtual sound card.
1156 long-name=STRING
1158 Long name of the virtual sound card.
1159 PCM specification:
1161 name=STRING
1163 Name of the PCM sound device within the virtual sound card.
1164 STREAM specification:
1166 unique-id=STRING
1168 Unique stream identifier.
1169 type=TYPE
1171 Stream type: "p" - playback stream, "c" - capture stream.
1172 EXAMPLE:
1174 vsnd = [
1176 ['CARD, short-name=Main, sample-formats=s16_le;s8;u32_be',
1177 'PCM, name=Main',
1178 'STREAM, id=0, type=p',
1179 'STREAM, id=1, type=c, channels-max=2'
1180 ],
1181 ['CARD, short-name=Second',
1182 'PCM, name=Second, buffer-size=1024',
1183 'STREAM, id=2, type=p',
1184 'STREAM, id=3, type=c'
1185 ]
1186 ]
1187 vkb=[ "VKB_SPEC_STRING", "VKB_SPEC_STRING", ...]
1189 Specifies the virtual keyboard device to be provided to the guest.
1190 Each VKB_SPEC_STRING is a comma-separated list of "KEY=VALUE"
1192 settings from the following list:
1193 unique-id=STRING
1195 Specifies the unique input device id.
1196 backend=domain-id
1198 Specifies the backend domain name or id.
1199 backend-type=type
1201 Specifies the backend type: qemu - for QEMU backend or linux -
1202 for Linux PV domain.
1203 feature-disable-keyboard=BOOLEAN
1205 Indicates if keyboard device is disabled.
1206 feature-disable-pointer=BOOLEAN
1208 Indicates if pointer device is disabled.
1209 feature-abs-pointer=BOOLEAN
1211 Indicates if pointer device can return absolute coordinates.
1212 feature-raw-pointer=BOOLEAN
1214 Indicates if pointer device can return raw (unscaled) absolute
1215 coordinates.
1216 feature-multi-touch=BOOLEAN
1218 Indicates if input device supports multi touch.
1219 multi-touch-width=MULTI_TOUCH_WIDTH
1221 Set maximum width for multi touch device.
1222 multi-touch-height=MULTI_TOUCH_HEIGHT
1224 Set maximum height for multi touch device.
1225 multi-touch-num-contacts=MULTI_TOUCH_NUM_CONTACTS
1227 Set maximum contacts number for multi touch device.
1228 width=WIDTH
1230 Set maximum width for pointer device.
1231 height=HEIGHT
1233 Set maximum height for pointer device.
1234 Paravirtualised (PV) Guest Specific Options
1236 The following options apply only to Paravirtual (PV) guests.
1237 bootloader="PROGRAM"
1239 Run "PROGRAM" to find the kernel image and ramdisk to use.
1240 Normally "PROGRAM" would be "pygrub", which is an emulation of
1241 grub/grub2/syslinux. Either kernel or bootloader must be specified
1242 for PV guests.
1243 bootloader_args=[ "ARG", "ARG", ...]
1245 Append ARGs to the arguments to the bootloader program.
1246 Alternatively if the argument is a simple string then it will be
1247 split into words at whitespace (this second option is deprecated).
1248 e820_host=BOOLEAN
1250 Selects whether to expose the host e820 (memory map) to the guest
1251 via the virtual e820. When this option is false (0) the guest
1252 pseudo-physical address space consists of a single contiguous RAM
1253 region. When this option is specified the virtual e820 instead
1254 reflects the host e820 and contains the same PCI holes. The total
1255 amount of RAM represented by the memory map is always the same,
1256 this option configures only how it is laid out.
1257 Exposing the host e820 to the guest gives the guest kernel the
1259 opportunity to set aside the required part of its pseudo-physical
1260 address space in order to provide address space to map
1261 passedthrough PCI devices. It is guest Operating System dependent
1262 whether this option is required, specifically it is required when
1263 using a mainline Linux ("pvops") kernel. This option defaults to
1264 true (1) if any PCI passthrough devices are configured and false
1265 (0) otherwise. If you do not configure any passthrough devices at
1266 domain creation time but expect to hotplug devices later then you
1267 should set this option. Conversely if your particular guest kernel
1268 does not require this behaviour then it is safe to allow this to be
1269 enabled but you may wish to disable it anyway.
1270 Fully-virtualised (HVM) Guest Specific Options
1272 The following options apply only to Fully-virtualised (HVM) guests.
1273 Boot Device
1275 boot="STRING"
1277 Specifies the emulated virtual device to boot from.
1278 Possible values are:
1280 c Hard disk.
1282 d CD-ROM.
1284 n Network / PXE.
1286 Note: multiple options can be given and will be attempted in the
1288 order they are given, e.g. to boot from CD-ROM but fall back to the
1289 hard disk you can specify it as dc.
1290 The default is cd, meaning try booting from the hard disk first,
1292 but fall back to the CD-ROM.
1293 Emulated disk controller type
1295 hdtype=STRING
1297 Specifies the hard disk type.
1298 Possible values are:
1300 ide If thise mode is specified xl adds an emulated IDE controller,
1302 which is suitable even for older operation systems.
1303 ahci
1305 If this mode is specified, xl adds an ich9 disk controller in
1306 AHCI mode and uses it with upstream QEMU to emulate disks
1307 instead of IDE. It decreases boot time but may not be supported
1308 by default in older operating systems, e.g. Windows XP.
1309 The default is ide.
1311 Paging
1313 The following options control the mechanisms used to virtualise guest
1315 memory. The defaults are selected to give the best results for the
1316 common cases so you should normally leave these options unspecified.
1317 hap=BOOLEAN
1319 Turns "hardware assisted paging" (the use of the hardware nested
1320 page table feature) on or off. This feature is called EPT
1321 (Extended Page Tables) by Intel and NPT (Nested Page Tables) or RVI
1322 (Rapid Virtualisation Indexing) by AMD. If turned off, Xen will run
1323 the guest in "shadow page table" mode where the guest's page table
1324 updates and/or TLB flushes etc. will be emulated. Use of HAP is
1325 the default when available.
1326 oos=BOOLEAN
1328 Turns "out of sync pagetables" on or off. When running in shadow
1329 page table mode, the guest's page table updates may be deferred as
1330 specified in the Intel/AMD architecture manuals. However, this may
1331 expose unexpected bugs in the guest, or find bugs in Xen, so it is
1332 possible to disable this feature. Use of out of sync page tables,
1333 when Xen thinks it appropriate, is the default.
1334 shadow_memory=MBYTES
1336 Number of megabytes to set aside for shadowing guest pagetable
1337 pages (effectively acting as a cache of translated pages) or to use
1338 for HAP state. By default this is 1MB per guest vCPU plus 8KB per
1339 MB of guest RAM. You should not normally need to adjust this value.
1340 However, if you are not using hardware assisted paging (i.e. you
1341 are using shadow mode) and your guest workload consists of a very
1342 large number of similar processes then increasing this value may
1343 improve performance.
1344 Processor and Platform Features
1346 The following options allow various processor and platform level
1348 features to be hidden or exposed from the guest's point of view. This
1349 can be useful when running older guest Operating Systems which may
1350 misbehave when faced with more modern features. In general, you should
1351 accept the defaults for these options wherever possible.
1352 bios="STRING"
1354 Select the virtual firmware that is exposed to the guest. By
1355 default, a guess is made based on the device model, but sometimes
1356 it may be useful to request a different one, like UEFI.
1357 rombios
1359 Loads ROMBIOS, a 16-bit x86 compatible BIOS. This is used by
1360 default when device_model_version=qemu-xen-traditional. This is
1361 the only BIOS option supported when
1362 device_model_version=qemu-xen-traditional. This is the BIOS
1363 used by all previous Xen versions.
1364 seabios
1366 Loads SeaBIOS, a 16-bit x86 compatible BIOS. This is used by
1367 default with device_model_version=qemu-xen.
1368 ovmf
1370 Loads OVMF, a standard UEFI firmware by Tianocore project.
1371 Requires device_model_version=qemu-xen.
1372 bios_path_override="PATH"
1374 Override the path to the blob to be used as BIOS. The blob provided
1375 here MUST be consistent with the bios= which you have specified.
1376 You should not normally need to specify this option.
1377 This option does not have any effect if using bios="rombios" or
1379 device_model_version="qemu-xen-traditional".
1380 pae=BOOLEAN
1382 Hide or expose the IA32 Physical Address Extensions. These
1383 extensions make it possible for a 32 bit guest Operating System to
1384 access more than 4GB of RAM. Enabling PAE also enabled other
1385 features such as NX. PAE is required if you wish to run a 64-bit
1386 guest Operating System. In general, you should leave this enabled
1387 and allow the guest Operating System to choose whether or not to
1388 use PAE. (X86 only)
1389 acpi=BOOLEAN
1391 Expose ACPI (Advanced Configuration and Power Interface) tables
1392 from the virtual firmware to the guest Operating System. ACPI is
1393 required by most modern guest Operating Systems. This option is
1394 enabled by default and usually you should omit it. However, it may
1395 be necessary to disable ACPI for compatibility with some guest
1396 Operating Systems. This option is true for x86 while it's false
1397 for ARM by default.
1398 acpi_s3=BOOLEAN
1400 Include the S3 (suspend-to-ram) power state in the virtual firmware
1401 ACPI table. True (1) by default.
1402 acpi_s4=BOOLEAN
1404 Include S4 (suspend-to-disk) power state in the virtual firmware
1405 ACPI table. True (1) by default.
1406 acpi_laptop_slate=BOOLEAN
1408 Include the Windows laptop/slate mode switch device in the virtual
1409 firmware ACPI table. False (0) by default.
1410 apic=BOOLEAN
1412 (x86 only) Include information regarding APIC (Advanced
1413 Programmable Interrupt Controller) in the firmware/BIOS tables on a
1414 single processor guest. This causes the MP (multiprocessor) and PIR
1415 (PCI Interrupt Routing) tables to be exported by the virtual
1416 firmware. This option has no effect on a guest with multiple
1417 virtual CPUs as they must always include these tables. This option
1418 is enabled by default and you should usually omit it but it may be
1419 necessary to disable these firmware tables when using certain older
1420 guest Operating Systems. These tables have been superseded by newer
1421 constructs within the ACPI tables.
1422 nx=BOOLEAN
1424 (x86 only) Hides or exposes the No-eXecute capability. This allows
1425 a guest Operating System to map pages in such a way that they
1426 cannot be executed which can enhance security. This options
1427 requires that PAE also be enabled.
1428 hpet=BOOLEAN
1430 (x86 only) Enables or disables HPET (High Precision Event Timer).
1431 This option is enabled by default and you should usually omit it.
1432 It may be necessary to disable the HPET in order to improve
1433 compatibility with guest Operating Systems.
1434 altp2m="MODE"
1436 (x86 only) Specifies the access mode to the alternate-p2m
1437 capability. Alternate-p2m allows a guest to manage multiple p2m
1438 guest physical "memory views" (as opposed to a single p2m). You
1439 may want this option if you want to access-control/isolate access
1440 to specific guest physical memory pages accessed by the guest, e.g.
1441 for domain memory introspection or for isolation/access-control of
1442 memory between components within a single guest domain. This option
1443 is disabled by default.
1444 The valid values are as follows:
1446 disabled
1448 Altp2m is disabled for the domain (default).
1449 mixed
1451 The mixed mode allows access to the altp2m interface for both
1452 in-guest and external tools as well.
1453 external
1455 Enables access to the alternate-p2m capability by external
1456 privileged tools.
1457 limited
1459 Enables limited access to the alternate-p2m capability, ie.
1460 giving the guest access only to enable/disable the VMFUNC and
1461 #VE features.
1462 altp2mhvm=BOOLEAN
1464 Enables or disables HVM guest access to alternate-p2m capability.
1465 Alternate-p2m allows a guest to manage multiple p2m guest physical
1466 "memory views" (as opposed to a single p2m). This option is
1467 disabled by default and is available only to HVM domains. You may
1468 want this option if you want to access-control/isolate access to
1469 specific guest physical memory pages accessed by the guest, e.g.
1470 for HVM domain memory introspection or for isolation/access-control
1471 of memory between components within a single guest HVM domain. This
1472 option is deprecated, use the option "altp2m" instead.
1473 Note: While the option "altp2mhvm" is deprecated, legacy
1475 applications for x86 systems will continue to work using it.
1476 nestedhvm=BOOLEAN
1478 Enable or disables guest access to hardware virtualisation
1479 features, e.g. it allows a guest Operating System to also function
1480 as a hypervisor. You may want this option if you want to run
1481 another hypervisor (including another copy of Xen) within a Xen
1482 guest or to support a guest Operating System which uses hardware
1483 virtualisation extensions (e.g. Windows XP compatibility mode on
1484 more modern Windows OS). This option is disabled by default.
1485 cpuid="LIBXL_STRING" or cpuid=[ "XEND_STRING", "XEND_STRING" ]
1487 Configure the value returned when a guest executes the CPUID
1488 instruction. Two versions of config syntax are recognized: libxl
1489 and xend.
1490 The libxl syntax is a comma separated list of key=value pairs,
1492 preceded by the word "host". A few keys take a numerical value, all
1493 others take a single character which describes what to do with the
1494 feature bit.
1495 Possible values for a single feature bit:
1497 '1' -> force the corresponding bit to 1
1498 '0' -> force to 0
1499 'x' -> Get a safe value (pass through and mask with the default
1500 policy)
1501 'k' -> pass through the host bit value
1502 's' -> as 'k' but preserve across save/restore and migration (not
1503 implemented)
1504 Note: when specifying cpuid for hypervisor leaves (0x4000xxxx major
1506 group) only the lowest 8 bits of leaf's 0x4000xx00 EAX register are
1507 processed, the rest are ignored (these 8 bits signify maximum
1508 number of hypervisor leaves).
1509 List of keys taking a value: apicidsize brandid clflush family
1511 localapicid maxleaf maxhvleaf model nc proccount procpkg stepping
1512 List of keys taking a character: 3dnow 3dnowext 3dnowprefetch abm
1514 acpi adx aes altmovcr8 apic arat avx avx2 avx512-4fmaps
1515 avx512-4vnniw avx512bw avx512cd avx512dq avx512er avx512f
1516 avx512ifma avx512pf avx512vbmi avx512vl bmi1 bmi2 clflushopt clfsh
1517 clwb cmov cmplegacy cmpxchg16 cmpxchg8 cmt cntxid dca de ds dscpl
1518 dtes64 erms est extapic f16c ffxsr fma fma4 fpu fsgsbase fxsr hle
1519 htt hypervisor ia64 ibs invpcid invtsc lahfsahf lm lwp mca mce
1520 misalignsse mmx mmxext monitor movbe mpx msr mtrr nodeid nx ospke
1521 osvw osxsave pae page1gb pat pbe pcid pclmulqdq pdcm perfctr_core
1522 perfctr_nb pge pku popcnt pse pse36 psn rdrand rdseed rdtscp rtm
1523 sha skinit smap smep smx ss sse sse2 sse3 sse4.1 sse4.2 sse4_1
1524 sse4_2 sse4a ssse3 svm svm_decode svm_lbrv svm_npt svm_nrips
1525 svm_pausefilt svm_tscrate svm_vmcbclean syscall sysenter tbm tm tm2
1526 topoext tsc tsc-deadline tsc_adjust umip vme vmx wdt x2apic xop
1527 xsave xtpr
1528 The xend syntax is a list of values in the form of
1530 'leafnum:register=bitstring,register=bitstring'
1531 "leafnum" is the requested function,
1532 "register" is the response register to modify
1533 "bitstring" represents all bits in the register, its length must
1534 be 32 chars.
1535 Each successive character represent a lesser-significant bit,
1536 possible values
1537 are listed above in the libxl section.
1538 Example to hide two features from the guest: 'tm', which is bit #29
1540 in EDX, and 'pni' (SSE3), which is bit #0 in ECX:
1541 xend: [
1543 "1:ecx=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx0,edx=xx0xxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
1544 ]
1545 libxl: "host,tm=0,sse3=0"
1547 More info about the CPUID instruction can be found in the processor
1549 manuals, and on Wikipedia: <http://en.wikipedia.org/wiki/CPUID>
1550 acpi_firmware="STRING"
1552 Specifies a path to a file that contains extra ACPI firmware tables
1553 to pass into a guest. The file can contain several tables in their
1554 binary AML form concatenated together. Each table self describes
1555 its length so no additional information is needed. These tables
1556 will be added to the ACPI table set in the guest. Note that
1557 existing tables cannot be overridden by this feature. For example,
1558 this cannot be used to override tables like DSDT, FADT, etc.
1559 smbios_firmware="STRING"
1561 Specifies a path to a file that contains extra SMBIOS firmware
1562 structures to pass into a guest. The file can contain a set of DMTF
1563 predefined structures which will override the internal defaults.
1564 Not all predefined structures can be overridden, only the following
1565 types: 0, 1, 2, 3, 11, 22, 39. The file can also contain any number
1566 of vendor defined SMBIOS structures (type 128 - 255). Since SMBIOS
1567 structures do not present their overall size, each entry in the
1568 file must be preceded by a 32b integer indicating the size of the
1569 following structure.
1570 ms_vm_genid="OPTION"
1572 Provide a VM generation ID to the guest.
1573 The VM generation ID is a 128-bit random number that a guest may
1575 use to determine if the guest has been restored from an earlier
1576 snapshot or cloned.
1577 This is required for Microsoft Windows Server 2012 (and later)
1579 domain controllers.
1580 Valid options are:
1582 generate
1584 Generate a random VM generation ID every time the domain is
1585 created or restored.
1586 none
1588 Do not provide a VM generation ID.
1589 See also "Virtual Machine Generation ID" by Microsoft:
1591 <http://www.microsoft.com/en-us/download/details.aspx?id=30707>
1592 Guest Virtual Time Controls
1594 tsc_mode="MODE"
1596 (x86 only) Specifies how the TSC (Time Stamp Counter) should be
1597 provided to the guest. Specifying this option as a number is
1598 deprecated.
1599 Options are:
1601 default
1603 Guest rdtsc/p is executed natively when monotonicity can be
1604 guaranteed and emulated otherwise (with frequency scaled if
1605 necessary).
1606 If a HVM container in default TSC mode is created on a host
1608 that provides constant host TSC, its guest TSC frequency will
1609 be the same as the host. If it is later migrated to another
1610 host that provide constant host TSC and supports Intel VMX TSC
1611 scaling/AMD SVM TSC ratio, its guest TSC frequency will be the
1612 same before and after migration, and guest rdtsc/p will be
1613 executed natively after migration as well
1614 always_emulate
1616 Guest rdtsc/p is always emulated and the virtual TSC will
1617 appear to increment (kernel and user) at a fixed 1GHz rate,
1618 regardless of the pCPU HZ rate or power state. Although there
1619 is an overhead associated with emulation, this will NOT affect
1620 underlying CPU performance.
1621 native
1623 Guest rdtsc/p is always executed natively (no
1624 monotonicity/frequency guarantees). Guest rdtsc/p is emulated
1625 at native frequency if unsupported by h/w, else executed
1626 natively.
1627 native_paravirt
1629 This mode has been removed.
1630 Please see xen-tscmode(7) for more information on this option.
1632 localtime=BOOLEAN
1634 Set the real time clock to local time or to UTC. False (0) by
1635 default, i.e. set to UTC.
1636 rtc_timeoffset=SECONDS
1638 Set the real time clock offset in seconds. No offset (0) by
1639 default.
1640 vpt_align=BOOLEAN
1642 Specifies that periodic Virtual Platform Timers should be aligned
1643 to reduce guest interrupts. Enabling this option can reduce power
1644 consumption, especially when a guest uses a high timer interrupt
1645 frequency (HZ) values. The default is true (1).
1646 timer_mode="MODE"
1648 Specifies the mode for Virtual Timers. The valid values are as
1649 follows:
1650 delay_for_missed_ticks
1652 Delay for missed ticks. Do not advance a vCPU's time beyond the
1653 correct delivery time for interrupts that have been missed due
1654 to preemption. Deliver missed interrupts when the vCPU is
1655 rescheduled and advance the vCPU's virtual time stepwise for
1656 each one.
1657 no_delay_for_missed_ticks
1659 No delay for missed ticks. As above, missed interrupts are
1660 delivered, but guest time always tracks wallclock (i.e., real)
1661 time while doing so. This is the default.
1662 no_missed_ticks_pending
1664 No missed interrupts are held pending. Instead, to ensure ticks
1665 are delivered at some non-zero rate, if we detect missed ticks
1666 then the internal tick alarm is not disabled if the vCPU is
1667 preempted during the next tick period.
1668 one_missed_tick_pending
1670 One missed tick pending. Missed interrupts are collapsed
1671 together and delivered as one 'late tick'. Guest time always
1672 tracks wallclock (i.e., real) time.
1673 Memory layout
1675 mmio_hole=MBYTES
1677 Specifies the size the MMIO hole below 4GiB will be. Only valid
1678 for device_model_version="qemu-xen".
1679 Cannot be smaller than 256. Cannot be larger than 3840.
1681 Known good large value is 3072.
1683 Support for Paravirtualisation of HVM Guests
1685 The following options allow Paravirtualised features (such as devices)
1687 to be exposed to the guest Operating System in an HVM guest. Utilising
1688 these features requires specific guest support but when available they
1689 will result in improved performance.
1690 xen_platform_pci=BOOLEAN
1692 Enable or disable the Xen platform PCI device. The presence of
1693 this virtual device enables a guest Operating System (subject to
1694 the availability of suitable drivers) to make use of
1695 paravirtualisation features such as disk and network devices etc.
1696 Enabling these drivers improves performance and is strongly
1697 recommended when available. PV drivers are available for various
1698 Operating Systems including HVM Linux
1699 <http://wiki.xen.org/wiki/XenLinuxPVonHVMdrivers> and Microsoft
1700 Windows <http://wiki.xen.org/wiki/XenWindowsGplPv>.
1701 Setting xen_platform_pci=0 with the default device_model "qemu-xen"
1703 requires at least QEMU 1.6.
1704 viridian=[ "GROUP", "GROUP", ...] or viridian=BOOLEAN
1706 The groups of Microsoft Hyper-V (AKA viridian) compatible
1707 enlightenments exposed to the guest. The following groups of
1708 enlightenments may be specified:
1709 base
1711 This group incorporates the Hypercall MSRs, Virtual processor
1712 index MSR, and APIC access MSRs. These enlightenments can
1713 improve performance of Windows Vista and Windows Server 2008
1714 onwards and setting this option for such guests is strongly
1715 recommended. This group is also a pre-requisite for all
1716 others. If it is disabled then it is an error to attempt to
1717 enable any other group.
1718 freq
1720 This group incorporates the TSC and APIC frequency MSRs. These
1721 enlightenments can improve performance of Windows 7 and Windows
1722 Server 2008 R2 onwards.
1723 time_ref_count
1725 This group incorporates Partition Time Reference Counter MSR.
1726 This enlightenment can improve performance of Windows 8 and
1727 Windows Server 2012 onwards.
1728 reference_tsc
1730 This set incorporates the Partition Reference TSC MSR. This
1731 enlightenment can improve performance of Windows 7 and Windows
1732 Server 2008 R2 onwards.
1733 hcall_remote_tlb_flush
1735 This set incorporates use of hypercalls for remote TLB
1736 flushing. This enlightenment may improve performance of
1737 Windows guests running on hosts with higher levels of
1738 (physical) CPU contention.
1739 apic_assist
1741 This set incorporates use of the APIC assist page to avoid EOI
1742 of the local APIC. This enlightenment may improve performance
1743 of guests that make use of per-vCPU event channel upcall
1744 vectors. Note that this enlightenment will have no effect if
1745 the guest is using APICv posted interrupts.
1746 crash_ctl
1748 This group incorporates the crash control MSRs. These
1749 enlightenments allow Windows to write crash information such
1750 that it can be logged by Xen.
1751 defaults
1753 This is a special value that enables the default set of groups,
1754 which is currently the base, freq, time_ref_count, apic_assist
1755 and crash_ctl groups.
1756 all This is a special value that enables all available groups.
1758 Groups can be disabled by prefixing the name with '!'. So, for
1760 example, to enable all groups except freq, specify:
1761 viridian=[ "all", "!freq" ]
1763 For details of the enlightenments see the latest version of
1765 Microsoft's Hypervisor Top-Level Functional Specification.
1766 The enlightenments should be harmless for other versions of Windows
1768 (although they will not give any benefit) and the majority of other
1769 non-Windows OSes. However it is known that they are incompatible
1770 with some other Operating Systems and in some circumstance can
1771 prevent Xen's own paravirtualisation interfaces for HVM guests from
1772 being used.
1773 The viridian option can be specified as a boolean. A value of true
1775 (1) is equivalent to the list [ "defaults" ], and a value of false
1776 (0) is equivalent to an empty list.
1777 Emulated VGA Graphics Device
1779 The following options control the features of the emulated graphics
1781 device. Many of these options behave similarly to the equivalent key
1782 in the VFB_SPEC_STRING for configuring virtual frame buffer devices
1783 (see above).
1784 videoram=MBYTES
1786 Sets the amount of RAM which the emulated video card will contain,
1787 which in turn limits the resolutions and bit depths which will be
1788 available.
1789 When using the qemu-xen-traditional device-model, the default as
1791 well as minimum amount of video RAM for stdvga is 8 MB, which is
1792 sufficient for e.g. 1600x1200 at 32bpp. For the upstream qemu-xen
1793 device-model, the default and minimum is 16 MB.
1794 When using the emulated Cirrus graphics card (vga="cirrus") and the
1796 qemu-xen-traditional device-model, the amount of video RAM is fixed
1797 at 4 MB, which is sufficient for 1024x768 at 32 bpp. For the
1798 upstream qemu-xen device-model, the default and minimum is 8 MB.
1799 For QXL vga, both the default and minimal are 128MB. If videoram
1801 is set less than 128MB, an error will be triggered.
1802 stdvga=BOOLEAN
1804 Speficies a standard VGA card with VBE (VESA BIOS Extensions) as
1805 the emulated graphics device. If your guest supports VBE 2.0 or
1806 later (e.g. Windows XP onwards) then you should enable this.
1807 stdvga supports more video ram and bigger resolutions than Cirrus.
1808 The default is false (0) which means to emulate a Cirrus Logic
1809 GD5446 VGA card. This option is deprecated, use vga="stdvga"
1810 instead.
1811 vga="STRING"
1813 Selects the emulated video card. Options are: none, stdvga, cirrus
1814 and qxl. The default is cirrus.
1815 In general, QXL should work with the Spice remote display protocol
1817 for acceleration, and a QXL driver is necessary in the guest in
1818 that case. QXL can also work with the VNC protocol, but it will be
1819 like a standard VGA card without acceleration.
1820 vnc=BOOLEAN
1822 Allow access to the display via the VNC protocol. This enables the
1823 other VNC-related settings. The default is (1) enabled.
1824 vnclisten="ADDRESS[:DISPLAYNUM]"
1826 Specifies the IP address and, optionally, the VNC display number to
1827 use.
1828 vncdisplay=DISPLAYNUM
1830 Specifies the VNC display number to use. The actual TCP port number
1831 will be DISPLAYNUM+5900.
1832 vncunused=BOOLEAN
1834 Requests that the VNC display setup searches for a free TCP port to
1835 use. The actual display used can be accessed with xl vncviewer.
1836 vncpasswd="PASSWORD"
1838 Specifies the password for the VNC server. If the password is set
1839 to an empty string, authentication on the VNC server will be
1840 disabled allowing any user to connect.
1841 keymap="LANG"
1843 Configure the keymap to use for the keyboard associated with this
1844 display. If the input method does not easily support raw keycodes
1845 (e.g. this is often the case when using VNC) then this allows us to
1846 correctly map the input keys into keycodes seen by the guest. The
1847 specific values which are accepted are defined by the version of
1848 the device-model which you are using. See Keymaps below or consult
1849 the qemu(1) manpage. The default is en-us.
1850 sdl=BOOLEAN
1852 Specifies that the display should be presented via an X window
1853 (using Simple DirectMedia Layer). The default is (0) not enabled.
1854 opengl=BOOLEAN
1856 Enable OpenGL acceleration of the SDL display. Only effects
1857 machines using device_model_version="qemu-xen-traditional" and only
1858 if the device-model was compiled with OpenGL support. Default is
1859 (0) false.
1860 nographic=BOOLEAN
1862 Enable or disable the virtual graphics device. The default is to
1863 provide a VGA graphics device but this option can be used to
1864 disable it.
1865 Spice Graphics Support
1867 The following options control the features of SPICE.
1869 spice=BOOLEAN
1871 Allow access to the display via the SPICE protocol. This enables
1872 the other SPICE-related settings.
1873 spicehost="ADDRESS"
1875 Specifies the interface address to listen on if given, otherwise
1876 any interface.
1877 spiceport=NUMBER
1879 Specifies the port to listen on by the SPICE server if SPICE is
1880 enabled.
1881 spicetls_port=NUMBER
1883 Specifies the secure port to listen on by the SPICE server if SPICE
1884 is enabled. At least one of spiceport or spicetls_port must be
1885 given if SPICE is enabled.
1886 Note: the options depending on spicetls_port have not been
1888 supported.
1889 spicedisable_ticketing=BOOLEAN
1891 Enable clients to connect without specifying a password. When
1892 disabled, spicepasswd must be set. The default is (0) false.
1893 spicepasswd="PASSWORD"
1895 Specify the password which is used by clients for establishing a
1896 connection.
1897 spiceagent_mouse=BOOLEAN
1899 Whether SPICE agent is used for client mouse mode. The default is
1900 (1) true.
1901 spicevdagent=BOOLEAN
1903 Enables the SPICE vdagent. The SPICE vdagent is an optional
1904 component for enhancing user experience and performing guest-
1905 oriented management tasks. Its features include: client mouse mode
1906 (no need to grab the mouse by the client, no mouse lag), automatic
1907 adjustment of screen resolution, copy and paste (text and image)
1908 between the client and the guest. It also requires the vdagent
1909 service installed on the guest OS to work. The default is (0)
1910 disabled.
1911 spice_clipboard_sharing=BOOLEAN
1913 Enables SPICE clipboard sharing (copy/paste). It requires that
1914 spicevdagent is enabled. The default is (0) false.
1915 spiceusbredirection=NUMBER
1917 Enables SPICE USB redirection. Creates a NUMBER of USB redirection
1918 channels for redirecting up to 4 USB devices from the SPICE client
1919 to the guest's QEMU. It requires an USB controller and, if not
1920 defined, it will automatically add an USB2.0 controller. The
1921 default is (0) disabled.
1922 spice_image_compression="COMPRESSION"
1924 Specifies what image compression is to be used by SPICE (if given),
1925 otherwise the QEMU default will be used. Please see the
1926 documentation of your QEMU version for more details.
1927 Available options are: auto_glz, auto_lz, quic, glz, lz, off.
1929 spice_streaming_video="VIDEO"
1931 Specifies what streaming video setting is to be used by SPICE (if
1932 given), otherwise the QEMU default will be used.
1933 Available options are: filter, all, off.
1935 Miscellaneous Emulated Hardware
1937 serial=[ "DEVICE", "DEVICE", ...]
1939 Redirect virtual serial ports to DEVICEs. Please see the -serial
1940 option in the qemu(1) manpage for details of the valid DEVICE
1941 options. Default is vc when in graphical mode and stdio if
1942 nographics=1 is used.
1943 The form serial=DEVICE is also accepted for backwards
1945 compatibility.
1946 soundhw="DEVICE"
1948 Select the virtual sound card to expose to the guest. The valid
1949 devices are defined by the device model configuration, please see
1950 the qemu(1) manpage for details. The default is not to export any
1951 sound device.
1952 usb=BOOLEAN
1954 Enables or disables an emulated USB bus in the guest.
1955 usbversion=NUMBER
1957 Specifies the type of an emulated USB bus in the guest, values 1
1958 for USB1.1, 2 for USB2.0 and 3 for USB3.0. It is available only
1959 with an upstream QEMU. Due to implementation limitations this is
1960 not compatible with the usb and usbdevice parameters. Default is
1961 (0) no USB controller defined.
1962 usbdevice=[ "DEVICE", "DEVICE", ...]
1964 Adds DEVICEs to the emulated USB bus. The USB bus must also be
1965 enabled using usb=1. The most common use for this option is
1966 usbdevice=['tablet'] which adds a pointer device using absolute
1967 coordinates. Such devices function better than relative coordinate
1968 devices (such as a standard mouse) since many methods of exporting
1969 guest graphics (such as VNC) work better in this mode. Note that
1970 this is independent of the actual pointer device you are using on
1971 the host/client side.
1972 Host devices can also be passed through in this way, by specifying
1974 host:USBID, where USBID is of the form xxxx:yyyy. The USBID can
1975 typically be found by using lsusb(1) or usb-devices(1).
1976 If you wish to use the "host:bus.addr" format, remove any leading
1978 '0' from the bus and addr. For example, for the USB device on bus
1979 008 dev 002, you should write "host:8.2".
1980 The form usbdevice=DEVICE is also accepted for backwards
1982 compatibility.
1983 More valid options can be found in the "usbdevice" section of the
1985 QEMU documentation.
1986 vendor_device="VENDOR_DEVICE"
1988 Selects which variant of the QEMU xen-pvdevice should be used for
1989 this guest. Valid values are:
1990 none
1992 The xen-pvdevice should be omitted. This is the default.
1993 xenserver
1995 The xenserver variant of the xen-pvdevice (device-id=C000) will
1996 be specified, enabling the use of XenServer PV drivers in the
1997 guest.
1998 This parameter only takes effect when
2000 device_model_version=qemu-xen. See xen-pci-device-reservations(7)
2001 for more information.
2002 PVH Guest Specific Options
2004 nestedhvm=BOOLEAN
2005 Enable or disables guest access to hardware virtualisation
2006 features, e.g. it allows a guest Operating System to also function
2007 as a hypervisor. You may want this option if you want to run
2008 another hypervisor (including another copy of Xen) within a Xen
2009 guest or to support a guest Operating System which uses hardware
2010 virtualisation extensions (e.g. Windows XP compatibility mode on
2011 more modern Windows OS).
2012 This option is disabled by default.
2014 bootloader="PROGRAM"
2016 Run "PROGRAM" to find the kernel image and ramdisk to use.
2017 Normally "PROGRAM" would be "pygrub", which is an emulation of
2018 grub/grub2/syslinux. Either kernel or bootloader must be specified
2019 for PV guests.
2020 bootloader_args=[ "ARG", "ARG", ...]
2022 Append ARGs to the arguments to the bootloader program.
2023 Alternatively if the argument is a simple string then it will be
2024 split into words at whitespace (this second option is deprecated).
2025 timer_mode="MODE"
2027 Specifies the mode for Virtual Timers. The valid values are as
2028 follows:
2029 delay_for_missed_ticks
2031 Delay for missed ticks. Do not advance a vCPU's time beyond the
2032 correct delivery time for interrupts that have been missed due
2033 to preemption. Deliver missed interrupts when the vCPU is
2034 rescheduled and advance the vCPU's virtual time stepwise for
2035 each one.
2036 no_delay_for_missed_ticks
2038 No delay for missed ticks. As above, missed interrupts are
2039 delivered, but guest time always tracks wallclock (i.e., real)
2040 time while doing so. This is the default.
2041 no_missed_ticks_pending
2043 No missed interrupts are held pending. Instead, to ensure ticks
2044 are delivered at some non-zero rate, if we detect missed ticks
2045 then the internal tick alarm is not disabled if the vCPU is
2046 preempted during the next tick period.
2047 one_missed_tick_pending
2049 One missed tick pending. Missed interrupts are collapsed
2050 together and delivered as one 'late tick'. Guest time always
2051 tracks wallclock (i.e., real) time.
2052 Paging
2054 The following options control the mechanisms used to virtualise guest
2056 memory. The defaults are selected to give the best results for the
2057 common cases so you should normally leave these options unspecified.
2058 hap=BOOLEAN
2060 Turns "hardware assisted paging" (the use of the hardware nested
2061 page table feature) on or off. This feature is called EPT
2062 (Extended Page Tables) by Intel and NPT (Nested Page Tables) or RVI
2063 (Rapid Virtualisation Indexing) by AMD. If turned off, Xen will run
2064 the guest in "shadow page table" mode where the guest's page table
2065 updates and/or TLB flushes etc. will be emulated. Use of HAP is
2066 the default when available.
2067 oos=BOOLEAN
2069 Turns "out of sync pagetables" on or off. When running in shadow
2070 page table mode, the guest's page table updates may be deferred as
2071 specified in the Intel/AMD architecture manuals. However, this may
2072 expose unexpected bugs in the guest, or find bugs in Xen, so it is
2073 possible to disable this feature. Use of out of sync page tables,
2074 when Xen thinks it appropriate, is the default.
2075 shadow_memory=MBYTES
2077 Number of megabytes to set aside for shadowing guest pagetable
2078 pages (effectively acting as a cache of translated pages) or to use
2079 for HAP state. By default this is 1MB per guest vCPU plus 8KB per
2080 MB of guest RAM. You should not normally need to adjust this value.
2081 However, if you are not using hardware assisted paging (i.e. you
2082 are using shadow mode) and your guest workload consists of a very
2083 large number of similar processes then increasing this value may
2084 improve performance.
2085 Device-Model Options
2087 The following options control the selection of the device-model. This
2088 is the component which provides emulation of the virtual devices to an
2089 HVM guest. For a PV guest a device-model is sometimes used to provide
2090 backends for certain PV devices (most usually a virtual framebuffer
2091 device).
2092 device_model_version="DEVICE-MODEL"
2094 Selects which variant of the device-model should be used for this
2095 guest.
2096 Valid values are:
2098 qemu-xen
2100 Use the device-model merged into the upstream QEMU project.
2101 This device-model is the default for Linux dom0.
2102 qemu-xen-traditional
2104 Use the device-model based upon the historical Xen fork of
2105 QEMU. This device-model is still the default for NetBSD dom0.
2106 It is recommended to accept the default value for new guests. If
2108 you have existing guests then, depending on the nature of the guest
2109 Operating System, you may wish to force them to use the device
2110 model which they were installed with.
2111 device_model_override="PATH"
2113 Override the path to the binary to be used as the device-model. The
2114 binary provided here MUST be consistent with the
2115 device_model_version which you have specified. You should not
2116 normally need to specify this option.
2117 device_model_stubdomain_override=BOOLEAN
2119 Override the use of stubdomain based device-model. Normally this
2120 will be automatically selected based upon the other features and
2121 options you have selected.
2122 device_model_stubdomain_seclabel="LABEL"
2124 Assign an XSM security label to the device-model stubdomain.
2125 device_model_args=[ "ARG", "ARG", ...]
2127 Pass additional arbitrary options on the device-model command line.
2128 Each element in the list is passed as an option to the device-
2129 model.
2130 device_model_args_pv=[ "ARG", "ARG", ...]
2132 Pass additional arbitrary options on the device-model command line
2133 for a PV device model only. Each element in the list is passed as
2134 an option to the device-model.
2135 device_model_args_hvm=[ "ARG", "ARG", ...]
2137 Pass additional arbitrary options on the device-model command line
2138 for an HVM device model only. Each element in the list is passed as
2139 an option to the device-model.
2140 Keymaps
2142 The keymaps available are defined by the device-model which you are
2143 using. Commonly this includes:
2144 ar de-ch es fo fr-ca hu ja mk no pt-br sv
2146 da en-gb et fr fr-ch is lt nl pl ru th
2147 de en-us fi fr-be hr it lv nl-be pt sl tr
2148 The default is en-us.
2150 See qemu(1) for more information.
2152 Architecture Specific options
2154 ARM
2155 gic_version="vN"
2157 Version of the GIC emulated for the guest.
2158 Currently, the following versions are supported:
2160 v2 Emulate a GICv2
2162 v3 Emulate a GICv3. Note that the emulated GIC does not support
2164 the GICv2 compatibility mode.
2165 default
2167 Emulate the same version as the native GIC hardware used by the
2168 host where the domain was created.
2169 This requires hardware compatibility with the requested version,
2171 either natively or via hardware backwards compatibility support.
2172 vuart="uart"
2174 To enable vuart console, user must specify the following option in
2175 the VM config file:
2176 vuart = "sbsa_uart"
2178 Currently, only the "sbsa_uart" model is supported for ARM.
2180 x86
2182 mca_caps=[ "CAP", "CAP", ... ]
2184 (HVM only) Enable MCA capabilities besides default ones enabled by
2185 Xen hypervisor for the HVM domain. "CAP" can be one in the
2186 following list:
2187 "lmce"
2189 Intel local MCE
2190 default
2192 No MCA capabilities in above list are enabled.
2193
2195 xl(1)
2196 xl.conf(5)
2197 xlcpupool.cfg(5)
2198 xl-disk-configuration(5)
2199 xl-network-configuration(5)
2200 xen-tscmode(7)
2201
2203 /etc/xen/NAME.cfg /var/lib/xen/dump/NAME
2204
2206 This document may contain items which require further documentation.
2207 Patches to improve incomplete items (or any other item) are gratefully
2208 received on the xen-devel@lists.xen.org mailing list. Please see
2209 <http://wiki.xen.org/wiki/SubmittingXenPatches> for information on how
2210 to submit a patch to Xen.
22114.12.1 2019-12-11 xl.cfg(5)