From Gentoo Wiki
Jump to: navigation, search

This article has some todo items:

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


USE flags

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

daemon Uses app-misc/screen to daemonize this application local
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 global
ipv6 Add support for IP version 6 global
selinux !!internal use only!! Security Enhanced Linux support, this must be set by the selinux profile or breakage will occur global
test Workaround to pull in packages needed to run with FEATURES=test. Portage-2.1.2 handles this internally, so don't set it in make.conf/package.use anymore global
xmlrpc Support for xml-rpc library global


Install net-p2p/rtorrent:

root #emerge --ask net-p2p/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.


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.set_directory=/home/user/media/series"
schedule2 = watch_directory_2,5,5,"load_start=/home/wim/media/watch_music/*.torrent,d.set_directory=/home/user/media/music"
schedule2 = watch_directory_3,5,300,"load_start=/home/user/media/watch_movies/*.torrent,d.set_directory=/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. However, it can be enhanced in various ways if needed. The following examples are completely optional.

Using screen as daemonizer (default)

TODO: Please write the screen specific part.

This is what's needed for using screen.

root #USE="daemon" emerge -av net-p2p/rtorrent

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

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.