-
Notifications
You must be signed in to change notification settings - Fork 0
/
xl-disk-configuration.txt
308 lines (215 loc) · 10.1 KB
/
xl-disk-configuration.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
Because I'm constantly referring to this.
From http://xenbits.xen.org/docs/unstable/misc/xl-disk-configuration.txt
Licenced under the GNU GPL v2
---------------------
XL DISK CONFIGURATION
---------------------
This document specifies the xl config file format disk configuration
option. It has the following form:
disk = [ '<diskspec>', '<diskspec>', ... ]
where each diskspec is in this form:
[<key>=<value>|<flag>,]*,
[<target>, [<format>, [<vdev>, [<access>]]]],
[<key>=<value>|<flag>,]*
[target=<target>]
For example, these strings are equivalent:
/dev/vg/guest-volume,,hda
/dev/vg/guest-volume,raw,hda,rw
format=raw, vdev=hda, access=rw, target=/dev/vg/guest-volume
raw:/dev/vg/guest-volume,hda,w (deprecated, see below)
As are these:
/root/image.iso,,hdc,cdrom
/root/image.iso,,hdc,,cdrom
/root/image.iso,raw,hdc,devtype=cdrom
format=raw, vdev=hdc, access=ro, devtype=cdrom, target=/root/image.iso
raw:/root/image.iso,hdc:cdrom,ro (deprecated, see below)
These might be specified in the domain config file like this:
disk = [ '/dev/vg/guest-volume,,hda', '/root/image.iso,,hdc,cdrom' ]
More formally, the string is a series of comma-separated keyword/value
pairs, flags and positional parameters. Parameters which are not bare
keywords and which do not contain "=" symbols are assigned to the
so-far-unspecified positional parameters, in the order below. The
positional parameters may also be specified explicitly by name.
Each parameter may be specified at most once, either as a positional
parameter or a named parameter. Default values apply if the parameter
is not specified, or if it is specified with an empty value (whether
positionally or explicitly).
Whitespace may appear before each parameter and will be ignored.
=====================
POSITIONAL PARAMETERS
=====================
target
------
Description: Block device or image file path. When this is
used as a path, /dev will be prepended
if the path doesn't start with a '/'.
Supported values: N/A
Deprecated values: N/A
Default value: None. While a path is provided in most cases
there is an exception: for a cdrom device, lack
of this attribute would imply an empty cdrom
drive.
Special syntax:
When this parameter is specified by name, ie with the "target="
syntax in the configuration file, it consumes the whole rest of the
<diskspec> including trailing whitespaces. Therefore in that case
it must come last. This is permissible even if an empty value for
the target was already specified as a positional parameter. This
is the only way to specify a target string containing metacharacters
such as commas and (in some cases) colons, which would otherwise be
misinterpreted.
Future parameter and flag names will start with an ascii letter and
contain only ascii alphanumerics, hyphens and underscores, and will
not be legal as vdevs. Targets which might match that syntax
should not be specified as positional parameters.
format
------
Description: Specifies the format of image file.
Supported values: raw, qcow, qcow2, vhd
Deprecated values: None
Default value: raw
vdev
----
Description: Virtual device as seen by the guest (also
referred to as guest drive designation in some
specifications). See docs/misc/vbd-interface.txt.
Supported values: hd[x], xvd[x], sd[x] etc. Please refer to the
above specification for further details.
Deprecated values: None
Default Value: None, this parameter is mandatory.
access
-------
Description: Specified access control information. Whether
or not the block device is provided to the
guest in read-only or read-write mode depends
on this attribute.
Supported values: ro, r (specifies read-only)
rw, w (specifies read/write)
Deprecated values: None
Default value: rw
unless devtype=cdrom, in which case r
==========================
OTHER PARAMETERS AND FLAGS
==========================
devtype=<devtype>
-----------------
Description: Qualifies virtual device type.
Supported values: cdrom
Deprecated values: None
Mandatory: No
cdrom
-----
Convenience alias for "devtype=cdrom".
backend=<domain-name>
---------------------
Description: Designates a backend domain for the device
Supported values: Valid domain names
Mandatory: No
Specifies the backend domain which this device should attach to. This
defaults to domain 0. Specifying another domain requires setting up a
driver domain which is outside the scope of this document.
backendtype=<backend-type>
--------------------------
Description: Specifies the backend implementation to use
Supported values: phy, tap, qdisk
Mandatory: No
Default value: Automatically determine which backend to use.
This does not affect the guest's view of the device. It controls
which software implementation of the Xen backend driver us used.
Not all backend drivers support all combinations of other options.
For example, "phy" does not support formats other than "raw".
Normally this option should not be specified, in which case libxl will
automatically determine the most suitable backend.
script=<script>
---------------
Specifies that <target> is not a normal host path, but rather
information to be interpreted by the executable program <script>,
(looked for in /etc/xen/scripts, if it doesn't contain a slash).
These scripts are normally called "block-<script>".
direct-io-safe
--------------
Description: Disables non-O_DIRECT workaround
Supported values: absent, present
Mandatory: No
Default value: absent (workaround may be enabled)
There is a memory lifetime bug in some driver domain (dom0) kernels
which can cause crashes when using O_DIRECT. The bug occurs due to a
mismatch between the backend-visible lifetime of pages used for the
Xen PV network protocol and that expected by the backend kernel's
networking subsystem. This can cause crashes when using certain
backends with certain underlying storage.
See:
http://lists.xen.org/archives/html/xen-devel/2012-12/msg01154.html
For this reason, (this version of) the Xen libxl toolstack disables
O_DIRECT when using the qemu-based Xen PV backend ("qdisk").
However, this workaround has performance and scaling implications, and
it is only necessary if the underlying device is a network filesystem.
If the underlying device is not, then it is good to disable it; that
is what this option is for.
This option simply requests that the workaround be disabled. (However,
not all backends versions which use the workaround understand this
option, so this is on a best effort basis.)
It's important to note that if you are storing the VM disk on a
network filesystem or a network block device (NFS or ISCSI) it might
not be safe to use this option. Otherwise specifying it is safe and
can give better performances.
If in the future the bug is fixed properly this option will then be
silently ignored.
discard / no-discard
---------------
Description: Request that backend advertise discard support to frontend
Supported values: discard
no-discard
Mandatory: No
Default value: discard
An advisory setting for the backend driver, specifying whether to
advertise discard support (TRIM, UNMAP) to the frontend. The real
benefit of this option is to be able to force it off rather than on. It
can be used to disable "hole punching" for file based backends which
were intentionally created non-sparse to avoid fragmentation of the
file.
============================================
DEPRECATED PARAMETERS, PREFIXES AND SYNTAXES
============================================
Deprecated forms are acceptable and are intended work compatibly with
xend and xl from xen 4.1. In future they may print a warning.
Support for deprecated parameters and syntaxes are likely to be
dropped in future versions of xl.
There is support for a deprecated old syntax for <diskspec>:
[<format>:][<target>],<vdev>[:<devtype>],<access> (deprecated)
This syntax also supports deprecated prefixes, described below. These
are found prepended to the format parameter - eg "tap:aio:qcow:".
<format>:
---------
Description: Specifies the format (deprecated)
Supported values: raw: qcow2: vhd:
In xend and old versions of libxl it was necessary to specify the
format with a prefix. For compatibility, these three prefixes are
recognised as specifying the corresponding format. They are
equivalent to "format=<format>" or the specification of <format>
(without a colon) as a positional parameter.
<script>:
---------
Description: Specifies the script (deprecated)
Supported values: iscsi: nbd: enbd: drbd:
In xend and old versions of libxl it was necessary to specify the
"script" (see above) with a prefix. For compatibility, these four
prefixes are recognised as specifying the corresponding script. They
are equivalent to "script=block-<script>".
<deprecated-prefix>:
--------------------
Description; Deprecated prefix, ignored
Supported values: tapdisk: tap2: aio: ioemu: file: phy:
Various prefixes were required by xend and older versions of libxl to
make the block devices work. In some cases these options would
override the backend type, but in other cases they would be ignored in
favour of "making it work"; in yet other cases it would be necessary
to specify several of these, for example:
"tap:aio:/some/path..."
All of these prefixes are now stripped and ignored.
Missing format and empty target
-------------------------------
The following syntax is also supported:
,<vdev>:<devtype>,<access> (deprecated)
This is soley for compatibility with xend's syntax for empty cdroms,
which is (for example) ",hdc:cdrom,r".