1=head1 NAME 2 3xl.cfg - xl domain configuration file syntax 4 5=head1 SYNOPSIS 6 7 /etc/xen/xldomain 8 9=head1 DESCRIPTION 10 11Creating a VM (a domain in Xen terminology, sometimes called a guest) 12with xl requires the provision of a domain configuration file. Typically, 13these live in F</etc/xen/DOMAIN.cfg>, where DOMAIN is the name of the 14domain. 15 16=head1 SYNTAX 17 18A domain configuration file consists of a series of options, specified by 19using C<KEY=VALUE> pairs. 20 21Some C<KEY>s are mandatory, some are general options which apply to 22any guest type, while others relate only to specific guest types 23(e.g. PV or HVM guests). 24 25A C<VALUE> can be one of: 26 27=over 4 28 29=item B<"STRING"> 30 31A string, surrounded by either single or double quotes. But if the 32STRING is part of a SPEC_STRING, the quotes should be omitted. 33 34=item B<NUMBER> 35 36A number, in either decimal, octal (using a C<0> prefix) or 37hexadecimal (using a C<0x> prefix) format. 38 39=item B<BOOLEAN> 40 41A C<NUMBER> interpreted as C<False> (C<0>) or C<True> (any other 42value). 43 44=item B<[ VALUE, VALUE, ... ]> 45 46A list of C<VALUE>s of the above types. Lists can be heterogeneous and 47nested. 48 49=back 50 51The semantics of each C<KEY> defines which type of C<VALUE> is required. 52 53Pairs may be separated either by a newline or a semicolon. Both 54of the following are valid: 55 56 name="h0" 57 type="hvm" 58 59 name="h0"; type="hvm" 60 61=head1 OPTIONS 62 63=head2 Mandatory Configuration Items 64 65The following key is mandatory for any guest type. 66 67=over 4 68 69=item B<name="NAME"> 70 71Specifies the name of the domain. Names of domains existing on a 72single host must be unique. 73 74=back 75 76=head2 Selecting Guest Type 77 78=over 4 79 80=item B<type="pv"> 81 82Specifies that this is to be a PV domain, suitable for hosting Xen-aware 83guest operating systems. This is the default. 84 85=item B<type="pvh"> 86 87Specifies that this is to be an PVH domain. That is a lightweight HVM-like 88guest without a device model and without many of the emulated devices 89available to HVM guests. Note that this mode requires a PVH aware kernel. 90 91=item B<type="hvm"> 92 93Specifies that this is to be an HVM domain. That is, a fully virtualised 94computer with emulated BIOS, disk and network peripherals, etc. 95 96=back 97 98=head3 Deprecated guest type selection 99 100Note that the builder option is being deprecated in favor of the type 101option. 102 103=over 4 104 105=item B<builder="generic"> 106 107Specifies that this is to be a PV domain, suitable for hosting Xen-aware guest 108operating systems. This is the default. 109 110=item B<builder="hvm"> 111 112Specifies that this is to be an HVM domain. That is, a fully 113virtualised computer with emulated BIOS, disk and network peripherals, 114etc. 115 116=back 117 118=head2 General Options 119 120The following options apply to guests of any type. 121 122=head3 CPU Allocation 123 124=over 4 125 126=item B<pool="CPUPOOLNAME"> 127 128Put the guest's vCPUs into the named CPU pool. 129 130=item B<vcpus=N> 131 132Start the guest with N vCPUs initially online. 133 134=item B<maxvcpus=M> 135 136Allow the guest to bring up a maximum of M vCPUs. When starting the guest, if 137B<vcpus=N> is less than B<maxvcpus=M> then the first B<N> vCPUs will be 138created online and the remainder will be created offline. 139 140=item B<cpus="CPULIST"> 141 142List of host CPUs the guest is allowed to use. Default is no pinning at 143all (more on this below). A C<CPULIST> may be specified as follows: 144 145=over 4 146 147=item "all" 148 149To allow all the vCPUs of the guest to run on all the CPUs on the host. 150 151=item "0-3,5,^1" 152 153To allow all the vCPUs of the guest to run on CPUs 0,2,3,5. It is possible to 154combine this with "all", meaning "all,^7" results in all the vCPUs 155of the guest being allowed to run on all the CPUs of the host except CPU 7. 156 157=item "nodes:0-3,^node:2" 158 159To allow all the vCPUs of the guest to run on the CPUs from NUMA nodes 1600,1,3 of the host. So, if CPUs 0-3 belong to node 0, CPUs 4-7 belong 161to node 1, CPUs 8-11 to node 2 and CPUs 12-15 to node 3, the above would mean 162all the vCPUs of the guest would be allowed to run on CPUs 0-7,12-15. 163 164Combining this notation with the one above is possible. For instance, 165"1,node:1,^6", means all the vCPUs of the guest will run on CPU 1 and 166on all the CPUs of NUMA node 1, but not on CPU 6. Following the same 167example as above, that would be CPUs 1,4,5,7. 168 169Combining this with "all" is also possible, meaning "all,^node:1" 170results in all the vCPUs of the guest running on all the CPUs on the 171host, except for the CPUs belonging to the host NUMA node 1. 172 173=item ["2", "3-8,^5"] 174 175To ask for specific vCPU mapping. That means (in this example), vCPU 0 176of the guest will run on CPU 2 of the host and vCPU 1 of the guest will 177run on CPUs 3,4,6,7,8 of the host (excluding CPU 5). 178 179More complex notation can be also used, exactly as described above. So 180"all,^5-8", or just "all", or "node:0,node:2,^9-11,18-20" are all legal, 181for each element of the list. 182 183=back 184 185If this option is not specified, no vCPU to CPU pinning is established, 186and the vCPUs of the guest can run on all the CPUs of the host. If this 187option is specified, the intersection of the vCPU pinning mask, provided 188here, and the soft affinity mask, if provided via B<cpus_soft=>, 189is utilized to compute the domain node-affinity for driving memory 190allocations. 191 192=item B<cpus_soft="CPULIST"> 193 194Exactly as B<cpus=>, but specifies soft affinity, rather than pinning 195(hard affinity). When using the credit scheduler, this means what CPUs 196the vCPUs of the domain prefer. 197 198A C<CPULIST> is specified exactly as for B<cpus=>, detailed earlier in the 199manual. 200 201If this option is not specified, the vCPUs of the guest will not have 202any preference regarding host CPUs. If this option is specified, 203the intersection of the soft affinity mask, provided here, and the vCPU 204pinning, if provided via B<cpus=>, is utilized to compute the 205domain node-affinity for driving memory allocations. 206 207If this option is not specified (and B<cpus=> is not specified either), 208libxl automatically tries to place the guest on the least possible 209number of nodes. A heuristic approach is used for choosing the best 210node (or set of nodes), with the goal of maximizing performance for 211the guest and, at the same time, achieving efficient utilization of 212host CPUs and memory. In that case, the soft affinity of all the vCPUs 213of the domain will be set to host CPUs belonging to NUMA nodes 214chosen during placement. 215 216For more details, see L<xl-numa-placement(7)>. 217 218=back 219 220=head3 CPU Scheduling 221 222=over 4 223 224=item B<cpu_weight=WEIGHT> 225 226A domain with a weight of 512 will get twice as much CPU as a domain 227with a weight of 256 on a contended host. 228Legal weights range from 1 to 65535 and the default is 256. 229Honoured by the credit and credit2 schedulers. 230 231=item B<cap=N> 232 233The cap optionally fixes the maximum amount of CPU a domain will be 234able to consume, even if the host system has idle CPU cycles. 235The cap is expressed as a percentage of one physical CPU: 236100 is 1 physical CPU, 50 is half a CPU, 400 is 4 CPUs, etc. 237The default, 0, means there is no cap. 238Honoured by the credit and credit2 schedulers. 239 240B<NOTE>: Many systems have features that will scale down the computing 241power of a CPU that is not 100% utilized. This can be done in the 242operating system, but can also sometimes be done below the operating system, 243in the BIOS. If you set a cap such that individual cores are running 244at less than 100%, this may have an impact on the performance of your 245workload over and above the impact of the cap. For example, if your 246processor runs at 2GHz, and you cap a VM at 50%, the power management 247system may also reduce the clock speed to 1GHz; the effect will be 248that your VM gets 25% of the available power (50% of 1GHz) rather than 24950% (50% of 2GHz). If you are not getting the performance you expect, 250look at performance and CPU frequency options in your operating system and 251your BIOS. 252 253=back 254 255=head3 Memory Allocation 256 257=over 4 258 259=item B<memory=MBYTES> 260 261Start the guest with MBYTES megabytes of RAM. 262 263=item B<maxmem=MBYTES> 264 265Specifies the maximum amount of memory a guest can ever see. 266The value of B<maxmem=> must be equal to or greater than that of B<memory=>. 267 268In combination with B<memory=> it will start the guest "pre-ballooned", 269if the values of B<memory=> and B<maxmem=> differ. 270A "pre-ballooned" HVM guest needs a balloon driver, without a balloon driver 271it will crash. 272 273B<NOTE>: Because of the way ballooning works, the guest has to allocate 274memory to keep track of maxmem pages, regardless of how much memory it 275actually has available to it. A guest with maxmem=262144 and 276memory=8096 will report significantly less memory available for use 277than a system with maxmem=8096 memory=8096 due to the memory overhead 278of having to track the unused pages. 279 280=back 281 282=head3 Guest Virtual NUMA Configuration 283 284=over 4 285 286=item B<vnuma=[ VNODE_SPEC, VNODE_SPEC, ... ]> 287 288Specify virtual NUMA configuration with positional arguments. The 289nth B<VNODE_SPEC> in the list specifies the configuration of the nth 290virtual node. 291 292Note that virtual NUMA is not supported for PV guests yet, because 293there is an issue with the CPUID instruction handling that affects PV virtual 294NUMA. Furthermore, guests with virtual NUMA cannot be saved or migrated 295because the migration stream does not preserve node information. 296 297Each B<VNODE_SPEC> is a list, which has a form of 298"[VNODE_CONFIG_OPTION, VNODE_CONFIG_OPTION, ... ]" (without the quotes). 299 300For example, vnuma = [ ["pnode=0","size=512","vcpus=0-4","vdistances=10,20"] ] 301means vnode 0 is mapped to pnode 0, has 512MB ram, has vcpus 0 to 4, the 302distance to itself is 10 and the distance to vnode 1 is 20. 303 304Each B<VNODE_CONFIG_OPTION> is a quoted C<KEY=VALUE> pair. Supported 305B<VNODE_CONFIG_OPTION>s are (they are all mandatory at the moment): 306 307=over 4 308 309=item B<pnode=NUMBER> 310 311Specifies which physical node this virtual node maps to. 312 313=item B<size=MBYTES> 314 315Specifies the size of this virtual node. The sum of memory sizes of all 316vnodes will become B<maxmem=>. If B<maxmem=> is specified separately, 317a check is performed to make sure the sum of all vnode memory matches 318B<maxmem=>. 319 320=item B<vcpus="CPUSTRING"> 321 322Specifies which vCPUs belong to this node. B<"CPUSTRING"> is a string of numerical 323values separated by a comma. You can specify a range and/or a single CPU. 324An example would be "vcpus=0-5,8", which means you specified vCPU 0 to vCPU 5, 325and vCPU 8. 326 327=item B<vdistances=NUMBER, NUMBER, ... > 328 329Specifies the virtual distance from this node to all nodes (including 330itself) with positional arguments. For example, "vdistance=10,20" 331for vnode 0 means the distance from vnode 0 to vnode 0 is 10, from 332vnode 0 to vnode 1 is 20. The number of arguments supplied must match 333the total number of vnodes. 334 335Normally you can use the values from B<xl info -n> or B<numactl 336--hardware> to fill the vdistances list. 337 338=back 339 340=back 341 342=head3 Event Actions 343 344=over 4 345 346=item B<on_poweroff="ACTION"> 347 348Specifies what should be done with the domain if it shuts itself down. 349The B<ACTION>s are: 350 351=over 4 352 353=item B<destroy> 354 355destroy the domain 356 357=item B<restart> 358 359destroy the domain and immediately create a new domain with the same 360configuration 361 362=item B<rename-restart> 363 364rename the domain which terminated, and then immediately create a new 365domain with the same configuration as the original 366 367=item B<preserve> 368 369keep the domain. It can be examined, and later destroyed with B<xl destroy>. 370 371=item B<coredump-destroy> 372 373write a "coredump" of the domain to F<@XEN_DUMP_DIR@/NAME> and then 374destroy the domain. 375 376=item B<coredump-restart> 377 378write a "coredump" of the domain to F<@XEN_DUMP_DIR@/NAME> and then 379restart the domain. 380 381=item B<soft-reset> 382 383Reset all Xen specific interfaces for the Xen-aware HVM domain allowing 384it to reestablish these interfaces and continue executing the domain. PV 385and non-Xen-aware HVM guests are not supported. 386 387=back 388 389The default for B<on_poweroff> is B<destroy>. 390 391=item B<on_reboot="ACTION"> 392 393Action to take if the domain shuts down with a reason code requesting 394a reboot. Default is B<restart>. 395 396=item B<on_watchdog="ACTION"> 397 398Action to take if the domain shuts down due to a Xen watchdog timeout. 399Default is B<destroy>. 400 401=item B<on_crash="ACTION"> 402 403Action to take if the domain crashes. Default is B<destroy>. 404 405=item B<on_soft_reset="ACTION"> 406 407Action to take if the domain performs a 'soft reset' (e.g. does B<kexec>). 408Default is B<soft-reset>. 409 410=back 411 412=head3 Direct Kernel Boot 413 414Direct kernel boot allows booting guests with a kernel and an initrd 415stored on a filesystem available to the host physical machine, allowing 416command line arguments to be passed directly. PV guest direct kernel boot is 417supported. HVM guest direct kernel boot is supported with some limitations 418(it's supported when using B<qemu-xen> and the default BIOS 'seabios', 419but not supported in case of using B<stubdom-dm> and the old 'rombios'.) 420 421=over 4 422 423=item B<kernel="PATHNAME"> 424 425Load the specified file as the kernel image. 426 427=item B<ramdisk="PATHNAME"> 428 429Load the specified file as the ramdisk. 430 431=item B<cmdline="STRING"> 432 433Append B<STRING> to the kernel command line. (Note: the meaning of 434this is guest specific). It can replace B<root="STRING"> 435along with B<extra="STRING"> and is preferred. When B<cmdline="STRING"> is set, 436B<root="STRING"> and B<extra="STRING"> will be ignored. 437 438=item B<root="STRING"> 439 440Append B<root=STRING> to the kernel command line (Note: the meaning of this 441is guest specific). 442 443=item B<extra="STRING"> 444 445Append B<STRING> to the kernel command line. (Note: the meaning of this 446is guest specific). 447 448=back 449 450=head3 Non direct Kernel Boot 451 452Non direct kernel boot allows booting guests with a firmware. This can be 453used by all types of guests, although the selection of options is different 454depending on the guest type. 455 456This option provides the flexibly of letting the guest decide which kernel 457they want to boot, while preventing having to poke at the guest file 458system form the toolstack domain. 459 460=head4 PV guest options 461 462=over 4 463 464=item B<firmware="pvgrub32|pvgrub64"> 465 466Boots a guest using a para-virtualized version of grub that runs inside 467of the guest. The bitness of the guest needs to be know, so that the right 468version of pvgrub can be selected. 469 470Note that xl expects to find the pvgrub32.bin and pvgrub64.bin binaries in 471F<@XENFIRMWAREDIR@>. 472 473=back 474 475=head4 HVM guest options 476 477=over 4 478 479=item B<firmware="bios"> 480 481Boot the guest using the default BIOS firmware, which depends on the 482chosen device model. 483 484=item B<firmware="uefi"> 485 486Boot the guest using the default UEFI firmware, currently OVMF. 487 488=item B<firmware="seabios"> 489 490Boot the guest using the SeaBIOS BIOS firmware. 491 492=item B<firmware="rombios"> 493 494Boot the guest using the ROMBIOS BIOS firmware. 495 496=item B<firmware="ovmf"> 497 498Boot the guest using the OVMF UEFI firmware. 499 500=item B<firmware="PATH"> 501 502Load the specified file as firmware for the guest. 503 504=back 505 506=head4 PVH guest options 507 508Currently there's no firmware available for PVH guests, they should be 509booted using the B<Direct Kernel Boot> method or the B<bootloader> option. 510 511=over 4 512 513=item B<pvshim=BOOLEAN> 514 515Whether to boot this guest as a PV guest within a PVH container. 516Ie, the guest will experience a PV environment, 517but 518processor hardware extensions are used to 519separate its address space 520to mitigate the Meltdown attack (CVE-2017-5754). 521 522Default is false. 523 524=item B<pvshim_path="PATH"> 525 526The PV shim is a specially-built firmware-like executable 527constructed from the hypervisor source tree. 528This option specifies to use a non-default shim. 529Ignored if pvhsim is false. 530 531=item B<pvshim_cmdline="STRING"> 532 533Command line for the shim. 534Default is "pv-shim console=xen,pv sched=null". 535Ignored if pvhsim is false. 536 537=item B<pvshim_extra="STRING"> 538 539Extra command line arguments for the shim. 540If supplied, appended to the value for pvshim_cmdline. 541Default is empty. 542Ignored if pvhsim is false. 543 544=back 545 546=head3 Other Options 547 548=over 4 549 550=item B<uuid="UUID"> 551 552Specifies the UUID of the domain. If not specified, a fresh unique 553UUID will be generated. 554 555=item B<seclabel="LABEL"> 556 557Assign an XSM security label to this domain. 558 559=item B<init_seclabel="LABEL"> 560 561Specify an XSM security label used for this domain temporarily during 562its build. The domain's XSM label will be changed to the execution 563seclabel (specified by B<seclabel>) once the build is complete, prior to 564unpausing the domain. With a properly constructed security policy (such 565as nomigrate_t in the example policy), this can be used to build a 566domain whose memory is not accessible to the toolstack domain. 567 568=item B<max_grant_frames=NUMBER> 569 570Specify the maximum number of grant frames the domain is allowed to have. 571This value controls how many pages the domain is able to grant access to for 572other domains, needed e.g. for the operation of paravirtualized devices. 573The default is settable via L<xl.conf(5)>. 574 575=item B<max_maptrack_frames=NUMBER> 576 577Specify the maximum number of grant maptrack frames the domain is allowed 578to have. This value controls how many pages of foreign domains can be accessed 579via the grant mechanism by this domain. The default value is settable via 580L<xl.conf(5)>. 581 582=item B<nomigrate=BOOLEAN> 583 584Disable migration of this domain. This enables certain other features 585which are incompatible with migration. Currently this is limited to 586enabling the invariant TSC feature flag in CPUID results when TSC is 587not emulated. 588 589=item B<driver_domain=BOOLEAN> 590 591Specify that this domain is a driver domain. This enables certain 592features needed in order to run a driver domain. 593 594=item B<device_tree=PATH> 595 596Specify a partial device tree (compiled via the Device Tree Compiler). 597Everything under the node "/passthrough" will be copied into the guest 598device tree. For convenience, the node "/aliases" is also copied to allow 599the user to define aliases which can be used by the guest kernel. 600 601Given the complexity of verifying the validity of a device tree, this 602option should only be used with a trusted device tree. 603 604Note that the partial device tree should avoid using the phandle 65000 605which is reserved by the toolstack. 606 607=back 608 609=head2 Devices 610 611The following options define the paravirtual, emulated and physical 612devices which the guest will contain. 613 614=over 4 615 616=item B<disk=[ "DISK_SPEC_STRING", "DISK_SPEC_STRING", ...]> 617 618Specifies the disks (both emulated disks and Xen virtual block 619devices) which are to be provided to the guest, and what objects on 620the host they should map to. See L<xl-disk-configuration(5)> for more 621details. 622 623=item B<vif=[ "NET_SPEC_STRING", "NET_SPEC_STRING", ...]> 624 625Specifies the network interfaces (both emulated network adapters, 626and Xen virtual interfaces) which are to be provided to the guest. See 627L<xl-network-configuration(5)> for more details. 628 629=item B<vtpm=[ "VTPM_SPEC_STRING", "VTPM_SPEC_STRING", ...]> 630 631Specifies the Virtual Trusted Platform module to be 632provided to the guest. See L<xen-vtpm(7)> for more details. 633 634Each B<VTPM_SPEC_STRING> is a comma-separated list of C<KEY=VALUE> 635settings from the following list: 636 637=over 4 638 639=item B<backend=domain-id> 640 641Specifies the backend domain name or id. B<This value is required!> 642If this domain is a guest, the backend should be set to the 643vTPM domain name. If this domain is a vTPM, the 644backend should be set to the vTPM manager domain name. 645 646=item B<uuid=UUID> 647 648Specifies the UUID of this vTPM device. The UUID is used to uniquely 649identify the vTPM device. You can create one using the B<uuidgen(1)> 650program on unix systems. If left unspecified, a new UUID 651will be randomly generated every time the domain boots. 652If this is a vTPM domain, you should specify a value. The 653value is optional if this is a guest domain. 654 655=back 656 657=item B<p9=[ "9PFS_SPEC_STRING", "9PFS_SPEC_STRING", ...]> 658 659Creates a Xen 9pfs connection to share a filesystem from the backend to the 660frontend. 661 662Each B<9PFS_SPEC_STRING> is a comma-separated list of C<KEY=VALUE> 663settings, from the following list: 664 665=over 4 666 667=item B<tag=STRING> 668 6699pfs tag to identify the filesystem share. The tag is needed on the 670guest side to mount it. 671 672=item B<security_model="none"> 673 674Only "none" is supported today, which means that the files are stored using 675the same credentials as those they have in the guest (no user ownership 676squash or remap). 677 678=item B<path=STRING> 679 680Filesystem path on the backend to export. 681 682=item B<backend=domain-id> 683 684Specify the backend domain name or id, defaults to dom0. 685 686=back 687 688=item B<vfb=[ "VFB_SPEC_STRING", "VFB_SPEC_STRING", ...]> 689 690Specifies the paravirtual framebuffer devices which should be supplied 691to the domain. 692 693This option does not control the emulated graphics card presented to 694an HVM guest. See B<Emulated VGA Graphics Device> below for how to 695configure the emulated device. If B<Emulated VGA Graphics Device> options 696are used in a PV guest configuration, B<xl> will pick up B<vnc>, B<vnclisten>, 697B<vncpasswd>, B<vncdisplay>, B<vncunused>, B<sdl>, B<opengl> and 698B<keymap> to construct the paravirtual framebuffer device for the guest. 699 700Each B<VFB_SPEC_STRING> is a comma-separated list of C<KEY=VALUE> 701settings, from the following list: 702 703=over 4 704 705=item B<vnc=BOOLEAN> 706 707Allow access to the display via the VNC protocol. This enables the 708other VNC-related settings. Default is 1 (enabled). 709 710=item B<vnclisten=ADDRESS[:DISPLAYNUM]> 711 712Specifies the IP address, and optionally the VNC display number, to use. 713 714Note: if you specify the display number here, you should not use 715the B<vncdisplay> option. 716 717=item B<vncdisplay=DISPLAYNUM> 718 719Specifies the VNC display number to use. The actual TCP port number 720will be DISPLAYNUM+5900. 721 722Note: you should not use this option if you set the DISPLAYNUM in the 723B<vnclisten> option. 724 725=item B<vncunused=BOOLEAN> 726 727Requests that the VNC display setup searches for a free TCP port to use. 728The actual display used can be accessed with B<xl vncviewer>. 729 730=item B<vncpasswd=PASSWORD> 731 732Specifies the password for the VNC server. If the password is set to an 733empty string, authentication on the VNC server will be disabled, 734allowing any user to connect. 735 736=item B<sdl=BOOLEAN> 737 738Specifies that the display should be presented via an X window (using 739Simple DirectMedia Layer). The default is 0 (not enabled). 740 741=item B<display=DISPLAY> 742 743Specifies the X Window display that should be used when the B<sdl> option 744is used. 745 746=item B<xauthority=XAUTHORITY> 747 748Specifies the path to the X authority file that should be used to 749connect to the X server when the B<sdl> option is used. 750 751=item B<opengl=BOOLEAN> 752 753Enable OpenGL acceleration of the SDL display. Only effects machines 754using B<device_model_version="qemu-xen-traditional"> and only if the 755device-model was compiled with OpenGL support. The default is 0 (disabled). 756 757=item B<keymap=LANG> 758 759Configure the keymap to use for the keyboard associated with this 760display. If the input method does not easily support raw keycodes 761(e.g. this is often the case when using VNC) then this allows us to 762correctly map the input keys into keycodes seen by the guest. The 763specific values which are accepted are defined by the version of the 764device-model which you are using. See B<Keymaps> below or consult the 765B<qemu(1)> manpage. The default is B<en-us>. 766 767=back 768 769=item B<channel=[ "CHANNEL_SPEC_STRING", "CHANNEL_SPEC_STRING", ...]> 770 771Specifies the virtual channels to be provided to the guest. A 772channel is a low-bandwidth, bidirectional byte stream, which resembles 773a serial link. Typical uses for channels include transmitting VM 774configuration after boot and signalling to in-guest agents. Please see 775L<xen-pv-channel(7)> for more details. 776 777Each B<CHANNEL_SPEC_STRING> is a comma-separated list of C<KEY=VALUE> 778settings. Leading and trailing whitespace is ignored in both KEY and 779VALUE. Neither KEY nor VALUE may contain ',', '=' or '"'. Defined values 780are: 781 782=over 4 783 784=item B<backend=domain-id> 785 786Specifies the backend domain name or id. This parameter is optional. If 787this parameter is omitted then the toolstack domain will be assumed. 788 789=item B<name=NAME> 790 791Specifies the name for this device. B<This parameter is mandatory!> 792This should be a well-known name for a specific application (e.g. 793guest agent) and should be used by the frontend to connect the 794application to the right channel device. There is no formal registry 795of channel names, so application authors are encouraged to make their 796names unique by including the domain name and a version number in the string 797(e.g. org.mydomain.guestagent.1). 798 799=item B<connection=CONNECTION> 800 801Specifies how the backend will be implemented. The following options are 802available: 803 804=over 4 805 806=item B<SOCKET> 807 808The backend will bind a Unix domain socket (at the path given by 809B<path=PATH>), listen for and accept connections. The backend will proxy 810data between the channel and the connected socket. 811 812=item B<PTY> 813 814The backend will create a pty and proxy data between the channel and the 815master device. The command B<xl channel-list> can be used to discover the 816assigned slave device. 817 818=back 819 820=back 821 822=item B<rdm="RDM_RESERVATION_STRING"> 823 824B<HVM/x86 only!> Specifies information about Reserved Device Memory (RDM), 825which is necessary to enable robust device passthrough. One example of RDM 826is reporting through the ACPI Reserved Memory Region Reporting (RMRR) structure 827on the x86 platform. 828 829B<RDM_RESERVATION_STRING> is a comma separated list of C<KEY=VALUE> settings, 830from the following list: 831 832=over 4 833 834=item B<strategy=STRING> 835 836Currently there is only one valid type, and that is "host". 837 838=over 4 839 840=item B<host> 841 842If set to "host" it means all reserved device memory on this platform should 843be checked to reserve regions in this VM's address space. This global RDM 844parameter allows the user to specify reserved regions explicitly, and using 845"host" includes all reserved regions reported on this platform, which is 846useful when doing hotplug. 847 848By default this isn't set so we don't check all RDMs. Instead, we just check 849the RDM specific to a given device if we're assigning this kind of a device. 850 851Note: this option is not recommended unless you can make sure that no 852conflicts exist. 853 854For example, you're trying to set "memory = 2800" to allocate memory to one 855given VM but the platform owns two RDM regions like: 856 857Device A [sbdf_A]: RMRR region_A: base_addr ac6d3000 end_address ac6e6fff 858 859Device B [sbdf_B]: RMRR region_B: base_addr ad800000 end_address afffffff 860 861In this conflict case, 862 863#1. If B<strategy> is set to "host", for example: 864 865rdm = "strategy=host,policy=strict" or rdm = "strategy=host,policy=relaxed" 866 867it means all conflicts will be handled according to the policy 868introduced by B<policy> as described below. 869 870#2. If B<strategy> is not set at all, but 871 872pci = [ 'sbdf_A, rdm_policy=xxxxx' ] 873 874it means only one conflict of region_A will be handled according to the policy 875introduced by B<rdm_policy=STRING> as described inside B<pci> options. 876 877=back 878 879=item B<policy=STRING> 880 881Specifies how to deal with conflicts when reserving already reserved device 882memory in the guest address space. 883 884=over 4 885 886=item B<strict> 887 888Specifies that in case of an unresolved conflict the VM can't be created, 889or the associated device can't be attached in the case of hotplug. 890 891=item B<relaxed> 892 893Specifies that in case of an unresolved conflict the VM is allowed to be 894created but may cause the VM to crash if a pass-through device accesses RDM. 895For example, the Windows IGD GFX driver always accesses RDM regions so it 896leads to a VM crash. 897 898Note: this may be overridden by the B<rdm_policy> option in the B<pci> 899device configuration. 900 901=back 902 903=back 904 905=item B<usbctrl=[ "USBCTRL_SPEC_STRING", "USBCTRL_SPEC_STRING", ...]> 906 907Specifies the USB controllers created for this guest. 908 909Each B<USBCTRL_SPEC_STRING> is a comma-separated list of C<KEY=VALUE> 910settings, from the following list: 911 912=over 4 913 914=item B<type=TYPE> 915 916Specifies the usb controller type. 917 918=over 4 919 920=item B<pv> 921 922Specifies a kernel based PVUSB backend. 923 924=item B<qusb> 925 926Specifies a QEMU based PVUSB backend. 927 928=item B<devicemodel> 929 930Specifies a USB controller emulated by QEMU. 931It will show up as a PCI-device in the guest. 932 933=item B<auto> 934 935Determines whether a kernel based backend is installed. 936If this is the case, B<pv> is used, otherwise B<qusb> will be used. 937For HVM domains B<devicemodel> will be selected. 938 939This option is the default. 940 941=back 942 943=item B<version=VERSION> 944 945Specifies the usb controller version. Possible values include 9461 (USB1.1), 2 (USB2.0) and 3 (USB3.0). 947Default is 2 (USB2.0). 948Value 3 (USB3.0) is available for the B<devicemodel> type only. 949 950=item B<ports=PORTS> 951 952Specifies the total number of ports of the usb controller. The maximum 953number is 31. The default is 8. 954With the type B<devicemodel> the number of ports is more limited: 955a USB1.1 controller always has 2 ports, 956a USB2.0 controller always has 6 ports 957and a USB3.0 controller can have up to 15 ports. 958 959USB controller ids start from 0. In line with the USB specification, however, 960ports on a controller start from 1. 961 962B<EXAMPLE> 963 964=over 2 965 966usbctrl=["version=1,ports=4", "version=2,ports=8"] 967 968The first controller is USB1.1 and has: 969 970controller id = 0, and ports 1,2,3,4. 971 972The second controller is USB2.0 and has: 973 974controller id = 1, and ports 1,2,3,4,5,6,7,8. 975 976=back 977 978=back 979 980=item B<usbdev=[ "USBDEV_SPEC_STRING", "USBDEV_SPEC_STRING", ...]> 981 982Specifies the USB devices to be attached to the guest at boot. 983 984Each B<USBDEV_SPEC_STRING> is a comma-separated list of C<KEY=VALUE> 985settings, from the following list: 986 987=over 4 988 989=item B<devtype=hostdev> 990 991Specifies USB device type. Currently only "hostdev" is supported. 992 993=item B<hostbus=busnum> 994 995Specifies busnum of the USB device from the host perspective. 996 997=item B<hostaddr=devnum> 998 999Specifies devnum of the USB device from the host perspective. 1000 1001=item B<controller=CONTROLLER> 1002 1003Specifies the USB controller id, to which controller the USB device is 1004attached. 1005 1006If no controller is specified, an available controller:port combination 1007will be used. If there are no available controller:port combinations, 1008a new controller will be created. 1009 1010=item B<port=PORT> 1011 1012Specifies the USB port to which the USB device is attached. The B<port> 1013option is valid only when the B<controller> option is specified. 1014 1015=back 1016 1017=item B<pci=[ "PCI_SPEC_STRING", "PCI_SPEC_STRING", ...]> 1018 1019Specifies the host PCI devices to passthrough to this guest. 1020Each B<PCI_SPEC_STRING> has the form of 1021B<[DDDD:]BB:DD.F[@VSLOT],KEY=VALUE,KEY=VALUE,...> where: 1022 1023=over 4 1024 1025=item B<[DDDD:]BB:DD.F> 1026 1027Identifies the PCI device from the host perspective in the domain 1028(B<DDDD>), Bus (B<BB>), Device (B<DD>) and Function (B<F>) syntax. This is 1029the same scheme as used in the output of B<lspci(1)> for the device in 1030question. 1031 1032Note: by default B<lspci(1)> will omit the domain (B<DDDD>) if it 1033is zero and it is optional here also. You may specify the function 1034(B<F>) as B<*> to indicate all functions. 1035 1036=item B<@VSLOT> 1037 1038Specifies the virtual slot where the guest will see this 1039device. This is equivalent to the B<DD> which the guest sees. In a 1040guest B<DDDD> and B<BB> are C<0000:00>. 1041 1042=item B<permissive=BOOLEAN> 1043 1044By default pciback only allows PV guests to write "known safe" values 1045into PCI configuration space, likewise QEMU (both qemu-xen and 1046qemu-xen-traditional) imposes the same constraint on HVM guests. 1047However, many devices require writes to other areas of the configuration space 1048in order to operate properly. This option tells the backend (pciback or QEMU) 1049to allow all writes to the PCI configuration space of this device by this 1050domain. 1051 1052B<This option should be enabled with caution:> it gives the guest much 1053more control over the device, which may have security or stability 1054implications. It is recommended to only enable this option for 1055trusted VMs under administrator's control. 1056 1057=item B<msitranslate=BOOLEAN> 1058 1059Specifies that MSI-INTx translation should be turned on for the PCI 1060device. When enabled, MSI-INTx translation will always enable MSI on 1061the PCI device regardless of whether the guest uses INTx or MSI. Some 1062device drivers, such as NVIDIA's, detect an inconsistency and do not 1063function when this option is enabled. Therefore the default is false (0). 1064 1065=item B<seize=BOOLEAN> 1066 1067Tells B<xl> to automatically attempt to re-assign a device to 1068pciback if it is not already assigned. 1069 1070B<WARNING:> If you set this option, B<xl> will gladly re-assign a critical 1071system device, such as a network or a disk controller being used by 1072dom0 without confirmation. Please use with care. 1073 1074=item B<power_mgmt=BOOLEAN> 1075 1076B<(HVM only)> Specifies that the VM should be able to program the 1077D0-D3hot power management states for the PCI device. The default is false (0). 1078 1079=item B<rdm_policy=STRING> 1080 1081B<(HVM/x86 only)> This is the same as the policy setting inside the B<rdm> 1082option but just specific to a given device. The default is "relaxed". 1083 1084Note: this would override global B<rdm> option. 1085 1086=back 1087 1088=item B<pci_permissive=BOOLEAN> 1089 1090Changes the default value of B<permissive> for all PCI devices passed 1091through to this VM. See B<permissive> above. 1092 1093=item B<pci_msitranslate=BOOLEAN> 1094 1095Changes the default value of B<msitranslate> for all PCI devices passed 1096through to this VM. See B<msitranslate> above. 1097 1098=item B<pci_seize=BOOLEAN> 1099 1100Changes the default value of B<seize> for all PCI devices passed 1101through to this VM. See B<seize> above. 1102 1103=item B<pci_power_mgmt=BOOLEAN> 1104 1105B<(HVM only)> Changes the default value of B<power_mgmt> for all PCI 1106devices passed through to this VM. See B<power_mgmt> 1107above. 1108 1109=item B<gfx_passthru=BOOLEAN|"STRING"> 1110 1111Enable graphics device PCI passthrough. This option makes an assigned 1112PCI graphics card become the primary graphics card in the VM. The QEMU 1113emulated graphics adapter is disabled and the VNC console for the VM 1114will not have any graphics output. All graphics output, including boot 1115time QEMU BIOS messages from the VM, will go to the physical outputs 1116of the passed through physical graphics card. 1117 1118The graphics card PCI device to pass through is chosen with the B<pci> 1119option, in exactly the same way a normal Xen PCI device 1120passthrough/assignment is done. Note that B<gfx_passthru> does not do 1121any kind of sharing of the GPU, so you can assign the GPU to only one 1122single VM at a time. 1123 1124B<gfx_passthru> also enables various legacy VGA memory ranges, BARs, MMIOs, 1125and ioports to be passed through to the VM, since those are required 1126for correct operation of things like VGA BIOS, text mode, VBE, etc. 1127 1128Enabling the B<gfx_passthru> option also copies the physical graphics card 1129video BIOS to the guest memory, and executes the VBIOS in the guest 1130to initialize the graphics card. 1131 1132Most graphics adapters require vendor specific tweaks for properly 1133working graphics passthrough. See the XenVGAPassthroughTestedAdapters 1134L<http://wiki.xen.org/wiki/XenVGAPassthroughTestedAdapters> wiki page 1135for graphics cards currently supported by B<gfx_passthru>. 1136 1137B<gfx_passthru> is currently supported both with the qemu-xen-traditional 1138device-model and upstream qemu-xen device-model. 1139 1140When given as a boolean the B<gfx_passthru> option either disables graphics 1141card passthrough or enables autodetection. 1142 1143When given as a string the B<gfx_passthru> option describes the type 1144of device to enable. Note that this behavior is only supported with the 1145upstream qemu-xen device-model. With qemu-xen-traditional IGD (Intel Graphics 1146Device) is always assumed and options other than autodetect or explicit IGD 1147will result in an error. 1148 1149Currently, valid values for the option are: 1150 1151=over 4 1152 1153=item B<0> 1154 1155Disables graphics device PCI passthrough. 1156 1157=item B<1>, B<"default"> 1158 1159Enables graphics device PCI passthrough and autodetects the type of device 1160which is being used. 1161 1162=item B<"igd"> 1163 1164Enables graphics device PCI passthrough but forcing the type of device to 1165Intel Graphics Device. 1166 1167=back 1168 1169Note that some graphics cards (AMD/ATI cards, for example) do not 1170necessarily require the B<gfx_passthru> option, so you can use the normal Xen 1171PCI passthrough to assign the graphics card as a secondary graphics 1172card to the VM. The QEMU-emulated graphics card remains the primary 1173graphics card, and VNC output is available from the QEMU-emulated 1174primary adapter. 1175 1176More information about the Xen B<gfx_passthru> feature is available 1177on the XenVGAPassthrough L<http://wiki.xen.org/wiki/XenVGAPassthrough> 1178wiki page. 1179 1180=item B<rdm_mem_boundary=MBYTES> 1181 1182Number of megabytes to set for a boundary when checking for RDM conflicts. 1183 1184When RDM conflicts with RAM, RDM is probably scattered over the whole RAM 1185space. Having multiple RDM entries would worsen this and lead to a complicated 1186memory layout. Here we're trying to figure out a simple solution to 1187avoid breaking the existing layout. When a conflict occurs, 1188 1189 #1. Above a predefined boundary 1190 - move lowmem_end below the reserved region to solve the conflict; 1191 1192 #2. Below a predefined boundary 1193 - Check if the policy is strict or relaxed. 1194 A "strict" policy leads to a fail in libxl. 1195 Note that when both policies are specified on a given region, 1196 "strict" is always preferred. 1197 The "relaxed" policy issues a warning message and also masks this 1198 entry INVALID to indicate we shouldn't expose this entry to 1199 hvmloader. 1200 1201The default value is 2048. 1202 1203=item B<dtdev=[ "DTDEV_PATH", "DTDEV_PATH", ...]> 1204 1205Specifies the host device tree nodes to passt hrough to this guest. Each 1206DTDEV_PATH is an absolute path in the device tree. 1207 1208=item B<ioports=[ "IOPORT_RANGE", "IOPORT_RANGE", ...]> 1209 1210Allow the guest to access specific legacy I/O ports. Each B<IOPORT_RANGE> 1211is given in hexadecimal format and may either be a range, e.g. C<2f8-2ff> 1212(inclusive), or a single I/O port, e.g. C<2f8>. 1213 1214It is recommended to only use this option for trusted VMs under 1215administrator's control. 1216 1217=item B<iomem=[ "IOMEM_START,NUM_PAGES[@GFN]", "IOMEM_START,NUM_PAGES[@GFN]", ...]> 1218 1219Allow auto-translated domains to access specific hardware I/O memory pages. 1220 1221B<IOMEM_START> is a physical page number. B<NUM_PAGES> is the number of pages, 1222beginning with B<START_PAGE>, to allow access to. B<GFN> specifies the guest 1223frame number where the mapping will start in the guest's address space. If 1224B<GFN> is not specified, the mapping will be performed using B<IOMEM_START> 1225as a start in the guest's address space, therefore performing a 1:1 mapping 1226by default. 1227All of these values must be given in hexadecimal format. 1228 1229Note that the IOMMU won't be updated with the mappings specified with this 1230option. This option therefore should not be used to pass through any 1231IOMMU-protected devices. 1232 1233It is recommended to only use this option for trusted VMs under 1234administrator's control. 1235 1236=item B<irqs=[ NUMBER, NUMBER, ...]> 1237 1238Allow a guest to access specific physical IRQs. 1239 1240It is recommended to only use this option for trusted VMs under 1241administrator's control. 1242 1243If vuart console is enabled then irq 32 is reserved for it. See 1244L</vuart="uart"> to know how to enable vuart console. 1245 1246=item B<max_event_channels=N> 1247 1248Limit the guest to using at most N event channels (PV interrupts). 1249Guests use hypervisor resources for each event channel they use. 1250 1251The default of 1023 should be sufficient for typical guests. The 1252maximum value depends on what the guest supports. Guests supporting the 1253FIFO-based event channel ABI support up to 131,071 event channels. 1254Other guests are limited to 4095 (64-bit x86 and ARM) or 1023 (32-bit 1255x86). 1256 1257=item B<vdispl=[ "VDISPL_SPEC_STRING", "VDISPL_SPEC_STRING", ...]> 1258 1259Specifies the virtual display devices to be provided to the guest. 1260 1261Each B<VDISPL_SPEC_STRING> is a comma-separated list of C<KEY=VALUE> 1262settings, from the following list: 1263 1264=over 4 1265 1266=item C<backend=DOMAIN> 1267 1268Specifies the backend domain name or id. If not specified Domain-0 is used. 1269 1270=item C<be-alloc=BOOLEAN> 1271 1272Indicates if backend can be a buffer provider/allocator for this domain. See 1273display protocol for details. 1274 1275=item C<connectors=CONNECTORS> 1276 1277Specifies virtual connectors for the device in following format 1278<id>:<W>x<H>;<id>:<W>x<H>... where: 1279 1280=over 4 1281 1282=item C<id> 1283 1284String connector ID. Space, comma symbols are not allowed. 1285 1286=item C<W> 1287 1288Connector width in pixels. 1289 1290=item C<H> 1291 1292Connector height in pixels. 1293 1294=back 1295 1296B<EXAMPLE> 1297 1298=over 4 1299 1300connectors=id0:1920x1080;id1:800x600;id2:640x480 1301 1302=back 1303 1304=back 1305 1306=item B<dm_restrict=BOOLEAN> 1307 1308Restrict the device model after startup, 1309to limit the consequencese of security vulnerabilities in qemu. 1310 1311With this feature enabled, 1312a compromise of the device model, 1313via such a vulnerability, 1314will not provide a privilege escalation attack on the whole system. 1315 1316This feature is a B<technology preview>. 1317There are some significant limitations: 1318 1319=over 4 1320 1321=item 1322 1323This is not likely to work at all for PV guests 1324nor guests using qdisk backends for their block devices. 1325 1326=item 1327 1328You must have a new enough qemu. 1329In particular, 1330if your qemu does not have the commit 1331B<xen: restrict: use xentoolcore_restrict_all> 1332the restriction request will be silently ineffective! 1333 1334=item 1335 1336The mechanisms used are not effective against 1337denial of service problems. 1338A compromised qemu can probably still impair 1339or perhaps even prevent 1340the proper functioning of the whole system, 1341(at the very least, but not limited to, 1342through resource exhaustion). 1343 1344=item 1345 1346It is not known whether the protection is 1347effective when a domain is migrated. 1348 1349=item 1350 1351Some domain management functions do not work. 1352For example, cdrom insert will fail. 1353 1354=item 1355 1356You should say C<vga="none">. 1357Domains with stdvga graphics cards to not work. 1358Domains with cirrus vga may seem to work. 1359 1360=item 1361 1362You must create user(s) for qemu to run as. 1363 1364Ideally, set aside a range of 32752 uids 1365(from N to N+32751) 1366and create a user 1367whose name is B<xen-qemuuser-range-base> 1368and whose uid is N 1369and whose gid is a plain unprivileged gid. 1370libxl will use one such user for each domid. 1371 1372Alternatively, either create 1373B<xen-qemuuser-domid$domid> 1374for every $domid from 1 to 32751 inclusive, 1375or 1376B<xen-qemuuser-shared> 1377(in which case different guests will not 1378be protected against each other). 1379 1380=item 1381 1382There are no countermeasures taken against reuse 1383of the same unix user (uid) 1384for subsequent domains, 1385even if the B<xen-qemuuser-domid$domid> users are created. 1386So a past domain with the same domid may be able to 1387interferer with future domains. 1388Possibly, even after a reboot. 1389 1390=item 1391 1392A compromised qemu will be able to read world-readable 1393files in the dom0 operating system. 1394 1395=item 1396 1397Because of these limitations, this functionality, 1398while it may enhance your security, 1399should not be relied on. 1400Any further limitations discovered in the current version 1401will B<not> be handled via the Xen Project Security Process. 1402 1403=item 1404 1405In the future as we enhance this feature to improve the security, 1406we may break backward compatibility. 1407 1408=back 1409 1410=back 1411 1412=head2 Paravirtualised (PV) Guest Specific Options 1413 1414The following options apply only to Paravirtual (PV) guests. 1415 1416=over 4 1417 1418=item B<bootloader="PROGRAM"> 1419 1420Run C<PROGRAM> to find the kernel image and ramdisk to use. Normally 1421C<PROGRAM> would be C<pygrub>, which is an emulation of 1422grub/grub2/syslinux. Either B<kernel> or B<bootloader> must be specified 1423for PV guests. 1424 1425=item B<bootloader_args=[ "ARG", "ARG", ...]> 1426 1427Append B<ARG>s to the arguments to the B<bootloader> 1428program. Alternatively if the argument is a simple string then it will 1429be split into words at whitespace B<(this second option is deprecated)>. 1430 1431=item B<e820_host=BOOLEAN> 1432 1433Selects whether to expose the host e820 (memory map) to the guest via 1434the virtual e820. When this option is false (0) the guest pseudo-physical 1435address space consists of a single contiguous RAM region. When this 1436option is specified the virtual e820 instead reflects the host e820 1437and contains the same PCI holes. The total amount of RAM represented 1438by the memory map is always the same, this option configures only how 1439it is laid out. 1440 1441Exposing the host e820 to the guest gives the guest kernel the 1442opportunity to set aside the required part of its pseudo-physical 1443address space in order to provide address space to map passedthrough 1444PCI devices. It is guest Operating System dependent whether this 1445option is required, specifically it is required when using a mainline 1446Linux ("pvops") kernel. This option defaults to true (1) if any PCI 1447passthrough devices are configured and false (0) otherwise. If you do not 1448configure any passthrough devices at domain creation time but expect 1449to hotplug devices later then you should set this option. Conversely 1450if your particular guest kernel does not require this behaviour then 1451it is safe to allow this to be enabled but you may wish to disable it 1452anyway. 1453 1454=back 1455 1456=head2 Fully-virtualised (HVM) Guest Specific Options 1457 1458The following options apply only to Fully-virtualised (HVM) guests. 1459 1460=head3 Boot Device 1461 1462=over 4 1463 1464=item B<boot="STRING"> 1465 1466Specifies the emulated virtual device to boot from. 1467 1468Possible values are: 1469 1470=over 4 1471 1472=item B<c> 1473 1474Hard disk. 1475 1476=item B<d> 1477 1478CD-ROM. 1479 1480=item B<n> 1481 1482Network / PXE. 1483 1484=back 1485 1486B<Note:> multiple options can be given and will be attempted in the order they 1487are given, e.g. to boot from CD-ROM but fall back to the hard disk you can 1488specify it as B<dc>. 1489 1490The default is B<cd>, meaning try booting from the hard disk first, but fall 1491back to the CD-ROM. 1492 1493 1494=back 1495 1496=head3 Emulated disk controller type 1497 1498=over 4 1499 1500=item B<hdtype=STRING> 1501 1502Specifies the hard disk type. 1503 1504Possible values are: 1505 1506=over 4 1507 1508=item B<ide> 1509 1510If thise mode is specified B<xl> adds an emulated IDE controller, which is 1511suitable even for older operation systems. 1512 1513=item B<ahci> 1514 1515If this mode is specified, B<xl> adds an ich9 disk controller in AHCI mode and 1516uses it with upstream QEMU to emulate disks instead of IDE. It decreases boot 1517time but may not be supported by default in older operating systems, e.g. 1518Windows XP. 1519 1520=back 1521 1522The default is B<ide>. 1523 1524=back 1525 1526=head3 Paging 1527 1528The following options control the mechanisms used to virtualise guest 1529memory. The defaults are selected to give the best results for the 1530common cases so you should normally leave these options 1531unspecified. 1532 1533=over 4 1534 1535=item B<hap=BOOLEAN> 1536 1537Turns "hardware assisted paging" (the use of the hardware nested page 1538table feature) on or off. This feature is called EPT (Extended Page 1539Tables) by Intel and NPT (Nested Page Tables) or RVI (Rapid 1540Virtualisation Indexing) by AMD. If turned 1541off, Xen will run the guest in "shadow page table" mode where the 1542guest's page table updates and/or TLB flushes etc. will be emulated. 1543Use of HAP is the default when available. 1544 1545=item B<oos=BOOLEAN> 1546 1547Turns "out of sync pagetables" on or off. When running in shadow page 1548table mode, the guest's page table updates may be deferred as 1549specified in the Intel/AMD architecture manuals. However, this may 1550expose unexpected bugs in the guest, or find bugs in Xen, so it is 1551possible to disable this feature. Use of out of sync page tables, 1552when Xen thinks it appropriate, is the default. 1553 1554=item B<shadow_memory=MBYTES> 1555 1556Number of megabytes to set aside for shadowing guest pagetable pages 1557(effectively acting as a cache of translated pages) or to use for HAP 1558state. By default this is 1MB per guest vCPU plus 8KB per MB of guest 1559RAM. You should not normally need to adjust this value. However, if you 1560are not using hardware assisted paging (i.e. you are using shadow 1561mode) and your guest workload consists of a very large number of 1562similar processes then increasing this value may improve performance. 1563 1564=back 1565 1566=head3 Processor and Platform Features 1567 1568The following options allow various processor and platform level 1569features to be hidden or exposed from the guest's point of view. This 1570can be useful when running older guest Operating Systems which may 1571misbehave when faced with more modern features. In general, you should 1572accept the defaults for these options wherever possible. 1573 1574=over 4 1575 1576=item B<bios="STRING"> 1577 1578Select the virtual firmware that is exposed to the guest. 1579By default, a guess is made based on the device model, but sometimes 1580it may be useful to request a different one, like UEFI. 1581 1582=over 4 1583 1584=item B<rombios> 1585 1586Loads ROMBIOS, a 16-bit x86 compatible BIOS. This is used by default 1587when B<device_model_version=qemu-xen-traditional>. This is the only BIOS 1588option supported when B<device_model_version=qemu-xen-traditional>. This is 1589the BIOS used by all previous Xen versions. 1590 1591=item B<seabios> 1592 1593Loads SeaBIOS, a 16-bit x86 compatible BIOS. This is used by default 1594with device_model_version=qemu-xen. 1595 1596=item B<ovmf> 1597 1598Loads OVMF, a standard UEFI firmware by Tianocore project. 1599Requires device_model_version=qemu-xen. 1600 1601=back 1602 1603=item B<bios_path_override="PATH"> 1604 1605Override the path to the blob to be used as BIOS. The blob provided here MUST 1606be consistent with the B<bios=> which you have specified. You should not 1607normally need to specify this option. 1608 1609This option does not have any effect if using B<bios="rombios"> or 1610B<device_model_version="qemu-xen-traditional">. 1611 1612=item B<pae=BOOLEAN> 1613 1614Hide or expose the IA32 Physical Address Extensions. These extensions 1615make it possible for a 32 bit guest Operating System to access more 1616than 4GB of RAM. Enabling PAE also enabled other features such as 1617NX. PAE is required if you wish to run a 64-bit guest Operating 1618System. In general, you should leave this enabled and allow the guest 1619Operating System to choose whether or not to use PAE. (X86 only) 1620 1621=item B<acpi=BOOLEAN> 1622 1623Expose ACPI (Advanced Configuration and Power Interface) tables from 1624the virtual firmware to the guest Operating System. ACPI is required 1625by most modern guest Operating Systems. This option is enabled by 1626default and usually you should omit it. However, it may be necessary to 1627disable ACPI for compatibility with some guest Operating Systems. 1628This option is true for x86 while it's false for ARM by default. 1629 1630=item B<acpi_s3=BOOLEAN> 1631 1632Include the S3 (suspend-to-ram) power state in the virtual firmware 1633ACPI table. True (1) by default. 1634 1635=item B<acpi_s4=BOOLEAN> 1636 1637Include S4 (suspend-to-disk) power state in the virtual firmware ACPI 1638table. True (1) by default. 1639 1640=item B<acpi_laptop_slate=BOOLEAN> 1641 1642Include the Windows laptop/slate mode switch device in the virtual 1643firmware ACPI table. False (0) by default. 1644 1645=item B<apic=BOOLEAN> 1646 1647B<(x86 only)> Include information regarding APIC (Advanced Programmable Interrupt 1648Controller) in the firmware/BIOS tables on a single processor 1649guest. This causes the MP (multiprocessor) and PIR (PCI Interrupt 1650Routing) tables to be exported by the virtual firmware. This option 1651has no effect on a guest with multiple virtual CPUs as they must 1652always include these tables. This option is enabled by default and you 1653should usually omit it but it may be necessary to disable these 1654firmware tables when using certain older guest Operating 1655Systems. These tables have been superseded by newer constructs within 1656the ACPI tables. 1657 1658=item B<nx=BOOLEAN> 1659 1660B<(x86 only)> Hides or exposes the No-eXecute capability. This allows a guest 1661Operating System to map pages in such a way that they cannot be executed which 1662can enhance security. This options requires that PAE also be 1663enabled. 1664 1665=item B<hpet=BOOLEAN> 1666 1667B<(x86 only)> Enables or disables HPET (High Precision Event Timer). This 1668option is enabled by default and you should usually omit it. 1669It may be necessary to disable the HPET in order to improve compatibility with 1670guest Operating Systems. 1671 1672=item B<altp2m="MODE"> 1673 1674B<(x86 only)> Specifies the access mode to the alternate-p2m capability. 1675Alternate-p2m allows a guest to manage multiple p2m guest physical "memory 1676views" (as opposed to a single p2m). 1677You may want this option if you want to access-control/isolate 1678access to specific guest physical memory pages accessed by the guest, e.g. for 1679domain memory introspection or for isolation/access-control of memory between 1680components within a single guest domain. This option is disabled by default. 1681 1682The valid values are as follows: 1683 1684=over 4 1685 1686=item B<disabled> 1687 1688Altp2m is disabled for the domain (default). 1689 1690=item B<mixed> 1691 1692The mixed mode allows access to the altp2m interface for both in-guest 1693and external tools as well. 1694 1695=item B<external> 1696 1697Enables access to the alternate-p2m capability by external privileged tools. 1698 1699=item B<limited> 1700 1701Enables limited access to the alternate-p2m capability, 1702ie. giving the guest access only to enable/disable the VMFUNC and #VE features. 1703 1704=back 1705 1706=item B<altp2mhvm=BOOLEAN> 1707 1708Enables or disables HVM guest access to alternate-p2m capability. 1709Alternate-p2m allows a guest to manage multiple p2m guest physical 1710"memory views" (as opposed to a single p2m). This option is 1711disabled by default and is available only to HVM domains. 1712You may want this option if you want to access-control/isolate 1713access to specific guest physical memory pages accessed by 1714the guest, e.g. for HVM domain memory introspection or 1715for isolation/access-control of memory between components within 1716a single guest HVM domain. B<This option is deprecated, use the option 1717"altp2m" instead.> 1718 1719B<Note>: While the option "altp2mhvm" is deprecated, legacy applications for 1720x86 systems will continue to work using it. 1721 1722=item B<nestedhvm=BOOLEAN> 1723 1724Enable or disables guest access to hardware virtualisation features, 1725e.g. it allows a guest Operating System to also function as a 1726hypervisor. You may want this 1727option if you want to run another hypervisor (including another copy 1728of Xen) within a Xen guest or to support a guest Operating System 1729which uses hardware virtualisation extensions (e.g. Windows XP 1730compatibility mode on more modern Windows OS). 1731This option is disabled by default. 1732 1733=item B<cpuid="LIBXL_STRING"> or B<cpuid=[ "XEND_STRING", "XEND_STRING" ]> 1734 1735Configure the value returned when a guest executes the CPUID instruction. 1736Two versions of config syntax are recognized: libxl and xend. 1737 1738The libxl syntax is a comma separated list of key=value pairs, preceded by the 1739word "host". A few keys take a numerical value, all others take a single 1740character which describes what to do with the feature bit. 1741 1742Possible values for a single feature bit: 1743 '1' -> force the corresponding bit to 1 1744 '0' -> force to 0 1745 'x' -> Get a safe value (pass through and mask with the default policy) 1746 'k' -> pass through the host bit value 1747 's' -> as 'k' but preserve across save/restore and migration (not implemented) 1748 1749Note: when specifying B<cpuid> for hypervisor leaves (0x4000xxxx major group) 1750only the lowest 8 bits of leaf's 0x4000xx00 EAX register are processed, the 1751rest are ignored (these 8 bits signify maximum number of hypervisor leaves). 1752 1753List of keys taking a value: 1754apicidsize brandid clflush family localapicid maxleaf maxhvleaf model nc 1755proccount procpkg stepping 1756 1757List of keys taking a character: 17583dnow 3dnowext 3dnowprefetch abm acpi adx aes altmovcr8 apic arat avx avx2 1759avx512-4fmaps avx512-4vnniw avx512bw avx512cd avx512dq avx512er avx512f 1760avx512ifma avx512pf avx512vbmi avx512vl bmi1 bmi2 clflushopt clfsh clwb cmov 1761cmplegacy cmpxchg16 cmpxchg8 cmt cntxid dca de ds dscpl dtes64 erms est extapic 1762f16c ffxsr fma fma4 fpu fsgsbase fxsr hle htt hypervisor ia64 ibs invpcid 1763invtsc lahfsahf lm lwp mca mce misalignsse mmx mmxext monitor movbe mpx msr 1764mtrr nodeid nx ospke osvw osxsave pae page1gb pat pbe pcid pclmulqdq pdcm 1765perfctr_core perfctr_nb pge pku popcnt pse pse36 psn rdrand rdseed rdtscp rtm 1766sha skinit smap smep smx ss sse sse2 sse3 sse4.1 sse4.2 sse4_1 sse4_2 sse4a 1767ssse3 svm svm_decode svm_lbrv svm_npt svm_nrips svm_pausefilt svm_tscrate 1768svm_vmcbclean syscall sysenter tbm tm tm2 topoext tsc tsc-deadline tsc_adjust 1769umip vme vmx wdt x2apic xop xsave xtpr 1770 1771 1772The xend syntax is a list of values in the form of 1773'leafnum:register=bitstring,register=bitstring' 1774 "leafnum" is the requested function, 1775 "register" is the response register to modify 1776 "bitstring" represents all bits in the register, its length must be 32 chars. 1777 Each successive character represent a lesser-significant bit, possible values 1778 are listed above in the libxl section. 1779 1780Example to hide two features from the guest: 'tm', which is bit #29 in EDX, and 1781'pni' (SSE3), which is bit #0 in ECX: 1782 1783xend: [ "1:ecx=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx0,edx=xx0xxxxxxxxxxxxxxxxxxxxxxxxxxxxx" ] 1784 1785libxl: "host,tm=0,sse3=0" 1786 1787More info about the CPUID instruction can be found in the processor manuals, 1788and on Wikipedia: L<http://en.wikipedia.org/wiki/CPUID> 1789 1790=item B<acpi_firmware="STRING"> 1791 1792Specifies a path to a file that contains extra ACPI firmware tables to pass into 1793a guest. The file can contain several tables in their binary AML form 1794concatenated together. Each table self describes its length so no additional 1795information is needed. These tables will be added to the ACPI table set in the 1796guest. Note that existing tables cannot be overridden by this feature. For 1797example, this cannot be used to override tables like DSDT, FADT, etc. 1798 1799=item B<smbios_firmware="STRING"> 1800 1801Specifies a path to a file that contains extra SMBIOS firmware structures to 1802pass into a guest. The file can contain a set of DMTF predefined structures 1803which will override the internal defaults. Not all predefined structures can be 1804overridden, 1805only the following types: 0, 1, 2, 3, 11, 22, 39. The file can also contain any 1806number of vendor defined SMBIOS structures (type 128 - 255). Since SMBIOS 1807structures do not present their overall size, each entry in the file must be 1808preceded by a 32b integer indicating the size of the following structure. 1809 1810=item B<ms_vm_genid="OPTION"> 1811 1812Provide a VM generation ID to the guest. 1813 1814The VM generation ID is a 128-bit random number that a guest may use 1815to determine if the guest has been restored from an earlier snapshot 1816or cloned. 1817 1818This is required for Microsoft Windows Server 2012 (and later) domain 1819controllers. 1820 1821Valid options are: 1822 1823=over 4 1824 1825=item B<generate> 1826 1827Generate a random VM generation ID every time the domain is created or 1828restored. 1829 1830=item B<none> 1831 1832Do not provide a VM generation ID. 1833 1834=back 1835 1836See also "Virtual Machine Generation ID" by Microsoft: 1837L<http://www.microsoft.com/en-us/download/details.aspx?id=30707> 1838 1839=back 1840 1841=head3 Guest Virtual Time Controls 1842 1843=over 4 1844 1845=item B<tsc_mode="MODE"> 1846 1847B<(x86 only)> Specifies how the TSC (Time Stamp Counter) should be provided to 1848the guest. B<Specifying this option as a number is deprecated.> 1849 1850Options are: 1851 1852=over 4 1853 1854=item B<default> 1855 1856Guest rdtsc/p is executed natively when monotonicity can be guaranteed 1857and emulated otherwise (with frequency scaled if necessary). 1858 1859If a HVM container in B<default> TSC mode is created on a host that 1860provides constant host TSC, its guest TSC frequency will be the same 1861as the host. If it is later migrated to another host that provide 1862constant host TSC and supports Intel VMX TSC scaling/AMD SVM TSC 1863ratio, its guest TSC frequency will be the same before and after 1864migration, and guest rdtsc/p will be executed natively after migration as well 1865 1866=item B<always_emulate> 1867 1868Guest rdtsc/p is always emulated and the virtual TSC will appear to increment 1869(kernel and user) at a fixed 1GHz rate, regardless of the pCPU HZ rate or 1870power state. Although there is an overhead associated with emulation, 1871this will NOT affect underlying CPU performance. 1872 1873=item B<native> 1874 1875Guest rdtsc/p is always executed natively (no monotonicity/frequency 1876guarantees). Guest rdtsc/p is emulated at native frequency if unsupported 1877by h/w, else executed natively. 1878 1879=item B<native_paravirt> 1880 1881Same as B<native>, except Xen manages the TSC_AUX register so the guest can 1882determine when a restore/migration has occurred and assumes guest 1883obtains/uses a pvclock-like mechanism to adjust for monotonicity and 1884frequency changes. 1885 1886If a HVM container in B<native_paravirt> TSC mode can execute both guest 1887rdtsc and guest rdtscp natively, then the guest TSC frequency will be 1888determined in a similar way to that of B<default> TSC mode. 1889 1890=back 1891 1892Please see B<xen-tscmode(7)> for more information on this option. 1893 1894=item B<localtime=BOOLEAN> 1895 1896Set the real time clock to local time or to UTC. False (0) by default, 1897i.e. set to UTC. 1898 1899=item B<rtc_timeoffset=SECONDS> 1900 1901Set the real time clock offset in seconds. No offset (0) by default. 1902 1903=item B<vpt_align=BOOLEAN> 1904 1905Specifies that periodic Virtual Platform Timers should be aligned to 1906reduce guest interrupts. Enabling this option can reduce power 1907consumption, especially when a guest uses a high timer interrupt 1908frequency (HZ) values. The default is true (1). 1909 1910=item B<timer_mode="MODE"> 1911 1912Specifies the mode for Virtual Timers. The valid values are as follows: 1913 1914=over 4 1915 1916=item B<delay_for_missed_ticks> 1917 1918Delay for missed ticks. Do not advance a vCPU's time beyond the 1919correct delivery time for interrupts that have been missed due to 1920preemption. Deliver missed interrupts when the vCPU is rescheduled and 1921advance the vCPU's virtual time stepwise for each one. 1922 1923=item B<no_delay_for_missed_ticks> 1924 1925No delay for missed ticks. As above, missed interrupts are delivered, 1926but guest time always tracks wallclock (i.e., real) time while doing 1927so. 1928 1929=item B<no_missed_ticks_pending> 1930 1931No missed interrupts are held pending. Instead, to ensure ticks are 1932delivered at some non-zero rate, if we detect missed ticks then the 1933internal tick alarm is not disabled if the vCPU is preempted during 1934the next tick period. 1935 1936=item B<one_missed_tick_pending> 1937 1938One missed tick pending. Missed interrupts are collapsed 1939together and delivered as one 'late tick'. Guest time always tracks 1940wallclock (i.e., real) time. 1941 1942=back 1943 1944=back 1945 1946=head3 Memory layout 1947 1948=over 4 1949 1950=item B<mmio_hole=MBYTES> 1951 1952Specifies the size the MMIO hole below 4GiB will be. Only valid for 1953B<device_model_version="qemu-xen">. 1954 1955Cannot be smaller than 256. Cannot be larger than 3840. 1956 1957Known good large value is 3072. 1958 1959=back 1960 1961=head3 Support for Paravirtualisation of HVM Guests 1962 1963The following options allow Paravirtualised features (such as devices) 1964to be exposed to the guest Operating System in an HVM guest. 1965Utilising these features requires specific guest support but when 1966available they will result in improved performance. 1967 1968=over 4 1969 1970=item B<xen_platform_pci=BOOLEAN> 1971 1972Enable or disable the Xen platform PCI device. The presence of this 1973virtual device enables a guest Operating System (subject to the 1974availability of suitable drivers) to make use of paravirtualisation 1975features such as disk and network devices etc. Enabling these drivers 1976improves performance and is strongly recommended when available. PV 1977drivers are available for various Operating Systems including HVM 1978Linux L<http://wiki.xen.org/wiki/XenLinuxPVonHVMdrivers> and Microsoft 1979Windows L<http://wiki.xen.org/wiki/XenWindowsGplPv>. 1980 1981Setting B<xen_platform_pci=0> with the default device_model "qemu-xen" 1982requires at least QEMU 1.6. 1983 1984=item B<viridian=[ "GROUP", "GROUP", ...]> or B<viridian=BOOLEAN> 1985 1986The groups of Microsoft Hyper-V (AKA viridian) compatible enlightenments 1987exposed to the guest. The following groups of enlightenments may be 1988specified: 1989 1990=over 4 1991 1992=item B<base> 1993 1994This group incorporates the Hypercall MSRs, Virtual processor index MSR, 1995and APIC access MSRs. These enlightenments can improve performance of 1996Windows Vista and Windows Server 2008 onwards and setting this option 1997for such guests is strongly recommended. 1998This group is also a pre-requisite for all others. If it is disabled 1999then it is an error to attempt to enable any other group. 2000 2001=item B<freq> 2002 2003This group incorporates the TSC and APIC frequency MSRs. These 2004enlightenments can improve performance of Windows 7 and Windows 2005Server 2008 R2 onwards. 2006 2007=item B<time_ref_count> 2008 2009This group incorporates Partition Time Reference Counter MSR. This 2010enlightenment can improve performance of Windows 8 and Windows 2011Server 2012 onwards. 2012 2013=item B<reference_tsc> 2014 2015This set incorporates the Partition Reference TSC MSR. This 2016enlightenment can improve performance of Windows 7 and Windows 2017Server 2008 R2 onwards. 2018 2019=item B<hcall_remote_tlb_flush> 2020 2021This set incorporates use of hypercalls for remote TLB flushing. 2022This enlightenment may improve performance of Windows guests running 2023on hosts with higher levels of (physical) CPU contention. 2024 2025=item B<apic_assist> 2026 2027This set incorporates use of the APIC assist page to avoid EOI of 2028the local APIC. 2029This enlightenment may improve performance of guests that make use of 2030per-vCPU event channel upcall vectors. 2031Note that this enlightenment will have no effect if the guest is 2032using APICv posted interrupts. 2033 2034=item B<crash_ctl> 2035 2036This group incorporates the crash control MSRs. These enlightenments 2037allow Windows to write crash information such that it can be logged 2038by Xen. 2039 2040=item B<defaults> 2041 2042This is a special value that enables the default set of groups, which 2043is currently the B<base>, B<freq>, B<time_ref_count>, B<apic_assist> 2044and B<crash_ctl> groups. 2045 2046=item B<all> 2047 2048This is a special value that enables all available groups. 2049 2050=back 2051 2052Groups can be disabled by prefixing the name with '!'. So, for example, 2053to enable all groups except B<freq>, specify: 2054 2055=over 4 2056 2057B<viridian=[ "all", "!freq" ]> 2058 2059=back 2060 2061For details of the enlightenments see the latest version of Microsoft's 2062Hypervisor Top-Level Functional Specification. 2063 2064The enlightenments should be harmless for other versions of Windows 2065(although they will not give any benefit) and the majority of other 2066non-Windows OSes. 2067However it is known that they are incompatible with some other Operating 2068Systems and in some circumstance can prevent Xen's own paravirtualisation 2069interfaces for HVM guests from being used. 2070 2071The viridian option can be specified as a boolean. A value of true (1) 2072is equivalent to the list [ "defaults" ], and a value of false (0) is 2073equivalent to an empty list. 2074 2075=back 2076 2077=head3 Emulated VGA Graphics Device 2078 2079The following options control the features of the emulated graphics 2080device. Many of these options behave similarly to the equivalent key 2081in the B<VFB_SPEC_STRING> for configuring virtual frame buffer devices 2082(see above). 2083 2084=over 4 2085 2086=item B<videoram=MBYTES> 2087 2088Sets the amount of RAM which the emulated video card will contain, 2089which in turn limits the resolutions and bit depths which will be 2090available. 2091 2092When using the qemu-xen-traditional device-model, the default as well as 2093minimum amount of video RAM for stdvga is 8 MB, which is sufficient for e.g. 20941600x1200 at 32bpp. For the upstream qemu-xen device-model, the default and 2095minimum is 16 MB. 2096 2097When using the emulated Cirrus graphics card (B<vga="cirrus">) and the 2098qemu-xen-traditional device-model, the amount of video RAM is fixed at 4 MB, 2099which is sufficient for 1024x768 at 32 bpp. For the upstream qemu-xen 2100device-model, the default and minimum is 8 MB. 2101 2102For QXL vga, both the default and minimal are 128MB. 2103If B<videoram> is set less than 128MB, an error will be triggered. 2104 2105=item B<stdvga=BOOLEAN> 2106 2107Speficies a standard VGA card with VBE (VESA BIOS Extensions) as the 2108emulated graphics device. If your guest supports VBE 2.0 or 2109later (e.g. Windows XP onwards) then you should enable this. 2110stdvga supports more video ram and bigger resolutions than Cirrus. 2111The default is false (0) which means to emulate 2112a Cirrus Logic GD5446 VGA card. 2113B<This option is deprecated, use vga="stdvga" instead>. 2114 2115=item B<vga="STRING"> 2116 2117Selects the emulated video card. 2118Options are: B<none>, B<stdvga>, B<cirrus> and B<qxl>. 2119The default is B<cirrus>. 2120 2121In general, QXL should work with the Spice remote display protocol 2122for acceleration, and a QXL driver is necessary in the guest in that case. 2123QXL can also work with the VNC protocol, but it will be like a standard 2124VGA card without acceleration. 2125 2126=item B<vnc=BOOLEAN> 2127 2128Allow access to the display via the VNC protocol. This enables the 2129other VNC-related settings. The default is (1) enabled. 2130 2131=item B<vnclisten="ADDRESS[:DISPLAYNUM]"> 2132 2133Specifies the IP address and, optionally, the VNC display number to use. 2134 2135=item B<vncdisplay=DISPLAYNUM> 2136 2137Specifies the VNC display number to use. The actual TCP port number 2138will be DISPLAYNUM+5900. 2139 2140=item B<vncunused=BOOLEAN> 2141 2142Requests that the VNC display setup searches for a free TCP port to use. 2143The actual display used can be accessed with B<xl vncviewer>. 2144 2145=item B<vncpasswd="PASSWORD"> 2146 2147Specifies the password for the VNC server. If the password is set to an 2148empty string, authentication on the VNC server will be disabled 2149allowing any user to connect. 2150 2151=item B<keymap="LANG"> 2152 2153Configure the keymap to use for the keyboard associated with this 2154display. If the input method does not easily support raw keycodes 2155(e.g. this is often the case when using VNC) then this allows us to 2156correctly map the input keys into keycodes seen by the guest. The 2157specific values which are accepted are defined by the version of the 2158device-model which you are using. See B<Keymaps> below or consult the 2159B<qemu(1)> manpage. The default is B<en-us>. 2160 2161=item B<sdl=BOOLEAN> 2162 2163Specifies that the display should be presented via an X window (using 2164Simple DirectMedia Layer). The default is (0) not enabled. 2165 2166=item B<opengl=BOOLEAN> 2167 2168Enable OpenGL acceleration of the SDL display. Only effects machines 2169using B<device_model_version="qemu-xen-traditional"> and only if the 2170device-model was compiled with OpenGL support. Default is (0) false. 2171 2172=item B<nographic=BOOLEAN> 2173 2174Enable or disable the virtual graphics device. The default is to 2175provide a VGA graphics device but this option can be used to disable 2176it. 2177 2178=back 2179 2180=head3 Spice Graphics Support 2181 2182The following options control the features of SPICE. 2183 2184=over 4 2185 2186=item B<spice=BOOLEAN> 2187 2188Allow access to the display via the SPICE protocol. This enables the 2189other SPICE-related settings. 2190 2191=item B<spicehost="ADDRESS"> 2192 2193Specifies the interface address to listen on if given, otherwise any 2194interface. 2195 2196=item B<spiceport=NUMBER> 2197 2198Specifies the port to listen on by the SPICE server if SPICE is 2199enabled. 2200 2201=item B<spicetls_port=NUMBER> 2202 2203Specifies the secure port to listen on by the SPICE server if SPICE 2204is enabled. At least one of B<spiceport> or B<spicetls_port> must be 2205given if SPICE is enabled. 2206 2207B<Note:> the options depending on B<spicetls_port> 2208have not been supported. 2209 2210=item B<spicedisable_ticketing=BOOLEAN> 2211 2212Enable clients to connect without specifying a password. When disabled, 2213B<spicepasswd> must be set. The default is (0) false. 2214 2215=item B<spicepasswd="PASSWORD"> 2216 2217Specify the password which is used by clients for establishing a connection. 2218 2219=item B<spiceagent_mouse=BOOLEAN> 2220 2221Whether SPICE agent is used for client mouse mode. The default is (1) true. 2222 2223=item B<spicevdagent=BOOLEAN> 2224 2225Enables the SPICE vdagent. The SPICE vdagent is an optional component for 2226enhancing user experience and performing guest-oriented management 2227tasks. Its features include: client mouse mode (no need to grab the mouse 2228by the client, no mouse lag), automatic adjustment of screen resolution, 2229copy and paste (text and image) between the client and the guest. It also 2230requires the vdagent service installed on the guest OS to work. 2231The default is (0) disabled. 2232 2233=item B<spice_clipboard_sharing=BOOLEAN> 2234 2235Enables SPICE clipboard sharing (copy/paste). It requires that 2236B<spicevdagent> is enabled. The default is (0) false. 2237 2238=item B<spiceusbredirection=NUMBER> 2239 2240Enables SPICE USB redirection. Creates a NUMBER of USB redirection channels 2241for redirecting up to 4 USB devices from the SPICE client to the guest's QEMU. 2242It requires an USB controller and, if not defined, it will automatically add 2243an USB2.0 controller. The default is (0) disabled. 2244 2245=item B<spice_image_compression="COMPRESSION"> 2246 2247Specifies what image compression is to be used by SPICE (if given), otherwise 2248the QEMU default will be used. Please see the documentation of your QEMU 2249version for more details. 2250 2251Available options are: B<auto_glz, auto_lz, quic, glz, lz, off>. 2252 2253=item B<spice_streaming_video="VIDEO"> 2254 2255Specifies what streaming video setting is to be used by SPICE (if given), 2256otherwise the QEMU default will be used. 2257 2258Available options are: B<filter, all, off>. 2259 2260=back 2261 2262=head3 Miscellaneous Emulated Hardware 2263 2264=over 4 2265 2266=item B<serial=[ "DEVICE", "DEVICE", ...]> 2267 2268Redirect virtual serial ports to B<DEVICE>s. Please see the 2269B<-serial> option in the B<qemu(1)> manpage for details of the valid 2270B<DEVICE> options. Default is B<vc> when in graphical mode and 2271B<stdio> if B<nographics=1> is used. 2272 2273The form serial=DEVICE is also accepted for backwards compatibility. 2274 2275=item B<soundhw="DEVICE"> 2276 2277Select the virtual sound card to expose to the guest. The valid 2278devices are defined by the device model configuration, please see the 2279B<qemu(1)> manpage for details. The default is not to export any sound 2280device. 2281 2282=item B<usb=BOOLEAN> 2283 2284Enables or disables an emulated USB bus in the guest. 2285 2286=item B<usbversion=NUMBER> 2287 2288Specifies the type of an emulated USB bus in the guest, values 1 for USB1.1, 22892 for USB2.0 and 3 for USB3.0. It is available only with an upstream QEMU. 2290Due to implementation limitations this is not compatible with the B<usb> 2291and B<usbdevice> parameters. 2292Default is (0) no USB controller defined. 2293 2294=item B<usbdevice=[ "DEVICE", "DEVICE", ...]> 2295 2296Adds B<DEVICE>s to the emulated USB bus. The USB bus must also be 2297enabled using B<usb=1>. The most common use for this option is 2298B<usbdevice=['tablet']> which adds a pointer device using absolute 2299coordinates. Such devices function better than relative coordinate 2300devices (such as a standard mouse) since many methods of exporting 2301guest graphics (such as VNC) work better in this mode. Note that this 2302is independent of the actual pointer device you are using on the 2303host/client side. 2304 2305Host devices can also be passed through in this way, by specifying 2306host:USBID, where USBID is of the form xxxx:yyyy. The USBID can 2307typically be found by using B<lsusb(1)> or B<usb-devices(1)>. 2308 2309If you wish to use the "host:bus.addr" format, remove any leading '0' from the 2310bus and addr. For example, for the USB device on bus 008 dev 002, you should 2311write "host:8.2". 2312 2313The form usbdevice=DEVICE is also accepted for backwards compatibility. 2314 2315More valid options can be found in the "usbdevice" section of the QEMU 2316documentation. 2317 2318=item B<vendor_device="VENDOR_DEVICE"> 2319 2320Selects which variant of the QEMU xen-pvdevice should be used for this 2321guest. Valid values are: 2322 2323=over 4 2324 2325=item B<none> 2326 2327The xen-pvdevice should be omitted. This is the default. 2328 2329=item B<xenserver> 2330 2331The xenserver variant of the xen-pvdevice (device-id=C000) will be 2332specified, enabling the use of XenServer PV drivers in the guest. 2333 2334=back 2335 2336This parameter only takes effect when device_model_version=qemu-xen. 2337See B<xen-pci-device-reservations(7)> for more information. 2338 2339=back 2340 2341=head2 PVH Guest Specific Options 2342 2343=over 4 2344 2345=item B<nestedhvm=BOOLEAN> 2346 2347Enable or disables guest access to hardware virtualisation features, 2348e.g. it allows a guest Operating System to also function as a hypervisor. 2349You may want this option if you want to run another hypervisor (including 2350another copy of Xen) within a Xen guest or to support a guest Operating 2351System which uses hardware virtualisation extensions (e.g. Windows XP 2352compatibility mode on more modern Windows OS). 2353 2354This option is disabled by default. 2355 2356=item B<apic=BOOLEAN> 2357 2358Enable the local APIC emulation for the guest. The local APIC information 2359will be exposed to the guest in the ACPI tables. This option is enabled by 2360default. 2361 2362=item B<bootloader="PROGRAM"> 2363 2364Run C<PROGRAM> to find the kernel image and ramdisk to use. Normally 2365C<PROGRAM> would be C<pygrub>, which is an emulation of 2366grub/grub2/syslinux. Either B<kernel> or B<bootloader> must be specified 2367for PV guests. 2368 2369=item B<bootloader_args=[ "ARG", "ARG", ...]> 2370 2371Append B<ARG>s to the arguments to the B<bootloader> 2372program. Alternatively if the argument is a simple string then it will 2373be split into words at whitespace B<(this second option is deprecated)>. 2374 2375=item B<timer_mode="MODE"> 2376 2377Specifies the mode for Virtual Timers. The valid values are as follows: 2378 2379=over 4 2380 2381=item B<delay_for_missed_ticks> 2382 2383Delay for missed ticks. Do not advance a vCPU's time beyond the 2384correct delivery time for interrupts that have been missed due to 2385preemption. Deliver missed interrupts when the vCPU is rescheduled and 2386advance the vCPU's virtual time stepwise for each one. 2387 2388=item B<no_delay_for_missed_ticks> 2389 2390No delay for missed ticks. As above, missed interrupts are delivered, 2391but guest time always tracks wallclock (i.e., real) time while doing 2392so. 2393 2394=item B<no_missed_ticks_pending> 2395 2396No missed interrupts are held pending. Instead, to ensure ticks are 2397delivered at some non-zero rate, if we detect missed ticks then the 2398internal tick alarm is not disabled if the vCPU is preempted during 2399the next tick period. 2400 2401=item B<one_missed_tick_pending> 2402 2403One missed tick pending. Missed interrupts are collapsed 2404together and delivered as one 'late tick'. Guest time always tracks 2405wallclock (i.e., real) time. 2406 2407=back 2408 2409=back 2410 2411=head3 Paging 2412 2413The following options control the mechanisms used to virtualise guest 2414memory. The defaults are selected to give the best results for the 2415common cases so you should normally leave these options 2416unspecified. 2417 2418=over 4 2419 2420=item B<hap=BOOLEAN> 2421 2422Turns "hardware assisted paging" (the use of the hardware nested page 2423table feature) on or off. This feature is called EPT (Extended Page 2424Tables) by Intel and NPT (Nested Page Tables) or RVI (Rapid 2425Virtualisation Indexing) by AMD. If turned 2426off, Xen will run the guest in "shadow page table" mode where the 2427guest's page table updates and/or TLB flushes etc. will be emulated. 2428Use of HAP is the default when available. 2429 2430=item B<oos=BOOLEAN> 2431 2432Turns "out of sync pagetables" on or off. When running in shadow page 2433table mode, the guest's page table updates may be deferred as 2434specified in the Intel/AMD architecture manuals. However, this may 2435expose unexpected bugs in the guest, or find bugs in Xen, so it is 2436possible to disable this feature. Use of out of sync page tables, 2437when Xen thinks it appropriate, is the default. 2438 2439=item B<shadow_memory=MBYTES> 2440 2441Number of megabytes to set aside for shadowing guest pagetable pages 2442(effectively acting as a cache of translated pages) or to use for HAP 2443state. By default this is 1MB per guest vCPU plus 8KB per MB of guest 2444RAM. You should not normally need to adjust this value. However, if you 2445are not using hardware assisted paging (i.e. you are using shadow 2446mode) and your guest workload consists of a very large number of 2447similar processes then increasing this value may improve performance. 2448 2449=back 2450 2451=head2 Device-Model Options 2452 2453The following options control the selection of the device-model. This 2454is the component which provides emulation of the virtual devices to an 2455HVM guest. For a PV guest a device-model is sometimes used to provide 2456backends for certain PV devices (most usually a virtual framebuffer 2457device). 2458 2459=over 4 2460 2461=item B<device_model_version="DEVICE-MODEL"> 2462 2463Selects which variant of the device-model should be used for this 2464guest. 2465 2466Valid values are: 2467 2468=over 4 2469 2470=item B<qemu-xen> 2471 2472Use the device-model merged into the upstream QEMU project. 2473This device-model is the default for Linux dom0. 2474 2475=item B<qemu-xen-traditional> 2476 2477Use the device-model based upon the historical Xen fork of QEMU. 2478This device-model is still the default for NetBSD dom0. 2479 2480=back 2481 2482It is recommended to accept the default value for new guests. If 2483you have existing guests then, depending on the nature of the guest 2484Operating System, you may wish to force them to use the device 2485model which they were installed with. 2486 2487=item B<device_model_override="PATH"> 2488 2489Override the path to the binary to be used as the device-model. The 2490binary provided here MUST be consistent with the 2491B<device_model_version> which you have specified. You should not 2492normally need to specify this option. 2493 2494=item B<device_model_stubdomain_override=BOOLEAN> 2495 2496Override the use of stubdomain based device-model. Normally this will 2497be automatically selected based upon the other features and options 2498you have selected. 2499 2500=item B<device_model_stubdomain_seclabel="LABEL"> 2501 2502Assign an XSM security label to the device-model stubdomain. 2503 2504=item B<device_model_args=[ "ARG", "ARG", ...]> 2505 2506Pass additional arbitrary options on the device-model command 2507line. Each element in the list is passed as an option to the 2508device-model. 2509 2510=item B<device_model_args_pv=[ "ARG", "ARG", ...]> 2511 2512Pass additional arbitrary options on the device-model command line for 2513a PV device model only. Each element in the list is passed as an 2514option to the device-model. 2515 2516=item B<device_model_args_hvm=[ "ARG", "ARG", ...]> 2517 2518Pass additional arbitrary options on the device-model command line for 2519an HVM device model only. Each element in the list is passed as an 2520option to the device-model. 2521 2522=back 2523 2524=head2 Keymaps 2525 2526The keymaps available are defined by the device-model which you are 2527using. Commonly this includes: 2528 2529 ar de-ch es fo fr-ca hu ja mk no pt-br sv 2530 da en-gb et fr fr-ch is lt nl pl ru th 2531 de en-us fi fr-be hr it lv nl-be pt sl tr 2532 2533The default is B<en-us>. 2534 2535See B<qemu(1)> for more information. 2536 2537=head2 Architecture Specific options 2538 2539=head3 ARM 2540 2541=over 4 2542 2543=item B<gic_version="vN"> 2544 2545Version of the GIC emulated for the guest. 2546 2547Currently, the following versions are supported: 2548 2549=over 4 2550 2551=item B<v2> 2552 2553Emulate a GICv2 2554 2555=item B<v3> 2556 2557Emulate a GICv3. Note that the emulated GIC does not support the 2558GICv2 compatibility mode. 2559 2560=item B<default> 2561 2562Emulate the same version as the native GIC hardware used by the host where 2563the domain was created. 2564 2565=back 2566 2567This requires hardware compatibility with the requested version, either 2568natively or via hardware backwards compatibility support. 2569 2570=item B<vuart="uart"> 2571 2572To enable vuart console, user must specify the following option in the 2573VM config file: 2574 2575vuart = "sbsa_uart" 2576 2577Currently, only the "sbsa_uart" model is supported for ARM. 2578 2579=back 2580 2581=head3 x86 2582 2583=over 4 2584 2585=item B<mca_caps=[ "CAP", "CAP", ... ]> 2586 2587(HVM only) Enable MCA capabilities besides default ones enabled 2588by Xen hypervisor for the HVM domain. "CAP" can be one in the 2589following list: 2590 2591=over 4 2592 2593=item B<"lmce"> 2594 2595Intel local MCE 2596 2597=item B<default> 2598 2599No MCA capabilities in above list are enabled. 2600 2601=back 2602 2603=back 2604 2605=head1 SEE ALSO 2606 2607=over 4 2608 2609=item L<xl(1)> 2610 2611=item L<xl.conf(5)> 2612 2613=item L<xlcpupool.cfg(5)> 2614 2615=item L<xl-disk-configuration(5)> 2616 2617=item L<xl-network-configuration(5)> 2618 2619=item L<xen-tscmode(7)> 2620 2621=back 2622 2623=head1 FILES 2624 2625F</etc/xen/NAME.cfg> 2626F<@XEN_DUMP_DIR@/NAME> 2627 2628=head1 BUGS 2629 2630This document may contain items which require further 2631documentation. Patches to improve incomplete items (or any other item) 2632are gratefully received on the xen-devel@lists.xen.org mailing 2633list. Please see L<http://wiki.xen.org/wiki/SubmittingXenPatches> for 2634information on how to submit a patch to Xen. 2635 2636