September 13, 2005

BitTorrent for Linux

By Mark Sobell¬â 

This article is excerpted from the newly published book A Practical Guide to Linux Commands, Editors, and Shell Programming.

Unlike protocols such as FTP, BitTorrent groups multiple files into a single package called a torrent. For example, you can typically download several installation ISO images as a single torrent.

Like other P2P systems, BitTorrent does not use a dedicated server. Instead, the functions of a server are performed by the tracker, peers, and seeds. The tracker allows clients to communicate with each other. A client -- called a peer when it has downloaded part of the torrent and a seed once it has downloaded the entire torrent -- acts as an additional source for the torrent. As with a P2P network, each peer and seed that downloads a torrent uploads to other clients the sections of the torrent it already has. There is nothing special about a seed: It can be removed at any time once the torrent is available for download from other seeds.

After you download and install BitTorrent, the first step in downloading a torrent using BitTorrent is to locate or acquire a .torrent file. A .torrent file contains the information about the torrent, such as its size and the location of the tracker. You can use a .torrent file using its URI or you can acquire it via the Web, an email attachment, or other means. The next step is for the BitTorrent client to connect to the tracker to learn the locations of other clients that it can download the torrent from.

Once you have downloaded a torrent, it is good manners to allow BitTorrent to continue to run so other clients can upload at least as much information as you have downloaded.


If no BitTorrent RPM file exists for your version of Linux, use an RPM file for a similar version. Because BitTorrent is written in Python and runs on any platform with a Python interpreter, it is not dependent on system architecture. The "noarch" in the name of the RPM file stands for no architecture.

To run, BitTorrent requires Python, which is installed as /usr/bin/python on many systems. Python is available in the python RPM package.

How BitTorrent works

The official BitTorrent distribution includes three client applications. You can use any of these applications to download BitTorrent files:

  • -- A text-based client that writes the status to standard output. Good for unattended downloads where the output is redirected to a file.
  • -- A text-based client that provides a pseudographical interface. Good for attended downloads to machines not running a GUI.
  • -- A graphical client.

In addition to the official clients, several other clients provide extra features.

Using BitTorrent

To use BitTorrent, first locate the .torrent file for the torrent you want to download. You can copy the .torrent file to the working directory (the first format shown below) or specify it with a --url option (second format). The simplest BitTorrent command lines have the following formats:

$ --responsefile tfile.torrent [--saveas savefile]


$ --url http://domain/tfile.torrent [--saveas savefile]

where tfile.torrent is the name of, or http://domain/tfile.torrent is the URI for, the .torrent file, and savefile is the location to save the torrent in. In the case of torrents containing a single file, the file is saved as savefile. For torrents containing multiple files, the files are saved in a directory named savefile. If you omit the --saveas argument, the files are saved in the name specified in the .torrent file. Because each of the btdownload*.py applications takes the same arguments, the preceding formats work for all three applications.

The next example shows how to download Fedora Core 3 ISO images. These large files take considerable time to download. To start the download, give the following command:

$ --max_upload_rate 8


This command uses a URI to specify a .torrent file and saves the downloaded files in a directory named heidelberg (the name of the Fedora release) as specified by the .torrent file.

The --max_upload_rate 8 option prevents BitTorrent from using more than 8 kilobytes per second of upstream bandwidth. BitTorrent usually gives higher download rates to clients that upload more, so feel free to increase this value if you have spare bandwidth. You need to leave enough free upstream bandwidth for the acknowledgment packets from your download to get through or your download will be very slow. By default the client uploads to a maximum of seven other clients at once. You can change this value by specifying the --max_uploads argument, followed by the maximum number of concurrent uploads you wish to permit. The default value of 7 is usually appropriate for typical broadband connections.

After you give the preceding command, the screen quickly fills with output that looks similar to the following:

saving:        heidelberg-binary-i386
percent done:  0.0
time left:     finishing in 27:09:04
download to:   /home/max/heidelberg-binary-i386
download rate: 32.9 KB/s
upload rate:   0.0 KB/s
share rating:  0.000 (0.0 MB up / 1.2 MB down)
seed status:   30 seen now, plus 1 distributed copies (2:81.5%, 3:23.0%, 4:2.1%)
peer status:   5 seen now

The file size is that of all the files you are downloading: four ISO images and several smaller files. To abort the download, press Ctrl-C. The download will automaticallyresume from where it left off when you download the same torrent to the same location again.

Use the following command to perform the same download as in the previous example, this time throttling the rate and number of uploads to values sensible for modem users.

$ --max_upload_rate 3 --max_uploads 2


The preceding command displays output similar to the following:

file:     heidelberg-binary-i386
size:     2,467,681,047 (2 GiB)
dest:     /home/max/heidelberg-binary-i386
progress: _________________________________________
status:   finishing in 6:40:42 (1.0%)
dl speed: 285.6 KB/s
ul speed: 2.6 KB/s
sharing:  0.009 (0.1 MB up / 15.1 MB down)
seeds:    29 seen now, plus 0 distributed copies (1:0.8%, 2:0.0%, 3:0.0%)
peers:    1 seen now
Click Here!