1QEMU-BLOCK-DRIVERS(7)                QEMU                QEMU-BLOCK-DRIVERS(7)
2
3
4

NAME

6       qemu-block-drivers - QEMU block drivers reference
7

SYNOPSIS

9       QEMU block driver reference manual
10

DESCRIPTION

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

SEE ALSO

785       The HTML documentation of QEMU for more precise information  and  Linux
786       user mode emulator invocation.
787

AUTHOR

789       Fabrice Bellard and the QEMU Project developers
790
792       2021, The QEMU Project Developers
793
794
795
796
7976.1.0                            Nov 08, 2021            QEMU-BLOCK-DRIVERS(7)
Impressum