From e1b72a3b741bba7eeabf17adb6519baee6649f18 Mon Sep 17 00:00:00 2001 From: Ian Jackson Date: Tue, 28 Jun 2011 12:19:13 +0100 Subject: docs: update xl-disk-configuration.txt to describe new syntax Signed-off-by: Ian Jackson Committed-by: Ian Jackson --- docs/misc/xl-disk-configuration.txt | 249 ++++++++++++++++++++++-------------- 1 file changed, 150 insertions(+), 99 deletions(-) (limited to 'docs/misc') diff --git a/docs/misc/xl-disk-configuration.txt b/docs/misc/xl-disk-configuration.txt index 58332a9f6c..de0a75e1bc 100644 --- a/docs/misc/xl-disk-configuration.txt +++ b/docs/misc/xl-disk-configuration.txt @@ -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 = [ '', '', ... ] -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: + + [=|,]*, + [, [, [, []]]], + [=|,]* + [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' ] -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: ----- -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 '/'. +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 -Mandatory: No. While a path is provided in most cases - there is an exception. For a cdrom device, lack +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. -vdev: +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 + . 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 @@ -60,95 +101,105 @@ Description: Virtual device as seen by the guest (also 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: ----- - -Description: Qualifies virtual device type. -Supported values: cdrom -Deprecated values: None -Mandatory: No -attrib: ------- +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: 'r', 'w' +Supported values: ro, r (specifies read-only) + rw, w (specifies read/write) Deprecated values: None -Mandatory: Yes +Default value: rw + unless devtype=cdrom, in which case r --------------- -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' ] +========================== +OTHER PARAMETERS AND FLAGS +========================== -------------------------- -Miscellaneous Information -------------------------- +devtype= +----------------- ---------------------- -Deprecated Attributes ---------------------- +Description: Qualifies virtual device type. +Supported values: cdrom +Deprecated values: None +Mandatory: No -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: +cdrom +----- -block-dev-type: --------------- +Convenience alias for "devtype=cdrom". -Description: Specifies the block device type. -Supported values: phy,file, tap, tap2 -access-type: ------------ +script=