Commands Reference#

The reference chapter lists all relevant XMLRPC and ‘private’ commands provided by rTorrent with a short explanation. See the Scripting Guide on how to combine them into meaningful command sequences, and Using XMLRPC for Remote Control for some general hints on using the XMLRPC API

Use the search box in the sidebar to find specific commands, or the generated index also lists all the command names.

The following are similar, but incomplete resources:

Format#

All commands will appear in the following format:

command_name#

command_name = type ‹argument› ≫ type ‹returned value›

All commands are formatted with a similar syntax as they would appear in rtorrent.rc. This section would normally contain a description of what the command does, along with any examples or references.

Important

All commands take a first argument, called target internally. This argument is given implicitly in rtorrent.rc and the kbd:Ctrl-X prompt, but must be given explicitly when using the XML-RPC API.

All of the d.*, f.* and p.* commands must have a valid target, the format of which is documented at the top of their sections. Commands that require a target to be supplied, even if implicitly, will have it documented as an argument. Any commands that don’t require a valid target should give an empty string as their first argument instead.

rtorrent.rc format:

d.name=
d.multicall2=main,d.start=
directory.default.set=/var/data/

XML-RPC format:

rtxmlrpc d.name DDEE5CB75C12F3165EF79A12A5CD6158BEF029AD
rtxmlrpc d.multicall2 '' main d.start=
rtxmlrpc directory.default.set '' /var/data/

Download Items and Attributes#

`d.*` commands#

For all d.* commands, a explicit target should be a hash, e.g. DDEE5CB75C12F3165EF79A12A5CD6158BEF029AD.

d.multicall2#

d.multicall.filtered#

d.multicall.filtered was added in rTorrent 0.9.8/rTorrent-PS 1.1

d.multicall2 = ‹view›, [‹cmd1›=[‹args›][, ‹cmd2›=…]] ≫  list[list] ‹results›
d.multicall.filtered = ‹view›, ‹predicate›, [‹cmd1›=[‹args›][, ‹cmd2›=…]] ≫ same as 'multicall2'

These commands iterate over the content of a given view, or default when the view is omitted or empty.

d.multicall2 iterates over all items in view and calls the given commands on each, assembling the results of those calls in a row per item.

d.multicall.filtered is only available in rTorrent-PS, and evaluates the predicate condition as a filter for each item, only calling the commands for items that match it. See elapsed.greater for an example.

If you request a lot of attribute values on all items, make sure you set a big enough value for network.xmlrpc.size_limit to hold all the returned data serialized to XML.

Example

$ rtxmlrpc --repr d.multicall2 '' tagged d.hash= d.name= d.custom=category
[['91C588B9A9B5A71F0462343BC74E2A88C1E0947D',
  'sparkylinux-4.0-x86_64-lxde.iso',
  'Software'],
 ['17C14214B60B92FFDEBFB550380ED3866BF49691',
  'sparkylinux-4.0-x86_64-xfce.iso',
  'Software']]

$ rtxmlrpc --repr download_list '' tagged
['91C588B9A9B5A71F0462343BC74E2A88C1E0947D',
 '17C14214B60B92FFDEBFB550380ED3866BF49691']

download_list#

download_list = ‹view› ≫ list[string] ‹infohashes›

download_list always returns a list of the contained infohashes from the specified view.

d.name#

d.base_filename#

d.base_path#

d.directory#

d.directory.set#

d.directory_base#

d.directory_base.set#

d.name = target ‹hash› ≫ string ‹name›
d.base_filename = target ‹hash› ≫ string ‹basename›
d.base_path = target ‹hash› ≫ string ‹path›
d.directory = target ‹hash› ≫ string ‹path›
d.directory_base = target ‹hash› ≫ string ‹path›
d.directory.set = target ‹hash›, ‹path› ≫ 0
d.directory_base.set = target ‹hash›, ‹path› ≫ 0

These commands return various forms of an item’s data path and name, and the last two can change the path, and sometimes the name in the file system. Note that rTorrent-PS can also change the displayed name, by setting the displayname custom attribute using d.custom.set.

Basics:

d.base_filename is always the basename of d.base_path.

d.directory_base and d.directory are always the same.

d.base_filename and d.base_path are empty on closed items, after a restart, i.e. not too useful (since 0.9.1 or so).

Behaviour when d.directory.set + d.directory_base.set are used (tested with 0.9.4):

d.base_path always remains unchanged, and item gets closed.

d.start sets d.base_path if resume data is OK.

‘single’ file items (no containing folder, see d.is_multi_file):

d.directory[_base].set → d.name is never appended (only in d.base_path).

after start, d.base_path := d.directory/d.name.

‘multi’ items (and yes, they can contain just one file):

d.directory.set → d.name is appended.

d.directory_base.set → d.name is not appended (i.e. item renamed to last path part).

after start, d.base_path := d.directory.

Making sense of it (trying to at least):

d.directory is always a directory (thus, single items auto-append d.name in d.base_path and cannot be renamed).

d.directory_base.set means set path plus basename together for a multi item (thus allowing a rename).

only d.directory.set behaves consistently for single+multi, regarding the end result in d.base_path.

The definition below is useful, since it always contains a valid path to an item’s data, and can be used in place of the unreliable d.base_path.

# Return path to item data (never empty, unlike `d.base_path`);
# multi-file items return a path ending with a '/'.
method.insert = d.data_path, simple,\
    "if=(d.is_multi_file),\
        (cat, (d.directory), /),\
        (cat, (d.directory), /, (d.name))"

d.state#

d.state_changed#

d.state_counter#

d.is_open#

d.is_active#

d.state = target ‹hash› ≫ bool (0 or 1)
d.state_changed = target ‹hash› ≫ value ‹timestamp›
d.state_counter = target ‹hash› ≫ value ‹count›
d.is_open = target ‹hash› ≫ bool (0 or 1)
d.is_active = target ‹hash› ≫ bool (0 or 1)

These commands return the item’s state (1 = started or paused, 0 = stopped), when that changed the last time, and how often it did change. Note that although pausing / resuming a started item does not change state, the timestamp and counter are still updated.

In summary:

Closed items are not open, with state=0.
Paused items are open, but not active, with state=1.
Started items are both open and active, with state=1.

The three state values are persisted to the session, while active (paused) is not. See How Can I Stop All Torrents From a Shell? on how you can use that to influence the startup behaviour of rTorrent.

d.open#

d.close#

d.pause#

d.resume#

d.close.directly#

d.try_close#

TODO

d.start#

d.stop#

d.try_start#

d.try_stop#

Starts or stops an item, including everything that needs to be done for that. For starting, that includes hashing the data if it already exists. On stop, incomplete chunks are discarded as part of the stop.

The try variants look at the d.ignore_commands flag and thus only conditionally start/stop the item.

d.loaded_file#

d.tied_to_file#

d.tied_to_file.set#

d.loaded_file is the metafile from which this item was created. After loading from a watch directory, this points to that watch directory, but after a client restart it is the session file (since the item is then loaded from there).

d.tied_to_file also starts out as the file the item is initially created from, but can be set to arbitrary values, and an item can be untied using d.delete_tied, leading to an empty value and the deletion of the tied file.

One of the stop_untied, close_untied, or remove_untied commands can then be used in a schedule to stop, close, or remove an item that lost its tied file, including when you delete or move it from the outside in a shell or cron job.

d.accepting_seeders#

d.accepting_seeders.disable#

d.accepting_seeders.enable#

d.accepting_seeders = target ‹hash› ≫ bool (0 or 1)
d.accepting_seeders.disable = target ‹hash› ≫ 0
d.accepting_seeders.enable = target ‹hash› ≫ 0

Controls whether or not new connections to seeders are sought out. Existing connections are not effected.

d.bitfield#

d.bitfield = target ‹hash› ≫ string ‹bitfield›

Returns the bitfield represented by a string of hexadecimal digits, with each character representing the “completeness” of each field. Note that due to rounding inaccuracies, the number of fields with likely neither align exactly with the number of chunks nor number of bytes.

d.bytes_done#

d.bytes_done = target ‹hash› ≫ value ‹bytes›

This tracks the amount of bytes for a torrent which has been accepted from peers. Note that bytes aren’t considered to be “completed” until the full chunk is downloaded and verified. See d.completed_bytes for that value. See also d.left_bytes for the number of bytes yet to be accepted.

d.check_hash#

d.check_hash = target ‹hash› ≫ 0

Checks the piece hashes of an item against its data. Started items are paused during the rehashing.

d.chunk_size#

d.chunk_size = target ‹hash› ≫ value ‹size›

Returns the item’s chunk size in bytes (also known as the “piece size”).

d.chunks_hashed#

d.chunks_hashed = target ‹hash› ≫ value ‹chunks›

While a torrent is hash checking, this tracks the number of chunks that have successfully hashed.

d.chunks_seen#

   d.chunks_seen = target ‹hash› ≫ string ‹bitfield›

Returns a hexidecimal representation of chunks that other
peers have sent "seen" messages for.

d.complete#

d.incomplete#

d.complete = target ‹hash› ≫ bool (0 or 1)
d.incomplete = target ‹hash› ≫ bool (0 or 1)

Indicates whether an item is complete (100% done) or not.

d.completed_bytes#

d.completed_chunks#

d.completed_bytes = target ‹hash› ≫ value ‹bytes›
d.completed_chunks = target ‹hash› ≫ value ‹chunks›

Returns the number of completed bytes and chunks, respectively. “Completed” means the bytes/chunk has been downloaded and verified against the hash.

d.connection_current#

d.connection_current.set#

d.connection_leech#

d.connection_seed#

TODO

d.create_link#

d.delete_link#

d.create_link = ‹type›, ‹path›, ‹suffix› ≫ 0
d.delete_link = ‹type›, ‹path›, ‹suffix› ≫ 0

These can be used to reflect an item’s state in the file system.

Creates or deletes a symbolic link. The link path is the concatenation of path, a value depending on the selected type, and suffix.

Available types are:

base_path uses the base path of the item,
base_filename uses the base filename of the item,
tied uses the path of the file the item is tied to, see d.tied_to_file.

d.delete_tied#

d.delete_tied = target ‹hash› ≫ 0

Delete the d.tied_to_file, which obviously also unties the item. This command is bound to the U key by default, and also called whenever an item is erased.

Example

# Delete metafile from a watch dir directly after loading it
# (note that a copy still remains in the session directory)
schedule2 = watch_cleaned, 29, 10, \
    ((load.normal, (cat,(cfg.watch),"cleaned/*.torrent"), "d.delete_tied="))

d.creation_date#

d.creation_date = target ‹hash› ≫ value ‹timestamp›

Returns a timestamp reflecting the .torrent file creation date (i.e. separate from the date the item was loaded into the client). This value can be inspected with tools like lstor:

$ lstor -o 'creation date' file.torrent
1480229112

TODO What does this return for magnet files?

d.custom#

d.custom.set#

d.custom_throw#

d.custom1#

d.custom1.set#

d.custom2…5#

d.custom2…5.set#

d.custom[_throw] = target ‹hash›, string ‹key› ≫ string ‹value›
d.custom.set = target ‹hash›, string ‹key›, string ‹value› ≫ 0
d.custom1 = target ‹hash› ≫ string ‹value›
d.custom1.set = target ‹hash›, string ‹value› ≫ 0

Set and return custom values using either arbitrary keys, or a limited set of 5 numbered slots. Note that d.custom1 is not the same as d.custom=1 or d.custom=custom1, and can only be accessed by its assigned commands.

If d.custom is called for a key that doesn’t exist, it will return an empty string, unlike d.custom_throw which throws a No such custom value error.

Try to avoid the numbered versions, they’re obviously limited, and collisions with other uses are quite likely. ruTorrent for example uses #1 for its label, and the other slots for various other purposes.

Warning

Never add spaces after the key when using new syntax, i.e. (d.custom, bugfest ) will look for the bugfest␣␣ key.

d.custom.if_z#

rTorrent-PS 1.1+ only

d.custom.if_z = target ‹hash›, string ‹key›, string ‹default› ≫ string ‹value›

Just like d.custom, but returns the ‹default› value if the ‹key› does not exist, or if its value is empty.

Examples

d.custom.set_if_z#

rTorrent-PS 1.1+ only

d.custom.set_if_z = target ‹hash›, string ‹key›, string ‹value› ≫ 0

This is a companion to d.custom.if_z and sets a custom value only once, if it was missing or empty previously.

Examples

d.custom.erase#

rTorrent-PS 1.1+ only

d.custom.erase = target ‹hash›, string ‹key›[, …] ≫ 0

Removes the given custom key(s) – erasing non-existent keys is not an error.

Examples

d.custom.toggle#

rTorrent-PS 1.1+ only

d.custom.toggle = target ‹hash›, string ‹key› ≫ value ‹negated›

Inverts the truthiness of a custom attribute using 0 or 1 as the only results. Empty strings and 0 become 1, and any other string becomes 0.

It also returns the current value that was set (as in the value type, i.e. as an integer).

Examples

d.custom.as_value#

rTorrent-PS 1.1+ only

d.custom.as_value = target ‹hash›, string ‹key› ≫ value ‹number›

Returns a custom attribute as a value (base 10 integer). Missing keys and empty strings are 0, while non-numbers raise an exception.

Major use-cases of this are custom timestamp fields, and querying toggles (see d.custom.toggle).

Examples

d.custom.keys#

rTorrent-PS 1.1+ only

d.custom.keys = target ‹hash› ≫ list of string ‹defined keys›

Returns a list of custom keys that are defined for an item.

Example

$ rtxmlrpc --repr d.custom.keys $(rtxmlrpc download_list | head -n1) | tr -d \\n
[… 'tm_downloaded', 'tm_last_scrape', 'tm_loaded', 'tm_started']

d.custom.items#

rTorrent-PS 1.1+ only

d.custom.items = target ‹hash› ≫ map of key / value strings ‹defined items›

Returns keys and their associated values, for all custom values of an item.

Example

$ rtxmlrpc --repr d.custom.items $(rtxmlrpc download_list | head -n1)
{…
 'tm_downloaded': '1522406424',
 'tm_last_scrape': '1527931151',
 'tm_loaded': '1522406432',
 'tm_started': '1522406432'}

d.disconnect.seeders#

d.disconnect.seeders = target ‹hash› ≫ 0

Cleanly drop all connections to seeders. This does not prevent them from reconnecting later on.

d.down.choke_heuristics#

d.down.choke_heuristics.leech#

d.down.choke_heuristics.seed#

d.down.choke_heuristics.set#

TODO

d.down.rate#

d.down.total#

d.down.rate = target ‹hash› ≫ value ‹rate (bytes/s)›
d.down.total = target ‹hash› ≫ value ‹total (bytes)›

The total amount and current rate of download traffic for this item. It’s possible for the total download to be greater than d.size_bytes, due to error correction or discarded data.

d.downloads_max#

d.downloads_max.set#

d.downloads_min#

d.downloads_min.set#

d.downloads_max = target ‹hash› ≫ value ‹max›
d.downloads_max.set = target ‹hash›, value ‹max› ≫ 0
d.downloads_min = target ‹hash› ≫ value ‹max›
d.downloads_min.set = target ‹hash›, value ‹max› ≫ 0

Control the maximum and minimum download slots that should be used per item. rTorrent will attempt to balance the number of active connections so that the number of unchoked connections is between the minimum and maximum, which means that these are not hard limits, but are instead goals that rTorrent will try to reach.

0 means unlimited, and while d.downloads_max can be set to less than d.downloads_min, rTorrent will then use d.downloads_min as the maximum instead. The default values are controlled by throttle.min_downloads and throttle.max_downloads.

d.erase#

d.erase = target ‹hash› ≫ 0

The item is marked as hash-failed (to invalidate it until it is totally gone) and closed. Any associated session files are removed. The event.download.erased event is fired, and the item is removed from all views it is listed on.

The data stored for the item is not touched in any way.

d.free_diskspace#

d.free_diskspace = target ‹hash› ≫ value ‹bytes›

Return the minimum free space of devices where files of the item reside on. In the usual case without symlinks and the like, it’s the free space of the drive holding d.directory.

`f.*` commands#

These commands can be used as arguments in a f.multicall. They can also be called directly, but you need to pass ‹infohash›:f‹index› as the first argument. Index counting starts at 0, the array size is d.size_files.

Example

$ rtxmlrpc --repr f.multicall "145B85116626651912298F9400805254FB1192AE" "" f.path=
[['ubuntu-16.04.3-server-amd64.iso']]

$ rtxmlrpc --repr f.size_bytes "145B85116626651912298F9400805254FB1192AE:f0"
865075200

f.multicall#

f.multicall = ‹infohash›, string ‹pattern›, [string ‹cmd1›=[‹args›][, ‹cmd2›=…]] ≫ list[list] ‹results›

Iterates over the files in an item, calling the given f.* commands. The second argument, if non-empty, is a glob-like pattern (e.g. *.mkv) and filters the result for matching filenames. That pattern matching is very simplistic, be cautious and test that you get the results you expect.

See also d.multicall2 on basics regarding multi-calls.

f.completed_chunks#

f.completed_chunks = ‹infohash› ≫ value ‹chunks›

The number of chunks in the file completed. Just as with f.size_chunks, this number is inclusive of any chunks that contain only part of the file.

f.frozen_path#

f.frozen_path = ‹infohash› ≫ string ‹abspath›

The absolute path to the file.

f.is_created#

f.is_open#

TODO

f.is_create_queued#

f.set_create_queued#

f.unset_create_queued#

f.is_resize_queued#

f.set_resize_queued#

f.unset_resize_queued#

TODO

f.last_touched#

f.last_touched = ‹infohash› ≫ value ‹microseconds›

The last time, in epoch microseconds, rTorrent prepared to use the file (for either reading or writing). This will not necessarily correspond to the file’s access or modification times.

f.match_depth_next#

f.match_depth_prev#

TODO

f.offset#

f.offset = ‹infohash› ≫ value ‹bytes›

The offset (in bytes) of the file from the start of the torrent data. The first file starts at 0, the second file at f.size_bytes of the first file, the third at f.size_bytes of the first two files combined, and so on.

f.path#

f.path = ‹infohash› ≫ string ‹path›

The path of the file relative to the base directory.

f.path_components#

f.path_components = ‹infohash› ≫ array ‹components›

Returns an array of the individual parts of the path.

f.path_depth#

f.path_depth = ‹infohash› ≫ value ‹depth›

Returns a value equal to how deep the file is relative to the base directory. This is equal to the number of elements in the array that f.path_components returns.

f.prioritize_first#

f.prioritize_first.disable#

f.prioritize_first.enable#

f.prioritize_last#

f.prioritize_last.disable#

f.prioritize_last.enable#

f.prioritize_first = ‹infohash› ≫ bool (0 or 1)
f.prioritize_first.disable = ‹infohash› ≫ 0
f.prioritize_first.enable = ‹infohash› ≫ 0
f.prioritize_last = ‹infohash› ≫ bool (0 or 1)
f.prioritize_last.disable = ‹infohash› ≫ 0
f.prioritize_last.enable = ‹infohash› ≫ 0

This determines how files are prioritized when f.priority is set to normal. While any high (i.e. 2) priority files take precedence, when a torrent is started, the rest of the files are sorted according to which are marked as prioritize_first vs prioritize_last. If both flags are set, prioritize_first is checked first. This sorting happens whenever d.update_priorities is called.

`p.*` commands#

These commands can be used as arguments in a p.multicall. They can also be called directly, but you need to pass ‹infohash›:p‹peerhash› as the first argument (referenced as target from here on out). The ‹peerhash› is the ID as returned by p.id, which is encoded as a hexadecimal string.

Example

$ hash="145B85116626651912298F9400805254FB1192AE" # some valid info hash
$ rtxmlrpc --repr p.multicall "$hash" "" p.id= p.port=
[['17C14214B60B92FFDEBFB550380ED3866BF49691', 62066]]
$ rtxmlrpc --repr p.port "$hash:p17C14214B60B92FFDEBFB550380ED3866BF49691"
62066

p.multicall#

p.multicall = ‹infohash›, "", [‹cmd1›=[‹args›][, ‹cmd2›=…]] ≫ list of lists of results ‹rows of results›

Iterates over the peers in an item, calling the given p.* commands.

The second argument is ignored, pass an empty string. See also d.multicall2 on basics regarding multi-calls.

p.address#

p.address = ‹target› ≫ string ‹address›

Returns the IP address of the peer.

p.banned#

p.banned.set#

p.banned = ‹target› ≫ bool (0 or 1)
p.banned.set = ‹target›, bool (0 or 1) ≫ 0

Returns (or sets) whether to ban the peer for too much bad data being sent, which means rTorrent will never connect to the peer again.

TODO What are the conditions for a peer being banned automatically?

Warning

Once a peer is set as banned, it cannot be unbanned. Only restarting rTorrent can clear the ban.

p.call_target#

p.call_target = ‹infohash›, ‹peerhash›, ‹cmd›, [‹arg1›, [, ‹arg2›…]] ≫ bool (0 or 1)

TODO While functional, the code looks incomplete and it isn’t very useful.

p.client_version#

p.client_version = ‹target› ≫ string ‹client version›

Returns a string client containing the client and version of the peer, if rTorrent knows enough to parse the peer ID. Otherwise, Unknown will be returned. The list of clients rTorrent understands is available in client_list.cc.

p.completed_percent#

p.completed_percent = ‹target› ≫ value ‹percent›

Returns the percent of data the remote peer has completed.

p.disconnect#

p.disconnect_delayed#

p.disconnect = ‹target› ≫ 0
p.disconnect_delayed = ‹target› ≫ 0

Disconnects from the specified peer. The p.disconnect disconnects immediately, while p.disconnect_delayed puts the actual disconnect into a queue.

TODO What causes delayed disconnect actions to finally be acted upon?

p.down_rate#

p.down_total#

p.down_rate = ‹target› ≫ value ‹rate  [bytes/s]›
p.down_total = ‹target› ≫ value ‹total  [bytes]›

Returns the rate and total of the bytes you are downloading from the peer.

p.id#

p.id = ‹target› ≫ string ‹peerhash›

Returns the peer ID hash, in the form of a 40-character hex string. This is the ID rTorrent uses to reference the peer in all XMLRPC commands, and is different from the ID peers send to identify themselves.

p.id_html#

p.id_html = ‹target› ≫ string ‹client id›

Returns the client ID string, with non-printable characters percent encoded, like URLs. This command is completely unrelated to p.id. This is instead the raw string that peers send to identify themselves uniquely, and is what p.client_version attempts to parse. See BEP 20 for more information on the conventions clients use for the value.

p.is_encrypted#

p.is_encrypted = ‹target› ≫ bool (0 or 1)

Returns true if the connection to the peer is encrypted (not just obfuscated). However, if this returns true, p.is_obfuscated will always be true as well. See protocol.encryption.set.

p.is_incoming#

p.is_incoming = ‹target› ≫ bool (0 or 1)

Return true if the remote peer was the first one to initiate the connection.

p.is_obfuscated#

p.is_obfuscated = ‹target› ≫ bool (0 or 1)

Returns true if the header messages sent to the peer are obfuscated. If the connection is fully encrypted, this is true automatically. Be aware that this means the data is still being sent unencrypted.

p.is_preferred#

p.is_unwanted#

p.is_preferred = ‹target› ≫ bool (0 or 1)
p.is_unwanted = ‹target› ≫ bool (0 or 1)

Returns whether or not the peer is marked as preferred or unwanted when IP filtering is in use.

p.options_str#

p.options_str = ‹target› ≫ string ‹options›

Returns the reserved option bytes as a string. Currently only two options are recognized by rTorrent: extensions (BEP 10) and DHT (BEP 5). For clients that support both (most modern ones do), 0000000000100005 will be the returned string.

p.peer_rate#

p.peer_total#

p.peer_rate = ‹target› ≫ value ‹rate [bytes/s]›
p.peer_total = ‹target› ≫ value ‹total [bytes]›

Returns the rate and total of the bytes which the peer is downloading from everyone (local client included). Note that this is calculated from the number of chunks the peer has completed, and as such should not be taken as an exact indicator.

p.port#

p.port = ‹target› ≫ value ‹port›

Returns the remote port as an integer.

p.is_snubbed#

p.snubbed#

p.snubbed.set#

p.snubbed = ‹target› ≫ bool (0 or 1)
p.is_snubbed = ‹target› ≫ bool (0 or 1)
p.snubbed.set = ‹target›, bool (0 or 1) ≫ 0

Control if a peer is snubbed, meaning that rTorrent will stop uploading to the peer. p.is_snubbed is an alias for p.snubbed.

p.up_rate#

p.up_total#

p.up_rate = ‹target› ≫ value ‹rate [bytes/s]›
p.up_total = ‹target› ≫ value ‹total [bytes]›

Returns the rate and total of the bytes you are uploading to the peer.

`t.*` commands#

These commands can be used as arguments in a t.multicall. They can also be called directly, but you need to pass ‹infohash›:t‹index› as the first argument. Index counting starts at 0, the array size is d.tracker_size.

Example

$ rtxmlrpc --repr t.multicall DDEE5CB75C12F3165EF79A12A5CD6158BEF029AD '' t.url=
[['https://torrent.ubuntu.com:6969/announce'],
 ['https://ipv6.torrent.ubuntu.com:6969/announce']]
$ rtxmlrpc --repr t.url DDEE5CB75C12F3165EF79A12A5CD6158BEF029AD:t0
'https://torrent.ubuntu.com:6969/announce'

t.multicall#

t.multicall = ‹infohash›, "", [‹cmd1›=[‹args›][, ‹cmd2›=…]] ≫ list of lists of results ‹rows of results›

Iterates over the trackers in an item, calling the given t.* commands.

The second argument is ignored, pass an empty string. See also d.multicall2 on basics regarding multi-calls.

t.activity_time_last#

t.activity_time_next#

t.activity_time_last = ‹target› ≫ value ‹epoch time in seconds›
t.activity_time_next = ‹target› ≫ value ‹epoch time in seconds›

t.activity_time_last returns the last time there was an attempt to announce to this tracker, regardless of whether or not the announce succeeded. t.activity_time_next indicates when rtorrent will attempt to announce to the tracker next. In most cases, t.activity_time_next - t.activity_time_last will equal t.normal_interval.

One common exception occurs when the tracker returns an error. In that case, rtorrent will being announcing more frequently, starting out with the next announce in 5 seconds, and then doubling the interval it waits until the maximum of 320 seconds between each announce is reached.

t.can_scrape#

t.can_scrape = ‹target› ≫ bool (0 or 1)

Checks if the announce URL is scrapeable. rTorrent considers a HTTP tracker scrapeable if the announce URL contains the string /announce somewhere after the rightmost / (inclusively).

See d.tracker.send_scrape for actually issuing the scrape request.

t.is_usable#

t.is_enabled#

t.is_enabled.set#

t.disable#

t.enable#

t.is_usable = ‹target› ≫ bool (0 or 1)
t.is_enabled = ‹target› ≫ bool (0 or 1)
t.is_enabled.set = ‹target›, bool (0 or 1) ≫ 0
t.disable = ‹target› ≫ 0
t.enable = ‹target› ≫ 0

These commands control enabling or disabling the tracker. If a tracker is disabled, rTorrent will stop trying to announce to it. t.is_usable is an alias for t.is_enabled.

t.failed_counter#

t.failed_counter = ‹target› ≫ value ‹count›

This tracks the number of failed requests to the tracker. Note that this value resets to 0 if a request succeeds.

`load.*` commands#

The client may be configured to check a directory for new metafiles and load them. Items loaded in this manner will be tied to the metafile’s path (see d.tied_to_file).

This means when the metafile is deleted, the item may be stopped (see stop_untied), and when the item is removed the metafile is also. Note that you can untie an item by using the U key (which will also delete the tied file), and using Ctrl-K also implicitly unties an item.

load.normal#

load.verbose#

load.start#

load.start_verbose#

# all other commands have the same arguments
load.normal = ‹metafile pattern›, [‹cmd1›=[‹args›][, ‹cmd2›=…]] ≫ 0

Load a single metafile, or expand a pattern of new files to be loaded. These commands are typically used in watch directory schedules.

normal loads them stopped, and verbose reports problems to the console, like when a new file’s infohash collides with an already loaded item.

# Simple watches that load items started or closed
schedule2 = watch_start, 1, 10, ((load.start_verbose, (cat, (cfg.watch), "start/*.torrent")))
schedule2 = watch_load,  2, 10, ((load.verbose, (cat, (cfg.watch), "load/*.torrent")))

Post-load commands

You can list any number of commands as additional arguments, after the metafile pattern in a load command. Typical uses are calling d.delete_tied, setting custom attributes via d.custom.set, or immediately setting a specific download directory with d.directory.set (as opposed to doing that in completion moving).

These commands are executed before the new item is fully added to the download list, and some commands like d.start won’t work in that state. So you sometimes have to use event.download.inserted_new handlers instead.

schedule2 = watch_with_category, 27, 10, \
    ((load.verbose, (cat,(cfg.watch),"foobar/*.torrent"), "d.custom1.set=foobar"))

Remotely loading an item with a specific path

The following example is also using post-load commands, but does so ‘from the outside’ using the XMLRPC API.

LOAD_PRIORITY=2
rtxmlrpc -q load.verbose '' "$metafile_path" \
    "d.directory_base.set=\"$data_dir\"" "d.priority.set=$LOAD_PRIORITY"

load.raw#

load.raw_start#

load.raw_start_verbose#

load.raw_verbose#

load.raw_start_verbose since rTorrent 0.9.7

# all other commands have the same arguments
load.raw = bytes ‹binary (i.e. raw) metafile›, [string ‹cmd1›=[‹args›][, ‹cmd2›=…]] ≫ 0

Load a metafile passed as base64 data. The method of encoding the data for XMLRPC will vary depending on which tool you’re using.

Take note that d.tied_to_file and d.loaded_file (until a client restart) will be empty for items added by these commands – which is the case for all items added via ruTorrent.

As with load.normal, raw loads them stopped, and raw_verbose reports problems to the console.

Example

$ mktor -q README.md local
$ rtxmlrpc --debug load.raw_verbose '' @README.md.torrent | egrep 'xmlrpclib|stats'
DEBUG    load.raw_verbose('', <xmlrpclib.Binary instance at 0x15e1200>) took 0.000 secs
DEBUG    XMLRPC stats: 3 req, out 795 bytes [564 bytes max], in 445 bytes [153 bytes max], …
$ rtxmlrpc d.multicall.filtered '' 'string.contains=$d.name=,README' \
           d.name= d.tied_to_file= d.loaded_file=
['README.md', '', '']

`session.*` commands#

session.name#

session.name.set#

session.name ≫ string ‹name›
session.name.set = string ‹name› ≫ 0

This controls the session name. By default this is set to system.hostname + ‘:’ + system.pid. Like session.path, once the session is active this cannot be changed

session.on_completion#

session.on_completion.set#

session.on_completion ≫ bool (0 or 1)
session.on_completion.set = bool (0 or 1) ≫ 0

When true, d.save_resume is called right before event.download.finished occurs.

session#

session.path#

session.path.set#

session.path ≫ string ‹path›
session.path.set = string ‹path› ≫ 0

session.path.set specifies the location of the directory where rTorrent saves its status between starts – a command you should always have in your configuration.

It enables session management, which means the metafiles and status information for all open downloads will be stored in this directory. When restarting rTorrent, all items previously loaded will be restored. Only one instance of rTorrent should be used with each session directory, though at the moment no locking is done.

An empty string will disable session handling. Note that you cannot change to another directory while a session directory is already active.

session is an alias for session.path.set, but should not be used as it may become deprecated.

session.save#

session.save ≫ 0

Flushes the full session state for all torrents to the related files in the session folder. Note that this can cause heavy IO with many torrents. The default interval this command runs at can be adjusted, however if rTorrent restarts or goes down, there may be a loss of statistics and resume data for any new torrents added after the last snapshot.

See also d.save_full_session, which saves the state of a single item.

session.use_lock#

session.use_lock.set#

session.use_lock ≫ bool (0 or 1)
session.use_lock.set = bool (0 or 1) ≫ 0

By default, a lockfile is created in the session directory to prevent multiple instances of rTorrent from using the same session simultaneously.

Scripting#

`method.*` commands#

method.insert#

method.insert = string ‹name›, string ‹type›[|‹sub-types›…][, string ‹definition›] ≫ 0

The general way to define any kind of command. See Object Types for the possible values in the 2nd argument, Commands regarding some basic info on custom commands, and get comfortable with Escaping because you typically need that in more complex command definitions.

TODO more details

method.insert.simple#

method.insert.simple = ‹name›, ‹definition› ≫ 0

This is a shortcut to define commands that are simple non-private functions.

method.insert.c_simple#

method.insert.c_simple = ‹name›, ‹definition› ≫ 0

Defines a const simple function. TODO Meaning what?

method.insert.s_c_simple#

method.insert.s_c_simple = ‹name›, ‹definition› ≫ 0

Defines a static const simple function. TODO Meaning what?

argument.0#

argument.1#

argument.2#

argument.3#

# Internal, not callable from XMLRPC!
$argument.‹N›= ≫ value of Nth argument

These can be used to refer to arguments passed into a custom method, either via $argument.‹N›= or (argument.‹N›).

method.insert.value#

method.insert.bool#

method.insert.string#

method.insert.list#

New in version 0.9.8: .bool, .string, and .list

method.insert.value = ‹name›, value ‹default› ≫ 0
method.insert.bool = ‹name›, bool ‹default› ≫ 0
method.insert.string = ‹name›, string ‹default› ≫ 0
method.insert.list = ‹name›, list ‹default› ≫ 0

Defines a variable that you can query and set, just like with any built-in variable. Each method corresponds with its object type (see Object Types for more information).

The example shows how to do optional logging for some new command you define, and also how to split a complicated command into steps using the multi method type.

# Enable verbose mode by setting this to 1
method.insert.value = sample.verbose, 0

# Do something with optional logging
method.insert = sample.action, multi|rlookup|static
method.set_key = sample.action, 10, ((print, "action"))
method.set_key = sample.action, 20, ((print, "action2"))
method.set_key = sample.action, 99,\
    ((branch, sample.verbose=,\
        "print=\"Some log message\""\
    ))
method.const.enable = sample.action

method.const#

method.const.enable#

method.const = ‹name› ≫ bool (0 or 1)
method.const.enable = ‹name› ≫ 0

Set a method to immutable (or final). method.const queries whether a given command is. If you try to change a const method, you’ll get an Object is wrong type or const. error.

See method.insert.value for an example.

method.erase#

Doesn’t work, don’t bother.

method.get#

method.get = ‹name› ≫ various (see text)

Returns the definition of a method, i.e. its current integer or string value, the definition for simple methods, or a dict of command definitions for multi methods. Querying any built-in method (a/k/a non-dynamic commands) results in a Key not found. fault.

The type of the definition can be either string or list, depending on whether "…" or ((…)) was used during insertion.

An example shows best what you get here, if you query the commands defined in the method.insert.value example, you’ll get this:

$ rtxmlrpc --repr method.get '' sample.verbose
1

$ rtxmlrpc --repr method.get '' sample.verbose.set
ERROR    While calling method.get('', 'sample.verbose.set'): <Fault -503: 'Key not found.'>

$ rtxmlrpc --repr method.get '' sample.action
{'10': ['print', 'action'],
 '20': ['print', 'action2'],
 '99': ['branch', 'sample.verbose=', 'print="Some log message"']}

method.get is also great to see what system handlers are registered. They often begin with a ! or ~ to ensure they sort before / after any user-defined handlers.

$ rtxmlrpc --repr method.get '' event.download.closed
{'!view.indemand': 'view.filter_download=indemand',
 'log': 'print="CLOSED ",$d.name=," [",$convert.date=$system.time=,"]"'}

The !view.‹viewname› handler is added dynamically when you register it for an event using view.filter_on.

method.set#

TODO

method.set_key#

method.has_key#

method.list_keys#

method.set_key = ‹name›, ‹key›[, ‹definition›] ≫ 0
method.has_key = ‹name›, ‹key› ≫ bool (0 or 1)
method.list_keys = ‹name› ≫ list[string] ‹method names›

Set entries in a multi method, query a single key, or list them all. If you omit the definition in a method.set_key call, the key is erased – it is safe to do that with a non-existing key.

method.set_key is commonly used to add handler commands to event types like event.download.finished. It can also be used to split complicated command definitions, see method.insert.value for an example.

See the explanation of the multi type for more details.

method.rlookup#

method.rlookup.clear#

method.rlookup = string ‹key› ≫ list[string] ‹method names›
method.rlookup.clear = string ‹key› ≫ 0

method.rlookup returns a list of multi-method names that have a reverse lookup entry for the given key. method.rlookup.clear erases all those entries registered for ‹key›, and also the reverse-lookup list for that key.

So if you added something under the same key to several events, you can find them again easily and also remove them in one go. Internally, this is used to clear old event handlers when setting new ones with view.filter_on.

Example:

$ rtxmlrpc --repr method.rlookup '' \!view.main
['event.download.finished', 'event.download.inserted_new']

method.redirect#

method.redirect = string ‹alias›, string ‹target› ≫ 0

Defines an alias for an existing command, the arguments are command names. Aliases cannot be changed, using the same alias name twice causes an error.

`event.*` commands#

rTorrent events are merely multi commands that are called automatically when certain things happen, like completion of a download item.

You can trigger them manually by calling them on selected items (e.g. via rtxmlrpc). Make sure though that the registered handlers do not have adverse effects when called repeatedly, i.e. know what you’re doing.

The handlers for an event can be listed like so:

rtxmlrpc --repr method.get '' event.download.finished

Note that practically all the events have pre-registered system handlers, often starting with a digit, !, or ~, for ordering reasons.

event.download.closed#

event.download.opened#

Download item was closed / opened.

event.download.paused#

event.download.resumed#

Download item was paused / resumed.

event.download.hash_done#

event.download.hash_failed#

event.download.hash_final_failed#

TODO

event.download.hash_queued#

event.download.hash_removed#

TODO

event.download.inserted#

event.download.inserted_new#

event.download.inserted_session#

inserted is always called when an item is added to the main downloads list. After that, inserted_session is called when the source of that item is the session state (on startup), or else inserted_new is called for items newly added via a load command.

event.download.finished#

Download item is complete.

event.download.erased#

Download item was removed.

Scheduling Commands#

The scheduling commands define tasks that call another command or list of commands repeatedly, just like a cron job, but with a resolution of seconds.

schedule2#

schedule2 = ‹name›, ‹start›, ‹interval›, ((‹command›[, ‹args›…])) ≫ 0
schedule2 = ‹name›, ‹start›, ‹interval›, "‹command›=[‹args›…][ ; ‹command›=…]" ≫ 0

Call the given command(s) every interval seconds, with an initial delay of start seconds after client startup. An interval of zero calls the task once, while a start of zero calls it immediately.

The name serves both as a handle for schedule_remove2, and as an easy way to document what this task actually does. Existing tasks can be changed at any time, just use the same name.

start and interval may optionally use a time format like [dd:]hh:mm:ss. An interval of 07:00:00:00 would mean weekly execution.

Examples:

# Watch directories
schedule2 = watch_start, 11, 10, ((load.start, (cat, (cfg.watch), "start/*.torrent")))
schedule2 = watch_load,  12, 10, ((load.normal, (cat, (cfg.watch), "load/*.torrent")))

# Add day break to console log
# → ( 0:00:00) New day: 20/03/2017
schedule2 = log_new_day, 00:00:00, 24:00:00,\
    "print=\"New day: \", (convert.date, (system.time))"

# … or the equivalent using "new" syntax:
schedule2 = log_new_day, 00:00:05, 24:00:00,\
    ((print, "New day: ", ((convert.date, ((system.time_seconds)) )) ))

schedule_remove2#

schedule_remove2 = ‹name› ≫ 0

Delete an existing task referenced by name from the scheduler. Deleting a non-existing task is not an error.

start_tied#

stop_untied#

close_untied#

remove_untied#

TODO

close_low_diskspace#

close_low_diskspace.normal#

New in master branch.

New in rTorrent-PS version 1.2.

close_low_diskspace = ‹limit› ≫ 0
close_low_diskspace.normal = ‹limit› ≫ 0

This command goes through all active downloads and checks if the storage of each of their files has more free space left than the given limit. The *.normal variant skips download items set to high priority, i.e. only stops items with normal priority and below.

By default, it is scheduled to run every 60 seconds and check for 500 MiB:

schedule2 = low_diskspace,5,60,((close_low_diskspace,500M))

Be aware that the check interval, the space limit, and your maximal bandwidth should fit to each other. Mathematically, limit > interval * bandwidth + buffer should be true, with buffer being the space you really want to be left with if things get tight.

Important

The above means that you should always replace the default schedule by one that fits your individual situation. Especially if your line is faster than 66 Mbit/s.

Items that fail the check are closed, set to hash-failed (i.e. you cannot just start them anymore without a rehash), and get a Low diskspace. message.

Use the following command to check what devices your forcibly stopped items are stored on:

rtcontrol -qorealpath d_hashing_failed=1 \
| xargs --no-run-if-empty -d$'\n' df -h \
| sort -ru

Importing Script Files#

import#

try_import#

import = ‹rc-file-path› ≫ 0
try_import = ‹rc-file-path› ≫ 0

Both of these commands open the given file and execute the contained commands, one per logical line.

Physical lines can be continued by escaping the line end with \. The maximum length is 4096 bytes.

Lines beginning with # are comments.

try_import ignores a missing script file, while import throws an error in that case.

If you’re nesting imports, relative filenames are resolved using system.cwd, and not based on the location of the importing file.

Example:

import = (cat, (cfg.basedir), "_rtlocal.rc")

import.return#

New in version rTorrent-PS 1.1 only.

import.return= ≫ throw('import.return')

Leaves the currently imported file and returns to the level above.

Since this works by throwing an exception, you will see that exception when called outside of an imported file.

Example: Quick toggle of experimental configuration:

Add a commented import.return into a configuration file, above some code you work on, at the very end of the file. Remove the # to test that code, put it back to ignore your experiment.

#import.return=
‹here be dragons›

Example: Protecting imports that use new features:

First, protect the import like this (to make it compatible with older builds):

branch=(system.has, "import.return="), ((import, using-math-stuff.rc))

Then in the using-math-stuff.rc file, you can return when certain capabilities are missing.

branch=(not, (system.has, "math.add=")), ((import.return))

You can do this incrementally ordered from older to younger capabilities, using exactly those features a build has to offer.

Conditions (if/branch/do)#

branch#

if#

branch = ‹condition-cmd›, ‹then-cmds›[, ‹else-cmds›] ≫ 0
if = ‹condition›, ‹then-cmds›[, ‹else-cmds›] ≫ 0

Both of these commands take a predicate, and based on its value execute either the command or commands given as the 2nd argument, or else the ones in the 3rd argument. See Conditional Operators below for details on these predicates, and do for calling several commands in ‘new’ syntax as the then or else part.

The fundamental difference between branch and if is the first takes commands to evaluate for the predicate, the latter expects values.

See the following examples for details, these are easier to understand than long-winded explanations. Take note of the different forms of Escaping needed when the then/else commands themselves take arguments.

And always consider adding additional helper methods when you have complex multi-command then or else arguments, because escaping escalates fast. You also must use double parentheses if you use those, because otherwise both then and else are already evaluated when the branch/if itself is, which defeats the whole purpose of the conditional.

# Toggle a value between 0 and 1
method.insert.value = foobar, 0
method.insert = foobar.toggle, simple, \
    "branch=(foobar), ((foobar.set, 0)), ((foobar.set, 1))"

Using branch=foobar=, … is equivalent, just using the older command syntax for the condition.

$ rtxmlrpc branch '' greater=value=2,value=2 cat=YES cat=NO
NO
$ rtxmlrpc branch '' greater=value=4,value=2 cat=YES cat=NO
YES

TODO: More examples, using or/and/not and other more complex constructs.

do#

New in version rTorrent-PS 1.1 only.

do = ‹cmd1›, [, ‹cmd2›…] ≫ 0

The do command behaves just like the vanilla catch command, the only difference being that it doesn’t catch exceptions.

It can be used to group a sequence of commands in ‘new’ syntax, for execution as the then or else command of if or branch.

Otherwise you’d need to use "cmd1=… ; cmd2=…; …" for such a sequence, with all the usual escaping problems when calling commands with several arguments.

Examples:

branch = (system.has, "do="), \
    ((do, \
        ((print, "Just")), \
        ((print, "DO")), \
        ((print, "it!")) \
    )), \
    ((print, "Awwwwww!"))

Conditional Operators#

false#

Ignores any amount of arguments, and always returns 0.

and#

or#

not#

TODO

less#

equal#

greater#

less = ‹cmd1›[, ‹cmd2›] ≫ bool (0 or 1)
equal = ‹cmd1›[, ‹cmd2›] ≫ bool (0 or 1)
greater = ‹cmd1›[, ‹cmd2›] ≫ bool (0 or 1)

The comparison operators can work with strings or values (integers), returned from the given command(s). The most common form is with one provided command, that is then called for a target (e.g. with view.filter) or a target pair (e.g. view.sort_new or view.sort_current).

Consider this example, where items are sorted by comparing the names of target pairs, and the less command is called by a typical sorting algorithm:

view.sort_new     = name,((less,((d.name))))
view.sort_current = name,((less,((d.name))))

An example for a filter with two commands returning integer values is the important view, showing only items with a high priority:

view.add = important
ui.current_view.set = important
method.insert = prio_high, value|const|private, 3
view.filter = important, "equal=d.priority=,prio_high="

When two commands are given, their return types must match, and each command is called with the target (or the left / right sides of a target pair, respectively).

As you can see above, to compare against a constant you have to define it as a command. If you run rTorrent-PS, you can use value instead.

For strings, you can use cat as the command, and pass it the text literal.

view.filter = important, ((not, ((equal, ((d.throttle_name)), ((cat)) )) ))
view.filter = important, ((equal, ((d.throttle_name)), ((cat, NULL)) ))

Looks strange, like so many things in rTorrent scripting. The first filter shows all items that have any throttle set, i.e. have a non-empty throttle name. ((cat)) is the command that returns that empty string we want to compare against. The second filter selects items that have the special unlimited throttle NULL set.

match#

New in version 0.9.8.

match = list {‹cmd›, ‹regexp›} ≫ bool (0 or 1)

match takes a 2-element list, of a command that returns a string, and a regexp to compare that string to. If it’s a match, it returns 1, otherwise 0. Note that it expects the entire string to match the regex.

Example:

$ # Note that the leading [ is how rtxmlrpc denotes a list
$ rtxmlrpc match '' '[cat=foobar,.*bar'
1
$ rtxmlrpc match '' '[cat=foo,.*bar'
0
$ rtxmlrpc match '' '[cat=barfoo,.*bar'
0

elapsed.greater#

elapsed.less#

elapsed.greater = ‹start-time›, ‹interval› ≫ bool (0 or 1)
elapsed.less = ‹start-time›, ‹interval› ≫ bool (0 or 1)

Compare time elapsed since a given timestamp against an interval in seconds. The timestamps are UNIX ones, like created by system.time_seconds. The result is 0 if the timestamp is empty / zero.

Example:

method.insert.value = cfg.seed_seconds, 259200
schedule2 = limit_seed_time, 66, 300, "d.multicall.filtered = started,\
    \"elapsed.greater = (d.timestamp.finished), (cfg.seed_seconds)\",\
    d.try_stop="

What this does is stop any item finished longer than 3 days ago (selected via d.multicall.filtered), unless it is set to ignore commands (d.try_stop checks the ignore flag before stopping).

compare#

New in version rTorrent-PS 1.1 only.

compare = ‹order›, ‹sort_key›=[, ...] ≫ bool (0 or 1)

Compares two items like less or greater, but allows to compare by several different sort criteria, and ascending or descending order per given field.

The first parameter is a string of order indicators, either one of aA+ for ascending or dD- for descending. The default, i.e. when there’s more fields than indicators, is ascending.

Field types other than value or string are treated as equal (or in other words, they’re ignored). If all fields are equal, then items are ordered in a random, but stable fashion.

Example: Sort a view by message and name:

view.add = messages
view.filter = messages, ((d.message))
view.sort_new = messages, "compare=,d.message=,d.name="

String Functions#

cat#

cat = string ‹text›[,…] ≫ string
cat={"list", "of", "text"}[,…] ≫ string

cat takes a list of object arguments, or an array of objects, and smushes them all together with no delimiter (see string.join for the variant with a delimiter).

Note that cat can be used to feed strings into the parser that are otherwise not representable, like passing an empty string where a command is expected via (cat,), or text starting with a dollar sign using (cat,{$}).

Example:

print=(cat, text\ or\ , {"array", " of", " text"})

will print (HH:MM:SS) text or array of text to the console.

string.len#

New in version rTorrent-PS 1.1 only.

string.len = string ‹text› ≫ value ‹length›

Returns the length of an UTF-8 encoded string in terms of Unicode characters.

Examples:

string.equals#

string.startswith#

string.endswith#

New in version rTorrent-PS 1.1 only.

string.equals = ‹text›, ‹other›[, …] ≫ bool (0 or 1)
string.startswith = ‹text›, ‹prefix›[, …] ≫ bool (0 or 1)
string.endswith = ‹text›, ‹tail›[, …] ≫ bool (0 or 1)

Checks whether the first argument is equal to, starts with, or ends with another string.

If you pass more than two arguments, any match with the 2nd to last argument will return true (1).

Examples:

# Show ETA column only on 'active' and 'leeching' views
method.set_key = event.view.show, ~eta_toggle, \
    "branch = \"string.equals=$ui.current_view=, active, leeching\", \
        ui.column.show=533, ui.column.hide=533"

string.contains#

string.contains_i#

New in version rTorrent-PS 1.1 only.

string.contains[_i] = ‹haystack›, ‹needle›[, …] ≫ bool (0 or 1)

Checks if a given string contains any of the strings following it. The variant with _i is case-ignoring, but only works for pure ASCII needles.

Example:

$ rtxmlrpc d.multicall.filtered '' 'string.contains_i=(d.name),Mate' d.name=
['sparkylinux-4.0-x86_64-mate.iso']

string.substr#

New in version rTorrent-PS 1.1 only.

string.substr = ‹text›[, ‹pos›[, ‹count›[, ‹count›]]] ≫ string

Returns part of an UTF-8 encoded string. The positional arguments can be passed as either strings (base 10) or values, and they count Unicode characters. A negative pos is relative to the end of the string.

When pos is outside the string bounds (including ‘at the end’), then pos is returned when provided, instead of an empty string.

Examples:

string.shorten#

New in version rTorrent-PS 1.2 only.

string.shorten = ‹text›[, ‹maxlen›[, ‹tail›]] ≫ string

Returns a condensed version of a UTF-8 encoded string, no longer than maxlen, by replacing a middle piece of it with … if necessary. The length arguments can be passed as either strings (base 10) or values, and they count Unicode characters.

tail determines the maximal length of the trailing part, with a default of 5.

Examples:

string.join#

New in version rTorrent-PS 1.1 only.

string.join = ‹delim›[, ‹object›[, …]] ≫ string

Works just like cat (including conversion of the passed objects to strings), but concatenates the arguments using a provided delimiter.

Examples:

string.split#

New in version rTorrent-PS 1.1 only.

string.split = ‹text›, ‹delim› ≫ array of string (parts)

Splits an UTF-8 encoded string into parts delimited by the 2nd argument. If that delimiter is the empty string, you’ll get a Unicode character array of the first argument.

Examples:

string.lpad#

string.rpad#

New in version rTorrent-PS 1.1 only.

string.lpad = ‹text›, ‹padlen›[, ‹padding›] ≫ string
string.rpad = ‹text›, ‹padlen›[, ‹padding›] ≫ string

Pad a string at the start or end, to the required padding length (counting UTF-8 code points). Strings longer than the padding length are returned unchanged. If no padding string is provided or if it is empty, a single space is assumed.

The first argument can also be of type value, since zero-padding numbers is a common use-case. Note that for numbers that might be negative, only padding with spaces makes sense.

Examples:

string.strip#

string.lstrip#

string.rstrip#

New in version rTorrent-PS 1.1 only.

string.strip = ‹text›[, ‹strippable›[, …]] ≫ string
string.lstrip = ‹text›[, ‹head›[, …]] ≫ string
string.rstrip = ‹text›[, ‹tail›[, …]] ≫ string

Strips a string on both sides, or its left / right side only.

If no additional arguments are passed, whitespace is removed (as defined by C++ std::isspace).

Additional arguments define segments that can be removed on the side(s) handled by the specific command. Their order is of no importance, segments are removed until none of them fits anymore, or the final result is empty.

Examples:

string.map#

string.replace#

New in version rTorrent-PS 1.1 only.

string.map = ‹text›, {‹old›,‹new›}[, …] ≫ string
string.replace = ‹text›, {‹old›,‹new›}[, …] ≫ string

string.map scans a list of replacement pairs for an old text that matches all of the given string, and replaces it by new.

string.replace substitutes any occurrence of the old text by the new one.

Examples:

$ rtxmlrpc string.map '' 'foo' [foo,bar [bar,baz
baz

$ rtxmlrpc string.replace '' "it's like 1" [1,2ic [2,ma3 [3,g
it's like magic

$ rtxmlrpc -i 'print = (string.map, (cat, (value,1)), {0,off}, {1,low}, {2,""}, {3,high})'
# prints 'low' as a console message, this is how you map integers

Array Functions#

array.at#

New in version rTorrent-PS 1.1 only.

array.at = ‹array›, ‹pos› ≫ ‹element›

TODO

Examples:

Math Functions#

Most of these commands are available in rTorrent-PS 1.1+, in rTorrent-PS-CH, and rTorrent 0.9.7+. Deviations are explicitly noted.

Values can either be of type value or string – strings are automatically converted, with an error thrown when the string contains something other than digits.

The handled values are restricted to integer arithmetic (as in bash), because rTorrent has no floating point type. Division, average, and median always round down.

All commands support multiple arguments, including lists. List arguments are handled recursively, as-if there were a nested math.* call of the same type, with the list as its arguments.

When using multiple list arguments, or mixing them with plain numbers, this can lead to unexpected results with non-commutative operators, see the math.sub examples below.

math.add#

math.sub#

math.mul#

math.div#

math.mod#

Basic arithmetic operators (+, -, *, /, %).

These share the same code, so the errors shown in the following examples usually apply to all commands, and are not repeated for each operator.

Examples:

math.min#

math.max#

math.cnt#

math.avg#

math.med#

Functions to calculate the minimum, maximum, element count, average, or median over the input values.

Examples:

Value Conversion & Formatting#

The to_* forms are deprecated and are only provided for reference.

convert.kb#

convert.mb#

convert.xb#

to_kb#

to_mb#

to_xb#

convert.kb = ‹value› ≫ string
convert.mb = ‹value› ≫ string
convert.xb = ‹value› ≫ string

Converts a value to KiB, MiB, or XiB string respectively, where X is the most appropriate prefix from K, M, G, T or the value itself.

convert.date#

convert.elapsed_time#

convert.gm_date#

convert.gm_time#

convert.time#

to_date#

to_elapsed_time#

to_gm_date#

to_gm_time#

to_time#

TODO

convert.throttle#

to_throttle#

TODO

convert.time_delta#

New in version rTorrent-PS 1.1 only.

convert.time_delta = ‹timestamp›[, ‹timebase›] ≫ string

Converts the difference of two timestamps into an approximate but short and human readable representation (the result is always 5 chars wide).

If timestamp is zero, the result is ⋅␣⋅⋅␣. If timebase is missing or zero, the current time is used instead.

Examples:

convert.human_size#

New in version rTorrent-PS 1.1 only.

convert.human_size = ‹bytes›[, ‹format›] ≫ string

Converts a size in bytes to a compact, human readable string. See also convert.xb for a similar command.

Format is a number (default 2), with these values:

0: use 6 chars (one decimal place)
1: just print the rounded value (4 chars)
2: combine the two formats into 4 chars by rounding for values >= 9.95
+8: adding 8 converts zero values to whitespace of the correct length

Examples:

$ rtxmlrpc --repr convert.human_size '' +970 +0
'  0.9K'
$ rtxmlrpc --repr convert.human_size '' +970 +1
'  1K'
$ rtxmlrpc --repr convert.human_size '' +970 +10
'0.9K'
$ rtxmlrpc --repr convert.human_size '' +0 +2
'0.0K'
$ rtxmlrpc --repr convert.human_size '' +0 +10
'    '

convert.magnitude#

New in version rTorrent-PS 1.1 only.

convert.magnitude = ‹number› ≫ string

Converts any positive number below 10 million into a very compact string representation with only 2 characters. Above 99, only the first significant digit is retained, plus an order of magnitude indicator using roman numerals (c = 10², m = 10³, X = 10⁴, C = 10⁵, M = 10⁶). Zero and out of range values are handled special (see examples below).

Examples:

$ rtxmlrpc convert.magnitude '' +0
 ·
$ rtxmlrpc convert.magnitude '' +1
 1
$ rtxmlrpc convert.magnitude '' +99
99
$ rtxmlrpc convert.magnitude '' +100
1c
$ rtxmlrpc convert.magnitude '' +999
9c
$ rtxmlrpc convert.magnitude '' +1000
1m
$ rtxmlrpc convert.magnitude '' +9999999
9M
$ rtxmlrpc convert.magnitude '' +10000000
♯♯
$ rtxmlrpc -- convert.magnitude '' -1
♯♯

value#

New in version 0.9.8.

New in rTorrent PS version 1.1.

value = ‹number›[, ‹base›] ≫ value

Converts a given number with the given base (or 10 as the default) to an integer value.

Examples:

$ rtxmlrpc -qi 'view.filter = rtcontrol, "equal = d.priority=, value=3"'
# the 'rtcontrol' view will now show all items with priority 'high'
$ rtxmlrpc --repr value '' 1b 16
27
$ rtxmlrpc --repr value '' 1b
ERROR    While calling value('', '1b'): <Fault -503: 'Junk at end of number: 1b'>

Logging, Files, and OS#

execute.* commands#

Call operating system commands, possibly catching their output for use within rTorrent.

Note

The .bg variants detach the child process from the rTorrent parent, i.e. it runs in the background. This must be used if you want to call back into rTorrent via XMLRPC, since otherwise there will be a deadlock.

throw means to raise an error when the called command fails, while the nothrow variants will return the exit code.

execute.throw#

execute.throw.bg#

execute2#

execute.throw[.bg] = string command, string arg1, string arg2, ... ≫ 0

This will execute a system command with the provided arguments. These commands either raise an error or return 0. execute2 is the same as execute.throw, and should be avoided.

Since internally spawn is used to call the OS command, the shell is not involved and things like shell redirection will not work here. There is also no reason to use shell quoting in arguments, just separate them by commas. If you need shell features, call bash -c "‹command›" like shown in this example:

# Write a PID file into the session directory
execute.throw = sh, -c, (cat, "echo >", (session.path), "rtorrent.pid", " ", (system.pid))

Note that the result of the (cat, …) command ends up as a single argument passed on to bash.

execute.nothrow#

execute.nothrow.bg#

execute.nothrow[.bg] = string command, string arg1, string arg2, ... ≫ value ‹exit status›

Like execute.throw, but return the command’s exit code (warning: due to a bug the return code is shifted by 8 bits, so 1 becomes 0x100).

The .bg variant will just indicate whether the child could be successfully spawned and detached.

execute.capture#

execute.capture_nothrow#

execute.capture[_nothrow] = string command, string arg1, string arg2, ... ≫ string ‹stdout›

Like execute.[no]throw, but returns the command’s standard output. The nothrow variant returns any output that was written before an error, in case one occurs. The exit code is never returned.

Note that any line-endings are included, so if you need a plain string value, wrap the command you want to call into an echo -n command:

method.insert = log_stamp, private|simple,\
    "execute.capture_nothrow = bash, -c, \"echo -n $(date +%Y-%m-%d-%H%M%S)\""

execute.raw#

execute.raw.bg#

execute.raw_nothrow#

execute.raw_nothrow.bg#

The execute.raw variants function identically to other execute.* commands, except that a tilde in the path to the executable is not expanded.

system.* commands#

Commands related to the operating system and the XMLRPC API.

system.listMethods#

system.methodExist#

system.methodHelp#

system.methodSignature#

system.getCapabilities#

system.listMethods ≫ list[string] ‹methods›
system.methodExist = string ‹method› ≫ bool (0 or 1)
system.methodHelp = string ‹method› ≫ string ‹help›
system.methodSignature = string ‹method› ≫ string ‹signature›
system.getCapabilities ≫ list[string] ‹capabilities›

XML-RPC introspection methods. For more information, see XML-RPC Introspection. Note that no help or signature is currently defined for rTorrent-specific commands.

system.capabilities#

system.capabilities ≫ list[string] ‹capabilities›

This returns protocol and version information about the XML-RPC interface implementation. See xmlrpc-c system.capabilities for more.

system.multicall#

Similar to d.multicall2, this allows multiple commands to be sent in one request. Unlike d.multicall2, this is a generic multicall not specific to rTorrent. See the xmlrpc-c system.multicall docs for more.

system.daemon#

system.daemon.set#

New in version 0.9.7.

When set to true, rTorrent starts in the background without any ncurses UI. It can then only be controlled via XMLRPC commands and POSIX signals.

See Daemon Mode in the rTorrent wiki for more.

system.shutdown.normal#

system.shutdown.quick#

New in version 0.9.7.

Shut down rTorrent gracefully. The normal version waits for BitTorrent stop events to be sent to trackers of all active items, while the quick version does not.

In older versions of rTorrent, the only way to shut down the client without using ^Q in the terminal UI is to send a signal:

POSIX Signal Handling

SIGINT and SIGHUP act like system.shutdown.normal, while SIGTERM is equivalent to system.shutdown.quick. SIGHUP support exists in rTorrent-PS and since rTorrent 0.9.7.

SIGWINCH causes a forced canvas redraw.

SIGPIPE is generally ignored, and SIGUSR1 ‘does nothing’.

SIGSEGV, SIGILL, and SIGFPE cause a panic, meaning things are cleaned up if possible, before exiting the client. Also a stack dump is created, if that was enabled during compilation.

SIGBUS behaves almost the same as SIGSEGV (exits the client), but also prints some additional information regarding the signal reason, like Invalid address alignment or Non-existent physical address.

system.shutdown#

This shuts down the XMLRPC server, but does not shut down rTorrent. It’s a built-in of the xmlrpc-c library.

system.api_version#

system.client_version#

system.library_version#

system.api_version ≫ string ‹version›
system.client_version ≫ string ‹version›
system.library_version ≫ string ‹version›

The versions of the XMLRPC API, the rTorrent client, and the libtorrent library respectively. The client and library versions are currently tightly coupled, while system.api_version is incremented whenever changes are made to the XMLRPC API.

system.client_version.as_value#

New in rTorrent-PS 1.1+ only

system.client_version.as_value ≫ value ‹Mmmpp version decimal›

Returns the same information as system.client_version, but instead of a dotted string you get an integer number that can be easily compared in version checks.

system.has should be preferred though to write configuration that works across some client version range.

Example:

$ rtxmlrpc --repr system.client_version.as_value
906
$ rtxmlrpc --repr system.client_version
'0.9.6'

system.colors.enabled#

system.colors.max#

system.colors.rgb#

# rTorrent-PS only
system.colors.enabled ≫ bool (0 or 1)
system.colors.max ≫ value ‹colors›
system.colors.rgb ≫ value

Returns some ncurses system state related to colors (in rTorrent-PS only).

system.cwd#

system.cwd.set#

system.cwd ≫ string ‹path›
system.cwd.set = string ‹path› ≫ 0

Query or change the current working directory of the running process. This will affect any relative paths used after the change, e.g. in schedules.

system.env#

New in version 0.9.7.

New in rTorrent-PS 0.X

system.env = ‹varname› ≫ string ‹env-value›

Query the value of an environment variable, returns an empty string if $varname is not defined.

Example:

session.path.set = (cat, (system.env, RTORRENT_HOME), "/.session")

system.file.allocate#

system.file.allocate.set#

system.file.allocate ≫ bool (0 or 1)
system.file.allocate.set = bool (0 or 1) ≫ 0

Controls whether file pre-allocation is enabled. If it is, and file allocation is supported by the file system, the full amount of space required for a file is allotted immediately when an item is started. Otherwise space is used only when data arrives and must be stored.

system.file.max_size#

system.file.max_size.set#

See d.max_file_size.

system.file.split_size#

system.file.split_size.set#

system.file.split_suffix#

system.file.split_suffix.set#

TODO

system.file_status_cache.prune#

system.file_status_cache.size#

system.file_status_cache.size ≫ value ‹size›
system.file_status_cache.prune ≫ 0

Used when loading metafiles from a directory/glob, this helps prevent rTorrent from trying to load the same file multiple times, especially when using watch directories.

system.files.closed_counter#

system.files.failed_counter#

system.files.opened_counter#

system.files.closed_counter ≫ value ‹closed›
system.files.failed_counter ≫ value ‹failed›
system.files.opened_counter ≫ value ‹opened›

Return the number of files which were closed, failed to open, and were successfully opened respectively.

system.has#

system.has.list#

New in rTorrent-PS 1.1+ only

system.has = ‹capability› ≫ bool (0 or 1)
system.has.list = ≫  list[string] ‹capabilities›

This can be used to write configuration files that work on older builds (and on vanilla rTorrent), even when new features and commands are introduced.

The system.has.list command returns a list of non-method capabilities the running client has on board.

$ rtxmlrpc --repr system.has.list
['canvas_v2', 'colors', 'rtorrent-ps', 'system.has']

If a method name (ending in =) is passed, the call returns true when that method is already defined. The XMLRPC command system.methodExist is similar, but cannot be used from within rTorrent and its configuration.

$ rtxmlrpc system.has '' system.has=
1
$ rtxmlrpc system.has '' cute.kittens=
0

To make sure the system.has command can be actually used, add this somewhere early in your configuration:

# `system.has` polyfill (the "false=" silences the `catch` command, in rTorrent-PS)
catch = {"false=", "method.redirect=system.has,false"}

The following branch somehow self-absorbedly shows how this can be used:

branch=(system.has, system.has), ((print, "Your build can haz system.has!"))

In a vanilla rTorrent, there is silence, and zero capabilities.

A very practical use-case is auto-detection of rTorrent-PS 1.1+:

# `system.has` polyfill (the "false=" silences the `catch` command, in rTorrent-PS)
catch = {"false=", "method.redirect=system.has,false"}

# Set "pyro.extended" to 1 to activate rTorrent-PS features!
method.insert = pyro.extended, const|value, (system.has, rtorrent-ps)

It’s also especially useful in combination with a branched import, so whole snippets using new features are safe and don’t blow up in older builds. Or conditionally backfill something missing in older builds, like in this example:

# Define default columns for older rTorrent-PS builds
branch=(not, (system.has, canvas_v2)), ((import, rtorrent.d/05-rt-ps-columns.rc.include))

system.has.private_methods#

system.has.public_methods#

New in rTorrent-PS 1.1+ only

system.has.private_methods ≫ list[string] ‹method names›
system.has.public_methods ≫ list[string] ‹method names›

The system.has.private_methods and system.has.public_methods commands return a list of private / public methods, either built-in or defined via configuration. Private means a method is not callable via XMLRPC.

system.has.public_methods returns almost the same result as system.listMethods – what’s missing is the built-in methods of xmlrpc-c (see the example below).

Both these commands are only useful for things like comparing the lists generated by different client versions, or checking the completeness of this reference.

$ rtxmlrpc system.has.private_methods | wc -l
112
$ rtxmlrpc system.has.public_methods | wc -l
818
$ ( rtxmlrpc system.has.public_methods ; rtxmlrpc system.has.private_methods ) \
  | sort | uniq -c | awk '{print $1}' | sort | uniq -c
    930 1
$ ( rtxmlrpc system.has.public_methods ; rtxmlrpc system.listMethods ) \
  | sort | uniq -c | egrep -v '^ +2 ' | awk '{print $2}'
system.capabilities
system.getCapabilities
system.listMethods
system.methodExist
system.methodHelp
system.methodSignature
system.multicall
system.shutdown

system.hostname#

system.hostname ≫ string ‹hostname›

Returns the hostname of the system.

system.pid#

system.pid ≫ value ‹pid›

Returns the main process ID of the running client.

system.random#

New in rTorrent-PS 1.0+ only

system.random = [[‹lower›,] ‹upper›] ≫ value

Generate uniformly distributed random numbers in the range defined by lower … upper.

The default range with no args is 0 … RAND_MAX. Providing just one argument sets an exclusive upper bound, and two args define an inclusive range.

An example use-case is adding jitter to time values that you later check with elapsed.greater, to avoid load spikes and similar effects of clustered time triggers.

system.time#

system.time_seconds#

system.time_usec#

system.time ≫ value ‹time›
system.time_seconds ≫ value ‹time›
system.time_usec ≫ value ‹time›

Returns the system times in epoch notation. system.time_usec returns the value in microseconds instead of seconds. system.time is essentially an alias for system.time_seconds.

TODO Is there any practical difference when using the cached system.time?

system.umask.set#

system.umask.set ≫ value ‹time›

Set the umask for the running rTorrent process.

log.* commands#

log.add_output#

log.add_output = string ‹scope›, string ‹name› ≫ 0

This command adds another logging scope to a named log file, opened by one of the log.open_file commands.

Log messages are classified into groups (connection, dht, peer, rpc, storage, thread, torrent, and tracker), and have a level of critical, error, warn, notice, info, or debug.

Scopes can either be a whole level, or else a group on a specific level by using ‹group›_‹level› as the scope’s name.

Example:

log.add_output = tracker_debug, tracelog

log.close#

New in version 0.9.8.

log.close = string ‹name› ≫ 0

Removes all outputs from the named log, and closes the file. To ‘close’ a log prior to 0.9.8, bind it to /dev/null.

log.execute#

log.execute = string ‹path› ≫ 0

(Re-)opens a log file that records commands called via execute.* commands, including their return code and output. This can grow large quickly, see Log Rotation, Archival, and Pruning for how to manage this and other log files.

Passing an empty string closes the file (but be aware of issue #743, only fixed in 0.9.8+ / PS 1.1).

Example:

log.execute = (cat, (cfg.logs), "execute.log")

log.xmlrpc#

log.xmlrpc = string ‹path› ≫ 0

(Re-)opens a log file that contains a log of commands executed via XMLRPC. This logs the raw SCGI and XMLRPC call and response for each request. The file can get huge quickly, see Log Rotation, Archival, and Pruning for how to manage this and other log files.

Passing an empty string closes the file.

Example:

log.xmlrpc = (cat, (cfg.logs), "xmlrpc.log")

log.open_file#

log.open_gz_file#

log.open_file_pid#

log.open_gz_file_pid#

log.open_file = string ‹name›, string ‹log file path›[, string ‹scope›…] ≫ 0
log.open_gz_file
log.open_file_pid
log.open_gz_file_pid

All these commands open a log file, giving it a name to refer to. Paths starting with ~ are expanded. You can immediately add some logging scopes, see log.add_output for details on those.

The pid variants add the PID of rTorrent at the end of the file name (see Log Rotation, Archival, and Pruning for a way better scheme for log separation). Adding gz opens the logfile directly as a compressed streams, note that you have to add an appropriate extension yourself.

There is an arbitrary limit on the number of log streams you can open (64 in 0.9.6). The core of the logging subsystem is implemented in torrent/utils/log of libtorrent.

You can re-open existing logs in rTorrent-PS 1.1+ (and maybe in rTorrent 0.9.7+), by just calling an open command with a new path. To close one, see log.close.

Example:

log.open_file_pid = tracker, /tmp/tracker.log, tracker_debug
# … opens '/tmp/tracker.log.NNNNN' for debugging tracker announces etc.

Warning

Compressed log files do not seem to work, in version 0.9.6 at least.

log.vmmap.dump#

log.vmmap.dump = string ‹dump file path› ≫ 0

Dumps all memory mapping regions to the given file, each line contains a region in the format ‹begin›-‹end› [‹size in KiB›k].

log.messages#

rTorrent-PS 0.x+ only

log.messages = string ‹log file path› ≫ 0

(Re-)opens a log file that contains the messages normally only visible on the main panel and via the l key. Each line is prefixed with the current date and time in ISO8601 format. If an empty path is passed, the file is closed.

Example:

log.messages = (cat, (cfg.logs), "messages.log")

Network (Sockets, HTTP, XMLRPC)#

network.* commands#

bind#

network.bind_address#

network.bind_address.set#

network.bind_address ≫ string ‹address›
network.bind_address.set = string ‹address› ≫ 0

Allows binding to a specific interface. This option can only be set at startup. bind is an alias for network.bind_address.

network.http.dns_cache_timeout#

network.http.dns_cache_timeout.set#

network.http.dns_cache_timeout ≫  value ‹seconds›
network.http.dns_cache_timeout.set = value ‹seconds› ≫ 0

Controls the DNS cache expiry (in seconds) for HTTP requests. The default is 60 seconds.

Set to zero to completely disable caching, or set to -1 to make the cached entries remain forever.

network.http.current_open#

network.http.max_open#

network.http.max_open.set#

network.http.current_open ≫ value ‹num›
network.http.max_open ≫ value ‹max›
network.http.max_open.set = value ‹max› ≫ 0

network.http.current_open returns the number of currently opened HTTP connections, and network.http.max_open determines the upper limit for simultaneous HTTP connections.

Be wary of setting this too high, as even if your connection can support that many requests, the target host may not be able to respond quickly enough, leading to timeouts.

network.http.proxy_address#

network.http.proxy_address.set#

network.http.proxy_address ≫  string ‹address›
network.http.proxy_address.set = string ‹address› ≫ 0

Controls the HTTP proxy for announcements. See the curl proxy documentation for more information.

Related: See network.proxy_address for proxying peer connections.

network.http.cacert#

network.http.cacert.set#

network.http.capath#

network.http.capath.set#

network.http.cacert ≫  string ‹file›
network.http.cacert.set = string ‹file› ≫ 0
network.http.capath ≫  string ‹dir›
network.http.capath.set = string ‹dir› ≫ 0

Allows for controlling which certificates or certificate paths are used for validating HTTPS connections. By default the system certificates are used, so this option is normally only needed for sites that used self-signed or non-standard certificates.

See the curl documentation for more information.

network.http.ssl_verify_host#

network.http.ssl_verify_host.set#

network.http.ssl_verify_peer#

network.http.ssl_verify_peer.set#

network.http.ssl_verify_host ≫ bool (0 or 1)
network.http.ssl_verify_host.set = bool (0 or 1) ≫ 0
network.http.ssl_verify_peer ≫ bool (0 or 1)
network.http.ssl_verify_peer.set = bool (0 or 1) ≫ 0

Determines if how HTTPS connections are validated. By default, both the peer and the host are fully validated. See the curl documentation for SSL_VERIFYHOST and SSL_VERIFYPEER for more information.

network.listen.backlog#

network.listen.backlog.set#

network.listen.backlog ≫ value ‹max›
network.listen.backlog.set = value ‹max› ≫ 0

Sets the max number of pending TCP connections allowed. This defaults to SOMAXCONN, which is 4096 on Linux 5.4+. Note that this is not a limit on how many peers can actively connect.

network.listen.port#

network.listen.port = value ‹port› ≫ 0

Allows controlling what is reported as the incoming port to the tracker. This defaults to whatever port is picked from network.port_range.

ip#

network.local_address#

network.local_address.set#

network.local_address ≫ string ‹address›
network.local_address.set = string ‹address› ≫ 0

This allows binding to a specific network interface. By default it is blank, meaning it will bind to all network interfaces (i.e. 0.0.0.0). ip is an alias for network.local_address

network.max_open_files#

network.max_open_files.set#

network.max_open_files ≫ value ‹max›
network.max_open_files.set = value ‹max› ≫ 0

ontrols the max number of open files allowed by the internal file anager. By default this is calculated dynamically based on the ulimit.

network.max_open_sockets#

network.max_open_sockets.set#

network.open_sockets#

network.max_open_sockets ≫ value ‹max›
network.max_open_sockets.set = value ‹max› ≫ 0
network.open_sockets ≫ value ‹active›

This controls the maximum number of open sockets allowed by the internal connection manager. By default this is calculated dynamically based on ulimit settings. network.open_sockets will return the number of actively open sockets controlled by this setting.

network.port_open#

network.port_open.set#

port_random#

network.port_random#

network.port_random.set#

port_range#

network.port_range#

network.port_range.set#

network.port_open ≫ bool (0 or 1)
network.port_open.set = bool (0 or 1) ≫ 0
network.port_random ≫ bool (0 or 1)
network.port_random.set = bool (0 or 1) ≫ 0
network.port_range ≫  string ‹range›
network.port_range.set = string ‹range› ≫ 0

This set of options controls how the incoming peer port is picked. network.port_open allows for disabling the port entirely, while network.port_range defines the range of ports rTorrent will consider for use. If network.port_random is false, the range will be scanned in sequence until a usable one is found. If no suitable ports are found, rTorrent will fail to start.

port_range is an alias for network.port_range.set. port_random is an alias for network.port_random.set.

network.proxy_address#

network.proxy_address.set#

network.proxy_address ≫  string ‹address›
network.proxy_address.set = string ‹address› ≫ 0

Controls the proxy for peer connections. This uses the CONNECT HTTP 1.0 call to set up the proxied connection, so the target must support proxying with that method. If a port is not set for the address, it is automatically set to 80.

Example:

network.proxy_address.set=proxy.example.com:8080

Note that when setting this to a hostname, a DNS lookup happens during the set, and the command only succeeds if the DNS lookup succeeds as well.

network.receive_buffer.size#

network.receive_buffer.size.set#

network.send_buffer.size#

network.send_buffer.size.set#

network.receive_buffer.size ≫ value ‹size›
network.receive_buffer.size.set = value ‹size› ≫ 0
network.send_buffer.size ≫ value ‹size›
network.send_buffer.size.set = value ‹size› ≫ 0

Sets or gets the maximum socket receive / send buffer in bytes.

On Linux, the default buffer size for receiving data is set by the /proc/sys/net/core/rmem_default file (wmem_default for sending). The maximum allowed value is set by the /proc/sys/net/core/rmem_max file (wmem_max for sending).

See the tuning guide for tweaking these values.

network.scgi.dont_route#

network.scgi.dont_route.set#

network.scgi.dont_route ≫ bool (0 or 1)
network.scgi.dont_route.set = bool (0 or 1) ≫ 0

Enable / disable routing on SCGI connections, directly calling setsockopt to modify the SO_DONTROUTE flag.

scgi_local#

network.scgi.open_local#

scgi_port#

network.scgi.open_port#

network.scgi.open_local = string ‹path› ≫ 0
network.scgi.open_port = string ‹domain_or_ip:port› ≫ 0

Open up a Unix domain socket or a TCP port for SCGI communication (i.e. the XMLRPC socket). Only use one of these!

Warning

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

scgi_local is an alias for network.scgi.open_local. scgi_port is an alias for network.scgi.open_port.

network.tos.set#

network.tos.set = ‹flag› ≫ 0

Set the type of service flag to use in IP packets.

The options as pulled from strings.ip_tos are:

default
lowdelay

throughput
reliability

mincost

default uses the system default setting. A raw hexadecimal value can also be passed in for custom flags.

network.xmlrpc.dialect.set#

network.xmlrpc.dialect.set = value ‹dialect› ≫ 0

Set the XMLRPC dialect to use, as defined by xmlrpc-c. The dialect parameter can have these values:

0 – dialect_generic
1 – dialect_i8
2 – dialect_apache

dialect_i8 is the default value, which means the XMLRPC API will use the xmlrpc-c i8 extension type for returning long integers.

See its documentation for more information on how xmlrpc-c handles dialects.

network.xmlrpc.size_limit#

network.xmlrpc.size_limit.set#

network.xmlrpc.size_limit = ≫ value ‹bytes›
network.xmlrpc.size_limit.set = string ‹max bytes› ≫ 0

Set or return the maximum size of any XMLRPC requests in bytes. Human-readable forms such as 2M are also allowed (for 2 MiB, i.e. 2097152 bytes).

network.history.auto_scale#

network.history.auto_scale.set#

network.history.depth#

network.history.depth.set#

network.history.refresh#

network.history.sample#

Commands to add network traffic charts to the bottom of the collapsed download display.

Add these lines to your configuration:

# rTorrent-PS 0.*+ only!

# Show traffic of the last hour (112*32 = 3584 ≈ 3600)
network.history.depth.set = 112

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="

schedule2 = network_history_sampling, 1, 32, "network.history.sample="
schedule2 = bind_auto_scale, 0, 0,\
    "ui.bind_key=download_list, =, network.history.auto_scale.ui_toggle="

This will add the graph above the footer, 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 base line 0, and a zoomed view that scales it to the current bounds.

ip_tables.* commands#

ip_tables.add_address#
ip_tables.get#
ip_tables.insert_table#
ip_tables.size_data#: TODO

ipv4_filter.* commands#

ipv4_filter.add_address#
ipv4_filter.dump#
ipv4_filter.get#
ipv4_filter.load#
ipv4_filter.size_data#: TODO

Bittorrent Protocol#

dht.* commands#

See the Github wiki for an example of enabling DHT in rTorrent.

dht.add_node#

dht.add_node = string ‹[host]:[port]› ≫ 0

Adds a hostname/port to use for bootstrapping DHT information.

dht.mode.set#

dht#

dht.mode.set = string ‹mode› ≫ 0
dht = string ‹mode› ≫ 0

Controls when (if at all) DHT is activated. Regardless of what this is set to, DHT will never be used for torrents with the “private” flag enabled (see d.is_private). dht is an alias for dht.mode.set.

Possible values are:

on – Start DHT immediately.
off – Do not start DHT.
auto – Start and stop DHT as needed.
disable – Completely disable DHT.

dht.port#

dht.port.set#

dht_port#

dht.port ≫ value ‹port›
dht.mode.set = value ‹port› ≫ 0
dht_port = value ‹port› ≫ 0

Controls which port DHT will listen on. Note that dht_port is an alias for dht.port.set, not dht.port.

dht.statistics#

dht.statistics ≫ dictionary ‹statistics›

Returns {'active': 0, 'dht': 'disable', 'throttle': ''} when DHT is off, and a variety of additional statistics when DHT is enabeld. See the source code for the full list of stats.

dht.throttle.name#

dht.throttle.name.set#

dht.throttle.name ≫ string ‹throttle›
dht.throttle.name.set = string ‹throttle› ≫ 0

Set the name of the throttle to be used for DHT traffic. This can only set before DHT becomes active.

pieces.* commands#

pieces.hash.on_completion#

pieces.hash.on_completion.set#

pieces.hash.on_completion ≫ bool (0 or 1)
pieces.hash.on_completion.set = bool (0 or 1) ≫ 0

When set to true, this triggers a full hash check after a torrent completes. This is not strictly necessary, as hashing already occurs as each piece is downloaded, and turning it off is recommended if you encounter bugs such as completed torrents not announcing properly.

pieces.hash.queue_size#

TODO

pieces.memory.block_count#

pieces.memory.block_count ≫ value ‹blocks›

Returns the number of blocks rTorrent is tracking in memory. TODO What determines block size?

pieces.memory.current#

pieces.memory.current ≫ value ‹bytes›

Returns the amount of memory rTorrent is currently using to track pieces which haven’t yet been synced to a file.

pieces.memory.max#

pieces.memory.max.set#

pieces.memory.max ≫ value ‹bytes›
pieces.memory.max.set = value ‹bytes› ≫ 0

Controls the max amount of memory used to hold chunk information. By default this is set to 1/5 of the available detected memory.

pieces.memory.sync_queue#

pieces.memory.sync_queue ≫ value ‹bytes›

The amount of memory queued to be synced.

pieces.preload.min_rate#

pieces.preload.min_rate.set#

pieces.preload.min_size#

pieces.preload.min_size.set#

pieces.preload.min_rate ≫ value ‹bytes›
pieces.preload.min_rate.set = ‹bytes› ≫ 0
pieces.preload.min_size ≫ value ‹chunks›
pieces.preload.min_size.set = ‹chunks› ≫ 0

Preloading can be controlled to only activate when an item either reaches a certain rate of upload, and when the piece size is greater than a certain amount. Both conditions must be met in order for preloading to occur.

pieces.preload.type#

pieces.preload.type.set#

pieces.preload.type ≫ value ‹type›
pieces.preload.type.set = value ‹type› ≫ 0

When a piece is to be uploaded to a peer, rTorrent can preload the piece of the file before it does the non-blocking write to the network. This will not complete the whole piece if parts of the piece is not already in memory, having instead to try again later.

Possible values for type are:

0 – off
1 – madvise
2 – direct page

Off means it doesn’t do any preloading at all.

madvise means it calls madvise on the file for the specific mmap’ed memory range, which tells the kernel to load it in memory when it gets around to it. Which is hopefully before rTorrent writes to the network socket.

Direct paging means it touches each file page in order to force the kernel to load it into memory. This can help if you’re dealing with very large number of peers and large/many files, especially in a low-memory setting, as you can avoid thrashing the disk where loaded file pages get thrown out before they manage to get sent.

Adapted from

https://github.com/rakshasa/rtorrent/issues/418#issuecomment-211335027

pieces.stats_not_preloaded#

pieces.stats_preloaded#

pieces.stats_not_preloaded ≫ value ‹num›
pieces.stats_preloaded ≫ value ‹num›

This counts the number of pieces that were preloaded or not, as per pieces.preload.min_size and pieces.preload.min_rate. If pieces.preload.type is set to 0, all pieces will be marked as not_preloaded.

pieces.stats.total_size#

pieces.stats.total_size ≫ value ‹bytes›

Returns the total cumulative size of all files in all items. This includes incomplete files and does not consider duplicates, so it will often be larger than the sum of all the files as they exist on the disk.

pieces.sync.always_safe#

pieces.sync.always_safe.set#

pieces.sync.always_safe ≫ bool (0 or 1)
pieces.sync.always_safe.set = bool (0 or 1) ≫ 0

When safe sync is enabled, each chunk is synced to the file synchronously, which is slightly slower but ensures that the file has been written correctly.

pieces.sync.queue_size#

pieces.sync.queue_size ≫ value ‹chunks›

The number of chunks that are queued up for writing in memory (i.e. not written to a file yet).

pieces.sync.safe_free_diskspace#

pieces.sync.safe_free_diskspace ≫ value ‹bytes›

If d.free_diskspace ever drops below this value, all chunks will behave as though pieces.sync.always_safe is set to true. This is set to pieces.memory.current + 512 MiB.

pieces.sync.timeout#

pieces.sync.timeout.set#

pieces.sync.timeout ≫ value ‹seconds›
pieces.sync.timeout.set = value ‹seconds› ≫ 0

If the piece hasn’t been synced within this time period, immediately mark it for syncing.

pieces.sync.timeout_safe#

pieces.sync.timeout_safe.set#

pieces.sync.timeout_safe ≫ value ‹seconds›
pieces.sync.timeout_safe.set = value ‹seconds› ≫ 0

TODO This does not appear to be in use.

protocol.* commands#

protocol.choke_heuristics.down.leech#

protocol.choke_heuristics.down.leech.set#

protocol.choke_heuristics.down.seed#

protocol.choke_heuristics.down.seed.set#

protocol.choke_heuristics.up.leech#

protocol.choke_heuristics.up.leech.set#

protocol.choke_heuristics.up.seed#

protocol.choke_heuristics.up.seed.set#

Warning

The following is only documented for informational purposes. Changing the choke heuristics from the defaults should not be done lightly.

The choke heuristics determine the process by which rTorrent decides which peer to choke/unchoke. There are 4 heuristics at play, each with a choke and unchoke weight process:

upload_leech choke: weight according to our download rate from them
upload_leech unchoke: weight according to our download rate from them, with a random component for currently choked peers.
upload_seed choke: weight according to our download rate from them
upload_seed unchoke: weight by if the peer is preferred, then randomly in each group
upload_leech_experimental choke: Don’t re-choke peers that have recently been unchoked. Weight preferred peers higher, and then by our download rate from them.
upload_leech_experimental unchoke: weight according to our download rate from them, with a random component for currently choked peers
download_leech choke: weight according to our download rate from them
download_leech unchoke: weight according to our download rate from them

choke_group.tracker.mode#

choke_group.tracker.mode.set#

Does not appear to have any functionality.

protocol.connection.leech#

protocol.connection.leech.set#

protocol.connection.seed#

protocol.connection.seed.set#

TODO

encryption#

protocol.encryption.set#

protocol.encryption.set = string ‹flags› ≫ 0

encryption is an alias for protocol.encryption.set.

This command takes a comma-separated list of flags, as enumerated in strings.encryption, and uses them to determine how to handle connections to other peers (i.e. tracker and DHT connections are not effected by this setting). The flags are all applied simultaneously, which means that certain applied flags may not take effect (e.g. for prefer_plaintext,require_rc4, plaintext will never be used despite the flag being applied). rTorrent has support for both plaintext “encryption” (uses no extra CPU cycles, provides only obfuscation of the header) and RC4 encryption (encrypts the entire header and message, at the cost of a few CPU cycles), with flags to control the behavior of both.

none – The default, don’t attempt any encryption.
allow_incoming – Allow incoming encrypted connections from other peers.
try_outgoing – Attempt to set up encryption when initiating a connection.
require – Require encryption, and reject peers who don’t support it.
require_RC4 – Require RC4 encryption specifically.
require_rc4 – Same as above.
enable_retry – If a peer is rejected for not supporting the encryption we need, retry the handshake.
prefer_plaintext – Prefer plaintext encryption.

See BitTorrent protocol encryption for more information.

protocol.pex#

protocol.pex.set#

protocol.pex ≫ bool (0 or 1)
protocol.pex.set = bool (0 or 1) ≫ 0

Controls whether peer exchange is enabled.

throttle.* commands#

Throttles are names for bandwidth limitation rules (for upload, download, or both). The throttle assigned to the item in focus can be changed using Ctrl-T – it will rotate through all defined ones.

There are two system throttles, NULL and the one with an empty name. NULL is a special throttle for unlimited, and the latter is the global throttle, which is the default for new items and what’s shown in the status bar on the left as [Throttle ‹UP›/‹DOWN› KB].

Other commands in this group determine the limits for upload / download slots, and the amount of peers requested in tracker announces.

Warning

Note that since named throttles borrow from the global throttle, the global one has to be set to a non-zero value for the named ones to work (because borrowing from ∞ means there is no limit).

throttle.down#

throttle.up#

throttle.down = string ‹name›, string ‹rate› ≫ 0
throttle.up = string ‹name›, string ‹rate› ≫ 0

Update the throttle name with a new rate. if the throttle does not exist, it will be created. The rate must be a string (important when using XMLRPC), and is always in KiB/s.

throttle.down.max#

throttle.up.max#

throttle.down.max = ‹name› ≫  value ‹limit›
throttle.up.max = ‹name› ≫  value ‹limit›

Get the current limit of a named throttle in bytes/s.

Unknown throttles return -1, unlimited ones 0. If the global throttle is not set, you also get 0 for any call.

throttle.down.rate#

throttle.up.rate#

throttle.down.rate = ‹name› ≫ value ‹rate›
throttle.up.rate = ‹name› ≫ value ‹rate›

Get the current rate of a named throttle in bytes/s, averaged over recent history.

Unknown throttles always return 0. If the global throttle is not set, you also get 0 for any call.

throttle.global_down.max_rate#

throttle.global_down.max_rate.set#

throttle.global_down.max_rate.set_kb#

throttle.global_up.max_rate#

throttle.global_up.max_rate.set#

throttle.global_up.max_rate.set_kb#

Query or change the current value for the global throttle. Always use set_kb to change these values (the set commands have bugs), and be aware that you always get bytes/s when querying them.

throttle.global_down.rate#

throttle.global_up.rate#

throttle.global_down.rate ≫ value ‹rate›
throttle.global_up.rate ≫ value ‹rate›

Current overall bandwidth usage in bytes/s, averaged over recent history.

throttle.global_down.total#

throttle.global_up.total#

throttle.global_down.total ≫ value ‹bytes›
throttle.global_up.total ≫ value ‹bytes›

Amount of data moved over all items, in bytes.

TODO … in this session, including deleted items?

throttle.max_downloads#

throttle.max_downloads.set#

throttle.max_downloads.div#

throttle.max_downloads.div.set#

throttle.max_uploads#

throttle.max_uploads.set#

throttle.max_uploads.div#

throttle.max_uploads.div.set#

throttle.max_downloads.global#

throttle.max_downloads.global.set#

throttle.max_uploads.global#

throttle.max_uploads.global.set#

Default values:

throttle.max_downloads	50
throttle.max_uploads	50
throttle.max_downloads.div	1
throttle.max_uploads.div	1
throttle.max_downloads_global	0
throttle.max_uploads_global	0

TODO

throttle.max_uploads.div._val#

throttle.max_uploads.div._val.set#

throttle.max_downloads.div._val#

throttle.max_downloads.div._val.set#

throttle.max_uploads.global._val#

throttle.max_uploads.global._val.set#

throttle.max_downloads.global._val#

throttle.max_downloads.global._val.set#

The _val variants are for internal use only, and should not be used. Specifically, they ensure the UI is updated to match any new values.

throttle.min_downloads#

throttle.min_downloads.set#

throttle.min_uploads#

throttle.min_uploads.set#

Default values:

throttle.min_downloads	0
throttle.min_uploads	0

Theses are used as the default values for d.downloads_min and d.uploads_min, respectively, when a torrent is created. See those commands for details.

throttle.min_peers.normal#

throttle.min_peers.normal.set#

throttle.max_peers.normal#

throttle.max_peers.normal.set#

throttle.min_peers.seed#

throttle.min_peers.seed.set#

throttle.max_peers.seed#

throttle.max_peers.seed.set#

These control the default values for d.peers_max and d.peers_min when an item is either incomplete (.normal) or complete (.seed). See those terms for a detailed explanation of how the value affect items.

If throttle.min/max_peers.seed is less than 0, it will use the same value as throttle.min/max_peeers.normal.

Default values:

throttle.min_peers.normal	100
throttle.max_peers.normal	200
throttle.min_peers.seed	-1
throttle.max_peers.seed	-1

throttle.unchoked_downloads#

throttle.unchoked_uploads#

TODO

throttle.ip#

throttle.ip = ‹throttle name›, ‹IP or domain name› ≫ 0

Throttle a specific peer by its IP address.

throttle.names#

# rTorrent-PS 1.1+ only
throttle.names= ≫ list[string] ‹names›

Returns a list of all defined throttle names, including the built-in ones (i.e. '' and 'NULL').

Example:

$ rtxmlrpc --repr throttle.names
['', 'NULL', 'kb500', 'lo_up', 'onemb']

User Interface#

ui.* commands#

Commands in this group control aspects of the curses UI.

ui.current_view#

ui.current_view.set#

ui.current_view since rTorrent-PS 0.x / rTorrent 0.9.7

ui.current_view.set = string ‹viewname› ≫ 0
ui.current_view ≫ string ‹viewname›

Query or change the current view the user is seeing. view.list gives you a list of all the built-in and added views.

Typical uses are to change and then restore the active view, or rotate through a set of views. Rotating through views requires querying the current view and the view list, to find the next one.

In rTorrent-PS 1.1+ and rTorrent 0.9.8+, view changes also trigger event handlers for event.view.hide and event.view.show.

ui.current_view is needed if you want to use a hyphen - as a view name in rtcontrol to refer to the currently shown view. An example for that is passing -M- as an option, which performs in-place filtering of the current view via rtcontrol.

torrent_list_layout#

ui.torrent_list.layout#

ui.torrent_list.layout.set#

since rTorrent 0.9.7

Offers a choice between full and compact layout.

ui.unfocus_download#

Used internally before erasing an item, to move the focus away from it.

ui.bind_key#

ui.bind_key.verbose#

ui.bind_key.verbose.set#

rTorrent-PS 0.x+ / 1.1+ only

# rTorrent-PS 0.x+ only
ui.bind_key = ‹display›, ‹key›, "command=[...]" ≫ 0
# rTorrent-PS 1.1+ only
ui.bind_key.verbose = ≫ bool (0 or 1)
ui.bind_key.verbose.set = ‹mode› (0 or 1) ≫ 0

Binds the given key on a specified display to execute the given command when pressed. Note that this needs to be called in a one-shot schedule, after rTorrent is fully initialized.

display must always be download_list, for the moment (currently, no other displays are supported).

key can be either a single character for normal keys, ^ plus a character for control keys, or a 4 digit octal code for special keys.

The ui.bind_key.verbose flag determines whether replacing an existing binding is logged (1, the default) or not (0).

Configuration Example

# Bind '^' to show the last "rtcontrol" result
schedule2 = bind_view_rtcontrol, 1, 0,\
    "ui.bind_key = download_list, ^, ui.current_view.set=rtcontrol"

Important

This currently can NOT be used immediately when rtorrent.rc is parsed, so it has to be scheduled for one-shot execution, shortly after startup (see above example).

ui.color.custom1…9#

ui.color.alarm#

ui.color.complete#

ui.color.even#

ui.color.focus#

ui.color.footer#

ui.color.incomplete#

ui.color.info#

ui.color.label#

ui.color.leeching#

ui.color.odd#

ui.color.progress0#

ui.color.progress20#

ui.color.progress40#

ui.color.progress60#

ui.color.progress80#

ui.color.progress100#

ui.color.progress120#

ui.color.queued#

ui.color.seeding#

ui.color.stopped#

ui.color.title#

ui.color.‹type›.set#

ui.color.‹type›.index#

New in rTorrent-PS 0.x+ only

ui.color.‹type›= ≫ string ‹color-spec›
ui.color.‹type›.set=‹color-spec› ≫ 0

These commands allow you to set colors for selected elements of the user interface in rTorrent-PS, in some cases depending on their status.

You can either provide colors by specifying the numerical index in the terminal’s color table, or by name (for the first 16 colors). The possible color names are “black”, “red”, “green”, “yellow”, “blue”, “magenta”, “cyan”, “gray”, and “white”.

You can use those names for both text and background color, in the form “‹fg› on ‹bg›”, and you can add “bright” in front of a color to select a more luminous version. If you don’t specify a color, the default of your terminal is used.

Also, these additional modifiers can be placed in the color definitions, but it depends on the terminal you’re using whether they have an effect: “bold”, “standout”, “underline”, “reverse”, “blink”, and “dim”.

The private ui.color.‹type›.index calls return the related ID in the rTorrent-PS color table. These IDs are used in the color definitions C‹id›/‹len› of ui.column.render.

See the color scheme for 256 xterm colors for an example.

ui.canvas_color#

ui.canvas_color.set#

New in rTorrent-PS 1.1+ only

Not working right now.

ui.column.render#

New in rTorrent-PS 1.1+ only

This is a multi-command that holds the column layout specifications for the customizable canvas v2 display in rTorrent-PS version 1.1+, and maps them to their rendering commands.

See Customizing the Display Layout in the rTorrent-PS manual for a detailed explanation.

ui.column.spec#

New in rTorrent-PS 1.1+ only

ui.column.spec = ‹column index› ≫ string (column specification)

For a given column index, looks up the column specification as defined in ui.column.render. This can also be used to check whether a certain index is defined – an undefined one returns an empty string.

Examples

# Permanently remove the 'ignoring commands' column
method.set_key = ui.column.render, (ui.column.spec, 130)

ui.column.hide#

ui.column.show#

ui.column.is_hidden#

ui.column.hidden.list#

New in rTorrent-PS 1.1+ only

ui.column.hide = ‹column index›[, …] ≫ 0
ui.column.show = ‹column index›[, …] ≫ 0
ui.column.is_hidden = ‹column index› ≫ bool (0 or 1)
ui.column.hidden.list = ≫ list[value] ‹column indices›

Hide or show columns by their index. The hide/show commands take any number of arguments, or a list of values.

The ui.column.is_hidden command allows to query the visibility of a column, and the last command returns a list of index values for all hidden columns.

The hidden state is not persisted over client restarts. Also note that some columns are auto-hidden in case the terminal gets too narrow to show all of them.

ui.column.sacrificed#

ui.column.sacrificed.set#

ui.column.sacrificed.toggle#

ui.column.sacrificial.list#

New in rTorrent-PS 1.1+ only

The ui.column.sacrificed value is false (0) by default, and can set set as usual. The ui.column.sacrificed.toggle command changes the state of this value and ui.column.hides or ui.column.shows all the columns that ui.column.sacrificial.list returns (as a list of values).

ui.focus.end#

ui.focus.home#

ui.focus.pgdn#

ui.focus.pgup#

ui.focus.page_size#

ui.focus.page_size.set#

New in rTorrent-PS 0.x+ only

These commands support quick paging through the download list, and jumping to the start or end of it. See bind-navigation-keys.rc on how to use them in a rTorrent-PS configuration.

With the ui.focus.page_size.set command, the amount of items to skip can be changed from the default value of 50, e.g. in the _rtlocal.rc file.

ui.find.term#

ui.find.term.set#

New in version 1.2: rTorrent-PS only

This string variable holds the current search term, and is normally set by entering a value into the Ctrl-F prompt.

When you hit Enter in the find> prompt, the entered text is saved here and then ui.find.next is called.

ui.find.next#

New in version 1.2: rTorrent-PS only

This command is bound to Shift-F and F3 and jumps to the next hit for a non-empty ui.find.term. The search is ignoring case (for ASCII names).

A console message is shown if nothing is found in the current view, or if the view is empty.

ui.input.history.clear#

ui.input.history.size#

ui.input.history.size.set#

New in version 0.9.8.

TODO

ui.style.progress#

ui.style.progress.set#

ui.style.ratio#

ui.style.ratio.set#

Deprecated since version 1.1: rTorrent-PS canvas v2 made these obsolete

ui.throttle.global.step.large#

ui.throttle.global.step.large.set#

ui.throttle.global.step.medium#

ui.throttle.global.step.medium.set#

ui.throttle.global.step.small#

ui.throttle.global.step.small.set#

New in version 0.9.8.

TODO

view.filter.temp#

view.filter.temp.excluded#

view.filter.temp.excluded.set#

view.filter.temp.log#

view.filter.temp.log.set#

New in version 0.9.8.

TODO

view.* commands#

view.add#

view.add = string ‹view-name› ≫ 0

Create a new view with the given name. By default the view contains no items.

view.list#

view.list ≫  list[string]

Returns a list of all the view names.

view.size#

view.size = string ‹view-name› ≫ value

Returns the size of all items in the view.

view.persistent#

view.persistent = string ‹view-name› ≫ 0

Marks the view as persistent. Persistent views are retained across restarts.

view.event_added#

view.event_removed#

TODO

view.filter#

view.filter = string ‹view-name›, string‹filter› ≫ 0

Sets the filter for the view. filter is a function that will be run against each download to determine if it should be included in the view. Note that views will not re-filter themselves automatically, either set up a schedule2, or use view.filter_on to keep the view up to date.

Examples from main.cc:

view.filter = complete,((d.complete))
view.filter = hashing,((d.hashing))

view.filter_all#

view.filter_download#

TODO

view.filter_on#

view.filter_on = string ‹view-name›, string ‹event-name›,... ≫ 0

Tell rTorrent to re-filter the named view on each event-name. event-name may be specified multiple times to allow for re-filtering on multiple different events.

Examples from main.cc:

view.filter_on = hashing,event.download.hash_queued,event.download.hash_removed
view.filter_on = complete,event.download.hash_done,event.download.hash_failed,event.download.hash_final_failed,event.download.finished

view.set#

view.set_visible#

view.set_not_visible#

view.size_not_visible#

TODO

view.sort#

view.sort_current#

view.sort_new#

TODO

view.collapsed.toggle#

# rTorrent-PS 0.*+ only
view.collapsed.toggle=‹view-name› ≫ 0

This command changes between the normal item display, where each item takes up three lines, to a more condensed form exclusive to rTorrent-PS, where each item only takes up one line.

Further explanations on what the columns show and what forms of abbreviations are used, to get a display as compact as possible while still showing all the important stuff, can be found on Extended Canvas Explained. There you also find hints on how to correctly setup your terminal.

Note that each view has its own state, and that if the view name is empty, the current view is toggled. Newly added views are expanded – but in rTorrent-PS 1.1+ the built-in views are collapsed by default.

You can set the default state of views to collapsed in your configuration, by adding a toggle command for each created view.

Also when using rTorrent-PS before version 1.1, you should bind the current view toggle to a key, like this:

schedule = bind_collapse,0,0,"ui.bind_key=download_list,*,view.collapsed.toggle="

Miscellaneous#

strings.* commands#

strings.choke_heuristics#

upload_leech
upload_leech_dummy

download_leech
download_leech_dummy

invalid

strings.choke_heuristics.download#

download_leech

download_leech_dummy

strings.choke_heuristics.upload#

upload_leech

upload_leech_dummy

strings.connection_type#

leech
seed

initial_seed

metadata

strings.encryption#

none
allow_incoming
try_outgoing

require
require_RC4
require_rc4

enable_retry
prefer_plaintext

strings.ip_filter#

unwanted

preferred

strings.ip_tos#

default
lowdelay

throughput
reliability

mincost

Options for network.tos.set.

strings.tracker_mode#

normal

aggressive

strings.tracker_event#

New in version 0.9.7.

completed
scrape

started
stopped

updated

strings.log_group#

New in version 0.9.7.

connection_critical
connection_debug
connection_error
connection_info
connection_notice
connection_warn
critical
debug
dht_all
dht_critical
dht_debug
dht_error
dht_info
dht_manager
dht_node
dht_notice
dht_router
dht_server
dht_warn
error
info
instrumentation_choke
instrumentation_memory
instrumentation_mincore
instrumentation_polling

instrumentation_transfers
__non_cascading__
notice
peer_critical
peer_debug
peer_error
peer_info
peer_list_events
peer_notice
peer_warn
protocol_metadata_events
protocol_network_errors
protocol_piece_events
protocol_storage_errors
resume_data
rpc_dump
rpc_events
socket_critical
socket_debug
socket_error
socket_info
socket_notice
socket_warn
storage_critical
storage_debug

storage_error
storage_info
storage_notice
storage_warn
thread_critical
thread_debug
thread_error
thread_info
thread_notice
thread_warn
torrent_critical
torrent_debug
torrent_error
torrent_info
torrent_notice
torrent_warn
tracker_critical
tracker_debug
tracker_error
tracker_info
tracker_notice
tracker_warn
ui_events
warn

Singular Commands#

These are ‘special’ and fall into no group.

try#

New in version 0.9.8.

try = string ‹command› ≫ 0

This command catches any input errors, and logs them to rpc_events.

Example:

log.open_file=rpc,rpc.log,rpc_events
try="print=(system.client_version)"
try="print=(system.client_versio)"

Both try lines will return 0, but the second line has a typo and will not work, which will trigger an error message in rpc.log.

directory.watch.added#

New in version 0.9.7.

directory.watch.added = ‹root folder path›, ‹handler command name› ≫ 0

On Linux, use this command to watch a directory tree via inotify.

The provided handler command is called with the the full path of new files as the first argument, i.e. argument.0 in a custom handler method. Use method.insert to define such a more complex multi-command handler, and then use its name as the second argument to directory.watch.added.

See Watch Directories in the rTorrent wiki for more.

Configuration Example

directory.watch.added = "~/Downloads/watch/", load.start_verbose

TODO (Groups)#

choke_group

file

group

group2

keys

ratio

scheduler

directory.default#

directory.default.set#

directory#

directory = string ‹path› ≫ 0
directory.default.set = string ‹path› ≫ 0
directory.default ≫ string ‹path›

Sets/gets the default d.directory for new torrents. directory is an alias for directory.default.set.

trackers.disable#

trackers.enable#

trackers.disable = ‹arg› ≫ 0
trackers.enable = ‹arg› ≫ 0

Respectively enables or disables trackers across all downloads. While an argument is required, it is ignored. If trackers.use_udp is false, UDP trackers will not be enabled.

trackers.numwant#

trackers.numwant.set#

trackers.numwant ≫ value ‹numwant›
trackers.numwant.set = value ‹numwant› ≫ 0

Sets the default value for d.tracker_numwant. Defaults to -1.

trackers.use_udp#

trackers.use_udp.set#

trackers.use_udp ≫  bool (0 or 1)
trackers.use_udp.set = bool (0 or 1) ≫ 0

If set to false, newly added torrents will have all UDP trackers set to disabled. It’s still possible to manually enable them afterwards.

trackers.alias.items#

New in version rTorrent-PS-1.1+.

Returns all the mappings in the form ‹domain›=‹alias› as a list.

Note that domains that were not explicitly defined so far, but shown previously, are also contained in the list, with an empty alias. So to create a list for you to fill in the aliases, scroll through all your items on main or trackers, so you can dump the domains of all loaded items.

Example that prints all the domains and their aliases as commands that define them:

rtxmlrpc trackers.alias.items \
    | sed -r -e 's/=/, "/' -e 's/^/trackers.alias.set_key = /' -e 's/$/"/' \
    | tee ~/rtorrent/rtorrent.d/tracker-aliases.rc

This also dumps them into the tracker-aliases.rc file to persist your mappings, and also make them easily editable. To reload edited alias definitions, use this:

rtxmlrpc "try_import=,~/rtorrent/rtorrent.d/tracker-aliases.rc"

trackers.alias.set_key#

Sets an alias that replaces the given domain, when displayed on the right of the collapsed canvas.

trackers.alias.set_key = bttracker.debian.org, Debian

TODO (singles)#

print#
add_peer#
catch#
check_hash#
connection_leech#
connection_seed#
download_rate#
encoding.add#
encoding_list#
key_layout#
max_downloads#
max_downloads_div#
max_downloads_global#
max_memory_usage#
max_peers#
max_peers_seed#
max_uploads#
max_uploads_div#
max_uploads_global#
min_downloads#
min_peers#
min_peers_seed#
min_uploads#
on_ratio#
proxy_address#
upload_rate#
file.append#
file.prioritize_toc#
keys.layout#
keys.layout.set#: TODO
fi.filename_last#
fi.is_file#: Reserved for internal use in the file list screen. Cannot be used via RPC.

‘Intermediate’ Commands#

The intermediate commands are kept around as aliases for ‘new’ ones – at least for the time being. Probably best avoided.

Avoiding the deprecated commands is a must, these will disappear at some time.

method.use_deprecated#

method.use_deprecated.set#

method.use_deprecated ≫ bool (0 or 1)
method.use_deprecated.set = ‹0 or 1› ≫ bool ‹current› (0 or 1)

The default is true. The undocumented -D command line options sets this to false with a Disabled deprecated commands console message.

method.use_intermediate#

method.use_intermediate.set#

method.use_intermediate ≫ value (0 … 2)
method.use_intermediate.set = ‹0 … 2› ≫ value ‹current› (0 … 2)

The default is 1 (allow everywhere), values other than 1 or 2 are treated like 0. The undocumented -I command line options sets this to 0 with a Disabled intermediate commands console message, while -K sets it to 2, printing Allowing intermediate commands without xmlrpc.

All the command aliases can be found in these three source files: command_local.cc, command_throttle.cc, and main.cc. Search for REDIRECT using grep.

These are called intermediate:

execute → execute2 (ignore both, just use execute.throw)
schedule → schedule2
schedule_remove → schedule_remove2
group.‹name›.view → group2.‹name›.view
group.‹name›.view.set → group2.‹name›.view.set
group.‹name›.ratio.min → group2.‹name›.ratio.min
group.‹name›.ratio.min.set → group2.‹name›.ratio.min.set
group.‹name›.ratio.max → group2.‹name›.ratio.max
group.‹name›.ratio.max.set → group2.‹name›.ratio.max.set
group.‹name›.ratio.upload → group2.‹name›.ratio.upload
group.‹name›.ratio.upload.set → group2.‹name›.ratio.upload.set

rTorrent 0.9.7 adds some missing group.seeding.* command aliases.

Standard Configuration Sets#

The following sections explain some major commands added by well-known configuration sets.

If you want other setups (rtinst, QuickBox, …) to be documented, we accept pull requests.

Examples in This Manual#

These commands are from snippets presented in other chapters.

cfg.drop_in#: The directory to import snippets from, see Load ‘Drop-In’ Config Fragments. This is a private command.
event.download.finished_delayed#
event.download.finished_delayed.interval#
event.download.finished_delayed.interval.set#: Events for delayed completion processing, see Delayed Completion Handling for a full explanation.

rTorrent Wiki Template#

The CONFIG Template wiki page defines a few commands in its configuration snippet. See Config Template Deconstructed for a detailed tour.

cfg.basedir#

cfg.watch#

cfg.logs#

These define important base paths in the file system layout of a rTorrent instance, and are all private. They are used where appropriate to define further paths like the session directory, and allow easy changes at just one place.

By default, cfg.watch and cfg.logs are sub-dirs of cfg.basedir.

system.startup_time#

A constant value that holds the system.time when the client was started.

d.data_path#

Return path to an item’s data – this is never empty, unlike d.base_path. Multi-file items return a path ending with a /.

Definition

method.insert = d.data_path, simple,\
    "if=(d.is_multi_file),\
        (cat, (d.directory), /),\
        (cat, (d.directory), /, (d.name))"

pyrocore Configuration#

In addition to the commands listed here, pyrocore also defines d.data_path.

startup_time#

The system.time the client was started at. Used in the message shown by rTorrent-PS when pressing u, and for similar purposes throughout rtcontrol.

This is an alias for system.startup_time.

d.session_file#

Return path to an item’s session file.

Definition

method.insert = d.session_file, simple, "cat=(session.path), (d.hash), .torrent"

d.tracker.bump_scrape#

Send a scrape request for an item, set its tm_last_scrape custom attribute to now, and save the session data. Part of auto-scrape.rc, and bound to the & key in rTorrent-PS, to manually request a scrape update.

d.timestamp.downloaded#

The modification time of the d.tied_to_file, or else system.time. This is set once when an item is newly added to the download list, so a later d.delete_tied does not change it.

d.timestamp.last_xfer#

d.last_xfer.is_active#

pyro.last_xfer.min_rate#

pyro.last_xfer.min_rate.set#

Last time any data was transferred for this item.

pyro.last_xfer.min_rate sets the threshold in bytes below which activity is not counted, and defaults to 5000. Do not set this too low, since there is always some accounting traffic on an item, when peers connect and then are not interested in transferring actual data.

d.last_xfer.is_active checks that threshold against both current upstream and downstream traffic.

Checking is done several times per minute, but very short transfer bursts might not be recorded. Redefine the pyro_update_last_xfer schedule if you want the check to run at a different frequency.

d.watch.start#

d.watch.startable#

cfg.watch.start#

cfg.watch.start.set#

TODO

d.watch.startable is private.

d.category.set#

load.category#

load.category.normal#

load.category.start#

To add an item to a category previously added with pyro.category.add, or move it from its old one, use d.category.set and pass the new category name.

The load commands use this to load items from watch directories named like a category – all items loaded from there are added to the related category view. cfg.watch is used as the root directory which contains the category watch directories. They are private, and all use the equivalent verbose built-in command under the hood. To make starting the new items optional, load.category uses the d.watch.startable mechanism.

The definitions are in rtorrent.d/categories.rc, and a usage example is in rtorrent.d/autolabel-categories.rc.

pyro.category.separated#

TODO

pyro.category.add#

pyro.category.list#

The private pyro.category.add command adds a named category. That means a category_‹name› view is defined – you can rotate though those views in rTorrent-PS using the < and > keys.

See d.category.set and load.category on how to put new items into a category.

If you call the pyro.category.list command, it prints a list of currently defined categories to the rTorrent console.

For a full example, see rtorrent.d/autolabel-categories.rc.

cull#

purge#

Convenience commands for use with the Ctrl-X prompt, to call rtcontrol --cull or rtcontrol --purge on the currently selected item.

These are private commands, from a shell prompt or script use rtcontrol directly.

tag.add#

tag.rm#

tag.show#

Convenience commands for use with the Ctrl-X prompt, to call rtcontrol --tag on the currently selected item.

tag.show is bound to the Ctrl-G key in rTorrent-PS, and uses the tag_show output format to define what is printed to the console (the list of tags and the item’s name by default).

These are private commands, from outside the client use rtcontrol with --tag, and its tagged field.

pyro.collapsed_view.add#

pyro.collapsed_view.add = ‹view name› ≫ 0

Like view.add, but sets the new view to collapsed state.

pyro.view.collapsed.toggle#

pyro.view.collapsed.toggle = ‹view name› ≫ 0

The same as view.collapsed.toggle, but protected by the pyro.extended flag (i.e. safe to call in vanilla rTorrent).

pyro.view.toggle_visible#

pyro.view.toggle_visible = ‹view name› ≫ 0

Toggle visibility of an item for the given view.

pyro.color_theme.name#

Used in color theme files of rTorrent-PS to announce switching to a different theme (defined in pyrocore’s rtorrent.d/theming.rc).

pyro.watchdog#

TODO

This is a private command.

pimp-my-box Configuration#

TODO

In addition to the commands listed here, pimp-my-box also defines cfg.basedir, cfg.watch, and cfg.logs, and includes anything from pyrocore Configuration.

quit#

TODO disable-control-q.rc

pyro.extended#

Set pyro.extended to 1 to activate rTorrent-PS features. Note that this tells the rest of the configuration that it can safely use the extended command set – it won’t magically make a vanilla rTorrent an extended one.

Starting with rTorrent-PS 1.1+, this setting is detected automatically, thanks to system.has.

pyro.bin_dir#

A constant that should be set to the bin directory where you installed the pyrocore tools.

Make sure you end it with a /; if this is left empty, then the shell’s path is searched.

pyro.logfile_path#

TODO

Commands Reference#

Format#

Download Items and Attributes#

d.* commands#

f.* commands#

p.* commands#

t.* commands#

load.* commands#

session.* commands#

Scripting#

method.* commands#

event.* commands#

Scheduling Commands#

Importing Script Files#

Conditions (if/branch/do)#

Conditional Operators#

String Functions#

Array Functions#

Math Functions#

Value Conversion & Formatting#

Logging, Files, and OS#

execute.* commands#

system.* commands#

log.* commands#

Network (Sockets, HTTP, XMLRPC)#

network.* commands#

ip_tables.* commands#

ipv4_filter.* commands#

Bittorrent Protocol#

dht.* commands#

pieces.* commands#

protocol.* commands#

throttle.* commands#

User Interface#

ui.* commands#

view.* commands#

Miscellaneous#

strings.* commands#

Singular Commands#

TODO (Groups)#

TODO (singles)#

‘Intermediate’ Commands#

Standard Configuration Sets#

Examples in This Manual#

rTorrent Wiki Template#

pyrocore Configuration#

pimp-my-box Configuration#

`d.*` commands#

`f.*` commands#

`p.*` commands#

`t.*` commands#

`load.*` commands#

`session.*` commands#

`method.*` commands#

`event.*` commands#