1xl-disk-configuration(5)              Xen             xl-disk-configuration(5)
2
3
4

NAME

6       xl-disk-configuration - XL Disk Configuration Syntax
7

SYNTAX

9       This document specifies the xl config file format disk configuration
10       option.  It has the following form:
11
12          disk = [ 'DISKSPEC', 'DISKSPEC', ... ]
13
14       where each "DISKSPEC" is in this form:
15
16          [<key>=<value>|<flag>,]*,
17            [<target>, [<format>, [<vdev>, [<access>]]]],
18            [<key>=<value>|<flag>,]*
19            [target=<target>]
20
21       For example, these strings are equivalent:
22
23           /dev/vg/guest-volume,,hda
24           /dev/vg/guest-volume,raw,hda,rw
25           format=raw, vdev=hda, access=rw, target=/dev/vg/guest-volume
26           raw:/dev/vg/guest-volume,hda,w  (deprecated, see below)
27
28       As are these:
29
30           /root/image.iso,,hdc,cdrom
31           /root/image.iso,,hdc,,cdrom
32           /root/image.iso,raw,hdc,devtype=cdrom
33           format=raw, vdev=hdc, access=ro, devtype=cdrom, target=/root/image.iso
34           raw:/root/image.iso,hdc:cdrom,ro   (deprecated, see below)
35
36       These might be specified in the domain config file like this:
37
38           disk = [ '/dev/vg/guest-volume,,hda', '/root/image.iso,,hdc,cdrom' ]
39
40       More formally, the string is a series of comma-separated keyword/value
41       pairs, flags and positional parameters.  Parameters which are not bare
42       keywords and which do not contain "=" symbols are assigned to the so-
43       far-unspecified positional parameters, in the order below.  The
44       positional parameters may also be specified explicitly by name.
45
46       Each parameter may be specified at most once, either as a positional
47       parameter or a named parameter.  Default values apply if the parameter
48       is not specified, or if it is specified with an empty value (whether
49       positionally or explicitly).
50
51       Whitespace may appear before each parameter and will be ignored.
52

Positional Parameters

54       target
55           Description
56               Block device or image file path.  When this is used as a path,
57               /dev will be prepended if the path doesn't start with a '/'.
58
59           Supported values
60               N/A
61
62           Deprecated values
63               N/A
64
65           Default value
66               None.  While a path is provided in most cases there is an
67               exception: for a cdrom device, lack of this attribute would
68               imply an empty cdrom drive.
69
70           Special syntax
71               When this parameter is specified by name, ie with the "target="
72               syntax in the configuration file, it consumes the whole rest of
73               the "DISKSPEC" including trailing whitespaces.  Therefore in
74               that case it must come last.  This is permissible even if an
75               empty value for the target was already specified as a
76               positional parameter.  This is the only way to specify a target
77               string containing metacharacters such as commas and (in some
78               cases) colons, which would otherwise be misinterpreted.
79
80               Future parameter and flag names will start with an ascii letter
81               and contain only ascii alphanumerics, hyphens and underscores,
82               and will not be legal as vdevs.  Targets which might match that
83               syntax should not be specified as positional parameters.
84
85       format
86           Description
87               Specifies the format of image file.
88
89           Supported values
90               raw, qcow, qcow2, vhd, qed
91
92           Deprecated values
93               None
94
95           Default value
96               raw
97
98       vdev
99           Description
100               Virtual device as seen by the guest (also referred to as guest
101               drive designation in some specifications).  See
102               xen-vbd-interface(7).
103
104           Supported values
105               hd[x], xvd[x], sd[x] etc.  Please refer to the above
106               specification for further details.
107
108           Deprecated values
109               None
110
111           Default Value
112               None, this parameter is mandatory.
113
114       access
115           Description
116               Specified access control information.  Whether or not the block
117               device is provided to the guest in read-only or read-write mode
118               depends on this attribute.
119
120           Supported values
121               "ro", "r"   (specifies read-only)
122
123               "rw", "w"   (specifies read/write)
124
125           Deprecated values
126               None
127
128           Default value
129               "rw" unless devtype=cdrom, in which case "r"
130

Other Parameters And Flags

132       devtype=DEVTYPE
133           Description
134               Qualifies virtual device type.
135
136           Supported values
137               cdrom
138
139           Deprecated values
140               None
141
142           Mandatory
143               No
144
145       cdrom
146           Convenience alias for "devtype=cdrom".
147
148       backend=DOMAIN-NAME
149           Description
150               Designates a backend domain for the device
151
152           Supported values
153               Valid domain names
154
155           Mandatory
156               No
157
158           Specifies the backend domain which this device should attach to.
159           This defaults to domain 0. Specifying another domain requires
160           setting up a driver domain which is outside the scope of this
161           document.
162
163       backendtype=TYPE
164           Description
165               Specifies the backend implementation to use
166
167           Supported values
168               phy, qdisk
169
170           Mandatory
171               No
172
173           Default value
174               Automatically determine which backend to use.
175
176           This does not affect the guest's view of the device.  It controls
177           which software implementation of the Xen backend driver is used.
178
179           Not all backend drivers support all combinations of other options.
180           For example, "phy" does not support formats other than "raw".
181           Normally this option should not be specified, in which case libxl
182           will automatically determine the most suitable backend.
183
184       script=SCRIPT
185           Specifies that target is not a normal host path, but rather
186           information to be interpreted by the executable program SCRIPT,
187           (looked for in /etc/xen/scripts, if it doesn't contain a slash).
188
189           These scripts are normally called "block-SCRIPT".
190
191       direct-io-safe
192           Description
193               Disables non-O_DIRECT workaround
194
195           Supported values
196               absent, present
197
198           Mandatory
199               No
200
201           Default value
202               absent (workaround may be enabled)
203
204           There is a memory lifetime bug in some driver domain (dom0) kernels
205           which can cause crashes when using O_DIRECT.  The bug occurs due to
206           a mismatch between the backend-visible lifetime of pages used for
207           the Xen PV network protocol and that expected by the backend
208           kernel's networking subsystem.  This can cause crashes when using
209           certain backends with certain underlying storage.
210
211           See:
212            <https://lists.xenproject.org/archives/html/xen-devel/2012-12/msg01154.html>
213
214           For this reason, (this version of) the Xen libxl toolstack disables
215           O_DIRECT when using the qemu-based Xen PV backend ("qdisk").
216
217           However, this workaround has performance and scaling implications,
218           and it is only necessary if the underlying device is a network
219           filesystem.  If the underlying device is not, then it is good to
220           disable it; that is what this option is for.
221
222           This option simply requests that the workaround be disabled.
223           (However, not all backends versions which use the workaround
224           understand this option, so this is on a best effort basis.)
225
226           It's important to note that if you are storing the VM disk on a
227           network filesystem or a network block device (NFS or ISCSI) it
228           might not be safe to use this option.  Otherwise specifying it is
229           safe and can give better performances.
230
231           If in the future the bug is fixed properly this option will then be
232           silently ignored.
233
234       discard / no-discard
235           Description
236               Request that backend advertise discard support to frontend
237
238           Supported values
239               discard, no-discard
240
241           Mandatory
242               No
243
244           Default value
245               discard
246
247           An advisory setting for the backend driver, specifying whether to
248           advertise discard support (TRIM, UNMAP) to the frontend.  The real
249           benefit of this option is to be able to force it off rather than
250           on.  It can be used to disable "hole punching" for file based
251           backends which were intentionally created non-sparse to avoid
252           fragmentation of the file.
253

COLO Parameters

255       colo
256           Enable COLO HA for disk. For better understanding block replication
257           on QEMU, please refer to:
258           <https://wiki.qemu.org/Features/BlockReplication> Note that the
259           COLO configuration settings should be considered unstable.  They
260           may change incompatibly in future versions of Xen.
261
262       colo-host
263           Description
264               Secondary host's address
265
266           Mandatory
267               Yes when COLO enabled
268
269       colo-port
270           Description
271               Secondary port.  We will run a nbd server on secondary host,
272               and the nbd server will listen this port.
273
274           Mandatory
275               Yes when COLO enabled
276
277       colo-export
278           Description
279               We will run a nbd server on secondary host, exportname is the
280               nbd server's disk export name.
281
282           Mandatory
283               Yes when COLO enabled
284
285       active-disk
286           Description
287               This is used by secondary. Secondary guest's write will be
288               buffered in this disk.
289
290           Mandatory
291               Yes when COLO enabled
292
293       hidden-disk
294           Description
295               This is used by secondary. It buffers the original content that
296               is modified by the primary VM.
297
298           Mandatory
299               Yes when COLO enabled
300

Deprecated Parameters, Prefixes And Syntaxes

302       Deprecated forms are acceptable and are intended work compatibly with
303       xend and xl from xen 4.1.  In future they may print a warning.  Support
304       for deprecated parameters and syntaxes are likely to be dropped in
305       future versions of xl.
306
307       There is support for a deprecated old syntax for "DISKSPEC":
308
309         [<format>:][<target>],<vdev>[:<devtype>],<access>   (deprecated)
310
311       This syntax also supports deprecated prefixes, described below.  These
312       are found prepended to the format parameter - eg "tap:aio:qcow:".
313
314       format
315           Description
316               Specifies the format (deprecated)
317
318           Supported values
319               raw:  qcow2:  vhd:
320
321           In xend and old versions of libxl it was necessary to specify the
322           format with a prefix.  For compatibility, these three prefixes are
323           recognised as specifying the corresponding format.  They are
324           equivalent to "format=FORMAT" or the specification of format
325           (without a colon) as a positional parameter.
326
327       script
328           Description
329               Specifies the script (deprecated)
330
331           Supported values
332               iscsi:  nbd:  enbd:  drbd:
333
334           In xend and old versions of libxl it was necessary to specify the
335           "script" (see above) with a prefix.  For compatibility, these four
336           prefixes are recognised as specifying the corresponding script.
337           They are equivalent to "script=block-SCRIPT".
338
339       deprecated-prefix
340           Description
341               Deprecated prefix, ignored
342
343           Supported values
344               tapdisk:  tap2:  aio:  ioemu:  file:  phy:
345
346           Various prefixes were required by xend and older versions of libxl
347           to make the block devices work.  In some cases these options would
348           override the backend type, but in other cases they would be ignored
349           in favour of "making it work"; in yet other cases it would be
350           necessary to specify several of these, for example:
351
352             tap:aio:/some/path...
353
354           All of these prefixes are now stripped and ignored.
355
356   Missing format and empty target
357       The following syntax is also supported:
358
359         ,<vdev>:<devtype>,<access>   (deprecated)
360
361       This is solely for compatibility with xend's syntax for empty cdroms,
362       which is (for example) ",hdc:cdrom,r".
363
364
365
3664.16.3                            2022-12-19          xl-disk-configuration(5)
Impressum