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