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
169 Mandatory
171 No
172 Default value
174 Automatically determine which backend to use.
175 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 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 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 These scripts are normally called "block-SCRIPT".
190 direct-io-safe
192 Description
193 Disables non-O_DIRECT workaround
194 Supported values
196 absent, present
197 Mandatory
199 No
200 Default value
202 absent (workaround may be enabled)
203 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 See:
212 <https://lists.xenproject.org/archives/html/xen-devel/2012-12/msg01154.html>
213 For this reason, (this version of) the Xen libxl toolstack disables
215 O_DIRECT when using the qemu-based Xen PV backend ("qdisk").
216 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 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 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 If in the future the bug is fixed properly this option will then be
232 silently ignored.
233 discard / no-discard
235 Description
236 Request that backend advertise discard support to frontend
237 Supported values
239 discard, no-discard
240 Mandatory
242 No
243 Default value
245 discard
246 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
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 colo-host
263 Description
264 Secondary host's address
265 Mandatory
267 Yes when COLO enabled
268 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 Mandatory
275 Yes when COLO enabled
276 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 Mandatory
283 Yes when COLO enabled
284 active-disk
286 Description
287 This is used by secondary. Secondary guest's write will be
288 buffered in this disk.
289 Mandatory
291 Yes when COLO enabled
292 hidden-disk
294 Description
295 This is used by secondary. It buffers the original content that
296 is modified by the primary VM.
297 Mandatory
299 Yes when COLO enabled
300
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 There is support for a deprecated old syntax for "DISKSPEC":
308 [<format>:][<target>],<vdev>[:<devtype>],<access> (deprecated)
310 This syntax also supports deprecated prefixes, described below. These
312 are found prepended to the format parameter - eg "tap:aio:qcow:".
313 format
315 Description
316 Specifies the format (deprecated)
317 Supported values
319 raw: qcow2: vhd:
320 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 script
328 Description
329 Specifies the script (deprecated)
330 Supported values
332 iscsi: nbd: enbd: drbd:
333 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 deprecated-prefix
340 Description
341 Deprecated prefix, ignored
342 Supported values
344 tapdisk: tap2: aio: ioemu: file: phy:
345 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 tap:aio:/some/path...
353 All of these prefixes are now stripped and ignored.
355 Missing format and empty target
357 The following syntax is also supported:
358 ,<vdev>:<devtype>,<access> (deprecated)
360 This is solely for compatibility with xend's syntax for empty cdroms,
362 which is (for example) ",hdc:cdrom,r".
3634.16.3 2022-12-19 xl-disk-configuration(5)