Re: [Qemu-block] [PATCH] docs: add qemu-block-drivers(7) man page

[John Snow]

On 06/22/2017 08:17 AM, Stefan Hajnoczi wrote:
> Block driver documentation is available in qemu-doc.html.  It would be
> convenient to have documentation for formats, protocols, and filter
> drivers in a man page.
> 
> Extract the relevant part of qemu-doc.html into a new file called
> docs/qemu-block-drivers.texi.  This file can also be built as a
> stand-alone document (man, html, etc).
> 
> Signed-off-by: Stefan Hajnoczi <address@hidden>

Thanks, this is really useful information to have. Looks good to me, but
Paolo's changes prevent it from applying now.

So, as of last week:

Reviewed-by: John Snow <address@hidden>

> ---
>  Makefile                     |  28 +-
>  docs/qemu-block-drivers.texi | 692 
> +++++++++++++++++++++++++++++++++++++++++++
>  qemu-doc.texi                | 673 +----------------------------------------
>  3 files changed, 712 insertions(+), 681 deletions(-)
>  create mode 100644 docs/qemu-block-drivers.texi
> 
> diff --git a/Makefile b/Makefile
> index c830d7a..ee9b434 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -209,6 +209,9 @@ ifdef BUILD_DOCS
>  DOCS=qemu-doc.html qemu-doc.txt qemu.1 qemu-img.1 qemu-nbd.8 qemu-ga.8
>  DOCS+=docs/qemu-qmp-ref.html docs/qemu-qmp-ref.txt docs/qemu-qmp-ref.7
>  DOCS+=docs/qemu-ga-ref.html docs/qemu-ga-ref.txt docs/qemu-ga-ref.7
> +DOCS+=docs/qemu-block-drivers.html
> +DOCS+=docs/qemu-block-drivers.txt
> +DOCS+=docs/qemu-block-drivers.7
>  ifdef CONFIG_VIRTFS
>  DOCS+=fsdev/virtfs-proxy-helper.1
>  endif
> @@ -520,10 +523,10 @@ distclean: clean
>       rm -f config.log
>       rm -f linux-headers/asm
>       rm -f docs/qemu-ga-qapi.texi docs/qemu-qmp-qapi.texi docs/version.texi
> -     rm -f docs/qemu-qmp-ref.7 docs/qemu-ga-ref.7
> -     rm -f docs/qemu-qmp-ref.txt docs/qemu-ga-ref.txt
> -     rm -f docs/qemu-qmp-ref.pdf docs/qemu-ga-ref.pdf
> -     rm -f docs/qemu-qmp-ref.html docs/qemu-ga-ref.html
> +     rm -f docs/qemu-qmp-ref.7 docs/qemu-ga-ref.7 docs/qemu-block-drivers.7
> +     rm -f docs/qemu-qmp-ref.txt docs/qemu-ga-ref.txt 
> docs/qemu-block-drivers.txt
> +     rm -f docs/qemu-qmp-ref.pdf docs/qemu-ga-ref.pdf 
> docs/qemu-block-drivers.pdf
> +     rm -f docs/qemu-qmp-ref.html docs/qemu-ga-ref.html 
> docs/qemu-block-drivers.html
>       for d in $(TARGET_DIRS); do \
>       rm -rf $$d || exit 1 ; \
>          done
> @@ -564,11 +567,14 @@ install-doc: $(DOCS)
>       $(INSTALL_DATA) qemu-doc.txt "$(DESTDIR)$(qemu_docdir)"
>       $(INSTALL_DATA) docs/qemu-qmp-ref.html "$(DESTDIR)$(qemu_docdir)"
>       $(INSTALL_DATA) docs/qemu-qmp-ref.txt "$(DESTDIR)$(qemu_docdir)"
> +     $(INSTALL_DATA) docs/qemu-block-drivers.html "$(DESTDIR)$(qemu_docdir)"
> +     $(INSTALL_DATA) docs/qemu-block-drivers.txt "$(DESTDIR)$(qemu_docdir)"
>  ifdef CONFIG_POSIX
>       $(INSTALL_DIR) "$(DESTDIR)$(mandir)/man1"
>       $(INSTALL_DATA) qemu.1 "$(DESTDIR)$(mandir)/man1"
>       $(INSTALL_DIR) "$(DESTDIR)$(mandir)/man7"
>       $(INSTALL_DATA) docs/qemu-qmp-ref.7 "$(DESTDIR)$(mandir)/man7"
> +     $(INSTALL_DATA) docs/qemu-block-drivers.7 "$(DESTDIR)$(mandir)/man7"
>  ifneq ($(TOOLS),)
>       $(INSTALL_DATA) qemu-img.1 "$(DESTDIR)$(mandir)/man1"
>       $(INSTALL_DIR) "$(DESTDIR)$(mandir)/man8"
> @@ -688,6 +694,7 @@ docs/version.texi: $(SRC_PATH)/VERSION
>  
>  docs/qemu-ga-ref.html docs/qemu-ga-ref.info docs/qemu-ga-ref.txt 
> docs/qemu-ga-ref.pdf docs/qemu-ga-ref.7.pod: docs/version.texi
>  docs/qemu-qmp-ref.html docs/qemu-qmp-ref.info docs/qemu-qmp-ref.txt 
> docs/qemu-qmp-ref.pdf docs/qemu-qmp-ref.pod: docs/version.texi
> +docs/qemu-block-drivers.html docs/qemu-block-drivers.info 
> docs/qemu-block-drivers.txt docs/qemu-block-drivers.pdf 
> docs/qemu-block-drivers.pod: docs/version.texi
>  
>  qemu-options.texi: $(SRC_PATH)/qemu-options.hx $(SRC_PATH)/scripts/hxtool
>       $(call quiet-command,sh $(SRC_PATH)/scripts/hxtool -t < $< > 
> $@,"GEN","$@")
> @@ -716,15 +723,15 @@ fsdev/virtfs-proxy-helper.1: 
> fsdev/virtfs-proxy-helper.texi
>  qemu-nbd.8: qemu-nbd.texi qemu-option-trace.texi
>  qemu-ga.8: qemu-ga.texi
>  
> -html: qemu-doc.html docs/qemu-qmp-ref.html docs/qemu-ga-ref.html
> -info: qemu-doc.info docs/qemu-qmp-ref.info docs/qemu-ga-ref.info
> -pdf: qemu-doc.pdf docs/qemu-qmp-ref.pdf docs/qemu-ga-ref.pdf
> -txt: qemu-doc.txt docs/qemu-qmp-ref.txt docs/qemu-ga-ref.txt
> +html: qemu-doc.html docs/qemu-qmp-ref.html docs/qemu-ga-ref.html 
> docs/qemu-block-drivers.html
> +info: qemu-doc.info docs/qemu-qmp-ref.info docs/qemu-ga-ref.info 
> docs/qemu-block-drivers.info
> +pdf: qemu-doc.pdf docs/qemu-qmp-ref.pdf docs/qemu-ga-ref.pdf 
> docs/qemu-block-drivers.pdf
> +txt: qemu-doc.txt docs/qemu-qmp-ref.txt docs/qemu-ga-ref.txt 
> docs/qemu-block-drivers.txt
>  
>  qemu-doc.html qemu-doc.info qemu-doc.pdf qemu-doc.txt: \
>       qemu-img.texi qemu-nbd.texi qemu-options.texi qemu-option-trace.texi \
>       qemu-monitor.texi qemu-img-cmds.texi qemu-ga.texi \
> -     qemu-monitor-info.texi
> +     qemu-monitor-info.texi docs/qemu-block-drivers.texi
>  
>  docs/qemu-ga-ref.dvi docs/qemu-ga-ref.html docs/qemu-ga-ref.info 
> docs/qemu-ga-ref.pdf docs/qemu-ga-ref.txt docs/qemu-ga-ref.7: \
>  docs/qemu-ga-ref.texi docs/qemu-ga-qapi.texi
> @@ -732,6 +739,9 @@ docs/qemu-ga-ref.texi docs/qemu-ga-qapi.texi
>  docs/qemu-qmp-ref.dvi docs/qemu-qmp-ref.html docs/qemu-qmp-ref.info 
> docs/qemu-qmp-ref.pdf docs/qemu-qmp-ref.txt docs/qemu-qmp-ref.7: \
>  docs/qemu-qmp-ref.texi docs/qemu-qmp-qapi.texi
>  
> +docs/qemu-block-drivers.dvi docs/qemu-block-drivers.html 
> docs/qemu-block-drivers.info docs/qemu-block-drivers.pdf 
> docs/qemu-block-drivers.txt docs/qemu-block-drivers.7: \
> +docs/qemu-block-drivers.texi
> +
>  
>  ifdef CONFIG_WIN32
>  
> diff --git a/docs/qemu-block-drivers.texi b/docs/qemu-block-drivers.texi
> new file mode 100644
> index 0000000..a43e878
> --- /dev/null
> +++ b/docs/qemu-block-drivers.texi
> @@ -0,0 +1,692 @@
> address@hidden man begin SYNOPSIS
> +QEMU block driver reference manual
> address@hidden man end
> +
> address@hidden man begin DESCRIPTION
> +
> address@hidden disk_images_formats
> +
> address@hidden 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
> address@hidden create} and @code{qemu-img convert} using the @code{-o} option.
> +This section describes each format and the options that are supported for it.
> +
> address@hidden @option
> address@hidden 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:
> address@hidden @code
> address@hidden preallocation
> +Preallocation mode (allowed values: @code{off}, @code{falloc}, @code{full}).
> address@hidden mode preallocates space for image by calling posix_fallocate().
> address@hidden mode preallocates space for image by writing zeros to 
> underlying
> +storage.
> address@hidden table
> +
> address@hidden 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:
> address@hidden @code
> address@hidden 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.
> address@hidden 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.
> +
> address@hidden backing_file
> +File name of a base image (see @option{create} subcommand)
> address@hidden backing_fmt
> +Image format of the base image
> address@hidden encryption
> +If this option is set to @code{on}, the image is encrypted with 128-bit 
> AES-CBC.
> +
> +The use of encryption in qcow and qcow2 images is considered to be flawed by
> +modern cryptography standards, suffering from a number of design problems:
> +
> address@hidden @minus
> address@hidden 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.
> address@hidden The user passphrase is directly used as the encryption key. A 
> poorly
> +chosen or short passphrase will compromise the security of the encryption.
> address@hidden 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.
> address@hidden itemize
> +
> +Use of qcow / qcow2 encryption with QEMU is deprecated, and support for
> +it will go away in a future release.  Users are recommended to use an
> +alternative encryption technology such as the Linux dm-crypt / LUKS
> +system.
> +
> address@hidden 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.
> +
> address@hidden preallocation
> +Preallocation mode (allowed values: @code{off}, @code{metadata}, 
> @code{falloc},
> address@hidden). 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.
> +
> address@hidden 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.
> +
> address@hidden 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).
> +
> address@hidden table
> +
> address@hidden 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
> address@hidden option to get a more QED-like behaviour.
> +
> +Supported options:
> address@hidden @code
> address@hidden backing_file
> +File name of a base image (see @option{create} subcommand).
> address@hidden 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.
> address@hidden 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.
> address@hidden 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.
> address@hidden table
> +
> address@hidden qcow
> +Old QEMU image format with support for backing files, compact image files,
> +encryption and compression.
> +
> +Supported options:
> address@hidden @code
> address@hidden backing_file
> +File name of a base image (see @option{create} subcommand)
> address@hidden encryption
> +If this option is set to @code{on}, the image is encrypted.
> address@hidden table
> +
> address@hidden vdi
> +VirtualBox 1.1 compatible image format.
> +Supported options:
> address@hidden @code
> address@hidden static
> +If this option is set to @code{on}, the image is created with metadata
> +preallocation.
> address@hidden table
> +
> address@hidden vmdk
> +VMware 3 and 4 compatible image format.
> +
> +Supported options:
> address@hidden @code
> address@hidden backing_file
> +File name of a base image (see @option{create} subcommand).
> address@hidden compat6
> +Create a VMDK version 6 image (instead of version 4)
> address@hidden hwversion
> +Specify vmdk virtual hardware version. Compat6 flag cannot be enabled
> +if hwversion is specified.
> address@hidden subformat
> +Specifies which VMDK subformat to use. Valid options are
> address@hidden (default),
> address@hidden,
> address@hidden,
> address@hidden and
> address@hidden
> address@hidden table
> +
> address@hidden vpc
> +VirtualPC compatible image format (VHD).
> +Supported options:
> address@hidden @code
> address@hidden subformat
> +Specifies which VHD subformat to use. Valid options are
> address@hidden (default) and @code{fixed}.
> address@hidden table
> +
> address@hidden VHDX
> +Hyper-V compatible image format (VHDX).
> +Supported options:
> address@hidden @code
> address@hidden subformat
> +Specifies which VHDX subformat to use. Valid options are
> address@hidden (default) and @code{fixed}.
> address@hidden 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
> address@hidden, which means parsers are free to return
> +arbitrary data for those blocks.  Do not set to @code{off} when using
> address@hidden convert} with @code{subformat=dynamic}.
> address@hidden block_size
> +Block size; min 1 MB, max 256 MB.  0 means auto-calculate based on image 
> size.
> address@hidden log_size
> +Log size; min 1 MB.
> address@hidden table
> address@hidden table
> +
> address@hidden Read-only formats
> +More disk image file formats are supported in a read-only mode.
> address@hidden @option
> address@hidden bochs
> +Bochs images of @code{growing} type.
> address@hidden cloop
> +Linux Compressed Loop image, useful only to reuse directly compressed
> +CD-ROM images present for example in the Knoppix CD-ROMs.
> address@hidden dmg
> +Apple disk image.
> address@hidden parallels
> +Parallels disk image format.
> address@hidden table
> +
> +
> address@hidden host_drives
> address@hidden 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.
> +
> address@hidden 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.
> +
> address@hidden @code
> address@hidden 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.
> address@hidden 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.
> address@hidden 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).
> address@hidden table
> +
> address@hidden Windows
> +
> address@hidden @code
> address@hidden 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.
> address@hidden Hard disks
> +Hard disks can be used with the syntax: @address@hidden
> +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).
> address@hidden table
> +
> +
> address@hidden Mac OS X
> +
> address@hidden/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.
> +
> address@hidden disk_images_fat_images
> address@hidden Virtual FAT disk images
> +
> +QEMU can automatically create a virtual FAT disk image from a
> +directory tree. In order to use it, just type:
> +
> address@hidden
> +qemu-system-i386 linux.img -hdb fat:/my_directory
> address@hidden 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:
> +
> address@hidden
> +qemu-system-i386 linux.img -fda fat:floppy:/my_directory
> address@hidden example
> +
> +A read/write support is available for testing (beta stage) with the
> address@hidden:rw:} option:
> +
> address@hidden
> +qemu-system-i386 linux.img -fda fat:floppy:rw:/my_directory
> address@hidden example
> +
> +What you should @emph{never} do:
> address@hidden
> address@hidden use non-ASCII filenames ;
> address@hidden use "-snapshot" together with ":rw:" ;
> address@hidden expect it to work when loadvm'ing ;
> address@hidden write to the FAT directory on the host system while accessing 
> it with the guest system.
> address@hidden itemize
> +
> address@hidden disk_images_nbd
> address@hidden NBD access
> +
> +QEMU can access directly to block device exported using the Network Block 
> Device
> +protocol.
> +
> address@hidden
> +qemu-system-i386 linux.img -hdb nbd://my_nbd_server.mydomain.org:1024/
> address@hidden example
> +
> +If the NBD server is located on the same host, you can use an unix socket 
> instead
> +of an inet socket:
> +
> address@hidden
> +qemu-system-i386 linux.img -hdb nbd+unix://?socket=/tmp/my_socket
> address@hidden example
> +
> +In this case, the block device must be exported using qemu-nbd:
> +
> address@hidden
> +qemu-nbd --socket=/tmp/my_socket my_disk.qcow2
> address@hidden example
> +
> +The use of qemu-nbd allows sharing of a disk between several guests:
> address@hidden
> +qemu-nbd --socket=/tmp/my_socket --share=2 my_disk.qcow2
> address@hidden example
> +
> address@hidden
> +and then you can use it with two guests:
> address@hidden
> +qemu-system-i386 linux1.img -hdb nbd+unix://?socket=/tmp/my_socket
> +qemu-system-i386 linux2.img -hdb nbd+unix://?socket=/tmp/my_socket
> address@hidden 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:
> address@hidden
> +qemu-system-i386 -cdrom nbd://localhost/debian-500-ppc-netinst
> +qemu-system-i386 -cdrom nbd://localhost/openSUSE-11.1-ppc-netinst
> address@hidden 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:
> address@hidden
> +qemu-system-i386 linux.img -hdb nbd:my_nbd_server.mydomain.org:1024
> +qemu-system-i386 linux2.img -hdb nbd:unix:/tmp/my_socket
> +qemu-system-i386 -cdrom nbd:localhost:10809:exportname=debian-500-ppc-netinst
> address@hidden example
> +
> address@hidden disk_images_sheepdog
> address@hidden 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:
> address@hidden
> +qemu-img create sheepdog:///@var{image} @var{size}
> address@hidden 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.
> address@hidden
> +qemu-img convert @var{filename} sheepdog:///@var{image}
> address@hidden example
> +
> +You can boot from the Sheepdog disk image with the command:
> address@hidden
> +qemu-system-i386 sheepdog:///@var{image}
> address@hidden example
> +
> +You can also create a snapshot of the Sheepdog image like qcow2.
> address@hidden
> +qemu-img snapshot -c @var{tag} sheepdog:///@var{image}
> address@hidden 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.
> address@hidden
> +qemu-system-i386 sheepdog:///@address@hidden
> address@hidden example
> +
> +You can create a cloned image from the existing snapshot.
> address@hidden
> +qemu-img create -b sheepdog:///@address@hidden sheepdog:///@var{image}
> address@hidden example
> +where @var{base} is a image name of the source snapshot and @var{tag}
> +is its tag name.
> +
> +You can use an unix socket instead of an inet socket:
> +
> address@hidden
> +qemu-system-i386 sheepdog+unix:///@address@hidden
> address@hidden example
> +
> +If the Sheepdog daemon doesn't run on the local host, you need to
> +specify one of the Sheepdog servers to connect to.
> address@hidden
> +qemu-img create sheepdog://@var{hostname}:@var{port}/@var{image} @var{size}
> +qemu-system-i386 sheepdog://@var{hostname}:@var{port}/@var{image}
> address@hidden example
> +
> address@hidden disk_images_iscsi
> address@hidden 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
> +
> address@hidden
> +URL syntax:
> +iscsi://[<username>[%<password>]@@]<host>[:<port>]/<target-iqn-name>/<lun>
> address@hidden 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
> +
> address@hidden
> +export LIBISCSI_CHAP_USERNAME=<username>
> +export LIBISCSI_CHAP_PASSWORD=<password>
> +iscsi://<host>/<target-iqn-name>/<lun>
> address@hidden 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[:<name>'] where <name> is the name of the
> +virtual machine.
> +
> +
> address@hidden
> +Setting a specific initiator name to use when logging in to the target
> +-iscsi initiator-name=iqn.qemu.test:my-initiator
> address@hidden example
> +
> address@hidden
> +Controlling which type of header digest to negotiate with the target
> +-iscsi header-digest=CRC32C|CRC32C-NONE|NONE-CRC32C|NONE
> address@hidden example
> +
> +These can also be set via a configuration file
> address@hidden
> +[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"
> address@hidden example
> +
> +
> +Setting the target name allows different options for different targets
> address@hidden
> +[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"
> address@hidden example
> +
> +
> +Howto use a configuration file to set iSCSI configuration options:
> address@hidden
> +cat >iscsi.conf <<EOF
> +[iscsi]
> +  user = "me"
> +  password = "my password"
> +  initiator-name = "iqn.qemu.test:my-initiator"
> +  header-digest = "CRC32C"
> +EOF
> +
> +qemu-system-i386 -drive file=iscsi://127.0.0.1/iqn.qemu.test/1 \
> +    -readconfig iscsi.conf
> address@hidden example
> +
> +
> +Howto set up a simple iSCSI target on loopback and accessing it via QEMU:
> address@hidden
> +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
> +
> +qemu-system-i386 -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
> address@hidden example
> +
> address@hidden disk_images_gluster
> address@hidden GlusterFS disk images
> +
> +GlusterFS is a user space distributed file system.
> +
> +You can boot from the GlusterFS disk image with the command:
> address@hidden
> +URI:
> +qemu-system-x86_64 -drive 
> address@hidden://address@hidden:@var{port}]]/@var{volume}/@var{path}
> +                               
> [?socket=...][,file.debug=9][,file.logfile=...]
> +
> +JSON:
> +qemu-system-x86_64 'json:@{"driver":"qcow2",
> +                           "file":@{"driver":"gluster",
> +                                    
> "volume":"testvol","path":"a.img","debug":9,"logfile":"...",
> +                                    
> "server":address@hidden"type":"tcp","host":"...","port":"..."@},
> +                                              
> @{"type":"unix","socket":"..."@address@hidden@}'
> address@hidden example
> +
> address@hidden is the protocol.
> +
> address@hidden 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.
> +
> address@hidden 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.
> +
> address@hidden 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.
> +
> address@hidden is the name of the gluster volume which contains the disk 
> image.
> +
> address@hidden is the path to the actual disk image that resides on gluster 
> volume.
> +
> address@hidden 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
> +
> address@hidden 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:
> address@hidden
> +qemu-img create gluster://@var{host}/@var{volume}/@var{path} @var{size}
> address@hidden example
> +
> +Examples
> address@hidden
> +qemu-system-x86_64 -drive file=gluster://1.2.3.4/testvol/a.img
> +qemu-system-x86_64 -drive file=gluster+tcp://1.2.3.4/testvol/a.img
> +qemu-system-x86_64 -drive file=gluster+tcp://1.2.3.4:24007/testvol/dir/a.img
> +qemu-system-x86_64 -drive 
> file=gluster+tcp://[1:2:3:4:5:6:7:8]/testvol/dir/a.img
> +qemu-system-x86_64 -drive 
> file=gluster+tcp://[1:2:3:4:5:6:7:8]:24007/testvol/dir/a.img
> +qemu-system-x86_64 -drive 
> file=gluster+tcp://server.domain.com:24007/testvol/dir/a.img
> +qemu-system-x86_64 -drive 
> file=gluster+unix:///testvol/dir/a.img?socket=/tmp/glusterd.socket
> +qemu-system-x86_64 -drive file=gluster+rdma://1.2.3.4:24007/testvol/a.img
> +qemu-system-x86_64 -drive 
> file=gluster://1.2.3.4/testvol/a.img,file.debug=9,file.logfile=/var/log/qemu-gluster.log
> +qemu-system-x86_64 'json:@{"driver":"qcow2",
> +                           "file":@{"driver":"gluster",
> +                                    "volume":"testvol","path":"a.img",
> +                                    
> "debug":9,"logfile":"/var/log/qemu-gluster.log",
> +                                    
> "server":address@hidden"type":"tcp","host":"1.2.3.4","port":address@hidden,
> +                                              
> @{"type":"unix","socket":"/var/run/glusterd.socket"@address@hidden@}'
> +qemu-system-x86_64 -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
> address@hidden example
> +
> address@hidden disk_images_ssh
> address@hidden Secure Shell (ssh) disk images
> +
> +You can access disk images located on a remote ssh server
> +by using the ssh protocol:
> +
> address@hidden
> +qemu-system-x86_64 -drive 
> file=ssh://address@hidden@@address@hidden:@var{port}]/@address@hidden
> address@hidden example
> +
> +Alternative syntax using properties:
> +
> address@hidden
> +qemu-system-x86_64 -drive 
> file.driver=ssh[,address@hidden,address@hidden,address@hidden,address@hidden,address@hidden
> address@hidden example
> +
> address@hidden is the protocol.
> +
> address@hidden is the remote user.  If not specified, then the local
> +username is tried.
> +
> address@hidden 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.
> +
> address@hidden is the port number on which sshd is listening.  By default
> +the standard ssh port (22) is used.
> +
> address@hidden 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:
> address@hidden: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 libssh2 and OpenSSH, @code{fsync} is
> +supported.
> +
> address@hidden man end
> +
> address@hidden
> +
> address@hidden qemu-block-drivers
> address@hidden QEMU block drivers reference
> +
> address@hidden man begin AUTHOR
> +Fabrice Bellard and the QEMU Project developers
> address@hidden man end
> +
> address@hidden ignore
> diff --git a/qemu-doc.texi b/qemu-doc.texi
> index 965ba59..740e827 100644
> --- a/qemu-doc.texi
> +++ b/qemu-doc.texi
> @@ -490,678 +490,7 @@ state is not saved or restored properly (in particular 
> USB).
>  
>  @include qemu-nbd.texi
>  
> address@hidden disk_images_formats
> address@hidden 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
> address@hidden create} and @code{qemu-img convert} using the @code{-o} option.
> -This section describes each format and the options that are supported for it.
> -
> address@hidden @option
> address@hidden 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:
> address@hidden @code
> address@hidden preallocation
> -Preallocation mode (allowed values: @code{off}, @code{falloc}, @code{full}).
> address@hidden mode preallocates space for image by calling posix_fallocate().
> address@hidden mode preallocates space for image by writing zeros to 
> underlying
> -storage.
> address@hidden table
> -
> address@hidden 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:
> address@hidden @code
> address@hidden 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.
> address@hidden 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.
> -
> address@hidden backing_file
> -File name of a base image (see @option{create} subcommand)
> address@hidden backing_fmt
> -Image format of the base image
> address@hidden encryption
> -If this option is set to @code{on}, the image is encrypted with 128-bit 
> AES-CBC.
> -
> -The use of encryption in qcow and qcow2 images is considered to be flawed by
> -modern cryptography standards, suffering from a number of design problems:
> -
> address@hidden @minus
> address@hidden 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.
> address@hidden The user passphrase is directly used as the encryption key. A 
> poorly
> -chosen or short passphrase will compromise the security of the encryption.
> address@hidden 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.
> address@hidden itemize
> -
> -Use of qcow / qcow2 encryption with QEMU is deprecated, and support for
> -it will go away in a future release.  Users are recommended to use an
> -alternative encryption technology such as the Linux dm-crypt / LUKS
> -system.
> -
> address@hidden 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.
> -
> address@hidden preallocation
> -Preallocation mode (allowed values: @code{off}, @code{metadata}, 
> @code{falloc},
> address@hidden). 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.
> -
> address@hidden 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.
> -
> address@hidden 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).
> -
> address@hidden table
> -
> address@hidden 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
> address@hidden option to get a more QED-like behaviour.
> -
> -Supported options:
> address@hidden @code
> address@hidden backing_file
> -File name of a base image (see @option{create} subcommand).
> address@hidden 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.
> address@hidden 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.
> address@hidden 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.
> address@hidden table
> -
> address@hidden qcow
> -Old QEMU image format with support for backing files, compact image files,
> -encryption and compression.
> -
> -Supported options:
> address@hidden @code
> address@hidden backing_file
> -File name of a base image (see @option{create} subcommand)
> address@hidden encryption
> -If this option is set to @code{on}, the image is encrypted.
> address@hidden table
> -
> address@hidden vdi
> -VirtualBox 1.1 compatible image format.
> -Supported options:
> address@hidden @code
> address@hidden static
> -If this option is set to @code{on}, the image is created with metadata
> -preallocation.
> address@hidden table
> -
> address@hidden vmdk
> -VMware 3 and 4 compatible image format.
> -
> -Supported options:
> address@hidden @code
> address@hidden backing_file
> -File name of a base image (see @option{create} subcommand).
> address@hidden compat6
> -Create a VMDK version 6 image (instead of version 4)
> address@hidden hwversion
> -Specify vmdk virtual hardware version. Compat6 flag cannot be enabled
> -if hwversion is specified.
> address@hidden subformat
> -Specifies which VMDK subformat to use. Valid options are
> address@hidden (default),
> address@hidden,
> address@hidden,
> address@hidden and
> address@hidden
> address@hidden table
> -
> address@hidden vpc
> -VirtualPC compatible image format (VHD).
> -Supported options:
> address@hidden @code
> address@hidden subformat
> -Specifies which VHD subformat to use. Valid options are
> address@hidden (default) and @code{fixed}.
> address@hidden table
> -
> address@hidden VHDX
> -Hyper-V compatible image format (VHDX).
> -Supported options:
> address@hidden @code
> address@hidden subformat
> -Specifies which VHDX subformat to use. Valid options are
> address@hidden (default) and @code{fixed}.
> address@hidden 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
> address@hidden, which means parsers are free to return
> -arbitrary data for those blocks.  Do not set to @code{off} when using
> address@hidden convert} with @code{subformat=dynamic}.
> address@hidden block_size
> -Block size; min 1 MB, max 256 MB.  0 means auto-calculate based on image 
> size.
> address@hidden log_size
> -Log size; min 1 MB.
> address@hidden table
> address@hidden table
> -
> address@hidden Read-only formats
> -More disk image file formats are supported in a read-only mode.
> address@hidden @option
> address@hidden bochs
> -Bochs images of @code{growing} type.
> address@hidden cloop
> -Linux Compressed Loop image, useful only to reuse directly compressed
> -CD-ROM images present for example in the Knoppix CD-ROMs.
> address@hidden dmg
> -Apple disk image.
> address@hidden parallels
> -Parallels disk image format.
> address@hidden table
> -
> -
> address@hidden host_drives
> address@hidden 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.
> -
> address@hidden 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.
> -
> address@hidden @code
> address@hidden 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.
> address@hidden 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.
> address@hidden 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).
> address@hidden table
> -
> address@hidden Windows
> -
> address@hidden @code
> address@hidden 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.
> address@hidden Hard disks
> -Hard disks can be used with the syntax: @address@hidden
> -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).
> address@hidden table
> -
> -
> address@hidden Mac OS X
> -
> address@hidden/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.
> -
> address@hidden disk_images_fat_images
> address@hidden Virtual FAT disk images
> -
> -QEMU can automatically create a virtual FAT disk image from a
> -directory tree. In order to use it, just type:
> -
> address@hidden
> -qemu-system-i386 linux.img -hdb fat:/my_directory
> address@hidden 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:
> -
> address@hidden
> -qemu-system-i386 linux.img -fda fat:floppy:/my_directory
> address@hidden example
> -
> -A read/write support is available for testing (beta stage) with the
> address@hidden:rw:} option:
> -
> address@hidden
> -qemu-system-i386 linux.img -fda fat:floppy:rw:/my_directory
> address@hidden example
> -
> -What you should @emph{never} do:
> address@hidden
> address@hidden use non-ASCII filenames ;
> address@hidden use "-snapshot" together with ":rw:" ;
> address@hidden expect it to work when loadvm'ing ;
> address@hidden write to the FAT directory on the host system while accessing 
> it with the guest system.
> address@hidden itemize
> -
> address@hidden disk_images_nbd
> address@hidden NBD access
> -
> -QEMU can access directly to block device exported using the Network Block 
> Device
> -protocol.
> -
> address@hidden
> -qemu-system-i386 linux.img -hdb nbd://my_nbd_server.mydomain.org:1024/
> address@hidden example
> -
> -If the NBD server is located on the same host, you can use an unix socket 
> instead
> -of an inet socket:
> -
> address@hidden
> -qemu-system-i386 linux.img -hdb nbd+unix://?socket=/tmp/my_socket
> address@hidden example
> -
> -In this case, the block device must be exported using qemu-nbd:
> -
> address@hidden
> -qemu-nbd --socket=/tmp/my_socket my_disk.qcow2
> address@hidden example
> -
> -The use of qemu-nbd allows sharing of a disk between several guests:
> address@hidden
> -qemu-nbd --socket=/tmp/my_socket --share=2 my_disk.qcow2
> address@hidden example
> -
> address@hidden
> -and then you can use it with two guests:
> address@hidden
> -qemu-system-i386 linux1.img -hdb nbd+unix://?socket=/tmp/my_socket
> -qemu-system-i386 linux2.img -hdb nbd+unix://?socket=/tmp/my_socket
> address@hidden 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:
> address@hidden
> -qemu-system-i386 -cdrom nbd://localhost/debian-500-ppc-netinst
> -qemu-system-i386 -cdrom nbd://localhost/openSUSE-11.1-ppc-netinst
> address@hidden 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:
> address@hidden
> -qemu-system-i386 linux.img -hdb nbd:my_nbd_server.mydomain.org:1024
> -qemu-system-i386 linux2.img -hdb nbd:unix:/tmp/my_socket
> -qemu-system-i386 -cdrom nbd:localhost:10809:exportname=debian-500-ppc-netinst
> address@hidden example
> -
> address@hidden disk_images_sheepdog
> address@hidden 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:
> address@hidden
> -qemu-img create sheepdog:///@var{image} @var{size}
> address@hidden 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.
> address@hidden
> -qemu-img convert @var{filename} sheepdog:///@var{image}
> address@hidden example
> -
> -You can boot from the Sheepdog disk image with the command:
> address@hidden
> -qemu-system-i386 sheepdog:///@var{image}
> address@hidden example
> -
> -You can also create a snapshot of the Sheepdog image like qcow2.
> address@hidden
> -qemu-img snapshot -c @var{tag} sheepdog:///@var{image}
> address@hidden 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.
> address@hidden
> -qemu-system-i386 sheepdog:///@address@hidden
> address@hidden example
> -
> -You can create a cloned image from the existing snapshot.
> address@hidden
> -qemu-img create -b sheepdog:///@address@hidden sheepdog:///@var{image}
> address@hidden example
> -where @var{base} is a image name of the source snapshot and @var{tag}
> -is its tag name.
> -
> -You can use an unix socket instead of an inet socket:
> -
> address@hidden
> -qemu-system-i386 sheepdog+unix:///@address@hidden
> address@hidden example
> -
> -If the Sheepdog daemon doesn't run on the local host, you need to
> -specify one of the Sheepdog servers to connect to.
> address@hidden
> -qemu-img create sheepdog://@var{hostname}:@var{port}/@var{image} @var{size}
> -qemu-system-i386 sheepdog://@var{hostname}:@var{port}/@var{image}
> address@hidden example
> -
> address@hidden disk_images_iscsi
> address@hidden 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
> -
> address@hidden
> -URL syntax:
> -iscsi://[<username>[%<password>]@@]<host>[:<port>]/<target-iqn-name>/<lun>
> address@hidden 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
> -
> address@hidden
> -export LIBISCSI_CHAP_USERNAME=<username>
> -export LIBISCSI_CHAP_PASSWORD=<password>
> -iscsi://<host>/<target-iqn-name>/<lun>
> address@hidden 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[:<name>'] where <name> is the name of the
> -virtual machine.
> -
> -
> address@hidden
> -Setting a specific initiator name to use when logging in to the target
> --iscsi initiator-name=iqn.qemu.test:my-initiator
> address@hidden example
> -
> address@hidden
> -Controlling which type of header digest to negotiate with the target
> --iscsi header-digest=CRC32C|CRC32C-NONE|NONE-CRC32C|NONE
> address@hidden example
> -
> -These can also be set via a configuration file
> address@hidden
> -[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"
> address@hidden example
> -
> -
> -Setting the target name allows different options for different targets
> address@hidden
> -[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"
> address@hidden example
> -
> -
> -Howto use a configuration file to set iSCSI configuration options:
> address@hidden
> -cat >iscsi.conf <<EOF
> -[iscsi]
> -  user = "me"
> -  password = "my password"
> -  initiator-name = "iqn.qemu.test:my-initiator"
> -  header-digest = "CRC32C"
> -EOF
> -
> -qemu-system-i386 -drive file=iscsi://127.0.0.1/iqn.qemu.test/1 \
> -    -readconfig iscsi.conf
> address@hidden example
> -
> -
> -Howto set up a simple iSCSI target on loopback and accessing it via QEMU:
> address@hidden
> -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
> -
> -qemu-system-i386 -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
> address@hidden example
> -
> address@hidden disk_images_gluster
> address@hidden GlusterFS disk images
> -
> -GlusterFS is a user space distributed file system.
> -
> -You can boot from the GlusterFS disk image with the command:
> address@hidden
> -URI:
> -qemu-system-x86_64 -drive 
> address@hidden://address@hidden:@var{port}]]/@var{volume}/@var{path}
> -                               
> [?socket=...][,file.debug=9][,file.logfile=...]
> -
> -JSON:
> -qemu-system-x86_64 'json:@{"driver":"qcow2",
> -                           "file":@{"driver":"gluster",
> -                                    
> "volume":"testvol","path":"a.img","debug":9,"logfile":"...",
> -                                    
> "server":address@hidden"type":"tcp","host":"...","port":"..."@},
> -                                              
> @{"type":"unix","socket":"..."@address@hidden@}'
> address@hidden example
> -
> address@hidden is the protocol.
> -
> address@hidden 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.
> -
> address@hidden 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.
> -
> address@hidden 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.
> -
> address@hidden is the name of the gluster volume which contains the disk 
> image.
> -
> address@hidden is the path to the actual disk image that resides on gluster 
> volume.
> -
> address@hidden 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
> -
> address@hidden 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:
> address@hidden
> -qemu-img create gluster://@var{host}/@var{volume}/@var{path} @var{size}
> address@hidden example
> -
> -Examples
> address@hidden
> -qemu-system-x86_64 -drive file=gluster://1.2.3.4/testvol/a.img
> -qemu-system-x86_64 -drive file=gluster+tcp://1.2.3.4/testvol/a.img
> -qemu-system-x86_64 -drive file=gluster+tcp://1.2.3.4:24007/testvol/dir/a.img
> -qemu-system-x86_64 -drive 
> file=gluster+tcp://[1:2:3:4:5:6:7:8]/testvol/dir/a.img
> -qemu-system-x86_64 -drive 
> file=gluster+tcp://[1:2:3:4:5:6:7:8]:24007/testvol/dir/a.img
> -qemu-system-x86_64 -drive 
> file=gluster+tcp://server.domain.com:24007/testvol/dir/a.img
> -qemu-system-x86_64 -drive 
> file=gluster+unix:///testvol/dir/a.img?socket=/tmp/glusterd.socket
> -qemu-system-x86_64 -drive file=gluster+rdma://1.2.3.4:24007/testvol/a.img
> -qemu-system-x86_64 -drive 
> file=gluster://1.2.3.4/testvol/a.img,file.debug=9,file.logfile=/var/log/qemu-gluster.log
> -qemu-system-x86_64 'json:@{"driver":"qcow2",
> -                           "file":@{"driver":"gluster",
> -                                    "volume":"testvol","path":"a.img",
> -                                    
> "debug":9,"logfile":"/var/log/qemu-gluster.log",
> -                                    
> "server":address@hidden"type":"tcp","host":"1.2.3.4","port":address@hidden,
> -                                              
> @{"type":"unix","socket":"/var/run/glusterd.socket"@address@hidden@}'
> -qemu-system-x86_64 -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
> address@hidden example
> -
> address@hidden disk_images_ssh
> address@hidden Secure Shell (ssh) disk images
> -
> -You can access disk images located on a remote ssh server
> -by using the ssh protocol:
> -
> address@hidden
> -qemu-system-x86_64 -drive 
> file=ssh://address@hidden@@address@hidden:@var{port}]/@address@hidden
> address@hidden example
> -
> -Alternative syntax using properties:
> -
> address@hidden
> -qemu-system-x86_64 -drive 
> file.driver=ssh[,address@hidden,address@hidden,address@hidden,address@hidden,address@hidden
> address@hidden example
> -
> address@hidden is the protocol.
> -
> address@hidden is the remote user.  If not specified, then the local
> -username is tried.
> -
> address@hidden 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.
> -
> address@hidden is the port number on which sshd is listening.  By default
> -the standard ssh port (22) is used.
> -
> address@hidden 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:
> address@hidden: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 libssh2 and OpenSSH, @code{fsync} is
> -supported.
> address@hidden docs/qemu-block-drivers.texi
>  
>  @node pcsys_network
>  @section Network emulation
> 

-- 
—js