diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/qemu-block-drivers.texi | 804 |
1 files changed, 804 insertions, 0 deletions
diff --git a/docs/qemu-block-drivers.texi b/docs/qemu-block-drivers.texi new file mode 100644 index 0000000000..1cb1e55686 --- /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-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 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-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=/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-system-i386 linux1.img -hdb nbd+unix://?socket=/tmp/my_socket +qemu-system-i386 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-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=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-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=@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 method +of using iSCSI together with QEMU. + +In QEMU, iSCSI devices are described using special iSCSI URLs + +@example +URL syntax: +iscsi://[<username>[%<password>]@@]<host>[:<port>]/<target-iqn-name>/<lun> +@end example + +Username and password are optional and only used if your target is set up +using CHAP authentication for access control. +Alternatively the username and password can also be set via environment +variables to have these not show up in the process list + +@example +export LIBISCSI_CHAP_USERNAME=<username> +export LIBISCSI_CHAP_PASSWORD=<password> +iscsi://<host>/<target-iqn-name>/<lun> +@end example + +Various session related parameters can be set via special options, either +in a configuration file provided via '-readconfig' or directly on the +command line. + +If the initiator-name is not specified qemu will use a default name +of 'iqn.2008-11.org.linux-kvm[:<uuid>'] where <uuid> is the UUID of the +virtual machine. If the UUID is not specified qemu will use +'iqn.2008-11.org.linux-kvm[:<name>'] where <name> is the name of the +virtual machine. + +@example +Setting a specific initiator name to use when logging in to the target +-iscsi initiator-name=iqn.qemu.test:my-initiator +@end example + +@example +Controlling which type of header digest to negotiate with the target +-iscsi header-digest=CRC32C|CRC32C-NONE|NONE-CRC32C|NONE +@end example + +These can also be set via a configuration file +@example +[iscsi] + user = "CHAP username" + password = "CHAP password" + initiator-name = "iqn.qemu.test:my-initiator" + # header digest is one of CRC32C|CRC32C-NONE|NONE-CRC32C|NONE + header-digest = "CRC32C" +@end example + + +Setting the target name allows different options for different targets +@example +[iscsi "iqn.target.name"] + user = "CHAP username" + password = "CHAP password" + initiator-name = "iqn.qemu.test:my-initiator" + # header digest is one of CRC32C|CRC32C-NONE|NONE-CRC32C|NONE + header-digest = "CRC32C" +@end example + + +Howto use a configuration file to set iSCSI configuration options: +@example +cat >iscsi.conf <<EOF +[iscsi] + user = "me" + password = "my password" + initiator-name = "iqn.qemu.test:my-initiator" + header-digest = "CRC32C" +EOF + +qemu-system-i386 -drive file=iscsi://127.0.0.1/iqn.qemu.test/1 \ + -readconfig iscsi.conf +@end example + + +Howto set up a simple iSCSI target on loopback and accessing it via QEMU: +@example +This example shows how to set up an iSCSI target with one CDROM and one DISK +using the Linux STGT software target. This target is available on Red Hat based +systems as the package 'scsi-target-utils'. + +tgtd --iscsi portal=127.0.0.1:3260 +tgtadm --lld iscsi --op new --mode target --tid 1 -T iqn.qemu.test +tgtadm --lld iscsi --mode logicalunit --op new --tid 1 --lun 1 \ + -b /IMAGES/disk.img --device-type=disk +tgtadm --lld iscsi --mode logicalunit --op new --tid 1 --lun 2 \ + -b /IMAGES/cd.iso --device-type=cd +tgtadm --lld iscsi --op bind --mode target --tid 1 -I ALL + +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 +@end example + +@node disk_images_gluster +@subsection GlusterFS disk images + +GlusterFS is a user space distributed file system. + +You can boot from the GlusterFS disk image with the command: +@example +URI: +qemu-system-x86_64 -drive file=gluster[+@var{type}]://[@var{host}[:@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":[@{"type":"tcp","host":"...","port":"..."@}, + @{"type":"unix","socket":"..."@}]@}@}' +@end example + +@var{gluster} is the protocol. + +@var{type} specifies the transport type used to connect to gluster +management daemon (glusterd). Valid transport types are +tcp and unix. In the URI form, if a transport type isn't specified, +then tcp type is assumed. + +@var{host} specifies the server where the volume file specification for +the given volume resides. This can be either a hostname or an ipv4 address. +If transport type is unix, then @var{host} field should not be specified. +Instead @var{socket} field needs to be populated with the path to unix domain +socket. + +@var{port} is the port number on which glusterd is listening. This is optional +and if not specified, it defaults to port 24007. If the transport type is unix, +then @var{port} should not be specified. + +@var{volume} is the name of the gluster volume which contains the disk image. + +@var{path} is the path to the actual disk image that resides on gluster volume. + +@var{debug} is the logging level of the gluster protocol driver. Debug levels +are 0-9, with 9 being the most verbose, and 0 representing no debugging output. +The default level is 4. The current logging levels defined in the gluster source +are 0 - None, 1 - Emergency, 2 - Alert, 3 - Critical, 4 - Error, 5 - Warning, +6 - Notice, 7 - Info, 8 - Debug, 9 - Trace + +@var{logfile} is a commandline option to mention log file path which helps in +logging to the specified file and also help in persisting the gfapi logs. The +default is stderr. + + + + +You can create a GlusterFS disk image with the command: +@example +qemu-img create gluster://@var{host}/@var{volume}/@var{path} @var{size} +@end example + +Examples +@example +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":[@{"type":"tcp","host":"1.2.3.4","port":24007@}, + @{"type":"unix","socket":"/var/run/glusterd.socket"@}]@}@}' +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 +@end example + +@node disk_images_ssh +@subsection Secure Shell (ssh) disk images + +You can access disk images located on a remote ssh server +by using the ssh protocol: + +@example +qemu-system-x86_64 -drive file=ssh://[@var{user}@@]@var{server}[:@var{port}]/@var{path}[?host_key_check=@var{host_key_check}] +@end example + +Alternative syntax using properties: + +@example +qemu-system-x86_64 -drive file.driver=ssh[,file.user=@var{user}],file.host=@var{server}[,file.port=@var{port}],file.path=@var{path}[,file.host_key_check=@var{host_key_check}] +@end example + +@var{ssh} is the protocol. + +@var{user} is the remote user. If not specified, then the local +username is tried. + +@var{server} specifies the remote ssh server. Any ssh server can be +used, but it must implement the sftp-server protocol. Most Unix/Linux +systems should work without requiring any extra configuration. + +@var{port} is the port number on which sshd is listening. By default +the standard ssh port (22) is used. + +@var{path} is the path to the disk image. + +The optional @var{host_key_check} parameter controls how the remote +host's key is checked. The default is @code{yes} which means to use +the local @file{.ssh/known_hosts} file. Setting this to @code{no} +turns off known-hosts checking. Or you can check that the host key +matches a specific fingerprint: +@code{host_key_check=md5:78:45:8e:14:57:4f:d5:45:83:0a:0e:f3:49:82:c9:c8} +(@code{sha1:} can also be used as a prefix, but note that OpenSSH +tools only use MD5 to print fingerprints). + +Currently authentication must be done using ssh-agent. Other +authentication methods may be supported in future. + +Note: Many ssh servers do not support an @code{fsync}-style operation. +The ssh driver cannot guarantee that disk flush requests are +obeyed, and this causes a risk of disk corruption if the remote +server or network goes down during writes. The driver will +print a warning when @code{fsync} is not supported: + +warning: ssh server @code{ssh.example.com:22} does not support fsync + +With sufficiently new versions of libssh2 and OpenSSH, @code{fsync} is +supported. + +@c man end + +@ignore + +@setfilename qemu-block-drivers +@settitle QEMU block drivers reference + +@c man begin SEEALSO +The HTML documentation of QEMU for more precise information and Linux +user mode emulator invocation. +@c man end + +@c man begin AUTHOR +Fabrice Bellard and the QEMU Project developers +@c man end + +@end ignore |