mirror of
https://github.com/xen-project/xen.git
synced 2026-10-28 02:01:24 +01:00
docs: convert xl-disk-configuration into a man page
Convert xl-disk-configuration.txt from plain text file to a POD file to get it as a man page. The references to it in the other man pages are also updated. Signed-off-by: Cédric Bosdonnat <cbosdonnat@suse.com> Acked-by: Wei Liu <wei.liu2@citrix.com>
This commit is contained in:
Cédric Bosdonnat authored and Wei Liu committed
1 parent
24512b59e4
commit
85e5d824b9
5 files changed
+534
-366
No files matched your search
@@ -16,7 +16,6 @@ misc/tscmode TSC Mode HOWTO
|
||||
misc/vbd-interface Xen Guest Disk (VBD) Interface
|
||||
misc/xenstore Xenstore protocol specification
|
||||
misc/xenstore-paths Xenstore path documentation
|
||||
misc/xl-disk-configuration XL Disk Configuration
|
||||
misc/distro_mapping Distro Directory Layouts
|
||||
misc/dump-core-format Xen Core Dump Format
|
||||
misc/vtd VT-d HOWTO
|
||||
|
||||
@@ -0,0 +1,529 @@
|
||||
=head1 NAME
|
||||
|
||||
xl-disk-configuration - XL Disk Configuration Syntax
|
||||
|
||||
=head1 SYNTAX
|
||||
|
||||
This document specifies the xl config file format disk configuration
|
||||
option. It has the following form:
|
||||
|
||||
disk = [ 'DISKSPEC', 'DISKSPEC', ... ]
|
||||
|
||||
where each C<DISKSPEC> is in this form:
|
||||
|
||||
[<key>=<value>|<flag>,]*,
|
||||
[<target>, [<format>, [<vdev>, [<access>]]]],
|
||||
[<key>=<value>|<flag>,]*
|
||||
[target=<target>]
|
||||
|
||||
For example, these strings are equivalent:
|
||||
|
||||
/dev/vg/guest-volume,,hda
|
||||
/dev/vg/guest-volume,raw,hda,rw
|
||||
format=raw, vdev=hda, access=rw, target=/dev/vg/guest-volume
|
||||
raw:/dev/vg/guest-volume,hda,w (deprecated, see below)
|
||||
|
||||
As are these:
|
||||
|
||||
/root/image.iso,,hdc,cdrom
|
||||
/root/image.iso,,hdc,,cdrom
|
||||
/root/image.iso,raw,hdc,devtype=cdrom
|
||||
format=raw, vdev=hdc, access=ro, devtype=cdrom, target=/root/image.iso
|
||||
raw:/root/image.iso,hdc:cdrom,ro (deprecated, see below)
|
||||
|
||||
These might be specified in the domain config file like this:
|
||||
|
||||
disk = [ '/dev/vg/guest-volume,,hda', '/root/image.iso,,hdc,cdrom' ]
|
||||
|
||||
|
||||
More formally, the string is a series of comma-separated keyword/value
|
||||
pairs, flags and positional parameters. Parameters which are not bare
|
||||
keywords and which do not contain "=" symbols are assigned to the
|
||||
so-far-unspecified positional parameters, in the order below. The
|
||||
positional parameters may also be specified explicitly by name.
|
||||
|
||||
Each parameter may be specified at most once, either as a positional
|
||||
parameter or a named parameter. Default values apply if the parameter
|
||||
is not specified, or if it is specified with an empty value (whether
|
||||
positionally or explicitly).
|
||||
|
||||
Whitespace may appear before each parameter and will be ignored.
|
||||
|
||||
=head1 Positional Parameters
|
||||
|
||||
=over 4
|
||||
|
||||
=item B<target>
|
||||
|
||||
=over 4
|
||||
|
||||
=item Description
|
||||
|
||||
Block device or image file path. When this is used as a path, F</dev>
|
||||
will be prepended if the path doesn't start with a '/'.
|
||||
|
||||
=item Supported values
|
||||
|
||||
N/A
|
||||
|
||||
=item Deprecated values
|
||||
|
||||
N/A
|
||||
|
||||
=item Default value
|
||||
|
||||
None. While a path is provided in most cases there is an exception:
|
||||
for a cdrom device, lack of this attribute would imply an empty cdrom
|
||||
drive.
|
||||
|
||||
=item Special syntax
|
||||
|
||||
When this parameter is specified by name, ie with the C<target=>
|
||||
syntax in the configuration file, it consumes the whole rest of the
|
||||
C<DISKSPEC> including trailing whitespaces. Therefore in that case
|
||||
it must come last. This is permissible even if an empty value for
|
||||
the target was already specified as a positional parameter. This
|
||||
is the only way to specify a target string containing metacharacters
|
||||
such as commas and (in some cases) colons, which would otherwise be
|
||||
misinterpreted.
|
||||
|
||||
Future parameter and flag names will start with an ascii letter and
|
||||
contain only ascii alphanumerics, hyphens and underscores, and will
|
||||
not be legal as vdevs. Targets which might match that syntax
|
||||
should not be specified as positional parameters.
|
||||
|
||||
=back
|
||||
|
||||
=item B<format>
|
||||
|
||||
=over 4
|
||||
|
||||
=item Description
|
||||
|
||||
Specifies the format of image file.
|
||||
|
||||
=item Supported values
|
||||
|
||||
raw, qcow, qcow2, vhd, qed
|
||||
|
||||
=item Deprecated values
|
||||
|
||||
None
|
||||
|
||||
=item Default value
|
||||
|
||||
raw
|
||||
|
||||
=back
|
||||
|
||||
=item B<vdev>
|
||||
|
||||
=over 4
|
||||
|
||||
=item Description
|
||||
|
||||
Virtual device as seen by the guest (also referred to as guest drive
|
||||
designation in some specifications). L<vbd-interface(7)>
|
||||
|
||||
=item Supported values
|
||||
|
||||
hd[x], xvd[x], sd[x] etc. Please refer to the above specification for
|
||||
further details.
|
||||
|
||||
=item Deprecated values
|
||||
|
||||
None
|
||||
|
||||
=item Default Value
|
||||
|
||||
None, this parameter is mandatory.
|
||||
|
||||
=back
|
||||
|
||||
=item B<access>
|
||||
|
||||
=over 4
|
||||
|
||||
=item Description
|
||||
|
||||
Specified access control information. Whether or not the block device is
|
||||
provided to the guest in read-only or read-write mode depends on this
|
||||
attribute.
|
||||
|
||||
=item Supported values
|
||||
|
||||
C<ro>, C<r> (specifies read-only)
|
||||
|
||||
C<rw>, C<w> (specifies read/write)
|
||||
|
||||
=item Deprecated values
|
||||
|
||||
None
|
||||
|
||||
=item Default value
|
||||
|
||||
C<rw> unless devtype=cdrom, in which case C<r>
|
||||
|
||||
=back
|
||||
|
||||
=back
|
||||
|
||||
=head1 Other Parameters And Flags
|
||||
|
||||
=over 4
|
||||
|
||||
=item B<devtype>=I<DEVTYPE>
|
||||
|
||||
=over 4
|
||||
|
||||
=item Description
|
||||
|
||||
Qualifies virtual device type.
|
||||
|
||||
=item Supported values
|
||||
|
||||
cdrom
|
||||
|
||||
=item Deprecated values
|
||||
|
||||
None
|
||||
|
||||
=item Mandatory
|
||||
|
||||
No
|
||||
|
||||
=back
|
||||
|
||||
=item B<cdrom>
|
||||
|
||||
Convenience alias for "devtype=cdrom".
|
||||
|
||||
|
||||
=item B<backend>=I<DOMAIN-NAME>
|
||||
|
||||
=over 4
|
||||
|
||||
=item Description
|
||||
|
||||
Designates a backend domain for the device
|
||||
|
||||
=item Supported values
|
||||
|
||||
Valid domain names
|
||||
|
||||
=item Mandatory
|
||||
|
||||
No
|
||||
|
||||
=back
|
||||
|
||||
Specifies the backend domain which this device should attach to. This
|
||||
defaults to domain 0. Specifying another domain requires setting up a
|
||||
driver domain which is outside the scope of this document.
|
||||
|
||||
|
||||
=item B<backendtype>=I<TYPE>
|
||||
|
||||
=over 4
|
||||
|
||||
=item Description
|
||||
|
||||
Specifies the backend implementation to use
|
||||
|
||||
=item Supported values
|
||||
|
||||
phy, tap, qdisk
|
||||
|
||||
=item Mandatory
|
||||
|
||||
No
|
||||
|
||||
=item Default value
|
||||
|
||||
Automatically determine which backend to use.
|
||||
|
||||
=back
|
||||
|
||||
This does not affect the guest's view of the device. It controls
|
||||
which software implementation of the Xen backend driver is used.
|
||||
|
||||
Not all backend drivers support all combinations of other options.
|
||||
For example, "phy" does not support formats other than "raw".
|
||||
Normally this option should not be specified, in which case libxl will
|
||||
automatically determine the most suitable backend.
|
||||
|
||||
|
||||
=item B<script>=I<SCRIPT>
|
||||
|
||||
Specifies that B<target> is not a normal host path, but rather
|
||||
information to be interpreted by the executable program I<SCRIPT>,
|
||||
(looked for in F</etc/xen/scripts>, if it doesn't contain a slash).
|
||||
|
||||
These scripts are normally called "block-I<SCRIPT>".
|
||||
|
||||
|
||||
=item B<direct-io-safe>
|
||||
|
||||
=over 4
|
||||
|
||||
=item Description
|
||||
|
||||
Disables non-O_DIRECT workaround
|
||||
|
||||
=item Supported values
|
||||
|
||||
absent, present
|
||||
|
||||
=item Mandatory
|
||||
|
||||
No
|
||||
|
||||
=item Default value
|
||||
|
||||
absent (workaround may be enabled)
|
||||
|
||||
=back
|
||||
|
||||
There is a memory lifetime bug in some driver domain (dom0) kernels
|
||||
which can cause crashes when using O_DIRECT. The bug occurs due to a
|
||||
mismatch between the backend-visible lifetime of pages used for the
|
||||
Xen PV network protocol and that expected by the backend kernel's
|
||||
networking subsystem. This can cause crashes when using certain
|
||||
backends with certain underlying storage.
|
||||
|
||||
See:
|
||||
L<http://lists.xen.org/archives/html/xen-devel/2012-12/msg01154.html>
|
||||
|
||||
For this reason, (this version of) the Xen libxl toolstack disables
|
||||
O_DIRECT when using the qemu-based Xen PV backend (C<qdisk>).
|
||||
|
||||
However, this workaround has performance and scaling implications, and
|
||||
it is only necessary if the underlying device is a network filesystem.
|
||||
If the underlying device is not, then it is good to disable it; that
|
||||
is what this option is for.
|
||||
|
||||
This option simply requests that the workaround be disabled. (However,
|
||||
not all backends versions which use the workaround understand this
|
||||
option, so this is on a best effort basis.)
|
||||
|
||||
It's important to note that if you are storing the VM disk on a
|
||||
network filesystem or a network block device (NFS or ISCSI) it might
|
||||
not be safe to use this option. Otherwise specifying it is safe and
|
||||
can give better performances.
|
||||
|
||||
If in the future the bug is fixed properly this option will then be
|
||||
silently ignored.
|
||||
|
||||
|
||||
=item B<discard> / B<no-discard>
|
||||
|
||||
=over 4
|
||||
|
||||
=item Description
|
||||
|
||||
Request that backend advertise discard support to frontend
|
||||
|
||||
=item Supported values
|
||||
|
||||
discard, no-discard
|
||||
|
||||
=item Mandatory
|
||||
|
||||
No
|
||||
|
||||
=item Default value
|
||||
|
||||
discard
|
||||
|
||||
=back
|
||||
|
||||
An advisory setting for the backend driver, specifying whether to
|
||||
advertise discard support (TRIM, UNMAP) to the frontend. The real
|
||||
benefit of this option is to be able to force it off rather than on. It
|
||||
can be used to disable "hole punching" for file based backends which
|
||||
were intentionally created non-sparse to avoid fragmentation of the
|
||||
file.
|
||||
|
||||
=back
|
||||
|
||||
|
||||
=head1 COLO Parameters
|
||||
|
||||
=over 4
|
||||
|
||||
=item B<colo>
|
||||
|
||||
Enable COLO HA for disk. For better understanding block replication on
|
||||
QEMU, please refer to: L<http://wiki.qemu.org/Features/BlockReplication>
|
||||
Note that the COLO configuration settings should be considered unstable.
|
||||
They may change incompatibly in future versions of Xen.
|
||||
|
||||
|
||||
=item B<colo-host>
|
||||
|
||||
=over 4
|
||||
|
||||
=item Description
|
||||
|
||||
Secondary host's address
|
||||
|
||||
=item Mandatory
|
||||
|
||||
Yes when COLO enabled
|
||||
|
||||
=back
|
||||
|
||||
=item B<colo-port>
|
||||
|
||||
=over 4
|
||||
|
||||
=item Description
|
||||
|
||||
Secondary port. We will run a nbd server on secondary host,
|
||||
and the nbd server will listen this port.
|
||||
|
||||
=item Mandatory
|
||||
|
||||
Yes when COLO enabled
|
||||
|
||||
=back
|
||||
|
||||
=item B<colo-export>
|
||||
|
||||
=over 4
|
||||
|
||||
=item Description
|
||||
|
||||
We will run a nbd server on secondary host, exportname is
|
||||
the nbd server's disk export name.
|
||||
|
||||
=item Mandatory
|
||||
|
||||
Yes when COLO enabled
|
||||
|
||||
=back
|
||||
|
||||
=item B<active-disk>
|
||||
|
||||
=over 4
|
||||
|
||||
=item Description
|
||||
|
||||
This is used by secondary. Secondary guest's write will be buffered in this
|
||||
disk.
|
||||
|
||||
=item Mandatory
|
||||
|
||||
Yes when COLO enabled
|
||||
|
||||
=back
|
||||
|
||||
=item B<hidden-disk>
|
||||
|
||||
=over 4
|
||||
|
||||
=item Description
|
||||
|
||||
This is used by secondary. It buffers the original content that is modified
|
||||
by the primary VM.
|
||||
|
||||
=item Mandatory
|
||||
|
||||
Yes when COLO enabled
|
||||
|
||||
=back
|
||||
|
||||
=back
|
||||
|
||||
|
||||
=head1 Deprecated Parameters, Prefixes And Syntaxes
|
||||
|
||||
Deprecated forms are acceptable and are intended work compatibly with
|
||||
xend and xl from xen 4.1. In future they may print a warning.
|
||||
Support for deprecated parameters and syntaxes are likely to be
|
||||
dropped in future versions of xl.
|
||||
|
||||
There is support for a deprecated old syntax for C<DISKSPEC>:
|
||||
|
||||
[<format>:][<target>],<vdev>[:<devtype>],<access> (deprecated)
|
||||
|
||||
This syntax also supports deprecated prefixes, described below. These
|
||||
are found prepended to the format parameter - eg C<tap:aio:qcow:>.
|
||||
|
||||
=over 4
|
||||
|
||||
=item B<format>
|
||||
|
||||
=over 4
|
||||
|
||||
=item Description
|
||||
|
||||
Specifies the format (deprecated)
|
||||
|
||||
=item Supported values
|
||||
|
||||
raw: qcow2: vhd:
|
||||
|
||||
=back
|
||||
|
||||
In xend and old versions of libxl it was necessary to specify the
|
||||
format with a prefix. For compatibility, these three prefixes are
|
||||
recognised as specifying the corresponding format. They are
|
||||
equivalent to C<format=FORMAT> or the specification of B<format>
|
||||
(without a colon) as a positional parameter.
|
||||
|
||||
|
||||
=item B<script>
|
||||
|
||||
=over 4
|
||||
|
||||
=item Description
|
||||
|
||||
Specifies the script (deprecated)
|
||||
|
||||
=item Supported values
|
||||
|
||||
iscsi: nbd: enbd: drbd:
|
||||
|
||||
=back
|
||||
|
||||
In xend and old versions of libxl it was necessary to specify the
|
||||
"script" (see above) with a prefix. For compatibility, these four
|
||||
prefixes are recognised as specifying the corresponding script. They
|
||||
are equivalent to C<script=block-SCRIPT>.
|
||||
|
||||
|
||||
=item B<deprecated-prefix>
|
||||
|
||||
=over 4
|
||||
|
||||
=item Description
|
||||
|
||||
Deprecated prefix, ignored
|
||||
|
||||
=item Supported values
|
||||
|
||||
tapdisk: tap2: aio: ioemu: file: phy:
|
||||
|
||||
=back
|
||||
|
||||
Various prefixes were required by xend and older versions of libxl to
|
||||
make the block devices work. In some cases these options would
|
||||
override the backend type, but in other cases they would be ignored in
|
||||
favour of "making it work"; in yet other cases it would be necessary
|
||||
to specify several of these, for example:
|
||||
|
||||
tap:aio:/some/path...
|
||||
|
||||
All of these prefixes are now stripped and ignored.
|
||||
|
||||
=back
|
||||
|
||||
=head2 Missing format and empty target
|
||||
|
||||
The following syntax is also supported:
|
||||
|
||||
,<vdev>:<devtype>,<access> (deprecated)
|
||||
|
||||
This is solely for compatibility with xend's syntax for empty cdroms,
|
||||
which is (for example) C<,hdc:cdrom,r>.
|
||||
@@ -480,7 +480,7 @@ devices which the guest will contain.
|
||||
|
||||
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 F<docs/misc/xl-disk-configuration.txt>.
|
||||
the host they should map to. See L<xl-disk-configuration(5)>.
|
||||
|
||||
=item B<vif=[ "NET_SPEC_STRING", "NET_SPEC_STRING", ...]>
|
||||
|
||||
@@ -2030,7 +2030,7 @@ natively or via hardware backwards compatibility support.
|
||||
|
||||
=item L<xlcpupool.cfg(5)>
|
||||
|
||||
=item F<xl-disk-configuration>
|
||||
=item L<xl-disk-configuration(5)>
|
||||
|
||||
=item L<xl-network-configuration(5)>
|
||||
|
||||
|
||||
@@ -1315,7 +1315,7 @@ The domain id of the guest domain that the device will be attached to.
|
||||
|
||||
A disc specification in the same format used for the B<disk> variable in
|
||||
the domain config file. See
|
||||
L<http://xenbits.xen.org/docs/unstable/misc/xl-disk-configuration.txt>.
|
||||
L<xl-disk-configuration(5)>.
|
||||
|
||||
=back
|
||||
|
||||
@@ -1354,7 +1354,7 @@ How the device should be presented to the guest domain; for example "hdc".
|
||||
|
||||
the target path in the backend domain (usually domain 0) to be
|
||||
exported; Can be a block device or a file etc. See B<target> in
|
||||
F<docs/misc/xl-disk-configuration.txt>.
|
||||
L<xl-disk-configuration(5)>.
|
||||
|
||||
=back
|
||||
|
||||
@@ -1796,12 +1796,11 @@ Transcendent Memory.
|
||||
|
||||
The following man pages:
|
||||
|
||||
L<xl.cfg>(5), L<xlcpupool.cfg>(5), B<xentop>(1)
|
||||
L<xl.cfg>(5), L<xlcpupool.cfg>(5), L<xentop>(1), L<xl-disk-configuration(5)>
|
||||
L<xl-network-configuration(5)>
|
||||
|
||||
And the following documents on the xen.org website:
|
||||
|
||||
L<http://xenbits.xen.org/docs/unstable/misc/xl-disk-configuration.txt>
|
||||
L<http://xenbits.xen.org/docs/unstable/misc/xsm-flask.txt>
|
||||
L<http://xenbits.xen.org/docs/unstable/misc/xl-psr.html>
|
||||
|
||||
|
||||
@@ -1,359 +0,0 @@
|
||||
---------------------
|
||||
XL DISK CONFIGURATION
|
||||
---------------------
|
||||
|
||||
This document specifies the xl config file format disk configuration
|
||||
option. It has the following form:
|
||||
|
||||
disk = [ '<diskspec>', '<diskspec>', ... ]
|
||||
|
||||
where each diskspec is in this form:
|
||||
|
||||
[<key>=<value>|<flag>,]*,
|
||||
[<target>, [<format>, [<vdev>, [<access>]]]],
|
||||
[<key>=<value>|<flag>,]*
|
||||
[target=<target>]
|
||||
|
||||
|
||||
For example, these strings are equivalent:
|
||||
|
||||
/dev/vg/guest-volume,,hda
|
||||
/dev/vg/guest-volume,raw,hda,rw
|
||||
format=raw, vdev=hda, access=rw, target=/dev/vg/guest-volume
|
||||
raw:/dev/vg/guest-volume,hda,w (deprecated, see below)
|
||||
|
||||
As are these:
|
||||
|
||||
/root/image.iso,,hdc,cdrom
|
||||
/root/image.iso,,hdc,,cdrom
|
||||
/root/image.iso,raw,hdc,devtype=cdrom
|
||||
format=raw, vdev=hdc, access=ro, devtype=cdrom, target=/root/image.iso
|
||||
raw:/root/image.iso,hdc:cdrom,ro (deprecated, see below)
|
||||
|
||||
These might be specified in the domain config file like this:
|
||||
|
||||
disk = [ '/dev/vg/guest-volume,,hda', '/root/image.iso,,hdc,cdrom' ]
|
||||
|
||||
|
||||
More formally, the string is a series of comma-separated keyword/value
|
||||
pairs, flags and positional parameters. Parameters which are not bare
|
||||
keywords and which do not contain "=" symbols are assigned to the
|
||||
so-far-unspecified positional parameters, in the order below. The
|
||||
positional parameters may also be specified explicitly by name.
|
||||
|
||||
Each parameter may be specified at most once, either as a positional
|
||||
parameter or a named parameter. Default values apply if the parameter
|
||||
is not specified, or if it is specified with an empty value (whether
|
||||
positionally or explicitly).
|
||||
|
||||
Whitespace may appear before each parameter and will be ignored.
|
||||
|
||||
|
||||
=====================
|
||||
POSITIONAL PARAMETERS
|
||||
=====================
|
||||
|
||||
target
|
||||
------
|
||||
|
||||
Description: Block device or image file path. When this is
|
||||
used as a path, /dev will be prepended
|
||||
if the path doesn't start with a '/'.
|
||||
Supported values: N/A
|
||||
Deprecated values: N/A
|
||||
Default value: None. While a path is provided in most cases
|
||||
there is an exception: for a cdrom device, lack
|
||||
of this attribute would imply an empty cdrom
|
||||
drive.
|
||||
|
||||
Special syntax:
|
||||
|
||||
When this parameter is specified by name, ie with the "target="
|
||||
syntax in the configuration file, it consumes the whole rest of the
|
||||
<diskspec> including trailing whitespaces. Therefore in that case
|
||||
it must come last. This is permissible even if an empty value for
|
||||
the target was already specified as a positional parameter. This
|
||||
is the only way to specify a target string containing metacharacters
|
||||
such as commas and (in some cases) colons, which would otherwise be
|
||||
misinterpreted.
|
||||
|
||||
Future parameter and flag names will start with an ascii letter and
|
||||
contain only ascii alphanumerics, hyphens and underscores, and will
|
||||
not be legal as vdevs. Targets which might match that syntax
|
||||
should not be specified as positional parameters.
|
||||
|
||||
|
||||
format
|
||||
------
|
||||
|
||||
Description: Specifies the format of image file.
|
||||
Supported values: raw, qcow, qcow2, vhd, qed
|
||||
Deprecated values: None
|
||||
Default value: raw
|
||||
|
||||
|
||||
vdev
|
||||
----
|
||||
|
||||
Description: Virtual device as seen by the guest (also
|
||||
referred to as guest drive designation in some
|
||||
specifications). See docs/misc/vbd-interface.txt.
|
||||
Supported values: hd[x], xvd[x], sd[x] etc. Please refer to the
|
||||
above specification for further details.
|
||||
Deprecated values: None
|
||||
Default Value: None, this parameter is mandatory.
|
||||
|
||||
|
||||
access
|
||||
-------
|
||||
|
||||
Description: Specified access control information. Whether
|
||||
or not the block device is provided to the
|
||||
guest in read-only or read-write mode depends
|
||||
on this attribute.
|
||||
Supported values: ro, r (specifies read-only)
|
||||
rw, w (specifies read/write)
|
||||
Deprecated values: None
|
||||
Default value: rw
|
||||
unless devtype=cdrom, in which case r
|
||||
|
||||
|
||||
|
||||
==========================
|
||||
OTHER PARAMETERS AND FLAGS
|
||||
==========================
|
||||
|
||||
|
||||
devtype=<devtype>
|
||||
-----------------
|
||||
|
||||
Description: Qualifies virtual device type.
|
||||
Supported values: cdrom
|
||||
Deprecated values: None
|
||||
Mandatory: No
|
||||
|
||||
|
||||
cdrom
|
||||
-----
|
||||
|
||||
Convenience alias for "devtype=cdrom".
|
||||
|
||||
|
||||
backend=<domain-name>
|
||||
---------------------
|
||||
|
||||
Description: Designates a backend domain for the device
|
||||
Supported values: Valid domain names
|
||||
Mandatory: No
|
||||
|
||||
Specifies the backend domain which this device should attach to. This
|
||||
defaults to domain 0. Specifying another domain requires setting up a
|
||||
driver domain which is outside the scope of this document.
|
||||
|
||||
|
||||
backendtype=<backend-type>
|
||||
--------------------------
|
||||
|
||||
Description: Specifies the backend implementation to use
|
||||
Supported values: phy, tap, qdisk
|
||||
Mandatory: No
|
||||
Default value: Automatically determine which backend to use.
|
||||
|
||||
This does not affect the guest's view of the device. It controls
|
||||
which software implementation of the Xen backend driver is used.
|
||||
|
||||
Not all backend drivers support all combinations of other options.
|
||||
For example, "phy" does not support formats other than "raw".
|
||||
Normally this option should not be specified, in which case libxl will
|
||||
automatically determine the most suitable backend.
|
||||
|
||||
|
||||
script=<script>
|
||||
---------------
|
||||
|
||||
Specifies that <target> is not a normal host path, but rather
|
||||
information to be interpreted by the executable program <script>,
|
||||
(looked for in /etc/xen/scripts, if it doesn't contain a slash).
|
||||
|
||||
These scripts are normally called "block-<script>".
|
||||
|
||||
|
||||
direct-io-safe
|
||||
--------------
|
||||
|
||||
Description: Disables non-O_DIRECT workaround
|
||||
Supported values: absent, present
|
||||
Mandatory: No
|
||||
Default value: absent (workaround may be enabled)
|
||||
|
||||
There is a memory lifetime bug in some driver domain (dom0) kernels
|
||||
which can cause crashes when using O_DIRECT. The bug occurs due to a
|
||||
mismatch between the backend-visible lifetime of pages used for the
|
||||
Xen PV network protocol and that expected by the backend kernel's
|
||||
networking subsystem. This can cause crashes when using certain
|
||||
backends with certain underlying storage.
|
||||
|
||||
See:
|
||||
http://lists.xen.org/archives/html/xen-devel/2012-12/msg01154.html
|
||||
|
||||
For this reason, (this version of) the Xen libxl toolstack disables
|
||||
O_DIRECT when using the qemu-based Xen PV backend ("qdisk").
|
||||
|
||||
However, this workaround has performance and scaling implications, and
|
||||
it is only necessary if the underlying device is a network filesystem.
|
||||
If the underlying device is not, then it is good to disable it; that
|
||||
is what this option is for.
|
||||
|
||||
This option simply requests that the workaround be disabled. (However,
|
||||
not all backends versions which use the workaround understand this
|
||||
option, so this is on a best effort basis.)
|
||||
|
||||
It's important to note that if you are storing the VM disk on a
|
||||
network filesystem or a network block device (NFS or ISCSI) it might
|
||||
not be safe to use this option. Otherwise specifying it is safe and
|
||||
can give better performances.
|
||||
|
||||
If in the future the bug is fixed properly this option will then be
|
||||
silently ignored.
|
||||
|
||||
|
||||
discard / no-discard
|
||||
---------------
|
||||
|
||||
Description: Request that backend advertise discard support to frontend
|
||||
Supported values: discard
|
||||
no-discard
|
||||
Mandatory: No
|
||||
Default value: discard
|
||||
|
||||
An advisory setting for the backend driver, specifying whether to
|
||||
advertise discard support (TRIM, UNMAP) to the frontend. The real
|
||||
benefit of this option is to be able to force it off rather than on. It
|
||||
can be used to disable "hole punching" for file based backends which
|
||||
were intentionally created non-sparse to avoid fragmentation of the
|
||||
file.
|
||||
|
||||
|
||||
===============
|
||||
COLO PARAMETERS
|
||||
===============
|
||||
|
||||
|
||||
colo
|
||||
----
|
||||
|
||||
Enable COLO HA for disk. For better understanding block replication on
|
||||
QEMU, please refer to:
|
||||
http://wiki.qemu.org/Features/BlockReplication
|
||||
Note that the COLO configuration settings should be considered unstable.
|
||||
They may change incompatibly in future versions of Xen.
|
||||
|
||||
|
||||
colo-host
|
||||
---------
|
||||
|
||||
Description: Secondary host's address
|
||||
Mandatory: Yes when COLO enabled
|
||||
|
||||
|
||||
colo-port
|
||||
---------
|
||||
|
||||
Description: Secondary port
|
||||
We will run a nbd server on secondary host,
|
||||
and the nbd server will listen this port.
|
||||
Mandatory: Yes when COLO enabled
|
||||
|
||||
|
||||
colo-export
|
||||
-----------
|
||||
|
||||
Description: We will run a nbd server on secondary host,
|
||||
exportname is the nbd server's disk export name.
|
||||
Mandatory: Yes when COLO enabled
|
||||
|
||||
|
||||
active-disk
|
||||
-----------
|
||||
|
||||
Description: This is used by secondary. Secondary guest's write
|
||||
will be buffered in this disk.
|
||||
Mandatory: Yes when COLO enabled
|
||||
|
||||
|
||||
hidden-disk
|
||||
-----------
|
||||
|
||||
Description: This is used by secondary. It buffers the original
|
||||
content that is modified by the primary VM.
|
||||
Mandatory: Yes when COLO enabled
|
||||
|
||||
|
||||
============================================
|
||||
DEPRECATED PARAMETERS, PREFIXES AND SYNTAXES
|
||||
============================================
|
||||
|
||||
Deprecated forms are acceptable and are intended work compatibly with
|
||||
xend and xl from xen 4.1. In future they may print a warning.
|
||||
Support for deprecated parameters and syntaxes are likely to be
|
||||
dropped in future versions of xl.
|
||||
|
||||
|
||||
There is support for a deprecated old syntax for <diskspec>:
|
||||
|
||||
[<format>:][<target>],<vdev>[:<devtype>],<access> (deprecated)
|
||||
|
||||
This syntax also supports deprecated prefixes, described below. These
|
||||
are found prepended to the format parameter - eg "tap:aio:qcow:".
|
||||
|
||||
|
||||
<format>:
|
||||
---------
|
||||
|
||||
Description: Specifies the format (deprecated)
|
||||
Supported values: raw: qcow2: vhd:
|
||||
|
||||
In xend and old versions of libxl it was necessary to specify the
|
||||
format with a prefix. For compatibility, these three prefixes are
|
||||
recognised as specifying the corresponding format. They are
|
||||
equivalent to "format=<format>" or the specification of <format>
|
||||
(without a colon) as a positional parameter.
|
||||
|
||||
|
||||
<script>:
|
||||
---------
|
||||
|
||||
Description: Specifies the script (deprecated)
|
||||
Supported values: iscsi: nbd: enbd: drbd:
|
||||
|
||||
In xend and old versions of libxl it was necessary to specify the
|
||||
"script" (see above) with a prefix. For compatibility, these four
|
||||
prefixes are recognised as specifying the corresponding script. They
|
||||
are equivalent to "script=block-<script>".
|
||||
|
||||
|
||||
<deprecated-prefix>:
|
||||
--------------------
|
||||
|
||||
Description; Deprecated prefix, ignored
|
||||
Supported values: tapdisk: tap2: aio: ioemu: file: phy:
|
||||
|
||||
Various prefixes were required by xend and older versions of libxl to
|
||||
make the block devices work. In some cases these options would
|
||||
override the backend type, but in other cases they would be ignored in
|
||||
favour of "making it work"; in yet other cases it would be necessary
|
||||
to specify several of these, for example:
|
||||
"tap:aio:/some/path..."
|
||||
|
||||
All of these prefixes are now stripped and ignored.
|
||||
|
||||
|
||||
Missing format and empty target
|
||||
-------------------------------
|
||||
|
||||
The following syntax is also supported:
|
||||
|
||||
,<vdev>:<devtype>,<access> (deprecated)
|
||||
|
||||
This is soley for compatibility with xend's syntax for empty cdroms,
|
||||
which is (for example) ",hdc:cdrom,r".
|
||||