From mboxrd@z Thu Jan  1 00:00:00 1970
Received: from eggs.gnu.org ([2001:4830:134:3::10]:46351)
	by lists.gnu.org with esmtp (Exim 4.71)
	(envelope-from <mbooth@redhat.com>) id 1WiJui-0007bq-En
	for qemu-devel@nongnu.org; Thu, 08 May 2014 04:42:52 -0400
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <mbooth@redhat.com>) id 1WiJue-0003Du-1a
	for qemu-devel@nongnu.org; Thu, 08 May 2014 04:42:48 -0400
Received: from mx1.redhat.com ([209.132.183.28]:52694)
	by eggs.gnu.org with esmtp (Exim 4.71)
	(envelope-from <mbooth@redhat.com>) id 1WiJud-0003Dp-Pe
	for qemu-devel@nongnu.org; Thu, 08 May 2014 04:42:43 -0400
From: Matthew Booth <mbooth@redhat.com>
Date: Thu,  8 May 2014 09:42:19 +0100
Message-Id: <1399538540-5076-4-git-send-email-mbooth@redhat.com>
In-Reply-To: <1399538540-5076-1-git-send-email-mbooth@redhat.com>
References: <1399538540-5076-1-git-send-email-mbooth@redhat.com>
Subject: [Qemu-devel] [PATCH 3/4] curl: Add usage documentation
List-Id: <qemu-devel.nongnu.org>
List-Unsubscribe: <https://lists.nongnu.org/mailman/options/qemu-devel>,
	<mailto:qemu-devel-request@nongnu.org?subject=unsubscribe>
List-Archive: <http://lists.nongnu.org/archive/html/qemu-devel>
List-Post: <mailto:qemu-devel@nongnu.org>
List-Help: <mailto:qemu-devel-request@nongnu.org?subject=help>
List-Subscribe: <https://lists.nongnu.org/mailman/listinfo/qemu-devel>,
	<mailto:qemu-devel-request@nongnu.org?subject=subscribe>
To: qemu-devel@nongnu.org
Cc: kwolf@redhat.com, peter.maydell@linaro.org

Signed-off-by: Matthew Booth <mbooth@redhat.com>
---
 qemu-options.hx | 72 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 72 insertions(+)

diff --git a/qemu-options.hx b/qemu-options.hx
index 781af14..4cc36bf 100644
--- a/qemu-options.hx
+++ b/qemu-options.hx
@@ -2191,6 +2191,78 @@ qemu-system-x86_64 --drive file=gluster://192.0.2.1/testvol/a.img
 @end example
 
 See also @url{http://www.gluster.org}.
+
+@item HTTP/HTTPS/FTP/FTPS/TFTP
+QEMU supports read-only access to files accessed over http(s), ftp(s) and tftp.
+
+Syntax using a single filename:
+@example
+<protocol>://[<username>[:<password>]@@]<host>/<path>['['<option>=<value>:<option>=<value>...']']
+@end example
+
+where:
+@table @option
+@item protocol
+'http', 'https', 'ftp', 'ftps', or 'tftp'.
+
+@item username
+Optional username for authentication to the remote server.
+
+@item password
+Optional password for authentication to the remote server.
+
+@item host
+Address of the remote server.
+
+@item path
+Path on the remote server, including any query string.
+@end table
+
+and options are:
+@table @option
+@item 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.
+
+@item 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'.
+@end table
+
+Note that options are enclosed in square brackets. Consequently, if the remote
+URI ends with a block enclosed in square brackets, the square brackets must be
+URI escaped. Otherwise, the block will be interpreted as a set of options.
+
+When passing options to qemu explicitly, @option{driver} is the value of
+<protocol>, the entire URL, i.e.
+<protocol>://[<username>[:<password>]@@]<host>/<path>, is passed in
+@option{url}, and @option{readahead} and @option{sslverify} are passed
+separately with values as described above.
+
+Example: boot from a remote Fedora 20 live ISO image
+@example
+qemu-system-x86_64 --drive media=cdrom,file=http://dl.fedoraproject.org/pub/fedora/linux/releases/20/Live/x86_64/Fedora-Live-Desktop-x86_64-20-1.iso,readonly
+
+qemu-system-x86_64 --drive media=cdrom,file.driver=http,file.url=http://dl.fedoraproject.org/pub/fedora/linux/releases/20/Live/x86_64/Fedora-Live-Desktop-x86_64-20-1.iso,readonly
+@end example
+
+Example: boot from a remote Fedora 20 cloud image using a local overlay for
+writes, copy-on-read, and a readahead of 64k
+@example
+qemu-img create -f qcow2 -o backing_file='https://dl.fedoraproject.org/pub/fedora/linux/releases/20/Images/x86_64/Fedora-x86_64-20-20131211.1-sda.qcow2[readahead=64k]' /tmp/Fedora-x86_64-20-20131211.1-sda.qcow2
+
+qemu-system-x86_64 -drive file=/tmp/Fedora-x86_64-20-20131211.1-sda.qcow2,copy-on-read=on
+@end example
+
+Example: boot from an image stored on a VMware vSphere server with a self-signed
+certificate using a local overlay for writes and a readahead of 64k
+@example
+qemu-img create -f qcow2 -o backing_file='https://user:password@@vsphere.example.com/folder/test/test-flat.vmdk?dcPath=Datacenter&dsName=datastore1[sslverify=off:readahead=64k]' /tmp/test.qcow2
+
+qemu-system-x86_64 -drive file=/tmp/test.qcow2
+@end example
 ETEXI
 
 STEXI
-- 
1.9.0