.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "xl.cfg 5" .TH xl.cfg 5 "2021-03-24" "4.11.4" "Xen" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" xl.cfg \- xl domain configuration file syntax .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& /etc/xen/xldomain .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" Creating a \s-1VM\s0 (a domain in Xen terminology, sometimes called a guest) with xl requires the provision of a domain configuration file. Typically, these live in \fI/etc/xen/DOMAIN.cfg\fR, where \s-1DOMAIN\s0 is the name of the domain. .SH "SYNTAX" .IX Header "SYNTAX" A domain configuration file consists of a series of options, specified by using \f(CW\*(C`KEY=VALUE\*(C'\fR pairs. .PP Some \f(CW\*(C`KEY\*(C'\fRs are mandatory, some are general options which apply to any guest type, while others relate only to specific guest types (e.g. \s-1PV\s0 or \s-1HVM\s0 guests). .PP A \f(CW\*(C`VALUE\*(C'\fR can be one of: .ie n .IP "\fB""\s-1STRING""\s0\fR" 4 .el .IP "\fB``\s-1STRING''\s0\fR" 4 .IX Item "STRING" A string, surrounded by either single or double quotes. But if the \&\s-1STRING\s0 is part of a \s-1SPEC_STRING,\s0 the quotes should be omitted. .IP "\fB\s-1NUMBER\s0\fR" 4 .IX Item "NUMBER" A number, in either decimal, octal (using a \f(CW0\fR prefix) or hexadecimal (using a \f(CW\*(C`0x\*(C'\fR prefix) format. .IP "\fB\s-1BOOLEAN\s0\fR" 4 .IX Item "BOOLEAN" A \f(CW\*(C`NUMBER\*(C'\fR interpreted as \f(CW\*(C`False\*(C'\fR (\f(CW0\fR) or \f(CW\*(C`True\*(C'\fR (any other value). .IP "\fB[ \s-1VALUE, VALUE, ...\s0 ]\fR" 4 .IX Item "[ VALUE, VALUE, ... ]" A list of \f(CW\*(C`VALUE\*(C'\fRs of the above types. Lists can be heterogeneous and nested. .PP The semantics of each \f(CW\*(C`KEY\*(C'\fR defines which type of \f(CW\*(C`VALUE\*(C'\fR is required. .PP Pairs may be separated either by a newline or a semicolon. Both of the following are valid: .PP .Vb 2 \& name="h0" \& type="hvm" \& \& name="h0"; type="hvm" .Ve .SH "OPTIONS" .IX Header "OPTIONS" .SS "Mandatory Configuration Items" .IX Subsection "Mandatory Configuration Items" The following key is mandatory for any guest type. .ie n .IP "\fBname=""\s-1NAME""\s0\fR" 4 .el .IP "\fBname=``\s-1NAME''\s0\fR" 4 .IX Item "name=NAME" Specifies the name of the domain. Names of domains existing on a single host must be unique. .SS "Selecting Guest Type" .IX Subsection "Selecting Guest Type" .ie n .IP "\fBtype=""pv""\fR" 4 .el .IP "\fBtype=``pv''\fR" 4 .IX Item "type=pv" Specifies that this is to be a \s-1PV\s0 domain, suitable for hosting Xen-aware guest operating systems. This is the default. .ie n .IP "\fBtype=""pvh""\fR" 4 .el .IP "\fBtype=``pvh''\fR" 4 .IX Item "type=pvh" Specifies that this is to be an \s-1PVH\s0 domain. That is a lightweight HVM-like guest without a device model and without many of the emulated devices available to \s-1HVM\s0 guests. Note that this mode requires a \s-1PVH\s0 aware kernel. .ie n .IP "\fBtype=""hvm""\fR" 4 .el .IP "\fBtype=``hvm''\fR" 4 .IX Item "type=hvm" Specifies that this is to be an \s-1HVM\s0 domain. That is, a fully virtualised computer with emulated \s-1BIOS,\s0 disk and network peripherals, etc. .PP \fIDeprecated guest type selection\fR .IX Subsection "Deprecated guest type selection" .PP Note that the builder option is being deprecated in favor of the type option. .ie n .IP "\fBbuilder=""generic""\fR" 4 .el .IP "\fBbuilder=``generic''\fR" 4 .IX Item "builder=generic" Specifies that this is to be a \s-1PV\s0 domain, suitable for hosting Xen-aware guest operating systems. This is the default. .ie n .IP "\fBbuilder=""hvm""\fR" 4 .el .IP "\fBbuilder=``hvm''\fR" 4 .IX Item "builder=hvm" Specifies that this is to be an \s-1HVM\s0 domain. That is, a fully virtualised computer with emulated \s-1BIOS,\s0 disk and network peripherals, etc. .SS "General Options" .IX Subsection "General Options" The following options apply to guests of any type. .PP \fI\s-1CPU\s0 Allocation\fR .IX Subsection "CPU Allocation" .ie n .IP "\fBpool=""\s-1CPUPOOLNAME""\s0\fR" 4 .el .IP "\fBpool=``\s-1CPUPOOLNAME''\s0\fR" 4 .IX Item "pool=CPUPOOLNAME" Put the guest's vCPUs into the named \s-1CPU\s0 pool. .IP "\fBvcpus=N\fR" 4 .IX Item "vcpus=N" Start the guest with N vCPUs initially online. .IP "\fBmaxvcpus=M\fR" 4 .IX Item "maxvcpus=M" Allow the guest to bring up a maximum of M vCPUs. When starting the guest, if \&\fBvcpus=N\fR is less than \fBmaxvcpus=M\fR then the first \fBN\fR vCPUs will be created online and the remainder will be created offline. .ie n .IP "\fBcpus=""\s-1CPULIST""\s0\fR" 4 .el .IP "\fBcpus=``\s-1CPULIST''\s0\fR" 4 .IX Item "cpus=CPULIST" List of host CPUs the guest is allowed to use. Default is no pinning at all (more on this below). A \f(CW\*(C`CPULIST\*(C'\fR may be specified as follows: .RS 4 .ie n .IP """all""" 4 .el .IP "``all''" 4 .IX Item "all" To allow all the vCPUs of the guest to run on all the CPUs on the host. .ie n .IP """0\-3,5,^1""" 4 .el .IP "``0\-3,5,^1''" 4 .IX Item "0-3,5,^1" To allow all the vCPUs of the guest to run on CPUs 0,2,3,5. It is possible to combine this with \*(L"all\*(R", meaning \*(L"all,^7\*(R" results in all the vCPUs of the guest being allowed to run on all the CPUs of the host except \s-1CPU 7.\s0 .ie n .IP """nodes:0\-3,^node:2""" 4 .el .IP "``nodes:0\-3,^node:2''" 4 .IX Item "nodes:0-3,^node:2" To allow all the vCPUs of the guest to run on the CPUs from \s-1NUMA\s0 nodes 0,1,3 of the host. So, if CPUs 0\-3 belong to node 0, CPUs 4\-7 belong to node 1, CPUs 8\-11 to node 2 and CPUs 12\-15 to node 3, the above would mean all the vCPUs of the guest would be allowed to run on CPUs 0\-7,12\-15. .Sp Combining this notation with the one above is possible. For instance, \&\*(L"1,node:1,^6\*(R", means all the vCPUs of the guest will run on \s-1CPU 1\s0 and on all the CPUs of \s-1NUMA\s0 node 1, but not on \s-1CPU 6.\s0 Following the same example as above, that would be CPUs 1,4,5,7. .Sp Combining this with \*(L"all\*(R" is also possible, meaning \*(L"all,^node:1\*(R" results in all the vCPUs of the guest running on all the CPUs on the host, except for the CPUs belonging to the host \s-1NUMA\s0 node 1. .ie n .IP "[""2"", ""3\-8,^5""]" 4 .el .IP "[``2'', ``3\-8,^5'']" 4 .IX Item "[2, 3-8,^5]" To ask for specific vCPU mapping. That means (in this example), vCPU 0 of the guest will run on \s-1CPU 2\s0 of the host and vCPU 1 of the guest will run on CPUs 3,4,6,7,8 of the host (excluding \s-1CPU 5\s0). .Sp More complex notation can be also used, exactly as described above. So \&\*(L"all,^5\-8\*(R", or just \*(L"all\*(R", or \*(L"node:0,node:2,^9\-11,18\-20\*(R" are all legal, for each element of the list. .RE .RS 4 .Sp If this option is not specified, no vCPU to \s-1CPU\s0 pinning is established, and the vCPUs of the guest can run on all the CPUs of the host. If this option is specified, the intersection of the vCPU pinning mask, provided here, and the soft affinity mask, if provided via \fBcpus_soft=\fR, is utilized to compute the domain node-affinity for driving memory allocations. .RE .ie n .IP "\fBcpus_soft=""\s-1CPULIST""\s0\fR" 4 .el .IP "\fBcpus_soft=``\s-1CPULIST''\s0\fR" 4 .IX Item "cpus_soft=CPULIST" Exactly as \fBcpus=\fR, but specifies soft affinity, rather than pinning (hard affinity). When using the credit scheduler, this means what CPUs the vCPUs of the domain prefer. .Sp A \f(CW\*(C`CPULIST\*(C'\fR is specified exactly as for \fBcpus=\fR, detailed earlier in the manual. .Sp If this option is not specified, the vCPUs of the guest will not have any preference regarding host CPUs. If this option is specified, the intersection of the soft affinity mask, provided here, and the vCPU pinning, if provided via \fBcpus=\fR, is utilized to compute the domain node-affinity for driving memory allocations. .Sp If this option is not specified (and \fBcpus=\fR is not specified either), libxl automatically tries to place the guest on the least possible number of nodes. A heuristic approach is used for choosing the best node (or set of nodes), with the goal of maximizing performance for the guest and, at the same time, achieving efficient utilization of host CPUs and memory. In that case, the soft affinity of all the vCPUs of the domain will be set to host CPUs belonging to \s-1NUMA\s0 nodes chosen during placement. .Sp For more details, see \fBxl\-numa\-placement\fR\|(7). .PP \fI\s-1CPU\s0 Scheduling\fR .IX Subsection "CPU Scheduling" .IP "\fBcpu_weight=WEIGHT\fR" 4 .IX Item "cpu_weight=WEIGHT" A domain with a weight of 512 will get twice as much \s-1CPU\s0 as a domain with a weight of 256 on a contended host. Legal weights range from 1 to 65535 and the default is 256. Honoured by the credit and credit2 schedulers. .IP "\fBcap=N\fR" 4 .IX Item "cap=N" The cap optionally fixes the maximum amount of \s-1CPU\s0 a domain will be able to consume, even if the host system has idle \s-1CPU\s0 cycles. The cap is expressed as a percentage of one physical \s-1CPU: 100\s0 is 1 physical \s-1CPU, 50\s0 is half a \s-1CPU, 400\s0 is 4 CPUs, etc. The default, 0, means there is no cap. Honoured by the credit and credit2 schedulers. .Sp \&\fB\s-1NOTE\s0\fR: Many systems have features that will scale down the computing power of a \s-1CPU\s0 that is not 100% utilized. This can be done in the operating system, but can also sometimes be done below the operating system, in the \s-1BIOS.\s0 If you set a cap such that individual cores are running at less than 100%, this may have an impact on the performance of your workload over and above the impact of the cap. For example, if your processor runs at 2GHz, and you cap a \s-1VM\s0 at 50%, the power management system may also reduce the clock speed to 1GHz; the effect will be that your \s-1VM\s0 gets 25% of the available power (50% of 1GHz) rather than 50% (50% of 2GHz). If you are not getting the performance you expect, look at performance and \s-1CPU\s0 frequency options in your operating system and your \s-1BIOS.\s0 .PP \fIMemory Allocation\fR .IX Subsection "Memory Allocation" .IP "\fBmemory=MBYTES\fR" 4 .IX Item "memory=MBYTES" Start the guest with \s-1MBYTES\s0 megabytes of \s-1RAM.\s0 .IP "\fBmaxmem=MBYTES\fR" 4 .IX Item "maxmem=MBYTES" Specifies the maximum amount of memory a guest can ever see. The value of \fBmaxmem=\fR must be equal to or greater than that of \fBmemory=\fR. .Sp In combination with \fBmemory=\fR it will start the guest \*(L"pre-ballooned\*(R", if the values of \fBmemory=\fR and \fBmaxmem=\fR differ. A \*(L"pre-ballooned\*(R" \s-1HVM\s0 guest needs a balloon driver, without a balloon driver it will crash. .Sp \&\fB\s-1NOTE\s0\fR: Because of the way ballooning works, the guest has to allocate memory to keep track of maxmem pages, regardless of how much memory it actually has available to it. A guest with maxmem=262144 and memory=8096 will report significantly less memory available for use than a system with maxmem=8096 memory=8096 due to the memory overhead of having to track the unused pages. .PP \fIGuest Virtual \s-1NUMA\s0 Configuration\fR .IX Subsection "Guest Virtual NUMA Configuration" .IP "\fBvnuma=[ \s-1VNODE_SPEC, VNODE_SPEC, ...\s0 ]\fR" 4 .IX Item "vnuma=[ VNODE_SPEC, VNODE_SPEC, ... ]" Specify virtual \s-1NUMA\s0 configuration with positional arguments. The nth \fB\s-1VNODE_SPEC\s0\fR in the list specifies the configuration of the nth virtual node. .Sp Note that virtual \s-1NUMA\s0 is not supported for \s-1PV\s0 guests yet, because there is an issue with the \s-1CPUID\s0 instruction handling that affects \s-1PV\s0 virtual \&\s-1NUMA.\s0 Furthermore, guests with virtual \s-1NUMA\s0 cannot be saved or migrated because the migration stream does not preserve node information. .Sp Each \fB\s-1VNODE_SPEC\s0\fR is a list, which has a form of \&\*(L"[\s-1VNODE_CONFIG_OPTION, VNODE_CONFIG_OPTION, ...\s0 ]\*(R" (without the quotes). .Sp For example, vnuma = [ [\*(L"pnode=0\*(R",\*(L"size=512\*(R",\*(L"vcpus=0\-4\*(R",\*(L"vdistances=10,20\*(R"] ] means vnode 0 is mapped to pnode 0, has 512MB ram, has vcpus 0 to 4, the distance to itself is 10 and the distance to vnode 1 is 20. .Sp Each \fB\s-1VNODE_CONFIG_OPTION\s0\fR is a quoted \f(CW\*(C`KEY=VALUE\*(C'\fR pair. Supported \&\fB\s-1VNODE_CONFIG_OPTION\s0\fRs are (they are all mandatory at the moment): .RS 4 .IP "\fBpnode=NUMBER\fR" 4 .IX Item "pnode=NUMBER" Specifies which physical node this virtual node maps to. .IP "\fBsize=MBYTES\fR" 4 .IX Item "size=MBYTES" Specifies the size of this virtual node. The sum of memory sizes of all vnodes will become \fBmaxmem=\fR. If \fBmaxmem=\fR is specified separately, a check is performed to make sure the sum of all vnode memory matches \&\fBmaxmem=\fR. .ie n .IP "\fBvcpus=""\s-1CPUSTRING""\s0\fR" 4 .el .IP "\fBvcpus=``\s-1CPUSTRING''\s0\fR" 4 .IX Item "vcpus=CPUSTRING" Specifies which vCPUs belong to this node. \fB\*(L"\s-1CPUSTRING\*(R"\s0\fR is a string of numerical values separated by a comma. You can specify a range and/or a single \s-1CPU.\s0 An example would be \*(L"vcpus=0\-5,8\*(R", which means you specified vCPU 0 to vCPU 5, and vCPU 8. .IP "\fBvdistances=NUMBER, \s-1NUMBER, ...\s0 \fR" 4 .IX Item "vdistances=NUMBER, NUMBER, ... " Specifies the virtual distance from this node to all nodes (including itself) with positional arguments. For example, \*(L"vdistance=10,20\*(R" for vnode 0 means the distance from vnode 0 to vnode 0 is 10, from vnode 0 to vnode 1 is 20. The number of arguments supplied must match the total number of vnodes. .Sp Normally you can use the values from \fBxl info \-n\fR or \fBnumactl \&\-\-hardware\fR to fill the vdistances list. .RE .RS 4 .RE .PP \fIEvent Actions\fR .IX Subsection "Event Actions" .ie n .IP "\fBon_poweroff=""\s-1ACTION""\s0\fR" 4 .el .IP "\fBon_poweroff=``\s-1ACTION''\s0\fR" 4 .IX Item "on_poweroff=ACTION" Specifies what should be done with the domain if it shuts itself down. The \fB\s-1ACTION\s0\fRs are: .RS 4 .IP "\fBdestroy\fR" 4 .IX Item "destroy" destroy the domain .IP "\fBrestart\fR" 4 .IX Item "restart" destroy the domain and immediately create a new domain with the same configuration .IP "\fBrename-restart\fR" 4 .IX Item "rename-restart" rename the domain which terminated, and then immediately create a new domain with the same configuration as the original .IP "\fBpreserve\fR" 4 .IX Item "preserve" keep the domain. It can be examined, and later destroyed with \fBxl destroy\fR. .IP "\fBcoredump-destroy\fR" 4 .IX Item "coredump-destroy" write a \*(L"coredump\*(R" of the domain to \fI/var/lib/xen/dump/NAME\fR and then destroy the domain. .IP "\fBcoredump-restart\fR" 4 .IX Item "coredump-restart" write a \*(L"coredump\*(R" of the domain to \fI/var/lib/xen/dump/NAME\fR and then restart the domain. .IP "\fBsoft-reset\fR" 4 .IX Item "soft-reset" Reset all Xen specific interfaces for the Xen-aware \s-1HVM\s0 domain allowing it to reestablish these interfaces and continue executing the domain. \s-1PV\s0 and non-Xen-aware \s-1HVM\s0 guests are not supported. .RE .RS 4 .Sp The default for \fBon_poweroff\fR is \fBdestroy\fR. .RE .ie n .IP "\fBon_reboot=""\s-1ACTION""\s0\fR" 4 .el .IP "\fBon_reboot=``\s-1ACTION''\s0\fR" 4 .IX Item "on_reboot=ACTION" Action to take if the domain shuts down with a reason code requesting a reboot. Default is \fBrestart\fR. .ie n .IP "\fBon_watchdog=""\s-1ACTION""\s0\fR" 4 .el .IP "\fBon_watchdog=``\s-1ACTION''\s0\fR" 4 .IX Item "on_watchdog=ACTION" Action to take if the domain shuts down due to a Xen watchdog timeout. Default is \fBdestroy\fR. .ie n .IP "\fBon_crash=""\s-1ACTION""\s0\fR" 4 .el .IP "\fBon_crash=``\s-1ACTION''\s0\fR" 4 .IX Item "on_crash=ACTION" Action to take if the domain crashes. Default is \fBdestroy\fR. .ie n .IP "\fBon_soft_reset=""\s-1ACTION""\s0\fR" 4 .el .IP "\fBon_soft_reset=``\s-1ACTION''\s0\fR" 4 .IX Item "on_soft_reset=ACTION" Action to take if the domain performs a 'soft reset' (e.g. does \fBkexec\fR). Default is \fBsoft-reset\fR. .PP \fIDirect Kernel Boot\fR .IX Subsection "Direct Kernel Boot" .PP Direct kernel boot allows booting guests with a kernel and an initrd stored on a filesystem available to the host physical machine, allowing command line arguments to be passed directly. \s-1PV\s0 guest direct kernel boot is supported. \s-1HVM\s0 guest direct kernel boot is supported with some limitations (it's supported when using \fBqemu-xen\fR and the default \s-1BIOS\s0 'seabios', but not supported in case of using \fBstubdom-dm\fR and the old 'rombios'.) .ie n .IP "\fBkernel=""\s-1PATHNAME""\s0\fR" 4 .el .IP "\fBkernel=``\s-1PATHNAME''\s0\fR" 4 .IX Item "kernel=PATHNAME" Load the specified file as the kernel image. .ie n .IP "\fBramdisk=""\s-1PATHNAME""\s0\fR" 4 .el .IP "\fBramdisk=``\s-1PATHNAME''\s0\fR" 4 .IX Item "ramdisk=PATHNAME" Load the specified file as the ramdisk. .ie n .IP "\fBcmdline=""\s-1STRING""\s0\fR" 4 .el .IP "\fBcmdline=``\s-1STRING''\s0\fR" 4 .IX Item "cmdline=STRING" Append \fB\s-1STRING\s0\fR to the kernel command line. (Note: the meaning of this is guest specific). It can replace \fBroot=\*(L"\s-1STRING\*(R"\s0\fR along with \fBextra=\*(L"\s-1STRING\*(R"\s0\fR and is preferred. When \fBcmdline=\*(L"\s-1STRING\*(R"\s0\fR is set, \&\fBroot=\*(L"\s-1STRING\*(R"\s0\fR and \fBextra=\*(L"\s-1STRING\*(R"\s0\fR will be ignored. .ie n .IP "\fBroot=""\s-1STRING""\s0\fR" 4 .el .IP "\fBroot=``\s-1STRING''\s0\fR" 4 .IX Item "root=STRING" Append \fBroot=STRING\fR to the kernel command line (Note: the meaning of this is guest specific). .ie n .IP "\fBextra=""\s-1STRING""\s0\fR" 4 .el .IP "\fBextra=``\s-1STRING''\s0\fR" 4 .IX Item "extra=STRING" Append \fB\s-1STRING\s0\fR to the kernel command line. (Note: the meaning of this is guest specific). .PP \fINon direct Kernel Boot\fR .IX Subsection "Non direct Kernel Boot" .PP Non direct kernel boot allows booting guests with a firmware. This can be used by all types of guests, although the selection of options is different depending on the guest type. .PP This option provides the flexibly of letting the guest decide which kernel they want to boot, while preventing having to poke at the guest file system form the toolstack domain. .PP \s-1PV\s0 guest options .IX Subsection "PV guest options" .ie n .IP "\fBfirmware=""pvgrub32|pvgrub64""\fR" 4 .el .IP "\fBfirmware=``pvgrub32|pvgrub64''\fR" 4 .IX Item "firmware=pvgrub32|pvgrub64" Boots a guest using a para-virtualized version of grub that runs inside of the guest. The bitness of the guest needs to be know, so that the right version of pvgrub can be selected. .Sp Note that xl expects to find the pvgrub32.bin and pvgrub64.bin binaries in \&\fI/usr/lib/xen\-4.11/boot\fR. .PP \s-1HVM\s0 guest options .IX Subsection "HVM guest options" .ie n .IP "\fBfirmware=""bios""\fR" 4 .el .IP "\fBfirmware=``bios''\fR" 4 .IX Item "firmware=bios" Boot the guest using the default \s-1BIOS\s0 firmware, which depends on the chosen device model. .ie n .IP "\fBfirmware=""uefi""\fR" 4 .el .IP "\fBfirmware=``uefi''\fR" 4 .IX Item "firmware=uefi" Boot the guest using the default \s-1UEFI\s0 firmware, currently \s-1OVMF.\s0 .ie n .IP "\fBfirmware=""seabios""\fR" 4 .el .IP "\fBfirmware=``seabios''\fR" 4 .IX Item "firmware=seabios" Boot the guest using the SeaBIOS \s-1BIOS\s0 firmware. .ie n .IP "\fBfirmware=""rombios""\fR" 4 .el .IP "\fBfirmware=``rombios''\fR" 4 .IX Item "firmware=rombios" Boot the guest using the \s-1ROMBIOS BIOS\s0 firmware. .ie n .IP "\fBfirmware=""ovmf""\fR" 4 .el .IP "\fBfirmware=``ovmf''\fR" 4 .IX Item "firmware=ovmf" Boot the guest using the \s-1OVMF UEFI\s0 firmware. .ie n .IP "\fBfirmware=""\s-1PATH""\s0\fR" 4 .el .IP "\fBfirmware=``\s-1PATH''\s0\fR" 4 .IX Item "firmware=PATH" Load the specified file as firmware for the guest. .PP \s-1PVH\s0 guest options .IX Subsection "PVH guest options" .PP Currently there's no firmware available for \s-1PVH\s0 guests, they should be booted using the \fBDirect Kernel Boot\fR method or the \fBbootloader\fR option. .IP "\fBpvshim=BOOLEAN\fR" 4 .IX Item "pvshim=BOOLEAN" Whether to boot this guest as a \s-1PV\s0 guest within a \s-1PVH\s0 container. Ie, the guest will experience a \s-1PV\s0 environment, but processor hardware extensions are used to separate its address space to mitigate the Meltdown attack (\s-1CVE\-2017\-5754\s0). .Sp Default is false. .ie n .IP "\fBpvshim_path=""\s-1PATH""\s0\fR" 4 .el .IP "\fBpvshim_path=``\s-1PATH''\s0\fR" 4 .IX Item "pvshim_path=PATH" The \s-1PV\s0 shim is a specially-built firmware-like executable constructed from the hypervisor source tree. This option specifies to use a non-default shim. Ignored if pvhsim is false. .ie n .IP "\fBpvshim_cmdline=""\s-1STRING""\s0\fR" 4 .el .IP "\fBpvshim_cmdline=``\s-1STRING''\s0\fR" 4 .IX Item "pvshim_cmdline=STRING" Command line for the shim. Default is \*(L"pv-shim console=xen,pv\*(R". Ignored if pvhsim is false. .ie n .IP "\fBpvshim_extra=""\s-1STRING""\s0\fR" 4 .el .IP "\fBpvshim_extra=``\s-1STRING''\s0\fR" 4 .IX Item "pvshim_extra=STRING" Extra command line arguments for the shim. If supplied, appended to the value for pvshim_cmdline. Default is empty. Ignored if pvhsim is false. .PP \fIOther Options\fR .IX Subsection "Other Options" .ie n .IP "\fBuuid=""\s-1UUID""\s0\fR" 4 .el .IP "\fBuuid=``\s-1UUID''\s0\fR" 4 .IX Item "uuid=UUID" Specifies the \s-1UUID\s0 of the domain. If not specified, a fresh unique \&\s-1UUID\s0 will be generated. .ie n .IP "\fBseclabel=""\s-1LABEL""\s0\fR" 4 .el .IP "\fBseclabel=``\s-1LABEL''\s0\fR" 4 .IX Item "seclabel=LABEL" Assign an \s-1XSM\s0 security label to this domain. .ie n .IP "\fBinit_seclabel=""\s-1LABEL""\s0\fR" 4 .el .IP "\fBinit_seclabel=``\s-1LABEL''\s0\fR" 4 .IX Item "init_seclabel=LABEL" Specify an \s-1XSM\s0 security label used for this domain temporarily during its build. The domain's \s-1XSM\s0 label will be changed to the execution seclabel (specified by \fBseclabel\fR) once the build is complete, prior to unpausing the domain. With a properly constructed security policy (such as nomigrate_t in the example policy), this can be used to build a domain whose memory is not accessible to the toolstack domain. .IP "\fBmax_grant_frames=NUMBER\fR" 4 .IX Item "max_grant_frames=NUMBER" Specify the maximum number of grant frames the domain is allowed to have. This value controls how many pages the domain is able to grant access to for other domains, needed e.g. for the operation of paravirtualized devices. The default is settable via \fBxl.conf\fR\|(5). .IP "\fBmax_maptrack_frames=NUMBER\fR" 4 .IX Item "max_maptrack_frames=NUMBER" Specify the maximum number of grant maptrack frames the domain is allowed to have. This value controls how many pages of foreign domains can be accessed via the grant mechanism by this domain. The default value is settable via \&\fBxl.conf\fR\|(5). .IP "\fBnomigrate=BOOLEAN\fR" 4 .IX Item "nomigrate=BOOLEAN" Disable migration of this domain. This enables certain other features which are incompatible with migration. Currently this is limited to enabling the invariant \s-1TSC\s0 feature flag in \s-1CPUID\s0 results when \s-1TSC\s0 is not emulated. .IP "\fBdriver_domain=BOOLEAN\fR" 4 .IX Item "driver_domain=BOOLEAN" Specify that this domain is a driver domain. This enables certain features needed in order to run a driver domain. .IP "\fBdevice_tree=PATH\fR" 4 .IX Item "device_tree=PATH" Specify a partial device tree (compiled via the Device Tree Compiler). Everything under the node \*(L"/passthrough\*(R" will be copied into the guest device tree. For convenience, the node \*(L"/aliases\*(R" is also copied to allow the user to define aliases which can be used by the guest kernel. .Sp Given the complexity of verifying the validity of a device tree, this option should only be used with a trusted device tree. .Sp Note that the partial device tree should avoid using the phandle 65000 which is reserved by the toolstack. .SS "Devices" .IX Subsection "Devices" The following options define the paravirtual, emulated and physical devices which the guest will contain. .ie n .IP "\fBdisk=[ ""\s-1DISK_SPEC_STRING"", ""DISK_SPEC_STRING"", ...\s0]\fR" 4 .el .IP "\fBdisk=[ ``\s-1DISK_SPEC_STRING'', ``DISK_SPEC_STRING'', ...\s0]\fR" 4 .IX Item "disk=[ DISK_SPEC_STRING, DISK_SPEC_STRING, ...]" Specifies the disks (both emulated disks and Xen virtual block devices) which are to be provided to the guest, and what objects on the host they should map to. See \fBxl\-disk\-configuration\fR\|(5) for more details. .ie n .IP "\fBvif=[ ""\s-1NET_SPEC_STRING"", ""NET_SPEC_STRING"", ...\s0]\fR" 4 .el .IP "\fBvif=[ ``\s-1NET_SPEC_STRING'', ``NET_SPEC_STRING'', ...\s0]\fR" 4 .IX Item "vif=[ NET_SPEC_STRING, NET_SPEC_STRING, ...]" Specifies the network interfaces (both emulated network adapters, and Xen virtual interfaces) which are to be provided to the guest. See \&\fBxl\-network\-configuration\fR\|(5) for more details. .ie n .IP "\fBvtpm=[ ""\s-1VTPM_SPEC_STRING"", ""VTPM_SPEC_STRING"", ...\s0]\fR" 4 .el .IP "\fBvtpm=[ ``\s-1VTPM_SPEC_STRING'', ``VTPM_SPEC_STRING'', ...\s0]\fR" 4 .IX Item "vtpm=[ VTPM_SPEC_STRING, VTPM_SPEC_STRING, ...]" Specifies the Virtual Trusted Platform module to be provided to the guest. See \fBxen\-vtpm\fR\|(7) for more details. .Sp Each \fB\s-1VTPM_SPEC_STRING\s0\fR is a comma-separated list of \f(CW\*(C`KEY=VALUE\*(C'\fR settings from the following list: .RS 4 .IP "\fBbackend=domain\-id\fR" 4 .IX Item "backend=domain-id" Specifies the backend domain name or id. \fBThis value is required!\fR If this domain is a guest, the backend should be set to the vTPM domain name. If this domain is a vTPM, the backend should be set to the vTPM manager domain name. .IP "\fBuuid=UUID\fR" 4 .IX Item "uuid=UUID" Specifies the \s-1UUID\s0 of this vTPM device. The \s-1UUID\s0 is used to uniquely identify the vTPM device. You can create one using the \fB\fBuuidgen\fB\|(1)\fR program on unix systems. If left unspecified, a new \s-1UUID\s0 will be randomly generated every time the domain boots. If this is a vTPM domain, you should specify a value. The value is optional if this is a guest domain. .RE .RS 4 .RE .ie n .IP "\fBp9=[ ""9PFS_SPEC_STRING"", ""9PFS_SPEC_STRING"", ...]\fR" 4 .el .IP "\fBp9=[ ``9PFS_SPEC_STRING'', ``9PFS_SPEC_STRING'', ...]\fR" 4 .IX Item "p9=[ 9PFS_SPEC_STRING, 9PFS_SPEC_STRING, ...]" Creates a Xen 9pfs connection to share a filesystem from the backend to the frontend. .Sp Each \fB9PFS_SPEC_STRING\fR is a comma-separated list of \f(CW\*(C`KEY=VALUE\*(C'\fR settings, from the following list: .RS 4 .IP "\fBtag=STRING\fR" 4 .IX Item "tag=STRING" 9pfs tag to identify the filesystem share. The tag is needed on the guest side to mount it. .ie n .IP "\fBsecurity_model=""none""\fR" 4 .el .IP "\fBsecurity_model=``none''\fR" 4 .IX Item "security_model=none" Only \*(L"none\*(R" is supported today, which means that the files are stored using the same credentials as those they have in the guest (no user ownership squash or remap). .IP "\fBpath=STRING\fR" 4 .IX Item "path=STRING" Filesystem path on the backend to export. .IP "\fBbackend=domain\-id\fR" 4 .IX Item "backend=domain-id" Specify the backend domain name or id, defaults to dom0. .RE .RS 4 .RE .ie n .IP "\fBpvcalls=[ ""backend=domain\-id"", ... ]\fR" 4 .el .IP "\fBpvcalls=[ ``backend=domain\-id'', ... ]\fR" 4 .IX Item "pvcalls=[ backend=domain-id, ... ]" Creates a Xen pvcalls connection to handle pvcalls requests from frontend to backend. It can be used as an alternative networking model. For more information about the protocol, see https://xenbits.xen.org/docs/unstable/misc/pvcalls.html. .ie n .IP "\fBvfb=[ ""\s-1VFB_SPEC_STRING"", ""VFB_SPEC_STRING"", ...\s0]\fR" 4 .el .IP "\fBvfb=[ ``\s-1VFB_SPEC_STRING'', ``VFB_SPEC_STRING'', ...\s0]\fR" 4 .IX Item "vfb=[ VFB_SPEC_STRING, VFB_SPEC_STRING, ...]" Specifies the paravirtual framebuffer devices which should be supplied to the domain. .Sp This option does not control the emulated graphics card presented to an \s-1HVM\s0 guest. See \fBEmulated \s-1VGA\s0 Graphics Device\fR below for how to configure the emulated device. If \fBEmulated \s-1VGA\s0 Graphics Device\fR options are used in a \s-1PV\s0 guest configuration, \fBxl\fR will pick up \fBvnc\fR, \fBvnclisten\fR, \&\fBvncpasswd\fR, \fBvncdisplay\fR, \fBvncunused\fR, \fBsdl\fR, \fBopengl\fR and \&\fBkeymap\fR to construct the paravirtual framebuffer device for the guest. .Sp Each \fB\s-1VFB_SPEC_STRING\s0\fR is a comma-separated list of \f(CW\*(C`KEY=VALUE\*(C'\fR settings, from the following list: .RS 4 .IP "\fBvnc=BOOLEAN\fR" 4 .IX Item "vnc=BOOLEAN" Allow access to the display via the \s-1VNC\s0 protocol. This enables the other VNC-related settings. Default is 1 (enabled). .IP "\fBvnclisten=ADDRESS[:DISPLAYNUM]\fR" 4 .IX Item "vnclisten=ADDRESS[:DISPLAYNUM]" Specifies the \s-1IP\s0 address, and optionally the \s-1VNC\s0 display number, to use. .Sp Note: if you specify the display number here, you should not use the \fBvncdisplay\fR option. .IP "\fBvncdisplay=DISPLAYNUM\fR" 4 .IX Item "vncdisplay=DISPLAYNUM" Specifies the \s-1VNC\s0 display number to use. The actual \s-1TCP\s0 port number will be \s-1DISPLAYNUM+5900.\s0 .Sp Note: you should not use this option if you set the \s-1DISPLAYNUM\s0 in the \&\fBvnclisten\fR option. .IP "\fBvncunused=BOOLEAN\fR" 4 .IX Item "vncunused=BOOLEAN" Requests that the \s-1VNC\s0 display setup searches for a free \s-1TCP\s0 port to use. The actual display used can be accessed with \fBxl vncviewer\fR. .IP "\fBvncpasswd=PASSWORD\fR" 4 .IX Item "vncpasswd=PASSWORD" Specifies the password for the \s-1VNC\s0 server. If the password is set to an empty string, authentication on the \s-1VNC\s0 server will be disabled, allowing any user to connect. .IP "\fBsdl=BOOLEAN\fR" 4 .IX Item "sdl=BOOLEAN" Specifies that the display should be presented via an X window (using Simple DirectMedia Layer). The default is 0 (not enabled). .IP "\fBdisplay=DISPLAY\fR" 4 .IX Item "display=DISPLAY" Specifies the X Window display that should be used when the \fBsdl\fR option is used. .IP "\fBxauthority=XAUTHORITY\fR" 4 .IX Item "xauthority=XAUTHORITY" Specifies the path to the X authority file that should be used to connect to the X server when the \fBsdl\fR option is used. .IP "\fBopengl=BOOLEAN\fR" 4 .IX Item "opengl=BOOLEAN" Enable OpenGL acceleration of the \s-1SDL\s0 display. Only effects machines using \fBdevice_model_version=\*(L"qemu\-xen\-traditional\*(R"\fR and only if the device-model was compiled with OpenGL support. The default is 0 (disabled). .IP "\fBkeymap=LANG\fR" 4 .IX Item "keymap=LANG" Configure the keymap to use for the keyboard associated with this display. If the input method does not easily support raw keycodes (e.g. this is often the case when using \s-1VNC\s0) then this allows us to correctly map the input keys into keycodes seen by the guest. The specific values which are accepted are defined by the version of the device-model which you are using. See \fBKeymaps\fR below or consult the \&\fB\fBqemu\fB\|(1)\fR manpage. The default is \fBen-us\fR. .RE .RS 4 .RE .ie n .IP "\fBchannel=[ ""\s-1CHANNEL_SPEC_STRING"", ""CHANNEL_SPEC_STRING"", ...\s0]\fR" 4 .el .IP "\fBchannel=[ ``\s-1CHANNEL_SPEC_STRING'', ``CHANNEL_SPEC_STRING'', ...\s0]\fR" 4 .IX Item "channel=[ CHANNEL_SPEC_STRING, CHANNEL_SPEC_STRING, ...]" Specifies the virtual channels to be provided to the guest. A channel is a low-bandwidth, bidirectional byte stream, which resembles a serial link. Typical uses for channels include transmitting \s-1VM\s0 configuration after boot and signalling to in-guest agents. Please see \&\fBxen\-pv\-channel\fR\|(7) for more details. .Sp Each \fB\s-1CHANNEL_SPEC_STRING\s0\fR is a comma-separated list of \f(CW\*(C`KEY=VALUE\*(C'\fR settings. Leading and trailing whitespace is ignored in both \s-1KEY\s0 and \&\s-1VALUE.\s0 Neither \s-1KEY\s0 nor \s-1VALUE\s0 may contain ',', '=' or '"'. Defined values are: .RS 4 .IP "\fBbackend=domain\-id\fR" 4 .IX Item "backend=domain-id" Specifies the backend domain name or id. This parameter is optional. If this parameter is omitted then the toolstack domain will be assumed. .IP "\fBname=NAME\fR" 4 .IX Item "name=NAME" Specifies the name for this device. \fBThis parameter is mandatory!\fR This should be a well-known name for a specific application (e.g. guest agent) and should be used by the frontend to connect the application to the right channel device. There is no formal registry of channel names, so application authors are encouraged to make their names unique by including the domain name and a version number in the string (e.g. org.mydomain.guestagent.1). .IP "\fBconnection=CONNECTION\fR" 4 .IX Item "connection=CONNECTION" Specifies how the backend will be implemented. The following options are available: .RS 4 .IP "\fB\s-1SOCKET\s0\fR" 4 .IX Item "SOCKET" The backend will bind a Unix domain socket (at the path given by \&\fBpath=PATH\fR), listen for and accept connections. The backend will proxy data between the channel and the connected socket. .IP "\fB\s-1PTY\s0\fR" 4 .IX Item "PTY" The backend will create a pty and proxy data between the channel and the master device. The command \fBxl channel-list\fR can be used to discover the assigned slave device. .RE .RS 4 .RE .RE .RS 4 .RE .ie n .IP "\fBrdm=""\s-1RDM_RESERVATION_STRING""\s0\fR" 4 .el .IP "\fBrdm=``\s-1RDM_RESERVATION_STRING''\s0\fR" 4 .IX Item "rdm=RDM_RESERVATION_STRING" \&\fBHVM/x86 only!\fR Specifies information about Reserved Device Memory (\s-1RDM\s0), which is necessary to enable robust device passthrough. One example of \s-1RDM\s0 is reporting through the \s-1ACPI\s0 Reserved Memory Region Reporting (\s-1RMRR\s0) structure on the x86 platform. .Sp \&\fB\s-1RDM_RESERVATION_STRING\s0\fR is a comma separated list of \f(CW\*(C`KEY=VALUE\*(C'\fR settings, from the following list: .RS 4 .IP "\fBstrategy=STRING\fR" 4 .IX Item "strategy=STRING" Currently there is only one valid type, and that is \*(L"host\*(R". .RS 4 .IP "\fBhost\fR" 4 .IX Item "host" If set to \*(L"host\*(R" it means all reserved device memory on this platform should be checked to reserve regions in this \s-1VM\s0's address space. This global \s-1RDM\s0 parameter allows the user to specify reserved regions explicitly, and using \&\*(L"host\*(R" includes all reserved regions reported on this platform, which is useful when doing hotplug. .Sp By default this isn't set so we don't check all RDMs. Instead, we just check the \s-1RDM\s0 specific to a given device if we're assigning this kind of a device. .Sp Note: this option is not recommended unless you can make sure that no conflicts exist. .Sp For example, you're trying to set \*(L"memory = 2800\*(R" to allocate memory to one given \s-1VM\s0 but the platform owns two \s-1RDM\s0 regions like: .Sp Device A [sbdf_A]: \s-1RMRR\s0 region_A: base_addr ac6d3000 end_address ac6e6fff .Sp Device B [sbdf_B]: \s-1RMRR\s0 region_B: base_addr ad800000 end_address afffffff .Sp In this conflict case, .Sp #1. If \fBstrategy\fR is set to \*(L"host\*(R", for example: .Sp rdm = \*(L"strategy=host,policy=strict\*(R" or rdm = \*(L"strategy=host,policy=relaxed\*(R" .Sp it means all conflicts will be handled according to the policy introduced by \fBpolicy\fR as described below. .Sp #2. If \fBstrategy\fR is not set at all, but .Sp pci = [ 'sbdf_A, rdm_policy=xxxxx' ] .Sp it means only one conflict of region_A will be handled according to the policy introduced by \fBrdm_policy=STRING\fR as described inside \fBpci\fR options. .RE .RS 4 .RE .IP "\fBpolicy=STRING\fR" 4 .IX Item "policy=STRING" Specifies how to deal with conflicts when reserving already reserved device memory in the guest address space. .RS 4 .IP "\fBstrict\fR" 4 .IX Item "strict" Specifies that in case of an unresolved conflict the \s-1VM\s0 can't be created, or the associated device can't be attached in the case of hotplug. .IP "\fBrelaxed\fR" 4 .IX Item "relaxed" Specifies that in case of an unresolved conflict the \s-1VM\s0 is allowed to be created but may cause the \s-1VM\s0 to crash if a pass-through device accesses \s-1RDM.\s0 For example, the Windows \s-1IGD GFX\s0 driver always accesses \s-1RDM\s0 regions so it leads to a \s-1VM\s0 crash. .Sp Note: this may be overridden by the \fBrdm_policy\fR option in the \fBpci\fR device configuration. .RE .RS 4 .RE .RE .RS 4 .RE .ie n .IP "\fBusbctrl=[ ""\s-1USBCTRL_SPEC_STRING"", ""USBCTRL_SPEC_STRING"", ...\s0]\fR" 4 .el .IP "\fBusbctrl=[ ``\s-1USBCTRL_SPEC_STRING'', ``USBCTRL_SPEC_STRING'', ...\s0]\fR" 4 .IX Item "usbctrl=[ USBCTRL_SPEC_STRING, USBCTRL_SPEC_STRING, ...]" Specifies the \s-1USB\s0 controllers created for this guest. .Sp Each \fB\s-1USBCTRL_SPEC_STRING\s0\fR is a comma-separated list of \f(CW\*(C`KEY=VALUE\*(C'\fR settings, from the following list: .RS 4 .IP "\fBtype=TYPE\fR" 4 .IX Item "type=TYPE" Specifies the usb controller type. .RS 4 .IP "\fBpv\fR" 4 .IX Item "pv" Specifies a kernel based \s-1PVUSB\s0 backend. .IP "\fBqusb\fR" 4 .IX Item "qusb" Specifies a \s-1QEMU\s0 based \s-1PVUSB\s0 backend. .IP "\fBdevicemodel\fR" 4 .IX Item "devicemodel" Specifies a \s-1USB\s0 controller emulated by \s-1QEMU.\s0 It will show up as a PCI-device in the guest. .IP "\fBauto\fR" 4 .IX Item "auto" Determines whether a kernel based backend is installed. If this is the case, \fBpv\fR is used, otherwise \fBqusb\fR will be used. For \s-1HVM\s0 domains \fBdevicemodel\fR will be selected. .Sp This option is the default. .RE .RS 4 .RE .IP "\fBversion=VERSION\fR" 4 .IX Item "version=VERSION" Specifies the usb controller version. Possible values include 1 (\s-1USB1.1\s0), 2 (\s-1USB2.0\s0) and 3 (\s-1USB3.0\s0). Default is 2 (\s-1USB2.0\s0). Value 3 (\s-1USB3.0\s0) is available for the \fBdevicemodel\fR type only. .IP "\fBports=PORTS\fR" 4 .IX Item "ports=PORTS" Specifies the total number of ports of the usb controller. The maximum number is 31. The default is 8. With the type \fBdevicemodel\fR the number of ports is more limited: a \s-1USB1.1\s0 controller always has 2 ports, a \s-1USB2.0\s0 controller always has 6 ports and a \s-1USB3.0\s0 controller can have up to 15 ports. .Sp \&\s-1USB\s0 controller ids start from 0. In line with the \s-1USB\s0 specification, however, ports on a controller start from 1. .Sp \&\fB\s-1EXAMPLE\s0\fR .RS 4 .Sp .RS 2 usbctrl=[\*(L"version=1,ports=4\*(R", \*(L"version=2,ports=8\*(R"] .Sp The first controller is \s-1USB1.1\s0 and has: .Sp controller id = 0, and ports 1,2,3,4. .Sp The second controller is \s-1USB2.0\s0 and has: .Sp controller id = 1, and ports 1,2,3,4,5,6,7,8. .RE .RE .RS 4 .RE .RE .RS 4 .RE .ie n .IP "\fBusbdev=[ ""\s-1USBDEV_SPEC_STRING"", ""USBDEV_SPEC_STRING"", ...\s0]\fR" 4 .el .IP "\fBusbdev=[ ``\s-1USBDEV_SPEC_STRING'', ``USBDEV_SPEC_STRING'', ...\s0]\fR" 4 .IX Item "usbdev=[ USBDEV_SPEC_STRING, USBDEV_SPEC_STRING, ...]" Specifies the \s-1USB\s0 devices to be attached to the guest at boot. .Sp Each \fB\s-1USBDEV_SPEC_STRING\s0\fR is a comma-separated list of \f(CW\*(C`KEY=VALUE\*(C'\fR settings, from the following list: .RS 4 .IP "\fBtype=hostdev\fR" 4 .IX Item "type=hostdev" Specifies \s-1USB\s0 device type. Currently only \*(L"hostdev\*(R" is supported. .IP "\fBhostbus=busnum\fR" 4 .IX Item "hostbus=busnum" Specifies busnum of the \s-1USB\s0 device from the host perspective. .IP "\fBhostaddr=devnum\fR" 4 .IX Item "hostaddr=devnum" Specifies devnum of the \s-1USB\s0 device from the host perspective. .IP "\fBcontroller=CONTROLLER\fR" 4 .IX Item "controller=CONTROLLER" Specifies the \s-1USB\s0 controller id, to which controller the \s-1USB\s0 device is attached. .Sp If no controller is specified, an available controller:port combination will be used. If there are no available controller:port combinations, a new controller will be created. .IP "\fBport=PORT\fR" 4 .IX Item "port=PORT" Specifies the \s-1USB\s0 port to which the \s-1USB\s0 device is attached. The \fBport\fR option is valid only when the \fBcontroller\fR option is specified. .RE .RS 4 .RE .ie n .IP "\fBpci=[ ""\s-1PCI_SPEC_STRING"", ""PCI_SPEC_STRING"", ...\s0]\fR" 4 .el .IP "\fBpci=[ ``\s-1PCI_SPEC_STRING'', ``PCI_SPEC_STRING'', ...\s0]\fR" 4 .IX Item "pci=[ PCI_SPEC_STRING, PCI_SPEC_STRING, ...]" Specifies the host \s-1PCI\s0 devices to passthrough to this guest. Each \fB\s-1PCI_SPEC_STRING\s0\fR has the form of \&\fB[\s-1DDDD:\s0]BB:DD.F[@VSLOT],KEY=VALUE,KEY=VALUE,...\fR where: .RS 4 .IP "\fB[\s-1DDDD:\s0]BB:DD.F\fR" 4 .IX Item "[DDDD:]BB:DD.F" Identifies the \s-1PCI\s0 device from the host perspective in the domain (\fB\s-1DDDD\s0\fR), Bus (\fB\s-1BB\s0\fR), Device (\fB\s-1DD\s0\fR) and Function (\fBF\fR) syntax. This is the same scheme as used in the output of \fB\fBlspci\fB\|(1)\fR for the device in question. .Sp Note: by default \fB\fBlspci\fB\|(1)\fR will omit the domain (\fB\s-1DDDD\s0\fR) if it is zero and it is optional here also. You may specify the function (\fBF\fR) as \fB*\fR to indicate all functions. .IP "\fB\f(CB@VSLOT\fB\fR" 4 .IX Item "@VSLOT" Specifies the virtual slot where the guest will see this device. This is equivalent to the \fB\s-1DD\s0\fR which the guest sees. In a guest \fB\s-1DDDD\s0\fR and \fB\s-1BB\s0\fR are \f(CW\*(C`0000:00\*(C'\fR. .IP "\fBpermissive=BOOLEAN\fR" 4 .IX Item "permissive=BOOLEAN" By default pciback only allows \s-1PV\s0 guests to write \*(L"known safe\*(R" values into \s-1PCI\s0 configuration space, likewise \s-1QEMU\s0 (both qemu-xen and qemu-xen-traditional) imposes the same constraint on \s-1HVM\s0 guests. However, many devices require writes to other areas of the configuration space in order to operate properly. This option tells the backend (pciback or \s-1QEMU\s0) to allow all writes to the \s-1PCI\s0 configuration space of this device by this domain. .Sp \&\fBThis option should be enabled with caution:\fR it gives the guest much more control over the device, which may have security or stability implications. It is recommended to only enable this option for trusted VMs under administrator's control. .IP "\fBmsitranslate=BOOLEAN\fR" 4 .IX Item "msitranslate=BOOLEAN" Specifies that MSI-INTx translation should be turned on for the \s-1PCI\s0 device. When enabled, MSI-INTx translation will always enable \s-1MSI\s0 on the \s-1PCI\s0 device regardless of whether the guest uses INTx or \s-1MSI.\s0 Some device drivers, such as \s-1NVIDIA\s0's, detect an inconsistency and do not function when this option is enabled. Therefore the default is false (0). .IP "\fBseize=BOOLEAN\fR" 4 .IX Item "seize=BOOLEAN" Tells \fBxl\fR to automatically attempt to re-assign a device to pciback if it is not already assigned. .Sp \&\fB\s-1WARNING:\s0\fR If you set this option, \fBxl\fR will gladly re-assign a critical system device, such as a network or a disk controller being used by dom0 without confirmation. Please use with care. .IP "\fBpower_mgmt=BOOLEAN\fR" 4 .IX Item "power_mgmt=BOOLEAN" \&\fB(\s-1HVM\s0 only)\fR Specifies that the \s-1VM\s0 should be able to program the D0\-D3hot power management states for the \s-1PCI\s0 device. The default is false (0). .IP "\fBrdm_policy=STRING\fR" 4 .IX Item "rdm_policy=STRING" \&\fB(HVM/x86 only)\fR This is the same as the policy setting inside the \fBrdm\fR option but just specific to a given device. The default is \*(L"relaxed\*(R". .Sp Note: this would override global \fBrdm\fR option. .RE .RS 4 .RE .IP "\fBpci_permissive=BOOLEAN\fR" 4 .IX Item "pci_permissive=BOOLEAN" Changes the default value of \fBpermissive\fR for all \s-1PCI\s0 devices passed through to this \s-1VM.\s0 See \fBpermissive\fR above. .IP "\fBpci_msitranslate=BOOLEAN\fR" 4 .IX Item "pci_msitranslate=BOOLEAN" Changes the default value of \fBmsitranslate\fR for all \s-1PCI\s0 devices passed through to this \s-1VM.\s0 See \fBmsitranslate\fR above. .IP "\fBpci_seize=BOOLEAN\fR" 4 .IX Item "pci_seize=BOOLEAN" Changes the default value of \fBseize\fR for all \s-1PCI\s0 devices passed through to this \s-1VM.\s0 See \fBseize\fR above. .IP "\fBpci_power_mgmt=BOOLEAN\fR" 4 .IX Item "pci_power_mgmt=BOOLEAN" \&\fB(\s-1HVM\s0 only)\fR Changes the default value of \fBpower_mgmt\fR for all \s-1PCI\s0 devices passed through to this \s-1VM.\s0 See \fBpower_mgmt\fR above. .ie n .IP "\fBgfx_passthru=BOOLEAN|""\s-1STRING""\s0\fR" 4 .el .IP "\fBgfx_passthru=BOOLEAN|``\s-1STRING''\s0\fR" 4 .IX Item "gfx_passthru=BOOLEAN|STRING" Enable graphics device \s-1PCI\s0 passthrough. This option makes an assigned \&\s-1PCI\s0 graphics card become the primary graphics card in the \s-1VM.\s0 The \s-1QEMU\s0 emulated graphics adapter is disabled and the \s-1VNC\s0 console for the \s-1VM\s0 will not have any graphics output. All graphics output, including boot time \s-1QEMU BIOS\s0 messages from the \s-1VM,\s0 will go to the physical outputs of the passed through physical graphics card. .Sp The graphics card \s-1PCI\s0 device to pass through is chosen with the \fBpci\fR option, in exactly the same way a normal Xen \s-1PCI\s0 device passthrough/assignment is done. Note that \fBgfx_passthru\fR does not do any kind of sharing of the \s-1GPU,\s0 so you can assign the \s-1GPU\s0 to only one single \s-1VM\s0 at a time. .Sp \&\fBgfx_passthru\fR also enables various legacy \s-1VGA\s0 memory ranges, BARs, MMIOs, and ioports to be passed through to the \s-1VM,\s0 since those are required for correct operation of things like \s-1VGA BIOS,\s0 text mode, \s-1VBE,\s0 etc. .Sp Enabling the \fBgfx_passthru\fR option also copies the physical graphics card video \s-1BIOS\s0 to the guest memory, and executes the \s-1VBIOS\s0 in the guest to initialize the graphics card. .Sp Most graphics adapters require vendor specific tweaks for properly working graphics passthrough. See the XenVGAPassthroughTestedAdapters wiki page for graphics cards currently supported by \fBgfx_passthru\fR. .Sp \&\fBgfx_passthru\fR is currently supported both with the qemu-xen-traditional device-model and upstream qemu-xen device-model. .Sp When given as a boolean the \fBgfx_passthru\fR option either disables graphics card passthrough or enables autodetection. .Sp When given as a string the \fBgfx_passthru\fR option describes the type of device to enable. Note that this behavior is only supported with the upstream qemu-xen device-model. With qemu-xen-traditional \s-1IGD\s0 (Intel Graphics Device) is always assumed and options other than autodetect or explicit \s-1IGD\s0 will result in an error. .Sp Currently, valid values for the option are: .RS 4 .IP "\fB0\fR" 4 .IX Item "0" Disables graphics device \s-1PCI\s0 passthrough. .ie n .IP "\fB1\fR, \fB""default""\fR" 4 .el .IP "\fB1\fR, \fB``default''\fR" 4 .IX Item "1, default" Enables graphics device \s-1PCI\s0 passthrough and autodetects the type of device which is being used. .ie n .IP "\fB""igd""\fR" 4 .el .IP "\fB``igd''\fR" 4 .IX Item "igd" Enables graphics device \s-1PCI\s0 passthrough but forcing the type of device to Intel Graphics Device. .RE .RS 4 .Sp Note that some graphics cards (\s-1AMD/ATI\s0 cards, for example) do not necessarily require the \fBgfx_passthru\fR option, so you can use the normal Xen \&\s-1PCI\s0 passthrough to assign the graphics card as a secondary graphics card to the \s-1VM.\s0 The QEMU-emulated graphics card remains the primary graphics card, and \s-1VNC\s0 output is available from the QEMU-emulated primary adapter. .Sp More information about the Xen \fBgfx_passthru\fR feature is available on the XenVGAPassthrough wiki page. .RE .IP "\fBrdm_mem_boundary=MBYTES\fR" 4 .IX Item "rdm_mem_boundary=MBYTES" Number of megabytes to set for a boundary when checking for \s-1RDM\s0 conflicts. .Sp When \s-1RDM\s0 conflicts with \s-1RAM, RDM\s0 is probably scattered over the whole \s-1RAM\s0 space. Having multiple \s-1RDM\s0 entries would worsen this and lead to a complicated memory layout. Here we're trying to figure out a simple solution to avoid breaking the existing layout. When a conflict occurs, .Sp .Vb 2 \& #1. Above a predefined boundary \& \- move lowmem_end below the reserved region to solve the conflict; \& \& #2. Below a predefined boundary \& \- Check if the policy is strict or relaxed. \& A "strict" policy leads to a fail in libxl. \& Note that when both policies are specified on a given region, \& "strict" is always preferred. \& The "relaxed" policy issues a warning message and also masks this \& entry INVALID to indicate we shouldn\*(Aqt expose this entry to \& hvmloader. .Ve .Sp The default value is 2048. .ie n .IP "\fBdtdev=[ ""\s-1DTDEV_PATH"", ""DTDEV_PATH"", ...\s0]\fR" 4 .el .IP "\fBdtdev=[ ``\s-1DTDEV_PATH'', ``DTDEV_PATH'', ...\s0]\fR" 4 .IX Item "dtdev=[ DTDEV_PATH, DTDEV_PATH, ...]" Specifies the host device tree nodes to passt hrough to this guest. Each \&\s-1DTDEV_PATH\s0 is an absolute path in the device tree. .ie n .IP "\fBioports=[ ""\s-1IOPORT_RANGE"", ""IOPORT_RANGE"", ...\s0]\fR" 4 .el .IP "\fBioports=[ ``\s-1IOPORT_RANGE'', ``IOPORT_RANGE'', ...\s0]\fR" 4 .IX Item "ioports=[ IOPORT_RANGE, IOPORT_RANGE, ...]" Allow the guest to access specific legacy I/O ports. Each \fB\s-1IOPORT_RANGE\s0\fR is given in hexadecimal format and may either be a range, e.g. \f(CW\*(C`2f8\-2ff\*(C'\fR (inclusive), or a single I/O port, e.g. \f(CW\*(C`2f8\*(C'\fR. .Sp It is recommended to only use this option for trusted VMs under administrator's control. .ie n .IP "\fBiomem=[ ""\s-1IOMEM_START\s0,NUM_PAGES[@GFN]"", ""\s-1IOMEM_START\s0,NUM_PAGES[@GFN]"", ...]\fR" 4 .el .IP "\fBiomem=[ ``\s-1IOMEM_START\s0,NUM_PAGES[@GFN]'', ``\s-1IOMEM_START\s0,NUM_PAGES[@GFN]'', ...]\fR" 4 .IX Item "iomem=[ IOMEM_START,NUM_PAGES[@GFN], IOMEM_START,NUM_PAGES[@GFN], ...]" Allow auto-translated domains to access specific hardware I/O memory pages. .Sp \&\fB\s-1IOMEM_START\s0\fR is a physical page number. \fB\s-1NUM_PAGES\s0\fR is the number of pages, beginning with \fB\s-1START_PAGE\s0\fR, to allow access to. \fB\s-1GFN\s0\fR specifies the guest frame number where the mapping will start in the guest's address space. If \&\fB\s-1GFN\s0\fR is not specified, the mapping will be performed using \fB\s-1IOMEM_START\s0\fR as a start in the guest's address space, therefore performing a 1:1 mapping by default. All of these values must be given in hexadecimal format. .Sp Note that the \s-1IOMMU\s0 won't be updated with the mappings specified with this option. This option therefore should not be used to pass through any IOMMU-protected devices. .Sp It is recommended to only use this option for trusted VMs under administrator's control. .IP "\fBirqs=[ \s-1NUMBER, NUMBER, ...\s0]\fR" 4 .IX Item "irqs=[ NUMBER, NUMBER, ...]" Allow a guest to access specific physical IRQs. .Sp It is recommended to only use this option for trusted VMs under administrator's control. .Sp If vuart console is enabled then irq 32 is reserved for it. See \&\*(L"vuart=\*(R"uart"" to know how to enable vuart console. .IP "\fBmax_event_channels=N\fR" 4 .IX Item "max_event_channels=N" Limit the guest to using at most N event channels (\s-1PV\s0 interrupts). Guests use hypervisor resources for each event channel they use. .Sp The default of 1023 should be sufficient for typical guests. The maximum value depends on what the guest supports. Guests supporting the FIFO-based event channel \s-1ABI\s0 support up to 131,071 event channels. Other guests are limited to 4095 (64\-bit x86 and \s-1ARM\s0) or 1023 (32\-bit x86). .ie n .IP "\fBvdispl=[ ""\s-1VDISPL_SPEC_STRING"", ""VDISPL_SPEC_STRING"", ...\s0]\fR" 4 .el .IP "\fBvdispl=[ ``\s-1VDISPL_SPEC_STRING'', ``VDISPL_SPEC_STRING'', ...\s0]\fR" 4 .IX Item "vdispl=[ VDISPL_SPEC_STRING, VDISPL_SPEC_STRING, ...]" Specifies the virtual display devices to be provided to the guest. .Sp Each \fB\s-1VDISPL_SPEC_STRING\s0\fR is a comma-separated list of \f(CW\*(C`KEY=VALUE\*(C'\fR settings, from the following list: .RS 4 .ie n .IP """backend=DOMAIN""" 4 .el .IP "\f(CWbackend=DOMAIN\fR" 4 .IX Item "backend=DOMAIN" Specifies the backend domain name or id. If not specified Domain\-0 is used. .ie n .IP """be\-alloc=BOOLEAN""" 4 .el .IP "\f(CWbe\-alloc=BOOLEAN\fR" 4 .IX Item "be-alloc=BOOLEAN" Indicates if backend can be a buffer provider/allocator for this domain. See display protocol for details. .ie n .IP """connectors=CONNECTORS""" 4 .el .IP "\f(CWconnectors=CONNECTORS\fR" 4 .IX Item "connectors=CONNECTORS" Specifies virtual connectors for the device in following format :x;:x... where: .RS 4 .ie n .IP """id""" 4 .el .IP "\f(CWid\fR" 4 .IX Item "id" String connector \s-1ID.\s0 Space, comma symbols are not allowed. .ie n .IP """W""" 4 .el .IP "\f(CWW\fR" 4 .IX Item "W" Connector width in pixels. .ie n .IP """H""" 4 .el .IP "\f(CWH\fR" 4 .IX Item "H" Connector height in pixels. .RE .RS 4 .Sp \&\fB\s-1EXAMPLE\s0\fR .Sp .RS 4 connectors=id0:1920x1080;id1:800x600;id2:640x480 .RE .RE .RS 4 .RE .RE .RS 4 .RE .IP "\fBdm_restrict=BOOLEAN\fR" 4 .IX Item "dm_restrict=BOOLEAN" Restrict the device model after startup, to limit the consequencese of security vulnerabilities in qemu. .Sp With this feature enabled, a compromise of the device model, via such a vulnerability, will not provide a privilege escalation attack on the whole system. .Sp This feature is a \fBtechnology preview\fR. There are some significant limitations: .RS 4 .IP "\(bu" 4 This is not likely to work at all for \s-1PV\s0 guests nor guests using qdisk backends for their block devices. .IP "\(bu" 4 You must have a new enough qemu. In particular, if your qemu does not have the commit \&\fBxen: restrict: use xentoolcore_restrict_all\fR the restriction request will be silently ineffective! .IP "\(bu" 4 The mechanisms used are not effective against denial of service problems. A compromised qemu can probably still impair or perhaps even prevent the proper functioning of the whole system, (at the very least, but not limited to, through resource exhaustion). .IP "\(bu" 4 It is not known whether the protection is effective when a domain is migrated. .IP "\(bu" 4 Some domain management functions do not work. For example, cdrom insert will fail. .IP "\(bu" 4 You should say \f(CW\*(C`vga="none"\*(C'\fR. Domains with stdvga graphics cards to not work. Domains with cirrus vga may seem to work. .IP "\(bu" 4 You must create user(s) for qemu to run as. .Sp Ideally, set aside a range of 32752 uids (from N to N+32751) and create a user whose name is \fBxen-qemuuser-range-base\fR and whose uid is N and whose gid is a plain unprivileged gid. libxl will use one such user for each domid. .Sp Alternatively, either create \&\fBxen\-qemuuser\-domid$domid\fR for every \f(CW$domid\fR from 1 to 32751 inclusive, or \&\fBxen-qemuuser-shared\fR (in which case different guests will not be protected against each other). .IP "\(bu" 4 There are no countermeasures taken against reuse of the same unix user (uid) for subsequent domains, even if the \fBxen\-qemuuser\-domid$domid\fR users are created. So a past domain with the same domid may be able to interferer with future domains. Possibly, even after a reboot. .IP "\(bu" 4 A compromised qemu will be able to read world-readable files in the dom0 operating system. .IP "\(bu" 4 Because of these limitations, this functionality, while it may enhance your security, should not be relied on. Any further limitations discovered in the current version will \fBnot\fR be handled via the Xen Project Security Process. .IP "\(bu" 4 In the future as we enhance this feature to improve the security, we may break backward compatibility. .RE .RS 4 .RE .SS "Paravirtualised (\s-1PV\s0) Guest Specific Options" .IX Subsection "Paravirtualised (PV) Guest Specific Options" The following options apply only to Paravirtual (\s-1PV\s0) guests. .ie n .IP "\fBbootloader=""\s-1PROGRAM""\s0\fR" 4 .el .IP "\fBbootloader=``\s-1PROGRAM''\s0\fR" 4 .IX Item "bootloader=PROGRAM" Run \f(CW\*(C`PROGRAM\*(C'\fR to find the kernel image and ramdisk to use. Normally \&\f(CW\*(C`PROGRAM\*(C'\fR would be \f(CW\*(C`pygrub\*(C'\fR, which is an emulation of grub/grub2/syslinux. Either \fBkernel\fR or \fBbootloader\fR must be specified for \s-1PV\s0 guests. .ie n .IP "\fBbootloader_args=[ ""\s-1ARG"", ""ARG"", ...\s0]\fR" 4 .el .IP "\fBbootloader_args=[ ``\s-1ARG'', ``ARG'', ...\s0]\fR" 4 .IX Item "bootloader_args=[ ARG, ARG, ...]" Append \fB\s-1ARG\s0\fRs to the arguments to the \fBbootloader\fR program. Alternatively if the argument is a simple string then it will be split into words at whitespace \fB(this second option is deprecated)\fR. .IP "\fBe820_host=BOOLEAN\fR" 4 .IX Item "e820_host=BOOLEAN" Selects whether to expose the host e820 (memory map) to the guest via the virtual e820. When this option is false (0) the guest pseudo-physical address space consists of a single contiguous \s-1RAM\s0 region. When this option is specified the virtual e820 instead reflects the host e820 and contains the same \s-1PCI\s0 holes. The total amount of \s-1RAM\s0 represented by the memory map is always the same, this option configures only how it is laid out. .Sp Exposing the host e820 to the guest gives the guest kernel the opportunity to set aside the required part of its pseudo-physical address space in order to provide address space to map passedthrough \&\s-1PCI\s0 devices. It is guest Operating System dependent whether this option is required, specifically it is required when using a mainline Linux (\*(L"pvops\*(R") kernel. This option defaults to true (1) if any \s-1PCI\s0 passthrough devices are configured and false (0) otherwise. If you do not configure any passthrough devices at domain creation time but expect to hotplug devices later then you should set this option. Conversely if your particular guest kernel does not require this behaviour then it is safe to allow this to be enabled but you may wish to disable it anyway. .SS "Fully-virtualised (\s-1HVM\s0) Guest Specific Options" .IX Subsection "Fully-virtualised (HVM) Guest Specific Options" The following options apply only to Fully-virtualised (\s-1HVM\s0) guests. .PP \fIBoot Device\fR .IX Subsection "Boot Device" .ie n .IP "\fBboot=""\s-1STRING""\s0\fR" 4 .el .IP "\fBboot=``\s-1STRING''\s0\fR" 4 .IX Item "boot=STRING" Specifies the emulated virtual device to boot from. .Sp Possible values are: .RS 4 .IP "\fBc\fR" 4 .IX Item "c" Hard disk. .IP "\fBd\fR" 4 .IX Item "d" CD-ROM. .IP "\fBn\fR" 4 .IX Item "n" Network / \s-1PXE.\s0 .RE .RS 4 .Sp \&\fBNote:\fR multiple options can be given and will be attempted in the order they are given, e.g. to boot from CD-ROM but fall back to the hard disk you can specify it as \fBdc\fR. .Sp The default is \fBcd\fR, meaning try booting from the hard disk first, but fall back to the CD-ROM. .RE .PP \fIEmulated disk controller type\fR .IX Subsection "Emulated disk controller type" .IP "\fBhdtype=STRING\fR" 4 .IX Item "hdtype=STRING" Specifies the hard disk type. .Sp Possible values are: .RS 4 .IP "\fBide\fR" 4 .IX Item "ide" If thise mode is specified \fBxl\fR adds an emulated \s-1IDE\s0 controller, which is suitable even for older operation systems. .IP "\fBahci\fR" 4 .IX Item "ahci" If this mode is specified, \fBxl\fR adds an ich9 disk controller in \s-1AHCI\s0 mode and uses it with upstream \s-1QEMU\s0 to emulate disks instead of \s-1IDE.\s0 It decreases boot time but may not be supported by default in older operating systems, e.g. Windows \s-1XP.\s0 .RE .RS 4 .Sp The default is \fBide\fR. .RE .PP \fIPaging\fR .IX Subsection "Paging" .PP The following options control the mechanisms used to virtualise guest memory. The defaults are selected to give the best results for the common cases so you should normally leave these options unspecified. .IP "\fBhap=BOOLEAN\fR" 4 .IX Item "hap=BOOLEAN" Turns \*(L"hardware assisted paging\*(R" (the use of the hardware nested page table feature) on or off. This feature is called \s-1EPT\s0 (Extended Page Tables) by Intel and \s-1NPT\s0 (Nested Page Tables) or \s-1RVI\s0 (Rapid Virtualisation Indexing) by \s-1AMD.\s0 If turned off, Xen will run the guest in \*(L"shadow page table\*(R" mode where the guest's page table updates and/or \s-1TLB\s0 flushes etc. will be emulated. Use of \s-1HAP\s0 is the default when available. .IP "\fBoos=BOOLEAN\fR" 4 .IX Item "oos=BOOLEAN" Turns \*(L"out of sync pagetables\*(R" on or off. When running in shadow page table mode, the guest's page table updates may be deferred as specified in the Intel/AMD architecture manuals. However, this may expose unexpected bugs in the guest, or find bugs in Xen, so it is possible to disable this feature. Use of out of sync page tables, when Xen thinks it appropriate, is the default. .IP "\fBshadow_memory=MBYTES\fR" 4 .IX Item "shadow_memory=MBYTES" Number of megabytes to set aside for shadowing guest pagetable pages (effectively acting as a cache of translated pages) or to use for \s-1HAP\s0 state. By default this is 1MB per guest vCPU plus 8KB per \s-1MB\s0 of guest \&\s-1RAM.\s0 You should not normally need to adjust this value. However, if you are not using hardware assisted paging (i.e. you are using shadow mode) and your guest workload consists of a very large number of similar processes then increasing this value may improve performance. .PP \fIProcessor and Platform Features\fR .IX Subsection "Processor and Platform Features" .PP The following options allow various processor and platform level features to be hidden or exposed from the guest's point of view. This can be useful when running older guest Operating Systems which may misbehave when faced with more modern features. In general, you should accept the defaults for these options wherever possible. .ie n .IP "\fBbios=""\s-1STRING""\s0\fR" 4 .el .IP "\fBbios=``\s-1STRING''\s0\fR" 4 .IX Item "bios=STRING" Select the virtual firmware that is exposed to the guest. By default, a guess is made based on the device model, but sometimes it may be useful to request a different one, like \s-1UEFI.\s0 .RS 4 .IP "\fBrombios\fR" 4 .IX Item "rombios" Loads \s-1ROMBIOS,\s0 a 16\-bit x86 compatible \s-1BIOS.\s0 This is used by default when \fBdevice_model_version=qemu\-xen\-traditional\fR. This is the only \s-1BIOS\s0 option supported when \fBdevice_model_version=qemu\-xen\-traditional\fR. This is the \s-1BIOS\s0 used by all previous Xen versions. .IP "\fBseabios\fR" 4 .IX Item "seabios" Loads SeaBIOS, a 16\-bit x86 compatible \s-1BIOS.\s0 This is used by default with device_model_version=qemu\-xen. .IP "\fBovmf\fR" 4 .IX Item "ovmf" Loads \s-1OVMF,\s0 a standard \s-1UEFI\s0 firmware by Tianocore project. Requires device_model_version=qemu\-xen. .RE .RS 4 .RE .ie n .IP "\fBbios_path_override=""\s-1PATH""\s0\fR" 4 .el .IP "\fBbios_path_override=``\s-1PATH''\s0\fR" 4 .IX Item "bios_path_override=PATH" Override the path to the blob to be used as \s-1BIOS.\s0 The blob provided here \s-1MUST\s0 be consistent with the \fBbios=\fR which you have specified. You should not normally need to specify this option. .Sp This option does not have any effect if using \fBbios=\*(L"rombios\*(R"\fR or \&\fBdevice_model_version=\*(L"qemu\-xen\-traditional\*(R"\fR. .IP "\fBpae=BOOLEAN\fR" 4 .IX Item "pae=BOOLEAN" Hide or expose the \s-1IA32\s0 Physical Address Extensions. These extensions make it possible for a 32 bit guest Operating System to access more than 4GB of \s-1RAM.\s0 Enabling \s-1PAE\s0 also enabled other features such as \&\s-1NX. PAE\s0 is required if you wish to run a 64\-bit guest Operating System. In general, you should leave this enabled and allow the guest Operating System to choose whether or not to use \s-1PAE.\s0 (X86 only) .IP "\fBacpi=BOOLEAN\fR" 4 .IX Item "acpi=BOOLEAN" Expose \s-1ACPI\s0 (Advanced Configuration and Power Interface) tables from the virtual firmware to the guest Operating System. \s-1ACPI\s0 is required by most modern guest Operating Systems. This option is enabled by default and usually you should omit it. However, it may be necessary to disable \s-1ACPI\s0 for compatibility with some guest Operating Systems. This option is true for x86 while it's false for \s-1ARM\s0 by default. .IP "\fBacpi_s3=BOOLEAN\fR" 4 .IX Item "acpi_s3=BOOLEAN" Include the S3 (suspend-to-ram) power state in the virtual firmware \&\s-1ACPI\s0 table. True (1) by default. .IP "\fBacpi_s4=BOOLEAN\fR" 4 .IX Item "acpi_s4=BOOLEAN" Include S4 (suspend-to-disk) power state in the virtual firmware \s-1ACPI\s0 table. True (1) by default. .IP "\fBacpi_laptop_slate=BOOLEAN\fR" 4 .IX Item "acpi_laptop_slate=BOOLEAN" Include the Windows laptop/slate mode switch device in the virtual firmware \s-1ACPI\s0 table. False (0) by default. .IP "\fBapic=BOOLEAN\fR" 4 .IX Item "apic=BOOLEAN" \&\fB(x86 only)\fR Include information regarding \s-1APIC\s0 (Advanced Programmable Interrupt Controller) in the firmware/BIOS tables on a single processor guest. This causes the \s-1MP\s0 (multiprocessor) and \s-1PIR\s0 (\s-1PCI\s0 Interrupt Routing) tables to be exported by the virtual firmware. This option has no effect on a guest with multiple virtual CPUs as they must always include these tables. This option is enabled by default and you should usually omit it but it may be necessary to disable these firmware tables when using certain older guest Operating Systems. These tables have been superseded by newer constructs within the \s-1ACPI\s0 tables. .IP "\fBnx=BOOLEAN\fR" 4 .IX Item "nx=BOOLEAN" \&\fB(x86 only)\fR Hides or exposes the No-eXecute capability. This allows a guest Operating System to map pages in such a way that they cannot be executed which can enhance security. This options requires that \s-1PAE\s0 also be enabled. .IP "\fBhpet=BOOLEAN\fR" 4 .IX Item "hpet=BOOLEAN" \&\fB(x86 only)\fR Enables or disables \s-1HPET\s0 (High Precision Event Timer). This option is enabled by default and you should usually omit it. It may be necessary to disable the \s-1HPET\s0 in order to improve compatibility with guest Operating Systems. .ie n .IP "\fBaltp2m=""\s-1MODE""\s0\fR" 4 .el .IP "\fBaltp2m=``\s-1MODE''\s0\fR" 4 .IX Item "altp2m=MODE" \&\fB(x86 only)\fR Specifies the access mode to the alternate\-p2m capability. Alternate\-p2m allows a guest to manage multiple p2m guest physical \*(L"memory views\*(R" (as opposed to a single p2m). You may want this option if you want to access\-control/isolate access to specific guest physical memory pages accessed by the guest, e.g. for domain memory introspection or for isolation/access\-control of memory between components within a single guest domain. This option is disabled by default. .Sp The valid values are as follows: .RS 4 .IP "\fBdisabled\fR" 4 .IX Item "disabled" Altp2m is disabled for the domain (default). .IP "\fBmixed\fR" 4 .IX Item "mixed" The mixed mode allows access to the altp2m interface for both in-guest and external tools as well. .IP "\fBexternal\fR" 4 .IX Item "external" Enables access to the alternate\-p2m capability by external privileged tools. .IP "\fBlimited\fR" 4 .IX Item "limited" Enables limited access to the alternate\-p2m capability, ie. giving the guest access only to enable/disable the \s-1VMFUNC\s0 and #VE features. .RE .RS 4 .RE .IP "\fBaltp2mhvm=BOOLEAN\fR" 4 .IX Item "altp2mhvm=BOOLEAN" Enables or disables \s-1HVM\s0 guest access to alternate\-p2m capability. Alternate\-p2m allows a guest to manage multiple p2m guest physical \&\*(L"memory views\*(R" (as opposed to a single p2m). This option is disabled by default and is available only to \s-1HVM\s0 domains. You may want this option if you want to access\-control/isolate access to specific guest physical memory pages accessed by the guest, e.g. for \s-1HVM\s0 domain memory introspection or for isolation/access\-control of memory between components within a single guest \s-1HVM\s0 domain. \fBThis option is deprecated, use the option \&\*(L"altp2m\*(R" instead.\fR .Sp \&\fBNote\fR: While the option \*(L"altp2mhvm\*(R" is deprecated, legacy applications for x86 systems will continue to work using it. .IP "\fBnestedhvm=BOOLEAN\fR" 4 .IX Item "nestedhvm=BOOLEAN" Enable or disables guest access to hardware virtualisation features, e.g. it allows a guest Operating System to also function as a hypervisor. You may want this option if you want to run another hypervisor (including another copy of Xen) within a Xen guest or to support a guest Operating System which uses hardware virtualisation extensions (e.g. Windows \s-1XP\s0 compatibility mode on more modern Windows \s-1OS\s0). This option is disabled by default. .ie n .IP "\fBcpuid=""\s-1LIBXL_STRING""\s0\fR or \fBcpuid=[ ""\s-1XEND_STRING"", ""XEND_STRING""\s0 ]\fR" 4 .el .IP "\fBcpuid=``\s-1LIBXL_STRING''\s0\fR or \fBcpuid=[ ``\s-1XEND_STRING'', ``XEND_STRING''\s0 ]\fR" 4 .IX Item "cpuid=LIBXL_STRING or cpuid=[ XEND_STRING, XEND_STRING ]" Configure the value returned when a guest executes the \s-1CPUID\s0 instruction. Two versions of config syntax are recognized: libxl and xend. .Sp The libxl syntax is a comma separated list of key=value pairs, preceded by the word \*(L"host\*(R". A few keys take a numerical value, all others take a single character which describes what to do with the feature bit. .Sp Possible values for a single feature bit: '1' \-> force the corresponding bit to 1 '0' \-> force to 0 'x' \-> Get a safe value (pass through and mask with the default policy) 'k' \-> pass through the host bit value 's' \-> as 'k' but preserve across save/restore and migration (not implemented) .Sp Note: when specifying \fBcpuid\fR for hypervisor leaves (0x4000xxxx major group) only the lowest 8 bits of leaf's 0x4000xx00 \s-1EAX\s0 register are processed, the rest are ignored (these 8 bits signify maximum number of hypervisor leaves). .Sp List of keys taking a value: apicidsize brandid clflush family localapicid maxleaf maxhvleaf model nc proccount procpkg stepping .Sp List of keys taking a character: 3dnow 3dnowext 3dnowprefetch abm acpi adx aes altmovcr8 apic arat avx avx2 avx512\-4fmaps avx512\-4vnniw avx512bw avx512cd avx512dq avx512er avx512f avx512ifma avx512pf avx512vbmi avx512vl bmi1 bmi2 clflushopt clfsh clwb cmov cmplegacy cmpxchg16 cmpxchg8 cmt cntxid dca de ds dscpl dtes64 erms est extapic f16c ffxsr fma fma4 fpu fsgsbase fxsr hle htt hypervisor ia64 ibs invpcid invtsc lahfsahf lm lwp mca mce misalignsse mmx mmxext monitor movbe mpx msr mtrr nodeid nx ospke osvw osxsave pae page1gb pat pbe pcid pclmulqdq pdcm perfctr_core perfctr_nb pge pku popcnt pse pse36 psn rdrand rdseed rdtscp rtm sha skinit smap smep smx ss sse sse2 sse3 sse4.1 sse4.2 sse4_1 sse4_2 sse4a ssse3 svm svm_decode svm_lbrv svm_npt svm_nrips svm_pausefilt svm_tscrate svm_vmcbclean syscall sysenter tbm tm tm2 topoext tsc tsc-deadline tsc_adjust umip vme vmx wdt x2apic xop xsave xtpr .Sp The xend syntax is a list of values in the form of \&'leafnum:register=bitstring,register=bitstring' \*(L"leafnum\*(R" is the requested function, \*(L"register\*(R" is the response register to modify \*(L"bitstring\*(R" represents all bits in the register, its length must be 32 chars. Each successive character represent a lesser-significant bit, possible values are listed above in the libxl section. .Sp Example to hide two features from the guest: 'tm', which is bit #29 in \s-1EDX,\s0 and \&'pni' (\s-1SSE3\s0), which is bit #0 in \s-1ECX:\s0 .Sp xend: [ \*(L"1:ecx=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx0,edx=xx0xxxxxxxxxxxxxxxxxxxxxxxxxxxxx\*(R" ] .Sp libxl: \*(L"host,tm=0,sse3=0\*(R" .Sp More info about the \s-1CPUID\s0 instruction can be found in the processor manuals, and on Wikipedia: .ie n .IP "\fBacpi_firmware=""\s-1STRING""\s0\fR" 4 .el .IP "\fBacpi_firmware=``\s-1STRING''\s0\fR" 4 .IX Item "acpi_firmware=STRING" Specifies a path to a file that contains extra \s-1ACPI\s0 firmware tables to pass into a guest. The file can contain several tables in their binary \s-1AML\s0 form concatenated together. Each table self describes its length so no additional information is needed. These tables will be added to the \s-1ACPI\s0 table set in the guest. Note that existing tables cannot be overridden by this feature. For example, this cannot be used to override tables like \s-1DSDT, FADT,\s0 etc. .ie n .IP "\fBsmbios_firmware=""\s-1STRING""\s0\fR" 4 .el .IP "\fBsmbios_firmware=``\s-1STRING''\s0\fR" 4 .IX Item "smbios_firmware=STRING" Specifies a path to a file that contains extra \s-1SMBIOS\s0 firmware structures to pass into a guest. The file can contain a set of \s-1DMTF\s0 predefined structures which will override the internal defaults. Not all predefined structures can be overridden, only the following types: 0, 1, 2, 3, 11, 22, 39. The file can also contain any number of vendor defined \s-1SMBIOS\s0 structures (type 128 \- 255). Since \s-1SMBIOS\s0 structures do not present their overall size, each entry in the file must be preceded by a 32b integer indicating the size of the following structure. .ie n .IP "\fBms_vm_genid=""\s-1OPTION""\s0\fR" 4 .el .IP "\fBms_vm_genid=``\s-1OPTION''\s0\fR" 4 .IX Item "ms_vm_genid=OPTION" Provide a \s-1VM\s0 generation \s-1ID\s0 to the guest. .Sp The \s-1VM\s0 generation \s-1ID\s0 is a 128\-bit random number that a guest may use to determine if the guest has been restored from an earlier snapshot or cloned. .Sp This is required for Microsoft Windows Server 2012 (and later) domain controllers. .Sp Valid options are: .RS 4 .IP "\fBgenerate\fR" 4 .IX Item "generate" Generate a random \s-1VM\s0 generation \s-1ID\s0 every time the domain is created or restored. .IP "\fBnone\fR" 4 .IX Item "none" Do not provide a \s-1VM\s0 generation \s-1ID.\s0 .RE .RS 4 .Sp See also \*(L"Virtual Machine Generation \s-1ID\*(R"\s0 by Microsoft: .RE .PP \fIGuest Virtual Time Controls\fR .IX Subsection "Guest Virtual Time Controls" .ie n .IP "\fBtsc_mode=""\s-1MODE""\s0\fR" 4 .el .IP "\fBtsc_mode=``\s-1MODE''\s0\fR" 4 .IX Item "tsc_mode=MODE" \&\fB(x86 only)\fR Specifies how the \s-1TSC\s0 (Time Stamp Counter) should be provided to the guest. \fBSpecifying this option as a number is deprecated.\fR .Sp Options are: .RS 4 .IP "\fBdefault\fR" 4 .IX Item "default" Guest rdtsc/p is executed natively when monotonicity can be guaranteed and emulated otherwise (with frequency scaled if necessary). .Sp If a \s-1HVM\s0 container in \fBdefault\fR \s-1TSC\s0 mode is created on a host that provides constant host \s-1TSC,\s0 its guest \s-1TSC\s0 frequency will be the same as the host. If it is later migrated to another host that provide constant host \s-1TSC\s0 and supports Intel \s-1VMX TSC\s0 scaling/AMD \s-1SVM TSC\s0 ratio, its guest \s-1TSC\s0 frequency will be the same before and after migration, and guest rdtsc/p will be executed natively after migration as well .IP "\fBalways_emulate\fR" 4 .IX Item "always_emulate" Guest rdtsc/p is always emulated and the virtual \s-1TSC\s0 will appear to increment (kernel and user) at a fixed 1GHz rate, regardless of the pCPU \s-1HZ\s0 rate or power state. Although there is an overhead associated with emulation, this will \s-1NOT\s0 affect underlying \s-1CPU\s0 performance. .IP "\fBnative\fR" 4 .IX Item "native" Guest rdtsc/p is always executed natively (no monotonicity/frequency guarantees). Guest rdtsc/p is emulated at native frequency if unsupported by h/w, else executed natively. .IP "\fBnative_paravirt\fR" 4 .IX Item "native_paravirt" Same as \fBnative\fR, except Xen manages the \s-1TSC_AUX\s0 register so the guest can determine when a restore/migration has occurred and assumes guest obtains/uses a pvclock-like mechanism to adjust for monotonicity and frequency changes. .Sp If a \s-1HVM\s0 container in \fBnative_paravirt\fR \s-1TSC\s0 mode can execute both guest rdtsc and guest rdtscp natively, then the guest \s-1TSC\s0 frequency will be determined in a similar way to that of \fBdefault\fR \s-1TSC\s0 mode. .RE .RS 4 .Sp Please see \fB\fBxen\-tscmode\fB\|(7)\fR for more information on this option. .RE .IP "\fBlocaltime=BOOLEAN\fR" 4 .IX Item "localtime=BOOLEAN" Set the real time clock to local time or to \s-1UTC.\s0 False (0) by default, i.e. set to \s-1UTC.\s0 .IP "\fBrtc_timeoffset=SECONDS\fR" 4 .IX Item "rtc_timeoffset=SECONDS" Set the real time clock offset in seconds. No offset (0) by default. .IP "\fBvpt_align=BOOLEAN\fR" 4 .IX Item "vpt_align=BOOLEAN" Specifies that periodic Virtual Platform Timers should be aligned to reduce guest interrupts. Enabling this option can reduce power consumption, especially when a guest uses a high timer interrupt frequency (\s-1HZ\s0) values. The default is true (1). .ie n .IP "\fBtimer_mode=""\s-1MODE""\s0\fR" 4 .el .IP "\fBtimer_mode=``\s-1MODE''\s0\fR" 4 .IX Item "timer_mode=MODE" Specifies the mode for Virtual Timers. The valid values are as follows: .RS 4 .IP "\fBdelay_for_missed_ticks\fR" 4 .IX Item "delay_for_missed_ticks" Delay for missed ticks. Do not advance a vCPU's time beyond the correct delivery time for interrupts that have been missed due to preemption. Deliver missed interrupts when the vCPU is rescheduled and advance the vCPU's virtual time stepwise for each one. .IP "\fBno_delay_for_missed_ticks\fR" 4 .IX Item "no_delay_for_missed_ticks" No delay for missed ticks. As above, missed interrupts are delivered, but guest time always tracks wallclock (i.e., real) time while doing so. This is the default. .IP "\fBno_missed_ticks_pending\fR" 4 .IX Item "no_missed_ticks_pending" No missed interrupts are held pending. Instead, to ensure ticks are delivered at some non-zero rate, if we detect missed ticks then the internal tick alarm is not disabled if the vCPU is preempted during the next tick period. .IP "\fBone_missed_tick_pending\fR" 4 .IX Item "one_missed_tick_pending" One missed tick pending. Missed interrupts are collapsed together and delivered as one 'late tick'. Guest time always tracks wallclock (i.e., real) time. .RE .RS 4 .RE .PP \fIMemory layout\fR .IX Subsection "Memory layout" .IP "\fBmmio_hole=MBYTES\fR" 4 .IX Item "mmio_hole=MBYTES" Specifies the size the \s-1MMIO\s0 hole below 4GiB will be. Only valid for \&\fBdevice_model_version=\*(L"qemu\-xen\*(R"\fR. .Sp Cannot be smaller than 256. Cannot be larger than 3840. .Sp Known good large value is 3072. .PP \fISupport for Paravirtualisation of \s-1HVM\s0 Guests\fR .IX Subsection "Support for Paravirtualisation of HVM Guests" .PP The following options allow Paravirtualised features (such as devices) to be exposed to the guest Operating System in an \s-1HVM\s0 guest. Utilising these features requires specific guest support but when available they will result in improved performance. .IP "\fBxen_platform_pci=BOOLEAN\fR" 4 .IX Item "xen_platform_pci=BOOLEAN" Enable or disable the Xen platform \s-1PCI\s0 device. The presence of this virtual device enables a guest Operating System (subject to the availability of suitable drivers) to make use of paravirtualisation features such as disk and network devices etc. Enabling these drivers improves performance and is strongly recommended when available. \s-1PV\s0 drivers are available for various Operating Systems including \s-1HVM\s0 Linux and Microsoft Windows . .Sp Setting \fBxen_platform_pci=0\fR with the default device_model \*(L"qemu-xen\*(R" requires at least \s-1QEMU 1.6.\s0 .ie n .IP "\fBviridian=[ ""\s-1GROUP"", ""GROUP"", ...\s0]\fR or \fBviridian=BOOLEAN\fR" 4 .el .IP "\fBviridian=[ ``\s-1GROUP'', ``GROUP'', ...\s0]\fR or \fBviridian=BOOLEAN\fR" 4 .IX Item "viridian=[ GROUP, GROUP, ...] or viridian=BOOLEAN" The groups of Microsoft Hyper-V (\s-1AKA\s0 viridian) compatible enlightenments exposed to the guest. The following groups of enlightenments may be specified: .RS 4 .IP "\fBbase\fR" 4 .IX Item "base" This group incorporates the Hypercall MSRs, Virtual processor index \s-1MSR,\s0 and \s-1APIC\s0 access MSRs. These enlightenments can improve performance of Windows Vista and Windows Server 2008 onwards and setting this option for such guests is strongly recommended. This group is also a pre-requisite for all others. If it is disabled then it is an error to attempt to enable any other group. .IP "\fBfreq\fR" 4 .IX Item "freq" This group incorporates the \s-1TSC\s0 and \s-1APIC\s0 frequency MSRs. These enlightenments can improve performance of Windows 7 and Windows Server 2008 R2 onwards. .IP "\fBtime_ref_count\fR" 4 .IX Item "time_ref_count" This group incorporates Partition Time Reference Counter \s-1MSR.\s0 This enlightenment can improve performance of Windows 8 and Windows Server 2012 onwards. .IP "\fBreference_tsc\fR" 4 .IX Item "reference_tsc" This set incorporates the Partition Reference \s-1TSC MSR.\s0 This enlightenment can improve performance of Windows 7 and Windows Server 2008 R2 onwards. .IP "\fBhcall_remote_tlb_flush\fR" 4 .IX Item "hcall_remote_tlb_flush" This set incorporates use of hypercalls for remote \s-1TLB\s0 flushing. This enlightenment may improve performance of Windows guests running on hosts with higher levels of (physical) \s-1CPU\s0 contention. .IP "\fBapic_assist\fR" 4 .IX Item "apic_assist" This set incorporates use of the \s-1APIC\s0 assist page to avoid \s-1EOI\s0 of the local \s-1APIC.\s0 This enlightenment may improve performance of guests that make use of per-vCPU event channel upcall vectors. Note that this enlightenment will have no effect if the guest is using APICv posted interrupts. .IP "\fBcrash_ctl\fR" 4 .IX Item "crash_ctl" This group incorporates the crash control MSRs. These enlightenments allow Windows to write crash information such that it can be logged by Xen. .IP "\fBdefaults\fR" 4 .IX Item "defaults" This is a special value that enables the default set of groups, which is currently the \fBbase\fR, \fBfreq\fR, \fBtime_ref_count\fR, \fBapic_assist\fR and \fBcrash_ctl\fR groups. .IP "\fBall\fR" 4 .IX Item "all" This is a special value that enables all available groups. .RE .RS 4 .Sp Groups can be disabled by prefixing the name with '!'. So, for example, to enable all groups except \fBfreq\fR, specify: .Sp .RS 4 \&\fBviridian=[ \*(L"all\*(R", \*(L"!freq\*(R" ]\fR .RE .RE .RS 4 .Sp For details of the enlightenments see the latest version of Microsoft's Hypervisor Top-Level Functional Specification. .Sp The enlightenments should be harmless for other versions of Windows (although they will not give any benefit) and the majority of other non-Windows OSes. However it is known that they are incompatible with some other Operating Systems and in some circumstance can prevent Xen's own paravirtualisation interfaces for \s-1HVM\s0 guests from being used. .Sp The viridian option can be specified as a boolean. A value of true (1) is equivalent to the list [ \*(L"defaults\*(R" ], and a value of false (0) is equivalent to an empty list. .RE .PP \fIEmulated \s-1VGA\s0 Graphics Device\fR .IX Subsection "Emulated VGA Graphics Device" .PP The following options control the features of the emulated graphics device. Many of these options behave similarly to the equivalent key in the \fB\s-1VFB_SPEC_STRING\s0\fR for configuring virtual frame buffer devices (see above). .IP "\fBvideoram=MBYTES\fR" 4 .IX Item "videoram=MBYTES" Sets the amount of \s-1RAM\s0 which the emulated video card will contain, which in turn limits the resolutions and bit depths which will be available. .Sp When using the qemu-xen-traditional device-model, the default as well as minimum amount of video \s-1RAM\s0 for stdvga is 8 \s-1MB,\s0 which is sufficient for e.g. 1600x1200 at 32bpp. For the upstream qemu-xen device-model, the default and minimum is 16 \s-1MB.\s0 .Sp When using the emulated Cirrus graphics card (\fBvga=\*(L"cirrus\*(R"\fR) and the qemu-xen-traditional device-model, the amount of video \s-1RAM\s0 is fixed at 4 \s-1MB,\s0 which is sufficient for 1024x768 at 32 bpp. For the upstream qemu-xen device-model, the default and minimum is 8 \s-1MB.\s0 .Sp For \s-1QXL\s0 vga, both the default and minimal are 128MB. If \fBvideoram\fR is set less than 128MB, an error will be triggered. .IP "\fBstdvga=BOOLEAN\fR" 4 .IX Item "stdvga=BOOLEAN" Speficies a standard \s-1VGA\s0 card with \s-1VBE\s0 (\s-1VESA BIOS\s0 Extensions) as the emulated graphics device. If your guest supports \s-1VBE 2.0\s0 or later (e.g. Windows \s-1XP\s0 onwards) then you should enable this. stdvga supports more video ram and bigger resolutions than Cirrus. The default is false (0) which means to emulate a Cirrus Logic \s-1GD5446 VGA\s0 card. \&\fBThis option is deprecated, use vga=\*(L"stdvga\*(R" instead\fR. .ie n .IP "\fBvga=""\s-1STRING""\s0\fR" 4 .el .IP "\fBvga=``\s-1STRING''\s0\fR" 4 .IX Item "vga=STRING" Selects the emulated video card. Options are: \fBnone\fR, \fBstdvga\fR, \fBcirrus\fR and \fBqxl\fR. The default is \fBcirrus\fR. .Sp In general, \s-1QXL\s0 should work with the Spice remote display protocol for acceleration, and a \s-1QXL\s0 driver is necessary in the guest in that case. \&\s-1QXL\s0 can also work with the \s-1VNC\s0 protocol, but it will be like a standard \&\s-1VGA\s0 card without acceleration. .IP "\fBvnc=BOOLEAN\fR" 4 .IX Item "vnc=BOOLEAN" Allow access to the display via the \s-1VNC\s0 protocol. This enables the other VNC-related settings. The default is (1) enabled. .ie n .IP "\fBvnclisten=""ADDRESS[:DISPLAYNUM]""\fR" 4 .el .IP "\fBvnclisten=``ADDRESS[:DISPLAYNUM]''\fR" 4 .IX Item "vnclisten=ADDRESS[:DISPLAYNUM]" Specifies the \s-1IP\s0 address and, optionally, the \s-1VNC\s0 display number to use. .IP "\fBvncdisplay=DISPLAYNUM\fR" 4 .IX Item "vncdisplay=DISPLAYNUM" Specifies the \s-1VNC\s0 display number to use. The actual \s-1TCP\s0 port number will be \s-1DISPLAYNUM+5900.\s0 .IP "\fBvncunused=BOOLEAN\fR" 4 .IX Item "vncunused=BOOLEAN" Requests that the \s-1VNC\s0 display setup searches for a free \s-1TCP\s0 port to use. The actual display used can be accessed with \fBxl vncviewer\fR. .ie n .IP "\fBvncpasswd=""\s-1PASSWORD""\s0\fR" 4 .el .IP "\fBvncpasswd=``\s-1PASSWORD''\s0\fR" 4 .IX Item "vncpasswd=PASSWORD" Specifies the password for the \s-1VNC\s0 server. If the password is set to an empty string, authentication on the \s-1VNC\s0 server will be disabled allowing any user to connect. .ie n .IP "\fBkeymap=""\s-1LANG""\s0\fR" 4 .el .IP "\fBkeymap=``\s-1LANG''\s0\fR" 4 .IX Item "keymap=LANG" Configure the keymap to use for the keyboard associated with this display. If the input method does not easily support raw keycodes (e.g. this is often the case when using \s-1VNC\s0) then this allows us to correctly map the input keys into keycodes seen by the guest. The specific values which are accepted are defined by the version of the device-model which you are using. See \fBKeymaps\fR below or consult the \&\fB\fBqemu\fB\|(1)\fR manpage. The default is \fBen-us\fR. .IP "\fBsdl=BOOLEAN\fR" 4 .IX Item "sdl=BOOLEAN" Specifies that the display should be presented via an X window (using Simple DirectMedia Layer). The default is (0) not enabled. .IP "\fBopengl=BOOLEAN\fR" 4 .IX Item "opengl=BOOLEAN" Enable OpenGL acceleration of the \s-1SDL\s0 display. Only effects machines using \fBdevice_model_version=\*(L"qemu\-xen\-traditional\*(R"\fR and only if the device-model was compiled with OpenGL support. Default is (0) false. .IP "\fBnographic=BOOLEAN\fR" 4 .IX Item "nographic=BOOLEAN" Enable or disable the virtual graphics device. The default is to provide a \s-1VGA\s0 graphics device but this option can be used to disable it. .PP \fISpice Graphics Support\fR .IX Subsection "Spice Graphics Support" .PP The following options control the features of \s-1SPICE.\s0 .IP "\fBspice=BOOLEAN\fR" 4 .IX Item "spice=BOOLEAN" Allow access to the display via the \s-1SPICE\s0 protocol. This enables the other SPICE-related settings. .ie n .IP "\fBspicehost=""\s-1ADDRESS""\s0\fR" 4 .el .IP "\fBspicehost=``\s-1ADDRESS''\s0\fR" 4 .IX Item "spicehost=ADDRESS" Specifies the interface address to listen on if given, otherwise any interface. .IP "\fBspiceport=NUMBER\fR" 4 .IX Item "spiceport=NUMBER" Specifies the port to listen on by the \s-1SPICE\s0 server if \s-1SPICE\s0 is enabled. .IP "\fBspicetls_port=NUMBER\fR" 4 .IX Item "spicetls_port=NUMBER" Specifies the secure port to listen on by the \s-1SPICE\s0 server if \s-1SPICE\s0 is enabled. At least one of \fBspiceport\fR or \fBspicetls_port\fR must be given if \s-1SPICE\s0 is enabled. .Sp \&\fBNote:\fR the options depending on \fBspicetls_port\fR have not been supported. .IP "\fBspicedisable_ticketing=BOOLEAN\fR" 4 .IX Item "spicedisable_ticketing=BOOLEAN" Enable clients to connect without specifying a password. When disabled, \&\fBspicepasswd\fR must be set. The default is (0) false. .ie n .IP "\fBspicepasswd=""\s-1PASSWORD""\s0\fR" 4 .el .IP "\fBspicepasswd=``\s-1PASSWORD''\s0\fR" 4 .IX Item "spicepasswd=PASSWORD" Specify the password which is used by clients for establishing a connection. .IP "\fBspiceagent_mouse=BOOLEAN\fR" 4 .IX Item "spiceagent_mouse=BOOLEAN" Whether \s-1SPICE\s0 agent is used for client mouse mode. The default is (1) true. .IP "\fBspicevdagent=BOOLEAN\fR" 4 .IX Item "spicevdagent=BOOLEAN" Enables the \s-1SPICE\s0 vdagent. The \s-1SPICE\s0 vdagent is an optional component for enhancing user experience and performing guest-oriented management tasks. Its features include: client mouse mode (no need to grab the mouse by the client, no mouse lag), automatic adjustment of screen resolution, copy and paste (text and image) between the client and the guest. It also requires the vdagent service installed on the guest \s-1OS\s0 to work. The default is (0) disabled. .IP "\fBspice_clipboard_sharing=BOOLEAN\fR" 4 .IX Item "spice_clipboard_sharing=BOOLEAN" Enables \s-1SPICE\s0 clipboard sharing (copy/paste). It requires that \&\fBspicevdagent\fR is enabled. The default is (0) false. .IP "\fBspiceusbredirection=NUMBER\fR" 4 .IX Item "spiceusbredirection=NUMBER" Enables \s-1SPICE USB\s0 redirection. Creates a \s-1NUMBER\s0 of \s-1USB\s0 redirection channels for redirecting up to 4 \s-1USB\s0 devices from the \s-1SPICE\s0 client to the guest's \s-1QEMU.\s0 It requires an \s-1USB\s0 controller and, if not defined, it will automatically add an \s-1USB2.0\s0 controller. The default is (0) disabled. .ie n .IP "\fBspice_image_compression=""\s-1COMPRESSION""\s0\fR" 4 .el .IP "\fBspice_image_compression=``\s-1COMPRESSION''\s0\fR" 4 .IX Item "spice_image_compression=COMPRESSION" Specifies what image compression is to be used by \s-1SPICE\s0 (if given), otherwise the \s-1QEMU\s0 default will be used. Please see the documentation of your \s-1QEMU\s0 version for more details. .Sp Available options are: \fBauto_glz, auto_lz, quic, glz, lz, off\fR. .ie n .IP "\fBspice_streaming_video=""\s-1VIDEO""\s0\fR" 4 .el .IP "\fBspice_streaming_video=``\s-1VIDEO''\s0\fR" 4 .IX Item "spice_streaming_video=VIDEO" Specifies what streaming video setting is to be used by \s-1SPICE\s0 (if given), otherwise the \s-1QEMU\s0 default will be used. .Sp Available options are: \fBfilter, all, off\fR. .PP \fIMiscellaneous Emulated Hardware\fR .IX Subsection "Miscellaneous Emulated Hardware" .ie n .IP "\fBserial=[ ""\s-1DEVICE"", ""DEVICE"", ...\s0]\fR" 4 .el .IP "\fBserial=[ ``\s-1DEVICE'', ``DEVICE'', ...\s0]\fR" 4 .IX Item "serial=[ DEVICE, DEVICE, ...]" Redirect virtual serial ports to \fB\s-1DEVICE\s0\fRs. Please see the \&\fB\-serial\fR option in the \fB\fBqemu\fB\|(1)\fR manpage for details of the valid \&\fB\s-1DEVICE\s0\fR options. Default is \fBvc\fR when in graphical mode and \&\fBstdio\fR if \fBnographics=1\fR is used. .Sp The form serial=DEVICE is also accepted for backwards compatibility. .ie n .IP "\fBsoundhw=""\s-1DEVICE""\s0\fR" 4 .el .IP "\fBsoundhw=``\s-1DEVICE''\s0\fR" 4 .IX Item "soundhw=DEVICE" Select the virtual sound card to expose to the guest. The valid devices are defined by the device model configuration, please see the \&\fB\fBqemu\fB\|(1)\fR manpage for details. The default is not to export any sound device. .IP "\fBusb=BOOLEAN\fR" 4 .IX Item "usb=BOOLEAN" Enables or disables an emulated \s-1USB\s0 bus in the guest. .IP "\fBusbversion=NUMBER\fR" 4 .IX Item "usbversion=NUMBER" Specifies the type of an emulated \s-1USB\s0 bus in the guest, values 1 for \s-1USB1.1, 2\s0 for \s-1USB2.0\s0 and 3 for \s-1USB3.0.\s0 It is available only with an upstream \s-1QEMU.\s0 Due to implementation limitations this is not compatible with the \fBusb\fR and \fBusbdevice\fR parameters. Default is (0) no \s-1USB\s0 controller defined. .ie n .IP "\fBusbdevice=[ ""\s-1DEVICE"", ""DEVICE"", ...\s0]\fR" 4 .el .IP "\fBusbdevice=[ ``\s-1DEVICE'', ``DEVICE'', ...\s0]\fR" 4 .IX Item "usbdevice=[ DEVICE, DEVICE, ...]" Adds \fB\s-1DEVICE\s0\fRs to the emulated \s-1USB\s0 bus. The \s-1USB\s0 bus must also be enabled using \fBusb=1\fR. The most common use for this option is \&\fBusbdevice=['tablet']\fR which adds a pointer device using absolute coordinates. Such devices function better than relative coordinate devices (such as a standard mouse) since many methods of exporting guest graphics (such as \s-1VNC\s0) work better in this mode. Note that this is independent of the actual pointer device you are using on the host/client side. .Sp Host devices can also be passed through in this way, by specifying host:USBID, where \s-1USBID\s0 is of the form xxxx:yyyy. The \s-1USBID\s0 can typically be found by using \fB\fBlsusb\fB\|(1)\fR or \fB\fBusb\-devices\fB\|(1)\fR. .Sp If you wish to use the \*(L"host:bus.addr\*(R" format, remove any leading '0' from the bus and addr. For example, for the \s-1USB\s0 device on bus 008 dev 002, you should write \*(L"host:8.2\*(R". .Sp The form usbdevice=DEVICE is also accepted for backwards compatibility. .Sp More valid options can be found in the \*(L"usbdevice\*(R" section of the \s-1QEMU\s0 documentation. .ie n .IP "\fBvendor_device=""\s-1VENDOR_DEVICE""\s0\fR" 4 .el .IP "\fBvendor_device=``\s-1VENDOR_DEVICE''\s0\fR" 4 .IX Item "vendor_device=VENDOR_DEVICE" Selects which variant of the \s-1QEMU\s0 xen-pvdevice should be used for this guest. Valid values are: .RS 4 .IP "\fBnone\fR" 4 .IX Item "none" The xen-pvdevice should be omitted. This is the default. .IP "\fBxenserver\fR" 4 .IX Item "xenserver" The xenserver variant of the xen-pvdevice (device\-id=C000) will be specified, enabling the use of XenServer \s-1PV\s0 drivers in the guest. .RE .RS 4 .Sp This parameter only takes effect when device_model_version=qemu\-xen. See \fB\fBxen\-pci\-device\-reservations\fB\|(7)\fR for more information. .RE .SS "\s-1PVH\s0 Guest Specific Options" .IX Subsection "PVH Guest Specific Options" .IP "\fBnestedhvm=BOOLEAN\fR" 4 .IX Item "nestedhvm=BOOLEAN" Enable or disables guest access to hardware virtualisation features, e.g. it allows a guest Operating System to also function as a hypervisor. You may want this option if you want to run another hypervisor (including another copy of Xen) within a Xen guest or to support a guest Operating System which uses hardware virtualisation extensions (e.g. Windows \s-1XP\s0 compatibility mode on more modern Windows \s-1OS\s0). .Sp This option is disabled by default. .ie n .IP "\fBbootloader=""\s-1PROGRAM""\s0\fR" 4 .el .IP "\fBbootloader=``\s-1PROGRAM''\s0\fR" 4 .IX Item "bootloader=PROGRAM" Run \f(CW\*(C`PROGRAM\*(C'\fR to find the kernel image and ramdisk to use. Normally \&\f(CW\*(C`PROGRAM\*(C'\fR would be \f(CW\*(C`pygrub\*(C'\fR, which is an emulation of grub/grub2/syslinux. Either \fBkernel\fR or \fBbootloader\fR must be specified for \s-1PV\s0 guests. .ie n .IP "\fBbootloader_args=[ ""\s-1ARG"", ""ARG"", ...\s0]\fR" 4 .el .IP "\fBbootloader_args=[ ``\s-1ARG'', ``ARG'', ...\s0]\fR" 4 .IX Item "bootloader_args=[ ARG, ARG, ...]" Append \fB\s-1ARG\s0\fRs to the arguments to the \fBbootloader\fR program. Alternatively if the argument is a simple string then it will be split into words at whitespace \fB(this second option is deprecated)\fR. .ie n .IP "\fBtimer_mode=""\s-1MODE""\s0\fR" 4 .el .IP "\fBtimer_mode=``\s-1MODE''\s0\fR" 4 .IX Item "timer_mode=MODE" Specifies the mode for Virtual Timers. The valid values are as follows: .RS 4 .IP "\fBdelay_for_missed_ticks\fR" 4 .IX Item "delay_for_missed_ticks" Delay for missed ticks. Do not advance a vCPU's time beyond the correct delivery time for interrupts that have been missed due to preemption. Deliver missed interrupts when the vCPU is rescheduled and advance the vCPU's virtual time stepwise for each one. .IP "\fBno_delay_for_missed_ticks\fR" 4 .IX Item "no_delay_for_missed_ticks" No delay for missed ticks. As above, missed interrupts are delivered, but guest time always tracks wallclock (i.e., real) time while doing so. This is the default. .IP "\fBno_missed_ticks_pending\fR" 4 .IX Item "no_missed_ticks_pending" No missed interrupts are held pending. Instead, to ensure ticks are delivered at some non-zero rate, if we detect missed ticks then the internal tick alarm is not disabled if the vCPU is preempted during the next tick period. .IP "\fBone_missed_tick_pending\fR" 4 .IX Item "one_missed_tick_pending" One missed tick pending. Missed interrupts are collapsed together and delivered as one 'late tick'. Guest time always tracks wallclock (i.e., real) time. .RE .RS 4 .RE .PP \fIPaging\fR .IX Subsection "Paging" .PP The following options control the mechanisms used to virtualise guest memory. The defaults are selected to give the best results for the common cases so you should normally leave these options unspecified. .IP "\fBhap=BOOLEAN\fR" 4 .IX Item "hap=BOOLEAN" Turns \*(L"hardware assisted paging\*(R" (the use of the hardware nested page table feature) on or off. This feature is called \s-1EPT\s0 (Extended Page Tables) by Intel and \s-1NPT\s0 (Nested Page Tables) or \s-1RVI\s0 (Rapid Virtualisation Indexing) by \s-1AMD.\s0 If turned off, Xen will run the guest in \*(L"shadow page table\*(R" mode where the guest's page table updates and/or \s-1TLB\s0 flushes etc. will be emulated. Use of \s-1HAP\s0 is the default when available. .IP "\fBoos=BOOLEAN\fR" 4 .IX Item "oos=BOOLEAN" Turns \*(L"out of sync pagetables\*(R" on or off. When running in shadow page table mode, the guest's page table updates may be deferred as specified in the Intel/AMD architecture manuals. However, this may expose unexpected bugs in the guest, or find bugs in Xen, so it is possible to disable this feature. Use of out of sync page tables, when Xen thinks it appropriate, is the default. .IP "\fBshadow_memory=MBYTES\fR" 4 .IX Item "shadow_memory=MBYTES" Number of megabytes to set aside for shadowing guest pagetable pages (effectively acting as a cache of translated pages) or to use for \s-1HAP\s0 state. By default this is 1MB per guest vCPU plus 8KB per \s-1MB\s0 of guest \&\s-1RAM.\s0 You should not normally need to adjust this value. However, if you are not using hardware assisted paging (i.e. you are using shadow mode) and your guest workload consists of a very large number of similar processes then increasing this value may improve performance. .SS "Device-Model Options" .IX Subsection "Device-Model Options" The following options control the selection of the device-model. This is the component which provides emulation of the virtual devices to an \&\s-1HVM\s0 guest. For a \s-1PV\s0 guest a device-model is sometimes used to provide backends for certain \s-1PV\s0 devices (most usually a virtual framebuffer device). .ie n .IP "\fBdevice_model_version=""\s-1DEVICE\-MODEL""\s0\fR" 4 .el .IP "\fBdevice_model_version=``\s-1DEVICE\-MODEL''\s0\fR" 4 .IX Item "device_model_version=DEVICE-MODEL" Selects which variant of the device-model should be used for this guest. .Sp Valid values are: .RS 4 .IP "\fBqemu-xen\fR" 4 .IX Item "qemu-xen" Use the device-model merged into the upstream \s-1QEMU\s0 project. This device-model is the default for Linux dom0. .IP "\fBqemu-xen-traditional\fR" 4 .IX Item "qemu-xen-traditional" Use the device-model based upon the historical Xen fork of \s-1QEMU.\s0 This device-model is still the default for NetBSD dom0. .RE .RS 4 .Sp It is recommended to accept the default value for new guests. If you have existing guests then, depending on the nature of the guest Operating System, you may wish to force them to use the device model which they were installed with. .RE .ie n .IP "\fBdevice_model_override=""\s-1PATH""\s0\fR" 4 .el .IP "\fBdevice_model_override=``\s-1PATH''\s0\fR" 4 .IX Item "device_model_override=PATH" Override the path to the binary to be used as the device-model. The binary provided here \s-1MUST\s0 be consistent with the \&\fBdevice_model_version\fR which you have specified. You should not normally need to specify this option. .IP "\fBdevice_model_stubdomain_override=BOOLEAN\fR" 4 .IX Item "device_model_stubdomain_override=BOOLEAN" Override the use of stubdomain based device-model. Normally this will be automatically selected based upon the other features and options you have selected. .ie n .IP "\fBdevice_model_stubdomain_seclabel=""\s-1LABEL""\s0\fR" 4 .el .IP "\fBdevice_model_stubdomain_seclabel=``\s-1LABEL''\s0\fR" 4 .IX Item "device_model_stubdomain_seclabel=LABEL" Assign an \s-1XSM\s0 security label to the device-model stubdomain. .ie n .IP "\fBdevice_model_args=[ ""\s-1ARG"", ""ARG"", ...\s0]\fR" 4 .el .IP "\fBdevice_model_args=[ ``\s-1ARG'', ``ARG'', ...\s0]\fR" 4 .IX Item "device_model_args=[ ARG, ARG, ...]" Pass additional arbitrary options on the device-model command line. Each element in the list is passed as an option to the device-model. .ie n .IP "\fBdevice_model_args_pv=[ ""\s-1ARG"", ""ARG"", ...\s0]\fR" 4 .el .IP "\fBdevice_model_args_pv=[ ``\s-1ARG'', ``ARG'', ...\s0]\fR" 4 .IX Item "device_model_args_pv=[ ARG, ARG, ...]" Pass additional arbitrary options on the device-model command line for a \s-1PV\s0 device model only. Each element in the list is passed as an option to the device-model. .ie n .IP "\fBdevice_model_args_hvm=[ ""\s-1ARG"", ""ARG"", ...\s0]\fR" 4 .el .IP "\fBdevice_model_args_hvm=[ ``\s-1ARG'', ``ARG'', ...\s0]\fR" 4 .IX Item "device_model_args_hvm=[ ARG, ARG, ...]" Pass additional arbitrary options on the device-model command line for an \s-1HVM\s0 device model only. Each element in the list is passed as an option to the device-model. .SS "Keymaps" .IX Subsection "Keymaps" The keymaps available are defined by the device-model which you are using. Commonly this includes: .PP .Vb 3 \& ar de\-ch es fo fr\-ca hu ja mk no pt\-br sv \& da en\-gb et fr fr\-ch is lt nl pl ru th \& de en\-us fi fr\-be hr it lv nl\-be pt sl tr .Ve .PP The default is \fBen-us\fR. .PP See \fB\fBqemu\fB\|(1)\fR for more information. .SS "Architecture Specific options" .IX Subsection "Architecture Specific options" \fI\s-1ARM\s0\fR .IX Subsection "ARM" .ie n .IP "\fBgic_version=""vN""\fR" 4 .el .IP "\fBgic_version=``vN''\fR" 4 .IX Item "gic_version=vN" Version of the \s-1GIC\s0 emulated for the guest. .Sp Currently, the following versions are supported: .RS 4 .IP "\fBv2\fR" 4 .IX Item "v2" Emulate a GICv2 .IP "\fBv3\fR" 4 .IX Item "v3" Emulate a GICv3. Note that the emulated \s-1GIC\s0 does not support the GICv2 compatibility mode. .IP "\fBdefault\fR" 4 .IX Item "default" Emulate the same version as the native \s-1GIC\s0 hardware used by the host where the domain was created. .RE .RS 4 .Sp This requires hardware compatibility with the requested version, either natively or via hardware backwards compatibility support. .RE .ie n .IP "\fBvuart=""uart""\fR" 4 .el .IP "\fBvuart=``uart''\fR" 4 .IX Item "vuart=uart" To enable vuart console, user must specify the following option in the \&\s-1VM\s0 config file: .Sp vuart = \*(L"sbsa_uart\*(R" .Sp Currently, only the \*(L"sbsa_uart\*(R" model is supported for \s-1ARM.\s0 .PP \fIx86\fR .IX Subsection "x86" .ie n .IP "\fBmca_caps=[ ""\s-1CAP"", ""CAP"", ...\s0 ]\fR" 4 .el .IP "\fBmca_caps=[ ``\s-1CAP'', ``CAP'', ...\s0 ]\fR" 4 .IX Item "mca_caps=[ CAP, CAP, ... ]" (\s-1HVM\s0 only) Enable \s-1MCA\s0 capabilities besides default ones enabled by Xen hypervisor for the \s-1HVM\s0 domain. \*(L"\s-1CAP\*(R"\s0 can be one in the following list: .RS 4 .ie n .IP "\fB""lmce""\fR" 4 .el .IP "\fB``lmce''\fR" 4 .IX Item "lmce" Intel local \s-1MCE\s0 .IP "\fBdefault\fR" 4 .IX Item "default" No \s-1MCA\s0 capabilities in above list are enabled. .RE .RS 4 .RE .SH "SEE ALSO" .IX Header "SEE ALSO" .IP "\fBxl\fR\|(1)" 4 .IX Item "xl" .PD 0 .IP "\fBxl.conf\fR\|(5)" 4 .IX Item "xl.conf" .IP "\fBxlcpupool.cfg\fR\|(5)" 4 .IX Item "xlcpupool.cfg" .IP "\fBxl\-disk\-configuration\fR\|(5)" 4 .IX Item "xl-disk-configuration" .IP "\fBxl\-network\-configuration\fR\|(5)" 4 .IX Item "xl-network-configuration" .IP "\fBxen\-tscmode\fR\|(7)" 4 .IX Item "xen-tscmode" .PD .SH "FILES" .IX Header "FILES" \&\fI/etc/xen/NAME.cfg\fR \&\fI/var/lib/xen/dump/NAME\fR .SH "BUGS" .IX Header "BUGS" This document may contain items which require further documentation. Patches to improve incomplete items (or any other item) are gratefully received on the xen\-devel@lists.xen.org mailing list. Please see for information on how to submit a patch to Xen.