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