mirror of
https://github.com/YGGverse/aquatic.git
synced 2026-03-31 17:55:36 +00:00
214 lines
6.7 KiB
Markdown
214 lines
6.7 KiB
Markdown
# aquatic
|
||
|
||
Blazingly fast, multi-threaded BitTorrent tracker written in Rust.
|
||
|
||
Consists of separate executables:
|
||
* `aquatic_udp`: UDP BitTorrent tracker with double the throughput of
|
||
opentracker (see benchmarks below)
|
||
* `aquatic_ws`: WebTorrent tracker (experimental)
|
||
* `aquatic_http`: HTTP BitTorrent tracker (experimental)
|
||
|
||
These are described in detail below, after the general information.
|
||
|
||
## Copyright and license
|
||
|
||
Copyright (c) 2020 Joakim Frostegård
|
||
|
||
Distributed under Apache 2.0 license (details in `LICENSE` file.)
|
||
|
||
## Technical overview of tracker design
|
||
|
||
One or more socket workers open sockets, read and parse requests from peers and
|
||
send them through channels to request workers. They in turn go through the
|
||
requests, update internal state as appropriate and generate responses, which
|
||
are sent back to the socket workers, which serialize them and send them to
|
||
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.
|
||
|
||
Currently, `aquatic_ws` and `aquatic_http` only support a single request
|
||
worker. Benchmarks of `aquatic_udp` indicate that this is sufficient.
|
||
|
||
## Installation prerequisites
|
||
|
||
- Install Rust with [rustup](https://rustup.rs/) (stable is recommended)
|
||
- Install cmake with your package manager (e.g., `apt-get install cmake`)
|
||
- For `aquatic_ws` and `aquatic_http` on GNU/Linux, also install the OpenSSL
|
||
components necessary for dynamic linking (e.g., `apt-get install libssl-dev`)
|
||
- Clone the git repository and refer to the next section.
|
||
|
||
## Compile and run
|
||
|
||
The command line interfaces for the tracker executables are identical. To run
|
||
the respective tracker, just run its binary. You can also run any of the helper
|
||
scripts, which will compile the binary for you and pass on any command line
|
||
parameters. (After compilation, the binaries are found in `target/release/`.)
|
||
|
||
To run with default settings:
|
||
|
||
```sh
|
||
./scripts/run-aquatic-udp.sh
|
||
```
|
||
|
||
```sh
|
||
./scripts/run-aquatic-ws.sh
|
||
```
|
||
|
||
```sh
|
||
./scripts/run-aquatic-http.sh
|
||
```
|
||
|
||
To print default settings to standard output, pass the "-p" flag to the binary:
|
||
|
||
```sh
|
||
./scripts/run-aquatic-udp.sh -p
|
||
```
|
||
|
||
```sh
|
||
./scripts/run-aquatic-ws.sh -p
|
||
```
|
||
|
||
```sh
|
||
./scripts/run-aquatic-http.sh -p
|
||
```
|
||
|
||
To adjust the settings, save the output of the previous command to a file and
|
||
make your changes. Then run the binaries with a "-c" argument pointing to the
|
||
file, e.g.:
|
||
|
||
```sh
|
||
./scripts/run-aquatic-udp.sh -c "/path/to/aquatic-udp-config.toml"
|
||
```
|
||
|
||
```sh
|
||
./scripts/run-aquatic-ws.sh -c "/path/to/aquatic-ws-config.toml"
|
||
```
|
||
|
||
```sh
|
||
./scripts/run-aquatic-http.sh -c "/path/to/aquatic-http-config.toml"
|
||
```
|
||
|
||
The configuration file 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 executables.
|
||
|
||
Some documentation of the various options might be available in source code
|
||
files `src/lib/config.rs` in the respective tracker crates.
|
||
|
||
## Details on protocol-specific executables
|
||
|
||
### aquatic_udp: UDP BitTorrent tracker
|
||
|
||
Aims to implements the
|
||
[UDP BitTorrent protocol](https://libtorrent.org/udp_tracker_protocol.html),
|
||
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.)
|
||
|
||
#### Benchmarks
|
||
|
||
Performance was compared to
|
||
[opentracker](http://erdgeist.org/arts/software/opentracker/) using
|
||
`aquatic_udp_load_test`.
|
||
|
||
Server responses per second, best result in bold:
|
||
|
||
| workers | aquatic | opentracker |
|
||
| ------- | ----------- | ----------- |
|
||
| 1 | n/a | __177k__ |
|
||
| 2 | __168k__ | 98k |
|
||
| 3 | __187k__ | 118k |
|
||
| 4 | __216k__ | 127k |
|
||
| 6 | __309k__ | 109k |
|
||
| 8 | __408k__ | 96k |
|
||
|
||
See `documents/aquatic-load-test-2020-04-19.pdf` for details on benchmark, and
|
||
end of README for more information about load testing.
|
||
|
||
### aquatic_ws: WebTorrent tracker
|
||
|
||
Aims for compatibility with [WebTorrent](https://github.com/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
|
||
|
||
`aquatic_ws` is not as well tested as `aquatic_udp`, but has been
|
||
successfully used as the tracker for a file transfer between two webtorrent
|
||
peers.
|
||
|
||
#### TLS
|
||
|
||
To run over TLS (wss protocol), 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:
|
||
|
||
```sh
|
||
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.
|
||
|
||
### aquatic_http: HTTP BitTorrent tracker
|
||
|
||
Aims for compatibility with the HTTP BitTorrent protocol, as described
|
||
[here](https://wiki.theory.org/index.php/BitTorrentSpecification#Tracker_HTTP.2FHTTPS_Protocol),
|
||
including TLS and scrape request support. There are 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
|
||
|
||
`aquatic_http` is a work in progress and hasn't been tested very much yet. It
|
||
has however successfully been used as the (non-TLS) tracker for a BitTorrent
|
||
file transfer.
|
||
|
||
Please refer to the `aquatic_ws` section for information about setting up TLS.
|
||
|
||
## Load testing
|
||
|
||
There are load test binaries for all protocols. They use the same CLI structure
|
||
as the trackers, including configuration file generation and loading.
|
||
|
||
### aquatic_udp_load_test
|
||
|
||
To load test `aquatic_udp`, start it and then run:
|
||
|
||
```sh
|
||
./scripts/run-load-test-udp.sh
|
||
```
|
||
|
||
### aquatic_ws_load_test
|
||
|
||
To load test `aquatic_ws`, start it and then run:
|
||
|
||
```sh
|
||
./scripts/run-load-test-ws.sh
|
||
```
|
||
|
||
To achieve high throughput, it is currently necessary to sharply reduce the
|
||
poll timeout setting in the tracker, and reduce it somewhat in the load tester.
|
||
|
||
### aquatic_http_load_test
|
||
|
||
To load test `aquatic_http`, start it and then run:
|
||
|
||
```sh
|
||
./scripts/run-load-test-http.sh
|
||
```
|
||
|
||
To achieve high throughput, it is currently necessary to sharply reduce the
|
||
poll timeout setting in the tracker, and reduce it somewhat in the load tester.
|
||
Reducing event capacity can also help.
|
||
|
||
## Trivia
|
||
|
||
The tracker is called aquatic because it thrives under a torrent of bits ;-)
|