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