root / dotorg / v8 / html / beps / bep_0015.html

Revision 10853, 13.5 kB (checked in by dave, 11 months ago)

regenerated html.

Line 
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></title>
8<link rel="stylesheet" href="../css/bep.css" type="text/css" />
9</head>
10<body>
11<div class="document">
12
13<div id="upper" class="clear">
14<div id="wrap">
15<div id="header">
16<h1><a href="../index.html">BitTorrent<span>.org</span></a></h1>
17</div>
18<div id="nav">
19<ul>
20<li><a href="../index.html">Home</a></li>
21<li><a href="../introduction.html">For Users</a></li>
22<li><span>For Developers</span></li>
23<!-- <li><a href="./blog">Blog</a></li> -->
24<li><a href="../donate.html">Donate!</a></li>
25</ul>
26</div> <!-- nav -->
27<!-- ### Begin Content ### -->
28<div id="second">
29
30
31
32<table class="rfc2822 docutils field-list" frame="void" rules="none">
33<col class="field-name" />
34<col class="field-body" />
35<tbody valign="top">
36<tr class="field"><th class="field-name">BEP:</th><td class="field-body">15</td>
37</tr>
38<tr class="field"><th class="field-name">Title:</th><td class="field-body">UDP Tracker Protocol for BitTorrent</td>
39</tr>
40<tr class="field"><th class="field-name">Version:</th><td class="field-body">10848</td>
41</tr>
42<tr class="field"><th class="field-name">Last-Modified:</th><td class="field-body"><a class="reference external" href="https://svn.bittorrent.com/trac.cgi/browser/dotorg/trunk/html/beps/bep_0015.rst">2008-02-15 14:53:10 -0800 (Fri, 15 Feb 2008)</a></td>
43</tr>
44<tr class="field"><th class="field-name">Author:</th><td class="field-body">Olaf van der Spek &lt;olafvdspek&#32;&#97;t&#32;gmail.com&gt;</td>
45</tr>
46<tr class="field"><th class="field-name">Status:</th><td class="field-body">Draft</td>
47</tr>
48<tr class="field"><th class="field-name">Type:</th><td class="field-body">Standards Track</td>
49</tr>
50<tr class="field"><th class="field-name">Created:</th><td class="field-body">13-Feb-2008</td>
51</tr>
52<tr class="field"><th class="field-name">Post-History:</th><td class="field-body"></td>
53</tr>
54</tbody>
55</table>
56<hr />
57<div class="contents topic" id="contents">
58<p class="topic-title first">Contents</p>
59<ul class="simple">
60<li><a class="reference internal" href="#introduction" id="id4">Introduction</a></li>
61<li><a class="reference internal" href="#overhead" id="id5">Overhead</a></li>
62<li><a class="reference internal" href="#udp-connections-spoofing" id="id6">UDP connections / spoofing</a></li>
63<li><a class="reference internal" href="#time-outs" id="id7">Time outs</a></li>
64<li><a class="reference internal" href="#examples" id="id8">Examples</a></li>
65<li><a class="reference internal" href="#udp-tracker-protocol" id="id9">UDP tracker protocol</a></li>
66<li><a class="reference internal" href="#existing-implementations" id="id10">Existing implementations</a></li>
67<li><a class="reference internal" href="#ipv6" id="id11">IPv6</a></li>
68<li><a class="reference internal" href="#extensions" id="id12">Extensions</a></li>
69<li><a class="reference internal" href="#references-and-footnotes" id="id13">References and Footnotes</a></li>
70</ul>
71</div>
72<div class="section" id="introduction">
73<h1>Introduction</h1>
74<p>To discover other peers in a swarm a client announces it's existance
75to a tracker.  The HTTP protocol is used and a typical request
76contains the following parameters: info_hash, key, peer_id, port,
77downloaded, left, uploaded and compact.  A response contains a list of
78peers (host and port) and some other information.  The request and
79response are both quite short.  Since TCP is used, a connection has to
80be opened and closed, introducing additional overhead.</p>
81</div>
82<div class="section" id="overhead">
83<h1>Overhead</h1>
84<p>Using HTTP introduces significant overhead. There's overhead at the
85ethernet layer (14 bytes per packet), at the IP layer (20 bytes per
86packet), at the TCP layer (20 bytes per packet) and at the HTTP layer.
87About 10 packets are used for a request plus response containing 50
88peers and the total number of bytes used is about 1206 [1].  This
89overhead can be reduced significantly by using a UDP based
90protocol. The protocol proposed here uses 4 packets and about 618
91bytes, reducing traffic by 50%.  For a client, saving 1 kbyte every
92hour isn't significant, but for a tracker serving a million peers,
93reducing traffic by 50% matters a lot.  An additional advantage is
94that a UDP based binary protocol doesn't require a complex parser and
95no connection handling, reducing the complexity of tracker code and
96increasing it's performance.</p>
97</div>
98<div class="section" id="udp-connections-spoofing">
99<h1>UDP connections / spoofing</h1>
100<p>In the ideal case, only 2 packets would be necessary. However, it is
101possible to spoof the source address of a UDP packet.  The tracker has
102to ensure this doesn't occur, so it calculates a value (connection_id)
103and sends it to the client.  If the client spoofed it's source
104address, it won't receive this value (unless it's sniffing the
105network).  The connection_id will then be send to the tracker again in
106packet 3. The tracker verifies the connection_id and ignores the
107request if it doesn't match.  Connection IDs should not be guessable
108by the client. This is comparable to a TCP handshake and a syn cookie
109like approach can be used to storing the connection IDs on the tracker
110side.  A connection ID can be used for multiple requests. A client can
111use a connection ID until one minute after it has received
112it. Trackers should accept the connection ID until two minutes after
113it has been send.</p>
114</div>
115<div class="section" id="time-outs">
116<h1>Time outs</h1>
117<p>UDP is an 'unreliable' protocol. This means it doesn't retransmit lost
118packets itself. The application is responsible for this.  If a
119response is not received after 15 * 2 ^ n seconds, the client should
120retransmit the request, where n starts at 0 and is increased up to 8
121(3840 seconds) after every retransmission.  Note that it is necessary
122to rerequest a connection ID when it has expired.</p>
123</div>
124<div class="section" id="examples">
125<h1>Examples</h1>
126<p>Normal announce:</p>
127<pre class="literal-block">
128t = 0: connect request
129t = 1: connect response
130t = 2: announce request
131t = 3: annonce response
132</pre>
133<p>Connect times out:</p>
134<pre class="literal-block">
135t = 0: connect request
136t = 15: connect request
137t = 45: connect request
138t = 105: connect request
139etc
140</pre>
141<p>Announce times out:</p>
142<pre class="literal-block">
143t = 0:
144t = 0: connect request
145t = 1: connect response
146t = 2: announce request
147t = 17: announce request
148t = 47: announce request
149t = 107: connect request (because connection ID expired)
150t = 227: connect request
151etc
152</pre>
153<p>Multiple requests:</p>
154<pre class="literal-block">
155t = 0: connect request
156t = 1: connect response
157t = 2: announce request
158t = 3: annonce response
159t = 4: announce request
160t = 5: annonce response
161t = 60: announce request
162t = 61: annonce response
163t = 62: connect request
164t = 63: connect response
165t = 64: announce request
166t = 64: scrape request
167t = 64: scrape request
168t = 64: announce request
169t = 65: announce response
170t = 66: announce response
171t = 67: scrape response
172t = 68: scrape response
173</pre>
174</div>
175<div class="section" id="udp-tracker-protocol">
176<h1>UDP tracker protocol</h1>
177<p>All values are send in network byte order (big endian). Do not expect
178packets to be exactly of a certain size. Future extensions could
179increase the size of packets.</p>
180<p>Before announcing or scraping, you have to obtain a connection ID.</p>
181<ol class="arabic simple">
182<li>Choose a random transaction ID.</li>
183<li>Fill the connect request structure.</li>
184<li>Send the packet.</li>
185</ol>
186<p>connect request:</p>
187<pre class="literal-block">
188Offset  Size            Name            Value
1890       64-bit integer  connection_id   0x41727101980
1908       32-bit integer  action          0 // connect
19112      32-bit integer  transaction_id
19216
193</pre>
194<ol class="arabic simple">
195<li>Receive the packet.</li>
196<li>Check whether the packet is at least 16 bytes.</li>
197<li>Check whether the transaction ID is equal to the one you chose.</li>
198<li>Check whether the action is connect.</li>
199<li>Store the connection ID for future use.</li>
200</ol>
201<p>connect response:</p>
202<pre class="literal-block">
203Offset  Size            Name            Value
2040       32-bit integer  action          0 // connect
2054       32-bit integer  transaction_id
2068       64-bit integer  connection_id
20716
208</pre>
209<ol class="arabic simple">
210<li>Choose a random transaction ID.</li>
211<li>Fill the announce request structure.</li>
212<li>Send the packet.</li>
213</ol>
214<p>announce request:</p>
215<pre class="literal-block">
216Offset  Size    Name    Value
2170       64-bit integer  connection_id
2188       32-bit integer  action          1 // announce
21912      32-bit integer  transaction_id
22016      20-byte string  info_hash
22136      20-byte string  peer_id
22256      64-bit integer  downloaded
22364      64-bit integer  left
22472      64-bit integer  uploaded
22580      32-bit integer  event           0 // 0: none; 1: completed; 2: started; 3: stopped
22684      32-bit integer  IP address      0 // default
22788      32-bit integer  key
22892      32-bit integer  num_want        -1 // default
22996      16-bit integer  port
23098
231</pre>
232<ol class="arabic simple">
233<li>Receive the packet.</li>
234<li>Check whether the packet is at least 20 bytes.</li>
235<li>Check whether the transaction ID is equal to the one you chose.</li>
236<li>Check whether the action is announce.</li>
237<li>Do not announce again until interval seconds have passed or an event has occurred.</li>
238</ol>
239<p>announce response:</p>
240<pre class="literal-block">
241Offset      Size            Name            Value
2420           32-bit integer  action          1 // announce
2434           32-bit integer  transaction_id
2448           32-bit integer  interval
24512          32-bit integer  leechers
24616          32-bit integer  seeders
24720 + 6 * n  32-bit integer  IP address
24824 + 6 * n  16-bit integer  TCP port
24920 + 6 * N
250</pre>
251<p>Up to about 74 torrents can be scraped at once. A full scrape can't be done with this protocol.</p>
252<ol class="arabic simple">
253<li>Choose a random transaction ID.</li>
254<li>Fill the scrape request structure.</li>
255<li>Send the packet.</li>
256</ol>
257<p>scrape request:</p>
258<pre class="literal-block">
259Offset          Size            Name            Value
2600               64-bit integer  connection_id
2618               32-bit integer  action          2 // scrape
26212              32-bit integer  transaction_id
26316 + 20 * n     20-byte string  info_hash
26416 + 20 * N
265</pre>
266<ol class="arabic simple">
267<li>Receive the packet.</li>
268<li>Check whether the packet is at least 8 bytes.</li>
269<li>Check whether the transaction ID is equal to the one you chose.</li>
270<li>Check whether the action is scrape.</li>
271</ol>
272<p>scrape response:</p>
273<pre class="literal-block">
274Offset      Size            Name            Value
2750           32-bit integer  action          2 // scrape
2764           32-bit integer  transaction_id
2778 + 12 * n  32-bit integer  seeders
27812 + 12 * n 32-bit integer  completed
27916 + 12 * n 32-bit integer  leechers
2808 + 12 * N
281</pre>
282<p>If the tracker encounters an error, it might send an error packet.</p>
283<ol class="arabic simple">
284<li>Receive the packet.</li>
285<li>Check whether the packet is at least 8 bytes.</li>
286<li>Check whether the transaction ID is equal to the one you chose.</li>
287</ol>
288<p>error response:</p>
289<pre class="literal-block">
290Offset  Size            Name            Value
2910       32-bit integer  action          3 // error
2924       32-bit integer  transaction_id
2938       string  message
294</pre>
295</div>
296<div class="section" id="existing-implementations">
297<h1>Existing implementations</h1>
298<p>Azureus, libtorrent [2], opentracker [3], XBT Client and XBT Tracker
299support this protocol.</p>
300</div>
301<div class="section" id="ipv6">
302<h1>IPv6</h1>
303<p>IPv6 is not supported at the moment. A simple way to support IPv6
304would be to increase the size of all IP addresses to 128 bits when the
305request is done over IPv6.  However, I think more experience with IPv6
306and discussion is needed before including it.</p>
307</div>
308<div class="section" id="extensions">
309<h1>Extensions</h1>
310<p>Extension bits or a version field are not included. Clients and
311trackers should not assume packets to be of a certain size. This way,
312additional fields can be added without breaking compatibility.</p>
313</div>
314<div class="section" id="references-and-footnotes">
315<h1>References and Footnotes</h1>
316<table class="docutils footnote" frame="void" id="id1" rules="none">
317<colgroup><col class="label" /><col /></colgroup>
318<tbody valign="top">
319<tr><td class="label">[1]</td><td><a class="reference external" href="http://xbtt.sourceforge.net/udp_tracker_protocol.html">http://xbtt.sourceforge.net/udp_tracker_protocol.html</a></td></tr>
320</tbody>
321</table>
322<table class="docutils footnote" frame="void" id="id2" rules="none">
323<colgroup><col class="label" /><col /></colgroup>
324<tbody valign="top">
325<tr><td class="label">[2]</td><td><a class="reference external" href="http://www.rasterbar.com/products/libtorrent/udp_tracker_protocol.html">http://www.rasterbar.com/products/libtorrent/udp_tracker_protocol.html</a></td></tr>
326</tbody>
327</table>
328<table class="docutils footnote" frame="void" id="id3" rules="none">
329<colgroup><col class="label" /><col /></colgroup>
330<tbody valign="top">
331<tr><td class="label">[3]</td><td><a class="reference external" href="http://opentracker.blog.h3q.com/">http://opentracker.blog.h3q.com/</a></td></tr>
332</tbody>
333</table>
334<!-- Local Variables:
335mode: indented-text
336indent-tabs-mode: nil
337sentence-end-double-space: t
338fill-column: 70
339coding: utf-8
340End: -->
341</div>
342
343
344</div>
345        <div id="footer">
346<hr/>
347</div>
348
349</div>
350</body>
351</html>
Note: See TracBrowser for help on using the browser.