@node sec_invocation @section Invocation @example @c man begin SYNOPSIS @command{@value{qemu_system}} [@var{options}] [@var{disk_image}] @c man end @end example @c man begin OPTIONS @var{disk_image} is a raw hard disk image for IDE hard disk 0. Some targets do not need a disk image. @include qemu-options.texi @c man end @subsection Device URL Syntax @c TODO merge this with section Disk Images @c man begin NOTES In addition to using normal file images for the emulated storage devices, QEMU can also use networked resources such as iSCSI devices. These are specified using a special URL syntax. @table @option @item iSCSI iSCSI support allows QEMU to access iSCSI resources directly and use as images for the guest storage. Both disk and cdrom images are supported. Syntax for specifying iSCSI LUNs is ``iscsi://[:]//'' By default qemu will use the iSCSI initiator-name 'iqn.2008-11.org.linux-kvm[:]' but this can also be set from the command line or a configuration file. Since version Qemu 2.4 it is possible to specify a iSCSI request timeout to detect stalled requests and force a reestablishment of the session. The timeout is specified in seconds. The default is 0 which means no timeout. Libiscsi 1.15.0 or greater is required for this feature. Example (without authentication): @example @value{qemu_system} -iscsi initiator-name=iqn.2001-04.com.example:my-initiator \ -cdrom iscsi://192.0.2.1/iqn.2001-04.com.example/2 \ -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1 @end example Example (CHAP username/password via URL): @example @value{qemu_system} -drive file=iscsi://user%password@@192.0.2.1/iqn.2001-04.com.example/1 @end example Example (CHAP username/password via environment variables): @example LIBISCSI_CHAP_USERNAME="user" \ LIBISCSI_CHAP_PASSWORD="password" \ @value{qemu_system} -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1 @end example @item NBD QEMU supports NBD (Network Block Devices) both using TCP protocol as well as Unix Domain Sockets. With TCP, the default port is 10809. Syntax for specifying a NBD device using TCP, in preferred URI form: ``nbd://[:]/[]'' Syntax for specifying a NBD device using Unix Domain Sockets; remember that '?' is a shell glob character and may need quoting: ``nbd+unix:///[]?socket='' Older syntax that is also recognized: ``nbd::[:exportname=]'' Syntax for specifying a NBD device using Unix Domain Sockets ``nbd:unix:[:exportname=]'' Example for TCP @example @value{qemu_system} --drive file=nbd:192.0.2.1:30000 @end example Example for Unix Domain Sockets @example @value{qemu_system} --drive file=nbd:unix:/tmp/nbd-socket @end example @item SSH QEMU supports SSH (Secure Shell) access to remote disks. Examples: @example @value{qemu_system} -drive file=ssh://user@@host/path/to/disk.img @value{qemu_system} -drive file.driver=ssh,file.user=user,file.host=host,file.port=22,file.path=/path/to/disk.img @end example Currently authentication must be done using ssh-agent. Other authentication methods may be supported in future. @item Sheepdog Sheepdog is a distributed storage system for QEMU. QEMU supports using either local sheepdog devices or remote networked devices. Syntax for specifying a sheepdog device @example sheepdog[+tcp|+unix]://[host:port]/vdiname[?socket=path][#snapid|#tag] @end example Example @example @value{qemu_system} --drive file=sheepdog://192.0.2.1:30000/MyVirtualMachine @end example See also @url{https://sheepdog.github.io/sheepdog/}. @item GlusterFS GlusterFS is a user space distributed file system. QEMU supports the use of GlusterFS volumes for hosting VM disk images using TCP, Unix Domain Sockets and RDMA transport protocols. Syntax for specifying a VM disk image on GlusterFS volume is @example URI: gluster[+type]://[host[:port]]/volume/path[?socket=...][,debug=N][,logfile=...] JSON: 'json:@{"driver":"qcow2","file":@{"driver":"gluster","volume":"testvol","path":"a.img","debug":N,"logfile":"...", @ "server":[@{"type":"tcp","host":"...","port":"..."@}, @ @{"type":"unix","socket":"..."@}]@}@}' @end example Example @example URI: @value{qemu_system} --drive file=gluster://192.0.2.1/testvol/a.img, @ file.debug=9,file.logfile=/var/log/qemu-gluster.log JSON: @value{qemu_system} 'json:@{"driver":"qcow2", @ "file":@{"driver":"gluster", @ "volume":"testvol","path":"a.img", @ "debug":9,"logfile":"/var/log/qemu-gluster.log", @ "server":[@{"type":"tcp","host":"1.2.3.4","port":24007@}, @ @{"type":"unix","socket":"/var/run/glusterd.socket"@}]@}@}' @value{qemu_system} -drive driver=qcow2,file.driver=gluster,file.volume=testvol,file.path=/path/a.img, @ file.debug=9,file.logfile=/var/log/qemu-gluster.log, @ file.server.0.type=tcp,file.server.0.host=1.2.3.4,file.server.0.port=24007, @ file.server.1.type=unix,file.server.1.socket=/var/run/glusterd.socket @end example See also @url{http://www.gluster.org}. @item HTTP/HTTPS/FTP/FTPS QEMU supports read-only access to files accessed over http(s) and ftp(s). Syntax using a single filename: @example ://[[:]@@]/ @end example where: @table @option @item protocol 'http', 'https', 'ftp', or 'ftps'. @item username Optional username for authentication to the remote server. @item password Optional password for authentication to the remote server. @item host Address of the remote server. @item path Path on the remote server, including any query string. @end table The following options are also supported: @table @option @item url The full URL when passing options to the driver explicitly. @item readahead The amount of data to read ahead with each range request to the remote server. This value may optionally have the suffix 'T', 'G', 'M', 'K', 'k' or 'b'. If it does not have a suffix, it will be assumed to be in bytes. The value must be a multiple of 512 bytes. It defaults to 256k. @item sslverify Whether to verify the remote server's certificate when connecting over SSL. It can have the value 'on' or 'off'. It defaults to 'on'. @item cookie Send this cookie (it can also be a list of cookies separated by ';') with each outgoing request. Only supported when using protocols such as HTTP which support cookies, otherwise ignored. @item timeout Set the timeout in seconds of the CURL connection. This timeout is the time that CURL waits for a response from the remote server to get the size of the image to be downloaded. If not set, the default timeout of 5 seconds is used. @end table Note that when passing options to qemu explicitly, @option{driver} is the value of . Example: boot from a remote Fedora 20 live ISO image @example @value{qemu_system_x86} --drive media=cdrom,file=https://archives.fedoraproject.org/pub/archive/fedora/linux/releases/20/Live/x86_64/Fedora-Live-Desktop-x86_64-20-1.iso,readonly @value{qemu_system_x86} --drive media=cdrom,file.driver=http,file.url=http://archives.fedoraproject.org/pub/fedora/linux/releases/20/Live/x86_64/Fedora-Live-Desktop-x86_64-20-1.iso,readonly @end example Example: boot from a remote Fedora 20 cloud image using a local overlay for writes, copy-on-read, and a readahead of 64k @example qemu-img create -f qcow2 -o backing_file='json:@{"file.driver":"http",, "file.url":"http://archives.fedoraproject.org/pub/archive/fedora/linux/releases/20/Images/x86_64/Fedora-x86_64-20-20131211.1-sda.qcow2",, "file.readahead":"64k"@}' /tmp/Fedora-x86_64-20-20131211.1-sda.qcow2 @value{qemu_system_x86} -drive file=/tmp/Fedora-x86_64-20-20131211.1-sda.qcow2,copy-on-read=on @end example Example: boot from an image stored on a VMware vSphere server with a self-signed certificate using a local overlay for writes, a readahead of 64k and a timeout of 10 seconds. @example qemu-img create -f qcow2 -o backing_file='json:@{"file.driver":"https",, "file.url":"https://user:password@@vsphere.example.com/folder/test/test-flat.vmdk?dcPath=Datacenter&dsName=datastore1",, "file.sslverify":"off",, "file.readahead":"64k",, "file.timeout":10@}' /tmp/test.qcow2 @value{qemu_system_x86} -drive file=/tmp/test.qcow2 @end example @end table @c man end