jcs.org
qemu with hax to log dma reads & writes
jcs.org/2018/11/12/vfio
qemu-block-drivers: Convert to rST
The qemu-block-drivers documentation is currently in
docs/qemu-block-drivers.texi in Texinfo format, which we present
to the user as:
* a qemu-block-drivers manpage
* a section of the main qemu-doc HTML documentation
Convert the documentation to rST format, and present it to
the user as:
* a qemu-block-drivers manpage
* part of the system/ Sphinx manual
This follows the same pattern we've done for qemu-ga and qemu-nbd.
We have to drop a cross-reference from the documentation of the
-cdrom option back to the qemu-block-drivers documentation, since
they're no longer within the same texinfo document.
As noted in a comment, the manpage output is slightly compromised
due to limitations in Sphinx. In an ideal world, the HTML output
would have the various headings like 'Disk image file formats'
as top-level section headings (which then appear in the overall
system manual's table-of-contents), and it would not have the
section headings which make sense only for the manpage like
'synopsis', 'description', and 'see also'. Unfortunately, the
mechanism Sphinx provides for restricting pieces of documentation
is limited to the point of being flawed: the 'only::' directive
is implemented as a filter that is applied at a very late stage
in the document processing pipeline, rather than as an early
equivalent of an #ifdef. This means that Sphinx's process of
identifying which section heading markup styles are which levels
of heading gets confused if the 'only::' directive contains
section headings which would affect the heading-level of a
later heading. I have opted to prioritise making the HTML format
look better, with the compromise being that in the manpage
the 'Disk image file formats' &c headings are top-level headings
rather than being sub-headings under the traditional 'Description'
top-level section title.
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
Tested-by: Alex Bennée <alex.bennee@linaro.org>
Acked-by: Stefan Hajnoczi <stefanha@redhat.com>
Message-id: 20200116141511.16849-4-peter.maydell@linaro.org
+1000
-907
+6
-5
Makefile
+6
-5
Makefile
···
342
342
DOCS=qemu-doc.html qemu-doc.txt qemu.1 qemu-img.1
343
343
DOCS+=$(MANUAL_BUILDDIR)/interop/qemu-nbd.8
344
344
DOCS+=$(MANUAL_BUILDDIR)/interop/qemu-ga.8
345
+
DOCS+=$(MANUAL_BUILDDIR)/system/qemu-block-drivers.7
345
346
DOCS+=docs/interop/qemu-qmp-ref.html docs/interop/qemu-qmp-ref.txt docs/interop/qemu-qmp-ref.7
346
347
DOCS+=docs/interop/qemu-ga-ref.html docs/interop/qemu-ga-ref.txt docs/interop/qemu-ga-ref.7
347
-
DOCS+=docs/qemu-block-drivers.7
348
348
DOCS+=docs/qemu-cpu-models.7
349
349
DOCS+=$(MANUAL_BUILDDIR)/index.html
350
350
ifdef CONFIG_VIRTFS
···
751
751
rm -f docs/interop/qemu-qmp-ref.txt docs/interop/qemu-ga-ref.txt
752
752
rm -f docs/interop/qemu-qmp-ref.pdf docs/interop/qemu-ga-ref.pdf
753
753
rm -f docs/interop/qemu-qmp-ref.html docs/interop/qemu-ga-ref.html
754
-
rm -f docs/qemu-block-drivers.7
755
754
rm -f docs/qemu-cpu-models.7
756
755
rm -rf .doctrees
757
756
$(call clean-manual,devel)
···
828
827
$(INSTALL_DATA) qemu.1 "$(DESTDIR)$(mandir)/man1"
829
828
$(INSTALL_DIR) "$(DESTDIR)$(mandir)/man7"
830
829
$(INSTALL_DATA) docs/interop/qemu-qmp-ref.7 "$(DESTDIR)$(mandir)/man7"
831
-
$(INSTALL_DATA) docs/qemu-block-drivers.7 "$(DESTDIR)$(mandir)/man7"
830
+
$(INSTALL_DATA) $(MANUAL_BUILDDIR)/system/qemu-block-drivers.7 "$(DESTDIR)$(mandir)/man7"
832
831
$(INSTALL_DATA) docs/qemu-cpu-models.7 "$(DESTDIR)$(mandir)/man7"
833
832
ifeq ($(CONFIG_TOOLS),y)
834
833
$(INSTALL_DATA) qemu-img.1 "$(DESTDIR)$(mandir)/man1"
···
1036
1035
$(MANUAL_BUILDDIR)/interop/qemu-nbd.8: $(call manual-deps,interop)
1037
1036
$(call build-manual,interop,man)
1038
1037
1038
+
$(MANUAL_BUILDDIR)/system/qemu-block-drivers.7: $(call manual-deps,system)
1039
+
$(call build-manual,system,man)
1040
+
1039
1041
$(MANUAL_BUILDDIR)/index.html: $(SRC_PATH)/docs/index.html.in qemu-version.h
1040
1042
@mkdir -p "$(MANUAL_BUILDDIR)"
1041
1043
$(call quiet-command, sed "s|@@VERSION@@|${VERSION}|g" $< >$@, \
···
1063
1065
qemu.1: qemu-option-trace.texi
1064
1066
qemu-img.1: qemu-img.texi qemu-option-trace.texi qemu-img-cmds.texi
1065
1067
fsdev/virtfs-proxy-helper.1: fsdev/virtfs-proxy-helper.texi
1066
-
docs/qemu-block-drivers.7: docs/qemu-block-drivers.texi
1067
1068
docs/qemu-cpu-models.7: docs/qemu-cpu-models.texi
1068
1069
scripts/qemu-trace-stap.1: scripts/qemu-trace-stap.texi
1069
1070
···
1076
1077
qemu-img.texi qemu-options.texi \
1077
1078
qemu-tech.texi qemu-option-trace.texi \
1078
1079
qemu-deprecated.texi qemu-monitor.texi qemu-img-cmds.texi \
1079
-
qemu-monitor-info.texi docs/qemu-block-drivers.texi \
1080
+
qemu-monitor-info.texi \
1080
1081
docs/qemu-cpu-models.texi docs/security.texi
1081
1082
1082
1083
docs/interop/qemu-ga-ref.dvi docs/interop/qemu-ga-ref.html \
-889
docs/qemu-block-drivers.texi
-889
docs/qemu-block-drivers.texi
···
1
-
@c man begin SYNOPSIS
2
-
QEMU block driver reference manual
3
-
@c man end
4
-
5
-
@set qemu_system qemu-system-x86_64
6
-
7
-
@c man begin DESCRIPTION
8
-
9
-
@node disk_images_formats
10
-
@subsection Disk image file formats
11
-
12
-
QEMU supports many image file formats that can be used with VMs as well as with
13
-
any of the tools (like @code{qemu-img}). This includes the preferred formats
14
-
raw and qcow2 as well as formats that are supported for compatibility with
15
-
older QEMU versions or other hypervisors.
16
-
17
-
Depending on the image format, different options can be passed to
18
-
@code{qemu-img create} and @code{qemu-img convert} using the @code{-o} option.
19
-
This section describes each format and the options that are supported for it.
20
-
21
-
@table @option
22
-
@item raw
23
-
24
-
Raw disk image format. This format has the advantage of
25
-
being simple and easily exportable to all other emulators. If your
26
-
file system supports @emph{holes} (for example in ext2 or ext3 on
27
-
Linux or NTFS on Windows), then only the written sectors will reserve
28
-
space. Use @code{qemu-img info} to know the real size used by the
29
-
image or @code{ls -ls} on Unix/Linux.
30
-
31
-
Supported options:
32
-
@table @code
33
-
@item preallocation
34
-
Preallocation mode (allowed values: @code{off}, @code{falloc}, @code{full}).
35
-
@code{falloc} mode preallocates space for image by calling posix_fallocate().
36
-
@code{full} mode preallocates space for image by writing data to underlying
37
-
storage. This data may or may not be zero, depending on the storage location.
38
-
@end table
39
-
40
-
@item qcow2
41
-
QEMU image format, the most versatile format. Use it to have smaller
42
-
images (useful if your filesystem does not supports holes, for example
43
-
on Windows), zlib based compression and support of multiple VM
44
-
snapshots.
45
-
46
-
Supported options:
47
-
@table @code
48
-
@item compat
49
-
Determines the qcow2 version to use. @code{compat=0.10} uses the
50
-
traditional image format that can be read by any QEMU since 0.10.
51
-
@code{compat=1.1} enables image format extensions that only QEMU 1.1 and
52
-
newer understand (this is the default). Amongst others, this includes
53
-
zero clusters, which allow efficient copy-on-read for sparse images.
54
-
55
-
@item backing_file
56
-
File name of a base image (see @option{create} subcommand)
57
-
@item backing_fmt
58
-
Image format of the base image
59
-
@item encryption
60
-
This option is deprecated and equivalent to @code{encrypt.format=aes}
61
-
62
-
@item encrypt.format
63
-
64
-
If this is set to @code{luks}, it requests that the qcow2 payload (not
65
-
qcow2 header) be encrypted using the LUKS format. The passphrase to
66
-
use to unlock the LUKS key slot is given by the @code{encrypt.key-secret}
67
-
parameter. LUKS encryption parameters can be tuned with the other
68
-
@code{encrypt.*} parameters.
69
-
70
-
If this is set to @code{aes}, the image is encrypted with 128-bit AES-CBC.
71
-
The encryption key is given by the @code{encrypt.key-secret} parameter.
72
-
This encryption format is considered to be flawed by modern cryptography
73
-
standards, suffering from a number of design problems:
74
-
75
-
@itemize @minus
76
-
@item The AES-CBC cipher is used with predictable initialization vectors based
77
-
on the sector number. This makes it vulnerable to chosen plaintext attacks
78
-
which can reveal the existence of encrypted data.
79
-
@item The user passphrase is directly used as the encryption key. A poorly
80
-
chosen or short passphrase will compromise the security of the encryption.
81
-
@item In the event of the passphrase being compromised there is no way to
82
-
change the passphrase to protect data in any qcow images. The files must
83
-
be cloned, using a different encryption passphrase in the new file. The
84
-
original file must then be securely erased using a program like shred,
85
-
though even this is ineffective with many modern storage technologies.
86
-
@end itemize
87
-
88
-
The use of this is no longer supported in system emulators. Support only
89
-
remains in the command line utilities, for the purposes of data liberation
90
-
and interoperability with old versions of QEMU. The @code{luks} format
91
-
should be used instead.
92
-
93
-
@item encrypt.key-secret
94
-
95
-
Provides the ID of a @code{secret} object that contains the passphrase
96
-
(@code{encrypt.format=luks}) or encryption key (@code{encrypt.format=aes}).
97
-
98
-
@item encrypt.cipher-alg
99
-
100
-
Name of the cipher algorithm and key length. Currently defaults
101
-
to @code{aes-256}. Only used when @code{encrypt.format=luks}.
102
-
103
-
@item encrypt.cipher-mode
104
-
105
-
Name of the encryption mode to use. Currently defaults to @code{xts}.
106
-
Only used when @code{encrypt.format=luks}.
107
-
108
-
@item encrypt.ivgen-alg
109
-
110
-
Name of the initialization vector generator algorithm. Currently defaults
111
-
to @code{plain64}. Only used when @code{encrypt.format=luks}.
112
-
113
-
@item encrypt.ivgen-hash-alg
114
-
115
-
Name of the hash algorithm to use with the initialization vector generator
116
-
(if required). Defaults to @code{sha256}. Only used when @code{encrypt.format=luks}.
117
-
118
-
@item encrypt.hash-alg
119
-
120
-
Name of the hash algorithm to use for PBKDF algorithm
121
-
Defaults to @code{sha256}. Only used when @code{encrypt.format=luks}.
122
-
123
-
@item encrypt.iter-time
124
-
125
-
Amount of time, in milliseconds, to use for PBKDF algorithm per key slot.
126
-
Defaults to @code{2000}. Only used when @code{encrypt.format=luks}.
127
-
128
-
@item cluster_size
129
-
Changes the qcow2 cluster size (must be between 512 and 2M). Smaller cluster
130
-
sizes can improve the image file size whereas larger cluster sizes generally
131
-
provide better performance.
132
-
133
-
@item preallocation
134
-
Preallocation mode (allowed values: @code{off}, @code{metadata}, @code{falloc},
135
-
@code{full}). An image with preallocated metadata is initially larger but can
136
-
improve performance when the image needs to grow. @code{falloc} and @code{full}
137
-
preallocations are like the same options of @code{raw} format, but sets up
138
-
metadata also.
139
-
140
-
@item lazy_refcounts
141
-
If this option is set to @code{on}, reference count updates are postponed with
142
-
the goal of avoiding metadata I/O and improving performance. This is
143
-
particularly interesting with @option{cache=writethrough} which doesn't batch
144
-
metadata updates. The tradeoff is that after a host crash, the reference count
145
-
tables must be rebuilt, i.e. on the next open an (automatic) @code{qemu-img
146
-
check -r all} is required, which may take some time.
147
-
148
-
This option can only be enabled if @code{compat=1.1} is specified.
149
-
150
-
@item nocow
151
-
If this option is set to @code{on}, it will turn off COW of the file. It's only
152
-
valid on btrfs, no effect on other file systems.
153
-
154
-
Btrfs has low performance when hosting a VM image file, even more when the guest
155
-
on the VM also using btrfs as file system. Turning off COW is a way to mitigate
156
-
this bad performance. Generally there are two ways to turn off COW on btrfs:
157
-
a) Disable it by mounting with nodatacow, then all newly created files will be
158
-
NOCOW. b) For an empty file, add the NOCOW file attribute. That's what this option
159
-
does.
160
-
161
-
Note: this option is only valid to new or empty files. If there is an existing
162
-
file which is COW and has data blocks already, it couldn't be changed to NOCOW
163
-
by setting @code{nocow=on}. One can issue @code{lsattr filename} to check if
164
-
the NOCOW flag is set or not (Capital 'C' is NOCOW flag).
165
-
166
-
@end table
167
-
168
-
@item qed
169
-
Old QEMU image format with support for backing files and compact image files
170
-
(when your filesystem or transport medium does not support holes).
171
-
172
-
When converting QED images to qcow2, you might want to consider using the
173
-
@code{lazy_refcounts=on} option to get a more QED-like behaviour.
174
-
175
-
Supported options:
176
-
@table @code
177
-
@item backing_file
178
-
File name of a base image (see @option{create} subcommand).
179
-
@item backing_fmt
180
-
Image file format of backing file (optional). Useful if the format cannot be
181
-
autodetected because it has no header, like some vhd/vpc files.
182
-
@item cluster_size
183
-
Changes the cluster size (must be power-of-2 between 4K and 64K). Smaller
184
-
cluster sizes can improve the image file size whereas larger cluster sizes
185
-
generally provide better performance.
186
-
@item table_size
187
-
Changes the number of clusters per L1/L2 table (must be power-of-2 between 1
188
-
and 16). There is normally no need to change this value but this option can be
189
-
used for performance benchmarking.
190
-
@end table
191
-
192
-
@item qcow
193
-
Old QEMU image format with support for backing files, compact image files,
194
-
encryption and compression.
195
-
196
-
Supported options:
197
-
@table @code
198
-
@item backing_file
199
-
File name of a base image (see @option{create} subcommand)
200
-
@item encryption
201
-
This option is deprecated and equivalent to @code{encrypt.format=aes}
202
-
203
-
@item encrypt.format
204
-
If this is set to @code{aes}, the image is encrypted with 128-bit AES-CBC.
205
-
The encryption key is given by the @code{encrypt.key-secret} parameter.
206
-
This encryption format is considered to be flawed by modern cryptography
207
-
standards, suffering from a number of design problems enumerated previously
208
-
against the @code{qcow2} image format.
209
-
210
-
The use of this is no longer supported in system emulators. Support only
211
-
remains in the command line utilities, for the purposes of data liberation
212
-
and interoperability with old versions of QEMU.
213
-
214
-
Users requiring native encryption should use the @code{qcow2} format
215
-
instead with @code{encrypt.format=luks}.
216
-
217
-
@item encrypt.key-secret
218
-
219
-
Provides the ID of a @code{secret} object that contains the encryption
220
-
key (@code{encrypt.format=aes}).
221
-
222
-
@end table
223
-
224
-
@item luks
225
-
226
-
LUKS v1 encryption format, compatible with Linux dm-crypt/cryptsetup
227
-
228
-
Supported options:
229
-
@table @code
230
-
231
-
@item key-secret
232
-
233
-
Provides the ID of a @code{secret} object that contains the passphrase.
234
-
235
-
@item cipher-alg
236
-
237
-
Name of the cipher algorithm and key length. Currently defaults
238
-
to @code{aes-256}.
239
-
240
-
@item cipher-mode
241
-
242
-
Name of the encryption mode to use. Currently defaults to @code{xts}.
243
-
244
-
@item ivgen-alg
245
-
246
-
Name of the initialization vector generator algorithm. Currently defaults
247
-
to @code{plain64}.
248
-
249
-
@item ivgen-hash-alg
250
-
251
-
Name of the hash algorithm to use with the initialization vector generator
252
-
(if required). Defaults to @code{sha256}.
253
-
254
-
@item hash-alg
255
-
256
-
Name of the hash algorithm to use for PBKDF algorithm
257
-
Defaults to @code{sha256}.
258
-
259
-
@item iter-time
260
-
261
-
Amount of time, in milliseconds, to use for PBKDF algorithm per key slot.
262
-
Defaults to @code{2000}.
263
-
264
-
@end table
265
-
266
-
@item vdi
267
-
VirtualBox 1.1 compatible image format.
268
-
Supported options:
269
-
@table @code
270
-
@item static
271
-
If this option is set to @code{on}, the image is created with metadata
272
-
preallocation.
273
-
@end table
274
-
275
-
@item vmdk
276
-
VMware 3 and 4 compatible image format.
277
-
278
-
Supported options:
279
-
@table @code
280
-
@item backing_file
281
-
File name of a base image (see @option{create} subcommand).
282
-
@item compat6
283
-
Create a VMDK version 6 image (instead of version 4)
284
-
@item hwversion
285
-
Specify vmdk virtual hardware version. Compat6 flag cannot be enabled
286
-
if hwversion is specified.
287
-
@item subformat
288
-
Specifies which VMDK subformat to use. Valid options are
289
-
@code{monolithicSparse} (default),
290
-
@code{monolithicFlat},
291
-
@code{twoGbMaxExtentSparse},
292
-
@code{twoGbMaxExtentFlat} and
293
-
@code{streamOptimized}.
294
-
@end table
295
-
296
-
@item vpc
297
-
VirtualPC compatible image format (VHD).
298
-
Supported options:
299
-
@table @code
300
-
@item subformat
301
-
Specifies which VHD subformat to use. Valid options are
302
-
@code{dynamic} (default) and @code{fixed}.
303
-
@end table
304
-
305
-
@item VHDX
306
-
Hyper-V compatible image format (VHDX).
307
-
Supported options:
308
-
@table @code
309
-
@item subformat
310
-
Specifies which VHDX subformat to use. Valid options are
311
-
@code{dynamic} (default) and @code{fixed}.
312
-
@item block_state_zero
313
-
Force use of payload blocks of type 'ZERO'. Can be set to @code{on} (default)
314
-
or @code{off}. When set to @code{off}, new blocks will be created as
315
-
@code{PAYLOAD_BLOCK_NOT_PRESENT}, which means parsers are free to return
316
-
arbitrary data for those blocks. Do not set to @code{off} when using
317
-
@code{qemu-img convert} with @code{subformat=dynamic}.
318
-
@item block_size
319
-
Block size; min 1 MB, max 256 MB. 0 means auto-calculate based on image size.
320
-
@item log_size
321
-
Log size; min 1 MB.
322
-
@end table
323
-
@end table
324
-
325
-
@subsubsection Read-only formats
326
-
More disk image file formats are supported in a read-only mode.
327
-
@table @option
328
-
@item bochs
329
-
Bochs images of @code{growing} type.
330
-
@item cloop
331
-
Linux Compressed Loop image, useful only to reuse directly compressed
332
-
CD-ROM images present for example in the Knoppix CD-ROMs.
333
-
@item dmg
334
-
Apple disk image.
335
-
@item parallels
336
-
Parallels disk image format.
337
-
@end table
338
-
339
-
340
-
@node host_drives
341
-
@subsection Using host drives
342
-
343
-
In addition to disk image files, QEMU can directly access host
344
-
devices. We describe here the usage for QEMU version >= 0.8.3.
345
-
346
-
@subsubsection Linux
347
-
348
-
On Linux, you can directly use the host device filename instead of a
349
-
disk image filename provided you have enough privileges to access
350
-
it. For example, use @file{/dev/cdrom} to access to the CDROM.
351
-
352
-
@table @code
353
-
@item CD
354
-
You can specify a CDROM device even if no CDROM is loaded. QEMU has
355
-
specific code to detect CDROM insertion or removal. CDROM ejection by
356
-
the guest OS is supported. Currently only data CDs are supported.
357
-
@item Floppy
358
-
You can specify a floppy device even if no floppy is loaded. Floppy
359
-
removal is currently not detected accurately (if you change floppy
360
-
without doing floppy access while the floppy is not loaded, the guest
361
-
OS will think that the same floppy is loaded).
362
-
Use of the host's floppy device is deprecated, and support for it will
363
-
be removed in a future release.
364
-
@item Hard disks
365
-
Hard disks can be used. Normally you must specify the whole disk
366
-
(@file{/dev/hdb} instead of @file{/dev/hdb1}) so that the guest OS can
367
-
see it as a partitioned disk. WARNING: unless you know what you do, it
368
-
is better to only make READ-ONLY accesses to the hard disk otherwise
369
-
you may corrupt your host data (use the @option{-snapshot} command
370
-
line option or modify the device permissions accordingly).
371
-
@end table
372
-
373
-
@subsubsection Windows
374
-
375
-
@table @code
376
-
@item CD
377
-
The preferred syntax is the drive letter (e.g. @file{d:}). The
378
-
alternate syntax @file{\\.\d:} is supported. @file{/dev/cdrom} is
379
-
supported as an alias to the first CDROM drive.
380
-
381
-
Currently there is no specific code to handle removable media, so it
382
-
is better to use the @code{change} or @code{eject} monitor commands to
383
-
change or eject media.
384
-
@item Hard disks
385
-
Hard disks can be used with the syntax: @file{\\.\PhysicalDrive@var{N}}
386
-
where @var{N} is the drive number (0 is the first hard disk).
387
-
388
-
WARNING: unless you know what you do, it is better to only make
389
-
READ-ONLY accesses to the hard disk otherwise you may corrupt your
390
-
host data (use the @option{-snapshot} command line so that the
391
-
modifications are written in a temporary file).
392
-
@end table
393
-
394
-
395
-
@subsubsection Mac OS X
396
-
397
-
@file{/dev/cdrom} is an alias to the first CDROM.
398
-
399
-
Currently there is no specific code to handle removable media, so it
400
-
is better to use the @code{change} or @code{eject} monitor commands to
401
-
change or eject media.
402
-
403
-
@node disk_images_fat_images
404
-
@subsection Virtual FAT disk images
405
-
406
-
QEMU can automatically create a virtual FAT disk image from a
407
-
directory tree. In order to use it, just type:
408
-
409
-
@example
410
-
@value{qemu_system} linux.img -hdb fat:/my_directory
411
-
@end example
412
-
413
-
Then you access access to all the files in the @file{/my_directory}
414
-
directory without having to copy them in a disk image or to export
415
-
them via SAMBA or NFS. The default access is @emph{read-only}.
416
-
417
-
Floppies can be emulated with the @code{:floppy:} option:
418
-
419
-
@example
420
-
@value{qemu_system} linux.img -fda fat:floppy:/my_directory
421
-
@end example
422
-
423
-
A read/write support is available for testing (beta stage) with the
424
-
@code{:rw:} option:
425
-
426
-
@example
427
-
@value{qemu_system} linux.img -fda fat:floppy:rw:/my_directory
428
-
@end example
429
-
430
-
What you should @emph{never} do:
431
-
@itemize
432
-
@item use non-ASCII filenames ;
433
-
@item use "-snapshot" together with ":rw:" ;
434
-
@item expect it to work when loadvm'ing ;
435
-
@item write to the FAT directory on the host system while accessing it with the guest system.
436
-
@end itemize
437
-
438
-
@node disk_images_nbd
439
-
@subsection NBD access
440
-
441
-
QEMU can access directly to block device exported using the Network Block Device
442
-
protocol.
443
-
444
-
@example
445
-
@value{qemu_system} linux.img -hdb nbd://my_nbd_server.mydomain.org:1024/
446
-
@end example
447
-
448
-
If the NBD server is located on the same host, you can use an unix socket instead
449
-
of an inet socket:
450
-
451
-
@example
452
-
@value{qemu_system} linux.img -hdb nbd+unix://?socket=/tmp/my_socket
453
-
@end example
454
-
455
-
In this case, the block device must be exported using qemu-nbd:
456
-
457
-
@example
458
-
qemu-nbd --socket=/tmp/my_socket my_disk.qcow2
459
-
@end example
460
-
461
-
The use of qemu-nbd allows sharing of a disk between several guests:
462
-
@example
463
-
qemu-nbd --socket=/tmp/my_socket --share=2 my_disk.qcow2
464
-
@end example
465
-
466
-
@noindent
467
-
and then you can use it with two guests:
468
-
@example
469
-
@value{qemu_system} linux1.img -hdb nbd+unix://?socket=/tmp/my_socket
470
-
@value{qemu_system} linux2.img -hdb nbd+unix://?socket=/tmp/my_socket
471
-
@end example
472
-
473
-
If the nbd-server uses named exports (supported since NBD 2.9.18, or with QEMU's
474
-
own embedded NBD server), you must specify an export name in the URI:
475
-
@example
476
-
@value{qemu_system} -cdrom nbd://localhost/debian-500-ppc-netinst
477
-
@value{qemu_system} -cdrom nbd://localhost/openSUSE-11.1-ppc-netinst
478
-
@end example
479
-
480
-
The URI syntax for NBD is supported since QEMU 1.3. An alternative syntax is
481
-
also available. Here are some example of the older syntax:
482
-
@example
483
-
@value{qemu_system} linux.img -hdb nbd:my_nbd_server.mydomain.org:1024
484
-
@value{qemu_system} linux2.img -hdb nbd:unix:/tmp/my_socket
485
-
@value{qemu_system} -cdrom nbd:localhost:10809:exportname=debian-500-ppc-netinst
486
-
@end example
487
-
488
-
@node disk_images_sheepdog
489
-
@subsection Sheepdog disk images
490
-
491
-
Sheepdog is a distributed storage system for QEMU. It provides highly
492
-
available block level storage volumes that can be attached to
493
-
QEMU-based virtual machines.
494
-
495
-
You can create a Sheepdog disk image with the command:
496
-
@example
497
-
qemu-img create sheepdog:///@var{image} @var{size}
498
-
@end example
499
-
where @var{image} is the Sheepdog image name and @var{size} is its
500
-
size.
501
-
502
-
To import the existing @var{filename} to Sheepdog, you can use a
503
-
convert command.
504
-
@example
505
-
qemu-img convert @var{filename} sheepdog:///@var{image}
506
-
@end example
507
-
508
-
You can boot from the Sheepdog disk image with the command:
509
-
@example
510
-
@value{qemu_system} sheepdog:///@var{image}
511
-
@end example
512
-
513
-
You can also create a snapshot of the Sheepdog image like qcow2.
514
-
@example
515
-
qemu-img snapshot -c @var{tag} sheepdog:///@var{image}
516
-
@end example
517
-
where @var{tag} is a tag name of the newly created snapshot.
518
-
519
-
To boot from the Sheepdog snapshot, specify the tag name of the
520
-
snapshot.
521
-
@example
522
-
@value{qemu_system} sheepdog:///@var{image}#@var{tag}
523
-
@end example
524
-
525
-
You can create a cloned image from the existing snapshot.
526
-
@example
527
-
qemu-img create -b sheepdog:///@var{base}#@var{tag} sheepdog:///@var{image}
528
-
@end example
529
-
where @var{base} is an image name of the source snapshot and @var{tag}
530
-
is its tag name.
531
-
532
-
You can use an unix socket instead of an inet socket:
533
-
534
-
@example
535
-
@value{qemu_system} sheepdog+unix:///@var{image}?socket=@var{path}
536
-
@end example
537
-
538
-
If the Sheepdog daemon doesn't run on the local host, you need to
539
-
specify one of the Sheepdog servers to connect to.
540
-
@example
541
-
qemu-img create sheepdog://@var{hostname}:@var{port}/@var{image} @var{size}
542
-
@value{qemu_system} sheepdog://@var{hostname}:@var{port}/@var{image}
543
-
@end example
544
-
545
-
@node disk_images_iscsi
546
-
@subsection iSCSI LUNs
547
-
548
-
iSCSI is a popular protocol used to access SCSI devices across a computer
549
-
network.
550
-
551
-
There are two different ways iSCSI devices can be used by QEMU.
552
-
553
-
The first method is to mount the iSCSI LUN on the host, and make it appear as
554
-
any other ordinary SCSI device on the host and then to access this device as a
555
-
/dev/sd device from QEMU. How to do this differs between host OSes.
556
-
557
-
The second method involves using the iSCSI initiator that is built into
558
-
QEMU. This provides a mechanism that works the same way regardless of which
559
-
host OS you are running QEMU on. This section will describe this second method
560
-
of using iSCSI together with QEMU.
561
-
562
-
In QEMU, iSCSI devices are described using special iSCSI URLs
563
-
564
-
@example
565
-
URL syntax:
566
-
iscsi://[<username>[%<password>]@@]<host>[:<port>]/<target-iqn-name>/<lun>
567
-
@end example
568
-
569
-
Username and password are optional and only used if your target is set up
570
-
using CHAP authentication for access control.
571
-
Alternatively the username and password can also be set via environment
572
-
variables to have these not show up in the process list
573
-
574
-
@example
575
-
export LIBISCSI_CHAP_USERNAME=<username>
576
-
export LIBISCSI_CHAP_PASSWORD=<password>
577
-
iscsi://<host>/<target-iqn-name>/<lun>
578
-
@end example
579
-
580
-
Various session related parameters can be set via special options, either
581
-
in a configuration file provided via '-readconfig' or directly on the
582
-
command line.
583
-
584
-
If the initiator-name is not specified qemu will use a default name
585
-
of 'iqn.2008-11.org.linux-kvm[:<uuid>'] where <uuid> is the UUID of the
586
-
virtual machine. If the UUID is not specified qemu will use
587
-
'iqn.2008-11.org.linux-kvm[:<name>'] where <name> is the name of the
588
-
virtual machine.
589
-
590
-
@example
591
-
Setting a specific initiator name to use when logging in to the target
592
-
-iscsi initiator-name=iqn.qemu.test:my-initiator
593
-
@end example
594
-
595
-
@example
596
-
Controlling which type of header digest to negotiate with the target
597
-
-iscsi header-digest=CRC32C|CRC32C-NONE|NONE-CRC32C|NONE
598
-
@end example
599
-
600
-
These can also be set via a configuration file
601
-
@example
602
-
[iscsi]
603
-
user = "CHAP username"
604
-
password = "CHAP password"
605
-
initiator-name = "iqn.qemu.test:my-initiator"
606
-
# header digest is one of CRC32C|CRC32C-NONE|NONE-CRC32C|NONE
607
-
header-digest = "CRC32C"
608
-
@end example
609
-
610
-
611
-
Setting the target name allows different options for different targets
612
-
@example
613
-
[iscsi "iqn.target.name"]
614
-
user = "CHAP username"
615
-
password = "CHAP password"
616
-
initiator-name = "iqn.qemu.test:my-initiator"
617
-
# header digest is one of CRC32C|CRC32C-NONE|NONE-CRC32C|NONE
618
-
header-digest = "CRC32C"
619
-
@end example
620
-
621
-
622
-
Howto use a configuration file to set iSCSI configuration options:
623
-
@example
624
-
cat >iscsi.conf <<EOF
625
-
[iscsi]
626
-
user = "me"
627
-
password = "my password"
628
-
initiator-name = "iqn.qemu.test:my-initiator"
629
-
header-digest = "CRC32C"
630
-
EOF
631
-
632
-
@value{qemu_system} -drive file=iscsi://127.0.0.1/iqn.qemu.test/1 \
633
-
-readconfig iscsi.conf
634
-
@end example
635
-
636
-
637
-
How to set up a simple iSCSI target on loopback and access it via QEMU:
638
-
@example
639
-
This example shows how to set up an iSCSI target with one CDROM and one DISK
640
-
using the Linux STGT software target. This target is available on Red Hat based
641
-
systems as the package 'scsi-target-utils'.
642
-
643
-
tgtd --iscsi portal=127.0.0.1:3260
644
-
tgtadm --lld iscsi --op new --mode target --tid 1 -T iqn.qemu.test
645
-
tgtadm --lld iscsi --mode logicalunit --op new --tid 1 --lun 1 \
646
-
-b /IMAGES/disk.img --device-type=disk
647
-
tgtadm --lld iscsi --mode logicalunit --op new --tid 1 --lun 2 \
648
-
-b /IMAGES/cd.iso --device-type=cd
649
-
tgtadm --lld iscsi --op bind --mode target --tid 1 -I ALL
650
-
651
-
@value{qemu_system} -iscsi initiator-name=iqn.qemu.test:my-initiator \
652
-
-boot d -drive file=iscsi://127.0.0.1/iqn.qemu.test/1 \
653
-
-cdrom iscsi://127.0.0.1/iqn.qemu.test/2
654
-
@end example
655
-
656
-
@node disk_images_gluster
657
-
@subsection GlusterFS disk images
658
-
659
-
GlusterFS is a user space distributed file system.
660
-
661
-
You can boot from the GlusterFS disk image with the command:
662
-
@example
663
-
URI:
664
-
@value{qemu_system} -drive file=gluster[+@var{type}]://[@var{host}[:@var{port}]]/@var{volume}/@var{path}
665
-
[?socket=...][,file.debug=9][,file.logfile=...]
666
-
667
-
JSON:
668
-
@value{qemu_system} 'json:@{"driver":"qcow2",
669
-
"file":@{"driver":"gluster",
670
-
"volume":"testvol","path":"a.img","debug":9,"logfile":"...",
671
-
"server":[@{"type":"tcp","host":"...","port":"..."@},
672
-
@{"type":"unix","socket":"..."@}]@}@}'
673
-
@end example
674
-
675
-
@var{gluster} is the protocol.
676
-
677
-
@var{type} specifies the transport type used to connect to gluster
678
-
management daemon (glusterd). Valid transport types are
679
-
tcp and unix. In the URI form, if a transport type isn't specified,
680
-
then tcp type is assumed.
681
-
682
-
@var{host} specifies the server where the volume file specification for
683
-
the given volume resides. This can be either a hostname or an ipv4 address.
684
-
If transport type is unix, then @var{host} field should not be specified.
685
-
Instead @var{socket} field needs to be populated with the path to unix domain
686
-
socket.
687
-
688
-
@var{port} is the port number on which glusterd is listening. This is optional
689
-
and if not specified, it defaults to port 24007. If the transport type is unix,
690
-
then @var{port} should not be specified.
691
-
692
-
@var{volume} is the name of the gluster volume which contains the disk image.
693
-
694
-
@var{path} is the path to the actual disk image that resides on gluster volume.
695
-
696
-
@var{debug} is the logging level of the gluster protocol driver. Debug levels
697
-
are 0-9, with 9 being the most verbose, and 0 representing no debugging output.
698
-
The default level is 4. The current logging levels defined in the gluster source
699
-
are 0 - None, 1 - Emergency, 2 - Alert, 3 - Critical, 4 - Error, 5 - Warning,
700
-
6 - Notice, 7 - Info, 8 - Debug, 9 - Trace
701
-
702
-
@var{logfile} is a commandline option to mention log file path which helps in
703
-
logging to the specified file and also help in persisting the gfapi logs. The
704
-
default is stderr.
705
-
706
-
707
-
708
-
709
-
You can create a GlusterFS disk image with the command:
710
-
@example
711
-
qemu-img create gluster://@var{host}/@var{volume}/@var{path} @var{size}
712
-
@end example
713
-
714
-
Examples
715
-
@example
716
-
@value{qemu_system} -drive file=gluster://1.2.3.4/testvol/a.img
717
-
@value{qemu_system} -drive file=gluster+tcp://1.2.3.4/testvol/a.img
718
-
@value{qemu_system} -drive file=gluster+tcp://1.2.3.4:24007/testvol/dir/a.img
719
-
@value{qemu_system} -drive file=gluster+tcp://[1:2:3:4:5:6:7:8]/testvol/dir/a.img
720
-
@value{qemu_system} -drive file=gluster+tcp://[1:2:3:4:5:6:7:8]:24007/testvol/dir/a.img
721
-
@value{qemu_system} -drive file=gluster+tcp://server.domain.com:24007/testvol/dir/a.img
722
-
@value{qemu_system} -drive file=gluster+unix:///testvol/dir/a.img?socket=/tmp/glusterd.socket
723
-
@value{qemu_system} -drive file=gluster+rdma://1.2.3.4:24007/testvol/a.img
724
-
@value{qemu_system} -drive file=gluster://1.2.3.4/testvol/a.img,file.debug=9,file.logfile=/var/log/qemu-gluster.log
725
-
@value{qemu_system} 'json:@{"driver":"qcow2",
726
-
"file":@{"driver":"gluster",
727
-
"volume":"testvol","path":"a.img",
728
-
"debug":9,"logfile":"/var/log/qemu-gluster.log",
729
-
"server":[@{"type":"tcp","host":"1.2.3.4","port":24007@},
730
-
@{"type":"unix","socket":"/var/run/glusterd.socket"@}]@}@}'
731
-
@value{qemu_system} -drive driver=qcow2,file.driver=gluster,file.volume=testvol,file.path=/path/a.img,
732
-
file.debug=9,file.logfile=/var/log/qemu-gluster.log,
733
-
file.server.0.type=tcp,file.server.0.host=1.2.3.4,file.server.0.port=24007,
734
-
file.server.1.type=unix,file.server.1.socket=/var/run/glusterd.socket
735
-
@end example
736
-
737
-
@node disk_images_ssh
738
-
@subsection Secure Shell (ssh) disk images
739
-
740
-
You can access disk images located on a remote ssh server
741
-
by using the ssh protocol:
742
-
743
-
@example
744
-
@value{qemu_system} -drive file=ssh://[@var{user}@@]@var{server}[:@var{port}]/@var{path}[?host_key_check=@var{host_key_check}]
745
-
@end example
746
-
747
-
Alternative syntax using properties:
748
-
749
-
@example
750
-
@value{qemu_system} -drive file.driver=ssh[,file.user=@var{user}],file.host=@var{server}[,file.port=@var{port}],file.path=@var{path}[,file.host_key_check=@var{host_key_check}]
751
-
@end example
752
-
753
-
@var{ssh} is the protocol.
754
-
755
-
@var{user} is the remote user. If not specified, then the local
756
-
username is tried.
757
-
758
-
@var{server} specifies the remote ssh server. Any ssh server can be
759
-
used, but it must implement the sftp-server protocol. Most Unix/Linux
760
-
systems should work without requiring any extra configuration.
761
-
762
-
@var{port} is the port number on which sshd is listening. By default
763
-
the standard ssh port (22) is used.
764
-
765
-
@var{path} is the path to the disk image.
766
-
767
-
The optional @var{host_key_check} parameter controls how the remote
768
-
host's key is checked. The default is @code{yes} which means to use
769
-
the local @file{.ssh/known_hosts} file. Setting this to @code{no}
770
-
turns off known-hosts checking. Or you can check that the host key
771
-
matches a specific fingerprint:
772
-
@code{host_key_check=md5:78:45:8e:14:57:4f:d5:45:83:0a:0e:f3:49:82:c9:c8}
773
-
(@code{sha1:} can also be used as a prefix, but note that OpenSSH
774
-
tools only use MD5 to print fingerprints).
775
-
776
-
Currently authentication must be done using ssh-agent. Other
777
-
authentication methods may be supported in future.
778
-
779
-
Note: Many ssh servers do not support an @code{fsync}-style operation.
780
-
The ssh driver cannot guarantee that disk flush requests are
781
-
obeyed, and this causes a risk of disk corruption if the remote
782
-
server or network goes down during writes. The driver will
783
-
print a warning when @code{fsync} is not supported:
784
-
785
-
warning: ssh server @code{ssh.example.com:22} does not support fsync
786
-
787
-
With sufficiently new versions of libssh and OpenSSH, @code{fsync} is
788
-
supported.
789
-
790
-
@node disk_images_nvme
791
-
@subsection NVMe disk images
792
-
793
-
NVM Express (NVMe) storage controllers can be accessed directly by a userspace
794
-
driver in QEMU. This bypasses the host kernel file system and block layers
795
-
while retaining QEMU block layer functionalities, such as block jobs, I/O
796
-
throttling, image formats, etc. Disk I/O performance is typically higher than
797
-
with @code{-drive file=/dev/sda} using either thread pool or linux-aio.
798
-
799
-
The controller will be exclusively used by the QEMU process once started. To be
800
-
able to share storage between multiple VMs and other applications on the host,
801
-
please use the file based protocols.
802
-
803
-
Before starting QEMU, bind the host NVMe controller to the host vfio-pci
804
-
driver. For example:
805
-
806
-
@example
807
-
# modprobe vfio-pci
808
-
# lspci -n -s 0000:06:0d.0
809
-
06:0d.0 0401: 1102:0002 (rev 08)
810
-
# echo 0000:06:0d.0 > /sys/bus/pci/devices/0000:06:0d.0/driver/unbind
811
-
# echo 1102 0002 > /sys/bus/pci/drivers/vfio-pci/new_id
812
-
813
-
# @value{qemu_system} -drive file=nvme://@var{host}:@var{bus}:@var{slot}.@var{func}/@var{namespace}
814
-
@end example
815
-
816
-
Alternative syntax using properties:
817
-
818
-
@example
819
-
@value{qemu_system} -drive file.driver=nvme,file.device=@var{host}:@var{bus}:@var{slot}.@var{func},file.namespace=@var{namespace}
820
-
@end example
821
-
822
-
@var{host}:@var{bus}:@var{slot}.@var{func} is the NVMe controller's PCI device
823
-
address on the host.
824
-
825
-
@var{namespace} is the NVMe namespace number, starting from 1.
826
-
827
-
@node disk_image_locking
828
-
@subsection Disk image file locking
829
-
830
-
By default, QEMU tries to protect image files from unexpected concurrent
831
-
access, as long as it's supported by the block protocol driver and host
832
-
operating system. If multiple QEMU processes (including QEMU emulators and
833
-
utilities) try to open the same image with conflicting accessing modes, all but
834
-
the first one will get an error.
835
-
836
-
This feature is currently supported by the file protocol on Linux with the Open
837
-
File Descriptor (OFD) locking API, and can be configured to fall back to POSIX
838
-
locking if the POSIX host doesn't support Linux OFD locking.
839
-
840
-
To explicitly enable image locking, specify "locking=on" in the file protocol
841
-
driver options. If OFD locking is not possible, a warning will be printed and
842
-
the POSIX locking API will be used. In this case there is a risk that the lock
843
-
will get silently lost when doing hot plugging and block jobs, due to the
844
-
shortcomings of the POSIX locking API.
845
-
846
-
QEMU transparently handles lock handover during shared storage migration. For
847
-
shared virtual disk images between multiple VMs, the "share-rw" device option
848
-
should be used.
849
-
850
-
By default, the guest has exclusive write access to its disk image. If the
851
-
guest can safely share the disk image with other writers the @code{-device
852
-
...,share-rw=on} parameter can be used. This is only safe if the guest is
853
-
running software, such as a cluster file system, that coordinates disk accesses
854
-
to avoid corruption.
855
-
856
-
Note that share-rw=on only declares the guest's ability to share the disk.
857
-
Some QEMU features, such as image file formats, require exclusive write access
858
-
to the disk image and this is unaffected by the share-rw=on option.
859
-
860
-
Alternatively, locking can be fully disabled by "locking=off" block device
861
-
option. In the command line, the option is usually in the form of
862
-
"file.locking=off" as the protocol driver is normally placed as a "file" child
863
-
under a format driver. For example:
864
-
865
-
@code{-blockdev driver=qcow2,file.filename=/path/to/image,file.locking=off,file.driver=file}
866
-
867
-
To check if image locking is active, check the output of the "lslocks" command
868
-
on host and see if there are locks held by the QEMU process on the image file.
869
-
More than one byte could be locked by the QEMU instance, each byte of which
870
-
reflects a particular permission that is acquired or protected by the running
871
-
block driver.
872
-
873
-
@c man end
874
-
875
-
@ignore
876
-
877
-
@setfilename qemu-block-drivers
878
-
@settitle QEMU block drivers reference
879
-
880
-
@c man begin SEEALSO
881
-
The HTML documentation of QEMU for more precise information and Linux
882
-
user mode emulator invocation.
883
-
@c man end
884
-
885
-
@c man begin AUTHOR
886
-
Fabrice Bellard and the QEMU Project developers
887
-
@c man end
888
-
889
-
@end ignore
+7
docs/system/conf.py
+7
docs/system/conf.py
···
13
13
# This slightly misuses the 'description', but is the best way to get
14
14
# the manual title to appear in the sidebar.
15
15
html_theme_options['description'] = u'System Emulation User''s Guide'
16
+
# One entry per manual page. List of tuples
17
+
# (source start file, name, description, authors, manual section).
18
+
man_pages = [
19
+
('qemu-block-drivers', 'qemu-block-drivers',
20
+
u'QEMU block drivers reference',
21
+
['Fabrice Bellard and the QEMU Project developers'], 7)
22
+
]
+985
docs/system/qemu-block-drivers.rst
+985
docs/system/qemu-block-drivers.rst
···
1
+
QEMU block drivers reference
2
+
============================
3
+
4
+
.. |qemu_system| replace:: qemu-system-x86_64
5
+
6
+
..
7
+
We put the 'Synopsis' and 'See also' sections into the manpage, but not
8
+
the HTML. This makes the HTML docs read better and means the ToC in
9
+
the index has a more useful set of entries. Ideally, the section
10
+
headings 'Disk image file formats' would be top-level headings for
11
+
the HTML, but sub-headings of the conventional manpage 'Description'
12
+
header for the manpage. Unfortunately, due to deficiencies in
13
+
the Sphinx 'only' directive, this isn't possible: they must be headers
14
+
at the same level as 'Synopsis' and 'See also', otherwise Sphinx's
15
+
identification of which header underline style is which gets confused.
16
+
17
+
.. only:: man
18
+
19
+
Synopsis
20
+
--------
21
+
22
+
QEMU block driver reference manual
23
+
24
+
Disk image file formats
25
+
-----------------------
26
+
27
+
QEMU supports many image file formats that can be used with VMs as well as with
28
+
any of the tools (like ``qemu-img``). This includes the preferred formats
29
+
raw and qcow2 as well as formats that are supported for compatibility with
30
+
older QEMU versions or other hypervisors.
31
+
32
+
Depending on the image format, different options can be passed to
33
+
``qemu-img create`` and ``qemu-img convert`` using the ``-o`` option.
34
+
This section describes each format and the options that are supported for it.
35
+
36
+
.. program:: image-formats
37
+
.. option:: raw
38
+
39
+
Raw disk image format. This format has the advantage of
40
+
being simple and easily exportable to all other emulators. If your
41
+
file system supports *holes* (for example in ext2 or ext3 on
42
+
Linux or NTFS on Windows), then only the written sectors will reserve
43
+
space. Use ``qemu-img info`` to know the real size used by the
44
+
image or ``ls -ls`` on Unix/Linux.
45
+
46
+
Supported options:
47
+
48
+
.. program:: raw
49
+
.. option:: preallocation
50
+
51
+
Preallocation mode (allowed values: ``off``, ``falloc``,
52
+
``full``). ``falloc`` mode preallocates space for image by
53
+
calling ``posix_fallocate()``. ``full`` mode preallocates space
54
+
for image by writing data to underlying storage. This data may or
55
+
may not be zero, depending on the storage location.
56
+
57
+
.. program:: image-formats
58
+
.. option:: qcow2
59
+
60
+
QEMU image format, the most versatile format. Use it to have smaller
61
+
images (useful if your filesystem does not supports holes, for example
62
+
on Windows), zlib based compression and support of multiple VM
63
+
snapshots.
64
+
65
+
Supported options:
66
+
67
+
.. program:: qcow2
68
+
.. option:: compat
69
+
70
+
Determines the qcow2 version to use. ``compat=0.10`` uses the
71
+
traditional image format that can be read by any QEMU since 0.10.
72
+
``compat=1.1`` enables image format extensions that only QEMU 1.1 and
73
+
newer understand (this is the default). Amongst others, this includes
74
+
zero clusters, which allow efficient copy-on-read for sparse images.
75
+
76
+
.. option:: backing_file
77
+
78
+
File name of a base image (see ``create`` subcommand)
79
+
80
+
.. option:: backing_fmt
81
+
82
+
Image format of the base image
83
+
84
+
.. option:: encryption
85
+
86
+
This option is deprecated and equivalent to ``encrypt.format=aes``
87
+
88
+
.. option:: encrypt.format
89
+
90
+
If this is set to ``luks``, it requests that the qcow2 payload (not
91
+
qcow2 header) be encrypted using the LUKS format. The passphrase to
92
+
use to unlock the LUKS key slot is given by the ``encrypt.key-secret``
93
+
parameter. LUKS encryption parameters can be tuned with the other
94
+
``encrypt.*`` parameters.
95
+
96
+
If this is set to ``aes``, the image is encrypted with 128-bit AES-CBC.
97
+
The encryption key is given by the ``encrypt.key-secret`` parameter.
98
+
This encryption format is considered to be flawed by modern cryptography
99
+
standards, suffering from a number of design problems:
100
+
101
+
- The AES-CBC cipher is used with predictable initialization vectors based
102
+
on the sector number. This makes it vulnerable to chosen plaintext attacks
103
+
which can reveal the existence of encrypted data.
104
+
- The user passphrase is directly used as the encryption key. A poorly
105
+
chosen or short passphrase will compromise the security of the encryption.
106
+
- In the event of the passphrase being compromised there is no way to
107
+
change the passphrase to protect data in any qcow images. The files must
108
+
be cloned, using a different encryption passphrase in the new file. The
109
+
original file must then be securely erased using a program like shred,
110
+
though even this is ineffective with many modern storage technologies.
111
+
112
+
The use of this is no longer supported in system emulators. Support only
113
+
remains in the command line utilities, for the purposes of data liberation
114
+
and interoperability with old versions of QEMU. The ``luks`` format
115
+
should be used instead.
116
+
117
+
.. option:: encrypt.key-secret
118
+
119
+
Provides the ID of a ``secret`` object that contains the passphrase
120
+
(``encrypt.format=luks``) or encryption key (``encrypt.format=aes``).
121
+
122
+
.. option:: encrypt.cipher-alg
123
+
124
+
Name of the cipher algorithm and key length. Currently defaults
125
+
to ``aes-256``. Only used when ``encrypt.format=luks``.
126
+
127
+
.. option:: encrypt.cipher-mode
128
+
129
+
Name of the encryption mode to use. Currently defaults to ``xts``.
130
+
Only used when ``encrypt.format=luks``.
131
+
132
+
.. option:: encrypt.ivgen-alg
133
+
134
+
Name of the initialization vector generator algorithm. Currently defaults
135
+
to ``plain64``. Only used when ``encrypt.format=luks``.
136
+
137
+
.. option:: encrypt.ivgen-hash-alg
138
+
139
+
Name of the hash algorithm to use with the initialization vector generator
140
+
(if required). Defaults to ``sha256``. Only used when ``encrypt.format=luks``.
141
+
142
+
.. option:: encrypt.hash-alg
143
+
144
+
Name of the hash algorithm to use for PBKDF algorithm
145
+
Defaults to ``sha256``. Only used when ``encrypt.format=luks``.
146
+
147
+
.. option:: encrypt.iter-time
148
+
149
+
Amount of time, in milliseconds, to use for PBKDF algorithm per key slot.
150
+
Defaults to ``2000``. Only used when ``encrypt.format=luks``.
151
+
152
+
.. option:: cluster_size
153
+
154
+
Changes the qcow2 cluster size (must be between 512 and 2M). Smaller cluster
155
+
sizes can improve the image file size whereas larger cluster sizes generally
156
+
provide better performance.
157
+
158
+
.. option:: preallocation
159
+
160
+
Preallocation mode (allowed values: ``off``, ``metadata``, ``falloc``,
161
+
``full``). An image with preallocated metadata is initially larger but can
162
+
improve performance when the image needs to grow. ``falloc`` and ``full``
163
+
preallocations are like the same options of ``raw`` format, but sets up
164
+
metadata also.
165
+
166
+
.. option:: lazy_refcounts
167
+
168
+
If this option is set to ``on``, reference count updates are postponed with
169
+
the goal of avoiding metadata I/O and improving performance. This is
170
+
particularly interesting with :option:`cache=writethrough` which doesn't batch
171
+
metadata updates. The tradeoff is that after a host crash, the reference count
172
+
tables must be rebuilt, i.e. on the next open an (automatic) ``qemu-img
173
+
check -r all`` is required, which may take some time.
174
+
175
+
This option can only be enabled if ``compat=1.1`` is specified.
176
+
177
+
.. option:: nocow
178
+
179
+
If this option is set to ``on``, it will turn off COW of the file. It's only
180
+
valid on btrfs, no effect on other file systems.
181
+
182
+
Btrfs has low performance when hosting a VM image file, even more
183
+
when the guest on the VM also using btrfs as file system. Turning off
184
+
COW is a way to mitigate this bad performance. Generally there are two
185
+
ways to turn off COW on btrfs:
186
+
187
+
- Disable it by mounting with nodatacow, then all newly created files
188
+
will be NOCOW.
189
+
- For an empty file, add the NOCOW file attribute. That's what this
190
+
option does.
191
+
192
+
Note: this option is only valid to new or empty files. If there is
193
+
an existing file which is COW and has data blocks already, it couldn't
194
+
be changed to NOCOW by setting ``nocow=on``. One can issue ``lsattr
195
+
filename`` to check if the NOCOW flag is set or not (Capital 'C' is
196
+
NOCOW flag).
197
+
198
+
.. program:: image-formats
199
+
.. option:: qed
200
+
201
+
Old QEMU image format with support for backing files and compact image files
202
+
(when your filesystem or transport medium does not support holes).
203
+
204
+
When converting QED images to qcow2, you might want to consider using the
205
+
``lazy_refcounts=on`` option to get a more QED-like behaviour.
206
+
207
+
Supported options:
208
+
209
+
.. program:: qed
210
+
.. option:: backing_file
211
+
212
+
File name of a base image (see ``create`` subcommand).
213
+
214
+
.. option:: backing_fmt
215
+
216
+
Image file format of backing file (optional). Useful if the format cannot be
217
+
autodetected because it has no header, like some vhd/vpc files.
218
+
219
+
.. option:: cluster_size
220
+
221
+
Changes the cluster size (must be power-of-2 between 4K and 64K). Smaller
222
+
cluster sizes can improve the image file size whereas larger cluster sizes
223
+
generally provide better performance.
224
+
225
+
.. option:: table_size
226
+
227
+
Changes the number of clusters per L1/L2 table (must be
228
+
power-of-2 between 1 and 16). There is normally no need to
229
+
change this value but this option can between used for
230
+
performance benchmarking.
231
+
232
+
.. program:: image-formats
233
+
.. option:: qcow
234
+
235
+
Old QEMU image format with support for backing files, compact image files,
236
+
encryption and compression.
237
+
238
+
Supported options:
239
+
240
+
.. program:: qcow
241
+
.. option:: backing_file
242
+
243
+
File name of a base image (see ``create`` subcommand)
244
+
245
+
.. option:: encryption
246
+
247
+
This option is deprecated and equivalent to ``encrypt.format=aes``
248
+
249
+
.. option:: encrypt.format
250
+
251
+
If this is set to ``aes``, the image is encrypted with 128-bit AES-CBC.
252
+
The encryption key is given by the ``encrypt.key-secret`` parameter.
253
+
This encryption format is considered to be flawed by modern cryptography
254
+
standards, suffering from a number of design problems enumerated previously
255
+
against the ``qcow2`` image format.
256
+
257
+
The use of this is no longer supported in system emulators. Support only
258
+
remains in the command line utilities, for the purposes of data liberation
259
+
and interoperability with old versions of QEMU.
260
+
261
+
Users requiring native encryption should use the ``qcow2`` format
262
+
instead with ``encrypt.format=luks``.
263
+
264
+
.. option:: encrypt.key-secret
265
+
266
+
Provides the ID of a ``secret`` object that contains the encryption
267
+
key (``encrypt.format=aes``).
268
+
269
+
.. program:: image-formats
270
+
.. option:: luks
271
+
272
+
LUKS v1 encryption format, compatible with Linux dm-crypt/cryptsetup
273
+
274
+
Supported options:
275
+
276
+
.. program:: luks
277
+
.. option:: key-secret
278
+
279
+
Provides the ID of a ``secret`` object that contains the passphrase.
280
+
281
+
.. option:: cipher-alg
282
+
283
+
Name of the cipher algorithm and key length. Currently defaults
284
+
to ``aes-256``.
285
+
286
+
.. option:: cipher-mode
287
+
288
+
Name of the encryption mode to use. Currently defaults to ``xts``.
289
+
290
+
.. option:: ivgen-alg
291
+
292
+
Name of the initialization vector generator algorithm. Currently defaults
293
+
to ``plain64``.
294
+
295
+
.. option:: ivgen-hash-alg
296
+
297
+
Name of the hash algorithm to use with the initialization vector generator
298
+
(if required). Defaults to ``sha256``.
299
+
300
+
.. option:: hash-alg
301
+
302
+
Name of the hash algorithm to use for PBKDF algorithm
303
+
Defaults to ``sha256``.
304
+
305
+
.. option:: iter-time
306
+
307
+
Amount of time, in milliseconds, to use for PBKDF algorithm per key slot.
308
+
Defaults to ``2000``.
309
+
310
+
.. program:: image-formats
311
+
.. option:: vdi
312
+
313
+
VirtualBox 1.1 compatible image format.
314
+
315
+
Supported options:
316
+
317
+
.. program:: vdi
318
+
.. option:: static
319
+
320
+
If this option is set to ``on``, the image is created with metadata
321
+
preallocation.
322
+
323
+
.. program:: image-formats
324
+
.. option:: vmdk
325
+
326
+
VMware 3 and 4 compatible image format.
327
+
328
+
Supported options:
329
+
330
+
.. program: vmdk
331
+
.. option:: backing_file
332
+
333
+
File name of a base image (see ``create`` subcommand).
334
+
335
+
.. option:: compat6
336
+
337
+
Create a VMDK version 6 image (instead of version 4)
338
+
339
+
.. option:: hwversion
340
+
341
+
Specify vmdk virtual hardware version. Compat6 flag cannot be enabled
342
+
if hwversion is specified.
343
+
344
+
.. option:: subformat
345
+
346
+
Specifies which VMDK subformat to use. Valid options are
347
+
``monolithicSparse`` (default),
348
+
``monolithicFlat``,
349
+
``twoGbMaxExtentSparse``,
350
+
``twoGbMaxExtentFlat`` and
351
+
``streamOptimized``.
352
+
353
+
.. program:: image-formats
354
+
.. option:: vpc
355
+
356
+
VirtualPC compatible image format (VHD).
357
+
358
+
Supported options:
359
+
360
+
.. program:: vpc
361
+
.. option:: subformat
362
+
363
+
Specifies which VHD subformat to use. Valid options are
364
+
``dynamic`` (default) and ``fixed``.
365
+
366
+
.. program:: image-formats
367
+
.. option:: VHDX
368
+
369
+
Hyper-V compatible image format (VHDX).
370
+
371
+
Supported options:
372
+
373
+
.. program:: VHDX
374
+
.. option:: subformat
375
+
376
+
Specifies which VHDX subformat to use. Valid options are
377
+
``dynamic`` (default) and ``fixed``.
378
+
379
+
.. option:: block_state_zero
380
+
381
+
Force use of payload blocks of type 'ZERO'. Can be set to ``on`` (default)
382
+
or ``off``. When set to ``off``, new blocks will be created as
383
+
``PAYLOAD_BLOCK_NOT_PRESENT``, which means parsers are free to return
384
+
arbitrary data for those blocks. Do not set to ``off`` when using
385
+
``qemu-img convert`` with ``subformat=dynamic``.
386
+
387
+
.. option:: block_size
388
+
389
+
Block size; min 1 MB, max 256 MB. 0 means auto-calculate based on
390
+
image size.
391
+
392
+
.. option:: log_size
393
+
394
+
Log size; min 1 MB.
395
+
396
+
Read-only formats
397
+
-----------------
398
+
399
+
More disk image file formats are supported in a read-only mode.
400
+
401
+
.. program:: image-formats
402
+
.. option:: bochs
403
+
404
+
Bochs images of ``growing`` type.
405
+
406
+
.. program:: image-formats
407
+
.. option:: cloop
408
+
409
+
Linux Compressed Loop image, useful only to reuse directly compressed
410
+
CD-ROM images present for example in the Knoppix CD-ROMs.
411
+
412
+
.. program:: image-formats
413
+
.. option:: dmg
414
+
415
+
Apple disk image.
416
+
417
+
.. program:: image-formats
418
+
.. option:: parallels
419
+
420
+
Parallels disk image format.
421
+
422
+
Using host drives
423
+
-----------------
424
+
425
+
In addition to disk image files, QEMU can directly access host
426
+
devices. We describe here the usage for QEMU version >= 0.8.3.
427
+
428
+
Linux
429
+
'''''
430
+
431
+
On Linux, you can directly use the host device filename instead of a
432
+
disk image filename provided you have enough privileges to access
433
+
it. For example, use ``/dev/cdrom`` to access to the CDROM.
434
+
435
+
CD
436
+
You can specify a CDROM device even if no CDROM is loaded. QEMU has
437
+
specific code to detect CDROM insertion or removal. CDROM ejection by
438
+
the guest OS is supported. Currently only data CDs are supported.
439
+
440
+
Floppy
441
+
You can specify a floppy device even if no floppy is loaded. Floppy
442
+
removal is currently not detected accurately (if you change floppy
443
+
without doing floppy access while the floppy is not loaded, the guest
444
+
OS will think that the same floppy is loaded).
445
+
Use of the host's floppy device is deprecated, and support for it will
446
+
be removed in a future release.
447
+
448
+
Hard disks
449
+
Hard disks can be used. Normally you must specify the whole disk
450
+
(``/dev/hdb`` instead of ``/dev/hdb1``) so that the guest OS can
451
+
see it as a partitioned disk. WARNING: unless you know what you do, it
452
+
is better to only make READ-ONLY accesses to the hard disk otherwise
453
+
you may corrupt your host data (use the ``-snapshot`` command
454
+
line option or modify the device permissions accordingly).
455
+
456
+
Windows
457
+
'''''''
458
+
459
+
CD
460
+
The preferred syntax is the drive letter (e.g. ``d:``). The
461
+
alternate syntax ``\\.\d:`` is supported. ``/dev/cdrom`` is
462
+
supported as an alias to the first CDROM drive.
463
+
464
+
Currently there is no specific code to handle removable media, so it
465
+
is better to use the ``change`` or ``eject`` monitor commands to
466
+
change or eject media.
467
+
468
+
Hard disks
469
+
Hard disks can be used with the syntax: ``\\.\PhysicalDriveN``
470
+
where *N* is the drive number (0 is the first hard disk).
471
+
472
+
WARNING: unless you know what you do, it is better to only make
473
+
READ-ONLY accesses to the hard disk otherwise you may corrupt your
474
+
host data (use the ``-snapshot`` command line so that the
475
+
modifications are written in a temporary file).
476
+
477
+
Mac OS X
478
+
''''''''
479
+
480
+
``/dev/cdrom`` is an alias to the first CDROM.
481
+
482
+
Currently there is no specific code to handle removable media, so it
483
+
is better to use the ``change`` or ``eject`` monitor commands to
484
+
change or eject media.
485
+
486
+
Virtual FAT disk images
487
+
-----------------------
488
+
489
+
QEMU can automatically create a virtual FAT disk image from a
490
+
directory tree. In order to use it, just type:
491
+
492
+
.. parsed-literal::
493
+
494
+
|qemu_system| linux.img -hdb fat:/my_directory
495
+
496
+
Then you access access to all the files in the ``/my_directory``
497
+
directory without having to copy them in a disk image or to export
498
+
them via SAMBA or NFS. The default access is *read-only*.
499
+
500
+
Floppies can be emulated with the ``:floppy:`` option:
501
+
502
+
.. parsed-literal::
503
+
504
+
|qemu_system| linux.img -fda fat:floppy:/my_directory
505
+
506
+
A read/write support is available for testing (beta stage) with the
507
+
``:rw:`` option:
508
+
509
+
.. parsed-literal::
510
+
511
+
|qemu_system| linux.img -fda fat:floppy:rw:/my_directory
512
+
513
+
What you should *never* do:
514
+
515
+
- use non-ASCII filenames
516
+
- use "-snapshot" together with ":rw:"
517
+
- expect it to work when loadvm'ing
518
+
- write to the FAT directory on the host system while accessing it with the guest system
519
+
520
+
NBD access
521
+
----------
522
+
523
+
QEMU can access directly to block device exported using the Network Block Device
524
+
protocol.
525
+
526
+
.. parsed-literal::
527
+
528
+
|qemu_system| linux.img -hdb nbd://my_nbd_server.mydomain.org:1024/
529
+
530
+
If the NBD server is located on the same host, you can use an unix socket instead
531
+
of an inet socket:
532
+
533
+
.. parsed-literal::
534
+
535
+
|qemu_system| linux.img -hdb nbd+unix://?socket=/tmp/my_socket
536
+
537
+
In this case, the block device must be exported using qemu-nbd:
538
+
539
+
.. parsed-literal::
540
+
541
+
qemu-nbd --socket=/tmp/my_socket my_disk.qcow2
542
+
543
+
The use of qemu-nbd allows sharing of a disk between several guests:
544
+
545
+
.. parsed-literal::
546
+
547
+
qemu-nbd --socket=/tmp/my_socket --share=2 my_disk.qcow2
548
+
549
+
and then you can use it with two guests:
550
+
551
+
.. parsed-literal::
552
+
553
+
|qemu_system| linux1.img -hdb nbd+unix://?socket=/tmp/my_socket
554
+
|qemu_system| linux2.img -hdb nbd+unix://?socket=/tmp/my_socket
555
+
556
+
If the nbd-server uses named exports (supported since NBD 2.9.18, or with QEMU's
557
+
own embedded NBD server), you must specify an export name in the URI:
558
+
559
+
.. parsed-literal::
560
+
561
+
|qemu_system| -cdrom nbd://localhost/debian-500-ppc-netinst
562
+
|qemu_system| -cdrom nbd://localhost/openSUSE-11.1-ppc-netinst
563
+
564
+
The URI syntax for NBD is supported since QEMU 1.3. An alternative syntax is
565
+
also available. Here are some example of the older syntax:
566
+
567
+
.. parsed-literal::
568
+
569
+
|qemu_system| linux.img -hdb nbd:my_nbd_server.mydomain.org:1024
570
+
|qemu_system| linux2.img -hdb nbd:unix:/tmp/my_socket
571
+
|qemu_system| -cdrom nbd:localhost:10809:exportname=debian-500-ppc-netinst
572
+
573
+
574
+
575
+
Sheepdog disk images
576
+
--------------------
577
+
578
+
Sheepdog is a distributed storage system for QEMU. It provides highly
579
+
available block level storage volumes that can be attached to
580
+
QEMU-based virtual machines.
581
+
582
+
You can create a Sheepdog disk image with the command:
583
+
584
+
.. parsed-literal::
585
+
586
+
qemu-img create sheepdog:///IMAGE SIZE
587
+
588
+
where *IMAGE* is the Sheepdog image name and *SIZE* is its
589
+
size.
590
+
591
+
To import the existing *FILENAME* to Sheepdog, you can use a
592
+
convert command.
593
+
594
+
.. parsed-literal::
595
+
596
+
qemu-img convert FILENAME sheepdog:///IMAGE
597
+
598
+
You can boot from the Sheepdog disk image with the command:
599
+
600
+
.. parsed-literal::
601
+
602
+
|qemu_system| sheepdog:///IMAGE
603
+
604
+
You can also create a snapshot of the Sheepdog image like qcow2.
605
+
606
+
.. parsed-literal::
607
+
608
+
qemu-img snapshot -c TAG sheepdog:///IMAGE
609
+
610
+
where *TAG* is a tag name of the newly created snapshot.
611
+
612
+
To boot from the Sheepdog snapshot, specify the tag name of the
613
+
snapshot.
614
+
615
+
.. parsed-literal::
616
+
617
+
|qemu_system| sheepdog:///IMAGE#TAG
618
+
619
+
You can create a cloned image from the existing snapshot.
620
+
621
+
.. parsed-literal::
622
+
623
+
qemu-img create -b sheepdog:///BASE#TAG sheepdog:///IMAGE
624
+
625
+
where *BASE* is an image name of the source snapshot and *TAG*
626
+
is its tag name.
627
+
628
+
You can use an unix socket instead of an inet socket:
629
+
630
+
.. parsed-literal::
631
+
632
+
|qemu_system| sheepdog+unix:///IMAGE?socket=PATH
633
+
634
+
If the Sheepdog daemon doesn't run on the local host, you need to
635
+
specify one of the Sheepdog servers to connect to.
636
+
637
+
.. parsed-literal::
638
+
639
+
qemu-img create sheepdog://HOSTNAME:PORT/IMAGE SIZE
640
+
|qemu_system| sheepdog://HOSTNAME:PORT/IMAGE
641
+
642
+
iSCSI LUNs
643
+
----------
644
+
645
+
iSCSI is a popular protocol used to access SCSI devices across a computer
646
+
network.
647
+
648
+
There are two different ways iSCSI devices can be used by QEMU.
649
+
650
+
The first method is to mount the iSCSI LUN on the host, and make it appear as
651
+
any other ordinary SCSI device on the host and then to access this device as a
652
+
/dev/sd device from QEMU. How to do this differs between host OSes.
653
+
654
+
The second method involves using the iSCSI initiator that is built into
655
+
QEMU. This provides a mechanism that works the same way regardless of which
656
+
host OS you are running QEMU on. This section will describe this second method
657
+
of using iSCSI together with QEMU.
658
+
659
+
In QEMU, iSCSI devices are described using special iSCSI URLs. URL syntax:
660
+
661
+
::
662
+
663
+
iscsi://[<username>[%<password>]@]<host>[:<port>]/<target-iqn-name>/<lun>
664
+
665
+
Username and password are optional and only used if your target is set up
666
+
using CHAP authentication for access control.
667
+
Alternatively the username and password can also be set via environment
668
+
variables to have these not show up in the process list:
669
+
670
+
::
671
+
672
+
export LIBISCSI_CHAP_USERNAME=<username>
673
+
export LIBISCSI_CHAP_PASSWORD=<password>
674
+
iscsi://<host>/<target-iqn-name>/<lun>
675
+
676
+
Various session related parameters can be set via special options, either
677
+
in a configuration file provided via '-readconfig' or directly on the
678
+
command line.
679
+
680
+
If the initiator-name is not specified qemu will use a default name
681
+
of 'iqn.2008-11.org.linux-kvm[:<uuid>'] where <uuid> is the UUID of the
682
+
virtual machine. If the UUID is not specified qemu will use
683
+
'iqn.2008-11.org.linux-kvm[:<name>'] where <name> is the name of the
684
+
virtual machine.
685
+
686
+
Setting a specific initiator name to use when logging in to the target:
687
+
688
+
::
689
+
690
+
-iscsi initiator-name=iqn.qemu.test:my-initiator
691
+
692
+
Controlling which type of header digest to negotiate with the target:
693
+
694
+
::
695
+
696
+
-iscsi header-digest=CRC32C|CRC32C-NONE|NONE-CRC32C|NONE
697
+
698
+
These can also be set via a configuration file:
699
+
700
+
::
701
+
702
+
[iscsi]
703
+
user = "CHAP username"
704
+
password = "CHAP password"
705
+
initiator-name = "iqn.qemu.test:my-initiator"
706
+
# header digest is one of CRC32C|CRC32C-NONE|NONE-CRC32C|NONE
707
+
header-digest = "CRC32C"
708
+
709
+
Setting the target name allows different options for different targets:
710
+
711
+
::
712
+
713
+
[iscsi "iqn.target.name"]
714
+
user = "CHAP username"
715
+
password = "CHAP password"
716
+
initiator-name = "iqn.qemu.test:my-initiator"
717
+
# header digest is one of CRC32C|CRC32C-NONE|NONE-CRC32C|NONE
718
+
header-digest = "CRC32C"
719
+
720
+
How to use a configuration file to set iSCSI configuration options:
721
+
722
+
.. parsed-literal::
723
+
724
+
cat >iscsi.conf <<EOF
725
+
[iscsi]
726
+
user = "me"
727
+
password = "my password"
728
+
initiator-name = "iqn.qemu.test:my-initiator"
729
+
header-digest = "CRC32C"
730
+
EOF
731
+
732
+
|qemu_system| -drive file=iscsi://127.0.0.1/iqn.qemu.test/1 \\
733
+
-readconfig iscsi.conf
734
+
735
+
How to set up a simple iSCSI target on loopback and access it via QEMU:
736
+
this example shows how to set up an iSCSI target with one CDROM and one DISK
737
+
using the Linux STGT software target. This target is available on Red Hat based
738
+
systems as the package 'scsi-target-utils'.
739
+
740
+
.. parsed-literal::
741
+
742
+
tgtd --iscsi portal=127.0.0.1:3260
743
+
tgtadm --lld iscsi --op new --mode target --tid 1 -T iqn.qemu.test
744
+
tgtadm --lld iscsi --mode logicalunit --op new --tid 1 --lun 1 \\
745
+
-b /IMAGES/disk.img --device-type=disk
746
+
tgtadm --lld iscsi --mode logicalunit --op new --tid 1 --lun 2 \\
747
+
-b /IMAGES/cd.iso --device-type=cd
748
+
tgtadm --lld iscsi --op bind --mode target --tid 1 -I ALL
749
+
750
+
|qemu_system| -iscsi initiator-name=iqn.qemu.test:my-initiator \\
751
+
-boot d -drive file=iscsi://127.0.0.1/iqn.qemu.test/1 \\
752
+
-cdrom iscsi://127.0.0.1/iqn.qemu.test/2
753
+
754
+
GlusterFS disk images
755
+
---------------------
756
+
757
+
GlusterFS is a user space distributed file system.
758
+
759
+
You can boot from the GlusterFS disk image with the command:
760
+
761
+
URI:
762
+
763
+
.. parsed-literal::
764
+
765
+
|qemu_system| -drive file=gluster[+TYPE]://[HOST}[:PORT]]/VOLUME/PATH
766
+
[?socket=...][,file.debug=9][,file.logfile=...]
767
+
768
+
JSON:
769
+
770
+
.. parsed-literal::
771
+
772
+
|qemu_system| 'json:{"driver":"qcow2",
773
+
"file":{"driver":"gluster",
774
+
"volume":"testvol","path":"a.img","debug":9,"logfile":"...",
775
+
"server":[{"type":"tcp","host":"...","port":"..."},
776
+
{"type":"unix","socket":"..."}]}}'
777
+
778
+
*gluster* is the protocol.
779
+
780
+
*TYPE* specifies the transport type used to connect to gluster
781
+
management daemon (glusterd). Valid transport types are
782
+
tcp and unix. In the URI form, if a transport type isn't specified,
783
+
then tcp type is assumed.
784
+
785
+
*HOST* specifies the server where the volume file specification for
786
+
the given volume resides. This can be either a hostname or an ipv4 address.
787
+
If transport type is unix, then *HOST* field should not be specified.
788
+
Instead *socket* field needs to be populated with the path to unix domain
789
+
socket.
790
+
791
+
*PORT* is the port number on which glusterd is listening. This is optional
792
+
and if not specified, it defaults to port 24007. If the transport type is unix,
793
+
then *PORT* should not be specified.
794
+
795
+
*VOLUME* is the name of the gluster volume which contains the disk image.
796
+
797
+
*PATH* is the path to the actual disk image that resides on gluster volume.
798
+
799
+
*debug* is the logging level of the gluster protocol driver. Debug levels
800
+
are 0-9, with 9 being the most verbose, and 0 representing no debugging output.
801
+
The default level is 4. The current logging levels defined in the gluster source
802
+
are 0 - None, 1 - Emergency, 2 - Alert, 3 - Critical, 4 - Error, 5 - Warning,
803
+
6 - Notice, 7 - Info, 8 - Debug, 9 - Trace
804
+
805
+
*logfile* is a commandline option to mention log file path which helps in
806
+
logging to the specified file and also help in persisting the gfapi logs. The
807
+
default is stderr.
808
+
809
+
You can create a GlusterFS disk image with the command:
810
+
811
+
.. parsed-literal::
812
+
813
+
qemu-img create gluster://HOST/VOLUME/PATH SIZE
814
+
815
+
Examples
816
+
817
+
.. parsed-literal::
818
+
819
+
|qemu_system| -drive file=gluster://1.2.3.4/testvol/a.img
820
+
|qemu_system| -drive file=gluster+tcp://1.2.3.4/testvol/a.img
821
+
|qemu_system| -drive file=gluster+tcp://1.2.3.4:24007/testvol/dir/a.img
822
+
|qemu_system| -drive file=gluster+tcp://[1:2:3:4:5:6:7:8]/testvol/dir/a.img
823
+
|qemu_system| -drive file=gluster+tcp://[1:2:3:4:5:6:7:8]:24007/testvol/dir/a.img
824
+
|qemu_system| -drive file=gluster+tcp://server.domain.com:24007/testvol/dir/a.img
825
+
|qemu_system| -drive file=gluster+unix:///testvol/dir/a.img?socket=/tmp/glusterd.socket
826
+
|qemu_system| -drive file=gluster+rdma://1.2.3.4:24007/testvol/a.img
827
+
|qemu_system| -drive file=gluster://1.2.3.4/testvol/a.img,file.debug=9,file.logfile=/var/log/qemu-gluster.log
828
+
|qemu_system| 'json:{"driver":"qcow2",
829
+
"file":{"driver":"gluster",
830
+
"volume":"testvol","path":"a.img",
831
+
"debug":9,"logfile":"/var/log/qemu-gluster.log",
832
+
"server":[{"type":"tcp","host":"1.2.3.4","port":24007},
833
+
{"type":"unix","socket":"/var/run/glusterd.socket"}]}}'
834
+
|qemu_system| -drive driver=qcow2,file.driver=gluster,file.volume=testvol,file.path=/path/a.img,
835
+
file.debug=9,file.logfile=/var/log/qemu-gluster.log,
836
+
file.server.0.type=tcp,file.server.0.host=1.2.3.4,file.server.0.port=24007,
837
+
file.server.1.type=unix,file.server.1.socket=/var/run/glusterd.socket
838
+
839
+
Secure Shell (ssh) disk images
840
+
------------------------------
841
+
842
+
You can access disk images located on a remote ssh server
843
+
by using the ssh protocol:
844
+
845
+
.. parsed-literal::
846
+
847
+
|qemu_system| -drive file=ssh://[USER@]SERVER[:PORT]/PATH[?host_key_check=HOST_KEY_CHECK]
848
+
849
+
Alternative syntax using properties:
850
+
851
+
.. parsed-literal::
852
+
853
+
|qemu_system| -drive file.driver=ssh[,file.user=USER],file.host=SERVER[,file.port=PORT],file.path=PATH[,file.host_key_check=HOST_KEY_CHECK]
854
+
855
+
*ssh* is the protocol.
856
+
857
+
*USER* is the remote user. If not specified, then the local
858
+
username is tried.
859
+
860
+
*SERVER* specifies the remote ssh server. Any ssh server can be
861
+
used, but it must implement the sftp-server protocol. Most Unix/Linux
862
+
systems should work without requiring any extra configuration.
863
+
864
+
*PORT* is the port number on which sshd is listening. By default
865
+
the standard ssh port (22) is used.
866
+
867
+
*PATH* is the path to the disk image.
868
+
869
+
The optional *HOST_KEY_CHECK* parameter controls how the remote
870
+
host's key is checked. The default is ``yes`` which means to use
871
+
the local ``.ssh/known_hosts`` file. Setting this to ``no``
872
+
turns off known-hosts checking. Or you can check that the host key
873
+
matches a specific fingerprint:
874
+
``host_key_check=md5:78:45:8e:14:57:4f:d5:45:83:0a:0e:f3:49:82:c9:c8``
875
+
(``sha1:`` can also be used as a prefix, but note that OpenSSH
876
+
tools only use MD5 to print fingerprints).
877
+
878
+
Currently authentication must be done using ssh-agent. Other
879
+
authentication methods may be supported in future.
880
+
881
+
Note: Many ssh servers do not support an ``fsync``-style operation.
882
+
The ssh driver cannot guarantee that disk flush requests are
883
+
obeyed, and this causes a risk of disk corruption if the remote
884
+
server or network goes down during writes. The driver will
885
+
print a warning when ``fsync`` is not supported:
886
+
887
+
::
888
+
889
+
warning: ssh server ssh.example.com:22 does not support fsync
890
+
891
+
With sufficiently new versions of libssh and OpenSSH, ``fsync`` is
892
+
supported.
893
+
894
+
NVMe disk images
895
+
----------------
896
+
897
+
NVM Express (NVMe) storage controllers can be accessed directly by a userspace
898
+
driver in QEMU. This bypasses the host kernel file system and block layers
899
+
while retaining QEMU block layer functionalities, such as block jobs, I/O
900
+
throttling, image formats, etc. Disk I/O performance is typically higher than
901
+
with ``-drive file=/dev/sda`` using either thread pool or linux-aio.
902
+
903
+
The controller will be exclusively used by the QEMU process once started. To be
904
+
able to share storage between multiple VMs and other applications on the host,
905
+
please use the file based protocols.
906
+
907
+
Before starting QEMU, bind the host NVMe controller to the host vfio-pci
908
+
driver. For example:
909
+
910
+
.. parsed-literal::
911
+
912
+
# modprobe vfio-pci
913
+
# lspci -n -s 0000:06:0d.0
914
+
06:0d.0 0401: 1102:0002 (rev 08)
915
+
# echo 0000:06:0d.0 > /sys/bus/pci/devices/0000:06:0d.0/driver/unbind
916
+
# echo 1102 0002 > /sys/bus/pci/drivers/vfio-pci/new_id
917
+
918
+
# |qemu_system| -drive file=nvme://HOST:BUS:SLOT.FUNC/NAMESPACE
919
+
920
+
Alternative syntax using properties:
921
+
922
+
.. parsed-literal::
923
+
924
+
|qemu_system| -drive file.driver=nvme,file.device=HOST:BUS:SLOT.FUNC,file.namespace=NAMESPACE
925
+
926
+
*HOST*:*BUS*:*SLOT*.\ *FUNC* is the NVMe controller's PCI device
927
+
address on the host.
928
+
929
+
*NAMESPACE* is the NVMe namespace number, starting from 1.
930
+
931
+
Disk image file locking
932
+
-----------------------
933
+
934
+
By default, QEMU tries to protect image files from unexpected concurrent
935
+
access, as long as it's supported by the block protocol driver and host
936
+
operating system. If multiple QEMU processes (including QEMU emulators and
937
+
utilities) try to open the same image with conflicting accessing modes, all but
938
+
the first one will get an error.
939
+
940
+
This feature is currently supported by the file protocol on Linux with the Open
941
+
File Descriptor (OFD) locking API, and can be configured to fall back to POSIX
942
+
locking if the POSIX host doesn't support Linux OFD locking.
943
+
944
+
To explicitly enable image locking, specify "locking=on" in the file protocol
945
+
driver options. If OFD locking is not possible, a warning will be printed and
946
+
the POSIX locking API will be used. In this case there is a risk that the lock
947
+
will get silently lost when doing hot plugging and block jobs, due to the
948
+
shortcomings of the POSIX locking API.
949
+
950
+
QEMU transparently handles lock handover during shared storage migration. For
951
+
shared virtual disk images between multiple VMs, the "share-rw" device option
952
+
should be used.
953
+
954
+
By default, the guest has exclusive write access to its disk image. If the
955
+
guest can safely share the disk image with other writers the
956
+
``-device ...,share-rw=on`` parameter can be used. This is only safe if
957
+
the guest is running software, such as a cluster file system, that
958
+
coordinates disk accesses to avoid corruption.
959
+
960
+
Note that share-rw=on only declares the guest's ability to share the disk.
961
+
Some QEMU features, such as image file formats, require exclusive write access
962
+
to the disk image and this is unaffected by the share-rw=on option.
963
+
964
+
Alternatively, locking can be fully disabled by "locking=off" block device
965
+
option. In the command line, the option is usually in the form of
966
+
"file.locking=off" as the protocol driver is normally placed as a "file" child
967
+
under a format driver. For example:
968
+
969
+
::
970
+
971
+
-blockdev driver=qcow2,file.filename=/path/to/image,file.locking=off,file.driver=file
972
+
973
+
To check if image locking is active, check the output of the "lslocks" command
974
+
on host and see if there are locks held by the QEMU process on the image file.
975
+
More than one byte could be locked by the QEMU instance, each byte of which
976
+
reflects a particular permission that is acquired or protected by the running
977
+
block driver.
978
+
979
+
.. only:: man
980
+
981
+
See also
982
+
--------
983
+
984
+
The HTML documentation of QEMU for more precise information and Linux
985
+
user mode emulator invocation.
-12
qemu-doc.texi
-12
qemu-doc.texi
···
633
633
* disk_images_snapshot_mode:: Snapshot mode
634
634
* vm_snapshots:: VM snapshots
635
635
* qemu_img_invocation:: qemu-img Invocation
636
-
* disk_images_formats:: Disk image file formats
637
-
* host_drives:: Using host drives
638
-
* disk_images_fat_images:: Virtual FAT disk images
639
-
* disk_images_nbd:: NBD access
640
-
* disk_images_sheepdog:: Sheepdog disk images
641
-
* disk_images_iscsi:: iSCSI LUNs
642
-
* disk_images_gluster:: GlusterFS disk images
643
-
* disk_images_ssh:: Secure Shell (ssh) disk images
644
-
* disk_images_nvme:: NVMe userspace driver
645
-
* disk_image_locking:: Disk image file locking
646
636
@end menu
647
637
648
638
@node disk_images_quickstart
···
722
712
@subsection @code{qemu-img} Invocation
723
713
724
714
@include qemu-img.texi
725
-
726
-
@include docs/qemu-block-drivers.texi
727
715
728
716
@node pcsys_network
729
717
@section Network emulation
+1
-1
qemu-options.hx
+1
-1
qemu-options.hx
···
953
953
@findex -cdrom
954
954
Use @var{file} as CD-ROM image (you cannot use @option{-hdc} and
955
955
@option{-cdrom} at the same time). You can use the host CD-ROM by
956
-
using @file{/dev/cdrom} as filename (@pxref{host_drives}).
956
+
using @file{/dev/cdrom} as filename.
957
957
ETEXI
958
958
959
959
DEF("blockdev", HAS_ARG, QEMU_OPTION_blockdev,