node package manager

bittorrent-tracker

Simple, robust, BitTorrent tracker (client & server) implementation

bittorrent-tracker

Node.js implementation of a BitTorrent tracker, client and server.

A BitTorrent tracker is a web service which responds to requests from BitTorrent 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 participate in the torrent swarm.

This module is used by WebTorrent.

  • Includes client & server implementations
  • Supports all mainstream tracker types:
  • Supports ipv4 & ipv6
  • Supports tracker "scrape" extension
  • Robust and well-tested
  • Tracker statistics available via web interface at /stats or JSON data at /stats.json

Also see bittorrent-dht.

npm install bittorrent-tracker

To connect to a tracker, just do this:

var Client = require('bittorrent-tracker')
 
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) 
}
 
var optionalOpts = {
  // RTCPeerConnection config object (only used in browser) 
  rtcConfig: {},
  // custom webrtc impl, useful in node to specify [wrtc](https://npmjs.com/package/wrtc) 
  wrtc: {},
  getAnnounceOpts: function () {
    // provide a callback that will be called whenever announce() is called 
    // internally (on timer), or by the user 
    return {
      uploaded: 0,
      downloaded: 0,
      left: 0,
      customParam: 'blah' // custom parameters supported 
    }
  }
}
 
var client = new Client(requiredOpts)
 
client.on('error', function (err) {
  // fatal client error! 
  console.log(err.message)
})
 
client.on('warning', function (err) {
  // a tracker was unavailable or sent bad data to the client. you can probably ignore it 
  console.log(err.message)
})
 
// start getting peers from the tracker 
client.start()
 
client.on('update', function (data) {
  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)
})
 
client.once('peer', function (addr) {
  console.log('found a peer: ' + addr) // 85.10.239.191:48623 
})
 
// announce that download has completed (and you are now a seeder) 
client.complete()
 
// force a tracker announce. will trigger more 'update' events and maybe more 'peer' events 
client.update()
 
// provide parameters to the tracker 
client.update({
  uploaded: 0,
  downloaded: 0,
  left: 0,
  customParam: 'blah' // custom parameters supported 
})
 
// stop getting peers from the tracker, gracefully leave the swarm 
client.stop()
 
// ungracefully leave the swarm (without sending final 'stop' message) 
client.destroy()
 
// scrape 
client.scrape()
 
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)
  console.log('number of total downloads of this torrent: ' + data.downloaded)
})

To start a BitTorrent tracker server to track swarms of peers:

var Server = require('bittorrent-tracker').Server
 
var server = new Server({
  udp: true, // enable udp server? [default=true] 
  http: true, // enable http server? [default=true] 
  ws: true, // enable websocket server? [default=true] 
  stats: true, // enable web-based statistics? [default=true] 
  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. 
 
    // 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 
    // are available in `params`. 
 
    // This example only allows one torrent. 
 
    var allowed = (infoHash === 'aaa67059ed6bd08362da625b3ae77f6f4a075aaa')
    cb(allowed)
 
    // In addition to returning a boolean (`true` for allowed, `false` for disallowed), 
    // you can return an `Error` object to disallow and provide a custom reason. 
  }
})
 
// Internal http, udp, and websocket servers exposed as public properties. 
server.http
server.udp
server.ws
 
server.on('error', function (err) {
  // fatal server error! 
  console.log(err.message)
})
 
server.on('warning', function (err) {
  // client sent bad data. probably not a problem, just a buggy client. 
  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)
})
 
// start tracker server listening! Use 0 to listen on a random free port. 
server.listen(port, hostname, onlistening)
 
// listen for individual tracker messages from peers: 
 
server.on('start', function (addr) {
  console.log('got start message from ' + addr)
})
 
server.on('complete', function (addr) {})
server.on('update', function (addr) {})
server.on('stop', function (addr) {})
 
// 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

The http server will handle requests for the following paths: /announce, /scrape. Requests for other paths will not be handled.

Scraping multiple torrent info is possible with a static Client.scrape method:

var Client = require('bittorrent-tracker')
Client.scrape(announceUrl, [ infoHash1, infoHash2 ], function (err, results) {
  results[infoHash1].announce
  results[infoHash1].infoHash
  results[infoHash1].complete
  results[infoHash1].incomplete
  results[infoHash1].downloaded
 
  // ... 
})

Easily start a tracker server:

$ bittorrent-tracker
http server listening on 8000
udp server listening on 8000
ws server listening on 8000

Lots of options:

$ bittorrent-tracker --help
  bittorrent-tracker - Start a bittorrent tracker server
 
  Usage:
    bittorrent-tracker [OPTIONS]
 
  If no --http, --udp, or --ws option is supplied, all tracker types will be started.
 
  Options:
    -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
 
  Please report bugs!  https://github.com/feross/bittorrent-tracker/issues

MIT. Copyright (c) Feross Aboukhadijeh.