Skip to content

Configuration

Configuration Guide

ccBitTorrent uses a comprehensive configuration system with TOML support, validation, hot-reload, and hierarchical loading from multiple sources.

Configuration system: ccbt/config/config.py:ConfigManager

Configuration Sources and Precedence

Configuration is loaded in this order (later sources override earlier ones):

  1. Defaults: Built-in sensible defaults from ccbt/models.py:Config
  2. Config File: ccbt.toml in current directory or ~/.config/ccbt/ccbt.toml. See ccbt/config/config.py:_find_config_file
  3. Environment Variables: CCBT_* prefixed variables. See env.example
  4. CLI Arguments: Command-line overrides. See ccbt/cli/main.py:_apply_cli_overrides
  5. Per-Torrent: Individual torrent settings (future feature)

Configuration loading: ccbt/config/config.py:_load_config

Configuration File

Default Configuration

Reference the default configuration file: ccbt.toml

The configuration is organized into sections:

Network Configuration

Network settings: ccbt.toml:4-43

Network config model: ccbt/models.py:NetworkConfig

Disk Configuration

Disk settings: ccbt.toml:57-96

Disk config model: ccbt/models.py:DiskConfig

Strategy Configuration

Strategy settings: ccbt.toml:99-114

Strategy config model: ccbt/models.py:StrategyConfig

Discovery Configuration

Discovery settings: ccbt.toml:116-136

  • DHT settings: ccbt.toml:118-125
  • PEX settings: ccbt.toml:128-129
  • Tracker settings: ccbt.toml:132-135
  • tracker_announce_interval: Tracker announce interval in seconds (default: 1800.0, range: 60.0-86400.0)
  • tracker_scrape_interval: Tracker scrape interval in seconds for periodic scraping (default: 3600.0, range: 60.0-86400.0)
  • tracker_auto_scrape: Automatically scrape trackers when torrents are added (BEP 48) (default: false)
  • Environment variables: CCBT_TRACKER_ANNOUNCE_INTERVAL, CCBT_TRACKER_SCRAPE_INTERVAL, CCBT_TRACKER_AUTO_SCRAPE

Discovery config model: ccbt/models.py:DiscoveryConfig

Limits Configuration

Rate limits: ccbt.toml:138-152

Limits config model: ccbt/models.py:LimitsConfig

Observability Configuration

Observability settings: ccbt.toml:154-171

Observability config model: ccbt/models.py:ObservabilityConfig

Security Configuration

Security settings: ccbt.toml:173-178

Security config model: ccbt/models.py:SecurityConfig

Encryption Configuration

ccBitTorrent supports BEP 3 Message Stream Encryption (MSE) and Protocol Encryption (PE) for secure peer connections.

Encryption Settings:

  • enable_encryption (bool, default: false): Enable protocol encryption support
  • encryption_mode (str, default: "preferred"): Encryption mode
    • "disabled": No encryption (plain connections only)
    • "preferred": Attempt encryption, fallback to plain if unavailable
    • "required": Encryption mandatory, connection fails if encryption unavailable
  • encryption_dh_key_size (int, default: 768): Diffie-Hellman key size in bits (768 or 1024)
  • encryption_prefer_rc4 (bool, default: true): Prefer RC4 cipher for compatibility with older clients
  • encryption_allowed_ciphers (list[str], default: ["rc4", "aes"]): Allowed cipher types
    • "rc4": RC4 stream cipher (most compatible)
    • "aes": AES cipher in CFB mode (more secure)
    • "chacha20": ChaCha20 cipher (not yet implemented)
  • encryption_allow_plain_fallback (bool, default: true): Allow fallback to plain connection if encryption fails (only applies when encryption_mode is "preferred")

Environment Variables:

  • CCBT_ENABLE_ENCRYPTION: Enable/disable encryption (true/false)
  • CCBT_ENCRYPTION_MODE: Encryption mode (disabled/preferred/required)
  • CCBT_ENCRYPTION_DH_KEY_SIZE: DH key size (768 or 1024)
  • CCBT_ENCRYPTION_PREFER_RC4: Prefer RC4 (true/false)
  • CCBT_ENCRYPTION_ALLOWED_CIPHERS: Comma-separated list (e.g., "rc4,aes")
  • CCBT_ENCRYPTION_ALLOW_PLAIN_FALLBACK: Allow plain fallback (true/false)

Example Configuration:

[security]
enable_encryption = true
encryption_mode = "preferred"
encryption_dh_key_size = 768
encryption_prefer_rc4 = true
encryption_allowed_ciphers = ["rc4", "aes"]
encryption_allow_plain_fallback = true

Security Considerations:

  1. RC4 Compatibility: RC4 is supported for compatibility but is cryptographically weak. Use AES for better security when possible.
  2. DH Key Size: 768-bit DH keys provide adequate security for most use cases. 1024-bit provides stronger security but increases handshake latency.
  3. Encryption Modes:
  4. preferred: Best for compatibility - attempts encryption but falls back gracefully
  5. required: Most secure but may fail to connect with peers that don't support encryption
  6. Performance Impact: Encryption adds minimal overhead (~1-5% for RC4, ~2-8% for AES) but improves privacy and helps avoid traffic shaping.

Implementation Details:

Encryption implementation: ccbt/security/encryption.py:EncryptionManager

ML Configuration

Machine learning settings: ccbt.toml:180-183

ML config model: ccbt/models.py:MLConfig

Dashboard Configuration

Dashboard settings: ccbt.toml:185-191

Dashboard config model: ccbt/models.py:DashboardConfig

Environment Variables

Environment variables use the CCBT_ prefix and follow a hierarchical naming scheme.

Reference: env.example

Format: CCBT_<SECTION>_<OPTION>=<value>

Examples: - Network: env.example:10-58 - Disk: env.example:62-102 - Strategy: env.example:106-121 - Discovery: env.example:125-141 - Observability: env.example:145-162 - Limits: env.example:166-180 - Security: env.example:184-189 - ML: env.example:193-196

Environment variable parsing: ccbt/config/config.py:_get_env_config

Configuration Schema

Configuration schema and validation: ccbt/config/config_schema.py

The schema defines: - Field types and constraints - Default values - Validation rules - Documentation

Configuration Capabilities

Configuration capabilities and feature detection: ccbt/config/config_capabilities.py

Configuration Templates

Predefined configuration templates: ccbt/config/config_templates.py

Templates for: - High-performance setup - Low-resource setup - Security-focused setup - Development setup

Configuration Examples

Example configurations are available in the examples/ directory:

Hot Reload

Configuration hot-reload support: ccbt/config/config.py:ConfigManager

The configuration system supports hot-reloading changes without restarting the client.

Configuration Migration

Configuration migration utilities: ccbt/config/config_migration.py

Tools for migrating between configuration versions.

Configuration Backup and Diff

Configuration management utilities: - Backup: ccbt/config/config_backup.py - Diff: ccbt/config/config_diff.py

Conditional Configuration

Conditional configuration support: ccbt/config/config_conditional.py

Tips and Best Practices

Performance Tuning

  • Increase disk.write_buffer_kib for large sequential writes: ccbt.toml:64
  • Enable direct_io on Linux/NVMe for better write throughput: ccbt.toml:81
  • Tune network.pipeline_depth and network.block_size_kib for your network: ccbt.toml:11-13

Resource Optimization

  • Adjust disk.hash_workers based on CPU cores: ccbt.toml:70
  • Configure disk.cache_size_mb based on available RAM: ccbt.toml:78
  • Set network.max_global_peers based on bandwidth: ccbt.toml:6

Network Configuration

For detailed performance tuning, see Performance Tuning Guide.