diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000..7585238 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1 @@ +book diff --git a/docs/book.toml b/docs/book.toml new file mode 100644 index 0000000..e8fea44 --- /dev/null +++ b/docs/book.toml @@ -0,0 +1,10 @@ +[book] +authors = ["Naim A."] +title = "UDPT v3" +description = "UDPT v3 User Guide" + +[build] +create-missing = false + +[output.html] +google-analytics = "UA-11289087-19" diff --git a/docs/src/README.md b/docs/src/README.md new file mode 100644 index 0000000..0575cde --- /dev/null +++ b/docs/src/README.md @@ -0,0 +1,25 @@ +# UDPT + +- Project Page: [github.com/naim94a/udpt](https://github.com/naim94a/udpt) +- Documentation: [naim94a.github.io/udpt](https://naim94a.github.io/udpt) + +UDPT is a lightweight torrent tracker that uses the UDP protocol for tracking and fully implements [BEP-15](http://bittorrent.org/beps/bep_0015.html). +This project was developed with security & simplicity in mind, so it shouldn't be difficult to get a server started. + +Unlike most HTTP torrent-trackers, you can save about 50% bandwidth using a UDP tracker. + +## Features +- UDP tracking protocol +- Simple [TOML](https://en.wikipedia.org/wiki/TOML) configuration +- [HTTP REST API](./api.md) +- Logging +- Choice to run in *static* or *dynamic* modes +- Blacklist torrents using the REST API +- Can be built/run on many platforms +- (Re)written in [Rust](https://www.rust-lang.org/) + +## Licenses +UDPT available under the [MIT license](https://github.com/naim94a/udpt/blob/master/LICENSE). + +## About +Originally written in C++ by [@naim94a](https://github.com/naim94a) in 2012 for fun. diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md new file mode 100644 index 0000000..0a21a94 --- /dev/null +++ b/docs/src/SUMMARY.md @@ -0,0 +1,9 @@ +# Summary + +[UDPT](README.md) + +* [Building](./build.md) +* [Configuration](./config.md) + - [Tracking Modes](tracking_modes.md) +* [Usage](./usage.md) +* [REST API](./api.md) diff --git a/docs/src/api.md b/docs/src/api.md new file mode 100644 index 0000000..eadd1b9 --- /dev/null +++ b/docs/src/api.md @@ -0,0 +1,39 @@ +# REST API +The REST API can help you manage UDPT with your own scripts. + +__**Notice:**__ +The API should only be used in trusted networks. +APIs should not be exposed directly to the internet, they are intended for internal use only. + +## Endpoints + +All Endpoints require a authorization token which must be set in the configuration before running the tracker. + +- Listing Torrents + + This can be useful if you want to see which torrents are currently registered in any of the tracking modes. + + `GET /t?offset=0&limit=1000&token=... HTTP/1.0` + + Optional Parameters: + - `offset` - Offset of the torrent list to return. Default: 0. + - `limit` - Limit of torrents to output. Between 1 and 4096. Default 1000. + +- Getting a torrent's stats + + Allows collection of stats from active torrents. + + `GET /t/?token=... HTTP/1.0` + + This request will return information about the torrent, such as: + - if the torrent is flagged + - seeders & leechers + - times the torrent's download was completed + +- Preforming actions on torrents + + `POST /t/&action=&token=... HTTP/1.0` + + Valid actions are: `flag`, `unflag`, `add` & `remove`. + + `add` & `remove` are only valid for non-dynamic tracking modes. \ No newline at end of file diff --git a/docs/src/build.md b/docs/src/build.md new file mode 100644 index 0000000..62ef61f --- /dev/null +++ b/docs/src/build.md @@ -0,0 +1,35 @@ +# Building UDPT +If you're reading this, you're probably interested in using UDPT - so first, thanks for your interest! + +UDPT used to be harder to build, especially on Windows due to it's dependencies. Thanks to Rust, it's much simpler now. + +## Required tools +- [Git](https://git-scm.com) - Version Control +- [Rust](https://www.rust-lang.org/) - Compiler toolchain & Package Manager (cargo) + +### Getting the sources +``` +git clone https://github.com/naim94a/udpt.git +``` + +If you prefer to just download the code, you can get the [latest codebase here](https://github.com/naim94a/udpt/archive/master.zip). + +### Building +This step will download all required dependencies (from [crates.io](https://crates.io/)) and build them as well. + +Building should always be done with the latest Rust compiler. + +``` +cd udpt +cargo build --release +``` + +Once cargo is done building, `udpt` will be built at `target/release/udpt`. + +### Running Tests +UDPT comes with unit tests, they can be run with the following command: +``` +cargo test +``` + +If a build or test fails, please submit Issues to [UDPT's issue tracker](https://github.com/naim94a/udpt/issues). \ No newline at end of file diff --git a/docs/src/config.md b/docs/src/config.md new file mode 100644 index 0000000..f10b03c --- /dev/null +++ b/docs/src/config.md @@ -0,0 +1,45 @@ +# Configuring UDPT +UDPT's configuration is a simple TOML file. + +## Configuration +At the root level, the following options are configurable: +`mode` - Specifies which mode the tracker will operate in. Values can be `static`, `dynamic` or `private`. + +### Root Level +- `mode` - Required. Possbile Values: `private`, `static` or `dynamic`. +- `log_level` - Default: `info`. Possible Values: `off`, `error`, `warning`, `info`, `debug`, `trace`. +- `db_path` - Database path. If not set, database will be volatile. +- `cleanup_interval` - Default: 600. Interval to run cleanup in seconds. Cleanup also saves the Database. + +### `[udp]` section +This section must exist. + +- `bind_address` - Required. This is where the UDP port will bind to. Example: `0.0.0.0:6969`. +- `announce_interval` - Required. Sets the `announce_interval` that will be sent to peers (in seconds). + +### `[http]` section +This section is optional. + +- `bind_address` - Required (if section exists). The HTTP REST API will be bound to this address. It's best not to expose this address publically. Example: `127.0.0.1:1234`. + +### `[http.access_tokens]` section +Section is required if `[http]` section exists. + +In this section you can make up keys that would be user ids, and values that would be their access token. +If this section is empty, the REST API will not be very useful. + +## Sample Configuration +```toml +mode = "dynamic" +db_path = "database.json.bz2" + +[udp] +announce_interval = 120 # Two minutes +bind_address = "0.0.0.0:1212" + +[http] +bind_address = "127.0.0.1:1212" + +[http.access_tokens] +someone = "MyAccessToken" +``` diff --git a/docs/src/tracking_modes.md b/docs/src/tracking_modes.md new file mode 100644 index 0000000..eea3bba --- /dev/null +++ b/docs/src/tracking_modes.md @@ -0,0 +1,24 @@ +# Tracking Modes +UDPT currently supports Static & Dynamic tracking modes. +Private tracking is planned, but isn't yet completely implemented. + +## Dynamic Mode +In this mode a tracker allows any torrent, even if unknown to be tracked. +Trackers that run in this mode usually don't know about the contents of the tracked torrent. +In addition, trackers don't usually know anything about the peers. + +UDPT supports dynamic mode, and allows blacklisting torrents to avoid copyright infringement. +Torrents can be blacklisted (or "flagged") using the REST API. + +## Static Mode +In static mode, anyone can use the tracker like in dynamic mode. +Except that torrents must be registered ahead of time. + +UDPT supports static mode, and torrents can be added or removed using the REST API. + +## Private Mode +Private tracking requires all peers to be authenticated. +Some implementations require torrents to be registered, and some do not. +This mode can be either static or dynamic with peer authentication. + +UDPT doesn't currently implement private mode, although there are plans to implement private tracking in the future. diff --git a/docs/src/usage.md b/docs/src/usage.md new file mode 100644 index 0000000..f359c0e --- /dev/null +++ b/docs/src/usage.md @@ -0,0 +1,4 @@ +# Usage +At the moment, `udpt` doesn't have many options. Once you've modified the configuration file, you could start `udpt`: + + udpt -c configuration.toml \ No newline at end of file