Anime-Sanctuary

A seedbox with rTorrent and ruTorrent

How do you set up a seedbox with rTorrent and ruTorrent on Debian? We build a program that downloads free files around the clock, and a password-protected web page to run it.

Course
Tutorial 29 of 35
Time
45 min to read
Tested with
Debian 13.7, rTorrent 0.9.8, ruTorrent 5.3.21, Apache 2.4.69, PHP 8.4
What you will be able to do
  • Run rTorrent as a service, under a dedicated account.
  • Plug ruTorrent into it through a socket, with no exposed port.
  • Protect the page with a password and HTTPS.
  • Fetch your files over SFTP, locked inside their folder.

Before you start: Your first website with Apache, Users, sudo and file permissions, A firewall with ufw, Reverse proxy, HTTPS with Let's Encrypt.

Contents
  1. The pieces of the setup
  2. What a commercial seedbox offers
  3. A dedicated account and its folders
  4. Install and configure rTorrent
  5. Run rTorrent as a service
  6. Install ruTorrent and plug it in
  7. Password and HTTPS with Apache
  8. A first free file, and the plugins
  9. Fetch your files over SFTP
  10. Back up the session
  11. If it fails
  12. What's next
  13. Sources

How do you set up a seedbox with rTorrent and ruTorrent on Debian? A seedbox is a server that downloads and shares files around the clock, so your computer doesn't have to stay on. Here it'll handle free files, like the Debian installation image, which is published to be redistributed. We build it in two pieces: a program that works behind the scenes, and a web page to tell it what to do. At the end, you open an address protected by a password, watch the download move, and fetch the file through an account limited to its folder.

The pieces of the setup

Peer-to-peer (BitTorrent) is a way to exchange files with no central server: everyone who downloads a file immediately sends pieces of it to the others. A small .torrent file describes what you want and how to reach the others. Debian publishes one for each of its installation images, and that's our test file.

Two programs share the work. rTorrent is the client: it talks to the other machines and writes the files to disk, with no screen. ruTorrent is a web page written in PHP: it shows the list of downloads and passes your instructions to rTorrent.

They still need to talk to each other. They use the SCGI protocol, a simple way to pass a request along, and we send it through a Unix socket: a special file that works as a pipe between two programs on the same machine. A file has no port number, so nothing opens onto the Internet.

The path of an instruction, from the browser to rTorrent The browser reaches Apache over HTTPS, and Apache hosts ruTorrent. ruTorrent talks to rTorrent through a socket file. rTorrent writes to a folder. The Internet reaches rTorrent on port 50000, and bob reads the folder over SFTP. Browser HTTPS, password Apache + PHP ruTorrent page SCGI socket (file) rTorrent rtorrent account writes the files /srv/seedbox Internet port 50000 bob SFTP
Text version: your browser reaches Apache over HTTPS with a password. Apache serves the ruTorrent page, which talks to rTorrent through a socket file. rTorrent writes to /srv/seedbox. Other machines reach rTorrent on port 50000, and the bob account reads the folder over SFTP.

Read it from top to bottom: only port 50000 and SSH stay open besides the web page, and the socket, drawn in another color, never leaves the machine. Before we build, let's look at what a commercial seedbox offers, so you know what we're rebuilding.

What a commercial seedbox offers

Ready-made seedboxes bundle almost the same features from one plan to the next. The table links each one to what you build here, and says what waits for another day.

FeatureHow to get it yourselfIn this article?
Web interfaceruTorrent behind ApacheYes, steps 4 and 5
HTTPS and passwordcertbot and htpasswdYes, step 5
File access (FTP, SFTP)OpenSSH's SFTP, locked in a folderYes, step 7
SSH accessThe one your server already hasAlready done
Automatic downloads (RSS)rss plugin of ruTorrentYes, step 6
Speed limit by time of dayscheduler pluginYes, step 6
Automatic sortingautotools pluginYes, step 6
Disk quotarTorrent's free-space thresholdYes, step 2
Backuprsync of the sessionYes, step 8
Stream your filesA media server, like JellyfinLater
One folder and one quota per personOne rTorrent instance per person, or file system quotasLater
NotificationsA script that sends a message when a download endsLater
VPNWireGuardAlready covered
API for other programsruTorrent's /RPC2 endpointLater

The core of the setup comes down to eight steps. The first gives rTorrent an account of its own.

1A dedicated account and its folders

rTorrent must run neither under your alice account nor under root: if someone breaks in, they'd inherit all of that account's rights. So we create a system user, an account with no password and no login, reserved for one program (accounts and rights are covered in Users, sudo and file permissions). It gets three folders: the finished files, its state (the session), and a watched folder where you drop .torrent files.

On the server
sudo adduser --system --group --home /var/lib/rtorrent rtorrent

Let's create the folders with their rights.

On the server
sudo install -d -o rtorrent -g rtorrent -m 0770 /var/lib/rtorrent/session /var/lib/rtorrent/watch
sudo install -d -o root -g root -m 0755 /srv/seedbox
sudo install -d -o rtorrent -g rtorrent -m 2770 /srv/seedbox/download

Let's check the rights of the finished-files folder.

On the server
ls -ld /srv/seedbox/download
Expected output
drwxrws--- 2 rtorrent rtorrent 4096 Nov  5 07:29 /srv/seedbox/download

Your date will differ. The s in rws keeps the rtorrent group on everything created there, and nobody else gets in. The /srv/seedbox folder belongs to root on purpose: step 7 turns it into a cage, and SSH insists on that owner. The folders are ready, so now we tell rTorrent to use them.

2Install and configure rTorrent

rTorrent is in Debian's packages, so installing it takes one command.

On the server
sudo apt install -y rtorrent

rTorrent reads its settings from a file where each line is an instruction of the form name = value. Here's ours, which we store in /etc/rtorrent.rc.

On the server
sudo tee /etc/rtorrent.rc > /dev/null <<'EOF'
# Dossiers : fichiers termines, etat de rTorrent, dossier surveille
directory.default.set = /srv/seedbox/download
session.path.set = /var/lib/rtorrent/session
schedule2 = watch_directory,5,5,"load.start=/var/lib/rtorrent/watch/*.torrent"

# Port d'ecoute pour les autres machines (a ouvrir dans ufw)
network.port_range.set = 50000-50000
network.port_random.set = no
dht.mode.set = disable
protocol.pex.set = no

# Canal SCGI : un fichier-socket, jamais un port reseau
network.scgi.open_local = /run/rtorrent/rpc.sock

# Ferme les telechargements quand il reste moins de 5 Go
schedule2 = low_diskspace,5,60,close_low_diskspace=5G

# Mode service : pas d'ecran, pas de terminal
system.daemon.set = true
EOF

The lines that matter:

  • directory.default.set and session.path.set: where the finished files and rTorrent's state go.
  • watch_directory: every 5 seconds, rTorrent starts any .torrent dropped in the watched folder.
  • network.port_range.set: a single listening port, 50000, fixed so you can open it in the firewall. We also turn off DHT and PEX, two ways to find other machines without the .torrent announcement.
  • network.scgi.open_local: creates the socket. The open_port variant would open a network port, and we don't want one.
  • close_low_diskspace: our simple quota. Under 5 GB free, rTorrent closes the downloads instead of filling the disk.

The file is ready. Now we start rTorrent in a way that survives a reboot.

3Run rTorrent as a service

A systemd service is a program that the system starts at boot and restarts if it crashes, like Apache. Its description file says who runs it and how. Here's the one for rTorrent.

On the server
sudo tee /etc/systemd/system/rtorrent.service > /dev/null <<'EOF'
[Unit]
Description=rTorrent
After=network-online.target
Wants=network-online.target

[Service]
User=rtorrent
Group=rtorrent
UMask=0007
RuntimeDirectory=rtorrent
RuntimeDirectoryMode=0750
ExecStart=/usr/bin/rtorrent -n -o import=/etc/rtorrent.rc
Restart=on-failure
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target
EOF
  • User and Group: the program runs under the rtorrent account.
  • UMask=0007: everything it creates stays closed to other accounts. So the socket will be readable by the rtorrent group only.
  • RuntimeDirectory: systemd recreates /run/rtorrent, with the right owner, at every start.
  • ExecStart: starts rTorrent with no screen, using our settings file.
  • Restart and LimitNOFILE: restarts after a crash, and allows many open files at once.

Let's turn it on: enable makes it start at every boot, and --now starts it right away.

On the server
sudo systemctl daemon-reload
sudo systemctl enable --now rtorrent

Two checks tell you whether everything is in place: the socket exists, and so does the listening port.

On the server
ls -l /run/rtorrent/
ss -ltn 'sport = :50000'
Expected output
total 0
srwxrwx--- 1 rtorrent rtorrent 0 Nov  5 07:29 rpc.sock
State  Recv-Q Send-Q Local Address:Port  Peer Address:Port
LISTEN 0      4096               *:50000            *:*

The s at the start of the first line marks a socket, and your date will differ. Port 50000 must now be open in the firewall, so other machines can reach rTorrent (see A firewall with ufw).

On the server
sudo ufw allow 50000/tcp
Expected output
Rules updated
Rules updated (v6)

rTorrent is working. The web page is still missing, and it needs permission to open the socket.

4Install ruTorrent and plug it in

ruTorrent isn't in Debian 13's packages, so we take the version published by its authors and put it in /var/www/rutorrent. Apache will serve it, with PHP and its extensions. These extensions read XML and file names, and make web requests for the plugins.

On the server
sudo apt install -y apache2 apache2-utils libapache2-mod-php php-curl php-xml php-mbstring

Next, download the archive of version 5.3.21, then unpack it into its folder.

On the server
cd /tmp
curl -fsSLO https://github.com/Novik/ruTorrent/archive/refs/tags/v5.3.21.tar.gz
sudo mkdir /var/www/rutorrent
sudo tar xzf v5.3.21.tar.gz --strip-components=1 -C /var/www/rutorrent
sudo chown -R www-data:www-data /var/www/rutorrent/share

The www-data account is Apache's. It must be able to write to share, where ruTorrent keeps its settings, and nowhere else. Now tell ruTorrent where to find rTorrent. The sed command replaces lines in its settings file:

  • $scgi_port = 0: no network port.
  • $scgi_host: the address of the socket.
  • $topDirectory: the limit of what ruTorrent may browse, here /srv/seedbox/.
On the server
sudo sed -i 's|^\(\s*\)$scgi_port = .*|\1$scgi_port = 0;|; s|^\(\s*\)$scgi_host = .*|\1$scgi_host = "unix:///run/rtorrent/rpc.sock";|; s|^\(\s*\)$topDirectory = .*|\1$topDirectory = "/srv/seedbox/";|' /var/www/rutorrent/conf/config.php
grep -E '^\s*\$(scgi_port|scgi_host|topDirectory)' /var/www/rutorrent/conf/config.php
Expected output
	$topDirectory = "/srv/seedbox/";
	$scgi_port = 0;
	$scgi_host = "unix:///run/rtorrent/rpc.sock";

One thing is missing: the right to open the socket, which only the rtorrent group has. Let's add www-data to that group, then check with Apache's own account.

On the server
sudo usermod -aG rtorrent www-data
sudo -u www-data php -r 'echo is_writable("/run/rtorrent/rpc.sock") ? "oui" : "non", PHP_EOL;'
Expected output
oui

Apache only reads its groups when it starts, and we restart it in the next step. The page exists, but nothing protects it yet, and that's the next step's job.

5Password and HTTPS with Apache

Without protection, anyone who found the address could run your downloads. So Apache will ask for a password before serving any page: that's Basic authentication. The htpasswd command keeps the password file, and its -c option creates it. It asks for the password twice.

On the server
sudo htpasswd -c /etc/apache2/rutorrent.htpasswd alice
sudo chgrp www-data /etc/apache2/rutorrent.htpasswd
sudo chmod 640 /etc/apache2/rutorrent.htpasswd
Expected output
Adding password for user alice

Next, write the site. Unlike in Reverse proxy, Apache forwards nothing: it serves the page itself, and PHP talks to rTorrent. The domain name rutorrent.exemple.fr must point to your server (see Domain name and DNS).

On the server
sudo tee /etc/apache2/sites-available/rutorrent.exemple.fr.conf > /dev/null <<'EOF'
<VirtualHost *:80>
    ServerName rutorrent.exemple.fr
    DocumentRoot /var/www/rutorrent
    ErrorLog ${APACHE_LOG_DIR}/rutorrent-error.log

    <Directory /var/www/rutorrent>
        Options -Indexes
        AllowOverride None
        AuthType Basic
        AuthName "ruTorrent"
        AuthUserFile /etc/apache2/rutorrent.htpasswd
        Require valid-user
    </Directory>

    # Donnees internes de ruTorrent : jamais servies
    <Directory /var/www/rutorrent/share>
        Require all denied
    </Directory>
</VirtualHost>
EOF
  • AuthType and Require valid-user: any request without a valid password gets refused.
  • Options -Indexes: no file list when someone visits a folder.
  • The share block: ruTorrent's internal data is never served, even to you.

Let's enable the site, test the syntax, then restart Apache so it picks up the group we added earlier.

On the server
sudo a2ensite rutorrent.exemple.fr.conf
sudo apache2ctl configtest
sudo systemctl restart apache2
Expected output
Enabling site rutorrent.exemple.fr.
Syntax OK

The a2ensite command also reminds you to reload Apache, which our restart already does. From your computer, let's check that the door is closed: without a password, the answer must be a refusal.

On your computer
curl -sI http://rutorrent.exemple.fr/ | head -n 1
Expected output
HTTP/1.1 401 Unauthorized

A Basic password travels in the clear over an HTTP connection. So let's encrypt the connection before you type it, with the command from HTTPS with Let's Encrypt.

On the server
sudo certbot --apache --redirect -d rutorrent.exemple.fr

Now let's open the page again, this time with the password. The command asks for it, and we expect a success.

On your computer
curl -sI -u alice https://rutorrent.exemple.fr/ | head -n 1
Expected output
HTTP/1.1 200 OK

The setup is complete and protected. Now it needs something to download.

6A first free file, and the plugins

Our test file is Debian's light installation image, about 0.8 GB. To download it, we drop its .torrent in the watched folder, using the rtorrent account so it stays the owner.

On the server
sudo -u rtorrent curl -fsSL -o /var/lib/rtorrent/watch/debian-netinst.torrent https://cdimage.debian.org/debian-cd/current/amd64/bt-cd/debian-13.7.0-amd64-netinst.iso.torrent

After a few seconds, rTorrent has started the download in the finished-files folder.

On the server
ls -lh /srv/seedbox/download
Expected output
total 757M
-rw-rw---- 1 rtorrent rtorrent 756M Nov  5 07:29 debian-13.7.0-amd64-netinst.iso

The numbers depend on progress, date and version. Open https://rutorrent.exemple.fr/ in your browser: after the password, the line for this image appears in the list, with its progress.

ruTorrent ships with plugins, small extensions that the page loads by itself. Four of them match features in the table.

  • rss: follows announcement feeds and starts whatever matches your filters.
  • scheduler: limits the speed by time of day, for example less during the day.
  • autotools: sorts or labels finished files, with no work from you.
  • diskspace: shows the free space, on top of the safeguard from step 2.

Let's check that the page really loads them.

On your computer
curl -s -u alice https://rutorrent.exemple.fr/php/getplugins.php | grep -o 'plugins/\(rss\|scheduler\|autotools\|diskspace\)/' | sort -u
Expected output
plugins/autotools/
plugins/diskspace/
plugins/rss/
plugins/scheduler/

The file is there, on the server. Now let's bring it home to your computer.

7Fetch your files over SFTP

SFTP moves files through SSH's encrypted pipe, the one from What is SSH?. It adds no port and no server program: port 22 is enough. We create a bob account and lock it in (a "chroot"): its root folder becomes /srv/seedbox, and it sees nothing else on the server. So it can read and delete the files, without getting a terminal.

On the server
sudo addgroup --system sftponly
sudo adduser --disabled-password --gecos "" --shell /usr/sbin/nologin bob
sudo usermod -aG sftponly,rtorrent bob

The sftponly group names the accounts to lock in, and rtorrent gives access to the files. An SSH rule locks in the first group.

On the server
sudo tee /etc/ssh/sshd_config.d/sftp-seedbox.conf > /dev/null <<'EOF'
# Les membres du groupe sftponly ne font que du SFTP, enfermes dans /srv/seedbox
Match Group sftponly
    ChrootDirectory /srv/seedbox
    ForceCommand internal-sftp
    AllowTcpForwarding no
    X11Forwarding no
EOF
sudo sshd -t

There's no password for bob: he connects with a key, as in Secure SSH: turn off passwords. He makes his key on his computer and sends you the public part. Put it in his file, then reload SSH.

On the server
sudo install -d -m 0700 -o bob -g bob /home/bob/.ssh
sudo install -m 0600 -o bob -g bob /dev/null /home/bob/.ssh/authorized_keys
sudo nano /home/bob/.ssh/authorized_keys
sudo systemctl reload ssh

In nano, paste bob's public key on one line, then save with Ctrl+O and quit with Ctrl+X. Let's try from bob's computer.

On your computer
printf 'pwd\nls\ncd ..\npwd\nbye\n' | sftp -b - bob@203.0.113.10
Expected output
sftp> pwd
Remote working directory: /
sftp> ls
download
sftp> cd ..
sftp> pwd
Remote working directory: /
sftp> bye

bob's root holds only download, and cd .. leads nowhere: the cage holds. To bring the file home, the sftp command takes a path after the address.

On your computer
sftp bob@203.0.113.10:/download/debian-13.7.0-amd64-netinst.iso .

The file lands in the current folder. Everything else is refused: ssh bob@203.0.113.10 answers This service allows sftp connections only. You, alice, keep your full access. There's one thing left to protect: what lets rTorrent pick up where it left off, its session.

8Back up the session

The session keeps the .torrent files and the progress of each one. Without it, rTorrent forgets what it shares and must recheck every file, which takes a long time. Let's stop it for a moment so the copy is consistent, copy with rsync (see Your first backup with rsync), then start it again.

On the server
sudo systemctl stop rtorrent
sudo install -d -m 0750 /var/backups/rtorrent-session
sudo rsync -a /var/lib/rtorrent/session/ /var/backups/rtorrent-session/
sudo systemctl start rtorrent

Add the copy to your usual backup, off the server. To restore, stop rTorrent and copy the folder back the other way. The files themselves are backed up with the same rsync, applied to /srv/seedbox/download.

If it fails

Three situations come up most often.

  • ruTorrent shows Could not reach rTorrent over XMLRPC. Is rTorrent running? The service is stopped, or Apache isn't allowed to open the socket. Check with ls -l /run/rtorrent/ and id www-data: the rtorrent group must appear. If you just added it, run sudo systemctl restart apache2.
  • rTorrent stops with Could not open/bind port for listening: Address already in use. Another rTorrent already holds port 50000, often one started by hand and left open. Find it with ss -ltnp 'sport = :50000', stop it, then restart the service.
  • SFTP cuts off: Connection closed. SSH's log says bad ownership or modes for chroot directory "/srv/seedbox" (see Read your logs with journalctl). The cage folder must belong to root and be writable by nobody else: sudo chown root:root /srv/seedbox.

What's next

Your server now works on its own, night and day, and shows the world only what you chose. There's one more kind of work to give it: thinking. The next article, An AI assistant on your server, installs an assistant that runs on your own server.