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 thelog.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, sod.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.
Download the latest stable release
Related Projects
----------------
* https://github.com/rakshasa/rbedit: A dependency-free bencode editor.
Donate to rTorrent development
------------------------------
* Paypal
* Patreon
* SubscribeStar
* 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 rtorrentInstall build dependencies
Install libtorrent with the same version rTorrent.
Generate configure scripts:
autoreconf -ivfOptionally, generate man pages:
docbook2man rtorrent.1.xmlMan pages output to "doc/rtorrent.1".
RTorrent follows the development of 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
---