[[libtorrentMirror]]

= Using XMLRPC with rtorrent =

Since version  0.7.5, rtorrent has a built-in XMLRPC interface (if enabled). Recommendations for secure usage will come later, just make sure you are aware of the implications of opening the XMLRPC port. See [wiki:RTorrentCommands] for an incomplete list of commands.

== Installation & Configuration ==

What you need:

 * http://python.ca/scgi/ for Apache, Lighttpd should have this built-in.
 * http://xmlrpc-c.sourceforge.net/ 1.00 or later, 1.07 or later for 64bit integer support.
 * rtorrent 0.7.5 or later.

Configure rtorrent with the --with-xmlrpc-c flag and add the following to:

{{{
httpd.conf:  SCGIMount /RPC2 127.0.0.1:5000
rtorrent.rc: scgi_port = localhost:5000
}}}

For lighttpd:
{{{
rtorrent.rc: scgi_local = /home/user/rtorrent/rpc.socket

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

For nxing:

Compile the latest nginx version with the modified mod_scgi found [http://libtorrent.rakshasa.no/downloads/mod_scgi-b466baa5fcdb.tar.gz here]. Note that you must use the linked version as it contained bug fixes and modifications to make it work properly.

{{{
location /RPC2 {
  scgi_pass   127.0.0.1:5000;
  include     scgi_vars;
  scgi_var    SCRIPT_NAME  /RPC2;
}
}}}

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.

To make it accessible from anywhere, use "scgi_port = :5000". This is 
however not recommend as rtorrent has no access control, which means the 
http server is responsible for handling that. Anyone who can send 
rtorrent xmlrpc commands is likely to have the ability to execute code 
with the privileges of the user running rtorrent.

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.'''

== 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 system.listMethods

 > # Get max upload rate.
 > xmlrpc localhost get_upload_rate

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

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

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

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

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

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

 > # Size of the first file in a specific download.
 > xmlrpc localhost f.get_size_bytes 91A2DF0C9288BC4C5D03EC8D8C26B4CF95A4DBEF i/0
}}}

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.

=== Targets ===

As we saw above, commands that requires a file or tracker can be called in several different ways. (rTorrent 0.8.1+)

{{{
 > xmlrpc localhost f.get_size_bytes 91A2DF0C9288BC4C5D03EC8D8C26B4CF95A4DBEF i/3
 > xmlrpc localhost f.get_size_bytes 91A2DF0C9288BC4C5D03EC8D8C26B4CF95A4DBEF "3"
 > 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 a 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.