configure: move accelerator logic to meson
[qemu.git] / docs / system / qemu-block-drivers.rst.inc
1 Disk image file formats
2 ~~~~~~~~~~~~~~~~~~~~~~~
3
4 QEMU supports many image file formats that can be used with VMs as well as with
5 any of the tools (like ``qemu-img``). This includes the preferred formats
6 raw and qcow2 as well as formats that are supported for compatibility with
7 older QEMU versions or other hypervisors.
8
9 Depending on the image format, different options can be passed to
10 ``qemu-img create`` and ``qemu-img convert`` using the ``-o`` option.
11 This 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
373 Read-only formats
374 ~~~~~~~~~~~~~~~~~
375
376 More 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
399 Using host drives
400 ~~~~~~~~~~~~~~~~~
401
402 In addition to disk image files, QEMU can directly access host
403 devices. We describe here the usage for QEMU version >= 0.8.3.
404
405 Linux
406 ^^^^^
407
408 On Linux, you can directly use the host device filename instead of a
409 disk image filename provided you have enough privileges to access
410 it. For example, use ``/dev/cdrom`` to access to the CDROM.
411
412 CD
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
417 Floppy
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
425 Hard 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
433 Windows
434 ^^^^^^^
435
436 CD
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
445 Hard 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
454 Mac OS X
455 ^^^^^^^^
456
457 ``/dev/cdrom`` is an alias to the first CDROM.
458
459 Currently there is no specific code to handle removable media, so it
460 is better to use the ``change`` or ``eject`` monitor commands to
461 change or eject media.
462
463 Virtual FAT disk images
464 ~~~~~~~~~~~~~~~~~~~~~~~
465
466 QEMU can automatically create a virtual FAT disk image from a
467 directory tree. In order to use it, just type:
468
469 .. parsed-literal::
470
471   |qemu_system| linux.img -hdb fat:/my_directory
472
473 Then you access access to all the files in the ``/my_directory``
474 directory without having to copy them in a disk image or to export
475 them via SAMBA or NFS. The default access is *read-only*.
476
477 Floppies can be emulated with the ``:floppy:`` option:
478
479 .. parsed-literal::
480
481   |qemu_system| linux.img -fda fat:floppy:/my_directory
482
483 A 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
490 What 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
497 NBD access
498 ~~~~~~~~~~
499
500 QEMU can access directly to block device exported using the Network Block Device
501 protocol.
502
503 .. parsed-literal::
504
505   |qemu_system| linux.img -hdb nbd://my_nbd_server.mydomain.org:1024/
506
507 If the NBD server is located on the same host, you can use an unix socket instead
508 of an inet socket:
509
510 .. parsed-literal::
511
512   |qemu_system| linux.img -hdb nbd+unix://?socket=/tmp/my_socket
513
514 In 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
520 The 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
526 and 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
533 If the nbd-server uses named exports (supported since NBD 2.9.18, or with QEMU's
534 own 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
541 The URI syntax for NBD is supported since QEMU 1.3.  An alternative syntax is
542 also 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
550
551
552 Sheepdog disk images
553 ~~~~~~~~~~~~~~~~~~~~
554
555 Sheepdog is a distributed storage system for QEMU.  It provides highly
556 available block level storage volumes that can be attached to
557 QEMU-based virtual machines.
558
559 You can create a Sheepdog disk image with the command:
560
561 .. parsed-literal::
562
563   qemu-img create sheepdog:///IMAGE SIZE
564
565 where *IMAGE* is the Sheepdog image name and *SIZE* is its
566 size.
567
568 To import the existing *FILENAME* to Sheepdog, you can use a
569 convert command.
570
571 .. parsed-literal::
572
573   qemu-img convert FILENAME sheepdog:///IMAGE
574
575 You can boot from the Sheepdog disk image with the command:
576
577 .. parsed-literal::
578
579   |qemu_system| sheepdog:///IMAGE
580
581 You can also create a snapshot of the Sheepdog image like qcow2.
582
583 .. parsed-literal::
584
585   qemu-img snapshot -c TAG sheepdog:///IMAGE
586
587 where *TAG* is a tag name of the newly created snapshot.
588
589 To boot from the Sheepdog snapshot, specify the tag name of the
590 snapshot.
591
592 .. parsed-literal::
593
594   |qemu_system| sheepdog:///IMAGE#TAG
595
596 You can create a cloned image from the existing snapshot.
597
598 .. parsed-literal::
599
600   qemu-img create -b sheepdog:///BASE#TAG sheepdog:///IMAGE
601
602 where *BASE* is an image name of the source snapshot and *TAG*
603 is its tag name.
604
605 You can use an unix socket instead of an inet socket:
606
607 .. parsed-literal::
608
609   |qemu_system| sheepdog+unix:///IMAGE?socket=PATH
610
611 If the Sheepdog daemon doesn't run on the local host, you need to
612 specify one of the Sheepdog servers to connect to.
613
614 .. parsed-literal::
615
616   qemu-img create sheepdog://HOSTNAME:PORT/IMAGE SIZE
617   |qemu_system| sheepdog://HOSTNAME:PORT/IMAGE
618
619 iSCSI LUNs
620 ~~~~~~~~~~
621
622 iSCSI is a popular protocol used to access SCSI devices across a computer
623 network.
624
625 There are two different ways iSCSI devices can be used by QEMU.
626
627 The first method is to mount the iSCSI LUN on the host, and make it appear as
628 any other ordinary SCSI device on the host and then to access this device as a
629 /dev/sd device from QEMU. How to do this differs between host OSes.
630
631 The second method involves using the iSCSI initiator that is built into
632 QEMU. This provides a mechanism that works the same way regardless of which
633 host OS you are running QEMU on. This section will describe this second method
634 of using iSCSI together with QEMU.
635
636 In QEMU, iSCSI devices are described using special iSCSI URLs. URL syntax:
637
638 ::
639
640   iscsi://[<username>[%<password>]@]<host>[:<port>]/<target-iqn-name>/<lun>
641
642 Username and password are optional and only used if your target is set up
643 using CHAP authentication for access control.
644 Alternatively the username and password can also be set via environment
645 variables to have these not show up in the process list:
646
647 ::
648
649   export LIBISCSI_CHAP_USERNAME=<username>
650   export LIBISCSI_CHAP_PASSWORD=<password>
651   iscsi://<host>/<target-iqn-name>/<lun>
652
653 Various session related parameters can be set via special options, either
654 in a configuration file provided via '-readconfig' or directly on the
655 command line.
656
657 If the initiator-name is not specified qemu will use a default name
658 of 'iqn.2008-11.org.linux-kvm[:<uuid>'] where <uuid> is the UUID of the
659 virtual machine. If the UUID is not specified qemu will use
660 'iqn.2008-11.org.linux-kvm[:<name>'] where <name> is the name of the
661 virtual machine.
662
663 Setting a specific initiator name to use when logging in to the target:
664
665 ::
666
667   -iscsi initiator-name=iqn.qemu.test:my-initiator
668
669 Controlling which type of header digest to negotiate with the target:
670
671 ::
672
673   -iscsi header-digest=CRC32C|CRC32C-NONE|NONE-CRC32C|NONE
674
675 These can also be set via a configuration file:
676
677 ::
678
679   [iscsi]
680     user = "CHAP username"
681     password = "CHAP password"
682     initiator-name = "iqn.qemu.test:my-initiator"
683     # header digest is one of CRC32C|CRC32C-NONE|NONE-CRC32C|NONE
684     header-digest = "CRC32C"
685
686 Setting the target name allows different options for different targets:
687
688 ::
689
690   [iscsi "iqn.target.name"]
691     user = "CHAP username"
692     password = "CHAP password"
693     initiator-name = "iqn.qemu.test:my-initiator"
694     # header digest is one of CRC32C|CRC32C-NONE|NONE-CRC32C|NONE
695     header-digest = "CRC32C"
696
697 How to use a configuration file to set iSCSI configuration options:
698
699 .. parsed-literal::
700
701   cat >iscsi.conf <<EOF
702   [iscsi]
703     user = "me"
704     password = "my password"
705     initiator-name = "iqn.qemu.test:my-initiator"
706     header-digest = "CRC32C"
707   EOF
708
709   |qemu_system| -drive file=iscsi://127.0.0.1/iqn.qemu.test/1 \\
710     -readconfig iscsi.conf
711
712 How to set up a simple iSCSI target on loopback and access it via QEMU:
713 this example shows how to set up an iSCSI target with one CDROM and one DISK
714 using the Linux STGT software target. This target is available on Red Hat based
715 systems as the package 'scsi-target-utils'.
716
717 .. parsed-literal::
718
719   tgtd --iscsi portal=127.0.0.1:3260
720   tgtadm --lld iscsi --op new --mode target --tid 1 -T iqn.qemu.test
721   tgtadm --lld iscsi --mode logicalunit --op new --tid 1 --lun 1 \\
722       -b /IMAGES/disk.img --device-type=disk
723   tgtadm --lld iscsi --mode logicalunit --op new --tid 1 --lun 2 \\
724       -b /IMAGES/cd.iso --device-type=cd
725   tgtadm --lld iscsi --op bind --mode target --tid 1 -I ALL
726
727   |qemu_system| -iscsi initiator-name=iqn.qemu.test:my-initiator \\
728     -boot d -drive file=iscsi://127.0.0.1/iqn.qemu.test/1 \\
729     -cdrom iscsi://127.0.0.1/iqn.qemu.test/2
730
731 GlusterFS disk images
732 ~~~~~~~~~~~~~~~~~~~~~
733
734 GlusterFS is a user space distributed file system.
735
736 You can boot from the GlusterFS disk image with the command:
737
738 URI:
739
740 .. parsed-literal::
741
742   |qemu_system| -drive file=gluster[+TYPE]://[HOST}[:PORT]]/VOLUME/PATH
743                                [?socket=...][,file.debug=9][,file.logfile=...]
744
745 JSON:
746
747 .. parsed-literal::
748
749   |qemu_system| 'json:{"driver":"qcow2",
750                            "file":{"driver":"gluster",
751                                     "volume":"testvol","path":"a.img","debug":9,"logfile":"...",
752                                     "server":[{"type":"tcp","host":"...","port":"..."},
753                                               {"type":"unix","socket":"..."}]}}'
754
755 *gluster* is the protocol.
756
757 *TYPE* specifies the transport type used to connect to gluster
758 management daemon (glusterd). Valid transport types are
759 tcp and unix. In the URI form, if a transport type isn't specified,
760 then tcp type is assumed.
761
762 *HOST* specifies the server where the volume file specification for
763 the given volume resides. This can be either a hostname or an ipv4 address.
764 If transport type is unix, then *HOST* field should not be specified.
765 Instead *socket* field needs to be populated with the path to unix domain
766 socket.
767
768 *PORT* is the port number on which glusterd is listening. This is optional
769 and if not specified, it defaults to port 24007. If the transport type is unix,
770 then *PORT* should not be specified.
771
772 *VOLUME* is the name of the gluster volume which contains the disk image.
773
774 *PATH* is the path to the actual disk image that resides on gluster volume.
775
776 *debug* is the logging level of the gluster protocol driver. Debug levels
777 are 0-9, with 9 being the most verbose, and 0 representing no debugging output.
778 The default level is 4. The current logging levels defined in the gluster source
779 are 0 - None, 1 - Emergency, 2 - Alert, 3 - Critical, 4 - Error, 5 - Warning,
780 6 - Notice, 7 - Info, 8 - Debug, 9 - Trace
781
782 *logfile* is a commandline option to mention log file path which helps in
783 logging to the specified file and also help in persisting the gfapi logs. The
784 default is stderr.
785
786 You can create a GlusterFS disk image with the command:
787
788 .. parsed-literal::
789
790   qemu-img create gluster://HOST/VOLUME/PATH SIZE
791
792 Examples
793
794 .. parsed-literal::
795
796   |qemu_system| -drive file=gluster://1.2.3.4/testvol/a.img
797   |qemu_system| -drive file=gluster+tcp://1.2.3.4/testvol/a.img
798   |qemu_system| -drive file=gluster+tcp://1.2.3.4:24007/testvol/dir/a.img
799   |qemu_system| -drive file=gluster+tcp://[1:2:3:4:5:6:7:8]/testvol/dir/a.img
800   |qemu_system| -drive file=gluster+tcp://[1:2:3:4:5:6:7:8]:24007/testvol/dir/a.img
801   |qemu_system| -drive file=gluster+tcp://server.domain.com:24007/testvol/dir/a.img
802   |qemu_system| -drive file=gluster+unix:///testvol/dir/a.img?socket=/tmp/glusterd.socket
803   |qemu_system| -drive file=gluster+rdma://1.2.3.4:24007/testvol/a.img
804   |qemu_system| -drive file=gluster://1.2.3.4/testvol/a.img,file.debug=9,file.logfile=/var/log/qemu-gluster.log
805   |qemu_system| 'json:{"driver":"qcow2",
806                            "file":{"driver":"gluster",
807                                     "volume":"testvol","path":"a.img",
808                                     "debug":9,"logfile":"/var/log/qemu-gluster.log",
809                                     "server":[{"type":"tcp","host":"1.2.3.4","port":24007},
810                                               {"type":"unix","socket":"/var/run/glusterd.socket"}]}}'
811   |qemu_system| -drive driver=qcow2,file.driver=gluster,file.volume=testvol,file.path=/path/a.img,
812                                        file.debug=9,file.logfile=/var/log/qemu-gluster.log,
813                                        file.server.0.type=tcp,file.server.0.host=1.2.3.4,file.server.0.port=24007,
814                                        file.server.1.type=unix,file.server.1.socket=/var/run/glusterd.socket
815
816 Secure Shell (ssh) disk images
817 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
818
819 You can access disk images located on a remote ssh server
820 by using the ssh protocol:
821
822 .. parsed-literal::
823
824   |qemu_system| -drive file=ssh://[USER@]SERVER[:PORT]/PATH[?host_key_check=HOST_KEY_CHECK]
825
826 Alternative syntax using properties:
827
828 .. parsed-literal::
829
830   |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]
831
832 *ssh* is the protocol.
833
834 *USER* is the remote user.  If not specified, then the local
835 username is tried.
836
837 *SERVER* specifies the remote ssh server.  Any ssh server can be
838 used, but it must implement the sftp-server protocol.  Most Unix/Linux
839 systems should work without requiring any extra configuration.
840
841 *PORT* is the port number on which sshd is listening.  By default
842 the standard ssh port (22) is used.
843
844 *PATH* is the path to the disk image.
845
846 The optional *HOST_KEY_CHECK* parameter controls how the remote
847 host's key is checked.  The default is ``yes`` which means to use
848 the local ``.ssh/known_hosts`` file.  Setting this to ``no``
849 turns off known-hosts checking.  Or you can check that the host key
850 matches a specific fingerprint:
851 ``host_key_check=md5:78:45:8e:14:57:4f:d5:45:83:0a:0e:f3:49:82:c9:c8``
852 (``sha1:`` can also be used as a prefix, but note that OpenSSH
853 tools only use MD5 to print fingerprints).
854
855 Currently authentication must be done using ssh-agent.  Other
856 authentication methods may be supported in future.
857
858 Note: Many ssh servers do not support an ``fsync``-style operation.
859 The ssh driver cannot guarantee that disk flush requests are
860 obeyed, and this causes a risk of disk corruption if the remote
861 server or network goes down during writes.  The driver will
862 print a warning when ``fsync`` is not supported:
863
864 ::
865
866   warning: ssh server ssh.example.com:22 does not support fsync
867
868 With sufficiently new versions of libssh and OpenSSH, ``fsync`` is
869 supported.
870
871 NVMe disk images
872 ~~~~~~~~~~~~~~~~
873
874 NVM Express (NVMe) storage controllers can be accessed directly by a userspace
875 driver in QEMU.  This bypasses the host kernel file system and block layers
876 while retaining QEMU block layer functionalities, such as block jobs, I/O
877 throttling, image formats, etc.  Disk I/O performance is typically higher than
878 with ``-drive file=/dev/sda`` using either thread pool or linux-aio.
879
880 The controller will be exclusively used by the QEMU process once started. To be
881 able to share storage between multiple VMs and other applications on the host,
882 please use the file based protocols.
883
884 Before starting QEMU, bind the host NVMe controller to the host vfio-pci
885 driver.  For example:
886
887 .. parsed-literal::
888
889   # modprobe vfio-pci
890   # lspci -n -s 0000:06:0d.0
891   06:0d.0 0401: 1102:0002 (rev 08)
892   # echo 0000:06:0d.0 > /sys/bus/pci/devices/0000:06:0d.0/driver/unbind
893   # echo 1102 0002 > /sys/bus/pci/drivers/vfio-pci/new_id
894
895   # |qemu_system| -drive file=nvme://HOST:BUS:SLOT.FUNC/NAMESPACE
896
897 Alternative syntax using properties:
898
899 .. parsed-literal::
900
901   |qemu_system| -drive file.driver=nvme,file.device=HOST:BUS:SLOT.FUNC,file.namespace=NAMESPACE
902
903 *HOST*:*BUS*:*SLOT*.\ *FUNC* is the NVMe controller's PCI device
904 address on the host.
905
906 *NAMESPACE* is the NVMe namespace number, starting from 1.
907
908 Disk image file locking
909 ~~~~~~~~~~~~~~~~~~~~~~~
910
911 By default, QEMU tries to protect image files from unexpected concurrent
912 access, as long as it's supported by the block protocol driver and host
913 operating system. If multiple QEMU processes (including QEMU emulators and
914 utilities) try to open the same image with conflicting accessing modes, all but
915 the first one will get an error.
916
917 This feature is currently supported by the file protocol on Linux with the Open
918 File Descriptor (OFD) locking API, and can be configured to fall back to POSIX
919 locking if the POSIX host doesn't support Linux OFD locking.
920
921 To explicitly enable image locking, specify "locking=on" in the file protocol
922 driver options. If OFD locking is not possible, a warning will be printed and
923 the POSIX locking API will be used. In this case there is a risk that the lock
924 will get silently lost when doing hot plugging and block jobs, due to the
925 shortcomings of the POSIX locking API.
926
927 QEMU transparently handles lock handover during shared storage migration.  For
928 shared virtual disk images between multiple VMs, the "share-rw" device option
929 should be used.
930
931 By default, the guest has exclusive write access to its disk image. If the
932 guest can safely share the disk image with other writers the
933 ``-device ...,share-rw=on`` parameter can be used.  This is only safe if
934 the guest is running software, such as a cluster file system, that
935 coordinates disk accesses to avoid corruption.
936
937 Note that share-rw=on only declares the guest's ability to share the disk.
938 Some QEMU features, such as image file formats, require exclusive write access
939 to the disk image and this is unaffected by the share-rw=on option.
940
941 Alternatively, locking can be fully disabled by "locking=off" block device
942 option. In the command line, the option is usually in the form of
943 "file.locking=off" as the protocol driver is normally placed as a "file" child
944 under a format driver. For example:
945
946 ::
947
948   -blockdev driver=qcow2,file.filename=/path/to/image,file.locking=off,file.driver=file
949
950 To check if image locking is active, check the output of the "lslocks" command
951 on host and see if there are locks held by the QEMU process on the image file.
952 More than one byte could be locked by the QEMU instance, each byte of which
953 reflects a particular permission that is acquired or protected by the running
954 block driver.