Peter Maydell <peter.mayd...@linaro.org> writes:
> The qemu-block-drivers documentation is currently in > docs/qemu-block-drivers.texi in Texinfo format, which we present > to the user as: > * a qemu-block-drivers manpage > * a section of the main qemu-doc HTML documentation > > Convert the documentation to rST format, and present it to > the user as: > * a qemu-block-drivers manpage > * part of the system/ Sphinx manual > > This follows the same pattern we've done for qemu-ga and qemu-nbd. > > We have to drop a cross-reference from the documentation of the > -cdrom option back to the qemu-block-drivers documentation, since > they're no longer within the same texinfo document. > > As noted in a comment, the manpage output is slightly compromised > due to limitations in Sphinx. In an ideal world, the HTML output > would have the various headings like 'Disk image file formats' > as top-level section headings (which then appear in the overall > system manual's table-of-contents), and it would not have the > section headings which make sense only for the manpage like > 'synopsis', 'description', and 'see also'. Unfortunately, the > mechanism Sphinx provides for restricting pieces of documentation > is limited to the point of being flawed: the 'only::' directive > is implemented as a filter that is applied at a very late stage > in the document processing pipeline, rather than as an early > equivalent of an #ifdef. This means that Sphinx's process of > identifying which section heading markup styles are which levels > of heading gets confused if the 'only::' directive contains > section headings which would affect the heading-level of a > later heading. I have opted to prioritise making the HTML format > look better, with the compromise being that in the manpage > the 'Disk image file formats' &c headings are top-level headings > rather than being sub-headings under the traditional 'Description' > top-level section title. > > Signed-off-by: Peter Maydell <peter.mayd...@linaro.org> Reviewed-by: Alex Bennée <alex.ben...@linaro.org> Tested-by: Alex Bennée <alex.ben...@linaro.org> > --- > I enquired on sphinx-users (without response so far) > https://www.mail-archive.com/sphinx-users@googlegroups.com/msg03837.html > whether there's a better approach than using 'only::' to delimit > output for a specific format. That directive seems fundamentally > flawed because it's implemented as a filter very late in the document > processing, so for instance text goes into the search index even if > it's marked as not-for-HTML: > https://github.com/sphinx-doc/sphinx/issues/1420 > What we want ideally would be some equivalent to #ifdef that happens > early in the processing pipeline, but I'm not sure Sphinx has it and > I'm not convinced that "run everything through the C preprocessor so > we can use #ifdef" is worthwhile for the minor benefit here. > --- > Makefile | 11 +- > docs/qemu-block-drivers.texi | 889 -------------------------- > docs/system/conf.py | 7 + > docs/system/index.rst | 1 + > docs/system/qemu-block-drivers.rst | 985 +++++++++++++++++++++++++++++ > qemu-doc.texi | 12 - > qemu-options.hx | 2 +- > 7 files changed, 1000 insertions(+), 907 deletions(-) > delete mode 100644 docs/qemu-block-drivers.texi > create mode 100644 docs/system/qemu-block-drivers.rst > > diff --git a/Makefile b/Makefile > index 4372d0d1fbd..318d1046c6c 100644 > --- a/Makefile > +++ b/Makefile > @@ -342,9 +342,9 @@ ifdef BUILD_DOCS > DOCS=qemu-doc.html qemu-doc.txt qemu.1 qemu-img.1 > DOCS+=$(MANUAL_BUILDDIR)/interop/qemu-nbd.8 > DOCS+=$(MANUAL_BUILDDIR)/interop/qemu-ga.8 > +DOCS+=$(MANUAL_BUILDDIR)/system/qemu-block-drivers.7 > DOCS+=docs/interop/qemu-qmp-ref.html docs/interop/qemu-qmp-ref.txt > docs/interop/qemu-qmp-ref.7 > DOCS+=docs/interop/qemu-ga-ref.html docs/interop/qemu-ga-ref.txt > docs/interop/qemu-ga-ref.7 > -DOCS+=docs/qemu-block-drivers.7 > DOCS+=docs/qemu-cpu-models.7 > DOCS+=$(MANUAL_BUILDDIR)/index.html > ifdef CONFIG_VIRTFS > @@ -751,7 +751,6 @@ distclean: clean > rm -f docs/interop/qemu-qmp-ref.txt docs/interop/qemu-ga-ref.txt > rm -f docs/interop/qemu-qmp-ref.pdf docs/interop/qemu-ga-ref.pdf > rm -f docs/interop/qemu-qmp-ref.html docs/interop/qemu-ga-ref.html > - rm -f docs/qemu-block-drivers.7 > rm -f docs/qemu-cpu-models.7 > rm -rf .doctrees > $(call clean-manual,devel) > @@ -828,7 +827,7 @@ ifdef CONFIG_POSIX > $(INSTALL_DATA) qemu.1 "$(DESTDIR)$(mandir)/man1" > $(INSTALL_DIR) "$(DESTDIR)$(mandir)/man7" > $(INSTALL_DATA) docs/interop/qemu-qmp-ref.7 "$(DESTDIR)$(mandir)/man7" > - $(INSTALL_DATA) docs/qemu-block-drivers.7 "$(DESTDIR)$(mandir)/man7" > + $(INSTALL_DATA) $(MANUAL_BUILDDIR)/system/qemu-block-drivers.7 > "$(DESTDIR)$(mandir)/man7" > $(INSTALL_DATA) docs/qemu-cpu-models.7 "$(DESTDIR)$(mandir)/man7" > ifeq ($(CONFIG_TOOLS),y) > $(INSTALL_DATA) qemu-img.1 "$(DESTDIR)$(mandir)/man1" > @@ -1036,6 +1035,9 @@ $(MANUAL_BUILDDIR)/interop/qemu-ga.8: $(call > manual-deps,interop) > $(MANUAL_BUILDDIR)/interop/qemu-nbd.8: $(call manual-deps,interop) > $(call build-manual,interop,man) > > +$(MANUAL_BUILDDIR)/system/qemu-block-drivers.7: $(call manual-deps,system) > + $(call build-manual,system,man) > + > $(MANUAL_BUILDDIR)/index.html: $(SRC_PATH)/docs/index.html.in qemu-version.h > $(call quiet-command, sed "s|@@VERSION@@|${VERSION}|g" $< >$@, \ > "GEN","$@") > @@ -1062,7 +1064,6 @@ qemu.1: qemu-doc.texi qemu-options.texi > qemu-monitor.texi qemu-monitor-info.texi > qemu.1: qemu-option-trace.texi > qemu-img.1: qemu-img.texi qemu-option-trace.texi qemu-img-cmds.texi > fsdev/virtfs-proxy-helper.1: fsdev/virtfs-proxy-helper.texi > -docs/qemu-block-drivers.7: docs/qemu-block-drivers.texi > docs/qemu-cpu-models.7: docs/qemu-cpu-models.texi > scripts/qemu-trace-stap.1: scripts/qemu-trace-stap.texi > > @@ -1075,7 +1076,7 @@ qemu-doc.html qemu-doc.info qemu-doc.pdf qemu-doc.txt: \ > qemu-img.texi qemu-options.texi \ > qemu-tech.texi qemu-option-trace.texi \ > qemu-deprecated.texi qemu-monitor.texi qemu-img-cmds.texi \ > - qemu-monitor-info.texi docs/qemu-block-drivers.texi \ > + qemu-monitor-info.texi \ > docs/qemu-cpu-models.texi docs/security.texi > > docs/interop/qemu-ga-ref.dvi docs/interop/qemu-ga-ref.html \ > diff --git a/docs/qemu-block-drivers.texi b/docs/qemu-block-drivers.texi > deleted file mode 100644 > index 2c7ea49c32d..00000000000 > --- a/docs/qemu-block-drivers.texi > +++ /dev/null > @@ -1,889 +0,0 @@ > -@c man begin SYNOPSIS > -QEMU block driver reference manual > -@c man end > - > -@set qemu_system qemu-system-x86_64 > - > -@c man begin DESCRIPTION > - > -@node disk_images_formats > -@subsection Disk image file formats > - > -QEMU supports many image file formats that can be used with VMs as well as > with > -any of the tools (like @code{qemu-img}). This includes the preferred formats > -raw and qcow2 as well as formats that are supported for compatibility with > -older QEMU versions or other hypervisors. > - > -Depending on the image format, different options can be passed to > -@code{qemu-img create} and @code{qemu-img convert} using the @code{-o} > option. > -This section describes each format and the options that are supported for it. > - > -@table @option > -@item raw > - > -Raw disk image format. This format has the advantage of > -being simple and easily exportable to all other emulators. If your > -file system supports @emph{holes} (for example in ext2 or ext3 on > -Linux or NTFS on Windows), then only the written sectors will reserve > -space. Use @code{qemu-img info} to know the real size used by the > -image or @code{ls -ls} on Unix/Linux. > - > -Supported options: > -@table @code > -@item preallocation > -Preallocation mode (allowed values: @code{off}, @code{falloc}, @code{full}). > -@code{falloc} mode preallocates space for image by calling posix_fallocate(). > -@code{full} mode preallocates space for image by writing data to underlying > -storage. This data may or may not be zero, depending on the storage > location. > -@end table > - > -@item qcow2 > -QEMU image format, the most versatile format. Use it to have smaller > -images (useful if your filesystem does not supports holes, for example > -on Windows), zlib based compression and support of multiple VM > -snapshots. > - > -Supported options: > -@table @code > -@item compat > -Determines the qcow2 version to use. @code{compat=0.10} uses the > -traditional image format that can be read by any QEMU since 0.10. > -@code{compat=1.1} enables image format extensions that only QEMU 1.1 and > -newer understand (this is the default). Amongst others, this includes > -zero clusters, which allow efficient copy-on-read for sparse images. > - > -@item backing_file > -File name of a base image (see @option{create} subcommand) > -@item backing_fmt > -Image format of the base image > -@item encryption > -This option is deprecated and equivalent to @code{encrypt.format=aes} > - > -@item encrypt.format > - > -If this is set to @code{luks}, it requests that the qcow2 payload (not > -qcow2 header) be encrypted using the LUKS format. The passphrase to > -use to unlock the LUKS key slot is given by the @code{encrypt.key-secret} > -parameter. LUKS encryption parameters can be tuned with the other > -@code{encrypt.*} parameters. > - > -If this is set to @code{aes}, the image is encrypted with 128-bit AES-CBC. > -The encryption key is given by the @code{encrypt.key-secret} parameter. > -This encryption format is considered to be flawed by modern cryptography > -standards, suffering from a number of design problems: > - > -@itemize @minus > -@item The AES-CBC cipher is used with predictable initialization vectors > based > -on the sector number. This makes it vulnerable to chosen plaintext attacks > -which can reveal the existence of encrypted data. > -@item The user passphrase is directly used as the encryption key. A poorly > -chosen or short passphrase will compromise the security of the encryption. > -@item In the event of the passphrase being compromised there is no way to > -change the passphrase to protect data in any qcow images. The files must > -be cloned, using a different encryption passphrase in the new file. The > -original file must then be securely erased using a program like shred, > -though even this is ineffective with many modern storage technologies. > -@end itemize > - > -The use of this is no longer supported in system emulators. Support only > -remains in the command line utilities, for the purposes of data liberation > -and interoperability with old versions of QEMU. The @code{luks} format > -should be used instead. > - > -@item encrypt.key-secret > - > -Provides the ID of a @code{secret} object that contains the passphrase > -(@code{encrypt.format=luks}) or encryption key (@code{encrypt.format=aes}). > - > -@item encrypt.cipher-alg > - > -Name of the cipher algorithm and key length. Currently defaults > -to @code{aes-256}. Only used when @code{encrypt.format=luks}. > - > -@item encrypt.cipher-mode > - > -Name of the encryption mode to use. Currently defaults to @code{xts}. > -Only used when @code{encrypt.format=luks}. > - > -@item encrypt.ivgen-alg > - > -Name of the initialization vector generator algorithm. Currently defaults > -to @code{plain64}. Only used when @code{encrypt.format=luks}. > - > -@item encrypt.ivgen-hash-alg > - > -Name of the hash algorithm to use with the initialization vector generator > -(if required). Defaults to @code{sha256}. Only used when > @code{encrypt.format=luks}. > - > -@item encrypt.hash-alg > - > -Name of the hash algorithm to use for PBKDF algorithm > -Defaults to @code{sha256}. Only used when @code{encrypt.format=luks}. > - > -@item encrypt.iter-time > - > -Amount of time, in milliseconds, to use for PBKDF algorithm per key slot. > -Defaults to @code{2000}. Only used when @code{encrypt.format=luks}. > - > -@item cluster_size > -Changes the qcow2 cluster size (must be between 512 and 2M). Smaller cluster > -sizes can improve the image file size whereas larger cluster sizes generally > -provide better performance. > - > -@item preallocation > -Preallocation mode (allowed values: @code{off}, @code{metadata}, > @code{falloc}, > -@code{full}). An image with preallocated metadata is initially larger but can > -improve performance when the image needs to grow. @code{falloc} and > @code{full} > -preallocations are like the same options of @code{raw} format, but sets up > -metadata also. > - > -@item lazy_refcounts > -If this option is set to @code{on}, reference count updates are postponed > with > -the goal of avoiding metadata I/O and improving performance. This is > -particularly interesting with @option{cache=writethrough} which doesn't batch > -metadata updates. The tradeoff is that after a host crash, the reference > count > -tables must be rebuilt, i.e. on the next open an (automatic) @code{qemu-img > -check -r all} is required, which may take some time. > - > -This option can only be enabled if @code{compat=1.1} is specified. > - > -@item nocow > -If this option is set to @code{on}, it will turn off COW of the file. It's > only > -valid on btrfs, no effect on other file systems. > - > -Btrfs has low performance when hosting a VM image file, even more when the > guest > -on the VM also using btrfs as file system. Turning off COW is a way to > mitigate > -this bad performance. Generally there are two ways to turn off COW on btrfs: > -a) Disable it by mounting with nodatacow, then all newly created files will > be > -NOCOW. b) For an empty file, add the NOCOW file attribute. That's what this > option > -does. > - > -Note: this option is only valid to new or empty files. If there is an > existing > -file which is COW and has data blocks already, it couldn't be changed to > NOCOW > -by setting @code{nocow=on}. One can issue @code{lsattr filename} to check if > -the NOCOW flag is set or not (Capital 'C' is NOCOW flag). > - > -@end table > - > -@item qed > -Old QEMU image format with support for backing files and compact image files > -(when your filesystem or transport medium does not support holes). > - > -When converting QED images to qcow2, you might want to consider using the > -@code{lazy_refcounts=on} option to get a more QED-like behaviour. > - > -Supported options: > -@table @code > -@item backing_file > -File name of a base image (see @option{create} subcommand). > -@item backing_fmt > -Image file format of backing file (optional). Useful if the format cannot be > -autodetected because it has no header, like some vhd/vpc files. > -@item cluster_size > -Changes the cluster size (must be power-of-2 between 4K and 64K). Smaller > -cluster sizes can improve the image file size whereas larger cluster sizes > -generally provide better performance. > -@item table_size > -Changes the number of clusters per L1/L2 table (must be power-of-2 between 1 > -and 16). There is normally no need to change this value but this option can > be > -used for performance benchmarking. > -@end table > - > -@item qcow > -Old QEMU image format with support for backing files, compact image files, > -encryption and compression. > - > -Supported options: > -@table @code > -@item backing_file > -File name of a base image (see @option{create} subcommand) > -@item encryption > -This option is deprecated and equivalent to @code{encrypt.format=aes} > - > -@item encrypt.format > -If this is set to @code{aes}, the image is encrypted with 128-bit AES-CBC. > -The encryption key is given by the @code{encrypt.key-secret} parameter. > -This encryption format is considered to be flawed by modern cryptography > -standards, suffering from a number of design problems enumerated previously > -against the @code{qcow2} image format. > - > -The use of this is no longer supported in system emulators. Support only > -remains in the command line utilities, for the purposes of data liberation > -and interoperability with old versions of QEMU. > - > -Users requiring native encryption should use the @code{qcow2} format > -instead with @code{encrypt.format=luks}. > - > -@item encrypt.key-secret > - > -Provides the ID of a @code{secret} object that contains the encryption > -key (@code{encrypt.format=aes}). > - > -@end table > - > -@item luks > - > -LUKS v1 encryption format, compatible with Linux dm-crypt/cryptsetup > - > -Supported options: > -@table @code > - > -@item key-secret > - > -Provides the ID of a @code{secret} object that contains the passphrase. > - > -@item cipher-alg > - > -Name of the cipher algorithm and key length. Currently defaults > -to @code{aes-256}. > - > -@item cipher-mode > - > -Name of the encryption mode to use. Currently defaults to @code{xts}. > - > -@item ivgen-alg > - > -Name of the initialization vector generator algorithm. Currently defaults > -to @code{plain64}. > - > -@item ivgen-hash-alg > - > -Name of the hash algorithm to use with the initialization vector generator > -(if required). Defaults to @code{sha256}. > - > -@item hash-alg > - > -Name of the hash algorithm to use for PBKDF algorithm > -Defaults to @code{sha256}. > - > -@item iter-time > - > -Amount of time, in milliseconds, to use for PBKDF algorithm per key slot. > -Defaults to @code{2000}. > - > -@end table > - > -@item vdi > -VirtualBox 1.1 compatible image format. > -Supported options: > -@table @code > -@item static > -If this option is set to @code{on}, the image is created with metadata > -preallocation. > -@end table > - > -@item vmdk > -VMware 3 and 4 compatible image format. > - > -Supported options: > -@table @code > -@item backing_file > -File name of a base image (see @option{create} subcommand). > -@item compat6 > -Create a VMDK version 6 image (instead of version 4) > -@item hwversion > -Specify vmdk virtual hardware version. Compat6 flag cannot be enabled > -if hwversion is specified. > -@item subformat > -Specifies which VMDK subformat to use. Valid options are > -@code{monolithicSparse} (default), > -@code{monolithicFlat}, > -@code{twoGbMaxExtentSparse}, > -@code{twoGbMaxExtentFlat} and > -@code{streamOptimized}. > -@end table > - > -@item vpc > -VirtualPC compatible image format (VHD). > -Supported options: > -@table @code > -@item subformat > -Specifies which VHD subformat to use. Valid options are > -@code{dynamic} (default) and @code{fixed}. > -@end table > - > -@item VHDX > -Hyper-V compatible image format (VHDX). > -Supported options: > -@table @code > -@item subformat > -Specifies which VHDX subformat to use. Valid options are > -@code{dynamic} (default) and @code{fixed}. > -@item block_state_zero > -Force use of payload blocks of type 'ZERO'. Can be set to @code{on} > (default) > -or @code{off}. When set to @code{off}, new blocks will be created as > -@code{PAYLOAD_BLOCK_NOT_PRESENT}, which means parsers are free to return > -arbitrary data for those blocks. Do not set to @code{off} when using > -@code{qemu-img convert} with @code{subformat=dynamic}. > -@item block_size > -Block size; min 1 MB, max 256 MB. 0 means auto-calculate based on image > size. > -@item log_size > -Log size; min 1 MB. > -@end table > -@end table > - > -@subsubsection Read-only formats > -More disk image file formats are supported in a read-only mode. > -@table @option > -@item bochs > -Bochs images of @code{growing} type. > -@item cloop > -Linux Compressed Loop image, useful only to reuse directly compressed > -CD-ROM images present for example in the Knoppix CD-ROMs. > -@item dmg > -Apple disk image. > -@item parallels > -Parallels disk image format. > -@end table > - > - > -@node host_drives > -@subsection Using host drives > - > -In addition to disk image files, QEMU can directly access host > -devices. We describe here the usage for QEMU version >= 0.8.3. > - > -@subsubsection Linux > - > -On Linux, you can directly use the host device filename instead of a > -disk image filename provided you have enough privileges to access > -it. For example, use @file{/dev/cdrom} to access to the CDROM. > - > -@table @code > -@item CD > -You can specify a CDROM device even if no CDROM is loaded. QEMU has > -specific code to detect CDROM insertion or removal. CDROM ejection by > -the guest OS is supported. Currently only data CDs are supported. > -@item Floppy > -You can specify a floppy device even if no floppy is loaded. Floppy > -removal is currently not detected accurately (if you change floppy > -without doing floppy access while the floppy is not loaded, the guest > -OS will think that the same floppy is loaded). > -Use of the host's floppy device is deprecated, and support for it will > -be removed in a future release. > -@item Hard disks > -Hard disks can be used. Normally you must specify the whole disk > -(@file{/dev/hdb} instead of @file{/dev/hdb1}) so that the guest OS can > -see it as a partitioned disk. WARNING: unless you know what you do, it > -is better to only make READ-ONLY accesses to the hard disk otherwise > -you may corrupt your host data (use the @option{-snapshot} command > -line option or modify the device permissions accordingly). > -@end table > - > -@subsubsection Windows > - > -@table @code > -@item CD > -The preferred syntax is the drive letter (e.g. @file{d:}). The > -alternate syntax @file{\\.\d:} is supported. @file{/dev/cdrom} is > -supported as an alias to the first CDROM drive. > - > -Currently there is no specific code to handle removable media, so it > -is better to use the @code{change} or @code{eject} monitor commands to > -change or eject media. > -@item Hard disks > -Hard disks can be used with the syntax: @file{\\.\PhysicalDrive@var{N}} > -where @var{N} is the drive number (0 is the first hard disk). > - > -WARNING: unless you know what you do, it is better to only make > -READ-ONLY accesses to the hard disk otherwise you may corrupt your > -host data (use the @option{-snapshot} command line so that the > -modifications are written in a temporary file). > -@end table > - > - > -@subsubsection Mac OS X > - > -@file{/dev/cdrom} is an alias to the first CDROM. > - > -Currently there is no specific code to handle removable media, so it > -is better to use the @code{change} or @code{eject} monitor commands to > -change or eject media. > - > -@node disk_images_fat_images > -@subsection Virtual FAT disk images > - > -QEMU can automatically create a virtual FAT disk image from a > -directory tree. In order to use it, just type: > - > -@example > -@value{qemu_system} linux.img -hdb fat:/my_directory > -@end example > - > -Then you access access to all the files in the @file{/my_directory} > -directory without having to copy them in a disk image or to export > -them via SAMBA or NFS. The default access is @emph{read-only}. > - > -Floppies can be emulated with the @code{:floppy:} option: > - > -@example > -@value{qemu_system} linux.img -fda fat:floppy:/my_directory > -@end example > - > -A read/write support is available for testing (beta stage) with the > -@code{:rw:} option: > - > -@example > -@value{qemu_system} linux.img -fda fat:floppy:rw:/my_directory > -@end example > - > -What you should @emph{never} do: > -@itemize > -@item use non-ASCII filenames ; > -@item use "-snapshot" together with ":rw:" ; > -@item expect it to work when loadvm'ing ; > -@item write to the FAT directory on the host system while accessing it with > the guest system. > -@end itemize > - > -@node disk_images_nbd > -@subsection NBD access > - > -QEMU can access directly to block device exported using the Network Block > Device > -protocol. > - > -@example > -@value{qemu_system} linux.img -hdb nbd://my_nbd_server.mydomain.org:1024/ > -@end example > - > -If the NBD server is located on the same host, you can use an unix socket > instead > -of an inet socket: > - > -@example > -@value{qemu_system} linux.img -hdb nbd+unix://?socket=/tmp/my_socket > -@end example > - > -In this case, the block device must be exported using qemu-nbd: > - > -@example > -qemu-nbd --socket=/tmp/my_socket my_disk.qcow2 > -@end example > - > -The use of qemu-nbd allows sharing of a disk between several guests: > -@example > -qemu-nbd --socket=/tmp/my_socket --share=2 my_disk.qcow2 > -@end example > - > -@noindent > -and then you can use it with two guests: > -@example > -@value{qemu_system} linux1.img -hdb nbd+unix://?socket=/tmp/my_socket > -@value{qemu_system} linux2.img -hdb nbd+unix://?socket=/tmp/my_socket > -@end example > - > -If the nbd-server uses named exports (supported since NBD 2.9.18, or with > QEMU's > -own embedded NBD server), you must specify an export name in the URI: > -@example > -@value{qemu_system} -cdrom nbd://localhost/debian-500-ppc-netinst > -@value{qemu_system} -cdrom nbd://localhost/openSUSE-11.1-ppc-netinst > -@end example > - > -The URI syntax for NBD is supported since QEMU 1.3. An alternative syntax is > -also available. Here are some example of the older syntax: > -@example > -@value{qemu_system} linux.img -hdb nbd:my_nbd_server.mydomain.org:1024 > -@value{qemu_system} linux2.img -hdb nbd:unix:/tmp/my_socket > -@value{qemu_system} -cdrom > nbd:localhost:10809:exportname=debian-500-ppc-netinst > -@end example > - > -@node disk_images_sheepdog > -@subsection Sheepdog disk images > - > -Sheepdog is a distributed storage system for QEMU. It provides highly > -available block level storage volumes that can be attached to > -QEMU-based virtual machines. > - > -You can create a Sheepdog disk image with the command: > -@example > -qemu-img create sheepdog:///@var{image} @var{size} > -@end example > -where @var{image} is the Sheepdog image name and @var{size} is its > -size. > - > -To import the existing @var{filename} to Sheepdog, you can use a > -convert command. > -@example > -qemu-img convert @var{filename} sheepdog:///@var{image} > -@end example > - > -You can boot from the Sheepdog disk image with the command: > -@example > -@value{qemu_system} sheepdog:///@var{image} > -@end example > - > -You can also create a snapshot of the Sheepdog image like qcow2. > -@example > -qemu-img snapshot -c @var{tag} sheepdog:///@var{image} > -@end example > -where @var{tag} is a tag name of the newly created snapshot. > - > -To boot from the Sheepdog snapshot, specify the tag name of the > -snapshot. > -@example > -@value{qemu_system} sheepdog:///@var{image}#@var{tag} > -@end example > - > -You can create a cloned image from the existing snapshot. > -@example > -qemu-img create -b sheepdog:///@var{base}#@var{tag} sheepdog:///@var{image} > -@end example > -where @var{base} is an image name of the source snapshot and @var{tag} > -is its tag name. > - > -You can use an unix socket instead of an inet socket: > - > -@example > -@value{qemu_system} sheepdog+unix:///@var{image}?socket=@var{path} > -@end example > - > -If the Sheepdog daemon doesn't run on the local host, you need to > -specify one of the Sheepdog servers to connect to. > -@example > -qemu-img create sheepdog://@var{hostname}:@var{port}/@var{image} @var{size} > -@value{qemu_system} sheepdog://@var{hostname}:@var{port}/@var{image} > -@end example > - > -@node disk_images_iscsi > -@subsection iSCSI LUNs > - > -iSCSI is a popular protocol used to access SCSI devices across a computer > -network. > - > -There are two different ways iSCSI devices can be used by QEMU. > - > -The first method is to mount the iSCSI LUN on the host, and make it appear as > -any other ordinary SCSI device on the host and then to access this device as > a > -/dev/sd device from QEMU. How to do this differs between host OSes. > - > -The second method involves using the iSCSI initiator that is built into > -QEMU. This provides a mechanism that works the same way regardless of which > -host OS you are running QEMU on. This section will describe this second > method > -of using iSCSI together with QEMU. > - > -In QEMU, iSCSI devices are described using special iSCSI URLs > - > -@example > -URL syntax: > -iscsi://[<username>[%<password>]@@]<host>[:<port>]/<target-iqn-name>/<lun> > -@end example > - > -Username and password are optional and only used if your target is set up > -using CHAP authentication for access control. > -Alternatively the username and password can also be set via environment > -variables to have these not show up in the process list > - > -@example > -export LIBISCSI_CHAP_USERNAME=<username> > -export LIBISCSI_CHAP_PASSWORD=<password> > -iscsi://<host>/<target-iqn-name>/<lun> > -@end example > - > -Various session related parameters can be set via special options, either > -in a configuration file provided via '-readconfig' or directly on the > -command line. > - > -If the initiator-name is not specified qemu will use a default name > -of 'iqn.2008-11.org.linux-kvm[:<uuid>'] where <uuid> is the UUID of the > -virtual machine. If the UUID is not specified qemu will use > -'iqn.2008-11.org.linux-kvm[:<name>'] where <name> is the name of the > -virtual machine. > - > -@example > -Setting a specific initiator name to use when logging in to the target > --iscsi initiator-name=iqn.qemu.test:my-initiator > -@end example > - > -@example > -Controlling which type of header digest to negotiate with the target > --iscsi header-digest=CRC32C|CRC32C-NONE|NONE-CRC32C|NONE > -@end example > - > -These can also be set via a configuration file > -@example > -[iscsi] > - user = "CHAP username" > - password = "CHAP password" > - initiator-name = "iqn.qemu.test:my-initiator" > - # header digest is one of CRC32C|CRC32C-NONE|NONE-CRC32C|NONE > - header-digest = "CRC32C" > -@end example > - > - > -Setting the target name allows different options for different targets > -@example > -[iscsi "iqn.target.name"] > - user = "CHAP username" > - password = "CHAP password" > - initiator-name = "iqn.qemu.test:my-initiator" > - # header digest is one of CRC32C|CRC32C-NONE|NONE-CRC32C|NONE > - header-digest = "CRC32C" > -@end example > - > - > -Howto use a configuration file to set iSCSI configuration options: > -@example > -cat >iscsi.conf <<EOF > -[iscsi] > - user = "me" > - password = "my password" > - initiator-name = "iqn.qemu.test:my-initiator" > - header-digest = "CRC32C" > -EOF > - > -@value{qemu_system} -drive file=iscsi://127.0.0.1/iqn.qemu.test/1 \ > - -readconfig iscsi.conf > -@end example > - > - > -How to set up a simple iSCSI target on loopback and access it via QEMU: > -@example > -This example shows how to set up an iSCSI target with one CDROM and one DISK > -using the Linux STGT software target. This target is available on Red Hat > based > -systems as the package 'scsi-target-utils'. > - > -tgtd --iscsi portal=127.0.0.1:3260 > -tgtadm --lld iscsi --op new --mode target --tid 1 -T iqn.qemu.test > -tgtadm --lld iscsi --mode logicalunit --op new --tid 1 --lun 1 \ > - -b /IMAGES/disk.img --device-type=disk > -tgtadm --lld iscsi --mode logicalunit --op new --tid 1 --lun 2 \ > - -b /IMAGES/cd.iso --device-type=cd > -tgtadm --lld iscsi --op bind --mode target --tid 1 -I ALL > - > -@value{qemu_system} -iscsi initiator-name=iqn.qemu.test:my-initiator \ > - -boot d -drive file=iscsi://127.0.0.1/iqn.qemu.test/1 \ > - -cdrom iscsi://127.0.0.1/iqn.qemu.test/2 > -@end example > - > -@node disk_images_gluster > -@subsection GlusterFS disk images > - > -GlusterFS is a user space distributed file system. > - > -You can boot from the GlusterFS disk image with the command: > -@example > -URI: > -@value{qemu_system} -drive > file=gluster[+@var{type}]://[@var{host}[:@var{port}]]/@var{volume}/@var{path} > - > [?socket=...][,file.debug=9][,file.logfile=...] > - > -JSON: > -@value{qemu_system} 'json:@{"driver":"qcow2", > - "file":@{"driver":"gluster", > - > "volume":"testvol","path":"a.img","debug":9,"logfile":"...", > - > "server":[@{"type":"tcp","host":"...","port":"..."@}, > - > @{"type":"unix","socket":"..."@}]@}@}' > -@end example > - > -@var{gluster} is the protocol. > - > -@var{type} specifies the transport type used to connect to gluster > -management daemon (glusterd). Valid transport types are > -tcp and unix. In the URI form, if a transport type isn't specified, > -then tcp type is assumed. > - > -@var{host} specifies the server where the volume file specification for > -the given volume resides. This can be either a hostname or an ipv4 address. > -If transport type is unix, then @var{host} field should not be specified. > -Instead @var{socket} field needs to be populated with the path to unix domain > -socket. > - > -@var{port} is the port number on which glusterd is listening. This is > optional > -and if not specified, it defaults to port 24007. If the transport type is > unix, > -then @var{port} should not be specified. > - > -@var{volume} is the name of the gluster volume which contains the disk image. > - > -@var{path} is the path to the actual disk image that resides on gluster > volume. > - > -@var{debug} is the logging level of the gluster protocol driver. Debug levels > -are 0-9, with 9 being the most verbose, and 0 representing no debugging > output. > -The default level is 4. The current logging levels defined in the gluster > source > -are 0 - None, 1 - Emergency, 2 - Alert, 3 - Critical, 4 - Error, 5 - Warning, > -6 - Notice, 7 - Info, 8 - Debug, 9 - Trace > - > -@var{logfile} is a commandline option to mention log file path which helps in > -logging to the specified file and also help in persisting the gfapi logs. The > -default is stderr. > - > - > - > - > -You can create a GlusterFS disk image with the command: > -@example > -qemu-img create gluster://@var{host}/@var{volume}/@var{path} @var{size} > -@end example > - > -Examples > -@example > -@value{qemu_system} -drive file=gluster://1.2.3.4/testvol/a.img > -@value{qemu_system} -drive file=gluster+tcp://1.2.3.4/testvol/a.img > -@value{qemu_system} -drive file=gluster+tcp://1.2.3.4:24007/testvol/dir/a.img > -@value{qemu_system} -drive > file=gluster+tcp://[1:2:3:4:5:6:7:8]/testvol/dir/a.img > -@value{qemu_system} -drive > file=gluster+tcp://[1:2:3:4:5:6:7:8]:24007/testvol/dir/a.img > -@value{qemu_system} -drive > file=gluster+tcp://server.domain.com:24007/testvol/dir/a.img > -@value{qemu_system} -drive > file=gluster+unix:///testvol/dir/a.img?socket=/tmp/glusterd.socket > -@value{qemu_system} -drive file=gluster+rdma://1.2.3.4:24007/testvol/a.img > -@value{qemu_system} -drive > file=gluster://1.2.3.4/testvol/a.img,file.debug=9,file.logfile=/var/log/qemu-gluster.log > -@value{qemu_system} 'json:@{"driver":"qcow2", > - "file":@{"driver":"gluster", > - "volume":"testvol","path":"a.img", > - > "debug":9,"logfile":"/var/log/qemu-gluster.log", > - > "server":[@{"type":"tcp","host":"1.2.3.4","port":24007@}, > - > @{"type":"unix","socket":"/var/run/glusterd.socket"@}]@}@}' > -@value{qemu_system} -drive > driver=qcow2,file.driver=gluster,file.volume=testvol,file.path=/path/a.img, > - > file.debug=9,file.logfile=/var/log/qemu-gluster.log, > - > file.server.0.type=tcp,file.server.0.host=1.2.3.4,file.server.0.port=24007, > - > file.server.1.type=unix,file.server.1.socket=/var/run/glusterd.socket > -@end example > - > -@node disk_images_ssh > -@subsection Secure Shell (ssh) disk images > - > -You can access disk images located on a remote ssh server > -by using the ssh protocol: > - > -@example > -@value{qemu_system} -drive > file=ssh://[@var{user}@@]@var{server}[:@var{port}]/@var{path}[?host_key_check=@var{host_key_check}] > -@end example > - > -Alternative syntax using properties: > - > -@example > -@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}] > -@end example > - > -@var{ssh} is the protocol. > - > -@var{user} is the remote user. If not specified, then the local > -username is tried. > - > -@var{server} specifies the remote ssh server. Any ssh server can be > -used, but it must implement the sftp-server protocol. Most Unix/Linux > -systems should work without requiring any extra configuration. > - > -@var{port} is the port number on which sshd is listening. By default > -the standard ssh port (22) is used. > - > -@var{path} is the path to the disk image. > - > -The optional @var{host_key_check} parameter controls how the remote > -host's key is checked. The default is @code{yes} which means to use > -the local @file{.ssh/known_hosts} file. Setting this to @code{no} > -turns off known-hosts checking. Or you can check that the host key > -matches a specific fingerprint: > -@code{host_key_check=md5:78:45:8e:14:57:4f:d5:45:83:0a:0e:f3:49:82:c9:c8} > -(@code{sha1:} can also be used as a prefix, but note that OpenSSH > -tools only use MD5 to print fingerprints). > - > -Currently authentication must be done using ssh-agent. Other > -authentication methods may be supported in future. > - > -Note: Many ssh servers do not support an @code{fsync}-style operation. > -The ssh driver cannot guarantee that disk flush requests are > -obeyed, and this causes a risk of disk corruption if the remote > -server or network goes down during writes. The driver will > -print a warning when @code{fsync} is not supported: > - > -warning: ssh server @code{ssh.example.com:22} does not support fsync > - > -With sufficiently new versions of libssh and OpenSSH, @code{fsync} is > -supported. > - > -@node disk_images_nvme > -@subsection NVMe disk images > - > -NVM Express (NVMe) storage controllers can be accessed directly by a > userspace > -driver in QEMU. This bypasses the host kernel file system and block layers > -while retaining QEMU block layer functionalities, such as block jobs, I/O > -throttling, image formats, etc. Disk I/O performance is typically higher > than > -with @code{-drive file=/dev/sda} using either thread pool or linux-aio. > - > -The controller will be exclusively used by the QEMU process once started. To > be > -able to share storage between multiple VMs and other applications on the > host, > -please use the file based protocols. > - > -Before starting QEMU, bind the host NVMe controller to the host vfio-pci > -driver. For example: > - > -@example > -# modprobe vfio-pci > -# lspci -n -s 0000:06:0d.0 > -06:0d.0 0401: 1102:0002 (rev 08) > -# echo 0000:06:0d.0 > /sys/bus/pci/devices/0000:06:0d.0/driver/unbind > -# echo 1102 0002 > /sys/bus/pci/drivers/vfio-pci/new_id > - > -# @value{qemu_system} -drive > file=nvme://@var{host}:@var{bus}:@var{slot}.@var{func}/@var{namespace} > -@end example > - > -Alternative syntax using properties: > - > -@example > -@value{qemu_system} -drive > file.driver=nvme,file.device=@var{host}:@var{bus}:@var{slot}.@var{func},file.namespace=@var{namespace} > -@end example > - > -@var{host}:@var{bus}:@var{slot}.@var{func} is the NVMe controller's PCI > device > -address on the host. > - > -@var{namespace} is the NVMe namespace number, starting from 1. > - > -@node disk_image_locking > -@subsection Disk image file locking > - > -By default, QEMU tries to protect image files from unexpected concurrent > -access, as long as it's supported by the block protocol driver and host > -operating system. If multiple QEMU processes (including QEMU emulators and > -utilities) try to open the same image with conflicting accessing modes, all > but > -the first one will get an error. > - > -This feature is currently supported by the file protocol on Linux with the > Open > -File Descriptor (OFD) locking API, and can be configured to fall back to > POSIX > -locking if the POSIX host doesn't support Linux OFD locking. > - > -To explicitly enable image locking, specify "locking=on" in the file protocol > -driver options. If OFD locking is not possible, a warning will be printed and > -the POSIX locking API will be used. In this case there is a risk that the > lock > -will get silently lost when doing hot plugging and block jobs, due to the > -shortcomings of the POSIX locking API. > - > -QEMU transparently handles lock handover during shared storage migration. > For > -shared virtual disk images between multiple VMs, the "share-rw" device option > -should be used. > - > -By default, the guest has exclusive write access to its disk image. If the > -guest can safely share the disk image with other writers the @code{-device > -...,share-rw=on} parameter can be used. This is only safe if the guest is > -running software, such as a cluster file system, that coordinates disk > accesses > -to avoid corruption. > - > -Note that share-rw=on only declares the guest's ability to share the disk. > -Some QEMU features, such as image file formats, require exclusive write > access > -to the disk image and this is unaffected by the share-rw=on option. > - > -Alternatively, locking can be fully disabled by "locking=off" block device > -option. In the command line, the option is usually in the form of > -"file.locking=off" as the protocol driver is normally placed as a "file" > child > -under a format driver. For example: > - > -@code{-blockdev > driver=qcow2,file.filename=/path/to/image,file.locking=off,file.driver=file} > - > -To check if image locking is active, check the output of the "lslocks" > command > -on host and see if there are locks held by the QEMU process on the image > file. > -More than one byte could be locked by the QEMU instance, each byte of which > -reflects a particular permission that is acquired or protected by the running > -block driver. > - > -@c man end > - > -@ignore > - > -@setfilename qemu-block-drivers > -@settitle QEMU block drivers reference > - > -@c man begin SEEALSO > -The HTML documentation of QEMU for more precise information and Linux > -user mode emulator invocation. > -@c man end > - > -@c man begin AUTHOR > -Fabrice Bellard and the QEMU Project developers > -@c man end > - > -@end ignore > diff --git a/docs/system/conf.py b/docs/system/conf.py > index 6435b4d3f8e..7ca115f5e03 100644 > --- a/docs/system/conf.py > +++ b/docs/system/conf.py > @@ -13,3 +13,10 @@ exec(compile(open(parent_config, "rb").read(), > parent_config, 'exec')) > # This slightly misuses the 'description', but is the best way to get > # the manual title to appear in the sidebar. > html_theme_options['description'] = u'System Emulation User''s Guide' > +# One entry per manual page. List of tuples > +# (source start file, name, description, authors, manual section). > +man_pages = [ > + ('qemu-block-drivers', 'qemu-block-drivers', > + u'QEMU block drivers reference', > + ['Fabrice Bellard and the QEMU Project developers'], 7) > +] > diff --git a/docs/system/index.rst b/docs/system/index.rst > index ea8ea5fe3dc..f66e6ea585c 100644 > --- a/docs/system/index.rst > +++ b/docs/system/index.rst > @@ -14,3 +14,4 @@ Contents: > .. toctree:: > :maxdepth: 2 > > + qemu-block-drivers > diff --git a/docs/system/qemu-block-drivers.rst > b/docs/system/qemu-block-drivers.rst > new file mode 100644 > index 00000000000..388adbefbf4 > --- /dev/null > +++ b/docs/system/qemu-block-drivers.rst > @@ -0,0 +1,985 @@ > +QEMU block drivers reference > +============================ > + > +.. |qemu_system| replace:: qemu-system-x86_64 > + > +.. > + We put the 'Synopsis' and 'See also' sections into the manpage, but not > + the HTML. This makes the HTML docs read better and means the ToC in > + the index has a more useful set of entries. Ideally, the section > + headings 'Disk image file formats' would be top-level headings for > + the HTML, but sub-headings of the conventional manpage 'Description' > + header for the manpage. Unfortunately, due to deficiencies in > + the Sphinx 'only' directive, this isn't possible: they must be headers > + at the same level as 'Synopsis' and 'See also', otherwise Sphinx's > + identification of which header underline style is which gets confused. > + > +.. only:: man > + > + Synopsis > + -------- > + > + QEMU block driver reference manual > + > +Disk image file formats > +----------------------- > + > +QEMU supports many image file formats that can be used with VMs as well as > with > +any of the tools (like ``qemu-img``). This includes the preferred formats > +raw and qcow2 as well as formats that are supported for compatibility with > +older QEMU versions or other hypervisors. > + > +Depending on the image format, different options can be passed to > +``qemu-img create`` and ``qemu-img convert`` using the ``-o`` option. > +This section describes each format and the options that are supported for it. > + > +.. program:: image-formats > +.. option:: raw > + > + Raw disk image format. This format has the advantage of > + being simple and easily exportable to all other emulators. If your > + file system supports *holes* (for example in ext2 or ext3 on > + Linux or NTFS on Windows), then only the written sectors will reserve > + space. Use ``qemu-img info`` to know the real size used by the > + image or ``ls -ls`` on Unix/Linux. > + > + Supported options: > + > + .. program:: raw > + .. option:: preallocation > + > + Preallocation mode (allowed values: ``off``, ``falloc``, > + ``full``). ``falloc`` mode preallocates space for image by > + calling ``posix_fallocate()``. ``full`` mode preallocates space > + for image by writing data to underlying storage. This data may or > + may not be zero, depending on the storage location. > + > +.. program:: image-formats > +.. option:: qcow2 > + > + QEMU image format, the most versatile format. Use it to have smaller > + images (useful if your filesystem does not supports holes, for example > + on Windows), zlib based compression and support of multiple VM > + snapshots. > + > + Supported options: > + > + .. program:: qcow2 > + .. option:: compat > + > + Determines the qcow2 version to use. ``compat=0.10`` uses the > + traditional image format that can be read by any QEMU since 0.10. > + ``compat=1.1`` enables image format extensions that only QEMU 1.1 and > + newer understand (this is the default). Amongst others, this includes > + zero clusters, which allow efficient copy-on-read for sparse images. > + > + .. option:: backing_file > + > + File name of a base image (see ``create`` subcommand) > + > + .. option:: backing_fmt > + > + Image format of the base image > + > + .. option:: encryption > + > + This option is deprecated and equivalent to ``encrypt.format=aes`` > + > + .. option:: encrypt.format > + > + If this is set to ``luks``, it requests that the qcow2 payload (not > + qcow2 header) be encrypted using the LUKS format. The passphrase to > + use to unlock the LUKS key slot is given by the ``encrypt.key-secret`` > + parameter. LUKS encryption parameters can be tuned with the other > + ``encrypt.*`` parameters. > + > + If this is set to ``aes``, the image is encrypted with 128-bit AES-CBC. > + The encryption key is given by the ``encrypt.key-secret`` parameter. > + This encryption format is considered to be flawed by modern cryptography > + standards, suffering from a number of design problems: > + > + - The AES-CBC cipher is used with predictable initialization vectors > based > + on the sector number. This makes it vulnerable to chosen plaintext > attacks > + which can reveal the existence of encrypted data. > + - The user passphrase is directly used as the encryption key. A poorly > + chosen or short passphrase will compromise the security of the > encryption. > + - In the event of the passphrase being compromised there is no way to > + change the passphrase to protect data in any qcow images. The files > must > + be cloned, using a different encryption passphrase in the new file. The > + original file must then be securely erased using a program like shred, > + though even this is ineffective with many modern storage technologies. > + > + The use of this is no longer supported in system emulators. Support only > + remains in the command line utilities, for the purposes of data > liberation > + and interoperability with old versions of QEMU. The ``luks`` format > + should be used instead. > + > + .. option:: encrypt.key-secret > + > + Provides the ID of a ``secret`` object that contains the passphrase > + (``encrypt.format=luks``) or encryption key (``encrypt.format=aes``). > + > + .. option:: encrypt.cipher-alg > + > + Name of the cipher algorithm and key length. Currently defaults > + to ``aes-256``. Only used when ``encrypt.format=luks``. > + > + .. option:: encrypt.cipher-mode > + > + Name of the encryption mode to use. Currently defaults to ``xts``. > + Only used when ``encrypt.format=luks``. > + > + .. option:: encrypt.ivgen-alg > + > + Name of the initialization vector generator algorithm. Currently defaults > + to ``plain64``. Only used when ``encrypt.format=luks``. > + > + .. option:: encrypt.ivgen-hash-alg > + > + Name of the hash algorithm to use with the initialization vector > generator > + (if required). Defaults to ``sha256``. Only used when > ``encrypt.format=luks``. > + > + .. option:: encrypt.hash-alg > + > + Name of the hash algorithm to use for PBKDF algorithm > + Defaults to ``sha256``. Only used when ``encrypt.format=luks``. > + > + .. option:: encrypt.iter-time > + > + Amount of time, in milliseconds, to use for PBKDF algorithm per key slot. > + Defaults to ``2000``. Only used when ``encrypt.format=luks``. > + > + .. option:: cluster_size > + > + Changes the qcow2 cluster size (must be between 512 and 2M). Smaller > cluster > + sizes can improve the image file size whereas larger cluster sizes > generally > + provide better performance. > + > + .. option:: preallocation > + > + Preallocation mode (allowed values: ``off``, ``metadata``, ``falloc``, > + ``full``). An image with preallocated metadata is initially larger but > can > + improve performance when the image needs to grow. ``falloc`` and ``full`` > + preallocations are like the same options of ``raw`` format, but sets up > + metadata also. > + > + .. option:: lazy_refcounts > + > + If this option is set to ``on``, reference count updates are postponed > with > + the goal of avoiding metadata I/O and improving performance. This is > + particularly interesting with :option:`cache=writethrough` which doesn't > batch > + metadata updates. The tradeoff is that after a host crash, the reference > count > + tables must be rebuilt, i.e. on the next open an (automatic) ``qemu-img > + check -r all`` is required, which may take some time. > + > + This option can only be enabled if ``compat=1.1`` is specified. > + > + .. option:: nocow > + > + If this option is set to ``on``, it will turn off COW of the file. It's > only > + valid on btrfs, no effect on other file systems. > + > + Btrfs has low performance when hosting a VM image file, even more > + when the guest on the VM also using btrfs as file system. Turning off > + COW is a way to mitigate this bad performance. Generally there are two > + ways to turn off COW on btrfs: > + > + - Disable it by mounting with nodatacow, then all newly created files > + will be NOCOW. > + - For an empty file, add the NOCOW file attribute. That's what this > + option does. > + > + Note: this option is only valid to new or empty files. If there is > + an existing file which is COW and has data blocks already, it couldn't > + be changed to NOCOW by setting ``nocow=on``. One can issue ``lsattr > + filename`` to check if the NOCOW flag is set or not (Capital 'C' is > + NOCOW flag). > + > +.. program:: image-formats > +.. option:: qed > + > + Old QEMU image format with support for backing files and compact image > files > + (when your filesystem or transport medium does not support holes). > + > + When converting QED images to qcow2, you might want to consider using the > + ``lazy_refcounts=on`` option to get a more QED-like behaviour. > + > + Supported options: > + > + .. program:: qed > + .. option:: backing_file > + > + File name of a base image (see ``create`` subcommand). > + > + .. option:: backing_fmt > + > + Image file format of backing file (optional). Useful if the format > cannot be > + autodetected because it has no header, like some vhd/vpc files. > + > + .. option:: cluster_size > + > + Changes the cluster size (must be power-of-2 between 4K and 64K). > Smaller > + cluster sizes can improve the image file size whereas larger cluster > sizes > + generally provide better performance. > + > + .. option:: table_size > + > + Changes the number of clusters per L1/L2 table (must be > + power-of-2 between 1 and 16). There is normally no need to > + change this value but this option can between used for > + performance benchmarking. > + > +.. program:: image-formats > +.. option:: qcow > + > + Old QEMU image format with support for backing files, compact image files, > + encryption and compression. > + > + Supported options: > + > + .. program:: qcow > + .. option:: backing_file > + > + File name of a base image (see ``create`` subcommand) > + > + .. option:: encryption > + > + This option is deprecated and equivalent to ``encrypt.format=aes`` > + > + .. option:: encrypt.format > + > + If this is set to ``aes``, the image is encrypted with 128-bit AES-CBC. > + The encryption key is given by the ``encrypt.key-secret`` parameter. > + This encryption format is considered to be flawed by modern cryptography > + standards, suffering from a number of design problems enumerated > previously > + against the ``qcow2`` image format. > + > + The use of this is no longer supported in system emulators. Support only > + remains in the command line utilities, for the purposes of data > liberation > + and interoperability with old versions of QEMU. > + > + Users requiring native encryption should use the ``qcow2`` format > + instead with ``encrypt.format=luks``. > + > + .. option:: encrypt.key-secret > + > + Provides the ID of a ``secret`` object that contains the encryption > + key (``encrypt.format=aes``). > + > +.. program:: image-formats > +.. option:: luks > + > + LUKS v1 encryption format, compatible with Linux dm-crypt/cryptsetup > + > + Supported options: > + > + .. program:: luks > + .. option:: key-secret > + > + Provides the ID of a ``secret`` object that contains the passphrase. > + > + .. option:: cipher-alg > + > + Name of the cipher algorithm and key length. Currently defaults > + to ``aes-256``. > + > + .. option:: cipher-mode > + > + Name of the encryption mode to use. Currently defaults to ``xts``. > + > + .. option:: ivgen-alg > + > + Name of the initialization vector generator algorithm. Currently defaults > + to ``plain64``. > + > + .. option:: ivgen-hash-alg > + > + Name of the hash algorithm to use with the initialization vector > generator > + (if required). Defaults to ``sha256``. > + > + .. option:: hash-alg > + > + Name of the hash algorithm to use for PBKDF algorithm > + Defaults to ``sha256``. > + > + .. option:: iter-time > + > + Amount of time, in milliseconds, to use for PBKDF algorithm per key slot. > + Defaults to ``2000``. > + > +.. program:: image-formats > +.. option:: vdi > + > + VirtualBox 1.1 compatible image format. > + > + Supported options: > + > + .. program:: vdi > + .. option:: static > + > + If this option is set to ``on``, the image is created with metadata > + preallocation. > + > +.. program:: image-formats > +.. option:: vmdk > + > + VMware 3 and 4 compatible image format. > + > + Supported options: > + > + .. program: vmdk > + .. option:: backing_file > + > + File name of a base image (see ``create`` subcommand). > + > + .. option:: compat6 > + > + Create a VMDK version 6 image (instead of version 4) > + > + .. option:: hwversion > + > + Specify vmdk virtual hardware version. Compat6 flag cannot be enabled > + if hwversion is specified. > + > + .. option:: subformat > + > + Specifies which VMDK subformat to use. Valid options are > + ``monolithicSparse`` (default), > + ``monolithicFlat``, > + ``twoGbMaxExtentSparse``, > + ``twoGbMaxExtentFlat`` and > + ``streamOptimized``. > + > +.. program:: image-formats > +.. option:: vpc > + > + VirtualPC compatible image format (VHD). > + > + Supported options: > + > + .. program:: vpc > + .. option:: subformat > + > + Specifies which VHD subformat to use. Valid options are > + ``dynamic`` (default) and ``fixed``. > + > +.. program:: image-formats > +.. option:: VHDX > + > + Hyper-V compatible image format (VHDX). > + > + Supported options: > + > + .. program:: VHDX > + .. option:: subformat > + > + Specifies which VHDX subformat to use. Valid options are > + ``dynamic`` (default) and ``fixed``. > + > + .. option:: block_state_zero > + > + Force use of payload blocks of type 'ZERO'. Can be set to ``on`` > (default) > + or ``off``. When set to ``off``, new blocks will be created as > + ``PAYLOAD_BLOCK_NOT_PRESENT``, which means parsers are free to return > + arbitrary data for those blocks. Do not set to ``off`` when using > + ``qemu-img convert`` with ``subformat=dynamic``. > + > + .. option:: block_size > + > + Block size; min 1 MB, max 256 MB. 0 means auto-calculate based on > + image size. > + > + .. option:: log_size > + > + Log size; min 1 MB. > + > +Read-only formats > +----------------- > + > +More disk image file formats are supported in a read-only mode. > + > +.. program:: image-formats > +.. option:: bochs > + > + Bochs images of ``growing`` type. > + > +.. program:: image-formats > +.. option:: cloop > + > + Linux Compressed Loop image, useful only to reuse directly compressed > + CD-ROM images present for example in the Knoppix CD-ROMs. > + > +.. program:: image-formats > +.. option:: dmg > + > + Apple disk image. > + > +.. program:: image-formats > +.. option:: parallels > + > + Parallels disk image format. > + > +Using host drives > +----------------- > + > +In addition to disk image files, QEMU can directly access host > +devices. We describe here the usage for QEMU version >= 0.8.3. > + > +Linux > +''''' > + > +On Linux, you can directly use the host device filename instead of a > +disk image filename provided you have enough privileges to access > +it. For example, use ``/dev/cdrom`` to access to the CDROM. > + > +CD > + You can specify a CDROM device even if no CDROM is loaded. QEMU has > + specific code to detect CDROM insertion or removal. CDROM ejection by > + the guest OS is supported. Currently only data CDs are supported. > + > +Floppy > + You can specify a floppy device even if no floppy is loaded. Floppy > + removal is currently not detected accurately (if you change floppy > + without doing floppy access while the floppy is not loaded, the guest > + OS will think that the same floppy is loaded). > + Use of the host's floppy device is deprecated, and support for it will > + be removed in a future release. > + > +Hard disks > + Hard disks can be used. Normally you must specify the whole disk > + (``/dev/hdb`` instead of ``/dev/hdb1``) so that the guest OS can > + see it as a partitioned disk. WARNING: unless you know what you do, it > + is better to only make READ-ONLY accesses to the hard disk otherwise > + you may corrupt your host data (use the ``-snapshot`` command > + line option or modify the device permissions accordingly). > + > +Windows > +''''''' > + > +CD > + The preferred syntax is the drive letter (e.g. ``d:``). The > + alternate syntax ``\\.\d:`` is supported. ``/dev/cdrom`` is > + supported as an alias to the first CDROM drive. > + > + Currently there is no specific code to handle removable media, so it > + is better to use the ``change`` or ``eject`` monitor commands to > + change or eject media. > + > +Hard disks > + Hard disks can be used with the syntax: ``\\.\PhysicalDriveN`` > + where *N* is the drive number (0 is the first hard disk). > + > + WARNING: unless you know what you do, it is better to only make > + READ-ONLY accesses to the hard disk otherwise you may corrupt your > + host data (use the ``-snapshot`` command line so that the > + modifications are written in a temporary file). > + > +Mac OS X > +'''''''' > + > +``/dev/cdrom`` is an alias to the first CDROM. > + > +Currently there is no specific code to handle removable media, so it > +is better to use the ``change`` or ``eject`` monitor commands to > +change or eject media. > + > +Virtual FAT disk images > +----------------------- > + > +QEMU can automatically create a virtual FAT disk image from a > +directory tree. In order to use it, just type: > + > +.. parsed-literal:: > + > + |qemu_system| linux.img -hdb fat:/my_directory > + > +Then you access access to all the files in the ``/my_directory`` > +directory without having to copy them in a disk image or to export > +them via SAMBA or NFS. The default access is *read-only*. > + > +Floppies can be emulated with the ``:floppy:`` option: > + > +.. parsed-literal:: > + > + |qemu_system| linux.img -fda fat:floppy:/my_directory > + > +A read/write support is available for testing (beta stage) with the > +``:rw:`` option: > + > +.. parsed-literal:: > + > + |qemu_system| linux.img -fda fat:floppy:rw:/my_directory > + > +What you should *never* do: > + > +- use non-ASCII filenames > +- use "-snapshot" together with ":rw:" > +- expect it to work when loadvm'ing > +- write to the FAT directory on the host system while accessing it with the > guest system > + > +NBD access > +---------- > + > +QEMU can access directly to block device exported using the Network Block > Device > +protocol. > + > +.. parsed-literal:: > + > + |qemu_system| linux.img -hdb nbd://my_nbd_server.mydomain.org:1024/ > + > +If the NBD server is located on the same host, you can use an unix socket > instead > +of an inet socket: > + > +.. parsed-literal:: > + > + |qemu_system| linux.img -hdb nbd+unix://?socket=/tmp/my_socket > + > +In this case, the block device must be exported using qemu-nbd: > + > +.. parsed-literal:: > + > + qemu-nbd --socket=/tmp/my_socket my_disk.qcow2 > + > +The use of qemu-nbd allows sharing of a disk between several guests: > + > +.. parsed-literal:: > + > + qemu-nbd --socket=/tmp/my_socket --share=2 my_disk.qcow2 > + > +and then you can use it with two guests: > + > +.. parsed-literal:: > + > + |qemu_system| linux1.img -hdb nbd+unix://?socket=/tmp/my_socket > + |qemu_system| linux2.img -hdb nbd+unix://?socket=/tmp/my_socket > + > +If the nbd-server uses named exports (supported since NBD 2.9.18, or with > QEMU's > +own embedded NBD server), you must specify an export name in the URI: > + > +.. parsed-literal:: > + > + |qemu_system| -cdrom nbd://localhost/debian-500-ppc-netinst > + |qemu_system| -cdrom nbd://localhost/openSUSE-11.1-ppc-netinst > + > +The URI syntax for NBD is supported since QEMU 1.3. An alternative syntax is > +also available. Here are some example of the older syntax: > + > +.. parsed-literal:: > + > + |qemu_system| linux.img -hdb nbd:my_nbd_server.mydomain.org:1024 > + |qemu_system| linux2.img -hdb nbd:unix:/tmp/my_socket > + |qemu_system| -cdrom nbd:localhost:10809:exportname=debian-500-ppc-netinst > + > + > + > +Sheepdog disk images > +-------------------- > + > +Sheepdog is a distributed storage system for QEMU. It provides highly > +available block level storage volumes that can be attached to > +QEMU-based virtual machines. > + > +You can create a Sheepdog disk image with the command: > + > +.. parsed-literal:: > + > + qemu-img create sheepdog:///IMAGE SIZE > + > +where *IMAGE* is the Sheepdog image name and *SIZE* is its > +size. > + > +To import the existing *FILENAME* to Sheepdog, you can use a > +convert command. > + > +.. parsed-literal:: > + > + qemu-img convert FILENAME sheepdog:///IMAGE > + > +You can boot from the Sheepdog disk image with the command: > + > +.. parsed-literal:: > + > + |qemu_system| sheepdog:///IMAGE > + > +You can also create a snapshot of the Sheepdog image like qcow2. > + > +.. parsed-literal:: > + > + qemu-img snapshot -c TAG sheepdog:///IMAGE > + > +where *TAG* is a tag name of the newly created snapshot. > + > +To boot from the Sheepdog snapshot, specify the tag name of the > +snapshot. > + > +.. parsed-literal:: > + > + |qemu_system| sheepdog:///IMAGE#TAG > + > +You can create a cloned image from the existing snapshot. > + > +.. parsed-literal:: > + > + qemu-img create -b sheepdog:///BASE#TAG sheepdog:///IMAGE > + > +where *BASE* is an image name of the source snapshot and *TAG* > +is its tag name. > + > +You can use an unix socket instead of an inet socket: > + > +.. parsed-literal:: > + > + |qemu_system| sheepdog+unix:///IMAGE?socket=PATH > + > +If the Sheepdog daemon doesn't run on the local host, you need to > +specify one of the Sheepdog servers to connect to. > + > +.. parsed-literal:: > + > + qemu-img create sheepdog://HOSTNAME:PORT/IMAGE SIZE > + |qemu_system| sheepdog://HOSTNAME:PORT/IMAGE > + > +iSCSI LUNs > +---------- > + > +iSCSI is a popular protocol used to access SCSI devices across a computer > +network. > + > +There are two different ways iSCSI devices can be used by QEMU. > + > +The first method is to mount the iSCSI LUN on the host, and make it appear as > +any other ordinary SCSI device on the host and then to access this device as > a > +/dev/sd device from QEMU. How to do this differs between host OSes. > + > +The second method involves using the iSCSI initiator that is built into > +QEMU. This provides a mechanism that works the same way regardless of which > +host OS you are running QEMU on. This section will describe this second > method > +of using iSCSI together with QEMU. > + > +In QEMU, iSCSI devices are described using special iSCSI URLs. URL syntax: > + > +:: > + > + iscsi://[<username>[%<password>]@]<host>[:<port>]/<target-iqn-name>/<lun> > + > +Username and password are optional and only used if your target is set up > +using CHAP authentication for access control. > +Alternatively the username and password can also be set via environment > +variables to have these not show up in the process list: > + > +:: > + > + export LIBISCSI_CHAP_USERNAME=<username> > + export LIBISCSI_CHAP_PASSWORD=<password> > + iscsi://<host>/<target-iqn-name>/<lun> > + > +Various session related parameters can be set via special options, either > +in a configuration file provided via '-readconfig' or directly on the > +command line. > + > +If the initiator-name is not specified qemu will use a default name > +of 'iqn.2008-11.org.linux-kvm[:<uuid>'] where <uuid> is the UUID of the > +virtual machine. If the UUID is not specified qemu will use > +'iqn.2008-11.org.linux-kvm[:<name>'] where <name> is the name of the > +virtual machine. > + > +Setting a specific initiator name to use when logging in to the target: > + > +:: > + > + -iscsi initiator-name=iqn.qemu.test:my-initiator > + > +Controlling which type of header digest to negotiate with the target: > + > +:: > + > + -iscsi header-digest=CRC32C|CRC32C-NONE|NONE-CRC32C|NONE > + > +These can also be set via a configuration file: > + > +:: > + > + [iscsi] > + user = "CHAP username" > + password = "CHAP password" > + initiator-name = "iqn.qemu.test:my-initiator" > + # header digest is one of CRC32C|CRC32C-NONE|NONE-CRC32C|NONE > + header-digest = "CRC32C" > + > +Setting the target name allows different options for different targets: > + > +:: > + > + [iscsi "iqn.target.name"] > + user = "CHAP username" > + password = "CHAP password" > + initiator-name = "iqn.qemu.test:my-initiator" > + # header digest is one of CRC32C|CRC32C-NONE|NONE-CRC32C|NONE > + header-digest = "CRC32C" > + > +How to use a configuration file to set iSCSI configuration options: > + > +.. parsed-literal:: > + > + cat >iscsi.conf <<EOF > + [iscsi] > + user = "me" > + password = "my password" > + initiator-name = "iqn.qemu.test:my-initiator" > + header-digest = "CRC32C" > + EOF > + > + |qemu_system| -drive file=iscsi://127.0.0.1/iqn.qemu.test/1 \\ > + -readconfig iscsi.conf > + > +How to set up a simple iSCSI target on loopback and access it via QEMU: > +this example shows how to set up an iSCSI target with one CDROM and one DISK > +using the Linux STGT software target. This target is available on Red Hat > based > +systems as the package 'scsi-target-utils'. > + > +.. parsed-literal:: > + > + tgtd --iscsi portal=127.0.0.1:3260 > + tgtadm --lld iscsi --op new --mode target --tid 1 -T iqn.qemu.test > + tgtadm --lld iscsi --mode logicalunit --op new --tid 1 --lun 1 \\ > + -b /IMAGES/disk.img --device-type=disk > + tgtadm --lld iscsi --mode logicalunit --op new --tid 1 --lun 2 \\ > + -b /IMAGES/cd.iso --device-type=cd > + tgtadm --lld iscsi --op bind --mode target --tid 1 -I ALL > + > + |qemu_system| -iscsi initiator-name=iqn.qemu.test:my-initiator \\ > + -boot d -drive file=iscsi://127.0.0.1/iqn.qemu.test/1 \\ > + -cdrom iscsi://127.0.0.1/iqn.qemu.test/2 > + > +GlusterFS disk images > +--------------------- > + > +GlusterFS is a user space distributed file system. > + > +You can boot from the GlusterFS disk image with the command: > + > +URI: > + > +.. parsed-literal:: > + > + |qemu_system| -drive file=gluster[+TYPE]://[HOST}[:PORT]]/VOLUME/PATH > + > [?socket=...][,file.debug=9][,file.logfile=...] > + > +JSON: > + > +.. parsed-literal:: > + > + |qemu_system| 'json:{"driver":"qcow2", > + "file":{"driver":"gluster", > + > "volume":"testvol","path":"a.img","debug":9,"logfile":"...", > + > "server":[{"type":"tcp","host":"...","port":"..."}, > + > {"type":"unix","socket":"..."}]}}' > + > +*gluster* is the protocol. > + > +*TYPE* specifies the transport type used to connect to gluster > +management daemon (glusterd). Valid transport types are > +tcp and unix. In the URI form, if a transport type isn't specified, > +then tcp type is assumed. > + > +*HOST* specifies the server where the volume file specification for > +the given volume resides. This can be either a hostname or an ipv4 address. > +If transport type is unix, then *HOST* field should not be specified. > +Instead *socket* field needs to be populated with the path to unix domain > +socket. > + > +*PORT* is the port number on which glusterd is listening. This is optional > +and if not specified, it defaults to port 24007. If the transport type is > unix, > +then *PORT* should not be specified. > + > +*VOLUME* is the name of the gluster volume which contains the disk image. > + > +*PATH* is the path to the actual disk image that resides on gluster volume. > + > +*debug* is the logging level of the gluster protocol driver. Debug levels > +are 0-9, with 9 being the most verbose, and 0 representing no debugging > output. > +The default level is 4. The current logging levels defined in the gluster > source > +are 0 - None, 1 - Emergency, 2 - Alert, 3 - Critical, 4 - Error, 5 - Warning, > +6 - Notice, 7 - Info, 8 - Debug, 9 - Trace > + > +*logfile* is a commandline option to mention log file path which helps in > +logging to the specified file and also help in persisting the gfapi logs. The > +default is stderr. > + > +You can create a GlusterFS disk image with the command: > + > +.. parsed-literal:: > + > + qemu-img create gluster://HOST/VOLUME/PATH SIZE > + > +Examples > + > +.. parsed-literal:: > + > + |qemu_system| -drive file=gluster://1.2.3.4/testvol/a.img > + |qemu_system| -drive file=gluster+tcp://1.2.3.4/testvol/a.img > + |qemu_system| -drive file=gluster+tcp://1.2.3.4:24007/testvol/dir/a.img > + |qemu_system| -drive file=gluster+tcp://[1:2:3:4:5:6:7:8]/testvol/dir/a.img > + |qemu_system| -drive > file=gluster+tcp://[1:2:3:4:5:6:7:8]:24007/testvol/dir/a.img > + |qemu_system| -drive > file=gluster+tcp://server.domain.com:24007/testvol/dir/a.img > + |qemu_system| -drive > file=gluster+unix:///testvol/dir/a.img?socket=/tmp/glusterd.socket > + |qemu_system| -drive file=gluster+rdma://1.2.3.4:24007/testvol/a.img > + |qemu_system| -drive > file=gluster://1.2.3.4/testvol/a.img,file.debug=9,file.logfile=/var/log/qemu-gluster.log > + |qemu_system| 'json:{"driver":"qcow2", > + "file":{"driver":"gluster", > + "volume":"testvol","path":"a.img", > + > "debug":9,"logfile":"/var/log/qemu-gluster.log", > + > "server":[{"type":"tcp","host":"1.2.3.4","port":24007}, > + > {"type":"unix","socket":"/var/run/glusterd.socket"}]}}' > + |qemu_system| -drive > driver=qcow2,file.driver=gluster,file.volume=testvol,file.path=/path/a.img, > + > file.debug=9,file.logfile=/var/log/qemu-gluster.log, > + > file.server.0.type=tcp,file.server.0.host=1.2.3.4,file.server.0.port=24007, > + > file.server.1.type=unix,file.server.1.socket=/var/run/glusterd.socket > + > +Secure Shell (ssh) disk images > +------------------------------ > + > +You can access disk images located on a remote ssh server > +by using the ssh protocol: > + > +.. parsed-literal:: > + > + |qemu_system| -drive > file=ssh://[USER@]SERVER[:PORT]/PATH[?host_key_check=HOST_KEY_CHECK] > + > +Alternative syntax using properties: > + > +.. parsed-literal:: > + > + |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] > + > +*ssh* is the protocol. > + > +*USER* is the remote user. If not specified, then the local > +username is tried. > + > +*SERVER* specifies the remote ssh server. Any ssh server can be > +used, but it must implement the sftp-server protocol. Most Unix/Linux > +systems should work without requiring any extra configuration. > + > +*PORT* is the port number on which sshd is listening. By default > +the standard ssh port (22) is used. > + > +*PATH* is the path to the disk image. > + > +The optional *HOST_KEY_CHECK* parameter controls how the remote > +host's key is checked. The default is ``yes`` which means to use > +the local ``.ssh/known_hosts`` file. Setting this to ``no`` > +turns off known-hosts checking. Or you can check that the host key > +matches a specific fingerprint: > +``host_key_check=md5:78:45:8e:14:57:4f:d5:45:83:0a:0e:f3:49:82:c9:c8`` > +(``sha1:`` can also be used as a prefix, but note that OpenSSH > +tools only use MD5 to print fingerprints). > + > +Currently authentication must be done using ssh-agent. Other > +authentication methods may be supported in future. > + > +Note: Many ssh servers do not support an ``fsync``-style operation. > +The ssh driver cannot guarantee that disk flush requests are > +obeyed, and this causes a risk of disk corruption if the remote > +server or network goes down during writes. The driver will > +print a warning when ``fsync`` is not supported: > + > +:: > + > + warning: ssh server ssh.example.com:22 does not support fsync > + > +With sufficiently new versions of libssh and OpenSSH, ``fsync`` is > +supported. > + > +NVMe disk images > +---------------- > + > +NVM Express (NVMe) storage controllers can be accessed directly by a > userspace > +driver in QEMU. This bypasses the host kernel file system and block layers > +while retaining QEMU block layer functionalities, such as block jobs, I/O > +throttling, image formats, etc. Disk I/O performance is typically higher > than > +with ``-drive file=/dev/sda`` using either thread pool or linux-aio. > + > +The controller will be exclusively used by the QEMU process once started. To > be > +able to share storage between multiple VMs and other applications on the > host, > +please use the file based protocols. > + > +Before starting QEMU, bind the host NVMe controller to the host vfio-pci > +driver. For example: > + > +.. parsed-literal:: > + > + # modprobe vfio-pci > + # lspci -n -s 0000:06:0d.0 > + 06:0d.0 0401: 1102:0002 (rev 08) > + # echo 0000:06:0d.0 > /sys/bus/pci/devices/0000:06:0d.0/driver/unbind > + # echo 1102 0002 > /sys/bus/pci/drivers/vfio-pci/new_id > + > + # |qemu_system| -drive file=nvme://HOST:BUS:SLOT.FUNC/NAMESPACE > + > +Alternative syntax using properties: > + > +.. parsed-literal:: > + > + |qemu_system| -drive > file.driver=nvme,file.device=HOST:BUS:SLOT.FUNC,file.namespace=NAMESPACE > + > +*HOST*:*BUS*:*SLOT*.\ *FUNC* is the NVMe controller's PCI device > +address on the host. > + > +*NAMESPACE* is the NVMe namespace number, starting from 1. > + > +Disk image file locking > +----------------------- > + > +By default, QEMU tries to protect image files from unexpected concurrent > +access, as long as it's supported by the block protocol driver and host > +operating system. If multiple QEMU processes (including QEMU emulators and > +utilities) try to open the same image with conflicting accessing modes, all > but > +the first one will get an error. > + > +This feature is currently supported by the file protocol on Linux with the > Open > +File Descriptor (OFD) locking API, and can be configured to fall back to > POSIX > +locking if the POSIX host doesn't support Linux OFD locking. > + > +To explicitly enable image locking, specify "locking=on" in the file protocol > +driver options. If OFD locking is not possible, a warning will be printed and > +the POSIX locking API will be used. In this case there is a risk that the > lock > +will get silently lost when doing hot plugging and block jobs, due to the > +shortcomings of the POSIX locking API. > + > +QEMU transparently handles lock handover during shared storage migration. > For > +shared virtual disk images between multiple VMs, the "share-rw" device option > +should be used. > + > +By default, the guest has exclusive write access to its disk image. If the > +guest can safely share the disk image with other writers the > +``-device ...,share-rw=on`` parameter can be used. This is only safe if > +the guest is running software, such as a cluster file system, that > +coordinates disk accesses to avoid corruption. > + > +Note that share-rw=on only declares the guest's ability to share the disk. > +Some QEMU features, such as image file formats, require exclusive write > access > +to the disk image and this is unaffected by the share-rw=on option. > + > +Alternatively, locking can be fully disabled by "locking=off" block device > +option. In the command line, the option is usually in the form of > +"file.locking=off" as the protocol driver is normally placed as a "file" > child > +under a format driver. For example: > + > +:: > + > + -blockdev > driver=qcow2,file.filename=/path/to/image,file.locking=off,file.driver=file > + > +To check if image locking is active, check the output of the "lslocks" > command > +on host and see if there are locks held by the QEMU process on the image > file. > +More than one byte could be locked by the QEMU instance, each byte of which > +reflects a particular permission that is acquired or protected by the running > +block driver. > + > +.. only:: man > + > + See also > + -------- > + > + The HTML documentation of QEMU for more precise information and Linux > + user mode emulator invocation. > diff --git a/qemu-doc.texi b/qemu-doc.texi > index 617485d1461..2328e7ea476 100644 > --- a/qemu-doc.texi > +++ b/qemu-doc.texi > @@ -633,16 +633,6 @@ encrypted disk images. > * disk_images_snapshot_mode:: Snapshot mode > * vm_snapshots:: VM snapshots > * qemu_img_invocation:: qemu-img Invocation > -* disk_images_formats:: Disk image file formats > -* host_drives:: Using host drives > -* disk_images_fat_images:: Virtual FAT disk images > -* disk_images_nbd:: NBD access > -* disk_images_sheepdog:: Sheepdog disk images > -* disk_images_iscsi:: iSCSI LUNs > -* disk_images_gluster:: GlusterFS disk images > -* disk_images_ssh:: Secure Shell (ssh) disk images > -* disk_images_nvme:: NVMe userspace driver > -* disk_image_locking:: Disk image file locking > @end menu > > @node disk_images_quickstart > @@ -723,8 +713,6 @@ state is not saved or restored properly (in particular > USB). > > @include qemu-img.texi > > -@include docs/qemu-block-drivers.texi > - > @node pcsys_network > @section Network emulation > > diff --git a/qemu-options.hx b/qemu-options.hx > index 709162c159a..224a8e8712a 100644 > --- a/qemu-options.hx > +++ b/qemu-options.hx > @@ -953,7 +953,7 @@ STEXI > @findex -cdrom > Use @var{file} as CD-ROM image (you cannot use @option{-hdc} and > @option{-cdrom} at the same time). You can use the host CD-ROM by > -using @file{/dev/cdrom} as filename (@pxref{host_drives}). > +using @file{/dev/cdrom} as filename. > ETEXI > > DEF("blockdev", HAS_ARG, QEMU_OPTION_blockdev, -- Alex Bennée