In this article I’d like to describe a text-mode Bittorrent client - rTorrent. It will be helpful to people that share a computer with other household members because it allows them to download files regardless of the logged in user. What’s more, because it is a text-mode client (runs under ncurses) you can watch how it works through any ssh client, web browser (ajaxterm) or even cell phone (MidpSSH). Wikipedia and the official website says that the very optimized code makes rTorrent much faster than the official client. So, do you want more? Bring it on!

What do you need?

First of all you will need a copy of rTorrent and libtorrent libs. You can download these two from the official website but first check your distribution’s repository. We will need also a program screen, which should be found in most repositories.

If you have already installed these packages, you can run rTorrent now. Just write “rtorrent” in a terminal. What appears is described below. You will feel a little bit confused for sure, so I’ll try to explain it all

Window description

These two screenshots show the main window of rTorrent. The first one shows you what rTorrent looks like when run for the first time. On the second screen there is a window with two downloads and the configuration file made.

Img.1 rTorrent — right after start

Img.2 rTorrent — basic functions description

Configuration file

The first question is - “how do we add a new torrents?” The answer is right here: torrents add themselves automatically. “How is it possible?” You will see in a moment

The magic is inside the configuration file of rTorrent which is in your home directory named .rtorrent.rc. You should create it now. Example one, which I use is below.

# The settings of torrents will be saved in this directory;
# and a file, which will prevent rTorrent running more than once;
session = /home/lukasz/dane/download/torrenty
# where the downloaded files will be saved;
directory = /home/lukasz/dane/download/torrenty
# Default upload speed (0 means No Limit);
upload_rate = 40
# Default download speed (0 means No Limit);
download_rate = 0
# if rTorrent should use UDP;
use_udp_trackers = yes
# Max. number of upload slots per torrent;
max_uploads = 20
# Port range from where rTorrent will try to connect;
port_range = 6892-6892
# Min. and max. connections to one torrent;
min_peers=10
max_peers=400
# Stops uploading when ratio is 2.0 and file size greater than 100MB
# or ratio is over 5.0;
schedule = ratio,60,60,stop_on_ratio=200,200M,500
# Stops downloading when there is less than 20MB diskspace;
schedule = low_diskspace,5,60,close_low_diskspace=20M
# Torrents will be automatically added to the download \\
list from this directory ;
schedule = \\
watch_directory,5,5,load_start=/home/lukasz/dane/download/torrenty/*.torrent
# After deleting torrents from that list .torrent files will be deleted too;
schedule = untied_directory,5,5,stop_untied=

If you have already prepared the configuration file you can check if rTorrent downloads the files automatically. To do this you have to download a torrent file to your download directory (in my case it was “/home/lukasz/dane/download/torrenty”). If rTorrent adds files from the directory it will mean that everything is OK. Otherwise you have to check the configuration file very carefully. Check if it is in the correct directory, has the right name and doesn’t contain any typos.
Of course torrents can also be added manually with keyboard shortcuts.

rTorrent, screen and init scripts

In the next step you will add rTorrent to your init scripts. To do this you will prepare a little script which you will add to /etc/init.d. You can read how to do this in article about /etc/init.d written by Bober. In my case it looks like this:

#!/bin/sh
su lukasz -c 'screen -mD sh /usr/bin/rtorrent';

Instead of “lukasz”, you have to write your own username what will made rTorrent not to run with a root privileges.

If you want to start this script on system startup you have to (with root privileges) make it executable (chmod +x), copy it to /etc/init.d/ and then run update-rc.d file defaults 20 where file is the name of the script.

After rebooting, rTorrent should run automatically. To see it you have to enter screen -r in any terminal. The full description of not only basic functions of the screen you can find in Screen: Tips & Tricks.

Basic keyboard shortcuts

• ^q — closes rTorrent, done twice makes the program shutdown.
• Up, down arrows — highlight the downloads.
• Left arrow — returns to the previous screen.
• Right arrow — goes to the next screen.
• a|s|d — increase global upload speed about 1|5|50 KB/s
• A|S|D — increase global download speed about 1|5|50 KB/s
• z|x|c — decrease global upload speed about 1|5|50 KB/s
• Z|X|C — decrease global download speed about 1|5|50 KB/s
• ^S — starts download
• ^D — pauses and resumes the active download
• +|- — changes the download priority of selected torrent.
• Backspace — adds the specified .torrent. After pressing this button write full path or URL of .torrent file. You can use Tab and other tricks from bash.

I hope the information I presented here will be useful. Obviously it is not 100% of rTorrent’s features but certainly this is enough to easily use the program. For more information take a look at the manuals. You can also ask any questions in the comments or personaly by writing to lukiasz(at)gmail.com