From Gentoo Wiki
Jump to:navigation Jump to:search

rTorrent is a highly configurable BitTorrent client based on libtorrent and ncurses.


USE flags

USE flags for net-p2p/rtorrent BitTorrent Client using libtorrent

debug Enable extra debug codepaths, like asserts and extra output. If you want to get meaningful backtraces see https://wiki.gentoo.org/wiki/Project:Quality_Assurance/Backtraces
selinux !!internal use only!! Security Enhanced Linux support, this must be set by the selinux profile or breakage will occur
test Enable dependencies and/or preparations necessary to run tests (usually controlled by FEATURES=test but can be toggled independently)
xmlrpc Support for xml-rpc library


Install net-p2p/rtorrent:

root #emerge --ask net-p2p/rtorrent


user $curl -Ls "https://raw.githubusercontent.com/wiki/rakshasa/rtorrent/CONFIG-Template.md" \
    | grep -A9999 '^######' | grep -B9999 '^### END' \
    | sed -re "s:/home/USERNAME:$HOME:" >~/.rtorrent.rc
mkdir ~/rtorrent

The RTorrent configuration is stored in the user's ~/.rtorrent.rc. A lot can be configured, for this reason, the configuration is divided in sections.

Any configuration should start with using the modernized rTorrent wiki config template. The configuration is loaded from the file ~/.rtorrent.rc by default (that is the hidden file .rtorrent.rc in your user home directory). This configuration uses 0.9.x syntax and is tested using 0.9.6

FILE /home/user/.rtorrent.rc
# Instance layout (base paths)
method.insert = cfg.basedir, private|const|string, (cat,"/home/USERNAME/rtorrent/")
method.insert = cfg.watch,   private|const|string, (cat,(cfg.basedir),"watch/")
method.insert = cfg.logs,    private|const|string, (cat,(cfg.basedir),"log/")
method.insert = cfg.logfile, private|const|string, (cat,(cfg.logs),"rtorrent-",(system.time),".log")

# Create instance directories
execute.throw = bash, -c, (cat,\
    "builtin cd \"", (cfg.basedir), "\" ",\
    "&& mkdir -p .session download log watch/{load,start}")

# Listening port for incoming peer traffic (fixed; you can also randomize it)
network.port_range.set = 50000-50000
network.port_random.set = no

# Peer settings
throttle.max_uploads.set = 100
throttle.max_uploads.global.set = 250

throttle.min_peers.normal.set = 20
throttle.max_peers.normal.set = 60
throttle.min_peers.seed.set = 30
throttle.max_peers.seed.set = 80
trackers.numwant.set = 80

protocol.encryption.set = allow_incoming,try_outgoing,enable_retry

# Limits for file handle resources, this is optimized for
# an `ulimit` of 1024 (a common default). You MUST leave
# a ceiling of handles reserved for rTorrent's internal needs!
network.http.max_open.set = 50
network.max_open_files.set = 600
network.max_open_sockets.set = 300

# Memory resource usage (increase if you have a large number of items loaded,
# and/or the available resources to spend)
pieces.memory.max.set = 1800M
network.xmlrpc.size_limit.set = 4M

# Basic operational settings (no need to change these)
session.path.set = (cat, (cfg.basedir), ".session")
directory.default.set = (cat, (cfg.basedir), "download/")
log.execute = (cat, (cfg.logs), "execute.log")
##log.xmlrpc = (cat, (cfg.logs), "xmlrpc.log")
execute.nothrow = bash, -c, (cat, "echo >",\
    (session.path), "rtorrent.pid", " ", (system.pid))

# Other operational settings (check & adapt)
encoding.add = utf8
system.umask.set = 0027
system.cwd.set = (directory.default)
network.http.dns_cache_timeout.set = 25
##network.http.capath.set = "/etc/ssl/certs"
##network.http.ssl_verify_peer.set = 0
##network.http.ssl_verify_host.set = 0
##pieces.hash.on_completion.set = no
##keys.layout.set = qwerty

##view.sort_current = seeding, greater=d.ratio=
schedule2 = monitor_diskspace, 15, 60, ((close_low_diskspace, 1000M))

# Some additional values and commands
method.insert = system.startup_time, value

And here is a simple start script that you should use before you tackle auto-starting rTorrent at boot time. First make it work for you, then add the bells and whistles. Copy the script to ~/rtorrent/start, and make it executable using chmod a+x ~/rtorrent/start.

FILE /rtorrent/start
#! /bin/bash
# rTorrent startup script
umask 0027
cd $(dirname "$0")

# Check for running process
export RT_SOCKET=$PWD/.scgi_local
test -S $RT_SOCKET && lsof $RT_SOCKET >/dev/null \
    && { echo "rTorrent already running"; exit 1; }
test ! -e $RT_SOCKET || rm $RT_SOCKET

# Clean up after rTorrent ends
_at_exit() {
    stty sane
    test ! -e $RT_SOCKET || rm $RT_SOCKET
trap _at_exit INT TERM EXIT

# Start rTorrent (optionally with configuration loaded
# from the directory this script is stored in)
rtorrent -D -I  # -n -o import=$PWD/rtorrent.rc

You can call it in a simple shell prompt first, but for normal operation it must be launched in a tmux session, like so:

user $tmux -2u new -n rTorrent -s rtorrent "~/rtorrent/start; exec bash"

The exec bash keeps your tmux window open if rTorrent exits, which allows you to actually read any error messages in case it exited unexpectedly.

You can of course add more elaborate start scripts, like a cron watchdog, init.d scripts or systemd units, see the rTorrent wiki for examples.


These options are pretty straightforward:

FILE /home/user/.rtorrent.rc
# Global upload and download rate in KiB. "0" for unlimited.
#throttle.global_down.max_rate.set_kb = 0
throttle.global_up.max_rate.set_kb = 75

# Default directory to save the downloaded torrents.
directory.default.set = /home/user/media/

# Default session directory. When restarting rtorrent, the torrents from this directory will be restarted.
session.path.set = /home/wim/media/session

Watching a directory

You can configure rTorrent to watch one or more directories for new torrent files and queue them automatically. You can also set a download directory for each watch directory (rather than downloading to the default download directory).

FILE /home/user/.rtorrent.rc
# A watch directory downloading to the default location
schedule2 = watch_directory_3,5,300,load.start=/home/user/media/watch/*.torrent

# Watch directories with customized download directories
schedule2 = watch_directory_1,5,60,"load.start=/home/user/media/watch_series/*.torrent,d.directory.set=/home/user/media/series"
schedule2 = watch_directory_2,5,5,"load.start=/home/wim/media/watch_music/*.torrent,d.directory.set=/home/user/media/music"
schedule2 = watch_directory_3,5,300,"load.start=/home/user/media/watch_movies/*.torrent,d.directory.set=/home/user/media/movies"

# Restart torrents that have been copied back and stop those that have been deleted
schedule2 = tied_directory,1,30,start_tied=
schedule2 = untied_directory,1,30,close_untied=

# Close torrents when diskspace is low.
schedule2 = low_diskspace,5,60,close_low_diskspace=100M
Several commands can be scheduled to run depending on two values, start and interval. The command in question is called every interval, beginning at start. The values can be seconds or a time format.
FILE /home/user/.rtorrent.rc
# Execute command after 5 seconds and again every 5 minutes
schedule2 = some_command,5,300,foo

# Execute command immediately and at 03:00
schedule2 = some_command,0,03:00,foo

Ratio handling

You can control seed time by making it dependent on each torrent's ratio. Each torrent is seeded for a minimum of min.set percent. if a total of upload.set has been uploaded. If upload.set is not reached, it will seed a maximum of max.set percent. Read the wiki on the GitHub site for different ratio groups.

FILE /home/user/.rtorrent.rc
# First, enable the default ratio group, which controls all loaded torrents. Set the limits for the group next.

Adding a self-signed certificate

Some trackers use SSL certificates, however most are not signed for various reasons. rTorrent uses the database located in /etc/ssl/certs/ca-certificates.crt. You also may want to use HTTPS because some ISPs (like Comcast) perform bandwidth shaping, effectively slowing down BitTorrent (regardless of whether your use is legitimate).

Add a certificate (if the domain was mytracker.net and the port was 443):

root #openssl s_client -connect mytracker.net:443 </dev/null 2>/dev/null | sed -n '/BEGIN CERTIFICATE/,/END CERTIFICATE/p' >> /etc/ssl/certs/ca-certificates.crt

You need to re-hash after adding a certificate:

root #c_rehash

Try with curl:

You should not get a warning regarding the self-signed certificate.

Restart rTorrent. If using the daemon:

root #rc-service rtorrentd restart

Customizing the daemonizer

The Gentoo ebuild installs a good basic init script for both openrc and systemd. However, it can be enhanced in various ways if needed. The following examples are completely optional.

Using openrc (default, applicable for all versions)

Change the the USER variable to your user account, or (better) a separate account.

FILE /etc/conf.d/rtorrentd

Starting rTorrent in the background, and run at system boot:

root #rc-service rtorrentd start
root #rc-update add rtorrentd default

Using dtach as daemonizer instead of screen (versions before 0.9.8-r1)

A smaller alternative to the app-misc/screen package is app-misc/dtach. This is all what's needed for using dtach instead of screen.

Save this patch to the system:

FILE rtorrentd-init.patch
--- /usr/portage/net-p2p/rtorrent/files/rtorrentd.init  2011-11-07 16:46:30.000000000 +0100
+++ /etc/init.d/rtorrentd   2013-12-21 10:55:01.251541772 +0100
@@ -15,13 +15,12 @@
    env TERM="xterm" \
        start-stop-daemon \
            --start \
-           --make-pidfile \
            --pidfile /var/run/rtorrentd.pid \
-           --background \
            --user $USER \
            --env HOME="${PWHOME:-/home/$USER}" \
-           --name rtorrent \
-           --exec /usr/bin/screen -- -D -m -S rtorrentd /usr/bin/rtorrent
+           --exec /usr/bin/dtach -- -n /tmp/rtorrentd.dtach /usr/bin/rtorrent
+   pgrep --newest --uid $USER --exact rtorrent >/var/run/rtorrentd.pid
    eend $?
root #USE="-daemon" emerge -av net-p2p/rtorrent app-misc/dtach
root #cp /usr/portage/net-p2p/rtorrent/files/rtorrentd.conf /etc/conf.d/rtorrentd
root #cp /usr/portage/net-p2p/rtorrent/files/rtorrentd.init /etc/init.d/rtorrentd
root #chmod +x /etc/init.d/rtorrentd
root #patch -p0 < /PATH/TO/rtorrentd-init.patch

Change the USER variable to the current user account, or (better) a separate account:

FILE /etc/conf.d/rtorrentd

If needed, give access to group members of the configured user. Add this at the end of the start() section of the init script:

FILE /etc/init.d/rtorrentd
chmod g+rw /tmp/rtorrentd.dtach
eend $?

Starting rTorrent in the background, and run at system boot:

root #rc-service rtorrentd start
root #rc-update add rtorrentd default

Login as user, or execute as a group member to attach the rtorrentd session:

user $su - p2p
user $dtach -a /tmp/rtorrentd.dtach

To detach the rtorrentd session again: press Ctrl+\ on the keyboard.

If the arrow keys don't work, enter this in one go instead:

user $tput smkx; dtach -a /tmp/rtorrentd.dtach; tput rmkx

When the arrow keys still don't work, start reading here.

Arrow keys not working

First check the value of the TERM variable the terminal application uses, and set it in the init script.

user $echo $TERM

Changing the TERM variable:

FILE /etc/init.d/rtorrentd
#env TERM="xterm" \
env TERM="linux" \
root #rc-service rtorrentd restart

If the arrow keys still do not work, try setting the TERM value to linux, even if the terminal application uses xterm. Although this setting is wrong, it doesn't seem to matter that much currently. However, it's preferred to enable the arrow keys in the terminal application instead.

It is a known limitation of dtach (and screen?), that reattaching the session in another terminal, drops the working arrow keys.

Any terminal

Enter "keyboard transmit mode" and leave "keyboard transmit mode", using tput:

user $tput smkx
user $<Here your command to reattach the rTorrent session>
user $tput rmkx


If Konsole doesn't switch to "Application Cursor Mode", you can create custom key bindings. To create the .keytab file with hacked bindings:

user $sed 's:^\(keyboard.*\)\":\1 +AppCuKeys\":;s:E\[\([ABCDFH]\):EO\1:' /usr/share/apps/konsole/default.keytab > ~/.kde4/share/apps/konsole/default+AppCuKeys.keytab

Restart Konsole, and create a new profile with the key bindings named "Default (XFree 4) +AppCuKeys". If you set TERM="linux" in your init script, choose "Linux console" key bindings instead. Select this profile, when you reattached the rtorrentd session as a user.


XTerm has "Enable Application Cursor Keys" in the toolbar, and you can set it by default in ~/.Xresources:

FILE ~/.Xresources
XTerm*vt100.appcursorDefault: true
user $xrdb -merge ~/.Xresources

If there's no toolbar, rebuild XTerm:

root #USE="toolbar" emerge -av x11-terms/xterm


Extra environment variable, if you set LANG in your users ~/.bashrc file. This doesn't affect translations, but only character set and sorting.

FILE /etc/init.d/rtorrentd
--env HOME="${PWHOME:-/home/$USER}" \
--env LANG="nl_NL@euro" \

Modifying scheduling priority

If hashing operations appear a bit heavy, try adding this at the end of the start() section of the init script:

FILE /etc/init.d/rtorrentd
renice -n 5 $(cat /var/run/rtorrentd.pid) >/dev/null
# and/or
ionice -c 3 -p $(cat /var/run/rtorrentd.pid)
eend $?

Controlling rTorrent exit

By default, the application is closed by the TERM signal. A more graceful exit would be to issue the INT signal, which is equivalent to the Ctrl+q key press in the rTorrent interface. This way, seeding quota get a last chance to be reported to the tracker. A second Ctrl+q key press is TERM exit, without waiting for the trackers to respond. After that, a KILL signal is justified.

Changing exit signals, and 1 or more seconds waiting time:

FILE /etc/init.d/rtorrentd
#start-stop-daemon --stop --signal 15 \
start-stop-daemon --stop --retry -INT/15/-INT/5/-KILL/5 \

Make rTorrent default application for magnet links

Add protocol handler under "Added Associations" section:

FILE ~/.config/mimeapps.list
[Added Associations]

Now create rtorrent shortcut:

FILE ~~/.local/share/applications/rtorrent.desktop
[Desktop Entry]
Exec=urxvtc -name rtorrent -e rtorrent %U
URxvt is example terminal, please use your preferred terminal application.