docs/system: convert Texinfo documentation to rST
[qemu.git] / 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