The syntax of XMLRPC commands changed with rTorrent version 0.8.9, and continues to change. Make sure that the versions of rTorrent and PyroScope you plan to install or update to are actually compatible. There are compensation mechanisms in both projects, but there are limits to those — scan the respective changelogs for breaking changes.
pyrocore 0.5+ will no longer support the old syntax, and thus not work with rTorrent 0.8.x versions. rTorrent 0.9.6 has the old commands disabled by default, and only a special command line switch will enable them again, for now. Also, this documentation uses the new syntax (mostly).
Since repairing broken files resulting from faulty updates usually is either a lot of work or simply impossible, always make a backup. Backups should be made when either PyroScope or rTorrent is changed to a new release version or git revision.
These steps should make a copy of pretty much anything important:
Copy your rTorrent session data and configuration (
rtorrentneeds to be running):rtxmlrpc -q session.save tar cvfz /tmp/instance-backup-$USER-$(date +'%Y-%m-%d').tgz \ $(echo $(rtxmlrpc session.path)/ | tr -s / /)*.torrent \ ~/rtorrent/*.rc ~/rtorrent/rtorrent.d ~/rtorrent/start
Backup your current PyroScope virtualenv and configuration (use
~/.localfor installations before
0.5.1):tar cvfz /tmp/pyroscope-backup-$USER-$(date +'%Y-%m-%d').tgz \ ~/.pyroscope/ ~/.local/pyroscope/
Depending on how you installed rTorrent, make a copy of the
libtorrent*.so*. Note that the rTorrent-PS build script installs into versioned directories, i.e. using that you don’t have to worry if changing to a new rTorrent version — the old one is still available, and you can switch back easily.
Updating the Software¶
Before adapting and extending your configuration to make use of new features, you first have to update the software itself. How to do that depends on the way you initially installed it, so follow one of the following sections, depending on whether you did a release installation or one from source.
How to Do a Release Version Software Update¶
Remember to read the migration instructions further below, and the changelog, BEFORE installing any new version.
Then to update an existing installation, use these commands
(but note the
0.5.1 update is different, see below):
cd ~/.local/pyroscope bin/pip install -U "pyrocore[templating]" ln -nfs $(egrep -l '(from.pyrocore.scripts|entry_point.*pyrocore.*console_scripts)' $PWD/bin/*) ~/bin
If you used
pip install --user -U pyrocore without creating a virtualenv, just repeat that command.
Now skip the next section describing a source installation upgrade, and go to the configuration update further below.
How to Update a Source Installation to the Newest Code¶
Then to update an existing installation, use this command:
Continue with any tasks regarding configuration changes from the next section.
Updating Your Configuration¶
After you installed a new version of the software,
you have to check for necessary changes to the default configuration,
after calling the
pyroadmin --create-config or the
Note that only the
*.default files (
and so on) will be overwritten, they are a literal copy of
the defaults packaged into the software, and are there for informational purposes only.
You can then use the
diff tool to check for the differences between
your current configuration and the new default one, and add any changes
you want to adopt.
Also note that sections of the configuration you leave out, and keys that you do not overwrite, are automatically taken from the defaults, which greatly simplifies any update. That is the reason why it is recommended to have a minimal configuration with just your customizations, in addition to the defaults.
and those contained in
~/.pyroscope/rtorrent.d, are a different story.
They change quite often, and since there is no merging of
*.rc files, the default ones are normally used.
You can still disable those default files one by one using the
in order to provide your own versions or simply disable certain features.
That is way better than switching altogether to
again for the reason updates become way more painless.
See the comments at the start of files in
rtorrent.d for details.
And remember to always read the changelog!
Migrating to Version 0.5.x¶
0.5.x release line adds a queue manager,
watching a directory tree for loading metafiles,
and removes support for ancient versions of Python and rTorrent.
More details on the contained changes can be found at GitHub releases and the changelog.
Install at least version
0.5.3, which has a few important fixes.
To upgrade your existing installation, follow these steps:
For people that run a source code installation, just use the
update-to-head.shscript as described in Installing from GitHub. When your old installation is still in
~/lib, you’ll be presented with the necessary commands to move to
~/lib/pyroscope/update-to-head.sh. Since all the documentation now points to
~/.localpaths, you should switch over.
For PyPI installs, just do a fresh install to the new location at
pyroadmin --create-configto update the
.defaultconfiguration examples, and create the new
In your rTorrent instance, update the start script (and save a copy of the old one before that).
You also MUST change the
importcommand in your
rtorrent.rcthat loads the PyroScope configuration include:
# 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
Read the rTorrent Queue Manager section if you plan to use item queueing and/or the tree watch feature; both are inactive by default and need to be enabled. You also need to add the new
pyro_watchdogschedule into your configuration, as shown in the Configuration Guide.
Remember to restart rTorrent after any configuration changes.
When you have a rather aged configuration, also consider switching to the new
set of configuration files as found in the
pimp-by-box project, that use
the new command names through-out and are thus way more future-proof.
There is an easy to use
make-rtorrent-config.sh script, see
rTorrent Configuration on how to use it.
At the same time, update the start script.
Note that these configuration files also work with a plain vanilla rTorrent version,
you do not need rTorrent-PS for them to work.
In any case, make a backup of your configuration and scripts,
as mentioned at the start of this chapter. After creating the new configuration,
merge in what’s missing from your old configuration, but migrate to the new syntax first.
For adding your custom settings, you can use your own files in the
Migrating to Version 0.6.1 (UNRELEASED)¶