1xl-disk-configuration(5) Xen xl-disk-configuration(5)
2
6 xl-disk-configuration - XL Disk Configuration Syntax
7
9 This document specifies the xl config file format disk configuration
10 option. It has the following form:
11 disk = [ 'DISKSPEC', 'DISKSPEC', ... ]
13 where each "DISKSPEC" is in this form:
15 [<key>=<value>|<flag>,]*,
17 [<target>, [<format>, [<vdev>, [<access>]]]],
18 [<key>=<value>|<flag>,]*
19 [target=<target>]
20 For example, these strings are equivalent:
22 /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 As are these:
29 /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 These might be specified in the domain config file like this:
37 disk = [ '/dev/vg/guest-volume,,hda', '/root/image.iso,,hdc,cdrom' ]
39 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 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 Whitespace may appear before each parameter and will be ignored.
52
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 Supported values
60 N/A
61 Deprecated values
63 N/A
64 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 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 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 format
86 Description
87 Specifies the format of image file.
88 Supported values
90 raw, qcow, qcow2, vhd, qed
91 Deprecated values
93 None
94 Default value
96 raw
97 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 Supported values
105 hd[x], xvd[x], sd[x] etc. Please refer to the above
106 specification for further details.
107 Deprecated values
109 None
110 Default Value
112 None, this parameter is mandatory.
113 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 Supported values
121 "ro", "r" (specifies read-only)
122 "rw", "w" (specifies read/write)
124 Deprecated values
126 None
127 Default value
129 "rw" unless devtype=cdrom, in which case "r"
130
132 devtype=DEVTYPE
133 Description
134 Qualifies virtual device type.
135 Supported values
137 cdrom
138 Deprecated values
140 None
141 Mandatory
143 No
144 cdrom
146 Convenience alias for "devtype=cdrom".
147 backend=DOMAIN-NAME
149 Description
150 Designates a backend domain for the device
151 Supported values
153 Valid domain names
154 Mandatory
156 No
157 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 backendtype=TYPE
164 Description
165 Specifies the backend implementation to use
166 Supported values
168 phy, qdisk, standalone
169 Mandatory
171 No
172 Default value
174 Automatically determine which backend to use.
175 It controls which software implementation of the backend driver is
177 used. Depending on the "specification" option this may affect the
178 guest's view of the device.
179 Not all backend drivers support all combinations of other options.
181 For example, "phy" and "standalone" do not support formats other
182 than "raw" and "standalone" does not support specifications other
183 than "virtio". Normally this option should not be specified, in
184 which case libxl will automatically determine the most suitable
185 backend.
186 script=SCRIPT
188 Specifies that target is not a normal host path, but rather
189 information to be interpreted by the executable program SCRIPT,
190 (looked for in /etc/xen/scripts, if it doesn't contain a slash).
191 These scripts are normally called "block-SCRIPT".
193 direct-io-safe
195 Description
196 Disables non-O_DIRECT workaround
197 Supported values
199 absent, present
200 Mandatory
202 No
203 Default value
205 absent (workaround may be enabled)
206 There is a memory lifetime bug in some driver domain (dom0) kernels
208 which can cause crashes when using O_DIRECT. The bug occurs due to
209 a mismatch between the backend-visible lifetime of pages used for
210 the Xen PV network protocol and that expected by the backend
211 kernel's networking subsystem. This can cause crashes when using
212 certain backends with certain underlying storage.
213 See:
215 <https://lists.xenproject.org/archives/html/xen-devel/2012-12/msg01154.html>
216 For this reason, (this version of) the Xen libxl toolstack disables
218 O_DIRECT when using the qemu-based Xen PV backend ("qdisk").
219 However, this workaround has performance and scaling implications,
221 and it is only necessary if the underlying device is a network
222 filesystem. If the underlying device is not, then it is good to
223 disable it; that is what this option is for.
224 This option simply requests that the workaround be disabled.
226 (However, not all backends versions which use the workaround
227 understand this option, so this is on a best effort basis.)
228 It's important to note that if you are storing the VM disk on a
230 network filesystem or a network block device (NFS or ISCSI) it
231 might not be safe to use this option. Otherwise specifying it is
232 safe and can give better performances.
233 If in the future the bug is fixed properly this option will then be
235 silently ignored.
236 discard / no-discard
238 Description
239 Request that backend advertise discard support to frontend
240 Supported values
242 discard, no-discard
243 Mandatory
245 No
246 Default value
248 discard
249 An advisory setting for the backend driver, specifying whether to
251 advertise discard support (TRIM, UNMAP) to the frontend. The real
252 benefit of this option is to be able to force it off rather than
253 on. It can be used to disable "hole punching" for file based
254 backends which were intentionally created non-sparse to avoid
255 fragmentation of the file.
256 trusted / untrusted
258 Description
259 Reports whether the backend should be trusted by the frontend
260 Supported values
262 trusted, untrusted
263 Mandatory
265 No
266 Default value
268 trusted
269 An advisory setting for the frontend driver on whether the backend
271 should be trusted. The frontend should deploy whatever protections
272 it has available to prevent an untrusted backend from accessing
273 guest data not related to the I/O processing or causing malfunction
274 to the frontend or the whole domain.
275 Note frontends can ignore such recommendation.
277 specification=SPECIFICATION
279 Description
280 Specifies the communication protocol (specification) to use for
281 the chosen "backendtype" option
282 Supported values
284 xen, virtio
285 Mandatory
287 No
288 Default value
290 xen
291 Besides forcing toolstack to use specific backend implementation,
293 this also affects the guest's view of the device. For example,
294 "virtio" requires Virtio frontend driver (virtio-blk) to be used.
295 Please note, the virtual device (vdev) is not passed to the guest
296 in that case, but it still must be specified for the internal
297 purposes.
298
300 colo
301 Enable COLO HA for disk. For better understanding block replication
302 on QEMU, please refer to:
303 <https://wiki.qemu.org/Features/BlockReplication> Note that the
304 COLO configuration settings should be considered unstable. They
305 may change incompatibly in future versions of Xen.
306 colo-host
308 Description
309 Secondary host's address
310 Mandatory
312 Yes when COLO enabled
313 colo-port
315 Description
316 Secondary port. We will run a nbd server on secondary host,
317 and the nbd server will listen this port.
318 Mandatory
320 Yes when COLO enabled
321 colo-export
323 Description
324 We will run a nbd server on secondary host, exportname is the
325 nbd server's disk export name.
326 Mandatory
328 Yes when COLO enabled
329 active-disk
331 Description
332 This is used by secondary. Secondary guest's write will be
333 buffered in this disk.
334 Mandatory
336 Yes when COLO enabled
337 hidden-disk
339 Description
340 This is used by secondary. It buffers the original content that
341 is modified by the primary VM.
342 Mandatory
344 Yes when COLO enabled
345
347 Deprecated forms are acceptable and are intended work compatibly with
348 xend and xl from xen 4.1. In future they may print a warning. Support
349 for deprecated parameters and syntaxes are likely to be dropped in
350 future versions of xl.
351 There is support for a deprecated old syntax for "DISKSPEC":
353 [<format>:][<target>],<vdev>[:<devtype>],<access> (deprecated)
355 This syntax also supports deprecated prefixes, described below. These
357 are found prepended to the format parameter - eg "tap:aio:qcow:".
358 format
360 Description
361 Specifies the format (deprecated)
362 Supported values
364 raw: qcow2: vhd:
365 In xend and old versions of libxl it was necessary to specify the
367 format with a prefix. For compatibility, these three prefixes are
368 recognised as specifying the corresponding format. They are
369 equivalent to "format=FORMAT" or the specification of format
370 (without a colon) as a positional parameter.
371 script
373 Description
374 Specifies the script (deprecated)
375 Supported values
377 iscsi: nbd: enbd: drbd:
378 In xend and old versions of libxl it was necessary to specify the
380 "script" (see above) with a prefix. For compatibility, these four
381 prefixes are recognised as specifying the corresponding script.
382 They are equivalent to "script=block-SCRIPT".
383 deprecated-prefix
385 Description
386 Deprecated prefix, ignored
387 Supported values
389 tapdisk: tap2: aio: ioemu: file: phy:
390 Various prefixes were required by xend and older versions of libxl
392 to make the block devices work. In some cases these options would
393 override the backend type, but in other cases they would be ignored
394 in favour of "making it work"; in yet other cases it would be
395 necessary to specify several of these, for example:
396 tap:aio:/some/path...
398 All of these prefixes are now stripped and ignored.
400 Missing format and empty target
402 The following syntax is also supported:
403 ,<vdev>:<devtype>,<access> (deprecated)
405 This is solely for compatibility with xend's syntax for empty cdroms,
407 which is (for example) ",hdc:cdrom,r".
4084.17.2 2023-11-14 xl-disk-configuration(5)