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).  See 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, qdisk, standalone, tap
236
237=item Mandatory
238
239No
240
241=item Default value
242
243Automatically determine which backend to use.
244
245=back
246
247It controls which software implementation of the backend driver is used.
248Depending on the "specification" option this may affect the guest's view
249of the device.
250
251Not all backend drivers support all combinations of other options.
252For example, "phy" and "standalone" do not support formats other than "raw"
253and "standalone" does not support specifications other than "virtio".
254Normally this option should not be specified, in which case libxl will
255automatically determine the most suitable backend.
256
257"tap" needs blktap's tapback to be running.
258
259
260=item B<script>=I<SCRIPT>
261
262Specifies that B<target> is not a normal host path, but rather
263information to be interpreted by the executable program I<SCRIPT>,
264(looked for in F<@XEN_SCRIPT_DIR@>, if it doesn't contain a slash).
265
266These scripts are normally called "block-I<SCRIPT>".
267
268
269=item B<direct-io-safe>
270
271=over 4
272
273=item Description
274
275Disables non-O_DIRECT workaround
276
277=item Supported values
278
279absent, present
280
281=item Mandatory
282
283No
284
285=item Default value
286
287absent (workaround may be enabled)
288
289=back
290
291There is a memory lifetime bug in some driver domain (dom0) kernels
292which can cause crashes when using O_DIRECT.  The bug occurs due to a
293mismatch between the backend-visible lifetime of pages used for the
294Xen PV network protocol and that expected by the backend kernel's
295networking subsystem.  This can cause crashes when using certain
296backends with certain underlying storage.
297
298See:
299 L<https://lists.xenproject.org/archives/html/xen-devel/2012-12/msg01154.html>
300
301For this reason, (this version of) the Xen libxl toolstack disables
302O_DIRECT when using the qemu-based Xen PV backend (C<qdisk>).
303
304However, this workaround has performance and scaling implications, and
305it is only necessary if the underlying device is a network filesystem.
306If the underlying device is not, then it is good to disable it; that
307is what this option is for.
308
309This option simply requests that the workaround be disabled.  (However,
310not all backends versions which use the workaround understand this
311option, so this is on a best effort basis.)
312
313It's important to note that if you are storing the VM disk on a
314network filesystem or a network block device (NFS or ISCSI) it might
315not be safe to use this option.  Otherwise specifying it is safe and
316can give better performances.
317
318If in the future the bug is fixed properly this option will then be
319silently ignored.
320
321
322=item B<discard> / B<no-discard>
323
324=over 4
325
326=item Description
327
328Request that backend advertise discard support to frontend
329
330=item Supported values
331
332discard, no-discard
333
334=item Mandatory
335
336No
337
338=item Default value
339
340discard
341
342=back
343
344An advisory setting for the backend driver, specifying whether to
345advertise discard support (TRIM, UNMAP) to the frontend.  The real
346benefit of this option is to be able to force it off rather than on.  It
347can be used to disable "hole punching" for file based backends which
348were intentionally created non-sparse to avoid fragmentation of the
349file.
350
351=item B<trusted> / B<untrusted>
352
353=over 4
354
355=item Description
356
357Reports whether the backend should be trusted by the frontend
358
359=item Supported values
360
361trusted, untrusted
362
363=item Mandatory
364
365No
366
367=item Default value
368
369trusted
370
371=back
372
373An advisory setting for the frontend driver on whether the backend should be
374trusted.  The frontend should deploy whatever protections it has available to
375prevent an untrusted backend from accessing guest data not related to the I/O
376processing or causing malfunction to the frontend or the whole domain.
377
378Note frontends can ignore such recommendation.
379
380=item B<specification>=I<SPECIFICATION>
381
382=over 4
383
384=item Description
385
386Specifies the communication protocol (specification) to use for the chosen
387"backendtype" option
388
389=item Supported values
390
391xen, virtio
392
393=item Mandatory
394
395No
396
397=item Default value
398
399xen
400
401=back
402
403Besides forcing toolstack to use specific backend implementation, this also
404affects the guest's view of the device. For example, "virtio" requires
405Virtio frontend driver (virtio-blk) to be used. Please note, the virtual
406device (vdev) is not passed to the guest in that case, but it still must be
407specified for the internal purposes.
408
409=item B<grant_usage=BOOLEAN>
410
411=over 4
412
413=item Description
414
415Specifies the usage of Xen grants for accessing guest memory. Only applicable
416to specification "virtio".
417
418=item Supported values
419
4201, 0
421
422=item Mandatory
423
424No
425
426=item Default value
427
428If this option is missing, then the default grant setting will be used,
429i.e. "grant_usage=1" if backend-domid != 0 or "grant_usage=0" otherwise.
430
431=back
432
433=back
434
435=head1 COLO Parameters
436
437=over 4
438
439=item B<colo>
440
441Enable COLO HA for disk. For better understanding block replication on
442QEMU, please refer to: L<https://wiki.qemu.org/Features/BlockReplication>
443Note that the COLO configuration settings should be considered unstable.
444They may change incompatibly in future versions of Xen.
445
446
447=item B<colo-host>
448
449=over 4
450
451=item Description
452
453Secondary host's address
454
455=item Mandatory
456
457Yes when COLO enabled
458
459=back
460
461=item B<colo-port>
462
463=over 4
464
465=item Description
466
467Secondary port.  We will run a nbd server on secondary host,
468and the nbd server will listen this port.
469
470=item Mandatory
471
472Yes when COLO enabled
473
474=back
475
476=item B<colo-export>
477
478=over 4
479
480=item Description
481
482We will run a nbd server on secondary host, exportname is
483the nbd server's disk export name.
484
485=item Mandatory
486
487Yes when COLO enabled
488
489=back
490
491=item B<active-disk>
492
493=over 4
494
495=item Description
496
497This is used by secondary. Secondary guest's write will be buffered in this
498disk.
499
500=item Mandatory
501
502Yes when COLO enabled
503
504=back
505
506=item B<hidden-disk>
507
508=over 4
509
510=item Description
511
512This is used by secondary. It buffers the original content that is modified
513by the primary VM.
514
515=item Mandatory
516
517Yes when COLO enabled
518
519=back
520
521=back
522
523
524=head1 Deprecated Parameters, Prefixes And Syntaxes
525
526Deprecated forms are acceptable and are intended work compatibly with
527xend and xl from xen 4.1.  In future they may print a warning.
528Support for deprecated parameters and syntaxes are likely to be
529dropped in future versions of xl.
530
531There is support for a deprecated old syntax for C<DISKSPEC>:
532
533  [<format>:][<target>],<vdev>[:<devtype>],<access>   (deprecated)
534
535This syntax also supports deprecated prefixes, described below.  These
536are found prepended to the format parameter - eg C<tap:aio:qcow:>.
537
538=over 4
539
540=item B<format>
541
542=over 4
543
544=item Description
545
546Specifies the format (deprecated)
547
548=item Supported values
549
550raw:  qcow2:  vhd:
551
552=back
553
554In xend and old versions of libxl it was necessary to specify the
555format with a prefix.  For compatibility, these three prefixes are
556recognised as specifying the corresponding format.  They are
557equivalent to C<format=FORMAT> or the specification of B<format>
558(without a colon) as a positional parameter.
559
560
561=item B<script>
562
563=over 4
564
565=item Description
566
567Specifies the script (deprecated)
568
569=item Supported values
570
571iscsi:  nbd:  enbd:  drbd:
572
573=back
574
575In xend and old versions of libxl it was necessary to specify the
576"script" (see above) with a prefix.  For compatibility, these four
577prefixes are recognised as specifying the corresponding script.  They
578are equivalent to C<script=block-SCRIPT>.
579
580
581=item B<deprecated-prefix>
582
583=over 4
584
585=item Description
586
587Deprecated prefix, ignored
588
589=item Supported values
590
591tapdisk:  tap2:  aio:  ioemu:  file:  phy:
592
593=back
594
595Various prefixes were required by xend and older versions of libxl to
596make the block devices work.  In some cases these options would
597override the backend type, but in other cases they would be ignored in
598favour of "making it work"; in yet other cases it would be necessary
599to specify several of these, for example:
600
601  tap:aio:/some/path...
602
603All of these prefixes are now stripped and ignored.
604
605=back
606
607=head2 Missing format and empty target
608
609The following syntax is also supported:
610
611  ,<vdev>:<devtype>,<access>   (deprecated)
612
613This is solely for compatibility with xend's syntax for empty cdroms,
614which is (for example) C<,hdc:cdrom,r>.
615