BitTorrent Tracker Protocol
This page describes the tracker protocol of BT1 version. The original protocol was designed by Bram Cohen.
Introduction
The BitTorrent tracker protocol is used by clients to request the IP addresses of other peers associated with a torrent, and to exchange the client's transfer statistics. Clients contact a centralized server, known as a *tracker*, which stores their addresses and responds with the addresses of other clients (also known as *peers*). The tracker does not know which nodes have which pieces; its job is to tell its clients where to find each other.
The standard tracker protocol is based on HTTP, with request data encoded as query parameters (as used by HTML forms) and response data BEncoded.
Query parameters must be encoded according to the rules for HTML form submissions through HTTP GET: 'reserved character' bytes are encoded in hexadecimal as %HH, and space is encoded as "+"; names and values are joined with "=" and the pairs joined with "&". (Python users can use urllib.urlencode and urllib.quote_plus.)
The tracker's announce URL is obtained from the announce entry of the root dictionary of the torrent metadata file.
'Extension: If an [AnnounceList] is present in the torrent metadata file, a compatible client should use the list of trackers in order to obtain the list of connected peers downloading the same torrent.
Clients announce themselves by sending a GET request to the tracker's announce URL with "?" and the following parameters (encoded as above) appended:
Basic Tracker Announce Request
- info_hash
- The 20 byte sha1 hash of the bencoded form of the info value from the metainfo file. Note that this is a substring of the metainfo file. Don't forget to URL-encode this.
- peer_id
- A string of length 20 which this downloader uses as its id. Each downloader generates its own id at random at the start of a new download. Don't forget to URL-encode this.
- ip
- An optional parameter giving the IP (or dns name) which this peer is at. Generally used for the origin if it's on the same machine as the tracker; otherwise it's not normally needed.
- port
- Port number this peer is listening on. Common behavior is for a downloader to try to listen on port 6881 and if that port is taken try 6882, then 6883, etc. and give up after 6889.
- uploaded
- Total amount uploaded so far, represented in base ten in ASCII.
- downloaded
- Total amount downloaded so far, represented in base ten in ASCII.
- left
- Number of bytes this client still has to download, represented in base ten in ASCII. Note that this can't be computed from downloaded and the file length since the client might be resuming an earlier download, and there's a chance that some of the downloaded data failed an integrity check and had to be re-downloaded.
- event
- Optional key which maps to
started,completed, orstopped(or empty, which is the same as not being present). If not present, this is one of the announcements done at regular intervals. An announcement using started is sent when a download first begins, and one using completed is sent when the download is complete. No completed is sent if the file was complete when started. Downloaders should send an announcement using 'stopped' when they cease downloading, if they can.
- numwant
- Optional key tells the tracker how many addresses the client wants in the tracker's response. The tracker does not have to supply that many. Default is 50.
Extensions
- no_peer_id
- Ask the tracker to 'not send the peer id information.
- compact
- Indicate that the tracker can send the IP address list in a compact form (see below for a detailed description)
Example GET Request
An example of this GET message could be:
http://some.tracker.com:999/announce ?info_hash=12345678901234567890 &peer_id=ABCDEFGHIJKLMNOPQRST &ip=255.255.255.255 &port=6881 &downloaded=1234 &left=98765 &event=stopped
Response Format
The tracker can send one of two kinds of response, as a [w:Bencode BEncoded] dictionary. If the tracker was able to process the client request it sends a BEncoded dictionary that has two keys:
- interval
- Number of seconds the downloader should wait between regular rerequests.
- peers
- List of dictionaries corresponding to peers.
Peer Dictionary Format
Each dictionary contains the following keys.
- id
- peer_id used by peer to identify with tracker. This key is not present if the no_peer_id extension is used (see below).
- ip
- IP address of the client.
- port
- Port on with the client is listening for a connection.
There are two extensions on the tracker protocol that affect how the tracker send the peers key. The first extension is the no_peer_id, that was short lived, but none the less most BitTorrent clients accept . If this extension is used the tracker does not send the id of each peer in the peers key.
The compact extension tells the tracker to send the peers key as a single string that represents all address and ports of peers. For example, a client at the IP 10.10.10.5 listening on port 128 would be coded as a string containing the following bytes 0A 0A 0A 05 00 80
- peers_ipv6
- Sent only if the client requested a compact response; it lists all the IPv6 addresses currently monitored by the tracker. For instance a client at 1002:1035:4527:3546:7854:1237:3247:3217 and port 6881 would be coded as a string containing the following bytes:
10 02 10 35 45 27 35 46 78 54 12 37 32 47 32 17 1A E1.
The second kind of response is a BEncoded dictionary with a failure reason key. It means that the tracker was unable to process the request. The value of the failure reason is a human readable text that contains the cause of the error. If this key is present, no other key needs to be present.
'Extension proposal: The following key is an extension of the failure reason key as proposed by Paulo Jr, a.k.a. MstrControl, who is currently developing a new BitTorrent client known as torrentNET, and a new tracker known as trackerNET
The tracker might also send a failure code key. The value of this key is an integer that still needs to be coordinated among the tracker developers and currently is proposed as follows:
Response Codes
| Code | Description |
|---|---|
| 100 | Invalid request type: client request was not a HTTP GET. |
| 101 | Missing info_hash.
|
| 102 | Missing peer_id.
|
| 103 | Missing port.
|
| 150 | Invalid infohash: infohash is not 20 bytes long.
|
| 151 | Invalid peerid: peerid is not 20 bytes long.
|
| 152 | Invalid numwant. Client requested more peers than allowed by tracker.
|
| 200 | info_hash not found in the database. Sent only by trackers that do not automatically include new hashes into the database.
|
| 500 | Client sent an eventless request before the specified time. |
| 900 | Generic error. |