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