Disclaimer
This guide is based on my experience with another guide. It's something of a work in progress and certainly isn't foolproof. However, nothing should go disastrously wrong if you at least follow the guide correctly. If something doesn't work for you, post here and I will try to help (but no guarantees that I can offer any). Note also: I'm running Mac OS X 10.6, so if you're running Lion, Leopard or Tiger then you may need to tweak parts of this guide for it to work.
To install rTorrent, we'll be using MacPorts. This requires the developer tools found on your Mac OS X installation disc.
1. Installing the Developer Tools
If you've already installed the Developer Tools, you can skip ahead to section 2
First things first: insert your Mac OS X installation disc into your Mac. Open up the disc in Finder, open the Optional Installs folder and open Xcode.mpkg, like so:
Continue through the installer until you get to the screen that lets you choose what you want to install. Make sure that System Tools and UNIX Dev Support are ticked:
Click Continue and carry on with the installation process. After a (possibly long) while, the Developer Tools should be successfully installed.
2. Installing MacPorts
This is pretty simple, really. Download MacPorts by getting the latest version for your system from here: https://distfiles.macports.org/MacPorts/
Open the .dmg and install MacPorts. There are no options to deal with so no screenshots here.
3. Installing rTorrent
Open up Terminal (if you've never used it before, you can find it in the Utilities folder in Applications). To make sure MacPorts is working, issue (that means, type into Terminal and press enter) the following command (throughout this guide, you can copy and paste any commands into Terminal):
port
If MacPorts was installed properly, you should see something like:
MacPorts 2.0.3
Entering interactive mode... ("help" for help, "quit" to quit)
[/your/current/working/directory] >
To leave the interactive mode, issue the command:
quit
We can now install rTorrent. Issue the following command:
sudo port install rtorrent-devel +xmlrpc
It will ask for your password. Type it in (note that it won't show up as you type it, not even in asterisks or dots; you can still press backspace to delete mistakes though) and press enter. You can now safely go do something else while MacPorts works on downloading and installing rTorrent and all its dependencies. Once it's finished, you'll have a working copy of rTorrent! Hurray! You can even start using it right now by issuing the command:
rtorrent
To quit rtorrent, use Ctrl q (i.e. hold down Ctrl and press q). There's a nicer way to use rTorrent via a program called screen. Issue the following command:
screen rtorrent
It may not look any different to when you issued just 'rtorrent' by itself but here's the clever part: press Ctrl a then d. You should be returned to the command prompt but with the following line above the prompt:
[detached]
screen is a program that effectively lets you create virtual terminals. This is useful because you can now quit Terminal without stopping rTorrent; it will carry on running in the virtual terminal you created, independently of the Terminal app. You can reattach the screen we've just made by issuing:
screen -r
This will return you to the screen where rTorrent is running. If you quit rTorrent (Ctrl q), the screen containing rTorrent will also be closed, and you'll have to issue 'screen rtorrent' again to start running it again. At this point, you have a fully functioning text-based BitTorrent client. There are many guides out there describing how to use and configure rTorrent and you can now start making use of them. However, if you're looking for a nice fancy GUI, read on...
4. Installing a web interface - pre-installation tweaks
There are various web interfaces that can control rTorrent through a protocol known as XML-RPC. To function, they need web server software. Luckily, Mac OS X comes with Apache, one of the most widely used web server software in the world. However, there is a fair amount of tweaking that needs to be done first (regardless of which interface you wish to use).
4.1 Apache: enabling PHP, installing mod_scgi and other tweaks
Mac OS X's preinstalled copy of Apache comes with the PHP extension but it's disabled by default. To enable it, we need to edit a certain text file. At this point, I'm going to assume you have a good text editor like TextMate (paid) or TextWrangler (free). TextEdit has to be constantly told to save files as plain text, and doesn't have any colour schemes for displaying code, so I don't recommend using it. The file we'll be editing is:
/private/etc/apache2/httpd.conf
The 'private' folder (found at the top level of the drive that Mac OS X is installed to; probably 'Macintosh HD') is, as the name suggests, hidden from view in the Finder. However, TextMate and TextWrangler both allow you to see hidden files in their 'Open' dialog box. So open the file with one of them and scroll down to line 115. You should see:
#LoadModule php5_module libexec/apache2/libphp5.so
The '#' at the beginning of the line means the whole line is treated as a comment; Apache will ignore it and so won't load the php module that we need to run a web interface. To fix this, simply delete the '#' so that the line becomes:
LoadModule php5_module libexec/apache2/libphp5.so
Save the file (you'll be prompted for your password) but don't close it, as we'll be editing it again soon. We now need to install mod_scgi, an extension that isn't included with Mac OS X. You can do so by issuing the following commands in Terminal in order:
curl -O http://python.ca/scgi/releases/scgi-1.14.tar.gz
tar xf scgi-1.14.tar.gz
cd scgi-1.14/apache2
sudo apxs -i -c mod_scgi.c
This will install mod_scgi (after which you can delete the files that the above commands just downloaded) but, before Apache can start using it, we need to make one last tweak.
Issue the following commands in order:
cd /usr/sbin
sudo mv ./httpd ./httpd.fat
file ./httpd.fat
You should see that the Apache binary is compiled with support for several architectures. If for example you're running Snow Leopard on a (64-bit) Intel processor, this will probably be displayed as:
./httpd.fat: Mach-O universal binary with 3 architectures
./httpd.fat (for architecture x86_64): Mach-O 64-bit executable x86_64
./httpd.fat (for architecture i386): Mach-O executable i386
./httpd.fat (for architecture ppc7400): Mach-O executable ppc
We need to strip the unneeded parts so that Apache can load the scgi module. Which part you need depends on which architecture you're on. If you're on a 64-bit capable processor (Intel Core 2 Duo, i5, i7, etc.), you'll want x86_64. If you're on the older 32-bit only capable ones (Intel Core Duo, Core Solo, etc.), you'll want i386. And if you're on PowerPC, you'll want ppc7400. Since my MacBook uses an Intel Core 2 Duo, I issue the following commands in order:
sudo lipo ./httpd.fat -thin x86_64 -output ./httpd.x86_64
sudo ln -s ./httpd.x86_64 ./httpd
file ./httpd.x86_64
If you want to keep i386, replace every instance of 'x86_64' in the above with 'i386', and similarly for ppc. You should be met with something like:
./httpd.x86_64: Mach-O 64-bit executable x86_64
showing the architecture that you kept.
We can now tell Apache to load the module by editing the file /private/etc/apache2/httpd.conf that we edited previously, so open it up again in TextMate/Wrangler. Scroll down to the bottom of the 'LoadModule' lines (around line 115) and add this line:
LoadModule scgi_module libexec/apache2/mod_scgi.so
Then, add this line at the bottom of the file:
SCGIMount /RPC2 localhost:5000
This is also a good chance to create a session directory for rTorrent, so issue the following commands in Terminal:
cd
mkdir .session
Then edit line 26 of .rtorrent.rc to tell rTorrent to use this directory ( /Users/username/.session ) as a session directory. In my case, line 26 would read:
session = /Users/Ali/.session
Don't forget to remove the # at the beginning of the line.
Save the file and quit TextMate/Wrangler. We're now almost ready to install a web interface. The only thing that remains is to make a certain configuration file for rTorrent.
rTorrent uses a configuration file in your home folder called .rtorrent.rc but there won't be such a file in your home folder right now. If rTorrent is still running, quit it, as it won't use the configuration file until it's been restarted.
You can download an example configuration file from here. Open it up with TextMate/Wrangler and add the following line to the bottom of the file:
scgi_port = localhost:5000
Save the file, then move it to your home folder. Rename it using the Terminal by issuing the following command:
mv rtorrent.rc.txt .rtorrent.rc
We can now install a web interface! Already?!
5.1 Installing ruTorrent
Before doing anything, make sure that rTorrent is running. If you haven't quit it yet, you can reattach the screen for it by issuing the command:
screen -r
Otherwise you can start it again by issuing the command:
screen rtorrent
Remember that you can detach from this screen by pressing Ctrl a then d.
Now, we need to download ruTorrent to the Sites folder in your home folder and modify its permissions. You can do all this by issuing the following commands in order:
cd ~/Sites
svn co http://rutorrent.googlecode.com/svn/trunk/rutorrent
chmod a+rx rutorrent
To start using ruTorrent, we need to start Apache. This is done most easily by opening up System Preferences and enabling 'Web Sharing' in the Sharing pane:
Finally, there's one last thing to install via MacPorts. Issue the following command in Terminal:
sudo port install proctools
When that's installed, you can run ruTorrent by pointing your web browser to the following address (depending on your username on Mac OS X):
http://localhost/~username/rutorrent/
In my case, this is:
http://localhost/~Ali/rutorrent/
You should now be greeted with a working copy of ruTorrent:
Hurray! You might notice a button with an icon of a star in my screenshot that you won't have at this point. This button is for a plugin that allows ruTorrent to create torrent files. If you don't want this functionality, you may stop reading now and go off and use ruTorrent like a giddy schoolgirl. Otherwise, keep reading.
5.2 Installing the create plugin for ruTorrent
To download the create plugin, issue the following commands in Terminal:
cd ~/Sites/rutorrent/plugins
svn co http://rutorrent.googlecode.com/svn/trunk/plugins/create
The create plugin itself can create torrent files but I prefer to just use it as a frontend for another little program called mktorrent, which works a bit better. You can install it using MacPorts with the following command:
sudo port install mktorrent
Now go to the ruTorrent folder (in your home folder's Sites folder). Open up the plugins folder, then the create folder. In there is a file called conf.php which we need to edit, so open it up with TextMate/Wrangler. Edit the first part of line 6 so that it reads:
$useExternal = 'mktorrent';
Then edit the first part of line 12 so that it reads:
$pathToCreatetorrent = '/opt/local/bin/mktorrent';
Now save the file and close it. If you open up ruTorrent now, you'll be able to see the star icon button for the create plugin. If you click it, you'll see a box that allows you to specify the path of the folder/file you want to create a torrent out of (plus other options). Specifying the full path of something can be a bit of a pain though, so let's install the _getdir plugin.
5.3 Installing the _getdir plugin for ruTorrent
To download the _getdir plugin, issue the following commands in Terminal:
cd ~/Sites/rutorrent/plugins
svn co http://rutorrent.googlecode.com/svn/trunk/plugins/_getdir
This plugin doesn't require any configuring but you might have to modify the permissions of rTorrent's download directory. I've configured rTorrent to download stuff to the Downloads folder in my home folder. You can specify this in the .rtorrent.rc file in your home folder that we created earlier; you'll need to use TextMate/Wrangler to open the file as it's hidden in the Finder. The part you need to edit in the .rtorrent.rc file is the following:
# Default directory to save the downloaded torrents.
directory = /Users/Ali/Downloads/
You'll notice I've removed the # at the beginning of the second line (this makes the option enabled) and specified the path of the folder I want rTorrent to download stuff to. If you're unsure of a folder's path, you can find out what it is by simply dragging and dropping that folder onto a Terminal window. When you do so, the path of the folder will appear in Terminal, which you can copy & paste into the .rtorrent.rc file.
This is the folder we also need to modify permissions for. You can do this by issuing the following command in Terminal (depending on the path of your download folder for rTorrent):
chmod a+rx path/of/rTorrent/download/folder
In my case, this is:
chmod a+rx ~/Downloads
Once you've done this, the create plugin will allow you to choose files/folders by clicking on the small box shown below:
You can go 'up' a folder in this box by double-clicking on /.. although you should note that it will only display folders for which it has permission to. If there's a folder you want to pick with it that isn't showing up, just modify the permissions for that folder in the same way that we did before, i.e. issue the following type of command:
chmod a+rx path/of/folder
Congrats, you now have a functioning copy of ruTorrent that can even create torrent files! Feel free to explore the other plugins available for ruTorrent if you so wish (see the list at the bottom of this page) but you'll have to support yourself in using them as I don't use any other plugins myself.
This guide is based on my experience with another guide. It's something of a work in progress and certainly isn't foolproof. However, nothing should go disastrously wrong if you at least follow the guide correctly. If something doesn't work for you, post here and I will try to help (but no guarantees that I can offer any). Note also: I'm running Mac OS X 10.6, so if you're running Lion, Leopard or Tiger then you may need to tweak parts of this guide for it to work.
To install rTorrent, we'll be using MacPorts. This requires the developer tools found on your Mac OS X installation disc.
1. Installing the Developer Tools
If you've already installed the Developer Tools, you can skip ahead to section 2
First things first: insert your Mac OS X installation disc into your Mac. Open up the disc in Finder, open the Optional Installs folder and open Xcode.mpkg, like so:
Continue through the installer until you get to the screen that lets you choose what you want to install. Make sure that System Tools and UNIX Dev Support are ticked:
Click Continue and carry on with the installation process. After a (possibly long) while, the Developer Tools should be successfully installed.
2. Installing MacPorts
This is pretty simple, really. Download MacPorts by getting the latest version for your system from here: https://distfiles.macports.org/MacPorts/
Open the .dmg and install MacPorts. There are no options to deal with so no screenshots here.
3. Installing rTorrent
Open up Terminal (if you've never used it before, you can find it in the Utilities folder in Applications). To make sure MacPorts is working, issue (that means, type into Terminal and press enter) the following command (throughout this guide, you can copy and paste any commands into Terminal):
port
If MacPorts was installed properly, you should see something like:
MacPorts 2.0.3
Entering interactive mode... ("help" for help, "quit" to quit)
[/your/current/working/directory] >
To leave the interactive mode, issue the command:
quit
We can now install rTorrent. Issue the following command:
sudo port install rtorrent-devel +xmlrpc
It will ask for your password. Type it in (note that it won't show up as you type it, not even in asterisks or dots; you can still press backspace to delete mistakes though) and press enter. You can now safely go do something else while MacPorts works on downloading and installing rTorrent and all its dependencies. Once it's finished, you'll have a working copy of rTorrent! Hurray! You can even start using it right now by issuing the command:
rtorrent
To quit rtorrent, use Ctrl q (i.e. hold down Ctrl and press q). There's a nicer way to use rTorrent via a program called screen. Issue the following command:
screen rtorrent
It may not look any different to when you issued just 'rtorrent' by itself but here's the clever part: press Ctrl a then d. You should be returned to the command prompt but with the following line above the prompt:
[detached]
screen is a program that effectively lets you create virtual terminals. This is useful because you can now quit Terminal without stopping rTorrent; it will carry on running in the virtual terminal you created, independently of the Terminal app. You can reattach the screen we've just made by issuing:
screen -r
This will return you to the screen where rTorrent is running. If you quit rTorrent (Ctrl q), the screen containing rTorrent will also be closed, and you'll have to issue 'screen rtorrent' again to start running it again. At this point, you have a fully functioning text-based BitTorrent client. There are many guides out there describing how to use and configure rTorrent and you can now start making use of them. However, if you're looking for a nice fancy GUI, read on...
4. Installing a web interface - pre-installation tweaks
There are various web interfaces that can control rTorrent through a protocol known as XML-RPC. To function, they need web server software. Luckily, Mac OS X comes with Apache, one of the most widely used web server software in the world. However, there is a fair amount of tweaking that needs to be done first (regardless of which interface you wish to use).
4.1 Apache: enabling PHP, installing mod_scgi and other tweaks
Mac OS X's preinstalled copy of Apache comes with the PHP extension but it's disabled by default. To enable it, we need to edit a certain text file. At this point, I'm going to assume you have a good text editor like TextMate (paid) or TextWrangler (free). TextEdit has to be constantly told to save files as plain text, and doesn't have any colour schemes for displaying code, so I don't recommend using it. The file we'll be editing is:
/private/etc/apache2/httpd.conf
The 'private' folder (found at the top level of the drive that Mac OS X is installed to; probably 'Macintosh HD') is, as the name suggests, hidden from view in the Finder. However, TextMate and TextWrangler both allow you to see hidden files in their 'Open' dialog box. So open the file with one of them and scroll down to line 115. You should see:
#LoadModule php5_module libexec/apache2/libphp5.so
The '#' at the beginning of the line means the whole line is treated as a comment; Apache will ignore it and so won't load the php module that we need to run a web interface. To fix this, simply delete the '#' so that the line becomes:
LoadModule php5_module libexec/apache2/libphp5.so
Save the file (you'll be prompted for your password) but don't close it, as we'll be editing it again soon. We now need to install mod_scgi, an extension that isn't included with Mac OS X. You can do so by issuing the following commands in Terminal in order:
curl -O http://python.ca/scgi/releases/scgi-1.14.tar.gz
tar xf scgi-1.14.tar.gz
cd scgi-1.14/apache2
sudo apxs -i -c mod_scgi.c
This will install mod_scgi (after which you can delete the files that the above commands just downloaded) but, before Apache can start using it, we need to make one last tweak.
Issue the following commands in order:
cd /usr/sbin
sudo mv ./httpd ./httpd.fat
file ./httpd.fat
You should see that the Apache binary is compiled with support for several architectures. If for example you're running Snow Leopard on a (64-bit) Intel processor, this will probably be displayed as:
./httpd.fat: Mach-O universal binary with 3 architectures
./httpd.fat (for architecture x86_64): Mach-O 64-bit executable x86_64
./httpd.fat (for architecture i386): Mach-O executable i386
./httpd.fat (for architecture ppc7400): Mach-O executable ppc
We need to strip the unneeded parts so that Apache can load the scgi module. Which part you need depends on which architecture you're on. If you're on a 64-bit capable processor (Intel Core 2 Duo, i5, i7, etc.), you'll want x86_64. If you're on the older 32-bit only capable ones (Intel Core Duo, Core Solo, etc.), you'll want i386. And if you're on PowerPC, you'll want ppc7400. Since my MacBook uses an Intel Core 2 Duo, I issue the following commands in order:
sudo lipo ./httpd.fat -thin x86_64 -output ./httpd.x86_64
sudo ln -s ./httpd.x86_64 ./httpd
file ./httpd.x86_64
If you want to keep i386, replace every instance of 'x86_64' in the above with 'i386', and similarly for ppc. You should be met with something like:
./httpd.x86_64: Mach-O 64-bit executable x86_64
showing the architecture that you kept.
We can now tell Apache to load the module by editing the file /private/etc/apache2/httpd.conf that we edited previously, so open it up again in TextMate/Wrangler. Scroll down to the bottom of the 'LoadModule' lines (around line 115) and add this line:
LoadModule scgi_module libexec/apache2/mod_scgi.so
Then, add this line at the bottom of the file:
SCGIMount /RPC2 localhost:5000
This is also a good chance to create a session directory for rTorrent, so issue the following commands in Terminal:
cd
mkdir .session
Then edit line 26 of .rtorrent.rc to tell rTorrent to use this directory ( /Users/username/.session ) as a session directory. In my case, line 26 would read:
session = /Users/Ali/.session
Don't forget to remove the # at the beginning of the line.
Save the file and quit TextMate/Wrangler. We're now almost ready to install a web interface. The only thing that remains is to make a certain configuration file for rTorrent.
rTorrent uses a configuration file in your home folder called .rtorrent.rc but there won't be such a file in your home folder right now. If rTorrent is still running, quit it, as it won't use the configuration file until it's been restarted.
You can download an example configuration file from here. Open it up with TextMate/Wrangler and add the following line to the bottom of the file:
scgi_port = localhost:5000
Save the file, then move it to your home folder. Rename it using the Terminal by issuing the following command:
mv rtorrent.rc.txt .rtorrent.rc
We can now install a web interface! Already?!
5.1 Installing ruTorrent
Before doing anything, make sure that rTorrent is running. If you haven't quit it yet, you can reattach the screen for it by issuing the command:
screen -r
Otherwise you can start it again by issuing the command:
screen rtorrent
Remember that you can detach from this screen by pressing Ctrl a then d.
Now, we need to download ruTorrent to the Sites folder in your home folder and modify its permissions. You can do all this by issuing the following commands in order:
cd ~/Sites
svn co http://rutorrent.googlecode.com/svn/trunk/rutorrent
chmod a+rx rutorrent
To start using ruTorrent, we need to start Apache. This is done most easily by opening up System Preferences and enabling 'Web Sharing' in the Sharing pane:
Finally, there's one last thing to install via MacPorts. Issue the following command in Terminal:
sudo port install proctools
When that's installed, you can run ruTorrent by pointing your web browser to the following address (depending on your username on Mac OS X):
http://localhost/~username/rutorrent/
In my case, this is:
http://localhost/~Ali/rutorrent/
You should now be greeted with a working copy of ruTorrent:
Hurray! You might notice a button with an icon of a star in my screenshot that you won't have at this point. This button is for a plugin that allows ruTorrent to create torrent files. If you don't want this functionality, you may stop reading now and go off and use ruTorrent like a giddy schoolgirl. Otherwise, keep reading.
5.2 Installing the create plugin for ruTorrent
To download the create plugin, issue the following commands in Terminal:
cd ~/Sites/rutorrent/plugins
svn co http://rutorrent.googlecode.com/svn/trunk/plugins/create
The create plugin itself can create torrent files but I prefer to just use it as a frontend for another little program called mktorrent, which works a bit better. You can install it using MacPorts with the following command:
sudo port install mktorrent
Now go to the ruTorrent folder (in your home folder's Sites folder). Open up the plugins folder, then the create folder. In there is a file called conf.php which we need to edit, so open it up with TextMate/Wrangler. Edit the first part of line 6 so that it reads:
$useExternal = 'mktorrent';
Then edit the first part of line 12 so that it reads:
$pathToCreatetorrent = '/opt/local/bin/mktorrent';
Now save the file and close it. If you open up ruTorrent now, you'll be able to see the star icon button for the create plugin. If you click it, you'll see a box that allows you to specify the path of the folder/file you want to create a torrent out of (plus other options). Specifying the full path of something can be a bit of a pain though, so let's install the _getdir plugin.
5.3 Installing the _getdir plugin for ruTorrent
To download the _getdir plugin, issue the following commands in Terminal:
cd ~/Sites/rutorrent/plugins
svn co http://rutorrent.googlecode.com/svn/trunk/plugins/_getdir
This plugin doesn't require any configuring but you might have to modify the permissions of rTorrent's download directory. I've configured rTorrent to download stuff to the Downloads folder in my home folder. You can specify this in the .rtorrent.rc file in your home folder that we created earlier; you'll need to use TextMate/Wrangler to open the file as it's hidden in the Finder. The part you need to edit in the .rtorrent.rc file is the following:
# Default directory to save the downloaded torrents.
directory = /Users/Ali/Downloads/
You'll notice I've removed the # at the beginning of the second line (this makes the option enabled) and specified the path of the folder I want rTorrent to download stuff to. If you're unsure of a folder's path, you can find out what it is by simply dragging and dropping that folder onto a Terminal window. When you do so, the path of the folder will appear in Terminal, which you can copy & paste into the .rtorrent.rc file.
This is the folder we also need to modify permissions for. You can do this by issuing the following command in Terminal (depending on the path of your download folder for rTorrent):
chmod a+rx path/of/rTorrent/download/folder
In my case, this is:
chmod a+rx ~/Downloads
Once you've done this, the create plugin will allow you to choose files/folders by clicking on the small box shown below:
You can go 'up' a folder in this box by double-clicking on /.. although you should note that it will only display folders for which it has permission to. If there's a folder you want to pick with it that isn't showing up, just modify the permissions for that folder in the same way that we did before, i.e. issue the following type of command:
chmod a+rx path/of/folder
Congrats, you now have a functioning copy of ruTorrent that can even create torrent files! Feel free to explore the other plugins available for ruTorrent if you so wish (see the list at the bottom of this page) but you'll have to support yourself in using them as I don't use any other plugins myself.
