plugins/curl/nbdkit-curl-plugin.pod

   1 =head1 NAME
   2
   3 nbdkit-curl-plugin - nbdkit curl plugin (HTTP, FTP and other protocols)
   4
   5 =head1 SYNOPSIS
   6
   7  nbdkit -r curl [url=]http://example.com/disk.img
   8
   9 =head1 DESCRIPTION
  10
  11 C<nbdkit-curl-plugin> is a plugin for L<nbdkit(1)> which turns content
  12 served over HTTP, FTP, and more, into a Network Block Device.  It uses
  13 a library called libcurl (also known as cURL) to read data from URLs.
  14 The exact list of protocols that libcurl can handle depends on how it
  15 was compiled, but most versions will handle HTTP, HTTPS, FTP, FTPS and
  16 more (see: S<C<curl -V>>).
  17
  18 B<Note:> This plugin supports writes.  However for HTTP, you may not
  19 want nbdkit to issue PUT requests to the remote server (which probably
  20 doesn't understand them).  To force nbdkit to use a readonly
  21 connection, pass the I<-r> flag.
  22
  23 Although this plugin can access SFTP (ie. SSH) servers, it is much
  24 better to use L<nbdkit-ssh-plugin(1)>.
  25
  26 =head1 EXAMPLE
  27
  28  nbdkit -r curl http://example.com/disk.img
  29
  30 serves the remote disk image as NBD on TCP port 10809 (to control
  31 ports and protocols used to serve NBD see L<nbdkit(1)>).
  32
  33 =head1 PARAMETERS
  34
  35 =over 4
  36
  37 =item B<cookie=>COOKIE
  38
  39 =item B<cookie=+>FILENAME
  40
  41 Set a cookie in the request header when connecting to the remote
  42 server.
  43
  44 A typical example is:
  45
  46  cookie='vmware_soap_session="52a01262-bf93-ccce-d379-8dabb3e55560"'
  47
  48 This option can be used at most once.  It only works for HTTP and
  49 HTTPS transports.  To set multiple cookies you must concatenate them
  50 yourself, eg:
  51
  52  cookie='name1=content1; name2=content2;'
  53
  54 See L<CURLOPT_COOKIE(3)> for more information about this.
  55
  56 If the cookie is used for authentication then passing it on the
  57 command line is not secure on shared machines.  Use the alternate
  58 C<+FILENAME> syntax to pass it in a file.
  59
  60 =item B<password=>PASSWORD
  61
  62 Set the password to use when connecting to the remote server.
  63
  64 Note that passing this on the command line is not secure on shared
  65 machines.
  66
  67 =item B<password=->
  68
  69 Ask for the password (interactively) when nbdkit starts up.
  70
  71 =item B<password=+>FILENAME
  72
  73 Read the password from the named file.  This is the most secure method
  74 to supply a password, as long as you set the permissions on the file
  75 appropriately.
  76
  77 =item B<protocols=>PROTO,PROTO,...
  78
  79 Limit the protocols that are allowed in the URL.  Use this option for
  80 extra security if the URL comes from an untrusted source and you want
  81 to avoid security isues in the more obscure protocols that curl
  82 supports.  (See qemu CVE-2013-0249 for an example of a security bug
  83 introduced by allowing unrestricted protocols).
  84
  85 For example if you only intend HTTP and HTTPS URLs to be used, then
  86 add this parameter: C<protocols=http,https>
  87
  88 The value of this parameter is a comma-separated list of protocols.
  89 The following protocols are known: B<dict>, B<file>, B<ftp>, B<ftps>,
  90 B<gopher>, B<http>, B<https>, B<imap>, B<imaps>, B<ldap>, B<ldaps>,
  91 B<pop3>, B<pop3s>, B<rtmp>, B<rtmpe>, B<rtmps>, B<rtmpt>, B<rtmpte>,
  92 B<rtmpts>, B<rtsp>, B<scp>, B<sftp>, B<smb>, B<smbs>, B<smtp>,
  93 B<smtps>, B<telnet>, B<tftp>.
  94
  95 The default is to allow any protocol.
  96
  97 =item B<proxy-password=>PASSWORD
  98
  99 =item B<proxy-password=->
 100
 101 =item B<proxy-password=+>FILENAME
 102
 103 =item B<proxy-user=>USERNAME
 104
 105 Set the proxy username and password.
 106
 107 =item B<sslverify=false>
 108
 109 Don't verify the SSL certificate of the remote host.
 110
 111 =item B<timeout=>SECS
 112
 113 Set the timeout for requests.
 114
 115 =item B<timeout=0>
 116
 117 Use the default libcurl timeout for requests.
 118
 119 =item B<unix-socket-path=>PATH
 120
 121 Instead of using a TCP connection, connect to the server over the
 122 named Unix domain socket.  See
 123 L<curl_easy_setopt(3)/CURLOPT_UNIX_SOCKET_PATH>.
 124
 125 =item [B<url=>]URL
 126
 127 The URL of the remote disk image.  This is passed to libcurl directly
 128 via L<curl_easy_setopt(3)/CURLOPT_URL>.
 129
 130 This parameter is required.
 131
 132 C<url=> is a magic config key and may be omitted in most cases.
 133 See L<nbdkit(1)/Magic parameters>.
 134
 135 =item B<user=>USERNAME
 136
 137 Set the username to use when connecting to the remote server.  This
 138 may also be set in the URL (eg. C<http://foo@example.com/disk.img>)
 139
 140 =back
 141
 142 =head1 DEBUG FLAG
 143
 144 =over 4
 145
 146 =item B<-D curl.verbose=1>
 147
 148 This enables very verbose curl debugging.  See L<CURLOPT_VERBOSE(3)>.
 149 This is mainly useful if you suspect there is a bug inside libcurl
 150 itself.
 151
 152 =back
 153
 154 =head1 FILES
 155
 156 =over 4
 157
 158 =item F<$plugindir/nbdkit-curl-plugin.so>
 159
 160 The plugin.
 161
 162 Use C<nbdkit --dump-config> to find the location of C<$plugindir>.
 163
 164 =back
 165
 166 =head1 VERSION
 167
 168 C<nbdkit-curl-plugin> first appeared in nbdkit 1.2.
 169
 170 =head1 SEE ALSO
 171
 172 L<curl(1)>,
 173 L<libcurl(3)>,
 174 L<CURLOPT_COOKIE(3)>
 175 L<CURLOPT_VERBOSE(3)>,
 176 L<nbdkit(1)>,
 177 L<nbdkit-readahead-filter(1)>,
 178 L<nbdkit-retry-filter(1)>,
 179 L<nbdkit-ssh-plugin(1)>,
 180 L<nbdkit-plugin(3)>,
 181 L<http://curl.haxx.se>.
 182
 183 =head1 AUTHORS
 184
 185 Richard W.M. Jones
 186
 187 Parts derived from Alexander Graf's "QEMU Block driver for CURL images".
 188
 189 =head1 COPYRIGHT
 190
 191 Copyright (C) 2014 Red Hat Inc.