plugins/torrent/nbdkit-torrent-plugin.pod

   1 =head1 NAME
   2
   3 nbdkit-torrent-plugin - serve a BitTorrent file or magnet link over NBD
   4
   5 =head1 SYNOPSIS
   6
   7  nbdkit torrent FILE.torrent|'magnet:?xt=urn:...'
   8                 [file=DISK.iso] [cache=DIR] ...
   9
  10 =head1 DESCRIPTION
  11
  12 C<nbdkit-torrent-plugin> is an L<nbdkit(1)> plugin which lets you
  13 serve a single file from within a torrent read-only over NBD.  The
  14 torrent to download can be a local F<FILE.torrent> file, or a L<magnet
  15 link|https://en.wikipedia.org/wiki/Magnet_URI_scheme>.
  16
  17 A single torrent contains a collection of files, and by default this
  18 plugin serves the largest file within the torrent.  For operating
  19 system installers this is usually the large ISO file and ignores other
  20 small files like READMEs.  You can also select a particular file by
  21 name to serve.
  22
  23 If you want to turn a file hosted on a web server into an NBD export
  24 use L<nbdkit-curl-plugin(1)> instead.  If you have a local ISO you can
  25 simply serve it using L<nbdkit-file-plugin(1)>.  If you want to turn a
  26 local directory into an ISO use L<nbdkit-iso-plugin(1)>.
  27
  28 =head1 NOTES
  29
  30 This plugin implements a full-featured BitTorrent client.  BitTorrent
  31 clients form a peer-to-peer (p2p) network and upload the file to other
  32 clients as well as downloading.
  33
  34 By default the plugin will cache the downloaded torrent into
  35 C<$TMPDIR>, potentially consuming a lot of disk space.  See the
  36 C<cache=DIR> parameter for how to control this.
  37
  38 By default the plugin will consume all available network bandwidth in
  39 both download and upload directions.  To limit it, set
  40 C<download-rate-limit> and C<upload-rate-limit> appropriately.
  41
  42 =head1 EXAMPLES
  43
  44 =head2 Boot the Fedora installer
  45
  46 Choose the right URL from L<https://torrent.fedoraproject.org/>:
  47
  48  url=https://torrent.fedoraproject.org/torrents/Fedora-Server-dvd-x86_64-32.torrent
  49  wget $url
  50  nbdkit -U - torrent Fedora-Server-*.torrent \
  51         --run 'qemu-system-x86_64 -m 2048 -cdrom $nbd -boot d'
  52
  53 =head2 Boot the Debian installer
  54
  55 Choose the right URL from L<https://www.debian.org/CD/torrent-cd/>:
  56
  57  url=https://cdimage.debian.org/debian-cd/current/amd64/bt-dvd/debian-10.4.0-amd64-DVD-1.iso.torrent
  58  wget $url
  59  nbdkit -U - torrent debian-*.torrent \
  60         --run 'qemu-system-x86_64 -m 2048 -cdrom $nbd -boot d'
  61
  62 =head1 PARAMETERS
  63
  64 =over 4
  65
  66 =item B<cache=>DIR
  67
  68 Set a directory which will be used to store the partially downloaded
  69 torrent between runs.
  70
  71 This parameter is optional.  If I<not> given then the plugin will
  72 create a randomly named temporary directory under C<$TMPDIR>, and will
  73 attempt to ensure it is cleaned up on exit (thus unless you set
  74 C<cache>, no state is saved between runs and the whole torrent must be
  75 downloaded each time).
  76
  77 =item B<connections-limit=>N
  78
  79 Set limit on number of connections to other peers that this client
  80 will open (default 200).
  81
  82 =item B<download-rate-limit=>BITS_PER_SEC
  83
  84 Set the download rate limit in bits per second.  Usual abbreviations
  85 can be used such as C<download-rate-limit=1M> for 1 megabit per
  86 second.  C<0> means unlimited, which is the default.
  87
  88 =item B<file=>DISK.iso
  89
  90 Select the file from within the torrent to serve.
  91
  92 This parameter is optional.  If not specified then the plugin searches
  93 the torrent for the largest file and serves that.  This is usually the
  94 right thing to do for operating system installers and similar because
  95 it serves the large F<.iso> file and ignores other files like READMEs.
  96
  97 The parameter is actually a path relative to the root directory of the
  98 torrent, so if the torrent contains subdirectories you may need to use
  99 a path like C<file=SUBDIR/DISK>.  To list all the files within the
 100 torrent try running:
 101
 102  $ nbdkit -fv -U - torrent file.torrent
 103
 104 and examining the debug output.  As an alternative you can use
 105 standard BitTorrent tools, eg:
 106
 107  $ transmission-show file.torrent
 108
 109 =item B<listen-interfaces=>IP_ADDRESS:PORT[,IP_ADDRESS:PORT[,...]]
 110
 111 Listening ports that are opened for accepting incoming connections.
 112 The parameter is a comma-separated list of C<IP-address:port>.
 113
 114 =item B<outgoing-interfaces=>IP_ADDRESS[,IP_ADDRESS[,...]]
 115
 116 Controls which IP address outgoing TCP connections are bound to.  The
 117 parameter is a comma-separated list of IP addresses.
 118
 119 =item [B<torrent=>]FILEB<.torrent>
 120
 121 Specify a local torrent file.
 122
 123 =item [B<torrent=>]magnet:?xt=urn:...
 124
 125 Specify a L<magnet link|https://en.wikipedia.org/wiki/Magnet_URI_scheme>.
 126
 127 C<torrent=> is a magic config key and may be omitted in most cases.
 128 See L<nbdkit(1)/Magic parameters>.
 129
 130 =item B<upload-rate-limit=>BITS_PER_SEC
 131
 132 Set the upload rate limit in bits per second.  Usual abbreviations can
 133 be used such as C<upload-rate-limit=1M> for 1 megabit per second.
 134 C<0> means unlimited, which is the default.
 135
 136 =item B<user-agent=>STRING
 137
 138 Set the user-agent.  The recommended format is
 139 C<client-name/client-version>.
 140
 141 =back
 142
 143 =head1 ENVIRONMENT VARIABLES
 144
 145 =over 4
 146
 147 =item C<TMPDIR>
 148
 149 This directory is used to cache the downloaded torrent file (or
 150 F</var/tmp> if not set).  See also the C<cache=DIR> parameter above.
 151
 152 =back
 153
 154 =head1 FILES
 155
 156 =over 4
 157
 158 =item F<$plugindir/nbdkit-torrent-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-torrent-plugin> first appeared in nbdkit 1.22.
 169
 170 =head1 SEE ALSO
 171
 172 L<nbdkit(1)>,
 173 L<nbdkit-plugin(3)>,
 174 L<nbdkit-curl-plugin(1)>,
 175 L<nbdkit-file-plugin(1)>,
 176 L<nbdkit-iso-plugin(1)>,
 177 L<nbdkit-readahead-filter(1)>,
 178 L<nbdkit-scan-filter(1)>,
 179 L<transmission-show(1)>,
 180 L<https://en.wikipedia.org/wiki/BitTorrent>,
 181 L<http://libtorrent.org/>.
 182
 183 =head1 AUTHORS
 184
 185 Richard W.M. Jones
 186
 187 =head1 COPYRIGHT
 188
 189 Copyright Red Hat