btpd/README

                     The BitTorrent Protocol Daemon

                                README

Contents
1               Introduction
1.a               What is btpd?
1.b               The programs
2.              Using btpd
2.a               Typical usage pattern
2.b               Starting btpd
2.c               Sharing torrents
2.d               Information on active torrents
2.e               Murder
3               Building
3.a               Requirements
3.b               Standard build

1. Introduction

1.a What is btpd?

  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
  client a good choice for the casual user as well.

1.b The programs

  btpd consists of the following programs:
  * btpd     - The BitTorrent client.
  * btcli    - Command line interface to btpd.
  * btinfo   - Shows information from a torrent file.

  All programs accept the helpful "--help" option.

2. Using btpd

2.a Typical usage pattern

  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.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.

  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'.

  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
  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

  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.

  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.

  Examples:
  Add foo.torrent and download its content to the foo.content directory.
  # btcli add -d foo.content foo.torrent

  Stop sharing foo.torrent.
  # btcli del foo.torrent

  Start it again. Notice the absence of '-d foo.content'.
  # btcli add foo.torrent

  Add bar.torrent and place the content like the mainline client.
  # btcli add --topdir -d . bar.torrent

2.d Information on active torrents

  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.

  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.

2.e Murder

  Too slay the innocent btpd process issue the command 'btcli kill'.
  Horrible user!

3. Building

3.a Requirements

  You should have a *BSD, Linux or sufficiently similar system with pthread
  support.

  Make sure you have recent versions of the following software:
  * curl      - Get at <URL:http://curl.haxx.se/>
  * openssl   - Get at <URL:http://www.openssl.org/>
  * libevent  - Get at <URL:http://www.monkey.org/~provos/libevent/>

  You also need a c99 compiler. A non antique GCC should do.

3.b Standard build

  # ./configure
  # make
  # make install

  See './configure --help' for options if the above fails or you're overcome
  by curiousity.