docs/system/device-url-syntax.rst.inc

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