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