bittorrentspecification.htm

关于ＢＴ的协议文档

<p>Lists are encoded as follows: <i><b>l</b>&lt;bencoded values&gt;<b>e</b></i><br />
The initial <b>l</b> and trailing <b>e</b> are beginning and ending delimiters. Lists may contain any bencoded type, including integers, strings, dictionaries, and other lists.
</p>
<dl><dd><b>Example:</b> <i><b>l</b>4:spam4:eggs<b>e</b></i> represents the list of two strings: [ "spam", "eggs" ]
</dd></dl>
<div class="editsection" style="float:right;margin-left:5px;">[<a href="/index.php?title=BitTorrentSpecification&amp;action=edit&amp;section=10" title="Edit section: dictionaries">edit</a>]</div><a name="dictionaries"></a><h3> dictionaries </h3>
<p>Dictionaries are encoded as follows: <i><b>d</b>&lt;bencoded string&gt;&lt;bencoded element&gt;<b>e</b></i> <br />
The initial <b>d</b> and trailing <b>e</b> are the beginning and ending delimiters. Note that the keys must be bencoded strings.  The values may be any bencoded type, including integers, strings, lists, and other dictionaries.  Keys must be strings and appear in sorted order (sorted as raw strings, not alphanumerics). The strings should be compared using a binary comparison, not a culture-specific "natural" comparison.
</p>
<dl><dd><b>Example</b>: <i><b>d</b>3:cow3:moo4:spam4:eggs<b>e</b></i> represents the dictionary { "cow" =&gt; "moo", "spam" =&gt; "eggs" } <br />
</dd><dd><b>Example</b>: <i><b>d</b>4:spaml1:a1:be<b>e</b></i> represents the dictionary { &quot;spam&quot; =&gt; [ &quot;a&quot;, &quot;b&quot; ] } <br />
</dd><dd><b>Example</b>: <i><b>d</b>9:publisher3:bob18:publisher.location4:home17:publisher-webpage15:www.example.com<b>e</b></i>
</dd></dl>
<div class="editsection" style="float:right;margin-left:5px;">[<a href="/index.php?title=BitTorrentSpecification&amp;action=edit&amp;section=11" title="Edit section: implementations">edit</a>]</div><a name="implementations"></a><h3> implementations </h3>
<ul><li> Perl implementation: <a href="http://search.cpan.org/dist/Convert-Bencode/lib/Convert/Bencode.pm" class="external free" title="http://search.cpan.org/dist/Convert-Bencode/lib/Convert/Bencode.pm" rel="nofollow">http://search.cpan.org/dist/Convert-Bencode/lib/Convert/Bencode.pm</a>
</li><li> Python bdecode: <a href="/Decoding_bencoded_data_with_python" title="Decoding bencoded data with python">decoding bencoded data with python</a> - I've written this because bencode.py in the bittorrent source directory doesn't really handle nested bencoded data found in scrapes and this is on average 5-6 times faster than the perl implementation --<a href="/index.php?title=User:Hackeron&amp;action=edit" class="new" title="User:Hackeron">Hackeron</a> 08:56, 28 February 2007 (PST)
</li></ul>
<div class="editsection" style="float:right;margin-left:5px;">[<a href="/index.php?title=BitTorrentSpecification&amp;action=edit&amp;section=12" title="Edit section: Metainfo File Structure">edit</a>]</div><a name="Metainfo_File_Structure"></a><h2> Metainfo File Structure </h2>
<p>All data in a metainfo file is bencoded.  The specification for bencoding is defined above.
</p><p>The content of a metainfo file (the file ending in ".torrent") is a bencoded dictionary, containing the keys listed below. All character string values are UTF-8 encoded.
</p>
<ul><li> <b>info</b>: a dictionary that describes the file(s) of the torrent.  There are two possible forms: one for the case of a 'single-file' torrent with no directory structure, and one for the case of a 'multi-file' torrent (see below for details)
</li><li> <b>announce</b>: The announce URL of the tracker (string)
</li><li> <b>announce-list</b>: (optional) this is an extention to the official specification, which is also backwards compatible.  This key is used to implement lists of backup trackers.  The full specification can be found <a href="http://home.elp.rr.com/tur/multitracker-spec.txt" class="external text" title="http://home.elp.rr.com/tur/multitracker-spec.txt" rel="nofollow">here</a>.
</li><li> <b>creation date</b>: (optional) the creation time of the torrent, in standard UNIX epoch format (integer seconds since 1-Jan-1970 00:00:00 UTC)
</li><li> <b>comment</b>: (optional) free-form textual comments of the author (string)
</li><li> <b>created by</b>: (optional) name and version of the program used to create the .torrent (string)
</li></ul>
<div class="editsection" style="float:right;margin-left:5px;">[<a href="/index.php?title=BitTorrentSpecification&amp;action=edit&amp;section=13" title="Edit section: Info Dictionary">edit</a>]</div><a name="Info_Dictionary"></a><h3>Info Dictionary</h3>
<p>This section contains the field which are common to both mode, "single file" and "multiple file".
</p>
<ul><li> <b>piece length</b>: number of bytes in each piece (integer)
</li><li> <b>pieces</b>: string consisting of the concatenation of all 20-byte SHA1 hash values, one per piece (byte string)
</li><li> <b>private</b>: (optional) this field is an integer. If it is set to "1", the client MUST publish its presence ot get other peers ONLY via the trackers explicitly described in the metainfo file. If this field is set to "0" or is not present, the client may obtain peer from other means, e.g. PEX peer exchange, dht. Here, "private" may be read as "no external peer source".
<ul><li> <b>NOTE:</b> this definition is a stub, use it at your own risk, some disagree with it. fell free to improve it. <a href="http://www.azureuswiki.com/index.php/Secure_Torrents" class="external free" title="http://www.azureuswiki.com/index.php/Secure_Torrents" rel="nofollow">http://www.azureuswiki.com/index.php/Secure_Torrents</a> is the definition from azureus wiki
</li><li> Additionnally it should be noted that even if this field is used in practice, it is not part of the official specification.
</li></ul>
</li></ul>
<div class="editsection" style="float:right;margin-left:5px;">[<a href="/index.php?title=BitTorrentSpecification&amp;action=edit&amp;section=14" title="Edit section: Info in Single File Mode">edit</a>]</div><a name="Info_in_Single_File_Mode"></a><h4>Info in Single File Mode</h4>
<p>For the case of the <b>single-file</b> mode, the <b>info</b> dictionary contains the following structure:
</p>
<ul><li> <b>name</b>: the filename of the file.  This is purely advisory. (string)
</li><li> <b>length</b>: length of the file in bytes (integer)
</li><li> <b>md5sum</b>: (optional) a 32-character hexadecimal string corresponding to the MD5 sum of the file.  This is not used by BitTorrent at all, but it is included by some programs for greater compatibility.
</li></ul>
<div class="editsection" style="float:right;margin-left:5px;">[<a href="/index.php?title=BitTorrentSpecification&amp;action=edit&amp;section=15" title="Edit section: Info in Multiple File Mode">edit</a>]</div><a name="Info_in_Multiple_File_Mode"></a><h4>Info in Multiple File Mode</h4>
<p>For the case of the <b>multi-file</b> mode, the <b>info</b> dictionary contains the following structure:
</p>
<ul><li> <b>name</b>: the filename of the directory in which to store all the files.  This is purely advisory. (string)
</li><li> <b>files</b>: a list of dictionaries, one for each file. Each dictionary in this list contains the following keys:
<ul><li> <b>length</b>: length of the file in bytes (integer)
</li><li> <b>md5sum</b>: (optional) a 32-character hexadecimal string corresponding to the MD5 sum of the file.  This is not used by BitTorrent at all, but it is included by some programs for greater compatibility.
</li><li> <b>path</b>: a list containing one or more string elements that together represent the path and filename.  Each element in the list corresponds to either a directory name or (in the case of the final element) the filename.  For example, a the file "dir1/dir2/file.ext" would consist of three string elements: "dir1", "dir2", and "file.ext".  This is encoded as a bencoded list of strings such as <i>l''</i><b>4</b>:dir1'<b>4</b><i>:dir2'<b>8</b></i>:file.ext'<b>e*</b>
</li></ul>
</li></ul>
<div class="editsection" style="float:right;margin-left:5px;">[<a href="/index.php?title=BitTorrentSpecification&amp;action=edit&amp;section=16" title="Edit section: Notes">edit</a>]</div><a name="Notes"></a><h3>Notes</h3>
<ul><li> The <b>piece length</b> specifies the nominal piece size, and is usually a power of 2.  The piece size is typically chosen based on the total amount of file data in the torrent, constrained by the fact that piece sizes too large cause inefficiency, and too small a piece size will result in a large .torrent metadata file.  The conventional wisdom used to be to pick the smallest piece size that results in a .torrent file no greater than approx. 50 - 75 kB (presumably to ease the load on the server hosting the torrent files).  However, now that hosting storage and bandwidth are not tightly constrained, <i>it is best to keep the piece size to 512KB or less,</i> at least for torrents under 8-10GB or so, even if that results in a larger torrent file, in order to have a more efficient swarm for sharing files.   The most common sizes are 256 kB, 512 kB, and 1 MB.<i>  Every piece is of equal length except for the final piece, which is irregular.  The number of pieces is thus determined by 'ceil( total length / piece size )'.  For the purposes of piece boundaries in the multi-file case, consider the file data as one long continuous stream, composed of the concatenation of each file in the order listed in the </i>files<i> list.  The number of pieces and their boundaries are then determined in the same manner as the case of a single file.  Pieces may overlap file boundaries.</i>
</li><li> Each piece has a corresponding SHA1 hash of the data contained within that piece.  These hashes are concatenated to form the <i>pieces<b> value in the above </b></i><b>info</b> dictionary.  Note that this is <b>not</b> a list but rather a single string. The length of the string must be a multiple of 20.
</li></ul>
<div class="editsection" style="float:right;margin-left:5px;">[<a href="/index.php?title=BitTorrentSpecification&amp;action=edit&amp;section=17" title="Edit section: Tracker HTTP/HTTPS Protocol">edit</a>]</div><a name="Tracker_HTTP.2FHTTPS_Protocol"></a><h2> Tracker HTTP/HTTPS Protocol </h2>
<p>The tracker is an HTTP/HTTPS service which responds to HTTP GET requests. The requests include metrics from clients that help the tracker keep overall statistics about the torrent. The response includes a peer list that helps the client participate in the torrent. The base URL consists of the "announce URL" as defined in the metadata (.torrent) file.  The parameters are then added to this URL, using standard CGI methods (i.e. a '?' after the announce URL, followed by 'param=value' sequences separated by '&amp;').
</p><p>Note that all binary data in the URL (particularly info_hash and peer_id) must be properly escaped.  This means any byte not in the set 0-9, a-z, A-Z, and $-_.+!*'(), must be encoded using the "%nn" format, where nn is the hexadecimal value of the byte. (See RFC1738 for details.) 
</p><p>A 20-byte hash looks like this: \x83\xb0\xc3\xd6&gt;\x8a\x11\xebn@\x07p0\xb5\x9e\x95\xbf\xe3\x1f\xfa <br />
That same hash properly quoted looks like this:  %04%96%1F%C0%5E1%5D%08%13%81%E3%AF%CC%89%144%A53%06%FE 
</p>
<div class="editsection" style="float:right;margin-left:5px;">[<a href="/index.php?title=BitTorrentSpecification&amp;action=edit&amp;section=18" title="Edit section: Tracker Request Parameters">edit</a>]</div><a name="Tracker_Request_Parameters"></a><h3>Tracker Request Parameters</h3>
<p>The parameters used in the client-&gt;tracker GET request are as follows:
</p>
<ul><li> <b>info_hash</b>: 20-byte SHA1 hash of the <i>value</i> of the <i>info</i> key from the Metainfo file.  Note that the <i>value</i> will be a bencoded dictionary, given the definition of the <i>info</i> key above. <i>Note: This string is always urlencoded, as opposed to <a href="#peer_id" title="">peer_id</a>, which needs to be unencoded.</i>
</li><li> <b><a href="#peer_id" title="">peer_id</a></b>: 20-byte string used as a unique ID for the client, generated by the client at startup.  This is allowed to be any value, and may be binary data.  <i>There are currently no guidelines for generating this peer ID.  However, one may rightly presume that it must at least be unique for your local machine, thus should probably incorporate things like process ID and perhaps a timestamp recorded at startup. See <a href="#peer_id" title="">peer_id </a> below for common client encodings of this field.</i>
</li><li> <b>port</b>: The port number that the client is listening on.  Ports reserved for BitTorrent are typically 6881-6889.  Clients may choose to give up if it cannot establish a port within this range.
</li><li> <b>uploaded</b>: The total amount uploaded (since the client sent the 'started' event to the tracker) in base ten ASCII.  While not explicitly stated in the official specification, the concensus is that this should be the total number of bytes uploaded.
</li><li> <b>downloaded</b>: The total amount downloaded (since the client sent the 'started' event to the tracker) in base ten ASCII.  While not explicitly stated in the official specification, the consensus is that this should be the total number of bytes downloaded.
</li><li> <b>left</b>: The number of bytes this client still has to download, encoded in base ten ASCII.
</li><li> <b>compact</b>: Indicates the client accepts a compact response. The peers list is replaced by a peers string with 6 bytes per peer. The first four bytes are the host (in network byte order), the last two bytes are the port (again in network byte order). It should be noted that some trackers only support compact responses (for saving bandwidth) and refuse normal requests.
</li><li> <b>event</b>: If specified, must be one of <i>started</i>, <i>completed</i>, <i>stopped</i>, (or empty which is the same as not being specified).  If not specified, then this request is one performed at regular intervals.
<ul><li> <b>started</b>: The first request to the tracker <i>must</i> include the event key with this value.
</li><li> <b>stopped</b>: Must be sent to the tracker if the client is shutting down gracefully.
</li><li> <b>completed</b>: Must be sent to the tracker when the download completes.  However, must not be sent if the download was already 100% complete when the client started.  Presumably, this is to allow the tracker to increment the "completed downloads" metric based soley on this event.
</li></ul>
</li><li> <b>ip</b>: Optional.  The true IP address of the client machine, in dotted quad format or rfc3513 defined hexed IPv6 address.  <i>Notes: In general this parameter is not necessary as the address of the client can be determined from the IP address from which the HTTP request came.  The parameter is only needed in the case where the IP address that the request came in on is not the IP address of the client.  This happens if the client is communicating to the tracker through a proxy (or a transparent web proxy/cache.)  It also is necessary when both the client and the tracker are on the same local side of a NAT gateway.  The reason for this is that otherwise the tracker would give out the internal (RFC1918) address of the client, which is not routeable.  Therefore the client must explicitly state its (external, routeable) IP address to be given out to external peers.  Various trackers treat this parameter differently.  Some only honor it only if the IP address that the request came in on is in RFC1918 space.  Others honor it unconditionally, while others ignore it completely. In case of IPv6 address (e.g.: 2001:db8:1:2::100) it indicates only that client can communicate via IPv6.</i>
</li><li> <b>numwant</b>: Optional.  Number of peers that the client would like to receive from the tracker.  This value is permitted to be zero.  If omitted, typically defaults to 50 peers.
</li><li> <b>key</b>: Optional. An additional identification that is not shared with any users. It is intended to allow a client to prove their identity should their IP address change.
</li><li> <b>trackerid</b>: Optional. If a previous announce contained a tracker id, it should be set here.
</li></ul>
<div class="editsection" style="float:right;margin-left:5px;">[<a href="/index.php?title=BitTorrentSpecification&amp;action=edit&amp;section=19" title="Edit section: Tracker Response">edit</a>]</div><a name="Tracker_Response"></a><h3>Tracker Response</h3>
<p>The tracker responds with "text/plain" document consisting of a bencoded dictionary with the following keys:
</p>
<ul><li> <b>failure reason</b>: If present, then no other keys may be present.  The value is a human-readable error message as to why the request failed (string).
</li><li> <b>warning message</b>: (new) Similar to failure reason, but the response still gets processed normally. The warning message is shown just like an error.
</li><li> <b>interval</b>: Interval in seconds that the client should wait between sending regular requests to the tracker (mandatory)
</li><li> <b>min interval</b>: Minimum announce interval. If present clients must not reannounce more frequently than this.
</li><li> <b>tracker id</b>: A string that the client should send back on its next announcements. If absent and a previous announce sent a tracker id, do not discard the old value; keep using it.
</li><li> <b>complete</b>: number of peers with the entire file, i.e. seeders (integer)
</li><li> <b>incomplete</b>: number of non-seeder peers, aka "leechers" (integer)
</li><li> <b>peers</b>: The value is a list of dictionaries, each with the following keys:
<ul><li> <b>peer id</b>: peer's self-selected ID, as described above for the tracker request (string)
</li><li> <b>ip</b>: peer's IP address (either IPv6 or IPv4) or DNS name (string)