# Welcome to the “rtorrent-ps” Manual!

rTorrent-PS is an extended rTorrent distribution with UI enhancements, colorization, some added features, and a comprehensive standard configuration.

See Overview for a more detailed description and a feature overview, and the rTorrent Handbook for general information regarding rTorrent, its configuration, and XMLRPC commands. The latter includes custom command extensions from rTorrent-PS.

Community Contacts and Solving Problems

To get in contact and share your experiences with other users of PyroScope, join the rtorrent-community channel rtorrent-ps on Gitter.

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.

## Overview

rTorrent-PS is a rTorrent distribution (not a fork of it), in form of a set of patches that improve the user experience and stability of official `rTorrent` releases, and releases new features more frequently. The Feature Overview below lists the major improvements and extensions. Also see the changelog for a timeline of applied changes, especially those since the last official release.

Note that rTorrent-PS is not the same as the PyroScope command line utilities (pyrocore), and doesn’t depend on them; the same is true the other way ‘round. It’s just that both unsurprisingly have synergies if used together, and some features do only work when both are present.

To get in contact and share your experiences with other users of PyroScope, join the rtorrent-community channel rtorrent-ps on Gitter.

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.

### Feature Overview

The main changes compared to vanilla rTorrent are these:

- self-contained installation into any location of your choosing, including your home directory, offering the ability to run several versions at once (in different client instances).
- rpath-linked to the major dependencies, so you can upgrade those independently from your OS distribution’s versions.
- extended command set:
  - sort views by more than one value, and set the sort direction for each of these.
  - (re-)bind keys in the downloads display to any command, e.g. change the built-in views.
  - record and display network traffic.
  - … and many more, see Command Extensions for details.
- interface additions:
  - easily customizable colors.
  - collapsed 1-line item display with a condensed information presentation.
  - almost fully customizable downloads display (selection of columns & adding new ones).
  - network bandwidth graph.
  - displaying the tracker domain for each item.
  - some more minor modifications to the download list view.

To get those features, you just need to either follow the build instructions, or download and install a package from Bintray — assuming one is available for your platform. See the Installation Guide on how to get your machine set up.

### Supported Platforms

The tested and officially supported platforms are Debian and any Debian-related Linux distro, specifically Ubuntu. Arch Linux is supported via contributors, and Fedora 26 has some limited support – anything else vanilla rTorrent runs on will likely work too, but in the end you have to fix any problems that might occur. If you want better support for your platform, provide a working derivative of `Dockerfile.Debian` and necessary modifications to `build.sh` via a PR.

Manual Turn-Key System Setup provides instructions to set up a working rTorrent-PS instance in combination with `pyrocore`, on Debian and most Debian-derived distros — i.e. a manual way to do parts of what pimp-my-box does automatically for you. Another option for automatic setup of a similar system is the one by chros73.

To help out other users, you can add your own content with configuration tricks and the like to the project’s wiki, and show to the world you’re awesome.

### Launching a Demo in Docker

To try out rTorrent-PS without any headaches, and if you have Docker 17.06+ installed, you can use the launch-rt-ps-demo.sh script to run an ephemeral instance in a container, like this:

    git clone "https://github.com/pyroscope/rtorrent-ps.git" ~/src/rtorrent-ps
    ~/src/rtorrent-ps/docker/launch-rt-ps-demo.sh

Detach from the process using `Ctrl-P Ctrl-Q`, and call `reset` to reset your terminal.

Reattach with `docker attach rt-ps-demo`, then enter `Ctrl-A r` to refresh the `tmux` screen.

If you want to do that directly via SSH from a remote machine, call `ssh -t YOU@HOST "docker attach rt-ps-demo"` and then refresh with `Ctrl-A r`.

Another use for such a container instance, besides taking a first look, is trying out experimental configurations, without any impact on your main installation.

Incidentally, that script is also a condensed version of the Manual Turn-Key System Setup instructions, and can be used as a blue-print for your own `Dockerfile`.

## Installation Guide

Note that this cannot be a Linux shell 101, so if the terminology and commands that follow are new for you, refer to the usual sources like The Debian Administrator’s Handbook, The Linux Command Line, and The Art of Command Line to get yourself acquainted.

### General Installation Options

See Build from Source on using the provided `build.sh` script, which will install rTorrent-PS into `~/.local/rtorrent/‹version›`.

The stable rTorrent version 0.9.6 is built by default, but 0.9.4 is also supported (but not tested anymore). And not all patches are applied equally, depending on whether they’re needed, or applicable at all.

After installation, make sure to read through the Setup & Configuration chapter in order to get the display-related changes set up correctly, since on many machines this requires some special configuration of your terminal.

Also take note of the pimp-my-box project that does it all (almost) automatically for Debian-type systems (and is the preferred way to install on those systems). The automation is done using Ansible, which implies you can easily admin several systems with it, and also maintain them – so it’s not a one-shot installation bash script creating a setup that can never be changed again.

Note

If you also install the PyroScope command line utilities, do not forget to activate the extended features available together with rTorrent-PS, as mentioned in the Configuration Guide. Starting with version 1.1, that activation is automatic.

### OS-Specific Installation Options

#### Installation Using Debian Packages

For a limited set of Debian-derived platforms, there are packages available that contain pre-compiled binaries (and only those, no configuration or init scripts). You can download and install such a package from Bintray — assuming one is available for your platform. The packages install the rTorrent-PS binary including some libraries into `/opt/rtorrent`.

Example on Ubuntu Xenial:

    version="0.9.6-PS-1.1~xenial_amd64"
    bintray="https://bintray.com/artifact/download/pyroscope"
    cd /tmp
    curl -Lko rt-ps.deb "$bintray/rtorrent-ps/rtorrent-ps_$version.deb"
    dpkg -i rt-ps.deb

After installation, you must provide a configuration file (typically located in `~/.rtorrent.rc` or `~/rtorrent/rtorrent.rc`). To start rTorrent-PS, always use the provided start script, which takes care of some technical details like settings the current working directory correctly. It also looks for the rTorrent binary at well-known places, including the `/opt` path the DEB package contains.

Note

You can safely install the package and test it out in parallel to an existing installation, just use the absolute path `/opt/rtorrent/bin/rtorrent` to start rTorrent. Your (session) data is in no way affected, as long as you normally run a 0.9.x version.

#### Installation on Arch Linux

There are now two options contributed by xsmile for installing on Arch via `pacman`.

1. The `pkg2pacman` command of The Build Script creates a package similar to the Debian one, embedding a tested version combination of dependencies. See Building the Debian Package for general instructions on building that variant, and use `pkg2pacman` instead of `pkg2deb`.

   Or you make your life easier and just use `./build.sh docker_arch` to build a pacman package, see Using Docker for Building Packages for more.

2. The “Arch User Repository” (AUR) PKGBUILDs maintained by @xsmile. These use a standard Arch build process, but include the usual rTorrent-PS patches.

   There is one package for `libtorrent-ps`, and one for `rtorrent-ps`, and both take their dependencies from the normal OS packages:

   - https://aur.archlinux.org/packages/libtorrent-ps/
   - https://aur.archlinux.org/packages/rtorrent-ps/

Before building binaries or packages yourself, install these packages on top of the `base` and `base-devel` groups (list is user-provided, report any problems):

    pacman -S \
        lsb-release subversion git time lsof tmux wget \
        python2-setuptools python2-virtualenv python2 python2-cffi \
        cppunit libxml2 libxslt

There is also the rtorrent-pyro-git AUR package. It is not the same as you get from using `build.sh`, and not recommended anymore by this project, given the new options above.

If you have problems with building or installing any of these packages, contact their maintainer.

#### Homebrew Tap for Mac OSX

See the homebrew-rtorrent-ps repository for instructions to build rTorrent-PS and related dependencies on Mac OSX.

Right now, it is not maintained by anyone.

### Manual Turn-Key System Setup

#### Introduction

The following shows installation instructions for a working rTorrent instance in combination with PyroScope from scratch, on Debian and most Debian-derived distros. Note that the pimp-my-box project does all this automatically for you, and is the tested and maintained way of installation — this page is just a reference of the core installation steps (if you run into problems, join the `freenode` IRC channel for help).

While the package names and the use of `apt-get` are somewhat dependent on Debian, the Preparatory Steps commands which are executed under `root` are similar for other distributions, and the compilation instructions should work as-is on practically any Linux and (F)BSD. These instructions are explicitly known to work on Debian Jessie + Stretch, and Ubuntu Xenial + Bionic.

The whole procedure takes 15 – 20 minutes, including full compilation from source. Subtract about 5 minutes if you install rTorrent via a package. This on a quad-core 3.3 GHz Xeon CPU with 32 GiB RAM, and assuming you are familiar with the procedure, or just blindly paste the command blocks that follow. Add plenty of reading time when doing your first setup, and it’s still under an hour.

Note

If you don’t understand a word of what follows, hit The Debian Administrator’s Handbook so then you do.

Non-packaged software is installed exclusively into your normal user account (home directory), i.e. this description works OK for non-root users as long as the required packages are installed before-hand. The default install location is `~/.local/rtorrent/«version»`, which means you can easily delete any installed software, and also run several versions concurrently.

For shared multi-user setups, this works fine also — compile and install to `/opt/rtorrent` using `./build.sh install`, then provide access to all users by calling `chmod -R go+rX /opt/rtorrent`. Perform the steps from PyroScope Installation onwards for each user repeatedly, so they get their own instance.

Important

Most of the command blocks further below can be copied & pasted wholesale into a terminal. Note that `bash` here documents (`... <<'EOF'`) MUST be pasted at once, up to and including the line having a single `EOF` on it.

Warning

If you have an existing `/usr/local` installation of rTorrent / libtorrent, it is very prudent to `make uninstall` that before compiling another version. Those might prevent successful compilation if your lookup paths somehow bring those versions to the front.

In the same vein, remove any packages of `libtorrent` and `rtorrent` you have on your machine. The build instructions on this page then ensure that it is no problem to have several versions concurrently on your machine. If anything goes wrong, you can easily reinstall the packages provided by your OS.

#### Preparatory Steps

##### Setting Up Locales

Commonly locales are already set up for you, but bare-bones installs often come without locale support, which rTorrent-PS absolutely requires due to its use of Unicode characters.

This ensures at least the common `en_US.UTF-8` one is available:

    apt-get install locales
    test "$LANG" = "en_US.UTF-8" \
        || { echo "en_US.UTF-8 UTF-8" >>/etc/locale.gen ; locale-gen --lang en_US.UTF-8; }

##### Installing Build Dependencies

You need to install a few required packages — and no, this is not optional in any way. These are the only steps that must be performed by the `root` user (i.e. in a root shell, or by writing `sudo` before the actual command):

    apt-get install sudo lsb-release build-essential pkg-config \
        subversion git time lsof binutils tmux curl wget \
        python-setuptools python-virtualenv python-dev \
        libssl-dev zlib1g-dev libncurses-dev libncursesw5-dev \
        libcppunit-dev autoconf automake libtool \
        libffi-dev libxml2-dev libxslt1-dev

Note that you can always show Debian’s current build dependencies for rTorrent using this command:

    echo $(apt-cache showsrc rtorrent libtorrent-dev | \
        grep Build-Depends: | cut -f2 -d: | tr ",)" " \\n" | cut -f1 -d"(")

On Fedora (26), use this (list is user-provided, report any problems):

    dnf install -y \
        redhat-lsb-core make autoconf automake libtool gcc gcc-c++ pkgconf-pkg-config \
        subversion git time lsof binutils tmux curl wget which \
        python-setuptools python-virtualenv python-devel python2-cffi \
        openssl-devel zlib-devel ncurses-devel cppunit-devel libxml2-devel libxslt-devel

For Arch, see the `pacman` command in Installation on Arch Linux.

##### Optional `root` Setup Steps

If you’re security-conscious, you can create a `rtorrent` user and do all the following setup steps under that new account. Doing that ensures that there is no way, on a properly maintained ∗nix system, for the build and setup scripts to break either your machine or your normal user account.

    groupadd rtorrent
    useradd -g rtorrent -G rtorrent,users -c "rTorrent client" \
            -s /bin/bash --create-home rtorrent
    chmod 750 ~rtorrent
    su - rtorrent -c "mkdir -p ~/bin"

#### rTorrent Installation

##### Install via Debian Packages

See Installation Using Debian Packages above for details. After adding the right package for your platform, skip the next section and continue with PyroScope Installation.

Note

During rTorrent instance setup, do not forget to change the value of `pyro.extended` to 1 so the extended features are actually accessible! Starting with version 1.1, that activation is automatic.

##### Build from Source

Get the build script via direct download or a `git clone`, and call it with the `all` parameter as shown below; the script will then download, build, and install all necessary components, storing temporary files in the current directory. You can pass the `clean_all` parameter to remove those temporary files later on, after everything works. Make sure you followed the Preparatory Steps in the section further up on this page.

Note

Be sure to select the version of rTorrent you want to compile, as determined by the settings at the start of the script. If you have no preference otherwise, stick to the default set in the script. Note that such a choice is sticky once you performed the `download` step, until you call `clean_all` again.

All installations go to `~/.local/rtorrent/«version»/`, and disturb neither any host setup nor another version of rTorrent you’ve installed the same way.

    # Run this in your NORMAL user account, or as ‘rtorrent’!
    mkdir -p ~/src/; cd $_
    git clone https://github.com/pyroscope/rtorrent-ps.git
    cd rtorrent-ps

    # Use this if you have the resources, adapt for the number of cores
    # and the amount of free memory you have available.
    export MAKE_OPTS="-j4"

    # Check the VERSION SELECTION at the top of the script, and edit as needed
    nice time ./build.sh all  # build 'deps', 'vanilla', and then 'extended'

Note that the unpatched version is still available as `rtorrent-vanilla`, and you can simply switch by changing the symlink in `~/bin`, or by calling either version with its full path. See the User’s Manual for more details on the changes applied.

The Build Script describes more use-cases like building in Docker, or an incremental update after a `git fetch` with new rTorrent-PS changes.

Note

If you use the configuration as outlined below, do not forget to change the value of `pyro.extended` to 1 in case you want to unlock the additional features of the extended version! Starting with version 1.1, that activation is automatic.

#### PyroScope Installation

The installation of `pyrocore` is done from source, see its manual for additional details.

    # Run this in your NORMAL user account, or as ‘rtorrent’!
    mkdir -p ~/bin ~/.local
    git clone "https://github.com/pyroscope/pyrocore.git" ~/.local/pyroscope

    # Pass "/usr/bin/python2", or whatever else fits, to the script as its
    # 1st argument, if the default of "/usr/bin/python" is not a suitable
    # version.
    ~/.local/pyroscope/update-to-head.sh

    # Check success
    exec $SHELL -l
    pyroadmin --version

The last call’s output should look similar to this:

    $ pyroadmin --version
    pyroadmin 0.6.1.dev20180601 on Python 2.7.13

#### rTorrent Instance Setup

To be able to use several different instances of rTorrent (e.g. a second one for experimental configuration changes), this setup doesn’t use `~/.rtorrent.rc` at all, but keeps everything in one place under the `~/rtorrent` directory. If you change the assignment to `RT_HOME`, you can place it anywhere you like, or create alternate instances with ease.

##### rTorrent Startup Script

First, create the instance’s directories and a start script:

    # Run this in your NORMAL user account, or as ‘rtorrent’!
    export RT_HOME="${RT_HOME:-$HOME/rtorrent}"
    mkdir -p $RT_HOME; cd $_
    mkdir -p .session log work done watch/{start,load,hdtv,cleaned}
    cp ~/.local/pyroscope/docs/examples/start.sh ./start
    chmod a+x ./start

Note that this script is needed on modern systems, else the special installation layout allowing concurrent use of several versions will not work as expected. So always call that script, and not `rtorrent` directly.

Tip

Safely storing downloads on a mounted device

In case your data resides on a mounted device (e.g. an external USB disk), add a check to the start script that it is actually present. To do that, create a `.mounted` file in the root of your device, and `exit` the start script if not found. For your convenience, the code for that is already there at the top of `start`, but commented out.

If you don’t check, that might lead to rehashing several terabytes of data, because rTorrent will mark the downloads stored on an absent device as broken (which they are without their data).

##### rTorrent Configuration

Next, a not-so-simple rtorrent.rc is created. It already provides everything needed to use all features of the PyroScope tools.

Note that built-in `pyrocore` settings are read from a provided include file, that in turn loads snippets from the `~/.pyroscope/rtorrent.d` directory. The same mechanism is used in the main `rtorrent.rc` file, so you can easily add your own customizations in new `rtorrent.d/*.rc` files.

To get all this set up for you, call this provided script:

    # Run this in your NORMAL user account, or as ‘rtorrent’!
    ~/.local/pyroscope/src/scripts/make-rtorrent-config.sh

After this, you should check at least the `rtorrent.d/20-host-var-settings.rc` file and adapt the values to your environment and preferences. Consider copying the commands for the settings you want to adapt to the `_rtlocal.rc` file – read on as to why.

The `_rtlocal.rc` file is the place for some simple custom settings, like additional resource limits or changing default values. The `make-rtorrent-config.sh` script does not copy that optional file. So create it yourself, and pick what you like from the example _rtlocal.rc, e.g. the logging configuration.

The script can be called again to get updates from GitHub, but will overwrite all standard configuration files with their new version. To safely customize configuration, provide your own version of standard files under a new name, and list the replaced files in the `rtorrent.d/.rcignore` file.

For anything special not covered by standard configuration, add your own additional files, or as mentioned use the `_rtlocal.rc` file.

Example for a `~/rtorrent/_rtlocal.rc` file:

    # Reduce retention period of uncompressed logs
    pyro.log_archival.days.set = 1

Note

In `rtorrent.rc`, change the value of `pyro.extended` to 1 so the extended rTorrent-PS features are actually accessible! Starting with version 1.1, that activation is automatic.

#### CLI Tools Configuration

This adds a minimal configuration, so that the defaults are taken from the installed software, which makes later updates a lot easier.

    # Run this in your NORMAL user account, or as ‘rtorrent’!
    pyroadmin --create-config

    cat >~/.pyroscope/config.ini <<EOF
    # PyroScope configuration file
    #
    # For details, see https://pyrocore.readthedocs.org/en/latest/setup.html
    #

    [GLOBAL]
    # Location of your rTorrent configuration
    rtorrent_rc = ~/rtorrent/rtorrent.rc

    # XMLRPC connection to rTorrent
    scgi_url = scgi://$HOME/rtorrent/.scgi_local

    [FORMATS]
    filelist = {{py:from pyrobase.osutil import shell_escape as quote}}{{#
        }}{{for i, x in looper(d.files)}}{{d.realpath | quote}}/{{x.path | quote}}{{#
            }}{{if i.next is not None}}{{chr(10)}}{{endif}}{{#
        }}{{endfor}}

    movehere = {{py:from pyrobase.osutil import shell_escape as quote}}{{#
        }}mv {{d.realpath | quote}} .

    # Formats for UI commands feedback
    tag_show = {{#}}Tags: {{ chr(32).join(d.tagged) }} [{{ d.name[:33] }}…]

    [SWEEP]
    # Settings for the "rtsweep" tool

    # Use the rules from the named [SWEEP_RULES_‹name›] sections
    default_rules = builtin, custom

    # Minimum amount of space that must be kept free (adds to the space request)
    space_min_free = 10g

    [SWEEP_RULES_CUSTOM]
    # Rules to manage disk space
    #
    # Rules are ordered by the given priority. You can disable built-in rules
    # found in the [SWEEP_RULES_BUILTIN] section by changing "default_rules"
    # in the [SWEEP] section. Use "rtsweep show" to list active rules.
    #
    # Default sort order for each rule is by "loaded" date (oldest first).
    # Note that active, prio 3, and ignored items are protected!
    #
    # If the active rules fail to provide enough space, as much of the oldest
    # items as needed are removed.

    # Seeded and bigger than 500M after 7 days, inactive and big items first
    seeded7d.prio   = 910
    seeded7d.sort   = active,-size
    seeded7d.filter = ratio=+1.2 size=+500m loaded=+5d

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

    # Public / open trackers
    PBT     = http://tracker.publicbt.com:80/announce
              udp://tracker.publicbt.com:80/announce
    PDT     = http://files2.publicdomaintorrents.com/bt/announce.php
    ArchOrg = http://bt1.archive.org:6969/announce
              http://bt2.archive.org:6969/announce
    OBT     = http://tracker.openbittorrent.com:80/announce
              udp://tracker.openbittorrent.com:80/announce
    Debian  = http://bttracker.debian.org:6969/announce
    Linux   = http://linuxtracker.org:2710/
    EOF

Read the pyrocore Configuration Guide for more information regarding this file. You can come back to customizing it later, your system will work fine with the above default.

#### First Start and Testing

##### tmux Configuration

We spruce up `tmux` a bit using a custom configuration, before we start it the first time. This also makes it more homey for long-time `screen` users:

    # Run this in your NORMAL user account, or as ‘rtorrent’!
    cp --no-clobber ~/.local/pyroscope/docs/examples/tmux.conf ~/.tmux.conf

##### Starting a tmux Session

You’re now ready to start your shiny new rTorrent-PS, so just do it:

    # Run this in your NORMAL user account, or as ‘rtorrent’!
    tmux -2u new -n rT-PS -s rtorrent "~/rtorrent/start; exec bash"

The `exec bash` keeps your `tmux` window open if `rtorrent` exits, which allows you to actually read any error messages in case it ends unexpectedly. If such an error occurs (e.g. about your terminal not providing enough colors), check out Setup & Configuration and the Trouble-Shooting Guide for a fix.

After that, test the XMLRPC connection by using this command in a new `tmux` window:

    # Open a new tmux terminal window by pressing "Ctrl-a" followed by "c", and then...
    rtxmlrpc system.time_usec

You can of course add more elaborate start scripts, like a cron watchdog, init.d scripts, or a systemd unit. Put the above `tmux` call into `ExecStart`, and use `… new -d …` to run a detached session – see the rTorrent wiki for detailed examples.

Continue with reading the pyrocore User’s Manual to get acquainted with the CLI tools, and Setup & Configuration for providing the necessary configuration regarding your terminal.

## Setup & Configuration

The main part of configuration regarding rTorrent-PS itself is already done, if you followed Manual Turn-Key System Setup or used pimp-my-box for it. If you used neither, look into what make-rtorrent-config.sh does (see also rTorrent Configuration), in order to get all the features described in the User’s Manual, which in large part rely on those standard configuration snippets.

This chapter contains hints on what you might need to do regarding the runtime environment and your system setup.

You can skip to the next chapter to learn about the special rTorrent-PS features and come back to this later, provided everything looks OK to you when you first started rTorrent-PS (especially that all special characters render correctly).

### Setting up Your Terminal Emulator

#### General Concerns

There are two major obstacles for a proper display of the extended canvas, and that is selecting the right font(s) and providing a terminal setup that supports 256 or more colors.

Read the following sections on how to solve any problems you might encounter within your environment.

#### Font Selection & Encoding Issues

Whatever font you use in your terminal profile, it has to support the characters used in the column headers and some of the displayed values, else you’re getting a degraded user experience. Also, your terminal must be set to use UTF-8, which nowadays usually is the default anyway.

On Linux, that means `LANG` should be something like `en_US.UTF-8`, and `LC_ALL` and `LC_CTYPE` should not be set at all! If you use a terminal multiplexer like most people do, and the display doesn’t look right, try `tmux -u` or `screen -U` to force UTF-8 mode.

Also make sure you have the `locales` package installed on Debian-type systems, and the `en_US.UTF-8` locale actually created. See Setting Up Locales for that.

The following command lets you easily check whether your font supports the most important characters and your terminal is configured correctly:

    PYTHONIOENCODING=utf-8 python -c 'print(u"\u22c5 \u22c5\u22c5 \u201d \u2019 \u266f \u2622 " \
        u"\u260d \u2318 \u2730 \u28ff \u26a1 \u262f \u2691 \u21ba \u2934 \u2935 \u2206 \u231a " \
        u"\u2240\u2207 \u2707 \u26a0\xa0\u25d4 \u26a1\xa0\u21af \xbf \u2a02 \u2716 \u21e3 \u21e1 " \
        u"\u2801 \u2809 \u280b \u281b \u281f \u283f \u287f \u28ff \u2639 \u2780 \u2781 \u2782 " \
        u"\u2783 \u2784 \u2785 \u2786 \u2787 \u2788 \u2789 \u25b9\xa0\u254d \u25aa \u26af \u2692 " \
        u"\u25cc \u21c5 \u21a1 \u219f \u229b \u267a ")'

In case you have unsolvable problems with only a few specific glyphs, see Defining Your Own Columns below on how to change them to ones working for you, or even switch them to plain ASCII.

#### Terminal Setup on Windows

To get full coverage of all Unicode glyphs used in the extended canvas, the steps below show you how to use font linking to make `Everson Mono` complement `DejaVu Sans Mono` when used in `PuTTY` version 0.70 or higher.

1. Download and install the DejaVu Sans Mono and Everson Mono fonts.

2. Next, add or edit a multi-string value for your preferred font under this Windows registry key:

       HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\FontLink\SystemLink

   To do that start `regedit` and go to that folder. Any key there names a font for which fallback fonts are registered. So add/edit the `DejaVu Sans Mono` key, and add fallback font references as its value.

   > - Right click `SystemLink` and select `New`, then `Multi String Value`.

   > - Use `DejaVu Sans Mono` as the key’s name.

   > - Double-click the new key, and enter this as the value:

   >       Everson Mono.ttf,EversonMono

3. After closing `regedit`, logout from Windows and back in again to activate the font link, but a full reboot is safer (hey, it’s Windows, you should be used to it).

4. Start `PuTTY` and select `Change settings` from the menu.

   > - In `Window › Appearance` select `DejaVu Sans Mono`.
   > - Set `UTF-8` in `Window / Translation`
   > - Under `Terminal` check `Use background colour to erase screen`.
   > - In `SSH › Data`, make sure to use `putty-256color` for the `terminal` setting.

5. Connect, and check the display.

Other fonts that were suggested are `Andale Mono`, and `GNU Unifont`. You have to try out yourself what looks good to you and works with your specific system and terminal emulator. Read more about fallback fonts on superuser.com.

> – based on feedback by @NoSubstitute, with help from superuser.com and MSDN

See also

Font linking on Windows and Using KiTTY instead of PuTTY

#### Terminal Setup on Linux

When you use `gnome-terminal`, everything should work out of the box, given you use the `start` script, which sets `TERM` and `LANG` correctly. Also always call `tmux` with the `-2u` options.

If you use `urxvt`, you have to provide fallback fonts as on Windows. Add the following to your `~/.Xresources`:

    URxvt*font: xft:DejaVu Sans Mono:style=regular:pixelsize=15,xft:Noto Sans Mono CJK JP:pixelsize=15,xft:FreeSerif

Note that 15pt is a threshold for the font size, below it `urxvt` thinks there’s not enough space to render the glyphs.

Generally, to cope with problems like this or find other fonts that suit you better, the `ttfdump` tool can help to check out fonts on the technical level. Another helper is the `gucharmap` GUI tool, that allows you to explore your installed fonts visually.

> – based on feedback by @ymvunjq

#### Supporting 256 or More Colors

Having 256 colors available means you can select very dark shades of grey, and that can be used for subtle even / odd line backgrounds in the collapsed canvas of rTorrent-PS.

To enable 256 colors, your terminal must obviously be able to support them at all (i.e. have a `xterm-256color` terminfo entry, or similar). But even if that is the case, you often need to give a little nudge to the terminal multiplexers; namely start `tmux` with the `-2` switch (that forces 256 color mode), or for `screen` start it with the terminal already set to 256 color mode so it can sense the underlying terminal supports them, i.e. use this in your startup script:

    if [ "$TERM" = "${TERM%-256color}" ]; then
        export TERM="$TERM-256color"
    fi
    tmux ...

Then, within the terminal multiplexer’s environment, you must again ensure the terminal is set to a 256 color terminfo entry. See the .tmux.conf by @chros73 for possible solutions for any tmux-related problems.

The reward for jumping through all those hoops is that you can then use color gradients for ratio coloring, and much more appropriate pallid color shades for backgrounds.

#### Showing a Terminal’s Palette

The term-256color.py script can help you with showing the colors your terminal supports, an example output using Gnome’s terminal looks like the following...

Output of term-256-color.py

### Trouble-Shooting Guide

#### Reporting Problems

If you have any trouble during rTorrent-PS installation and configuration, or using any of the commands from the documentation, join the rtorrent-community channel rtorrent-ps on Gitter. You can also ask questions on platforms like Reddit or Stack Exchange.

If you are sure there is a bug, then open an issue on GitHub. Report any problems that are clearly rooted in the rTorrent core to the upstream issue tracker.

Make sure that nobody else reported the same problem before you, there is a search box you can use (after the Filters button). Please note that the GitHub issue tracker is not a support platform, use the Gitter channel or Reddit for any questions, as mentioned above.

And ESR’s golden oldie How To Ask Questions The Smart Way is still a most valuable resource, too.

Note

Please describe your problem clearly, and provide any pertinent information. What are the version numbers of software and OS? What did you do? What was the unexpected result? If things worked and ‘suddenly’ broke, what did you change?

In the chat, don’t ask if somebody is there, just describe your problem. Eventually, someone will notice you – people do live in different time zones than you.

Put up any logs on 0bin or any other pastebin service, and make sure you removed any personal information you don’t want to be publically known. Copy the pastebin link into the chat window.

The following helps with querying your system environment, e.g. the version of Python and your OS.

#### Providing Diagnostic Information

##### Python Diagnostics

Execute the following command to be able to provide some information on your Python installation:

    deactivate 2>/dev/null; /usr/bin/virtualenv --version; python <<'.'
    import sys, os, time, pprint
    pprint.pprint(dict(
        version=sys.version,
        prefix=sys.prefix,
        os_uc_names=os.path.supports_unicode_filenames,
        enc_def=sys.getdefaultencoding(),
        maxuchr=sys.maxunicode,
        enc_fs=sys.getfilesystemencoding(),
        tz=time.tzname,
        lang=os.getenv("LANG"),
        term=os.getenv("TERM"),
        sh=os.getenv("SHELL"),
    ))
    .

If `enc_fs` is not `UTF-8`, then call `dpkg-reconfigure locales` (on Debian type systems) and choose a proper locale (you might also need `locale-gen en_US.UTF-8`), and make sure `LANG` is set to `en_US.UTF-8` (or another locale with UTF-8 encoding).

##### OS Diagnostics

Similarly, execute this in a shell prompt:

    uname -a; echo $(lsb_release -as 2>/dev/null); grep name /proc/cpuinfo | uniq -c; \
    free -m | head -n2; uptime; \
    strings $(which rtorrent) | grep "client version"; \
    ldd $(which rtorrent) | egrep "lib(torrent|curses|curl|xmlrpc.so|cares|ssl|crypto)"; \
    ps auxw | egrep "USER|/rtorrent" | grep -v grep

#### Common Problems & Solutions

Please open an issue on GitHub if you think that you have a problem that happens a lot, or you know several other people have the same problem, and it’s not already mentioned below.

##### Error in option file: …/05-rt-ps-columns.rc:…: Invalid key

You combined a brand-new pimp-my-box configuration with an older version of rTorrent-PS.

Solution ♯1 (preferred)

Update to a recent build rTorrent-PS.

Also make sure your `~/rtorrent/rtorrent.rc` is the newest one with the line…

    method.insert = pyro.extended, const|value, (system.has, rtorrent-ps)

This auto-detects the presence of rTorrent-PS, but only works with builds from June 2018 onwards.

Solution ♯2

Replace this line in `~/rtorrent/rtorrent.rc`…

    method.insert = pyro.extended, const|value, (system.has, rtorrent-ps)

with that one…

    method.insert = pyro.extended, const|value, 1

##### Startup Failure: ‘your terminal only supports 8 colors’

See Setting up Your Terminal Emulator for detailed help on proper terminal setup.

If all else fails or you’re in a rush, you can switch to the 8-color theme by calling the `echo` command as shown and then start rTorrent-PS again:

    echo default-8 >~/.pyroscope/color-schemes/.current
    ~/rtorrent/start

If you don’t use the standard configuration (where theme support comes from), then add the `ui.color.*` commands from this configuration snippet to `rtorrent.rc`, which does the same thing.

##### Startup Failure: ‘libxmlrpc_*.so cannot open shared object file’

On newer systems, `RPATH` is replaced by `RUNPATH` with consequences regarding the search path for transitive library dependencies (like that of `libxmlrpc` to the other `libxmlrpc_*` libraries). In the end, those transitive dependencies cannot be resolved without some extra config.

The solution is to use the provided start script, which explicitly sets `LD_LIBRARY_PATH` from any `RPATH` or `RUNPATH` found in the executable. Or if you use a systemd unit, use an `Environment` directive to set the library path, e.g. `Environment=LD_LIBRARY_PATH=/opt/rtorrent/lib`.

## User’s Manual

This chapter describes the additional features in rTorrent-PS, and other differences to a vanilla rTorrent build.

### Additional Features

Using the right default configuration (more on that below), you will get the following additional features in your rTorrent-PS installation:

1. The `t` key is bound to a `trackers` view that shows all items sorted by tracker and then by name.
2. The `!` key is bound to a `messages` view, listing all items that currently have a non-empty message, sorted in order of the message text.
3. The `^` key is bound to the `rtcontrol` search result view, so you can easily return to your last search.
4. The `?` key is bound to the `indemand` view, which sorts all open items by their activity, with the most recently active on top.
5. The `%` key is bound to the `ratio` view, which sorts all open items by their ratio (descending).
6. The `°` key is bound to the `uploaded` view, which sorts all open items by their total upload amount (descending).
7. The `"` key is bound to the `datasize` view, which sorts all open items by the size of their content data (descending).
8. Add even more views, see Additional Views for details.
9. `Page ↑` and `Page ↓` scroll by 50 items at a time (or whatever other value `ui.focus.page_size` has).
10. `Home` / `End` jump to the first / last item in the current view.
11. `Ctrl-F` opens a prompt where you can enter a search term, and `Shift-F` or `F3` jump to the next hit for that term. If nothing matches, a message is shown on the console.
12. The `~` key rotates through all available color themes, or a user-selected subset. See Color Themes for details.
13. The `<` and `>` keys rotate through all added category views (`pyro.category.add=‹name›`), with filtering based on the ruTorrent label (`custom_1=‹name›`). See Category Views for details.
14. `|` reapplies the category filter and thus updates the current category view.
15. The `u` key shows the uptime and some other essential data of your rTorrent instance.
16. `F2` shows some important help resources (web links) in the console log.
17. `*` toggles between the collapsed (as described on Extended Canvas Explained) and the expanded display of the current view.
18. `/` toggles the visibility of ‘sacrificial’ columns – normally, they’re only hidden when the terminal width gets too small.
19. The `active` view is changed to include all incomplete items regardless of whether they have any traffic, and then groups the list into complete, incomplete, and queued items, in that order. Within each group, they’re sorted by download and then upload speed.
20. Some canvas v2 columns are added in the pimp-my-box configuration – the selected throttle (⋉), a download’s chunk size (≣), and the expected time of arrival (⟲ ◥◤) on the active and leeching displays only. The visibility of the chunk size column can be toggled using the `_` key.
21. The commands `s=«keyword»`, `t=«tracker_alias»`, and `f=«filter_condition»` are pre-defined for searching using a Ctrl-X prompt.
22. The `.` key toggles the membership in the `tagged` view for the item in focus, `:` shows the `tagged` view, and `T` clears that view (i.e. removes the tagged state on all items). This can be very useful to manually select a few items and then run `rtcontrol` on them, or alternatively use `--to-view tagged` to populate the `tagged` view, then deselect some items interactively with the `.` key, and finally mass-control the rest. See Additional Views for details.
23. You can use the `purge=` and `cull=` commands (on a Ctrl-X prompt) for deleting the current item and its (incomplete) data.
24. `Ctrl-g` shows the tags of an item (as managed by `rtcontrol`); `tag.add=‹tag›` and `tag.rm=‹tag›` can be used to change the set of tags, both also show the new set of tags after changing them.
25. Time-stamped log files with rotation, archival (compression), and pruning – with a setting for the number of days to keep logs in uncompressed form, or at all.
26. Trackers are scraped regularly (active items relatively often, inactive items including closed ones seldomly), so that the display of downloads / seeders / leechers is not totally outdated. The `&` key can be used to manually scrape the item in focus.
27. A watchdog for the `pyrotorque` daemon process (checks every 5 minutes, and starts it when not running if the ~/.pyroscope/run/pyrotorque file exists).

With regards to using the ‘right’ configuration to get the above, you need the `*.rc.default` files in the `~/.pyroscope/rtorrent.d` directory provided by pyrocore. Standard Configuration Explained has details on these. Some more features are defined by the pimp-my-box configuration templates.

To get there, perform the Manual Turn-Key System Setup as described in this manual, or use the pimp-my-box project for an automatic remote installation. The instructions in the Extending your ‘.rtorrent.rc’ section of the pyrocore manual only cover half of it, and you might miss some described features.

### Extended Canvas Explained

The following is an explanation of the collapsed display of rTorrent-PS (canvas v2).

Extended Canvas Screenshot

In case your screen looks broken compared to this, see Setting up Your Terminal Emulator for necessary pre-conditions and settings regarding your terminal emulator application and operating system.

In older builds, you need to remember to press the `*` key while showing a view, or change the state of new views after adding them (by calling the view.collapsed.toggle command), else you won’t ever see it.

The following is an overview of the default columns, and what the values and icons in them mean.

A `⍰` after the column title indicates a ‘sacrificial’ column, which disappear when the display gets too narrow to display all the columns. When even that does not provide enough space, columns are omitted beginning on the right side (Name is always included). Sacrificial columns can also be toggled using the `/` key – note they’re toggled as a whole group, so other dynamic states like the `≣` column toggle are ignored.

Columns marked `⪮` are provided by a pimp-my-box configuration include (i.e. loaded from `~/rtorrent/rtorrent.d/`), and ones carrying `✶` by `pyrocore` (from `~/.pyroscope/rtorrent.d/`). All others are built-in.

❢
  Message or alert indicator (♺ = Tracker cycle complete, i.e. “Tried all trackers”; ʘ = item’s data path does not exist (needs support by a cron job); ⚡ = establishing connection; ↯ = data transfer problem; ◔ = timeout; ¿? = unknown torrent / info hash; ⨂ = authorization problem (possibly temporary); ⋫ = tracker downtime; ☡ = DNS problems; ⚠ = other)
☢
  Item state (▹ = started, ╍ = paused, ▪ = stopped)
☍ `⍰`
  Tied item? [⚯]
⌘ `⍰`
  Command lock-out? (⚒ = heed commands, ◌ = ignore commands)
↺ `⍰`
  Number of completions from last scrape info
⤴ `⍰`
  Number of seeds from last scrape info
⤵ `⍰`
  Number of leeches from last scrape info
↕ `⍰`
  Transfer direction indicator [⇅ ↡ ↟]
℞
  Number of connected peers
∆⋮ ⟲
  Upload rate, or when inactive, time the download took (only after completion).
∇⋮ ◷
  Approximate time since completion (units are «”’hdwmy» from seconds to years); for incomplete items the download rate or, if there’s no traffic, the time since the item was started or loaded
⟲ ◥◤ `⍰ ⪮`
  Expected time of arrival (only on the active and leeching views)
⋉ `⍰ ⪮`
  Throttle selected for this item (∞ is the special `NULL` throttle; ⓪…⑨ for ruTorrent‘s `thr_0…9` channels)
Σ⇈ `⍰`
  Total sum of uploaded data
⣿
  Completion status (✔ = done; else up to 8 dots [⣿] and ❚, i.e. progress in 10% steps); the old `ui.style.progress.set` command is deprecated, see Defining Your Own Columns for the new way to get a different set of glyphs or an ASCII version
☯
  Ratio (☹ plus color indication for < 1, ➀ — ➉ : >= the number, ⊛ : >= 11); the old `ui.style.ratio.set` command is deprecated, see Defining Your Own Columns for the new way to get a different set of number glyphs or an ASCII version
☯ ‰ `⍰ ✶`
  Detailed ratio, in promille and as a number (only on the ratio view).
⛁
  Data size
≣ `⍰ ⪮`
  Chunk size – this column can be toggled on / off using the `_` key
◷ ↑↓ `✶`
  Time of last data transfer (only on the last_xfer view).
◷ ↺⤴⤵ `✶`
  Time of last tracker scrape (only on the trackers view).
Domain `⍰ ✶`
  15 characters of the unmapped tracker domain name (only on the trackers view).
◷ ℞ `✶`
  Time a peer was last connected, or the number of peers connected right now (only on the indemand view).
✰
  Priority (✖ = off, ⇣ = low, nothing for normal, ⇡ = high)
⚑
  A ⚑ indicates this item is on the `tagged` view
Name
  Name of the download item – either the name contained in the metafile, or else the value of the `displayname` custom field when set on an item
Tracker
  Domain of the first HTTP tracker with seeds or leeches, or else the first one altogether – note that you can define nicer aliases using the trackers.alias.set_key command in your configuration

For the various time displays to work, you need the pyrocore standard configuration for rtorrent.rc.

The scrape info and peer numbers are exact only for values below 100, else they indicate the order of magnitude using roman numerals (c = 10², m = 10³, X = 10⁴, C = 10⁵, M = 10⁶). For up-to-date scrape info, you need the Tracker Auto-Scraping configuration from pyrocore.

### Command Extensions

The following new commands are available. Note that the links point to the Commands Reference chapter in the rTorrent Handbook.

math.* Commands

math.add math.avg math.cnt math.div | math.max math.med math.min | math.mod math.mul math.sub

string.* Commands

string.contains string.contains_i string.endswith string.equals string.join string.len | string.lpad string.lstrip string.map string.replace string.rpad string.rstrip | string.shorten string.split string.startswith string.strip string.substr

convert.* Commands

convert.human_size | convert.magnitude | convert.time_delta

system.* Commands

system.client_version.as_value system.env system.has | system.has.list system.has.private_methods | system.has.public_methods system.random

d.* Commands

d.custom.as_value d.custom.erase d.custom.if_z d.custom.items d.custom.keys | d.custom.set_if_z d.custom.toggle d.is_meta d.message.alert d.multicall.filtered | d.tracker_alias d.tracker_domain d.tracker_scrape.complete d.tracker_scrape.downloaded d.tracker_scrape.incomplete

network.* Commands

network.history.auto_scale network.history.depth | network.history.depth.set network.history.refresh | network.history.sample

ui.* Commands

ui.bind_key ui.bind_key.verbose ui.canvas_color ui.canvas_color.set ui.color.*.index ui.color.*.set ui.color.alarm…title ui.column.hidden.list ui.column.hide | ui.column.is_hidden ui.column.render ui.column.sacrificed ui.column.sacrificial.list ui.column.show ui.column.spec ui.current_view ui.find.next | ui.find.term ui.focus.end ui.focus.home ui.focus.page_size ui.focus.pgdn ui.focus.pgup ui.style.progress ui.style.ratio

Other Commands

array.at close_low_diskspace.normal compare do | import.return log.messages throttle.names trackers.alias.items | trackers.alias.set_key value view.collapsed.toggle

## Tips & How-Tos

### Checking Details of the Standard Configuration

Not every detail of the standard configuration can be documented in this manual, because at some point it would basically duplicate the `*.rc` files in English, and also run the risk of being out of date (i.e. wrong) very fast.

To understand every nook and cranny of the features added by the config sets that get installed if you follow Manual Turn-Key System Setup, look into the `*.rc` files and specifically read the comments in them.

The `pyrocore` files are in the `~/.pyroscope/rtorrent.d` directory, and `pimp-my-box` ones in `~/rtorrent/rtorrent.d`.

Remember that `.rcignore` files in those directories allow to selectively disable parts of the standard configuration, like so:

    echo >>~/rtorrent/rtorrent.d/.rcignore "disable-control-q.rc"

For finding specifics on added commands or paths and such, `grep` is your friend, as in this example:

    $ grep -C1 import.rc ~/.pyroscope/rtorrent.d/*.rc.default ~/rtorrent/rtorrent.d/*.rc ~/rtorrent/*rt*rc
    rtorrent/rtorrent.rc-execute2 = (cat,(pyro.bin_dir),pyroadmin),-q,--create-import,(cat,(cfg.basedir),"rtorrent.d/*.rc")
    rtorrent/rtorrent.rc:import = (cat,(cfg.basedir),"rtorrent.d/.import.rc")
    rtorrent/rtorrent.rc-

### Validate Self-Signed Certs

The following helps in case you want to use trackers with `https` announce URLs that still use self-signed certificates, instead of Let’s Encrypt like they should. Unless you disable certificate checks in the rTorrent configuration, you must add such certificates to your the system to make them valid.

This script does that via an easy command call, just pass it the tracker domain or URL:

    cat >/usr/local/sbin/load-domain-certificate <<'EOF'
    #! /bin/bash
    if test -z "$1"; then
        echo "usage: $0 <domainname_or_url>"
        exit 1
    fi
    DOMAINNAME=$(sed -re 's%^(https://)?([^/]+)(.*)$%\2%' <<<$1)
    set -x
    openssl s_client -servername ${DOMAINNAME} -connect ${DOMAINNAME}:443 </dev/null | tee /tmp/${DOMAINNAME}.crt
    openssl x509 -inform PEM -in /tmp/${DOMAINNAME}.crt -text -out /usr/share/ca-certificates/${DOMAINNAME}.crt
    grep ${DOMAINNAME}.crt /etc/ca-certificates.conf >/dev/null || echo ${DOMAINNAME}.crt >>/etc/ca-certificates.conf
    update-ca-certificates
    ls -l /etc/ssl/certs | grep ${DOMAINNAME}
    EOF
    chmod a+x /usr/local/sbin/load-domain-certificate

## Advanced Customization

This chapter helps you to personalize your rTorrent experience, specifically regarding the ncurses terminal user interface. It provides some background on the standard configuration, and how you can tweak it further according to your preferences.

### Color Scheme Configuration

This section describes how you can change all the colors in rTorrent-PS to your liking. Note that there are existing color schemes provided by the pyrocore configuration, and you can rotate through them using the `~` key thanks to rtorrent.d/theming.rc.

You can copy one of the provided color scheme `*.rc.default` files in `~/.pyroscope/color-schemes/` to a new `‹mytheme›.rc` file. Details about how to specify colors and so on are in the sub-sections that follow.

Color Configuration Details

- Working With Color Schemes
- Adding Your Own Color Schemes

And here are some visuals of the default schemes…

#### Working With Color Schemes

If your terminal works as intended, you now might want to find you own color theme. The easiest way is to use a second shell and rtxmlrpc. Try out some colors, and add the combinations you like to your `~/.rtorrent.rc`.

    # For people liking candy stores...
    rtxmlrpc ui.color.title.set "bold magenta on bright cyan"

You can use the following code in a terminal to dump a full color scheme from the running client:

    for i in $(rtxmlrpc system.listMethods | egrep '^ui.color.[^.]+$'); do
        echo $i = $(rtxmlrpc -r $i | tr "'" '"') ;
    done

#### Adding Your Own Color Schemes

Color schemes are lists of `ui.color.‹color name›.set` commands in your configuration, or in a `*.rc[.default]` file in the `~/.pyroscope/color-schemes/` directory. If you want to use scheme rotation at all (via the `~` key), put your own schemes into extra `color-schemes/*.rc` files and not the main configuration.

The set of color names is predetermined and refers to the meaning of the color, i.e. where it is used on the canvas. `footer` and `alarm` are obvious examples.

Here’s a configuration example showing all the commands and their defaults:

    # UI/VIEW: Colors
    ui.color.alarm.set="bold white on red"
    ui.color.complete.set="bright green"
    ui.color.even.set=""
    ui.color.focus.set="reverse"
    ui.color.footer.set="bold bright cyan on blue"
    ui.color.incomplete.set="yellow"
    ui.color.info.set="white"
    ui.color.label.set="gray"
    ui.color.leeching.set="bold bright yellow"
    ui.color.odd.set=""
    ui.color.progress0.set="red"
    ui.color.progress20.set="bold bright red"
    ui.color.progress40.set="bold bright magenta"
    ui.color.progress60.set="yellow"
    ui.color.progress80.set="bold bright yellow"
    ui.color.progress100.set="green"
    ui.color.progress120.set="bold bright green"
    ui.color.queued.set="magenta"
    ui.color.seeding.set="bold bright green"
    ui.color.stopped.set="blue"
    ui.color.title.set="bold bright white on blue"

See the ui.color.* command reference for details on these and related commands.

The following color settings work better than the default ones in a 256 color terminal (gnome-terminal), for me at least. Your mileage (color table) may vary. Having 256 colors means you have very dark shades of grey, and that is used here to set the even / odd backgrounds.

    ui.color.complete.set=41
    ui.color.stopped.set=33

    ui.color.footer.set="bright cyan on 20"
    ui.color.even.set="on 234"
    ui.color.odd.set="on 232"

    ui.color.progress0.set=196
    ui.color.progress20.set=202
    ui.color.progress40.set=213
    ui.color.progress60.set=214
    ui.color.progress80.set=226
    ui.color.progress100.set=41
    ui.color.progress120.set="bold bright green"

Note that you might need to enable support for 256 colors in your terminal, see Supporting 256 or More Colors for a description. In a nutshell, you need to install the `ncurses-term` package if you don’t have it already, and also add these commands to your rTorrent start script:

    if [ "$TERM" = "${TERM%-256color}" ]; then
        export TERM="$TERM-256color"
    fi

### Customizing the Display Layout

Canvas v2 Topics

- Canvas v2 Overview
- Inspecting Your Display
- Column Layout Definitions
- Defining Your Own Columns
- Disabling Columns
- Adding Traffic Graphs

#### Canvas v2 Overview

The main display with the downloads list is flexible and can be configured to your will, in rTorrent-PS 1.1 and up. This is also known as canvas v2.

Use the following rtxmlrpc command to check if you have a version that can do this:

    $ rtxmlrpc "system.has=,canvas_v2"
    1
    # The '1' means you have canvas v2 on board;
    # a '0' or "Method 'system.has' not defined" means you don't.

The only fixed parts are the position indicator at the very left of the display, and the combined name / tracker column on the right. The latter takes all the space left by other columns.

#### Inspecting Your Display

To list the columns you have in your setup, call rtxmlrpc like so:

    $ rtxmlrpc method.get=,ui.column.render | sed -re 's/ /␣/g' | sort
    100:3C95/2:❢␣␣
    110:2C92/2:☢␣
    120:?2:☍␣
    130:?2:⌘␣
    400:?3C23/3:␣↺␣
    410:?3C24/3:␣⤴␣
    420:?3C14/3:␣⤵␣
    500:?2:⚡␣
    510:3C28/3:℞␣␣
    520:6C96/6:∆⋮␣⌛␣␣
    530:6C90/6:∇⋮␣⌚␣␣
    800:3:⋉␣
    900:?5C24/3C21/2:␣Σ⇈␣␣
    910:2C94/2:⣿␣
    920:3C93/3:☯␣␣
    930:5C15/3C21/2:␣✇␣␣␣
    970:2C91/2:✰␣
    980:2C16/2:⚑␣

The important thing here are the numbers in front, which define the sort order of columns from left to right. They also allow to address a specific column, which becomes important in a moment.

All these are built-in defaults, except the throttle indicator `⋉` with index 800, which is defined in ~/rtorrent/rtorrent.d/05-rt-ps-columns-v2.rc.include of pimp-my-box.

Important

You MUST update your pimp-my-box configuration if you used that to set up your system. Otherwise you’ll get duplicate columns.

To show the full column definitions with their code, call pyroadmin:

    $ pyroadmin --dump-rc | grep -A1 ui.column.render | egrep '^(method.set_key|    )'
    method.set_key = ui.column.render, "100:3C95/2:❢  ", \
        ((array.at, {"  ", "♺ ", "⚠ ", "◔ ", "⚡ ", "↯ ", "¿?", "⨂ "}, ((d.message.alert)) ))
    method.set_key = ui.column.render, "110:2C92/2:☢ ", \
        ((string.map, ((cat, ((d.is_open)), ((d.is_active)) )), {00, "▪ "}, …, {11, "▹ "}))
    …
    method.set_key = ui.column.render, "980:2C16/2:⚑ ", \
        ((array.at, {"  ", "⚑ "}, ((d.views.has, tagged)) ))

#### Column Layout Definitions

The keys of the `ui.column.render` multi-command must follow a defined format, namely `‹index›:〈?〉‹width›〈‹color definition›〉:‹title›`. There are three fields, separated by colons. The parts in `〈…〉` are optional.

`‹index›` was already mentioned, used for sorting and addressing columns.

The second field can start with a `?` to tag this column as ‘sacrificial’, i.e. optional in the face of too narrow terminals. `‹width›` is a column’s width in characters. The `‹color definition›` determines what terminal attributes are used to render these characters, and is a sequence of `C‹color index›/‹length›` elements.

Finally, `‹title›` is used for the column’s heading. Make sure to end it with a space to leave room for wide Unicode glyphs, and always make it as long as the column width.

To get a color index table, try this command:

    rtxmlrpc system.has.private_methods \
        | egrep '^ui.color.*index$' \
        | xargs -I+ rtxmlrpc -i 'print="+ = ",(+)'

Since the `ui.color.*index` commands are private, the output must go to the rTorrent console. This is what you’ll see (timestamps removed):

    ui.color.alarm.index = 22
    ui.color.complete.index = 23
    ui.color.custom1.index = 1
    ui.color.custom2.index = 2
    ui.color.custom3.index = 3
    ui.color.custom4.index = 4
    ui.color.custom5.index = 5
    ui.color.custom6.index = 6
    ui.color.custom7.index = 7
    ui.color.custom8.index = 8
    ui.color.custom9.index = 9
    ui.color.even.index = 30
    ui.color.focus.index = 19
    ui.color.footer.index = 18
    ui.color.incomplete.index = 27
    ui.color.info.index = 21
    ui.color.label.index = 20
    ui.color.leeching.index = 28
    ui.color.odd.index = 29
    ui.color.progress0.index = 10
    ui.color.progress20.index = 11
    ui.color.progress40.index = 12
    ui.color.progress60.index = 13
    ui.color.progress80.index = 14
    ui.color.progress100.index = 15
    ui.color.progress120.index = 16
    ui.color.queued.index = 26
    ui.color.seeding.index = 24
    ui.color.stopped.index = 25
    ui.color.title.index = 17

There are also columns with dynamic color schemes, using a color index ≥ 90, which map to a ‘normal’ color index depending on an item’s attributes. An example is `3C95/2` for the alert column, which changes to red (`ui.color.alarm`) if there is an active alert.

This is a list of the dynamic color schemes:

> - 90: `DOWN_TIME` – Download (∇ leeching) or time display (⌚ info + seeding/incomplete)
> - 91: `PRIO` – A color for ✰, depending on `d.priority`: progress0, progress60, info, progress120
> - 92: `STATE` – A color for ☢, depending on `d.is_open` (progress0 if not) and `d.is_active` (progress80 or progress100)
> - 93: `RATIO` – A progress color for ☯ from 0 to 120
> - 94: `PROGRESS` – A progress color from 0 to 100 for the ⣿ column
> - 95: `ALERT` – For ❢, info or alarm depending on alert state
> - 96: `UP_TIME` – Upload (∆ seeding) or time display (⌛ info + seeding/incomplete)

The mixed `DOWN_TIME` and `UP_TIME` schemes must span the full width of the column, and can only be used with one color definition in the column key (anything after them is ignored).

#### Defining Your Own Columns

This example shows how to replace the ratio column (920) with a pure ASCII version. You can see the result on the right.

Place this code in your custom configuration, e.g. in the `_rtlocal.rc` file (when using pimp-my-box).

    # Remove the default column
    method.set_key = ui.column.render, (ui.column.spec, 920)

    # Add ASCII ratio in percent
    # (1..99 for incomplete; 1c = 1.0; 1m = 10.0; …)
    method.set_key = ui.column.render, "922:3C93/3:R% ", \
        ((string.replace, ((convert.magnitude, ((math.div, ((d.ratio)), 10)) )), \
                          {"⋅", "."} ))

To construct a column definition like this, you need to understand rTorrent Scripting first – more so than what’s sufficient for writing simple configurations.

Looking at the original column definition often helps, e.g. to grab a few snippets for your own version:

    $ pyroadmin --dump-rc | egrep -A1 '"920:.+"'
    method.set_key = ui.column.render, "920:3C93/3:☯  ", \
        ((string.substr, "☹ ➀ ➁ ➂ ➃ ➄ ➅ ➆ ➇ ➈ ➉ ", \
                         ((math.mul, 2, ((math.div, ((d.ratio)), 1000)) )), 2, "⊛ "))

Also, try to understand how all the other column definitions work, you can learn a few tricks that are typical for column rendering.

Especially if you want to display additional values in the same format as an existing column, you just have to swap the command accessing the displayed item’s data. Here’s a chunk size column, all you need to do is replace `d.size_bytes` in the code of column 930 with `d.chunk_size`, and give it a new index and heading.

    ui.color.custom9.set = "bright blue"
    method.set_key = ui.column.render, "935:5C9/3C21/2: ≣   ", \
        ((convert.human_size, ((d.chunk_size)) ))

That example also shows how to use a custom color.

#### Disabling Columns

The `ui.column.show` and `ui.column.hide` commands provide the means to easily change the visibility of columns, without touching their definition. They both take a list of column keys as their arguments, as either strings or values.

The following example shows column ♯42 only on the active and leeching views,

    method.set_key = event.view.show, ~column_42_toggle, \
        "branch = \"string.contains=$ui.current_view=, active, leeching\", \
            ui.column.show=42, ui.column.hide=42"
    ui.column.hide = 42

The `ui.column.is_hidden` and `ui.column.hidden.list` commands can be used to query the visibility of columns, the first one takes a single column key as its argument.

    $ rtxmlrpc --repr ui.column.is_hidden '' 42
    1
    $ rtxmlrpc --repr ui.column.hidden.list
    [42]

A practical use of `ui.column.is_hidden` is to toggle a column. This code does so for ♯935, and binds the toggle to the `_` key.

    method.insert = pmb._toggle_chunk_size, simple|private, \
        "branch = ui.column.is_hidden=935, ui.column.show=935, ui.column.hide=935 ; \
         ui.current_view.set = (ui.current_view)"
    pyro.bind_key = toggle_chunk_size, _, "pmb._toggle_chunk_size="

The `ui.current_view.set = (ui.current_view)` part forces a redraw of the canvas, giving you instant feedback.

#### Adding Traffic Graphs

Add these lines to your configuration:

    # Show traffic of the last hour
    network.history.depth.set = 112
    schedule = network_history_sampling,1,32, network.history.sample=
    method.insert = network.history.auto_scale.toggle, simple|private, \
        "branch=network.history.auto_scale=, \
            \"network.history.auto_scale.set=0\", \
            \"network.history.auto_scale.set=1\""
    method.insert = network.history.auto_scale.ui_toggle, simple|private, \
        "network.history.auto_scale.toggle= ;network.history.refresh="
    branch=pyro.extended=,"schedule = bind_auto_scale,0,0, \
        \"ui.bind_key=download_list,=,network.history.auto_scale.ui_toggle=\""

And you’ll get this in your terminal:

rTorrent-PS Network History

As you can see, you get the upper and lower bounds of traffic within your configured time window, and each bar of the graph represents an interval determined by the sampling schedule. Pressing `=` toggles between a graph display with a baseline of 0, and a zoomed view that scales it to the current bounds.

## Development Guide

This chapter contains some explanations of the project structure and activities related to development of the project.

### Running Integration Tests

The `tasks.py` script defines a `test` task for invoke, which runs tests located in the `tests/commands/*.txt` files.

These test scripts are edited console logs of shell calls, and the test runner executes any line starting with a `$`. It then checks that any line following the command is contained in its output. The return code is checked via a `RC=n` line.

Any line starting with `#` is a comment.

The lines asserting output can contain `…` to mark omissions – any whitespace around it is ignored. That means that `foo … bar` checks that both `foo` and `bar` are contained somewhere in the command’s output.

Here’s the sample output you want to have (no failures):

    $ invoke test
    --- Running tests in 'tests/commands/array.txt'...
    .......

    --- Running tests in 'tests/commands/misc.txt'...
    ..................................................

    --- Running tests in 'tests/commands/string.txt'...
    ....................

    --- Running tests in 'tests/commands/math.txt'...
    .......................................

    ☺ ☺ ☺  ALL OK. ☺ ☺ ☺

And this is what a failure looks like:

    $ invoke test -n misc
    --- Running tests in 'tests/commands/misc.txt'...
    .
    FAIL: »!1’20”« not found in output of »rtxmlrpc convert.time_delta '' +1527903580 +1527903500«
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    1’20”
    RC=0
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    ................................................

    ☹ ☹ ☹  1 TEST(S) FAILED. ☹ ☹ ☹

This also shows how you can run only one selected test suite, using the `--name` or `-n` option.

### The Build Script

The build.sh script contains all the minute details and settings to successfully build selected dependencies and the libtorrent / rtorrent source on many platforms.

And no, it is not a Makefile, since there’s no benefit in that, for the things the script does. `[g]make` is used within the contributing projects.

See Build from Source on the ‘normal’ use of the script for building a binary. Other uses like building packages (with or without Docker) or the most recent upstream source are described in the following sections.

To build a new extended binary after you downloaded updates via a `git pull --ff-only`, just call `./build.sh extend` – this will apply any new patches included in that update, but not re-build all the dependencies.

If you’re sure that the diff only contains source code changes (in `patches/*.cc`), only calling `make` in the rTorrent source directory is way faster. In case dependency versions changed in `build.sh`, you have to go the slowest route with `./build.sh clean_all all` to get them onto your machine.

For everything else, call `./build.sh help` to get a usage summary similar to this:

    $ ./build.sh help
    Environment for building rTorrent PS-1.0-349-g12ccbe8-2018-06-30-1143 0.9.6/0.13.6
    export PACKAGE_ROOT=/opt/rtorrent
    export INSTALL_ROOT=/home/pyroscope
    …

    Usage: ./build.sh (all | clean | clean_all | download | build | check | extend)
    Build rTorrent PS-1.0-… 0.9.6/0.13.6 into ~/.local/rtorrent/0.9.6-PS-1.1-dev

    Custom environment variables:
        CURL_OPTS="-sLS" (e.g. --insecure)
        MAKE_OPTS="-j4"
        CFG_OPTS="" (e.g. --enable-debug --enable-extra-debug)
        CFG_OPTS_LT="" (e.g. --disable-instrumentation for MIPS, PowerPC, ARM)
        CFG_OPTS_RT=""

    Build actions:
        build_all   a/k/a ‹all› – Download and build and install all deps + vanilla + extended
        build       Build and install all components
        build_git   a/k/a ‹git› – Build and install libtorrent and rtorrent from git checkouts
        check       Print some diagnostic success indicators
        clean_all   Remove all downloads and created files
        clean       Clean up generated files
        deps        Build all dependencies
        deps_git    Build all dependencies [GIT HEAD MODE]
        docker_deb  Build Debian packages via Docker
        download    Download and unpack sources
        env         Show build environement
        extend      Rebuild and install libtorrent and rTorrent with patches applied
        install     Install to /opt/rtorrent
        pkg2deb     Package current /opt/rtorrent installation for APT [needs fpm]
        pkg2pacman  Package current /opt/rtorrent installation for PACMAN [needs fpm]
        vanilla     Build vanilla rTorrent [also un-patches src dirs]

### Creating a Release

- Finish `docs/CHANGES.md` and set the release date
- Run `invoke cmd_docs >docs/include-commands.rst`, and commit any additions
- Make sure every command has docs in the manual (`invoke undoc`)
- Tag the release, push tags, put changelog up on GitHub
- Build packages and upload to Bintray (using `bintray.sh`)
- Change DEB download links in pimp-my-box
- Make a stable snapshot of docs under the new version
- Bump version to next release in `docs/conf.py`
- Announce to reddit etc.

### Building the Debian Package

A Debian package for easy installation is built using fpm, so you have to install that first on the build machine, if you don’t have it yet:

    apt-get install ruby ruby-dev
    gem install fpm
    fpm -h | grep fpm.version

Then you need to prepare the install target, as follows (we assume building under the `rtorrent` user here):

    mkdir -p /opt/rtorrent
    chmod 0755 /opt/rtorrent
    chown -R rtorrent.rtorrent /opt/rtorrent

Then, the contents of the package are built by calling `./build.sh install`, which will populate the `/opt/rtorrent` directory. When that is done, you can test the resulting executable located at `/opt/rtorrent/bin/rtorrent`.

Finally, `./build.sh pkg2deb` creates the Debian package in `/tmp`. The script expects the packager’s name and email in the usual environment variables, namely `DEBFULLNAME` and `DEBEMAIL`. For a few platforms (recent Debian, Ubuntu, and Raspbian), you can find pre-built ones at Bintray.

See also

Using Docker for Building Packages

### Building git HEAD of rTorrent

You can also build the latest source of the main rTorrent project (including its `libtorrent`), with all the settings and rpath linking of the `rtorrent-ps` builds, but just like vanilla when it comes to applying patches (only essential ones are applied, like the OpenSSL one).

This is intended to be used for checking compatibility of patches with the head of the core project, and preparing PRs for it. You will not get a stable system and these builds are in no way recommended for production use.

Start by checking out the two projects as siblings of the `rtorrent-ps` workdir, leading to a folder structure like this:

    .
    ├── libtorrent
    ├── rakshasa-rtorrent
    └── rtorrent-ps

As you can see, the sibling folders can have an optional `rakshasa-` prefix.

Then use these commands within `rtorrent-ps` to build all dependencies and the git HEAD code from the sibling folders:

    INSTALL_DIR=$HOME/.local/rtorrent-git ./build.sh clean_all deps_git build_git

Just like with the vanilla and extended version, you’ll get a ‘branded’ binary called `rtorrent-git`, and a symlink at `~/bin/rtorrent` will point to it.

The `INSTALL_DIR` is set explicitly, so that a release version and git HEAD can be installed and used concurrently, without any conflicts.

### Using Docker for Building Packages

The `docker_deb` build action uses `Dockerfile.Debian` to compile and package rTorrent-PS on a given Debian or Ubuntu release. Similarly, `docker_arch` does the same for Arch Linux using `Dockerfile.ArchLinux`.

`docker_deb` takes an optional `‹distro›:‹codename›` argument, and defaults to `debian:stretch`. You can also use `all`, `stable`, or `oldstable` to name classes of distributions, defined in the related docker_distros_* lists at the start of build.sh.

`docker_arch` takes no release names due to its rolling release nature, but check out the `ARG CODENAME=20200205` at the top of `Dockerfile.ArchLinux` that makes the build more reproducible – you might want to update that to `latest` or a newer release date.

Any additional arguments to the `build.sh` call are passed on to the underlying `docker build` command. Since `docker_*` takes arguments, you cannot call any further actions after it, in the same `build.sh` call.

Note

You need Docker version `17.06` or higher to use this.

## Change History

List of Releases

- 2018-10-xx v1.2 “rTorrent 0.9.7”
- 2018-07-01 v1.1 “Design Your Canvas”
- 2017-03-12 v1.0 “First version-tagged release”

### 2018-10-xx v1.2 “rTorrent 0.9.7”

UNRELEASED DEVELOPMENT VERSION

- UI: Added item search via `Ctrl-F` and `Shift-F` / `F3`
- UI: Added no data indicator to alerts (in the `❢` column)
- UI: Replaced problematic glyphs like ‘hourglass’ (caused visual defects on Stretch and Bionic)
- Command: Added `string.shorten` command (for logging)
- Fix: Compilation on 32bit platforms (issue #108)
- Docker: Demo launcher renamed to `launch-rt-ps-demo.sh`, and supports any distro with a package available for it

### 2018-07-01 v1.1 “Design Your Canvas”

This release adds the new fully customizable and responsive canvas v2, and many new configuration and XMLRPC commands plus a few fixes – see below for a full list of changes. It comes with complete documentation hosted on Read the Docs and built with Sphinx. Binary builds for Debian and Ubuntu are available as DEB packages on Bintray.

Note that rTorrent-PS is based on the stable release of rTorrent, and that is still version 0.9.6 at the time of this release. Many of the features and commands in version 0.9.7 are originally developed in or otherwise back-ported to this project anyway.

Read the related Migrating to Version 0.6.1 (UNRELEASED) instructions, which will update configuration snippets in the `rtorrent.d` directories. If you used those snippets before, their update is required to run the new version – else you’ll get visual defects at the very minimum, but worse stuff might happen.

If you do not have a `~/rtorrent/rtorrent.d` directory created by the helper scripts, then you just have to know yourself what to do (i.e. browse through `git` diffs) – those scripts can only handle standard situations and setups.

- Docs: Much improved (moved to Read the Docs and using Sphinx)
- UI: Added responsive canvas v2 with full customization (issue #60)
  - New `ui.column.render` multi-command
  - Added `ui.column.hide` and related commands
  - Added 3 new `convert.*` commands
  - Added `ui.color.custom1…9` and `ui.color.*.index` commands
  - New default columns: ❢ ℞ ⋉ ≣
  - New alert indicators for “tracker down” and “DNS problems”
  - ‘Tagged’ indicator (⚑) now in its own column
  - Built-in views are collapsed by default now
- UI: `Info` details panel is now active by default (not `Peer list`)
- UI: Made `*` key a built-in keyboard shortcut [@chros73]
- UI: Key to toggle sacrificial columns manually (bound to `/`)
- Command: Added `string.*` command group (issue #59)
- Command: Added `math.*` command group [@chros73] (issue #65)
- Command: Added `value` conversion command
- Command: Added `array.at` command (issue #60)
- Command: Added `d.custom.if_z` and more `d.custom.*` commands (issue #101)
- Command: Added `d.is_meta` command [@chros73]
- Command: Added `d.tracker_alias` command (issue #97)
- Command: Added `d.multicall.filtered`
- Command: Added `system.has` and 3 other related commands (issue #82)
- Command: Added `system.client_version.as_value` command
- Command: Added `do` command (issue #98)
- Command: Added `import.return` private command
- Command: Added `throttle.names` (issue #65)
- Command: Added `ui.bind_key.verbose` flag (issue #55)
- Command: Added `event.view.hide` and `event.view.show` events
- Fix: Prevent filtering of `started` and `stopped` views [@chros73] (issue #36)
- Fix: `system.file.allocate.set=[0|1]` semantics [@chros73] (issue #41)
- Fix: `log.messages` – restored lost patch for message writing (issue #78)
- Fix: Properly close XMLRPC log, i.e. only once (issue #94)
- Fix: `start` handles platforms that use `RUNPATH` instead of `RPATH`
- Patch: `catch` command is silent when first command is `false=`
- Build: `bootstrap` script – switch to Python3 (issue #84)
- Build: Improved git build process
- Build: `all` now really does it all, and added a few more actions
- Build: Allow installation of several concurrent patch versions
- Build: Apply patches for OpenSSL 1.1 (on platforms using it)
- Build: Added `-std=c++11|0x` option (needed for `algorithm::median` patch)
- Build: Fixed `CXXFLAGS` for GCC 6+
- Build: Dropped rTorrent 0.8.x/0.9.2 support (issue #26)
- Build: Fedora 26 support (if you use this: it’s unmaintained, unless people open PRs)
- Tasks: Added integration tests for commands – `invoke test [-n ‹name›]` (issue #84)
- Tasks: New `cmd_docs` task to generate extension command index
- Docker: Run `pkg2deb` for several Debian / Ubuntu LTS versions
- Docker: Run an EPHEMERAL rTorrent-PS instance in a Debian Stretch container

NOTE: Support for rTorrent versions before 0.9.6 and non-C++11 compilers will end soon!

### 2017-03-12 v1.0 “First version-tagged release”

- Improved build script
- `system.random = [[<lower>,] <upper>]` command
- UI: tracker alias mappings
  - `trackers.alias.set_key=«domain»,«alias»` and `trackers.alias.items=` commands
- New Arch AUR PKGBUILDs, and `pkg2pacman` action by @xsmile (#48)
- More flexible installation options (#43)
- Easier manual setup with `make-rtorrent-config.sh` script

## Indices & Tables

- Index
- Module Index
- Search Page

Read the Docs v: latest

Versions
  latest
  stable
  ps-1.1

Downloads
  pdf
  html
  epub

On Read the Docs
  Project Home
  Builds

Free document hosting provided by Read the Docs.