Torrent file

Torrent file

Filename extension	.torrent
Internet media type	application/x-bittorrent
Standard	BEP-0003

A torrent file stores metadata used for BitTorrent. It is defined in the BitTorrent specification. Simply, a torrent is data about a target file, though it contains no information about the content of the file. The only data that the torrent holds is information about the location of different pieces of the target file. Torrents work by dividing the target file into small information chunks, found on an unlimited number of different hosts. Through this method, torrents are able to download large files quickly. When a client (the recipient of a target file) has initiated a torrent download, the chunks of target file that are needed can be found easily, based on the data from the torrent itself. Once all the chunks are downloaded the client can assemble them into a usable form. Note: the torrent must be completed before it can be assembled into a usable form. This differs from conventional internet downloads which have only one host and are usable even if the file is incomplete.

A torrent file contains the URLs of many trackers and integrity metadata about all the pieces. It can also contain additional metadata defined in extensions to the BitTorrent specification. These are known as "BitTorrent Enhancement Proposals". Examples of such proposals include metadata for stating who created the torrent, and when.

File structure

A torrent file is a bencoded dictionary with the following keys:

• announce - the URL of the tracker
• info - this maps to a dictionary whose keys are dependent on whether one or more files are being shared:
  • name - suggested file/directory name where the file(s) is/are to be saved
  • piece length - number of bytes per piece. This is commonly 2¹⁸ = 256 KiB = 262,144 B.
  • pieces - a hash list. That is, a concatenation of each piece's SHA-1 hash. As SHA-1 returns a 160-bit hash, pieces will be a string whose length is a multiple of 160-bits.
  • length - size of the file in bytes (only when one file is being shared)
  • files - a list of dictionaries each corresponding to a file (only when multiple files are being shared). Each dictionary has the following keys:
    • path - a list of strings corresponding to subdirectory names, the last of which is the actual file name
    • length - size of the file in bytes.

All strings must be UTF-8 encoded.

Extensions

Draft extensions

These extensions are under consideration for standardization. the torrent file uses the extension is ".torrent"

Distributed hash tables

BEP-0005 extends BitTorrent to support distributed hash tables.

A trackerless torrent dictionary does not have an announce key. Instead, a trackerless torrent has a nodes key:

{
...
'nodes': [["<host>", <port>], ["<host>", <port>], ...]
...
}

For example,

'nodes': [["127.0.0.1", 6881], ["your.router.node", 4804]]

The specification recommends that nodes "should be set to the K closest nodes in the torrent generating client's routing table. Alternatively, the key could be set to a known good node such as one operated by the person generating the torrent."

Multiple trackers

BEP-0012 extends BitTorrent to support multiple trackers.

A new key, announce-list, is placed in the top-most list (i.e. with announce and info)

...
}

HTTP seeds

BEP-0017 extends BitTorrent to support HTTP seeds.

A new key, httpseeds, is placed in the top-most list (i.e. with announce and info). This key's value is a list of web addresses where torrent data can be retrieved:

{
...
'httpseeds': ['http://www.site1.com/source1.php', 'http://www.site2.com/source2.php']
...
}

Private torrents

BEP-0027 extends BitTorrent to support private torrents.

A new key, private, is placed in the info dictionary. This key's value is 1 if the torrent is private:

{
...
'private': 1
...
}

Merkle trees

BEP-0030 extends BitTorrent to support Merkle trees.

A torrent file using Merkle trees does not have a pieces key in the info list. Instead, such a torrent file has a root hash key in the info list. This key's value is the root hash of the Merkle hash:

{
...
'info': {
...
'root hash': e6bdebcc5d55da0a77f4bb1b57d88de794838577
...
}
...
}

Examples

Single file

Here is what a de-bencoded torrent file (with piece length 256KiB = 262144 bytes) for a file debian-503-amd64-CD-1.iso (whose size is 647MiB = 678301696 bytes) might look like:

{'announce': 'http://bttracker.debian.org:6969/announce',
'info': {'name': 'debian-503-amd64-CD-1.iso',
'piece length': 262144,
'length': 678301696,
'pieces': '841ae846bc5b6d7bd6e9aa3dd9e551559c82abc1 ... d14f1631d776008f83772ee170c42411618190a4'
}
}

Note: pieces here would be a ceil(length/piece length) * 160-bit = ceil(678301696/262144) * 160-bit = ceil(2587.515625) * 160-bit = 2588 * 160-bit = 414080-bit = 51KiB value.

Multiple files

Here is what a de-bencoded torrent file (with piece length 256KiB = 262144) for two files, 111.txt & 222.txt, might look like:

{'announce': 'http://tracker.site1.com/announce',
'info: {
   'name': 'directoryName',
   'piece length': 262144,
   'files': [ {'path': '111.txt', 'length': 111}, {'path': '222.txt', 'length': 222} ],
   'pieces': '6a8af7eda90ba9f851831073c48ea6b7b7e9feeb...8a43d9d965a47f75488d3fb47d2c586337a20b9f'
  }
}

External links

• Official BitTorrent Specification
• Search engine for Torrent files