[[libtorrentMirror]]

= 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.

[[PageOutline(2,,inline)]]


== 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 [wiki: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 [http://libtorrent.rakshasa.no/wiki/RTorrentCommonTasks#tkt-changes-hdr 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