Configuration Guide

Introduction

After you installed the software as described in the previous chapter, you need to add personal configuration that is loaded from the directory ~/.pyroscope containing the files config.ini and config.py. A default set can be automatically created for you, see below for details.

For simple setups, you only need to edit the plain text file config.ini. The script config.py allows much more detailed control over complex setups, at the price of you knowing at least the basics of the Python programming language. See Advanced Features for that.

Note

For a fresh installation of this software in addition to an existing rTorrent one, you will also need to back-fill some data that your already running rTorrent instance is missing otherwise. If you skip this step, item filtering in rtcontrol and other tools will not work correctly for existing items. More on that below.

In summary, you’ll perform these steps, explained in the sections that follow:

  1. Create a directory with the default configuration.
  2. Edit ~/.pyroscope/config.ini to adapt it to your needs, e.g. add tracker aliases.
  3. Modify your ~/.rtorrent.rc to integrate necessary settings.
  4. Back-fill some data into the rTorrent session.

To get in contact and share your experiences with other users of PyroScope, join the pyroscope-users mailing list or the inofficial ##rtorrent channel on irc.freenode.net.

This is also the way to resolve any problems with or questions about your configuration and software installation. Always look into the Trouble-Shooting Guide as a first measure, which is often the fastest way to get back to a working system. That guide also explains how to efficiently report your problem when you cannot fix it yourself.

Creating a set of default configuration files

To create your own configuration, the best way is to start from the default files that are part of your PyroScope installation. To create them at the default location ~/.pyroscope, simply call this command:

pyroadmin --create-config

Note that you can delete any defult setting from config.ini that you don’t want changed. These defaults are always loaded before your own settings, from a copy the software keeps and updates.

Deleting unchanged defaults has the advantage that on software updates, you’ll automatically get the newer version of settings, as soon as they’re updated. The created config.ini.default file is just for reference, and will be overwritten on updates.

If you need several distinct configuration sets, just add the --config-dir option to commands like so:

pyroadmin --create-config --config-dir ~/rtorrent/special/.pyroscope

To view your loaded configuration with all the system defaults added, use this (again, the --config-dir option allows non-default configuration locations):

pyroadmin --dump-config

To start over with a pristine set of configuration files, and remove any stale ones, add the --remove-all-rc-files option:

pyroadmin --remove-all-rc-files --create-config

Be aware that this really removes any *.rc and *.rc.default file in ~/.pyroscope and its subfolder rtorrent.d, before writing a new set of files.

Note

Each PyroScope configuration file is accompanied by a matching *.default file that contains the system defaults at the time you last called the pyroadmin --create-config command. These are over-written on repeated calls (unlike the real config files), and are for informational purposes only.

For the rTorrent configuration files (rtorrent-pyro.rc[.default] and files in rtorrent.d), the rules are different. These files change frequently, so the *.default versions are loaded usually, and you get an up-to-date version on a rTorrent restart.

You can ignore specific files in rtorrent.d if they don’t fit or you want to provide your own version under another name. See the files themselves for instructions.

Setting values in ‘config.ini’

The main configuration file consists of sections, led by a [section] header and followed by name: value entries; name = value is also accepted. Longer values can be broken into several lines and the continuation lines must be indented (start with a space). Note that leading whitespace is removed from values.

Lines beginning with a semicolon (;), a hash mark (#), or the letters REM (uppercase or lowercase) will be ignored and can be used for comments. You cannot append a comment to an option line, a comment MUST start at the beginning of a line!

As an example, this is a very minimal configuration file:

# PyroScope configuration file

[GLOBAL]
# Note that the "config_dir" value is provided by the system!
config_script = %(config_dir)s/config.py
rtorrent_rc = ~/.rtorrent.rc

[ANNOUNCE]
# Add alias names for announce URLs to this section; those aliases are used
# at many places, e.g. by the "mktor" tool

# Public trackers
PBT     = http://tracker.publicbt.com:80/announce
          udp://tracker.publicbt.com:80/announce
OBT     = http://tracker.openbittorrent.com:80/announce
          udp://tracker.openbittorrent.com:80/announce
Debian  = http://bttracker.debian.org:6969/announce

Note

For advanced users: Values can contain format strings of the form %(name)s which refer to other values in the same section, or values in the [DEFAULT] section.

Extending your ‘.rtorrent.rc’

You need either a network.scgi.open_local or network.scgi.open_port specification in your rTorrent configuration, else XMLRPC cannot work; network.scgi.open_local is preferable since more secure. Furthermore, you need to provide the path to a session directory via session.path. See the rTorrent documentation for details.

Note

Using network.scgi.open_port means any user on the machine you run rTorrent on can execute arbitrary commands with the permission of the rTorrent runtime user. Most people don’t realize that, now you do! Also, never use any other address than 127.0.0.1 with it.

For the loaded and completed fields to work, as well as the started, leechtime and seedtime ones, you also have to add these commands (note that most settings actually reside in an included file):

#
# PyroScope SETTINGS
#

# Set "pyro.extended" to 1 to activate rTorrent-PS features!
# LEAVE THIS AT 0 IF YOU RUN A VANILLA rTorrent!
method.insert = pyro.extended, value|const, 0

# Set "pyro.bin_dir" to the "bin" directory where you installed the pyrocore tools!
# Make sure you end it with a "/"; if this is left empty, then the shell's path is searched.
method.insert = pyro.bin_dir, string|const,

# Remove the ".default" if you want to change something (else your changes
# get over-written on update, when you put them into ``*.default`` files).
import = ~/.pyroscope/rtorrent-pyro.rc.default

# TORQUE: Daemon watchdog schedule
# Must be activated by touching the "~/.pyroscope/run/pyrotorque" file!
# Set the second argument to "-v" or "-q" to change log verbosity.
schedule = pyro_watchdog,30,300,"pyro.watchdog=~/.pyroscope,"

See this rtorrent.rc and the _rtlocal.rc file it includes for a complete example, including some view changes regarding sort order made possible by the additional custom fields.

Note

Remember to restart rTorrent for the new configuration to take effect. If you also installed the rtorrent-ps distribution of rTorrent, do not forget to activate the extended features available with it, by setting pyro.extended to 1 in the above configuration.

Adding Missing Data to Your rTorrent Session

Now that you have the additional configuration, newly loaded items will get the correct values set – but existing items are still missing them, and so those items will not always be filtered correctly. If you just started with a fresh install and have no items added to rTorrent yet, you can ignore this section.

To add the missing data, call these commands:

# Make a full, current backup of the session data
rtxmlrpc -q session.save
tar cvfz ~/session-backup-$(date +'%Y-%m-%d').tgz \
    $(echo $(rtxmlrpc session.path)/ | tr -s / /)*.torrent*

# Set missing "loaded" times to that of the .torrent file
rtcontrol '!*"*' loaded=0 -q -sname -o 'echo "$(name)s"\ntest -f "$(metafile)s" && rtxmlrpc -q d.custom.set $(hash)s tm_loaded \$(\
    ls -l --time-style "+%%s" "$(metafile)s" \
    | cut -f6 -d" ")\nrtxmlrpc -q d.save_full_session $(hash)s' | bash

# Set missing "completed" times to that of the data file or directory
rtcontrol '!*"*' completed=0 done=100 path=\! is_ghost=no -q -sname -o 'echo "$(name)s"\ntest -e "$(realpath)s" && rtxmlrpc -q d.custom.set $(hash)s tm_completed \$(\
    ls -ld --time-style "+%%s" "$(realpath)s" \
    | cut -f6 -d" ")\nrtxmlrpc -q d.save_full_session $(hash)s' | bash

It’s safe to call them repeatedly, since existing values are kept unchanged.

To check, use the command rtcontrol completed=-1d -scompleted which should now show your completed downloads of the last 24 hours, in order.

Continue with the User’s Manual to get to know all the commands.