Changeset 10528

Show
Ignore:
Timestamp:
02/04/2008 04:10:30 PM (10 months ago)
Author:
dave
Message:

Change revision number to automatically updated $Revision$ in all .rst files.
Change last-modified date to automatically updated $Date$ in all .rst files.
Add "Local Variables" to the end of all .rst files.
Fix BEP numbers.
Make header formatting in all .rst files conform to PEP-style rst formatting requirements.

Remove some HTML markup from the bep_0003.rst, the BitTorrent? protocol standard.

Location:
dotorg/trunk_fixed/html/beps
Files:
9 modified

Legend:

Unmodified
Added
Removed

  • dotorg/trunk_fixed/html/beps/bep_0000.rst

    r10491 r10528  
    11BEP: 0 
    22Title: Index of BitTorrent Enhancement Proposals  
    3 Version: 1 
    4 Last-Modified: 11-Jan-2008 
    5 Author:  David Harrison 
     3Version: $Revision$ 
     4Last-Modified: $Date$ 
     5Author:  David Harrison <dave@bittorrent.com> 
    66Status:  Active 
    77Type:    Process 
    … …  
    1313wish of Bram Cohen that the BitTorrent mainline python implementation 
    1414remain open source and that the protocol development process be 
    15 modelled after the Python Enhancement Proposal~(PEP) process. 
     15modelled after the Python Enhancement Proposal (PEP) process. 
    1616 
    1717This document indexes all BitTorrent Enhancement Proposals (BEPs). 
    1818When a new proposal is submitted, one of the BitTorrent.org editors  
    1919assigns a BEP number and updates this index appropriately.  The process  
    20 is modelled after the PEP process used in the python community [#python].  Each  
     20is modelled after the PEP process used in the python community [#python]_.  Each  
    2121document has a number that never changes and the history of document is  
    22 maintained in subversion [#svn].   
     22maintained in subversion [#svn]_.   
    2323 
    2424 
    25 =====  =========================================   
    26 Num    Title                                      
    27 =====  ========================================= 
    28 0_     Index of BitTorrent Enhancement Proporsals 
    29 1_     The BEP Process                            
    30 2_     The BitTorrent Protocol Specification      
    31 3_     Known Number Allocations                   
    32 4_     DHT Protocol                               
    33 5_     Fast Extension                             
    34 6_     IPv6 Tracker Extension                     
    35 7_     Tracker Peer Obfuscation                   
    36 8_     Metadata Extension                         
    37 9_     Extension Protocol 
    38 =====  =========================================  
     25======     ==========================================   
     26Num        Title                                      
     27======     ========================================== 
     28|0|        Index of BitTorrent Enhancement Proporsals 
     29|1|        The BEP Process                            
     30|2|        Sample reStructured Text BEP Template 
     31|3|        The BitTorrent Protocol Specification      
     32|4|        Known Number Allocations                   
     33|5|        DHT Protocol                               
     34|6|        Fast Extension                             
     35|7|        IPv6 Tracker Extension                     
     36|8|        Tracker Peer Obfuscation                   
     37|9|        Metadata Extension                         
     38|10|       Extension Protocol 
     39|1000|     Pending Standards Track Documents 
     40======     ========================================== 
    3941 
    4042 
     43.. role:: raw-html(raw) 
     44   :format: html 
    4145 
    4246.. [#python] http://www.python.org/dev/peps/ 
    4347.. [#svn] http://svn.bittorrent.org 
    44 .. _0: bep_0000.html 
    45 .. _1: bep_0001.html 
    46 .. _2: bep_0002.html 
    47 .. _3: bep_0003.html 
    48 .. _4: bep_0004.html 
    49 .. _5: bep_0005.html 
    50 .. _6: bep_0006.html 
    51 .. _7: bep_0007.html 
    52 .. _8: bep_0008.html 
    53 .. _9: bep_0009.html 
    54 .. _10: bep_0010.html 
    55 .. _11: bep_0011.html 
     48.. |0| replace:: :raw-html:`<A HREF="bep_0000.html">0</A>` 
     49.. |1| replace:: :raw-html:`<A HREF="bep_0001.html">1</A>` 
     50.. |2| replace:: :raw-html:`<A HREF="bep_0002.html">2</A>` 
     51.. |3| replace:: :raw-html:`<A HREF="bep_0003.html">3</A>` 
     52.. |4| replace:: :raw-html:`<A HREF="bep_0004.html">4</A>` 
     53.. |5| replace:: :raw-html:`<A HREF="bep_0005.html">5</A>` 
     54.. |6| replace:: :raw-html:`<A HREF="bep_0006.html">6</A>` 
     55.. |7| replace:: :raw-html:`<A HREF="bep_0007.html">7</A>` 
     56.. |8| replace:: :raw-html:`<A HREF="bep_0008.html">8</A>` 
     57.. |9| replace:: :raw-html:`<A HREF="bep_0009.html">9</A>` 
     58.. |10| replace:: :raw-html:`<A HREF="bep_0009.html">10</A>` 
     59.. |1000| replace:: :raw-html:`<A HREF="bep_1000.html">1000</A>` 

  • dotorg/trunk_fixed/html/beps/bep_0003.rst

    r10524 r10528  
    1 BEP: 2 
     1BEP: 3 
    22Title: The BitTorrent Protocol Specification 
    3 Version: 2 
    4 Last-Modified: 11-Jan-2008 
     3Version: $Revision$ 
     4Last-Modified: $Date$ 
    55Author:  Bram Cohen <bram@bittorrent.com> 
    66Status:  Final 
    … …  
    5252------------------------------- 
    5353 
    54 - Strings are length-prefixed base ten followed by a colon and the string. For example <code>4:spam</code> corresponds to 'spam'. 
     54- Strings are length-prefixed base ten followed by a colon and the string. For example ``4:spam`` corresponds to 'spam'. 
    5555 
    5656- Integers are represented by an 'i' followed by the number in base 10 
    57   followed by an 'e'. For example <code>i3e</code> corresponds to 3 and 
    58   <code>i-3e </code>corresponds to -3. Integers have no size 
    59   limitation. <code>i-0e</code> is invalid. All encodings with a leading 
    60   zero, such as <code>i03e</code>, are invalid, other than 
    61   <code>i0e</code>, which of course corresponds to 0. 
     57  followed by an 'e'. For example ``i3e`` corresponds to 3 and 
     58  ``i-3e`` corresponds to -3. Integers have no size 
     59  limitation. ``i-0e`` is invalid. All encodings with a leading 
     60  zero, such as ``i03e``, are invalid, other than 
     61  ``i0e``, which of course corresponds to 0. 
    6262 
    6363- Lists are encoded as an 'l' followed by their elements (also 
    64   bencoded) followed by an 'e'. For example <code>l4:spam4:eggse</code> 
     64  bencoded) followed by an 'e'. For example ``l4:spam4:eggse`` 
    6565  corresponds to ['spam', 'eggs']. 
    6666 
    6767- Dictionaries are encoded as a 'd' followed by a list of alternating 
    6868  keys and their corresponding values followed by an 'e'. For example, 
    69   <code>d3:cow3:moo4:spam4:eggse</code> corresponds to {'cow': 'moo', 
    70   'spam': 'eggs'} and <code>d4:spaml1:a1:bee</code> corresponds to 
     69  ``d3:cow3:moo4:spam4:eggse`` corresponds to {'cow': 'moo', 
     70  'spam': 'eggs'} and ``d4:spaml1:a1:bee`` corresponds to 
    7171  {'spam': ['a', 'b']}. Keys must be strings and appear in sorted order 
    7272  (sorted as raw strings, not alphanumerics). 
    … …  
    8282  This maps to a dictionary, with keys described below. 
    8383 
    84   The <code>name</code> key maps to a string which is the suggested name  
     84  The ``name`` key maps to a string which is the suggested name  
    8585  to save the file (or directory) as. It is purely advisory. 
    8686 
    87   <code>piece length</code> maps to the number of bytes in each piece 
     87  ``piece length`` maps to the number of bytes in each piece 
    8888  the file is split into. For the purposes of transfer, files are 
    8989  split into fixed-size pieces which are all the same length except for 
    90   possibly the last one which may be truncated. <code>piece 
    91   length</code> is almost always a power of two, most commonly 2 18 = 
     90  possibly the last one which may be truncated. ``piece 
     91  length`` is almost always a power of two, most commonly 2 18 = 
    9292  256 K (BitTorrent prior to version 3.2 uses 2 20 = 1 M as 
    9393  default). 
    9494 
    95   <code>pieces</code> maps to a string whose length is a multiple of 
     95  ``pieces`` maps to a string whose length is a multiple of 
    9696  20. It is to be subdivided into strings of length 20, each of which is 
    9797  the SHA1 hash of the piece at the corresponding index. 
    9898 
    99   There is also a key <code>length</code> or a key <code>files</code>, 
    100   but not both or neither. If <code>length</code> is present then the 
     99  There is also a key ``length`` or a key ``files``, 
     100  but not both or neither. If ``length`` is present then the 
    101101  download represents a single file, otherwise it represents a set of 
    102102  files which go in a directory structure. 
    103103 
    104   In the single file case, <code>length</code> maps to the length of 
     104  In the single file case, ``length`` maps to the length of 
    105105  the file in bytes. 
    106106 
    … …  
    108108  only having a single file by concatenating the files in the order they 
    109109  appear in the files list. The files list is the value 
    110   <code>files</code> maps to, and is a list of dictionaries containing 
     110  ``files`` maps to, and is a list of dictionaries containing 
    111111  the following keys: 
    112112   
    113   <code>length</code> - The length of the file, in bytes. 
    114  
    115   <code>path</code> - A list of strings corresponding to subdirectory 
     113  ``length`` - The length of the file, in bytes. 
     114 
     115  ``path`` - A list of strings corresponding to subdirectory 
    116116  names, the last of which is the actual file name (a zero length list 
    117117  is an error case). 
    … …  
    157157 
    158158event 
    159   This is an optional key which maps to <code>started</code>, 
    160   <code>completed</code>, or <code>stopped</code> (or 
    161   <code>empty</code>, which is the same as not being present). If not 
     159  This is an optional key which maps to ``started``, 
     160  ``completed``, or ``stopped`` (or 
     161  ``empty``, which is the same as not being present). If not 
    162162  present, this is one of the announcements done at regular 
    163   intervals. An announcement using <code>started</code> is sent when a 
    164   download first begins, and one using <code>completed</code> is sent 
    165   when the download is complete. No <code>completed</code> is sent if 
     163  intervals. An announcement using ``started`` is sent when a 
     164  download first begins, and one using ``completed`` is sent 
     165  when the download is complete. No ``completed`` is sent if 
    166166  the file was complete when started. Downloaders send an announcement 
    167   using <code>stopped</code> when they cease downloading. 
     167  using ``stopped`` when they cease downloading. 
    168168 
    169169Tracker responses are bencoded dictionaries. If a tracker response 
    170 has a key <code>failure reason</code>, then that maps to a human 
     170has a key ``failure reason``, then that maps to a human 
    171171readable string which explains why the query failed, and no other keys 
    172 are required. Otherwise, it must have two keys: <code>interval</code>, 
     172are required. Otherwise, it must have two keys: ``interval``, 
    173173which maps to the number of seconds the downloader should wait between 
    174 regular rerequests, and <code>peers</code>. <code>peers</code> maps to 
    175 a list of dictionaries corresponding to <code>peers</code>, each of 
    176 which contains the keys <code>peer id</code>, <code>ip</code>, and 
    177 <code>port</code>, which map to the peer's self-selected ID, IP 
     174regular rerequests, and ``peers``. ``peers`` maps to 
     175a list of dictionaries corresponding to ``peers``, each of 
     176which contains the keys ``peer id``, ``ip``, and 
     177``port``, which map to the peer's self-selected ID, IP 
    178178address or dns name as a string, and port number, respectively. Note 
    179179that downloaders may rerequest on nonscheduled times if an event 
    … …  
    234234Next comes the 20 byte sha1 hash of the bencoded form of the info 
    235235value from the metainfo file. (This is the same value which is 
    236 announced as <code>info_hash</code> to the tracker, only here it's raw 
     236announced as ``info_hash`` to the tracker, only here it's raw 
    237237instead of quoted here). If both sides don't send the same value, they 
    238238sever the connection. The one possible exception is if a downloader 
    … …  
    341341are three times as likely to start as the current optimistic unchoke 
    342342as anywhere else in the rotation. 
    343  
     343  
     344.. 
     345   Local Variables: 
     346   mode: indented-text 
     347   indent-tabs-mode: nil 
     348   sentence-end-double-space: t 
     349   fill-column: 70 
     350   coding: utf-8 
     351   End: 
     352 

  • dotorg/trunk_fixed/html/beps/bep_0004.rst

    r10523 r10528  
    1 BEP: 3 
     1BEP: 4 
    22Title: Assigned Numbers 
    3 Version: 1 
    4 Last-Modified: 31-Jan-2008 
     3Version: $Revision$ 
     4Last-Modified: $Date$ 
    55Author:  David Harrison 
    66Status:  Active 
    … …  
    1010 
    1111 
    12 -------------------------------------------------- 
    13 BitTorrent.org » For Developers » Assigned Numbers 
    14 -------------------------------------------------- 
    15  
    1612This document describes the known bit allocations and message IDs for 
    1713the BitTorrent protocol.  To request a bit allocation contact 
    … …  
    2016 
    2117Reserved Bit Allocations 
    22 ------------------------ 
     18======================== 
    2319 
    2420:: 
    … …  
    3531 
    3632Reserved Message IDs 
    37 -------------------- 
     33==================== 
    3834 
    3935:: 
    … …  
    6157 Additional IDs used in deployed clients 
    6258 0x14   LTEP Handshake (implemented in libtorrent, uTorrent,...) 
     59 
     60  
     61.. 
     62   Local Variables: 
     63   mode: indented-text 
     64   indent-tabs-mode: nil 
     65   sentence-end-double-space: t 
     66   fill-column: 70 
     67   coding: utf-8 
     68   End: 

  • dotorg/trunk_fixed/html/beps/bep_0005.rst

    r10522 r10528  
    1 BEP: 4 
     1BEP: 5 
    22Title: DHT Protocol 
    3 Version: 2 
    4 Last-Modified: 11-Jan-2008 
     3Version: $Revision$ 
     4Last-Modified: $Date$ 
    55Author:  Andrew Loewenstern <drue@bittorrent.com> 
    6 Status:  Accepted 
     6Status:  Draft 
    77Type:    Standards Track 
    88Created: 31-Jan-2008 
    … …  
    1111BitTorrent uses a "distributed sloppy hash table" (DHT) for storing 
    1212peer contact information for "trackerless" torrents. In effect, each 
    13 peer becomes a tracker. The protocol is based on Kademila[Kademlia]_ and is 
     13peer becomes a tracker. The protocol is based on Kademila [#Kademlia]_ and is 
    1414implemented over UDP. 
    1515 
    … …  
    2323using the BitTorrent protocol. 
    2424 
     25 
    2526Overview 
    26 -------- 
     27======== 
    2728 
    2829Each node has a globally unique identifier known as the "node ID." 
    29 Node IDs are chosen at random from the same 160-bit space as BitTorrent 
    30 infohashes [#entropy]_.  A "distance metric" is used to compare two node IDs or a node  
    31 ID and an infohash for "closeness." Nodes must maintain a routing table 
    32 containing the contact information for a small number of other nodes. 
    33 The routing table becomes more detailed as IDs get closer to the node's 
    34 own ID. Nodes know about many other nodes in the DHT that have IDs that 
    35 are "close" to their own but have only a handful of contacts with IDs 
    36 that are very far away from their own. 
     30Node IDs are chosen at random from the same 160-bit space as 
     31BitTorrent infohashes [#entropy]_.  A "distance metric" is used to 
     32compare two node IDs or a node ID and an infohash for "closeness." 
     33Nodes must maintain a routing table containing the contact information 
     34for a small number of other nodes.  The routing table becomes more 
     35detailed as IDs get closer to the node's own ID. Nodes know about many 
     36other nodes in the DHT that have IDs that are "close" to their own but 
     37have only a handful of contacts with IDs that are very far away from 
     38their own. 
    3739 
    3840In Kademlia, the distance metric is XOR and the result is interpreted 
    … …  
    7072 
    7173Routing Table 
    72 ------------- 
     74============= 
    7375 
    7476Every node maintains a routing table of known good nodes. The nodes in 
    … …  
    137139 
    138140BitTorrent Protocol Extension 
    139 ----------------------------- 
     141============================= 
    140142 
    141143The BitTorrent protocol has been extended to exchange node UDP port 
    … …  
    159161 
    160162Torrent File Extensions 
    161 ----------------------- 
     163======================= 
    162164 
    163165A trackerless torrent dictionary does not have an "announce" key. 
    … …  
    177179 
    178180KRPC Protocol 
    179 ------------- 
     181============= 
    180182 
    181183The KRPC protocol is a simple RPC mechanism consisting of bencoded 
    … …  
    198200 
    199201Contact Encoding 
    200   Contact information for peers is encoded as a 6-byte string. Also 
    201   known as "Compact IP-address/port info" the 4-byte IP address is in 
    202   network byte order with the 2 byte port in network byte order 
    203   concatenated onto the end. 
    204  
    205   Contact information for nodes is encoded as a 26-byte string. 
    206   Also known as "Compact node info" the 20-byte Node ID in network byte 
    207   order has the compact IP-address/port info concatenated to the end. 
     202---------------- 
     203 
     204Contact information for peers is encoded as a 6-byte string. Also 
     205known as "Compact IP-address/port info" the 4-byte IP address is in 
     206network byte order with the 2 byte port in network byte order 
     207concatenated onto the end. 
     208   
     209Contact information for nodes is encoded as a 26-byte string. 
     210Also known as "Compact node info" the 20-byte Node ID in network byte 
     211order has the compact IP-address/port info concatenated to the end. 
    208212 
    209213Queries 
    210   Queries, or KRPC message dictionaries with a "y" value of "q", 
    211   contain two additional keys; "q" and "a". Key "q" has a string value 
    212   containing the method name of the query. Key "a" has a dictionary value 
    213   containing named arguments to the query. 
     214------- 
     215 
     216Queries, or KRPC message dictionaries with a "y" value of "q", 
     217contain two additional keys; "q" and "a". Key "q" has a string value 
     218containing the method name of the query. Key "a" has a dictionary value 
     219containing named arguments to the query. 
    214220 
    215221Responses 
    216   Responses, or KRPC message dictionaries with a "y" value of "r", 
    217   contain one additional key "r". The value of "r" is a dictionary 
    218   containing named return values. Response messages are sent upon 
    219   successful completion of a query. 
     222--------- 
     223 
     224Responses, or KRPC message dictionaries with a "y" value of "r", 
     225contain one additional key "r". The value of "r" is a dictionary 
     226containing named return values. Response messages are sent upon 
     227successful completion of a query. 
    220228 
    221229Errors 
    222   Errors, or KRPC message dictionaries with a "y" value of "e", 
    223   contain one additional key "e". The value of "e" is a list. The first 
    224   element is an integer representing the error code. The second element 
    225   is a string containing the error message. Errors are sent when a query 
    226   cannot be fulfilled. The following table describes the possible error 
    227   codes: 
     230------ 
     231 
     232Errors, or KRPC message dictionaries with a "y" value of "e", 
     233contain one additional key "e". The value of "e" is a list. The first 
     234element is an integer representing the error code. The second element 
     235is a string containing the error message. Errors are sent when a query 
     236cannot be fulfilled. The following table describes the possible error 
     237codes: 
    228238 
    229239+----------+------------------------------------------+ 
    … …  
    249259   
    250260DHT Queries 
    251 ----------- 
     261=========== 
    252262 
    253263All queries have an "id" key and value containing the node ID of the 
    … …  
    256266 
    257267ping 
    258   The most basic query is a ping. "q" = "ping" A ping query has a 
    259   single argument, "id" the value is a 20-byte string containing the 
    260   senders node ID in network byte order. The appropriate response to a 
    261   ping has a single key "id" containing the node ID of the responding 
    262   node. 
     268---- 
     269 
     270The most basic query is a ping. "q" = "ping" A ping query has a 
     271single argument, "id" the value is a 20-byte string containing the 
     272senders node ID in network byte order. The appropriate response to a 
     273ping has a single key "id" containing the node ID of the responding 
     274node. 
    263275 
    264276:: 
    … …  
    283295 
    284296find_node 
    285   Find node is used to find the contact information for a node given 
    286   its ID. "q" == "find_node" A find_node query has two arguments, "id" 
    287   containing the node ID of the querying node, and "target" containing 
    288   the ID of the node sought by the queryer. When a node receives a 
    289   find_node query, it should respond with a key "nodes" and value of a 
    290   string containing the compact node info for the target node or the K 
    291   (8) closest good nodes in its own routing table. 
     297--------- 
     298 
     299Find node is used to find the contact information for a node given 
     300its ID. "q" == "find_node" A find_node query has two arguments, "id" 
     301containing the node ID of the querying node, and "target" containing 
     302the ID of the node sought by the queryer. When a node receives a 
     303find_node query, it should respond with a key "nodes" and value of a 
     304string containing the compact node info for the target node or the K 
     305(8) closest good nodes in its own routing table. 
    292306 
    293307:: 
    … …  
    312326 
    313327get_peers 
    314   Get peers associated with a torrent infohash. "q" = "get_peers" A 
    315   get_peers query has two arguments, "id" containing the node ID of the 
    316   querying node, and "info_hash" containing the infohash of the torrent. 
    317   If the queried node has peers for the infohash, they are returned in a 
    318   key "values" as a list of strings. Each string containing "compact" format 
    319   peer information for a single peer. If the queried node has no 
    320   peers for the infohash, a key "nodes" is returned containing the K 
    321   nodes in the queried nodes routing table closest to the infohash 
    322   supplied in the query. In either case a "token" key is also included in 
    323   the return value. The token value is a required argument for a future 
    324   announce_peer query. The token value should be a short binary string. 
     328--------- 
     329 
     330Get peers associated with a torrent infohash. "q" = "get_peers" A 
     331get_peers query has two arguments, "id" containing the node ID of the 
     332querying node, and "info_hash" containing the infohash of the torrent. 
     333If the queried node has peers for the infohash, they are returned in a 
     334key "values" as a list of strings. Each string containing "compact" format 
     335peer information for a single peer. If the queried node has no 
     336peers for the infohash, a key "nodes" is returned containing the K 
     337nodes in the queried nodes routing table closest to the infohash 
     338supplied in the query. In either case a "token" key is also included in 
     339the return value. The token value is a required argument for a future 
     340announce_peer query. The token value should be a short binary string. 
    325341 
    326342:: 
    … …  
    353369 
    354370announce_peer 
    355   Announce that the peer, controlling the querying node, is downloading 
    356   a torrent on a port. announce_peer has four arguments: "id" containing the node ID of the 
    357   querying node, "info_hash" containing the infohash of the torrent, 
    358   "port" containing the port as an integer, and the "token" received in 
    359   response to a previous get_peers query. The queried node must verify 
    360   that the token was previously sent to the same IP address as the 
    361   querying node. Then the queried node should store the IP address of the 
    362   querying node and the supplied port number under the infohash in its 
    363   store of peer contact information. 
     371------------- 
     372 
     373Announce that the peer, controlling the querying node, is downloading 
     374a torrent on a port. announce_peer has four arguments: "id" containing the node ID of the 
     375querying node, "info_hash" containing the infohash of the torrent, 
     376"port" containing the port as an integer, and the "token" received in 
     377response to a previous get_peers query. The queried node must verify 
     378that the token was previously sent to the same IP address as the 
     379querying node. Then the queried node should store the IP address of the 
     380querying node and the supplied port number under the infohash in its 
     381store of peer contact information. 
    364382 
    365383:: 
    … …  
    383401  bencoded = d1:rd2:id20:mnopqrstuvwxyz123456e1:t2:aa1:y1:re 
    384402 
    385  
    386 Send questions, comments and corrections to editor@bittorrent.org 
    387  
    388  
    389 .. [Kademlia] Peter Maymounkov, David Mazieres, "`Kademlia: A Peer-to-peer Information System Based on the XOR Metric`_", IPTPS 2002. 
    390  
    391 .. _`Kademlia: A Peer-to-peer Information System Based on the XOR Metric`: http://www.cs.rice.edu/Conferences/IPTPS02/109.pdf 
     403References 
     404========== 
     405 
     406.. [#Kademlia] Peter Maymounkov, David Mazieres, "Kademlia: A Peer-to-peer Information System Based on the XOR Metric", *IPTPS 2002*. http://www.cs.rice.edu/Conferences/IPTPS02/109.pdf 
    392407 
    393408.. [#entropy] Use SHA1 and plenty of entropy to ensure a unique ID. 
    394409 
     410 
     411  
     412.. 
     413   Local Variables: 
     414   mode: indented-text 
     415   indent-tabs-mode: nil 
     416   sentence-end-double-space: t 
     417   fill-column: 70 
     418   coding: utf-8 
     419   End: 

  • dotorg/trunk_fixed/html/beps/bep_0006.rst

    r10521 r10528  
    1 BEP: 5 
    2 Title: DHT Protocol 
     1BEP: 6 
     2Title: Fast Extension 
    33Version: $Revision$ 
    44Last-Modified: $Date$ 
    5 Author:  Andrew Loewenstern <drue@bittorrent.com> 
     5Author:  David Harrison <dave@bittorrent.com>, Bram Cohen <bram@bittorrent.com> 
    66Status:  Draft 
    77Type:    Standards Track 
    8 Created: 31-Jan-2008 
     8Created: 01-Feb-2008 
    99Post-History: 
    1010 
    11 BitTorrent uses a "distributed sloppy hash table" (DHT) for storing 
    12 peer contact information for "trackerless" torrents. In effect, each 
    13 peer becomes a tracker. The protocol is based on Kademila [#Kademlia]_ and is 
    14 implemented over UDP. 
    15  
    16 Please note the terminology used in this document to avoid 
    17 confusion. A "peer" is a client/server listening on a TCP port that 
    18 implements the BitTorrent protocol. A "node" is a client/server 
    19 listening on a UDP port implementing the distributed hash table 
    20 protocol. The DHT is composed of nodes and stores the location of 
    21 peers. BitTorrent clients include a DHT node, which is used to contact 
    22 other nodes in the DHT to get the location of peers to download from 
    23 using the BitTorrent protocol. 
    24  
    25  
    26 Overview 
    27 ======== 
    28  
    29 Each node has a globally unique identifier known as the "node ID." 
    30 Node IDs are chosen at random from the same 160-bit space as 
    31 BitTorrent infohashes [#entropy]_.  A "distance metric" is used to 
    32 compare two node IDs or a node ID and an infohash for "closeness." 
    33 Nodes must maintain a routing table containing the contact information 
    34 for a small number of other nodes.  The routing table becomes more 
    35 detailed as IDs get closer to the node's own ID. Nodes know about many 
    36 other nodes in the DHT that have IDs that are "close" to their own but 
    37 have only a handful of contacts with IDs that are very far away from 
    38 their own. 
    39  
    40 In Kademlia, the distance metric is XOR and the result is interpreted 
    41 as an unsigned integer. ``distance(A,B) = |A xor B|`` Smaller values 
    42 are closer. 
    43  
    44 When a node wants to find peers for a torrent, it uses the distance 
    45 metric to compare the infohash of the torrent with the IDs of the 
    46 nodes in its own routing table. It then contacts the nodes it knows 
    47 about with IDs closest to the infohash and asks them for the contact 
    48 information of peers currently downloading the torrent. If a contacted 
    49 node knows about peers for the torrent, the peer contact information 
    50 is returned with the response. Otherwise, the contacted node must 
    51 respond with the contact information of the nodes in its routing table 
    52 that are closest to the infohash of the torrent. The original node 
    53 iteratively queries nodes that are closer to the target infohash until 
    54 it cannot find any closer nodes. After the search is exhausted, the 
    55 client then inserts the peer contact information for itself onto the 
    56 responding nodes with IDs closest to the infohash of the torrent. 
    57  
    58 The return value for a query for peers includes an opaque value known 
    59