entry torrent_file; // ... // throws if this is not a dictionary if (entry* i = torrent_file.find_key("announce")) { std::string tracker_url = i->string(); std::cout << tracker_url << "\n"; }
To make it easier to extract information from a torrent file, the class torrent_info exists.
[report issue]operator[]()
entry& operator[] (string_view key); const entry& operator[] (string_view key) const;
All of these functions requires the entry to be a dictionary, if it isn't they will throw system_error.
The non-const versions of the operator[] will return a reference to either the existing element at the given key or, if there is no element with the given key, a reference to a newly inserted element at that key.
The const version of operator[] will only return a reference to an existing element at the given key. If the key is not found, it will throw system_error.
[report issue]find_key()
entry* find_key (string_view key); entry const* find_key (string_view key) const;
These functions requires the entry to be a dictionary, if it isn't they will throw system_error.
They will look for an element at the given key in the dictionary, if the element cannot be found, they will return nullptr. If an element with the given key is found, the return a pointer to it.
[report issue]to_string()
std::string to_string (bool single_line = false) const;
returns a pretty-printed string representation of the bencoded structure, with JSON-style syntax
[report issue]enum data_type
Declared in "libtorrent/entry.hpp"
| name | value | description |
|---|---|---|
| int_t | 0 | |
| string_t | 1 | |
| list_t | 2 | |
| dictionary_t | 3 | |
| undefined_t | 4 | |
| preformatted_t | 5 |
- m_type_queried
- in debug mode this is set to false by bdecode to indicate that the program has not yet queried the type of this entry, and should not assume that it has a certain type. This is asserted in the accessor functions. This does not apply if exceptions are used.
bencode()
Declared in "libtorrent/bencode.hpp"
template<class OutIt> int bencode (OutIt out, const entry& e);
This function will encode data to bencoded form.
The entry class is the internal representation of the bencoded data and it can be used to retrieve information, an entry can also be build by the program and given to bencode() to encode it into the OutIt iterator.
OutIt is an OutputIterator. It's a template and usually instantiated as ostream_iterator or back_insert_iterator. This function assumes the value_type of the iterator is a char. In order to encode entry e into a buffer, do:
std::vector<char> buffer; bencode(std::back_inserter(buf), e);[report issue]
operator<<()
Declared in "libtorrent/entry.hpp"
inline std::ostream& operator<< (std::ostream& os, const entry& e);
prints the bencoded structure to the ostream as a JSON-style structure.
| Author: | Arvid Norberg<EMAIL_ADDRESS>|
|---|---|
| Version: | 1.2.6 |
Alerts
The pop_alerts() function on session is the main interface for retrieving alerts (warnings, messages and errors from libtorrent). If no alerts have been posted by libtorrent pop_alerts() will return an empty list.
By default, only errors are reported. settings_pack::alert_mask can be used to specify which kinds of events should be reported. The alert mask is a combination of the alert_category_t flags in the alert class.
Every alert belongs to one or more category. There is a cost associated with posting alerts. Only alerts that belong to an enabled category are posted. Setting the alert bitmask to 0 will disable all alerts (except those that are non-discardable). Alerts that are responses to API calls such as save_resume_data() and post_session_stats() are non-discardable and will be posted even if their category is disabled.
There are other alert base classes that some alerts derive from, all the alerts that are generated for a specific torrent are derived from torrent_alert, and tracker events derive from tracker_alert.
Alerts returned by pop_alerts() are only valid until the next call to pop_alerts(). You may not copy an alert object to access it after the next call to pop_alerts(). Internal members of alerts also become invalid once pop_alerts() is called again.
[report issue]alert
Declared in "libtorrent/alert.hpp"
The alert class is the base class that specific messages are derived from. alert types are not copyable, and cannot be constructed by the client. The pointers returned by libtorrent are short lived (the details are described under session_handle::pop_alerts())
class alert { time_point timestamp () const; virtual int type () const noexcept = 0; virtual char const* what () const noexcept = 0; virtual std::string message () const = 0; virtual alert_category_t category () const noexcept = 0; static constexpr alert_category_t error_notification = 0_bit; static constexpr alert_category_t peer_notification = 1_bit; static constexpr alert_category_t port_mapping_notification = 2_bit; static constexpr alert_category_t storage_notification = 3_bit; static constexpr alert_category_t tracker_notification = 4_bit; static constexpr alert_category_t connect_notification = 5_bit; static constexpr alert_category_t status_notification = 6_bit; static constexpr alert_category_t ip_block_notification = 8_bit; static constexpr alert_category_t performance_warning = 9_bit; static constexpr alert_category_t dht_notification = 10_bit; static constexpr alert_category_t stats_notification = 11_bit; static constexpr alert_category_t session_log_notification = 13_bit; static constexpr alert_category_t torrent_log_notification = 14_bit; static constexpr alert_category_t peer_log_notification = 15_bit; static constexpr alert_category_t incoming_request_notification = 16_bit; static constexpr alert_category_t dht_log_notification = 17_bit; static constexpr alert_category_t dht_operation_notification = 18_bit; static constexpr alert_category_t port_mapping_log_notification = 19_bit; static constexpr alert_category_t picker_log_notification = 20_bit; static constexpr alert_category_t file_progress_notification = 21_bit; static constexpr alert_category_t piece_progress_notification = 22_bit; static constexpr alert_category_t upload_notification = 23_bit; static constexpr alert_category_t block_progress_notification = 24_bit; static constexpr alert_category_t all_categories = alert_category_t::all(); };[report issue]
timestamp()
time_point timestamp () const;
a timestamp is automatically created in the constructor
[report issue]type()
virtual int type () const noexcept = 0;
returns an integer that is unique to this alert type. It can be compared against a specific alert by querying a static constant called alert_type in the alert. It can be used to determine the run-time type of an alert* in order to cast to that alert type and access specific members.
e.g:
std::vector<alert*> alerts; ses.pop_alerts(&alerts); for (alert* i : alerts) { switch (a->type()) { case read_piece_alert::alert_type: { auto* p = static_cast<read_piece_alert*>(a); if (p->ec) { // read_piece failed break; } // use p break; } case file_renamed_alert::alert_type: { // etc... } } }[report issue]
what()
virtual char const* what () const noexcept = 0;
returns a string literal describing the type of the alert. It does not include any information that might be bundled with the alert.
[report issue]message()
virtual std::string message () const = 0;
generate a string describing the alert and the information bundled with it. This is mainly intended for debug and development use. It is not suitable to use this for applications that may be localized. Instead, handle each alert type individually and extract and render the information from the alert depending on the locale.
[report issue]category()
virtual alert_category_t category () const noexcept = 0;
returns a bitmask specifying which categories this alert belong to.
[report issue]dht_routing_bucket
Declared in "libtorrent/alert_types.hpp"
struct to hold information about a single DHT routing table bucket
struct dht_routing_bucket { int num_nodes; int num_replacements; int last_active; };[report issue]
- num_nodes num_replacements
- the total number of nodes and replacement nodes in the routing table
- last_active
- number of seconds since last activity
torrent_alert
Declared in "libtorrent/alert_types.hpp"
This is a base class for alerts that are associated with a specific torrent. It contains a handle to the torrent.
struct torrent_alert : alert { std::string message () const override; char const* torrent_name () const; torrent_handle handle; };[report issue]
message()
std::string message () const override;
returns the message associated with this alert
[report issue]- handle
- The torrent_handle pointing to the torrent this alert is associated with.
peer_alert
Declared in "libtorrent/alert_types.hpp"
The peer alert is a base class for alerts that refer to a specific peer. It includes all the information to identify the peer. i.e. ip and peer-id.
struct peer_alert : torrent_alert { std::string message () const override; aux::noexcept_movable<tcp::endpoint> endpoint; peer_id pid; };[report issue]
- endpoint
- The peer's IP address and port.
- pid
- the peer ID, if known.
tracker_alert
Declared in "libtorrent/alert_types.hpp"
This is a base class used for alerts that are associated with a specific tracker. It derives from torrent_alert since a tracker is also associated with a specific torrent.
struct tracker_alert : torrent_alert { std::string message () const override; char const* tracker_url () const; aux::noexcept_movable<tcp::endpoint> local_endpoint; };[report issue]
tracker_url()
char const* tracker_url () const;
returns a 0-terminated string of the tracker's URL
[report issue]- local_endpoint
- endpoint of the listen interface being announced
torrent_removed_alert
Declared in "libtorrent/alert_types.hpp"
The torrent_removed_alert is posted whenever a torrent is removed. Since the torrent handle in its base class will always be invalid (since the torrent is already removed) it has the info hash as a member, to identify it. It's posted when the status_notification bit is set in the alert_mask.
Even though the handle member doesn't point to an existing torrent anymore, it is still useful for comparing to other handles, which may also no longer point to existing torrents, but to the same non-existing torrents.
The torrent_handle acts as a weak_ptr, even though its object no longer exists, it can still compare equal to another weak pointer which points to the same non-existent object.
struct torrent_removed_alert final : torrent_alert { std::string message () const override; static constexpr alert_category_t static_category = alert_category::status; sha1_hash info_hash; };[report issue]
read_piece_alert
Declared in "libtorrent/alert_types.hpp"
This alert is posted when the asynchronous read operation initiated by a call to torrent_handle::read_piece() is completed. If the read failed, the torrent is paused and an error state is set and the buffer member of the alert is 0. If successful, buffer points to a buffer containing all the data of the piece. piece is the piece index that was read. size is the number of bytes that was read.
If the operation fails, error will indicate what went wrong.
struct read_piece_alert final : torrent_alert { std::string message () const override; static constexpr alert_category_t static_category = alert_category::storage; error_code const error; boost::shared_array<char> const buffer; piece_index_t const piece; int const size; };[report issue]
file_completed_alert
Declared in "libtorrent/alert_types.hpp"
This is posted whenever an individual file completes its download. i.e. All pieces overlapping this file have passed their hash check.
struct file_completed_alert final : torrent_alert { std::string message () const override; file_index_t const index; };[report issue]
- index
- refers to the index of the file that completed.
file_renamed_alert
Declared in "libtorrent/alert_types.hpp"
This is posted as a response to a torrent_handle::rename_file() call, if the rename operation succeeds.
struct file_renamed_alert final : torrent_alert { std::string message () const override; char const* new_name () const; static constexpr alert_category_t static_category = alert_category::storage; file_index_t const index; };[report issue]
- index
- refers to the index of the file that was renamed,
file_rename_failed_alert
Declared in "libtorrent/alert_types.hpp"
This is posted as a response to a torrent_handle::rename_file() call, if the rename operation failed.
struct file_rename_failed_alert final : torrent_alert { std::string message () const override; static constexpr alert_category_t static_category = alert_category::storage; file_index_t const index; error_code const error; };[report issue]
- index error
- refers to the index of the file that was supposed to be renamed, error is the error code returned from the filesystem.
performance_alert
Declared in "libtorrent/alert_types.hpp"
This alert is generated when a limit is reached that might have a negative impact on upload or download rate performance.
struct performance_alert final : torrent_alert { std::string message () const override; enum performance_warning_t { outstanding_disk_buffer_limit_reached, outstanding_request_limit_reached, upload_limit_too_low, download_limit_too_low, send_buffer_watermark_too_low, too_many_optimistic_unchoke_slots, too_high_disk_queue_limit, aio_limit_reached, deprecated_bittyrant_with_no_uplimit, too_few_outgoing_ports, too_few_file_descriptors, num_warnings, }; static constexpr alert_category_t static_category = alert_category::performance_warning; performance_warning_t const warning_code; };[report issue]
enum performance_warning_t
Declared in "libtorrent/alert_types.hpp"
| name | value | description |
|---|---|---|
| outstanding_disk_buffer_limit_reached | 0 | This warning means that the number of bytes queued to be written to disk exceeds the max disk byte queue setting (settings_pack::max_queued_disk_bytes). This might restrict the download rate, by not queuing up enough write jobs to the disk I/O thread. When this alert is posted, peer connections are temporarily stopped from downloading, until the queued disk bytes have fallen below the limit again. Unless your max_queued_disk_bytes setting is already high, you might want to increase it to get better performance. |
| outstanding_request_limit_reached | 1 | This is posted when libtorrent would like to send more requests to a peer, but it's limited by settings_pack::max_out_request_queue. The queue length libtorrent is trying to achieve is determined by the download rate and the assumed round-trip-time (settings_pack::request_queue_time). The assumed round-trip-time is not limited to just the network RTT, but also the remote disk access time and message handling time. It defaults to 3 seconds. The target number of outstanding requests is set to fill the bandwidth-delay product (assumed RTT times download rate divided by number of bytes per request). When this alert is posted, there is a risk that the number of outstanding requests is too low and limits the download rate. You might want to increase the max_out_request_queue setting. |
| upload_limit_too_low | 2 | This warning is posted when the amount of TCP/IP overhead is greater than the upload rate limit. When this happens, the TCP/IP overhead is caused by a much faster download rate, triggering TCP ACK packets. These packets eat into the rate limit specified to libtorrent. When the overhead traffic is greater than the rate limit, libtorrent will not be able to send any actual payload, such as piece requests. This means the download rate will suffer, and new requests can be sent again. There will be an equilibrium where the download rate, on average, is about 20 times the upload rate limit. If you want to maximize the download rate, increase the upload rate limit above 5% of your download capacity. |
| download_limit_too_low | 3 | This is the same warning as upload_limit_too_low but referring to the download limit instead of upload. This suggests that your download rate limit is much lower than your upload capacity. Your upload rate will suffer. To maximize upload rate, make sure your download rate limit is above 5% of your upload capacity. |
| send_buffer_watermark_too_low | 4 | We're stalled on the disk. We want to write to the socket, and we can write but our send buffer is empty, waiting to be refilled from the disk. This either means the disk is slower than the network connection or that our send buffer watermark is too small, because we can send it all before the disk gets back to us. The number of bytes that we keep outstanding, requested from the disk, is calculated as follows: min(512, max(upload_rate * send_buffer_watermark_factor / 100, send_buffer_watermark)) If you receive this alert, you might want to either increase your send_buffer_watermark or send_buffer_watermark_factor. |
| too_many_optimistic_unchoke_slots | 5 | If the half (or more) of all upload slots are set as optimistic unchoke slots, this warning is issued. You probably want more regular (rate based) unchoke slots. |
| too_high_disk_queue_limit | 6 | If the disk write queue ever grows larger than half of the cache size, this warning is posted. The disk write queue eats into the total disk cache and leaves very little left for the actual cache. This causes the disk cache to oscillate in evicting large portions of the cache before allowing peers to download any more, onto the disk write queue. Either lower max_queued_disk_bytes or increase cache_size. |
| aio_limit_reached | 7 | |
| deprecated_bittyrant_with_no_uplimit | 8 | |
| too_few_outgoing_ports | 9 | This is generated if outgoing peer connections are failing because of address in use errors, indicating that settings_pack::outgoing_ports is set and is too small of a range. Consider not using the outgoing_ports setting at all, or widen the range to include more ports. |
| too_few_file_descriptors | 10 | |
| num_warnings | 11 |
state_changed_alert
Declared in "libtorrent/alert_types.hpp"
Generated whenever a torrent changes its state.
struct state_changed_alert final : torrent_alert { std::string message () const override; static constexpr alert_category_t static_category = alert_category::status; torrent_status::state_t const state; torrent_status::state_t const prev_state; };[report issue]
- state
- the new state of the torrent.
- prev_state
- the previous state.
tracker_error_alert
Declared in "libtorrent/alert_types.hpp"
This alert is generated on tracker time outs, premature disconnects, invalid response or a HTTP response other than "200 OK". From the alert you can get the handle to the torrent the tracker belongs to.
The times_in_row member says how many times in a row this tracker has failed. status_code is the code returned from the HTTP server. 401 means the tracker needs authentication, 404 means not found etc. If the tracker timed out, the code will be set to 0.
struct tracker_error_alert final : tracker_alert { std::string message () const override; char const* error_message () const; static constexpr alert_category_t static_category = alert_category::tracker | alert_category::error; int const times_in_row; error_code const error; };[report issue]
error_message()
char const* error_message () const;
the message associated with this error
[report issue]tracker_warning_alert
Declared in "libtorrent/alert_types.hpp"
This alert is triggered if the tracker reply contains a warning field. Usually this means that the tracker announce was successful, but the tracker has a message to the client.
struct tracker_warning_alert final : tracker_alert { std::string message () const override; char const* warning_message () const; static constexpr alert_category_t static_category = alert_category::tracker | alert_category::error; };[report issue]
warning_message()
char const* warning_message () const;
the message associated with this warning
[report issue]scrape_reply_alert
Declared in "libtorrent/alert_types.hpp"
This alert is generated when a scrape request succeeds.
struct scrape_reply_alert final : tracker_alert { std::string message () const override; static constexpr alert_category_t static_category = alert_category::tracker; int const incomplete; int const complete; };[report issue]
- incomplete complete
- the data returned in the scrape response. These numbers may be -1 if the response was malformed.
scrape_failed_alert
Declared in "libtorrent/alert_types.hpp"
If a scrape request fails, this alert is generated. This might be due to the tracker timing out, refusing connection or returning an http response code indicating an error.
struct scrape_failed_alert final : tracker_alert { std::string message () const override; char const* error_message () const; static constexpr alert_category_t static_category = alert_category::tracker | alert_category::error; error_code const error; };[report issue]
error_message()
char const* error_message () const;
if the error indicates there is an associated message, this returns that message. Otherwise and empty string.
[report issue]- error
- the error itself. This may indicate that the tracker sent an error message (error::tracker_failure), in which case it can be retrieved by calling error_message().
tracker_reply_alert
Declared in "libtorrent/alert_types.hpp"
This alert is only for informational purpose. It is generated when a tracker announce succeeds. It is generated regardless what kind of tracker was used, be it UDP, HTTP or the DHT.
struct tracker_reply_alert final : tracker_alert { std::string message () const override; static constexpr alert_category_t static_category = alert_category::tracker; int const num_peers; };[report issue]
- num_peers
- tells how many peers the tracker returned in this response. This is not expected to be greater than the num_want settings. These are not necessarily all new peers, some of them may already be connected.
dht_reply_alert
Declared in "libtorrent/alert_types.hpp"
This alert is generated each time the DHT receives peers from a node. num_peers is the number of peers we received in this packet. Typically these packets are received from multiple DHT nodes, and so the alerts are typically generated a few at a time.
struct dht_reply_alert final : tracker_alert { std::string message () const override; static constexpr alert_category_t static_category = alert_category::dht | alert_category::tracker; int const num_peers; };[report issue]
tracker_announce_alert
Declared in "libtorrent/alert_types.hpp"
This alert is generated each time a tracker announce is sent (or attempted to be sent). There are no extra data members in this alert. The url can be found in the base class however.
struct tracker_announce_alert final : tracker_alert { std::string message () const override; static constexpr alert_category_t static_category = alert_category::tracker; int const event; };[report issue]
- event
specifies what event was sent to the tracker. It is defined as:
- None
- Completed
- Started
- Stopped
hash_failed_alert
Declared in "libtorrent/alert_types.hpp"
This alert is generated when a finished piece fails its hash check. You can get the handle to the torrent which got the failed piece and the index of the piece itself from the alert.
struct hash_failed_alert final : torrent_alert { std::string message () const override; static constexpr alert_category_t static_category = alert_category::status; piece_index_t const piece_index; };[report issue]
peer_ban_alert
Declared in "libtorrent/alert_types.hpp"
This alert is generated when a peer is banned because it has sent too many corrupt pieces to us. ip is the endpoint to the peer that was banned.
struct peer_ban_alert final : peer_alert { std::string message () const override; static constexpr alert_category_t static_category = alert_category::peer; };[report issue]
peer_unsnubbed_alert
Declared in "libtorrent/alert_types.hpp"
This alert is generated when a peer is un-snubbed. Essentially when it was snubbed for stalling sending data, and now it started sending data again.
struct peer_unsnubbed_alert final : peer_alert { std::string message () const override; static constexpr alert_category_t static_category = alert_category::peer; };[report issue]
peer_snubbed_alert
Declared in "libtorrent/alert_types.hpp"
This alert is generated when a peer is snubbed, when it stops sending data when we request it.
struct peer_snubbed_alert final : peer_alert { std::string message () const override; static constexpr alert_category_t static_category = alert_category::peer; };[report issue]
peer_error_alert
Declared in "libtorrent/alert_types.hpp"
This alert is generated when a peer sends invalid data over the peer-peer protocol. The peer will be disconnected, but you get its ip address from the alert, to identify it.
struct peer_error_alert final : peer_alert { std::string message () const override; static constexpr alert_category_t static_category = alert_category::peer; operation_t op; error_code const error; };[report issue]
- op
- a 0-terminated string of the low-level operation that failed, or nullptr if there was no low level disk operation.
- error
- tells you what error caused this alert.
peer_connect_alert
Declared in "libtorrent/alert_types.hpp"
This alert is posted every time an outgoing peer connect attempts succeeds.
struct peer_connect_alert final : peer_alert { std::string message () const override; static constexpr alert_category_t static_category = alert_category::connect; int const socket_type; };[report issue]
peer_disconnected_alert
Declared in "libtorrent/alert_types.hpp"
This alert is generated when a peer is disconnected for any reason (other than the ones covered by peer_error_alert ).
struct peer_disconnected_alert final : peer_alert { std::string message () const override; static constexpr alert_category_t static_category = alert_category::connect; int const socket_type; operation_t const op; error_code const error; close_reason_t const reason; };[report issue]
- socket_type
- the kind of socket this peer was connected over
- op
- the operation or level where the error occurred. Specified as an value from the operation_t enum. Defined in operations.hpp.
- error
- tells you what error caused peer to disconnect.
- reason
- the reason the peer disconnected (if specified)
invalid_request_alert
Declared in "libtorrent/alert_types.hpp"
This is a debug alert that is generated by an incoming invalid piece request. ip is the address of the peer and the request is the actual incoming request from the peer. See peer_request for more info.
struct invalid_request_alert final : peer_alert { std::string message () const override; static constexpr alert_category_t static_category = alert_category::peer; peer_request const request; bool const we_have; bool const peer_interested; bool const withheld; };[report issue]
- request
- the request we received from the peer
- we_have
- true if we have this piece
- peer_interested
- true if the peer indicated that it was interested to download before sending the request
- withheld
- if this is true, the peer is not allowed to download this piece because of super-seeding rules.
torrent_finished_alert
Declared in "libtorrent/alert_types.hpp"
This alert is generated when a torrent switches from being a downloader to a seed. It will only be generated once per torrent. It contains a torrent_handle to the torrent in question.
struct torrent_finished_alert final : torrent_alert { std::string message () const override; static constexpr alert_category_t static_category = alert_category::status; };[report issue]
piece_finished_alert
Declared in "libtorrent/alert_types.hpp"
this alert is posted every time a piece completes downloading and passes the hash check. This alert derives from torrent_alert which contains the torrent_handle to the torrent the piece belongs to. Note that being downloaded and passing the hash check may happen before the piece is also fully flushed to disk. So torrent_handle::have_piece() may still return false
struct piece_finished_alert final : torrent_alert { std::string message () const override; piece_index_t const piece_index; };[report issue]
- piece_index
- the index of the piece that finished
request_dropped_alert
Declared in "libtorrent/alert_types.hpp"
This alert is generated when a peer rejects or ignores a piece request.
struct request_dropped_alert final : peer_alert { std::string message () const override; int const block_index; piece_index_t const piece_index; };[report issue]
block_timeout_alert
Declared in "libtorrent/alert_types.hpp"
This alert is generated when a block request times out.
struct block_timeout_alert final : peer_alert { std::string message () const override; int const block_index; piece_index_t const piece_index; };[report issue]
block_finished_alert
Declared in "libtorrent/alert_types.hpp"
This alert is generated when a block request receives a response.
struct block_finished_alert final : peer_alert { std::string message () const override; int const block_index; piece_index_t const piece_index; };[report issue]
block_downloading_alert
Declared in "libtorrent/alert_types.hpp"
This alert is generated when a block request is sent to a peer.
struct block_downloading_alert final : peer_alert { std::string message () const override; int const block_index; piece_index_t const piece_index; };[report issue]
unwanted_block_alert
Declared in "libtorrent/alert_types.hpp"
This alert is generated when a block is received that was not requested or whose request timed out.
struct unwanted_block_alert final : peer_alert { std::string message () const override; static constexpr alert_category_t static_category = alert_category::peer; int const block_index; piece_index_t const piece_index; };[report issue]
storage_moved_alert
Declared in "libtorrent/alert_types.hpp"
The storage_moved_alert is generated when all the disk IO has completed and the files have been moved, as an effect of a call to torrent_handle::move_storage. This is useful to synchronize with the actual disk. The storage_path() member return the new path of the storage.
struct storage_moved_alert final : torrent_alert { std::string message () const override; char const* storage_path () const; static constexpr alert_category_t static_category = alert_category::storage; };[report issue]
storage_moved_failed_alert
Declared in "libtorrent/alert_types.hpp"
The storage_moved_failed_alert is generated when an attempt to move the storage, via torrent_handle::move_storage(), fails.
struct storage_moved_failed_alert final : torrent_alert { std::string message () const override; char const* file_path () const; static constexpr alert_category_t static_category = alert_category::storage; error_code const error; operation_t op; };[report issue]
file_path()
char const* file_path () const;
If the error happened for a specific file, this returns its path.
[report issue]- op
- this indicates what underlying operation caused the error
torrent_deleted_alert
Declared in "libtorrent/alert_types.hpp"
This alert is generated when a request to delete the files of a torrent complete.
The info_hash is the info-hash of the torrent that was just deleted. Most of the time the torrent_handle in the torrent_alert will be invalid by the time this alert arrives, since the torrent is being deleted. The info_hash member is hence the main way of identifying which torrent just completed the delete.
This alert is posted in the storage_notification category, and that bit needs to be set in the alert_mask.
struct torrent_deleted_alert final : torrent_alert { std::string message () const override; static constexpr alert_category_t static_category = alert_category::storage; sha1_hash info_hash; };[report issue]
torrent_delete_failed_alert
Declared in "libtorrent/alert_types.hpp"
This alert is generated when a request to delete the files of a torrent fails. Just removing a torrent from the session cannot fail
struct torrent_delete_failed_alert final : torrent_alert { std::string message () const override; static constexpr alert_category_t static_category = alert_category::storage | alert_category::error; error_code const error; sha1_hash info_hash; };[report issue]
- error
- tells you why it failed.
- info_hash
- the info hash of the torrent whose files failed to be deleted
save_resume_data_alert
Declared in "libtorrent/alert_types.hpp"
This alert is generated as a response to a torrent_handle::save_resume_data request. It is generated once the disk IO thread is done writing the state for this torrent.
struct save_resume_data_alert final : torrent_alert { std::string message () const override; static constexpr alert_category_t static_category = alert_category::storage; add_torrent_params params; };[report issue]
- params
- the params structure is populated with the fields to be passed to add_torrent() or async_add_torrent() to resume the torrent. To save the state to disk, you may pass it on to write_resume_data().
save_resume_data_failed_alert
Declared in "libtorrent/alert_types.hpp"
This alert is generated instead of save_resume_data_alert if there was an error generating the resume data. error describes what went wrong.
struct save_resume_data_failed_alert final : torrent_alert { std::string message () const override; static constexpr alert_category_t static_category = alert_category::storage | alert_category::error; error_code const error; };[report issue]
- error
- the error code from the resume_data failure
torrent_paused_alert
Declared in "libtorrent/alert_types.hpp"
This alert is generated as a response to a torrent_handle::pause request. It is generated once all disk IO is complete and the files in the torrent have been closed. This is useful for synchronizing with the disk.
struct torrent_paused_alert final : torrent_alert { std::string message () const override; static constexpr alert_category_t static_category = alert_category::status; };[report issue]
torrent_resumed_alert
Declared in "libtorrent/alert_types.hpp"
This alert is generated as a response to a torrent_handle::resume() request. It is generated when a torrent goes from a paused state to an active state.
struct torrent_resumed_alert final : torrent_alert { std::string message () const override; static constexpr alert_category_t static_category = alert_category::status; };[report issue]
torrent_checked_alert
Declared in "libtorrent/alert_types.hpp"
This alert is posted when a torrent completes checking. i.e. when it transitions out of the checking files state into a state where it is ready to start downloading
struct torrent_checked_alert final : torrent_alert { std::string message () const override; static constexpr alert_category_t static_category = alert_category::status; };[report issue]
url_seed_alert
Declared in "libtorrent/alert_types.hpp"
This alert is generated when a HTTP seed name lookup fails.
struct url_seed_alert final : torrent_alert { std::string message () const override; char const* server_url () const; char const* error_message () const; static constexpr alert_category_t static_category = alert_category::peer | alert_category::error; error_code const error; };[report issue]
error_message()
char const* error_message () const;
in case the web server sent an error message, this function returns it.
[report issue]- error
- the error the web seed encountered. If this is not set, the server sent an error message, call error_message().
file_error_alert
Declared in "libtorrent/alert_types.hpp"
If the storage fails to read or write files that it needs access to, this alert is generated and the torrent is paused.
struct file_error_alert final : torrent_alert { std::string message () const override; char const* filename () const; static constexpr alert_category_t static_category = alert_category::status | alert_category::storage; error_code const error; operation_t op; };[report issue]
filename()
char const* filename () const;
the file that experienced the error
[report issue]- error
- the error code describing the error.
- op
- indicates which underlying operation caused the error
metadata_failed_alert
Declared in "libtorrent/alert_types.hpp"
This alert is generated when the metadata has been completely received and the info-hash failed to match it. i.e. the metadata that was received was corrupt. libtorrent will automatically retry to fetch it in this case. This is only relevant when running a torrent-less download, with the metadata extension provided by libtorrent.
struct metadata_failed_alert final : torrent_alert { std::string message () const override; static constexpr alert_category_t static_category = alert_category::error; error_code const error; };[report issue]
- error
- indicates what failed when parsing the metadata. This error is what's returned from lazy_bdecode().
metadata_received_alert
Declared in "libtorrent/alert_types.hpp"
This alert is generated when the metadata has been completely received and the torrent can start downloading. It is not generated on torrents that are started with metadata, but only those that needs to download it from peers (when utilizing the libtorrent extension).
There are no additional data members in this alert.
Typically, when receiving this alert, you would want to save the torrent file in order to load it back up again when the session is restarted. Here's an example snippet of code to do that:
torrent_handle h = alert->handle(); if (h.is_valid()) { std::shared_ptr<torrent_info const> ti = h.torrent_file(); create_torrent ct(*ti); entry te = ct.generate(); std::vector<char> buffer; bencode(std::back_inserter(buffer), te); FILE* f = fopen((to_hex(ti->info_hash().to_string()) + ".torrent").c_str(), "wb+"); if (f) { fwrite(&buffer[0], 1, buffer.size(), f); fclose(f); } }
struct metadata_received_alert final : torrent_alert { std::string message () const override; static constexpr alert_category_t static_category = alert_category::status; };[report issue]
udp_error_alert
Declared in "libtorrent/alert_types.hpp"
This alert is posted when there is an error on a UDP socket. The UDP sockets are used for all uTP, DHT and UDP tracker traffic. They are global to the session.
struct udp_error_alert final : alert { std::string message () const override; static constexpr alert_category_t static_category = alert_category::error; aux::noexcept_movable<udp::endpoint> endpoint; operation_t operation; error_code const error; };[report issue]
- endpoint
- the source address associated with the error (if any)
- operation
- the operation that failed
- error
- the error code describing the error
external_ip_alert
Declared in "libtorrent/alert_types.hpp"
Whenever libtorrent learns about the machines external IP, this alert is generated. The external IP address can be acquired from the tracker (if it supports that) or from peers that supports the extension protocol. The address can be accessed through the external_address member.
struct external_ip_alert final : alert { std::string message () const override; static constexpr alert_category_t static_category = alert_category::status; aux::noexcept_movable<address> external_address; };[report issue]
- external_address
- the IP address that is believed to be our external IP
listen_failed_alert
Declared in "libtorrent/alert_types.hpp"
This alert is generated when none of the ports, given in the port range, to session can be opened for listening. The listen_interface member is the interface that failed, error is the error code describing the failure.
In the case an endpoint was created before generating the alert, it is represented by address and port. The combinations of socket type and operation in which such address and port are not valid are: accept - i2p accept - socks5 enum_if - tcp
libtorrent may sometimes try to listen on port 0, if all other ports failed. Port 0 asks the operating system to pick a port that's free). If that fails you may see a listen_failed_alert with port 0 even if you didn't ask to listen on it.
struct listen_failed_alert final : alert { listen_failed_alert (aux::stack_allocator& alloc, string_view iface , tcp::endpoint const& ep, operation_t op, error_code const& ec , lt::socket_type_t t); listen_failed_alert (aux::stack_allocator& alloc, string_view iface , udp::endpoint const& ep, operation_t op, error_code const& ec , lt::socket_type_t t); listen_failed_alert (aux::stack_allocator& alloc, string_view iface , operation_t op, error_code const& ec, lt::socket_type_t t); std::string message () const override; char const* listen_interface () const; static constexpr alert_category_t static_category = alert_category::status | alert_category::error; error_code const error; operation_t op; lt::socket_type_t const socket_type; aux::noexcept_movable<lt::address> address; int const port; };[report issue]
listen_interface()
char const* listen_interface () const;
the network device libtorrent attempted to listen on, or the IP address
[report issue]- error
- the error the system returned
- op
- the underlying operation that failed
- socket_type
- the type of listen socket this alert refers to.
- address
- the address libtorrent attempted to listen on see alert documentation for validity of this value
- port
- the port libtorrent attempted to listen on see alert documentation for validity of this value
listen_succeeded_alert
Declared in "libtorrent/alert_types.hpp"
This alert is posted when the listen port succeeds to be opened on a particular interface. address and port is the endpoint that successfully was opened for listening.
struct listen_succeeded_alert final : alert { listen_succeeded_alert (aux::stack_allocator& alloc , tcp::endpoint const& ep , lt::socket_type_t t); listen_succeeded_alert (aux::stack_allocator& alloc , udp::endpoint const& ep , lt::socket_type_t t); std::string message () const override; static constexpr alert_category_t static_category = alert_category::status; aux::noexcept_movable<lt::address> address; int const port; lt::socket_type_t const socket_type; };[report issue]
- address
- the address libtorrent ended up listening on. This address refers to the local interface.
- port
- the port libtorrent ended up listening on.
- socket_type
- the type of listen socket this alert refers to.
portmap_error_alert
Declared in "libtorrent/alert_types.hpp"
This alert is generated when a NAT router was successfully found but some part of the port mapping request failed. It contains a text message that may help the user figure out what is wrong. This alert is not generated in case it appears the client is not running on a NAT:ed network or if it appears there is no NAT router that can be remote controlled to add port mappings.
struct portmap_error_alert final : alert { std::string message () const override; static constexpr alert_category_t static_category = alert_category::port_mapping | alert_category::error; port_mapping_t const mapping; portmap_transport map_transport; error_code const error; };[report issue]
- mapping
- refers to the mapping index of the port map that failed, i.e. the index returned from add_mapping().
- map_transport
- UPnP or NAT-PMP
- error
- tells you what failed.
portmap_alert
Declared in "libtorrent/alert_types.hpp"
This alert is generated when a NAT router was successfully found and a port was successfully mapped on it. On a NAT:ed network with a NAT-PMP capable router, this is typically generated once when mapping the TCP port and, if DHT is enabled, when the UDP port is mapped.
struct portmap_alert final : alert { std::string message () const override; static constexpr alert_category_t static_category = alert_category::port_mapping; port_mapping_t const mapping; int const external_port; portmap_protocol const map_protocol; portmap_transport const map_transport; };[report issue]
- mapping
- refers to the mapping index of the port map that failed, i.e. the index returned from add_mapping().
- external_port
- the external port allocated for the mapping.
portmap_log_alert
Declared in "libtorrent/alert_types.hpp"
This alert is generated to log informational events related to either UPnP or NAT-PMP. They contain a log line and the type (0 = NAT-PMP and 1 = UPnP). Displaying these messages to an end user is only useful for debugging the UPnP or NAT-PMP implementation. This alert is only posted if the alert_category::port_mapping_log flag is enabled in the alert mask.
struct portmap_log_alert final : alert { std::string message () const override; char const* log_message () const; static constexpr alert_category_t static_category = alert_category::port_mapping_log; portmap_transport const map_transport; };[report issue]
log_message()
char const* log_message () const;
the message associated with this log line
[report issue]fastresume_rejected_alert
Declared in "libtorrent/alert_types.hpp"
This alert is generated when a fast resume file has been passed to add_torrent() but the files on disk did not match the fast resume file. The error_code explains the reason why the resume file was rejected.
struct fastresume_rejected_alert final : torrent_alert { std::string message () const override; char const* file_path () const; static constexpr alert_category_t static_category = alert_category::status | alert_category::error; error_code error; operation_t op; };[report issue]
file_path()
char const* file_path () const;
If the error happened to a specific file, this returns the path to it.
[report issue]- op
- the underlying operation that failed
peer_blocked_alert
Declared in "libtorrent/alert_types.hpp"
This alert is posted when an incoming peer connection, or a peer that's about to be added to our peer list, is blocked for some reason. This could be any of:
- the IP filter
- i2p mixed mode restrictions (a normal peer is not allowed on an i2p swarm)
- the port filter
- the peer has a low port and no_connect_privileged_ports is enabled
- the protocol of the peer is blocked (uTP/TCP blocking)
struct peer_blocked_alert final : peer_alert { std::string message () const override; enum reason_t { ip_filter, port_filter, i2p_mixed, privileged_ports, utp_disabled, tcp_disabled, invalid_local_interface, }; static constexpr alert_category_t static_category = alert_category::ip_block; int const reason; };[report issue]
enum reason_t
Declared in "libtorrent/alert_types.hpp"
| name | value | description |
|---|---|---|
| ip_filter | 0 | |
| port_filter | 1 | |
| i2p_mixed | 2 | |
| privileged_ports | 3 | |
| utp_disabled | 4 | |
| tcp_disabled | 5 | |
| invalid_local_interface | 6 |
- reason
- the reason for the peer being blocked. Is one of the values from the reason_t enum.
dht_announce_alert
Declared in "libtorrent/alert_types.hpp"
This alert is generated when a DHT node announces to an info-hash on our DHT node. It belongs to the dht_notification category.
struct dht_announce_alert final : alert { std::string message () const override; static constexpr alert_category_t static_category = alert_category::dht; aux::noexcept_movable<address> ip; int port; sha1_hash info_hash; };[report issue]
dht_get_peers_alert
Declared in "libtorrent/alert_types.hpp"
This alert is generated when a DHT node sends a get_peers message to our DHT node. It belongs to the dht_notification category.
struct dht_get_peers_alert final : alert { std::string message () const override; static constexpr alert_category_t static_category = alert_category::dht; sha1_hash info_hash; };[report issue]
stats_alert
Declared in "libtorrent/alert_types.hpp"
This alert is posted approximately once every second, and it contains byte counters of most statistics that's tracked for torrents. Each active torrent posts these alerts regularly. This alert has been superseded by calling post_torrent_updates() regularly on the session object. This alert will be removed
struct stats_alert final : torrent_alert { std::string message () const override; enum stats_channel { upload_payload, upload_protocol, download_payload, download_protocol, upload_ip_protocol, deprecated1, deprecated2, download_ip_protocol, deprecated3, deprecated4, num_channels, }; static constexpr alert_category_t static_category = alert_category::stats; std::array<int, num_channels> const transferred; int const interval; };[report issue]
enum stats_channel
Declared in "libtorrent/alert_types.hpp"
| name | value | description |
|---|---|---|
| upload_payload | 0 | |
| upload_protocol | 1 | |
| download_payload | 2 | |
| download_protocol | 3 | |
| upload_ip_protocol | 4 | |
| deprecated1 | 5 | |
| deprecated2 | 6 | |
| download_ip_protocol | 7 | |
| deprecated3 | 8 | |
| deprecated4 | 9 | |
| num_channels | 10 |
- transferred
- an array of samples. The enum describes what each sample is a measurement of. All of these are raw, and not smoothing is performed.
- interval
- the number of milliseconds during which these stats were collected. This is typically just above 1000, but if CPU is limited, it may be higher than that.
cache_flushed_alert
Declared in "libtorrent/alert_types.hpp"
This alert is posted when the disk cache has been flushed for a specific torrent as a result of a call to torrent_handle::flush_cache(). This alert belongs to the storage_notification category, which must be enabled to let this alert through. The alert is also posted when removing a torrent from the session, once the outstanding cache flush is complete and the torrent does no longer have any files open.
struct cache_flushed_alert final : torrent_alert { static constexpr alert_category_t static_category = alert_category::storage; };[report issue]
lsd_peer_alert
Declared in "libtorrent/alert_types.hpp"
This alert is generated when we receive a local service discovery message from a peer for a torrent we're currently participating in.
struct lsd_peer_alert final : peer_alert { std::string message () const override; static constexpr alert_category_t static_category = alert_category::peer; };[report issue]
trackerid_alert
Declared in "libtorrent/alert_types.hpp"
This alert is posted whenever a tracker responds with a trackerid. The tracker ID is like a cookie. libtorrent will store the tracker ID for this tracker and repeat it in subsequent announces.
struct trackerid_alert final : tracker_alert { std::string message () const override; char const* tracker_id () const; static constexpr alert_category_t static_category = alert_category::status; };[report issue]
dht_bootstrap_alert
Declared in "libtorrent/alert_types.hpp"
This alert is posted when the initial DHT bootstrap is done.
struct dht_bootstrap_alert final : alert { std::string message () const override; static constexpr alert_category_t static_category = alert_category::dht; };[report issue]
torrent_error_alert
Declared in "libtorrent/alert_types.hpp"
This is posted whenever a torrent is transitioned into the error state.
struct torrent_error_alert final : torrent_alert { std::string message () const override; char const* filename () const; static constexpr alert_category_t static_category = alert_category::error | alert_category::status; error_code const error; };[report issue]
filename()
char const* filename () const;
the filename (or object) the error occurred on.
[report issue]- error
- specifies which error the torrent encountered.
torrent_need_cert_alert
Declared in "libtorrent/alert_types.hpp"
This is always posted for SSL torrents. This is a reminder to the client that the torrent won't work unless torrent_handle::set_ssl_certificate() is called with a valid certificate. Valid certificates MUST be signed by the SSL certificate in the .torrent file.
struct torrent_need_cert_alert final : torrent_alert { std::string message () const override; static constexpr alert_category_t static_category = alert_category::status; };[report issue]
incoming_connection_alert
Declared in "libtorrent/alert_types.hpp"
The incoming connection alert is posted every time we successfully accept an incoming connection, through any mean. The most straight-forward ways of accepting incoming connections are through the TCP listen socket and the UDP listen socket for uTP sockets. However, connections may also be accepted through a Socks5 or i2p listen socket, or via an SSL listen socket.
struct incoming_connection_alert final : alert { std::string message () const override; static constexpr alert_category_t static_category = alert_category::peer; int const socket_type; aux::noexcept_movable<tcp::endpoint> endpoint; };[report issue]
- socket_type
tells you what kind of socket the connection was accepted as:
- none (no socket instantiated)
- TCP
- Socks5
- HTTP
- uTP
- i2p
- SSL/TCP
- SSL/Socks5
- HTTPS (SSL/HTTP)
- SSL/uTP
- endpoint
- is the IP address and port the connection came from.
add_torrent_alert
Declared in "libtorrent/alert_types.hpp"
This alert is always posted when a torrent was attempted to be added and contains the return status of the add operation. The torrent handle of the new torrent can be found as the handle member in the base class. If adding the torrent failed, error contains the error code.
struct add_torrent_alert final : torrent_alert { std::string message () const override; static constexpr alert_category_t static_category = alert_category::status; add_torrent_params params; error_code error; };[report issue]
- params
- a copy of the parameters used when adding the torrent, it can be used to identify which invocation to async_add_torrent() caused this alert.
- error
- set to the error, if one occurred while adding the torrent.
state_update_alert
Declared in "libtorrent/alert_types.hpp"
This alert is only posted when requested by the user, by calling session::post_torrent_updates() on the session. It contains the torrent status of all torrents that changed since last time this message was posted. Its category is status_notification, but it's not subject to filtering, since it's only manually posted anyway.
struct state_update_alert final : alert { state_update_alert (aux::stack_allocator& alloc , std::vector<torrent_status> st); std::string message () const override; static constexpr alert_category_t static_category = alert_category::status; std::vector<torrent_status> status; };[report issue]
- status
- contains the torrent status of all torrents that changed since last time this message was posted. Note that you can map a torrent status to a specific torrent via its handle member. The receiving end is suggested to have all torrents sorted by the torrent_handle or hashed by it, for efficient updates.
session_stats_alert
Declared in "libtorrent/alert_types.hpp"
The session_stats_alert is posted when the user requests session statistics by calling post_session_stats() on the session object. Its category is status_notification, but it is not subject to filtering, since it's only manually posted anyway.
the message() member function returns a string representation of the values that properly match the line returned in session_stats_header_alert::message().
this specific output is parsed by tools/parse_session_stats.py if this is changed, that parser should also be changed
struct session_stats_alert final : alert { std::string message () const override; span<std::int64_t const> counters () const; static constexpr alert_category_t static_category = alert_category::stats; };[report issue]
counters()
span<std::int64_t const> counters () const;
An array are a mix of counters and gauges, which meanings can be queries via the session_stats_metrics() function on the session. The mapping from a specific metric to an index into this array is constant for a specific version of libtorrent, but may differ for other versions. The intended usage is to request the mapping, i.e. call session_stats_metrics(), once on startup, and then use that mapping to interpret these values throughout the process' runtime.
For more information, see the session statistics section.
[report issue]dht_error_alert
Declared in "libtorrent/alert_types.hpp"
posted when something fails in the DHT. This is not necessarily a fatal error, but it could prevent proper operation
struct dht_error_alert final : alert { std::string message () const override; static constexpr alert_category_t static_category = alert_category::error | alert_category::dht; error_code error; operation_t op; };[report issue]
- error
- the error code
- op
- the operation that failed
dht_immutable_item_alert
Declared in "libtorrent/alert_types.hpp"
this alert is posted as a response to a call to session::get_item(), specifically the overload for looking up immutable items in the DHT.
struct dht_immutable_item_alert final : alert { std::string message () const override; static constexpr alert_category_t static_category = alert_category::dht; sha1_hash target; entry item; };[report issue]
- target
- the target hash of the immutable item. This must match the SHA-1 hash of the bencoded form of item.
- item
- the data for this item
dht_mutable_item_alert
Declared in "libtorrent/alert_types.hpp"
this alert is posted as a response to a call to session::get_item(), specifically the overload for looking up mutable items in the DHT.
struct dht_mutable_item_alert final : alert { std::string message () const override; static constexpr alert_category_t static_category = alert_category::dht; std::array<char, 32> key; std::array<char, 64> signature; std::int64_t seq; std::string salt; entry item; bool authoritative; };[report issue]
- key
- the public key that was looked up
- signature
- the signature of the data. This is not the signature of the plain encoded form of the item, but it includes the sequence number and possibly the hash as well. See the dht_store document for more information. This is primarily useful for echoing back in a store request.
- seq
- the sequence number of this item
- salt
- the salt, if any, used to lookup and store this item. If no salt was used, this is an empty string
- item
- the data for this item
- authoritative
- the last response for mutable data is authoritative.
dht_put_alert
Declared in "libtorrent/alert_types.hpp"
this is posted when a DHT put operation completes. This is useful if the client is waiting for a put to complete before shutting down for instance.
struct dht_put_alert final : alert { std::string message () const override; static constexpr alert_category_t static_category = alert_category::dht; sha1_hash target; std::array<char, 32> public_key; std::array<char, 64> signature; std::string salt; std::int64_t seq; int num_success; };[report issue]
- target
- the target hash the item was stored under if this was an immutable item.
- public_key signature salt seq
- if a mutable item was stored, these are the public key, signature, salt and sequence number the item was stored under.
- num_success
- DHT put operation usually writes item to k nodes, maybe the node is stale so no response, or the node doesn't support 'put', or the token for write is out of date, etc. num_success is the number of successful responses we got from the puts.
i2p_alert
Declared in "libtorrent/alert_types.hpp"
this alert is used to report errors in the i2p SAM connection
struct i2p_alert final : alert { std::string message () const override; static constexpr alert_category_t static_category = alert_category::error; error_code error; };[report issue]
- error
- the error that occurred in the i2p SAM connection
dht_outgoing_get_peers_alert
Declared in "libtorrent/alert_types.hpp"
This alert is generated when we send a get_peers request It belongs to the dht_notification category.
struct dht_outgoing_get_peers_alert final : alert { std::string message () const override; static constexpr alert_category_t static_category = alert_category::dht; sha1_hash info_hash; sha1_hash obfuscated_info_hash; aux::noexcept_movable<udp::endpoint> endpoint; };[report issue]
- info_hash
- the info_hash of the torrent we're looking for peers for.
- obfuscated_info_hash
- if this was an obfuscated lookup, this is the info-hash target actually sent to the node.
- endpoint
- the endpoint we're sending this query to
log_alert
Declared in "libtorrent/alert_types.hpp"
This alert is posted by some session wide event. Its main purpose is trouble shooting and debugging. It's not enabled by the default alert mask and is enabled by the alert_category::session_log bit. Furthermore, it's by default disabled as a build configuration.
struct log_alert final : alert { std::string message () const override; char const* log_message () const; static constexpr alert_category_t static_category = alert_category::session_log; };[report issue]
torrent_log_alert
Declared in "libtorrent/alert_types.hpp"
This alert is posted by torrent wide events. It's meant to be used for trouble shooting and debugging. It's not enabled by the default alert mask and is enabled by the alert_category::torrent_log bit. By default it is disabled as a build configuration.
struct torrent_log_alert final : torrent_alert { std::string message () const override; char const* log_message () const; static constexpr alert_category_t static_category = alert_category::torrent_log; };[report issue]
peer_log_alert
Declared in "libtorrent/alert_types.hpp"
This alert is posted by events specific to a peer. It's meant to be used for trouble shooting and debugging. It's not enabled by the default alert mask and is enabled by the alert_category::peer_log bit. By default it is disabled as a build configuration.
struct peer_log_alert final : peer_alert { std::string message () const override; char const* log_message () const; enum direction_t { incoming_message, outgoing_message, incoming, outgoing, info, }; static constexpr alert_category_t static_category = alert_category::peer_log; char const* event_type; direction_t direction; };[report issue]
enum direction_t
Declared in "libtorrent/alert_types.hpp"
| name | value | description |
|---|---|---|
| incoming_message | 0 | |
| outgoing_message | 1 | |
| incoming | 2 | |
| outgoing | 3 | |
| info | 4 |
- event_type
- string literal indicating the kind of event. For messages, this is the message name.
lsd_error_alert
Declared in "libtorrent/alert_types.hpp"
posted if the local service discovery socket fails to start properly. it's categorized as error_notification.
struct lsd_error_alert final : alert { std::string message () const override; static constexpr alert_category_t static_category = alert_category::error; error_code error; };[report issue]
- error
- The error code
dht_lookup
Declared in "libtorrent/alert_types.hpp"
holds statistics about a current dht_lookup operation. a DHT lookup is the traversal of nodes, looking up a set of target nodes in the DHT for retrieving and possibly storing information in the DHT
struct dht_lookup { char const* type; int outstanding_requests; int timeouts; int responses; int branch_factor; int nodes_left; int last_sent; int first_timeout; sha1_hash target; };[report issue]
- type
- string literal indicating which kind of lookup this is
- outstanding_requests
- the number of outstanding request to individual nodes this lookup has right now
- timeouts
- the total number of requests that have timed out so far for this lookup
- responses
- the total number of responses we have received for this lookup so far for this lookup
- branch_factor
- the branch factor for this lookup. This is the number of nodes we keep outstanding requests to in parallel by default. when nodes time out we may increase this.
- nodes_left
- the number of nodes left that could be queries for this lookup. Many of these are likely to be part of the trail while performing the lookup and would never end up actually being queried.
- last_sent
- the number of seconds ago the last message was sent that's still outstanding
- first_timeout
- the number of outstanding requests that have exceeded the short timeout and are considered timed out in the sense that they increased the branch factor
- target
- the node-id or info-hash target for this lookup
dht_stats_alert
Declared in "libtorrent/alert_types.hpp"
contains current DHT state. Posted in response to session::post_dht_stats().
struct dht_stats_alert final : alert { std::string message () const override; static constexpr alert_category_t static_category = alert_category::stats; std::vector<dht_lookup> active_requests; std::vector<dht_routing_bucket> routing_table; };[report issue]
- active_requests
- a vector of the currently running DHT lookups.
- routing_table
- contains information about every bucket in the DHT routing table.
incoming_request_alert
Declared in "libtorrent/alert_types.hpp"
posted every time an incoming request from a peer is accepted and queued up for being serviced. This alert is only posted if the alert_category::incoming_request flag is enabled in the alert mask.
struct incoming_request_alert final : peer_alert { std::string message () const override; static constexpr alert_category_t static_category = alert_category::incoming_request; peer_request req; };[report issue]
- req
- the request this peer sent to us
dht_log_alert
Declared in "libtorrent/alert_types.hpp"
debug logging of the DHT when dht_log_notification is set in the alert mask.
struct dht_log_alert final : alert { std::string message () const override; char const* log_message () const; enum dht_module_t { tracker, node, routing_table, rpc_manager, traversal, }; static constexpr alert_category_t static_category = alert_category::dht_log; dht_module_t module; };[report issue]
enum dht_module_t
Declared in "libtorrent/alert_types.hpp"
| name | value | description |
|---|---|---|
| tracker | 0 | |
| node | 1 | |
| routing_table | 2 | |
| rpc_manager | 3 | |
| traversal | 4 |
- module
- the module, or part, of the DHT that produced this log message.
dht_pkt_alert
Declared in "libtorrent/alert_types.hpp"
This alert is posted every time a DHT message is sent or received. It is only posted if the alert_category::dht_log alert category is enabled. It contains a verbatim copy of the message.
struct dht_pkt_alert final : alert { std::string message () const override; span<char const> pkt_buf () const; enum direction_t { incoming, outgoing, }; static constexpr alert_category_t static_category = alert_category::dht_log; direction_t direction; aux::noexcept_movable<udp::endpoint> node; };[report issue]
pkt_buf()
span<char const> pkt_buf () const;
returns a pointer to the packet buffer and size of the packet, respectively. This buffer is only valid for as long as the alert itself is valid, which is owned by libtorrent and reclaimed whenever pop_alerts() is called on the session.
[report issue]enum direction_t
Declared in "libtorrent/alert_types.hpp"
| name | value | description |
|---|---|---|
| incoming | 0 | |
| outgoing | 1 |
- direction
- whether this is an incoming or outgoing packet.
- node
- the DHT node we received this packet from, or sent this packet to (depending on direction).
dht_get_peers_reply_alert
Declared in "libtorrent/alert_types.hpp"
Posted when we receive a response to a DHT get_peers request.
struct dht_get_peers_reply_alert final : alert { std::string message () const override; int num_peers () const; std::vector<tcp::endpoint> peers () const; static constexpr alert_category_t static_category = alert_category::dht_operation; sha1_hash info_hash; };[report issue]
dht_direct_response_alert
Declared in "libtorrent/alert_types.hpp"
This is posted exactly once for every call to session_handle::dht_direct_request. If the request failed, response() will return a default constructed bdecode_node.
struct dht_direct_response_alert final : alert { std::string message () const override; dht_direct_response_alert (aux::stack_allocator& alloc, void* userdata , udp::endpoint const& addr); bdecode_node response () const; static constexpr alert_category_t static_category = alert_category::dht; void const* userdata; aux::noexcept_movable<udp::endpoint> endpoint; };[report issue]
dht_direct_response_alert() message()
std::string message () const override; dht_direct_response_alert (aux::stack_allocator& alloc, void* userdata , udp::endpoint const& addr);
for when there was a timeout so we don't have a response
[report issue]picker_log_alert
Declared in "libtorrent/alert_types.hpp"
this is posted when one or more blocks are picked by the piece picker, assuming the verbose piece picker logging is enabled (see picker_log_notification).
struct picker_log_alert final : peer_alert { std::string message () const override; std::vector<piece_block> blocks () const; static constexpr alert_category_t static_category = alert_category::picker_log; static constexpr picker_flags_t partial_ratio = 0_bit; static constexpr picker_flags_t prioritize_partials = 1_bit; static constexpr picker_flags_t rarest_first_partials = 2_bit; static constexpr picker_flags_t rarest_first = 3_bit; static constexpr picker_flags_t reverse_rarest_first = 4_bit; static constexpr picker_flags_t suggested_pieces = 5_bit; static constexpr picker_flags_t prio_sequential_pieces = 6_bit; static constexpr picker_flags_t sequential_pieces = 7_bit; static constexpr picker_flags_t reverse_pieces = 8_bit; static constexpr picker_flags_t time_critical = 9_bit; static constexpr picker_flags_t random_pieces = 10_bit; static constexpr picker_flags_t prefer_contiguous = 11_bit; static constexpr picker_flags_t reverse_sequential = 12_bit; static constexpr picker_flags_t backup1 = 13_bit; static constexpr picker_flags_t backup2 = 14_bit; static constexpr picker_flags_t end_game = 15_bit; static constexpr picker_flags_t extent_affinity = 16_bit; picker_flags_t const picker_flags; };[report issue]
- picker_flags
- this is a bitmask of which features were enabled for this particular pick. The bits are defined in the picker_flags_t enum.
session_error_alert
Declared in "libtorrent/alert_types.hpp"
this alert is posted when the session encounters a serious error, potentially fatal
struct session_error_alert final : alert { std::string message () const override; static constexpr alert_category_t static_category = alert_category::error; error_code const error; };[report issue]
- error
- The error code, if one is associated with this error
dht_live_nodes_alert
Declared in "libtorrent/alert_types.hpp"
posted in response to a call to session::dht_live_nodes(). It contains the live nodes from the DHT routing table of one of the DHT nodes running locally.
struct dht_live_nodes_alert final : alert { std::string message () const override; int num_nodes () const; std::vector<std::pair<sha1_hash, udp::endpoint>> nodes () const; static constexpr alert_category_t static_category = alert_category::dht; sha1_hash node_id; };[report issue]
nodes() num_nodes()
int num_nodes () const; std::vector<std::pair<sha1_hash, udp::endpoint>> nodes () const;
the number of nodes in the routing table and the actual nodes.
[report issue]- node_id
- the local DHT node's node-ID this routing table belongs to
session_stats_header_alert
Declared in "libtorrent/alert_types.hpp"
The session_stats_header alert is posted the first time post_session_stats() is called
the message() member function returns a string representation of the header that properly match the stats values string returned in session_stats_alert::message().
this specific output is parsed by tools/parse_session_stats.py if this is changed, that parser should also be changed
struct session_stats_header_alert final : alert { std::string message () const override; static constexpr alert_category_t static_category = alert_category::stats; };[report issue]
dht_sample_infohashes_alert
Declared in "libtorrent/alert_types.hpp"
posted as a response to a call to session::dht_sample_infohashes() with the information from the DHT response message.
struct dht_sample_infohashes_alert final : alert { std::string message () const override; std::vector<sha1_hash> samples () const; int num_samples () const; int num_nodes () const; std::vector<std::pair<sha1_hash, udp::endpoint>> nodes () const; static constexpr alert_category_t static_category = alert_category::dht_operation; aux::noexcept_movable<udp::endpoint> endpoint; time_duration const interval; int const num_infohashes; };[report issue]
num_samples() samples()
std::vector<sha1_hash> samples () const; int num_samples () const;
returns the number of info-hashes returned by the node, as well as the actual info-hashes. num_samples() is more efficient than samples().size().
[report issue]nodes()
std::vector<std::pair<sha1_hash, udp::endpoint>> nodes () const;
This is the set of more DHT nodes returned by the request.
The information is included so that indexing nodes can perform a key space traversal with a single RPC per node by adjusting the target value for each RPC.
[report issue]- endpoint
- the node the request was sent to (and this response was received from)
- interval
- the interval to wait before making another request to this node
- num_infohashes
- This field indicates how many info-hash keys are currently in the node's storage. If the value is larger than the number of returned samples it indicates that the indexer may obtain additional samples after waiting out the interval.
block_uploaded_alert
Declared in "libtorrent/alert_types.hpp"
This alert is posted when a block intended to be sent to a peer is placed in the send buffer. Note that if the connection is closed before the send buffer is sent, the alert may be posted without the bytes having been sent to the peer. It belongs to the upload_notification category.
struct block_uploaded_alert final : peer_alert { std::string message () const override; int const block_index; piece_index_t const piece_index; };[report issue]
alerts_dropped_alert
Declared in "libtorrent/alert_types.hpp"
this alert is posted to indicate to the client that some alerts were dropped. Dropped meaning that the alert failed to be delivered to the client. The most common cause of such failure is that the internal alert queue grew too big (controlled by alert_queue_size).
struct alerts_dropped_alert final : alert { std::string message () const override; static constexpr alert_category_t static_category = alert_category::error; std::bitset<num_alert_types> dropped_alerts; };[report issue]
- dropped_alerts
- a bitmask indicating which alerts were dropped. Each bit represents the alert type ID, where bit 0 represents whether any alert of type 0 has been dropped, and so on.
socks5_alert
Declared in "libtorrent/alert_types.hpp"
this alert is posted with SOCKS5 related errors, when a SOCKS5 proxy is configured. It's enabled with the error_notification alert category.
struct socks5_alert final : alert { std::string message () const override; static constexpr alert_category_t static_category = alert_category::error; error_code error; operation_t op; aux::noexcept_movable<tcp::endpoint> ip; };[report issue]
- error
- the error
- op
- the operation that failed
- ip
- the endpoint configured as the proxy
alert_cast()
Declared in "libtorrent/alert.hpp"
template <class T> T* alert_cast (alert* a); template <class T> T const* alert_cast (alert const* a);
When you get an alert, you can use alert_cast<> to attempt to cast the pointer to a specific alert type, in order to query it for more information.
Note
alert_cast<> can only cast to an exact alert type, not a base class
operation_name()
Declared in "libtorrent/operations.hpp"
char const* operation_name (operation_t op);
maps an operation id (from peer_error_alert and peer_disconnected_alert) to its name. See operation_t for the constants
[report issue]enum operation_t
Declared in "libtorrent/operations.hpp"
| name | value | description |
|---|---|---|
| unknown | 0 | the error was unexpected and it is unknown which operation caused it |
| bittorrent | 1 | this is used when the bittorrent logic determines to disconnect |
| iocontrol | 2 | a call to iocontrol failed |
| getpeername | 3 | a call to getpeername() failed (querying the remote IP of a connection) |
| getname | 4 | a call to getname failed (querying the local IP of a connection) |
| alloc_recvbuf | 5 | an attempt to allocate a receive buffer failed |
| alloc_sndbuf | 6 | an attempt to allocate a send buffer failed |
| file_write | 7 | writing to a file failed |
| file_read | 8 | reading from a file failed |
| file | 9 | a non-read and non-write file operation failed |
| sock_write | 10 | a socket write operation failed |
| sock_read | 11 | a socket read operation failed |
| sock_open | 12 | a call to open(), to create a socket socket failed |
| sock_bind | 13 | a call to bind() on a socket failed |
| available | 14 | an attempt to query the number of bytes available to read from a socket failed |
| encryption | 15 | a call related to bittorrent protocol encryption failed |
| connect | 16 | an attempt to connect a socket failed |
| ssl_handshake | 17 | establishing an SSL connection failed |
| get_interface | 18 | a connection failed to satisfy the bind interface setting |
| sock_listen | 19 | a call to listen() on a socket |
| sock_bind_to_device | 20 | a call to the ioctl to bind a socket to a specific network device or adapter |
| sock_accept | 21 | a call to accept() on a socket |
| parse_address | 22 | convert a string into a valid network address |
| enum_if | 23 | enumeration network devices or adapters |
| file_stat | 24 | invoking stat() on a file |
| file_copy | 25 | copying a file |
| file_fallocate | 26 | allocating storage for a file |
| file_hard_link | 27 | creating a hard link |
| file_remove | 28 | removing a file |
| file_rename | 29 | renaming a file |
| file_open | 30 | opening a file |
| mkdir | 31 | creating a directory |
| check_resume | 32 | check fast resume data against files on disk |
| exception | 33 | an unknown exception |
| alloc_cache_piece | 34 | allocate space for a piece in the cache |
| partfile_move | 35 | move a part-file |
| partfile_read | 36 | read from a part file |
| partfile_write | 37 | write to a part-file |
| hostname_lookup | 38 | a hostname lookup |
| symlink | 39 | create or read a symlink |
| handshake | 40 | handshake with a peer or server |
| sock_option | 41 | set socket option |
| enum_route | 42 | enumeration network routes |
enum socket_type_t
Declared in "libtorrent/alert_types.hpp"
| name | value | description |
|---|---|---|
| tcp | 0 | |
| tcp_ssl | 1 | |
| udp | 2 | |
| i2p | 3 | |
| socks5 | 4 | |
| utp_ssl | 5 |
int
Declared in "libtorrent/alert_types.hpp"
- user_alert_id
- user defined alerts should use IDs greater than this
- num_alert_types
- this constant represents "max_alert_index" + 1
alert_category_t
Declared in "libtorrent/alert.hpp"
- error
Enables alerts that report an error. This includes:
- tracker errors
- tracker warnings
- file errors
- resume data failures
- web seed errors
- .torrent files errors
- listen socket errors
- port mapping errors
- peer
- Enables alerts when peers send invalid requests, get banned or snubbed.
- port_mapping
- Enables alerts for port mapping events. For NAT-PMP and UPnP.
- storage
- Enables alerts for events related to the storage. File errors and synchronization events for moving the storage, renaming files etc.
- tracker
- Enables all tracker events. Includes announcing to trackers, receiving responses, warnings and errors.
- connect
- Low level alerts for when peers are connected and disconnected.
- status
- Enables alerts for when a torrent or the session changes state.
- ip_block
- Alerts when a peer is blocked by the ip blocker or port blocker.
- performance_warning
- Alerts when some limit is reached that might limit the download or upload rate.
- dht
- Alerts on events in the DHT node. For incoming searches or bootstrapping being done etc.
- stats
- If you enable these alerts, you will receive a stats_alert approximately once every second, for every active torrent. These alerts contain all statistics counters for the interval since the lasts stats alert.
- session_log
- Enables debug logging alerts. These are available unless libtorrent was built with logging disabled (TORRENT_DISABLE_LOGGING). The alerts being posted are log_alert and are session wide.
- torrent_log
- Enables debug logging alerts for torrents. These are available unless libtorrent was built with logging disabled (TORRENT_DISABLE_LOGGING). The alerts being posted are torrent_log_alert and are torrent wide debug events.
- peer_log
- Enables debug logging alerts for peers. These are available unless libtorrent was built with logging disabled (TORRENT_DISABLE_LOGGING). The alerts being posted are peer_log_alert and low-level peer events and messages.
- incoming_request
- enables the incoming_request_alert.
- dht_log
- enables dht_log_alert, debug logging for the DHT
- dht_operation
- enable events from pure dht operations not related to torrents
- port_mapping_log
- enables port mapping log events. This log is useful for debugging the UPnP or NAT-PMP implementation
- picker_log
- enables verbose logging from the piece picker.
- file_progress
- alerts when files complete downloading
- piece_progress
- alerts when pieces complete downloading or fail hash check
- upload
- alerts when we upload blocks to other peers
- block_progress
- alerts on individual blocks being requested, downloading, finished, rejected, time-out and cancelled. This is likely to post alerts at a high rate.
- all
The full bitmask, representing all available categories.
since the enum is signed, make sure this isn't interpreted as -1. For instance, boost.python does that and fails when assigning it to an unsigned parameter.
| Author: | Arvid Norberg<EMAIL_ADDRESS>|
|---|---|
| Version: | 1.2.6 |
Filter
[report issue]ip_filter
Declared in "libtorrent/ip_filter.hpp"
The ip_filter class is a set of rules that uniquely categorizes all ip addresses as allowed or disallowed. The default constructor creates a single rule that allows all addresses (<IP_ADDRESS> - <IP_ADDRESS> for the IPv4 range, and the equivalent range covering all addresses for the IPv6 range).
A default constructed ip_filter does not filter any address.
struct ip_filter { void add_rule (address const& first, address const& last, std::uint32_t flags); std::uint32_t access (address const& addr) const; filter_tuple_t export_filter () const; enum access_flags { blocked, }; };[report issue]
add_rule()
void add_rule (address const& first, address const& last, std::uint32_t flags);
Adds a rule to the filter. first and last defines a range of ip addresses that will be marked with the given flags. The flags can currently be 0, which means allowed, or ip_filter::blocked, which means disallowed.
precondition: first.is_v4() == last.is_v4() && first.is_v6() == last.is_v6()
postcondition: access(x) == flags for every x in the range [first, last]
This means that in a case of overlapping ranges, the last one applied takes precedence.
[report issue]access()
std::uint32_t access (address const& addr) const;
Returns the access permissions for the given address (addr). The permission can currently be 0 or ip_filter::blocked. The complexity of this operation is O(log n), where n is the minimum number of non-overlapping ranges to describe the current filter.
[report issue]export_filter()
filter_tuple_t export_filter () const;
This function will return the current state of the filter in the minimum number of ranges possible. They are sorted from ranges in low addresses to high addresses. Each entry in the returned vector is a range with the access control specified in its flags field.
The return value is a tuple containing two range-lists. One for IPv4 addresses and one for IPv6 addresses.
[report issue]enum access_flags
Declared in "libtorrent/ip_filter.hpp"
| name | value | description |
|---|---|---|
| blocked | 1 | indicates that IPs in this range should not be connected to nor accepted as incoming connections |
port_filter
Declared in "libtorrent/ip_filter.hpp"
the port filter maps non-overlapping port ranges to flags. This is primarily used to indicate whether a range of ports should be connected to or not. The default is to have the full port range (0-65535) set to flag 0.
class port_filter { void add_rule (std::uint16_t first, std::uint16_t last, std::uint32_t flags); std::uint32_t access (std::uint16_t port) const; enum access_flags { blocked, }; };[report issue]
add_rule()
void add_rule (std::uint16_t first, std::uint16_t last, std::uint32_t flags);
set the flags for the specified port range (first, last) to flags overwriting any existing rule for those ports. The range is inclusive, i.e. the port last also has the flag set on it.
[report issue]access()
std::uint32_t access (std::uint16_t port) const;
test the specified port (port) for whether it is blocked or not. The returned value is the flags set for this port. see access_flags.
[report issue]enum access_flags
Declared in "libtorrent/ip_filter.hpp"
| name | value | description |
|---|---|---|
| blocked | 1 | this flag indicates that destination ports in the range should not be connected to |
| Author: | Arvid Norberg<EMAIL_ADDRESS>|
|---|---|
| Version: | 1.2.6 |
Settings
You have some control over session configuration through the session::apply_settings() member function. To change one or more configuration options, create a settings_pack object and fill it with the settings to be set and pass it in to session::apply_settings().
The settings_pack object is a collection of settings updates that are applied to the session when passed to session::apply_settings(). It's empty when constructed.
You have control over proxy and authorization settings and also the user-agent that will be sent to the tracker. The user-agent will also be used to identify the client with other peers.
Each configuration option is named with an enum value inside the settings_pack class. These are the available settings:
| name | type | default |
|---|---|---|
| user_agent | string | libtorrent/ |
this is the client identification to the tracker. The recommended format of this string is: "client-name/client-version libtorrent/libtorrent-version". This name will not only be used when making HTTP requests, but also when sending extended headers to peers that support that extension. It may not contain r or n
| name | type | default |
|---|---|---|
| announce_ip | string | nullptr |
announce_ip is the ip address passed along to trackers as the &ip= parameter. If left as the default, that parameter is omitted.
Note
This setting is only meant for very special cases where a seed is running on the same host as the tracker, and the tracker accepts the IP parameter (which normal trackers don't). Do not set this option unless you also control the tracker.
| name | type | default |
|---|---|---|
| handshake_client_version | string | nullptr |
this is the client name and version identifier sent to peers in the handshake message. If this is an empty string, the user_agent is used instead
| name | type | default |
|---|---|---|
| outgoing_interfaces | string |
This controls which IP address outgoing TCP connections are bound to, in addition to controlling whether such connections are also bound to a specific network interface/adapter (bind-to-device). This string is a comma-separated list of IP addresses and interface names. An empty string will not bind TCP sockets to a device, and let the network stack assign the local address. A list of names will be used to bind outgoing TCP sockets in a round-robin fashion. An IP address will simply be used to bind() the socket. An interface name will attempt to bind the socket to that interface. If that fails, or is unsupported, one of the IP addresses configured for that interface is used to bind() the socket to. If the interface or adapter doesn't exist, the outgoing connection will failed with an error message suggesting the device cannot be found. Adapter names on Unix systems are of the form "eth0", "eth1", "tun0", etc. This may be useful for clients that are multi-homed. Binding an outgoing connection to a local IP does not necessarily make the connection via the associated NIC/Adapter.
| name | type | default |
|---|---|---|
| listen_interfaces | string | <IP_ADDRESS>:6881,[::]:6881 |
a comma-separated list of (IP or device name, port) pairs. These are the listen ports that will be opened for accepting incoming uTP and TCP connections. These are also used for outgoing uTP and UDP tracker connections and DHT nodes.
It is possible to listen on multiple interfaces and multiple ports. Binding to port 0 will make the operating system pick the port.
Note
There are reasons to stick to the same port across sessions, which would mean only using port 0 on the first start, and recording the port that was picked for subsequent startups. Trackers, the DHT and other peers will remember the port they see you use and hand that port out to other peers trying to connect to you, as well as trying to connect to you themselves.
A port that has an "s" suffix will accept SSL connections. (note that SSL sockets are not enabled by default).
A port that has an "l" suffix will be considered a local network. i.e. it's assumed to only be able to reach hosts in the same local network as the IP address (based on the netmask associated with the IP, queried from the operating system).
if binding fails, the listen_failed_alert is posted. Once a socket binding succeeds (if it does), the listen_succeeded_alert is posted. There may be multiple failures before a success.
If a device name that does not exist is configured, no listen socket will be opened for that interface. If this is the only interface configured, it will be as if no listen ports are configured.
If no listen ports are configured (e.g. listen_interfaces is an empty string), networking will be disabled. No DHT will start, no outgoing uTP or tracker connections will be made. No incoming TCP or uTP connections will be accepted. (outgoing TCP connections will still be possible, depending on settings_pack::outgoing_interfaces).
For example: [::1]:8888 - will only accept connections on the IPv6 loopback address on port 8888.
eth0:4444,eth1:4444 - will accept connections on port 4444 on any IP address bound to device eth0 or eth1.
[::]:0s - will accept SSL connections on a port chosen by the OS. And not accept non-SSL connections at all.
<IP_ADDRESS>:6881,[::]:6881 - binds to all interfaces on port 6881.
<IP_ADDRESS>:6881l - binds to the local IP address, port 6881, but only allow talking to peers on the same local network. The netmask is queried from the operating system. Interfaces marked l are not announced to trackers, unless the tracker is also on the same local network.
Windows OS network adapter device name must be specified with GUID. It can be obtained from "netsh lan show interfaces" command output. GUID must be uppercased string embraced in curly brackets. {E4F0B674-0DFC-48BB-98A5-2AA730BDB6D6}::7777 - will accept connections on port 7777 on adapter with this GUID.
For more information, see the Multi-homed hosts section.
| name | type | default |
|---|---|---|
| proxy_hostname | string |
when using a proxy, this is the hostname where the proxy is running see proxy_type. Note that when using a proxy, the settings_pack::listen_interfaces setting is overridden and only a single interface is created, just to contact the proxy. This means a proxy cannot be combined with SSL torrents or multiple listen interfaces. This proxy listen interface will not accept incoming TCP connections, will not map ports with any gateway and will not enable local service discovery. All traffic is supposed to be channeled through the proxy.
| name | type | default |
|---|---|---|
| proxy_username | string | |
| proxy_password | string |
when using a proxy, these are the credentials (if any) to use when connecting to it. see proxy_type
| name | type | default |
|---|---|---|
| i2p_hostname | string |
sets the i2p SAM bridge to connect to. set the port with the i2p_port setting.
| name | type | default |
|---|---|---|
| peer_fingerprint | string | -LT1260- |
this is the fingerprint for the client. It will be used as the prefix to the peer_id. If this is 20 bytes (or longer) it will be truncated to 20 bytes and used as the entire peer-id
There is a utility function, generate_fingerprint() that can be used to generate a standard client peer ID fingerprint prefix.
| name | type | default |
|---|---|---|
| dht_bootstrap_nodes | string | dht.libtorrent.org:25401 |
This is a comma-separated list of IP port-pairs. They will be added to the DHT node (if it's enabled) as back-up nodes in case we don't know of any.
Changing these after the DHT has been started may not have any effect until the DHT is restarted.
| name | type | default |
|---|---|---|
| allow_multiple_connections_per_ip | bool | false |
determines if connections from the same IP address as existing connections should be rejected or not. Rejecting multiple connections from the same IP address will prevent abusive behavior by peers. The logic for determining whether connections are to the same peer is more complicated with this enabled, and more likely to fail in some edge cases. It is not recommended to enable this feature.
| name | type | default |
|---|---|---|
| send_redundant_have | bool | true |
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.
| name | type | default |
|---|---|---|
| use_dht_as_fallback | bool | false |
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. If this is false, the DHT is used regardless of if the trackers fail or not.
| name | type | default |
|---|---|---|
| use_parole_mode | bool | true |
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.
| name | type | default |
|---|---|---|
| use_read_cache | bool | true |
enable and disable caching of blocks read from disk. the purpose of the read cache is partly read-ahead of requests but also to avoid reading blocks back from the disk multiple times for popular pieces.
| name | type | default |
|---|---|---|
| coalesce_reads | bool | false |
| coalesce_writes | bool | false |
allocate separate, contiguous, buffers for read and write calls. Only used where writev/readv cannot be used will use more RAM but may improve performance
| name | type | default |
|---|---|---|
| auto_manage_prefer_seeds | bool | false |
if true, prefer seeding torrents when determining which torrents to give active slots to. If false, give preference to downloading torrents
| name | type | default |
|---|---|---|
| dont_count_slow_torrents | bool | true |
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.
| name | type | default |
|---|---|---|
| close_redundant_connections | bool | true |
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.
| name | type | default |
|---|---|---|
| prioritize_partial_pieces | bool | false |
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.
| name | type | default |
|---|---|---|
| rate_limit_ip_overhead | bool | true |
if set to true, the estimated TCP/IP overhead is drained from the rate limiters, to avoid exceeding the limits with the total traffic
| name | type | default |
|---|---|---|
| announce_to_all_tiers | bool | false |
| announce_to_all_trackers | bool | false |
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.
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. To be compliant with the Multi-tracker specification, set it to false.
| name | type | default |
|---|---|---|
| prefer_udp_trackers | bool | true |
prefer_udp_trackers: true 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 false means that the tracker's tier is respected and there's no preference of one protocol over another.
| name | type | default |
|---|---|---|
| disable_hash_checks | bool | false |
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)
| name | type | default |
|---|---|---|
| allow_i2p_mixed | bool | false |
if this is true, i2p torrents are allowed to also get peers from other sources than the tracker, and connect to regular IPs, not providing any anonymization. This may be useful if the user is not interested in the anonymization of i2p, but still wants to be able to connect to i2p peers.
| name | type | default |
|---|---|---|
| volatile_read_cache | bool | false |
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.
| name | type | default |
|---|---|---|
| no_atime_storage | bool | true |
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.
| name | type | default |
|---|---|---|
| incoming_starts_queued_torrents | bool | false |
incoming_starts_queued_torrents. 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.
| name | type | default |
|---|---|---|
| report_true_downloaded | bool | false |
when set to true, the downloaded counter sent to trackers will include the actual number of payload bytes downloaded including redundant bytes. If set to false, it will not include any redundancy bytes
| name | type | default |
|---|---|---|
| strict_end_game_mode | bool | true |
strict_end_game_mode controls when a block may be requested twice. If this is true, a block may only be requested twice when there's at 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.
| name | type | default |
|---|---|---|
| enable_outgoing_utp | bool | true |
| enable_incoming_utp | bool | true |
| enable_outgoing_tcp | bool | true |
| enable_incoming_tcp | bool | true |
when set to true, libtorrent will try to make outgoing utp connections controls whether libtorrent will accept incoming connections or make outgoing connections of specific type.
| name | type | default |
|---|---|---|
| no_recheck_incomplete_resume | bool | false |
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. If false, any existing files will be checked. By setting this setting to true, the files won't be checked, but will go straight to download mode.
| name | type | default |
|---|---|---|
| anonymous_mode | bool | false |
anonymous_mode: When set to true, the client tries to hide its identity to a certain degree. The user-agent will be reset to an empty string (except for private torrents). Trackers will only be used if they are using a proxy server. 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). Since no incoming connections are accepted, NAT-PMP, UPnP, DHT and local peer discovery are all turned off when this setting is enabled.
If you're using I2P, it might make sense to enable anonymous mode as well.
| name | type | default |
|---|---|---|
| report_web_seed_downloads | bool | true |
specifies whether downloads from web seeds is reported to the tracker or not. Turning it off also excludes web seed traffic from other stats and download rate reporting via the libtorrent API.
| name | type | default |
|---|---|---|
| seeding_outgoing_connections | bool | true |
seeding_outgoing_connections determines if seeding (and finished) torrents should attempt to make outgoing connections or not. 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.
| name | type | default |
|---|---|---|
| no_connect_privileged_ports | bool | false |
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
| name | type | default |
|---|---|---|
| smooth_connects | bool | true |
smooth_connects 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 connect in batches, and timing them out in batches.
| name | type | default |
|---|---|---|
| always_send_user_agent | bool | false |
always send user-agent in every web seed request. If false, only the first request per http connection will include the user agent
| name | type | default |
|---|---|---|
| apply_ip_filter_to_trackers | bool | true |
apply_ip_filter_to_trackers 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.
| name | type | default |
|---|---|---|
| ban_web_seeds | bool | true |
when true, web seeds sending bad data will be banned
| name | type | default |
|---|---|---|
| allow_partial_disk_writes | bool | true |
when set to false, the write_cache_line_size will apply across piece boundaries. this is a bad idea unless the piece picker also is configured to have an affinity to pick pieces belonging to the same write cache line as is configured in the disk cache.
| name | type | default |
|---|---|---|
| support_share_mode | bool | true |
if false, prevents libtorrent to advertise share-mode support
| name | type | default |
|---|---|---|
| support_merkle_torrents | bool | true |
if this is false, don't advertise support for the Tribler merkle tree piece message
| name | type | default |
|---|---|---|
| report_redundant_bytes | bool | true |
if this is true, the number of redundant bytes is sent to the tracker
| name | type | default |
|---|---|---|
| listen_system_port_fallback | bool | true |
if this is true, libtorrent will fall back to listening on a port chosen by the operating system (i.e. binding to port 0). If a failure is preferred, set this to false.
| name | type | default |
|---|---|---|
| announce_crypto_support | bool | true |
when this is true, and incoming encrypted connections are enabled, &supportcrypt=1 is included in http tracker announces
| name | type | default |
|---|---|---|
| enable_upnp | bool | true |
Starts and stops the UPnP service. When started, the listen port and the DHT port are attempted to be forwarded on local UPnP router devices.
The upnp object returned by start_upnp() can be used to add and remove arbitrary port mappings. Mapping status is returned through the portmap_alert and the portmap_error_alert. The object will be valid until stop_upnp() is called. See upnp and nat pmp.
| name | type | default |
|---|---|---|
| enable_natpmp | bool | true |
Starts and stops the NAT-PMP service. When started, the listen port and the DHT port are attempted to be forwarded on the router through NAT-PMP.
The natpmp object returned by start_natpmp() can be used to add and remove arbitrary port mappings. Mapping status is returned through the portmap_alert and the portmap_error_alert. The object will be valid until stop_natpmp() is called. See upnp and nat pmp.
| name | type | default |
|---|---|---|
| enable_lsd | bool | true |
Starts and stops Local Service Discovery. This service will broadcast the info-hashes of all the non-private torrents on the local network to look for peers on the same swarm within multicast reach.
| name | type | default |
|---|---|---|
| enable_dht | bool | true |
starts the dht node and makes the trackerless service available to torrents.
| name | type | default |
|---|---|---|
| prefer_rc4 | bool | false |
if the allowed encryption level is both, setting this to true will prefer RC4 if both methods are offered, plain text otherwise
| name | type | default |
|---|---|---|
| proxy_hostnames | bool | true |
if true, hostname lookups are done via the configured proxy (if any). This is only supported by SOCKS5 and HTTP.
| name | type | default |
|---|---|---|
| proxy_peer_connections | bool | true |
if true, peer connections are made (and accepted) over the configured proxy, if any. Web seeds as well as regular bittorrent peer connections are considered "peer connections". Anything transporting actual torrent payload (trackers and DHT traffic are not considered peer connections).
| name | type | default |
|---|---|---|
| auto_sequential | bool | true |
if this setting is true, torrents with a very high availability of pieces (and seeds) are downloaded sequentially. This is more efficient for the disk I/O. With many seeds, the download order is unlikely to matter anyway
| name | type | default |
|---|---|---|
| proxy_tracker_connections | bool | true |
if true, tracker connections are made over the configured proxy, if any.
| name | type | default |
|---|---|---|
| enable_ip_notifier | bool | true |
Starts and stops the internal IP table route changes notifier.
The current implementation supports multiple platforms, and it is recommended to have it enable, but you may want to disable it if it's supported but unreliable, or if you have a better way to detect the changes. In the later case, you should manually call session_handle::reopen_network_sockets to ensure network changes are taken in consideration.
| name | type | default |
|---|---|---|
| dht_prefer_verified_node_ids | bool | true |
when this is true, nodes whose IDs are derived from their source IP according to BEP 42 are preferred in the routing table.
| name | type | default |
|---|---|---|
| piece_extent_affinity | bool | false |
when this is true, create an affinity for downloading 4 MiB extents of adjacent pieces. This is an attempt to achieve better disk I/O throughput by downloading larger extents of bytes, for torrents with small piece sizes
| name | type | default |
|---|---|---|
| validate_https_trackers | bool | false |
when set to true, the certificate of HTTPS trackers will be validated against the system's certificate store (as defined by OpenSSL). If the system does not have one, enabling this may cause HTTPS trackers to fail.
| name | type | default |
|---|---|---|
| tracker_completion_timeout | int | 30 |
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.
| name | type | default |
|---|---|---|
| tracker_receive_timeout | int | 10 |
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.
| name | type | default |
|---|---|---|
| stop_tracker_timeout | int | 5 |
stop_tracker_timeout is the number of seconds 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. If the value is set to 0, the connections to trackers with the stopped event are suppressed.
| name | type | default |
|---|---|---|
| tracker_maximum_response_length | int | 1024*1024 |
this is the maximum number of bytes in a tracker response. If a response size passes this number of bytes 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 megabytes, it will be interrupted before the entire response has been uncompressed (assuming the limit is lower than 2 MiB).
| name | type | default |
|---|---|---|
| piece_timeout | int | 20 |
the number of seconds from a request is sent until it times out if no piece response is returned.
| name | type | default |
|---|---|---|
| request_timeout | int | 60 |
the number of seconds one block (16 kiB) is expected to be received within. If it's not, the block is requested from a different peer
| name | type | default |
|---|---|---|
| request_queue_time | int | 3 |
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.
| name | type | default |
|---|---|---|
| max_allowed_in_request_queue | int | 500 |
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 sent) the last request will be dropped. the higher this is, the faster upload speeds the client can get to a single peer.
| name | type | default |
|---|---|---|
| max_out_request_queue | int | 500 |
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.
| name | type | default |
|---|---|---|
| whole_pieces_threshold | int | 20 |
if a whole piece can be downloaded in this number of seconds, or less, the peer_connection will prefer to request 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.
| name | type | default |
|---|---|---|
| peer_timeout | int | 120 |
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. 120 seconds is specified in the protocol specification. After half the time out, a keep alive message is sent.
| name | type | default |
|---|---|---|
| urlseed_timeout | int | 20 |
same as peer_timeout, but only applies to url-seeds. this is usually set lower, because web servers are expected to be more reliable.
| name | type | default |
|---|---|---|
| urlseed_pipeline_size | int | 5 |
controls the pipelining size of url and http seeds. i.e. the number of HTTP request to keep outstanding before waiting for the first one to complete. It's common for web servers to limit this to a relatively low number, like 5
| name | type | default |
|---|---|---|
| urlseed_wait_retry | int | 30 |
number of seconds until a new retry of a url-seed takes place. Default retry value for http-seeds that don't provide a valid retry-after header.
| name | type | default |
|---|---|---|
| file_pool_size | int | 40 |
sets 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.
| name | type | default |
|---|---|---|
| max_failcount | int | 3 |
max_failcount is the maximum times we try to connect to a peer before stop connecting again. If a peer succeeds, the failure counter is reset. If a peer is retrieved from a peer source (other than DHT) the failcount is decremented by one, allowing another try.
| name | type | default |
|---|---|---|
| min_reconnect_time | int | 60 |
the number of seconds to wait to reconnect to a peer. this time is multiplied with the failcount.
| name | type | default |
|---|---|---|
| peer_connect_timeout | int | 15 |
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. 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.
| name | type | default |
|---|---|---|
| connection_speed | int | 30 |
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.
| name | type | default |
|---|---|---|
| inactivity_timeout | int | 600 |
if a peer is uninteresting and uninterested for longer than this number of seconds, it will be disconnected.
| name | type | default |
|---|---|---|
| unchoke_interval | int | 15 |
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.
| name | type | default |
|---|---|---|
| optimistic_unchoke_interval | int | 30 |
optimistic_unchoke_interval is the number of seconds between each optimistic unchoke. On this timer, the currently optimistically unchoked peer will change.
| name | type | default |
|---|---|---|
| num_want | int | 200 |
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.
| name | type | default |
|---|---|---|
| initial_picker_threshold | int | 4 |
initial_picker_threshold specifies the number of pieces we need before we switch to rarest first picking. The first initial_picker_threshold pieces in any torrent are picked at random , the following pieces are picked in rarest first order.
| name | type | default |
|---|---|---|
| allowed_fast_set_size | int | 5 |
the number of allowed pieces to send to peers that supports the fast extensions
| name | type | default |
|---|---|---|
| suggest_mode | int | settings_pack::no_piece_suggestions |
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_suggestions which 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.
| name | type | default |
|---|---|---|
| max_queued_disk_bytes | int | 1024 * 1024 |
max_queued_disk_bytes is the 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 severely limit your download rate.
| name | type | default |
|---|---|---|
| handshake_timeout | int | 10 |
the number of seconds to wait for a handshake response from a peer. If no response is received within this time, the peer is disconnected.
| name | type | default |
|---|---|---|
| send_buffer_low_watermark | int | 10 * 1024 |
| send_buffer_watermark | int | 500 * 1024 |
| send_buffer_watermark_factor | int | 50 |
send_buffer_low_watermark the minimum send buffer target size (send buffer includes bytes pending being read from disk). For good and snappy seeding performance, set this fairly high, to 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
if the send buffer has fewer bytes than send_buffer_watermark, we'll read another 16 kiB 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.
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 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. 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.
| name | type | default |
|---|---|---|
| choking_algorithm | int | settings_pack::fixed_slots_choker |
| seed_choking_algorithm | int | settings_pack::round_robin |
choking_algorithm specifies which algorithm to use to determine how many peers to unchoke. The unchoking algorithm for downloading torrents is always "tit-for-tat", i.e. the peers we download the fastest from are unchoked.
The options for choking algorithms are:
- fixed_slots_choker is the traditional choker with a fixed number of unchoke slots (as specified by settings_pack::unchoke_slots_limit).
- 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.
seed_choking_algorithm controls the seeding unchoke behavior. i.e. How we select which peers to unchoke for seeding torrents. Since a seeding torrent isn't downloading anything, the tit-for-tat mechanism cannot be used. The available options are:
- round_robin which round-robins the peers that are unchoked when seeding. This distributes the upload bandwidth 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. This does not just take into account the pieces a peer is reporting having downloaded, but also the pieces we have sent to it.
| name | type | default |
|---|---|---|
| cache_size | int | 2048 |
| cache_expiry | int | 300 |
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 based on the amount of physical RAM on the machine. If the amount of physical RAM cannot be determined, it's set to 1024 (= 16 MiB).
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.
On 32 bit builds, the effective cache size will be limited to 3/4 of 2 GiB to avoid exceeding the virtual address space limit.
| name | type | default |
|---|---|---|
| disk_io_write_mode | int | settings_pack::enable_os_cache |
| disk_io_read_mode | int | settings_pack::enable_os_cache |
determines how files are opened when they're in read only mode versus read and write mode. The options are:
- enable_os_cache
- Files are opened normally, with the OS caching reads and writes.
- disable_os_cache
- This opens all files in no-cache mode. This corresponds to the OS not letting blocks for the files linger in the cache. This makes sense in order to avoid the bittorrent client to potentially evict all other processes' cache by simply handling high throughput and large files. If libtorrent's read cache is disabled, enabling this may reduce performance.
One reason to disable caching is that it may help the operating system from growing its file cache indefinitely.
| name | type | default |
|---|---|---|
| outgoing_port | int | 0 |
| num_outgoing_ports | int | 0 |
this is the first port to use for binding outgoing connections to. This is useful for users that have routers that allow QoS settings based on local port. when binding outgoing connections to specific ports, num_outgoing_ports is the size of the range. It should be more than a few
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.
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.
| name | type | default |
|---|---|---|
| peer_tos | int | 0x20 |
peer_tos determines the TOS byte set in the IP header of every packet sent to peers (including web seeds). 0x0 means no marking, 0x20 represents the QBone scavenger service. For more details, see QBSS.
| name | type | default |
|---|---|---|
| active_downloads | int | 3 |
| active_seeds | int | 5 |
| active_checking | int | 1 |
| active_dht_limit | int | 88 |
| active_tracker_limit | int | 1600 |
| active_lsd_limit | int | 60 |
| active_limit | int | 500 |
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_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 not counted against these limits.
active_checking is the limit of number of simultaneous checking torrents.
active_limit is a hard limit on the number of active (auto managed) torrents. This limit also applies to slow torrents.
active_dht_limit is the max number of torrents to announce to the DHT.
active_tracker_limit is the max number of torrents to announce to their trackers.
active_lsd_limit is the max number of torrents to announce to the local network over the local service discovery protocol.
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.
| name | type | default |
|---|---|---|
| auto_manage_interval | int | 30 |
auto_manage_interval is the number of seconds between the torrent queue is updated, and rotated.
| name | type | default |
|---|---|---|
| seed_time_limit | int | 24 * 60 * 60 |
this 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.
| name | type | default |
|---|---|---|
| auto_scrape_interval | int | 1800 |
| auto_scrape_min_interval | int | 300 |
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.
| name | type | default |
|---|---|---|
| max_peerlist_size | int | 3000 |
| max_paused_peerlist_size | int | 1000 |
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 can be used to save memory for paused torrents, since it's not as important for them to keep a large peer list.
| name | type | default |
|---|---|---|
| min_announce_interval | int | 5 * 60 |
this is the minimum allowed announce interval for a tracker. This is specified in seconds and is used as a sanity check on what is returned from a tracker. It mitigates hammering mis-configured trackers.
| name | type | default |
|---|---|---|
| auto_manage_startup | int | 60 |
this 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.
| name | type | default |
|---|---|---|
| seeding_piece_quota | int | 20 |
seeding_piece_quota is the number of pieces to send to a peer, when seeding, before rotating in another peer to the unchoke set.
| name | type | default |
|---|---|---|
| max_rejects | int | 50 |
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.
| name | type | default |
|---|---|---|
| recv_socket_buffer_size | int | 0 |
| send_socket_buffer_size | int | 0 |