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
- The pieces of the setup
- What a commercial seedbox offers
- A dedicated account and its folders
- Install and configure rTorrent
- Run rTorrent as a service
- Install ruTorrent and plug it in
- Password and HTTPS with Apache
- A first free file, and the plugins
- Fetch your files over SFTP
- Back up the session
- If it fails
- What's next
- 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.
/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.
| Feature | How to get it yourself | In this article? |
|---|---|---|
| Web interface | ruTorrent behind Apache | Yes, steps 4 and 5 |
| HTTPS and password | certbot and htpasswd | Yes, step 5 |
| File access (FTP, SFTP) | OpenSSH's SFTP, locked in a folder | Yes, step 7 |
| SSH access | The one your server already has | Already done |
| Automatic downloads (RSS) | rss plugin of ruTorrent | Yes, step 6 |
| Speed limit by time of day | scheduler plugin | Yes, step 6 |
| Automatic sorting | autotools plugin | Yes, step 6 |
| Disk quota | rTorrent's free-space threshold | Yes, step 2 |
| Backup | rsync of the session | Yes, step 8 |
| Stream your files | A media server, like Jellyfin | Later |
| One folder and one quota per person | One rTorrent instance per person, or file system quotas | Later |
| Notifications | A script that sends a message when a download ends | Later |
| VPN | WireGuard | Already covered |
| API for other programs | ruTorrent's /RPC2 endpoint | Later |
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.
sudo adduser --system --group --home /var/lib/rtorrent rtorrentLet's create the folders with their rights.
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/downloadLet's check the rights of the finished-files folder.
ls -ld /srv/seedbox/downloaddrwxrws--- 2 rtorrent rtorrent 4096 Nov 5 07:29 /srv/seedbox/downloadYour 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.
sudo apt install -y rtorrentrTorrent 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.
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
EOFThe lines that matter:
directory.default.setandsession.path.set: where the finished files and rTorrent's state go.watch_directory: every 5 seconds, rTorrent starts any.torrentdropped 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.torrentannouncement.network.scgi.open_local: creates the socket. Theopen_portvariant 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.
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
EOFUserandGroup: the program runs under thertorrentaccount.UMask=0007: everything it creates stays closed to other accounts. So the socket will be readable by thertorrentgroup only.RuntimeDirectory: systemd recreates/run/rtorrent, with the right owner, at every start.ExecStart: starts rTorrent with no screen, using our settings file.RestartandLimitNOFILE: 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.
sudo systemctl daemon-reload
sudo systemctl enable --now rtorrentTwo checks tell you whether everything is in place: the socket exists, and so does the listening port.
ls -l /run/rtorrent/
ss -ltn 'sport = :50000'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).
sudo ufw allow 50000/tcpRules 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.
sudo apt install -y apache2 apache2-utils libapache2-mod-php php-curl php-xml php-mbstringNext, download the archive of version 5.3.21, then unpack it into its folder.
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/shareThe 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/.
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 $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.
sudo usermod -aG rtorrent www-data
sudo -u www-data php -r 'echo is_writable("/run/rtorrent/rpc.sock") ? "oui" : "non", PHP_EOL;'ouiApache 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.
sudo htpasswd -c /etc/apache2/rutorrent.htpasswd alice
sudo chgrp www-data /etc/apache2/rutorrent.htpasswd
sudo chmod 640 /etc/apache2/rutorrent.htpasswdAdding password for user aliceNext, 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).
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>
EOFAuthTypeandRequire valid-user: any request without a valid password gets refused.Options -Indexes: no file list when someone visits a folder.- The
shareblock: 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.
sudo a2ensite rutorrent.exemple.fr.conf
sudo apache2ctl configtest
sudo systemctl restart apache2Enabling site rutorrent.exemple.fr.
Syntax OKThe 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.
curl -sI http://rutorrent.exemple.fr/ | head -n 1HTTP/1.1 401 UnauthorizedA 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.
sudo certbot --apache --redirect -d rutorrent.exemple.frNow let's open the page again, this time with the password. The command asks for it, and we expect a success.
curl -sI -u alice https://rutorrent.exemple.fr/ | head -n 1HTTP/1.1 200 OKThe 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.
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.torrentAfter a few seconds, rTorrent has started the download in the finished-files folder.
ls -lh /srv/seedbox/downloadtotal 757M
-rw-rw---- 1 rtorrent rtorrent 756M Nov 5 07:29 debian-13.7.0-amd64-netinst.isoThe 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.
curl -s -u alice https://rutorrent.exemple.fr/php/getplugins.php | grep -o 'plugins/\(rss\|scheduler\|autotools\|diskspace\)/' | sort -uplugins/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.
sudo addgroup --system sftponly
sudo adduser --disabled-password --gecos "" --shell /usr/sbin/nologin bob
sudo usermod -aG sftponly,rtorrent bobThe sftponly group names the accounts to lock in, and rtorrent gives access to the files. An SSH rule locks in the first group.
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 -tThere'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.
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 sshIn 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.
printf 'pwd\nls\ncd ..\npwd\nbye\n' | sftp -b - bob@203.0.113.10sftp> pwd
Remote working directory: /
sftp> ls
download
sftp> cd ..
sftp> pwd
Remote working directory: /
sftp> byebob'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.
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.
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 rtorrentAdd 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 withls -l /run/rtorrent/andid www-data: thertorrentgroup must appear. If you just added it, runsudo 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 withss -ltnp 'sport = :50000', stop it, then restart the service. - SFTP cuts off:
Connection closed. SSH's log saysbad ownership or modes for chroot directory "/srv/seedbox"(see Read your logs with journalctl). The cage folder must belong torootand 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.