tor-switch
Tor configuration and routing management for Kodachi OS
Version: 9.0.1 | Size: 7.5MB | Author: Warith Al Maawali
License: Proprietary | Website: https://digi77.com
File Information
| Property | Value |
|---|---|
| Binary Name | tor-switch |
| Version | 9.0.1 |
| Build Date | 2026-03-23T08:26:05.913948603Z |
| Rust Version | 1.82.0 |
| File Size | 7.5MB |
| JSON Data | View Raw JSON |
SHA256 Checksum
Features
| Feature | Description |
|---|---|
| Feature | Tor network management and configuration |
| Feature | Multi-instance Tor support |
| Feature | Exit node rotation and control |
| Feature | DNS leak prevention integration |
| Feature | Firewall rule management |
| Feature | HAProxy configuration for load balancing |
| Feature | Authentication and security verification |
| Feature | Comprehensive logging and monitoring |
Security Features
| Feature | Description |
|---|---|
| Authentication | Secure authentication with certificate pinning |
| Encryption | TLS 1.3 for all network communications |
| Inputvalidation | All inputs are validated and sanitized |
| Ratelimiting | Built-in rate limiting for network operations |
System Requirements
| Requirement | Value |
|---|---|
| OS | Linux (Debian-based) |
| Privileges | root/sudo for system operations |
| Dependencies | OpenSSL, libcurl |
Global Options
| Flag | Description |
|---|---|
-h, --help |
Print help information |
-v, --version |
Print version information |
-n, --info |
Display detailed information |
-e, --examples |
Show usage examples |
--json |
Output in JSON format |
--json-pretty |
Pretty-print JSON output with indentation |
--json-human |
Enhanced JSON output with improved formatting (like jq) |
--verbose |
Enable verbose output |
--quiet |
Suppress non-essential output |
--no-color |
Disable colored output |
--config <FILE> |
Use custom configuration file |
--timeout <SECS> |
Set timeout (default: 30) |
--retry <COUNT> |
Retry attempts (default: 3) |
Commands
Basic Operations
start-tor
Start Tor daemon
Usage:
stop-tor
Stop Tor daemon
Usage:
restart-tor
Restart Tor daemon
Usage:
Configuration
validate-torrc
Validate torrc configuration
Usage:
reload-tor-config
Reload Tor configuration
Usage:
reload-tor-config-all
Reload config for all instances
Usage:
backup-config
Backup configuration
Usage:
backup-config-all
Backup all configurations
Usage:
restore-config
Restore configuration
Usage:
restore-config-all
Restore all configurations
Usage:
list-backups
List configuration backups
Usage:
generate-new-tor-password
Generate new Tor control password
Usage:
generate-new-tor-password-all
Generate password for all instances
Usage:
clean-torrc-custom
Clean custom torrc file
Usage:
clean-torrc-custom-all
Clean custom torrc for all instances
Usage:
DNS Management
start-tor-dns-iptables
Start Tor DNS with iptables
Usage:
start-tor-dns-nftables
Start Tor DNS with nftables
Usage:
stop-tor-dns-iptables
Stop Tor DNS iptables
Usage:
stop-tor-dns-nftables
Stop Tor DNS nftables
Usage:
torrify-system-dns
Route DNS through Tor
Usage:
torrify-system-iptables-dns
Route DNS through Tor with iptables
Usage:
torrify-system-nftables-dns
Route DNS through Tor with nftables
Usage:
verify-tor-dns
Verify Tor DNS resolution
Usage:
verify-tor-dns-all
Verify DNS for all instances
Usage:
verify-tor-dns-direct
Direct Tor DNS verification
Usage:
verify-tor-dns-port
Verify Tor DNS port
Usage:
Exit Node Control
set-exit-node
Set Tor exit node
Usage:
set-exit-node-all
Set exit node for all instances
Usage:
set-exclude-node
Set excluded nodes
Usage:
set-exclude-node-all
Set excluded nodes for all instances
Usage:
clear-exit-node
Clear exit node restrictions
Usage:
clear-exit-node-all
Clear exit node for all instances
Usage:
new-tor-circuit
Create new Tor circuit
Usage:
new-tor-circuit-all
New circuit for all instances
Usage:
Firewall
flush-iptables
Flush iptables rules
Usage:
flush-nftables
Flush nftables rules
Usage:
list-iptables
List iptables rules
Usage:
list-iptables-nat
List iptables NAT rules
Usage:
list-nftables
List nftables rules
Usage:
HAProxy
generate-haproxy-config
Generate HAProxy configuration
Usage:
haproxy-start
Start HAProxy service
Usage:
haproxy-stop
Stop HAProxy service
Usage:
haproxy-status
Check HAProxy status
Usage:
list-haproxy-modes
List HAProxy load balancing modes
Usage:
display-load-balancing-config
Display load balancing configuration
Usage:
Help
show-help
Show help information
Usage:
show-examples
Show usage examples
Usage:
Instance Management
create-instance
Create new Tor instance
Usage:
delete-instance
Delete Tor instance
Usage:
delete-all-instances
Delete all Tor instances
Usage:
delete-all-instances-with-default
Delete all instances including default
Usage:
start-instance
Start a Tor instance
Usage:
stop-instance
Stop a Tor instance
Usage:
restart-instance
Restart a Tor instance
Usage:
start-all-instances
Start all Tor instances
Usage:
stop-all-instances
Stop all Tor instances
Usage:
restart-all-instances
Restart all Tor instances
Usage:
show-instance
Show instance details
Usage:
set-default-instance
Set default Tor instance
Usage:
rename-instance
Rename a Tor instance
Usage:
clone-instance
Clone a Tor instance
Usage:
create-multiple-instances
Create multiple Tor instances
Usage:
Load Balancing
set-load-balancing-mode
Set load balancing mode
Usage:
set-instance-weight
Set instance weight for load balancing
Usage:
torrify-system-iptables-load-balanced
Torrify with iptables load balancing
Usage:
torrify-system-nftables-load-balanced
Torrify with nftables load balancing
Usage:
Main Tor Management
validate-torrc-main
Validate main Tor configuration
Usage:
read-main-tor-config
Display main Tor settings (ports, exit/exclude nodes, security)
Usage:
backup-main-tor-config
Backup main Tor configuration
Usage:
restore-main-tor-config
Restore main Tor configuration from backup
Usage:
set-exit-node-main
Set exit node for main Tor
Usage:
clear-exit-node-main
Clear exit restrictions for main Tor
Usage:
set-exclude-node-main
Set excluded countries for main Tor
Usage:
clear-exclude-node-main
Clear exclude restrictions for main Tor
Usage:
list-exit-exclude-main
Show current exit/exclude settings for main Tor
Usage:
reload-main-tor
Reload main Tor configuration (SIGHUP)
Usage:
status-main-tor
Detailed status of main Tor daemon
Usage:
verify-main-tor-dns
Verify DNS routing through main Tor
Usage:
new-circuit-main-tor
Request new circuit for main Tor
Usage:
check-main-tor-security
Security audit of main Tor config
Usage:
main-tor-bandwidth
Show bandwidth usage of main Tor
Usage:
main-tor-connections
List active connections through main Tor
Usage:
main-tor-logs
Display recent main Tor logs
Usage:
Status Operations
check-tor
Check if Tor service is running via systemctl
Usage:
check-tor-all
Check systemctl status for all Tor instances
Usage:
torverify
Verify Tor connectivity through network check
Usage:
tor-status
Get comprehensive Tor service status (PID, memory, uptime)
Usage:
tor-status-all
Get comprehensive status for all Tor instances
Usage:
get-tor-status
Get Tor status information
Usage:
get-tor-custom-status
Get custom Tor status
Usage:
list-instances
List all Tor instances
Usage:
list-instances-with-ip
List all Tor instances with IP addresses
Usage:
System Management
which-is-active
Check active firewall system
Usage:
cleanup
Clean up orphaned Tor instances
Usage:
clean-orphan-services
Clean orphaned services
Usage:
System Routing
torrify-system-iptables
Route all traffic through Tor (iptables)
Usage:
detorrify-system-iptables
Stop routing traffic through Tor (iptables)
Usage:
torrify-system-nftables
Route all traffic through Tor (nftables)
Usage:
detorrify-system-nftables
Stop routing traffic through Tor (nftables)
Usage:
Timer & Automation
auto-ip-change
Enable automatic IP changes
Usage:
stop-auto-ip-change
Stop automatic IP changes
Usage:
update-ip-timer
Update IP change timer
Usage:
update-ip-all-timer
Update timer for all instances
Usage:
remove-ip-timer
Remove IP change timer
Usage:
remove-ip-all-timer
Remove all IP timers
Usage:
list-ip-timers
List all IP change timers
Usage:
list-auto-ip-change
List auto IP change settings
Usage:
Operational Scenarios
Scenario-oriented workflows generated from the binary's built-in -e --json examples.
Scenario 1: Basic Usage
Essential operations for getting started
Step 1: Start Tor daemon
Expected Output: Tor daemon started successfullyNote
Requires sudo privileges for system-level operations
Step 2: Stop Tor daemon
Expected Output: Tor daemon stopped successfullyNote
Gracefully shuts down Tor service
Step 3: Restart Tor daemon
Expected Output: Tor daemon restarted successfullyNote
Combines stop and start operations
Step 4: Route DNS through Tor using iptables
Expected Output: DNS routing through Tor enabled (iptables)Note
Redirects all system DNS queries to Tor DNS listener
Step 5: Route DNS through Tor using nftables
Expected Output: DNS routing through Tor enabled (nftables)Note
Redirects all system DNS queries to Tor DNS listener
Step 6: Route all traffic through Tor
Expected Output: System traffic routing through Tor enabledNote
All network traffic will be routed through Tor
Step 7: Stop routing traffic through Tor
Expected Output: System traffic routing through Tor disabledNote
Returns to normal direct internet connection
Step 8: Check if Tor service is running
Expected Output: Tor is responding/not respondingNote
Checks if Tor service is active via systemctl
Step 9: Verify actual Tor connectivity
Expected Output: Shows whether traffic is routed through Tor and displays IPNote
Makes direct HTTP request to check.torproject.org to verify torrification
Step 10: Get new Tor circuit/IP
Expected Output: New circuit established with different exit IPNote
Forces new Tor circuit for different exit node
Scenario 2: Instance Management
Managing multiple Tor instances for performance
Step 1: Create a secondary Tor instance
Expected Output: Instance 'secondary' created successfullyNote
Multiple instances provide load balancing and redundancy
Step 2: List all available instances
Expected Output: Shows all instances with their statusStep 3: Start specific instance
Expected Output: Instance 'secondary' startedStep 4: Stop specific instance
Expected Output: Instance 'secondary' stoppedStep 5: Restart specific instance
Expected Output: Instance 'secondary' restartedStep 6: Restart all Tor instances
Expected Output: Restarted 5 out of 5 Tor instancesStep 7: Delete an instance permanently
Expected Output: Instance 'secondary' deletedNote
This permanently removes the instance configuration
Step 8: Start all configured instances
Expected Output: All Tor instances startedStep 9: Stop all running instances
Expected Output: All Tor instances stoppedScenario 3: Advanced Instance Operations
Create, clone, rename and manage multiple Tor instances
Step 1: Create 5 auto-named instances
Expected Output: 5 Tor instances created with auto-generated namesNote
Useful for load balancing and redundancy
Step 2: Create 3 instances with 'performance' prefix
Expected Output: 3 instances created: performance-0, performance-1, performance-2Note
Creates instances with custom naming prefix
Step 3: Create 10 worker instances
Expected Output: 10 instances created: worker-1 through worker-10Note
Ideal for high-throughput operations
Step 4: Create 5 regional instances
Expected Output: 5 instances created: region-1 through region-5Note
Perfect for geographic distribution
Step 5: Create 3 node instances
Expected Output: 3 instances created: node-1, node-2, node-3Note
Simple node-based naming
Step 6: Clone 'main' instance to 'backup'
Expected Output: Instance 'main' cloned to 'backup' successfullyNote
Copies all configuration from source instance
Step 7: Rename instance
Expected Output: Instance renamed from 'old-name' to 'new-name'Note
Updates all references and configuration files
Step 8: List all instances with current IP addresses
Expected Output: All instances listed with their current exit IPsNote
Shows both instance names and their current exit IPs
Step 9: Show detailed information for 'streaming' instance
Expected Output: Detailed configuration and status for 'streaming' instanceNote
Shows configuration, status, and current IP information
Step 10: Set 'performance-0' as the default instance
Expected Output: Default instance set to 'performance-0'Note
Changes which instance is used for default operations
Step 11: Set weight for load balancing
Expected Output: Instance 'secondary' weight set to 50Note
Used for load balancing when multiple instances are active
Step 12: Delete all instances except default
Expected Output: All non-default instances deletedNote
Preserves default instance for basic functionality
Step 13: Delete ALL instances including default
Expected Output: All instances deleted including defaultNote
WARNING: Removes all instances
Scenario 4: Monitoring & Status
Checking system status and verifying operations
Step 1: Get detailed Tor status
Expected Output: Comprehensive status report of all Tor componentsStep 2: Detailed status in JSON format
Expected Output: JSON-formatted status reportNote
Machine-readable output for scripts
Step 3: Check Tor status for all instances
Expected Output: Connection status for every configured instanceNote
Quick health check across all instances
Step 4: Verify if system traffic is routed through Tor
Expected Output: ✓ You are connected through Tor IP Address:Note
Makes HTTP request to check.torproject.org API to verify torrification
Step 5: Verify Tor connectivity with detailed JSON output
Expected Output: { "is_tor": true, "ip_address": "Note
Useful for scripts and automation
Step 6: Get detailed status for all instances
Expected Output: Comprehensive status report for all instancesStep 7: Get Tor daemon status
Expected Output: Current Tor daemon statusNote
Quick status check - use tor-status for detailed report
Scenario 5: Troubleshooting
Debug and resolve common issues
Step 1: Clean up orphaned processes
Expected Output: Orphaned instances and services cleaned upNote
Use when experiencing startup issues
Step 2: Clean orphaned Tor instances and services
Expected Output: Cleanup completed successfullyNote
Removes orphaned instances and service files
Step 3: Clean orphaned services
Expected Output: Orphaned services removedStep 4: New circuits for all instances
Expected Output: All instances have new circuits with different IPsNote
Refreshes exit IPs for all active instances
Scenario 6: 4. EXIT NODE MANAGEMENT
Control and configure Tor exit nodes for geographic routing and privacy
Step 1: Route via United States
Expected Output: Exit node set to United StatesNote
Affects the default Tor instance. Traffic will exit through US-based Tor nodes
Step 2: Set UK exit for specific instance
Expected Output: Exit node set to United Kingdom for 'secondary'Note
Instance-specific exit node configuration
Step 3: Set Germany exit for streaming instance
Expected Output: Exit node set to Germany for 'streaming'Note
Useful for geo-restricted content
Step 4: Set Switzerland exit for secure instance
Expected Output: Exit node set to Switzerland for 'secure'Note
Privacy-friendly jurisdiction
Step 5: Random exit node selection
Expected Output: Exit node set to random selectionNote
Maximum anonymity through randomization
Step 6: Random worldwide exit node
Expected Output: Exit node set to random country worldwideNote
Maximum geographic diversity
Step 7: Random European exit node
Expected Output: Exit node set to random European countryNote
Stay within European jurisdiction
Step 8: Random Asian exit node
Expected Output: Exit node set to random Asian countryNote
Exit through Asian infrastructure
Step 9: Random African exit node
Expected Output: Exit node set to random African countryNote
Exit through African networks
Step 10: Random North American exit
Expected Output: Exit node set to random North American countryNote
US, Canada, or Mexico exit
Step 11: Random South American exit
Expected Output: Exit node set to random South American countryNote
Latin American exit points
Step 12: Random Oceania exit node
Expected Output: Exit node set to random Oceania countryNote
Australia, NZ, or Pacific islands
Step 13: Random Middle Eastern exit
Expected Output: Exit node set to random Middle Eastern countryNote
Middle Eastern exit points
Step 14: Random Five Eyes exit
Expected Output: Exit node set to random Five Eyes countryNote
US, GB, CA, AU, NZ
Step 15: Random Nine Eyes exit
Expected Output: Exit node set to random Nine Eyes countryNote
5eyes + DK, FR, NL, NO
Step 16: Random Fourteen Eyes exit
Expected Output: Exit node set to random Fourteen Eyes countryNote
9eyes + DE, BE, IT, ES, SE
Step 17: Random high-traffic exit
Expected Output: Exit node set to random high-volume countryNote
Better performance and anonymity
Step 18: Random low-traffic exit
Expected Output: Exit node set to random low-volume countryNote
Less common exit points
Step 19: Route through any European country
Expected Output: Exit node set to Europe regionNote
Countries: AT, BE, BG, CH, CZ, DE, DK, EE, ES, FI, FR, GB, GR, HR, HU, IE, IS, IT, LT, LU, LV, MD, NL, NO, PL, PT, RO, RS, SE, SI, SK, UA
Step 20: Route through any Asian country
Expected Output: Exit node set to Asia regionNote
Countries: HK, ID, IN, JP, KR, MY, PH, SG, TH, TW, VN
Step 21: Route through any African country
Expected Output: Exit node set to Africa regionNote
Countries: EG, KE, MA, NG, SC, TN, ZA
Step 22: Route through North America
Expected Output: Exit node set to North America regionNote
US, Canada, or Mexico
Step 23: Route through South America
Expected Output: Exit node set to South America regionNote
Countries: AR, BR, CL, CO, PE, UY, VE
Step 24: Route through Oceania
Expected Output: Exit node set to Oceania regionNote
Countries: AU, NZ
Step 25: Route through Middle East
Expected Output: Exit node set to Middle East regionNote
Countries: AE, IL, IR, LB, OM, QA, SA, TR
Step 26: Use Five Eyes countries
Expected Output: Exit node set to Five Eyes allianceNote
US, GB, CA, AU, NZ
Step 27: Use Nine Eyes countries
Expected Output: Exit node set to Nine Eyes allianceNote
5eyes + Denmark, France, Netherlands, Norway
Step 28: Use Fourteen Eyes countries
Expected Output: Exit node set to Fourteen Eyes allianceNote
9eyes + Germany, Belgium, Italy, Spain, Sweden
Step 29: Use high-traffic countries
Expected Output: Exit node set to high-volume countriesNote
Affects default instance. High-volume countries: AL, AT, BE, BG, BR, BZ, CH, CZ, FI, HU, IS, JP, KR, LU, MD, PL, RO, RU, SC, SG, TH, TR, UA, ZA
Step 30: Use low-traffic countries
Expected Output: Exit node set to low-volume countriesNote
Affects default instance. Countries excluding high-volume and 14eyes nations for uniqueness
Step 31: Set Canada for all instances
Expected Output: Exit node set to Canada for all instancesNote
Applies setting to all configured instances
Step 32: Clear exit node restrictions
Expected Output: Exit node restrictions clearedNote
Returns to default random exit selection
Step 33: Exclude specific countries
Expected Output: Excluded nodes setNote
Prevents routing through specified countries
Step 34: Exclude Five Eyes countries
Expected Output: Five Eyes countries excludedNote
US, GB, CA, AU, NZ
Step 35: Exclude Nine Eyes countries
Expected Output: Nine Eyes countries excludedNote
5eyes + Denmark, France, Netherlands, Norway
Step 36: Exclude Fourteen Eyes countries
Expected Output: Fourteen Eyes countries excludedNote
9eyes + Germany, Belgium, Italy, Spain, Sweden
Step 37: Exclude all European countries
Expected Output: European countries excludedNote
Excludes: AT, BE, BG, CH, CZ, DE, DK, EE, ES, FI, FR, GB, GR, HR, HU, IE, IS, IT, LT, LU, LV, MD, NL, NO, PL, PT, RO, RS, SE, SI, SK, UA
Step 38: Exclude all Asian countries
Expected Output: Asian countries excludedNote
Excludes: HK, ID, IN, JP, KR, MY, PH, SG, TH, TW, VN
Step 39: Exclude North American countries
Expected Output: North American countries excludedNote
US, Canada, Mexico excluded
Step 40: Exclude high-traffic countries
Expected Output: High-volume countries excludedNote
Excludes: AL, AT, BE, BG, BR, BZ, CH, CZ, FI, HU, IS, JP, KR, LU, MD, PL, RO, RU, SC, SG, TH, TR, UA, ZA
Step 41: Exclude low-traffic countries
Expected Output: Low-volume countries excludedNote
Use only high-traffic exit nodes
Step 42: Exclude one random high-traffic country
Expected Output: Random high-volume country excludedNote
Randomly blocks one popular exit country
Step 43: Exclude one random low-traffic country
Expected Output: Random low-volume country excludedNote
Randomly blocks one uncommon exit country
Step 44: Exclude Asia for secure instance
Expected Output: Asia excluded for 'secure' instanceNote
Instance-specific exclusion
Step 45: Exclude 14eyes for privacy instance
Expected Output: 14eyes excluded for 'privacy-1' instanceNote
Maximum privacy configuration
Step 46: Exclude France for all instances
Expected Output: France excluded for all instancesNote
Global exclusion across all instances
Step 47: Clear all excluded countries
Expected Output: All exclusions removedNote
Resets to default behavior
Step 48: Clear exit restrictions for all instances
Expected Output: Exit restrictions cleared for all instancesNote
All instances return to random exit selection
Scenario 7: 7. LOAD BALANCING (Native Kernel-Level)
Native load balancing using iptables/nftables firewall rules
Step 1: Sequential distribution
Expected Output: Load balancing mode set to round-robinNote
Each new connection uses the next Tor instance in order
Step 2: Weight-based distribution
Expected Output: Load balancing mode set to weightedNote
Routes traffic based on instance weights
Step 3: Client IP affinity for session persistence
Expected Output: Load balancing mode set to consistent-hashingNote
Same client IP always routes to same Tor instance
Step 4: Set weight for specific instance
Expected Output: Weight for instance 'tor1' set to 50Note
Only affects weighted mode distribution
Step 5: Set low weight for minimal traffic
Expected Output: Weight for instance 'tor1' set to 10Note
10% of traffic when using weighted mode
Step 6: Set moderate weight for balanced traffic
Expected Output: Weight for instance 'tor2' set to 30Note
30% of traffic distribution
Step 7: Set high weight for primary traffic
Expected Output: Weight for instance 'tor3' set to 60Note
60% of traffic - primary instance
Step 8: High weight for performance instance
Expected Output: Weight for instance 'performance-0' set to 75Note
Prioritize high-performance instance
Step 9: Minimal weight for backup instance
Expected Output: Weight for instance 'backup' set to 5Note
Mostly idle, used for failover
Step 10: Equal weight for worker instances
Expected Output: Weight for instance 'worker-1' set to 25Note
4 workers at 25% each = equal distribution
Step 11: Show current load balancing setup
Expected Output: Current load balancing configuration detailsStep 12: Apply load balanced routing (iptables)
Expected Output: Load balanced routing through Tor enabledNote
Routes traffic through multiple Tor instances using iptables
Step 13: Apply load balanced routing (nftables)
Expected Output: Load balanced routing through Tor enabled (nftables)Note
Modern firewall load balanced routing using nftables
Scenario 8: 8. HAPROXY INTEGRATION (Application-Level Proxy)
HAProxy provides advanced application-level load balancing
Step 1: Generate config with round-robin algorithm
Expected Output: HAProxy configuration generatedNote
Each server is used in turns on port 9055
Step 2: Generate config with source IP hash
Expected Output: HAProxy configuration generatedNote
IP hash persistence on port 8080
Step 3: Generate config with least connections
Expected Output: HAProxy configuration generatedNote
Routes to instance with fewest active connections
Step 4: Generate config with random selection
Expected Output: HAProxy configuration generatedNote
Randomly selects backend for each connection
Step 5: Start HAProxy service
Expected Output: HAProxy started successfullyStep 6: Check HAProxy status
Expected Output: HAProxy service status and statisticsStep 7: Stop HAProxy service
Expected Output: HAProxy stoppedStep 8: Show available HAProxy algorithms
Expected Output: List of supported HAProxy algorithmsNote
roundrobin, source, leastconn, random
Scenario 9: Timer Management and Automation
Automatic IP rotation and timer-based operations
Step 1: Auto IP change every 10 minutes
Expected Output: Automatic IP change enabled with 10 minute intervalNote
Creates new Tor circuit for default instance to get new exit IP
Step 2: Set timer for specific instance
Expected Output: IP change timer set for 'browsing' instanceStep 3: Set 30-minute timer for worker instance
Expected Output: IP change timer set for 'worker-1' instance: 30 minutesNote
Balanced rotation for moderate privacy
Step 4: Set hourly timer for streaming
Expected Output: IP change timer set for 'streaming' instance: 1 hourNote
Less frequent changes for stable connections
Step 5: Set 15-minute timer for research
Expected Output: IP change timer set for 'research' instance: 15 minutesNote
Frequent rotation for privacy-focused browsing
Step 6: Set daily timer for backup instance
Expected Output: IP change timer set for 'backup' instance: 24 hoursNote
Minimal rotation for long-running operations
Step 7: Set 10-minute timer for all instances
Expected Output: IP change timer set for all instances: 10 minutesNote
Synchronizes rotation across all instances
Step 8: Set 2-hour timer for all instances
Expected Output: IP change timer set for all instances: 2 hoursNote
Stable rotation for production workloads
Step 9: List all IP change timers
Expected Output: Table showing all instances with their IP change intervalsStep 10: Remove timer for instance
Expected Output: IP change timer removedStep 11: Stop auto IP change
Expected Output: Automatic IP change stoppedStep 12: Set timer for all instances
Expected Output: IP change timer set for all instancesNote
Synchronizes IP rotation across instances
Step 13: Remove all IP change timers
Expected Output: All IP timers removedNote
Removes all automatic IP rotation timers from all instances
Step 14: List automatic IP change settings
Expected Output: Auto IP change configurations for all instancesScenario 10: DNS Management
Configure and manage DNS routing through Tor
Step 1: Start Tor DNS listener with iptables
Expected Output: Tor DNS service started with iptables rulesNote
Sets up Tor DNS listener service on port 9053
Step 2: Stop Tor DNS routing
Expected Output: Tor DNS iptables rules removedStep 3: Route all DNS through Tor
Expected Output: System DNS queries routed through TorNote
Universal command - auto-detects and uses active firewall
Step 4: Start Tor DNS listener with nftables
Expected Output: Tor DNS service started with nftables rulesNote
Sets up Tor DNS listener service on port 9053
Step 5: Stop Tor DNS (nftables)
Expected Output: Tor DNS nftables rules removedStep 6: Route DNS through Tor using iptables
Expected Output: DNS routing through Tor enabled (iptables)Note
Redirects all system DNS queries to Tor DNS listener
Step 7: Route DNS through Tor using nftables
Expected Output: DNS routing through Tor enabled (nftables)Note
Redirects all system DNS queries to Tor DNS listener
Scenario 11: DNS Verification
Test and verify DNS routing through Tor
Step 1: Verify Tor DNS resolution of .onion addresses
Expected Output: DNS verification successful! (tests both direct and port methods)Note
Resolves .onion addresses to verify DNS goes through Tor
Step 2: Verify DNS resolution for all Tor instances
Expected Output: DNS verification results for each instanceNote
Tests .onion resolution for all configured Tor instances
Step 3: Verify .onion resolution using system DNS
Expected Output: Onion addresses can be resolved directlyNote
Uses system resolver to test .onion domain resolution
Step 4: Verify .onion resolution via Tor DNS port
Expected Output: Onion addresses can be resolved using DNS portNote
Uses instance's DNS port to test .onion resolution
Step 5: Verify DNS for specific instance
Expected Output: DNS verification successful for instance 'tor1'Note
Tests DNS for a specific Tor instance
Scenario 12: Firewall Operations
Manage iptables and nftables firewall rules
Step 1: Flush iptables rules
Expected Output: All iptables rules clearedNote
Removes all current iptables rules and policies
Step 2: List current iptables rules
Expected Output: Display of all active iptables rulesStep 3: Check active firewall
Expected Output: Shows whether iptables or nftables is activeStep 4: Flush nftables rules
Expected Output: All nftables rules clearedNote
Removes all current nftables rules
Step 5: List current nftables rules
Expected Output: Display of all active nftables rulesStep 6: List NAT rules
Expected Output: Display of all NAT table rulesNote
Shows network address translation rules
Scenario 13: Configuration Management
Manage Tor configuration files and validation
Step 1: Validate torrc configuration
Expected Output: Configuration validation resultsNote
Checks syntax without starting Tor
Step 2: Reload configuration
Expected Output: Configuration reloaded successfullyNote
Applies changes without restart
Step 3: Generate new control password
Expected Output: New control password generatedStep 4: Clean custom configuration
Expected Output: Custom torrc entries removedStep 5: Clean all custom configurations
Expected Output: Custom entries removed from all instancesStep 6: Reload all configurations
Expected Output: All instance configurations reloadedStep 7: Generate passwords for all instances
Expected Output: New control passwords generated for allStep 8: Get custom configuration status
Expected Output: Status of custom configurationsScenario 14: Backup and Restore
Backup and restore Tor instance configurations
Step 1: Backup configuration
Expected Output: Configuration backed up with timestamp (default instance)Step 2: List available backups
Expected Output: Table showing all backup filesStep 3: Restore from backup
Expected Output: Configuration restoredNote
Restores configuration and restarts instances
Step 4: Backup all configurations
Expected Output: All instance configurations backed upStep 5: Restore all from backup
Expected Output: All configurations restored from backupNote
Restores complete multi-instance setup
Scenario 15: Main Tor Management (TROUBLESHOOTING ONLY)
TROUBLESHOOTING ONLY: Commands for debugging the main system Tor. Most operations should use Kodachi instances instead. Only use these for troubleshooting main Tor issues.
Step 1: Do NOT modify main Tor for regular use
Expected Output: Use Kodachi instances instead for all normal operationsNote
Only use these commands for debugging main Tor issues
Step 2: Validate main Tor configuration
Expected Output: Main Tor configuration validatedNote
Validates /etc/tor/torrc syntax and settings
Step 3: Display main Tor configuration
Expected Output: Main Tor configuration displayedNote
Shows ports, exit/exclude nodes, and security settings
Step 4: Backup main Tor configuration
Expected Output: Main Tor configuration backed upNote
Creates timestamped backup in backups/main-tor/
Step 5: Restore main Tor configuration
Expected Output: Main Tor configuration restoredNote
Current config is backed up before restoring
Step 6: Set US exit node for main Tor
Expected Output: Exit node set to US for main TorNote
Forces traffic to exit through United States
Step 7: Clear exit node restrictions
Expected Output: Exit node restrictions cleared for main TorNote
Allows Tor to choose any exit country
Step 8: Exclude countries from circuits
Expected Output: Excluded nodes set for main TorNote
Prevents routing through specified countries
Step 9: Clear excluded countries
Expected Output: Exclude restrictions cleared for main TorNote
Removes all country exclusions
Step 10: Show exit/exclude settings
Expected Output: Exit/exclude settings displayedNote
Displays current geographic routing rules
Step 11: Reload main Tor configuration
Expected Output: Main Tor configuration reloadedNote
Sends SIGHUP signal to apply config changes
Step 12: Get main Tor daemon status
Expected Output: Main Tor status displayedNote
Shows systemctl status and port information
Step 13: Verify DNS routing through Tor
Expected Output: DNS routing through main Tor verifiedNote
Tests DNS resolution via tor-resolve
Step 14: Request new Tor circuit
Expected Output: New circuit requested for main TorNote
Gets new IP by building fresh circuit
Step 15: Security audit main Tor
Expected Output: Security audit completedNote
Checks for security misconfigurations
Step 16: Show Tor bandwidth usage
Expected Output: Bandwidth usage displayedNote
Displays active SOCKS connections count
Step 17: List active Tor connections
Expected Output: Active connections listedNote
Shows established connections on SOCKS port
Step 18: Display recent Tor logs
Expected Output: Recent logs displayedNote
Shows last 50 lines from Tor log or journald
Step 19: Validate with JSON output
Expected Output: JSON validation output returnedNote
Machine-readable output for scripting
Scenario 16: Advanced Workflows
Complete workflow examples for common use cases
Step 1: Complete privacy-focused setup
# Privacy-focused browsing setup
sudo tor-switch create-multiple-instances 3 privacy
sudo tor-switch set-exclude-node 5eyes --instance privacy-1
sudo tor-switch set-exclude-node 9eyes --instance privacy-2
sudo tor-switch set-exclude-node 14eyes --instance privacy-3
sudo tor-switch update-ip-timer privacy-1 5m
sudo tor-switch update-ip-timer privacy-2 10m
sudo tor-switch update-ip-timer privacy-3 15m
Note
Avoids surveillance alliance countries with rapid rotation
Step 2: Geographic distribution setup
# Regional distribution setup
sudo tor-switch create-instance europe
sudo tor-switch create-instance asia
sudo tor-switch create-instance americas
sudo tor-switch set-exit-node europe --instance europe
sudo tor-switch set-exit-node asia --instance asia
sudo tor-switch set-exit-node north-america --instance americas
Note
Access region-specific content simultaneously
Step 3: High-availability load balanced setup
# High-availability setup
sudo tor-switch create-multiple-instances 5 ha
sudo tor-switch set-load-balancing-mode weighted
sudo tor-switch set-instance-weight ha-1 30
sudo tor-switch set-instance-weight ha-2 25
sudo tor-switch set-instance-weight ha-3 20
sudo tor-switch set-instance-weight ha-4 15
sudo tor-switch set-instance-weight ha-5 10
sudo tor-switch torrify-system-iptables-load-balanced
Note
Redundant instances with priority-based traffic distribution
Step 4: Research and testing environment
# Research and testing setup
sudo tor-switch create-instance research
sudo tor-switch create-instance testing
sudo tor-switch set-exit-node random-low-volume --instance research
sudo tor-switch set-exit-node high-volume --instance testing
sudo tor-switch update-ip-timer research 2m
sudo tor-switch verify-tor-dns --instance research
sudo tor-switch verify-tor-dns --instance testing
Note
Separate instances for different testing scenarios
Step 5: Maximum performance configuration
# Performance-optimized setup
sudo tor-switch create-multiple-instances 10 perf
sudo tor-switch set-load-balancing-mode round-robin
sudo tor-switch generate-haproxy-config
sudo tor-switch haproxy-start
sudo tor-switch haproxy-status
Note
10 instances with HAProxy for maximum throughput
Step 6: Complete reset to default state
# Clean slate reset
sudo tor-switch stop-all-instances
sudo tor-switch cleanup
sudo tor-switch flush-iptables
sudo tor-switch restart-tor
sudo tor-switch check-tor
Note
Removes all custom configurations and instances
Step 7: Complete system status check
# Monitoring and diagnostics
sudo tor-switch tor-status-all
sudo tor-switch list-instances
sudo tor-switch list-ip-timers
sudo tor-switch display-load-balancing-config
sudo tor-switch haproxy-status
Note
Comprehensive view of all Tor configurations
Environment Variables
| Variable | Description | Default | Values |
|---|---|---|---|
RUST_LOG |
Set logging level | info | error |
NO_COLOR |
Disable all colored output when set | unset | 1 |
Exit Codes
| Code | Description |
|---|---|
| 0 | Success |
| 1 | General error |
| 2 | Invalid arguments |
| 3 | Permission denied |
| 4 | Network error |
| 5 | File not found |