1=head1 NAME
2
3xl-disk-configuration - XL Disk Configuration Syntax
4
5=head1 SYNTAX
6
7This document specifies the xl config file format disk configuration
8option.  It has the following form:
9
10   disk = [ 'DISKSPEC', 'DISKSPEC', ... ]
11
12where each C<DISKSPEC> is in this form:
13
14   [<key>=<value>|<flag>,]*,
15     [<target>, [<format>, [<vdev>, [<access>]]]],
16     [<key>=<value>|<flag>,]*
17     [target=<target>]
18
19For example, these strings are equivalent:
20
21    /dev/vg/guest-volume,,hda
22    /dev/vg/guest-volume,raw,hda,rw
23    format=raw, vdev=hda, access=rw, target=/dev/vg/guest-volume
24    raw:/dev/vg/guest-volume,hda,w  (deprecated, see below)
25
26As are these:
27
28    /root/image.iso,,hdc,cdrom
29    /root/image.iso,,hdc,,cdrom
30    /root/image.iso,raw,hdc,devtype=cdrom
31    format=raw, vdev=hdc, access=ro, devtype=cdrom, target=/root/image.iso
32    raw:/root/image.iso,hdc:cdrom,ro   (deprecated, see below)
33
34These might be specified in the domain config file like this:
35
36    disk = [ '/dev/vg/guest-volume,,hda', '/root/image.iso,,hdc,cdrom' ]
37
38
39More formally, the string is a series of comma-separated keyword/value
40pairs, flags and positional parameters.  Parameters which are not bare
41keywords and which do not contain "=" symbols are assigned to the
42so-far-unspecified positional parameters, in the order below.  The
43positional parameters may also be specified explicitly by name.
44
45Each parameter may be specified at most once, either as a positional
46parameter or a named parameter.  Default values apply if the parameter
47is not specified, or if it is specified with an empty value (whether
48positionally or explicitly).
49
50Whitespace may appear before each parameter and will be ignored.
51
52=head1 Positional Parameters
53
54=over 4
55
56=item B<target>
57
58=over 4
59
60=item Description
61
62Block device or image file path.  When this is used as a path, F</dev>
63will be prepended if the path doesn't start with a '/'.
64
65=item Supported values
66
67N/A
68
69=item Deprecated values
70
71N/A
72
73=item Default value
74
75None.  While a path is provided in most cases there is an exception:
76for a cdrom device, lack of this attribute would imply an empty cdrom
77drive.
78
79=item Special syntax
80
81When this parameter is specified by name, ie with the C<target=>
82syntax in the configuration file, it consumes the whole rest of the
83C<DISKSPEC> including trailing whitespaces.  Therefore in that case
84it must come last.  This is permissible even if an empty value for
85the target was already specified as a positional parameter.  This
86is the only way to specify a target string containing metacharacters
87such as commas and (in some cases) colons, which would otherwise be
88misinterpreted.
89
90Future parameter and flag names will start with an ascii letter and
91contain only ascii alphanumerics, hyphens and underscores, and will
92not be legal as vdevs.  Targets which might match that syntax
93should not be specified as positional parameters.
94
95=back
96
97=item B<format>
98
99=over 4
100
101=item Description
102
103Specifies the format of image file.
104
105=item Supported values
106
107raw, qcow, qcow2, vhd, qed
108
109=item Deprecated values
110
111None
112
113=item Default value
114
115raw
116
117=back
118
119=item B<vdev>
120
121=over 4
122
123=item Description
124
125Virtual device as seen by the guest (also referred to as guest drive
126designation in some specifications).  L<xen-vbd-interface(7)>
127
128=item Supported values
129
130hd[x], xvd[x], sd[x] etc.  Please refer to the above specification for
131further details.
132
133=item Deprecated values
134
135None
136
137=item Default Value
138
139None, this parameter is mandatory.
140
141=back
142
143=item B<access>
144
145=over 4
146
147=item Description
148
149Specified access control information.  Whether or not the block device is
150provided to the guest in read-only or read-write mode depends on this
151attribute.
152
153=item Supported values
154
155C<ro>, C<r>   (specifies read-only)
156
157C<rw>, C<w>   (specifies read/write)
158
159=item Deprecated values
160
161None
162
163=item Default value
164
165C<rw> unless devtype=cdrom, in which case C<r>
166
167=back
168
169=back
170
171=head1 Other Parameters And Flags
172
173=over 4
174
175=item B<devtype>=I<DEVTYPE>
176
177=over 4
178
179=item Description
180
181Qualifies virtual device type.
182
183=item Supported values
184
185cdrom
186
187=item Deprecated values
188
189None
190
191=item Mandatory
192
193No
194
195=back
196
197=item B<cdrom>
198
199Convenience alias for "devtype=cdrom".
200
201
202=item B<backend>=I<DOMAIN-NAME>
203
204=over 4
205
206=item Description
207
208Designates a backend domain for the device
209
210=item Supported values
211
212Valid domain names
213
214=item Mandatory
215
216No
217
218=back
219
220Specifies the backend domain which this device should attach to. This
221defaults to domain 0. Specifying another domain requires setting up a
222driver domain which is outside the scope of this document.
223
224
225=item B<backendtype>=I<TYPE>
226
227=over 4
228
229=item Description
230
231Specifies the backend implementation to use
232
233=item Supported values
234
235phy, tap, qdisk
236
237=item Mandatory
238
239No
240
241=item Default value
242
243Automatically determine which backend to use.
244
245=back
246
247This does not affect the guest's view of the device.  It controls
248which software implementation of the Xen backend driver is used.
249
250Not all backend drivers support all combinations of other options.
251For example, "phy" does not support formats other than "raw".
252Normally this option should not be specified, in which case libxl will
253automatically determine the most suitable backend.
254
255
256=item B<script>=I<SCRIPT>
257
258Specifies that B<target> is not a normal host path, but rather
259information to be interpreted by the executable program I<SCRIPT>,
260(looked for in F</etc/xen/scripts>, if it doesn't contain a slash).
261
262These scripts are normally called "block-I<SCRIPT>".
263
264
265=item B<direct-io-safe>
266
267=over 4
268
269=item Description
270
271Disables non-O_DIRECT workaround
272
273=item Supported values
274
275absent, present
276
277=item Mandatory
278
279No
280
281=item Default value
282
283absent (workaround may be enabled)
284
285=back
286
287There is a memory lifetime bug in some driver domain (dom0) kernels
288which can cause crashes when using O_DIRECT.  The bug occurs due to a
289mismatch between the backend-visible lifetime of pages used for the
290Xen PV network protocol and that expected by the backend kernel's
291networking subsystem.  This can cause crashes when using certain
292backends with certain underlying storage.
293
294See:
295 L<http://lists.xen.org/archives/html/xen-devel/2012-12/msg01154.html>
296
297For this reason, (this version of) the Xen libxl toolstack disables
298O_DIRECT when using the qemu-based Xen PV backend (C<qdisk>).
299
300However, this workaround has performance and scaling implications, and
301it is only necessary if the underlying device is a network filesystem.
302If the underlying device is not, then it is good to disable it; that
303is what this option is for.
304
305This option simply requests that the workaround be disabled.  (However,
306not all backends versions which use the workaround understand this
307option, so this is on a best effort basis.)
308
309It's important to note that if you are storing the VM disk on a
310network filesystem or a network block device (NFS or ISCSI) it might
311not be safe to use this option.  Otherwise specifying it is safe and
312can give better performances.
313
314If in the future the bug is fixed properly this option will then be
315silently ignored.
316
317
318=item B<discard> / B<no-discard>
319
320=over 4
321
322=item Description
323
324Request that backend advertise discard support to frontend
325
326=item Supported values
327
328discard, no-discard
329
330=item Mandatory
331
332No
333
334=item Default value
335
336discard
337
338=back
339
340An advisory setting for the backend driver, specifying whether to
341advertise discard support (TRIM, UNMAP) to the frontend.  The real
342benefit of this option is to be able to force it off rather than on.  It
343can be used to disable "hole punching" for file based backends which
344were intentionally created non-sparse to avoid fragmentation of the
345file.
346
347=back
348
349
350=head1 COLO Parameters
351
352=over 4
353
354=item B<colo>
355
356Enable COLO HA for disk. For better understanding block replication on
357QEMU, please refer to: L<http://wiki.qemu.org/Features/BlockReplication>
358Note that the COLO configuration settings should be considered unstable.
359They may change incompatibly in future versions of Xen.
360
361
362=item B<colo-host>
363
364=over 4
365
366=item Description
367
368Secondary host's address
369
370=item Mandatory
371
372Yes when COLO enabled
373
374=back
375
376=item B<colo-port>
377
378=over 4
379
380=item Description
381
382Secondary port.  We will run a nbd server on secondary host,
383and the nbd server will listen this port.
384
385=item Mandatory
386
387Yes when COLO enabled
388
389=back
390
391=item B<colo-export>
392
393=over 4
394
395=item Description
396
397We will run a nbd server on secondary host, exportname is
398the nbd server's disk export name.
399
400=item Mandatory
401
402Yes when COLO enabled
403
404=back
405
406=item B<active-disk>
407
408=over 4
409
410=item Description
411
412This is used by secondary. Secondary guest's write will be buffered in this
413disk.
414
415=item Mandatory
416
417Yes when COLO enabled
418
419=back
420
421=item B<hidden-disk>
422
423=over 4
424
425=item Description
426
427This is used by secondary. It buffers the original content that is modified
428by the primary VM.
429
430=item Mandatory
431
432Yes when COLO enabled
433
434=back
435
436=back
437
438
439=head1 Deprecated Parameters, Prefixes And Syntaxes
440
441Deprecated forms are acceptable and are intended work compatibly with
442xend and xl from xen 4.1.  In future they may print a warning.
443Support for deprecated parameters and syntaxes are likely to be
444dropped in future versions of xl.
445
446There is support for a deprecated old syntax for C<DISKSPEC>:
447
448  [<format>:][<target>],<vdev>[:<devtype>],<access>   (deprecated)
449
450This syntax also supports deprecated prefixes, described below.  These
451are found prepended to the format parameter - eg C<tap:aio:qcow:>.
452
453=over 4
454
455=item B<format>
456
457=over 4
458
459=item Description
460
461Specifies the format (deprecated)
462
463=item Supported values
464
465raw:  qcow2:  vhd:
466
467=back
468
469In xend and old versions of libxl it was necessary to specify the
470format with a prefix.  For compatibility, these three prefixes are
471recognised as specifying the corresponding format.  They are
472equivalent to C<format=FORMAT> or the specification of B<format>
473(without a colon) as a positional parameter.
474
475
476=item B<script>
477
478=over 4
479
480=item Description
481
482Specifies the script (deprecated)
483
484=item Supported values
485
486iscsi:  nbd:  enbd:  drbd:
487
488=back
489
490In xend and old versions of libxl it was necessary to specify the
491"script" (see above) with a prefix.  For compatibility, these four
492prefixes are recognised as specifying the corresponding script.  They
493are equivalent to C<script=block-SCRIPT>.
494
495
496=item B<deprecated-prefix>
497
498=over 4
499
500=item Description
501
502Deprecated prefix, ignored
503
504=item Supported values
505
506tapdisk:  tap2:  aio:  ioemu:  file:  phy:
507
508=back
509
510Various prefixes were required by xend and older versions of libxl to
511make the block devices work.  In some cases these options would
512override the backend type, but in other cases they would be ignored in
513favour of "making it work"; in yet other cases it would be necessary
514to specify several of these, for example:
515
516  tap:aio:/some/path...
517
518All of these prefixes are now stripped and ignored.
519
520=back
521
522=head2 Missing format and empty target
523
524The following syntax is also supported:
525
526  ,<vdev>:<devtype>,<access>   (deprecated)
527
528This is solely for compatibility with xend's syntax for empty cdroms,
529which is (for example) C<,hdc:cdrom,r>.
530