docs/udp_tracker_protocol.html

   1 <?xml version="1.0" encoding="utf-8" ?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
   4 <head>
   5 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   6 <meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
   7 <title>Bittorrent udp-tracker protocol extension</title>
   8 <meta name="author" content="Arvid Norberg, arvid&#64;rasterbar.com" />
   9 <link rel="stylesheet" href="style.css" type="text/css" />
  10 </head>
  11 <body>
  12 <div class="document" id="bittorrent-udp-tracker-protocol-extension">
  13 <h1 class="title">Bittorrent udp-tracker protocol extension</h1>
  14 <table class="docinfo" frame="void" rules="none">
  15 <col class="docinfo-name" />
  16 <col class="docinfo-content" />
  17 <tbody valign="top">
  18 <tr><th class="docinfo-name">Author:</th>
  19 <td>Arvid Norberg, <a class="last reference" href="mailto:arvid&#64;rasterbar.com">arvid&#64;rasterbar.com</a></td></tr>
  20 </tbody>
  21 </table>
  22 <div class="contents topic" id="table-of-contents">
  23 <p class="topic-title first"><a name="table-of-contents">Table of contents</a></p>
  24 <ul class="simple">
  25 <li><a class="reference" href="#introduction" id="id2" name="id2">introduction</a></li>
  26 <li><a class="reference" href="#connecting" id="id3" name="id3">connecting</a></li>
  27 <li><a class="reference" href="#announcing" id="id4" name="id4">announcing</a></li>
  28 <li><a class="reference" href="#scraping" id="id5" name="id5">scraping</a></li>
  29 <li><a class="reference" href="#errors" id="id6" name="id6">errors</a></li>
  30 <li><a class="reference" href="#actions" id="id7" name="id7">actions</a></li>
  31 <li><a class="reference" href="#extensions" id="id8" name="id8">extensions</a><ul>
  32 <li><a class="reference" href="#authentication" id="id9" name="id9">authentication</a></li>
  33 </ul>
  34 </li>
  35 <li><a class="reference" href="#credits" id="id10" name="id10">credits</a></li>
  36 </ul>
  37 </div>
  38 <div class="section">
  39 <h1><a id="introduction" name="introduction">introduction</a></h1>
  40 <p>A tracker with the protocol &quot;udp://&quot; in its URI
  41 is supposed to be contacted using this protocol.</p>
  42 <p>This protocol is supported by
  43 <a class="reference" href="http://xbtt.sourceforge.net">xbt-tracker</a>.</p>
  44 <p>For additional information and descritptions of
  45 the terminology used in this document, see
  46 the <a class="reference" href="http://wiki.theory.org/index.php/BitTorrentSpecification">protocol specification</a></p>
  47 <p>All values are sent in network byte order (big endian). The sizes
  48 are specified with ANSI-C standard types.</p>
  49 <p>If no response to a request is received within 15 seconds, resend
  50 the request. If no reply has been received after 60 seconds, stop
  51 retrying.</p>
  52 </div>
  53 <div class="section">
  54 <h1><a id="connecting" name="connecting">connecting</a></h1>
  55 <p>Client sends packet:</p>
  56 <table border="1" class="docutils">
  57 <colgroup>
  58 <col width="18%" />
  59 <col width="28%" />
  60 <col width="54%" />
  61 </colgroup>
  62 <thead valign="bottom">
  63 <tr><th class="head">size</th>
  64 <th class="head">name</th>
  65 <th class="head">description</th>
  66 </tr>
  67 </thead>
  68 <tbody valign="top">
  69 <tr><td>int64_t</td>
  70 <td>connection_id</td>
  71 <td>Must be initialized to 0x41727101980
  72 in network byte order. This will
  73 identify the protocol.</td>
  74 </tr>
  75 <tr><td>int32_t</td>
  76 <td>action</td>
  77 <td>0 for a connection request</td>
  78 </tr>
  79 <tr><td>int32_t</td>
  80 <td>transaction_id</td>
  81 <td>Randomized by client.</td>
  82 </tr>
  83 </tbody>
  84 </table>
  85 <p>Server replies with packet:</p>
  86 <table border="1" class="docutils">
  87 <colgroup>
  88 <col width="18%" />
  89 <col width="28%" />
  90 <col width="54%" />
  91 </colgroup>
  92 <thead valign="bottom">
  93 <tr><th class="head">size</th>
  94 <th class="head">name</th>
  95 <th class="head">description</th>
  96 </tr>
  97 </thead>
  98 <tbody valign="top">
  99 <tr><td>int32_t</td>
 100 <td>action</td>
 101 <td>Describes the type of packet, in this
 102 case it should be 0, for connect.
 103 If 3 (for error) see <a class="reference" href="#errors">errors</a>.</td>
 104 </tr>
 105 <tr><td>int32_t</td>
 106 <td>transaction_id</td>
 107 <td>Must match the transaction_id sent
 108 from the client.</td>
 109 </tr>
 110 <tr><td>int64_t</td>
 111 <td>connection_id</td>
 112 <td>A connection id, this is used when
 113 further information is exchanged with
 114 the tracker, to identify you.
 115 This connection id can be reused for
 116 multiple requests, but if it's cached
 117 for too long, it will not be valid
 118 anymore.</td>
 119 </tr>
 120 </tbody>
 121 </table>
 122 </div>
 123 <div class="section">
 124 <h1><a id="announcing" name="announcing">announcing</a></h1>
 125 <p>Client sends packet:</p>
 126 <table border="1" class="docutils">
 127 <colgroup>
 128 <col width="18%" />
 129 <col width="28%" />
 130 <col width="54%" />
 131 </colgroup>
 132 <thead valign="bottom">
 133 <tr><th class="head">size</th>
 134 <th class="head">name</th>
 135 <th class="head">description</th>
 136 </tr>
 137 </thead>
 138 <tbody valign="top">
 139 <tr><td>int64_t</td>
 140 <td>connection_id</td>
 141 <td>The connection id acquired from
 142 establishing the connection.</td>
 143 </tr>
 144 <tr><td>int32_t</td>
 145 <td>action</td>
 146 <td>Action. in this case, 1 for announce.
 147 See <a class="reference" href="#actions">actions</a>.</td>
 148 </tr>
 149 <tr><td>int32_t</td>
 150 <td>transaction_id</td>
 151 <td>Randomized by client.</td>
 152 </tr>
 153 <tr><td>int8_t[20]</td>
 154 <td>info_hash</td>
 155 <td>The info-hash of the torrent you want
 156 announce yourself in.</td>
 157 </tr>
 158 <tr><td>int8_t[20]</td>
 159 <td>peer_id</td>
 160 <td>Your peer id.</td>
 161 </tr>
 162 <tr><td>int64_t</td>
 163 <td>downloaded</td>
 164 <td>The number of byte you've downloaded
 165 in this session.</td>
 166 </tr>
 167 <tr><td>int64_t</td>
 168 <td>left</td>
 169 <td>The number of bytes you have left to
 170 download until you're finished.</td>
 171 </tr>
 172 <tr><td>int64_t</td>
 173 <td>uploaded</td>
 174 <td>The number of bytes you have uploaded
 175 in this session.</td>
 176 </tr>
 177 <tr><td>int32_t</td>
 178 <td>event</td>
 179 <td><p class="first">The event, one of</p>
 180 <blockquote class="last">
 181 <ul class="simple">
 182 <li>none = 0</li>
 183 <li>completed = 1</li>
 184 <li>started = 2</li>
 185 <li>stopped = 3</li>
 186 </ul>
 187 </blockquote>
 188 </td>
 189 </tr>
 190 <tr><td>uint32_t</td>
 191 <td>ip</td>
 192 <td>Your ip address. Set to 0 if you want
 193 the tracker to use the <tt class="docutils literal"><span class="pre">sender</span></tt> of
 194 this udp packet.</td>
 195 </tr>
 196 <tr><td>uint32_t</td>
 197 <td>key</td>
 198 <td>A unique key that is randomized by the
 199 client.</td>
 200 </tr>
 201 <tr><td>int32_t</td>
 202 <td>num_want</td>
 203 <td>The maximum number of peers you want
 204 in the reply. Use -1 for default.</td>
 205 </tr>
 206 <tr><td>uint16_t</td>
 207 <td>port</td>
 208 <td>The port you're listening on.</td>
 209 </tr>
 210 <tr><td>uint16_t</td>
 211 <td>extensions</td>
 212 <td>See <a class="reference" href="#extensions">extensions</a></td>
 213 </tr>
 214 </tbody>
 215 </table>
 216 <p>Server replies with packet:</p>
 217 <table border="1" class="docutils">
 218 <colgroup>
 219 <col width="18%" />
 220 <col width="28%" />
 221 <col width="54%" />
 222 </colgroup>
 223 <thead valign="bottom">
 224 <tr><th class="head">size</th>
 225 <th class="head">name</th>
 226 <th class="head">description</th>
 227 </tr>
 228 </thead>
 229 <tbody valign="top">
 230 <tr><td>int32_t</td>
 231 <td>action</td>
 232 <td>The action this is a reply to. Should
 233 in this case be 1 for announce.
 234 If 3 (for error) see <a class="reference" href="#errors">errors</a>.
 235 See <a class="reference" href="#actions">actions</a>.</td>
 236 </tr>
 237 <tr><td>int32_t</td>
 238 <td>transaction_id</td>
 239 <td>Must match the transaction_id sent
 240 in the announce request.</td>
 241 </tr>
 242 <tr><td>int32_t</td>
 243 <td>interval</td>
 244 <td>the number of seconds you should wait
 245 until reannouncing yourself.</td>
 246 </tr>
 247 <tr><td>int32_t</td>
 248 <td>leechers</td>
 249 <td>The number of peers in the swarm that
 250 has not finished downloading.</td>
 251 </tr>
 252 <tr><td>int32_t</td>
 253 <td>seeders</td>
 254 <td>The number of peers in the swarm that
 255 has finished downloading and are
 256 seeding.</td>
 257 </tr>
 258 </tbody>
 259 </table>
 260 <p>The rest of the server reply is a variable number of the following structure:</p>
 261 <table border="1" class="docutils">
 262 <colgroup>
 263 <col width="18%" />
 264 <col width="28%" />
 265 <col width="54%" />
 266 </colgroup>
 267 <thead valign="bottom">
 268 <tr><th class="head">size</th>
 269 <th class="head">name</th>
 270 <th class="head">description</th>
 271 </tr>
 272 </thead>
 273 <tbody valign="top">
 274 <tr><td>int32_t</td>
 275 <td>ip</td>
 276 <td>The ip of a peer in the swarm.</td>
 277 </tr>
 278 <tr><td>uint16_t</td>
 279 <td>port</td>
 280 <td>The peer's listen port.</td>
 281 </tr>
 282 </tbody>
 283 </table>
 284 </div>
 285 <div class="section">
 286 <h1><a id="scraping" name="scraping">scraping</a></h1>
 287 <p>Client sends packet:</p>
 288 <table border="1" class="docutils">
 289 <colgroup>
 290 <col width="18%" />
 291 <col width="28%" />
 292 <col width="54%" />
 293 </colgroup>
 294 <thead valign="bottom">
 295 <tr><th class="head">size</th>
 296 <th class="head">name</th>
 297 <th class="head">description</th>
 298 </tr>
 299 </thead>
 300 <tbody valign="top">
 301 <tr><td>int64_t</td>
 302 <td>connection_id</td>
 303 <td>The connection id retreived from the
 304 establishing of the connection.</td>
 305 </tr>
 306 <tr><td>int32_t</td>
 307 <td>action</td>
 308 <td>The action, in this case, 2 for
 309 scrape. See <a class="reference" href="#actions">actions</a>.</td>
 310 </tr>
 311 <tr><td>int32_t</td>
 312 <td>transaction_id</td>
 313 <td>Randomized by client.</td>
 314 </tr>
 315 </tbody>
 316 </table>
 317 <p>The following structure is repeated for each info-hash to scrape, but limited by
 318 the MTU.</p>
 319 <table border="1" class="docutils">
 320 <colgroup>
 321 <col width="18%" />
 322 <col width="28%" />
 323 <col width="54%" />
 324 </colgroup>
 325 <thead valign="bottom">
 326 <tr><th class="head">size</th>
 327 <th class="head">name</th>
 328 <th class="head">description</th>
 329 </tr>
 330 </thead>
 331 <tbody valign="top">
 332 <tr><td>int8_t[20]</td>
 333 <td>info_hash</td>
 334 <td>The info hash that is to be scraped.</td>
 335 </tr>
 336 </tbody>
 337 </table>
 338 <p>Server replies with packet:</p>
 339 <table border="1" class="docutils">
 340 <colgroup>
 341 <col width="18%" />
 342 <col width="28%" />
 343 <col width="54%" />
 344 </colgroup>
 345 <thead valign="bottom">
 346 <tr><th class="head">size</th>
 347 <th class="head">name</th>
 348 <th class="head">description</th>
 349 </tr>
 350 </thead>
 351 <tbody valign="top">
 352 <tr><td>int32_t</td>
 353 <td>action</td>
 354 <td>The action, should in this case be
 355 2 for scrape.
 356 If 3 (for error) see <a class="reference" href="#errors">errors</a>.</td>
 357 </tr>
 358 <tr><td>int32_t</td>
 359 <td>transaction_id</td>
 360 <td>Must match the sent transaction id.</td>
 361 </tr>
 362 </tbody>
 363 </table>
 364 <p>The rest of the packet contains the following structures once for each info-hash
 365 you asked in the scrape request.</p>
 366 <table border="1" class="docutils">
 367 <colgroup>
 368 <col width="18%" />
 369 <col width="28%" />
 370 <col width="54%" />
 371 </colgroup>
 372 <thead valign="bottom">
 373 <tr><th class="head">size</th>
 374 <th class="head">name</th>
 375 <th class="head">description</th>
 376 </tr>
 377 </thead>
 378 <tbody valign="top">
 379 <tr><td>int32_t</td>
 380 <td>complete</td>
 381 <td>The total number of completed
 382 downloads.</td>
 383 </tr>
 384 <tr><td>int32_t</td>
 385 <td>downloaded</td>
 386 <td>The current number of connected seeds.</td>
 387 </tr>
 388 <tr><td>int32_t</td>
 389 <td>incomplete</td>
 390 <td>The current number of connected
 391 leechers.</td>
 392 </tr>
 393 </tbody>
 394 </table>
 395 </div>
 396 <div class="section">
 397 <h1><a id="errors" name="errors">errors</a></h1>
 398 <p>In case of a tracker error,</p>
 399 <p>server replies packet:</p>
 400 <table border="1" class="docutils">
 401 <colgroup>
 402 <col width="18%" />
 403 <col width="28%" />
 404 <col width="54%" />
 405 </colgroup>
 406 <thead valign="bottom">
 407 <tr><th class="head">size</th>
 408 <th class="head">name</th>
 409 <th class="head">description</th>
 410 </tr>
 411 </thead>
 412 <tbody valign="top">
 413 <tr><td>int32_t</td>
 414 <td>action</td>
 415 <td>The action, in this case 3, for error.
 416 See <a class="reference" href="#actions">actions</a>.</td>
 417 </tr>
 418 <tr><td>int32_t</td>
 419 <td>transaction_id</td>
 420 <td>Must match the transaction_id sent
 421 from the client.</td>
 422 </tr>
 423 <tr><td>int8_t[]</td>
 424 <td>error_string</td>
 425 <td>The rest of the packet is a string
 426 describing the error.</td>
 427 </tr>
 428 </tbody>
 429 </table>
 430 </div>
 431 <div class="section">
 432 <h1><a id="actions" name="actions">actions</a></h1>
 433 <p>The action fields has the following encoding:</p>
 434 <blockquote>
 435 <ul class="simple">
 436 <li>connect = 0</li>
 437 <li>announce = 1</li>
 438 <li>scrape = 2</li>
 439 <li>error = 3 (only in server replies)</li>
 440 </ul>
 441 </blockquote>
 442 </div>
 443 <div class="section">
 444 <h1><a id="extensions" name="extensions">extensions</a></h1>
 445 <p>The extensions field is a bitmask. The following
 446 bits are assigned:</p>
 447 <blockquote>
 448 <ul class="simple">
 449 <li>1 = <a class="reference" href="#authentication">authentication</a>.</li>
 450 </ul>
 451 </blockquote>
 452 <div class="section">
 453 <h2><a id="authentication" name="authentication">authentication</a></h2>
 454 <p>The packet will have an authentication part
 455 appended to it. It has the following format:</p>
 456 <table border="1" class="docutils">
 457 <colgroup>
 458 <col width="18%" />
 459 <col width="28%" />
 460 <col width="54%" />
 461 </colgroup>
 462 <thead valign="bottom">
 463 <tr><th class="head">size</th>
 464 <th class="head">name</th>
 465 <th class="head">description</th>
 466 </tr>
 467 </thead>
 468 <tbody valign="top">
 469 <tr><td>int8_t</td>
 470 <td>username_length</td>
 471 <td>The number of characters in the
 472 username.</td>
 473 </tr>
 474 <tr><td>int8_t[]</td>
 475 <td>username</td>
 476 <td>The username, the number of characters
 477 as specified in the previous field.</td>
 478 </tr>
 479 <tr><td>uint8_t[8]</td>
 480 <td>passwd_hash</td>
 481 <td>sha1(packet + sha1(password))
 482 The packet in this case means the
 483 entire packet except these 8 bytes
 484 that are the password hash. These are
 485 the 8 first bytes (most significant)
 486 from the 20 bytes hash calculated.</td>
 487 </tr>
 488 </tbody>
 489 </table>
 490 </div>
 491 </div>
 492 <div class="section">
 493 <h1><a id="credits" name="credits">credits</a></h1>
 494 <p>Protocol designed by Olaf van der Spek</p>
 495 </div>
 496 </div>
 497 </body>
 498 </html>