From 68a57218e7bb0d1bc73df7c8cf04f86b7b53e4d6 Mon Sep 17 00:00:00 2001 From: arvidn Date: Tue, 18 Feb 2020 13:06:29 +0100 Subject: [PATCH] add note about listening to port 0. Add bittorrent glossary --- docs/hunspell/libtorrent.dic | 1 + docs/manual.rst | 104 +++++++++++++++++++++++++++ include/libtorrent/settings_pack.hpp | 8 +++ 3 files changed, 113 insertions(+) diff --git a/docs/hunspell/libtorrent.dic b/docs/hunspell/libtorrent.dic index a19e8469f..847aaaf86 100644 --- a/docs/hunspell/libtorrent.dic +++ b/docs/hunspell/libtorrent.dic @@ -555,3 +555,4 @@ InternetGatewayDevice netmask fe80 vcpkg +leecher diff --git a/docs/manual.rst b/docs/manual.rst index f06c822df..27fe55e76 100644 --- a/docs/manual.rst +++ b/docs/manual.rst @@ -84,6 +84,13 @@ troubleshooting_ .. _troubleshooting: troubleshooting.html +ABI considerations +================== + +libtorrent maintains a stable ABI for versions with the same major and minor versions. + +e.g. libtorrent-1.2.0 is ABI compatible with libtorrent-1.2.1 but not with libtorrent-1.1 + network primitives ================== @@ -1108,3 +1115,100 @@ The available stats metrics are: .. include:: stats_counters.rst +glossary +======== + +The libtorrent documentation use words that are bittorrent terms of art. This +section defines some of these words. For an overview of what bittorrent is and +how it works, see these slides_. For an introduction to the bittorrent DHT, see +`this presentation`_. + +.. _slides: bittorrent.pdf +.. _`this presentation`: https://vimeo.com/56044595 + +announce + The act of telling a tracker or the DHT network about the existence of + oneself and how other peers can connect, by specifying port one is listening + on. + +block + A subset of a piece. Almost always 16 kiB of payload, unless the piece size is + smaller. This is the granularity file payload is requested from peers on the + network. + +DHT + The distributed hash table is a cross-swarm, world-wide network of bittorrent + peers. It's loosely connected, implementing the Kademlia protocol. Its purpose + is to act as a tracker. Peers can announce their presence to nodes on the DHT + and other peers can discover them to join the swarm. + +HTTP tracker + A tracker that uses the HTTP protocol for announces. + +info dictionary + The subset of a torrent file that describes piece hashes and file names. This + is the only mandatory part necessary to join the swarm (network of peers) for + the torrent. + +info hash + The hash of the info dictionary. This uniquely identifies a torrent and is + used by the protocol to ensure peers talking to each other agree on which swarm + they are participating in. Sometimes spelled info-hash. + +leecher + A peer that is still interested in downloading more pieces for the torrent. + It is not a seed. + +magnet link + A URI containing the info hash for a torrent, allowing peers to join its + swarm. May optionally contain a display name, trackers and web seeds. + Typically magnet links rely on peers joining the swarm via the DHT. + +metadata + Synonymous to a torrent file + +peer + A computer running bittorrent client software that participates in the network + for a particular torrent/set of files. + +piece + The smallest number of bytes that can be validated when downloading (no + longer the case in bittorrent V2). The smallest part of the files that can be + advertised to other peers. The size of a piece is determined by the info + dictionary inside the torrent file. + +seed + A computer running bittorrent client software that has the complete files for + a specific torrent, able to share any piece for that file with other peers in + the network + +swarm + The network of peers participating in sharing and downloading of a specific torrent. + +torrent + May refer to a torrent file or the swarm (network of peers) created around + the torrent file. + +torrent file + A file ending in .torrent describing the content of a set of files (but not + containing the content). Importantly, it contains hashes of all files, split + up into pieces. It may optionally contain references to trackers and nodes on + the DHT network to aid peers in joining the network of peers sharing + these files. + +tracker + A server peers can announce to and receive other peers back belonging to the + same swarm. Trackers are used to introduce peers to each other, within a swarm. + When announcing, the info hash of the torrent is included. Trackers can + introduce peers to any info-hash that's specified, given other peers also use + the same tracker. Some trackers restrict which info hashes they support based + on a white list. + +UDP tracker + A tracker that uses a UDP based protocol for announces. + +web seed + A web server that is acting a seed, providing access to all pieces of all + files over HTTP. This is an extension that client software may or may not + support. + diff --git a/include/libtorrent/settings_pack.hpp b/include/libtorrent/settings_pack.hpp index 9672e45fc..b16fb7a70 100644 --- a/include/libtorrent/settings_pack.hpp +++ b/include/libtorrent/settings_pack.hpp @@ -206,6 +206,14 @@ namespace aux { // multiple ports. Binding to port 0 will make the operating system // pick the port. // + // .. note:: + // There are reasons to stick to the same port across sessions, + // which would mean only using port 0 on the first start, and + // recording the port that was picked for subsequent startups. + // Trackers, the DHT and other peers will remember the port they see + // you use and hand that port out to other peers trying to connect + // to you, as well as trying to connect to you themselves. + // // a port that has an "s" suffix will accept SSL connections. (note // that SSL sockets are not enabled by default). //