xen-project/xen
1
0 Fork 1
mirror of https://github.com/xen-project/xen.git synced 2026-10-29 18:50:05 +01:00
Code Issues Activity
Files
bfa493f52e894f2c8877aba525b0a04df7e452bb
xen/docs/man/xl.cfg.pod.5
T
Haozhong Zhang 0a9bf8c044 docs: Add descriptions of TSC scaling in xl.cfg and tscmode.txt 
Signed-off-by: Haozhong Zhang <haozhong.zhang@intel.com>
Reviewed-by: Kevin Tian <kevin.tian@intel.com>
2016-03-01 14:09:29 +00:00

1936 lines
62 KiB
Plaintext
Raw Blame History

=head1 NAME
xl.cfg - XL Domain Configuration File Syntax
=head1 SYNOPSIS
/etc/xen/xldomain
=head1 DESCRIPTION
To create a VM (a domain in Xen terminology, sometimes called a guest)
with xl requires the provision of a domain config file. Typically
these live in `/etc/xen/DOMAIN.cfg` where DOMAIN is the name of the
domain.
=head1 SYNTAX
A domain config file consists of a series of C<KEY=VALUE> pairs.
Some C<KEY>s are mandatory, others are general options which apply to
any guest type while others relate only to specific guest types
(e.g. PV or HVM guests).
A value C<VALUE> is one of:
=over 4
=item B<"STRING">
A string, surrounded by either single or double quotes.
=item B<NUMBER>
A number, in either decimal, octal (using a C<0> prefix) or
hexadecimal (using an C<0x> prefix).
=item B<BOOLEAN>
A C<NUMBER> interpreted as C<False> (C<0>) or C<True> (any other
value).
=item B<[ VALUE, VALUE, ... ]>
A list of C<VALUES> of the above types. Lists can be heterogeneous and
nested.
=back
The semantics of each C<KEY> defines which form of C<VALUE> is required.
Pairs may be separated either by a newline or a semicolon. Both
of the following are valid:
name="h0"
builder="hvm"
name="h0"; builder="hvm"
=head1 OPTIONS
=head2 Mandatory Configuration Items
The following key is mandatory for any guest type:
=over 4
=item B<name="NAME">
Specifies the name of the domain. Names of domains existing on a
single host must be unique.
=back
=head2 Selecting Guest Type
=over 4
=item B<builder="generic">
Specifies that this is to be a PV domain. This is the default.
=item B<builder="hvm">
Specifies that this is to be an HVM domain. That is, a fully
virtualised computer with emulated BIOS, disk and network peripherals,
etc. The default is a PV domain, suitable for hosting Xen-aware guest
operating systems.
=back
=head2 General Options
The following options apply to guests of any type.
=head3 CPU Allocation
=over 4
=item B<pool="CPUPOOLNAME">
Put the guest's vcpus into the named cpu pool.
=item B<vcpus=N>
Start the guest with N vcpus initially online.
=item B<maxvcpus=M>
Allow the guest to bring up a maximum of M vcpus. At start of day if
`vcpus=N` is less than `maxvcpus=M` then the first `N` vcpus will be
created online and the remainder will be offline.
=item B<cpus="CPU-LIST">
List of which cpus the guest is allowed to use. Default is no pinning at
all (more on this below). A C<CPU-LIST> may be specified as follows:
=over 4
=item "all"
To allow all the vcpus of the guest to run on all the cpus on the host.
=item "0-3,5,^1"
To allow all the vcpus of the guest to run on cpus 0,2,3,5. Combining
this with "all" is possible, meaning "all,^7" results in all the vcpus
of the guest running on all the cpus on the host except cpu 7.
=item "nodes:0-3,node:^2"
To allow all the vcpus of the guest to run on the cpus from NUMA nodes
0,1,3 of the host. So, if cpus 0-3 belongs to node 0, cpus 4-7 belongs
to node 1 and cpus 8-11 to node 3, the above would mean all the vcpus
of the guest will run on cpus 0-3,8-11.
Combining this notation with the one above is possible. For instance,
"1,node:2,^6", means all the vcpus of the guest will run on cpu 1 and
on all the cpus of NUMA node 2, but not on cpu 6. Following the same
example as above, that would be cpus 1,4,5,7.
Combining this with "all" is also possible, meaning "all,^nodes:1"
results in all the vcpus of the guest running on all the cpus on the
host, except for the cpus belonging to the host NUMA node 1.
=item ["2", "3-8,^5"]
To ask for specific vcpu mapping. That means (in this example), vcpu 0
of the guest will run on cpu 2 of the host and vcpu 1 of the guest will
run on cpus 3,4,6,7,8 of the host.
More complex notation can be also used, exactly as described above. So
"all,^5-8", or just "all", or "node:0,node:2,^9-11,18-20" are all legal,
for each element of the list.
=back
If this option is not specified, no vcpu to cpu 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, provided via B<cpus\_soft=> (if any),
is utilized to compute the domain node-affinity, for driving memory
allocations.
=item B<cpus_soft="CPU-LIST">
Exactly as B<cpus=>, but specifies soft affinity, rather than pinning
(hard affinity). When using the credit scheduler, this means what cpus
the vcpus of the domain prefer.
A C<CPU-LIST> is specified exactly as above, for B<cpus=>.
If this option is not specified, the vcpus of the guest will not have
any preference regarding on what cpu to run. If this option is specified,
the intersection of the soft affinity mask, provided here, and the vcpu
pinning, provided via B<cpus=> (if any), is utilized to compute the
domain node-affinity, for driving memory allocations.
If this option is not specified (and B<cpus=> 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 the pcpus belonging to the NUMA nodes
chosen during placement.
For more details, see F<docs/misc/xl-numa-placement.markdown>.
=back
=head3 CPU Scheduling
=over 4
=item B<cpu_weight=WEIGHT>
A domain with a weight of 512 will get twice as much CPU 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.
=item B<cap=N>
The cap optionally fixes the maximum amount of CPU a domain will be
able to consume, even if the host system has idle CPU cycles.
The cap is expressed in percentage of one physical CPU:
100 is 1 physical CPU, 50 is half a CPU, 400 is 4 CPUs, etc.
The default, 0, means there is no upper cap.
Honoured by the credit and credit2 schedulers.
NB: Many systems have features that will scale down the computing
power of a cpu that is not 100% utilized. This can be in the
operating system, but can also sometimes be below the operating system
in the BIOS. 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 vm at 50%, the power management
system may also reduce the clock speed to 1GHz; the effect will be
that your VM 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 cpufreq options in your operating system and
your BIOS.
=back
=head3 Memory Allocation
=over 4
=item B<memory=MBYTES>
Start the guest with MBYTES megabytes of RAM.
=item B<maxmem=MBYTES>
Specifies the maximum amount of memory a guest can ever see.
The value of B<maxmem=> must be equal or greater than B<memory=>.
In combination with B<memory=> it will start the guest "pre-ballooned",
if the values of B<memory=> and B<maxmem=> differ.
A "pre-ballooned" HVM guest needs a balloon driver, without a balloon driver
it will crash.
NOTE: 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.
=back
=head3 Guest Virtual NUMA Configuration
=over 4
=item B<vnuma=[ VNODE_SPEC, VNODE_SPEC, ... ]>
Specify virtual NUMA configuration with positional arguments. The
nth B<VNODE_SPEC> in the list specifies the configuration of nth
virtual node.
Note that virtual NUMA for PV guest is not yet supported, because
there is an issue with cpuid handling that affects PV virtual NUMA.
Furthermore, guests with virtual NUMA cannot be saved or migrated
because the migration stream does not preserve node information.
Each B<VNODE_SPEC> is a list, which has a form of
"[VNODE_CONFIG_OPTION,VNODE_CONFIG_OPTION, ... ]" (without quotes).
For example vnuma = [ ["pnode=0","size=512","vcpus=0-4","vdistances=10,20"] ]
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.
Each B<VNODE_CONFIG_OPTION> is a quoted key=value pair. Supported
B<VNODE_CONFIG_OPTION>s are (they are all mandatory at the moment):
=over 4
=item B<pnode=NUMBER>
Specify which physical node this virtual node maps to.
=item B<size=MBYTES>
Specify the size of this virtual node. The sum of memory size of all
vnodes will become B<maxmem=>. If B<maxmem=> is specified separately,
a check is performed to make sure the sum of all vnode memory matches
B<maxmem=>.
=item B<vcpus=CPU-STRING>
Specify which vcpus belong to this node. B<CPU-STRING> is a string
separated by comma. You can specify range and single cpu. An example
is "vcpus=0-5,8", which means you specify vcpu 0 to vcpu 5, and vcpu
8.
=item B<vdistances=NUMBER, NUMBER, ... >
Specify virtual distance from this node to all nodes (including
itself) with positional arguments. For example, "vdistance=10,20"
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.
Normally you can use the values from "xl info -n" or "numactl
--hardware" to fill in vdistance list.
=back
=back
=head3 Event Actions
=over 4
=item B<on_poweroff="ACTION">
Specifies what should be done with the domain if it shuts itself down.
The C<ACTION>s are:
=over 4
=item B<destroy>
destroy the domain
=item B<restart>
destroy the domain and immediately create a new domain with the same
configuration
=item B<rename-restart>
rename the domain which terminated, and then immediately create a new
domain with the same configuration as the original
=item B<preserve>
keep the domain. It can be examined, and later destroyed with `xl
destroy`.
=item B<coredump-destroy>
write a "coredump" of the domain to F</var/lib/xen/dump/NAME> and then
destroy the domain.
=item B<coredump-restart>
write a "coredump" of the domain to F</var/lib/xen/dump/NAME> and then
restart the domain.
=item B<soft-reset>
Reset all Xen specific interfaces for the Xen-aware HVM domain allowing
it to reestablish these interfaces and continue executing the domain. PV
and non-Xen-aware HVM guests are not supported.
=back
The default for C<on_poweroff> is C<destroy>.
=item B<on_reboot="ACTION">
Action to take if the domain shuts down with a reason code requesting
a reboot. Default is C<restart>.
=item B<on_watchdog="ACTION">
Action to take if the domain shuts down due to a Xen watchdog timeout.
Default is C<destroy>.
=item B<on_crash="ACTION">
Action to take if the domain crashes. Default is C<destroy>.
=item B<on_soft_reset="ACTION">
Action to take if the domain performs 'soft reset' (e.g. does kexec).
Default is C<soft-reset>.
=back
=head3 Direct Kernel Boot
Direct kernel boot allows booting directly from a kernel and initrd
stored in the host physical machine OS, allowing command line arguments
to be passed directly. PV guest direct kernel boot is supported. HVM
guest direct kernel boot is supported with limitation (it's supported
when using qemu-xen and default BIOS 'seabios'; not supported in case of
stubdom-dm and old rombios.)
=over 4
=item B<kernel="PATHNAME">
Load the specified file as the kernel image.
=item B<ramdisk="PATHNAME">
Load the specified file as the ramdisk.
=item B<cmdline="STRING">
Append B<cmdline="STRING"> to the kernel command line. (Note: it is
guest specific what meaning this has). It can replace B<root="STRING">
plus B<extra="STRING"> and is preferred. When B<cmdline="STRING"> is set,
B<root="STRING"> and B<extra="STRING"> will be ignored.
=item B<root="STRING">
Append B<root="STRING"> to the kernel command line (Note: it is guest
specific what meaning this has).
=item B<extra="STRING">
Append B<STRING> to the kernel command line. (Note: it is guest
specific what meaning this has).
=back
=head3 Other Options
=over 4
=item B<uuid="UUID">
Specifies the UUID of the domain. If not specified, a fresh unique
UUID will be generated.
=item B<seclabel="LABEL">
Assign an XSM security label to this domain.
=item B<init_seclabel="LABEL">
Specify an XSM security label used for this domain temporarily during
its build. The domain's XSM label will be changed to the execution
seclabel (specified by "seclabel") 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.
=item B<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 TSC feature flag in cpuid results when TSC is
not emulated.
=item B<driver_domain=BOOLEAN>
Specify that this domain is a driver domain. This enables certain
features needed in order to run a driver domain.
=item B<device_tree=PATH>
Specify a partial device tree (compiled via the Device Tree Compiler).
Everything under the node "/passthrough" will be copied into the guest
device tree. For convenience, the node "/aliases" is also copied to allow
the user to defined aliases which can be used by the guest kernel.
Given the complexity of verifying the validity of a device tree, this
option should only be used with trusted device tree.
Note that the partial device tree should avoid to use the phandle 65000
which is reserved by the toolstack.
=back
=head2 Devices
The following options define the paravirtual, emulated and physical
devices which the guest will contain.
=over 4
=item B<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 they should map to. See F<docs/misc/xl-disk-configuration.txt>.
=item B<vif=[ "NET_SPEC_STRING", "NET_SPEC_STRING", ...]>
Specifies the networking provision (both emulated network adapters,
and Xen virtual interfaces) to provided to the guest. See
F<docs/misc/xl-network-configuration.markdown>.
=item B<vtpm=[ "VTPM_SPEC_STRING", "VTPM_SPEC_STRING", ...]>
Specifies the virtual trusted platform module to be
provided to the guest. Please see F<docs/misc/vtpm.txt>
for more details.
Each B<VTPM_SPEC_STRING> is a comma-separated list of C<KEY=VALUE>
settings, from the following list:
=over 4
=item C<backend=DOMAIN>
Specify the backend domain name of id. This value is required!
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.
=item C<uuid=UUID>
Specify the uuid of this vtpm device. The uuid is used to uniquely
identify the vtpm device. You can create one using the uuidgen
program on unix systems. If left unspecified, a new uuid
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.
=back
=item B<vfb=[ "VFB_SPEC_STRING", "VFB_SPEC_STRING", ...]>
Specifies the paravirtual framebuffer devices which should be supplied
to the domain.
This option does not control the emulated graphics card presented to
an HVM guest. See L<Emulated VGA Graphics Device> below for how to
configure the emulated device. If L<Emulated VGA Graphics Device> options
are used in a PV guest configuration, xl will pick up B<vnc>, B<vnclisten>,
B<vncpasswd>, B<vncdisplay>, B<vncunused>, B<sdl>, B<opengl> and
B<keymap> to construct paravirtual framebuffer device for the guest.
Each B<VFB_SPEC_STRING> is a comma-separated list of C<KEY=VALUE>
settings, from the following list:
=over 4
=item C<vnc=BOOLEAN>
Allow access to the display via the VNC protocol. This enables the
other VNC-related settings. The default is to enable this.
=item C<vnclisten="ADDRESS[:DISPLAYNUM]">
Specifies the IP address, and optionally VNC display number, to use.
NB that if you specify the display number here, you should not use
vncdisplay.
=item C<vncdisplay=DISPLAYNUM>
Specifies the VNC display number to use. The actual TCP port number
will be DISPLAYNUM+5900.
NB that you should not use this option if you set the displaynum in the
vnclisten string.
=item C<vncunused=BOOLEAN>
Requests that the VNC display setup search for a free TCP port to use.
The actual display used can be accessed with C<xl vncviewer>.
=item C<vncpasswd="PASSWORD">
Specifies the password for the VNC server.
=item C<sdl=BOOLEAN>
Specifies that the display should be presented via an X window (using
Simple DirectMedia Layer). The default is to not enable this mode.
=item C<display=DISPLAY>
Specifies the X Window display that should be used when the sdl option
is used.
=item C<xauthority=XAUTHORITY>
Specifies the path to the X authority file that should be used to
connect to the X server when the sdl option is used.
=item C<opengl=BOOLEAN>
Enable OpenGL acceleration of the SDL display. Only effects machines
using C<device_model_version="qemu-xen-traditional"> and only if the
device-model was compiled with OpenGL support. Disabled by default.
=item C<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 VNC) 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 L</"Keymaps"> below or consult the
L<qemu(1)> manpage. The default is B<en-us>.
=back
=item B<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 VM
configuration after boot and signalling to in-guest agents. Please see
F<docs/misc/channels.txt> for more details.
Each B<CHANNEL_SPEC_STRING> is a comma-separated list of C<KEY=VALUE>
seettings. Leading and trailing whitespace is ignored in both KEY and
VALUE. Neither KEY nor VALUE may contain ',', '=' or '"'. Defined values
are:
=over 4
=item C<backend=DOMAIN>
Specify the backend domain name or id. This parameter is optional. If
this parameter is omitted then the toolstack domain will be assumed.
=item C<name=NAME>
Specify the string name for this device. This parameter is mandatory.
This should be a well-known name for the 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 domain name and version number in the string
(e.g. org.mydomain.guestagent.1).
=item C<connection=CONNECTION>
Specify how the backend will be implemented. This following options are
available:
=over 4
=item B<connection=SOCKET>
The backend will bind a Unix domain socket (at the path given by
B<path=PATH>), call listen and accept connections. The backend will proxy
data between the channel and the connected socket.
=item B<connection=PTY>
The backend will create a pty and proxy data between the channel and the
master device. The command B<xl channel-list> can be used to discover the
assigned slave device.
=back
=back
=item B<rdm="RDM_RESERVATION_STRING">
(HVM/x86 only) Specifies information about Reserved Device Memory (RDM),
which is necessary to enable robust device passthrough. One example of RDM
is reported through ACPI Reserved Memory Region Reporting (RMRR) structure
on x86 platform.
B<RDM_RESERVE_STRING> has the form C<[KEY=VALUE,KEY=VALUE,...> where:
=over 4
=item B<KEY=VALUE>
Possible B<KEY>s are:
=over 4
=item B<strategy="STRING">
Currently there is only one valid type:
"host" means all reserved device memory on this platform should be checked to
reserve regions in this VM's guest address space. This global rdm parameter
allows user to specify reserved regions explicitly, and using "host" includes
all reserved regions reported on this platform, which is useful when doing
hotplug.
By default this isn't set so we don't check all rdms. Instead, we just check
rdm specific to a given device if you're assigning this kind of device. Note
this option is not recommended unless you can make sure any conflict does exist.
For example, you're trying to set "memory = 2800" to allocate memory to one
given VM but the platform owns two RDM regions like,
Device A [sbdf_A]: RMRR region_A: base_addr ac6d3000 end_address ac6e6fff
Device B [sbdf_B]: RMRR region_B: base_addr ad800000 end_address afffffff
In this conflict case,
#1. If B<strategy> is set to "host", for example,
rdm = "strategy=host,policy=strict" or rdm = "strategy=host,policy=relaxed"
It means all conflicts will be handled according to the policy
introduced by B<policy> as described below.
#2. If B<strategy> is not set at all, but
pci = [ 'sbdf_A, rdm_policy=xxxxx' ]
It means only one conflict of region_A will be handled according to the policy
introduced by B<rdm_policy="STRING"> as described inside pci options.
=item B<policy="STRING">
Specifies how to deal with conflicts when reserving reserved device
memory in guest address space.
When that conflict is unsolved,
"strict" means VM can't be created, or the associated device can't be
attached in the case of hotplug.
"relaxed" allows VM to be created but may cause VM to crash if
pass-through device accesses RDM. For exampl,e Windows IGD GFX driver
always accessed RDM regions so it leads to VM crash.
Note this may be overridden by rdm_policy option in PCI device configuration.
=back
=back
=item B<pci=[ "PCI_SPEC_STRING", "PCI_SPEC_STRING", ... ]>
Specifies the host PCI devices to passthrough to this guest. Each B<PCI_SPEC_STRING>
has the form C<[DDDD:]BB:DD.F[@VSLOT],KEY=VALUE,KEY=VALUE,...> where:
=over 4
=item B<DDDD:BB:DD.F>
Identifies the PCI device from the host perspective in domain
(B<DDDD>), Bus (B<BB>), Device (B<DD>) and Function (B<F>) syntax. This is
the same scheme as used in the output of C<lspci> for the device in
question. Note: By default C<lspci> will omit the domain (B<DDDD>) if it
is zero and it is optional here also. You may specify the function
(B<F>) as B<*> to indicate all functions.
=item B<@VSLOT>
Specifies the virtual device where the guest will see this
device. This is equivalent to the B<DD> which the guest sees. In a
guest B<DDDD> and B<BB> are C<0000:00>.
=item B<KEY=VALUE>
Possible B<KEY>s are:
=over 4
=item B<permissive=BOOLEAN>
By default pciback only allows PV guests to write "known safe" values
into PCI config space, likewise QEMU (both qemu-xen and
qemu-traditional) imposes the same contraint on HVM guests. However
many devices require writes to other areas of config space in order to
operate properly. This option tells the backend (pciback or QEMU) to
allow all writes to PCI config space of this device by this domain.
This option should be enabled with caution: it gives the guest much
more control over the device, which may have security or stability
implications. It is recommended to enable this option only for
trusted VMs under administrator control.
=item B<msitranslate=BOOLEAN>
Specifies that MSI-INTx translation should be turned on for the PCI
device. When enabled, MSI-INTx translation will always enable MSI on
the PCI device regardless whether the guest uses INTx or MSI. Some
device drivers, such as NVIDIA's, detect an inconsistency and do not
function when this option is enabled. Therefore the default is false (0).
=item B<seize=BOOLEAN>
Tells xl to automatically attempt to re-assign a device to
pciback if it is not already assigned.
WARNING: If you set this option, xl 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.
=item B<power_mgmt=BOOLEAN>
(HVM only) Specifies that the VM should be able to program the
D0-D3hot power management states for the PCI device. False (0) by
default.
=item B<rdm_policy="STRING">
(HVM/x86 only) This is same as policy option inside the rdm option but
just specific to a given device. Therefore the default is "relaxed" as
same as policy option as well.
Note this would override global B<rdm> option.
=back
=back
=item B<pci_permissive=BOOLEAN>
Changes the default value of 'permissive' for all PCI devices passed
through to this VM. See L<permissive|/"permissive_boolean"> above.
=item B<pci_msitranslate=BOOLEAN>
Changes the default value of 'msitranslate' for all PCI devices passed
through to this VM. See L<msitranslate|/"msitranslate_boolean"> above.
=item B<pci_seize=BOOLEAN>
Changes the default value of 'seize' for all PCI devices passed
through to this VM. See L<seize|/"seize_boolean"> above.
=item B<pci_power_mgmt=BOOLEAN>
(HVM only) Changes the default value of 'power_mgmt' for all PCI
devices passed through to this VM. See L<power_mgt|/"power_mgmt_boolean">
above.
=item B<gfx_passthru=BOOLEAN|"STRING">
Enable graphics device PCI passthrough. This option makes an assigned
PCI graphics card become primary graphics card in the VM. The QEMU
emulated graphics adapter is disabled and the VNC console for the VM
will not have any graphics output. All graphics output, including boot
time QEMU BIOS messages from the VM, will go to the physical outputs
of the passedthrough physical graphics card.
The graphics card PCI device to passthrough is chosen with B<pci>
option, exactly in the same way as normal Xen PCI device
passthrough/assignment is done. Note that gfx_passthru does not do
any kind of sharing of the GPU, so you can only assign the GPU to one
single VM at a time.
gfx_passthru also enables various legacy VGA memory ranges, BARs, MMIOs,
and ioports to be passed thru to the VM, since those are required
for correct operation of things like VGA BIOS, text mode, VBE, etc.
Enabling gfx_passthru option also copies the physical graphics card
video BIOS to the guest memory, and executes the VBIOS in the guest
to initialize the graphics card.
Most graphics adapters require vendor specific tweaks for properly
working graphics passthrough. See the XenVGAPassthroughTestedAdapters
L<http://wiki.xen.org/wiki/XenVGAPassthroughTestedAdapters> wiki page
for currently supported graphics cards for gfx_passthru.
gfx_passthru is currently supported both with the qemu-xen-traditional
device-model and upstream qemu-xen device-model.
When given as a boolean the B<gfx_passthru> option either disables gfx
passthru or enables autodetection.
But when given as a string the B<gfx_passthru> option describes the type
of device to enable. Note this behavior is only supported with the upstream
qemu-xen device-model. With qemu-xen-traditional IGD is always assumed
and other options than autodetect or explicit IGD will result in an error.
Currently, valid options are:
=over 4
=item B<gfx_passthru=0>
Disables graphics device PCI passthrough.
=item B<gfx_passthru=1>, B<gfx_passthru="default">
Enables graphics device PCI passthrough and autodetects the type of device
which is being used.
=item "igd"
Enables graphics device PCI passthrough but forcing the type of device to
Intel Graphics Device.
=back
Note that some graphics adapters (AMD/ATI cards, for example) do not
necessarily require gfx_passthru option, so you can use the normal Xen
PCI passthrough to assign the graphics card as a secondary graphics
card to the VM. The QEMU-emulated graphics card remains the primary
graphics card, and VNC output is available from the QEMU-emulated
primary adapter.
More information about Xen gfx_passthru feature is available
on the XenVGAPassthrough L<http://wiki.xen.org/wiki/XenVGAPassthrough>
wiki page.
=item B<rdm_mem_boundary=MBYTES>
Number of megabytes to set a boundary for checking rdm conflict.
When RDM conflicts with RAM, RDM probably scatter the whole RAM space.
Especially multiple RDM entries would worsen this to lead a complicated
memory layout. So here we're trying to figure out a simple solution to
avoid breaking existing layout. So when a conflict occurs,
#1. Above a predefined boundary
- move lowmem_end below reserved region to solve conflict;
#2. Below a predefined boundary
- Check strict/relaxed policy.
"strict" policy leads to fail libxl. Note when both policies
are specified on a given region, 'strict' is always preferred.
"relaxed" policy issue a warning message and also mask this
entry INVALID to indicate we shouldn't expose this entry to
hvmloader.
Here the default is 2G.
=item B<dtdev=[ "DTDEV_PATH", "DTDEV_PATH", ... ]>
Specifies the host device tree nodes to passthrough to this guest. Each
DTDEV_PATH is the absolute path in the device tree.
=item B<ioports=[ "IOPORT_RANGE", "IOPORT_RANGE", ... ]>
Allow guest to access specific legacy I/O ports. Each B<IOPORT_RANGE>
is given in hexadecimal and may either a span e.g. C<2f8-2ff>
(inclusive) or a single I/O port C<2f8>.
It is recommended to use this option only for trusted VMs under
administrator control.
=item B<iomem=[ "IOMEM_START,NUM_PAGES[@GFN]", "IOMEM_START,NUM_PAGES[@GFN]", ... ]>
Allow auto-translated domains to access specific hardware I/O memory pages.
B<IOMEM_START> is a physical page number. B<NUM_PAGES> is the number of pages
beginning with B<START_PAGE> to allow access. B<GFN> specifies the guest frame
number where the mapping will start in the domU's address space. If B<GFN> is
not given, the mapping will be performed using B<IOMEM_START> as a start in the
domU's address space, therefore performing an 1:1 mapping as default.
All of these values must be given in hexadecimal.
Note that the IOMMU won't be updated with the mappings specified with this
option. This option therefore should not be used to passthrough any
IOMMU-protected device.
It is recommended to use this option only for trusted VMs under
administrator control.
=item B<irqs=[ NUMBER, NUMBER, ... ]>
Allow a guest to access specific physical IRQs.
It is recommended to use this option only for trusted VMs under
administrator control.
=item B<max_event_channels=N>
Limit the guest to using at most N event channels (PV interrupts).
Guests use hypervisor resources for each event channel they use.
The default of 1023 should be sufficient for typical guests. The
maximum value depends what the guest supports. Guests supporting the
FIFO-based event channel ABI support up to 131,071 event channels.
Other guests are limited to 4095 (64-bit x86 and ARM) or 1023 (32-bit
x86).
=back
=head2 Paravirtualised (PV) Guest Specific Options
The following options apply only to Paravirtual guests.
=over 4
=item B<bootloader="PROGRAM">
Run C<PROGRAM> to find the kernel image and ramdisk to use. Normally
C<PROGRAM> would be C<pygrub>, which is an emulation of
grub/grub2/syslinux. Either B<kernel> or B<bootloader> must be specified
for PV guests.
=item B<bootloader_args=[ "ARG", "ARG", ...]>
Append B<ARG>s to the arguments to the B<bootloader>
program. Alternatively if the argument is a simple string then it will
be split into words at whitespace (this second option is deprecated).
=item B<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 RAM region. When this
option is specified the virtual e820 instead reflects the host e820
and contains the same PCI holes. The total amount of RAM represented
by the memory map is always the same, this option configures only how
it is laid out.
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
PCI devices. It is guest Operating System dependent whether this
option is required, specifically it is required when using a mainline
Linux ("pvops") kernel. This option defaults to true (1) if any PCI
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.
=item B<pvh=BOOLEAN>
Selects whether to run this PV guest in an HVM container. Default is 0.
=back
=head2 Fully-virtualised (HVM) Guest Specific Options
The following options apply only to HVM guests.
=head3 Boot Device
=over 4
=item B<boot=[c|d|n]>
Selects the emulated virtual device to boot from. Options are hard
disk (B<c>), cd-rom (B<d>) or network/PXE (B<n>). Multiple options can be
given and will be attempted in the order they are given. e.g. to boot
from cd-rom but fallback to the hard disk you can give B<dc>. The
default is B<cd>.
=back
=head3 Emulated disk controller type
=over 4
=item B<hdtype="STRING">
Select the hd disk type (ide|ahci).
If hdtype=ahci adds ich9 disk controller in AHCI mode and uses it with
upstream qemu to emulate disks instead of IDE. It decreases boot time
but may not be supported by default in Windows xp and older Windows.
The default is ide.
=back
=head3 Paging
The following options control the mechanisms used to virtualise guest
memory. The defaults are selected to give the best results for the
common case and so you should normally leave these options
unspecified.
=over 4
=item B<hap=BOOLEAN>
Turns "hardware assisted paging" (the use of the hardware nested page
table feature) on or off. This feature is called EPT (Extended Page
Tables) by Intel and NPT (Nested Page Tables) or RVI (Rapid
Virtualisation Indexing) by AMD. Affects HVM guests only. If turned
off, Xen will run the guest in "shadow page table" mode where the
guest's page table updates and/or TLB flushes etc. will be emulated.
Use of HAP is the default when available.
=item B<oos=BOOLEAN>
Turns "out of sync pagetables" 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.
=item B<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 HAP
state. By default this is 1MB per guest vcpu plus 8KB per MB of guest
RAM. 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 a very large number of
similar processes then increasing this value may improve performance.
=back
=head3 Processor and Platform Features
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.
=over 4
=item B<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 UEFI.
=over 4
=item B<rombios>
Loads ROMBIOS, a 16-bit x86 compatible BIOS. This is used by default
when device_model_version=qemu-xen-traditional. This is the only BIOS
option supported when device_model_version=qemu-xen-traditional. This is
the BIOS used by all previous Xen versions.
=item B<seabios>
Loads SeaBIOS, a 16-bit x86 compatible BIOS. This is used by default
with device_model_version=qemu-xen.
=item B<ovmf>
Loads OVMF, a standard UEFI firmware by Tianocore project.
Requires device_model_version=qemu-xen.
=back
=item B<pae=BOOLEAN>
Hide or expose the IA32 Physical Address Extensions. These extensions
make it possible for a 32 bit guest Operating System to access more
than 4GB of RAM. Enabling PAE also enabled other features such as
NX. PAE 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 PAE. (X86 only)
=item B<acpi=BOOLEAN>
Expose ACPI (Advanced Configuration and Power Interface) tables from
the virtual firmware to the guest Operating System. ACPI 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 ACPI for compatibility with some guest Operating Systems.
=item B<acpi_s3=BOOLEAN>
Include the S3 (suspend-to-ram) power state in the virtual firmware
ACPI table. True (1) by default.
=item B<acpi_s4=BOOLEAN>
Include S4 (suspend-to-disk) power state in the virtual firmware ACPI
table. True (1) by default.
=item B<apic=BOOLEAN>
Include information regarding APIC (Advanced Programmable Interrupt
Controller) in the firmware/BIOS tables on a single processor
guest. This causes the MP (multiprocessor) and PIR (PCI 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 ACPI tables. (X86 only)
=item B<nx=BOOLEAN>
Hides or exposes the No-eXecute capability. This allows a guest
Operating system to map pages such that they cannot be executed which
can enhance security. This options requires that PAE also be
enabled. (X86 only)
=item B<hpet=BOOLEAN>
Enables or disables HPET (High Precision Event Timer). This option is
enabled by default and you should usually omit it. It may be necessary
to disable the HPET in order to improve compatibility with guest
Operating Systems (X86 only)
=item B<altp2mhvm=BOOLEAN>
Enables or disables hvm guest access to alternate-p2m capability.
Alternate-p2m allows a guest to manage multiple p2m guest physical
"memory views" (as opposed to a single p2m). This option is
disabled by default and is available only to hvm 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 HVM domain memory introspection or
for isolation/access-control of memory between components within
a single guest hvm domain.
=item B<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. This option is disabled by default. 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 XP
compatibility mode on more modern Windows OS).
=item B<cpuid="LIBXL_STRING"> or B<cpuid=[ "XEND_STRING", "XEND_STRING" ]>
Configure the value returned when a guest executes CPUID instruction.
Two versions of config syntax are recognized: libxl and xend.
The libxl syntax is a comma separated list of key=value pairs, preceded by the
word "host". A few keys take a numerical value, all others take a single
character which describes what to do with the feature bit.
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)
Note: when specifying B<cpuid> for hypervisor leaves (0x4000xxxx major group)
only the lowest 8 bits of leaf's 0x4000xx00 EAX register are processed, the rest
are ignored (these 8 bits signify maximum number of hypervisor leaves).
List of keys taking a value:
apicidsize brandid clflush family localapicid maxleaf maxhvleaf model nc
proccount procpkg stepping
List of keys taking a character:
3dnow 3dnowext 3dnowprefetch abm acpi aes altmovcr8 apic avx clfsh cmov
cmplegacy cmpxchg16 cmpxchg8 cntxid dca de ds dscpl dtes64 est extapic f16c
ffxsr fma4 fpu fxsr htt hypervisor ia64 ibs lahfsahf lm lwp mca mce misalignsse
mmx mmxext monitor movbe msr mtrr nodeid nx osvw osxsave pae page1gb pat pbe
pclmulqdq pdcm pge popcnt pse pse36 psn rdtscp skinit smx ss sse sse2 sse3
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
vme vmx wdt x2apic xop xsave xtpr
The xend syntax is a list of values in the form of
'leafnum:register=bitstring,register=bitstring'
"leafnum" is the requested function,
"register" is the response register to modify
"bitstring" 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.
Example to hide two features from the guest: 'tm', which is bit #29 in EDX, and
'pni' (SSE3), which is bit #0 in ECX:
xend: [ '1:ecx=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx0,edx=xx0xxxxxxxxxxxxxxxxxxxxxxxxxxxxx' ]
libxl: 'host,tm=0,sse3=0'
More info about the CPUID instruction can be found in the processor manuals, and
in Wikipedia: L<http://en.wikipedia.org/wiki/CPUID>
=item B<acpi_firmware="STRING">
Specify a path to a file that contains extra ACPI firmware tables to pass in to
a guest. The file can contain several tables in their binary AML form
concatenated together. Each table self describes its length so no additional
information is needed. These tables will be added to the ACPI 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 DSDT, FADT, etc.
=item B<smbios_firmware="STRING">
Specify a path to a file that contains extra SMBIOS firmware structures to pass
in to a guest. The file can contain a set DMTF 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 SMBIOS structures (type 128 - 255). Since SMBIOS
structures do not present their overall size, each entry in the file must be
preceded by a 32b integer indicating the size of the next structure.
=item B<ms_vm_genid="OPTION">
Provide a VM generation ID to the guest.
The VM generation ID as a 128-bit random number that a guest may use
to determine if the guest has been restored from an earlier snapshot
or cloned.
This is required for Microsoft Windows Server 2012 (and later) domain
controllers.
Valid options are:
=over 4
=item B<"generate">
Generate a random VM generation ID every time the domain is created or
restored.
=item B<"none">
Do not provide a VM generation ID.
=back
See also "Virtual Machine Generation ID" by Microsoft
(http://www.microsoft.com/en-us/download/details.aspx?id=30707).
=back
=head3 Guest Virtual Time Controls
=over 4
=item B<tsc_mode="MODE">
Specifies how the TSC (Time Stamp Counter) should be provided to the
guest (X86 only). Specifying this option as a number is
deprecated. Options are:
=over 4
=item B<"default">
Guest rdtsc/p is executed natively when monotonicity can be guaranteed
and emulated otherwise (with frequency scaled if necessary).
If a HVM container in B<default> TSC mode is created on a host that
provides constant host TSC, its guest TSC frequency will be the same
as the host. If it is later migrated to another host that provide
constant host TSC and supports Intel VMX TSC scaling/AMD SVM TSC
ratio, its guest TSC frequency will be the same before and after
migration, and guest rdtsc/p will be executed natively as well after
migration.
=item B<"always_emulate">
Guest rdtsc/p always emulated at 1GHz (kernel and user). Guest rdtsc/p
always emulated and the virtual TSC will appear to increment (kernel
and user) at a fixed 1GHz rate, regardless of the PCPU HZ rate or
power state; Although there is an overhead associated with emulation
this will NOT affect underlying CPU performance.
=item B<"native">
Guest rdtsc always executed natively (no monotonicity/frequency
guarantees); guest rdtscp emulated at native frequency if unsupported
by h/w, else executed natively.
=item B<"native_paravirt">
Same as B<native>, except xen manages TSC_AUX register so guest can
determine when a restore/migration has occurred and assumes guest
obtains/uses pvclock-like mechanism to adjust for monotonicity and
frequency changes.
If a HVM container in B<native_paravirt> TSC mode can execute both guest
rdtsc and guest rdtscp natively, then the guest TSC frequency will be
determined in the similar way to that of B<default> TSC mode.
=back
Please see F<docs/misc/tscmode.txt> for more information on this option.
=item B<localtime=BOOLEAN>
Set the real time clock to local time or to UTC. False (0) by default,
i.e. set to UTC.
=item B<rtc_timeoffset=SECONDS>
Set the real time clock offset in seconds. False (0) by default.
=item B<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 (HZ) values. The default is true (1).
=item B<timer_mode=MODE>
Specifies the mode for Virtual Timers. The valid values are as follows:
=over 4
=item B<"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.
=item B<"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.
=item B<"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.
=item B<"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.
=back
=back
=head3 Memory layout
=over 4
=item B<mmio_hole=MBYTES>
Specifies the size the MMIO hole below 4GiB will be. Only valid for
device_model_version = "qemu-xen".
Cannot be smaller than 256. Cannot be larger than 3840.
Known good large value is 3072.
=back
=head3 Support for Paravirtualisation of HVM Guests
The following options allow Paravirtualised features (such as devices)
to be exposed to the guest Operating System in an HVM guest.
Utilising these features requires specific guest support but when
available they will result in improved performance.
=over 4
=item B<xen_platform_pci=BOOLEAN>
Enable or disable the Xen platform PCI 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. PV
drivers are available for various Operating Systems including HVM
Linux L<http://wiki.xen.org/wiki/XenLinuxPVonHVMdrivers> and Microsoft
Windows L<http://wiki.xen.org/wiki/XenWindowsGplPv>.
Setting B<xen_platform_pci=0> with the default device_model "qemu-xen"
requires at least QEMU 1.6.
=item B<viridian=[ "GROUP", "GROUP", ...]>
The groups of Microsoft Hyper-V (AKA viridian) compatible enlightenments
exposed to the guest. The following groups of enlightenments may be
specified:
=over 4
=item B<base>
This group incorporates the Hypercall MSRs, Virtual processor index MSR,
and APIC 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.
=item B<freq>
This group incorporates the TSC and APIC frequency MSRs. These
enlightenments can improve performance of Windows 7 and Windows
Server 2008 R2 onwards.
=item B<time_ref_count>
This group incorporates Partition Time Reference Counter MSR. This
enlightenment can improve performance of Windows 8 and Windows
Server 2012 onwards.
=item B<reference_tsc>
This set incorporates the Partition Reference TSC MSR. This
enlightenment can improve performance of Windows 7 and Windows
Server 2008 R2 onwards.
=item B<hcall_remote_tlb_flush>
This set incorporates use of hypercalls for remote TLB flushing.
This enlightenment may improve performance of Windows guests running
on hosts with higher levels of (physical) CPU contention.
=item B<defaults>
This is a special value that enables the default set of groups, which
is currently the B<base>, B<freq> and B<time_ref_count> groups.
=item B<all>
This is a special value that enables all available groups.
=back
Groups can be disabled by prefixing the name with '!'. So, for example,
to enable all groups except B<freq>, specify:
=over 4
B<viridian=[ "all", "!freq" ]>
=back
For details of the enlightenments see the latest version of Microsoft's
Hypervisor Top-Level Functional Specification.
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 HVM guests from being used.
The viridian option can be specified as a boolean. A value of true (1)
is equivalent to the list [ "defaults" ], and a value of false (0) is
equivalent to an empty list.
=back
=head3 Emulated VGA Graphics Device
The following options control the features of the emulated graphics
device. Many of these options behave similarly to the equivalent key
in the B<VFB_SPEC_STRING> for configuring virtual frame buffer devices
(see above).
=over 4
=item B<videoram=MBYTES>
Sets the amount of RAM which the emulated video card will contain,
which in turn limits the resolutions and bit depths which will be
available.
When using the qemu-xen-traditional device-model, the default as well as
minimum amount of video RAM for stdvga is 8 MB, which is sufficient for e.g.
1600x1200 at 32bpp. For the upstream qemu-xen device-model, the default and
minimum is 16 MB.
When using the emulated Cirrus graphics card (B<vga="cirrus">) and the
qemu-xen-traditional device-model, the amount of video RAM is fixed at 4 MB,
which is sufficient for 1024x768 at 32 bpp. For the upstream qemu-xen
device-model, the default and minimum is 8 MB.
For B<qxl> vga, the default is both default and minimal 128MB.
If B<videoram> is set less than 128MB, an error will be triggered.
=item B<stdvga=BOOLEAN>
Select a standard VGA card with VBE (VESA BIOS Extensions) as the
emulated graphics device. The default is false (0) which means to emulate
a Cirrus Logic GD5446 VGA card. If your guest supports VBE 2.0 or
later (e.g. Windows XP onwards) then you should enable this.
stdvga supports more video ram and bigger resolutions than Cirrus.
This option is deprecated, use vga="stdvga" instead.
=item B<vga="STRING">
Selects the emulated video card (none|stdvga|cirrus|qxl).
The default is cirrus.
In general, QXL should work with the Spice remote display protocol
for acceleration, and QXL driver is necessary in guest in this case.
QXL can also work with the VNC protocol, but it will be like a standard
VGA without acceleration.
=item B<vnc=BOOLEAN>
Allow access to the display via the VNC protocol. This enables the
other VNC-related settings. The default is to enable this.
=item B<vnclisten="ADDRESS[:DISPLAYNUM]">
Specifies the IP address, and optionally VNC display number, to use.
=item B<vncdisplay=DISPLAYNUM>
Specifies the VNC display number to use. The actual TCP port number
will be DISPLAYNUM+5900.
=item B<vncunused=BOOLEAN>
Requests that the VNC display setup search for a free TCP port to use.
The actual display used can be accessed with C<xl vncviewer>.
=item B<vncpasswd="PASSWORD">
Specifies the password for the VNC server.
=item B<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 VNC) 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 L</"Keymaps"> below or consult the
L<qemu(1)> manpage. The default is B<en-us>.
=item B<sdl=BOOLEAN>
Specifies that the display should be presented via an X window (using
Simple DirectMedia Layer). The default is not to enable this mode.
=item B<opengl=BOOLEAN>
Enable OpenGL acceleration of the SDL display. Only effects machines
using B<device_model_version="qemu-xen-traditional"> and only if the
device-model was compiled with OpenGL support. False (0) by default.
=item B<nographic=BOOLEAN>
Enable or disable the virtual graphics device. The default is to
provide a VGA graphics device but this option can be used to disable
it.
=back
=head3 Spice Graphics Support
The following options control the features of SPICE.
=over 4
=item B<spice=BOOLEAN>
Allow access to the display via the SPICE protocol. This enables the
other SPICE-related settings.
=item B<spicehost="ADDRESS">
Specify the interface address to listen on if given, otherwise any
interface.
=item B<spiceport=NUMBER>
Specify the port to listen on by the SPICE server if the SPICE is
enabled.
=item B<spicetls_port=NUMBER>
Specify the secure port to listen on by the SPICE server if the SPICE
is enabled. At least one of the spiceport or spicetls_port must be
given if SPICE is enabled. NB. the options depending on spicetls_port
have not been supported.
=item B<spicedisable_ticketing=BOOLEAN>
Enable client connection without password. When disabled, spicepasswd
must be set. The default is false (0).
=item B<spicepasswd="PASSWORD">
Specify the ticket password which is used by a client for connection.
=item B<spiceagent_mouse=BOOLEAN>
Whether SPICE agent is used for client mouse mode. The default is true (1)
(turn on)
=item B<spicevdagent=BOOLEAN>
Enables spice vdagent. The Spice vdagent is an optional component for
enhancing user experience and performing guest-oriented management
tasks. Its features includes: client mouse mode (no need to grab mouse
by client, no mouse lag), automatic adjustment of screen resolution,
copy and paste (text and image) between client and domU. It also
requires vdagent service installed on domU o.s. to work. The default is 0.
=item B<spice_clipboard_sharing=BOOLEAN>
Enables Spice clipboard sharing (copy/paste). It requires spicevdagent
enabled. The default is false (0).
=item B<spiceusbredirection=NUMBER>
Enables spice usbredirection. Creates NUMBER usbredirection channels
for redirection of up to 4 usb devices from spice client to domU's qemu.
It requires an usb controller and if not defined it will automatically adds
an usb2 controller. The default is disabled (0).
=item B<spice_image_compression=[auto_glz|auto_lz|quic|glz|lz|off]>
Specifies what image compression is to be used by spice (if given), otherwise
the qemu default will be used. Please see documentations of your current qemu
version for details.
=item B<spice_streaming_video=[filter|all|off]>
Specifies what streaming video setting is to be used by spice (if given),
otherwise the qemu default will be used.
=back
=head3 Miscellaneous Emulated Hardware
=over 4
=item B<serial=[ "DEVICE", "DEVICE", ...]>
Redirect virtual serial ports to B<DEVICE>s. Please see the
B<-serial> option in the L<qemu(1)> manpage for details of the valid
B<DEVICE> options. Default is B<vc> when in graphical mode and
B<stdio> if B<nographics=1> is used.
The form serial=DEVICE is also accepted for backwards compatibilty.
=item B<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
L<qemu(1)> manpage for details. The default is not to export any sound
device.
=item B<usb=BOOLEAN>
Enables or disables an emulated USB bus in the guest.
=item B<usbversion=NUMBER>
Specifies the type of an emulated USB bus in the guest. 1 for usb1,
2 for usb2 and 3 for usb3, it is available only with upstream qemu.
Due to implementation limitations this is not compatible with the usb
and usbdevice parameters.
Default is 0 (no usb controller defined).
=item B<usbdevice=[ "DEVICE", "DEVICE", ...]>
Adds B<DEVICE>s to the emulated USB bus. The USB bus must also be
enabled using B<usb=1>. The most common use for this option is
B<usbdevice=['tablet']> which adds 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 VNC) work better in this mode. Note that this
is independent of the actual pointer device you are using on the
host/client side.
Host devices can also be passed through in this way, by specifying
host:USBID, where USBID is of the form xxxx:yyyy. The USBID can
typically be found by using lsusb or usb-devices.
If you wish to use the "host:bus.addr" format, remove any leading '0' from the
bus and addr. For example, for the USB device on bus 008 dev 002, you should
write "host:8.2".
The form usbdevice=DEVICE is also accepted for backwards compatibility.
More valid options can be found in the "usbdevice" section of the qemu
documentation.
=item B<vendor_device="VENDOR_DEVICE">
Selects which variant of the QEMU xen-pvdevice should be used for this
guest. Valid values are:
=over 4
=item B<none>
The xen-pvdevice should be omitted. This is the default.
=item B<xenserver>
The xenserver variant of the xen-pvdevice (device-id=C000) will be
specified, enabling the use of XenServer PV drivers in the guest.
=back
This parameter only takes effect when device_model_version=qemu-xen.
See F<docs/misc/pci-device-reservations.txt> for more information.
=back
=head2 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
HVM guest. For a PV guest a device-model is sometimes used to provide
backends for certain PV devices (most usually a virtual framebuffer
device).
=over 4
=item B<device_model_version="DEVICE-MODEL">
Selects which variant of the device-model should be used for this
guest. Valid values are:
=over 4
=item B<qemu-xen>
Use the device-model merged into the upstream QEMU project.
This device-model is the default for Linux dom0.
=item B<qemu-xen-traditional>
Use the device-model based upon the historical Xen fork of Qemu.
This device-model is still the default for NetBSD dom0.
=item B<none>
Don't use any device model. This requires a kernel capable of booting
without emulated devices.
=back
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.
=item B<device_model_override="PATH">
Override the path to the binary to be used as the device-model. The
binary provided here MUST be consistent with the
`device_model_version` which you have specified. You should not
normally need to specify this option.
=item B<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.
=item B<device_model_stubdomain_seclabel="LABEL">
Assign an XSM security label to the device-model stubdomain.
=item B<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.
=item B<device_model_args_pv=[ "ARG", "ARG", ...]>
Pass additional arbitrary options on the device-model command line for
a PV device model only. Each element in the list is passed as an
option to the device-model.
=item B<device_model_args_hvm=[ "ARG", "ARG", ...]>
Pass additional arbitrary options on the device-model command line for
an HVM device model only. Each element in the list is passed as an
option to the device-model.
=item B<device_model_user="username">
Run the device model as user "username", instead of
xen-qemudepriv-domid$domid or xen-qemudepriv-shared or root.
Please note that running QEMU as non-root causes migration and PCI
passthrough not to work properly.
=back
=head2 Keymaps
The keymaps available are defined by the device-model which you are
using. Commonly this includes:
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
The default is B<en-us>.
See L<qemu(1)> for more information.
=head2 Architecture Specific options
=head3 ARM
=over 4
=item B<gic_version="vN">
Version of the GIC emulated for the guest. Currently, the following
versions are supported:
=over 4
=item B<v2>
Emulate a GICv2
=item B<v3>
Emulate a GICv3. Note that the emulated GIC does not support the
GICv2 compatibility mode.
=item B<default>
Emulate the same version as the native GIC hardware used by host where
the domain was created.
=back
This requires hardware compatibility with the requested version. Either
natively or via hardware backwards compatibility support.
=back
=head1 SEE ALSO
=over 4
=item L<xl(1)>
=item L<xlcpupool.cfg(5)>
=item F<xl-disk-configuration>
=item F<xl-network-configuration>
=item F<docs/misc/tscmode.txt>
=back
=head1 FILES
F</etc/xen/NAME.cfg>
F</var/lib/xen/dump/NAME>
=head1 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 L<http://wiki.xen.org/wiki/SubmittingXenPatches> for
information on how to submit a patch to Xen.
Reference in new issue View Git Blame Copy Permalink