]>
Commit | Line | Data |
---|---|---|
bf87bef0 PM |
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 |