This is a mirror for the old http://libtorrent.rakshasa.no/ site based on the archives from the wayback machine.

If you find any broken links please let me know via mail.

Common Tasks in rTorrent for Dummies

This page is for showing examples on how to use the many options in rTorrent. Only real examples you can apply immediately, no theory at all.

1. Saving torrent state and resume data between sessions
2. Watch a directory for torrents
3. Create symbolic links to indicate the download state
4. Move completed torrents
5. Move completed torrents to different directory depending on watch directory
6. Move .torrent file after loading it manually
7. Send email for completed downloads
8. Stop torrents after reaching a specified upload ratio
9. Delete data files when removing incomplete downloads
10. Scheduling download rate
11. Using custom throttles
12. Using a different configuration file
13. Adding fast resume data to torrent files
14. Starting rTorrent on System Startup
15. Using custom views
16. Start or stop all torrents

Saving torrent state and resume data between sessions

# Point to a directory where rTorrent will save the torrent files. You
# may also use relative paths if you want different session
# directories depending on where you execute rtorrent.
#
# session = ./session

session = ~/Download/session

Watch a directory for torrents

# Watch a directory for new torrents, restart torrents that have been
# copied back and stop those that have been deleted.

schedule = watch_directory,10,10,load_start=~/Download/watch/*.torrent
schedule = tied_directory,10,10,start_tied=
schedule = untied_directory,10,10,close_untied=

# Watch another directory with a different destination. (0.7.7+)

schedule = watch_directory_2,10,10,"load_start=~/Download/watch_stuff/*.torrent,d.set_directory=~/Download/stuff/"

Create symbolic links to indicate the download state

# Create symlinks in the watch directory with a suffix indicating the
# download state.

on_start    = link1,"create_link=tied,,.started"
on_stop     = link1,"delete_link=tied,,.started"
on_finished = link1,"create_link=tied,,.finished"
on_erase    = link1,"delete_link=tied,,.finished"

# Create symlinks in the same directory as the download.

on_start    = link2,"create_link=base_path,,.started"
on_stop     = link2,"delete_link=base_path,,.started"
on_finished = link2,"create_link=base_path,,.finished"
on_erase    = link2,"delete_link=base_path,,.finished"

# Create a symlink in another directory without a suffix.
# You need to quote the command in this case.

on_finished = link3,"create_link=base_filename,/files,"

Move completed torrents

When the torrent finishes, it executes "mv <base_path> ~/Download/" and then sets the destination directory to "~/Download/". (0.8.4+)

system.method.set_key = event.download.finished,move_complete,"execute=mv,-u,$d.get_base_path=,~/Download/;d.set_directory=~/Download/"

# On MacOSX and *BSD.
system.method.set_key = event.download.finished,move_complete,"execute=mv,-n,$d.get_base_path=,~/Download/;d.set_directory=~/Download/"

For versions 0.7.7 to 0.8.3 use this:

on_finished = move_complete,"execute=mv,-u,$d.get_base_path=,~/Download/ ;d.set_directory=~/Download/"

# On MacOSX and *BSD.
on_finished = move_complete,"execute=mv,-n,$d.get_base_path=,~/Download/ ;d.set_directory=~/Download/"

Move completed torrents to different directory depending on watch directory

Each watch directory adds torrents with the final destination stored in the "custom1" string of the download. You can check this string with ctrl-X then "print=$d.get_custom1=" in the client. In rtorrent 0.8.4+:

schedule = watch_directory_1,10,10,"load_start=~/Download/watch_stuff1/*.torrent,d.set_custom1=~/Download/stuff1/"
schedule = watch_directory_2,10,10,"load_start=~/Download/watch_stuff2/*.torrent,d.set_custom1=~/Download/stuff2/"

# On completion, move the torrent to the directory from custom1.
system.method.set_key =event.download.finished,move_complete,"d.set_directory=$d.get_custom1= ;execute=mv,-u,$d.get_base_path=,$d.get_custom1="

# On MacOSX and *BSD.
system.method.set_key =event.download.finished,move_complete,"d.set_directory=$d.get_custom1= ;execute=mv,-n,$d.get_base_path=,$d.get_custom1="

For versions 0.7.7 to 0.8.3 use this on_finished handler instead:

on_finished = move_complete,"execute=mv,-u,$d.get_base_path=,$d.get_custom1= ;d.set_directory=$d.get_custom1="

# On MacOSX and *BSD.
on_finished = move_complete,"execute=mv,-n,$d.get_base_path=,$d.get_custom1= ;d.set_directory=$d.get_custom1="

Move .torrent file after loading it manually

Do NOT use this if in combination with a watch folder!

When loading a torrent manually (i.e. 'load' and 'load_start'), moves the original XXX.torrent file to a directory (for example you may want to move the file to the trash bin, since rtorrent made a copy of it in the session directory).

# 0.8.4+ Linux
system.method.set_key = event.download.inserted_new,move_tor,"execute=mv,-u,$d.get_loaded_file=,/path/to/trash_bin"

# 0.8.4+ MacOSX and *BSD.
system.method.set_key = event.download.inserted_new,move_tor,"execute=mv,-n,$d.get_loaded_file=,/path/to/trash_bin"

Send email for completed downloads

For 0.8.4+

# First and only argument to rtorrent_mail.sh is completed file's name (d.get_name)
system.method.set_key = event.download.finished,notify_me,"execute=~/rtorrent_mail.sh,$d.get_name="

Assuming you have a working mail system and this script is executable.

rtorrent_mail.sh :

#!/bin/sh
echo "$(date) : $1 - Download completed." | mail -s "[rtorrent] - Download completed : $1" alerts@example.com

Stop torrents after reaching a specified upload ratio

For rTorrent 0.8.4 please see RTorrentRatioHandling.

For versions before 0.8.4:

# stop_on_ratio = min_ratio,min_upload,max_ratio
#
# Example:

schedule = ratio,60,60,"stop_on_ratio=200,50M,300"

The "stop_on_ratio" command can be scheduled to stop torrents that have reached a specified upload ratio. The above example will stop a torrent once it has uploaded 200% of the torrent size, unless less than 50MB has been uploaded and the ratio is below 300%.

Use shift-I to make a torrent ignore this and other commands.

Delete data files when removing incomplete downloads

If you often add older torrents and find that they never complete due to lack of seeds, these commands will automatically delete the data files when removing an incomplete download (either manually or with remove_untied by removing the tied file). Note that all files will be removed on incomplete or partially complete downloads, even those files from it which are in fact completely downloaded.

WARNING: Do not use this setup if you ever change a download's base_path to something like /home/bob/ or similar, or you could lose a lot of files!

# Enable removal for all downloads added from this watch directory.
schedule = watch_directory,10,10,"load_start=~/Download/watch_stuff/*.torrent,d.set_custom2=1"

# Clear custom2 when download completes.
on_finished = set_done_var,d.set_custom2=

# Erase data files when a download is removed that still has custom2 set.
on_erase = rm_files,"branch=d.get_custom2=,\"execute={rm,-rf,--,$d.get_base_path=}\""

To make an incomplete download exempt from the automated deletion on removal, select the download then press Ctrl-X and enter "d.set_custom2=".

Scheduling download rate

schedule = throttle_1,01:00:00,24:00:00,download_rate=0
schedule = throttle_2,05:00:00,24:00:00,download_rate=25 

Every day "throttle_1" gets triggered at 01:00 and sets the download rate to unlimited, while "throttle_2" sets it to 25kb at 05:00. Using this the client may be made to perform a somewhat crude form of bandwidth scheduling.

Using custom throttles

Since rtorrent 0.8.5, you can define different throttle rates for (groups of) downloads or IP ranges. These throttles borrow bandwidth from the global throttle and thus are limited by it too.

throttle_up=slowupload,10
throttle_down=slowdownload,50
throttle_up=sloweverything,10
throttle_down=sloweverything,50
throttle_ip=NULL,192.168.0.0/16

The "slowupload" throttle limits the upload to 10 kb/s. The "slowdownload" throttle limits download to 50 kb/s. The "sloweverything" throttle limits both.

You can assign throttles to a stopped download with Ctrl-T. The NULL throttle is a special unlimited throttle that bypasses the global throttle.

Ticket #20 has some more detailed instructions throughout the comments block.

Using a different configuration file

$ rtorrent -n -o import=~/foo.rc

The '-n' switch tells rtorrent not to load the default resource file, while the import option loads '~/foo.rc'.

Adding fast resume data to torrent files

When you are the first seeder for a torrent, rTorrent will normally have to hash-check all files even if you just created the torrent file from them and thus know that they are correct. To eliminate this step, the following Perl script by Josef Drexler can add rTorrent's fast resume data to the torrent file: ​http://libtorrent.rakshasa.no/downloads/rtorrent_fast_resume.pl.

Usage:

$ rtorrent_fast_resume.pl [base-directory] < original.torrent > modified.torrent

Then you can distribute the original torrent file and load the modified file into rTorrent and start seeding without needing a hash check. The base directory specifies where the files in the torrent are located, equivalent to the "directory" option in rtorrent.rc. If not specified, the files are assumed to be in the current directory.

Note that this script requires the Convert::Bencode module from CPAN, if this module is not available on your system you will need to install it first:

$ perl -MCPAN -e 'install Convert::Bencode'

Starting rTorrent on System Startup

Debian

Step 1: Assuming a Debian-based distribution, create /etc/init.d/rtorrent with one of the ​rtorrentInit files attached to this page, editing the Configuration to suit your needs.

Step 2: Make sure it has appropriate permissions:

# ls -l /etc/init.d/rtorrent
-rwxr-xr-x 1 root root 3000 2007-03-06 22:40 /etc/init.d/rtorrent

Step 3: Update your init system (as sudo/su/root):

# update-rc.d rtorrent defaults

Gentoo

Step 1: Assuming a Gentoo distribution, and having the daemon USE flag enabled ; select the user you want rtorrent to be runned as modifying /etc/conf.d/rtorrentd

Step 2: Update your init system (as sudo/su/root):

# rc-update add rtorrentd default

Using custom views

Show downloads currently uploading or downloading in active view. Update every 30 seconds.

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

Show downloads currently downloading in active view. Update every 30 seconds.

schedule = filter_active,30,30,"view_filter = active,d.get_down_rate="

Show downloads currently uploading in active view. Update every 30 seconds.

schedule = filter_active,30,30,"view_filter = active,d.get_up_rate="

Switch to a custom view with

ui.current_view.set = viewname

Start or stop all torrents

In the userinterface:

^x d.multicall=,d.start=

Replace d.start= with d.stop= to stop all torrents