1nbdkit-curl-plugin(1)               NBDKIT               nbdkit-curl-plugin(1)
2
3
4

NAME

6       nbdkit-curl-plugin - nbdkit curl plugin (HTTP, FTP and other protocols)
7

SYNOPSIS

9        nbdkit -r curl [url=]http://example.com/disk.img
10

DESCRIPTION

12       "nbdkit-curl-plugin" is a plugin for nbdkit(1) which turns content
13       served over HTTP, FTP, and more, into a Network Block Device.  It uses
14       a library called libcurl (also known as cURL) to read data from URLs.
15       The exact list of protocols that libcurl can handle depends on how it
16       was compiled, but most versions will handle HTTP, HTTPS, FTP, FTPS and
17       more (see: "curl -V").
18
19       Note: This plugin supports writes.  However for HTTP, you may not want
20       nbdkit to issue PUT requests to the remote server (which probably
21       doesn't understand them).  To force nbdkit to use a readonly
22       connection, pass the -r flag.
23
24       Although this plugin can access SFTP (ie. SSH) servers, it is much
25       better to use nbdkit-ssh-plugin(1).
26

EXAMPLE

28        nbdkit -r curl http://example.com/disk.img
29
30       serves the remote disk image as NBD on TCP port 10809 (to control ports
31       and protocols used to serve NBD see nbdkit(1)).
32

PARAMETERS

34       cookie=COOKIE
35       cookie=+FILENAME
36           Set a cookie in the request header when connecting to the remote
37           server.
38
39           A typical example is:
40
41            cookie='vmware_soap_session="52a01262-bf93-ccce-d379-8dabb3e55560"'
42
43           This option can be used at most once.  It only works for HTTP and
44           HTTPS transports.  To set multiple cookies you must concatenate
45           them yourself, eg:
46
47            cookie='name1=content1; name2=content2;'
48
49           See CURLOPT_COOKIE(3) for more information about this.
50
51           If the cookie is used for authentication then passing it on the
52           command line is not secure on shared machines.  Use the alternate
53           "+FILENAME" syntax to pass it in a file.
54
55       password=PASSWORD
56           Set the password to use when connecting to the remote server.
57
58           Note that passing this on the command line is not secure on shared
59           machines.
60
61       password=-
62           Ask for the password (interactively) when nbdkit starts up.
63
64       password=+FILENAME
65           Read the password from the named file.  This is the most secure
66           method to supply a password, as long as you set the permissions on
67           the file appropriately.
68
69       protocols=PROTO,PROTO,...
70           Limit the protocols that are allowed in the URL.  Use this option
71           for extra security if the URL comes from an untrusted source and
72           you want to avoid security isues in the more obscure protocols that
73           curl supports.  (See qemu CVE-2013-0249 for an example of a
74           security bug introduced by allowing unrestricted protocols).
75
76           For example if you only intend HTTP and HTTPS URLs to be used, then
77           add this parameter: "protocols=http,https"
78
79           The value of this parameter is a comma-separated list of protocols.
80           The following protocols are known: dict, file, ftp, ftps, gopher,
81           http, https, imap, imaps, ldap, ldaps, pop3, pop3s, rtmp, rtmpe,
82           rtmps, rtmpt, rtmpte, rtmpts, rtsp, scp, sftp, smb, smbs, smtp,
83           smtps, telnet, tftp.
84
85           The default is to allow any protocol.
86
87       proxy-password=PASSWORD
88       proxy-password=-
89       proxy-password=+FILENAME
90       proxy-user=USERNAME
91           Set the proxy username and password.
92
93       sslverify=false
94           Don't verify the SSL certificate of the remote host.
95
96       timeout=SECS
97           Set the timeout for requests.
98
99       timeout=0
100           Use the default libcurl timeout for requests.
101
102       unix-socket-path=PATH
103           Instead of using a TCP connection, connect to the server over the
104           named Unix domain socket.  See "CURLOPT_UNIX_SOCKET_PATH" in
105           curl_easy_setopt(3).
106
107       [url=]URL
108           The URL of the remote disk image.  This is passed to libcurl
109           directly via "CURLOPT_URL" in curl_easy_setopt(3).
110
111           This parameter is required.
112
113           "url=" is a magic config key and may be omitted in most cases.  See
114           "Magic parameters" in nbdkit(1).
115
116       user=USERNAME
117           Set the username to use when connecting to the remote server.  This
118           may also be set in the URL (eg. "http://foo@example.com/disk.img")
119

DEBUG FLAG

121       -D curl.verbose=1
122           This enables very verbose curl debugging.  See CURLOPT_VERBOSE(3).
123           This is mainly useful if you suspect there is a bug inside libcurl
124           itself.
125

SEE ALSO

127       curl(1), libcurl(3), CURLOPT_COOKIE(3) CURLOPT_VERBOSE(3), nbdkit(1),
128       nbdkit-readahead-filter(1), nbdkit-ssh-plugin(1), nbdkit-plugin(3),
129       http://curl.haxx.se.
130

AUTHORS

132       Richard W.M. Jones
133
134       Parts derived from Alexander Graf's "QEMU Block driver for CURL
135       images".
136
138       Copyright (C) 2014 Red Hat Inc.
139

LICENSE

141       Redistribution and use in source and binary forms, with or without
142       modification, are permitted provided that the following conditions are
143       met:
144
145       ·   Redistributions of source code must retain the above copyright
146           notice, this list of conditions and the following disclaimer.
147
148       ·   Redistributions in binary form must reproduce the above copyright
149           notice, this list of conditions and the following disclaimer in the
150           documentation and/or other materials provided with the
151           distribution.
152
153       ·   Neither the name of Red Hat nor the names of its contributors may
154           be used to endorse or promote products derived from this software
155           without specific prior written permission.
156
157       THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
158       EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
159       IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
160       PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
161       LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
162       CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
163       SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
164       BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
165       WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
166       OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
167       ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
168
169
170
171nbdkit-1.12.3                     2019-05-22             nbdkit-curl-plugin(1)
Impressum