Remote torrent machine based on Slackware Linux and rTorrent with rtGUI – step by step guide

This guide is to show how to install the BitTorrent client for Linux known as rTorrent, along with its graphical user interface called rtGUI, based on PHP, as well as an FTP server used to access the data downloaded by rTorrent.

The article is meant to be read by users who know a little bit around GNU/Linux (but, having written everything, I come to the conclusion that you don’t really need to know much more than how to setup your network connection, and you mustn’t be afraid of the console, since we’re not going to install the X server). Even though it is destined for the Slackware Linux distribution, it should be „adaptable” for other distributions with a little effort on the user’s side.

1. Hardware requirements.

They’re definitely not too big at all. I’m running the system as described in this article on a Duron 750MHz, equipped with 1.25GB of RAM and a 20GB hard drive. The most important factor when it comes to the hardware is the hard disk, which size has to be proportional to the size of the things we want to download from BitTorrent. RAM is far less important, and the processor will only influence the compilation time, the hashing process and the page generation time.

Slackware itself (according to needs a 486 processor, 64MB RAM, more than 5GB free space for installation (when we’re talking about a full install – I usually only install the groups A, AP, D and selected packets from groups L and N – thanks to that, the system itself doesn’t occupy more than 2GB of space) and a CD or DVD drive to install and run it (though there are other ways – the installer itself supports installing the system from a HTTP server, FTP server, NFS server or a Samba share).

I wasn’t able to find the requirements of Lighttpd or rTorrent, but that’s just a proof for the fact that they are absolutely minimal. I think that the whole machine should run smoothly with a 200MHz processor and 256MB of RAM.

I think it’s obvious that the machine itself needs to be equipped with a network interface card, or some kind of a modem (for xDSL, for example). The configuration of the network interface is, however, far beyond the topics covered by the scope of this guide. There’s a thing you should remember when setting up a machine with a weaker processor, though – the branded cards (Intel, 3com) are usually less of a hog for the CPU compared to, for example, Realtek cards.

Before you proceed any further, I assume that you’ve got the Slackware Linux system properly installed and that your Internet connection is properly configured and working.

2. XML-RPC installation

We’ve got to begin with installation of the XML-RPC library, through which rtGUI gains access to rTorrent. It can be downloaded from the site I’ve tested everything myself using the Super Stable version (1.06.32 at the time of writing), and I haven’t encountered any problems. Having downloaded the package, we unpack it and compile :

tar -zxf xmlrpc-c*
cd xmlrpc-c*
./configure --disable-wininet-client --disable-libwww-client --disable-abyss-server --disable-cgi-server --disable-abyss-threads
make install

This way, we’ve got a properly installed and functional XML-RPC library, let’s head on to the installation of PHP.

3. PHP installation

rtGUI is based on PHP and makes use of the AJAX technology. Therefore, to properly use it, we’ll need a working PHP installation and a proper HTTP server (more on that later).

Let’s head on to the PHP site then – it’s – and download the newest PHP source tarball. At the time of writing, it’s 5.2.8, and works without any problems with used versions of Lighttpd and rtGUI.

Having downloaded the package, we unpack it and compile :

tar -jxf php*
cd php*
./configure --enable-fastcgi --enable-force-cgi-redirect --enable-discard-path --disable-ipv6 --with-xmlrpc
make install

This way, we’ve got the PHP FastCGI binary installed in our system, its default location is /usr/local/bin and its name is php-cgi. If you want to check if everything’s ok, you can just issue the program with the -v switch. The result should be similar to this one :

root@sandbox:~# php-cgi -v
PHP 5.2.8 (cgi-fcgi) (built: Jan 10 2009 12:36:56)
Copyright (c) 1997-2008 The PHP Group
Zend Engine v2.2.0, Copyright (c) 1998-2008 Zend Technologies

If you see something like that, it’s a sign that PHP is working (more or less) properly. What we need to do next is to copy its sample configuration to the /usr/local/lib/ directory :

cp php.ini-dist /usr/local/lib/php.ini

and, eventually, make our own changes into it (I’m not going to get into details, since I don’t even know the configuration myself). Now we’re going to take care of the installation of the HTTP server and integrating it with our PHP installation. But firstly, we’re going to create a dedicated user with whose privileges all the „torrenting” tasks will be run.

4. Creating a dedicated user for all the tasks related to rTorrent

It would be, of course, the easiest to just run all the services with root privileges. Unfortunately, doing so is connected with leaving a really big hole in the machine’s security, since all the commands issued by these services will have full filesystem access (therefore, if somebody – hipothetically – breaks into the system through a service run with root privileges, can read/write just everything). To prevent this, we’ll create a user with read/write privileges to just few directories and an accompanying group for him. I called both the user and the group torrent, but you’re free to change it to anything you wish. The whole procedure consists of just two commands :

groupadd torrent
useradd -g torrent -d /home/torrent -s /bin/bash -m torrent

The first one will create a group called torrent, and the second will add the same-named user into it, with his home directory located in /home/torrent and a /bin/bash shell (unfortunately, having a shell for this user is needed, since rTorrent needs it – if we use, for example, /bin/false as a shell, dtach will refuse to run, and therefore – so will rTorrent). The home directory will be created if it doesn’t exist (-m).

5. Installing Lighttpd and enabling PHP support

We’ll use Lighttpd as our HTTP server of choice, since it’s got an SCGI module (needed to access XMLRPC sockets) built right in, and also because Apache is really cool, but I feel that using it in this situation will be just too much – I mean, there’s no real occassion to use all of its features.

The homepage of the Lighttpd server is, and that’s the place where we’re going to get it from. At the time of writing, the newest version is 1.4.20. Having downloaded the source tarball, we unpack it and compile :

tar -jxf lighttpd*
cd lighttpd*
./configure --disable-ipv6
make install

Having done all this, we’ve got Lighttpd installed, all we’ve got to do more is to configure it. In order to do this, we copy the example configuration to the /etc directory :

cp doc/lighttpd.conf /etc/lighttpd.conf

and we open it in our favorite text editor (in my case it’s mcedit). We need to change a few things :

  • remove the hash character (#) by mod_fcgi and mod_auth on the module list,
  • add mod_scgi to the module list,
  • remove all the hash characters by the FastCGI configuration section (all the paths are set to default ones, so if you haven’t changed them, there’s no need to change them now, they’ll just work),
  • remove the hashes by server.username and server.groupname directives and change their values to the group and the user created in the previous chapter,
  • we add SCGI support by adding directives below to the configuration file :

scgi.server = (
"/RPC2" =>
( "" =>
"socket" => "/home/torrent/rpc.socket", # change it to the "rpc.socket"
"check-local" => "disable",
"disable-time" => 0,

Of course, you’re free to change the default location of the files exposed by the server or the location of server logs and PIDs. For the needs of the guide, though, I’ll just assume that the default locations are used – that is, /srv/www/htdocs for the server documents, /var/log/lighttpd for the server logs and /var/run/lighttpd for the PIDs. We need to create the second and third directory, as well as change their ownership :

mkdir /var/log/lighttpd
mkdir /var/run/lighttpd
chown torrent:torrent /var/log/lighttpd
chown torrent:torrent /var/run/lighttpd

Now we’ll try to run our Lighttpd :

lighttpd -f /etc/lighttpd.conf

If there were no messages printed to the console, it means that the server has properly read, understood and applied the configuration located in the file /etc/lighttpd.conf, though that doesn’t have to mean that it’s already running properly. We’ll test its PHP integration by creating a simple PHP script in its document root directory and calling it index.php :

If you enter http://localhost in your browser, you should see a site with informations about the PHP installation used by the server. It’s a clear sign that the server itself and its integration with PHP works properly. If it doesn’t – have a look at the lighttpd errorlog, since it’s very common to find the cause of the problem right there.

If lighttpd works properly, let’s shut it down for now (killall lighttpd). Now, let’s move on to the practically most important thing – libtorrent and rTorrent.

6. Installing libtorrent and rTorrent

libtorrent is a library containing an implementation of the BitTorrent network, written in C++. rTorrent uses it in order to communicate with this network. The homepage of the library, as well as the program, is – that’s where we get both of the things from. I’ve used the stable version in my setup – for the time of writing, the newest stable were 0.12.2 for libtorrent and 0.8.2 for rTorrent.

Attention! During the compilation, you may encounter the configure program moaning about some needed dependiences – in my case it was libsigc++ – in order to solve this problem quickly, look for it on the Slackware CD/DVD, and then have a google search for a tgz package. If you’re missing the libsigc++, a tgz file (Slackware’s package, you install it by typing installpkg) lies right here :

Having downloaded libtorrent and rTorrent, we unpack them and compile as follows :

tar -zxf libtorrent*
cd libtorrent*
./configure --disable-ipv6
make install

tar -zxf rtorrent*
cd rtorrent*
./configure --with-xmlrpc-c
make install

rTorrent will probably groan about not being able to find libtorrent (which has been installed to /usr/local/lib) – in that case, we just create a symbolic link :

ln -s /usr/local/lib/ /usr/lib/

Now we just type rtorrent and see if it works properly. Its interface should show – let’s shut it down by now (CTRL-Q) and attempt to configure it.

Configuring rTorrent means nothing more than editing the .rtorrent.rc (notice the dot at the beginning) file, which should reside in the root of the home directory of the user currently running the process (that is, in our case, /home/torrent/). An example configuration file is located here and should be pretty self-explanatory. It seems obvious for me that it’s necessary (or at least good) to enable encryption, DHT, UDP trackers and PEX. Another thing about the directories – I always set the default download location to just /home/torrent, session directory to /home/torrent/session, and – important! the „new torrents” directory to /home/torrent/newtorrents (this is essential for rtGUI’s Add Torrent feature to work). Another thing that should be remembered about is enabling XMLRPC support by adding :

scgi_local = /home/torrent/rpc.socket # the path given here must be the same as the one in lighttpd configuration!

to the .rtorrent.rc file. It’s also useful to enable UTF-8 support :

encoding_list = UTF-8

in order to avoid problems with non-Latin-standard characters. Having done all this, we’ve got rTorrent configured for the torrent user. Let’s run it as this user, then :

su - torrent -c "rtorrent"

If you can see rTorrents interface and a proud message saying XMLRPC initialized with 444 functions, everything’s alright and the program has been configured correctly. The issue of port forwarding and being connectable will be skipped at this point.

7. dtach

Since rTorrent is an ncurses program, it always displays its console interface when launched. There is (sadly) no commandline switch which would make it get daemonized. Therefore, it is needed to use an external program for doing that. I, myself, have been trying to achieve that with the well-known program screen, but, unfortunately, I failed miserably. On the rTorrent’s site, though, I’ve encountered a mention of a similar program called dtach. It worked flawlessly, and we’re going to use it now.

For starters, we just download the source tarball. Its homepage is At the time of writing, the newest version is 0.8.

tar -zxf dtach*.tar.gz
cd dtach*
mv dtach /usr/bin/

This way, we’ve got the dtach problem installed, thanks to which we can „hide” the programs and come back to them later. Let’s try to execute rTorrent as the „torrent” user and „hide” it as well, then :

su - torrent -c "dtach -n torrent rtorrent"

This command will cause the command dtach -n torrent rtorrent (which will create a new screen socket called torrent, execute the rtorrent command in this socket and automatically detach from this socket) to be executed as the user torrent. Therefore, we don’t know if rTorrent is working, but we can check that quickly by issuing the following command :

ps -A | grep rtorrent

If we see the process’ PID and its name by it, everything’s alright. Leave rTorrent running for now on.

8. Installing rtGUI

Installing rtGUI is by far the easiest process and consists of nothing more than unpacking the package and editing the config file. The homepage of this project is, and that’s where we’re going to get it from. At the time of writing, the newest version is 0.2.6.

cd /srv/www/htdocs # delete index.php, too
tar -zxf rtgui-0.2.6.tgz
cd rtgui
cp config.php.example config.php

Nextly, we open the newly copied config.php in our favorite text editor and change the following things in it :

  • the watchdir variable should point to the „new torrents” directory as set in the rTorrent config (include a slash at the end!)
  • the downloaddir variable should point to the path where downloaded data goes
  • the rtguiurl variable should point to the address of rtGUI as seen from the Internet – if you’ve got a dynamic IP, it would be best for you to type in your domain name here, and include the path to rtGUI, of course

You can also have some fun with tracker coloring and similar stuff (details included in the config.php itself), but that’s by no means necessary.

At this point, you should have a working rtGUI. So, we point our browser to http://localhost/rtgui/ (or access it from a remote machine, with a graphical browser) and please ourselves with the how pretty GUI for rTorrent. It’s also good to test the torrent upload feature.

If something’s not right – have a look at „Troubleshooting” (at the end).

9. PureFTPd installation

Having the already downloaded files on the disk, we would like to have some kind of access to them. rtGUI doesn’t give us such a possibility, and that’s why we have to set up an FTP server on our machine. We’ll use PureFTPd to achieve this. Its homepage is, and that’s where we get the source tarball from. At the time of writing, the newest version is 1.0.21.

tar -jxf pure-ftpd*.tar.bz2
cd pure-ftpd*
./configure --with-largefile --with-puredb
make install

We’ve got the FTP server installed. Its configuration is nothing more than just running the executable with proper parameters, but firstly we should set up the users which will be able to access it. We’ll use PureFTPd’s „virtual users”, who physically don’t exist in the system, but the server grants them access.

Firstly, we need to create the user and the group, under whose privileges all the virtual users will fall under.

groupadd ftpgroup
useradd -g ftpgroup -d /dev/null -s /bin/false ftpuser

Now we can add virtual users. May our be called torrent

pure-pw useradd torrent -u ftpuser -d /home/torrent

This command will create the torrent user, recognized by the system as ftpuser, being able to access only his home directory – /home/torrent. Having issued the command, we’ll be asked for the password twice. The virtual users are contained in a file similar to /etc/passwd – namely /etc/pureftpd.passwd. However, in order for PureFTPd to use the virtual user base, we need to commit the changes and create a puredb database, which PureFTPd is able to read. We achieve that by issuing

pure-pw mkdb

This command has to be issued every time the userbase is modified in any way – otherwise PureFTPd won’t see the changes (it doesn’t even read the pureftpd.passwd file). We can now start up the server by issuing the following command :

pure-ftpd -4 -A -B -c 5 -E -p 59900:60000 -P -l puredb:/etc/pureftpd.pdb -u 1000

It will cause PureFTPd to be run and (in parameter order) :

  • listen only on IPv4 addresses
  • lock every user to its home directory (eg. so that it cannot access any directories lower in the directory tree than its home)
  • cause it to go into daemon mode
  • allow only 5 simultanous connections
  • deny any anonymous logins
  • make it use ports from the range 59900-60000 for passive mode transfers
  • make it report the IP associated to the domain to clients using passive mode (the IP is updated each time a user logs in, so it’s a good choice for those of you with dynamic IPs)
  • read the virtual users database from /etc/pureftpd.pdb
  • deny any logins as users whose UIDs are lower than 1000 (root, system services, etc.)

10. Securing rtGUI

Of course, we don’t want just random people fooling around our rTorrent. That’s why we’ll restrict the access to the rtGUI catalogue by using basic HTTP authentication – any user attempting to access the rtgui catalogue on the server will be prompted by the browser to enter a username and a password. To achieve this, we add the following lines to our /etc/lighttpd.conf :

auth.backend = "plain"
auth.backend.plain.userfile = "/etc/lighttpdpasswd"
auth.require = ( "/rtgui/" =>
"method" => "basic",
"realm" => "rTorrent",
"require" => "user=torrent" # change according to the username you want to use for authenticating

We also create the file /etc/lighttpdpasswd, in which we type in the username and the password, separated by a colon – for example torrent:verysecretpassword. Of course, we secure the file itself :

chmod 400 /etc/lighttpdpasswd
chown torrent:torrent /etc/lighttpdpasswd

Thanks to these commands, nobody except the user torrent (and, of course, root) will be able to read this file.

11. Startup scripts

At this point, you should have everything configured in a way that it works. It’s worthy checking it all once again, issuing – in such order! – rtorrent, lighttpd and pureftpd. rTorrent must be issued before Lighttpd, since it creates a XMLRPC socket for itself. Lighttpd is configured to bind into that socket, and if it doesn’t find it, it will just start going crazy.

We would also like all the daemons to be run at system startup. In order to achieve that, I’ve written a couple of very simple scripts doing just that. Please modify them according to your needs, copy them to /etc/rc.d/ and give them proper permissions (chmod +x filename)


Execution of these scripts also needs to be added to rc.M and rc.6 according to their pattern. In both situations, we don’t add them at the very end, but rather in the middle, along with other services. They need to be shutdown in the opposite direction than the one they were run in. So, that’s what you’d need to add :

to rc.M :

# Start rTorrent
if [ -x /etc/rc.d/rc.rtorrent ]; then
. /etc/rc.d/rc.rtorrent start

# Start Lighttpd
if [ -x /etc/rc.d/rc.lighttpd ]; then
. /etc/rc.d/rc.lighttpd start

# Start Pure-FTPd
if [ -x /etc/rc.d/rc.pureftpd ]; then
. /etc/rc.d/rc.pureftpd start

to rc.6 :

# Stop Pure-FTPd
if [ -x /etc/rc.d/rc.pureftpd ]; then
. /etc/rc.d/rc.pureftpd stop

# Stop Lighttpd
if [ -x /etc/rc.d/rc.lighttpd ]; then
. /etc/rc.d/rc.lighttpd stop

# Stop rTorrent
if [ -x /etc/rc.d/rc.rtorrent ]; then
. /etc/rc.d/rc.rtorrent stop

12. The End

If you’ve passed all the steps from the beginning to the end, then upon rebooting the machine, you should have a fully functional remote torrent machine all running. Congratulations! :)

13. Troubleshooting

  • rtGUI spits out Cannot connect to rtorrent :(

This probably means that Lighttpd isn’t able to bind to the rTorrent’s XMLRPC socket – the most common cause of that problem is that Lighttpd was run BEFORE rTorrent, while rTorrent NEEDS TO BE RUN BEFORE Lighttpd. If that doesn’t help – check out the Lighttpd’s errorlog, located at /var/log/lighttpd by default.

14. Special Thanks

  • Paweł Dymacz for supporting me all the time
  • Bartłomiej Piekarski for donating the hardware

Informacje o Daniel

freezingly cold soul
Ten wpis został opublikowany w kategorii komputer. Dodaj zakładkę do bezpośredniego odnośnika.

Jedna odpowiedź na „Remote torrent machine based on Slackware Linux and rTorrent with rtGUI – step by step guide

  1. mstrswrd06 pisze:

    Great walkthrough, though you’re missing something.

    For the PHP install, the tag –enable-mbstring should be added, otherwise the torrent into box will be blank.


Wprowadź swoje dane lub kliknij jedną z tych ikon, aby się zalogować:


Komentujesz korzystając z konta Wyloguj /  Zmień )

Zdjęcie na Google+

Komentujesz korzystając z konta Google+. Wyloguj /  Zmień )

Zdjęcie z Twittera

Komentujesz korzystając z konta Twitter. Wyloguj /  Zmień )

Zdjęcie na Facebooku

Komentujesz korzystając z konta Facebook. Wyloguj /  Zmień )


Connecting to %s