docs/udp_tracker_protocol.rst

   1 Bittorrent udp-tracker protocol extension
   2 =========================================
   3
   4 :Author: Arvid Norberg, arvid@rasterbar.com
   5
   6 .. contents:: Table of contents
   7         :depth: 2
   8         :backlinks: none
   9
  10
  11 introduction
  12 ------------
  13
  14 A tracker with the protocol "udp://" in its URI
  15 is supposed to be contacted using this protocol.
  16
  17 This protocol is supported by
  18 xbt-tracker_.
  19
  20
  21 .. _xbt-tracker: http://xbtt.sourceforge.net
  22
  23 For additional information and descritptions of
  24 the terminology used in this document, see
  25 the `protocol specification`__
  26
  27 __ http://wiki.theory.org/index.php/BitTorrentSpecification
  28
  29 All values are sent in network byte order (big endian). The sizes
  30 are specified with ANSI-C standard types.
  31
  32 If no response to a request is received within 15 seconds, resend
  33 the request. If no reply has been received after 60 seconds, stop
  34 retrying.
  35
  36
  37 connecting
  38 ----------
  39
  40 Client 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
  54 Server 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
  76 announcing
  77 ----------
  78
  79 Client 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
 129 Server 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 reannouncing 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
 153 The 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
 164 scraping
 165 --------
 166
 167 Client sends packet:
 168
 169 +-------------+---------------------+----------------------------------------+
 170 | size        | name                | description                            |
 171 +=============+=====================+========================================+
 172 | int64_t     | connection_id       | The connection id retreived 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
 181 The following structure is repeated for each info-hash to scrape, but limited by
 182 the 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
 191 Server 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
 203 The rest of the packet contains the following structures once for each info-hash
 204 you asked in the scrape request.
 205
 206 +-------------+---------------------+----------------------------------------+
 207 | size        | name                | description                            |
 208 +=============+=====================+========================================+
 209 | int32_t     | complete            | The total number of completed          |
 210 |             |                     | downloads.                             |
 211 +-------------+---------------------+----------------------------------------+
 212 | int32_t     | downloaded          | The current number of connected seeds. |
 213 +-------------+---------------------+----------------------------------------+
 214 | int32_t     | incomplete          | The current number of connected        |
 215 |             |                     | leechers.                              |
 216 +-------------+---------------------+----------------------------------------+
 217
 218
 219 errors
 220 ------
 221
 222 In case of a tracker error,
 223
 224 server 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
 240 actions
 241 -------
 242
 243 The 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
 251 extensions
 252 ----------
 253
 254 The extensions field is a bitmask. The following
 255 bits are assigned:
 256
 257         * 1 = authentication_.
 258
 259
 260
 261 authentication
 262 ~~~~~~~~~~~~~~
 263
 264 The packet will have an authentication part
 265 appended to it. It has the following format:
 266
 267 +-------------+---------------------+----------------------------------------+
 268 | size        | name                | description                            |
 269 +=============+=====================+========================================+
 270 | int8_t      | username_length     | The number of characters in the        |
 271 |             |                     | username.                              |
 272 +-------------+---------------------+----------------------------------------+
 273 | int8_t[]    | username            | The username, the number of characters |
 274 |             |                     | as specified in the previous field.    |
 275 +-------------+---------------------+----------------------------------------+
 276 | uint8_t[8]  | passwd_hash         | sha1(packet + sha1(password))          |
 277 |             |                     | The packet in this case means the      |
 278 |             |                     | entire packet except these 8 bytes     |
 279 |             |                     | that are the password hash. These are  |
 280 |             |                     | the 8 first bytes (most significant)   |
 281 |             |                     | from the 20 bytes hash calculated.     |
 282 +-------------+---------------------+----------------------------------------+
 283
 284
 285 credits
 286 -------
 287
 288 Protocol designed by Olaf van der Spek
 289