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/larry:$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/larry/.rtorrent.rc
# Instance layout (base paths)
method.insert = cfg.basedir, private|const|string, (cat,"/home/larry/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:

user $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/larry/.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/larry/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/larry/.rtorrent.rc
# A watch directory downloading to the default location
schedule2 = watch_directory_3,5,300,load.start=/home/larry/media/watch/*.torrent

# Watch directories with customized download directories
schedule2 = watch_directory_1,5,60,"load.start=/home/larry/media/watch_series/*.torrent,d.directory.set=/home/larry/media/series"
schedule2 = watch_directory_2,5,5,"load.start=/home/larry/media/watch_music/*.torrent,d.directory.set=/home/larry/media/music"
schedule2 = watch_directory_3,5,300,"load.start=/home/larry/media/watch_movies/*.torrent,d.directory.set=/home/larry/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/larry/.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/larry/.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 rtorrent 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, built-in daemon)

This uses the built-in daemon mode, disabling the user interface. You can only control it via XML-RPC.

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

FILE /etc/conf.d/rtorrent

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

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

Using openrc with dtach as daemonizer

It is also possible to work in the user interface, and use an external daemonizer like screen. A smaller alternative to the app-misc/screen package is app-misc/dtach. This is all what's needed for using dtach instead of the built-in daemon.

Save next two files to the system:

FILE /etc/init.d/rtorrentd
# Copyright 1999-2024 Gentoo Authors
# Distributed under the terms of the GNU General Public License v2

description="rTorrent BitTorrent client over dtach"

PWHOME="$(getent passwd $USER | awk -F ':' '{ print $6 }')"
dtach_tmpfile="$(mktemp -u /tmp/rtorrentd.XXXXXXXXXX)"

description_attach="Attaches to the session (interactive console) of the rTorrent client"

start_stop_daemon_args="--env HOME=${PWHOME:-/home/$USER} --env LANG=${LANG} --env TERM=${TERM:-linux}"
command_args="-n ${dtach_tmpfile} ${rtorrent_command} ${RTORRENT_OPTS}"
## Graceful exit:

   use net ypbind nis
   after slapd mysqld postgresql

   ppid="$(lsof -a -U -u $USER | grep ${dtach_tmpfile} | awk '{ print $2 }')"
   pgrep -P ${ppid} 1>${pidfile} 2>/dev/null || return 1

   ## Modifying scheduling priority:
   #renice -n 5 $(cat ${pidfile}) >/dev/null
   ## and/or
   #ionice -c 3 -p $(cat ${pidfile})

   ## Group access to the rTorrent session:
   #chmod g+rw ${dtach_tmpfile}

   return 0

   # Session still running?
   test "$(ps -q $(cat ${pidfile}) -o comm=)" = "rtorrent main" || rm -f ${pidfile}

   ppid="$(ps -q $(cat ${pidfile}) -o ppid= | awk '{ print $1 }')"
   dtach_tmpfile="$(cat /proc/${ppid}/cmdline | awk -F '\000' '{ print $3 }')"

   if [ -S "${dtach_tmpfile}" ]; then
      if [ "${ENABLE_ARROWS}" = "yes" ]; then
         tput smkx ; eval "${command}" -a "${dtach_tmpfile}" "${DTACH_OPTS}" ; tput rmkx
         eval "${command}" -a "${dtach_tmpfile}" "${DTACH_OPTS}"
      eerror "The determined socket file for dtach could not be found!"
      eerror "Did the process crash?"

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

FILE /etc/conf.d/rtorrentd


root #chmod +x /etc/init.d/rtorrentd
root #emerge -av app-misc/dtach

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

FILE /etc/init.d/rtorrentd
chmod g+rw ${dtach_tmpfile}

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

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.*; tput rmkx

It is easier to use the attach function of the init script instead:

user $rc-service rtorrentd attach

It has a configuration option to enable the arrow keys:

FILE /etc/conf.d/rtorrentd

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 config file.

user $echo $TERM

Changing the TERM variable:

FILE /etc/conf.d/rtorrentd
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/konsole/default.keytab > ~/.local/share/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


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

FILE /etc/conf.d/rtorrentd

Modifying scheduling priority

If hashing operations appear a bit heavy, try adding this in the start_post() section of the init script:

FILE /etc/init.d/rtorrentd
renice -n 5 $(cat ${pidfile}) >/dev/null
# and/or
ionice -c 3 -p $(cat ${pidfile})

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

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.