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