diff --git a/docs/manual.rst b/docs/manual.rst index 2a0b68623..cd1dccd3c 100644 --- a/docs/manual.rst +++ b/docs/manual.rst @@ -352,922 +352,6 @@ session_settings bool use_disk_cache_pool; }; -``version`` is automatically set to the libtorrent version you're using -in order to be forward binary compatible. This field should not be changed. - -``user_agent`` this is the client identification to the tracker. -The recommended format of this string is: -"ClientName/ClientVersion libtorrent/libtorrentVersion". -This name will not only be used when making HTTP requests, but also when -sending extended headers to peers that support that extension. - -``tracker_completion_timeout`` is the number of seconds the tracker -connection will wait from when it sent the request until it considers the -tracker to have timed-out. Default value is 60 seconds. - -``tracker_receive_timeout`` is the number of seconds to wait to receive -any data from the tracker. If no data is received for this number of -seconds, the tracker will be considered as having timed out. If a tracker -is down, this is the kind of timeout that will occur. The default value -is 20 seconds. - -``stop_tracker_timeout`` is the time to wait for tracker responses when -shutting down the session object. This is given in seconds. Default is -10 seconds. - -``tracker_maximum_response_length`` is the maximum number of bytes in a -tracker response. If a response size passes this number it will be rejected -and the connection will be closed. On gzipped responses this size is measured -on the uncompressed data. So, if you get 20 bytes of gzip response that'll -expand to 2 megs, it will be interrupted before the entire response has been -uncompressed (given your limit is lower than 2 megs). Default limit is -1 megabyte. - -``piece_timeout`` controls the number of seconds from a request is sent until -it times out if no piece response is returned. - -``request_queue_time`` is the length of the request queue given in the number -of seconds it should take for the other end to send all the pieces. i.e. the -actual number of requests depends on the download rate and this number. - -``max_allowed_in_request_queue`` is the number of outstanding block requests -a peer is allowed to queue up in the client. If a peer sends more requests -than this (before the first one has been handled) the last request will be -dropped. The higher this is, the faster upload speeds the client can get to a -single peer. - -``max_out_request_queue`` is the maximum number of outstanding requests to -send to a peer. This limit takes precedence over ``request_queue_time``. i.e. -no matter the download speed, the number of outstanding requests will never -exceed this limit. - -``whole_pieces_threshold`` is a limit in seconds. if a whole piece can be -downloaded in at least this number of seconds from a specific peer, the -peer_connection will prefer requesting whole pieces at a time from this peer. -The benefit of this is to better utilize disk caches by doing localized -accesses and also to make it easier to identify bad peers if a piece fails -the hash check. - -``peer_timeout`` is the number of seconds the peer connection should -wait (for any activity on the peer connection) before closing it due -to time out. This defaults to 120 seconds, since that's what's specified -in the protocol specification. After half the time out, a keep alive message -is sent. - -``urlseed_timeout`` is the same as ``peer_timeout`` but applies only to -url seeds. This value defaults to 20 seconds. - -``urlseed_pipeline_size`` controls the pipelining with the web server. When -using persistent connections to HTTP 1.1 servers, the client is allowed to -send more requests before the first response is received. This number controls -the number of outstanding requests to use with url-seeds. Default is 5. - -``file_pool_size`` is the the upper limit on the total number of files this -session will keep open. The reason why files are left open at all is that -some anti virus software hooks on every file close, and scans the file for -viruses. deferring the closing of the files will be the difference between -a usable system and a completely hogged down system. Most operating systems -also has a limit on the total number of file descriptors a process may have -open. It is usually a good idea to find this limit and set the number of -connections and the number of files limits so their sum is slightly below it. - -``allow_multiple_connections_per_ip`` determines if connections from the -same IP address as existing connections should be rejected or not. Multiple -connections from the same IP address is not allowed by default, to prevent -abusive behavior by peers. It may be useful to allow such connections in -cases where simulations are run on the same machie, and all peers in a -swarm has the same IP address. - -``max_failcount`` is the maximum times we try to connect to a peer before -stop connecting again. If a peer succeeds, the failcounter is reset. If -a peer is retrieved from a peer source (other than DHT) the failcount is -decremented by one, allowing another try. - -``min_reconnect_time`` is the time to wait between connection attempts. If -the peer fails, the time is multiplied by fail counter. - -``peer_connect_timeout`` the number of seconds to wait after a connection -attempt is initiated to a peer until it is considered as having timed out. -The default is 10 seconds. This setting is especially important in case -the number of half-open connections are limited, since stale half-open -connection may delay the connection of other peers considerably. - -``ignore_limits_on_local_network``, if set to true, upload, download and -unchoke limits are ignored for peers on the local network. - -``connection_speed`` is the number of connection attempts that -are made per second. If a number < 0 is specified, it will default to -200 connections per second. If 0 is specified, it means don't make -outgoing connections at all. - -``send_redundant_have`` controls if have messages will be sent -to peers that already have the piece. This is typically not necessary, -but it might be necessary for collecting statistics in some cases. -Default is false. - -``lazy_bitfields`` prevents outgoing bitfields from being full. If the -client is seed, a few bits will be set to 0, and later filled in with -have-messages. This is to prevent certain ISPs from stopping people -from seeding. - -``inactivity_timeout``, if a peer is uninteresting and uninterested -for longer than this number of seconds, it will be disconnected. -Default is 10 minutes - -``unchoke_interval`` is the number of seconds between chokes/unchokes. -On this interval, peers are re-evaluated for being choked/unchoked. This -is defined as 30 seconds in the protocol, and it should be significantly -longer than what it takes for TCP to ramp up to it's max rate. - -``optimistic_unchoke_interval`` is the number of seconds between -each *optimistic* unchoke. On this timer, the currently optimistically -unchoked peer will change. - -``announce_ip`` is the ip address passed along to trackers as the ``&ip=`` parameter. -If left as the default (an empty string), that parameter is omitted. - -``num_want`` is the number of peers we want from each tracker request. It defines -what is sent as the ``&num_want=`` parameter to the tracker. - -``initial_picker_threshold`` specifies the number of pieces we need before we -switch to rarest first picking. This defaults to 4, which means the 4 first -pieces in any torrent are picked at random, the following pieces are picked -in rarest first order. - -``allowed_fast_set_size`` is the number of pieces we allow peers to download -from us without being unchoked. - -``suggest_mode`` controls whether or not libtorrent will send out suggest -messages to create a bias of its peers to request certain pieces. The modes -are: - -* ``no_piece_suggestsions`` which is the default and will not send out suggest - messages. -* ``suggest_read_cache`` which will send out suggest messages for the most - recent pieces that are in the read cache. - -``max_queued_disk_bytes`` is the number maximum number of bytes, to be -written to disk, that can wait in the disk I/O thread queue. This queue -is only for waiting for the disk I/O thread to receive the job and either -write it to disk or insert it in the write cache. When this limit is reached, -the peer connections will stop reading data from their sockets, until the disk -thread catches up. Setting this too low will severly limit your download rate. - -``handshake_timeout`` specifies the number of seconds we allow a peer to -delay responding to a protocol handshake. If no response is received within -this time, the connection is closed. - -``use_dht_as_fallback`` determines how the DHT is used. If this is true, -the DHT will only be used for torrents where all trackers in its tracker -list has failed. Either by an explicit error message or a time out. This -is false by default, which means the DHT is used by default regardless of -if the trackers fail or not. - -``free_torrent_hashes`` determines whether or not the torrent's piece hashes -are kept in memory after the torrent becomes a seed or not. If it is set to -``true`` the hashes are freed once the torrent is a seed (they're not -needed anymore since the torrent won't download anything more). If it's set -to false they are not freed. If they are freed, the torrent_info_ returned -by get_torrent_info() will return an object that may be incomplete, that -cannot be passed back to `async_add_torrent() add_torrent()`_ for instance. - -``upnp_ignore_nonrouters`` indicates whether or not the UPnP implementation -should ignore any broadcast response from a device whose address is not the -configured router for this machine. i.e. it's a way to not talk to other -people's routers by mistake. - -``send_buffer_watermark`` is the upper limit of the send buffer low-watermark. -if the send buffer has fewer bytes than this, we'll read another 16kB block -onto it. If set too small, upload rate capacity will suffer. If set too high, -memory will be wasted. The actual watermark may be lower than this in case -the upload rate is low, this is the upper limit. - -``send_buffer_watermark_factor`` is multiplied to the peer's upload rate -to determine the low-watermark for the peer. It is specified as a percentage, -which means 100 represents a factor of 1. -The low-watermark is still clamped to not exceed the ``send_buffer_watermark`` -upper limit. This defaults to 50. For high capacity connections, setting this -higher can improve upload performance and disk throughput. Setting it too -high may waste RAM and create a bias towards read jobs over write jobs. - -``auto_upload_slots`` defaults to true. When true, if there is a global upload -limit set and the current upload rate is less than 90% of that, another upload -slot is opened. If the upload rate has been saturated for an extended period -of time, on upload slot is closed. The number of upload slots will never be -less than what has been set by ``session::set_max_uploads()``. To query the -current number of upload slots, see ``session_status::allowed_upload_slots``. - -When ``auto_upload_slots_rate_based`` is set, and ``auto_upload_slots`` is set, -the max upload slots setting is used as a minimum number of unchoked slots. -This algorithm is designed to prevent the peer from spreading its upload -capacity too thin, but still open more slots in order to utilize the full capacity. - -``choking_algorithm`` specifies which algorithm to use to determine which peers -to unchoke. This setting replaces the deprecated settings ``auto_upload_slots`` -and ``auto_upload_slots_rate_based``. - -The options for choking algorithms are: - -* ``fixed_slots_choker`` is the traditional choker with a fixed number of unchoke - slots (as specified by ``session::set_max_uploads()``). - -* ``auto_expand_choker`` opens at least the number of slots as specified by - ``session::set_max_uploads()`` but opens up more slots if the upload capacity - is not saturated. This unchoker will work just like the ``fixed_slot_choker`` - if there's no global upload rate limit set. - -* ``rate_based_choker`` opens up unchoke slots based on the upload rate - achieved to peers. The more slots that are opened, the marginal upload - rate required to open up another slot increases. - -* ``bittyrant_choker`` attempts to optimize download rate by finding the - reciprocation rate of each peer individually and prefers peers that gives - the highest *return on investment*. It still allocates all upload capacity, - but shuffles it around to the best peers first. For this choker to be - efficient, you need to set a global upload rate limit - (``session_settings::upload_rate_limit``). For more information about this - choker, see the paper_. - -.. _paper: http://bittyrant.cs.washington.edu/#papers - -``seed_choking_algorithm`` controls the seeding unchoke behavior. The available -options are: - -* ``round_robin`` which round-robins the peers that are unchoked when seeding. This - distributes the upload bandwidht uniformly and fairly. It minimizes the ability - for a peer to download everything without redistributing it. - -* ``fastest_upload`` unchokes the peers we can send to the fastest. This might be - a bit more reliable in utilizing all available capacity. - -* ``anti_leech`` prioritizes peers who have just started or are just about to finish - the download. The intention is to force peers in the middle of the download to - trade with each other. - -``use_parole_mode`` specifies if parole mode should be used. Parole mode means -that peers that participate in pieces that fail the hash check are put in a mode -where they are only allowed to download whole pieces. If the whole piece a peer -in parole mode fails the hash check, it is banned. If a peer participates in a -piece that passes the hash check, it is taken out of parole mode. - -``cache_size`` is the disk write and read cache. It is specified in units of -16 KiB blocks. Buffers that are part of a peer's send or receive buffer also -count against this limit. Send and receive buffers will never be denied to be -allocated, but they will cause the actual cached blocks to be flushed or evicted. -If this is set to -1, the cache size is automatically set to the amount -of physical RAM available in the machine divided by 8. If the amount of physical -RAM cannot be determined, it's set to 1024 (= 16 MiB). - -Disk buffers are allocated using a pool allocator, the number of blocks that -are allocated at a time when the pool needs to grow can be specified in -``cache_buffer_chunk_size``. This defaults to 16 blocks. Lower numbers -saves memory at the expense of more heap allocations. It must be at least 1. - -``cache_expiry`` is the number of seconds from the last cached write to a piece -in the write cache, to when it's forcefully flushed to disk. Default is 60 second. - -``use_read_cache``, is set to true (default), the disk cache is also used to -cache pieces read from disk. Blocks for writing pieces takes presedence. - -``explicit_read_cache`` defaults to 0. If set to something greater than 0, the -disk read cache will not be evicted by cache misses and will explicitly be -controlled based on the rarity of pieces. Rare pieces are more likely to be -cached. This would typically be used together with ``suggest_mode`` set to -``suggest_read_cache``. The value is the number of pieces to keep in the read -cache. If the actual read cache can't fit as many, it will essentially be clamped. - -``explicit_cache_interval`` is the number of seconds in between each refresh of -a part of the explicit read cache. Torrents take turns in refreshing and this -is the time in between each torrent refresh. Refreshing a torrent's explicit -read cache means scanning all pieces and picking a random set of the rarest ones. -There is an affinity to pick pieces that are already in the cache, so that -subsequent refreshes only swaps in pieces that are rarer than whatever is in -the cache at the time. - -``disk_io_write_mode`` and ``disk_io_read_mode`` determines how files are -opened when they're in read only mode versus read and write mode. The options -are: - - * enable_os_cache - This is the default and files are opened normally, with the OS caching - reads and writes. - * disable_os_cache_for_aligned_files - This will open files in unbuffered mode for files where every read and - write would be sector aligned. Using aligned disk offsets is a requirement - on some operating systems. - * disable_os_cache - This opens all files in unbuffered mode (if allowed by the operating system). - Linux and Windows, for instance, require disk offsets to be sector aligned, - and in those cases, this option is the same as ``disable_os_caches_for_aligned_files``. - -One reason to disable caching is that it may help the operating system from growing -its file cache indefinitely. Since some OSes only allow aligned files to be opened -in unbuffered mode, It is recommended to make the largest file in a torrent the first -file (with offset 0) or use pad files to align all files to piece boundries. - -``outgoing_ports``, if set to something other than (0, 0) is a range of ports -used to bind outgoing sockets to. This may be useful for users whose router -allows them to assign QoS classes to traffic based on its local port. It is -a range instead of a single port because of the problems with failing to reconnect -to peers if a previous socket to that peer and port is in ``TIME_WAIT`` state. - -.. warning:: setting outgoing ports will limit the ability to keep multiple - connections to the same client, even for different torrents. It is not - recommended to change this setting. Its main purpose is to use as an - escape hatch for cheap routers with QoS capability but can only classify - flows based on port numbers. - -``peer_tos`` determines the TOS byte set in the IP header of every packet -sent to peers (including web seeds). The default value for this is ``0x0`` -(no marking). One potentially useful TOS mark is ``0x20``, this represents -the *QBone scavenger service*. For more details, see QBSS_. - -.. _`QBSS`: http://qbone.internet2.edu/qbss/ - -``active_downloads`` and ``active_seeds`` controls how many active seeding and -downloading torrents the queuing mechanism allows. The target number of active -torrents is ``min(active_downloads + active_seeds, active_limit)``. -``active_downloads`` and ``active_seeds`` are upper limits on the number of -downloading torrents and seeding torrents respectively. Setting the value to --1 means unlimited. - -For example if there are 10 seeding torrents and 10 downloading torrents, and -``active_downloads`` is 4 and ``active_seeds`` is 4, there will be 4 seeds -active and 4 downloading torrents. If the settings are ``active_downloads`` = 2 -and ``active_seeds`` = 4, then there will be 2 downloading torrents and 4 seeding -torrents active. Torrents that are not auto managed are also counted against these -limits. If there are non-auto managed torrents that use up all the slots, no -auto managed torrent will be activated. - -``auto_manage_prefer_seeds`` specifies if libtorrent should prefer giving seeds -active slots or downloading torrents. The default is ``false``. - -if ``dont_count_slow_torrents`` is true, torrents without any payload transfers are -not subject to the ``active_seeds`` and ``active_downloads`` limits. This is intended -to make it more likely to utilize all available bandwidth, and avoid having torrents -that don't transfer anything block the active slots. - -``active_limit`` is a hard limit on the number of active torrents. This applies even to -slow torrents. - -``active_dht_limit`` is the max number of torrents to announce to the DHT. By default -this is set to 88, which is no more than one DHT announce every 10 seconds. - -``active_tracker_limit`` is the max number of torrents to announce to their trackers. -By default this is 360, which is no more than one announce every 5 seconds. - -``active_lsd_limit`` is the max number of torrents to announce to the local network -over the local service discovery protocol. By default this is 80, which is no more -than one announce every 5 seconds (assuming the default announce interval of 5 minutes). - -You can have more torrents *active*, even though they are not announced to the DHT, -lsd or their tracker. If some peer knows about you for any reason and tries to connect, -it will still be accepted, unless the torrent is paused, which means it won't accept -any connections. - -``auto_manage_interval`` is the number of seconds between the torrent queue -is updated, and rotated. - -``share_ratio_limit`` is the upload / download ratio limit for considering a -seeding torrent have met the seed limit criteria. See queuing_. - -``seed_time_ratio_limit`` is the seeding time / downloading time ratio limit -for considering a seeding torrent to have met the seed limit criteria. See queuing_. - -``seed_time_limit`` is the limit on the time a torrent has been an active seed -(specified in seconds) before it is considered having met the seed limit criteria. -See queuing_. - -``peer_turnover_interval`` controls a feature where libtorrent periodically can disconnect -the least useful peers in the hope of connecting to better ones. This settings controls -the interval of this optimistic disconnect. It defaults to every 5 minutes, and -is specified in seconds. - -``peer_turnover`` Is the fraction of the peers that are disconnected. This is -a float where 1.f represents all peers an 0 represents no peers. It defaults to -4% (i.e. 0.04f) - -``peer_turnover_cutoff`` is the cut off trigger for optimistic unchokes. If a torrent -has more than this fraction of its connection limit, the optimistic unchoke is -triggered. This defaults to 90% (i.e. 0.9f). - -``close_redundant_connections`` specifies whether libtorrent should close -connections where both ends have no utility in keeping the connection open. -For instance if both ends have completed their downloads, there's no point -in keeping it open. This defaults to ``true``. - -``auto_scrape_interval`` is the number of seconds between scrapes of -queued torrents (auto managed and paused torrents). Auto managed -torrents that are paused, are scraped regularly in order to keep -track of their downloader/seed ratio. This ratio is used to determine -which torrents to seed and which to pause. - -``auto_scrape_min_interval`` is the minimum number of seconds between any -automatic scrape (regardless of torrent). In case there are a large number -of paused auto managed torrents, this puts a limit on how often a scrape -request is sent. - -``max_peerlist_size`` is the maximum number of peers in the list of -known peers. These peers are not necessarily connected, so this number -should be much greater than the maximum number of connected peers. -Peers are evicted from the cache when the list grows passed 90% of -this limit, and once the size hits the limit, peers are no longer -added to the list. If this limit is set to 0, there is no limit on -how many peers we'll keep in the peer list. - -``max_paused_peerlist_size`` is the max peer list size used for torrents -that are paused. This default to the same as ``max_peerlist_size``, but -can be used to save memory for paused torrents, since it's not as -important for them to keep a large peer list. - -``min_announce_interval`` is the minimum allowed announce interval -for a tracker. This is specified in seconds, defaults to 5 minutes and -is used as a sanity check on what is returned from a tracker. It -mitigates hammering misconfigured trackers. - -If ``prioritize_partial_pieces`` is true, partial pieces are picked -before pieces that are more rare. If false, rare pieces are always -prioritized, unless the number of partial pieces is growing out of -proportion. - -``auto_manage_startup`` is the number of seconds a torrent is considered -active after it was started, regardless of upload and download speed. This -is so that newly started torrents are not considered inactive until they -have a fair chance to start downloading. - -If ``rate_limit_ip_overhead`` is set to true, the estimated TCP/IP overhead is -drained from the rate limiters, to avoid exceeding the limits with the total traffic - -``announce_to_all_trackers`` controls how multi tracker torrents are -treated. If this is set to true, all trackers in the same tier are -announced to in parallel. If all trackers in tier 0 fails, all trackers -in tier 1 are announced as well. If it's set to false, the behavior is as -defined by the multi tracker specification. It defaults to false, which -is the same behavior previous versions of libtorrent has had as well. - -``announce_to_all_tiers`` also controls how multi tracker torrents are -treated. When this is set to true, one tracker from each tier is announced -to. This is the uTorrent behavior. This is false by default in order -to comply with the multi-tracker specification. - -``prefer_udp_trackers`` is true by default. It means that trackers may -be rearranged in a way that udp trackers are always tried before http -trackers for the same hostname. Setting this to fails means that the -trackers' tier is respected and there's no preference of one protocol -over another. - -``strict_super_seeding`` when this is set to true, a piece has to -have been forwarded to a third peer before another one is handed out. -This is the traditional definition of super seeding. - -``seeding_piece_quota`` is the number of pieces to send to a peer, -when seeding, before rotating in another peer to the unchoke set. -It defaults to 3 pieces, which means that when seeding, any peer we've -sent more than this number of pieces to will be unchoked in favour of -a choked peer. - -``max_sparse_regions`` is a limit of the number of *sparse regions* in -a torrent. A sparse region is defined as a hole of pieces we have not -yet downloaded, in between pieces that have been downloaded. This is -used as a hack for windows vista which has a bug where you cannot -write files with more than a certain number of sparse regions. This -limit is not hard, it will be exceeded. Once it's exceeded, pieces -that will maintain or decrease the number of sparse regions are -prioritized. To disable this functionality, set this to 0. It defaults -to 0 on all platforms except windows. - -``lock_disk_cache`` if lock disk cache is set to true the disk cache -that's in use, will be locked in physical memory, preventing it from -being swapped out. - -``max_rejects`` is the number of piece requests we will reject in a row -while a peer is choked before the peer is considered abusive and is -disconnected. - - -``recv_socket_buffer_size`` and ``send_socket_buffer_size`` specifies -the buffer sizes set on peer sockets. 0 (which is the default) means -the OS default (i.e. don't change the buffer sizes). The socket buffer -sizes are changed using setsockopt() with SOL_SOCKET/SO_RCVBUF and -SO_SNDBUFFER. - -``optimize_hashing_for_speed`` chooses between two ways of reading back -piece data from disk when its complete and needs to be verified against -the piece hash. This happens if some blocks were flushed to the disk -out of order. Everything that is flushed in order is hashed as it goes -along. Optimizing for speed will allocate space to fit all the the -remaingin, unhashed, part of the piece, reads the data into it in a single -call and hashes it. This is the default. If ``optimizing_hashing_for_speed`` -is false, a single block will be allocated (16 kB), and the unhashed parts -of the piece are read, one at a time, and hashed in this single block. This -is appropriate on systems that are memory constrained. - -``file_checks_delay_per_block`` is the number of milliseconds to sleep -in between disk read operations when checking torrents. This defaults -to 0, but can be set to higher numbers to slow down the rate at which -data is read from the disk while checking. This may be useful for -background tasks that doesn't matter if they take a bit longer, as long -as they leave disk I/O time for other processes. - -``disk_cache_algorithm`` tells the disk I/O thread which cache flush -algorithm to use. The default algorithm is largest_contiguous. This -flushes the entire piece, in the write cache, that was least recently -written to. This is specified by the ``session_settings::lru`` enum -value. ``session_settings::largest_contiguous`` will flush the largest -sequences of contiguous blocks from the write cache, regarless of the -piece's last use time. ``session_settings::avoid_readback`` will prioritize -flushing blocks that will avoid having to read them back in to verify -the hash of the piece once it's done. This is especially useful for high -throughput setups, where reading from the disk is especially expensive. - -``read_cache_line_size`` is the number of blocks to read into the read -cache when a read cache miss occurs. Setting this to 0 is essentially -the same thing as disabling read cache. The number of blocks read -into the read cache is always capped by the piece boundry. - -When a piece in the write cache has ``write_cache_line_size`` contiguous -blocks in it, they will be flushed. Setting this to 1 effectively -disables the write cache. - -``optimistic_disk_retry`` is the number of seconds from a disk write -errors occur on a torrent until libtorrent will take it out of the -upload mode, to test if the error condition has been fixed. - -libtorrent will only do this automatically for auto managed torrents. - -You can explicitly take a torrent out of upload only mode using -`set_upload_mode()`_. - -``disable_hash_checks`` controls if downloaded pieces are verified against -the piece hashes in the torrent file or not. The default is false, i.e. -to verify all downloaded data. It may be useful to turn this off for performance -profiling and simulation scenarios. Do not disable the hash check for regular -bittorrent clients. - -``max_suggest_pieces`` is the max number of suggested piece indices received -from a peer that's remembered. If a peer floods suggest messages, this limit -prevents libtorrent from using too much RAM. It defaults to 10. - -If ``drop_skipped_requests`` is set to true (it defaults to false), piece -requests that have been skipped enough times when piece messages -are received, will be considered lost. Requests are considered skipped -when the returned piece messages are re-ordered compared to the order -of the requests. This was an attempt to get out of dead-locks caused by -BitComet peers silently ignoring some requests. It may cause problems -at high rates, and high level of reordering in the uploading peer, that's -why it's disabled by default. - -``low_prio_disk`` determines if the disk I/O should use a normal -or low priority policy. This defaults to true, which means that -it's low priority by default. Other processes doing disk I/O will -normally take priority in this mode. This is meant to improve the -overall responsiveness of the system while downloading in the -background. For high-performance server setups, this might not -be desirable. - -``local_service_announce_interval`` is the time between local -network announces for a torrent. By default, when local service -discovery is enabled a torrent announces itself every 5 minutes. -This interval is specified in seconds. - -``dht_announce_interval`` is the number of seconds between announcing -torrents to the distributed hash table (DHT). This is specified to -be 15 minutes which is its default. - -``dht_max_torrents`` is the max number of torrents we will track -in the DHT. - -``udp_tracker_token_expiry`` is the number of seconds libtorrent -will keep UDP tracker connection tokens around for. This is specified -to be 60 seconds, and defaults to that. The higher this value is, the -fewer packets have to be sent to the UDP tracker. In order for higher -values to work, the tracker needs to be configured to match the -expiration time for tokens. - -``volatile_read_cache``, if this is set to true, read cache blocks -that are hit by peer read requests are removed from the disk cache -to free up more space. This is useful if you don't expect the disk -cache to create any cache hits from other peers than the one who -triggered the cache line to be read into the cache in the first place. - -``guided_read_cache`` enables the disk cache to adjust the size -of a cache line generated by peers to depend on the upload rate -you are sending to that peer. The intention is to optimize the RAM -usage of the cache, to read ahead further for peers that you're -sending faster to. - -``default_cache_min_age`` is the minimum number of seconds any read -cache line is kept in the cache. This defaults to one second but -may be greater if ``guided_read_cache`` is enabled. Having a lower -bound on the time a cache line stays in the cache is an attempt -to avoid swapping the same pieces in and out of the cache in case -there is a shortage of spare cache space. - -``num_optimistic_unchoke_slots`` is the number of optimistic unchoke -slots to use. It defaults to 0, which means automatic. Having a higher -number of optimistic unchoke slots mean you will find the good peers -faster but with the trade-off to use up more bandwidth. When this is -set to 0, libtorrent opens up 20% of your allowed upload slots as -optimistic unchoke slots. - -``no_atime_storage`` this is a linux-only option and passes in the -``O_NOATIME`` to ``open()`` when opening files. This may lead to -some disk performance improvements. - -``default_est_reciprocation_rate`` is the assumed reciprocation rate -from peers when using the BitTyrant choker. This defaults to 14 kiB/s. -If set too high, you will over-estimate your peers and be more altruistic -while finding the true reciprocation rate, if it's set too low, you'll -be too stingy and waste finding the true reciprocation rate. - -``increase_est_reciprocation_rate`` specifies how many percent the -extimated reciprocation rate should be increased by each unchoke -interval a peer is still choking us back. This defaults to 20%. -This only applies to the BitTyrant choker. - -``decrease_est_reciprocation_rate`` specifies how many percent the -estimated reciprocation rate should be decreased by each unchoke -interval a peer unchokes us. This default to 3%. -This only applies to the BitTyrant choker. - -``incoming_starts_queued_torrents`` defaults to false. If a torrent -has been paused by the auto managed feature in libtorrent, i.e. -the torrent is paused and auto managed, this feature affects whether -or not it is automatically started on an incoming connection. The -main reason to queue torrents, is not to make them unavailable, but -to save on the overhead of announcing to the trackers, the DHT and to -avoid spreading one's unchoke slots too thin. If a peer managed to -find us, even though we're no in the torrent anymore, this setting -can make us start the torrent and serve it. - -When ``report_true_downloaded`` is true, the ``&downloaded=`` argument -sent to trackers will include redundant downloaded bytes. It defaults -to ``false``, which means redundant bytes are not reported to the tracker. - -``strict_end_game_mode`` defaults to true, and controls when a block -may be requested twice. If this is ``true``, a block may only be requested -twice when there's ay least one request to every piece that's left to -download in the torrent. This may slow down progress on some pieces -sometimes, but it may also avoid downloading a lot of redundant bytes. -If this is ``false``, libtorrent attempts to use each peer connection -to its max, by always requesting something, even if it means requesting -something that has been requested from another peer already. - -if ``broadcast_lsd`` is set to true, the local peer discovery -(or Local Service Discovery) will not only use IP multicast, but also -broadcast its messages. This can be useful when running on networks -that don't support multicast. Since broadcast messages might be -expensive and disruptive on networks, only every 8th announce uses -broadcast. - -``enable_outgoing_utp``, ``enable_incoming_utp``, ``enable_outgoing_tcp``, -``enable_incoming_tcp`` all determines if libtorrent should attempt to make -outgoing connections of the specific type, or allow incoming connection. By -default all of them are enabled. - -``ignore_resume_timestamps`` determines if the storage, when loading -resume data files, should verify that the file modification time -with the timestamps in the resume data. This defaults to false, which -means timestamps are taken into account, and resume data is less likely -to accepted (torrents are more likely to be fully checked when loaded). -It might be useful to set this to true if your network is faster than your -disk, and it would be faster to redownload potentially missed pieces than -to go through the whole storage to look for them. - -``no_recheck_incomplete_resume`` determines if the storage should check -the whole files when resume data is incomplete or missing or whether -it should simply assume we don't have any of the data. By default, this -is determined by the existance of any of the files. By setting this setting -to true, the files won't be checked, but will go straight to download -mode. - -``anonymous_mode`` defaults to false. When set to true, the client tries -to hide its identity to a certain degree. The peer-ID will no longer -include the client's fingerprint. The user-agent will be reset to an -empty string. - -If you're using I2P, it might make sense to enable anonymous mode. - -``force_proxy`` disables any communication that's not going over a proxy. -Enabling this requires a proxy to be configured as well, see ``set_proxy_settings``. -The listen sockets are closed, and incoming connections will -only be accepted through a SOCKS5 or I2P proxy (if a peer proxy is set up and -is run on the same machine as the tracker proxy). This setting also -disabled peer country lookups, since those are done via DNS lookups that -aren't supported by proxies. - -``tick_interval`` specifies the number of milliseconds between internal -ticks. This is the frequency with which bandwidth quota is distributed to -peers. It should not be more than one second (i.e. 1000 ms). Setting this -to a low value (around 100) means higher resolution bandwidth quota distribution, -setting it to a higher value saves CPU cycles. - -``share_mode_target`` specifies the target share ratio for share mode torrents. -This defaults to 3, meaning we'll try to upload 3 times as much as we download. -Setting this very high, will make it very conservative and you might end up -not downloading anything ever (and not affecting your share ratio). It does -not make any sense to set this any lower than 2. For instance, if only 3 peers -need to download the rarest piece, it's impossible to download a single piece -and upload it more than 3 times. If the share_mode_target is set to more than 3, -nothing is downloaded. - -``upload_rate_limit``, ``download_rate_limit``, ``local_upload_rate_limit`` -and ``local_download_rate_limit`` sets the session-global limits of upload -and download rate limits, in bytes per second. The local rates refer to peers -on the local network. By default peers on the local network are not rate limited. - -These rate limits are only used for local peers (peers within the same subnet as -the client itself) and it is only used when ``session_settings::ignore_limits_on_local_network`` -is set to true (which it is by default). These rate limits default to unthrottled, -but can be useful in case you want to treat local peers preferentially, but not -quite unthrottled. - -A value of 0 means unlimited. - -``dht_upload_rate_limit`` sets the rate limit on the DHT. This is specified in -bytes per second and defaults to 4000. For busy boxes with lots of torrents -that requires more DHT traffic, this should be raised. - -``unchoke_slots_limit`` is the max number of unchoked peers in the session. The -number of unchoke slots may be ignored depending on what ``choking_algorithm`` -is set to. A value of -1 means infinite. - -``half_open_limit`` sets the maximum number of half-open connections -libtorrent will have when connecting to peers. A half-open connection is one -where connect() has been called, but the connection still hasn't been established -(nor failed). Windows XP Service Pack 2 sets a default, system wide, limit of -the number of half-open connections to 10. So, this limit can be used to work -nicer together with other network applications on that system. The default is -to have no limit, and passing -1 as the limit, means to have no limit. When -limiting the number of simultaneous connection attempts, peers will be put in -a queue waiting for their turn to get connected. - -``connections_limit`` sets a global limit on the number of connections -opened. The number of connections is set to a hard minimum of at least two per -torrent, so if you set a too low connections limit, and open too many torrents, -the limit will not be met. - -``utp_target_delay`` is the target delay for uTP sockets in milliseconds. A high -value will make uTP connections more aggressive and cause longer queues in the upload -bottleneck. It cannot be too low, since the noise in the measurements would cause -it to send too slow. The default is 50 milliseconds. - -``utp_gain_factor`` is the number of bytes the uTP congestion window can increase -at the most in one RTT. This defaults to 300 bytes. If this is set too high, -the congestion controller reacts too hard to noise and will not be stable, if it's -set too low, it will react slow to congestion and not back off as fast. - -``utp_min_timeout`` is the shortest allowed uTP socket timeout, specified in milliseconds. -This defaults to 500 milliseconds. The timeout depends on the RTT of the connection, but -is never smaller than this value. A connection times out when every packet in a window -is lost, or when a packet is lost twice in a row (i.e. the resent packet is lost as well). - -The shorter the timeout is, the faster the connection will recover from this situation, -assuming the RTT is low enough. - -``utp_syn_resends`` is the number of SYN packets that are sent (and timed out) before -giving up and closing the socket. - -``utp_num_resends`` is the number of times a packet is sent (and lossed or timed out) -before giving up and closing the connection. - -``utp_connect_timeout`` is the number of milliseconds of timeout for the initial SYN -packet for uTP connections. For each timed out packet (in a row), the timeout is doubled. - -``utp_dynamic_sock_buf`` controls if the uTP socket manager is allowed to increase -the socket buffer if a network interface with a large MTU is used (such as loopback -or ethernet jumbo frames). This defaults to true and might improve uTP throughput. -For RAM constrained systems, disabling this typically saves around 30kB in user space -and probably around 400kB in kernel socket buffers (it adjusts the send and receive -buffer size on the kernel socket, both for IPv4 and IPv6). - -``utp_loss_multiplier`` controls how the congestion window is changed when a packet -loss is experienced. It's specified as a percentage multiplier for ``cwnd``. By default -it's set to 50 (i.e. cut in half). Do not change this value unless you know what -you're doing. Never set it higher than 100. - -The ``mixed_mode_algorithm`` determines how to treat TCP connections when there are -uTP connections. Since uTP is designed to yield to TCP, there's an inherent problem -when using swarms that have both TCP and uTP connections. If nothing is done, uTP -connections would often be starved out for bandwidth by the TCP connections. This mode -is ``prefer_tcp``. The ``peer_proportional`` mode simply looks at the current throughput -and rate limits all TCP connections to their proportional share based on how many of -the connections are TCP. This works best if uTP connections are not rate limited by -the global rate limiter (which they aren't by default). - -``rate_limit_utp`` determines if uTP connections should be throttled by the global rate -limiter or not. By default they are. - -``listen_queue_size`` is the value passed in to listen() for the listen socket. -It is the number of outstanding incoming connections to queue up while we're not -actively waiting for a connection to be accepted. The default is 5 which should -be sufficient for any normal client. If this is a high performance server which -expects to receive a lot of connections, or used in a simulator or test, it -might make sense to raise this number. It will not take affect until listen_on() -is called again (or for the first time). - -if ``announce_double_nat`` is true, the ``&ip=`` argument in tracker requests -(unless otherwise specified) will be set to the intermediate IP address, if the -user is double NATed. If ther user is not double NATed, this option has no affect. - -``torrent_connect_boost`` is the number of peers to try to connect to immediately -when the first tracker response is received for a torrent. This is a boost to -given to new torrents to accelerate them starting up. The normal connect scheduler -is run once every second, this allows peers to be connected immediately instead -of waiting for the session tick to trigger connections. - -``seeding_outgoing_connections`` determines if seeding (and finished) torrents -should attempt to make outgoing connections or not. By default this is true. It -may be set to false in very specific applications where the cost of making -outgoing connections is high, and there are no or small benefits of doing so. -For instance, if no nodes are behind a firewall or a NAT, seeds don't need to -make outgoing connections. - -if ``no_connect_privileged_ports`` is true (which is the default), libtorrent -will not connect to any peers on priviliged ports (<= 1023). This can mitigate -using bittorrent swarms for certain DDoS attacks. - -``alert_queue_size`` is the maximum number of alerts queued up internally. If -alerts are not popped, the queue will eventually fill up to this level. This -defaults to 1000. - -``max_metadata_size`` is the maximum allowed size (in bytes) to be received -by the metadata extension, i.e. magnet links. It defaults to 1 MiB. - -``smooth_connects`` is true by default, which means the number of connection -attempts per second may be limited to below the ``connection_speed``, in case -we're close to bump up against the limit of number of connections. The intention -of this setting is to more evenly distribute our connection attempts over time, -instead of attempting to connectin in batches, and timing them out in batches. - -``always_send_user_agent`` defaults to false. When set to true, web connections -will include a user-agent with every request, as opposed to just the first -request in a connection. - -``apply_ip_filter_to_trackers`` defaults to true. It determines whether the -IP filter applies to trackers as well as peers. If this is set to false, -trackers are exempt from the IP filter (if there is one). If no IP filter -is set, this setting is irrelevant. - -``read_job_every`` is used to avoid starvation of read jobs in the disk I/O -thread. By default, read jobs are deferred, sorted by physical disk location -and serviced once all write jobs have been issued. In scenarios where the -download rate is enough to saturate the disk, there's a risk the read jobs will -never be serviced. With this setting, every *x* write job, issued in a row, will -instead pick one read job off of the sorted queue, where *x* is ``read_job_every``. - -``use_disk_read_ahead`` defaults to true and will attempt to optimize disk reads -by giving the operating system heads up of disk read requests as they are queued -in the disk job queue. This gives a significant performance boost for seeding. - -``lock_files`` determines whether or not to lock files which libtorrent is downloading -to or seeding from. This is implemented using ``fcntl(F_SETLK)`` on unix systems and -by not passing in ``SHARE_READ`` and ``SHARE_WRITE`` on windows. This might prevent -3rd party processes from corrupting the files under libtorrent's feet. - -``ssl_listen`` sets the listen port for SSL connections. If this is set to 0, -no SSL listen port is opened. Otherwise a socket is opened on this port. This -setting is only taken into account when opening the regular listen port, and -won't re-open the listen socket simply by changing this setting. - -It defaults to port 4433. - -``tracker_backoff`` determines how aggressively to back off from retrying -failing trackers. This value determines *x* in the following formula, determining -the number of seconds to wait until the next retry: - - delay = 5 + 5 * x / 100 * fails^2 - -It defaults to 250. - -This setting may be useful to make libtorrent more or less aggressive in hitting -trackers. - -``ban_web_seeds`` enables banning web seeds. By default, web seeds that send -corrupt data are banned. - -``max_http_recv_buffer_size`` specifies the max number of bytes to receive into -RAM buffers when downloading stuff over HTTP. Specifically when specifying a -URL to a .torrent file when adding a torrent or when announcing to an HTTP -tracker. The default is 2 MiB. - -``support_share_mode`` enables or disables the share mode extension. This is -enabled by default. - -``support_merkle_torrents`` enables or disables the merkle tree torrent support. -This is enabled by default. - -``report_redundant_bytes`` enables or disables reporting redundant bytes to the tracker. -This is enabled by default. - -``handshake_client_version`` is the client name advertized in the peer handshake. If -set to an empty string, the user_agent string is used. - -``use_disk_cache_pool`` enables using a pool allocator for disk cache blocks. This is -disabled by default. Enabling it makes the cache perform better at high throughput. -It also makes the cache less likely and slower at returning memory back to the system -once allocated. - exceptions ========== diff --git a/include/libtorrent/session_settings.hpp b/include/libtorrent/session_settings.hpp index fa90c1155..b5ba669ba 100644 --- a/include/libtorrent/session_settings.hpp +++ b/include/libtorrent/session_settings.hpp @@ -119,34 +119,48 @@ namespace libtorrent LIBTORRENT_VERSION); ~session_settings(); - // libtorrent version. Used for forward binary compatibility + // automatically set to the libtorrent version you're using + // in order to be forward binary compatible. This field should not be changed. int version; - // this is the user agent that will be sent to the tracker - // when doing requests. It is used to identify the client. - // It cannot contain \r or \n + // the client identification to the tracker. + // The recommended format of this string is: + // "ClientName/ClientVersion libtorrent/libtorrentVersion". + // This name will not only be used when making HTTP requests, but also when + // sending extended headers to peers that support that extension. std::string user_agent; - // the number of seconds to wait until giving up on a - // tracker request if it hasn't finished + // the number of seconds the tracker + // connection will wait from when it sent the request until it considers the + // tracker to have timed-out. Default value is 60 seconds. int tracker_completion_timeout; - // the number of seconds where no data is received - // from the tracker until it should be considered - // as timed out + // the number of seconds to wait to receive + // any data from the tracker. If no data is received for this number of + // seconds, the tracker will be considered as having timed out. If a tracker + // is down, this is the kind of timeout that will occur. The default value + // is 20 seconds. int tracker_receive_timeout; // the time to wait when sending a stopped message // before considering a tracker to have timed out. // this is usually shorter, to make the client quit // faster + // + // This is given in seconds. Default is + // 10 seconds. int stop_tracker_timeout; - // if the content-length is greater than this value - // the tracker connection will be aborted + // the maximum number of bytes in a + // tracker response. If a response size passes this number it will be rejected + // and the connection will be closed. On gzipped responses this size is measured + // on the uncompressed data. So, if you get 20 bytes of gzip response that'll + // expand to 2 megs, it will be interrupted before the entire response has been + // uncompressed (given your limit is lower than 2 megs). Default limit is + // 1 megabyte. int tracker_maximum_response_length; - // the number of seconds from a request is sent until + // controls the number of seconds from a request is sent until // it times out if no piece response is returned. int piece_timeout; @@ -172,6 +186,8 @@ namespace libtorrent // the maximum number of outstanding requests to // send to a peer. This limit takes precedence over // request_queue_time. + // i.e. no matter the download speed, the number of outstanding requests will never + // exceed this limit. int max_out_request_queue; // if a whole piece can be downloaded in this number @@ -185,14 +201,21 @@ namespace libtorrent // the number of seconds to wait for any activity on // the peer wire before closing the connectiong due // to time out. + // This defaults to 120 seconds, since that's what's specified + // in the protocol specification. After half the time out, a keep alive message + // is sent. int peer_timeout; // same as peer_timeout, but only applies to url-seeds. // this is usually set lower, because web servers are // expected to be more reliable. + // This value defaults to 20 seconds. int urlseed_timeout; - // controls the pipelining size of url-seeds + // controls the pipelining with the web server. When + // using persistent connections to HTTP 1.1 servers, the client is allowed to + // send more requests before the first response is received. This number controls + // the number of outstanding requests to use with url-seeds. Default is 5. int urlseed_pipeline_size; // time to wait until a new retry takes place @@ -212,21 +235,29 @@ namespace libtorrent // limits so their sum is slightly below it. int file_pool_size; - // false to not allow multiple connections from the same - // IP address. true will allow it. + // determines if connections from the + // same IP address as existing connections should be rejected or not. Multiple + // connections from the same IP address is not allowed by default, to prevent + // abusive behavior by peers. It may be useful to allow such connections in + // cases where simulations are run on the same machie, and all peers in a + // swarm has the same IP address. bool allow_multiple_connections_per_ip; - // the number of times we can fail to connect to a peer - // before we stop retrying it. + // the maximum times we try to connect to a peer before + // stop connecting again. If a peer succeeds, its failcounter is reset. If + // a peer is retrieved from a peer source (other than DHT) the failcount is + // decremented by one, allowing another try. int max_failcount; // the number of seconds to wait to reconnect to a peer. // this time is multiplied with the failcount. int min_reconnect_time; - // this is the timeout for a connection attempt. If - // the connect does not succeed within this time, the - // connection is dropped. The time is specified in seconds. + // the number of seconds to wait after a connection + // attempt is initiated to a peer until it is considered as having timed out. + // The default is 10 seconds. This setting is especially important in case + // the number of half-open connections are limited, since stale half-open + // connection may delay the connection of other peers considerably. int peer_connect_timeout; // if set to true, upload, download and unchoke limits @@ -234,7 +265,9 @@ namespace libtorrent bool ignore_limits_on_local_network; // the number of connection attempts that - // are made per second. + // are made per second. If a number < 0 is specified, it will default to + // 200 connections per second. If 0 is specified, it means don't make + // outgoing connections at all. int connection_speed; // if this is set to true, have messages will be sent @@ -243,9 +276,9 @@ namespace libtorrent // for collecting statistics in some cases. Default is false. bool send_redundant_have; - // if this is true, outgoing bitfields will never be fuil. If the - // client is seed, a few bits will be set to 0, and later filled - // in with have messages. This is to prevent certain ISPs + // prevents outgoing bitfields from being full. If the + // client is seed, a few bits will be set to 0, and later filled in with + // have-messages. This is an old attempt to prevent certain ISPs // from stopping people from seeding. bool lazy_bitfields; @@ -254,44 +287,71 @@ namespace libtorrent // default is 10 minutes int inactivity_timeout; - // the number of seconds between chokes/unchokes + // the number of seconds between chokes/unchokes. + // On this interval, peers are re-evaluated for being choked/unchoked. This + // is defined as 30 seconds in the protocol, and it should be significantly + // longer than what it takes for TCP to ramp up to it's max rate. int unchoke_interval; // the number of seconds between - // optimistic unchokes + // each *optimistic* unchoke. On this timer, the currently optimistically + // unchoked peer will change. int optimistic_unchoke_interval; - // if this is set, this IP will be reported do the - // tracker in the ip= parameter. + // the ip address passed along to trackers as the ``&ip=`` parameter. + // If left as the default (an empty string), that parameter is omitted. + // Most trackers ignore this argument. This is here for completeness + // for edge-cases where it may be useful. std::string announce_ip; - // the num want sent to trackers + // the number of peers we want from each tracker request. It defines + // what is sent as the ``&num_want=`` parameter to the tracker. + // Stopped messages always send num_want=0. This setting control what + // to say in the case where we actually want peers. int num_want; - // while we have fewer pieces than this, pick - // random pieces instead of rarest first. + // specifies the number of pieces we need before we + // switch to rarest first picking. This defaults to 4, which means the 4 first + // pieces in any torrent are picked at random, the following pieces are picked + // in rarest first order. int initial_picker_threshold; - // the number of allowed pieces to send to peers + // the number of allowed pieces to send to choked peers // that supports the fast extensions int allowed_fast_set_size; + // options for session_settings::suggest_mode. + enum suggest_mode_t + { + // the default. will not send out suggest messages. + no_piece_suggestions = 0, + + // send out suggest messages for the most + // recent pieces that are in the read cache. + suggest_read_cache = 1 + }; + // this determines which pieces will be suggested to peers // suggest read cache will make libtorrent suggest pieces // that are fresh in the disk read cache, to potentially // lower disk access and increase the cache hit ratio - enum suggest_mode_t { no_piece_suggestions = 0, suggest_read_cache = 1 }; + // + // for options, see suggest_mode_t. int suggest_mode; // the maximum number of bytes a connection may have // pending in the disk write queue before its download // rate is being throttled. This prevents fast downloads - // to slow medias to allocate more and more memory + // to slow medias to allocate more memory // indefinitely. This should be set to at least 16 kB // to not completely disrupt normal downloads. If it's // set to 0, you will be starving the disk thread and // nothing will be written to disk. // this is a per session setting. + // + // When this limit is reached, + // the peer connections will stop reading data from their sockets, until the disk + // thread catches up. Setting this too low will severly limit your download rate. int max_queued_disk_bytes; // this is the low watermark for the disk buffer queue. @@ -307,19 +367,26 @@ namespace libtorrent // within this time, the peer is disconnected. int handshake_timeout; - // while this is true, the dht will not be used unless the - // tracker is online + // determines how the DHT is used. If this is true, + // the DHT will only be used for torrents where all trackers in its tracker + // list has failed. Either by an explicit error message or a time out. This + // is false by default, which means the DHT is used by default regardless of + // if the trackers fail or not. bool use_dht_as_fallback; - // if this is true, the piece hashes will be freed, in order - // to save memory, once the torrent is seeding. This will - // make the get_torrent_info() function to return an incomplete - // torrent object that cannot be passed back to add_torrent() + // determines whether or not the torrent's piece hashes + // are kept in memory after the torrent becomes a seed or not. If it is set to + // ``true`` the hashes are freed once the torrent is a seed (they're not + // needed anymore since the torrent won't download anything more). If it's set + // to false they are not freed. If they are freed, the torrent_info_ returned + // by get_torrent_info() will return an object that may be incomplete, that + // cannot be passed back to `async_add_torrent() add_torrent()`_ for instance. bool free_torrent_hashes; - // when this is true, the upnp port mapper will ignore - // any upnp devices that don't have an address that matches - // our currently configured router. + // indicates whether or not the UPnP implementation + // should ignore any broadcast response from a device whose address is not the + // configured router for this machine. i.e. it's a way to not talk to other + // people's routers by mistake. bool upnp_ignore_nonrouters; // This is the minimum send buffer target size (send buffer @@ -328,62 +395,122 @@ namespace libtorrent // at least fit a few blocks. This is essentially the initial // window size which will determine how fast we can ramp up // the send rate - int send_buffer_low_watermark; + int send_buffer_low_watermark; - // if the send buffer has fewer bytes than this, we'll - // read another 16kB block onto it. If set too small, - // upload rate capacity will suffer. If set too high, - // memory will be wasted. - // The actual watermark may be lower than this in case - // the upload rate is low, this is the upper limit. - int send_buffer_watermark; + // the upper limit of the send buffer low-watermark. + // + // if the send buffer has fewer bytes than this, we'll + // read another 16kB block onto it. If set too small, + // upload rate capacity will suffer. If set too high, + // memory will be wasted. + // The actual watermark may be lower than this in case + // the upload rate is low, this is the upper limit. + int send_buffer_watermark; // the current upload rate to a peer is multiplied by // this factor to get the send buffer watermark. The - // factor is specified as a percentage. i.e. 50 -> 0.5 + // factor is specified as a percentage. i.e. 50 indicates + // a factor of 0.5. + // // This product is clamped to the send_buffer_watermark // setting to not exceed the max. For high speed // upload, this should be set to a greater value than // 100. The default is 50. + // + // For high capacity connections, setting this + // higher can improve upload performance and disk throughput. Setting it too + // high may waste RAM and create a bias towards read jobs over write jobs. int send_buffer_watermark_factor; #ifndef TORRENT_NO_DEPRECATE // deprecated in 0.16 + // defaults to true. When true, if there is a global upload + // limit set and the current upload rate is less than 90% of that, another upload + // slot is opened. If the upload rate has been saturated for an extended period + // of time, on upload slot is closed. The number of upload slots will never be + // less than what has been set by ``session::set_max_uploads()``. To query the + // current number of upload slots, see ``session_status::allowed_upload_slots``. bool auto_upload_slots; + + // When set, and ``auto_upload_slots`` is set, + // the max upload slots setting is used as a minimum number of unchoked slots. + // This algorithm is designed to prevent the peer from spreading its upload + // capacity too thin, but still open more slots in order to utilize the full capacity. bool auto_upload_slots_rate_based; #endif enum choking_algorithm_t { + // the traditional choker with a fixed number of unchoke + // slots, as specified by session::set_max_uploads().. fixed_slots_choker, + + // opens at least the number of slots as specified by + // session::set_max_uploads() but opens up more slots if the upload capacity + // is not saturated. This unchoker will work just like the ``fixed_slot_choker`` + // if there's no global upload rate limit set. auto_expand_choker, + + // opens up unchoke slots based on the upload rate + // achieved to peers. The more slots that are opened, the marginal upload + // rate required to open up another slot increases. rate_based_choker, + // attempts to optimize download rate by finding the + // reciprocation rate of each peer individually and prefers peers that gives + // the highest *return on investment*. It still allocates all upload capacity, + // but shuffles it around to the best peers first. For this choker to be + // efficient, you need to set a global upload rate limit + // session_settings::upload_rate_limit. For more information about this + // choker, see the paper_. + // + // .. _paper: http://bittyrant.cs.washington.edu/#papers bittyrant_choker }; + // specifies which algorithm to use to determine which peers + // to unchoke. This setting replaces the deprecated settings ``auto_upload_slots`` + // and ``auto_upload_slots_rate_based``. For options, see choking_algorithm_t. int choking_algorithm; enum seed_choking_algorithm_t { + // round-robins the peers that are unchoked when seeding. This + // distributes the upload bandwidht uniformly and fairly. It minimizes the ability + // for a peer to download everything without redistributing it. round_robin, + + // unchokes the peers we can send to the fastest. This might be + // a bit more reliable in utilizing all available capacity. fastest_upload, + + // prioritizes peers who have just started or are just about to finish + // the download. The intention is to force peers in the middle of the download to + // trade with each other. anti_leech }; - // the choking algorithm to use for seeding torrents + // controls the seeding unchoke behavior. For options, see seed_choking_algorithm_t. int seed_choking_algorithm; - // if set to true, peers that participate in a failing - // piece is put in parole mode. i.e. They will only - // download whole pieces until they either fail or pass. - // they are taken out of parole mode as soon as they - // participate in a piece that passes. + // specifies if parole mode should be used. Parole mode means + // that peers that participate in pieces that fail the hash check are put in a mode + // where they are only allowed to download whole pieces. If the whole piece a peer + // in parole mode fails the hash check, it is banned. If a peer participates in a + // piece that passes the hash check, it is taken out of parole mode. bool use_parole_mode; - // the disk write cache, specified in 16 KiB blocks. - // default is 1024 (= 16 MiB). -1 means automatic, which - // adjusts the cache size depending on the amount - // of physical RAM in the machine. + // the disk write and read cache. It is specified in units of + // 16 KiB blocks. Buffers that are part of a peer's send or receive buffer also + // count against this limit. Send and receive buffers will never be denied to be + // allocated, but they will cause the actual cached blocks to be flushed or evicted. + // If this is set to -1, the cache size is automatically set to the amount + // of physical RAM available in the machine divided by 8. If the amount of physical + // RAM cannot be determined, it's set to 1024 (= 16 MiB). + // + // Disk buffers are allocated using a pool allocator, the number of blocks that + // are allocated at a time when the pool needs to grow can be specified in + // ``cache_buffer_chunk_size``. This defaults to 16 blocks. Lower numbers + // saves memory at the expense of more heap allocations. It must be at least 1. int cache_size; // this is the number of disk buffer blocks (16 kiB) @@ -394,57 +521,118 @@ namespace libtorrent // the number of seconds a write cache entry sits // idle in the cache before it's forcefully flushed - // to disk. Default is 5 minutes. + // to disk. int cache_expiry; - // when true, the disk I/O thread uses the disk - // cache for caching blocks read from disk too + // when set to true (default), the disk cache is also used to + // cache pieces read from disk. Blocks for writing pieces takes presedence. bool use_read_cache; - // don't implicitly cache pieces in the read cache, - // only cache pieces that are explicitly asked to be - // cached. + // defaults to 0. If set to something greater than 0, the + // disk read cache will not be evicted by cache misses and will explicitly be + // controlled based on the rarity of pieces. Rare pieces are more likely to be + // cached. This would typically be used together with ``suggest_mode`` set to + // ``suggest_read_cache``. The value is the number of pieces to keep in the read + // cache. If the actual read cache can't fit as many, it will essentially be clamped. bool explicit_read_cache; - // the number of seconds between refreshes of - // explicit caches + // the number of seconds in between each refresh of + // a part of the explicit read cache. Torrents take turns in refreshing and this + // is the time in between each torrent refresh. Refreshing a torrent's explicit + // read cache means scanning all pieces and picking a random set of the rarest ones. + // There is an affinity to pick pieces that are already in the cache, so that + // subsequent refreshes only swaps in pieces that are rarer than whatever is in + // the cache at the time. int explicit_cache_interval; enum io_buffer_mode_t { + // This is the default and files are opened normally, with the OS caching + // reads and writes. enable_os_cache = 0, + // This will open files in unbuffered mode for files where every read and + // write would be sector aligned. Using aligned disk offsets is a requirement + // on some operating systems. disable_os_cache_for_aligned_files = 1, + // This opens all files in unbuffered mode (if allowed by the operating system). + // Linux and Windows, for instance, require disk offsets to be sector aligned, + // and in those cases, this option is the same as ``disable_os_caches_for_aligned_files``. disable_os_cache = 2 }; + + // determines how files are + // opened when they're in read only mode versus read and write mode. For options, + // see io_buffer_mode_t. + // + // One reason to disable caching is that it may help the operating system from growing + // its file cache indefinitely. Since some OSes only allow aligned files to be opened + // in unbuffered mode, It is recommended to make the largest file in a torrent the first + // file (with offset 0) or use pad files to align all files to piece boundries. int disk_io_write_mode; int disk_io_read_mode; bool coalesce_reads; bool coalesce_writes; - // if != (0, 0), this is the range of ports that - // outgoing connections will be bound to. This - // is useful for users that have routers that - // allow QoS settings based on local port. + // if set to something other than (0, 0) is a range of ports + // used to bind outgoing sockets to. This may be useful for users whose router + // allows them to assign QoS classes to traffic based on its local port. It is + // a range instead of a single port because of the problems with failing to reconnect + // to peers if a previous socket to that peer and port is in ``TIME_WAIT`` state. + // + //.. warning:: setting outgoing ports will limit the ability to keep multiple + // connections to the same client, even for different torrents. It is not + // recommended to change this setting. Its main purpose is to use as an + // escape hatch for cheap routers with QoS capability but can only classify + // flows based on port numbers. std::pair outgoing_ports; - // the TOS byte of all peer traffic (including - // web seeds) is set to this value. The default - // is the QBSS scavenger service - // http://qbone.internet2.edu/qbss/ - // For unmarked packets, set to 0 + // determines the TOS byte set in the IP header of every packet + // sent to peers (including web seeds). The default value for this is ``0x0`` + // (no marking). One potentially useful TOS mark is ``0x20``, this represents + // the *QBone scavenger service*. For more details, see QBSS_. + // + // .. _`QBSS`: http://qbone.internet2.edu/qbss/ char peer_tos; // for auto managed torrents, these are the limits // they are subject to. If there are too many torrents // some of the auto managed ones will be paused until // some slots free up. - // active_dht_limit and active_tracker_limit limits the + // + // ``active_dht_limit`` and ``active_tracker_limit`` limits the // number of torrents that will be active on the DHT - // versus the tracker. If the active limit is set higher + // and their tracker. If the active limit is set higher // than these numbers, some torrents will be "active" in // the sense that they will accept incoming connections, - // but not announce on the DHT or the tracker + // but not announce on the DHT or their trackers. + // + // ``active_lsd_limit`` is the max number of torrents to announce to the local network + // over the local service discovery protocol. By default this is 80, which is no more + // than one announce every 5 seconds (assuming the default announce interval of 5 minutes). + // + // ``active_limit`` is a hard limit on the number of active torrents. This applies even to + // slow torrents. + // + // You can have more torrents *active*, even though they are not announced to the DHT, + // lsd or their tracker. If some peer knows about you for any reason and tries to connect, + // it will still be accepted, unless the torrent is paused, which means it won't accept + // any connections. + // + // ``active_downloads`` and ``active_seeds`` controls how many active seeding and + // downloading torrents the queuing mechanism allows. The target number of active + // torrents is ``min(active_downloads + active_seeds, active_limit)``. + // ``active_downloads`` and ``active_seeds`` are upper limits on the number of + // downloading torrents and seeding torrents respectively. Setting the value to + // -1 means unlimited. + // + // For example if there are 10 seeding torrents and 10 downloading torrents, and + // ``active_downloads`` is 4 and ``active_seeds`` is 4, there will be 4 seeds + // active and 4 downloading torrents. If the settings are ``active_downloads`` = 2 + // and ``active_seeds`` = 4, then there will be 2 downloading torrents and 4 seeding + // torrents active. Torrents that are not auto managed are also counted against these + // limits. If there are non-auto managed torrents that use up all the slots, no + // auto managed torrent will be activated. int active_downloads; int active_seeds; int active_dht_limit; @@ -457,9 +645,10 @@ namespace libtorrent // downloading torrents bool auto_manage_prefer_seeds; - // if this is true, torrents that don't have any significant - // transfers are not counted as active when determining which - // auto managed torrents to pause and resume + // if true, torrents without any payload transfers are + // not subject to the ``active_seeds`` and ``active_downloads`` limits. This is intended + // to make it more likely to utilize all available bandwidth, and avoid having torrents + // that don't transfer anything block the active slots. bool dont_count_slow_torrents; // the number of seconds in between recalculating which @@ -474,56 +663,81 @@ namespace libtorrent // the default value for share ratio is 2 // the default seed time ratio is 7, because that's a common // asymmetry ratio on connections + // + //.. note:: + // This is an out-dated option that doesn't make much sense. + // It will be removed in future versions of libtorrent float share_ratio_limit; + + // the seeding time / downloading time ratio limit + // for considering a seeding torrent to have met the seed limit criteria. See queuing_. float seed_time_ratio_limit; + + // the limit on the time a torrent has been an active seed + // (specified in seconds) before it is considered having met the seed limit criteria. + // See queuing_. int seed_time_limit; - // the interval (in seconds) between optimistic disconnects - // if the disconnects happen and how many peers are disconnected - // is controlled by peer_turnover and peer_turnover_cutoff + // controls a feature where libtorrent periodically can disconnect + // the least useful peers in the hope of connecting to better ones. ``peer_turnover_interval`` controls + // the interval of this optimistic disconnect. It defaults to every 5 minutes, and + // is specified in seconds. + // + // ``peer_turnover`` Is the fraction of the peers that are disconnected. This is + // a float where 1.f represents all peers an 0 represents no peers. It defaults to + // 4% (i.e. 0.04f) + // + // ``peer_turnover_cutoff`` is the cut off trigger for optimistic unchokes. If a torrent + // has more than this fraction of its connection limit, the optimistic unchoke is + // triggered. This defaults to 90% (i.e. 0.9f). int peer_turnover_interval; - - // the percentage of peers to disconnect every - // turnoever interval (if we're at the peer limit) - // defaults to 2/50:th float peer_turnover; - - // when we are connected to more than - // limit * peer_turnover_cutoff peers - // disconnect peer_turnover fraction - // of the peers float peer_turnover_cutoff; - // if this is true (default) connections where both - // ends have no utility in keeping the connection open - // are closed. for instance if both ends have completed - // their downloads + // specifies whether libtorrent should close + // connections where both ends have no utility in keeping the connection open. + // For instance if both ends have completed their downloads, there's no point + // in keeping it open. This defaults to ``true``. bool close_redundant_connections; // the number of seconds between scrapes of - // queued torrents (auto managed and paused) + // queued torrents (auto managed and paused torrents). Auto managed + // torrents that are paused, are scraped regularly in order to keep + // track of their downloader/seed ratio. This ratio is used to determine + // which torrents to seed and which to pause. int auto_scrape_interval; // the minimum number of seconds between any - // automatic scrape (regardless of torrent) + // automatic scrape (regardless of torrent). In case there are a large number + // of paused auto managed torrents, this puts a limit on how often a scrape + // request is sent. int auto_scrape_min_interval; - // the max number of peers in the peer list - // per torrent. This is the peers we know - // about, not necessarily connected to. + // the maximum number of peers in the list of + // known peers. These peers are not necessarily connected, so this number + // should be much greater than the maximum number of connected peers. + // Peers are evicted from the cache when the list grows passed 90% of + // this limit, and once the size hits the limit, peers are no longer + // added to the list. If this limit is set to 0, there is no limit on + // how many peers we'll keep in the peer list. int max_peerlist_size; - // when a torrent is paused, this is the max peer - // list size that's used + // the max peer list size used for torrents + // that are paused. This default to the same as ``max_peerlist_size``, but + // can be used to save memory for paused torrents, since it's not as + // important for them to keep a large peer list. int max_paused_peerlist_size; - // any announce intervals reported from a tracker - // that is lower than this, will be clamped to this - // value. It's specified in seconds + // the minimum allowed announce interval + // for a tracker. This is specified in seconds, defaults to 5 minutes and + // is used as a sanity check on what is returned from a tracker. It + // mitigates hammering misconfigured trackers. int min_announce_interval; - // if true, partial pieces are picked before pieces - // that are more rare + // If true, partial pieces are picked + // before pieces that are more rare. If false, rare pieces are always + // prioritized, unless the number of partial pieces is growing out of + // proportion. bool prioritize_partial_pieces; // the number of seconds a torrent is considered @@ -539,81 +753,122 @@ namespace libtorrent // the limits with the total traffic bool rate_limit_ip_overhead; - // this announces to all trackers within the current - // tier. Trackers within a tier are supposed to share - // peers, this could be used for trackers that don't, - // and require the clients to announce to all of them. + // controls how multi tracker torrents are + // treated. If this is set to true, all trackers in the same tier are + // announced to in parallel. If all trackers in tier 0 fails, all trackers + // in tier 1 are announced as well. If it's set to false, the behavior is as + // defined by the multi tracker specification. It defaults to false, which + // is the same behavior previous versions of libtorrent has had as well. bool announce_to_all_trackers; - // if set to true, multi tracker torrents are treated - // the same way uTorrent treats them. It defaults to - // false in order to comply with the extension definition. - // When this is enabled, one tracker from each tier is - // announced + // controls how multi tracker torrents are + // treated. When this is set to true, one tracker from each tier is announced + // to. This is the uTorrent behavior. This is false by default in order + // to comply with the multi-tracker specification. bool announce_to_all_tiers; - // when this is set to true, if there is a tracker entry - // with udp:// protocol, it is preferred over the same - // tracker over http://. + // true by default. It means that trackers may + // be rearranged in a way that udp trackers are always tried before http + // trackers for the same hostname. Setting this to fails means that the + // trackers' tier is respected and there's no preference of one protocol + // over another. bool prefer_udp_trackers; - // when set to true, a piece has to have been forwarded - // to a third peer before another one is handed out + // when this is set to true, a piece has to + // have been forwarded to a third peer before another one is handed out. + // This is the traditional definition of super seeding. bool strict_super_seeding; - // the number of pieces to send to each peer when seeding - // before rotating to a new peer + // the number of pieces to send to a peer, + // when seeding, before rotating in another peer to the unchoke set. + // It defaults to 3 pieces, which means that when seeding, any peer we've + // sent more than this number of pieces to will be unchoked in favour of + // a choked peer. int seeding_piece_quota; - // the maximum number of sparse regions before starting - // to prioritize pieces close to other pieces (to maintain - // the number of sparse regions). This is set to 30000 on - // windows because windows vista has a new limit on the - // numbers of sparse regions one file may have - // if it is set to 0 this behavior is disabled - // this is a hack to avoid a terrible bug on windows - // don't use unless you have to, it screws with rarest-first - // piece selection, and reduces swarm performance + // is a limit of the number of *sparse regions* in + // a torrent. A sparse region is defined as a hole of pieces we have not + // yet downloaded, in between pieces that have been downloaded. This is + // used as a hack for windows vista which has a bug where you cannot + // write files with more than a certain number of sparse regions. This + // limit is not hard, it will be exceeded. Once it's exceeded, pieces + // that will maintain or decrease the number of sparse regions are + // prioritized. To disable this functionality, set this to 0. It defaults + // to 0 on all platforms except windows. int max_sparse_regions; #ifndef TORRENT_DISABLE_MLOCK - // if this is set to true, the memory allocated for the - // disk cache will be locked in physical RAM, never to - // be swapped out + // if lock disk cache is set to true the disk cache + // that's in use, will be locked in physical memory, preventing it from + // being swapped out. bool lock_disk_cache; #endif - // the number of times to reject requests while being - // choked before disconnecting a peer for being malicious + // the number of piece requests we will reject in a row + // while a peer is choked before the peer is considered abusive and is + // disconnected. int max_rejects; - // sets the socket send and receive buffer sizes - // 0 means OS default + // specifies + // the buffer sizes set on peer sockets. 0 (which is the default) means + // the OS default (i.e. don't change the buffer sizes). The socket buffer + // sizes are changed using setsockopt() with SOL_SOCKET/SO_RCVBUF and + // SO_SNDBUFFER. int recv_socket_buffer_size; int send_socket_buffer_size; - // if this is set to false, the hashing will be - // optimized for memory usage instead of the - // number of read operations + // chooses between two ways of reading back + // piece data from disk when its complete and needs to be verified against + // the piece hash. This happens if some blocks were flushed to the disk + // out of order. Everything that is flushed in order is hashed as it goes + // along. Optimizing for speed will allocate space to fit all the the + // remaingin, unhashed, part of the piece, reads the data into it in a single + // call and hashes it. This is the default. If ``optimizing_hashing_for_speed`` + // is false, a single block will be allocated (16 kB), and the unhashed parts + // of the piece are read, one at a time, and hashed in this single block. This + // is appropriate on systems that are memory constrained. bool optimize_hashing_for_speed; - // if > 0, file checks will have a short - // delay between disk operations, to make it - // less intrusive on the system as a whole - // blocking the disk. This delay is specified - // in milliseconds and the delay will be this - // long per 16kiB block - // the default of 10 ms/16kiB will limit - // the checking rate to 1.6 MiB per second + // the number of milliseconds to sleep + // in between disk read operations when checking torrents. This defaults + // to 0, but can be set to higher numbers to slow down the rate at which + // data is read from the disk while checking. This may be useful for + // background tasks that doesn't matter if they take a bit longer, as long + // as they leave disk I/O time for other processes. int file_checks_delay_per_block; enum disk_cache_algo_t - { lru, largest_contiguous, avoid_readback }; + { + // This + // flushes the entire piece, in the write cache, that was least recently + // written to. + lru, + // will flush the largest + // sequences of contiguous blocks from the write cache, regarless of the + // piece's last use time. + largest_contiguous, + + // will prioritize + // flushing blocks that will avoid having to read them back in to verify + // the hash of the piece once it's done. This is especially useful for high + // throughput setups, where reading from the disk is especially expensive. + avoid_readback + }; + + // tells the disk I/O thread which cache flush + // algorithm to use. The default algorithm is largest_contiguous. This is + // specified by the disk_cache_algo_t enum. disk_cache_algo_t disk_cache_algorithm; - // the number of blocks that will be read ahead - // when reading a block into the read cache + // the number of blocks to read into the read + // cache when a read cache miss occurs. Setting this to 0 is essentially + // the same thing as disabling read cache. The number of blocks read + // into the read cache is always capped by the piece boundry. + // + // When a piece in the write cache has ``write_cache_line_size`` contiguous + // blocks in it, they will be flushed. Setting this to 1 effectively + // disables the write cache. int read_cache_line_size; // whenever a contiguous range of this many @@ -621,16 +876,21 @@ namespace libtorrent // is flushed immediately int write_cache_line_size; - // this is the number of seconds a disk failure - // occurs until libtorrent will re-try. + // the number of seconds from a disk write + // errors occur on a torrent until libtorrent will take it out of the + // upload mode, to test if the error condition has been fixed. + // + // libtorrent will only do this automatically for auto managed torrents. + // + // You can explicitly take a torrent out of upload only mode using + // set_upload_mode(). int optimistic_disk_retry; - // when set to true, all data downloaded from - // peers will be assumed to be correct, and not - // tested to match the hashes in the torrent - // this is only useful for simulation and - // testing purposes (typically combined with - // disabled_storage) + // controls if downloaded pieces are verified against + // the piece hashes in the torrent file or not. The default is false, i.e. + // to verify all downloaded data. It may be useful to turn this off for performance + // profiling and simulation scenarios. Do not disable the hash check for regular + // bittorrent clients. bool disable_hash_checks; // if this is true, disk read operations may @@ -652,82 +912,112 @@ namespace libtorrent // be able to connect to i2p peers. bool allow_i2p_mixed; - // the max number of pieces that a peer can - // suggest to use before we start dropping - // previous suggested piece + // the max number of suggested piece indices received + // from a peer that's remembered. If a peer floods suggest messages, this limit + // prevents libtorrent from using too much RAM. It defaults to 10. int max_suggest_pieces; - // if set to true, requests that have have not been - // satisfied after the equivalence of the entire - // request queue has been received, will be considered lost + // If set to true (it defaults to false), piece + // requests that have been skipped enough times when piece messages + // are received, will be considered lost. Requests are considered skipped + // when the returned piece messages are re-ordered compared to the order + // of the requests. This was an attempt to get out of dead-locks caused by + // BitComet peers silently ignoring some requests. It may cause problems + // at high rates, and high level of reordering in the uploading peer, that's + // why it's disabled by default. bool drop_skipped_requests; - // if this is set to true, the disk I/O will be - // run at lower-than-normal priority. This is - // intended to make the machine more responsive - // to foreground tasks, while bittorrent runs - // in the background + // determines if the disk I/O should use a normal + // or low priority policy. This defaults to true, which means that + // it's low priority by default. Other processes doing disk I/O will + // normally take priority in this mode. This is meant to improve the + // overall responsiveness of the system while downloading in the + // background. For high-performance server setups, this might not + // be desirable. bool low_prio_disk; - // number of seconds between local service announces for - // torrents. Defaults to 5 minutes + // the time between local + // network announces for a torrent. By default, when local service + // discovery is enabled a torrent announces itself every 5 minutes. + // This interval is specified in seconds. int local_service_announce_interval; - // number of seconds between DHT announces for - // torrents. Defaults to 15 minutes + // the number of seconds between announcing + // torrents to the distributed hash table (DHT). This is specified to + // be 15 minutes which is its default. int dht_announce_interval; - // the number of seconds a connection ID received - // from a UDP tracker is valid for. This is specified - // as 60 seconds + // the number of seconds libtorrent + // will keep UDP tracker connection tokens around for. This is specified + // to be 60 seconds, and defaults to that. The higher this value is, the + // fewer packets have to be sent to the UDP tracker. In order for higher + // values to work, the tracker needs to be configured to match the + // expiration time for tokens. int udp_tracker_token_expiry; - // if this is set to true, any block read from the - // disk cache will be dropped from the cache immediately - // following. This may be useful if the block is not - // expected to be hit again. It would save some memory + // if this is set to true, read cache blocks + // that are hit by peer read requests are removed from the disk cache + // to free up more space. This is useful if you don't expect the disk + // cache to create any cache hits from other peers than the one who + // triggered the cache line to be read into the cache in the first place. bool volatile_read_cache; - // if this is set to true, the size of the cache line - // generated by a particular read request depends on the - // rate you're sending to that peer. This optimizes the - // memory usage of the disk read cache by reading - // further ahead for peers that you're uploading at high - // rates to + // enables the disk cache to adjust the size + // of a cache line generated by peers to depend on the upload rate + // you are sending to that peer. The intention is to optimize the RAM + // usage of the cache, to read ahead further for peers that you're + // sending faster to. bool guided_read_cache; - // this is the default minimum time any read cache line - // is kept in the cache. + // the minimum number of seconds any read + // cache line is kept in the cache. This defaults to one second but + // may be greater if ``guided_read_cache`` is enabled. Having a lower + // bound on the time a cache line stays in the cache is an attempt + // to avoid swapping the same pieces in and out of the cache in case + // there is a shortage of spare cache space. int default_cache_min_age; - // the global number of optimistic unchokes - // 0 means automatic + // the number of optimistic unchoke + // slots to use. It defaults to 0, which means automatic. Having a higher + // number of optimistic unchoke slots mean you will find the good peers + // faster but with the trade-off to use up more bandwidth. When this is + // set to 0, libtorrent opens up 20% of your allowed upload slots as + // optimistic unchoke slots. int num_optimistic_unchoke_slots; - // if set to true, files won't have their atime updated - // on disk reads. This works on linux + // this is a linux-only option and passes in the + // ``O_NOATIME`` to ``open()`` when opening files. This may lead to + // some disk performance improvements. bool no_atime_storage; - // === BitTyrant unchoker settings == - - // when using BitTyrant choker, this is the default - // assumed reciprocation rate. This is where each peer starts + // the assumed reciprocation rate + // from peers when using the BitTyrant choker. This defaults to 14 kiB/s. + // If set too high, you will over-estimate your peers and be more altruistic + // while finding the true reciprocation rate, if it's set too low, you'll + // be too stingy and waste finding the true reciprocation rate. int default_est_reciprocation_rate; - // this is the increase of the estimated reciprocation rate - // in percent. We increase by this amount once every unchoke - // interval that we are choked by the other peer and we have - // unchoked them + // specifies how many percent the + // extimated reciprocation rate should be increased by each unchoke + // interval a peer is still choking us back. This defaults to 20%. + // This only applies to the BitTyrant choker. int increase_est_reciprocation_rate; - // each unchoke interval that we stay unchoked by the other - // peer, and we have unchoked this peer as well, we decrease - // our estimate of the reciprocation rate, since we might have - // over-estimated it + // specifies how many percent the + // estimated reciprocation rate should be decreased by each unchoke + // interval a peer unchokes us. This default to 3%. + // This only applies to the BitTyrant choker. int decrease_est_reciprocation_rate; - // if set to true, an incoming connection to a torrent that's - // paused and auto-managed will make the torrent start. + // defaults to false. If a torrent + // has been paused by the auto managed feature in libtorrent, i.e. + // the torrent is paused and auto managed, this feature affects whether + // or not it is automatically started on an incoming connection. The + // main reason to queue torrents, is not to make them unavailable, but + // to save on the overhead of announcing to the trackers, the DHT and to + // avoid spreading one's unchoke slots too thin. If a peer managed to + // find us, even though we're no in the torrent anymore, this setting + // can make us start the torrent and serve it. bool incoming_starts_queued_torrents; // when set to true, the downloaded counter sent to trackers @@ -736,26 +1026,30 @@ namespace libtorrent // any redundany bytes bool report_true_downloaded; - // if set to true, libtorrent won't request a piece multiple times - // until every piece is requested + // defaults to true, and controls when a block + // may be requested twice. If this is ``true``, a block may only be requested + // twice when there's ay least one request to every piece that's left to + // download in the torrent. This may slow down progress on some pieces + // sometimes, but it may also avoid downloading a lot of redundant bytes. + // If this is ``false``, libtorrent attempts to use each peer connection + // to its max, by always requesting something, even if it means requesting + // something that has been requested from another peer already. bool strict_end_game_mode; - // if this is true, the broadcast socket will not only use IP multicast - // but also send the messages on the broadcast address. This is false by - // default in order to avoid flooding networks for no good reason. If - // a network is known not to support multicast, this can be enabled + // if set to true, the local peer discovery + // (or Local Service Discovery) will not only use IP multicast, but also + // broadcast its messages. This can be useful when running on networks + // that don't support multicast. Since broadcast messages might be + // expensive and disruptive on networks, only every 8th announce uses + // broadcast. bool broadcast_lsd; - // when set to true, libtorrent will try to make outgoing utp connections + // these all determines if libtorrent should attempt to make + // outgoing connections of the specific type, or allow incoming connection. By + // default all of them are enabled. bool enable_outgoing_utp; - - // if set to false, libtorrent will reject incoming utp connections bool enable_incoming_utp; - - // when set to false, no outgoing TCP connections will be made bool enable_outgoing_tcp; - - // if set to false, libtorrent will reject incoming tcp connections bool enable_incoming_tcp; // the max number of peers we accept from pex messages from a single peer. @@ -764,97 +1058,144 @@ namespace libtorrent // ignore any peer that exceeds this limit int max_pex_peers; - // when set to true, the file modification time is ignored when loading - // resume data. The resume data includes the expected timestamp of each - // file and is typically compared to make sure the files haven't changed - // since the last session + // determines if the storage, when loading + // resume data files, should verify that the file modification time + // with the timestamps in the resume data. This defaults to false, which + // means timestamps are taken into account, and resume data is less likely + // to accepted (torrents are more likely to be fully checked when loaded). + // It might be useful to set this to true if your network is faster than your + // disk, and it would be faster to redownload potentially missed pieces than + // to go through the whole storage to look for them. bool ignore_resume_timestamps; - // normally, if a resume file is incomplete (typically there's no - // "file sizes" field) the torrent is queued for a full check. If - // this settings is set to true, instead libtorrent will assume - // we have none of the files and go straight to download + // determines if the storage should check + // the whole files when resume data is incomplete or missing or whether + // it should simply assume we don't have any of the data. By default, this + // is determined by the existance of any of the files. By setting this setting + // to true, the files won't be checked, but will go straight to download + // mode. bool no_recheck_incomplete_resume; - // when this is true, libtorrent will take actions to make sure no - // privacy sensitive information is leaked out from the client. - // With this option, your IP address will not be exposed over - // the wire protocol. Other measures will also be taken to make it - // harder to track you. + // defaults to false. When set to true, the client tries + // to hide its identity to a certain degree. The peer-ID will no longer + // include the client's fingerprint. The user-agent will be reset to an + // empty string. It will also try to not leak other identifying information, + // such as your local listen port, your IP etc. + // + // If you're using I2P, a VPN or a proxy, it might make sense to enable anonymous mode. bool anonymous_mode; - // when this is true, no connection will ever be made without going - // through a proxy. If you set up a proxy and prefer connections not - // supported by the proxy to fail, rather than circumventing it, set - // this to true. For instance, reverse DNS lookups can rarely be - // made via a proxy, so resolving peer countries is disabled with - // this switch. + // disables any communication that's not going over a proxy. + // Enabling this requires a proxy to be configured as well, see ``set_proxy_settings``. + // The listen sockets are closed, and incoming connections will + // only be accepted through a SOCKS5 or I2P proxy (if a peer proxy is set up and + // is run on the same machine as the tracker proxy). This setting also + // disabled peer country lookups, since those are done via DNS lookups that + // aren't supported by proxies. bool force_proxy; - // the number of milliseconds between internal ticks. Should be no - // more than one second (i.e. 1000). + // specifies the number of milliseconds between internal + // ticks. This is the frequency with which bandwidth quota is distributed to + // peers. It should not be more than one second (i.e. 1000 ms). Setting this + // to a low value (around 100) means higher resolution bandwidth quota distribution, + // setting it to a higher value saves CPU cycles. int tick_interval; // specifies whether downloads from web seeds is reported to the // tracker or not. Defaults to on bool report_web_seed_downloads; - // this is the target share ratio for share-mode torrents + // specifies the target share ratio for share mode torrents. + // This defaults to 3, meaning we'll try to upload 3 times as much as we download. + // Setting this very high, will make it very conservative and you might end up + // not downloading anything ever (and not affecting your share ratio). It does + // not make any sense to set this any lower than 2. For instance, if only 3 peers + // need to download the rarest piece, it's impossible to download a single piece + // and upload it more than 3 times. If the share_mode_target is set to more than 3, + // nothing is downloaded. int share_mode_target; - // max upload rate in bytes per second for the session + // sets the session-global limits of upload + // and download rate limits, in bytes per second. The local rates refer to peers + // on the local network. By default peers on the local network are not rate limited. + // + // These rate limits are only used for local peers (peers within the same subnet as + // the client itself) and it is only used when ``session_settings::ignore_limits_on_local_network`` + // is set to true (which it is by default). These rate limits default to unthrottled, + // but can be useful in case you want to treat local peers preferentially, but not + // quite unthrottled. + // + // A value of 0 means unlimited. int upload_rate_limit; - - // max download rate in bytes per second for the session int download_rate_limit; - - // max upload rate in bytes per second for peers on the local - // network, in the session int local_upload_rate_limit; - - // max download rate in bytes per second for peers on the local - // network, in the session int local_download_rate_limit; - // max upload rate used by the DHT in bytes per second + // sets the rate limit on the DHT. This is specified in + // bytes per second and defaults to 4000. For busy boxes with lots of torrents + // that requires more DHT traffic, this should be raised. int dht_upload_rate_limit; - // the max number of unchoke slots in the session (might be - // overridden by unchoke algorithm) + // the max number of unchoked peers in the session. The + // number of unchoke slots may be ignored depending on what ``choking_algorithm`` + // is set to. A value of -1 means infinite. int unchoke_slots_limit; - // the max number of half-open TCP connections + // sets the maximum number of half-open connections + // libtorrent will have when connecting to peers. A half-open connection is one + // where connect() has been called, but the connection still hasn't been established + // (nor failed). Windows XP Service Pack 2 sets a default, system wide, limit of + // the number of half-open connections to 10. So, this limit can be used to work + // nicer together with other network applications on that system. The default is + // to have no limit, and passing -1 as the limit, means to have no limit. When + // limiting the number of simultaneous connection attempts, peers will be put in + // a queue waiting for their turn to get connected. int half_open_limit; - // the max number of connections in the session + // sets a global limit on the number of connections + // opened. The number of connections is set to a hard minimum of at least two per + // torrent, so if you set a too low connections limit, and open too many torrents, + // the limit will not be met. int connections_limit; // the number of extra incoming connections allowed // temporarily, in order to support replacing peers int connections_slack; - // target delay, milliseconds + // the target delay for uTP sockets in milliseconds. A high + // value will make uTP connections more aggressive and cause longer queues in the upload + // bottleneck. It cannot be too low, since the noise in the measurements would cause + // it to send too slow. The default is 50 milliseconds. int utp_target_delay; - // max number of bytes to increase cwnd per rtt in uTP - // congestion controller + // the number of bytes the uTP congestion window can increase + // at the most in one RTT. This defaults to 300 bytes. If this is set too high, + // the congestion controller reacts too hard to noise and will not be stable, if it's + // set too low, it will react slow to congestion and not back off as fast. int utp_gain_factor; - // the shortest allowed uTP connection timeout in milliseconds - // defaults to 500 milliseconds. The shorter timeout, the - // faster the connection recovers from a loss of an entire window + // the shortest allowed uTP socket timeout, specified in milliseconds. + // This defaults to 500 milliseconds. The timeout depends on the RTT of the connection, but + // is never smaller than this value. A connection times out when every packet in a window + // is lost, or when a packet is lost twice in a row (i.e. the resent packet is lost as well). + // + // The shorter the timeout is, the faster the connection will recover from this situation, + // assuming the RTT is low enough. int utp_min_timeout; - // the number of SYN packets that are sent before giving up + // the number of SYN packets that are sent (and timed out) before + // giving up and closing the socket. int utp_syn_resends; // the number of resent packets sent on a closed socket before giving up int utp_fin_resends; - // the number of times to send a packet before giving up + // the number of times a packet is sent (and lossed or timed out) + // before giving up and closing the connection. int utp_num_resends; - // initial timeout for uTP SYN packets + // the number of milliseconds of timeout for the initial SYN + // packet for uTP connections. For each timed out packet (in a row), the timeout is doubled. int utp_connect_timeout; #ifndef TORRENT_NO_DEPRECATE @@ -862,15 +1203,18 @@ namespace libtorrent int utp_delayed_ack; #endif - // set to true if the uTP socket buffer size is allowed to increase - // dynamically based on the NIC MTU setting. This is true by default - // and improves uTP performance for networks with larger frame sizes - // including loopback + // controls if the uTP socket manager is allowed to increase + // the socket buffer if a network interface with a large MTU is used (such as loopback + // or ethernet jumbo frames). This defaults to true and might improve uTP throughput. + // For RAM constrained systems, disabling this typically saves around 30kB in user space + // and probably around 400kB in kernel socket buffers (it adjusts the send and receive + // buffer size on the kernel socket, both for IPv4 and IPv6). bool utp_dynamic_sock_buf; - // what to multiply the congestion window by on packet loss. - // it's specified as a percent. The default is 50, i.e. cut - // in half + // controls how the congestion window is changed when a packet + // loss is experienced. It's specified as a percentage multiplier for ``cwnd``. By default + // it's set to 50 (i.e. cut in half). Do not change this value unless you know what + // you're doing. Never set it higher than 100. int utp_loss_multiplier; enum bandwidth_mixed_algo_t @@ -883,102 +1227,146 @@ namespace libtorrent peer_proportional = 1 }; - // the algorithm to use to balance bandwidth between tcp - // connections and uTP connections + + // determines how to treat TCP connections when there are + // uTP connections. Since uTP is designed to yield to TCP, there's an inherent problem + // when using swarms that have both TCP and uTP connections. If nothing is done, uTP + // connections would often be starved out for bandwidth by the TCP connections. This mode + // is ``prefer_tcp``. The ``peer_proportional`` mode simply looks at the current throughput + // and rate limits all TCP connections to their proportional share based on how many of + // the connections are TCP. This works best if uTP connections are not rate limited by + // the global rate limiter (which they aren't by default). + // + // see bandwidth_mixed_algo_t for options. int mixed_mode_algorithm; - // set to true if uTP connections should be rate limited - // defaults to false + // determines if uTP connections should be throttled by the global rate + // limiter or not. By default they are. bool rate_limit_utp; - // this is the number passed in to listen(). i.e. - // the number of connections to accept while we're - // not waiting in an accept() call. + // the value passed in to listen() for the listen socket. + // It is the number of outstanding incoming connections to queue up while we're not + // actively waiting for a connection to be accepted. The default is 5 which should + // be sufficient for any normal client. If this is a high performance server which + // expects to receive a lot of connections, or used in a simulator or test, it + // might make sense to raise this number. It will not take affect until listen_on() + // is called again (or for the first time). int listen_queue_size; - // if this is true, the &ip= argument in tracker requests - // (unless otherwise specified) will be set to the intermediate - // IP address if the user is double NATed. If ther user is not - // double NATed, this option does not have an affect + // if true, the ``&ip=`` argument in tracker requests + // (unless otherwise specified) will be set to the intermediate IP address, if the + // user is double NATed. If ther user is not double NATed, this option has no affect. bool announce_double_nat; - // the first tracker response after a torrent is started - // will cause this many connections to be made immediately. - // instead of waiting for the connection scheduler which - // triggeres every second + // the number of peers to try to connect to immediately + // when the first tracker response is received for a torrent. This is a boost to + // given to new torrents to accelerate them starting up. The normal connect scheduler + // is run once every second, this allows peers to be connected immediately instead + // of waiting for the session tick to trigger connections. int torrent_connect_boost; - // this controls whether or not seeding (and complete) torrents - // attempt to make outgoing connections or not. It defaults to - // true, but can be set to zero for specific applications where - // making outgoing connections is costly and known to not - // add any benefits + // determines if seeding (and finished) torrents + // should attempt to make outgoing connections or not. By default this is true. It + // may be set to false in very specific applications where the cost of making + // outgoing connections is high, and there are no or small benefits of doing so. + // For instance, if no nodes are behind a firewall or a NAT, seeds don't need to + // make outgoing connections. bool seeding_outgoing_connections; - // when this is true, libtorrent will not attempt to make outgoing - // connections to peers whose port is < 1024. This is a safety - // precaution to avoid being part of a DDoS attack + // if true (which is the default), libtorrent + // will not connect to any peers on priviliged ports (<= 1023). This can mitigate + // using bittorrent swarms for certain DDoS attacks. bool no_connect_privileged_ports; - // the max alert queue size + // the maximum number of alerts queued up internally. If + // alerts are not popped, the queue will eventually fill up to this level. This + // defaults to 1000. int alert_queue_size; - // the max allowed size for metadata received by the - // ut_metadata extension (i.e. magnet links) + // the maximum allowed size (in bytes) to be received + // by the metadata extension, i.e. magnet links. It defaults to 1 MiB. int max_metadata_size; - // attempt to smooth out connects to avoid getting spikes in - // opening connections and timing out connections + // true by default, which means the number of connection + // attempts per second may be limited to below the ``connection_speed``, in case + // we're close to bump up against the limit of number of connections. The intention + // of this setting is to more evenly distribute our connection attempts over time, + // instead of attempting to connectin in batches, and timing them out in batches. bool smooth_connects; - // always send user-agent + // defaults to false. When set to true, web connections + // will include a user-agent with every request, as opposed to just the first + // request in a connection. bool always_send_user_agent; - // if true, trackers will also be filtered by the IP - // filter, otherwise they are exempt + // defaults to true. It determines whether the + // IP filter applies to trackers as well as peers. If this is set to false, + // trackers are exempt from the IP filter (if there is one). If no IP filter + // is set, this setting is irrelevant. bool apply_ip_filter_to_trackers; - // to avoid write jobs starving read jobs, if this many - // write jobs have been taking priority in a row, service - // one read job + // used to avoid starvation of read jobs in the disk I/O + // thread. By default, read jobs are deferred, sorted by physical disk location + // and serviced once all write jobs have been issued. In scenarios where the + // download rate is enough to saturate the disk, there's a risk the read jobs will + // never be serviced. With this setting, every *x* write job, issued in a row, will + // instead pick one read job off of the sorted queue, where *x* is ``read_job_every``. int read_job_every; - // issue posix_fadvise() or fcntl(F_RDADVISE) for disk reads - // ahead of time + // defaults to true and will attempt to optimize disk reads + // by giving the operating system heads up of disk read requests as they are queued + // in the disk job queue. This gives a significant performance boost for seeding. bool use_disk_read_ahead; - // if set to true, files will be locked when opened. - // preventing any other process from modifying them + // determines whether or not to lock files which libtorrent is downloading + // to or seeding from. This is implemented using ``fcntl(F_SETLK)`` on unix systems and + // by not passing in ``SHARE_READ`` and ``SHARE_WRITE`` on windows. This might prevent + // 3rd party processes from corrupting the files under libtorrent's feet. bool lock_files; - // open an ssl listen socket for ssl torrents on this port + // sets the listen port for SSL connections. If this is set to 0, + // no SSL listen port is opened. Otherwise a socket is opened on this port. This + // setting is only taken into account when opening the regular listen port, and + // won't re-open the listen socket simply by changing this setting. + // // if this is 0, outgoing SSL connections are disabled + // + // It defaults to port 4433. int ssl_listen; - // this is the factor X in the formula to calculate the - // next tracker timeout: - // delay = 5 + X/100 * fails^2 - // so, it's an exponential back-off, and this factor - // determines how fast the back-off happens. Default - // is 250 + // ``tracker_backoff`` determines how aggressively to back off from retrying + // failing trackers. This value determines *x* in the following formula, determining + // the number of seconds to wait until the next retry: + // + // delay = 5 + 5 * x / 100 * fails^2 + // + // It defaults to 250. + // + // This setting may be useful to make libtorrent more or less aggressive in hitting + // trackers. + // int tracker_backoff; - // when true, web seeds sending bad data will be banned + // enables banning web seeds. By default, web seeds that send + // corrupt data are banned. bool ban_web_seeds; - // http_connection maximum receive buffer size - // limits torrent file size for URL torrents + // specifies the max number of bytes to receive into + // RAM buffers when downloading stuff over HTTP. Specifically when specifying a + // URL to a .torrent file when adding a torrent or when announcing to an HTTP + // tracker. The default is 2 MiB. int max_http_recv_buffer_size; - // enables/disables the share-mode extension + // enables or disables the share mode extension. This is + // enabled by default. bool support_share_mode; - // if this is false, don't advertise support for - // the Tribler merkle tree piece message + // enables or disables the merkle tree torrent support. + // This is enabled by default. bool support_merkle_torrents; - // if this is true, the number of redundant bytes - // is sent to the tracker + // enables or disables reporting redundant bytes to the tracker. + // This is enabled by default. bool report_redundant_bytes; // the version string to advertise for this client