### Doc/Manual/Choke Groups

# Choke Groups

## Settings

    choke_group.insert = "leech_fast"

Create a new group named "leech_fast", accessible by the string or
index / reverse index according to order of insertion. E.g. '-1'
refers to the last inserted choke group, while 0 refers to the first.

All commands that applies to a group requires the first argument to be
the index, reverse index or the group name.

    choke_group.tracker.mode.set = -1,"aggressive"

Set the tracker mode for torrents in this group.

    choke_group.up.heuristics.set = -1,"upload_leech_experimental"
    choke_group.down.heuristics.set = -1,"download_leech"

Set the heuristics used when deciding on which peers to choke and
unchoke. Use "strings.choke_heuristics{,.upload,.download}" to get a
list of the available heuristics.

    choke_group.up.max.set = -1,250
    choke_group.down.max.set = -1,500

Set the max total number of unchoked peers for all torrents in this choke group.

---

### Doc/Manual/Ip Filtering

# IP filtering

## Introduction

## Make a new ip table

    ip_tables.insert_table = <table_name>

Create a new empty table with the name ’table\_name’, with the default
value returned being $0$.

There is currently no use of the generic ip tables commands.

## Add a new address block

    ip_tables.add_address = <table_name>, 10.0.0.0/8, <value>

Set <value\> for all addresses in the address block, overwriting prior
values.

## Add a new address block

    ip_tables.load = <table_name>, ~/foo.txt, <value>

Set <value\> for all addresses in the file ’foo.txt’ separated by
newline, similar to ’add\_address’.

## Get value for address

    ip_tables.get = <table_name>, 10.10.10.10

Returns the value set for an address, or the address block it belongs
to. The default is $0$.

## Size of data structures

    ip_tables.size_data = <table_name>

Returns the size in bytes of all data structures for this table,
excluding the root class object itself. Note that the in-memory table is
dynamically consolidated, as such memory use will always be based on
actual fragmentation.

The table is a b-tree with 1024 nodes per branch.

## IPv4 filtering table

    ipv4_filter.add_address = 10.0.0.0/8, unwanted
    ipv4_filter.add_address = 11.0.0.0/8, preferred
    ipv4_filter.load = ~/filters.txt, unwanted
    ipv4_filter.get = 10.10.10.10
    ipv4_filter.size_data =

The main ip filter, currently supporting ’unwanted’ (do not allow
connections) and ’preferred’ (currently used only in private code).

## Constants

    strings.ip_filter =
    =>
    { "unwanted",  PeerInfo::flag_unwanted },
    { "preferred", PeerInfo::flag_preferred },

Constants used by ipv4\_filter values.

---

### Doc/Manual/Logging

# Logging

## Opening log files

    # log.open_file = "log name", "file path"

    log.open_file = "rtorrent.log", (cat,/tmp/rtorrent.log.,(system.pid))

A newly opened log file is not connected to any logging events.

Some control over formatting will be provided at a later date.

## Appending to log files

    log.append_file = "rtorrent.log", "/tmp/rtorrent.log"

The `log.open_file` clears any existing contents of the file. If you'd
prefer to have a single log file that persists across application
restarts, you can use the `log.append_file` in place of the
`log.open_file` configuration key.

## Adding outputs to events

    # log.add_output = "logging event", "log name"

    log.add_output = "info", "rtorrent.log"

    log.add_output = "dht_all", "tracker.log"
    log.add_output = "tracker_events", "tracker.log"
    log.add_output = "tracker_requests", "tracker.log"

Each log handle can be added to multiple different logging events.

## Logging events

    "critical"
    "error"
    "warn"
    "notice"
    "info"
    "debug"

The above events receive logging events from all the sub-groups
displayed below, and each event also receiving events from the event
above in importance.

Thus some high-volume sub-group events such as “tracker\_debug” are not
part of “debug” and every “warn” event will receive events from “error”,
“critical”.

    "connection_*"
    "dht_*"
    "peer_*"
    "rpc_*"
    "storage_*"
    "thread_*"
    "tracker_*"
    "torrent_*"

All sub-groups have events from “critical” to “debug” defined.

---

### Doc/Manual/Paths

# Resolving paths

Commands that return a path have `.realpath` variants that resolve it to a
canonical one, with symlinks followed and any `.` or `..` components removed.

The intent is to make paths safer to hand to an external script.
A script called through `execute` receives whatever path rtorrent gives it, and
many scripts do no sanity checking of their own, so resolving the path before it
leaves rtorrent removes a class of surprises: a download directory that is a
symlink into somewhere unexpected, or a torrent whose name walks upwards out of
the directory it is supposed to live in.

    # Instead of this
    execute = ~/bin/on-finished, (d.base_path)

    # Pass the resolved path
    execute = ~/bin/on-finished, (d.base_path.realpath.or_throw)

## Available variants

Each command below comes in an `.or_empty` and an `.or_throw` form.

| Command | Resolves |
| --- | --- |
| `d.base_path.realpath.*` | `d.base_path` |
| `d.directory.realpath.*` | `d.directory` |
| `d.tied_to_file.realpath.*` | `d.tied_to_file` |
| `d.loaded_file.realpath.*` | `d.loaded_file` |
| `f.frozen_path.realpath.*` | `f.frozen_path` |
| `session.path.realpath.*` | `session.path` |
| `directory.default.realpath.*` | `directory.default` |

A leading `~` is expanded first, exactly as it is for `execute`, so
`~/downloads` resolves the same way it would on the command line.

## Paths that do not exist

Resolving requires the path to name an existing file or directory, which is
often not the case for a download whose data has not been written yet.
The two forms differ only in what they do about it.

`.or_empty` returns an empty string:

    print = (d.base_path.realpath.or_empty)    # ""

This keeps `d.multicall` usable over a view that mixes started and unstarted
downloads, since a single unresolvable path does not abort the whole call.
A script receiving one of these paths should still check that it is not empty
before acting on it.

`.or_throw` raises an error instead:

    print = (d.base_path.realpath.or_throw)    # Could not resolve path: '...'

Prefer this one wherever an unresolvable path means the command should not run
at all, such as a single `execute` on `event.download.finished`.

Note that a download only has a file list once it has been opened, so
`d.base_path` and `f.frozen_path` are empty at `event.download.inserted` time
and their `.realpath` variants resolve nothing.

---

### Doc/Manual/String Functions

# String functions

The `string.*` commands manipulate and inspect text from within the
configuration file.
They are pure functions with no side effects, so they can be nested freely and
are safe to call over RPC.

Every argument is converted to its string representation before use, which means
numbers can be passed where text is expected.
Commands that count characters, such as `string.length` and `string.substr`, count
utf-8 characters rather than bytes.

## string.length

    # string.length = «text»

    string.length = "héllo"    # 5

Returns the number of utf-8 characters in the text.

## string.equals

    # string.equals = «text», «other»[, ...]

    string.equals = (d.name), "first.iso", "second.iso"

Returns `1` if the first argument equals any of the following arguments,
otherwise `0`.

## string.starts_with, string.ends_with

    # string.starts_with = «text», «prefix»[, ...]
    # string.ends_with = «text», «tail»[, ...]

    string.starts_with = (t.url), "http://", "https://"
    string.ends_with = (d.name), ".iso"

Returns `1` if the text begins, or ends, with any of the given prefixes or
tails.

## string.contains, string.contains_i

    # string.contains = «haystack», «needle»[, ...]
    # string.contains_i = «haystack», «needle»[, ...]

    string.contains = (t.url), "retracker.local"
    string.contains_i = (t.url), "RETRACKER.local"

Returns `1` if the haystack contains any of the needles.
The `_i` variant compares case-insensitively, and only handles ascii.

## string.substr

    # string.substr = «text»[, «position»[, «count»[, «default»]]]

    string.substr = "abcdef", 2, 3       # "cde"
    string.substr = "abcdef", -2         # "ef"
    string.substr = "abcdef", 10, 1, "?" # "?"

Extracts a part of the text, starting at `position` and spanning `count`
characters.
The position defaults to the start of the text, and the count to the rest of it.
A negative position is relative to the end of the text.
If the position falls outside the text, the default value is returned instead,
which is the empty string unless given.

## string.split

    # string.split = «text», «delimiter»

    string.split = "a.b.c", "."    # {"a", "b", "c"}
    string.split = "abc", ""       # {"a", "b", "c"}

Splits the text into a list, keeping empty fields.
An empty delimiter splits the text into its utf-8 characters.

## string.join

    # string.join = «delimiter»[, «object»[, ...]]

    string.join = "-", (string.split, "a.b.c", ".")    # "a-b-c"

Concatenates the objects, inserting the delimiter between them.
Lists are flattened, so the result of `string.split` can be joined back
together.

## string.lpad, string.rpad

    # string.lpad = «text», «length»[, «padding»]
    # string.rpad = «text», «length»[, «padding»]

    string.lpad = 7, 3, 0    # "007"
    string.rpad = "a", 3     # "a  "

Pads the text at the start, or the end, until it is `length` characters long.
The padding defaults to a single space and is repeated as needed.
Text that is already long enough is returned unchanged.

## string.strip, string.lstrip, string.rstrip

    # string.strip = «text»[, «strippable»[, ...]]
    # string.lstrip = «text»[, «head»[, ...]]
    # string.rstrip = «text»[, «tail»[, ...]]

    string.strip = "  padded  "      # "padded"
    string.strip = "//path//", "/"   # "path"

Removes characters from both ends of the text, or from only the start or the
end.
The arguments after the text form a set of utf-8 characters to remove.
Without them, whitespace is removed.

## string.map

    # string.map = «text», {«old», «new»}[, ...]

    string.map = (d.state), {0, "stopped"}, {1, "started"}

Returns the replacement of the first pair whose `old` value equals the whole
text.
If no pair matches, the text is returned unchanged.

## string.replace

    # string.replace = «text», {«old», «new»}[, ...]

    string.replace = "a-b-c", {"-", "+"}    # "a+b+c"

Replaces every occurrence of `old` with `new`.
The pairs are applied in order, so a later pair operates on the result of the
earlier ones.

## Example: dropping unwanted trackers

The following disables every tracker that points at `retracker.local` as soon as
a download is inserted.

    method.set_key = event.download.inserted, drop_retracker, \
      ((t.multicall, default, "branch=(string.contains,(t.url),retracker.local),((t.disable))"))

---

### README

RTorrent BitTorrent Client
========

Introduction
------------

A ncurses-based command line torrent client for high performance. 

To learn how to use rTorrent visit the [Wiki](https://github.com/rakshasa/rtorrent/wiki).

Download the [latest stable release](https://github.com/rakshasa/rtorrent/releases/latest)

Related Projects
----------------

* [https://github.com/rakshasa/rbedit](https://github.com/rakshasa/rbedit): A dependency-free bencode editor.

Donate to rTorrent development
------------------------------

* [Paypal](https://paypal.me/jarisundellno)
* [Patreon](https://www.patreon.com/rtorrent)
* [SubscribeStar](https://www.subscribestar.com/rtorrent)
* Bitcoin: 1MpmXm5AHtdBoDaLZstJw8nupJJaeKu8V8
* Ethereum: 0x9AB1e3C3d8a875e870f161b3e9287Db0E6DAfF78
* Litecoin: LdyaVR67LBnTf6mAT4QJnjSG2Zk67qxmfQ
* Cardano: addr1qytaslmqmk6dspltw06sp0zf83dh09u79j49ceh5y26zdcccgq4ph7nmx6kgmzeldauj43254ey97f3x4xw49d86aguqwfhlte


Help keep rTorrent development going by donating to its creator.


BUILDING
--------

Jump into the github cloned directory

```
cd rtorrent
```

## Install build dependencies

Install [libtorrent](https://github.com/rakshasa/libtorrent) with the same version rTorrent.

Generate configure scripts:

```
autoreconf -ivf
```

Optionally, generate man pages:

```
docbook2man rtorrent.1.xml
```

Man pages output to "doc/rtorrent.1".

RTorrent follows the development of [libtorrent](https://github.com/rakshasa/libtorrent) closely, and thus the versions must be in sync.

## USAGE

Refer to User Guide: https://github.com/rakshasa/rtorrent/wiki/User-Guide

## LICENSE

GNU GPL, see COPYING. "libtorrent/src/utils/sha_fast.{cc,h}" is
originally from the Mozilla NSS and is under a triple license; MPL,
LGPL and GPL. An exception to non-NSS code has been added for linking to OpenSSL as requested by Debian, though the author considers that library to be part of the Operative System and thus linking is allowed according to the GPL.

Use whatever fits your purpose, the code required to compile with
Mozilla's NSS implementation of SHA1 has been retained and can be
compiled if the user wishes to avoid using OpenSSL.

## DEPENDENCIES

* libcurl >= 7.12.0
* libtorrent = (same version)
* ncurses

## BUILD DEPENDENCIES

* libtoolize
* aclocal
* autoconf
* autoheader
* automake

---