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