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