1Bittorrent UDP-tracker protocol extension
2=========================================
3
4:Author: Arvid Norberg, arvid@libtorrent.org
5
6.. contents:: Table of contents
7	:depth: 2
8	:backlinks: none
9
10
11introduction
12------------
13
14A tracker with the protocol "udp://" in its URI
15is supposed to be contacted using this protocol.
16
17This protocol is supported by
18xbt-tracker_.
19
20
21.. _xbt-tracker: http://xbtt.sourceforge.net
22
23For additional information and descriptions of
24the terminology used in this document, see
25the `protocol specification`__
26
27__ http://wiki.theory.org/index.php/BitTorrentSpecification
28
29All values are sent in network byte order (big-endian). The sizes
30are specified with ANSI-C standard types.
31
32If no response to a request is received within 15 seconds, resend
33the request. If no reply has been received after 60 seconds, stop
34retrying.
35
36
37connecting
38----------
39
40Client sends packet:
41
42+-------------+---------------------+----------------------------------------+
43| size        | name                | description                            |
44+=============+=====================+========================================+
45| int64_t     | connection_id       | Must be initialized to 0x41727101980   |
46|             |                     | in network byte order. This will       |
47|             |                     | identify the protocol.                 |
48+-------------+---------------------+----------------------------------------+
49| int32_t     | action              | 0 for a connection request             |
50+-------------+---------------------+----------------------------------------+
51| int32_t     | transaction_id      | Randomized by client.                  |
52+-------------+---------------------+----------------------------------------+
53
54Server replies with packet:
55
56+-------------+---------------------+----------------------------------------+
57| size        | name                | description                            |
58+=============+=====================+========================================+
59| int32_t     | action              | Describes the type of packet, in this  |
60|             |                     | case it should be 0, for connect.      |
61|             |                     | If 3 (for error) see errors_.          |
62+-------------+---------------------+----------------------------------------+
63| int32_t     | transaction_id      | Must match the transaction_id sent     |
64|             |                     | from the client.                       |
65+-------------+---------------------+----------------------------------------+
66| int64_t     | connection_id       | A connection id, this is used when     |
67|             |                     | further information is exchanged with  |
68|             |                     | the tracker, to identify you.          |
69|             |                     | This connection id can be reused for   |
70|             |                     | multiple requests, but if it's cached  |
71|             |                     | for too long, it will not be valid     |
72|             |                     | anymore.                               |
73+-------------+---------------------+----------------------------------------+
74
75
76announcing
77----------
78
79Client sends packet:
80
81+-------------+---------------------+----------------------------------------+
82| size        | name                | description                            |
83+=============+=====================+========================================+
84| int64_t     | connection_id       | The connection id acquired from        |
85|             |                     | establishing the connection.           |
86+-------------+---------------------+----------------------------------------+
87| int32_t     | action              | Action. in this case, 1 for announce.  |
88|             |                     | See actions_.                          |
89+-------------+---------------------+----------------------------------------+
90| int32_t     | transaction_id      | Randomized by client.                  |
91+-------------+---------------------+----------------------------------------+
92| int8_t[20]  | info_hash           | The info-hash of the torrent you want  |
93|             |                     | announce yourself in.                  |
94+-------------+---------------------+----------------------------------------+
95| int8_t[20]  | peer_id             | Your peer id.                          |
96+-------------+---------------------+----------------------------------------+
97| int64_t     | downloaded          | The number of byte you've downloaded   |
98|             |                     | in this session.                       |
99+-------------+---------------------+----------------------------------------+
100| int64_t     | left                | The number of bytes you have left to   |
101|             |                     | download until you're finished.        |
102+-------------+---------------------+----------------------------------------+
103| int64_t     | uploaded            | The number of bytes you have uploaded  |
104|             |                     | in this session.                       |
105+-------------+---------------------+----------------------------------------+
106| int32_t     | event               | The event, one of                      |
107|             |                     |                                        |
108|             |                     |    * none = 0                          |
109|             |                     |    * completed = 1                     |
110|             |                     |    * started = 2                       |
111|             |                     |    * stopped = 3                       |
112+-------------+---------------------+----------------------------------------+
113| uint32_t    | ip                  | Your ip address. Set to 0 if you want  |
114|             |                     | the tracker to use the ``sender`` of   |
115|             |                     | this UDP packet.                       |
116+-------------+---------------------+----------------------------------------+
117| uint32_t    | key                 | A unique key that is randomized by the |
118|             |                     | client.                                |
119+-------------+---------------------+----------------------------------------+
120| int32_t     | num_want            | The maximum number of peers you want   |
121|             |                     | in the reply. Use -1 for default.      |
122+-------------+---------------------+----------------------------------------+
123| uint16_t    | port                | The port you're listening on.          |
124+-------------+---------------------+----------------------------------------+
125| uint16_t    | extensions          | See extensions_                        |
126+-------------+---------------------+----------------------------------------+
127
128
129Server replies with packet:
130
131+-------------+---------------------+----------------------------------------+
132| size        | name                | description                            |
133+=============+=====================+========================================+
134| int32_t     | action              | The action this is a reply to. Should  |
135|             |                     | in this case be 1 for announce.        |
136|             |                     | If 3 (for error) see errors_.          |
137|             |                     | See actions_.                          |
138+-------------+---------------------+----------------------------------------+
139| int32_t     | transaction_id      | Must match the transaction_id sent     |
140|             |                     | in the announce request.               |
141+-------------+---------------------+----------------------------------------+
142| int32_t     | interval            | the number of seconds you should wait  |
143|             |                     | until re-announcing yourself.          |
144+-------------+---------------------+----------------------------------------+
145| int32_t     | leechers            | The number of peers in the swarm that  |
146|             |                     | has not finished downloading.          |
147+-------------+---------------------+----------------------------------------+
148| int32_t     | seeders             | The number of peers in the swarm that  |
149|             |                     | has finished downloading and are       |
150|             |                     | seeding.                               |
151+-------------+---------------------+----------------------------------------+
152
153The rest of the server reply is a variable number of the following structure:
154
155+-------------+---------------------+----------------------------------------+
156| size        | name                | description                            |
157+=============+=====================+========================================+
158| int32_t     | ip                  | The ip of a peer in the swarm.         |
159+-------------+---------------------+----------------------------------------+
160| uint16_t    | port                | The peer's listen port.                |
161+-------------+---------------------+----------------------------------------+
162
163
164scraping
165--------
166
167Client sends packet:
168
169+-------------+---------------------+----------------------------------------+
170| size        | name                | description                            |
171+=============+=====================+========================================+
172| int64_t     | connection_id       | The connection id retrieved from the   |
173|             |                     | establishing of the connection.        |
174+-------------+---------------------+----------------------------------------+
175| int32_t     | action              | The action, in this case, 2 for        |
176|             |                     | scrape. See actions_.                  |
177+-------------+---------------------+----------------------------------------+
178| int32_t     | transaction_id      | Randomized by client.                  |
179+-------------+---------------------+----------------------------------------+
180
181The following structure is repeated for each info-hash to scrape, but limited by
182the MTU.
183
184+-------------+---------------------+----------------------------------------+
185| size        | name                | description                            |
186+=============+=====================+========================================+
187| int8_t[20]  | info_hash           | The info hash that is to be scraped.   |
188+-------------+---------------------+----------------------------------------+
189
190
191Server replies with packet:
192
193+-------------+---------------------+----------------------------------------+
194| size        | name                | description                            |
195+=============+=====================+========================================+
196| int32_t     | action              | The action, should in this case be     |
197|             |                     | 2 for scrape.                          |
198|             |                     | If 3 (for error) see errors_.          |
199+-------------+---------------------+----------------------------------------+
200| int32_t     | transaction_id      | Must match the sent transaction id.    |
201+-------------+---------------------+----------------------------------------+
202
203The rest of the packet contains the following structures once for each info-hash
204you asked in the scrape request.
205
206+-------------+---------------------+----------------------------------------+
207| size        | name                | description                            |
208+=============+=====================+========================================+
209| int32_t     | complete            | The current number of connected seeds. |
210+-------------+---------------------+----------------------------------------+
211| int32_t     | downloaded          | The number of times this torrent has   |
212|             |                     | been downloaded.                       |
213+-------------+---------------------+----------------------------------------+
214| int32_t     | incomplete          | The current number of connected        |
215|             |                     | leechers.                              |
216+-------------+---------------------+----------------------------------------+
217
218
219errors
220------
221
222In case of a tracker error,
223
224server replies packet:
225
226+-------------+---------------------+----------------------------------------+
227| size        | name                | description                            |
228+=============+=====================+========================================+
229| int32_t     | action              | The action, in this case 3, for error. |
230|             |                     | See actions_.                          |
231+-------------+---------------------+----------------------------------------+
232| int32_t     | transaction_id      | Must match the transaction_id sent     |
233|             |                     | from the client.                       |
234+-------------+---------------------+----------------------------------------+
235| int8_t[]    | error_string        | The rest of the packet is a string     |
236|             |                     | describing the error.                  |
237+-------------+---------------------+----------------------------------------+
238
239
240actions
241-------
242
243The action fields has the following encoding:
244
245	* connect = 0
246	* announce = 1
247	* scrape = 2
248	* error = 3 (only in server replies)
249
250
251extensions
252----------
253
254The extensions field is a bitmask. The following
255bits are assigned:
256
257	* 1 = authentication_.
258	* 2 = `request string`_.
259
260If multiple bits are present in the extension field, the extension
261bodies are appended to the packet in the order of least significant
262bit first. For instance, if both bit 1 and 2 are set, the extension
263represented by bit 1 comes first, followed by the extension represented
264by bit 2.
265
266authentication
267~~~~~~~~~~~~~~
268
269The packet will have an authentication part
270appended to it. It has the following format:
271
272+-------------+---------------------+----------------------------------------+
273| size        | name                | description                            |
274+=============+=====================+========================================+
275| int8_t      | username_length     | The number of characters in the        |
276|             |                     | username.                              |
277+-------------+---------------------+----------------------------------------+
278| int8_t[]    | username            | The username, the number of characters |
279|             |                     | as specified in the previous field.    |
280+-------------+---------------------+----------------------------------------+
281| uint8_t[8]  | passwd_hash         | sha1(packet + sha1(password))          |
282|             |                     | The packet in this case means the      |
283|             |                     | entire packet except these 8 bytes     |
284|             |                     | that are the password hash. These are  |
285|             |                     | the 8 first bytes (most significant)   |
286|             |                     | from the 20 bytes hash calculated.     |
287+-------------+---------------------+----------------------------------------+
288
289request string
290--------------
291
292The request string extension is meant to allow torrent creators pass along
293cookies back to the tracker. This can be useful for authenticating that a
294torrent is allowed to be tracked by a tracker for instance. It could also
295be used to authenticate users by generating torrents with unique tokens
296in the tracker URL for each user. The extension body has the following format:
297
298+-------------+---------------------+----------------------------------------+
299| size        | name                | description                            |
300+=============+=====================+========================================+
301| int8_t      | request length      | The number of bytes in the request     |
302|             |                     | string.                                |
303+-------------+---------------------+----------------------------------------+
304| int8_t[]    | request string      | The string that comes after the host-  |
305|             |                     | name and port in the UDP tracker URL.  |
306|             |                     | Typically this starts with "/announce" |
307|             |                     | The bittorrent client is not expected  |
308|             |                     | to append query string arguments for   |
309|             |                     | stats reporting, like "uploaded" and   |
310|             |                     | "downloaded" since this is already     |
311|             |                     | reported in the UDP tracker protocol.  |
312|             |                     | However, the client is free to add     |
313|             |                     | arguments as extensions.               |
314+-------------+---------------------+----------------------------------------+
315
316credits
317-------
318
319Protocol designed by Olaf van der Spek and extended by Arvid Norberg
320
321