Crate torrust_tracker

Expand description

Torrust Tracker is a modern and feature-rich (private) BitTorrent tracker.

BitTorrent is a protocol for distributing files using a peer-to-peer network.

Peers in the networks need to know where they can find other peers with the files they are looking for.

Tracker are services that allow peers to quickly find other peers. Client peers announce their existence to a tracker, and the tracker responds to the peer with a list of other peers in the swarm.

You can learn more about BitTorrent and BitTorrent Trackers on these sites:

Torrust Tracker is a BitTorrent tracker with a focus on:

Performance
Robustness
Extensibility
Security
Usability
And with a community-driven development

Features

Multiple UDP server and HTTP(S) server blocks for socket binding possible
Full IPv4 and IPv6 support for both UDP and HTTP(S)
Private and Whitelisted mode
Built-in API
Peer authentication using time-bound keys
Database persistence for authentication keys, whitelist and completed peers counter
DB Support for SQLite and MySQl

Services

From the end-user perspective the Torrust Tracker exposes three different services.

A REST API
One or more UDP trackers
One or more HTTP trackers

Installation

Minimum requirements

Rust Stable 1.68
You might have problems compiling with a machine with low resources.

It has been tested with:

Docker containers with:

6 CPUs
7.5G of ram
2GB of swap

VM with:

1 core of Intel Xeon Processor (Icelake)
1G of ram
25G of disk
Debian 11
no swap by default

Adding swap may help with compilation. See issue #321.

Prerequisites

The tracker has some system dependencies:

Since we are using the openssl crate with the vendored feature, enabled, you will need to install the following dependencies:

sudo apt-get install pkg-config libssl-dev make

If you are using SQLite3 as database driver, you will need to install the following dependency:

sudo apt-get install libsqlite3-dev

NOTICE: those are the commands for Ubuntu. If you are using a different OS, you will need to install the equivalent packages. Please refer to the documentation of your OS.

With the default configuration you will need to create the storage directory:

storage/
├── database
│   └── data.db
└── tls
    ├── localhost.crt
    └── localhost.key

The default configuration expects a directory ./storage/tracker/lib/database to be writable by the tracker process.

By default the tracker uses SQLite and the database file name data.db.

You only need the tls directory in case you are setting up SSL for the HTTP tracker or the tracker API. Visit HTTP or API if you want to know how you can use HTTPS.

Install from sources

git clone https://github.com/torrust/torrust-tracker.git \
  && cd torrust-tracker \
  && cargo build --release \
  && mkdir -p ./storage/tracker/lib/database \
  && mkdir -p ./storage/tracker/lib/tls

Run with docker

You can run the tracker with a pre-built docker image. Please refer to the tracker docker documentation.

In order to run the tracker you need to provide the configuration. If you run the tracker without providing the configuration, the tracker will generate the default configuration the first time you run it. It will generate a tracker.toml file with in the root directory.

The default configuration is:

log_level = "info"
mode = "public"
db_driver = "Sqlite3"
db_path = "./storage/tracker/lib/database/sqlite3.db"
announce_interval = 120
min_announce_interval = 120
max_peer_timeout = 900
on_reverse_proxy = false
external_ip = "0.0.0.0"
tracker_usage_statistics = true
persistent_torrent_completed_stat = false
inactive_peer_cleanup_interval = 600
remove_peerless_torrents = true

[[udp_trackers]]
enabled = false
bind_address = "0.0.0.0:6969"

[[http_trackers]]
enabled = false
bind_address = "0.0.0.0:7070"
ssl_enabled = false
ssl_cert_path = ""
ssl_key_path = ""

[http_api]
enabled = true
bind_address = "127.0.0.1:1212"
ssl_enabled = false
ssl_cert_path = ""
ssl_key_path = ""

[http_api.access_tokens]
admin = "MyAccessToken"

The default configuration includes one disabled UDP server, one disabled HTTP server and the enabled API.

For more information about each service and options you can visit the documentation for the torrust-tracker-configuration crate.

Alternatively to the tracker.toml file you can use one environment variable TORRUST_TRACKER_CONFIG to pass the configuration to the tracker:

TORRUST_TRACKER_CONFIG=$(cat tracker.toml)
cargo run

In the previous example you are just setting the env var with the contents of the tracker.toml file.

The env var contains the same data as the tracker.toml. It’s particularly useful in you are running the tracker with docker.

NOTE: The TORRUST_TRACKER_CONFIG env var has priority over the tracker.toml file.

Usage

Running the tracker with the default configuration and enabling the UDP and HTTP trackers will expose the services on these URLs:

API

In order to use the tracker API you need to enable it in the configuration:

[http_api]
enabled = true
bind_address = "127.0.0.1:1212"
ssl_enabled = false
ssl_cert_path = ""
ssl_key_path = ""

By default it’s enabled on port 1212. You also need to add access tokens in the configuration:

[http_api.access_tokens]
admin = "MyAccessToken"
LABEL = "YOUR_TOKEN"

All tokens give full access the the API. Once you have defined you token you can make request adding the token as a GET parameter. For example:

http://127.0.0.1:1212/api/v1/stats?token=MyAccessToken

That endpoint will give you the tracker metrics:

{
    "torrents": 0,
    "seeders": 0,
    "completed": 0,
    "leechers": 0,
    "tcp4_connections_handled": 0,
    "tcp4_announces_handled": 0,
    "tcp4_scrapes_handled": 0,
    "tcp6_connections_handled": 0,
    "tcp6_announces_handled": 0,
    "tcp6_scrapes_handled": 0,
    "udp4_connections_handled": 0,
    "udp4_announces_handled": 0,
    "udp4_scrapes_handled": 0,
    "udp6_connections_handled": 0,
    "udp6_announces_handled": 0,
    "udp6_scrapes_handled": 0
}

Refer to the API documentation for more information about the API endpoints.

HTTP tracker

The HTTP tracker implements two type of requests:

Announce: http://127.0.0.1:7070/announce
Scrape: http://127.0.0.1:7070/scrape

In you are using the tracker in private or private_listed mode you will need to append the authentication key:

Announce: http://127.0.0.1:7070/announce/key
Scrape: http://127.0.0.1:7070/scrape/key

In order to use the HTTP tracker you need to enable at least one server in the configuration:

[[http_trackers]]
enabled = true
bind_address = "0.0.0.0:7070"

Refer to the HTTP documentation for more information about the HTTP tracker.

Announce

The announce request allows a peer to announce itself and obtain a list of peer for an specific torrent.

A sample announce request:

http://0.0.0.0:7070/announce?info_hash=%81%00%00%00%00%00%00%00%00%00%00%00%00%00%00%00%00%00%00%00&peer_addr=2.137.87.41&downloaded=0&uploaded=0&peer_id=-qB00000000000000001&port=17548&left=0&event=completed&compact=0

If you want to know more about the announce request:

Scrape

The scrape request allows a peer to get swarm metadata for multiple torrents at the same time.

A sample scrape request for only one torrent:

http://0.0.0.0:7070/scrape?info_hash=%81%00%00%00%00%00%00%00%00%00%00%00%00%00%00%00%00%00%00%00

The response contains the swarm metadata for that torrent:

complete: the number of active peers that have completed downloading, also known as seeders. Peers from which other peers can get a full copy of the torrent.
downloaded: the number of peers that have ever completed downloading.
incomplete: the number of active peers that have not completed downloading, also known as leechers.

The scrape response is a bencoded byte array like the following:

d5:filesd20:xxxxxxxxxxxxxxxxxxxxd8:completei11e10:downloadedi13772e10:incompletei19e20:yyyyyyyyyyyyyyyyyyyyd8:completei21e10:downloadedi206e10:incompletei20eee

If you save the response as a file and you open it with a program that can handle binary data you would see:

00000000: 6435 3a66 696c 6573 6432 303a 8100 0000  d5:filesd20:....
00000010: 0000 0000 0000 0000 0000 0000 0000 0000  ................
00000020: 6438 3a63 6f6d 706c 6574 6569 3165 3130  d8:completei1e10
00000030: 3a64 6f77 6e6c 6f61 6465 6469 3065 3130  :downloadedi0e10
00000040: 3a69 6e63 6f6d 706c 6574 6569 3065 6565  :incompletei0eee
00000050: 65                                       e

BitTorrent uses a data formatting specification called Bencode.

If you want to know more about the scrape request:

Authentication keys

If the tracker is running in private or private_listed mode you will need to provide a valid authentication key.

Right now the only way to add new keys is via the REST API. The endpoint POST /api/vi/key/:duration_in_seconds will return an expiring key that will be valid for duration_in_seconds seconds.

Using curl you can create a 2-minute valid auth key:

$ curl -X POST "http://127.0.0.1:1212/api/v1/key/120?token=MyAccessToken"

Response:

{
    "key": "nvCFlJCq7fz7Qx6KoKTDiMZvns8l5Kw7",
    "valid_until": 1679334334,
    "expiry_time": "2023-03-20 17:45:34.712077008 UTC"
}

You can also use the Torrust Tracker together with the Torrust Index. If that’s the case, the Index will create the keys by using the tracker API.

UDP tracker

The UDP tracker also implements two type of requests:

Announce: udp://127.0.0.1:6969
Scrape: udp://127.0.0.1:6969

In order to use the UDP tracker you need to enable at least one server in the configuration:

[[udp_trackers]]
enabled = true
bind_address = "0.0.0.0:6969"

Refer to the UDP documentation for more information about the UDP tracker.

If you want to know more about the UDP tracker protocol:

BEP 15. UDP Tracker Protocol for BitTorrent

Components

Torrust Tracker has four main components:

The core tracker
The tracker REST API
The UDP tracker
The HTTP tracker

Core tracker

The core tracker is the main containing the tracker generic tracker logic.

The core tracker handles:

Authentication with keys
Authorization using a torrent whitelist
Statistics
Persistence

See tracker for more details on the tracker module.

Tracker API

The tracker exposes a REST API. The API has four resource groups:

Authentication keys: to handle the keys for the HTTP tracker
Statistics: to get the tracker metrics like requests counters
Torrents: to get peers for a torrent
Whitelist: to handle the torrent whitelist when the tracker runs on listed or private_listed mode

See API for more details on the REST API.

UDP tracker

UDP trackers are trackers with focus on performance. By Using UDP instead of HTTP the tracker removed the overhead of opening and closing TCP connections. It also reduces the response size.

You can find more information about UDP tracker on:

See UDP for more details on the UDP tracker.

HTTP tracker

HTTP tracker was the original tracker specification defined on the BEP 3.

See HTTP for more details on the HTTP tracker.

You can find more information about UDP tracker on:

Implemented BEPs

BEP stands for BitTorrent Enhancement Proposal. BEPs are documents providing information to the BitTorrent community or describing a new feature for the BitTorrent protocols.

You can find all BEPs on https://www.bittorrent.org/

Torrust Tracker implements these BEPs:

BEP 3: The BitTorrent Protocol
BEP 7: IPv6 Support
BEP 15: UDP Tracker Protocol for BitTorrent
BEP 23: Tracker Returns Compact Peer Lists
BEP 27: Private Torrents
BEP 48: Tracker Protocol Extension: Scrape

Contributing

If you want to contribute to this documentation you can open a new pull request.

Documentation

You can find this documentation on docs.rs.

If you want to contribute to this documentation you can open a new pull request.

In addition to the production code documentation you can find a lot of examples on the integration and unit tests.

Modules

app
Torrust Tracker application.
bootstrap
Tracker application bootstrapping.
servers
Servers. Services that can be started and stopped.
shared
Modules with generic logic used by several modules.
tracker
The core tracker module contains the generic BitTorrent tracker logic which is independent of the delivery layer.

Crate torrust_tracker

Table of contents

Features

Services

Installation

Minimum requirements

Prerequisites

Install from sources

Run with docker

Configuration

Usage

API

HTTP tracker

Announce

Scrape

Authentication keys

UDP tracker

Components

Core tracker

Tracker API

UDP tracker

HTTP tracker

Implemented BEPs

Contributing

Documentation

Modules