docs/system/invocation.rst

   1 .. _sec_005finvocation:
   2
   3 Invocation
   4 ----------
   5
   6 .. parsed-literal::
   7
   8    |qemu_system| [options] [disk_image]
   9
  10 disk_image is a raw hard disk image for IDE hard disk 0. Some targets do
  11 not need a disk image.
  12
  13 Device URL Syntax
  14 ~~~~~~~~~~~~~~~~~
  15
  16 In addition to using normal file images for the emulated storage
  17 devices, QEMU can also use networked resources such as iSCSI devices.
  18 These are specified using a special URL syntax.
  19
  20 ``iSCSI``
  21    iSCSI support allows QEMU to access iSCSI resources directly and use
  22    as images for the guest storage. Both disk and cdrom images are
  23    supported.
  24
  25    Syntax for specifying iSCSI LUNs is
  26    "iscsi://<target-ip>[:<port>]/<target-iqn>/<lun>"
  27
  28    By default qemu will use the iSCSI initiator-name
  29    'iqn.2008-11.org.linux-kvm[:<name>]' but this can also be set from
  30    the command line or a configuration file.
  31
  32    Since version Qemu 2.4 it is possible to specify a iSCSI request
  33    timeout to detect stalled requests and force a reestablishment of the
  34    session. The timeout is specified in seconds. The default is 0 which
  35    means no timeout. Libiscsi 1.15.0 or greater is required for this
  36    feature.
  37
  38    Example (without authentication):
  39
  40    .. parsed-literal::
  41
  42       |qemu_system| -iscsi initiator-name=iqn.2001-04.com.example:my-initiator \
  43                        -cdrom iscsi://192.0.2.1/iqn.2001-04.com.example/2 \
  44                        -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
  45
  46    Example (CHAP username/password via URL):
  47
  48    .. parsed-literal::
  49
  50       |qemu_system| -drive file=iscsi://user%password@192.0.2.1/iqn.2001-04.com.example/1
  51
  52    Example (CHAP username/password via environment variables):
  53
  54    .. parsed-literal::
  55
  56       LIBISCSI_CHAP_USERNAME="user" \
  57       LIBISCSI_CHAP_PASSWORD="password" \
  58       |qemu_system| -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1
  59
  60 ``NBD``
  61    QEMU supports NBD (Network Block Devices) both using TCP protocol as
  62    well as Unix Domain Sockets. With TCP, the default port is 10809.
  63
  64    Syntax for specifying a NBD device using TCP, in preferred URI form:
  65    "nbd://<server-ip>[:<port>]/[<export>]"
  66
  67    Syntax for specifying a NBD device using Unix Domain Sockets;
  68    remember that '?' is a shell glob character and may need quoting:
  69    "nbd+unix:///[<export>]?socket=<domain-socket>"
  70
  71    Older syntax that is also recognized:
  72    "nbd:<server-ip>:<port>[:exportname=<export>]"
  73
  74    Syntax for specifying a NBD device using Unix Domain Sockets
  75    "nbd:unix:<domain-socket>[:exportname=<export>]"
  76
  77    Example for TCP
  78
  79    .. parsed-literal::
  80
  81       |qemu_system| --drive file=nbd:192.0.2.1:30000
  82
  83    Example for Unix Domain Sockets
  84
  85    .. parsed-literal::
  86
  87       |qemu_system| --drive file=nbd:unix:/tmp/nbd-socket
  88
  89 ``SSH``
  90    QEMU supports SSH (Secure Shell) access to remote disks.
  91
  92    Examples:
  93
  94    .. parsed-literal::
  95
  96       |qemu_system| -drive file=ssh://user@host/path/to/disk.img
  97       |qemu_system| -drive file.driver=ssh,file.user=user,file.host=host,file.port=22,file.path=/path/to/disk.img
  98
  99    Currently authentication must be done using ssh-agent. Other
 100    authentication methods may be supported in future.
 101
 102 ``Sheepdog``
 103    Sheepdog is a distributed storage system for QEMU. QEMU supports
 104    using either local sheepdog devices or remote networked devices.
 105
 106    Syntax for specifying a sheepdog device
 107
 108    ::
 109
 110       sheepdog[+tcp|+unix]://[host:port]/vdiname[?socket=path][#snapid|#tag]
 111
 112    Example
 113
 114    .. parsed-literal::
 115
 116       |qemu_system| --drive file=sheepdog://192.0.2.1:30000/MyVirtualMachine
 117
 118    See also https://sheepdog.github.io/sheepdog/.
 119
 120 ``GlusterFS``
 121    GlusterFS is a user space distributed file system. QEMU supports the
 122    use of GlusterFS volumes for hosting VM disk images using TCP, Unix
 123    Domain Sockets and RDMA transport protocols.
 124
 125    Syntax for specifying a VM disk image on GlusterFS volume is
 126
 127    .. parsed-literal::
 128
 129       URI:
 130       gluster[+type]://[host[:port]]/volume/path[?socket=...][,debug=N][,logfile=...]
 131
 132       JSON:
 133       'json:{"driver":"qcow2","file":{"driver":"gluster","volume":"testvol","path":"a.img","debug":N,"logfile":"...",
 134                                        "server":[{"type":"tcp","host":"...","port":"..."},
 135                                                  {"type":"unix","socket":"..."}]}}'
 136
 137    Example
 138
 139    .. parsed-literal::
 140
 141       URI:
 142       |qemu_system| --drive file=gluster://192.0.2.1/testvol/a.img,
 143                                      file.debug=9,file.logfile=/var/log/qemu-gluster.log
 144
 145       JSON:
 146       |qemu_system| 'json:{"driver":"qcow2",
 147                                 "file":{"driver":"gluster",
 148                                          "volume":"testvol","path":"a.img",
 149                                          "debug":9,"logfile":"/var/log/qemu-gluster.log",
 150                                          "server":[{"type":"tcp","host":"1.2.3.4","port":24007},
 151                                                    {"type":"unix","socket":"/var/run/glusterd.socket"}]}}'
 152       |qemu_system| -drive driver=qcow2,file.driver=gluster,file.volume=testvol,file.path=/path/a.img,
 153                                             file.debug=9,file.logfile=/var/log/qemu-gluster.log,
 154                                             file.server.0.type=tcp,file.server.0.host=1.2.3.4,file.server.0.port=24007,
 155                                             file.server.1.type=unix,file.server.1.socket=/var/run/glusterd.socket
 156
 157    See also http://www.gluster.org.
 158
 159 ``HTTP/HTTPS/FTP/FTPS``
 160    QEMU supports read-only access to files accessed over http(s) and
 161    ftp(s).
 162
 163    Syntax using a single filename:
 164
 165    ::
 166
 167       <protocol>://[<username>[:<password>]@]<host>/<path>
 168
 169    where:
 170
 171    ``protocol``
 172       'http', 'https', 'ftp', or 'ftps'.
 173
 174    ``username``
 175       Optional username for authentication to the remote server.
 176
 177    ``password``
 178       Optional password for authentication to the remote server.
 179
 180    ``host``
 181       Address of the remote server.
 182
 183    ``path``
 184       Path on the remote server, including any query string.
 185
 186    The following options are also supported:
 187
 188    ``url``
 189       The full URL when passing options to the driver explicitly.
 190
 191    ``readahead``
 192       The amount of data to read ahead with each range request to the
 193       remote server. This value may optionally have the suffix 'T', 'G',
 194       'M', 'K', 'k' or 'b'. If it does not have a suffix, it will be
 195       assumed to be in bytes. The value must be a multiple of 512 bytes.
 196       It defaults to 256k.
 197
 198    ``sslverify``
 199       Whether to verify the remote server's certificate when connecting
 200       over SSL. It can have the value 'on' or 'off'. It defaults to
 201       'on'.
 202
 203    ``cookie``
 204       Send this cookie (it can also be a list of cookies separated by
 205       ';') with each outgoing request. Only supported when using
 206       protocols such as HTTP which support cookies, otherwise ignored.
 207
 208    ``timeout``
 209       Set the timeout in seconds of the CURL connection. This timeout is
 210       the time that CURL waits for a response from the remote server to
 211       get the size of the image to be downloaded. If not set, the
 212       default timeout of 5 seconds is used.
 213
 214    Note that when passing options to qemu explicitly, ``driver`` is the
 215    value of <protocol>.
 216
 217    Example: boot from a remote Fedora 20 live ISO image
 218
 219    .. parsed-literal::
 220
 221       |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
 222
 223       |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
 224
 225    Example: boot from a remote Fedora 20 cloud image using a local
 226    overlay for writes, copy-on-read, and a readahead of 64k
 227
 228    .. parsed-literal::
 229
 230       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
 231
 232       |qemu_system_x86| -drive file=/tmp/Fedora-x86_64-20-20131211.1-sda.qcow2,copy-on-read=on
 233
 234    Example: boot from an image stored on a VMware vSphere server with a
 235    self-signed certificate using a local overlay for writes, a readahead
 236    of 64k and a timeout of 10 seconds.
 237
 238    .. parsed-literal::
 239
 240       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
 241
 242       |qemu_system_x86| -drive file=/tmp/test.qcow2