June 12, 2008

Headless torrent downloads with rTorrent and Screen

Author: Chad Files

I have a constantly running server that would be a perfect on which to run torrent downloads. The only catch is that the server is headless -- it has no monitor or keyboard. To overcome this obstacle, I use rTorrent as my torrent client, and GNU Screen so that I can disconnect my terminal session and leave rTorrent running.

rTorrent is a full-featured BitTorrent client that was built to run on a terminal. It uses ncurses as an interface layer and libTorrent under the hood. rTorrent is in the package repositories for most major distributions. If it is not available on your system you can download and install from source.

rTorrent has loads of settings and switches. All of the primary settings can be configured in the .rtorrent.rc file in your home directory; rTorrent looks for it every time it starts. A good place to start learning about the settings is with the example configuration on the project's Web site. Copy and paste the contents into ~/.rtorrent.rc

I recommend you change a few settings before you use rTorrent:

  • directory is a path where rTorrent will save downloaded files.
  • schedule -- This setting can be used several times in the configuration file to tell rTorrent what to do when certain events occur. It provides the ability to scan for new torrent files and remove torrents that have been deleted. For instance:
    schedule = watch_directory,5,5,load_start=~/*.torrent
    schedule = untied_directory,5,5,stop_untied=

    The first line scans for .torrent files in your home directory; if one is found, rTorrent will immediately queue the torrent when it is launched. The second line stops any torrent download if its source file is deleted.

  • max_uploads -- It is good practice to give a bit for every bit you receive, but too many connections can choke your network link. This setting allows you to limit how many leechers can connect to you at one time. I leave mine at 2 during the day when I am using my connection and up it to 5 at night.
  • upload_rate allows you to throttle your upload rate to a reasonable amount; 25 to 40 is a good range.
  • download_rate -- Downloading at full force can also choke your connection. This setting allows you to scale rTorrent's download speed. During peak usage I usually set this to 50.

If you do not want to bother with the configuration file, you can pass rTorrent all of these parameters; for more information consult the rTorrent man page.

Once you're set up, open a terminal and run rtorrent. The main screen shows you a summary of all the torrents that are currently queued. It has seven views that you can access by typing 1-7. The views sort and filter the active torrents by name and all the possible states (complete, incomplete, started, stopped, and so forth). From any of these screens you can navigate through the torrents by using the up and down arrow keys. Press Ctrl-s to start a download and Ctrl-d to stop one. If you type Ctrl-d twice, the torrent file, not the downloaded files, will be deleted.

rTorrent also provides extensive information about each download. To view the information, navigate to one of the torrents and press the right arrow key to launch the download view. From this view you can see a complete peer list, file information, tracker list, transfer list, and even the downloaded file chunks. To get back to the main view, press the left arrow key.

To exit rTorrent, type Ctrl-q. When rTorrent exits, it maintains the state of all the torrents. If there is a previously active torrent queued, then when rTorrent launches again it will do a complete hash check of the downloaded content and restore the torrent's state.

rTorrent has many more options and settings. For a complete list of everything available in rTorrent see the man page.

rTorrent with screen

rTorrent really shines when used in conjunction with Screen, which is essentially an interactive shell that attaches itself to a virtual terminal. It allows you to disconnect from a terminal session and leave everything in that session running. Screen is available in the package management system for most major distributions; you can also install it from source.

To start a Screen session, open a terminal and type screen. You will not notice much when Screen is launched; the screen will clear and you will be presented with a prompt. From here you can start any process, such as rTorrent, or run any command available on your system.

To detach the session, type Ctrl-A then Ctrl-D. Ctrl-A tells Screen that the next keystrokes will be a command. Ctrl-D is the detach command. Once you are detached you can exit the session and whatever is running will continue to run -- barring a catastrophe.

When you want to reconnect, you need to get the name of the detached session by using the -ls parameter (screen -ls) to list all of the screen sessions that are running. To reattach to one of them, use the -r parameter and pass in the name:

screen -r 12345.pts-1.machine

If only one screen session is running you can use the -r parameter without the name of the session.

Of course Screen can do much more than what is mentioned here; refer to its man page for more information.

rTorrent and Screen may not be the most flashy BitTorrent setup, but it is one of the most useful and full-featured.


  • Filesharing & P2P
  • Internet & WWW
Click Here!