Run rtorrent Safely with a Persistent Session

Start rtorrent the lazy way and you will spend an evening hunting for half-finished files. This guide sets up a deliberate download directory and a separate persistent session directory, so you get a repeatable command, downloads that survive a restart, and a clear idea of what to back up. Allow about 15 minutes, plus the time needed to obtain a torrent or magnet URL from a source you trust.

This guide uses the installed Ubuntu package rtorrent 0.9.8-1ubuntu0.1. The local manual page is dated 25 February 2015, so the examples describe this installed release. Run the client as your normal user. Do not use sudo rtorrent: it would create downloads and session files owned by root and would make later recovery harder.

1. Confirm the installed client

Check the executable and read the built-in help before creating any directories:

$ command -v rtorrent
/usr/bin/rtorrent
$ rtorrent -h
Rakshasa's BitTorrent client version 0.9.8.
...
  -n                Don't try to load rtorrent.rc on startup
  -d <directory>    Save torrents to this directory by default
  -s <directory>    Set the session directory

The help output is longer than the excerpt above. The important check is that the program reports version 0.9.8 and accepts -d, -s and -n. The manual also documents -p a-b for a listening port range and -o key=opt,... for command-line settings.

2. Create private working directories

Choose locations that your user can write to. The example keeps completed data below ~/Downloads/rtorrent and session state below ~/.local/share/rtorrent/session:

$ mkdir -p "$HOME/Downloads/rtorrent" "$HOME/.local/share/rtorrent/session"
$ test -w "$HOME/Downloads/rtorrent" && echo 'download directory writable'
download directory writable
$ test -w "$HOME/.local/share/rtorrent/session" && echo 'session directory writable'
session directory writable

Warning: keep the session directory private. It records the state of open downloads and may include information about torrents you have loaded. The manual says that only one rtorrent instance should use a session directory, and this release does not provide locking for that directory. Running two clients against it can corrupt or overwrite state.

3. Start one controlled instance

Start rtorrent with the two directories and a port range. Replace the example port range only if it conflicts with another service or your network policy:

$ rtorrent \
    -d "$HOME/Downloads/rtorrent" \
    -s "$HOME/.local/share/rtorrent/session" \
    -p 49160-49170

The command opens the ncurses interface in the current terminal.

Checkpoint: if the interface opens without an error, leave this instance running and press Backspace. Enter the path to a torrent file or a torrent URL, then press Enter. Use a known, lawful source. The new download should appear in the main view; rtorrent does not start it merely because it was entered.

4. Start, inspect and stop a download

Select the torrent in the main view. The arrow keys move between entries and views; the right arrow opens the selected download, where the manual documents peer, tracker and file information.

If the client does not stop and you accept the consequence of skipping the tracker stop signal, press Ctrl-Q a second time. Do not use kill -9 as a normal shutdown method.

5. Make the settings repeatable with rtorrent.rc

Once the one-off command works, put the settings in ~/.rtorrent.rc. The manpage lists directory, session and port_range as configuration settings. Create the file with your own paths:

$ umask 077
$ cat > "$HOME/.rtorrent.rc" <<'EOF'
directory = /home/REPLACE_ME/Downloads/rtorrent
session = /home/REPLACE_ME/.local/share/rtorrent/session
port_range = 49160-49170
port_random = no
check_hash = yes
dht = auto
EOF

Warning: replace /home/REPLACE_ME before starting rtorrent. Do not copy that literal path. The settings enable hash checking for completed torrents and allow DHT to start when needed. The manual says DHT needs a session directory so its cache can be saved. It also says that dht = off is the default, while auto starts the DHT server for a non-private torrent and stops it after the last one is stopped.

Inspect the file before use:

$ sed -n '1,20p' "$HOME/.rtorrent.rc"
directory = /home/REPLACE_ME/Downloads/rtorrent
session = /home/REPLACE_ME/.local/share/rtorrent/session
port_range = 49160-49170
port_random = no
check_hash = yes
dht = auto

Start the client with rtorrent alone after replacing the path. By default it tries to load ~/.rtorrent.rc. Use -n only for a deliberate temporary run that must not load that file; command-line settings supplied with -o or -O override resource-file settings.

6. Recover from common mistakes

If rtorrent reports that it cannot load the configuration, run rtorrent -n with explicit -d and -s options. This bypasses the file without deleting it. Check spelling, absolute paths and permissions before editing:

$ ls -ld "$HOME/Downloads/rtorrent" "$HOME/.local/share/rtorrent/session"
$ sed -n 'l' "$HOME/.rtorrent.rc"

If a download was removed or its files were truncated, stop and close the torrent first. The manual documents Ctrl-E for setting the create or resize flags, and Ctrl-R for a hash check. These operations can create or change files, so confirm the path and keep a backup before using them. If you only need to remove the torrent's association with its tied file, the manual documents U; do not press it accidentally when you meant to stop a download.

Recovery: to undo this guide's configuration without touching downloaded data, stop rtorrent cleanly, copy the configuration for reference, and remove the session directory only after confirming that no download still needs it:

$ cp --preserve=mode,timestamps "$HOME/.rtorrent.rc" "$HOME/.rtorrent.rc.backup"
$ rm -f "$HOME/.rtorrent.rc"
$ printf '%s\n' 'Configuration disabled; download and session data retained'

The final command removes only the per-user configuration file. Do not recursively remove the session directory as a troubleshooting shortcut. It contains state that may be needed to resume open downloads.

Done means