From e0c4fea13e21c1f5085429640c37c8dcc33c7a65 Mon Sep 17 00:00:00 2001 From: Richard Nyberg Date: Mon, 16 Oct 2006 15:00:31 +0000 Subject: [PATCH] Rewrote parts of the README and updated it with information on the new stuff in 0.12. --- README | 178 +++++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 116 insertions(+), 62 deletions(-) diff --git a/README b/README index 08c6c97..fb95e6d 100644 --- a/README +++ b/README @@ -6,113 +6,161 @@ Contents 1 Introduction 1.a What is btpd? 1.b The programs +1.c The btcli commands 2. Using btpd -2.a Typical usage pattern +2.a Introduction 2.b Starting btpd -2.c Sharing torrents -2.d Information on active torrents -2.e Murder +2.c Examples +2.d Troubleshooting 3 Building 3.a Requirements 3.b Standard build +4 Upgrade notes +4.a btpd 0.12 1. Introduction 1.a What is btpd? - btpd is a BitTorrent client consisting of a daemon and client commands, + btpd is a bittorrent client consisting of a daemon and client commands, which can be used to read and/or manipulate the daemon state. The daemon is capable of running several torrents simultaneously and only uses one - tcp port. It's fairly low on resource usage and should be perfect for a - torrent distribution site. Efficient downloads and ease of use makes this + tcp port. It's fairly low on resource usage and should be perfect for + file distribution sites. Efficient downloads and ease of use makes this client a good choice for the casual user as well. 1.b The programs btpd consists of the following programs: - * btpd - The BitTorrent client. + * btpd - The bittorrent client. * btcli - Command line interface to btpd. * btinfo - Shows information from a torrent file. - All programs accept the helpful "--help" option. + All programs accept the "--help" option. -2. Using btpd +1.c The btcli commands + + The btcli utility has several different modes of operation. One of the + following commands must be specified when running btcli: + * add - Add torrents to btpd. + * del - Remove torrents from btpd. + * kill - Shut down btpd. + * list - List torrents. + * start - Activate torrents. + * stat - Display stats for active torrents. + * stop - Deactivate torrents. -2.a Typical usage pattern +2. Using btpd - When you use this client you will mostly use the btcli tool. With btcli - you can tell btpd which torrents to run, list the active torrents and - display stats for them. You can even tell btpd to exit if you're so in- - clined. Before you can use this tool however, btpd must be started. The - typical usage pattern goes something like this: - 1. start btpd. - 2. add one or more torrents to btpd. - 3. any of many different actions: display stats, add more or remove - torrents, go drink coffe, etc... - 666. tell btpd to exit. +2.a Introduction + + To start sharing a torrent with btpd, the torrent needs to be added to + btpd. This is done with 'btcli add'. When you add a torrent btpd auto- + matically (if you didn't specify otherwise) starts to share the torrent + and download any missing data. The content directory you specify when + adding a torrent doesn't need to exist; it will be created by btpd. + + You can see which torrents have been added to btpd with 'btcli list'. + The list command also displays a number for each added torrent. This number + can be used to specify the target torrent for the btcli commands, so you + don't have to keep the torrent file once you've added it. + + The up- and download progress can be followed by using the 'btcli stat' + command. Both the list and stat commands use the following indicators to + display the state of a torrent: + + the torrent is starting. This Can take time if btpd needs to test + the content of this torrent or one started before it. + - the torrent is being stopped. Can take time if the tracker is + unresponsive. + I the torrent is inactive. + S btpd is seeding the torrent. + L btpd is leeching the torrent. + + You can stop an active torrent with 'btcli stop' and, of course, + start an inactive torrent by using 'btcli start'. + + The 'btcli del' command should only be used when you're totally finished + with sharing a torrent. The command will remove the torrent and its + associated data from btpd. It's an escpecially bad idea to remove a not + fully downloaded torrent and then adding it again, since btpd has lost + information on the not fully downloaded pieces and will need to download + the data again. + + To shut down btpd use 'btcli kill'. Don't forget to read the help for each + of btcli's commands. 2.b Starting btpd - NOTE: As described in the section above, you should only need one instance - of btpd regardless of how many torrents you want to share. + NOTE: You should only need one instance of btpd regardless of how many + torrents you want to share. - To start btpd with default settings you only need to run it. There are - however, many useful options you may want to use. To see a full list run - 'btpd --help'. + To start btpd with default settings you only need to run it. However, + there are many useful options you may want to use. To see a full list + run 'btpd --help'. If you didn't specify otherwise, btpd starts with + the same set of active torrents as it had the last time it was shut down. btdp will store information and write its log in $HOME/.btpd. Therefore it needs to be able to write there during its execution. You can specify another directory via the '-d' option or the $BTPD_HOME variable. - I recommend specifiying the maximum number of uploads. BitTorrent employs a + I recommend specifiying the maximum number of uploads. bittorrent employs a tit for tat algorithm, so uploading at good rates allows for downloading. Try to find a balance between uploads/outgoing bandwidth and the number of active torrents. -2.c Sharing torrents +2.c Examples + + Start btpd with all options set to their default values. + # btpd + + Start btpd and make it listen on port 12345, limit outgoing bandwidth to + 200kB/s, limit the number of peers to 40 and not start any torrents that + were active the last time btpd was shut down. + # btpd -p 12345 --bw-out 200 --max-peers 40 --empty-start + + Display a list btpd's torrents and their number, size, status, etc. + # btcli list - To make btpd start leeching or seeding a torrent you use the 'btcli add' - command. In similar vein the 'btcli del' command will make btpd stop shar- - ing the torrent. + Same as above, but only for torrent 12 and my.little.torrent. + # btcli list 12 my.little.torrent + + Same as above but only for active torrents. + # btcli list -a - The first time you add a torrent you must specify where btpd should put - its content. This is not needed on subsequent add's of the same torrent - since btpd stores that information. Of course, if you move the content - directory between runs you need to specify it again. + Add foo.torrent, with content dir foo.torrent.d, and start it. + # btcli add -d foo.torrent.d foo.torrent - Examples: - Add foo.torrent and download its content to the foo.content directory. - # btcli add -d foo.content foo.torrent + Same as above without starting it. + # btcli add --no-start -d foo.torrent.d foo.torrent - Stop sharing foo.torrent. - # btcli del foo.torrent + Start bar.torrent and torrent number 7. + # btcli start bar.torrent 7 - Start it again. Notice the absence of '-d foo.content'. - # btcli add foo.torrent + Stop torrent number 7. + # btcli stop 7 - Add bar.torrent and place the content like the mainline client. - # btcli add --topdir -d . bar.torrent + Stop all active torrents. + # btcli stop -a -2.d Information on active torrents + Remove bar.torrent and it's associated information from btpd. + # btcli del bar.torrent - In case you're not happy only guessing about your torrents progress, or - can't remember which torrents are active, you may want to take a look at - the 'btcli stat' and 'btcli list' commands. 'btcli list' will, not totally - surprisingly, display a list of active torrents. 'btcli stat' will display - information such as rates and MBs uploaded and downloaded. See - 'btcli --help stat' to make sense of it. + Display a summary of up/download stats for the active torrents. + # btcli stat - Each line 'btcli list' shows is prefixed by either '+', '-', 'S' or 'L'. - + means the torrent hasn't been started yet, because btpd is checking - the content of either this or another torrent with '+'. - - means the torrent is being stopped. - S means btpd is seeding the torrent. - L means btpd is leeching the torrent. + Display the summary once every five seconds. + # btcli stat -w 5 -2.e Murder + Same as above, but also display individual stats for each active torrent. + # btcli stat -w 5 -i - Too slay the innocent btpd process issue the command 'btcli kill'. - Horrible user! + Shut down btpd. + # btcli kill + +2.d Troubleshooting + + If btpd has shut down for some unknown reason, check the logfile for + possible clues. 3. Building @@ -134,5 +182,11 @@ Contents # make # make install - See './configure --help' for options if the above fails or you're overcome - by curiousity. + See './configure --help' for available build options if the above fails. + +4. Upgrade notes + +4.a btpd 0.12 + + The layout of the torrents directory in the btpd directory has changed + since previous versions. Please remove it before running the new version.