| 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 | ``HTTP/HTTPS/FTP/FTPS`` |
| 89 | QEMU supports read-only access to files accessed over http(s) and |
| 90 | ftp(s). |
| 91 | |
| 92 | Syntax using a single filename: |
| 93 | |
| 94 | :: |
| 95 | |
| 96 | <protocol>://[<username>[:<password>]@]<host>/<path> |
| 97 | |
| 98 | where: |
| 99 | |
| 100 | ``protocol`` |
| 101 | 'http', 'https', 'ftp', or 'ftps'. |
| 102 | |
| 103 | ``username`` |
| 104 | Optional username for authentication to the remote server. |
| 105 | |
| 106 | ``password`` |
| 107 | Optional password for authentication to the remote server. |
| 108 | |
| 109 | ``host`` |
| 110 | Address of the remote server. |
| 111 | |
| 112 | ``path`` |
| 113 | Path on the remote server, including any query string. |
| 114 | |
| 115 | The following options are also supported: |
| 116 | |
| 117 | ``url`` |
| 118 | The full URL when passing options to the driver explicitly. |
| 119 | |
| 120 | ``readahead`` |
| 121 | The amount of data to read ahead with each range request to the |
| 122 | remote server. This value may optionally have the suffix 'T', 'G', |
| 123 | 'M', 'K', 'k' or 'b'. If it does not have a suffix, it will be |
| 124 | assumed to be in bytes. The value must be a multiple of 512 bytes. |
| 125 | It defaults to 256k. |
| 126 | |
| 127 | ``sslverify`` |
| 128 | Whether to verify the remote server's certificate when connecting |
| 129 | over SSL. It can have the value 'on' or 'off'. It defaults to |
| 130 | 'on'. |
| 131 | |
| 132 | ``cookie`` |
| 133 | Send this cookie (it can also be a list of cookies separated by |
| 134 | ';') with each outgoing request. Only supported when using |
| 135 | protocols such as HTTP which support cookies, otherwise ignored. |
| 136 | |
| 137 | ``timeout`` |
| 138 | Set the timeout in seconds of the CURL connection. This timeout is |
| 139 | the time that CURL waits for a response from the remote server to |
| 140 | get the size of the image to be downloaded. If not set, the |
| 141 | default timeout of 5 seconds is used. |
| 142 | |
| 143 | ``force-range`` |
| 144 | Don't issue a HEAD HTTP request to discover if the http server |
| 145 | server supports range requests and rely only on GET requests. This |
| 146 | is especially useful for S3 presigned URLs where HEAD requests |
| 147 | are unauthorized. It defaults to 'false'. |
| 148 | |
| 149 | Note that when passing options to qemu explicitly, ``driver`` is the |
| 150 | value of <protocol>. |
| 151 | |
| 152 | Example: boot from a remote Fedora 20 live ISO image |
| 153 | |
| 154 | .. parsed-literal:: |
| 155 | |
| 156 | |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 |
| 157 | |
| 158 | |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 |
| 159 | |
| 160 | Example: boot from a remote Fedora 20 cloud image using a local |
| 161 | overlay for writes, copy-on-read, and a readahead of 64k |
| 162 | |
| 163 | .. parsed-literal:: |
| 164 | |
| 165 | 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 |
| 166 | |
| 167 | |qemu_system_x86| -drive file=/tmp/Fedora-x86_64-20-20131211.1-sda.qcow2,copy-on-read=on |
| 168 | |
| 169 | Example: boot from an image stored on a VMware vSphere server with a |
| 170 | self-signed certificate using a local overlay for writes, a readahead |
| 171 | of 64k and a timeout of 10 seconds. |
| 172 | |
| 173 | .. parsed-literal:: |
| 174 | |
| 175 | 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 |
| 176 | |
| 177 | |qemu_system_x86| -drive file=/tmp/test.qcow2 |