1xl.cfg(5)                             Xen                            xl.cfg(5)
2
3
4

NAME

6       xl.cfg - xl domain configuration file syntax
7

SYNOPSIS

9        /etc/xen/xldomain
10

DESCRIPTION

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

SYNTAX

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

OPTIONS

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

SEE ALSO

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

FILES

2106       /etc/xen/NAME.cfg /var/lib/xen/dump/NAME
2107

BUGS

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)
Impressum