YGGverse/aquatic
1
0
Fork 0
mirror of https://github.com/YGGverse/aquatic.git synced 2026-04-01 18:25:30 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

README: rewrite and improve

Browse source
This commit is contained in:
Joakim Frostegård 2021-10-28 18:15:12 +02:00
parent a24a10c518
commit 109a3e34f3
1 changed files with 62 additions and 54 deletions
Download patch file Download diff file Expand all files Collapse all files

116
README.md
View file

@ -4,7 +4,7 @@
Blazingly fast, multi-threaded BitTorrent tracker written in Rust. Blazingly fast, multi-threaded BitTorrent tracker written in Rust.
Consists of three sub-implementations for different protocols: Consists of sub-implementations for different protocols:
[BitTorrent over UDP]: https://libtorrent.org/udp_tracker_protocol.html [BitTorrent over UDP]: https://libtorrent.org/udp_tracker_protocol.html
[BitTorrent over HTTP]: https://wiki.theory.org/index.php/BitTorrentSpecification#Tracker_HTTP.2FHTTPS_Protocol [BitTorrent over HTTP]: https://wiki.theory.org/index.php/BitTorrentSpecification#Tracker_HTTP.2FHTTPS_Protocol
@ -14,11 +14,11 @@ Consists of three sub-implementations for different protocols:
[mio]: https://github.com/tokio-rs/mio [mio]: https://github.com/tokio-rs/mio
[glommio]: https://github.com/DataDog/glommio [glommio]: https://github.com/DataDog/glommio
| Name | Protocol | OS requirements | | Name | Protocol | OS requirements |
|--------------|-----------------------------------------------|-----------------------------------------------------------------| |--------------|------------------------------------------------|-----------------------------------------------------------------|
| aquatic_udp | [BitTorrent over UDP] | Cross-platform with [mio] (default) / Linux 5.8+ with [glommio] | | 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_http | [BitTorrent over HTTP] with TLS ([rustls]) | Linux 5.8+ |
| aquatic_ws | [WebTorrent], plain / with TLS ([native-tls]) | Cross-platform | | aquatic_ws | [WebTorrent], plain or with TLS ([native-tls]) | Cross-platform |
## Copyright and license ## Copyright and license
@ -26,48 +26,52 @@ Copyright (c) 2020-2021 Joakim Frostegård
Distributed under Apache 2.0 license (details in `LICENSE` file.) Distributed under Apache 2.0 license (details in `LICENSE` file.)
## Installation prerequisites ## Building
### Prerequisites
- Install Rust with [rustup](https://rustup.rs/) (stable is recommended) - Install Rust with [rustup](https://rustup.rs/) (stable is recommended)
- Install cmake with your package manager (e.g., `apt-get install cmake`) - Install cmake with your package manager (e.g., `apt-get install cmake`)
- On GNU/Linux, also install the OpenSSL components necessary for dynamic - If you want to run aquatic_ws and are on a Unix-like OS, install the OpenSSL
linking (e.g., `apt-get install libssl-dev`) components necessary for dynamic linking (e.g., `apt-get install libssl-dev`)
- Clone the git repository and refer to the next section. - Clone this git repository and enter it
## Compile and run ### Compiling
To compile the master executable for all protocols, run: Compile the implementations that you are interested in:
```sh ```sh
./scripts/build-aquatic.sh 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
``` ```
To start the tracker for a protocol with default settings, run: ## Running
To start a tracker with default configuration, run any of:
```sh ```sh
./target/release/aquatic udp ./target/release/aquatic_udp
./target/release/aquatic http ./target/release/aquatic_http
./target/release/aquatic ws ./target/release/aquatic_ws
``` ```
To print default settings to standard output, pass the "-p" flag to the binary: To adjust the configuration, begin by generating configuration files. They
differ between protocols.
```sh ```sh
./target/release/aquatic udp -p ./target/release/aquatic_udp -p > "aquatic-udp-config.toml"
./target/release/aquatic http -p ./target/release/aquatic_http -p > "aquatic-http-config.toml"
./target/release/aquatic ws -p ./target/release/aquatic_ws -p > "aquatic-ws-config.toml"
``` ```
Note that the configuration files differ between protocols. Make adjustments to the files. Then run the tracker with:
To adjust the settings, save the output of the relevant previous command to a
file and make your changes. Then run `aquatic` with a "-c" argument pointing to
the file, e.g.:
```sh ```sh
./target/release/aquatic udp -c "/path/to/aquatic-udp-config.toml" ./target/release/aquatic_udp -c "aquatic-udp-config.toml"
./target/release/aquatic http -c "/path/to/aquatic-http-config.toml" ./target/release/aquatic_http -c "aquatic-http-config.toml"
./target/release/aquatic ws -c "/path/to/aquatic-ws-config.toml" ./target/release/aquatic_ws -c "aquatic-ws-config.toml"
``` ```
The configuration file values you will most likely want to adjust are The configuration file values you will most likely want to adjust are
@ -83,7 +87,7 @@ mode = 'off' # Change to 'black' (blacklist) or 'white' (whitelist)
path = '' # Path to text file with newline-delimited hex-encoded info hashes path = '' # Path to text file with newline-delimited hex-encoded info hashes
``` ```
Some more documentation of configuration file values might be available under More documentation of configuration file values might be available under
`src/lib/config.rs` in crates `aquatic_udp`, `aquatic_http`, `aquatic_ws`. `src/lib/config.rs` in crates `aquatic_udp`, `aquatic_http`, `aquatic_ws`.
## Details on implementations ## Details on implementations
@ -131,25 +135,39 @@ 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). [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. In some cases, it performs even better than the cross-platform implementation.
To use it, pass the `with-glommio` feature when building, e.g.:
```sh
cargo build -p aquatic_udp --features "with-glommio" --no-default-features
./target/release/aquatic_udp
```
### aquatic_http: HTTP BitTorrent tracker ### aquatic_http: HTTP BitTorrent tracker
Aims for compatibility with the HTTP BitTorrent protocol, as described [HTTP BitTorrent protocol]: https://wiki.theory.org/index.php/BitTorrentSpecification#Tracker_HTTP.2FHTTPS_Protocol
[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). 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 * 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 `aquatic_http` has not been tested as much as `aquatic_udp` but likely works
fine. 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.:
```toml
[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](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
#### TLS #### TLS
To run over TLS, a pkcs12 file (`.pkx`) is needed. It can be generated from To run over TLS, a pkcs12 file (`.pkx`) is needed. It can be generated from
@ -164,24 +182,14 @@ Enter a password when prompted. Then move `identity.pfx` somewhere suitable,
and enter the path into the tracker configuration field `tls_pkcs12_path`. Set 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. the password in the field `tls_pkcs12_password` and set `use_tls` to true.
### 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
For information about running over TLS, please refer to the TLS subsection
of the `aquatic_http` section above.
#### Benchmarks #### Benchmarks
[wt-tracker]: https://github.com/Novage/wt-tracker [wt-tracker]: https://github.com/Novage/wt-tracker
[bittorrent-tracker]: https://github.com/webtorrent/bittorrent-tracker [bittorrent-tracker]: https://github.com/webtorrent/bittorrent-tracker
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. 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: Server responses per second, best result in bold: