2 QEMU block driver reference manual
5 @c man begin DESCRIPTION
7 @node disk_images_formats
8 @subsection Disk image file formats
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.
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.
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.
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
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
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.
54 File name of a base image (see @option{create} subcommand)
56 Image format of the base image
58 This option is deprecated and equivalent to @code{encrypt.format=aes}
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.
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:
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.
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.
91 @item encrypt.key-secret
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}).
96 @item encrypt.cipher-alg
98 Name of the cipher algorithm and key length. Currently defaults
99 to @code{aes-256}. Only used when @code{encrypt.format=luks}.
101 @item encrypt.cipher-mode
103 Name of the encryption mode to use. Currently defaults to @code{xts}.
104 Only used when @code{encrypt.format=luks}.
106 @item encrypt.ivgen-alg
108 Name of the initialization vector generator algorithm. Currently defaults
109 to @code{plain64}. Only used when @code{encrypt.format=luks}.
111 @item encrypt.ivgen-hash-alg
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}.
116 @item encrypt.hash-alg
118 Name of the hash algorithm to use for PBKDF algorithm
119 Defaults to @code{sha256}. Only used when @code{encrypt.format=luks}.
121 @item encrypt.iter-time
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}.
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.
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
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.
146 This option can only be enabled if @code{compat=1.1} is specified.
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.
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
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).
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).
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.
176 File name of a base image (see @option{create} subcommand).
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.
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.
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.
191 Old QEMU image format with support for backing files, compact image files,
192 encryption and compression.
197 File name of a base image (see @option{create} subcommand)
199 This option is deprecated and equivalent to @code{encrypt.format=aes}
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.
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.
212 Users requiring native encryption should use the @code{qcow2} format
213 instead with @code{encrypt.format=luks}.
215 @item encrypt.key-secret
217 Provides the ID of a @code{secret} object that contains the encryption
218 key (@code{encrypt.format=aes}).
224 LUKS v1 encryption format, compatible with Linux dm-crypt/cryptsetup
231 Provides the ID of a @code{secret} object that contains the passphrase.
235 Name of the cipher algorithm and key length. Currently defaults
240 Name of the encryption mode to use. Currently defaults to @code{xts}.
244 Name of the initialization vector generator algorithm. Currently defaults
249 Name of the hash algorithm to use with the initialization vector generator
250 (if required). Defaults to @code{sha256}.
254 Name of the hash algorithm to use for PBKDF algorithm
255 Defaults to @code{sha256}.
259 Amount of time, in milliseconds, to use for PBKDF algorithm per key slot.
260 Defaults to @code{2000}.
265 VirtualBox 1.1 compatible image format.
269 If this option is set to @code{on}, the image is created with metadata
274 VMware 3 and 4 compatible image format.
279 File name of a base image (see @option{create} subcommand).
281 Create a VMDK version 6 image (instead of version 4)
283 Specify vmdk virtual hardware version. Compat6 flag cannot be enabled
284 if hwversion is specified.
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}.
295 VirtualPC compatible image format (VHD).
299 Specifies which VHD subformat to use. Valid options are
300 @code{dynamic} (default) and @code{fixed}.
304 Hyper-V compatible image format (VHDX).
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}.
317 Block size; min 1 MB, max 256 MB. 0 means auto-calculate based on image size.
323 @subsubsection Read-only formats
324 More disk image file formats are supported in a read-only mode.
327 Bochs images of @code{growing} type.
329 Linux Compressed Loop image, useful only to reuse directly compressed
330 CD-ROM images present for example in the Knoppix CD-ROMs.
334 Parallels disk image format.
339 @subsection Using host drives
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.
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.
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.
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.
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).
371 @subsubsection Windows
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.
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.
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).
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).
393 @subsubsection Mac OS X
395 @file{/dev/cdrom} is an alias to the first CDROM.
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.
401 @node disk_images_fat_images
402 @subsection Virtual FAT disk images
404 QEMU can automatically create a virtual FAT disk image from a
405 directory tree. In order to use it, just type:
408 qemu-system-i386 linux.img -hdb fat:/my_directory
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}.
415 Floppies can be emulated with the @code{:floppy:} option:
418 qemu-system-i386 linux.img -fda fat:floppy:/my_directory
421 A read/write support is available for testing (beta stage) with the
425 qemu-system-i386 linux.img -fda fat:floppy:rw:/my_directory
428 What you should @emph{never} do:
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.
436 @node disk_images_nbd
437 @subsection NBD access
439 QEMU can access directly to block device exported using the Network Block Device
443 qemu-system-i386 linux.img -hdb nbd://my_nbd_server.mydomain.org:1024/
446 If the NBD server is located on the same host, you can use an unix socket instead
450 qemu-system-i386 linux.img -hdb nbd+unix://?socket=/tmp/my_socket
453 In this case, the block device must be exported using qemu-nbd:
456 qemu-nbd --socket=/tmp/my_socket my_disk.qcow2
459 The use of qemu-nbd allows sharing of a disk between several guests:
461 qemu-nbd --socket=/tmp/my_socket --share=2 my_disk.qcow2
465 and then you can use it with two guests:
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
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:
474 qemu-system-i386 -cdrom nbd://localhost/debian-500-ppc-netinst
475 qemu-system-i386 -cdrom nbd://localhost/openSUSE-11.1-ppc-netinst
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:
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
486 @node disk_images_sheepdog
487 @subsection Sheepdog disk images
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.
493 You can create a Sheepdog disk image with the command:
495 qemu-img create sheepdog:///@var{image} @var{size}
497 where @var{image} is the Sheepdog image name and @var{size} is its
500 To import the existing @var{filename} to Sheepdog, you can use a
503 qemu-img convert @var{filename} sheepdog:///@var{image}
506 You can boot from the Sheepdog disk image with the command:
508 qemu-system-i386 sheepdog:///@var{image}
511 You can also create a snapshot of the Sheepdog image like qcow2.
513 qemu-img snapshot -c @var{tag} sheepdog:///@var{image}
515 where @var{tag} is a tag name of the newly created snapshot.
517 To boot from the Sheepdog snapshot, specify the tag name of the
520 qemu-system-i386 sheepdog:///@var{image}#@var{tag}
523 You can create a cloned image from the existing snapshot.
525 qemu-img create -b sheepdog:///@var{base}#@var{tag} sheepdog:///@var{image}
527 where @var{base} is an image name of the source snapshot and @var{tag}
530 You can use an unix socket instead of an inet socket:
533 qemu-system-i386 sheepdog+unix:///@var{image}?socket=@var{path}
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.
539 qemu-img create sheepdog://@var{hostname}:@var{port}/@var{image} @var{size}
540 qemu-system-i386 sheepdog://@var{hostname}:@var{port}/@var{image}
543 @node disk_images_iscsi
544 @subsection iSCSI LUNs
546 iSCSI is a popular protocol used to access SCSI devices across a computer
549 There are two different ways iSCSI devices can be used by QEMU.
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.
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.
560 In QEMU, iSCSI devices are described using special iSCSI URLs
564 iscsi://[<username>[%<password>]@@]<host>[:<port>]/<target-iqn-name>/<lun>
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
573 export LIBISCSI_CHAP_USERNAME=<username>
574 export LIBISCSI_CHAP_PASSWORD=<password>
575 iscsi://<host>/<target-iqn-name>/<lun>
578 Various session related parameters can be set via special options, either
579 in a configuration file provided via '-readconfig' or directly on the
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
589 Setting a specific initiator name to use when logging in to the target
590 -iscsi initiator-name=iqn.qemu.test:my-initiator
594 Controlling which type of header digest to negotiate with the target
595 -iscsi header-digest=CRC32C|CRC32C-NONE|NONE-CRC32C|NONE
598 These can also be set via a configuration file
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"
609 Setting the target name allows different options for different targets
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"
620 Howto use a configuration file to set iSCSI configuration options:
622 cat >iscsi.conf <<EOF
625 password = "my password"
626 initiator-name = "iqn.qemu.test:my-initiator"
627 header-digest = "CRC32C"
630 qemu-system-i386 -drive file=iscsi://127.0.0.1/iqn.qemu.test/1 \
631 -readconfig iscsi.conf
635 Howto set up a simple iSCSI target on loopback and accessing it via QEMU:
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'.
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
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
654 @node disk_images_gluster
655 @subsection GlusterFS disk images
657 GlusterFS is a user space distributed file system.
659 You can boot from the GlusterFS disk image with the command:
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=...]
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":"..."@}]@}@}'
673 @var{gluster} is the protocol.
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.
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
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.
690 @var{volume} is the name of the gluster volume which contains the disk image.
692 @var{path} is the path to the actual disk image that resides on gluster volume.
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
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
707 You can create a GlusterFS disk image with the command:
709 qemu-img create gluster://@var{host}/@var{volume}/@var{path} @var{size}
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
735 @node disk_images_ssh
736 @subsection Secure Shell (ssh) disk images
738 You can access disk images located on a remote ssh server
739 by using the ssh protocol:
742 qemu-system-x86_64 -drive file=ssh://[@var{user}@@]@var{server}[:@var{port}]/@var{path}[?host_key_check=@var{host_key_check}]
745 Alternative syntax using properties:
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}]
751 @var{ssh} is the protocol.
753 @var{user} is the remote user. If not specified, then the local
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.
760 @var{port} is the port number on which sshd is listening. By default
761 the standard ssh port (22) is used.
763 @var{path} is the path to the disk image.
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).
774 Currently authentication must be done using ssh-agent. Other
775 authentication methods may be supported in future.
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:
783 warning: ssh server @code{ssh.example.com:22} does not support fsync
785 With sufficiently new versions of libssh2 and OpenSSH, @code{fsync} is
788 @node disk_images_nvme
789 @subsection NVMe disk images
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.
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.
801 Before starting QEMU, bind the host NVMe controller to the host 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
811 # qemu-system-x86_64 -drive file=nvme://@var{host}:@var{bus}:@var{slot}.@var{func}/@var{namespace}
814 Alternative syntax using properties:
817 qemu-system-x86_64 -drive file.driver=nvme,file.device=@var{host}:@var{bus}:@var{slot}.@var{func},file.namespace=@var{namespace}
820 @var{host}:@var{bus}:@var{slot}.@var{func} is the NVMe controller's PCI device
823 @var{namespace} is the NVMe namespace number, starting from 1.
825 @node disk_image_locking
826 @subsection Disk image file locking
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.
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.
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.
844 QEMU transparently handles lock handover during shared storage migration. For
845 shared virtual disk images between multiple VMs, the "share-rw" device option
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
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.
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:
863 @code{-blockdev driver=qcow2,file.filename=/path/to/image,file.locking=off,file.driver=file}
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
875 @setfilename qemu-block-drivers
876 @settitle QEMU block drivers reference
879 The HTML documentation of QEMU for more precise information and Linux
880 user mode emulator invocation.
884 Fabrice Bellard and the QEMU Project developers