Difference between revisions of "RTorrent"

From ArchWiki
Jump to: navigation, search
(Controls: Format and clarify text)
(Installing: Add install command)
Line 6: Line 6:
== Installing ==
== Installing ==
[[pacman|Install]] the {{Pkg|rtorrent}} package which is available in the [[Official Repositories|official repositories]].
Install the {{Pkg|rtorrent}} package that is available in the [[community|community  repository]]:
# pacman -S rtorrent
You can also install {{AUR|rtorrent-svn}} from the [[Arch User Repository|AUR]].
Alternatively, install {{AUR|rtorrent-svn}} from the [[Arch User Repository|AUR]].
== Configuring ==
== Configuring ==

Revision as of 05:22, 2 December 2011

This template has only maintenance purposes. For linking to local translations please use interlanguage links, see Help:i18n#Interlanguage links.

Local languages: Català – Dansk – English – Español – Esperanto – Hrvatski – Indonesia – Italiano – Lietuviškai – Magyar – Nederlands – Norsk Bokmål – Polski – Português – Slovenský – Česky – Ελληνικά – Български – Русский – Српски – Українська – עברית – العربية – ไทย – 日本語 – 正體中文 – 简体中文 – 한국어

External languages (all articles in these languages should be moved to the external wiki): Deutsch – Français – Română – Suomi – Svenska – Tiếng Việt – Türkçe – فارسی

rTorrent is a very simple, elegant and ultra-light BitTorrent client. It is written in C++ and uses ncurses, so it is completely text-based and runs entirely in a console. rTorrent is ideal for low-end systems, and with the addition of GNU Screen and openssh, it is convenient as a remote BitTorrent client.


Install the rtorrent package that is available in the community repository:

# pacman -S rtorrent

Alternatively, install rtorrent-svnAUR from the AUR.


Before running rTorrent, copy the default configuration file, which is available at the rTorrent project page, and save it as .rtorrent.rc in your home directory.

Once the file has been saved, open it with your preferred text editor and make any necessary changes. Simply uncomment the options you wish to enable/utilize. For more detailed information on the options available, visit rTorrent Common Tasks

Recommended Configuration

These values in the following are subjective and dependent upon your own system and Internet connection speed. To find the optimal settings for you to use, visit the following website and follow the instructions: Optimize Your BitTorrent Download Speed

# Maximum and minimum number of peers to connect to per torrent.
#min_peers = 40
max_peers = 52

# Same as above but for seeding completed torrents (-1 = same as downloading)
#min_peers_seed = 10
max_peers_seed = 52

# Maximum number of simultanious uploads per torrent.
max_uploads = 8

# Global upload and download rate in KiB. "0" for unlimited.
download_rate = 200
upload_rate = 28

The option below will determine where your torrent data will be saved. Change the default save directory to whatever is most convenient. Be sure to enter the absolute path; there is an odd bug with rTorrent sometimes does not respect relative paths (e.g. ~/torrents):

# Default directory to save the downloaded torrents.
directory = /home/[user]/torrents/

This option will allow rTorrent to save the progess of your torrents. Be sure to create a directory called .session (simply run as normal user: mkdir ~/.session):

# Default session directory. Make sure you do not run multiple instance
# of rtorrent using the same session directory. Perhaps using a
# relative path?
session = /home/[user]/.session/

The following option will have rTorrent "watch" a particular directory for new .torrent files. Be careful when using this option as rtorrent will move the torrent file to your session folder and rename it to its hash value. Using your browser, when you find a .torrent file you would like to download, just save the file into this directory and rTorrent will automatically start the torrent. Be sure to create the directory that will be watched (simply run as normal user: mkdir ~/watch):

# Watch a directory for new torrents, and stop those that have been
# deleted.
#schedule = watch_directory,5,5,load_start=./watch/*.torrent
#schedule = untied_directory,5,5,stop_untied=
schedule = watch_directory,5,5,load_start=/home/[user]/watch/*.torrent
schedule = untied_directory,5,5,stop_untied=
schedule = tied_directory,5,5,start_tied=

The option below will stop rTorrent from downloading any further when disk space is low. This is particuarly useful with a seedbox where disk space is quite limited. Change the value as you like:

# Close torrents when diskspace is low.
schedule = low_diskspace,5,60,close_low_diskspace=100M

This option will set what port to use for listening. It is recommended to use a port that is higher than 49152. rTorrent allows the use of a single port rather than a range; a single port rather than an actual range is recommended.

# Port range to use for listening.
port_range = 49164-49164

The following option allow for a hash check whenever a torrent is complete or whenever rTorrent is restarted. This will make sure there are no errors with your acquired/seeding files.

# Check hash for finished torrents. Might be usefull until the bug is
# fixed that causes lack of diskspace not to be properly reported.
check_hash = yes

The following option allows for the enabling of encryption. This is very important to enable, if not for yourself, but for others in the torrent swarm; people might need to obscure their bandwidth usage from their ISP. Does not hurt you to enable even if you do not need such protection. More information: BitTorrent Protocol Encryption

# Encryption options, set to none (default) or any combination of the following:
# allow_incoming, try_outgoing, require, require_RC4, enable_retry, prefer_plaintext
# The example value allows incoming encrypted connections, starts unencrypted
# outgoing connections but retries with encryption if they fail, preferring
# plaintext to RC4 encryption after the encrypted handshake
# encryption = allow_incoming,enable_retry,prefer_plaintext
encryption = allow_incoming,try_outgoing,enable_retry

The following is for DHT support. If you use public trackers, you will want to enable DHT to acquire more peers. If you only use private trackers, there is no benefit to enabling DHT support.

# Enable DHT support for trackerless torrents or when all trackers are down.
# May be set to "disable" (completely disable DHT), "off" (do not start DHT),
# "auto" (start and stop DHT as needed), or "on" (start DHT immediately).
# The default is "off". For DHT to work, a session directory must be defined.
# dht = auto

# UDP port to use for DHT. 
# dht_port = 6881

# Enable peer exchange (for torrents not marked private)
# peer_exchange = yes

Be sure to forward the proper port(s) with your router if you use one. A decent guide per router make/model can be found here.


One could recompile libtorrent from ABS with a new switch to configure pre-allocation:

 ./configure --prefix=/usr --disable-debug --with-posix-fallocate

And enable it by adding the following to your rtorrent.rc:

 # Preallocate files; reduces defragmentation on filesystems.
 system.file_allocate.set = yes

It will pre-allocate files before downloading the torrent but this has its pros and cons:


This limits/avoids fragmentation of the filesystem


This introduces a delay during the pre-allocation if the filesystem does not support natively the fallocate syscall.

So I recommend its use for users of xfs, ext4 and btrfs which have native fallocate syscall. They will see no delay during preallocation and no fragmented filesystem. Others filesystems will cause delay at pre-allocation time but no fragmented file.


rTorrent relies exclusively on keyboard shortcuts for user input. Here are the basics for quick reference:

Cmd Action
Ctrl-q Close rTorrent, done twice makes the program shutdown without waiting to send stopping information to the trackers.
Left Returns to the previous screen
Right Goes to the next screen
a, s, d Increase global upload throttle about 1/5/50 KB/s
A, S, D Increase global download throttle about 1/5/50 KB/s
z, x, c Decrease global upload throttle about 1/5/50 KB/s
Z, X, C Decrease global download throttle about 1/5/50 KB/s
Ctrl-S Starts download
Ctrl-D Stops an active download, removes a stopped 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.

A complete guide is available on the rTorrent wiki (see: rTorrent User Guide).

Redundant mapping

Template:Keypress is often used for terminal control to stop screen output while Template:Keypress is used to start it. These mappings may interfere with rTorrent. Check to see if these terminal options are bound to a mapping:

$ stty -a
swtch = <undef>; start = ^Q; stop = ^S; susp = ^Z; rprnt = ^R; werase = ^W; lnext = ^V;

To remove the mappings, change the terminal characteristics to undefine the aforementioned special characters (i.e. stop and start):

# stty stop undef
# stty start undef

To remove these mappings automatically at startup you may add the two preceding commands to your Template:Filename file.

Use rTorrent with Screen

Screen is a program that will allow CLI applications to be run in the background and without X running.

Install screen:

# pacman -S screen

And then copy screenrc to your home directory as normal user:

$ cp /etc/screenrc ~/.screenrc

To have rTorrent always start with screen, add the following to your .screenrc file:

$ screen -t rtorrent rtorrent 

Now, you can start rTorrent with screen simply by running screen command from a terminal. Control-a followed by d will detach screen, and running screen -r will open screen again.

It is recommended to disable screen flow-control, because it interferes with Control-q command which is not sent to rTorrent. Disable it adding to your .screenrc:

defflow off

On a remote machine

Most setups of rTorrent on a remote machine involve using Screen. Supposing you have a detached Screen session with rtorrent on the remote machine (and the option to SSH into it), you can gain access to it using:

/usr/bin/ssh -t -p <ssh port on remote machine> <user>@<remote machine> screen -RD

If you want immediate access on startup, you will need to upload a key from your machine to remote host (so you will not be prompted for a password) and setup a terminal to run the command above. An inittab example using rungetty on virtual console 4:

sam:45:respawn:/sbin/rungetty tty4 -u <local user> -- /usr/bin/ssh -t -p <ssh port on remote machine> <remote user>@<remote machine> screen -RD

rtorrent Daemon with screen

I use this on my home server to run rtorrent w/ screen as a daemon. With the username user Just create an rtorrent file in your /etc/rc.d/ and add the following code.


. /etc/rc.conf
. /etc/rc.d/functions

case "$1" in
    stat_busy "Starting rtorrent"
    su user -c 'screen -d -m -S rtorrent rtorrent' &> /dev/null
    if [ $? -gt 0 ]; then
      add_daemon rtorrent
    stat_busy "Stopping rtorrent"
    killall -w -s 2 /usr/bin/rtorrent &> /dev/null
    if [ $? -gt 0 ]; then
      rm_daemon rtorrent
    $0 stop
    sleep 1
    $0 start
    echo "usage: $0 {start|stop|restart}"
exit 0
Note: works with tmux, too. "su rtorrent -c 'tmux -d -s rtorrent rtorrent' &> /dev/null"

Make File Executable

sudo chmod +x /etc/rc.d/rtorrent

On a remote computer I use the following script to connect to the server's daemon process:

ssh -t rtorrent@ 'screen -r'

Setting the working directory .rtorrent.rc

When I used the above script to start a daemon it worked fine until I added a .rtorrent.rc file into the users directory. This was caused the use of by relative paths the .rtorrent.rc file that assumed the instance for rtorrent was running in the users home folder. As I wanted to run multiple instances of rtorrent under different users I opted to change the /etc/rc.d/ script to the following :

    su username -c 'cd /home/username && screen -d -m -S rtorrent rtorrent' &> /dev/null

You could instead set absolute paths in the rc file if you preferred.

Running Multiple Daemons

It's also possible using a very similar script to that above to run the daemon user multiple users. To achieve this you can create an /etc/rc.d script for each user that you want to run rtorrent under.

Then change the killall line on the script to:

    su username -c 'killall -w -s 2 /usr/bin/rtorrent' &> /dev/null

It's possible to use a single script to manage all the users but I found this was easier to manage.

Additional Tips

  • To use rTorrent with a tracker that uses https, do the following as root:
cd /etc/ssl/certs
wget --no-check-certificate https://www.geotrust.com/resources/root_certificates/certificates/Equifax_Secure_Global_eBusiness_CA-1.cer
mv Equifax_Secure_Global_eBusiness_CA-1.cer Equifax_Secure_Global_eBusiness_CA-1.pem

And from now on run rTorrent with:

rtorrent -o http_capath=/etc/ssl/certs

Be sure to change .screenrc to reflect this change if you use screen:

screen -t rtorrent rtorrent -o http_capath=/etc/ssl/certs

Automatically Move Completed Torrent Data to 'Completed' Folders

NOTE: Currently, this part requires either the svn version of rtorrent/libtorrent or having applied the patch to 0.8.6 that adds 'equal'.

NOTE: If you're having trouble with this tip, it's probably easier to follow this

It is possible to have rtorrent sort completed torrent data to specific folders based on which 'watch' folder you drop the *.torrent into while continuing to seed. Many examples show how to do this with torrents downloaded by rtorrent. The problem is when you try to drop in 100% done torrent data and then have rtorrent check the data and resume. It will not be sorted.

As a solution, use the following example in your ~/.rtorrent.rc. Make sure to change the paths.

# location where new torrent data is placed, and where you should place your
# 'complete' data before you place your *.torrent file into the watch folder
directory = /home/user/torrents/incomplete

# schedule a timer event named 'watch_directory_1':
# 1) triggers 10 seconds after rtorrent starts
# 2) triggers at 10 second intervals thereafter
# 3) Upon trigger, attempt to load (and start) new *.torrent files found in /home/user/torrents/watch/
# 4) set a variable named 'custom1' with the value "/home/user/torrents/complete"
# NOTE: if you do not want it to automatically start the torrent, change 'load_start' to 'load'
schedule = watch_directory_1,10,10,"load_start=/home/user/torrents/watch/*.torrent,d.set_custom1=/home/user/torrents/complete"

# insert a method with the alias 'checkdirs1'
# 1) returns true if the current path of the torrent data is not equal to the value of custom1
# 2) otherwise, returns false

# insert a method with the alias 'movecheck1'
# 1) returns true if all 3 commands return true ('result of checkdirs1' && 'torrent is 100% done', 'custom1 variable is set')
# 2) otherwise, returns false

# insert a method with the alias 'movedir1'
# (a series of commands, separated by ';') 
# 1) "set path of torrent to equal the value of custom1";
# 2) "mv -u <current data path> <custom1 path>";
# 3) "clear custom1", "stop the torrent","resume the torrent"
# 4) stop the torrent
# 5) start the torrent (to get the torrent to update the 'base path')

# set a key with the name 'move_hashed1' that is triggered by the hash_done event.
# 1) When hashing of a torrent completes, this custom key will be triggered.
# 2) when triggered, execute the 'movecheck1' method and check the return value.
# 3) if the 'movecheck' method returns 'true', execute the 'movedir1' method we inserted above.
# NOTE: 'branch' is an 'if' conditional statement: if(movecheck1){movedir1}

You can add additional watch folders and rules should you like to sort your torrents into special folders.

For example, if you would like the torrents to download in: /home/user/torrents/incomplete and then sort the torrent data based on which folder you dropped the *.torrent into: /home/user/torrents/watch => /home/user/torrents/complete /home/user/torrents/watch/iso => /home/user/torrents/complete/iso /home/user/torrents/watch/music => /home/user/torrents/complete/music

You can have the following in your .rtorrent.rc:

directory = /home/user/torrents/incomplete
schedule = watch_directory_1,10,10,"load_start=/home/user/torrents/watch/*.torrent,d.set_custom1=/home/user/torrents/complete"

schedule = watch_directory_2,10,10,"load_start=/home/user/torrents/watch/iso/*.torrent,d.set_custom1=/home/user/torrents/complete/iso"

schedule = watch_directory_3,10,10,"load_start=/home/user/torrents/watch/music/*.torrent,d.set_custom1=/home/user/torrents/complete/music"


Also see pyroscope especially the rtcontrol examples. There is an AUR package.

Send Text Message Upon Torrent Completion Using GMail

Cell phone providers allow you to "email" your phone:

Verizon: 10digitphonenumber@vtext.com
AT&T: 10digitphonenumber@txt.att.net
Former AT&T customers: 10digitphonenumber@mmode.com
Sprint: 10digitphonenumber@messaging.sprintpcs.com
T-Mobile: 10digitphonenumber@tmomail.net
Nextel: 10digitphonenumber@messaging.nextel.com
Cingular: 10digitphonenumber@cingularme.com
Virgin Mobile: 10digitphonenumber@vmobl.com
Alltel: 10digitphonenumber@alltelmessage.com OR
CellularOne: 10digitphonenumber@mobile.celloneusa.com
Omnipoint: 10digitphonenumber@omnipointpcs.com
Qwest: 10digitphonenumber@qwestmp.com
Telus: 10digitphonenumber@msg.telus.com
Rogers Wireless: 10digitphonenumber@pcs.rogers.com
Fido: 10digitphonenumber@fido.ca
Bell Mobility: 10digitphonenumber@txt.bell.ca
Koodo Mobile: 10digitphonenumber@msg.koodomobile.com
MTS: 10digitphonenumber@text.mtsmobility.com
President's Choice: 10digitphonenumber@txt.bell.ca
Sasktel: 10digitphonenumber@sms.sasktel.com
Solo: 10digitphonenumber@txt.bell.ca
  • Install Heirloom's mailx program:
pacman -S mailx-heirloom
  • Clear the /etc/mail.rc file and enter:
Note: Older versions of Heirloom's mailx use /etc/nail.rc.
set sendmail="/usr/bin/mailx"
set smtp=smtp.gmail.com:587
set smtp-use-starttls
set ssl-verify=ignore
set ssl-auth=login
set smtp-auth-user=USERNAME@gmail.com
set smtp-auth-password=PASSWORD

Now to send the text, we must pipe a message to the mailx program.

  • Make a bash script (/path/to/mail.sh):
echo "$@: Done" | mailx 5551234567@vtext.com

Where the $@ is a variable holding all the arguments passed to our script.

  • And finally, add the important ~/.rtorrent.rc line:
system.method.set_key = event.download.finished,notify_me,"execute=/path/to/mail.sh,$d.get_name="

Breaking it down:

notify_me is the command id, which may be used by other commands, it can be just about anything you like, so long as it is unique.

execute= is the rtorrent command, in this case to execute a shell command.

/path/to/mail.sh is the name of our script (or whatever command you want to execute) followed by a comma separated list of all the switches/arguments to be passed.

$d.get_name= 'd' is an alias to whatever download triggered the command, get_name is a function which returns the name of our download, and the '$' tells rTorrent to replace the command with its output before it calls execute.

The end result? When that torrent, 'All Live Nudibranches', that we started before leaving for work finishes, we will be texted:

All Live Nudibranches: Done

Make "active" tab show only active torrents

The rtorrent doesn't list the active tab properly by default, add this line to your .rtorrent.rc to show only active torrents

schedule = filter_active,30,30,"view_filter = active,\"or={d.get_up_rate=,d.get_down_rate=}\""

Now press 9 in your rtorrent client to see the changes in action.

See Also

  • Screen Tips
  • A detailed introduction to BitTorrent including definitions of terms terms.
  • the rTorrent Community Wiki is designed to have information on all things rTorrent, including a comprehensive reference to rTorrent's command language.
Display rTorrent stats in conky

See this thread.

Misc Info


rTorrent is currently built using xmlrpc-c which is needed for some web GUIs, such as rutorrent.


If you want to use rtorrent with some web GUI's such as rutorrent you need to add the following to you config:

scgi_port = localhost:5000

For more information, see the rTorrent wiki

See also

Web GUI clients for rTorrent

  • WTorrent is a web interface to rtorrent programmed in php using Smarty templates and XMLRPC for PHP library.
  • nTorrent is a graphical user interface client to rtorrent (a cli torrent client) written in Java.
  • rTWi is a simple rTorrent web interface written in PHP.
  • Rtgui is a web based front end for rTorrent written in PHP and uses XML-RPC to communicate with the rTorrent client.
  • rutorrent (guide in bbs) is a web-based front-end with an interface very similar to uTorrent which supports many plugins and advanced features.

CLI clients for rTorrent

  • PyroScope is a collection of command line tools for rTorrent. It provides commands for creating and modifying torrent files, moving data on completion without having multiple watch folders, and mass-controlling download items via rTorrent's XML-RPC interface: searching, start/stop, deleting items with or without their data, etc. It also offers a documented Python API, with which these tools are implemented.

Additional resources