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