premiere
/
premiere-libtorrent
2
2
Fork 1
Code Issues Pull Requests Releases Wiki Activity
premiere-libtorrent/docs/udp_tracker_protocol.html

605 lines
16 KiB
HTML
Raw Normal View History

regenerate documentation
2013-07-19 18:31:52 +02:00
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
merged changes from RC_1_0
2014-10-14 18:36:06 +02:00
<meta name="generator" content="Docutils 0.11: http://docutils.sourceforge.net/" />
regenerate documentation
2013-07-19 18:31:52 +02:00
<title>Bittorrent udp-tracker protocol extension</title>
merged changes from RC_1_0 to change email address from @rasterbar.com to @libtorrent.org
2014-10-14 04:06:20 +02:00
<meta name="author" content="Arvid Norberg, arvid&#64;libtorrent.org" />
merged fixes from RC_1_0
2014-08-26 05:14:32 +02:00
<link rel="stylesheet" type="text/css" href="rst.css" />
regenerate documentation
2013-07-19 18:31:52 +02:00
<script type="text/javascript">
/* <![CDATA[ */
(function() {
var s = document.createElement('script'), t = document.getElementsByTagName('script')[0];
s.type = 'text/javascript';
s.async = true;
s.src = 'http://api.flattr.com/js/0.6/load.js?mode=auto';
t.parentNode.insertBefore(s, t);
})();
/* ]]> */
</script>
<link rel="stylesheet" href="style.css" type="text/css" />
<style type="text/css">
/* Hides from IE-mac \*/
* html pre { height: 1%; }
/* End hide from IE-mac */
</style>
</head>
<body>
<div class="document" id="bittorrent-udp-tracker-protocol-extension">
<div id="container">
merged changes from RC_1_0
2014-10-14 18:36:06 +02:00
<table id="header">
<tr><td id="orange"></td>
<td id="logo">libtorrent</td></tr>
</table>
regenerate documentation
2013-07-19 18:31:52 +02:00
<div id="main">
<h1 class="title">Bittorrent udp-tracker protocol extension</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<col class="docinfo-content" />
<tbody valign="top">
<tr><th class="docinfo-name">Author:</th>
merged changes from RC_1_0 to change email address from @rasterbar.com to @libtorrent.org
2014-10-14 04:06:20 +02:00
<td>Arvid Norberg, <a class="last reference external" href="mailto:arvid&#64;libtorrent.org">arvid&#64;libtorrent.org</a></td></tr>
regenerate documentation
2013-07-19 18:31:52 +02:00
</tbody>
</table>
<div class="contents topic" id="table-of-contents">
<p class="topic-title first">Table of contents</p>
<ul class="simple">
<li><a class="reference internal" href="#introduction" id="id2">introduction</a></li>
<li><a class="reference internal" href="#connecting" id="id3">connecting</a></li>
<li><a class="reference internal" href="#announcing" id="id4">announcing</a></li>
<li><a class="reference internal" href="#scraping" id="id5">scraping</a></li>
<li><a class="reference internal" href="#errors" id="id6">errors</a></li>
<li><a class="reference internal" href="#actions" id="id7">actions</a></li>
<li><a class="reference internal" href="#extensions" id="id8">extensions</a><ul>
<li><a class="reference internal" href="#authentication" id="id9">authentication</a></li>
</ul>
</li>
<li><a class="reference internal" href="#request-string" id="id10">request string</a></li>
<li><a class="reference internal" href="#credits" id="id11">credits</a></li>
</ul>
</div>
<div class="section" id="introduction">
<h1>introduction</h1>
<p>A tracker with the protocol &quot;udp://&quot; in its URI
is supposed to be contacted using this protocol.</p>
<p>This protocol is supported by
<a class="reference external" href="http://xbtt.sourceforge.net">xbt-tracker</a>.</p>
<p>For additional information and descritptions of
the terminology used in this document, see
the <a class="reference external" href="http://wiki.theory.org/index.php/BitTorrentSpecification">protocol specification</a></p>
<p>All values are sent in network byte order (big endian). The sizes
are specified with ANSI-C standard types.</p>
<p>If no response to a request is received within 15 seconds, resend
the request. If no reply has been received after 60 seconds, stop
retrying.</p>
</div>
<div class="section" id="connecting">
<h1>connecting</h1>
<p>Client sends packet:</p>
<table border="1" class="docutils">
<colgroup>
<col width="18%" />
<col width="28%" />
<col width="54%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">size</th>
<th class="head">name</th>
<th class="head">description</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>int64_t</td>
<td>connection_id</td>
<td>Must be initialized to 0x41727101980
in network byte order. This will
identify the protocol.</td>
</tr>
<tr><td>int32_t</td>
<td>action</td>
<td>0 for a connection request</td>
</tr>
<tr><td>int32_t</td>
<td>transaction_id</td>
<td>Randomized by client.</td>
</tr>
</tbody>
</table>
<p>Server replies with packet:</p>
<table border="1" class="docutils">
<colgroup>
<col width="18%" />
<col width="28%" />
<col width="54%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">size</th>
<th class="head">name</th>
<th class="head">description</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>int32_t</td>
<td>action</td>
<td>Describes the type of packet, in this
case it should be 0, for connect.
If 3 (for error) see <a class="reference internal" href="#errors">errors</a>.</td>
</tr>
<tr><td>int32_t</td>
<td>transaction_id</td>
<td>Must match the transaction_id sent
from the client.</td>
</tr>
<tr><td>int64_t</td>
<td>connection_id</td>
<td>A connection id, this is used when
further information is exchanged with
the tracker, to identify you.
This connection id can be reused for
multiple requests, but if it's cached
for too long, it will not be valid
anymore.</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="announcing">
<h1>announcing</h1>
<p>Client sends packet:</p>
<table border="1" class="docutils">
<colgroup>
<col width="18%" />
<col width="28%" />
<col width="54%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">size</th>
<th class="head">name</th>
<th class="head">description</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>int64_t</td>
<td>connection_id</td>
<td>The connection id acquired from
establishing the connection.</td>
</tr>
<tr><td>int32_t</td>
<td>action</td>
<td>Action. in this case, 1 for announce.
See <a class="reference internal" href="#actions">actions</a>.</td>
</tr>
<tr><td>int32_t</td>
<td>transaction_id</td>
<td>Randomized by client.</td>
</tr>
<tr><td>int8_t[20]</td>
<td>info_hash</td>
<td>The info-hash of the torrent you want
announce yourself in.</td>
</tr>
<tr><td>int8_t[20]</td>
<td>peer_id</td>
<td>Your peer id.</td>
</tr>
<tr><td>int64_t</td>
<td>downloaded</td>
<td>The number of byte you've downloaded
in this session.</td>
</tr>
<tr><td>int64_t</td>
<td>left</td>
<td>The number of bytes you have left to
download until you're finished.</td>
</tr>
<tr><td>int64_t</td>
<td>uploaded</td>
<td>The number of bytes you have uploaded
in this session.</td>
</tr>
<tr><td>int32_t</td>
<td>event</td>
<td><p class="first">The event, one of</p>
<blockquote class="last">
<ul class="simple">
<li>none = 0</li>
<li>completed = 1</li>
<li>started = 2</li>
<li>stopped = 3</li>
</ul>
</blockquote>
</td>
</tr>
<tr><td>uint32_t</td>
<td>ip</td>
<td>Your ip address. Set to 0 if you want
the tracker to use the <tt class="docutils literal">sender</tt> of
this udp packet.</td>
</tr>
<tr><td>uint32_t</td>
<td>key</td>
<td>A unique key that is randomized by the
client.</td>
</tr>
<tr><td>int32_t</td>
<td>num_want</td>
<td>The maximum number of peers you want
in the reply. Use -1 for default.</td>
</tr>
<tr><td>uint16_t</td>
<td>port</td>
<td>The port you're listening on.</td>
</tr>
<tr><td>uint16_t</td>
<td>extensions</td>
<td>See <a class="reference internal" href="#extensions">extensions</a></td>
</tr>
</tbody>
</table>
<p>Server replies with packet:</p>
<table border="1" class="docutils">
<colgroup>
<col width="18%" />
<col width="28%" />
<col width="54%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">size</th>
<th class="head">name</th>
<th class="head">description</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>int32_t</td>
<td>action</td>
<td>The action this is a reply to. Should
in this case be 1 for announce.
If 3 (for error) see <a class="reference internal" href="#errors">errors</a>.
See <a class="reference internal" href="#actions">actions</a>.</td>
</tr>
<tr><td>int32_t</td>
<td>transaction_id</td>
<td>Must match the transaction_id sent
in the announce request.</td>
</tr>
<tr><td>int32_t</td>
<td>interval</td>
<td>the number of seconds you should wait
until reannouncing yourself.</td>
</tr>
<tr><td>int32_t</td>
<td>leechers</td>
<td>The number of peers in the swarm that
has not finished downloading.</td>
</tr>
<tr><td>int32_t</td>
<td>seeders</td>
<td>The number of peers in the swarm that
has finished downloading and are
seeding.</td>
</tr>
</tbody>
</table>
<p>The rest of the server reply is a variable number of the following structure:</p>
<table border="1" class="docutils">
<colgroup>
<col width="18%" />
<col width="28%" />
<col width="54%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">size</th>
<th class="head">name</th>
<th class="head">description</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>int32_t</td>
<td>ip</td>
<td>The ip of a peer in the swarm.</td>
</tr>
<tr><td>uint16_t</td>
<td>port</td>
<td>The peer's listen port.</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="scraping">
<h1>scraping</h1>
<p>Client sends packet:</p>
<table border="1" class="docutils">
<colgroup>
<col width="18%" />
<col width="28%" />
<col width="54%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">size</th>
<th class="head">name</th>
<th class="head">description</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>int64_t</td>
<td>connection_id</td>
<td>The connection id retreived from the
establishing of the connection.</td>
</tr>
<tr><td>int32_t</td>
<td>action</td>
<td>The action, in this case, 2 for
scrape. See <a class="reference internal" href="#actions">actions</a>.</td>
</tr>
<tr><td>int32_t</td>
<td>transaction_id</td>
<td>Randomized by client.</td>
</tr>
</tbody>
</table>
<p>The following structure is repeated for each info-hash to scrape, but limited by
the MTU.</p>
<table border="1" class="docutils">
<colgroup>
<col width="18%" />
<col width="28%" />
<col width="54%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">size</th>
<th class="head">name</th>
<th class="head">description</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>int8_t[20]</td>
<td>info_hash</td>
<td>The info hash that is to be scraped.</td>
</tr>
</tbody>
</table>
<p>Server replies with packet:</p>
<table border="1" class="docutils">
<colgroup>
<col width="18%" />
<col width="28%" />
<col width="54%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">size</th>
<th class="head">name</th>
<th class="head">description</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>int32_t</td>
<td>action</td>
<td>The action, should in this case be
2 for scrape.
If 3 (for error) see <a class="reference internal" href="#errors">errors</a>.</td>
</tr>
<tr><td>int32_t</td>
<td>transaction_id</td>
<td>Must match the sent transaction id.</td>
</tr>
</tbody>
</table>
<p>The rest of the packet contains the following structures once for each info-hash
you asked in the scrape request.</p>
<table border="1" class="docutils">
<colgroup>
<col width="18%" />
<col width="28%" />
<col width="54%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">size</th>
<th class="head">name</th>
<th class="head">description</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>int32_t</td>
<td>complete</td>
<td>The current number of connected seeds.</td>
</tr>
<tr><td>int32_t</td>
<td>downloaded</td>
<td>The number of times this torrent has
been downloaded.</td>
</tr>
<tr><td>int32_t</td>
<td>incomplete</td>
<td>The current number of connected
leechers.</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="errors">
<h1>errors</h1>
<p>In case of a tracker error,</p>
<p>server replies packet:</p>
<table border="1" class="docutils">
<colgroup>
<col width="18%" />
<col width="28%" />
<col width="54%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">size</th>
<th class="head">name</th>
<th class="head">description</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>int32_t</td>
<td>action</td>
<td>The action, in this case 3, for error.
See <a class="reference internal" href="#actions">actions</a>.</td>
</tr>
<tr><td>int32_t</td>
<td>transaction_id</td>
<td>Must match the transaction_id sent
from the client.</td>
</tr>
<tr><td>int8_t[]</td>
<td>error_string</td>
<td>The rest of the packet is a string
describing the error.</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="actions">
<h1>actions</h1>
<p>The action fields has the following encoding:</p>
<blockquote>
<ul class="simple">
<li>connect = 0</li>
<li>announce = 1</li>
<li>scrape = 2</li>
<li>error = 3 (only in server replies)</li>
</ul>
</blockquote>
</div>
<div class="section" id="extensions">
<h1>extensions</h1>
<p>The extensions field is a bitmask. The following
bits are assigned:</p>
<blockquote>
<ul class="simple">
<li>1 = <a class="reference internal" href="#authentication">authentication</a>.</li>
<li>2 = <a class="reference internal" href="#request-string">request string</a>.</li>
</ul>
</blockquote>
<p>If multiple bits are present in the extension field, the extension
bodies are appended to the packet in the order of least significant
bit first. For instance, if both bit 1 and 2 are set, the extension
represented by bit 1 comes first, followed by the extension represented
by bit 2.</p>
<div class="section" id="authentication">
<h2>authentication</h2>
<p>The packet will have an authentication part
appended to it. It has the following format:</p>
<table border="1" class="docutils">
<colgroup>
<col width="18%" />
<col width="28%" />
<col width="54%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">size</th>
<th class="head">name</th>
<th class="head">description</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>int8_t</td>
<td>username_length</td>
<td>The number of characters in the
username.</td>
</tr>
<tr><td>int8_t[]</td>
<td>username</td>
<td>The username, the number of characters
as specified in the previous field.</td>
</tr>
<tr><td>uint8_t[8]</td>
<td>passwd_hash</td>
<td>sha1(packet + sha1(password))
The packet in this case means the
entire packet except these 8 bytes
that are the password hash. These are
the 8 first bytes (most significant)
from the 20 bytes hash calculated.</td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="section" id="request-string">
<h1>request string</h1>
<p>The request string extension is meant to allow torrent creators pass along
cookies back to the tracker. This can be useful for authenticating that a
torrent is allowed to be tracked by a tracker for instance. It could also
be used to authenticate users by generating torrents with unique tokens
in the tracker URL for each user. The extension body has the following format:</p>
<table border="1" class="docutils">
<colgroup>
<col width="18%" />
<col width="28%" />
<col width="54%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">size</th>
<th class="head">name</th>
<th class="head">description</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>int8_t</td>
<td>request length</td>
<td>The number of bytes in the request
string.</td>
</tr>
<tr><td>int8_t[]</td>
<td>request string</td>
<td>The string that comes after the host-
name and port in the udp tracker URL.
Typically this starts with &quot;/announce&quot;
The bittorrent client is not expected
to append query string arguments for
stats reporting, like &quot;uploaded&quot; and
&quot;downloaded&quot; since this is already
reported in the udp tracker protocol.
However, the client is free to add
arguments as extensions.</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="credits">
<h1>credits</h1>
<p>Protocol designed by Olaf van der Spek and extended by Arvid Norberg</p>
</div>
merged changes from RC_1_0
2014-10-14 18:36:06 +02:00
</div>
</div>
<div id="gradient"></div>
<div id="footer">
<table>
<tr>
<td><a href="index.html">home</a></td>
<td><a href="http://blog.libtorrent.org">blog</a></td>
<td><a href="utp.html">uTP</a></td>
</tr>
<tr>
<td><a href="https://sourceforge.net/projects/libtorrent/files/libtorrent/">download</a></td>
<td><a href="reference.html">documentation</a></td>
<td><a href="dht_store.html">DHT put extension</a></td>
</tr>
<tr>
<td><a href="https://sourceforge.net/projects/libtorrent/files/py-libtorrent/">python bindings</a></td>
<td><a href="features.html">features</a></td>
<td><a href="dht_sec.html">DHT security extension</a></td>
</tr>
<tr>
<td><a href="http://dir.gmane.org/gmane.network.bit-torrent.libtorrent">mailing list archive</a></td>
<td><a href="contributing.html">contributing</a></td>
<td><a href="streaming.html">streaming</a></td>
</tr>
<tr>
<td><a href="http://code.google.com/p/libtorrent/issues/entry">report a bug</a></td>
<td><a href="building.html">building</a></td>
<td><a href="bittorrent.pdf">bittorrent slides</a></td>
</tr>
</table>
</div>
<div id="filler"></div></div>
regenerate documentation
2013-07-19 18:31:52 +02:00
</div>
</body>
</html>