rtorrent XMLRPC over nginx SCGI

2 minute read

Screenshot of rtorrent running in a terminal

So I’ve just started coding a new Rails project - a frontend for the awesome rtorrent BitTorrent client - and already wasted a bit of time getting started due to outdated instructions for setting up XMLRPC/SCGI on nginx from the rtorrent guide. Here’s what I did, current as of nginx 1.0.4 and rtorrent 0.8.6:

  1. Download / compile latest rtorrent and nginx from source. You do not need any third-party SCGI module for nginx, as it now comes integrated. Therefore, if you are installing nginx for Ruby on Rails usage using Passenger, you don’t need to do the advanced setup if you don’t have any extra settings / modules to pass to the configure script (although you probably won’t pull in the latest nginx version using the easy method; it currently grabs 1.0.0 while latest stable is 1.0.4).

  2. Add these lines to your .rtorrent.rc file:

     encoding_list = UTF-8
     scgi_local = /home/rtorrent/scgi.socket
     execute = chmod,ug=rw\,o=,/home/rtorrent/scgi.socket
     execute = chgrp,rtorrent-nginx,/home/rtorrent/scgi.socket

    The execute lines are for setting permissions on the Unix domain socket file that rtorrent and nginx will use to communicate. These will be dependent on how you want to set up your permissions. This is a very important security step to take if you are doing this on a shared server, as any user that has read/write access on the socket file could execute arbitrary code by sending commands to rtorrent!

    In my case, I set up a separate user for running rtorrent (named rtorrent) and a separate user for running nginx (named nginx). I then created a group called rtorrent-nginx, and only have my rtorrent and nginx users added to it.

  3. Add this block to nginx.conf inside of the server block you are using:

     location ^~ /scgi {
         include scgi_params;
         scgi_pass  unix:/home/rtorrent/scgi.socket;

    It should end up looking something like this afterwards:

     http {
         server {
             listen      80;
             server_name localhost;
             root        /home/rtorrent/my_site/public;
             location ^~ /scgi {
                 include scgi_params;
                 scgi_pass  unix:/home/rtorrent/scgi.socket;
  4. Done configuring! Start up nginx and rtorrent; you should now be able to test your setup. Here’s an example, using the xmlrpc utility from the xmlprc-c library (sudo apt-get install libxmlrpc-c3-dev on Ubuntu):

     $ xmlrpc localhost/scgi system.client_version
     String: '0.8.6'

    or using Ruby (irb):

     require 'xmlrpc/client'
     server = XMLRPC::Client.new2("http://localhost/scgi")
     #=> "0.8.6"

And that’s it. Also, you should be aware that anyone with access to your nginx server will be able to send commands to rtorrent unless you set up at least some basic HTTP authentication!

Hopefully, my next posting will be with some Rails code that takes advantage of this process. :-)