aboutsummaryrefslogtreecommitdiff
path: root/docs/system/invocation.rst
blob: c112bcb45a4437cf3e6ec7a7aaaf918e522617f2 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
.. _sec_005finvocation:

Invocation
----------

.. parsed-literal::

   |qemu_system| [options] [disk_image]

disk_image is a raw hard disk image for IDE hard disk 0. Some targets do
not need a disk image.

Device URL Syntax
~~~~~~~~~~~~~~~~~

In addition to using normal file images for the emulated storage
devices, QEMU can also use networked resources such as iSCSI devices.
These are specified using a special URL syntax.

``iSCSI``
   iSCSI support allows QEMU to access iSCSI resources directly and use
   as images for the guest storage. Both disk and cdrom images are
   supported.

   Syntax for specifying iSCSI LUNs is
   "iscsi://<target-ip>[:<port>]/<target-iqn>/<lun>"

   By default qemu will use the iSCSI initiator-name
   'iqn.2008-11.org.linux-kvm[:<name>]' but this can also be set from
   the command line or a configuration file.

   Since version Qemu 2.4 it is possible to specify a iSCSI request
   timeout to detect stalled requests and force a reestablishment of the
   session. The timeout is specified in seconds. The default is 0 which
   means no timeout. Libiscsi 1.15.0 or greater is required for this
   feature.

   Example (without authentication):

   .. parsed-literal::

      |qemu_system| -iscsi initiator-name=iqn.2001-04.com.example:my-initiator \
                       -cdrom iscsi://192.0.2.1/iqn.2001-04.com.example/2 \
                       -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1

   Example (CHAP username/password via URL):

   .. parsed-literal::

      |qemu_system| -drive file=iscsi://user%password@192.0.2.1/iqn.2001-04.com.example/1

   Example (CHAP username/password via environment variables):

   .. parsed-literal::

      LIBISCSI_CHAP_USERNAME="user" \
      LIBISCSI_CHAP_PASSWORD="password" \
      |qemu_system| -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1

``NBD``
   QEMU supports NBD (Network Block Devices) both using TCP protocol as
   well as Unix Domain Sockets. With TCP, the default port is 10809.

   Syntax for specifying a NBD device using TCP, in preferred URI form:
   "nbd://<server-ip>[:<port>]/[<export>]"

   Syntax for specifying a NBD device using Unix Domain Sockets;
   remember that '?' is a shell glob character and may need quoting:
   "nbd+unix:///[<export>]?socket=<domain-socket>"

   Older syntax that is also recognized:
   "nbd:<server-ip>:<port>[:exportname=<export>]"

   Syntax for specifying a NBD device using Unix Domain Sockets
   "nbd:unix:<domain-socket>[:exportname=<export>]"

   Example for TCP

   .. parsed-literal::

      |qemu_system| --drive file=nbd:192.0.2.1:30000

   Example for Unix Domain Sockets

   .. parsed-literal::

      |qemu_system| --drive file=nbd:unix:/tmp/nbd-socket

``SSH``
   QEMU supports SSH (Secure Shell) access to remote disks.

   Examples:

   .. parsed-literal::

      |qemu_system| -drive file=ssh://user@host/path/to/disk.img
      |qemu_system| -drive file.driver=ssh,file.user=user,file.host=host,file.port=22,file.path=/path/to/disk.img

   Currently authentication must be done using ssh-agent. Other
   authentication methods may be supported in future.

``Sheepdog``
   Sheepdog is a distributed storage system for QEMU. QEMU supports
   using either local sheepdog devices or remote networked devices.

   Syntax for specifying a sheepdog device

   ::

      sheepdog[+tcp|+unix]://[host:port]/vdiname[?socket=path][#snapid|#tag]

   Example

   .. parsed-literal::

      |qemu_system| --drive file=sheepdog://192.0.2.1:30000/MyVirtualMachine

   See also https://sheepdog.github.io/sheepdog/.

``GlusterFS``
   GlusterFS is a user space distributed file system. QEMU supports the
   use of GlusterFS volumes for hosting VM disk images using TCP, Unix
   Domain Sockets and RDMA transport protocols.

   Syntax for specifying a VM disk image on GlusterFS volume is

   .. parsed-literal::

      URI:
      gluster[+type]://[host[:port]]/volume/path[?socket=...][,debug=N][,logfile=...]

      JSON:
      'json:{"driver":"qcow2","file":{"driver":"gluster","volume":"testvol","path":"a.img","debug":N,"logfile":"...",
                                       "server":[{"type":"tcp","host":"...","port":"..."},
                                                 {"type":"unix","socket":"..."}]}}'

   Example

   .. parsed-literal::

      URI:
      |qemu_system| --drive file=gluster://192.0.2.1/testvol/a.img,
                                     file.debug=9,file.logfile=/var/log/qemu-gluster.log

      JSON:
      |qemu_system| 'json:{"driver":"qcow2",
                                "file":{"driver":"gluster",
                                         "volume":"testvol","path":"a.img",
                                         "debug":9,"logfile":"/var/log/qemu-gluster.log",
                                         "server":[{"type":"tcp","host":"1.2.3.4","port":24007},
                                                   {"type":"unix","socket":"/var/run/glusterd.socket"}]}}'
      |qemu_system| -drive driver=qcow2,file.driver=gluster,file.volume=testvol,file.path=/path/a.img,
                                            file.debug=9,file.logfile=/var/log/qemu-gluster.log,
                                            file.server.0.type=tcp,file.server.0.host=1.2.3.4,file.server.0.port=24007,
                                            file.server.1.type=unix,file.server.1.socket=/var/run/glusterd.socket

   See also http://www.gluster.org.

``HTTP/HTTPS/FTP/FTPS``
   QEMU supports read-only access to files accessed over http(s) and
   ftp(s).

   Syntax using a single filename:

   ::

      <protocol>://[<username>[:<password>]@]<host>/<path>

   where:

   ``protocol``
      'http', 'https', 'ftp', or 'ftps'.

   ``username``
      Optional username for authentication to the remote server.

   ``password``
      Optional password for authentication to the remote server.

   ``host``
      Address of the remote server.

   ``path``
      Path on the remote server, including any query string.

   The following options are also supported:

   ``url``
      The full URL when passing options to the driver explicitly.

   ``readahead``
      The amount of data to read ahead with each range request to the
      remote server. This value may optionally have the suffix 'T', 'G',
      'M', 'K', 'k' or 'b'. If it does not have a suffix, it will be
      assumed to be in bytes. The value must be a multiple of 512 bytes.
      It defaults to 256k.

   ``sslverify``
      Whether to verify the remote server's certificate when connecting
      over SSL. It can have the value 'on' or 'off'. It defaults to
      'on'.

   ``cookie``
      Send this cookie (it can also be a list of cookies separated by
      ';') with each outgoing request. Only supported when using
      protocols such as HTTP which support cookies, otherwise ignored.

   ``timeout``
      Set the timeout in seconds of the CURL connection. This timeout is
      the time that CURL waits for a response from the remote server to
      get the size of the image to be downloaded. If not set, the
      default timeout of 5 seconds is used.

   Note that when passing options to qemu explicitly, ``driver`` is the
   value of <protocol>.

   Example: boot from a remote Fedora 20 live ISO image

   .. parsed-literal::

      |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

      |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

   Example: boot from a remote Fedora 20 cloud image using a local
   overlay for writes, copy-on-read, and a readahead of 64k

   .. parsed-literal::

      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

      |qemu_system_x86| -drive file=/tmp/Fedora-x86_64-20-20131211.1-sda.qcow2,copy-on-read=on

   Example: boot from an image stored on a VMware vSphere server with a
   self-signed certificate using a local overlay for writes, a readahead
   of 64k and a timeout of 10 seconds.

   .. parsed-literal::

      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

      |qemu_system_x86| -drive file=/tmp/test.qcow2