nbdkit-torrent-plugin(1)

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

NAME

6       nbdkit-torrent-plugin - serve a BitTorrent file or magnet link over NBD
7

SYNOPSIS

9        nbdkit torrent FILE.torrent|'magnet:?xt=urn:...'
10                       [file=DISK.iso] [cache=DIR] ...
11

DESCRIPTION

13       "nbdkit-torrent-plugin" is an nbdkit(1) plugin which lets you serve a
14       single file from within a torrent read-only over NBD.  The torrent to
15       download can be a local FILE.torrent file, or a magnet link.
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 nbdkit-curl-plugin(1) instead.  If you have a local ISO you can
25       simply serve it using nbdkit-file-plugin(1).  If you want to turn a
26       local directory into an ISO use nbdkit-iso-plugin(1).
27

NOTES

29       This plugin implements a full-featured BitTorrent client.  BitTorrent
30       clients form a peer-to-peer (p2p) network and upload the file to other
31       clients as well as downloading.
32
33       By default the plugin will cache the downloaded torrent into $TMPDIR,
34       potentially consuming a lot of disk space.  See the "cache=DIR"
35       parameter for how to control this.
36
37       By default the plugin will consume all available network bandwidth in
38       both download and upload directions.  To limit it, set
39       "download-rate-limit" and "upload-rate-limit" appropriately.
40

EXAMPLES

42   Boot the Fedora installer
43       Choose the right URL from https://torrent.fedoraproject.org/:
44
45        url=https://torrent.fedoraproject.org/torrents/Fedora-Server-dvd-x86_64-32.torrent
46        wget $url
47        nbdkit -U - torrent Fedora-Server-*.torrent \
48               --run 'qemu-system-x86_64 -m 2048 -cdrom $nbd -boot d'
49
50   Boot the Debian installer
51       Choose the right URL from https://www.debian.org/CD/torrent-cd/:
52
53        url=https://cdimage.debian.org/debian-cd/current/amd64/bt-dvd/debian-10.4.0-amd64-DVD-1.iso.torrent
54        wget $url
55        nbdkit -U - torrent debian-*.torrent \
56               --run 'qemu-system-x86_64 -m 2048 -cdrom $nbd -boot d'
57

PARAMETERS

59       cache=DIR
60           Set a directory which will be used to store the partially
61           downloaded torrent between runs.
62
63           This parameter is optional.  If not given then the plugin will
64           create a randomly named temporary directory under $TMPDIR, and will
65           attempt to ensure it is cleaned up on exit (thus unless you set
66           "cache", no state is saved between runs and the whole torrent must
67           be downloaded each time).
68
69       connections-limit=N
70           Set limit on number of connections to other peers that this client
71           will open (default 200).
72
73       download-rate-limit=BITS_PER_SEC
74           Set the download rate limit in bits per second.  Usual
75           abbreviations can be used such as "download-rate-limit=1M" for 1
76           megabit per second.  0 means unlimited, which is the default.
77
78       file=DISK.iso
79           Select the file from within the torrent to serve.
80
81           This parameter is optional.  If not specified then the plugin
82           searches the torrent for the largest file and serves that.  This is
83           usually the right thing to do for operating system installers and
84           similar because it serves the large .iso file and ignores other
85           files like READMEs.
86
87           The parameter is actually a path relative to the root directory of
88           the torrent, so if the torrent contains subdirectories you may need
89           to use a path like "file=SUBDIR/DISK".  To list all the files
90           within the torrent try running:
91
92            $ nbdkit -fv -U - torrent file.torrent
93
94           and examining the debug output.  As an alternative you can use
95           standard BitTorrent tools, eg:
96
97            $ transmission-show file.torrent
98
99       listen-interfaces=IP_ADDRESS:PORT[,IP_ADDRESS:PORT[,...]]
100           Listening ports that are opened for accepting incoming connections.
101           The parameter is a comma-separated list of "IP-address:port".
102
103       outgoing-interfaces=IP_ADDRESS[,IP_ADDRESS[,...]]
104           Controls which IP address outgoing TCP connections are bound to.
105           The parameter is a comma-separated list of IP addresses.
106
107       [torrent=]FILE.torrent
108           Specify a local torrent file.
109
110       [torrent=]magnet:?xt=urn:...
111           Specify a magnet link.
112
113           "torrent=" is a magic config key and may be omitted in most cases.
114           See "Magic parameters" in nbdkit(1).
115
116       upload-rate-limit=BITS_PER_SEC
117           Set the upload rate limit in bits per second.  Usual abbreviations
118           can be used such as "upload-rate-limit=1M" for 1 megabit per
119           second.  0 means unlimited, which is the default.
120
121       user-agent=STRING
122           Set the user-agent.  The recommended format is
123           "client-name/client-version".
124

ENVIRONMENT VARIABLES

126       "TMPDIR"
127           This directory is used to cache the downloaded torrent file (or
128           /var/tmp if not set).  See also the "cache=DIR" parameter above.
129

FILES

131       $plugindir/nbdkit-torrent-plugin.so
132           The plugin.
133
134           Use "nbdkit --dump-config" to find the location of $plugindir.
135

VERSION

137       "nbdkit-torrent-plugin" first appeared in nbdkit 1.22.
138

AUTHORS

147       Richard W.M. Jones
148

COPYRIGHT

150       Copyright (C) 2020 Red Hat Inc.
151

LICENSE

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