Overview Configuration management commands help you work with TurkeyDPI configuration files without running the daemon. These commands validate syntax, check for errors, and generate template configurations.
Commands validate Validate a configuration file without starting the daemon.
turkeydpi validate < FIL E >
Path to configuration file to validate. Supported formats:
TOML (.toml)
JSON (.json)
Success Output: ✓ Configuration is valid: /etc/turkeydpi/config.toml
Error Output: ✗ Configuration error: missing field `enabled` at line 3 column 1
Exit codes:
0 - Configuration is valid1 - Configuration has errors
Validation Checks:
Syntax Validation
Verifies TOML/JSON syntax is correct
Schema Validation
Ensures all required fields are present
Type Validation
Checks field types match expected values
Value Validation
Validates ranges, enums, and constraints
Reference Validation
Checks rule references and transform types
Use cases:
Pre-deployment configuration testing
CI/CD pipeline validation
Debugging configuration errors
Learning configuration syntax
reload Reload daemon configuration from a file without restart.
Path to new configuration file. File is validated before reload. If validation fails, current config remains active.
Output: Error Output: Error: Failed to load config from /etc/turkeydpi/config.toml: invalid value for field 'priority'
Reload Process:
Validate new configuration file
If valid, send to daemon via control socket
Daemon applies new configuration
Existing flows continue with old config
New flows use new configuration
What Gets Reloaded:
Global settings (feature flags)
All rules and priorities
Transform parameters
Resource limits
What Doesn’t Change:
Proxy listen address (requires restart)
Socket path (requires restart)
Log level (requires restart)
Active flow table
Use cases:
Adjusting fragmentation parameters
Adding/removing rules
Changing transform settings
Tuning performance limits
Requirements:
Daemon must be running
Control socket must be accessible
New config must be valid
gen-config Generate an example configuration file with all options documented.
turkeydpi gen-config [OPTIONS]
Output format. Options:
toml - TOML format (default, recommended)json - JSON format Output file path. If not specified, prints to stdout. Examples:
-o config.toml--output /etc/turkeydpi/config.toml Examples: Generate TOML to stdout Output: [ global ] enabled = true enable_fragmentation = true enable_jitter = false enable_padding = true enable_header_normalization = true log_level = "info" json_logging = false [[ rules ]] name = "https-evasion" enabled = true priority = 100 dst_ports = [ 443 ] protocols = [ "tcp" ] transforms = [ "fragment" , "padding" ] [[ rules ]] name = "dns-protection" enabled = true priority = 90 dst_ports = [ 53 ] protocols = [ "udp" ] transforms = [ "padding" ] [ limits ] max_flows = 10000 max_queue_size = 1000 max_memory_mb = 128 max_jitter_ms = 500 flow_timeout_secs = 120 log_rate_limit = 100 [ transforms . fragment ] min_size = 1 max_size = 40 split_at_offset = 0 randomize = true [ transforms . resegment ] segment_size = 16 max_segments = 8 [ transforms . padding ] min_bytes = 0 max_bytes = 64 fill_byte = 0 [ transforms . jitter ] min_ms = 0 max_ms = 50 [ transforms . header ] normalize_ttl = false ttl_value = 64 normalize_window = false randomize_ip_id = true [ transforms . decoy ] send_before = false send_after = false ttl = 1 probability = 0.0
Generate JSON to file turkeydpi gen-config --format json --output config.json
Output: Configuration written to config.json
File contents (config.json): { "global" : { "enabled" : true , "enable_fragmentation" : true , "enable_jitter" : false , "enable_padding" : true , "enable_header_normalization" : true , "log_level" : "info" , "json_logging" : false }, "rules" : [ { "name" : "https-evasion" , "enabled" : true , "priority" : 100 , "match_criteria" : { "dst_ports" : [ 443 ], "protocols" : [ "tcp" ] }, "transforms" : [ "fragment" , "padding" ], "overrides" : {} }, { "name" : "dns-protection" , "enabled" : true , "priority" : 90 , "match_criteria" : { "dst_ports" : [ 53 ], "protocols" : [ "udp" ] }, "transforms" : [ "padding" ], "overrides" : {} } ], "limits" : { "max_flows" : 10000 , "max_queue_size" : 1000 , "max_memory_mb" : 128 , "max_jitter_ms" : 500 , "flow_timeout_secs" : 120 , "log_rate_limit" : 100 }, "transforms" : { "fragment" : { "min_size" : 1 , "max_size" : 40 , "split_at_offset" : null , "randomize" : true }, "resegment" : { "segment_size" : 16 , "max_segments" : 8 }, "padding" : { "min_bytes" : 0 , "max_bytes" : 64 , "fill_byte" : null }, "jitter" : { "min_ms" : 0 , "max_ms" : 50 }, "header" : { "normalize_ttl" : false , "ttl_value" : 64 , "normalize_window" : false , "randomize_ip_id" : true }, "decoy" : { "send_before" : false , "send_after" : false , "ttl" : 1 , "probability" : 0.0 } } }
Save and customize turkeydpi gen-config -o base-config.toml # Edit base-config.toml with your settings turkeydpi validate base-config.toml turkeydpi run --config base-config.toml --proxy
Configuration Structure The generated configuration includes these sections:
Global Settings [ global ] enabled = true # Master enable/disable enable_fragmentation = true # Enable fragmentation transform enable_jitter = false # Enable jitter/delay transform enable_padding = true # Enable padding transform enable_header_normalization = true # Enable header manipulation log_level = "info" # trace, debug, info, warn, error json_logging = false # JSON log output
Rules Define which traffic gets transformed:
[[ rules ]] name = "https-evasion" # Rule identifier enabled = true # Enable this rule priority = 100 # Higher = checked first dst_ports = [ 443 ] # Destination ports to match protocols = [ "tcp" ] # tcp, udp, icmp transforms = [ "fragment" , "padding" ] # Transform chain
Global defaults for each transform type:
Fragment [ transforms . fragment ] min_size = 1 # Minimum fragment size (bytes) max_size = 40 # Maximum fragment size (bytes) split_at_offset = 0 # Specific offset to split (0 = auto) randomize = true # Randomize fragment sizes
Padding [ transforms . padding ] min_bytes = 0 # Minimum padding (bytes) max_bytes = 64 # Maximum padding (bytes) fill_byte = 0 # Padding byte value (0-255, null = random)
Jitter [ transforms . jitter ] min_ms = 0 # Minimum delay (milliseconds) max_ms = 50 # Maximum delay (milliseconds)
[ transforms . header ] normalize_ttl = false # Normalize IP TTL ttl_value = 64 # TTL to set if normalizing normalize_window = false # Normalize TCP window randomize_ip_id = true # Randomize IP ID field
Decoy [ transforms . decoy ] send_before = false # Send decoy before real packet send_after = false # Send decoy after real packet ttl = 1 # Decoy packet TTL (expires quickly) probability = 0.0 # Probability of sending decoy (0.0-1.0)
Limits [ limits ] max_flows = 10000 # Maximum concurrent flows max_queue_size = 1000 # Packet queue size max_memory_mb = 128 # Memory limit max_jitter_ms = 500 # Maximum jitter delay flow_timeout_secs = 120 # Flow idle timeout log_rate_limit = 100 # Max log messages per second
Workflow Examples Development Workflow # 1. Generate base config turkeydpi gen-config -o dev-config.toml # 2. Edit configuration vim dev-config.toml # 3. Validate changes turkeydpi validate dev-config.toml # 4. Test with daemon turkeydpi run --config dev-config.toml --proxy # 5. Monitor effectiveness turkeydpi stats # 6. Adjust and reload vim dev-config.toml turkeydpi validate dev-config.toml turkeydpi reload dev-config.toml
CI/CD Pipeline # .gitlab-ci.yml validate-config : script : - turkeydpi validate production-config.toml only : - merge_requests deploy : script : - scp production-config.toml server:/etc/turkeydpi/ - ssh server 'turkeydpi validate /etc/turkeydpi/production-config.toml' - ssh server 'turkeydpi reload /etc/turkeydpi/production-config.toml' only : - main
Testing Different Presets #!/bin/bash # Test different fragmentation settings for MAX_SIZE in 10 20 40 80 ; do echo "Testing max_size= $MAX_SIZE " turkeydpi gen-config -o test.toml sed -i "s/max_size = 40/max_size = $MAX_SIZE /" test.toml turkeydpi validate test.toml turkeydpi reload test.toml sleep 30 # Test traffic turkeydpi stats | grep "Transformed" turkeydpi reset-stats done
Global Options Not used by config management commands.
Logging level for the command.
Output logs in JSON format.
--socket
path
default: "/tmp/turkeydpi.sock"
Control socket path (used by reload command).
Troubleshooting
Validation fails with syntax error
Check TOML/JSON syntax: Common TOML errors:
Missing quotes around strings
Incorrect array syntax (use [...] not (...))
Duplicate keys
Invalid escape sequences
Common JSON errors:
Trailing commas
Single quotes instead of double quotes
Missing commas between fields
Use a linter: # TOML taplo check config.toml # JSON jq . config.json
Reload fails with validation error
Validate first to see detailed error: turkeydpi validate /etc/turkeydpi/config.toml
Reasons:
Config file path is wrong
Changes don’t affect active flows (only new ones)
Daemon needs restart for some settings
Solution: # Check what changed turkeydpi status # For socket/listen changes, restart required systemctl restart turkeydpi
gen-config output is truncated
Redirect to file instead of viewing in terminal: turkeydpi gen-config -o config.toml cat config.toml
Configuration Best Practices
Version Control Store configs in git, use branches for testing: git checkout -b test-aggressive-fragment vim config.toml turkeydpi validate config.toml
Documentation Add comments explaining ISP-specific settings: # Türk Telekom blocks at SNI offset 2 max_size = 20
Testing Validate in CI before deployment: test : script : - turkeydpi validate config.toml
Monitoring Track effectiveness after changes: turkeydpi reload config.toml watch turkeydpi stats
See Also