README
1 The BitTorrent Protocol Daemon
2
3 README
4
5 btpd version 0.16
6
7
8Contents
91 Introduction
101.a What is btpd?
111.b The programs
121.c The btcli commands
132 Using btpd
142.a Introduction
152.b Starting btpd
162.c Examples
172.d Troubleshooting
183 Building
193.a Requirements
203.b Standard build
214 Additional notes
224.a Upgrade form old versions
234.b Pre exit mode
244.c Using both IPv6 and IPv4
25
261. Introduction
27
281.a What is btpd?
29
30 Btpd is a utility for sharing files over the BitTorrent network protocol.
31 It runs in daemon mode, thus needing no controlling terminal or gui.
32 Instead, the daemon is controlled by btcli, its command line utility,
33 or other programs capable of sending commands and queries on the control
34 socket.
35
361.b The programs
37
38 btpd consists of the following programs:
39 * btpd - The bittorrent client.
40 * btcli - Command line interface to btpd.
41 * btinfo - Shows information from a torrent file.
42
43 All programs accept the "--help" option.
44
451.c The btcli commands
46
47 The btcli utility has several different modes of operation. One of the
48 following commands must be specified when running btcli:
49 * add - Add torrents to btpd.
50 * del - Remove torrents from btpd.
51 * kill - Shut down btpd.
52 * list - List torrents.
53 * start - Activate torrents.
54 * stat - Display stats for active torrents.
55 * stop - Deactivate torrents.
56
572. Using btpd
58
592.a Introduction
60
61 To start sharing a torrent with btpd, the torrent needs to be added to
62 btpd. This is done with 'btcli add'. When you add a torrent btpd auto-
63 matically (if you didn't specify otherwise) starts to share the torrent
64 and download any missing data. The content directory you specify when
65 adding a torrent doesn't need to exist; it will be created by btpd.
66
67 You can see which torrents have been added to btpd with 'btcli list'.
68 The list command also displays a number for each added torrent. This number
69 can be used to specify the target torrent for the btcli commands, so you
70 don't have to keep the torrent file once you've added it.
71
72 The up- and download progress can be followed by using the 'btcli stat'
73 command. Both the list and stat commands use the following indicators to
74 display the state of a torrent:
75 + the torrent is starting. This may take time if btpd needs to test
76 the content of this torrent or one started before it.
77 - the torrent is being stopped.
78 I the torrent is inactive.
79 S btpd is seeding the torrent.
80 L btpd is leeching the torrent.
81
82 You can stop an active torrent with 'btcli stop' and, of course,
83 start an inactive torrent by using 'btcli start'.
84
85 The 'btcli del' command should only be used when you're totally finished
86 with sharing a torrent. The command will remove the torrent and its
87 associated data from btpd. It's an escpecially bad idea to remove a not
88 fully downloaded torrent and then adding it again, since btpd has lost
89 information on the not fully downloaded pieces and will need to download
90 the data again.
91
92 To shut down btpd use 'btcli kill'. Don't forget to read the help for each
93 of btcli's commands.
94
952.b Starting btpd
96
97 NOTE: You should only need one instance of btpd regardless of how many
98 torrents you want to share.
99
100 To start btpd with default settings you only need to run it. However,
101 there are many useful options you may want to use. To see a full list
102 run 'btpd --help'. If you didn't specify otherwise, btpd starts with
103 the same set of active torrents as it had the last time it was shut down.
104
105 btdp will store information and write its log in $HOME/.btpd. Therefore
106 it needs to be able to write there during its execution. You can specify
107 another directory via the '-d' option or the $BTPD_HOME variable.
108
109 I recommend specifiying the maximum number of uploads. Bittorrent employs a
110 tit for tat algorithm, so uploading at good rates allows for downloading.
111 Try to find a balance between uploads/outgoing bandwidth and the number of
112 active torrents.
113
1142.c Examples
115
116 Start btpd with all options set to their default values.
117 # btpd
118
119 Start btpd and make it listen on port 12345, limit outgoing bandwidth to
120 200kB/s, limit the number of peers to 40 and not start any torrents that
121 were active the last time btpd was shut down.
122 # btpd -p 12345 --bw-out 200 --max-peers 40 --empty-start
123
124 Display a list btpd's torrents and their number, size, status, etc.
125 # btcli list
126
127 Same as above, but only for torrent 12 and my.little.torrent.
128 # btcli list 12 my.little.torrent
129
130 Same as above but only for active torrents.
131 # btcli list -a
132
133 Same as above, but print using a custom format
134 # btcli list -a -f "btcli list -f "%n\t%#\t%p%s\t%r\n"
135
136 Add foo.torrent, with content dir foo.torrent.d, and start it.
137 # btcli add -d foo.torrent.d foo.torrent
138
139 Same as above without starting it.
140 # btcli add --no-start -d foo.torrent.d foo.torrent
141
142 Start bar.torrent and torrent number 7.
143 # btcli start bar.torrent 7
144
145 Stop torrent number 7.
146 # btcli stop 7
147
148 Stop all active torrents.
149 # btcli stop -a
150
151 Remove bar.torrent and it's associated information from btpd.
152 # btcli del bar.torrent
153
154 Display a summary of up/download stats for the active torrents.
155 # btcli stat
156
157 Display the summary once every five seconds.
158 # btcli stat -w 5
159
160 Same as above, but also display individual stats for each active torrent.
161 # btcli stat -w 5 -i
162
163 Shut down btpd.
164 # btcli kill
165
1662.d Troubleshooting
167
168 If btpd has shut down for some unknown reason, check the logfile for
169 possible clues.
170
1713. Building
172
1733.a Requirements
174
175 You should have a *BSD, Linux or sufficiently similar system.
176
177 Make sure you have recent versions of the following software:
178 * OpenSSL - Get at <URL:http://www.openssl.org/>
179
180 You also need a c99 compiler. A non antique GCC should do.
181
1823.b Standard build
183
184 # ./configure
185 # make
186 # make install
187
188 See './configure --help' for available build options if the above fails.
189
1904. Additional notes
191
1924.a Upgrade from old version
193
194 The layout of the torrents directory in the btpd directory has changed
195 since btpd 0.11. Please remove the torrents directory before running
196 later versions.
197
1984.b Pre exit mode
199
200 If btpd needs to send stop messages to trackers before shutting down,
201 it will enter the pre exit mode. A btpd process in this mode can safely
202 be ignored and will not interfere with any new btpd started in the same
203 directory.
204
2054.c Using both IPv6 and IPv4
206
207 Unfortunately enabling both IPv6 and IPv4 in btpd is less useful than it
208 should be. The problem is that some sites have trackers for both versions
209 and it's likely that the IPv6 one, which probably has less peers, will be
210 used in favour of the IPv4 one.
211
212 In order to fix this problem, the IP version options should be changed to
213 be per torrent, in some future version of btpd.
214