bittorrent-tracker/README.md

278 lines
8.8 KiB
Markdown
Raw Normal View History

2017-03-21 02:28:34 +00:00
# bittorrent-tracker [![travis][travis-image]][travis-url] [![npm][npm-image]][npm-url] [![downloads][downloads-image]][downloads-url] [![javascript style guide][standard-image]][standard-url]
2015-01-22 22:28:06 +00:00
2016-01-13 22:34:49 +00:00
[travis-image]: https://img.shields.io/travis/feross/bittorrent-tracker/master.svg
2015-01-22 22:28:06 +00:00
[travis-url]: https://travis-ci.org/feross/bittorrent-tracker
2016-01-13 22:34:49 +00:00
[npm-image]: https://img.shields.io/npm/v/bittorrent-tracker.svg
2015-01-22 22:28:06 +00:00
[npm-url]: https://npmjs.org/package/bittorrent-tracker
2016-01-13 22:34:49 +00:00
[downloads-image]: https://img.shields.io/npm/dm/bittorrent-tracker.svg
2015-01-22 22:28:06 +00:00
[downloads-url]: https://npmjs.org/package/bittorrent-tracker
2017-03-21 02:28:34 +00:00
[standard-image]: https://img.shields.io/badge/code_style-standard-brightgreen.svg
[standard-url]: https://standardjs.com
2014-03-26 08:37:13 +00:00
2014-03-27 07:39:14 +00:00
#### Simple, robust, BitTorrent tracker (client & server) implementation
2014-03-26 08:37:13 +00:00
2014-03-27 07:45:25 +00:00
![tracker](https://raw.githubusercontent.com/feross/bittorrent-tracker/master/img.png)
2014-03-26 08:37:13 +00:00
Node.js implementation of a [BitTorrent tracker](https://wiki.theory.org/BitTorrentSpecification#Tracker_HTTP.2FHTTPS_Protocol), client and server.
2016-07-06 02:13:30 +00:00
A **BitTorrent tracker** is a web service which responds to requests from BitTorrent
2014-03-26 08:37:13 +00:00
clients. The requests include metrics from clients that help the tracker keep overall
statistics about the torrent. The response includes a peer list that helps the client
2015-11-22 02:22:48 +00:00
participate in the torrent swarm.
2014-03-26 08:37:13 +00:00
2015-01-26 03:17:51 +00:00
This module is used by [WebTorrent](http://webtorrent.io).
2014-03-26 08:37:13 +00:00
2014-03-28 04:08:20 +00:00
## features
2015-11-22 02:23:45 +00:00
- Includes client & server implementations
- Supports all mainstream tracker types:
2015-11-22 02:22:48 +00:00
- HTTP trackers
- UDP trackers ([BEP 15](http://www.bittorrent.org/beps/bep_0015.html))
- WebTorrent trackers ([BEP forthcoming](http://webtorrent.io))
2015-11-22 02:23:45 +00:00
- Supports ipv4 & ipv6
- Supports tracker "scrape" extension
- Robust and well-tested
- Comprehensive test suite (runs entirely offline, so it's reliable)
- Used by popular clients: [WebTorrent](http://webtorrent.io), [peerflix](https://github.com/mafintosh/peerflix), and [playback](https://mafintosh.github.io/playback/)
2016-06-07 08:49:27 +00:00
- Tracker statistics available via web interface at `/stats` or JSON data at `/stats.json`
2014-03-28 04:08:20 +00:00
2015-01-26 03:17:51 +00:00
Also see [bittorrent-dht](https://github.com/feross/bittorrent-dht).
2014-03-27 07:45:25 +00:00
## install
2014-03-26 08:37:13 +00:00
```
npm install bittorrent-tracker
```
2014-03-27 07:45:25 +00:00
## usage
2014-03-27 07:39:14 +00:00
2014-03-27 07:45:25 +00:00
### client
2014-03-26 08:37:13 +00:00
To connect to a tracker, just do this:
```js
var Client = require('bittorrent-tracker')
2014-03-26 08:37:13 +00:00
var requiredOpts = {
infoHash: new Buffer('012345678901234567890'), // hex string or Buffer
peerId: new Buffer('01234567890123456789'), // hex string or Buffer
announce: [], // list of tracker server urls
port: 6881 // torrent client port, (in browser, optional)
}
2014-03-26 08:37:13 +00:00
var optionalOpts = {
2016-03-01 02:16:08 +00:00
getAnnounceOpts: function () {
2017-01-16 23:43:47 +00:00
// Provide a callback that will be called whenever announce() is called
2016-03-01 02:16:08 +00:00
// internally (on timer), or by the user
return {
uploaded: 0,
downloaded: 0,
left: 0,
customParam: 'blah' // custom parameters supported
}
}
2017-01-16 23:43:47 +00:00
// RTCPeerConnection config object (only used in browser)
rtcConfig: {},
// User-Agent header for http requests
userAgent: '',
// Custom webrtc impl, useful in node to specify [wrtc](https://npmjs.com/package/wrtc)
wrtc: {},
2016-03-01 02:16:08 +00:00
}
var client = new Client(requiredOpts)
2014-03-26 08:37:13 +00:00
client.on('error', function (err) {
// fatal client error!
2014-03-26 08:37:13 +00:00
console.log(err.message)
})
client.on('warning', function (err) {
2014-03-26 08:37:13 +00:00
// a tracker was unavailable or sent bad data to the client. you can probably ignore it
console.log(err.message)
2014-03-26 08:37:13 +00:00
})
2014-03-26 09:11:27 +00:00
// start getting peers from the tracker
client.start()
2014-03-26 08:37:13 +00:00
client.on('update', function (data) {
2014-05-12 00:29:12 +00:00
console.log('got an announce response from tracker: ' + data.announce)
console.log('number of seeders in the swarm: ' + data.complete)
console.log('number of leechers in the swarm: ' + data.incomplete)
2014-03-26 08:37:13 +00:00
})
client.once('peer', function (addr) {
console.log('found a peer: ' + addr) // 85.10.239.191:48623
})
2014-03-26 09:11:27 +00:00
// announce that download has completed (and you are now a seeder)
client.complete()
2014-03-26 08:37:13 +00:00
2014-03-26 09:11:27 +00:00
// force a tracker announce. will trigger more 'update' events and maybe more 'peer' events
client.update()
2014-03-26 08:37:13 +00:00
2016-03-01 02:16:08 +00:00
// provide parameters to the tracker
client.update({
uploaded: 0,
downloaded: 0,
left: 0,
customParam: 'blah' // custom parameters supported
})
2014-03-26 09:11:27 +00:00
// stop getting peers from the tracker, gracefully leave the swarm
client.stop()
2014-05-12 00:29:12 +00:00
// ungracefully leave the swarm (without sending final 'stop' message)
client.destroy()
2014-05-12 00:29:12 +00:00
// scrape
2014-06-06 08:21:01 +00:00
client.scrape()
2014-05-12 00:29:12 +00:00
client.on('scrape', function (data) {
console.log('got a scrape response from tracker: ' + data.announce)
console.log('number of seeders in the swarm: ' + data.complete)
console.log('number of leechers in the swarm: ' + data.incomplete)
2015-12-18 15:02:52 +00:00
console.log('number of total downloads of this torrent: ' + data.downloaded)
2014-05-12 00:29:12 +00:00
})
2014-03-26 08:37:13 +00:00
```
2014-03-27 07:45:25 +00:00
### server
2014-03-27 07:39:14 +00:00
To start a BitTorrent tracker server to track swarms of peers:
2014-03-26 08:37:13 +00:00
```js
var Server = require('bittorrent-tracker').Server
2014-05-24 01:06:29 +00:00
var server = new Server({
udp: true, // enable udp server? [default=true]
http: true, // enable http server? [default=true]
2015-07-29 08:47:09 +00:00
ws: true, // enable websocket server? [default=true]
2016-03-30 07:31:51 +00:00
stats: true, // enable web-based statistics? [default=true]
2015-07-05 00:15:07 +00:00
filter: function (infoHash, params, cb) {
// Blacklist/whitelist function for allowing/disallowing torrents. If this option is
// omitted, all torrents are allowed. It is possible to interface with a database or
// external system before deciding to allow/deny, because this function is async.
2015-02-19 20:56:09 +00:00
// It is possible to block by peer id (whitelisting torrent clients) or by secret
// key (private trackers). Full access to the original HTTP/UDP request parameters
2015-12-01 06:27:59 +00:00
// are available in `params`.
2015-07-05 00:15:07 +00:00
// This example only allows one torrent.
var allowed = (infoHash === 'aaa67059ed6bd08362da625b3ae77f6f4a075aaa')
if (allowed) {
// If the callback is passed `null`, the torrent will be allowed.
cb(null)
} else {
// If the callback is passed an `Error` object, the torrent will be disallowed
// and the error's `message` property will be given as the reason.
cb(new Error('disallowed torrent'))
}
}
2014-05-24 01:06:29 +00:00
})
2014-03-27 07:36:46 +00:00
// Internal http, udp, and websocket servers exposed as public properties.
server.http
server.udp
server.ws
2014-03-27 07:36:46 +00:00
server.on('error', function (err) {
2014-05-24 01:05:18 +00:00
// fatal server error!
console.log(err.message)
})
server.on('warning', function (err) {
// client sent bad data. probably not a problem, just a buggy client.
2014-03-27 07:36:46 +00:00
console.log(err.message)
})
server.on('listening', function () {
// fired when all requested servers are listening
console.log('listening on http port:' + server.http.address().port)
console.log('listening on udp port:' + server.udp.address().port)
2014-03-27 07:36:46 +00:00
})
// start tracker server listening! Use 0 to listen on a random free port.
server.listen(port, hostname, onlistening)
2014-03-27 07:47:12 +00:00
2014-03-27 07:36:46 +00:00
// listen for individual tracker messages from peers:
server.on('start', function (addr) {
2014-03-27 07:36:46 +00:00
console.log('got start message from ' + addr)
})
server.on('complete', function (addr) {})
server.on('update', function (addr) {})
server.on('stop', function (addr) {})
2014-03-27 07:36:46 +00:00
// get info hashes for all torrents in the tracker server
Object.keys(server.torrents)
// get the number of seeders for a particular torrent
server.torrents[infoHash].complete
// get the number of leechers for a particular torrent
server.torrents[infoHash].incomplete
// get the peers who are in a particular torrent swarm
server.torrents[infoHash].peers
2014-03-26 08:37:13 +00:00
```
2014-07-04 03:05:02 +00:00
The http server will handle requests for the following paths: `/announce`, `/scrape`. Requests for other paths will not be handled.
## multi scrape
Scraping multiple torrent info is possible with a static `Client.scrape` method:
```js
var Client = require('bittorrent-tracker')
Client.scrape({ announce: announceUrl, infoHash: [ infoHash1, infoHash2 ]}, function (err, results) {
results[infoHash1].announce
results[infoHash1].infoHash
results[infoHash1].complete
results[infoHash1].incomplete
results[infoHash1].downloaded
// ...
})
````
2015-03-20 10:01:44 +00:00
## command line
2015-03-20 10:02:43 +00:00
Easily start a tracker server:
2015-03-20 10:01:44 +00:00
```sh
$ bittorrent-tracker
http server listening on 8000
udp server listening on 8000
ws server listening on 8000
2015-03-20 10:01:44 +00:00
```
Lots of options:
```sh
2015-03-20 10:02:43 +00:00
$ bittorrent-tracker --help
2015-03-20 10:01:44 +00:00
bittorrent-tracker - Start a bittorrent tracker server
Usage:
2015-11-22 02:00:55 +00:00
bittorrent-tracker [OPTIONS]
If no --http, --udp, or --ws option is supplied, all tracker types will be started.
2015-03-20 10:01:44 +00:00
Options:
2015-11-22 02:00:55 +00:00
-p, --port [number] change the port [default: 8000]
--trust-proxy trust 'x-forwarded-for' header from reverse proxy
--interval client announce interval (ms) [default: 600000]
--http enable http server
--udp enable udp server
--ws enable websocket server
-q, --quiet only show error output
-s, --silent show no output
-v, --version print the current version
2015-03-20 10:01:44 +00:00
Please report bugs! https://github.com/feross/bittorrent-tracker/issues
```
2014-03-26 08:37:13 +00:00
## license
MIT. Copyright (c) [Feross Aboukhadijeh](http://feross.org).