aquatic

Blazingly fast, multi-threaded BitTorrent tracker written in Rust.

Consists of sub-implementations for different protocols:

Name	Protocol	OS requirements
aquatic_udp	BitTorrent over UDP	Cross-platform with mio (default) / Linux 5.8+ with glommio
aquatic_http	BitTorrent over HTTP with TLS (rustls)	Linux 5.8+
aquatic_ws	WebTorrent, plain or with TLS (native-tls)	Cross-platform

Copyright and license

Copyright (c) 2020-2021 Joakim Frostegård

Distributed under Apache 2.0 license (details in LICENSE file.)

Usage

Prerequisites

• Install Rust with rustup (stable is recommended)
• Install cmake with your package manager (e.g., apt-get install cmake)
• If you want to run aquatic_ws and are on a Unix-like OS, install the OpenSSL components necessary for dynamic linking (e.g., apt-get install libssl-dev)
• Clone this git repository and enter it

Compiling

Compile the implementations that you are interested in:

cargo build --release -p aquatic_udp
cargo build --release -p aquatic_udp --features "with-glommio" --no-default-features
cargo build --release -p aquatic_http
cargo build --release -p aquatic_ws

Running

Begin by generating configuration files. They differ between protocols.

./target/release/aquatic_udp -p > "aquatic-udp-config.toml"
./target/release/aquatic_http -p > "aquatic-http-config.toml"
./target/release/aquatic_ws -p > "aquatic-ws-config.toml"

Make adjustments to the files. The values you will most likely want to adjust are socket_workers (number of threads reading from and writing to sockets) and address under the network section (listening address). This goes for all three protocols.

aquatic_http requires configuring a TLS certificate file and a private key file to run. More information is available futher down in this document.

Once done, run the tracker:

./target/release/aquatic_udp -c "aquatic-udp-config.toml"
./target/release/aquatic_http -c "aquatic-http-config.toml"
./target/release/aquatic_ws -c "aquatic-ws-config.toml"

More documentation of configuration file values might be available under src/lib/config.rs in crates aquatic_udp, aquatic_http, aquatic_ws.

General settings

Access control by info hash is supported for all protocols. The relevant part of configuration is:

[access_list]
mode = 'off' # Change to 'black' (blacklist) or 'white' (whitelist)
path = '' # Path to text file with newline-delimited hex-encoded info hashes

Details on implementations

aquatic_udp: UDP BitTorrent tracker

Aims to implements the UDP BitTorrent protocol, except that it:

• Doesn't care about IP addresses sent in announce requests. The packet source IP is always used.
• Doesn't track of the number of torrent downloads (0 is always sent).

Supports IPv4 and IPv6 (BitTorrent UDP protocol doesn't support IPv6 very well, however.)

For optimal performance, enable setting of core affinities in configuration.

Benchmarks

Server responses per second, best result in bold:

workers	aquatic	opentracker
1	n/a	232k
2	309k	293k
3	597k	397k
4	603k	481k
6	757k	587k
8	850k	431k
10	826k	165k
16	785k	139k

Please refer to documents/aquatic-udp-load-test-2021-08-19.pdf for more details.

Alternative implementation using io_uring

There is an alternative implementation that utilizes io_uring by running on glommio. It only runs on Linux and requires a recent kernel (version 5.8 or later). In some cases, it performs even better than the cross-platform implementation.

aquatic_http: HTTP BitTorrent tracker

Aims for compatibility with the HTTP BitTorrent protocol, with some exceptions:

• Only runs over TLS
• Doesn't track of the number of torrent downloads (0 is always sent)
• Doesn't allow full scrapes, i.e. of all registered info hashes

aquatic_http has not been tested as much as aquatic_udp but likely works fine.

A TLS certificate file (DER-encoded X.509) and a corresponding private key file (DER-encoded ASN.1 in either PKCS#8 or PKCS#1 format) are required. Set their paths in the configuration file, e.g.:

[network]
address = '0.0.0.0:3000'
tls_certificate_path = './cert.crt'
tls_private_key_path = './key.pk8'

aquatic_ws: WebTorrent tracker

Aims for compatibility with WebTorrent clients, including wss protocol support (WebSockets over TLS), with some exceptions:

• Doesn't track of the number of torrent downloads (0 is always sent).
• Doesn't allow full scrapes, i.e. of all registered info hashes

TLS

To run over TLS, a pkcs12 file (.pkx) is needed. It can be generated from Let's Encrypt certificates as follows, assuming you are in the directory where they are stored:

openssl pkcs12 -export -out identity.pfx -inkey privkey.pem -in cert.pem -certfile fullchain.pem

Enter a password when prompted. Then move identity.pfx somewhere suitable, and enter the path into the tracker configuration field tls_pkcs12_path. Set the password in the field tls_pkcs12_password and set use_tls to true.

Benchmarks

The following benchmark is not very realistic, as it simulates a small number of clients, each sending a large number of requests. Nonetheless, I think that it gives a useful indication of relative performance.

Server responses per second, best result in bold:

workers	aquatic	wt-tracker	bittorrent-tracker
1	n/a	117k	45k
2	225k	n/a	n/a
4	627k	n/a	n/a
6	831k*	n/a	n/a
8	1209k*	n/a	n/a
10	1455k*	n/a	n/a
12	1650k*	n/a	n/a
14	1804k*	n/a	n/a
16	1789k*	n/a	n/a

* Using a VPS with 32 vCPUs. The other measurements were made using a 16 vCPU VPS.

Please refer to documents/aquatic-ws-load-test-2021-08-18.pdf for more details.

Load testing

There are load test binaries for all protocols. They use a CLI structure similar to aquatic and support generation and loading of configuration files.

To run, first start the tracker that you want to test. Then run the corresponding load test binary:

./scripts/run-load-test-udp.sh
./scripts/run-load-test-http.sh
./scripts/run-load-test-ws.sh

To fairly compare HTTP performance to opentracker, set keepalive to false in aquatic_http settings.

Architectural overview

One or more socket workers open sockets, read and parse requests from peers and send them through channels to request workers. The request workers go through the requests, update shared internal tracker state as appropriate and generate responses that are sent back to the socket workers. The responses are then serialized and sent back to the peers.

This design means little waiting for locks on internal state occurs, while network work can be efficiently distributed over multiple threads, making use of SO_REUSEPORT setting.

Trivia

The tracker is called aquatic because it thrives under a torrent of bits ;-)