NAME
xl-disk-configuration - XL Disk Configuration Syntax
SYNTAX
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
xen-vbd-interface(7).
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=*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 solely for compatibility with xend's syntax for empty cdroms,
which is (for example) ",hdc:cdrom,r".
