Howto: Use rtorrent like a pro

I’m a huge rtorrent fan. I can’t imagine why anyone would use anything else, unless there’s something funky the big-name programs can do, that rtorrent just doesn’t handle yet.

This time, instead of introducing you to rtorrent nice and easy, like I did with cplay, I’m going to give you a brief tour, and then I’ll show you something very cool you can do with it. rtorrent is an amazing, complex, powerful program that is at the same time sleek, clean, comprehensive and ultralight — and I’m giving you just one small idea of its potential.

But first, let’s scratch the surface. Like a lot of console-driven programs, the startup screen for rtorrent is … rather dry.

That’s all you get. Exciting, isn’t it? 🙄

To add a torrent, press return and navigate to the torrent file. In this example, I’m using one of my favorite Revolution Void albums, “Increase the Dosage,” from Jamendo. I can’t guarantee you’ll like it, but it’s a free and legal download and it makes for a good example.

You can use tab completion to make your way to it. Double-tab shows a list of available path options that match the path you’ve already started. Your path starts in your home directory (unless you started it in a lower directory than that), so you don’t have to give it the full root path if you don’t want to. Press enter when you’ve found the one you want, and rtorrent will add it to the list.

Note that it’s still labeled as “INACTIVE.” rtorrent won’t start downloading until you tell it to. Use the arrow up and down keys to highlight the torrent (it will be marked with a bar of asterisks) and press CTRL+S.

Now we’re moving. The torrent is marked as active, the tracker will be contacted, and provided there are adequate seeds, downloading will start.

That’s about it, in a nutshell. There are some customary points that you’d expect from a torrent client. Press the right arrow while a torrent is highlighted, to see a detailed breakdown of the information available.

To get back to the main list, use the left arrow. Bandwidth throttling might be important to you too. If you’re used to capping your bandwidth (I choke my upload speeds to keep my wireless router from having a nervous breakdown), try using the a-s-d, A-S-D, z-x-c and Z-X-C keys to trim the speed to your liking.

If you take a few moments to experiment, you’ll find that pressing the numbers 1-6 gives you a revised view, with different filters applied. That can be useful if you’ve got 10 or 12 torrents running at a time, and you want a clear list of finished torrents, or stopped torrents. And most important, you can quit the program with CTRL+Q.

This is where you can stop if you just wanted the short tour. The next part is for people who really want to put rtorrent to work, and don’t mind getting their hands dirty. 😈

When you started rtorrent for the very first time, you probably saw a warning message that told you there wasn’t a .rtorrent.rc file to follow. That configuration file is what morphs rtorrent from a mild-mannered, law-abiding console gimmick into an unholy torrent-wrangling banshee.

In Ubuntu, the sample rtorrent configuration file is hiding at /usr/share/doc/rtorrent/examples/rtorrent.rc. Copy one for your own perusal, and give it the proper hidden file prefix.

cp /usr/share/doc/rtorrent/examples/rtorrent.rc ~/.rtorrent.rc

Edit, 2010-05-07: Please remember that this post was written a few years ago, and the configuration file for the current, vanilla rtorrent may be different from what you see here. — K.Mandla

Now open that file in your favorite text editor. Take a minute or two to peruse the guts. (I’ve copied one to the Ubuntu-nl pastebin for reference, or if you’re reading this at work on your $3,000 DRM-crippled Vista rig. 😛 )

You should get an idea of what the file can do; setting max uploads and downloads, default throttling and IP masking are all options. But take a closer look at some of these settings.

# Watch a directory for new torrents, and stop those that have been
# deleted.
#schedule = watch_directory,5,5,load_start=./watch/*.torrent
#schedule = untied_directory,5,5,stop_untied=

What’s that mean, you say? Well, it means rtorrent can watch a directory and add torrents to its list automatically, and stop torrents if the corresponding file disappears. Now look at this:

# Stop torrents when reaching upload ratio in percent,
# when also reaching total upload in bytes, or when
# reaching final upload ratio in percent.
# example: stop at ratio 2.0 with at least 200 MB uploaded, or else ratio 20.0
#schedule = ratio,60,60,stop_on_ratio=200,200M,2000

You can also allow seeding to a specific ratio, a specific total uploaded or both. So if you get tired of carrying the weight of the Internets on your shoulders, you can limit your sharing on any number of criteria.

That’s nothing new, you might say. Azureus does all that, plus it has a feature-rich GUI, is proof of the viability of Java applications and has a cool blue frog as a mascot.

Well, please allow me to retort … with a case study: Imagine you’ve got two machines: Your $3,000 dual-core, dual SATA-drive, LED-bespeckled laptop straight from Dell, with an array of glossy sheen snap covers, eight USB ports, a gigabit connection and a built-in 802.11a-wireless card.

Your other machine is the lowly 166Mhz Pentium laptop. The one with 64Mb of PC66 and a 3Gb hard drive. The one you got from work in 1997 and never took back, even when you left them for another company during the dot-com boom. Burnt-out pixels, loose hinges and one scratchy speaker. The one with the Stone Temple Pilots sticker peeling off the lid. You know what I’m talking about.

Set up your main rig with a shared network folder (NFS would be perfect for this) on a static IP address. Set up your lowly Pentium machine with a hard line to your router, maybe with a PCMCIA LAN card — something that at least gives you decent access speeds.

Now mount that shared folder directly into your slave’s home directory, maybe under ./watch. Set up the configuration file. Trigger rtorrent on bootup, and tell it to watch that folder.

Now you surf away in the comfort of your shiny dual-core desktop-replacement laptop, and when you find a torrent you like, save it into the local networked folder — perhaps even sending it to that folder automatically, through Firefox’s file extension preferences.

When you save it, rtorrent snaps it up and adds it to its list. It starts downloading it automatically, saving the file locally or perhaps on an external drive. You can set it to follow a certain bandwidth schedule so it doesn’t overwhelm the network, or you could hold all the torrents until the middle of the night, and do all your downloading during the wee hours.

It continues to download until it’s finished, then seeds for as long as you allow it. If it reaches the seeding ratio you set, it stops. If it reaches the upload limit, it stops. And best of all, if you delete the control torrent file out of your local download directory, it halts all the activity on that torrent and subtracts it from the list. Download the torrent, and it starts immediately. Change your mind and delete it, and rtorrent cuts it loose. Clean and neat, all handled automatically and without the least amount of effort on your part. It’s almost like a torrent daemon.

(In my experience, rtorrent never deletes the product files it has already created. So if you start downloading and change your mind an hour later, rtorrent might take the torrent out of the list, but the target files are still available. Conceivably, you could change your mind again and re-download the torrent file, and rtorrent would pick up the already downloaded fraction and get back to work on it. But I’m not 100 percent sure on that because I don’t recall ever doing it, so don’t hold me to that. 🙂 )

I’ll be honest and say I haven’t used Azureus in more than a year, and so it’s possible that you could create the same arrangement with Azureus. But can Azureus run on your leftover Pentium Pro laptop?

rtorrent is highlighted in yellow in that htop window. CPU usage is roughly 1.0 percent of my 300Mhz and the memory profile around 10 percent of my 64Mb, and that’s while it actively downloads the album I started with when I began writing this. Add a few more torrents and of course the profile will go up, but the benefit of running without Java, without the X interface and without two dozen Gnome dependencies should be blatantly obvious. I’m willing to bet your old Pentium could do it.

Spacewise, rtorrent is going to cost you 314Kb for the download and 860Kb to install. libtorrent9 is necessary, so that’s another 284Kb to download and 788Kb on your drive, so you’re looking at less than 600Kb of bandwidth and maybe 1.6Mb installed. Again, I’ve written letters to Mom that took up more space than that.

I hope this is convincing enough to get you to try rtorrent, and maybe even use it on a regular basis. I really believe it’s a better option than most of the prevailing torrent clients, even if it is console-based. If you want to delve even deeper into this amazing little program, take a spin past the rtorrent wiki, which is one of the best-composed and best-written I’ve seen in a long time. The project is very active, and it has the look of it.

Next time: Give up on the Gecko, and browse with elinks instead.

Edit, 2008-02-14: dodger has been kind enough to translate this howto into Spanish; it’s on his blog here. Please remember that my blog is GFDL 1.2, which means you’re free to use or translate this post as you like, so long as you redistribute the content with the same license, or a later version. For more details, see my About page.

Edit, 2008-08-04: If you’d like to see a working example and configuration files for the systems I described here, take a look at this post.

Edit, 2009-01-23: If you’d like to see this setup on exceptionally low-end hardware, consider this example. Even at 100Mhz with only 16Mb for system memory and a lethargic 810Mb hard drive, it’s possible to use rtorrent in a networked arrangement and feed it the work of downloading and seeding.

Edit, 2009-11-14: This post is more than two years old now, but is still one of the heaviest draws to this site. I had to re-upload photos for this page, and likewise had to edit the text slightly to make sure what you saw in the pictures was what you were reading in the text. My apologies if I overlooked any discrepancies. Cheers and enjoy.

Edit, 2010-05-07: It’s ironic that almost exactly on the third birthday of this post, a second image host has expired and I’ve had to reupload the images again. I suppose it’s a testimonial to either this post or to rtorrent (or maybe Revolution Void), take your pick. 😉 Once again, if you see something different from what’s in the pictures, please let me know. It might be around for a couple more years still. 😯

P.S., 2010-05-07: Just for the record, the screenshots that you see currently are of the rtorrent-extended package available in Arch’s AUR. The system is a 300Mhz Celeron laptop running only framebuffer applications on Arch Linux, writing downloads directly over USB1.1 to an external hard drive, accessed across a wireless network with ssh and nfs, and managed by a 120Mhz Pentium laptop running Crux. This is the part where you try to out-geek me. 😈