device-url-syntax.rst.inc (8079B)
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 ``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. 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