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 slackware.com) 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 http://xmlrpc-c.sf.net. 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*
./configure --disable-wininet-client --disable-libwww-client --disable-abyss-server --disable-cgi-server --disable-abyss-threads
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 http://php.net – 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*
./configure --enable-fastcgi --enable-force-cgi-redirect --enable-discard-path --disable-ipv6 --with-xmlrpc
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 :
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 http://www.lighttpd.net, 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*
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 = (
( "127.0.0.1" =>
"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 :
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 http://libtorrent.rakshasa.no – 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 : http://repository.slacky.eu/slackware-12.2/libraries/libsigc++/2.2.3/libsigc++-2.2.3-i486-1as.tgz
Having downloaded libtorrent and rTorrent, we unpack them and compile as follows :
tar -zxf libtorrent*
tar -zxf rtorrent*
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/libtorrent.so.9.2.0 /usr/lib/libtorrent.so.9
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.
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 http://dtach.sf.net. At the time of writing, the newest version is 0.8.
tar -zxf dtach*.tar.gz
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 http://code.google.com/p/rtgui/, 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
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 http://www.pureftpd.org, 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
./configure --with-largefile --with-puredb
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.
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
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 yourdomain.com -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 yourdomain.com 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! :)
- 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