In the
BitTorrent file distribution system, a
torrent file is a
computer file that contains
metadata about files and folders to be distributed, and usually also a list of the network locations of
trackers, which are computers that help participants in the system find each other and form efficient distribution groups called
swarms.
[1]
A torrent file does not contain the content to be distributed; it only
contains information about those files, such as their names, sizes,
folder structure, and
cryptographic hash values for verifying file integrity. Depending on context, a
torrent may be the torrent file or the referenced content.
Torrent files are normally named with the
extension .torrent, as in
MyFile.torrent.
Background
Typically, Internet access is asymmetrical, supporting greater
download speeds than upload speeds, limiting the bandwidth of each
download, and sometimes enforcing bandwidth caps and periods where
systems are not accessible. This creates inefficiency when many people
want to obtain the same set of files from a single source; the source
must always be online and must have massive outbound bandwidth. The
BitTorrent protocol addresses this by decentralizing the distribution,
leveraging the ability of people to network "
peer-to-peer", among themselves.
Each file to be distributed is divided into very small
information chunks called
pieces.
Downloading peers achieve rapid download speeds by requesting multiple
pieces from different computers in the swarm. Once obtained, these
pieces are usually immediately made available for download by others in
the swarm. In this way, the burden on the network is spread among the
downloaders, rather than concentrating at a central distribution hub or
cluster. As long as all the pieces are available, peers (downloaders and
uploaders) can come and go; no one peer needs to have all the chunks,
or to even stay connected to the swarm in order for distribution to
continue among the other peers.
A small torrent file is created to represent a file or folder to be
shared. The torrent file acts as the key to initiating downloading of
the actual content. Someone interested in receiving the shared file or
folder first obtains the corresponding torrent file, either by directly
downloading it, or by using a
magnet link.
The user then opens that file in a BitTorrent client, which automates
the rest of the process. In order to learn the Internet locations of
peers which may be sharing pieces, the client connects to the trackers
named in the torrent file, and/or achieves a similar result through the
use of
distributed hash tables.
Then the client connects directly to the peers in order to request
pieces and otherwise participate in a swarm. The client may also report
progress to trackers, to help the tracker with its peer recommendations.
When the client has all the pieces, it assembles them into a usable
form. It may also continue sharing the pieces, elevating its status to
that of
seeder rather than ordinary peer.
File structure
A torrent file is a specially formatted
binary file. It always contains a list of files, integrity metadata about all the pieces, and an optional list of trackers.
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 28KiB = 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
A torrent file can also contain additional metadata defined in extensions to the BitTorrent specification.
[2]
These are known as "BitTorrent Enhancement Proposals." Examples of such
proposals include metadata for stating who created the torrent, and
when.
Draft extensions
These
extensions are under consideration for standardization.
Distributed hash tables
BEP-0005
[3] 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
[4] 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
[5] 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
[6] 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
[7] 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 256 KiB = 262144 bytes) for a file
debian-503-amd64-CD-1.iso (whose size is 647 MiB = 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 51 KiB value (
ceil(
length /
piece length) * 160 = 414080 bits).
Multiple files
Here is what a de-bencoded torrent file (with
piece length 256 KiB = 262144 B) for two files,
111.txt and
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'
}
}
