root/dotorg/trunk/html/beps/bep_0028.rst

BEP: 28
Title: Tracker exchange extension
Version: $Revision$
Last-Modified: $Date$
Author:  Arvid Norberg <arvid@bittorrent.com>
Status:  Draft
Type:    Standards Track
Content-Type: text/x-rst
Created: 26-Nov-2008
Post-History: 15-Oct-2009: Add a section on not hammering bad trackers

Tracker exchange extension
==========================

This extension makes it possible for BitTorrent peers to learn about new
trackers for a swarm they have joined. Ideally ending up with every peer
knowing about every tracker used for the torrent.

rationale
---------

There are mainly two scenarios where it's desirable for a peer to learn
about trackers that other peers are using:

1. If the peer joined the swarm via a magnet link (`BEP 9`_), bootstrapping
   by joining peers from the DHT. The number of peers that's accessable might
   not be sufficient. Announcing with a tracker could make a significant
   difference for the peer, receiving more peers.

2. If the tracker the peer joined only know of a small number of peers, but
   there are other peers (acquired from DHT for instance) that are using
   a much more popular tracker, the peer might want to announce with that
   other tracker in order to receive enough peers.

This extension is designed to have minimal impact on the common case of every
peer knowing of the exact same trackers. This case is recognized as
the dominant case, and is important to not add any penalty in terms of
bandwidth, since that might deter implementors from adopting this extension.

.. _`BEP 9`: http://www.bittorrent.org/beps/bep_0009.html

definitions
===========

In this extension, every peer has a list of trackers. In this list are only
*verified trackers*. A verified tracker is a tracker that either was in the
.torrent file that was loaded (just like without this extension, they are
assumed to be good) or a tracker that we have received over the TEX protocol
*and* received a successful response from.

The tracker list used by this extension is hence different from the tracker
list used by the client itself, since it does not include some trackers that
we have never successfully announced with. This list of trackers is the only
list of verified trackers referred to in this extension, unless explicitly
stated otherwise.

The extension message is used to send *changes* to the tracker list to other
peers. If the peers have different tracker lists on handshake, the first
message MUST contain the full list of trackers. Any subsequent message SHOULD
only contain added trackers. If the peers have the same tracker list when
connecting, the first extension message SHOULD only contain added trackers.


extension header
================

The tracker exchange extension (TEX for short) uses the extension protocol
(specified in `BEP 10`_) to advertize support. It adds the "lt_tex" entry
to the "m" dictionary in the extension header hand-shake message. This identifies
the message code used for this message. It also adds "tr" to the handshake message
specifying a hash of the current tracker list this peer has for this torrent.

.. _`BEP 10`: http://www.bittorrent.org/beps/bep_0010.html

Example extension handshake message::

{'m': {'lt_tex', 3}, 'tr': '426c8fe69d59ce85626177749d66e864cc39a82d'}

Note that the string under the 'tr' key is *binary*. It is printed as a hex encoded
string here for clarity. It is always supposed to be 20 bytes.

The tracker list hash is computed as follows:

1. All tracker urls are put in a list
2. All urls SHOULD be normalized

   1. the protocol part (before the '://') is made lower case
   2. the hostname is made lower case
   3. the path and argument components are quote-normalized. Any %-encoding
      that decodes into an ``unreserved`` character (as defined by `RFC 2396`_)
      should be decoded. Any remaining encoded characters should use lower case
      hex encoding. i.e. ``%ff`` instead of ``%FF``

3. The list of urls is sorted in ascending lexicographical order. Where each byte
   is interpreted as its ascii value, and sorted by it.
4. The SHA-1 hash is constructed of the concatenation of all urls in the order in
   the list.

.. _`RFC 2396`: http://www.ietf.org/rfc/rfc2396.txt

The wording "SHOULD" in point 2 means that an implementation that skips this step
is assumed to work efficiently in the vast majority of cases, but might be slightly
more susceptible to attacks.

The tracker list hash in the handshake is used to compare with ones own tracker list.
In most cases it is assumed that this hash will be the same for both peers. If this is
the case, the client SHOULD assume that the peers have the same list, and not send a
full tracker list message.


extension message
=================

The extension message is sent on a regular interval. It is recommended not to be sent
more often than every 2 minutes.

Any message that does not contain any new trackers SHOULD be omitted (i.e. not sent
at all).

The extension message is bencoded and contains a single key: ``added`` which is a list
of strings. Each string is the url of a tracker that was added since the last update.

example message::

        { 'added': ['http://tracker.bittorrent.com/announce', 'http://tracker2.bittorrent.com'] }

trackers
========

Trackers discovered through this protocol SHOULD be treated with a certain amount of
suspicion. Since the source of a tracker exchange message cannot be trusted, an
implementation SHOULD have a lower number of retries before giving up entirely.

Also, as specified under the definitions_ section, a tracker that has not worked
should never be propagated to other peers over the tracker exchange protocol.



..
   Local Variables:
   mode: indented-text
   indent-tabs-mode: nil
   sentence-end-double-space: t
   fill-column: 70
   coding: utf-8
   End: