From nobody Mon Apr 29 16:45:06 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zoho.com: domain of gnu.org designates 208.118.235.17 as permitted sender) client-ip=208.118.235.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Authentication-Results: mx.zoho.com; spf=pass (zoho.com: domain of gnu.org designates 208.118.235.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; Return-Path: Received: from lists.gnu.org (lists.gnu.org [208.118.235.17]) by mx.zohomail.com with SMTPS id 1498583917018846.961521494728; Tue, 27 Jun 2017 10:18:37 -0700 (PDT) Received: from localhost ([::1]:57243 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dPu8I-0004b1-42 for importer@patchew.org; Tue, 27 Jun 2017 13:18:34 -0400 Received: from eggs.gnu.org ([2001:4830:134:3::10]:53308) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1dPtlb-0007wp-HS for qemu-devel@nongnu.org; Tue, 27 Jun 2017 12:55:19 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1dPsco-0007Uv-ES for qemu-devel@nongnu.org; Tue, 27 Jun 2017 11:42:05 -0400 Received: from mx1.redhat.com ([209.132.183.28]:46042) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1dPsch-0006zI-8i; Tue, 27 Jun 2017 11:41:51 -0400 Received: from smtp.corp.redhat.com (int-mx06.intmail.prod.int.phx2.redhat.com [10.5.11.16]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id 24F0541A47; Tue, 27 Jun 2017 15:41:50 +0000 (UTC) Received: from localhost (ovpn-116-200.ams2.redhat.com [10.36.116.200]) by smtp.corp.redhat.com (Postfix) with ESMTP id 51FE18A8AE; Tue, 27 Jun 2017 15:41:21 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.3.2 mx1.redhat.com 24F0541A47 Authentication-Results: ext-mx06.extmail.prod.ext.phx2.redhat.com; dmarc=none (p=none dis=none) header.from=redhat.com Authentication-Results: ext-mx06.extmail.prod.ext.phx2.redhat.com; spf=pass smtp.mailfrom=stefanha@redhat.com DKIM-Filter: OpenDKIM Filter v2.11.0 mx1.redhat.com 24F0541A47 From: Stefan Hajnoczi To: Date: Tue, 27 Jun 2017 16:41:20 +0100 Message-Id: <20170627154120.20346-1-stefanha@redhat.com> X-Scanned-By: MIMEDefang 2.79 on 10.5.11.16 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.5.110.30]); Tue, 27 Jun 2017 15:41:50 +0000 (UTC) X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] [fuzzy] X-Received-From: 209.132.183.28 Subject: [Qemu-devel] [PATCH v2] docs: add qemu-block-drivers(7) man page X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Kevin Wolf , Stefan Hajnoczi , qemu-block@nongnu.org, el13635@mail.ntua.gr Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail: RSF_0 Z_629925259 SPT_0 Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" 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 Reviewed-by: John Snow --- v2: * Rebased onto qemu.git/master after Paolo's docs/ changes [jsnow] Makefile | 23 +- docs/qemu-block-drivers.texi | 692 +++++++++++++++++++++++++++++++++++++++= ++++ qemu-doc.texi | 673 +--------------------------------------= -- 3 files changed, 711 insertions(+), 677 deletions(-) create mode 100644 docs/qemu-block-drivers.texi diff --git a/Makefile b/Makefile index 16a0430..8d32d01 100644 --- a/Makefile +++ b/Makefile @@ -209,6 +209,9 @@ ifdef BUILD_DOCS DOCS=3Dqemu-doc.html qemu-doc.txt qemu.1 qemu-img.1 qemu-nbd.8 qemu-ga.8 DOCS+=3Ddocs/interop/qemu-qmp-ref.html docs/interop/qemu-qmp-ref.txt docs/= interop/qemu-qmp-ref.7 DOCS+=3Ddocs/interop/qemu-ga-ref.html docs/interop/qemu-ga-ref.txt docs/in= terop/qemu-ga-ref.7 +DOCS+=3Ddocs/qemu-block-drivers.html +DOCS+=3Ddocs/qemu-block-drivers.txt +DOCS+=3Ddocs/qemu-block-drivers.7 ifdef CONFIG_VIRTFS DOCS+=3Dfsdev/virtfs-proxy-helper.1 endif @@ -528,6 +531,8 @@ 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 docs/qemu-block-drivers.txt + rm -f docs/qemu-block-drivers.pdf docs/qemu-block-drivers.html for d in $(TARGET_DIRS); do \ rm -rf $$d || exit 1 ; \ done @@ -568,11 +573,14 @@ install-doc: $(DOCS) $(INSTALL_DATA) qemu-doc.txt "$(DESTDIR)$(qemu_docdir)" $(INSTALL_DATA) docs/interop/qemu-qmp-ref.html "$(DESTDIR)$(qemu_docdir)" $(INSTALL_DATA) docs/interop/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/interop/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" @@ -719,15 +727,15 @@ fsdev/virtfs-proxy-helper.1: fsdev/virtfs-proxy-helpe= r.texi qemu-nbd.8: qemu-nbd.texi qemu-option-trace.texi qemu-ga.8: qemu-ga.texi =20 -html: qemu-doc.html docs/interop/qemu-qmp-ref.html docs/interop/qemu-ga-re= f.html -info: qemu-doc.info docs/interop/qemu-qmp-ref.info docs/interop/qemu-ga-re= f.info -pdf: qemu-doc.pdf docs/interop/qemu-qmp-ref.pdf docs/interop/qemu-ga-ref.p= df -txt: qemu-doc.txt docs/interop/qemu-qmp-ref.txt docs/interop/qemu-ga-ref.t= xt +html: qemu-doc.html docs/interop/qemu-qmp-ref.html docs/interop/qemu-ga-re= f.html docs/qemu-block-drivers.html +info: qemu-doc.info docs/interop/qemu-qmp-ref.info docs/interop/qemu-ga-re= f.info docs/qemu-block-drivers.info +pdf: qemu-doc.pdf docs/interop/qemu-qmp-ref.pdf docs/interop/qemu-ga-ref.p= df docs/qemu-block-drivers.pdf +txt: qemu-doc.txt docs/interop/qemu-qmp-ref.txt docs/interop/qemu-ga-ref.t= xt docs/qemu-block-drivers.txt =20 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 =20 docs/interop/qemu-ga-ref.dvi docs/interop/qemu-ga-ref.html \ docs/interop/qemu-ga-ref.info docs/interop/qemu-ga-ref.pdf \ @@ -739,6 +747,11 @@ docs/interop/qemu-qmp-ref.dvi docs/interop/qemu-qmp-re= f.html \ docs/interop/qemu-qmp-ref.txt docs/interop/qemu-qmp-ref.7: \ docs/interop/qemu-qmp-ref.texi docs/interop/qemu-qmp-qapi.texi =20 +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 + =20 ifdef CONFIG_WIN32 =20 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 @@ +@c man begin SYNOPSIS +QEMU block driver reference manual +@c man end + +@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 forma= ts +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} opt= ion. +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 zeros to underlyi= ng +storage. +@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=3D0.10} uses the +traditional image format that can be read by any QEMU since 0.10. +@code{compat=3D1.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 +If this option is set to @code{on}, the image is encrypted with 128-bit AE= S-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: + +@itemize @minus +@item The AES-CBC cipher is used with predictable initialization vectors b= ased +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 + +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. + +@item cluster_size +Changes the qcow2 cluster size (must be between 512 and 2M). Smaller clust= er +sizes can improve the image file size whereas larger cluster sizes general= ly +provide better performance. + +@item preallocation +Preallocation mode (allowed values: @code{off}, @code{metadata}, @code{fal= loc}, +@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=3Dwritethrough} which doesn't = batch +metadata updates. The tradeoff is that after a host crash, the reference c= ount +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=3D1.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 mit= igate +this bad performance. Generally there are two ways to turn off COW on btrf= s: +a) Disable it by mounting with nodatacow, then all newly created files wil= l be +NOCOW. b) For an empty file, add the NOCOW file attribute. That's what thi= s option +does. + +Note: this option is only valid to new or empty files. If there is an exis= ting +file which is COW and has data blocks already, it couldn't be changed to N= OCOW +by setting @code{nocow=3Don}. One can issue @code{lsattr filename} to chec= k 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 fil= es +(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=3Don} 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 c= an 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 +If this option is set to @code{on}, the image is encrypted. +@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} (defa= ult) +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=3Ddynamic}. +@item block_size +Block size; min 1 MB, max 256 MB. 0 means auto-calculate based on image s= ize. +@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 >=3D 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 +qemu-system-i386 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 +qemu-system-i386 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 +qemu-system-i386 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 wit= h 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 +qemu-system-i386 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 +qemu-system-i386 linux.img -hdb nbd+unix://?socket=3D/tmp/my_socket +@end example + +In this case, the block device must be exported using qemu-nbd: + +@example +qemu-nbd --socket=3D/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=3D/tmp/my_socket --share=3D2 my_disk.qcow2 +@end example + +@noindent +and then you can use it with two guests: +@example +qemu-system-i386 linux1.img -hdb nbd+unix://?socket=3D/tmp/my_socket +qemu-system-i386 linux2.img -hdb nbd+unix://?socket=3D/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 +qemu-system-i386 -cdrom nbd://localhost/debian-500-ppc-netinst +qemu-system-i386 -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 +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=3Ddebian-500-ppc-ne= tinst +@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 +qemu-system-i386 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 +qemu-system-i386 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 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: + +@example +qemu-system-i386 sheepdog+unix:///@var{image}?socket=3D@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} +qemu-system-i386 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 me= thod +of using iSCSI together with QEMU. + +In QEMU, iSCSI devices are described using special iSCSI URLs + +@example +URL syntax: +iscsi://[[%]@@][:]// +@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=3D +export LIBISCSI_CHAP_PASSWORD=3D +iscsi://// +@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[:'] where is the name of the +virtual machine. + + +@example +Setting a specific initiator name to use when logging in to the target +-iscsi initiator-name=3Diqn.qemu.test:my-initiator +@end example + +@example +Controlling which type of header digest to negotiate with the target +-iscsi header-digest=3DCRC32C|CRC32C-NONE|NONE-CRC32C|NONE +@end example + +These can also be set via a configuration file +@example +[iscsi] + user =3D "CHAP username" + password =3D "CHAP password" + initiator-name =3D "iqn.qemu.test:my-initiator" + # header digest is one of CRC32C|CRC32C-NONE|NONE-CRC32C|NONE + header-digest =3D "CRC32C" +@end example + + +Setting the target name allows different options for different targets +@example +[iscsi "iqn.target.name"] + user =3D "CHAP username" + password =3D "CHAP password" + initiator-name =3D "iqn.qemu.test:my-initiator" + # header digest is one of CRC32C|CRC32C-NONE|NONE-CRC32C|NONE + header-digest =3D "CRC32C" +@end example + + +Howto use a configuration file to set iSCSI configuration options: +@example +cat >iscsi.conf <=3D 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 -qemu-system-i386 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 -qemu-system-i386 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 -qemu-system-i386 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 wit= h 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 -qemu-system-i386 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 -qemu-system-i386 linux.img -hdb nbd+unix://?socket=3D/tmp/my_socket -@end example - -In this case, the block device must be exported using qemu-nbd: - -@example -qemu-nbd --socket=3D/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=3D/tmp/my_socket --share=3D2 my_disk.qcow2 -@end example - -@noindent -and then you can use it with two guests: -@example -qemu-system-i386 linux1.img -hdb nbd+unix://?socket=3D/tmp/my_socket -qemu-system-i386 linux2.img -hdb nbd+unix://?socket=3D/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 -qemu-system-i386 -cdrom nbd://localhost/debian-500-ppc-netinst -qemu-system-i386 -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 -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=3Ddebian-500-ppc-ne= tinst -@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 -qemu-system-i386 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 -qemu-system-i386 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 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: - -@example -qemu-system-i386 sheepdog+unix:///@var{image}?socket=3D@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} -qemu-system-i386 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 me= thod -of using iSCSI together with QEMU. - -In QEMU, iSCSI devices are described using special iSCSI URLs - -@example -URL syntax: -iscsi://[[%]@@][:]// -@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=3D -export LIBISCSI_CHAP_PASSWORD=3D -iscsi://// -@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[:'] where is the name of the -virtual machine. - - -@example -Setting a specific initiator name to use when logging in to the target --iscsi initiator-name=3Diqn.qemu.test:my-initiator -@end example - -@example -Controlling which type of header digest to negotiate with the target --iscsi header-digest=3DCRC32C|CRC32C-NONE|NONE-CRC32C|NONE -@end example - -These can also be set via a configuration file -@example -[iscsi] - user =3D "CHAP username" - password =3D "CHAP password" - initiator-name =3D "iqn.qemu.test:my-initiator" - # header digest is one of CRC32C|CRC32C-NONE|NONE-CRC32C|NONE - header-digest =3D "CRC32C" -@end example - - -Setting the target name allows different options for different targets -@example -[iscsi "iqn.target.name"] - user =3D "CHAP username" - password =3D "CHAP password" - initiator-name =3D "iqn.qemu.test:my-initiator" - # header digest is one of CRC32C|CRC32C-NONE|NONE-CRC32C|NONE - header-digest =3D "CRC32C" -@end example - - -Howto use a configuration file to set iSCSI configuration options: -@example -cat >iscsi.conf <