nbdkit-curl-plugin(1)

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

DEBUG FLAG

137       -D curl.verbose=1
138           This enables very verbose curl debugging.  See CURLOPT_VERBOSE(3).
139           This is mainly useful if you suspect there is a bug inside libcurl
140           itself.
141

FILES

143       $plugindir/nbdkit-curl-plugin.so
144           The plugin.
145
146           Use "nbdkit --dump-config" to find the location of $plugindir.
147

VERSION

149       "nbdkit-curl-plugin" first appeared in nbdkit 1.2.
150

AUTHORS

158       Richard W.M. Jones
159
160       Parts derived from Alexander Graf's "QEMU Block driver for CURL
161       images".
162

COPYRIGHT

164       Copyright (C) 2014 Red Hat Inc.
165

LICENSE

167       Redistribution and use in source and binary forms, with or without
168       modification, are permitted provided that the following conditions are
169       met:
170
171       ·   Redistributions of source code must retain the above copyright
172           notice, this list of conditions and the following disclaimer.
173
174       ·   Redistributions in binary form must reproduce the above copyright
175           notice, this list of conditions and the following disclaimer in the
176           documentation and/or other materials provided with the
177           distribution.
178
179       ·   Neither the name of Red Hat nor the names of its contributors may
180           be used to endorse or promote products derived from this software
181           without specific prior written permission.
182
183       THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
184       EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
185       IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
186       PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
187       LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
188       CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
189       SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
190       BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
191       WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
192       OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
193       ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
194
195
196
197nbdkit-1.18.4                     2020-04-16             nbdkit-curl-plugin(1)