util/git-hooks/applypatch-msg


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
                     ---------------------
                     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>.  Therefore in that case it must come last.  This is
   permissible even if an empty value for the target was already
   specifed 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
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".


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 us 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 /etc/xen/scripts/block-<script>.


==================================
DEPRECATED PARAMETERS AND PREFIXES
==================================

Deprecated values 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 also 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=<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.