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
433Zoned block devices
434  Zoned block devices can be passed through to the guest if the emulated storage
435  controller supports zoned storage. Use ``--blockdev host_device,
436  node-name=drive0,filename=/dev/nullb0,cache.direct=on`` to pass through
437  ``/dev/nullb0`` as ``drive0``.
438
439Windows
440^^^^^^^
441
442CD
443  The preferred syntax is the drive letter (e.g. ``d:``). The
444  alternate syntax ``\\.\d:`` is supported. ``/dev/cdrom`` is
445  supported as an alias to the first CDROM drive.
446
447  Currently there is no specific code to handle removable media, so it
448  is better to use the ``change`` or ``eject`` monitor commands to
449  change or eject media.
450
451Hard disks
452  Hard disks can be used with the syntax: ``\\.\PhysicalDriveN``
453  where *N* is the drive number (0 is the first hard disk).
454
455  WARNING: unless you know what you do, it is better to only make
456  READ-ONLY accesses to the hard disk otherwise you may corrupt your
457  host data (use the ``-snapshot`` command line so that the
458  modifications are written in a temporary file).
459
460Mac OS X
461^^^^^^^^
462
463``/dev/cdrom`` is an alias to the first CDROM.
464
465Currently there is no specific code to handle removable media, so it
466is better to use the ``change`` or ``eject`` monitor commands to
467change or eject media.
468
469Virtual FAT disk images
470~~~~~~~~~~~~~~~~~~~~~~~
471
472QEMU can automatically create a virtual FAT disk image from a
473directory tree. In order to use it, just type:
474
475.. parsed-literal::
476
477  |qemu_system| linux.img -hdb fat:/my_directory
478
479Then you access access to all the files in the ``/my_directory``
480directory without having to copy them in a disk image or to export
481them via SAMBA or NFS. The default access is *read-only*.
482
483Floppies can be emulated with the ``:floppy:`` option:
484
485.. parsed-literal::
486
487  |qemu_system| linux.img -fda fat:floppy:/my_directory
488
489A read/write support is available for testing (beta stage) with the
490``:rw:`` option:
491
492.. parsed-literal::
493
494  |qemu_system| linux.img -fda fat:floppy:rw:/my_directory
495
496What you should *never* do:
497
498- use non-ASCII filenames
499- use "-snapshot" together with ":rw:"
500- expect it to work when loadvm'ing
501- write to the FAT directory on the host system while accessing it with the guest system
502
503NBD access
504~~~~~~~~~~
505
506QEMU can access directly to block device exported using the Network Block Device
507protocol.
508
509.. parsed-literal::
510
511  |qemu_system| linux.img -hdb nbd://my_nbd_server.mydomain.org:1024/
512
513If the NBD server is located on the same host, you can use an unix socket instead
514of an inet socket:
515
516.. parsed-literal::
517
518  |qemu_system| linux.img -hdb nbd+unix://?socket=/tmp/my_socket
519
520In this case, the block device must be exported using ``qemu-nbd``:
521
522.. parsed-literal::
523
524  qemu-nbd --socket=/tmp/my_socket my_disk.qcow2
525
526The use of ``qemu-nbd`` allows sharing of a disk between several guests:
527
528.. parsed-literal::
529
530  qemu-nbd --socket=/tmp/my_socket --share=2 my_disk.qcow2
531
532and then you can use it with two guests:
533
534.. parsed-literal::
535
536  |qemu_system| linux1.img -hdb nbd+unix://?socket=/tmp/my_socket
537  |qemu_system| linux2.img -hdb nbd+unix://?socket=/tmp/my_socket
538
539If the ``nbd-server`` uses named exports (supported since NBD 2.9.18, or with QEMU's
540own embedded NBD server), you must specify an export name in the URI:
541
542.. parsed-literal::
543
544  |qemu_system| -cdrom nbd://localhost/debian-500-ppc-netinst
545  |qemu_system| -cdrom nbd://localhost/openSUSE-11.1-ppc-netinst
546
547The URI syntax for NBD is supported since QEMU 1.3.  An alternative syntax is
548also available.  Here are some example of the older syntax:
549
550.. parsed-literal::
551
552  |qemu_system| linux.img -hdb nbd:my_nbd_server.mydomain.org:1024
553  |qemu_system| linux2.img -hdb nbd:unix:/tmp/my_socket
554  |qemu_system| -cdrom nbd:localhost:10809:exportname=debian-500-ppc-netinst
555
556iSCSI LUNs
557~~~~~~~~~~
558
559iSCSI is a popular protocol used to access SCSI devices across a computer
560network.
561
562There are two different ways iSCSI devices can be used by QEMU.
563
564The first method is to mount the iSCSI LUN on the host, and make it appear as
565any other ordinary SCSI device on the host and then to access this device as a
566/dev/sd device from QEMU. How to do this differs between host OSes.
567
568The second method involves using the iSCSI initiator that is built into
569QEMU. This provides a mechanism that works the same way regardless of which
570host OS you are running QEMU on. This section will describe this second method
571of using iSCSI together with QEMU.
572
573In QEMU, iSCSI devices are described using special iSCSI URLs. URL syntax:
574
575::
576
577  iscsi://[<username>[%<password>]@]<host>[:<port>]/<target-iqn-name>/<lun>
578
579Username and password are optional and only used if your target is set up
580using CHAP authentication for access control.
581Alternatively the username and password can also be set via environment
582variables to have these not show up in the process list:
583
584::
585
586  export LIBISCSI_CHAP_USERNAME=<username>
587  export LIBISCSI_CHAP_PASSWORD=<password>
588  iscsi://<host>/<target-iqn-name>/<lun>
589
590Various session related parameters can be set via special options, either
591in a configuration file provided via '-readconfig' or directly on the
592command line.
593
594If the initiator-name is not specified qemu will use a default name
595of 'iqn.2008-11.org.linux-kvm[:<uuid>'] where <uuid> is the UUID of the
596virtual machine. If the UUID is not specified qemu will use
597'iqn.2008-11.org.linux-kvm[:<name>'] where <name> is the name of the
598virtual machine.
599
600Setting a specific initiator name to use when logging in to the target:
601
602::
603
604  -iscsi initiator-name=iqn.qemu.test:my-initiator
605
606Controlling which type of header digest to negotiate with the target:
607
608::
609
610  -iscsi header-digest=CRC32C|CRC32C-NONE|NONE-CRC32C|NONE
611
612These can also be set via a configuration file:
613
614::
615
616  [iscsi]
617    user = "CHAP username"
618    password = "CHAP password"
619    initiator-name = "iqn.qemu.test:my-initiator"
620    # header digest is one of CRC32C|CRC32C-NONE|NONE-CRC32C|NONE
621    header-digest = "CRC32C"
622
623Setting the target name allows different options for different targets:
624
625::
626
627  [iscsi "iqn.target.name"]
628    user = "CHAP username"
629    password = "CHAP password"
630    initiator-name = "iqn.qemu.test:my-initiator"
631    # header digest is one of CRC32C|CRC32C-NONE|NONE-CRC32C|NONE
632    header-digest = "CRC32C"
633
634How to use a configuration file to set iSCSI configuration options:
635
636.. parsed-literal::
637
638  cat >iscsi.conf <<EOF
639  [iscsi]
640    user = "me"
641    password = "my password"
642    initiator-name = "iqn.qemu.test:my-initiator"
643    header-digest = "CRC32C"
644  EOF
645
646  |qemu_system| -drive file=iscsi://127.0.0.1/iqn.qemu.test/1 \\
647    -readconfig iscsi.conf
648
649How to set up a simple iSCSI target on loopback and access it via QEMU:
650this example shows how to set up an iSCSI target with one CDROM and one DISK
651using the Linux STGT software target. This target is available on Red Hat based
652systems as the package 'scsi-target-utils'.
653
654.. parsed-literal::
655
656  tgtd --iscsi portal=127.0.0.1:3260
657  tgtadm --lld iscsi --op new --mode target --tid 1 -T iqn.qemu.test
658  tgtadm --lld iscsi --mode logicalunit --op new --tid 1 --lun 1 \\
659      -b /IMAGES/disk.img --device-type=disk
660  tgtadm --lld iscsi --mode logicalunit --op new --tid 1 --lun 2 \\
661      -b /IMAGES/cd.iso --device-type=cd
662  tgtadm --lld iscsi --op bind --mode target --tid 1 -I ALL
663
664  |qemu_system| -iscsi initiator-name=iqn.qemu.test:my-initiator \\
665    -boot d -drive file=iscsi://127.0.0.1/iqn.qemu.test/1 \\
666    -cdrom iscsi://127.0.0.1/iqn.qemu.test/2
667
668GlusterFS disk images
669~~~~~~~~~~~~~~~~~~~~~
670
671GlusterFS is a user space distributed file system.
672
673You can boot from the GlusterFS disk image with the command:
674
675URI:
676
677.. parsed-literal::
678
679  |qemu_system| -drive file=gluster[+TYPE]://[HOST}[:PORT]]/VOLUME/PATH
680                               [?socket=...][,file.debug=9][,file.logfile=...]
681
682JSON:
683
684.. parsed-literal::
685
686  |qemu_system| 'json:{"driver":"qcow2",
687                           "file":{"driver":"gluster",
688                                    "volume":"testvol","path":"a.img","debug":9,"logfile":"...",
689                                    "server":[{"type":"tcp","host":"...","port":"..."},
690                                              {"type":"unix","socket":"..."}]}}'
691
692*gluster* is the protocol.
693
694*TYPE* specifies the transport type used to connect to gluster
695management daemon (glusterd). Valid transport types are
696tcp and unix. In the URI form, if a transport type isn't specified,
697then tcp type is assumed.
698
699*HOST* specifies the server where the volume file specification for
700the given volume resides. This can be either a hostname or an ipv4 address.
701If transport type is unix, then *HOST* field should not be specified.
702Instead *socket* field needs to be populated with the path to unix domain
703socket.
704
705*PORT* is the port number on which glusterd is listening. This is optional
706and if not specified, it defaults to port 24007. If the transport type is unix,
707then *PORT* should not be specified.
708
709*VOLUME* is the name of the gluster volume which contains the disk image.
710
711*PATH* is the path to the actual disk image that resides on gluster volume.
712
713*debug* is the logging level of the gluster protocol driver. Debug levels
714are 0-9, with 9 being the most verbose, and 0 representing no debugging output.
715The default level is 4. The current logging levels defined in the gluster source
716are 0 - None, 1 - Emergency, 2 - Alert, 3 - Critical, 4 - Error, 5 - Warning,
7176 - Notice, 7 - Info, 8 - Debug, 9 - Trace
718
719*logfile* is a commandline option to mention log file path which helps in
720logging to the specified file and also help in persisting the gfapi logs. The
721default is stderr.
722
723You can create a GlusterFS disk image with the command:
724
725.. parsed-literal::
726
727  qemu-img create gluster://HOST/VOLUME/PATH SIZE
728
729Examples
730
731.. parsed-literal::
732
733  |qemu_system| -drive file=gluster://1.2.3.4/testvol/a.img
734  |qemu_system| -drive file=gluster+tcp://1.2.3.4/testvol/a.img
735  |qemu_system| -drive file=gluster+tcp://1.2.3.4:24007/testvol/dir/a.img
736  |qemu_system| -drive file=gluster+tcp://[1:2:3:4:5:6:7:8]/testvol/dir/a.img
737  |qemu_system| -drive file=gluster+tcp://[1:2:3:4:5:6:7:8]:24007/testvol/dir/a.img
738  |qemu_system| -drive file=gluster+tcp://server.domain.com:24007/testvol/dir/a.img
739  |qemu_system| -drive file=gluster+unix:///testvol/dir/a.img?socket=/tmp/glusterd.socket
740  |qemu_system| -drive file=gluster://1.2.3.4/testvol/a.img,file.debug=9,file.logfile=/var/log/qemu-gluster.log
741  |qemu_system| 'json:{"driver":"qcow2",
742                           "file":{"driver":"gluster",
743                                    "volume":"testvol","path":"a.img",
744                                    "debug":9,"logfile":"/var/log/qemu-gluster.log",
745                                    "server":[{"type":"tcp","host":"1.2.3.4","port":24007},
746                                              {"type":"unix","socket":"/var/run/glusterd.socket"}]}}'
747  |qemu_system| -drive driver=qcow2,file.driver=gluster,file.volume=testvol,file.path=/path/a.img,
748                                       file.debug=9,file.logfile=/var/log/qemu-gluster.log,
749                                       file.server.0.type=tcp,file.server.0.host=1.2.3.4,file.server.0.port=24007,
750                                       file.server.1.type=unix,file.server.1.socket=/var/run/glusterd.socket
751
752Secure Shell (ssh) disk images
753~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
754
755You can access disk images located on a remote ssh server
756by using the ssh protocol:
757
758.. parsed-literal::
759
760  |qemu_system| -drive file=ssh://[USER@]SERVER[:PORT]/PATH[?host_key_check=HOST_KEY_CHECK]
761
762Alternative syntax using properties:
763
764.. parsed-literal::
765
766  |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]
767
768*ssh* is the protocol.
769
770*USER* is the remote user.  If not specified, then the local
771username is tried.
772
773*SERVER* specifies the remote ssh server.  Any ssh server can be
774used, but it must implement the sftp-server protocol.  Most Unix/Linux
775systems should work without requiring any extra configuration.
776
777*PORT* is the port number on which sshd is listening.  By default
778the standard ssh port (22) is used.
779
780*PATH* is the path to the disk image.
781
782The optional *HOST_KEY_CHECK* parameter controls how the remote
783host's key is checked.  The default is ``yes`` which means to use
784the local ``.ssh/known_hosts`` file.  Setting this to ``no``
785turns off known-hosts checking.  Or you can check that the host key
786matches a specific fingerprint. The fingerprint can be provided in
787``md5``, ``sha1``, or ``sha256`` format, however, it is strongly
788recommended to only use ``sha256``, since the other options are
789considered insecure by modern standards. The fingerprint value
790must be given as a hex encoded string::
791
792  host_key_check=sha256:04ce2ae89ff4295a6b9c4111640bdcb3297858ee55cb434d9dd88796e93aa795
793
794The key string may optionally contain ":" separators between
795each pair of hex digits.
796
797The ``$HOME/.ssh/known_hosts`` file contains the base64 encoded
798host keys. These can be converted into the format needed for
799QEMU using a command such as::
800
801   $ for key in `grep 10.33.8.112 known_hosts | awk '{print $3}'`
802     do
803       echo $key | base64 -d | sha256sum
804     done
805     6c3aa525beda9dc83eadfbd7e5ba7d976ecb59575d1633c87cd06ed2ed6e366f  -
806     12214fd9ea5b408086f98ecccd9958609bd9ac7c0ea316734006bc7818b45dc8  -
807     d36420137bcbd101209ef70c3b15dc07362fbe0fa53c5b135eba6e6afa82f0ce  -
808
809Note that there can be multiple keys present per host, each with
810different key ciphers. Care is needed to pick the key fingerprint
811that matches the cipher QEMU will negotiate with the remote server.
812
813Currently authentication must be done using ssh-agent.  Other
814authentication methods may be supported in future.
815
816Note: Many ssh servers do not support an ``fsync``-style operation.
817The ssh driver cannot guarantee that disk flush requests are
818obeyed, and this causes a risk of disk corruption if the remote
819server or network goes down during writes.  The driver will
820print a warning when ``fsync`` is not supported:
821
822::
823
824  warning: ssh server ssh.example.com:22 does not support fsync
825
826With sufficiently new versions of libssh and OpenSSH, ``fsync`` is
827supported.
828
829NVMe disk images
830~~~~~~~~~~~~~~~~
831
832NVM Express (NVMe) storage controllers can be accessed directly by a userspace
833driver in QEMU.  This bypasses the host kernel file system and block layers
834while retaining QEMU block layer functionalities, such as block jobs, I/O
835throttling, image formats, etc.  Disk I/O performance is typically higher than
836with ``-drive file=/dev/sda`` using either thread pool or linux-aio.
837
838The controller will be exclusively used by the QEMU process once started. To be
839able to share storage between multiple VMs and other applications on the host,
840please use the file based protocols.
841
842Before starting QEMU, bind the host NVMe controller to the host vfio-pci
843driver.  For example:
844
845.. parsed-literal::
846
847  # modprobe vfio-pci
848  # lspci -n -s 0000:06:0d.0
849  06:0d.0 0401: 1102:0002 (rev 08)
850  # echo 0000:06:0d.0 > /sys/bus/pci/devices/0000:06:0d.0/driver/unbind
851  # echo 1102 0002 > /sys/bus/pci/drivers/vfio-pci/new_id
852
853  # |qemu_system| -drive file=nvme://HOST:BUS:SLOT.FUNC/NAMESPACE
854
855Alternative syntax using properties:
856
857.. parsed-literal::
858
859  |qemu_system| -drive file.driver=nvme,file.device=HOST:BUS:SLOT.FUNC,file.namespace=NAMESPACE
860
861*HOST*:*BUS*:*SLOT*.\ *FUNC* is the NVMe controller's PCI device
862address on the host.
863
864*NAMESPACE* is the NVMe namespace number, starting from 1.
865
866Disk image file locking
867~~~~~~~~~~~~~~~~~~~~~~~
868
869By default, QEMU tries to protect image files from unexpected concurrent
870access, as long as it's supported by the block protocol driver and host
871operating system. If multiple QEMU processes (including QEMU emulators and
872utilities) try to open the same image with conflicting accessing modes, all but
873the first one will get an error.
874
875This feature is currently supported by the file protocol on Linux with the Open
876File Descriptor (OFD) locking API, and can be configured to fall back to POSIX
877locking if the POSIX host doesn't support Linux OFD locking.
878
879To explicitly enable image locking, specify "locking=on" in the file protocol
880driver options. If OFD locking is not possible, a warning will be printed and
881the POSIX locking API will be used. In this case there is a risk that the lock
882will get silently lost when doing hot plugging and block jobs, due to the
883shortcomings of the POSIX locking API.
884
885QEMU transparently handles lock handover during shared storage migration.  For
886shared virtual disk images between multiple VMs, the "share-rw" device option
887should be used.
888
889By default, the guest has exclusive write access to its disk image. If the
890guest can safely share the disk image with other writers the
891``-device ...,share-rw=on`` parameter can be used.  This is only safe if
892the guest is running software, such as a cluster file system, that
893coordinates disk accesses to avoid corruption.
894
895Note that share-rw=on only declares the guest's ability to share the disk.
896Some QEMU features, such as image file formats, require exclusive write access
897to the disk image and this is unaffected by the share-rw=on option.
898
899Alternatively, locking can be fully disabled by "locking=off" block device
900option. In the command line, the option is usually in the form of
901"file.locking=off" as the protocol driver is normally placed as a "file" child
902under a format driver. For example:
903
904::
905
906  -blockdev driver=qcow2,file.filename=/path/to/image,file.locking=off,file.driver=file
907
908To check if image locking is active, check the output of the "lslocks" command
909on host and see if there are locks held by the QEMU process on the image file.
910More than one byte could be locked by the QEMU instance, each byte of which
911reflects a particular permission that is acquired or protected by the running
912block driver.
913
914Filter drivers
915~~~~~~~~~~~~~~
916
917QEMU supports several filter drivers, which don't store any data, but perform
918some additional tasks, hooking io requests.
919
920.. program:: filter-drivers
921.. option:: preallocate
922
923  The preallocate filter driver is intended to be inserted between format
924  and protocol nodes and preallocates some additional space
925  (expanding the protocol file) when writing past the file’s end. This can be
926  useful for file-systems with slow allocation.
927
928  Supported options:
929
930  .. program:: preallocate
931  .. option:: prealloc-align
932
933    On preallocation, align the file length to this value (in bytes), default 1M.
934
935  .. program:: preallocate
936  .. option:: prealloc-size
937
938    How much to preallocate (in bytes), default 128M.
939