Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
xl-disk-configuration(5)	      Xen	      xl-disk-configuration(5)

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).  See
	       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, 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:
	    <https://lists.xenproject.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:
	   <https://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".

4.14.0				  2020-07-23	      xl-disk-configuration(5)

NAME | SYNTAX | Positional Parameters | Other Parameters And Flags | COLO Parameters | Deprecated Parameters, Prefixes And Syntaxes

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=xl-disk-configuration&sektion=5&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help