1.. _sec_005finvocation: 2 3Invocation 4---------- 5 6.. parsed-literal:: 7 8 |qemu_system| [options] [disk_image] 9 10disk_image is a raw hard disk image for IDE hard disk 0. Some targets do 11not need a disk image. 12 13Device URL Syntax 14~~~~~~~~~~~~~~~~~ 15 16In addition to using normal file images for the emulated storage 17devices, QEMU can also use networked resources such as iSCSI devices. 18These 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 243