summaryrefslogtreecommitdiff
path: root/stories/projects/opentracker.rst
blob: 294d2c932328dfa76807386e282e03704bf2b213 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
.. link:
.. description: is a highly scalable tracker software for the bittorrent protocol, currently in use on the largest bulk trackers around.
.. tags: project
.. date: 2015/02/19 19:10:08
.. title: opentracker
.. subtitle: An open and free bittorrent tracker
.. slug: ../arts/software/opentracker/index
.. prio: 1000

.. contents::
  :depth: 1
  :class: ezjail-toc

----

.. image:: opentracker_beta3.png
  :align: left
  :width: 200px

Overview
========

*opentracker* is a open and free `bittorrent tracker <http://wiki.theory.org/BitTorrentSpecification>`_ project. It aims for minimal resource usage and is intended to run at your wlan router. Currently it is deployed as an open and free tracker instance. Read our `free and open tracker blog <http://opentracker.blog.h3q.com/>`_ and announce your torrents there (but do not hesitate to setup your own free trackers!).

----

Version History
===============

*opentracker* is currently only available from CVS. A tar ball will be rolled soon. Use ``git clone git://erdgeist.org/opentracker`` or the legacy view ``cvs -d :pserver:anoncvs@cvs.erdgeist.org:/home/cvsroot co opentracker`` with an empty passwort to check it out. An `*opentracker* gitweb </gitweb/opentracker/>`_ and an `*opentracker* cvsweb (deprecated) </cvsweb/opentracker/>`_ are available.

----

Build instructions
==================

Until *opentracker* is declared official release ready, the way to install it is::

  cvs -d :pserver:cvs@cvs.fefe.de:/cvs -z9 co libowfat
  cd libowfat
  make
  cd ..
  # LEGACY: cvs -d:pserver:anoncvs@cvs.erdgeist.org:/home/cvsroot co opentracker
  git clone git://erdgeist.org/opentracker
  cd opentracker
  make

That should leave you with an exectuable called ``opentracker`` and one debug version ``opentracker.debug``.

Some variables in *opentracker*'s Makefile control features and behaviour of *opentracker*. Here they are:

* ``-DWANT_V6`` makes *opentracker* an IPv6-only tracker. More in the v6-section below.
* *opentracker* can deliver gzip compressed full scrapes. Enable this with ``-DWANT_COMPRESSION_GZIP`` option.
* Normally *opentracker* tracks any torrent announced to it. You can change that behaviour by enabling ONE of ``-DWANT_ACCESSLIST_BLACK`` or ``-DWANT_ACCESSLIST_WHITE``. Note, that you have to provide a whitelist file in order to make *opentracker* do anything in the latter case. More in the closed mode section below.
* *opentracker* can run in a cluster. Enable this behaviour by enabling ``-DWANT_SYNC_LIVE``. Note, that you have to configure your cluster before you can use *opentracker* when this option is on.
* Some statistics *opentracker* can provide are sensitive. You can restrict access to these statistics by enabling ``-DWANT_RESTRICT_STATS``. See section statistics for more details.
* Fullscrapes is bittorrent's way to query a tracker for all tracked torrents. Since it's in the standard, it is enabled by default. Disable it by commenting out ``-DWANT_FULLSCRAPE``.
* By default *opentracker* will only allow the connecting endpoint's IP address to be announced. Bittorrent standard allows clients to provide an IP address in its query string. You can make *opentracker* use this IP address by enabling ``-DWANT_IP_FROM_QUERY_STRING``.
* Some experimental or older, deprecated features can be enabled by the ``-DWANT_LOG_NETWORKS``, ``-DWANT_SYNC_SCRAPE`` or ``-DWANT_IP_FROM_PROXY`` switch.
* Currently there is some packages for some linux distributions and OpenBSD around, but some of them patch Makefile and default config to make *opentracker* closed by default. I explicitly don't endorse those packages and will not give support for problems stemming from these missconfigurations.

----

Invocation
==========

*opentracker* can be run by just typing ``./opentracker``. This will make *opentracker* bind to ``0.0.0.0:6969`` and happily serve all torrents presented to it. If ran as root, *opentracker* will immediately chroot to . (or any directory given with the -d option) and drop all priviliges after binding to whatever tcp or udp ports it is requested.

When options were few, *opentracker* used to accept all of them from command line. While this still is possible for most options, using them is quite unhandy: an example invocation would look like ``./opentracker -i 23.23.23.7 -p 80 -P 80 -p 6969 -i 23.23.23.8 -p 80 -r http://www.mytorrentsite.com/ -d /usr/local/etc/opentracker -w mytorrents.list -A 127.0.0.1``.

*opentracker* now uses a config file that you can provide with the ``-f`` switch.

----

Config file
===========

*opentracker*'s config file is very straight forward and a very well documented example config can be found in the file `opentracker.conf.sample </gitweb/opentracker/tree/opentracker.conf.sample>`_.

----

Closed mode
===========

While personally I like my tracker to be open, I can see that there's people that want to control what torrents to track – or not to track. If you've compiled *opentracker* with one of the accesslist-options (see Build instructions above), you can control which torrents are tracked by providing a file that contains a list of human readable info_hashes. An example whitelist file would look like ::

  0123456789abcdef0123456789abcdef01234567
  890123456789abcdef0123456789abcdef012345

To make *opentracker* reload it's white/blacklist, send a ``SIGHUP`` unix signal.

----

Statistics
==========

Given its very network centric approach, talking to *opentracker* via http comes very naturally. Besides the ``/announce`` and ``/scrape`` paths, there is a third path you can access the tracker by: ``/stats``. This request takes parameters, for a quick overview just inquire `/stats?mode=everything``.

Statistics have grown over time and are currently not very tidied up. Most modes were written to dump legacy-SNMP-style blocks that can easily be monitored by `MRTG <http://oss.oetiker.ch/mrtg/>`_. These modes are: ``peer``, ``conn``, ``scrp``, ``udp4``, ``tcp4``, ``busy``, ``torr``, ``fscr``, ``completed``, ``syncs``. I'm not going to explain these here.

The ``statedump`` mode dumps non-recreatable states of the tracker so you can later reconstruct an *opentracker* session with the -l option. This is beta and wildly undocumented.

You can inquire *opentracker*'s version (i.e. CVS versions of all its objects) using the ``version`` mode.

----

Philosophy
==========

A torrent tracker basically is an http-Server that collects all clients ip addresses into pools sorted by one of the request strings parameters and answers all other clients that specified this exact same parameter a list of all other recent clients. All technologies to implement this are around for more than twenty years. Still most implementations suck performancewise.

Utilizing the highly scalable server framework from `libowfat <http://www.fefe.de/libowfat/>`_, *opentracker* can easily serve multiple thousands of requests on a standard plastic WLAN-router, limited only by your kernels capabilities ;)

One important design decision of *opentracker* was to not store any data persistently. This reduces wear&tear on hard disks and eliminates problems with corrupt databases.

----

Author
======

*opentracker* was written by `Dirk Engling <mailto:erdgeist@erdgeist.org>`_, who likes to hear from happy customers.

----

Thanks
======

A project like this one is impossible without lots of help from friends. It is powered by beer, much energy and love, batches of bug reports and support on the operating system integration side by denis, taklamakan, cryx, supergrobi and – his libowfat always on the bleeding edge – Fefe. Thanks are also due to Hannes for helping me out with designing internal data representation.

----

License
=======

*opentracker* is considered `beer ware </beerware.html>`_.