target/i386: reimplement 0x0f 0x10-0x17, add AVX
[qemu.git] / docs / system / device-url-syntax.rst.inc
blob7dbc525fa80f3ec0898832c58a99f09e910958ed
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.
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.
11    Syntax for specifying iSCSI LUNs is
12    "iscsi://<target-ip>[:<port>]/<target-iqn>/<lun>"
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.
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.
24    Example (without authentication):
26    .. parsed-literal::
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
32    Example (CHAP username/password via URL):
34    .. parsed-literal::
36       |qemu_system| -drive file=iscsi://user%password@192.0.2.1/iqn.2001-04.com.example/1
38    Example (CHAP username/password via environment variables):
40    .. parsed-literal::
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
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.
50    Syntax for specifying a NBD device using TCP, in preferred URI form:
51    "nbd://<server-ip>[:<port>]/[<export>]"
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>"
57    Older syntax that is also recognized:
58    "nbd:<server-ip>:<port>[:exportname=<export>]"
60    Syntax for specifying a NBD device using Unix Domain Sockets
61    "nbd:unix:<domain-socket>[:exportname=<export>]"
63    Example for TCP
65    .. parsed-literal::
67       |qemu_system| --drive file=nbd:192.0.2.1:30000
69    Example for Unix Domain Sockets
71    .. parsed-literal::
73       |qemu_system| --drive file=nbd:unix:/tmp/nbd-socket
75 ``SSH``
76    QEMU supports SSH (Secure Shell) access to remote disks.
78    Examples:
80    .. parsed-literal::
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
85    Currently authentication must be done using ssh-agent. Other
86    authentication methods may be supported in future.
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, Unix
91    Domain Sockets and RDMA transport protocols.
93    Syntax for specifying a VM disk image on GlusterFS volume is
95    .. parsed-literal::
97       URI:
98       gluster[+type]://[host[:port]]/volume/path[?socket=...][,debug=N][,logfile=...]
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":"..."}]}}'
105    Example
107    .. parsed-literal::
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
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
125    See also http://www.gluster.org.
127 ``HTTP/HTTPS/FTP/FTPS``
128    QEMU supports read-only access to files accessed over http(s) and
129    ftp(s).
131    Syntax using a single filename:
133    ::
135       <protocol>://[<username>[:<password>]@]<host>/<path>
137    where:
139    ``protocol``
140       'http', 'https', 'ftp', or 'ftps'.
142    ``username``
143       Optional username for authentication to the remote server.
145    ``password``
146       Optional password for authentication to the remote server.
148    ``host``
149       Address of the remote server.
151    ``path``
152       Path on the remote server, including any query string.
154    The following options are also supported:
156    ``url``
157       The full URL when passing options to the driver explicitly.
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.
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'.
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.
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.
182    Note that when passing options to qemu explicitly, ``driver`` is the
183    value of <protocol>.
185    Example: boot from a remote Fedora 20 live ISO image
187    .. parsed-literal::
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
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
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
196    .. parsed-literal::
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
200       |qemu_system_x86| -drive file=/tmp/Fedora-x86_64-20-20131211.1-sda.qcow2,copy-on-read=on
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.
206    .. parsed-literal::
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
210       |qemu_system_x86| -drive file=/tmp/test.qcow2