Struct Settings

Source

pub struct Settings {Show 138 fields
    pub listen_port: u16,
    pub download_dir: PathBuf,
    pub max_torrents: usize,
    pub resume_data_dir: Option<PathBuf>,
    pub save_resume_interval_secs: u64,
    pub enable_dht: bool,
    pub enable_pex: bool,
    pub enable_lsd: bool,
    pub enable_fast_extension: bool,
    pub enable_utp: bool,
    pub enable_upnp: bool,
    pub enable_natpmp: bool,
    pub enable_ipv6: bool,
    pub enable_web_seed: bool,
    pub enable_holepunch: bool,
    pub enable_bep40_eviction: bool,
    pub encryption_mode: EncryptionMode,
    pub anonymous_mode: bool,
    pub external_ip: Option<IpAddr>,
    pub seed_ratio_limit: Option<f64>,
    pub default_super_seeding: bool,
    pub default_share_mode: bool,
    pub upload_only_announce: bool,
    pub upload_rate_limit: u64,
    pub download_rate_limit: u64,
    pub tcp_upload_rate_limit: u64,
    pub tcp_download_rate_limit: u64,
    pub utp_upload_rate_limit: u64,
    pub utp_download_rate_limit: u64,
    pub auto_upload_slots: bool,
    pub auto_upload_slots_min: usize,
    pub auto_upload_slots_max: usize,
    pub mixed_mode_algorithm: MixedModeAlgorithm,
    pub active_downloads: i32,
    pub active_seeds: i32,
    pub active_limit: i32,
    pub active_checking: i32,
    pub dont_count_slow_torrents: bool,
    pub inactive_down_rate: u64,
    pub inactive_up_rate: u64,
    pub auto_manage_interval: u64,
    pub auto_manage_startup: u64,
    pub auto_manage_prefer_seeds: bool,
    pub alert_mask: AlertCategory,
    pub alert_channel_size: usize,
    pub smart_ban_max_failures: u32,
    pub smart_ban_parole: bool,
    pub disk_io_threads: usize,
    pub max_blocking_threads: usize,
    pub storage_mode: StorageMode,
    pub preallocate_mode: Option<PreallocateMode>,
    pub disk_cache_size: usize,
    pub disk_write_cache_ratio: f32,
    pub disk_channel_capacity: usize,
    pub buffer_pool_capacity: usize,
    pub enable_mlock: bool,
    pub io_uring_sq_depth: u32,
    pub io_uring_direct_io: bool,
    pub filesystem_direct_io: bool,
    pub io_uring_batch_threshold: usize,
    pub iocp_concurrent_threads: u32,
    pub iocp_direct_io: bool,
    pub hashing_threads: usize,
    pub max_request_queue_depth: usize,
    pub initial_queue_depth: usize,
    pub request_queue_time: f64,
    pub block_request_timeout_secs: u32,
    pub max_concurrent_stream_reads: usize,
    pub auto_sequential: bool,
    pub strict_end_game: bool,
    pub max_web_seeds: usize,
    pub initial_picker_threshold: u32,
    pub whole_pieces_threshold: u32,
    pub snub_timeout_secs: u32,
    pub readahead_pieces: u32,
    pub streaming_timeout_escalation: bool,
    pub steal_threshold_ratio: f64,
    pub use_block_stealing: bool,
    pub steal_stale_piece_secs: u64,
    pub steal_threshold_endgame: f64,
    pub min_pipeline_depth: u32,
    pub max_pipeline_depth: u32,
    pub target_buffer_secs: f64,
    pub fixed_pipeline_depth: usize,
    pub piece_extent_affinity: bool,
    pub suggest_mode: bool,
    pub max_suggest_pieces: usize,
    pub predictive_piece_announce_ms: u64,
    pub proxy: ProxyConfig,
    pub force_proxy: bool,
    pub apply_ip_filter_to_trackers: bool,
    pub dht_queries_per_second: usize,
    pub dht_query_timeout_secs: u64,
    pub dht_enforce_node_id: bool,
    pub dht_restrict_routing_ips: bool,
    pub dht_max_items: usize,
    pub dht_item_lifetime_secs: u64,
    pub dht_sample_infohashes_interval: u64,
    pub dht_read_only: bool,
    pub upnp_lease_duration: u32,
    pub natpmp_lifetime: u32,
    pub utp_max_connections: usize,
    pub enable_i2p: bool,
    pub i2p_hostname: String,
    pub i2p_port: u16,
    pub i2p_inbound_quantity: u8,
    pub i2p_outbound_quantity: u8,
    pub i2p_inbound_length: u8,
    pub i2p_outbound_length: u8,
    pub allow_i2p_mixed: bool,
    pub ssl_listen_port: u16,
    pub ssl_cert_path: Option<PathBuf>,
    pub ssl_key_path: Option<PathBuf>,
    pub seed_choking_algorithm: SeedChokingAlgorithm,
    pub choking_algorithm: ChokingAlgorithm,
    pub max_peers_per_torrent: usize,
    pub peer_read_timeout_secs: u64,
    pub peer_write_timeout_secs: u64,
    pub data_contribution_timeout_secs: u64,
    pub choke_rotation_max_evictions: u32,
    pub max_concurrent_connects: u16,
    pub connect_soft_timeout: u64,
    pub ssrf_mitigation: bool,
    pub allow_idna: bool,
    pub validate_https_trackers: bool,
    pub max_metadata_size: u64,
    pub max_message_size: usize,
    pub max_piece_length: u64,
    pub max_outstanding_requests: usize,
    pub max_in_flight_pieces: usize,
    pub peer_connect_timeout: u64,
    pub peer_dscp: u8,
    pub stats_report_interval: u64,
    pub runtime_worker_threads: usize,
    pub pin_cores: bool,
    pub lock_warn_threshold_ms: u64,
    pub dht_saved_nodes: Vec<String>,
    pub dht_node_id: Option<Id20>,
}

Expand description

Unified session settings (replaces SessionConfig).

All 56 configurable fields in a single strongly-typed struct. Supports presets via factory functions and runtime mutation via SessionHandle::apply_settings().

Fields§

§listen_port: u16

TCP listen port for incoming peer connections (default: 42020).

§download_dir: PathBuf

Default download directory for new torrents (default: “.”).

§max_torrents: usize

Maximum number of concurrent torrents (default: 100).

§resume_data_dir: Option<PathBuf>

Directory for fast-resume data files. If None, resume data is not persisted.

§save_resume_interval_secs: u64

Interval in seconds between periodic resume file saves (0 = disabled). Default: 300 (5 minutes).

§enable_dht: bool

Enable Kademlia DHT peer discovery (BEP 5). Default: true.

§enable_pex: bool

Enable Peer Exchange (BEP 11). Default: true.

§enable_lsd: bool

Enable Local Service Discovery via multicast (BEP 14). Default: true.

§enable_fast_extension: bool

Enable BEP 6 Fast Extension (AllowedFast, HaveAll, HaveNone, Reject, SuggestPiece). Default: true.

§enable_utp: bool

Enable uTP (BEP 29) micro transport protocol. When enabled, outbound connections try uTP first with a 5-second timeout before falling back to TCP. Default: true.

§enable_upnp: bool

Enable UPnP IGD port mapping (last resort after PCP and NAT-PMP). Default: true.

§enable_natpmp: bool

Enable NAT-PMP (RFC 6886) and PCP (RFC 6887) port mapping. PCP is tried first, then NAT-PMP as fallback. Default: true.

§enable_ipv6: bool

Enable IPv6 dual-stack support (BEP 7, 24). Binds listeners on both IPv4 and IPv6, starts a second DHT instance, and processes IPv6 peers in PEX and tracker responses. Default: true.

§enable_web_seed: bool

Enable HTTP/web seeding (BEP 19 GetRight, BEP 17 Hoffman). Torrents with url-list or httpseeds download pieces from HTTP servers alongside peer-to-peer transfers. Default: true.

§enable_holepunch: bool

Enable BEP 55 holepunch extension for NAT traversal. Advertises ut_holepunch in the extension handshake and can act as initiator, relay, or target for holepunch connections. Default: true.

§enable_bep40_eviction: bool

Enable BEP 40 canonical peer priority for connection eviction. When at capacity, incoming peers with higher deterministic priority can displace lower-priority ones. Default: true.

§encryption_mode: EncryptionMode

Connection encryption mode (MSE/PE). Default: Disabled.

§anonymous_mode: bool

Suppress identifying information (client version in BEP 10 handshake) and disable DHT, LSD, UPnP, and NAT-PMP. Default: false.

§external_ip: Option<IpAddr>

Manually configured external IP for BEP 40 peer priority. If not set, discovered automatically via NAT traversal.

§seed_ratio_limit: Option<f64>

Stop seeding when this upload/download ratio is reached. None = unlimited.

§default_super_seeding: bool

Enable BEP 16 super seeding for new torrents. Reveals pieces one-per-peer to maximize piece diversity across the swarm. Default: false.

§default_share_mode: bool

Default share mode for new torrents. When true, torrents relay pieces in memory without writing to disk. Requires fast extension (BEP 6).

§upload_only_announce: bool

Advertise upload-only status via extension handshake when a torrent transitions to seeding (BEP 21). Default: true.

§upload_rate_limit: u64

Global upload rate limit in bytes/sec (0 = unlimited).

§download_rate_limit: u64

Global download rate limit in bytes/sec (0 = unlimited).

§tcp_upload_rate_limit: u64

TCP upload rate limit in bytes/sec (0 = unlimited).

§tcp_download_rate_limit: u64

TCP download rate limit in bytes/sec (0 = unlimited).

§utp_upload_rate_limit: u64

uTP upload rate limit in bytes/sec (0 = unlimited).

§utp_download_rate_limit: u64

uTP download rate limit in bytes/sec (0 = unlimited).

§auto_upload_slots: bool

Automatically adjust the number of upload slots based on bandwidth. Default: true.

§auto_upload_slots_min: usize

Minimum number of automatic upload slots (default: 2).

§auto_upload_slots_max: usize

Maximum number of automatic upload slots (default: 20).

§mixed_mode_algorithm: MixedModeAlgorithm

Mixed-mode TCP/uTP bandwidth allocation algorithm.

§active_downloads: i32

Maximum concurrent auto-managed downloading torrents (-1 = unlimited, default: 3).

§active_seeds: i32

Maximum concurrent auto-managed seeding torrents (-1 = unlimited, default: 5).

§active_limit: i32

Hard cap on all active auto-managed torrents (-1 = unlimited, default: 500).

§active_checking: i32

Maximum concurrent hash-check operations (default: 1).

§dont_count_slow_torrents: bool

Exempt inactive torrents from download/seed limits. A torrent is inactive if its rate is below inactive_down_rate / inactive_up_rate. Default: true.

§inactive_down_rate: u64

Download rate threshold (bytes/sec) below which a torrent is considered inactive for queue management purposes (default: 2048).

§inactive_up_rate: u64

Upload rate threshold (bytes/sec) below which a torrent is considered inactive for queue management purposes (default: 2048).

§auto_manage_interval: u64

Interval in seconds between queue evaluations (default: 30).

§auto_manage_startup: u64

Grace period in seconds where a torrent is considered active regardless of speed after being started (default: 60).

§auto_manage_prefer_seeds: bool

Allocate seeding slots before download slots. Default: false.

§alert_mask: AlertCategory

Bitmask of alert categories to receive (default: ALL).

§alert_channel_size: usize

Capacity of the alert broadcast channel (default: 1024).

§smart_ban_max_failures: u32

Number of hash-failure involvements before a peer is auto-banned. Lower values ban faster but risk false positives (default: 3).

§smart_ban_parole: bool

Enable parole mode: re-download a failed piece from a single uninvolved peer to definitively attribute fault before striking. Default: true.

§disk_io_threads: usize

Number of concurrent disk I/O threads (default: 4).

§max_blocking_threads: usize

Maximum number of concurrent blocking I/O operations dispatched via block_in_place. Defaults to the number of available CPU cores.

§storage_mode: StorageMode

Storage allocation mode: Auto, FullPreallocate, or SparseFile (default: Auto).

§preallocate_mode: Option<PreallocateMode>

Override pre-allocation strategy (None/Sparse/Full). When None (default), derived from storage_mode: Full → PreallocateMode::Full, else → PreallocateMode::None.

§disk_cache_size: usize

Total ARC disk cache size in bytes (default: 16 MiB, minimum: 1 MiB).

§disk_write_cache_ratio: f32

Fraction of disk cache reserved for write buffering (0.0–1.0, default: 0.5).

§disk_channel_capacity: usize

Capacity of the async disk I/O command channel (default: 512).

§buffer_pool_capacity: usize

Unified buffer pool capacity in bytes (default: 64 MiB). Replaces disk_cache_size when set. Covers both write buffering and read cache.

§enable_mlock: bool

Lock cached piece data in physical memory (default: true on Unix). Prevents the OS from swapping out hot cache entries. Silently ignored if RLIMIT_MEMLOCK is exceeded.

§io_uring_sq_depth: u32

io_uring submission queue depth (number of SQEs). Only used when storage_mode is IoUring. Default: 256.

§io_uring_direct_io: bool

Enable O_DIRECT for io_uring writes, bypassing the kernel page cache. Unaligned writes fall back to regular pwritev. Default: false.

§filesystem_direct_io: bool

Enable direct I/O for filesystem storage (bypasses kernel page cache). Linux/FreeBSD: O_DIRECT, macOS: F_NOCACHE. Windows: use --iocp with --direct-io. Default: false.

§io_uring_batch_threshold: usize

Minimum number of file segments to batch before using io_uring. Below this threshold, pwritev may be cheaper. Default: 4.

§iocp_concurrent_threads: u32

IOCP concurrent thread count (0 = system default). Only used when storage_mode is Iocp. Default: 0.

§iocp_direct_io: bool

Enable FILE_FLAG_NO_BUFFERING for IOCP I/O, bypassing the OS page cache. Requires sector-aligned writes. Default: false.

§hashing_threads: usize

Number of concurrent piece hash verification threads (default: 2).

§max_request_queue_depth: usize

Maximum per-peer request queue depth (default: 250).

§initial_queue_depth: usize

Initial per-peer request queue depth (default: 128). Higher values let peers reach full throughput faster by skipping slow-start ramp-up.

§request_queue_time: f64

Request queue time multiplier in seconds (default: 3.0).

Deprecated: This field is retained for backward compatibility with existing config files. The pipeline now uses a fixed-depth model where queue depth equals initial_queue_depth for the lifetime of the connection; this value is no longer used in depth computation.

§block_request_timeout_secs: u32

Block request timeout in seconds before the request is considered lost and re-issued (default: 60).

§max_concurrent_stream_reads: usize

Maximum concurrent FileStream readers. Controls how many simultaneous file-streaming reads can proceed (default: 8).

§auto_sequential: bool

Automatically switch to sequential piece picking when too many partial pieces accumulate. Uses hysteresis (1.6x activate / 1.3x deactivate).

§strict_end_game: bool

In end-game mode, cancel duplicate requests when a piece completes. When false, both copies download — wastes bandwidth but finishes faster on unreliable peers. Default: true.

§max_web_seeds: usize

Maximum concurrent web seed connections per torrent (default: 4).

§initial_picker_threshold: u32

Completed piece count below which the picker uses random selection to promote piece diversity in the swarm. Default: 4.

§whole_pieces_threshold: u32

Seconds to download a piece — if a peer is faster, it gets exclusive assignment (no block splitting). Default: 20.

§snub_timeout_secs: u32

Seconds without data from a peer before marking it as snubbed. Snubbed peers get queue depth clamped to 1. Default: 60.

§readahead_pieces: u32

Number of pieces ahead of the streaming cursor to prioritize (default: 8).

§streaming_timeout_escalation: bool

Escalate streaming piece requests that exceed the mean RTT. Default: true.

§steal_threshold_ratio: f64

Steal blocks from peers this many times slower than the requesting peer (default: 10.0). Set to 0.0 to disable stealing.

§use_block_stealing: bool

Enable per-block stealing: fast peers can steal individual unrequested blocks from pieces reserved by slower peers (default: true).

§steal_stale_piece_secs: u64

Seconds between steal-queue population scans. Every N seconds, all in-flight pieces are pushed into the steal queue so fast peers can steal blocks mid-download (not just at endgame). 0 = disabled. Default: 2.

§steal_threshold_endgame: f64

M149: Steal threshold multiplier when >90% complete (endgame). Pieces taking longer than swarm_avg * this value are stolen. Default: 3.0.

§min_pipeline_depth: u32

M149: Minimum per-peer pipeline depth (requests in flight). Default: 16.

§max_pipeline_depth: u32

M149: Maximum per-peer pipeline depth (requests in flight). Default: 512.

§target_buffer_secs: f64

M149: Seconds of data to buffer in the pipeline per peer. Used to compute dynamic depth: depth = (download_rate / block_size) * target_buffer_secs.

§fixed_pipeline_depth: usize

Fixed per-peer pipeline depth (number of concurrent requests per peer). Replaces the old AIMD dynamic depth system. rqbit uses a fixed Semaphore(128) per peer — simpler and faster. This setting allows benchmarking different fixed depths. Default: 128.

§piece_extent_affinity: bool

Prefer pieces adjacent to those already downloaded for improved sequential disk access patterns (4 MiB extent groups). Default: true.

§suggest_mode: bool

Enable BEP 6 SuggestPiece: suggest newly verified pieces to peers that don’t have them, improving piece diversity in the swarm. Default: false.

§max_suggest_pieces: usize

Maximum SuggestPiece messages per peer to avoid flooding (default: 10).

§predictive_piece_announce_ms: u64

Predictive piece announce delay in milliseconds. When > 0, a Have message is sent before hash verification completes, reducing piece availability latency at the cost of a possible false announce. Default: 0 (disabled).

§proxy: ProxyConfig

Proxy configuration for peer and tracker connections. Default: no proxy.

§force_proxy: bool

Force all connections through the configured proxy. Disables listen sockets, UPnP, NAT-PMP, DHT, and LSD. Default: false.

§apply_ip_filter_to_trackers: bool

Check tracker IP addresses against the IP filter. When false, trackers are exempt from IP filtering. Default: true.

§dht_queries_per_second: usize

Maximum DHT queries per second to control network traffic (default: 50).

§dht_query_timeout_secs: u64

Timeout in seconds for a single DHT query before it is abandoned (default: 5).

§dht_enforce_node_id: bool

BEP 42: Enforce node ID verification in DHT routing table. Disabled by default: too many real DHT nodes lack BEP 42-compliant IDs.

§dht_restrict_routing_ips: bool

BEP 42: Restrict DHT routing table to one node per IP.

§dht_max_items: usize

Maximum number of BEP 44 items stored in the DHT (immutable + mutable).

§dht_item_lifetime_secs: u64

Lifetime of BEP 44 DHT items in seconds before expiry (default: 7200 = 2 hours).

§dht_sample_infohashes_interval: u64

Interval in seconds for periodic sample_infohashes queries (BEP 51). 0 = disabled (default). Non-zero enables background DHT indexing.

§dht_read_only: bool

BEP 43: Run DHT in read-only mode. Read-only nodes can query the DHT but do not store data or announce. Other nodes should not add us to their routing tables. Useful for resource-constrained clients.

§upnp_lease_duration: u32

UPnP lease duration in seconds (default: 3600).

§natpmp_lifetime: u32

NAT-PMP mapping lifetime in seconds (default: 7200).

§utp_max_connections: usize

Maximum concurrent uTP connections (default: 256).

§enable_i2p: bool

Enable I2P anonymous network support (requires SAM bridge).

§i2p_hostname: String

SAM bridge hostname (default: “127.0.0.1”).

§i2p_port: u16

SAM bridge port (default: 7656).

§i2p_inbound_quantity: u8

Number of inbound I2P tunnels (1-16, default: 3).

§i2p_outbound_quantity: u8

Number of outbound I2P tunnels (1-16, default: 3).

§i2p_inbound_length: u8

Number of hops in inbound I2P tunnels (0-7, default: 3).

§i2p_outbound_length: u8

Number of hops in outbound I2P tunnels (0-7, default: 3).

§allow_i2p_mixed: bool

Allow mixing I2P and clearnet peers in the same torrent. When false (default), I2P-enabled torrents only connect to I2P peers.

§ssl_listen_port: u16

SSL listen port for SSL torrent incoming connections. 0 = disabled (no SSL listener). When set, a TLS listener is bound on this port for torrents with ssl-cert in their info dict.

§ssl_cert_path: Option<PathBuf>

Path to the PEM-encoded certificate file for SSL torrent connections. If not set, a self-signed certificate is auto-generated on first use and stored in resume_data_dir (or a temp directory).

§ssl_key_path: Option<PathBuf>

Path to the PEM-encoded private key file for SSL torrent connections.

§seed_choking_algorithm: SeedChokingAlgorithm

Algorithm for ranking peers during seed-mode choking.

§choking_algorithm: ChokingAlgorithm

Algorithm for determining the number of unchoke slots.

§max_peers_per_torrent: usize

Maximum peer connections per torrent (default: 128).

§peer_read_timeout_secs: u64

M133: Seconds without any wire message before disconnecting a peer. Matches rqbit’s 10s read timeout. 0 = disabled. Default: 10.

§peer_write_timeout_secs: u64

M133: Seconds before a stalled outgoing write disconnects a peer. 0 = disabled. Default: 10.

§data_contribution_timeout_secs: u64

M137: Data contribution timeout — seconds without receiving a Piece message before disconnecting. Set to 0 to disable. Default: 60.

§choke_rotation_max_evictions: u32

M138: Maximum peers to evict per choke rotation tick (0 = disabled).

§max_concurrent_connects: u16

M138: Maximum concurrent outbound peer connections (throttles connect ramp).

§connect_soft_timeout: u64

M147: Seconds without TCP SYN-ACK before soft reap disconnects a connecting peer. Peers that have received SYN-ACK get the full peer_connect_timeout.

§ssrf_mitigation: bool

Enable SSRF mitigation: restrict localhost tracker paths, block public-to-private redirects, and reject query strings on local web seeds.

§allow_idna: bool

Allow internationalised (non-ASCII) domain names in tracker/web seed URLs.

§validate_https_trackers: bool

Require HTTPS for HTTP tracker announces (UDP trackers are unaffected).

§max_metadata_size: u64

Maximum BEP 9 metadata size in bytes that will be accepted from peers. Protects against OOM from peers claiming enormous metadata. Default: 4 MiB.

§max_message_size: usize

Maximum wire protocol message size in bytes. Messages exceeding this are rejected by the codec. Default: 16 MiB.

§max_piece_length: u64

Maximum accepted piece length when adding a torrent. Rejects torrents with piece sizes above this limit. Default: 32 MiB.

§max_outstanding_requests: usize

Maximum outstanding incoming requests per peer. When a peer sends more Request messages than this without them being served, excess requests are dropped. Default: 500.

§max_in_flight_pieces: usize

Maximum number of pieces simultaneously in-flight (downloaded but not yet verified). Caps memory usage for in-progress pieces. When the cap is reached, the piece selector only returns blocks from already-in-flight pieces. Default: 512.

§peer_connect_timeout: u64

Timeout in seconds for outbound TCP peer connections. Default 10. Set to 0 to use the OS default (~2 minutes on Linux).

§peer_dscp: u8

DSCP (Differentiated Services Code Point) value for peer traffic sockets. Applied to TCP listeners, outbound TCP connections, uTP sockets, and UDP tracker sockets. Default 0x08 (CS1/scavenger — low-priority background). Set to 0 to disable DSCP marking.

§stats_report_interval: u64

Interval in milliseconds between SessionStatsAlert emissions. Default 1000 (1 second). Set to 0 to disable periodic stats alerts.

§runtime_worker_threads: usize

Number of tokio worker threads. Default: min(available cores, 8). Set to 0 to use tokio’s default (= available_parallelism()).

§pin_cores: bool

Pin tokio worker threads to CPU cores for cache locality. Default: true.

§lock_warn_threshold_ms: u64

Warning threshold in milliseconds for lock hold duration. When a hot-path lock is held longer than this, a tracing warning is emitted. Set to 0 to disable timing entirely (zero overhead). Default: 50.

§dht_saved_nodes: Vec<String>

Previously saved DHT routing table nodes for fast bootstrap. These are prepended to the bootstrap node list on startup so that peer discovery starts instantly instead of bootstrapping from scratch. Runtime-injected, not serialized.

§dht_node_id: Option<Id20>

BEP 42-compliant DHT node ID from previous session. Reusing the same ID avoids routing table regeneration on every startup. Runtime-injected, not serialized.