Upgrading rTorrent to a new version

This page shows how to change the installed version of rTorrent and adapt its configuration. It also contains detailed change logs for differences between the versions.

1. Introduction

As with every software, the feature set of rTorrent grows with every version, and usually the changes are small and limited to certain features. See RtorrentVersions for an overview, including a list of release dates and the like. The rTorrent website also contains an index of the official changelogs.

In the 0.8.x line, versions up to 0.8.6 are pretty much compatible to each other. rTorrent 0.8.4 introduced a different kind of event handling using system.method.set_key, and group-wise ratio handling. Custom throttles were introduced in version 0.8.5.

From rTorrent 0.8.7 onwards, things change drastically, since most of the commands including configuration commands change their name for the sake of more consistency. rTorrent 0.8.7 has special modes that enable mappings for most commands from the old to the new name (the most part is likely unintentional, a/k/a a bug), for more see the section below.

The 0.9.x line introduced a new logging system, IPv4 filters for peers, and a dedicated thread for hashing to increase UI responsiveness, resulting in the current stable 0.9.2.

TODO more...

2. General Instructions

Before you perform any installations or configuration changes, follow these steps:

1. Stop any web interfaces.
2. Prevent any cron jobs related to rTorrent from running.
3. Stop rTorrent.

4. Make backups.

5. Make some more backups.

3. Specific Instructions

3.1. Version 0.8.6 to 0.8.7

TODO

1. Did you make your backups?

2. Due to presumably a bug in the core code, you need to add this to your ~/.rtorrent.rc:

   • session.name.set = "$cat=$system.hostname=,:,$system.pid="
     

   This also applies to version 0.8.8.

To support the command migration, there are new command line options -D (method.use_deprecated=0, else 1), -I (method.use_intermediate=0, else 1), and -K (method.use_intermediate=2, overrides -I). Use -D to ensure your scripts and web UIs will be compatible with future releases, -I to disable all additional mappings, and -K to keep internal mappings without exporting them. A full command definition diff is available, done with the -K -D switches active.

• To ease the migration from the old to the new syntax, here is a rtorrent.rc migration script that does the tedious work. Still, make sure that everything looks OK, and test your event handlers afterwards. Also, make backups, in case I didn't mention that before.

TODO Do a diff of listMethods against 0.8.6, and with the switch combinations.

TODO List unmapped commands, right now seems like:

• max_open_sockets ⇒ network.max_open_sockets
• max_open_files ⇒ network.max_open_files
• umask ⇒ system.umask.set
• d.save_session ⇒ d.save_full_session

The new version also splits the session data into three files per item, namely the original torrent, plus one with .libtorrent_resume added to the name (for libtorrent fast-resume), and a .torrent.rtorrent one for rTorrent data like custom values.

3.2. Version 0.8.7 to 0.8.8

TODO

1. Did you make your backups?

There are some new commands in 0.8.8.

New features:

• Another form of escaping nested commands using parentheses [1191]:

  • print = (convert.time,(system.time))
    schedule2 = test_print_2,2,2,((print,"current ",((convert.time,((system.time))))))
    

  Multiple parentheses need to be used with schedule2, to ensure the commands don't get evaluated at the time of defining the schedule. Nesting is limited to depth 3. The exact semantics are murky as usual, this seems to get rid of the trailing = and implicitely evaluate the commands.

• log.libtorrent was added [1192].

• leeching view added and bound to key '9'; 'active' is now bound to '0' [1193].

• ip_tables.insert_table, ip_tables.get, and ip_tables.add_address added [1193].

• ...

3.3. Version 0.8.8 to 0.8.9

TODO

1. Did you make your backups?

New features (up to rev. 1230):

• Background execution of external commands, append .bg to one of the existing execute commands (execute.throw.bg, execute.nothrow.bg, execute.raw.bg, execute.raw_nothrow.bg), the return value is always 0 [1230]. The release version leaves behind zombies when using this!

• Prioritization of leading/trailing chunks based on file type [833, 1230]:

  • # Enable the feature
    file.prioritize_toc.set=1
    
    # List of files it is applied to (assuming the above is set), applied to first
    # and last chunk repectively. The matching is done when a download is inserted.
    file.prioritize_toc.first.set = {*.avi,*.mp4,*.mkv,*.gz}
    file.prioritize_toc.last.set = {*.zip}
    

  The list of file extensions can be extended as shown above, and it has to be enabled with file.prioritize_toc.set. It can also be determined and queried on a per-file basis using these commands: f.prioritize_first, f.prioritize_first.enable, f.prioritize_first.disable, f.prioritize_last, f.prioritize_last.enable, and f.prioritize_last.disable.

• The first argument of f.multicall can be empty (no filter), a pattern, or a list thereof. Those will be matched against the file paths, and only files with at least one match will be considered. This is part of the file prioritization feature, but can of course be used independently. Note that the C++ code calls them regex, but they're not; they're very limited glob patterns only supporting *, nothing else (as of rev. 1230).

• Some statistics stuff, undocumented as we're used to, hints might be in rtorrent/doc/log_stats.plot.

Jari's changelog for 0.8.9:

• Added 'execute.*.bg' commands for non-blocking calls. Always returns 0.

• Added support for prioritizing first/last chunk of files matching specified patterns. Default:

    file.prioritize_toc.set=0
    file.prioritize_toc.first.set = {*.avi,*.mp4,*.mkv,*.gz}
    file.prioritize_toc.last.set  = {*.zip}

• Added 'method.rlookup' and 'method.rlookup.clear' commands for looking up the event handlers holding a specified key, and set views to support rlookup.
• Added 'd.timestamp.finished' that is set when a downloading torrent completes. For torrents that only seed it remains '0'.
• Added 'elapsed.{less,greater}' for checking the time elapsed since a time is less/greater, and it also returns false in all cases where the time is '0'.
• Moved the default value for 'system.files.max_size' to rtorrent, and set the default in libtorrent to ~0.
• Increased the default values for min/max_peers and max_uploads.
• Fixed a bug that would cause hash checking to block excessively in some cases.
• Fixed a bug when setting the pex flags.
• Fixed an issue where DHT's hashing function for TR1 unordered_map was casting unaligned size_t pointers.
• Fixed default session name.
• Added a missing inline that could cause linking errors.

3.4. Version 0.8.9 to 0.9.2

TODO

1. Did you make your backups?

New features:

• Only request from one tracker in a tier at one time.
• When in promiscuous mode, only do one additional request from a tracker. This should handle the cases of connecting to a completely new torrent before any other peers and to ensure we get enough peers for normal trackers, while keeping loads low.
• Only do scrape for one tracker per tier.
• Allow tilde for 'log.open_file' path.
• Added logging of options for created torrents.
• Differentiate scrape and normal requests in the tracker list.
• When 'throttle.max_*.global.*.set' commands are called they will automatically update the libtorrent settings, so it is no longer needed to set the throttle to force this update.
• Added 't.is_usable', 't.is_busy', 't.is_extra_tracker', 't.can_scrape', 't.activity_time_next', 't.activity_time_last', 't.success_time_next' and 't.failed_time_next'.
• Return hex instead of binary for 'd.chunks_seen'.
• Moved hash checking to a separate thread.
• Removed obsolete 'system.hash.read_ahead', 'system.hash.interval' and 'system.hash.max_tries'.

• Filter out unwanted peers using the IPv4 filter list:

  ipv4_filter.add_address = 1.0.0.0/2, unwanted
  ipv4_filter.load = ~/foo/rtorrent.ip.filter,unwanted
  print = "IPv4 filter list size data:",(to_kb,(ipv4_filter.size_data))," kb."
  
  xmlrpc localhost ipv4_filter.dump ""

• Improved logging of file and hashing events, specifically to improve user feedback when something goes wrong during hashing.
• Improved logging using the new logging facilities.
• Disown tracker requests when closing or deleting a torrent so that they complete.
• Added stricter checking of negative and '-0' integers for the non-stream-based parsers.
• Added 'd.chunks_seen', which is limited to 'Download::peers_accounted()' number of peers for optimization reasons.
• Added 'system.api_version', which will be incremented every time the API changes. (sans brainfarts)
• Bumped default max. file size to 128Gb.

• Rewritten logging facilities, will be phased in gradually. Usage:

  log.open_file = "tracker.log",(cat,/Users/rakshasa/tmp/tracker.log.,(system.pid))
  log.add_output = "tracker_debug", "tracker.log"

• Requesting from multiple trackers when necessary, e.g. if the first tracker does not respond within a few seconds or when more peers are needed.
• Automatically retrieve scrape information from all supported trackers.
• Do scrape on UDP tracker requests.
• Individual trackers now have their own timeouts, e.g. when trackers fail they will not have to wait all other trackers to be tried before reconnecting.
• Number of new peers received from a tracker the last time is used to decide on when to retry.

• Keep stopped/completed tracker requests active after TrackerController::disable() is called.

• Trace back SIGBUS errors to the download, file and offset.
• Added 'd.tracker.insert' command for adding trackers.
• Added 'd.{up,down}loads_{max,min}', and the keys 1/2/3/4 and !/@/#/$ control these.
• Added 'd.disconnect.seeders', 'd.accepting_seeders{,.enable,.disable}', 'd.wanted_chunks', 'd.timestamp.started' commands.
• Added 't.success_time_last' and 't.failed_time_last'.
• Fixed 'm_data.wanted_chunks() == 0' exception in Download::hash_check(...). #2664
• Fixed a potential issue causing high loads while waiting for main thread to exit polling. #2661
• Fixed an issue where SCGI m_task queue could overflow as the check was not working properly.
• Fixed 'd.directory.set' so it detects that torrent data being moved happens after setting the new directory.

3.5. Version 0.9.2 to ...

TODO

1. Did you make your backups?

Changesets worthy of a backport:

• HTTP wait: https://github.com/rakshasa/rtorrent/commit/b79dea94b2f537eda620ed48207369c076fcd11f

New features:

• ...