root / dotorg / trunk / html / beps / bep_0015.html

Revision 11040, 13.6 kB (checked in by dave, 8 weeks ago)

All HTML docs now reference the new SVN server running at bittorrent.org

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