1
2In addition to using normal file images for the emulated storage
3devices, QEMU can also use networked resources such as iSCSI devices.
4These 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``GlusterFS``
89   GlusterFS is a user space distributed file system. QEMU supports the
90   use of GlusterFS volumes for hosting VM disk images using TCP and Unix
91   Domain Sockets transport protocols.
92
93   Syntax for specifying a VM disk image on GlusterFS volume is
94
95   .. parsed-literal::
96
97      URI:
98      gluster[+type]://[host[:port]]/volume/path[?socket=...][,debug=N][,logfile=...]
99
100      JSON:
101      'json:{"driver":"qcow2","file":{"driver":"gluster","volume":"testvol","path":"a.img","debug":N,"logfile":"...",
102                                       "server":[{"type":"tcp","host":"...","port":"..."},
103                                                 {"type":"unix","socket":"..."}]}}'
104
105   Example
106
107   .. parsed-literal::
108
109      URI:
110      |qemu_system| --drive file=gluster://192.0.2.1/testvol/a.img,
111                                     file.debug=9,file.logfile=/var/log/qemu-gluster.log
112
113      JSON:
114      |qemu_system| 'json:{"driver":"qcow2",
115                                "file":{"driver":"gluster",
116                                         "volume":"testvol","path":"a.img",
117                                         "debug":9,"logfile":"/var/log/qemu-gluster.log",
118                                         "server":[{"type":"tcp","host":"1.2.3.4","port":24007},
119                                                   {"type":"unix","socket":"/var/run/glusterd.socket"}]}}'
120      |qemu_system| -drive driver=qcow2,file.driver=gluster,file.volume=testvol,file.path=/path/a.img,
121                                            file.debug=9,file.logfile=/var/log/qemu-gluster.log,
122                                            file.server.0.type=tcp,file.server.0.host=1.2.3.4,file.server.0.port=24007,
123                                            file.server.1.type=unix,file.server.1.socket=/var/run/glusterd.socket
124
125   See also http://www.gluster.org.
126
127``HTTP/HTTPS/FTP/FTPS``
128   QEMU supports read-only access to files accessed over http(s) and
129   ftp(s).
130
131   Syntax using a single filename:
132
133   ::
134
135      <protocol>://[<username>[:<password>]@]<host>/<path>
136
137   where:
138
139   ``protocol``
140      'http', 'https', 'ftp', or 'ftps'.
141
142   ``username``
143      Optional username for authentication to the remote server.
144
145   ``password``
146      Optional password for authentication to the remote server.
147
148   ``host``
149      Address of the remote server.
150
151   ``path``
152      Path on the remote server, including any query string.
153
154   The following options are also supported:
155
156   ``url``
157      The full URL when passing options to the driver explicitly.
158
159   ``readahead``
160      The amount of data to read ahead with each range request to the
161      remote server. This value may optionally have the suffix 'T', 'G',
162      'M', 'K', 'k' or 'b'. If it does not have a suffix, it will be
163      assumed to be in bytes. The value must be a multiple of 512 bytes.
164      It defaults to 256k.
165
166   ``sslverify``
167      Whether to verify the remote server's certificate when connecting
168      over SSL. It can have the value 'on' or 'off'. It defaults to
169      'on'.
170
171   ``cookie``
172      Send this cookie (it can also be a list of cookies separated by
173      ';') with each outgoing request. Only supported when using
174      protocols such as HTTP which support cookies, otherwise ignored.
175
176   ``timeout``
177      Set the timeout in seconds of the CURL connection. This timeout is
178      the time that CURL waits for a response from the remote server to
179      get the size of the image to be downloaded. If not set, the
180      default timeout of 5 seconds is used.
181
182   Note that when passing options to qemu explicitly, ``driver`` is the
183   value of <protocol>.
184
185   Example: boot from a remote Fedora 20 live ISO image
186
187   .. parsed-literal::
188
189      |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
190
191      |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
192
193   Example: boot from a remote Fedora 20 cloud image using a local
194   overlay for writes, copy-on-read, and a readahead of 64k
195
196   .. parsed-literal::
197
198      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
199
200      |qemu_system_x86| -drive file=/tmp/Fedora-x86_64-20-20131211.1-sda.qcow2,copy-on-read=on
201
202   Example: boot from an image stored on a VMware vSphere server with a
203   self-signed certificate using a local overlay for writes, a readahead
204   of 64k and a timeout of 10 seconds.
205
206   .. parsed-literal::
207
208      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
209
210      |qemu_system_x86| -drive file=/tmp/test.qcow2
211