PyroScope Project edited this page Mar 4, 2018 · 12 revisions

Using XMLRPC with rTorrent

TODOs for this page

  • Security review of all the webserver config snippets (specifically nginx)
  • Use non-deprecated commands
  • Use domain sockets, and only mention TCP in a warning
  • Take out all the "you could" stuff that only confuses people (less options is more)

Configuring rtorrent and your webserver

What you need:

Configure rtorrent with the --with-xmlrpc-c flag. Then add appropriate configuration, according used web-server.


httpd.conf (2.2):


httpd.conf (2.4):

ProxyPass /RPC2 scgi://


scgi_port =



scgi_local = /home/user/rtorrent/rpc.socket

# Set correct access rights to the socket file ----------+
# so both, lighttpd and rtorrent, could perform          |
# read-write operations                                  v
schedule = scgi_permission,0,0,"execute.nothrow=chmod,\"g+w,o=\",/home/user/rtorrent/rpc.socket"


server.modules += ( "mod_scgi" )
scgi.server = (
                "/RPC2" =>
                  ( "" =>
                      "socket" => "/home/user/rtorrent/rpc.socket",
                      "check-local" => "disable",
                      "disable-time" => 0,  # don't disable scgi if connection fails



scgi_port =



location /RPC2 {
  include     scgi_vars;
  scgi_var    SCRIPT_NAME  /RPC2;

or (on ubuntu server 14.04)

http {
  server {
    server_name ngnix-rtorrent;
    access_log /var/log/nginx/rtorrent.access_log;
    error_log /var/log/nginx/rtorrent.error_log;

    location /RPC2 {
      include     scgi_params;

Do not forget, that on http://localhost:8008/RPC2 you will not see anything (through in rtorrent.error_log you will see something as upstream prematurely closed connection while reading response header from upstream, client:, server: ngnix-rtorrent, request: "GET /RPC2 HTTP/1.1", upstream: "scgi://", host: "". It is xmlrpc, not web service. You can test it by xmlrpc (see later))

Other notes

If any of your downloads have non-ascii characters in the filenames, you must also set the following in rtorrent.rc to force rtorrent to use the UTF-8 encoding. The XMLRPC standard requires UTF-8 replies, and rtorrent presently has no facilities to convert between encodings so it might generate invalid replies otherwise.

encoding_list = UTF-8

The web server will now route xmlrpc requests to rtorrent, which is listening only on connections from the local machine or on the local socket file. Also make sure the /RPC2 location is properly protected, and also name it differently to evade attackers probing for vulnerabilities.

:bangbang: Never bind the SCGI port to anything but Anyone who can send rtorrent xmlrpc commands does have the ability to execute code with the privileges of the user running rtorrent. If you want to be more secure on principle, use UNIX domain sockets instead of TCP ports (see below).

You may also use scgi_local = /foo/bar to create a local domain socket, which supports file permissions. Set the rw permissions of the directory the socket will reside in to only allow the necessary processes. This is the recommended way of using XMLRPC with rtorrent, though not all http servers support local domain sockets for scgi.

Test and usage

Access the XMLRPC interface using any XMLRPC-capable client. For example, using the xmlrpc utility that comes with xmlrpc-c:

 > # To list all the xmlrpc methods rtorrent supports.
 > xmlrpc localhost:8008 system.listMethods

 > # Get max upload rate.
 > xmlrpc localhost:8008 get_upload_rate ""

 > # Set upload rate, exact 100000 bytes.
 > xmlrpc localhost:8008 set_upload_rate "" i/100000

 > # Set upload rate, 100kb.
 > xmlrpc localhost:8008 set_upload_rate "" 100k

 > # See list of downloads in "main" view
 > xmlrpc localhost:8008 download_list ""

 > # See list of downloads in "started" view
 > xmlrpc localhost:8008 download_list "" started

 > # Get uploaded bytes for specific download by info-hash
 > xmlrpc localhost:8008 d.get_up_total e66e7012b8346271009110ac38f91bc0ad8ce281

 > # Change the directory for a specific download.
 > xmlrpc localhost:8008 d.set_directory 91A2DF0C9288BC4C5D03EC8D8C26B4CF95A4DBEF foo/bar/

 > # Size of the first file in a specific download.
 > xmlrpc localhost:8008 f.get_size_bytes 91A2DF0C9288BC4C5D03EC8D8C26B4CF95A4DBEF:f0

It supports both single strings akin to what the option file accepts, and proper xmlrpc integer, string and lists.

See the man page and the rtorrent/src/command_* source files for more details on what parameters some of the commands take.


Note that all commands now require a target, even if it is an empty string.

 > xmlrpc localhost f.get_size_bytes 91A2DF0C9288BC4C5D03EC8D8C26B4CF95A4DBEF:f3
 > xmlrpc localhost p.get_url        91A2DF0C9288BC4C5D03EC8D8C26B4CF95A4DBEF:p0

The first and second example passes the index of the file as an integer and string respectively. The third example uses a more compact syntax that contains both the info hash, type and index in the same string.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.