3 nbdkit-torrent-plugin - serve a BitTorrent file or magnet link over NBD
7 nbdkit torrent FILE.torrent|'magnet:?xt=urn:...'
8 [file=DISK.iso] [cache=DIR] ...
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>.
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
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)>.
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.
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.
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.
44 =head2 Boot the Fedora installer
46 Choose the right URL from L<https://torrent.fedoraproject.org/>:
48 url=https://torrent.fedoraproject.org/torrents/Fedora-Server-dvd-x86_64-32.torrent
50 nbdkit -U - torrent Fedora-Server-*.torrent \
51 --run 'qemu-system-x86_64 -m 2048 -cdrom $nbd -boot d'
53 =head2 Boot the Debian installer
55 Choose the right URL from L<https://www.debian.org/CD/torrent-cd/>:
57 url=https://cdimage.debian.org/debian-cd/current/amd64/bt-dvd/debian-10.4.0-amd64-DVD-1.iso.torrent
59 nbdkit -U - torrent debian-*.torrent \
60 --run 'qemu-system-x86_64 -m 2048 -cdrom $nbd -boot d'
68 Set a directory which will be used to store the partially downloaded
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).
77 =item B<connections-limit=>N
79 Set limit on number of connections to other peers that this client
80 will open (default 200).
82 =item B<download-rate-limit=>BITS_PER_SEC
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.
88 =item B<file=>DISK.iso
90 Select the file from within the torrent to serve.
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.
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
102 $ nbdkit -fv -U - torrent file.torrent
104 and examining the debug output. As an alternative you can use
105 standard BitTorrent tools, eg:
107 $ transmission-show file.torrent
109 =item B<listen-interfaces=>IP_ADDRESS:PORT[,IP_ADDRESS:PORT[,...]]
111 Listening ports that are opened for accepting incoming connections.
112 The parameter is a comma-separated list of C<IP-address:port>.
114 =item B<outgoing-interfaces=>IP_ADDRESS[,IP_ADDRESS[,...]]
116 Controls which IP address outgoing TCP connections are bound to. The
117 parameter is a comma-separated list of IP addresses.
119 =item [B<torrent=>]FILEB<.torrent>
121 Specify a local torrent file.
123 =item [B<torrent=>]magnet:?xt=urn:...
125 Specify a L<magnet link|https://en.wikipedia.org/wiki/Magnet_URI_scheme>.
127 C<torrent=> is a magic config key and may be omitted in most cases.
128 See L<nbdkit(1)/Magic parameters>.
130 =item B<upload-rate-limit=>BITS_PER_SEC
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.
136 =item B<user-agent=>STRING
138 Set the user-agent. The recommended format is
139 C<client-name/client-version>.
143 =head1 ENVIRONMENT VARIABLES
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.
158 =item F<$plugindir/nbdkit-torrent-plugin.so>
162 Use C<nbdkit --dump-config> to find the location of C<$plugindir>.
168 C<nbdkit-torrent-plugin> first appeared in nbdkit 1.22.
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/>.