Skip to content

Commit 2cbda4c

Browse files
josecelanojosecelano
committed
docs: [#253] crate docs for lib.rs
Entrypoint for the crate documentation, the `lib.rs` file.
1 parent 62cd78f commit 2cbda4c

File tree

3 files changed

+384
-0
lines changed

3 files changed

+384
-0
lines changed

‎cSpell.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@
77
"Azureus",
88
"bencode",
99
"bencoded",
10+
"beps",
1011
"binascii",
1112
"Bitflu",
1213
"bools",

‎docs/media/torrust-tracker-components.png‎

82.9 KB
Loading

‎src/lib.rs‎

Lines changed: 383 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,386 @@
1+
//! **Torrust Tracker** is a modern and feature-rich (private) [`BitTorrent`](https://www.bittorrent.org/) tracker.
2+
//!
3+
//! [`BitTorrent`](https://en.wikipedia.org/wiki/BitTorrent) is a protocol for distributing files using a peer-to-peer network.
4+
//!
5+
//! Peers in the networks need to know where they can find other peers with the files they are looking for.
6+
//!
7+
//! Tracker are services that allow peers to quickly find other peers. Client peers announce their existence to a tracker,
8+
//! and the tracker responds to the peer with a list of other peers in the swarm.
9+
//!
10+
//! You can learn more about `BitTorrent` and `BitTorrent` Trackers on these sites:
11+
//!
12+
//! - <https://www.bittorrent.org/>
13+
//! - <https://en.wikipedia.org/wiki/BitTorrent>
14+
//! - <https://en.wikipedia.org/wiki/BitTorrent_tracker>
15+
//!
16+
//! Torrust Tracker is a `BitTorrent` tracker with a focus on:
17+
//!
18+
//! - Performance
19+
//! - Robustness
20+
//! - Extensibility
21+
//! - Security
22+
//! - Usability
23+
//! - And with a community-driven development
24+
//!
25+
//! # Table of contents
26+
//!
27+
//! - [Features](#features)
28+
//! - [Services](#services)
29+
//! - [Installation](#installation)
30+
//! - [Configuration](#configuration)
31+
//! - [Usage](#usage)
32+
//! - [Components](#components)
33+
//! - [Implemented BEPs](#implemented-beps)
34+
//!
35+
//! # Features
36+
//!
37+
//! - Multiple UDP server and HTTP(S) server blocks for socket binding possible
38+
//! - Full IPv4 and IPv6 support for both UDP and HTTP(S)
39+
//! - Private and Whitelisted mode
40+
//! - Built-in API
41+
//! - Peer authentication using time-bound keys
42+
//! - Database persistence for authentication keys, whitelist and completed peers counter
43+
//! - DB Support for `SQLite` and `MySQl`
44+
//!
45+
//! # Services
46+
//!
47+
//! From the end-user perspective the Torrust Tracker exposes three different services.
48+
//!
49+
//! - A REST [`API`](crate::servers::apis)
50+
//! - One or more [`UDP`](crate::servers::udp) trackers
51+
//! - One or more [`HTTP`](crate::servers::http) trackers
52+
//!
53+
//! # Installation
54+
//!
55+
//! ## Minimum requirements
56+
//!
57+
//! - Rust Stable `1.68`
58+
//! - You might have problems compiling with a machine with low resources. Or with low resources limits on docker containers. It has been tested with docker containers with 6 CPUs, 7.5 GM of memory and 2GB of swap
59+
//!
60+
//! ## Install from sources
61+
//!
62+
//! ```text
63+
//! git clone https://github.com/torrust/torrust-tracker.git
64+
//! cd torrust-tracker
65+
//! cargo build --release
66+
//! mkdir -p ./storage/database
67+
//! ```
68+
//!
69+
//! # Configuration
70+
//!
71+
//! In order to run the tracker you need to provide the configuration. If you run the tracker without providing the configuration,
72+
//! the tracker will generate the default configuration the first time you run it. It will generate a `config.toml` file with
73+
//! in the root directory.
74+
//!
75+
//! The default configuration is:
76+
//!
77+
//! ```toml
78+
//! log_level = "info"
79+
//! mode = "public"
80+
//! db_driver = "Sqlite3"
81+
//! db_path = "./storage/database/data.db"
82+
//! announce_interval = 120
83+
//! min_announce_interval = 120
84+
//! max_peer_timeout = 900
85+
//! on_reverse_proxy = false
86+
//! external_ip = "0.0.0.0"
87+
//! tracker_usage_statistics = true
88+
//! persistent_torrent_completed_stat = false
89+
//! inactive_peer_cleanup_interval = 600
90+
//! remove_peerless_torrents = true
91+
//!
92+
//! [[udp_trackers]]
93+
//! enabled = false
94+
//! bind_address = "0.0.0.0:6969"
95+
//!
96+
//! [[http_trackers]]
97+
//! enabled = false
98+
//! bind_address = "0.0.0.0:7070"
99+
//! ssl_enabled = false
100+
//! ssl_cert_path = ""
101+
//! ssl_key_path = ""
102+
//!
103+
//! [http_api]
104+
//! enabled = true
105+
//! bind_address = "127.0.0.1:1212"
106+
//! ssl_enabled = false
107+
//! ssl_cert_path = ""
108+
//! ssl_key_path = ""
109+
//!
110+
//! [http_api.access_tokens]
111+
//! admin = "MyAccessToken"
112+
//! ```
113+
//!
114+
//! The default configuration includes one disabled UDP server, one disabled HTTP server and the enabled API.
115+
//!
116+
//! For more information about each service and options you can visit the documentation for the [torrust-tracker-configuration crate](https://docs.rs/torrust-tracker-configuration/3.0.0-alpha.1/torrust_tracker_configuration/).
117+
//!
118+
//! Alternatively to the `config.toml` file you can use one environment variable `TORRUST_TRACKER_CONFIG` to pass the configuration to the tracker:
119+
//!
120+
//! ```text
121+
//! TORRUST_TRACKER_CONFIG=$(cat config.toml)
122+
//! cargo run
123+
//! ```
124+
//!
125+
//! In the previous example you are just setting the env var with the contents of the `config.toml` file.
126+
//!
127+
//! The env var contains the same data as the `config.toml`. It's particularly useful in you are [running the tracker with docker](https://github.com/torrust/torrust-tracker/tree/develop/docker).
128+
//!
129+
//! > NOTE: The `TORRUST_TRACKER_CONFIG` env var has priority over the `config.toml` file.
130+
//!
131+
//! # Usage
132+
//!
133+
//! Running the tracker with the default configuration and enabling the UDP and HTTP trackers will expose the services on these URLs:
134+
//!
135+
//! - REST API: <http://localhost:1212>
136+
//! - UDP tracker: <http://localhost:6969>
137+
//! - HTTP tracker: <http://localhost:7070>
138+
//!
139+
//! ## API usage
140+
//!
141+
//! In order to use the tracker API you need to enable it in the configuration:
142+
//!
143+
//! ```toml
144+
//! [http_api]
145+
//! enabled = true
146+
//! bind_address = "127.0.0.1:1212"
147+
//! ssl_enabled = false
148+
//! ssl_cert_path = ""
149+
//! ssl_key_path = ""
150+
//! ```
151+
//!
152+
//! By default it's enabled on port `1212`. You also need to can add access tokens in the configuration:
153+
//!
154+
//! ```toml
155+
//! [http_api.access_tokens]
156+
//! admin = "MyAccessToken"
157+
//! LABEL = "YOUR_TOKEN"
158+
//! ```
159+
//!
160+
//! 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:
161+
//!
162+
//! <http://127.0.0.1:1212/api/v1/stats?token=MyAccessToken>
163+
//!
164+
//! That endpoint will give you the tracker metrics:
165+
//!
166+
//! ```json
167+
//! {
168+
//! "torrents": 0,
169+
//! "seeders": 0,
170+
//! "completed": 0,
171+
//! "leechers": 0,
172+
//! "tcp4_connections_handled": 0,
173+
//! "tcp4_announces_handled": 0,
174+
//! "tcp4_scrapes_handled": 0,
175+
//! "tcp6_connections_handled": 0,
176+
//! "tcp6_announces_handled": 0,
177+
//! "tcp6_scrapes_handled": 0,
178+
//! "udp4_connections_handled": 0,
179+
//! "udp4_announces_handled": 0,
180+
//! "udp4_scrapes_handled": 0,
181+
//! "udp6_connections_handled": 0,
182+
//! "udp6_announces_handled": 0,
183+
//! "udp6_scrapes_handled": 0
184+
//! }
185+
//! ```
186+
//!
187+
//! Refer to the [`API`](crate::servers::apis) documentation for more information about the [`API`](crate::servers::apis) endpoints.
188+
//!
189+
//! ## HTTP tracker usage
190+
//!
191+
//! The HTTP tracker implements two type of requests:
192+
//!
193+
//! - Announce: <http://127.0.0.1:7070/announce>
194+
//! - Scrape: <http://127.0.0.1:7070/scrape>
195+
//!
196+
//! In you are using the tracker in `private` or `private_listed` mode you will need to append the authentication key:
197+
//!
198+
//! - Announce: <http://127.0.0.1:7070/announce/key>
199+
//! - Scrape: <http://127.0.0.1:7070/scrape/key>
200+
//!
201+
//! In order to use the HTTP tracker you need to enable at least one server in the configuration:
202+
//!
203+
//! ```toml
204+
//! [[http_trackers]]
205+
//! enabled = true
206+
//! bind_address = "0.0.0.0:7070"
207+
//! ```
208+
//!
209+
//! Refer to the [`HTTP`](crate::servers::http) documentation for more information about the [`HTTP`](crate::servers::http) tracker.
210+
//!
211+
//! ### Announce
212+
//!
213+
//! The `announce` request allows a peer to announce itself and obtain a list of peer for an specific torrent.
214+
//!
215+
//! A sample `announce` request:
216+
//!
217+
//! <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>
218+
//!
219+
//! If you want to know more about the `announce` request:
220+
//!
221+
//! - [BEP 03. The `BitTorrent` Protocol Specification](https://www.bittorrent.org/beps/bep_0003.html)
222+
//! - [BEP 23. Tracker Returns Compact Peer Lists](https://www.bittorrent.org/beps/bep_0023.html)
223+
//! - [Vuze announce docs](https://wiki.vuze.com/w/Announce)
224+
//!
225+
//! ### Scrape
226+
//!
227+
//! The `scrape` request allows a peer to get swarm metadata for multiple torrents at the same time.
228+
//!
229+
//! A sample `scrape` request for only one torrent:
230+
//!
231+
//! <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>
232+
//!
233+
//! The response contains the swarm metadata for that torrent:
234+
//!
235+
//! - `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.
236+
//! - `downloaded`: the number of peers that have ever completed downloading.
237+
//! - `incomplete`: the number of active peers that have not completed downloading, also known as leechers.
238+
//!
239+
//! The `scrape` response is a bencoded byte array like the following:
240+
//!
241+
//! ```text
242+
//! d5:filesd20:xxxxxxxxxxxxxxxxxxxxd8:completei11e10:downloadedi13772e10:incompletei19e20:yyyyyyyyyyyyyyyyyyyyd8:completei21e10:downloadedi206e10:incompletei20eee
243+
//! ```
244+
//!
245+
//! If you save the response as a file and you open it with a program that can handle binary data you would see:
246+
//!
247+
//! ```text
248+
//! 00000000: 6435 3a66 696c 6573 6432 303a 8100 0000 d5:filesd20:....
249+
//! 00000010: 0000 0000 0000 0000 0000 0000 0000 0000 ................
250+
//! 00000020: 6438 3a63 6f6d 706c 6574 6569 3165 3130 d8:completei1e10
251+
//! 00000030: 3a64 6f77 6e6c 6f61 6465 6469 3065 3130 :downloadedi0e10
252+
//! 00000040: 3a69 6e63 6f6d 706c 6574 6569 3065 6565 :incompletei0eee
253+
//! 00000050: 65 e
254+
//! ```
255+
//!
256+
//! `BitTorrent` uses a data formatting specification called [Bencode](https://en.wikipedia.org/wiki/Bencode).
257+
//!
258+
//! If you want to know more about the `scrape` request:
259+
//!
260+
//! - [BEP 48. Tracker Protocol Extension: Scrape](https://www.bittorrent.org/beps/bep_0048.html)
261+
//! - [Vuze scrape docs](https://wiki.vuze.com/w/Scrape)
262+
//!
263+
//! ### Authentication keys
264+
//!
265+
//! If the tracker is running in `private` or `private_listed` mode you will need to provide a valid authentication key.
266+
//!
267+
//! Right now the only way to add new keys is via the REST [`API`](crate::servers::apis). The endpoint `POST /api/vi/key/:duration_in_seconds`
268+
//! will return an expiring key that will be valid for `duration_in_seconds` seconds.
269+
//!
270+
//! Using `curl` you can create a 2-minute valid auth key:
271+
//!
272+
//! ```text
273+
//! $ curl -X POST http://127.0.0.1:1212/api/v1/key/120?token=MyAccessToken
274+
//! ```
275+
//!
276+
//! Response:
277+
//!
278+
//! ```json
279+
//! {
280+
//! "key": "nvCFlJCq7fz7Qx6KoKTDiMZvns8l5Kw7",
281+
//! "valid_until": 1679334334,
282+
//! "expiry_time": "2023-03-20 17:45:34.712077008 UTC"
283+
//! }
284+
//! ```
285+
//!
286+
//! You can also use the Torrust Tracker together with the [Torrust Index](https://github.com/torrust/torrust-index). If that's the case,
287+
//! the Index will create the keys by using the API.
288+
//!
289+
//! ## UDP tracker usage
290+
//!
291+
//! The UDP tracker also implements two type of requests:
292+
//!
293+
//! - Announce: <udp://127.0.0.1:6969>
294+
//! - Scrape: <udp://127.0.0.1:6969>
295+
//!
296+
//! In order to use the UDP tracker you need to enable at least one server in the configuration:
297+
//!
298+
//! ```toml
299+
//! [[udp_trackers]]
300+
//! enabled = true
301+
//! bind_address = "0.0.0.0:6969"
302+
//! ```
303+
//!
304+
//! Refer to the [`UDP`](crate::servers::udp) documentation for more information about the [`UDP`](crate::servers::udp) tracker.
305+
//!
306+
//! If you want to know more about the UDP tracker protocol:
307+
//!
308+
//! - [BEP 15. UDP Tracker Protocol for `BitTorrent`](https://www.bittorrent.org/beps/bep_0015.html)
309+
//!
310+
//! # Components
311+
//!
312+
//! Torrust Tracker has four main components:
313+
//!
314+
//! - The core [`tracker`](crate::tracker)
315+
//! - The tracker REST [`API`](crate::servers::apis)
316+
//! - The [`UDP`](crate::servers::udp) tracker
317+
//! - The [`HTTP`](crate::servers::http) tracker
318+
//!
319+
//! ![Torrust Tracker Components](https://github.com/torrust/torrust-tracker/blob/main/docs/media/torrust-tracker-components.png)
320+
//!
321+
//! ## Core tracker
322+
//!
323+
//! The core tracker is the main containing the tracker generic tracker logic.
324+
//!
325+
//! The core tracker handles:
326+
//!
327+
//! - Authentication with keys
328+
//! - Authorization using a torrent whitelist
329+
//! - Statistics
330+
//! - Persistence
331+
//!
332+
//! See [`tracker`](crate::tracker) for more details on the [`tracker`](crate::tracker) module.
333+
//!
334+
//! ## Tracker API
335+
//!
336+
//! The tracker exposes a REST API. The API has four resource groups:
337+
//!
338+
//! - Authentication keys: to handle the keys for the HTTP tracker
339+
//! - Statistics: to get the tracker metrics like requests counters
340+
//! - Torrents: to get peers for a torrent
341+
//! - Whitelist: to handle the torrent whitelist when the tracker runs on `listed` or `private_listed` mode
342+
//!
343+
//! See [`API`](crate::servers::apis) for more details on the REST API.
344+
//!
345+
//! ## UDP tracker
346+
//!
347+
//! UDP trackers are trackers with focus on performance. By Using UDP instead of HTTP the tracker removed the overhead
348+
//! of opening and closing TCP connections. It also reduces the response size.
349+
//!
350+
//! You can find more information about UDP tracker on:
351+
//!
352+
//! - [Wikipedia: UDP tracker](https://en.wikipedia.org/wiki/UDP_tracker)
353+
//! - [BEP 15: UDP Tracker Protocol for `BitTorrent`](https://www.bittorrent.org/beps/bep_0015.html)
354+
//!
355+
//! See [`UDP`](crate::servers::udp) for more details on the UDP tracker.
356+
//!
357+
//! ## HTTP tracker
358+
//!
359+
//! HTTP tracker was the original tracker specification defined on the [BEP 3]((https://www.bittorrent.org/beps/bep_0003.html)).
360+
//!
361+
//! See [`HTTP`](crate::servers::http) for more details on the HTTP tracker.
362+
//!
363+
//! You can find more information about UDP tracker on:
364+
//!
365+
//! - [Wikipedia: `BitTorrent` tracker](https://en.wikipedia.org/wiki/BitTorrent_tracker)
366+
//! - [BEP 3: The `BitTorrent` Protocol Specification](https://www.bittorrent.org/beps/bep_0003.html)
367+
//!
368+
//! # Implemented BEPs
369+
//!
370+
//! BEP stands for `BitTorrent` Enhancement Proposal. BEPs are documents providing information to the `BitTorrent`
371+
//! community or describing a new feature for the `BitTorrent` protocols.
372+
//!
373+
//! You can find all BEPs on <https://www.bittorrent.org/>
374+
//!
375+
//! Torrust Tracker implements these BEPs:
376+
//!
377+
//! - [BEP 3](https://www.bittorrent.org/beps/bep_0003.html): The `BitTorrent` Protocol
378+
//! - [BEP 7](https://www.bittorrent.org/beps/bep_0007.html): IPv6 Support
379+
//! - [BEP 15](https://www.bittorrent.org/beps/bep_0015.html): UDP Tracker Protocol for `BitTorrent`
380+
//! - [BEP 23](https://www.bittorrent.org/beps/bep_0023.html): Tracker Returns Compact Peer Lists
381+
//! - [BEP 27](https://www.bittorrent.org/beps/bep_0027.html): Private Torrents
382+
//! - [BEP 41](https://www.bittorrent.org/beps/bep_0041.html): UDP Tracker Protocol Extensions
383+
//! - [BEP 48](https://www.bittorrent.org/beps/bep_0048.html): Tracker Protocol Extension: Scrape
1384
pub mod app;
2385
pub mod bootstrap;
3386
pub mod servers;

0 commit comments

Comments
 (0)