sts0mrg0 / bitflu Goto Github PK

Welcome to bitflu!

Bitflu is a 'download-daemon' for *NIX-like operating systems, written
in Perl5. Currently BitTorrent and HTTP are supported.

Report bugs to <[email protected]>

~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ 
FAQ Index:

1. Getting started
1.1	What systems does bitflu run on?
1.2	What do i need to run bitflu?
1.3	How do i install or upgrade bitflu?
1.4	How do i start bitflu?

2. Configuration
2.1	Introduction
2.2	Ports you must open
2.3	Chrooting bitflu

3. Using Bitflu
3.1	Connecting to the telnet gui
3.2	Starting a new download
3.3	Viewing existing downloads
3.4	Working with multifile downloads
3.5	Removing a download
3.6	How to seed a torrent




~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~

1. Getting started

1.1	What systems does bitflu run on?

Bitflu should work fine on all *NIX-like operating systems with a
working Perl5 installation. Development and regular testing is done
on Linux 2.6 (x86 and ppc), but people reported success running
it on FreeBSD and OpenBSD.

Note: If you are running bitflu on Solaris with a 32bit Perl5
version, bitflu will be limited to ~255 file descriptors.
(This is a perl limitation. Using a 64bit version 'fixes'
 this problem)


1.2	What do i need to run bitflu?

Not much:

	* Perl 5 (5.8 >= recommended)
	* The module 'Danga::Socket' >= 1.52 and 'Digest::SHA' (or 'Digest::SHA1')
	* A correctly configured 'firewall'
	  (You must accept/forward $torrent_port [udp AND tcp])
	* Some spare disk-space and bandwidth ;-)


1.3	How do i install or upgrade bitflu?

Installation:

	* mkdir /foo/bitflu
	* mv bitflu-*.tgz /foo/bitflu
	* cd /foo/bitflu
	* tar -xzf bitflu-*.tgz ; rm bitflu-*.tgz
	* mv bitflu-*/bitflu.pl bitflu-*/plugins .
	Note: You must install Digest::SHA1 for bitflu.
	Most distributions provide a package for this module, if
	your distribution doesnt, try:
	# perl -MCPAN -e 'install Digest::SHA1'

Upgrade:

	Just replace 'bitflu.pl' and the 'plugins' folder
	with the new version:
	* mv bitflu-*.tgz /foo/bitflu
	* cd /foo/bitflu
	* rm -rf bitflu.pl plugins # removes the old version
	* tar -xzf bitflu-*.tgz ; rm bitflu-*.tgz
	* mv bitflu-*/bitflu.pl bitflu-*/plugins .

1.4	How do i start bitflu?

	* cd /foo/bitflu
	* ./bitflu.pl
	You can now connect to bitflu using
	'telnet 127.0.0.1 4001'

Note: Do not run bitflu via an absolute path (eg. /foo/bitflu/bitflu.pl)
      unless you changed the 'workdir' value into an absolute path.
      (The default is './workdir' (= the folder 'workdir' at the current
       directory))



2. Configuration

2.1	Introduction

At startup, bitflu will try to read the the file '.bitflu.config'
(This can be changed using the --config switch). Most values can
be changed while running using the 'config' command:
	* config show        : Displays current configuration
	* config set foo bar : Set 'foo' to 'bar'

Some values (such as torrent_port) cannot be configured 'online'.
To change this value, you must stop bitflu and edit the configuration 
file using a text editor (such as vi).


2.2	Ports you must open

The ports used by the BitTorrent plugin must be reachable from
the internet (otherwise DHT won't work and downloads will be slow).
Per default, bitflu uses port 6688 (torrent_port):
tcp:6688 is used for 'BitTorrent connections', udp:6688 is 
used for Kademlia (finding sources)


2.3	Chrooting bitflu

Chrooting bitflu is recommended for security reasons.

This is how you could create a chroot jail:
(Replace '12345' with an unprivileged UID/GID)

Step 1: Edit your .bitflu.config:
	  chroot    = /foo/bitflu/chroot
	  runas_uid = 12345
	  runas_gid = 12345

Step 2: Create the jail
          mkdir -p /foo/bitflu/chroot/workdir
          chmod 12345:12345 /foo/bitflu/chroot/workdir

Step 3: Start bitflu

Note: If you are using IPv6 you must also copy /etc/protocols
      into /foo/bitflu/chroot/etc/protocols

Depending on your operating system you may need to add some additional
files (to get DNS working). Use 'strace' (or truss) to find them :-)


3. Using Bitflu

3.1	Connecting to the telnet gui

Just connect to '127.0.0.1' on port 4001 using a normal telnet client:
	telnet 127.0.0.1 4001

The telnet client uses colored output, supports shell-like history and has 
tab completition for some commands (and queue id's)


3.2	Starting a new download

Use the 'load' command to start downloading a localy saved torrent file:
	load /tmp/foo.torrent

You can also download files via HTTP:
	load http://bitflu.workaround.ch/ChangeLog.txt
	Note 1: Bitflu will fail to download HTTP files if the webserver
	        failed to specify the size.

	Note 2: Downloading a .torrent file via HTTP causes bitflu to
	        'auto-import' the file itself

Torrent files can also be placed into the 'autoload folder'. Bitflu will re-
scan this folder each 300 seconds. You can force a re-scan using the
'autoload' command


3.3	Viewing existing downloads

Just type 'vd' (or 'ls'):

 *** Upload:  37.18 KiB/s | Download:  34.99 KiB/s | Peers:  74/208
>[Type] Name                     /================= Hash =================\ Peers |   Pieces   |   Done (MB)    | Done | Ratio|  Up  | Down |
 [ bt ] Name of the download     |1234567890abcdef1234567890abcdef01234567|  8/16 |  951/ 2222 | 1902.0/ 4442.8 |  42% | 0.40 |  6.5 | 15.6 | 


	[ bt ]        : Type of the download
	Name of..     : Name of the download
	12345678..    : The Queue-ID (SHA1 of the Torrent)
	8/16          : We got 16 peers and can download from 8
	951/2222      : The download has 2222 pieces, we got 951
	1902.0/4442.8 : 1902.0MB of 4442.8MB are downloaded
	42%           : ..that's 42%
	0.40          : We got an Up/Down ratio of 0.4 (40%)
	Up            : We are uploading 6.5 KiB/s
	Down          : We are downloading 15.6 KiB/s


3.4	Working with multifile downloads

Torrents can include multiple files. Use 'files queue_id list' to display them:
	files 1234567890abcdef1234567890abcdef01234567 list
	Note: The telnet-gui supports tab completition, so you can just
	      tybe: 'files 123<TAB>'


3.5	Removing a download

Use the 'cancel' command to remove a download from queue (also stops seeding).
Bitflu will auto-cancel downloads itself after reaching a ratio >= 1.5
You can change this setting on a global basis using 'config set autocancel 3.5'
Setting a per-torrent value is also possible using the 'autocancel' command:
	autocancel 1234567890abcdef1234567890abcdef01234567 off
	(See 'help autocancel' for more information)


3.6	How to seed a torrent

Use the 'create_torrent' command
See 'help create_torrent' for details