Required Software

The following software should be installed before attempting to build BTG.

Its assumed that a working C and C++ compiler is installed.

Its also assumed that, if one is generating the configure script, the following applications are installed:

• GNU autoconf 2.61 or later.
• GNU automake 1.9.6 or later.
• GNU libtool 1.4.3 or later.
• pkg-config 0.21 or later.

Building the Daemon

mkdir ~/btg-devel

cd ~/btg-devel && svn checkout http://svn.berlios.de/svnroot/repos/btg/trunk

cd ~/btg-devel/trunk
./autogen.sh

./configure

./configure --enable-debug --enable-unittest

make check

checking whether the a command list should be generated... yes
configure: Link test, compiler flags: -Wall -W -g -I/pack/libtorrent/svn/include -I/pack/libtorrent/svn/include/libtorrent -I/usr/include -I/usr/include
configure: Link test, linker flags  :
          -lboost_iostreams -lboost_filesystem -lboost_date_time
          -lboost_thread -lboost_program_options
          -L/pack/libtorrent/svn/lib -ltorrent -lgnutls
checking if BTG can link with the provided/found libraries... yes

export CPPFLAGS="-I~/boost-1.33.1/include/boost-1_33_1"
export LDFLAGS="-L~/boost-1.33.1/lib"

./configure --with-boost-iostreams=boost_iostreams-gcc-mt-1_33_1

make

make install

make install-strip

Distro Packages

See the list of BTG packages.

Using btg-config

One can use the provided btg-config script. It asks the user a number of questions and produces the daemon and client .ini files based on the answers.

The final step of the script is to write the configuration files. They will be written in the directory in which btg-config was executed.

btg-config will not create a passwd file, only add an entry to the daemon.ini configuration file about where to find it. Therefore one should use btgpasswd to add the contents of the passwd file.

Daemon

daemon.ini - Place this file in ~/.btg/daemon.ini, which is the default daemon config file location.

The above config sets the daemon to do the following:

• Setup BTG auth, namely the file from which users are read from.
• Uses the XML-RPC transport.
• Enables logging to a file.
• Makes the daemon listen to port 16000 or all interfaces.
• Use ports 10024,10025 for libtorrent. If DHT is used, two ports are used per session, without DHT one port is used per session.
• Enables limits on upload speed, download speed, max connections and max uploads. All speeds are in bytes or bytes per second.

btgpasswd --create -a -t "~/some/path/torrents" -w "~/some/path/work" -d "~/btg/some/path/finished" -s "~/btg/some/path/seeding" -p -u <username>

Clients

Before attempting to use any of the clients, follow the instruction in Testing to make sure that the daemon starts and can communicate with clients.

AddType application/x-httpd-php .php
AddType application/x-httpd-php-source .phps

ln -s /usr/local/share/wwwbtg/htdocs /home/www/btg

killall btgdaemon

Starting the daemon

The following command will start the daemon.

btgdaemon

One can pass the -n parameter so it wont fork into background, which is good when testing.

The verbose(-v) or debug (-D, only when debug is compiled in) can also be added for more logging - this helps alot when troubleshooting. To interact with the daemon you have to use a client, either the CLI-client, the GUI-client or wwwBTG. All three can be used to setup sessions.

Starting the CLI

btgcli

This will start the command line client. Most operations can be done from the web interface (see below), but some things are not yet doable (for example, set individual limits on torrents).

You will be requested to enter username and password. If you run without any parameters, you will create a new session which later can be reattached. Write "detach" to detach the session, but leave it running in the daemon (what you normally do). Note that if you write "quit" the session will be terminated! If you like to run the CLI later, you can use the parameter -A to attach to the first available session.

Emule

An Emule filter can contain lines like (white space was added here):

IPv4            IPv4            LEVEL DESCRIPTION
--------------- --------------- ---   -------------------------------------------
003.000.000.000-003.255.255.255,110,  [L1]General Electric Company
004.000.025.146-004.000.025.148,110,  [L1]s0-0.ciscoseattle.bbnplanet.net
004.000.026.014-004.000.029.024,110,  [L1]p1-0.cisco.bbnplanet.net
004.002.144.032-004.002.144.047,120,  [L2]International Generating Co. (Intergen)

When a filter it read the following is extracted:

• IPv4 range (the two IPv4 addresses).
• Level.

If the level is greater than 0 and less or equal to 120 then the IPv4 range is blocked.

Level One

The Level One filter can consist of lines like (white space was added here):

LABEL                           IPv4        IPv4
------------------------------- ----------- -------------
General Electric Company       :3.0.0.0    -3.255.255.255
s0-0.ciscoseattle.bbnplanet.net:4.0.25.146 -4.0.25.148
p1-0.cisco.bbnplanet.net       :4.0.26.14  -4.0.29.24
Cisco Systems, Inc             :4.2.144.64 -4.2.144.95
Drug Enforcement Adm           :4.2.144.224-4.2.144.231
US Dept of Treasury - TIGTA    :4.2.144.248-4.2.144.255

When a filter it read the following is extracted:

• IPv4 range (the two IPv4 addresses).

All IPv4 ranges found are blocked.

Format

The passwd file used by BTG consists of lines formatted as follows (notice the use of ":"):

User name:Password Hash:Temporary directory:Work directory:Seed directory:Destination directory:Control:Callback

Using Commands

In the following, a few command sequences are listed. Notice that error handling is left as an excersise for the reader.

The following sequence could be used to create a session:

Command               Description
--------------------- --------------------------
(g) Init connection   Initialize the connection.
(g) Ack               Response, OK.
(g) Setup command     Setup the session.
(g) Ack               Response, OK.

Having created a session, one can create a context(load a torrent):

Command               Description
--------------------- -----------------
(g) Create context    Create a context.
(g) Ack               Response, OK.

After a torrent has been loaded, it can be started. Also, one can get its status, which contains information such as the upload/download rate, number of percent finished and its state.

Command               Description
--------------------- -------------------------------
(c) Start context     Start a torrent.
(g) Ack               Response, OK.
(c) Status            Get the status of one context.
(c) Status response   The status of the context (OK).

Loading All Torrent Files from a Directory

Use the following command from a shell (like Bash):

ls -1 *.torrent|xargs -n1 -ITORRENT btgcli -A -n -c "detach" -o "TORRENT"

The above commands works when using Debian Linux.

FreeBSD users should use the following command instead (thanks Andros):

ls -1 *.torrent|xargs -n1 -o -ITORRENT btgcli -A -n -c "detach" -o "TORRENT"

(Tested on FreeBSD 6.2-RELEASE-p5.)

The above command executes the following actions for each torrent file present in the current directory:

• start btgcli and attach to the first available session.
• upload a torrent file to the daemon.
• detach the session.

Notice that there can be slight differencies between which command line arguments are supported by the different xargs versions.

Using an Incoming Directory

Using a script and cron, one can emulate an incoming directory, like the one used by a bash script used to run btlaunchmany.py.

#!/bin/sh

CLIENT=btgcli
# The directory containing the torrent files.
INCOMING_DIR=~/btg/incomming
# The directory to which .torrent files are moved
# to after loading them into BTG.
DONE_DIR=~/btg/incomming/done

GOT_SESSION=0
$CLIENT -A -n -c "detach" &> /dev/null && GOT_SESSION=1

if [ $GOT_SESSION -eq 0 ]
then
  $CLIENT -n -c "detach" &> /dev/null && GOT_SESSION=1
fi

if [ $GOT_SESSION -eq 0 ]
then
  echo "Unable to attach or create a BTG session."
  exit -1
fi

TORRENT_ADDED=0

cd $INCOMING_DIR && \
for f in `ls -1 *.torrent 2> /dev/null` ; do
  echo "Loading file: $f" && \
  $CLIENT -A -n -c "detach" -o $f &> /dev/null && \
  TORRENT_ADDED=`expr $TORRENT_ADDED + 1` && \
  mv $f $DONE_DIR
done

if [ $TORRENT_ADDED -gt 0 ]
then
  echo "Added $TORRENT_ADDED torrents to BTG."
fi

The above script attempts to:

• Create a new BTG session or attach to an existing BTG session.
• Load all present torrent files into BTG.
• Move any loaded torrent files to another directory.
• Write the filename of the torrent file which is being loaded into BTG.
• Write the total number of files loaded.

Remember to add a section named "auth" to your client.ini file. This section should contain two keys: "username" and "password-hash". This is done to avoid having the client (btgcli) prompt for username and password, since its being used from a script called from cron.

Notice that once a torrent file is loaded by BTG, there is no reason for keeping the torrent file. See Supported Directory Structure.

Call the script from Vixie Cron, using an entry like this:

*/1 * * * *   /path/to/script

The above entry calls the script each minute. Notice that cron will e-mail the output of the script to you, so add "&> /dev/null" to avoid any e-mail.

Setting global limits based on the time of the day

The following script could be used to set upload limits based on the time of the day.

#!/bin/sh

# The location of the BTG client application.
CLIENT=btgcli

H=`date +%H`
O="none"

if [ "$H" -gt "0" ] || [ "$H" -lt "6" ]
then
    O="night"
fi

if [ "$H" -gt "6" ] || [ "$H" -lt "12" ]
then
    O="morning"
fi

if [ "$H" -gt "12" ] || [ "$H" -lt "16" ]
then
    O="midday"
fi

if [ "$H" -gt "16" ] || [ "$H" -lt "23" ]
then
    O="evening"
fi

# Max upload limit.
UL_MAX=75

# Global limits in KiB/sec.
UL=-1
DL=-1
SET_LIMIT=0

case "$O" in
    night)
       UL=$UL_MAX
       SET_LIMIT=1
       echo "Limit:$O:$UL:$DL"
       ;;
    morning)
       UL=`expr $UL_MAX - 20`
       SET_LIMIT=1
       echo "Limit:$O:$UL:$DL"
       ;;
    midday)
       UL=`expr $UL_MAX - 40`
       SET_LIMIT=1
       echo "Limit:$O:$UL:$DL"
       ;;
    evening)
       UL=`expr $UL_MAX - 70`
       SET_LIMIT=1
       echo "Limit:$O:$UL:$DL"
       ;;
    *)
       echo "Not setting limit."
       ;;
esac

if [ "$SET_LIMIT" -eq "0" ]
then
    exit 0
fi

GOT_SESSION=0
$CLIENT -A -n -c "detach" &> /dev/null && GOT_SESSION=1

if [ $GOT_SESSION -eq 0 ]
then
  $CLIENT -n -c "detach" &> /dev/null && GOT_SESSION=1
fi

if [ $GOT_SESSION -eq 0 ]
then
  echo "Unable to attach or create a BTG session."
  exit -1
fi

$CLIENT -A -n -c "glimit $UL $DL -1 -1;detach" &> /dev/null && \
echo "Limit set."

Add it to cron like the script used to load torrents from an incoming directory.

Revisions

The following OpenWrt revisions are known to build:

Revision 328 Notes

Uses boost 1.34.1, libtorrent 0.13 and BTG from the trunk of SVN.

GCC 4.2.3 is used because other versions had problems compiling libtorrent 0.13. To be able to build revision 328 for the XScale-IXP42x, the following had to be used in the .config file.

CONFIG_TARGET_OPTIMIZATION="-Os -pipe -march=armv5te -mtune=xscale -funit-at-a-time"
CONFIG_GCC_VERSION="4.2.3"
CONFIG_UCLIBC_VERSION="0.9.29"