WARNING - OLD ARCHIVES

This is an archived copy of the Xen.org mailing list, which we have preserved to ensure that existing links to archives are not broken. The live archive, which contains the latest emails, can be found at http://lists.xen.org/
   
 
 
Xen 
 
Home Products Support Community News
 
   
 

xen-changelog

[Xen-changelog] [xen-unstable] docs: update xl-disk-configuration.txt to

To: xen-changelog@xxxxxxxxxxxxxxxxxxx
Subject: [Xen-changelog] [xen-unstable] docs: update xl-disk-configuration.txt to describe new syntax
From: Xen patchbot-unstable <patchbot@xxxxxxx>
Date: Fri, 08 Jul 2011 06:22:16 +0100
Delivery-date: Thu, 07 Jul 2011 22:25:40 -0700
Envelope-to: www-data@xxxxxxxxxxxxxxxxxxx
List-help: <mailto:xen-changelog-request@lists.xensource.com?subject=help>
List-id: BK change log <xen-changelog.lists.xensource.com>
List-post: <mailto:xen-changelog@lists.xensource.com>
List-subscribe: <http://lists.xensource.com/mailman/listinfo/xen-changelog>, <mailto:xen-changelog-request@lists.xensource.com?subject=subscribe>
List-unsubscribe: <http://lists.xensource.com/mailman/listinfo/xen-changelog>, <mailto:xen-changelog-request@lists.xensource.com?subject=unsubscribe>
Reply-to: xen-devel@xxxxxxxxxxxxxxxxxxx
Sender: xen-changelog-bounces@xxxxxxxxxxxxxxxxxxx
# HG changeset patch
# User Ian Jackson <ian.jackson@xxxxxxxxxxxxx>
# Date 1309259953 -3600
# Node ID e13db1e55971a97c2045e17a09c2d7ce8f8e9800
# Parent  8510fe013fdb4edd0977fffea092b92abfa8a39c
docs: update xl-disk-configuration.txt to describe new syntax

Signed-off-by: Ian Jackson <ian.jackson@xxxxxxxxxxxxx>
Committed-by: Ian Jackson <Ian.Jackson@xxxxxxxxxxxxx>
---


diff -r 8510fe013fdb -r e13db1e55971 docs/misc/xl-disk-configuration.txt
--- a/docs/misc/xl-disk-configuration.txt       Tue Jun 28 12:19:12 2011 +0100
+++ b/docs/misc/xl-disk-configuration.txt       Tue Jun 28 12:19:13 2011 +0100
@@ -1,57 +1,98 @@
+                     ---------------------
+                     XL DISK CONFIGURATION
+                     ---------------------
 
+This document specifies the xl config file format disk configuration
+option.  It has the following form:
 
-                         ----------------------------
-                         xl Disk Configuration Option
-                         ----------------------------
+    disk = [ '<diskspec>', '<diskspec>', ... ]
 
-This document provides a brief description of xl disk configuration
-option, different attributes that can be passed through it and the
-format in which they need to be specified.
+where each diskspec is in this form:
+    
+   [<key>=<value>|<flag>,]*,
+     [<target>, [<format>, [<vdev>, [<access>]]]],
+     [<key>=<value>|<flag>,]*
+     [target=<target>]
 
-At a higher level, xl disk configuration option takes the following
-format:
 
-    disk = [ '[format:][path],vdev[:type],attrib',
-             '[format:][path],vdev[:type],attrib', ... ]
+For example, these strings are equivalent:
 
-Not all attributes are required (the attributes enclosed within square
-brackets above are optional) and some are deprecated.  Following is a
-brief description of each of the attribute along with information on
-whether or not they are mandatory.
+  /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:
 
-------------------
-Attribute Details
-------------------
+  /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:
 
-format:
+  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
-Mandatory:             No.  When not specified raw format is assumed.
-                       For a physical block device the format must be
-                       raw and need not be explicitly specified.  For
-                       an image file the format could be one of the
-                       supported values and when not specified assumed
-                       to be raw.
-path:
-----
+Default value:         raw
 
-Description:           Block  device or image file path.  For a
-                       physical block device a /dev  will be prepended
-                       when not specified and when the path doesn't
-                       start  with a '/'.
-Supported values:      N/A
-Deprecated values:     N/A
-Mandatory:             No.  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.
 
-vdev:
+vdev
 ----
 
 Description:           Virtual device as seen by the guest (also
@@ -60,95 +101,105 @@
 Supported values:      hd[x], xvd[x], sd[x] etc.  Please refer to the
                        above specification for further details.
 Deprecated values:     None
-Mandatory:             Yes
+Default Value:         None, this parameter is mandatory.
 
-type:
-----
+
+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
 
-attrib:
-------
 
-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:      'r', 'w'
-Deprecated values:     None
-Mandatory:             Yes
+cdrom
+-----
 
+Convenience alias for "devtype=cdrom".
 
---------------
-Example usages
---------------
 
-disk = [ 'vhd:/path/to/dev,hda,w', '/path/to/iso,hdc:cdrom,r' ]
-disk = [ 'path/to/phy/dev,hda,w', '/dev/cdrom,hdc:cdrom,r' ]
-disk = [ 'qcow:/path/to/file,hda,w' ]
-disk = [ 'qcow2:/path/to/file,hda,w', 'raw:/path/to/dev,hdc:cdrom,r' ]
-
-
--------------------------
-Miscellaneous Information
--------------------------
-
----------------------
-Deprecated Attributes
----------------------
-
-Deprecated values are acceptable and will work the way they did
-earlier except with a warning message printed to the xl log or screen.
-However it's usage is supported purely for backward compatibility
-purpose and not recommended. Also, support for these deprecated
-attributes are likely to be dropped in future versions of xl.
-
-The block-dev-type and access-type deprecated attributes described
-below are prepended to the format attribute.  Example - tap:aio:qcow
-Further details on the deprecated attributes are below:
-
-block-dev-type:
---------------
-
-Description:           Specifies the block device type.
-Supported values:      phy,file, tap, tap2
-
-access-type:
------------
-
-Description:           Backend implementation option to choose from
-                       while accessing block device.
-                       Example: tap:aio:vhd:/path/to/file
-Supported values:      'aio', 'tapdisk', 'ioemu'
-
----------------------
-Impementation Details
----------------------
-
-Backend Details:
+script=<script>
 ---------------
 
-For 'phy' block device type, blkback is always used as the backend.
-When the running dom0 instance does not support blkback, block device
-access will fail.  For block device type 'file' with format raw or
-when no format specfied, tapdisk2 is used when present otherwise qemu
-fallback option is used.  For 'file', 'tap' or 'tap2' block device
-type with format 'vhd', only tapdisk2 is used as qemu does not support
-vhd format.  Absence of tapdisk2 support in this case will result in
-failure.  When it comes to image format and how that affects the
-backend choice, for qcow/qcow2 qemu backend is used as tapdisk2 does
-not work with these formats. For raw format image file, tapdisk2 is
-used and when not available qemu backend is used as fallback.  For vhd
-format, as mentioned earlier tapdisk2 is used and tapdisk2
-unavailability will result in failure as qemu fallback option does not
-support vhd file format.
+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.

_______________________________________________
Xen-changelog mailing list
Xen-changelog@xxxxxxxxxxxxxxxxxxx
http://lists.xensource.com/xen-changelog

<Prev in Thread] Current Thread [Next in Thread>
  • [Xen-changelog] [xen-unstable] docs: update xl-disk-configuration.txt to describe new syntax, Xen patchbot-unstable <=