From 8a61770b2643a2af889205cc643d62d0ea3121f5 Mon Sep 17 00:00:00 2001

From: Fam Zheng <famz@redhat.com>

Date: Thu, 30 Nov 2017 09:25:41 +0100

Subject: [PATCH 04/36] docs: add qemu-block-drivers(7) man page

RH-Author: Fam Zheng <famz@redhat.com>

Message-id: <20171130092544.19231-3-famz@redhat.com>

Patchwork-id: 78014

O-Subject: [RHV7.5 qemu-kvm-ma PATCH 2/5] docs: add qemu-block-drivers(7) man page

Bugzilla: 1494210

RH-Acked-by: Stefan Hajnoczi <stefanha@redhat.com>

RH-Acked-by: Jeffrey Cody <jcody@redhat.com>

RH-Acked-by: John Snow <jsnow@redhat.com>

From: Stefan Hajnoczi <stefanha@redhat.com>

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 <stefanha@redhat.com>

Signed-off-by: Kevin Wolf <kwolf@redhat.com>

(cherry picked from commit 78aa8aa019b999ec07b62b322c1280a8250e44ac)

Signed-off-by: Fam Zheng <famz@redhat.com>

Signed-off-by: Miroslav Rezanina <mrezanin@redhat.com>

Conflicts:

	Makefile

Context different because we have reverted 60b412dd18362bd in downstream

(as e0425f69f13).

	qemu-doc.texi

We do s/qemu-system-i386/qemu-kvm/ everywhere in downstream docs.

---

 Makefile                     |   6 +-

 docs/qemu-block-drivers.texi | 804 +++++++++++++++++++++++++++++++++++++++++++

 qemu-doc.texi                | 781 +----------------------------------------

 3 files changed, 810 insertions(+), 781 deletions(-)

 create mode 100644 docs/qemu-block-drivers.texi

diff --git a/Makefile b/Makefile

index 312ed5e..1a773a8 100644

--- a/Makefile

+++ b/Makefile

@@ -209,6 +209,7 @@ ifdef BUILD_DOCS

 DOCS=qemu-doc.html qemu-doc.txt qemu.1 qemu-img.1 qemu-nbd.8 qemu-ga.8

 DOCS+=docs/interop/qemu-qmp-ref.html docs/interop/qemu-qmp-ref.txt docs/interop/qemu-qmp-ref.7

 DOCS+=docs/interop/qemu-ga-ref.html docs/interop/qemu-ga-ref.txt docs/interop/qemu-ga-ref.7

+DOCS+=docs/qemu-block-drivers.7

 ifdef CONFIG_LINUX

 DOCS+=kvm_stat.1

 endif

@@ -531,6 +532,7 @@ 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

 	for d in $(TARGET_DIRS); do \

 	rm -rf $$d || exit 1 ; \

         done

@@ -576,6 +578,7 @@ ifdef CONFIG_POSIX

 	$(INSTALL_DATA) qemu.1 "$(DESTDIR)$(mandir)/man1/qemu-kvm.1"

 	$(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"

@@ -725,6 +728,7 @@ qemu-img.1: qemu-img.texi qemu-option-trace.texi qemu-img-cmds.texi

 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

+docs/qemu-block-drivers.7: docs/qemu-block-drivers.texi

 html: qemu-doc.html docs/interop/qemu-qmp-ref.html docs/interop/qemu-ga-ref.html

 info: qemu-doc.info docs/interop/qemu-qmp-ref.info docs/interop/qemu-ga-ref.info

@@ -739,7 +743,7 @@ kvm_stat.1: scripts/kvm/kvm_stat.texi

 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/interop/qemu-ga-ref.dvi docs/interop/qemu-ga-ref.html \

     docs/interop/qemu-ga-ref.info docs/interop/qemu-ga-ref.pdf \

diff --git a/docs/qemu-block-drivers.texi b/docs/qemu-block-drivers.texi

new file mode 100644

index 0000000..d3b8f3b

--- /dev/null

+++ b/docs/qemu-block-drivers.texi

@@ -0,0 +1,804 @@

+@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 formats

+raw and qcow2 as well as formats that are supported for compatibility with

+older QEMU versions or other hypervisors.

+

+Depending on the image format, different options can be passed to

+@code{qemu-img create} and @code{qemu-img convert} using the @code{-o} option.

+This section describes each format and the options that are supported for it.

+

+@table @option

+@item raw

+

+Raw disk image format. This format has the advantage of

+being simple and easily exportable to all other emulators. If your

+file system supports @emph{holes} (for example in ext2 or ext3 on

+Linux or NTFS on Windows), then only the written sectors will reserve

+space. Use @code{qemu-img info} to know the real size used by the

+image or @code{ls -ls} on Unix/Linux.

+

+Supported options:

+@table @code

+@item preallocation

+Preallocation mode (allowed values: @code{off}, @code{falloc}, @code{full}).

+@code{falloc} mode preallocates space for image by calling posix_fallocate().

+@code{full} mode preallocates space for image by writing zeros to underlying

+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=0.10} uses the

+traditional image format that can be read by any QEMU since 0.10.

+@code{compat=1.1} enables image format extensions that only QEMU 1.1 and

+newer understand (this is the default). Amongst others, this includes

+zero clusters, which allow efficient copy-on-read for sparse images.

+

+@item backing_file

+File name of a base image (see @option{create} subcommand)

+@item backing_fmt

+Image format of the base image

+@item encryption

+This option is deprecated and equivalent to @code{encrypt.format=aes}

+

+@item encrypt.format

+

+If this is set to @code{luks}, it requests that the qcow2 payload (not

+qcow2 header) be encrypted using the LUKS format. The passphrase to

+use to unlock the LUKS key slot is given by the @code{encrypt.key-secret}

+parameter. LUKS encryption parameters can be tuned with the other

+@code{encrypt.*} parameters.

+

+If this is set to @code{aes}, the image is encrypted with 128-bit AES-CBC.

+The encryption key is given by the @code{encrypt.key-secret} parameter.

+This encryption format is considered to be flawed by modern cryptography

+standards, suffering from a number of design problems:

+

+@itemize @minus

+@item The AES-CBC cipher is used with predictable initialization vectors based

+on the sector number. This makes it vulnerable to chosen plaintext attacks

+which can reveal the existence of encrypted data.

+@item The user passphrase is directly used as the encryption key. A poorly

+chosen or short passphrase will compromise the security of the encryption.

+@item In the event of the passphrase being compromised there is no way to

+change the passphrase to protect data in any qcow images. The files must

+be cloned, using a different encryption passphrase in the new file. The

+original file must then be securely erased using a program like shred,

+though even this is ineffective with many modern storage technologies.

+@end itemize

+

+The use of this is no longer supported in system emulators. Support only

+remains in the command line utilities, for the purposes of data liberation

+and interoperability with old versions of QEMU. The @code{luks} format

+should be used instead.

+

+@item encrypt.key-secret

+

+Provides the ID of a @code{secret} object that contains the passphrase

+(@code{encrypt.format=luks}) or encryption key (@code{encrypt.format=aes}).

+

+@item encrypt.cipher-alg

+

+Name of the cipher algorithm and key length. Currently defaults

+to @code{aes-256}. Only used when @code{encrypt.format=luks}.

+

+@item encrypt.cipher-mode

+

+Name of the encryption mode to use. Currently defaults to @code{xts}.

+Only used when @code{encrypt.format=luks}.

+

+@item encrypt.ivgen-alg

+

+Name of the initialization vector generator algorithm. Currently defaults

+to @code{plain64}. Only used when @code{encrypt.format=luks}.

+

+@item encrypt.ivgen-hash-alg

+

+Name of the hash algorithm to use with the initialization vector generator

+(if required). Defaults to @code{sha256}. Only used when @code{encrypt.format=luks}.

+

+@item encrypt.hash-alg

+

+Name of the hash algorithm to use for PBKDF algorithm

+Defaults to @code{sha256}. Only used when @code{encrypt.format=luks}.

+

+@item encrypt.iter-time

+

+Amount of time, in milliseconds, to use for PBKDF algorithm per key slot.

+Defaults to @code{2000}. Only used when @code{encrypt.format=luks}.

+

+@item cluster_size

+Changes the qcow2 cluster size (must be between 512 and 2M). Smaller cluster

+sizes can improve the image file size whereas larger cluster sizes generally

+provide better performance.

+

+@item preallocation

+Preallocation mode (allowed values: @code{off}, @code{metadata}, @code{falloc},

+@code{full}). An image with preallocated metadata is initially larger but can

+improve performance when the image needs to grow. @code{falloc} and @code{full}

+preallocations are like the same options of @code{raw} format, but sets up

+metadata also.

+

+@item lazy_refcounts

+If this option is set to @code{on}, reference count updates are postponed with

+the goal of avoiding metadata I/O and improving performance. This is

+particularly interesting with @option{cache=writethrough} which doesn't batch

+metadata updates. The tradeoff is that after a host crash, the reference count

+tables must be rebuilt, i.e. on the next open an (automatic) @code{qemu-img

+check -r all} is required, which may take some time.

+

+This option can only be enabled if @code{compat=1.1} is specified.

+

+@item nocow

+If this option is set to @code{on}, it will turn off COW of the file. It's only

+valid on btrfs, no effect on other file systems.

+

+Btrfs has low performance when hosting a VM image file, even more when the guest

+on the VM also using btrfs as file system. Turning off COW is a way to mitigate

+this bad performance. Generally there are two ways to turn off COW on btrfs:

+a) Disable it by mounting with nodatacow, then all newly created files will be

+NOCOW. b) For an empty file, add the NOCOW file attribute. That's what this option

+does.

+

+Note: this option is only valid to new or empty files. If there is an existing

+file which is COW and has data blocks already, it couldn't be changed to NOCOW

+by setting @code{nocow=on}. One can issue @code{lsattr filename} to check if

+the NOCOW flag is set or not (Capital 'C' is NOCOW flag).

+

+@end table

+

+@item qed

+Old QEMU image format with support for backing files and compact image files

+(when your filesystem or transport medium does not support holes).

+

+When converting QED images to qcow2, you might want to consider using the

+@code{lazy_refcounts=on} option to get a more QED-like behaviour.

+

+Supported options:

+@table @code

+@item backing_file

+File name of a base image (see @option{create} subcommand).

+@item backing_fmt

+Image file format of backing file (optional).  Useful if the format cannot be

+autodetected because it has no header, like some vhd/vpc files.

+@item cluster_size

+Changes the cluster size (must be power-of-2 between 4K and 64K). Smaller

+cluster sizes can improve the image file size whereas larger cluster sizes

+generally provide better performance.

+@item table_size

+Changes the number of clusters per L1/L2 table (must be power-of-2 between 1

+and 16).  There is normally no need to change this value but this option can be

+used for performance benchmarking.

+@end table

+

+@item qcow

+Old QEMU image format with support for backing files, compact image files,

+encryption and compression.

+

+Supported options:

+@table @code

+@item backing_file

+File name of a base image (see @option{create} subcommand)

+@item encryption

+This option is deprecated and equivalent to @code{encrypt.format=aes}

+

+@item encrypt.format

+If this is set to @code{aes}, the image is encrypted with 128-bit AES-CBC.

+The encryption key is given by the @code{encrypt.key-secret} parameter.

+This encryption format is considered to be flawed by modern cryptography

+standards, suffering from a number of design problems enumerated previously

+against the @code{qcow2} image format.

+

+The use of this is no longer supported in system emulators. Support only

+remains in the command line utilities, for the purposes of data liberation

+and interoperability with old versions of QEMU.

+

+Users requiring native encryption should use the @code{qcow2} format

+instead with @code{encrypt.format=luks}.

+

+@item encrypt.key-secret

+

+Provides the ID of a @code{secret} object that contains the encryption

+key (@code{encrypt.format=aes}).

+

+@end table

+

+@item luks

+

+LUKS v1 encryption format, compatible with Linux dm-crypt/cryptsetup

+

+Supported options:

+@table @code

+

+@item key-secret

+

+Provides the ID of a @code{secret} object that contains the passphrase.

+

+@item cipher-alg

+

+Name of the cipher algorithm and key length. Currently defaults

+to @code{aes-256}.

+

+@item cipher-mode

+

+Name of the encryption mode to use. Currently defaults to @code{xts}.

+

+@item ivgen-alg

+

+Name of the initialization vector generator algorithm. Currently defaults

+to @code{plain64}.

+

+@item ivgen-hash-alg

+

+Name of the hash algorithm to use with the initialization vector generator

+(if required). Defaults to @code{sha256}.

+

+@item hash-alg

+

+Name of the hash algorithm to use for PBKDF algorithm

+Defaults to @code{sha256}.

+

+@item iter-time

+

+Amount of time, in milliseconds, to use for PBKDF algorithm per key slot.

+Defaults to @code{2000}.

+

+@end table

+

+@item vdi

+VirtualBox 1.1 compatible image format.

+Supported options:

+@table @code

+@item static

+If this option is set to @code{on}, the image is created with metadata

+preallocation.

+@end table

+

+@item vmdk

+VMware 3 and 4 compatible image format.

+

+Supported options:

+@table @code

+@item backing_file

+File name of a base image (see @option{create} subcommand).

+@item compat6

+Create a VMDK version 6 image (instead of version 4)

+@item hwversion

+Specify vmdk virtual hardware version. Compat6 flag cannot be enabled

+if hwversion is specified.

+@item subformat

+Specifies which VMDK subformat to use. Valid options are

+@code{monolithicSparse} (default),

+@code{monolithicFlat},

+@code{twoGbMaxExtentSparse},

+@code{twoGbMaxExtentFlat} and

+@code{streamOptimized}.

+@end table

+

+@item vpc

+VirtualPC compatible image format (VHD).

+Supported options:

+@table @code

+@item subformat

+Specifies which VHD subformat to use. Valid options are

+@code{dynamic} (default) and @code{fixed}.

+@end table

+

+@item VHDX

+Hyper-V compatible image format (VHDX).

+Supported options:

+@table @code

+@item subformat

+Specifies which VHDX subformat to use. Valid options are

+@code{dynamic} (default) and @code{fixed}.

+@item block_state_zero

+Force use of payload blocks of type 'ZERO'.  Can be set to @code{on} (default)

+or @code{off}.  When set to @code{off}, new blocks will be created as

+@code{PAYLOAD_BLOCK_NOT_PRESENT}, which means parsers are free to return

+arbitrary data for those blocks.  Do not set to @code{off} when using

+@code{qemu-img convert} with @code{subformat=dynamic}.

+@item block_size

+Block size; min 1 MB, max 256 MB.  0 means auto-calculate based on image size.

+@item log_size

+Log size; min 1 MB.

+@end table

+@end table

+

+@subsubsection Read-only formats

+More disk image file formats are supported in a read-only mode.

+@table @option

+@item bochs

+Bochs images of @code{growing} type.

+@item cloop

+Linux Compressed Loop image, useful only to reuse directly compressed

+CD-ROM images present for example in the Knoppix CD-ROMs.

+@item dmg

+Apple disk image.

+@item parallels

+Parallels disk image format.

+@end table

+

+

+@node host_drives

+@subsection Using host drives

+

+In addition to disk image files, QEMU can directly access host

+devices. We describe here the usage for QEMU version >= 0.8.3.

+

+@subsubsection Linux

+

+On Linux, you can directly use the host device filename instead of a

+disk image filename provided you have enough privileges to access

+it. For example, use @file{/dev/cdrom} to access to the CDROM.

+

+@table @code

+@item CD

+You can specify a CDROM device even if no CDROM is loaded. QEMU has

+specific code to detect CDROM insertion or removal. CDROM ejection by

+the guest OS is supported. Currently only data CDs are supported.

+@item Floppy

+You can specify a floppy device even if no floppy is loaded. Floppy

+removal is currently not detected accurately (if you change floppy

+without doing floppy access while the floppy is not loaded, the guest

+OS will think that the same floppy is loaded).

+Use of the host's floppy device is deprecated, and support for it will

+be removed in a future release.

+@item Hard disks

+Hard disks can be used. Normally you must specify the whole disk

+(@file{/dev/hdb} instead of @file{/dev/hdb1}) so that the guest OS can

+see it as a partitioned disk. WARNING: unless you know what you do, it

+is better to only make READ-ONLY accesses to the hard disk otherwise

+you may corrupt your host data (use the @option{-snapshot} command

+line option or modify the device permissions accordingly).

+@end table

+

+@subsubsection Windows

+

+@table @code

+@item CD

+The preferred syntax is the drive letter (e.g. @file{d:}). The

+alternate syntax @file{\\.\d:} is supported. @file{/dev/cdrom} is

+supported as an alias to the first CDROM drive.

+

+Currently there is no specific code to handle removable media, so it

+is better to use the @code{change} or @code{eject} monitor commands to

+change or eject media.

+@item Hard disks

+Hard disks can be used with the syntax: @file{\\.\PhysicalDrive@var{N}}

+where @var{N} is the drive number (0 is the first hard disk).

+

+WARNING: unless you know what you do, it is better to only make

+READ-ONLY accesses to the hard disk otherwise you may corrupt your

+host data (use the @option{-snapshot} command line so that the

+modifications are written in a temporary file).

+@end table

+

+

+@subsubsection Mac OS X

+

+@file{/dev/cdrom} is an alias to the first CDROM.

+

+Currently there is no specific code to handle removable media, so it

+is better to use the @code{change} or @code{eject} monitor commands to

+change or eject media.

+

+@node disk_images_fat_images

+@subsection Virtual FAT disk images

+

+QEMU can automatically create a virtual FAT disk image from a

+directory tree. In order to use it, just type:

+

+@example

+qemu-kvm 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-kvm 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-kvm linux.img -fda fat:floppy:rw:/my_directory

+@end example

+

+What you should @emph{never} do:

+@itemize

+@item use non-ASCII filenames ;

+@item use "-snapshot" together with ":rw:" ;

+@item expect it to work when loadvm'ing ;

+@item write to the FAT directory on the host system while accessing it with the guest system.

+@end itemize

+

+@node disk_images_nbd

+@subsection NBD access

+

+QEMU can access directly to block device exported using the Network Block Device

+protocol.

+

+@example

+qemu-kvm 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-kvm linux.img -hdb nbd+unix://?socket=/tmp/my_socket

+@end example

+

+In this case, the block device must be exported using qemu-nbd:

+

+@example

+qemu-nbd --socket=/tmp/my_socket my_disk.qcow2

+@end example

+

+The use of qemu-nbd allows sharing of a disk between several guests:

+@example

+qemu-nbd --socket=/tmp/my_socket --share=2 my_disk.qcow2

+@end example

+

+@noindent

+and then you can use it with two guests:

+@example

+qemu-kvm linux1.img -hdb nbd+unix://?socket=/tmp/my_socket

+qemu-kvm linux2.img -hdb nbd+unix://?socket=/tmp/my_socket

+@end example

+

+If the nbd-server uses named exports (supported since NBD 2.9.18, or with QEMU's

+own embedded NBD server), you must specify an export name in the URI:

+@example

+qemu-kvm -cdrom nbd://localhost/debian-500-ppc-netinst

+qemu-kvm -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-kvm linux.img -hdb nbd:my_nbd_server.mydomain.org:1024

+qemu-kvm linux2.img -hdb nbd:unix:/tmp/my_socket

+qemu-kvm -cdrom nbd:localhost:10809:exportname=debian-500-ppc-netinst

+@end example

+

+@node disk_images_sheepdog

+@subsection Sheepdog disk images

+

+Sheepdog is a distributed storage system for QEMU.  It provides highly

+available block level storage volumes that can be attached to

+QEMU-based virtual machines.

+

+You can create a Sheepdog disk image with the command:

+@example

+qemu-img create sheepdog:///@var{image} @var{size}

+@end example

+where @var{image} is the Sheepdog image name and @var{size} is its

+size.

+

+To import the existing @var{filename} to Sheepdog, you can use a

+convert command.

+@example

+qemu-img convert @var{filename} sheepdog:///@var{image}

+@end example

+

+You can boot from the Sheepdog disk image with the command:

+@example

+qemu-kvm 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-kvm 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-kvm sheepdog+unix:///@var{image}?socket=@var{path}

+@end example

+

+If the Sheepdog daemon doesn't run on the local host, you need to

+specify one of the Sheepdog servers to connect to.

+@example

+qemu-img create sheepdog://@var{hostname}:@var{port}/@var{image} @var{size}

+qemu-kvm sheepdog://@var{hostname}:@var{port}/@var{image}

+@end example

+

+@node disk_images_iscsi

+@subsection iSCSI LUNs

+

+iSCSI is a popular protocol used to access SCSI devices across a computer

+network.

+

+There are two different ways iSCSI devices can be used by QEMU.

+

+The first method is to mount the iSCSI LUN on the host, and make it appear as

+any other ordinary SCSI device on the host and then to access this device as a

+/dev/sd device from QEMU. How to do this differs between host OSes.

+

+The second method involves using the iSCSI initiator that is built into

+QEMU. This provides a mechanism that works the same way regardless of which

+host OS you are running QEMU on. This section will describe this second method

+of using iSCSI together with QEMU.

+

+In QEMU, iSCSI devices are described using special iSCSI URLs

+

+@example

+URL syntax:

+iscsi://[<username>[%<password>]@@]<host>[:<port>]/<target-iqn-name>/<lun>

+@end example

+

+Username and password are optional and only used if your target is set up

+using CHAP authentication for access control.

+Alternatively the username and password can also be set via environment

+variables to have these not show up in the process list

+

+@example

+export LIBISCSI_CHAP_USERNAME=<username>

+export LIBISCSI_CHAP_PASSWORD=<password>

+iscsi://<host>/<target-iqn-name>/<lun>

+@end example

+

+Various session related parameters can be set via special options, either

+in a configuration file provided via '-readconfig' or directly on the

+command line.

+

+If the initiator-name is not specified qemu will use a default name

+of 'iqn.2008-11.org.linux-kvm[:<uuid>'] where <uuid> is the UUID of the

+virtual machine. If the UUID is not specified qemu will use

+'iqn.2008-11.org.linux-kvm[:<name>'] where <name> is the name of the

+virtual machine.

+

+@example

+Setting a specific initiator name to use when logging in to the target

+-iscsi initiator-name=iqn.qemu.test:my-initiator

+@end example

+

+@example

+Controlling which type of header digest to negotiate with the target

+-iscsi header-digest=CRC32C|CRC32C-NONE|NONE-CRC32C|NONE

+@end example

+

+These can also be set via a configuration file

+@example

+[iscsi]

+  user = "CHAP username"

+  password = "CHAP password"

+  initiator-name = "iqn.qemu.test:my-initiator"

+  # header digest is one of CRC32C|CRC32C-NONE|NONE-CRC32C|NONE

+  header-digest = "CRC32C"

+@end example

+

+

+Setting the target name allows different options for different targets

+@example

+[iscsi "iqn.target.name"]

+  user = "CHAP username"

+  password = "CHAP password"

+  initiator-name = "iqn.qemu.test:my-initiator"

+  # header digest is one of CRC32C|CRC32C-NONE|NONE-CRC32C|NONE

+  header-digest = "CRC32C"

+@end example

+

+

+Howto use a configuration file to set iSCSI configuration options:

+@example

+cat >iscsi.conf <

+[iscsi]

+  user = "me"

+  password = "my password"

+  initiator-name = "iqn.qemu.test:my-initiator"