xen-project/xen
1
0 Fork 1
mirror of https://github.com/xen-project/xen.git synced 2026-10-29 18:50:05 +01:00
Code Issues Activity
Files
e245bf1dbaffea88bc4d4bd1545dca77fc5ca0b0
xen/docs/misc/xl-disk-configuration.txt
T
Ian Campbell 6e844c2af0 libxl: support custom block hotplug scripts 
These are provided using the "script=" syntax described in
docs/misc/xl-disk-configuration.txt.

The existing hotplug scripts currently conflate two different
concepts, namely that of making a datapath available in the backend
domain (logging into iSCSI LUNs and the like) and that of actually
connecting that datapath to a Xen backend path (e.g. writing
"physical-device" node in xenstore to bring up blkback).

For this reason the script support implemented here is only supported
in conjunction with backendtype=phy.

Eventually we hope to rework the hotplug scripts to separate the to
concepts, but that is not 4.2 material.

In addition there are some other subtleties:

 - Previously in the blktap case we would add "script = .../blktap" to
   the backend flex array, but then jumped to the PHY case which added
   "script = .../block" too. The block one takes precendence since it
   comes second.

   This was, accidentally, correct. The blktap script is for blktap1
   devices and not blktap2 devices. libxl completely manages the
   blktap2 side of things without resorting to hotplug scripts and
   creates a blkback device directly.  Therefore the "block" script is
   always the correct one to call. Custom script are not supported in
   this context.

 - libxl should not write the "physical-device" node. This is the
   responsibility of the block script. Writing the "physical-device"
   node in libxl basically completely short-cuts the standard block
   hotplug script which uses "physical-device" to know if it has run
   already or not.

   In the case of more complex scripts libxl cannot know the right
   value to write here anyway, in particular the device may not exist
   until after the script is called.

   This change has the side effect of re-enabling the checks for
   device sharing aspect of the default block script, which I have tested
   and which now cause libxl to properly abort now that libxl properly
   checks for hotplug script errors.

   There is no sharing check for blktap2 since even if you reuse the
   same vhd the resulting tap device is different. I would have preferred
   to simply write the "physical-device" node for the blktap2 case but
   the hotplug script infrastructure is not currently setup to handle
   LIBXL__DEVICE_KIND_VBD
   devices without a hotplug script (backendtype phy and tap both end
   up as KIND_VBD). Changing this was more surgery than I was happy doing
   for 4.2 and therefore I have simply hardcoded to the block script for
   the LIBXL_DISK_BACKEND_TAP case.

 - libxl__device_disk_set_backend running against a phy device with a
   script cannot stat the device to check its properties since it may
   not exist until the script is run. Therefore I have special cased
   this in disk_try_backend to simply assume that backend == phy is
   always ok if a script was
   configured.  Similarly the other backend types are always rejected
   if a script was configured.

   Note that the reason for implementing the default script behaviour
   in device_disk_add instead of libxl__device_disk_setdefault is
   because we need to be able to tell when the script was
   user-supplied rather than defaulted by libxl in order to correctly
   implement the above. The setdefault function must be idempotent so
   we cannot simply update disk->script.

   I suspect that for 4.3 a script member should be added to
   libxl__device, this would also help in the case above of handling
   devices with no script in a consistent manner. This is not 4.2
   material.

 - When the block script falls through and shells out to a block-$type
   script it used to pass "$node" however the only place this was
   assigned was in the remove+phy case (in which case it contains the
   file:// derived /dev/loopN device), and in that case the script
   exits without falling through to the block-$type case.

   Since libxl never creates a type other than phy this never happens
   in practice anyway and we now call the correct block-$type script
   directly.  But fix it up anyway since it is confusing.

 - The block-nbd and block-enbd scripts which we supply appear to be
   broken WRT the hotplug calling convention, in that they seem to
   expect a command line parameter (perhaps the $node described above)
   rather than reading the appropriate node from xenstore.

   I rather suspect this was broken by 7774:e2e7f47e6f79 in November
   2005. I think it is safe to say no one is using these scripts! I
   haven't fixed this here. It would be good to track down some working
   scripts and either incorproate them or defer to them in their existing
   home (e.g. if they live somewhere useful like the nbd tools
   package).

 - Added a few block script related entries to check-xl-disk-parse
   from http://backdrift.org/xen-block-iscsi-script-with-multipath-support
   and http://lists.linbit.com/pipermail/drbd-user/2008-September/010221.html /
   http://www.drbd.org/users-guide-emb/s-xen-configure-domu.html (and
   snuck in another interesting empty CDROM case)

   This highlighted two bugs in the libxlu disk parser handling of the
   deprecated "<script>:" prefix:

   - It was failing to prefix with "block-" to construct the actual
     script name

   - The regex for matching iscsi or drdb or e?nbd was incorrect

 - Use libxl__abs_path for the nic script too. Just because the
   existing code nearly tricked me into repeating the mistake

I have tested with a custom block script which uses "lvchange -a" to
dynamically add remove the referenced device (simulates iSCSI
login/logout without requiring me to faff around setting up an iSCSI
target). I also tested on a blktap2 system.

I haven't directly tested anything more complex like iscsi: or nbd:
other than what check-xl-disk-parse exercises.

[ Recommit of correct version of 25727:a8d708fcb347, which was mangled
  during commit.  Sorry. -iwj ]

Signed-off-by: Ian Campbell <ian.campbell@citrix.com>
Acked-by: Ian Jackson <ian.jackson@eu.citrix.com>
Committed-by: Ian Jackson <ian.jackson@eu.citrix.com>
2012-08-06 12:28:03 +01:00

238 lines
7.5 KiB
Plaintext
Raw Blame History

---------------------
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
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
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 the executable program <script>,
(looked for in /etc/xen/scripts, if it doesn't contain a slash).
These scripts are normally called "block-<script>".
============================================
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 soley for compatibility with xend's syntax for empty cdroms,
which is (for example) ",hdc:cdrom,r".
Reference in new issue View Git Blame Copy Permalink