Permalink
Switch branches/tags
Nothing to show
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
324 lines (220 sloc) 12.1 KB

Common Configuration Use-Cases

After you went through :doc:`cookbook` and got familiar with the handling of rTorrent, it's time to look at settings that you should consider for your configuration, but which weren't necessary to start using it.

The Common Tasks in rTorrent wiki page contains more of these typical configuration use-cases.

Load ‘Drop-In’ Config Fragments

The examples here and in the wiki are mostly short snippets written to serve a specific purpose. To easily add those by just dropping them into a new file, add this to your main configuration file (which then can be the last change you apply to it).

method.insert = cfg.drop_in, private|const|string, (cat, (cfg.basedir), "config.d")
execute.nothrow = bash, -c, (cat,\
    "find ", (cfg.drop_in), " -name '*.rc' ",\
    "| sort | sed -re 's/^/import=/' >", (cfg.drop_in), "/.import")
try_import = (cat, (cfg.drop_in), "/.import")

To test the change, execute these commands:

mkdir -p ~/rtorrent/config.d
echo 'print="Hello from config.d!"' >$_/hello.rc

Then restart rTorrent, and you should see Hello from config.d! amongst the initial console messages.

Hint

Config drop-ins are very useful when you manage your systems in a state-of-the-art way, i.e. using a configuration management tool like Ansible. Then you can simply add files with customizations to a system, without having to fiddle with changing existing files.

Note

If a drop-in file just contains commands that can be repeated several times, they can be re-imported making them way easier to test after changes. For example, schedules can be redefined, but method definitions can not (under the same name).

Log Rotation, Archival, and Pruning

The following longer snippet adds logs that don't endlessly grow, get archived after some days, and are finally deleted after a while. See rtorrent.d/15-logging.rc for the full snippet.

Warning

If you include this, take care to comment out any conflicting logging commands that you already have in your main configuration.

The time spans for archival and pruning are set using pyro.log_archival.days (default: 2) and pyro.log_retention.days (default: 7). You can change these in your main configuration, after including the snippet via :term:`import`.

.. literalinclude:: pimp-my-box/roles/rtorrent-ps/templates/rtorrent/rtorrent.d/15-logging.rc
   :language: ini
   :start-after: ----------
   :end-before: YYYY-mm-dd

Log files are time stamped (see pyro.date_iso.log_stamp and pyro.log_stamp.current). Full log file paths for different types are created using pyro.logfile_path, which takes the type as an argument.

.. literalinclude:: pimp-my-box/roles/rtorrent-ps/templates/rtorrent/rtorrent.d/15-logging.rc
   :language: ini
   :start-after: pyro.log_archival.days
   :end-before: open all logs

The pyro.log_rotate multi-method takes care of calculating a new time stamp, and rotating all the log files by re-opening them with their new name. A daily schedule calls this method and thus triggers the rotation.

.. literalinclude:: pimp-my-box/roles/rtorrent-ps/templates/rtorrent/rtorrent.d/15-logging.rc
   :language: ini
   :start-after: cat = (cfg.logs)
   :end-before: Log file archival

Finally, two schedules take care of daily archival (1:10 AM) and pruning (1:20 AM), passing the command built by pyro._logfile_find_cmd to bash for execution. The pyro.log_rotate method is used near the end to open log files at startup.

.. literalinclude:: pimp-my-box/roles/rtorrent-ps/templates/rtorrent/rtorrent.d/15-logging.rc
   :language: ini
   :start-after: pyro_daily_log_rotate
   :end-before: END logging


Rename Item Using its Tied-to File

The rename2tied.sh script overwrites an item's name using the file name of its tied-to file, when you press the R key with a fresh unstarted item in focus.

This is useful when the metafile names generated by a tracker contain more useful information than the info.name of the metafile content. Also, those metafile names typically have a common format, which can help with properly organizing your downloads.

Warning

Right now, this only works for items that are not started yet, i.e. were added using load.normal and have no data files yet.

Also, the item needs to be loaded from a file, so there actually is a tied-to name – items loaded via ruTorrent do not have one!

Here is the core script code (minus some boilerplate):

.. literalinclude:: examples/rename2tied.sh
   :language: shell
   :start-after: # pyro.bind_key
   :end-before: # End of

Install the full script by calling these commands:

gh_raw="https://raw.githubusercontent.com/rtorrent-community/rtorrent-docs"
mkdir -p ~/rtorrent/scripts
wget $gh_raw/master/docs/examples/rename2tied.sh -O $_/rename2tied.sh
chmod a+rx $_

Note that you also must have pyrocore installed, so that the rtcontrol and rtxmlrpc commands are available.

This is the configuration snippet that binds calling the script to the R key. For key binding, you need rTorrent-PS though – otherwise leave out the pyro.bind_key command, and call pyro._rename2tied= via a Ctrl-X prompt.

method.insert = pyro._rename2tied, private|simple, \
    "execute.nothrow = ~/rtorrent/scripts/rename2tied.sh, \
     (d.hash), (d.name), (d.directory), (d.tied_to_file), (d.is_multi_file)"

pyro.bind_key = rename2tied, R, "pyro._rename2tied="

Depending on your needs, it can also make sense to call the script in an inserted_new event handler, or as a post-load command in a watch schedule. If you do that, you should probably add some checks that only apply changes for certain trackers, or when the tied-to file name has a certain format.

Versatile Move on Completion

The completion-path.sh script allows you to perform very versatile completion moving, based on logic defined in a bash script

Calling the script with -h prints full installation instructions including the rTorrent config snippet shown further below.

gh_raw="https://raw.githubusercontent.com/rtorrent-community/rtorrent-docs"
wget -O /tmp/completion-path.sh $gh_raw/master/docs/examples/completion-path.sh
bash /tmp/completion-path.sh -h

Read on to learn how this works when added to your rTorrent instance.

The target path is determined in the set_target_path function at the top of the script:

.. literalinclude:: examples/completion-path.sh
   :language: shell
   :start-after: set_target_path
   :end-before: } # set_target_path

Change it according to your preferences. If you don't assign a value to target, the item is not moved and remains in its default download location for later manual moving.

The is_movie helper function uses an inline Python script to check for typical names of movie releases using a regular expression:

.. literalinclude:: examples/completion-path.sh
   :language: python
   :start-after: python -
   :end-before: EOF

The is_movie check is done after the more reliable name checks.

For the script to be called and used as part of completion moving, these commands need to be added to your rtorrent.rc or config.d/move_on_completion.rc (see :ref:`drop-in-config` on how to get a config.d directory):

.. literalinclude:: examples/completion-path.sh
   :language: ini
   :start-after: # Completion moving
   :end-before: EOF

In the completion_move_handler method, you can change completion_move_verbose to just completion_move, if you don't want the move logged.

The completion_path method already passes the major item attributes to the script. You can add more if you need to, but then you also need to extend the list of names in arglist at the top of the bash script.

.. literalinclude:: examples/completion-path.sh
   :language: shell
   :start-after: List of attributes
   :end-before: #

If you run rTorrent-PS, which has the d.tracker_domain command, you can use that command to add a rule for trackers dedicated to one specific content type. Extend the last line of completion_path to read …displayname), (d.tracker_domain)", and add tracker_domain to the end of arglist. Then add a rule like this to the body of set_target_path:

# Move by tracker
test -n "$target" || case $(tr A-Z' ' a-z_ <<<"${tracker_domain:-NOT_SET}") in
    linuxtracker.org) target="Software" ;;
esac

Delayed Completion Handling

The following config snippet defines a new :term:`event.download.finished_delayed` trigger that works like the normal finished event, but only fires after a customizable delay.

One use-case for such a thing is to move a download from fast storage (RAM disk, SSD) to slow storage (HDD) for permanent seeding, after the initial rush in a swarm is over.

The following is the config you need to add to a config.d/event.download.finished_delayed.rc file (see :ref:`drop-in-config` on how to get a config.d directory), or else to your normal rtorrent.rc file:

.. literalinclude:: examples/event.download.finished_delayed.rc
   :language: ini

The last command adding a !debug handler can be left out, if you want less verbosity.

Set a Download to “Seed Only”

The d.seed_only command helps you to stop all download activity on an item. Select any unfinished item, press Ctrl-X, and enter d.seed_only= followed by . Then all files in that item are set to off, and any peers still sending you data are cut off. The data you have is still seeded, as long as the item is not stopped.

method.insert = d.seed_only, private|simple,\
    "f.multicall = *, f.priority.set=0 ;\
     d.update_priorities= ;\
     d.disconnect.seeders="

:term:`f.multicall` calls :term:`f.priority.set` on every file, :term:`d.update_priorities` makes these changes known, and finally :term:`d.disconnect.seeders` kicks any active seeders.

Scheduled Bandwidth Shaping

This example shows how to use :term:`schedule2` with absolute start times, to set the download rate depending on the wall clock time, at 10AM and 4PM. The result is a very simple form of bandwidth shaping, with full speed transfers enabled while you're at work (about 16 MiB/s in the example), and only very moderate bandwidth usage when you're at home.

schedule2 = throttle_full, 10:00:00, 24:00:00, ((throttle.global_down.max_rate.set_kb, 16000))
schedule2 = throttle_slow, 16:00:00, 24:00:00, ((throttle.global_down.max_rate.set_kb,  1000))

Use :term:`throttle.global_up.max_rate.set_kb` for setting the upload rate.

If you call these commands via XMLRPC from an outside script, you can implement more complex rules, e.g. throttling when other computers are visible on the network.

External scripts should also be used when saving money is the goal, in cases where you have to live with disadvantageous ISP plans with bandwidth caps. Run such a script very regularly (via cron), to enforce the bandwidth rules continuously.