[mirror_qemu.git] / docs / system / device-url-syntax.rst.inc


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.

``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
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
5135fe71	18	Since version QEMU 2.4 it is possible to specify a iSCSI request
bf87bef0 PM	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
353a06b4 LE	28	\|qemu_system\| -iscsi initiator-name=iqn.2001-04.com.example:my-initiator \\
353a06b4 LE	29	-cdrom iscsi://192.0.2.1/iqn.2001-04.com.example/2 \\
bf87bef0 PM	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
353a06b4 LE	42	LIBISCSI_CHAP_USERNAME="user" \\
353a06b4 LE	43	LIBISCSI_CHAP_PASSWORD="password" \\
bf87bef0 PM	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
bf87bef0 PM	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