Changes between Initial Version and Version 1 of archive/libtorrent.rakshasa.no/RTorrentXMLRPCGuide

Timestamp:

08/08/15 16:37:08 (9 years ago)

Author:

Gabor Hudiczius

Comment:

--

archive/libtorrent.rakshasa.no/RTorrentXMLRPCGuide

@@ +1 @@
+[[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.