Tracker HTTP Protocol

---

The Tracker HTTP Protocol below is used in BitComet v0.59 and later.

Client->Tracker

The tracker is an HTTP service which responds to HTTP GET requests. The base URL consists of the "announce URL" as defined in the metadata (.torrent) file. The parameters are then added to this URL, using standard CGI methods (i.e. a '?' after the announce URL, followed by 'param=value' sequences separated by '&')

Note that all binary data in the URL (particularly info_hash and peer_id) must be properly escaped. This means any byte not in the set 0-9, a-z, A-Z, and $-_.+!*'(), must be encoded using the "%nn" format, where nn is the hexadecimal value of the byte. (See RFC1738 for details.)

The parameters used in the client->tracker GET request are as follows:

• info_hash: 20-byte SHA1 hash of the value of the info key from the Metainfo file.

• peer_id: 20-byte string used as a unique ID for the client, generated by the client at startup. See PeerID Format for the peer_id BitComet will use in v0.59 or later.

• port: The port number that BitComet is listening on.

• uploaded: The total number of bytes uploaded (since the client sent the 'started' event to the tracker) in base ten ASCII.

• downloaded: The total number of bytes downloaded (since the client sent the 'started' event to the tracker) in base ten ASCII.

• left: The number of bytes this client still has to download, encoded in base ten ASCII.

• no_peer_id: Indicates the client accepts a no_peer_id response. The peer_id key is then not required to be in the response of the tracker.

• compact: Indicates the client accepts a compact response. The peers list is replaced by a peers string with 6 bytes per peer. The first four bytes are the host (in network byte order), the last two bytes are the port (again in network byte order).

• event: If specified, must be one of started, completed, stopped, (or empty which is the same as not being specified). If not specified, then this request is one performed at regular intervals.

• started: The first request to the tracker must include the event key with the started value.
• stopped: Must be sent to the tracker if the client is shutting down gracefully.
• completed: Must be sent to the tracker when the download completes. However, must not be sent if the download was already 100% complete when the client started. Presumably, this is to allow the tracker to increment the "completed downloads" metric based soley on this event.

• numwant: Optional. Number of peers that the client would like to receive from the tracker. This value is permitted to be zero. If omitted, typically defaults to 50 peers.

• key: Optional. An additional identification that is not shared with any users. It is intended to allow a client to prove their identity should their IP address change.

Tracker->Client

The tracker responds with "text/plain" document consisting of a bencoded dictionary with the following keys:

• failure reason: Optional. If present, then no other keys may be present. The value is a human-readable error message as to why the request failed (string).

• interval: Interval in seconds that the client should wait between sending regular requests to the tracker (mandatory)

• min interval: Optional. Minimum announce interval. If present clients must not reannounce more frequently than this.

• peers: The value is a string of compacted peers <ip:port> 6 bytes in compact mode, or a list of dictionaries, each with the following keys:

• peer id: peer's self-selected ID, as described above for the tracker request (string)
• ip: peer's IP address (either IPv6 or IPv4) or DNS name (string)
• port: peer's port number (integer)

• tracker_alias_url: Optional. a string list of of alias trackers. If the other tracker is in the same server, server domain can be omitted. e.g. udp://:8080/ means that client can connect to a UDP tracker instead of the http one.

• private: Optional. If specified, can be 0 or 1 indicate if the tracker is a private tracker. When a torrent is made under Disable Public DHT Network (Use Tracker Server), i.e. there is no nodes key in the torrent, and any tracker in the list announce that it is private tracker explicitly by send "private" = 1, BitComet will not add DHT Network as Backup Tracker even all the trackers can not be connected later, and will also disable Peer Exchange between peers.