Provided by: xen-utils-common_4.11.3+24-g14b62ab3e5-1ubuntu2.3_amd64 bug

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).  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".