rtorstat is a simple web page generator, written in Python, which shows status information about the rTorrent bittorrent client. This makes it possible to quickly have an overview of your torrent list from a remote location, without having to log into the remote machine that actually runs rTorrent.

The script can operate in two modes:

• Run through cron at predefined intervals. In this case it reads the saved rtorrent session data, creates a summary about the loaded torrent files status and prints the HTML code to stdout, which can then be redirected to a file and thus be made publicly available by a web server.
• Run as a CGI script, which makes it possible to dynamically generate the HTML page on-demand. This method, compared to running rtorstat through cron at short pre-defined intervals, has the advantage of limiting system resource waste by parsing the session data only when a user runs the CGI script through the web browser. Also, depending on your rtorrent settings, the displayed information is usually more current than that of the HTML page generated through cron, unless cron runs the script very often.

rtorstat does not support or will never support any kind of remote rTorrent administration. It is not supposed to be a web-based rtorrent frontend, but, as the title says, a simple status page generator (status web interface).

Requirements

rtorstat is not dependency-free. Here is the list of the required software in order to run rtorstat:

• Python
• rTorrent (configured to save session data – see below)
• The file “bencode.py“, part of the official Bittorrent client (Mainline) distribution, has been included in the rtorstat distribution package, so the Mainline Bittorrent client is no longer a dependency for rtorstat.

rTorrent Configuration

rtorstat needs to read the torrent session data, so rTorrent needs to be configured to save this information to a pre-defined directory. The following shows all the session-data specific configuration rTorrent (.rtorrent.rc) options:

# Sets the directory where session data files are stored
session = /opt/bittorrent/sessiondata

# Keeps session data files even if torrent has finished
session_on_completion = yes

# Not really required, but recommended - see rtorrent(1) man page
session_lock = yes

# Setup A: Run through CRON
# Save session data every 5 mins, with a 4 min offset
schedule = session_save,240,300,session_save=

# Setup B: Run as a CGI
# Save session data every 300 seconds
# (This is an example value. Setting it to a lower value is highly recommended)
#schedule = session_save,300,300,session_save=

The last directive (schedule) instructs rtorrent to save session data at the specified interval.

Usage

rtorstat can be run through cron or as a CGI script. Running it as a CGI is the preferred way of running it as the parsing of the session data and the HTML page generation take place dynamically only when you visit the web page. This leads to wasting less system resources.

Running rtorstat through cron

No special installation is needed as the location of rtorstat.py can be set within the cron job. Just make sure that the file bencode.py exists in the same directory as rtorstat.py.

rtorstat requires one argument; that is the path to the directory where the session data is saved:

$ python rtorstat.py /opt/bittorrent/sessiondata/

Having parsed the session data files and having created the summary, the HTML code is printed to stdout, from where it can be redirected to a html file. For example:

$ python rtorstat.py /opt/bittorrent/sessiondata/ > /var/www/index.html

rtorstat is supposed to be run through cron at regular intervals. In the example configuration above (Setup A), rtorrent saves the session data every 5 minutes (300 sec), so rtorstat needs to be run at the same interval through cron. The 4 min offset (240 sec) that had been set in the rtorrent scheduler serves so that there is good timing between rTorrent saving the session data and rtorstat parsing it.

Such a cron job would be:

*/5 * * * *   root python /path/to/rtorstat.py /opt/bittorrent/sessiondata/ > /var/www/index.html

rtorstat will parse the session data files, for example, at 00:05, 00:10 etc.

Having adjusted the paths according to your configuration, save the above cronjob to a file inside the /etc/cron.d/ directory and you are set.

Running rtorstat as a CGI script

In this case, you need to place 3 files in your cgi-bin: rtorstat.py, rtorstat.cgi and bencode.py.

Apart from the rtorrent configuration, it is required to set the path of the directory where rtorrent saves session data in rtorstat.cgi. So, open rtorstat.cgi in your favourite text editor and fill-in the required information:

session_dir = "/path/to/rtorrent/session/dir/"

Now, you can visit the web page http://yourdomain.example.org/cgi-bin/rtorstat.cgi

Setting up a scriptaliased directory is covered by your web server’s documentation and is outside of the scope of this document.

Security

rtorstat generates a HTML page which is made publicly available through a web server (most probably). Therefore it is your responsibility to secure this location using any of your web server’s access control methods.

License

This project is released under the terms of the Apache License version 2.

Download

All versions of the software, including the latest stable release, are available from the development web site’s download area.

Support

This software is released as free software without any warranties or official support. You can still get first class support from the community of users.

Bugs and Feature Requests

Found a bug? Want to suggest a new feature for the upcoming release? Feel free to file your requests in the issue database on the development website.

Things to consider

It has been mentioned before, but here it goes again:

Note that by making the rtorrent status page publicly available through a web server, the world will know what you download at any time. It is your exclusive responsibility to keep this page private, if this is what you really want. This piece of information is of course beyond the scope of this article.

This script was written in a quick and dirty way. If you encounter any bugs, please notify me through the g-loaded forums and I will get back to you when I have the time.

rtorstat – a simple rTorrent status web page generator by George Notaras is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.
Copyright © 2007 - Some Rights Reserved