NETWORK GUIDE
Tor Switch Guide
Orchestrate the Tor daemon, multiple instances, exit nodes, bridges, and load balancing, then verify Tor route and leak signals. These checks do not prove anonymity end to end. This guide walks real operational scenarios; the CLI catalog holds every one of the 121 commands.
Tor
Exit nodes
Bridges
Load balancing
Documentation Navigation
This page is scenario-first (operational workflows, real run order, and troubleshooting). For the full autogenerated command/flag catalog, use the CLI Reference.
File Information
| Property | Value |
|---|---|
| Binary Name | tor-switch |
| Version | 10.0.3 (build 11) |
| Build Date | Not disclosed |
| Rust Version | 1.82.0 |
| File Size | 8.3MB |
| Author | Warith Al Maawali |
| License | Proprietary |
| Category | Network & Routing |
| Description | Tor configuration and routing management for Kodachi OS |
| JSON Data | View Raw JSON |
SHA256 Checksum
Key Features
Tor Network Management
| Feature | Description |
|---|---|
| System-wide Torrification | Route all system traffic through Tor with one command |
| Multi-instance Support | Create and manage multiple Tor instances for load balancing |
| Exit Node Control | Choose specific countries for your traffic to exit through |
| Automatic IP Rotation | Schedule automatic IP address changes at custom intervals |
Why Tor Switch is Essential
| Benefit | Description |
|---|---|
| System-wide Tor routing | Routes network traffic through the Tor network when active |
| Geographic Freedom | Bypass geo-restrictions by selecting specific exit countries |
| Load Balancing | Distribute traffic across multiple Tor instances for better performance |
| DNS Leak Prevention | Ensures DNS queries don't reveal your real location |
| Firewall Integration | Works with both iptables and nftables for maximum compatibility |
TL;DR - Essential Commands
PRIVILEGE REQUIREMENTS
Most tor-switch commands require sudo (root privileges) as they:
- Modify iptables/nftables firewall rules
- Start/stop system services (Tor daemon)
- Configure network routing tables
- Manage system-wide torrification
SECURITY: Only run tor-switch with sudo on trusted systems.
Basic Tor Management
sudo tor-switch start-tor # Start the Tor daemon service
sudo tor-switch stop-tor # Stop the Tor daemon service
System Torrification (Route ALL Traffic Through Tor)
sudo tor-switch torrify-system-nftables # Route all traffic through Tor (RECOMMENDED - modern & faster)
sudo tor-switch torrify-system-iptables # Route all traffic through Tor (legacy support)
# Prefer nftables in overview examples for consistency with modern stacks
FIREWALL RECOMMENDATION
- nftables (RECOMMENDED) - Modern, faster, and more secure
- iptables (Legacy support) - Use only if nftables unavailable
Always prefer nftables commands for optimal performance and security.
Load Balancing Setup (Multiple Tor Instances)
sudo tor-switch set-load-balancing-mode round-robin # Set sequential rotation mode
sudo tor-switch torrify-system-nftables-load-balanced # Apply load balanced routing (nftables)
sudo tor-switch torrify-system-iptables-load-balanced # Apply load balanced routing (iptables)
DNS Routing Through Tor
sudo tor-switch start-tor-dns-nftables # Route all DNS queries through Tor (nftables)
sudo tor-switch start-tor-dns-iptables # Route all DNS queries through Tor (iptables)
Verification Commands
tor-switch torverify # Check if traffic is going through Tor
tor-switch check-tor-all # Check systemctl status for all Tor instances
tor-switch get-tor-status # Get Tor status information
tor-switch get-tor-custom-status # Get custom Tor status
tor-switch tor-status # Get comprehensive Tor service status (PID, memory, uptime)
ip-fetch check-tor --json # Cross-verify using independent IP/ASN check
tor-switch verify-tor-dns # Verify DNS is routed through Tor
# Verify with IP Fetch for complete confirmation
ip-fetch check-tor # Comprehensive Tor verification with geolocation
ip-fetch --refresh-cache # Get fresh IP after Tor connection
Emergency Commands
sudo tor-switch flush-iptables # Clear ALL iptables rules (emergency reset)
sudo tor-switch flush-nftables # Clear ALL nftables rules (emergency reset)
WARNING
These commands remove ALL firewall rules, returning to direct connection.
Understanding Tor Routing
What is Torrification?
Torrification applies firewall and routing rules intended to redirect covered traffic through Tor's relay path. Applications, protocols, or namespaces that bypass those rules remain outside the route, so verify IP and DNS behavior separately and do not treat the mode as proof of anonymity.
# Enable full system torrification with modern nftables (RECOMMENDED)
sudo tor-switch torrify-system-nftables
# Or use legacy iptables if nftables isn't available
sudo tor-switch torrify-system-iptables
# Check if torrification is active
tor-switch torverify
How Torrification Works
| Component | Description |
|---|---|
| Firewall Rules | Creates NAT (Network Address Translation) rules that intercept all TCP traffic |
| SOCKS Proxy Redirect | Routes intercepted traffic to the active instance's SocksPort (10000 for the first instance) |
| Transparent Proxy | Uses the instance's TransPort (14000 for the first instance) for applications that don't support SOCKS |
| DNS Redirection | Optionally routes DNS queries through the instance's DNSPort (16000 for the first instance) to prevent leaks |
Torrification Benefits
| Benefit | Description |
|---|---|
| IP Protection | Hides your real IP address from websites and services |
| Multi-hop Encryption | Encrypts traffic through multiple relay nodes (typically 3 hops) |
| Surveillance Prevention | Prevents network surveillance and tracking |
| Onion Access | Allows access to .onion sites on the dark web |
| Transparent Operation | Works transparently for all applications (no per-app configuration needed) |
Load Balancing Modes
When using multiple Tor instances, tor-switch provides three native kernel-level load balancing modes:
1. Round-Robin (Sequential Distribution)
sudo tor-switch set-load-balancing-mode round-robin
sudo tor-switch torrify-system-nftables-load-balanced
| Aspect | Description |
|---|---|
| How it works | Each new TCP flow is assigned to the next Tor instance in sequence using numgen inc mod N. The chosen instance is persisted in conntrack (ct mark), so packets within the same flow stay on the same instance. Each new flow gets a different exit IP. |
| Best for | General use cases with even distribution of traffic and regular IP rotation. |
| Example | Flow 1 → Instance A (exit IP A), Flow 2 → Instance B (exit IP B), Flow 3 → Instance C (exit IP C), Flow 4 → Instance A (cycle repeats), each new connection sees a different exit IP. |
2. Weighted Distribution (Priority-Based)
sudo tor-switch set-load-balancing-mode weighted
sudo tor-switch set-instance-weight tor1 50 # 50% of traffic
sudo tor-switch set-instance-weight tor2 30 # 30% of traffic
sudo tor-switch set-instance-weight tor3 20 # 20% of traffic
sudo tor-switch torrify-system-nftables-load-balanced
| Aspect | Description |
|---|---|
| How it works | Distributes traffic based on assigned weights. TCP traffic uses numgen random mod total_weight, each new TCP flow lands on a random instance weighted by assigned share. DNS traffic uses jhash ip saddr (source-IP hash) against the total weight for session affinity, so DNS queries from the same host consistently reach the same instance. This means a single host can simultaneously use multiple exit IPs (one for TCP flows, one for DNS) depending on how the hash falls. |
| Best for | Prioritizing faster or more reliable instances, testing setups with controlled traffic distribution, or balancing load based on instance capacity. |
| Example | TCP: Instance A (weight 60) gets ~60% of new TCP flows, Instance B (weight 30) gets ~30%, etc. DNS: queries from a given source IP are consistently hashed to one instance. |
3. Consistent Hashing (Source IP Affinity)
sudo tor-switch set-load-balancing-mode consistent-hashing
sudo tor-switch torrify-system-nftables-load-balanced
| Aspect | Description |
|---|---|
| How it works | Uses jhash ip saddr mod N so the same source IP always maps to the same Tor instance. TCP traffic and DNS traffic use different random seeds (tcp_seed and dns_seed), so on a single-host system the TCP flows and DNS queries may land on different instances. Within each traffic type (TCP or DNS), the mapping is stable, the same source IP always hashes to the same bucket. |
| Best for | Services that block frequent IP changes including banking, financial services, streaming platforms, and social media sessions. |
| Example | Device A's TCP flows always use Instance B; Device A's DNS queries may hash to Instance C (different seed). Device B's TCP flows always use Instance A. Each device gets a stable exit IP per traffic type. |
HAProxy Integration (Application-Level Proxy)
For more advanced load balancing, tor-switch can generate HAProxy configurations:
# Generate HAProxy config with different algorithms
sudo tor-switch generate-haproxy-config roundrobin 9055 # Sequential distribution
sudo tor-switch generate-haproxy-config source 9055 # Source IP persistence
sudo tor-switch generate-haproxy-config leastconn 9055 # Least connections
sudo tor-switch generate-haproxy-config random 9055 # Random selection
# Start HAProxy
sudo tor-switch haproxy-start
HAProxy vs Native Load Balancing
| Type | Description |
|---|---|
| Native (iptables/nftables) | Kernel-level operation with lower overhead, works transparently without requiring additional software. |
| HAProxy | Application-level proxy offering more load balancing algorithms, detailed statistics and monitoring, plus health checks for instances. |
Using a SOCKS Proxy
If you prefer application-level proxy configuration instead of system-wide torrification:
# Kodachi tor-switch instances use a dedicated port pool. It is
# deliberately clear of the system Tor ports (9050 SOCKS, 9051 control):
# Instance 1: SOCKS 10000 Control 12000 Trans 14000 DNS 16000
# Instance 2: SOCKS 10001 Control 12001 Trans 14001 DNS 16001
# Instance 3: SOCKS 10002 Control 12002 Trans 14002 DNS 16002
# (each further instance adds 1 to each of the four ports)
# Confirm the live values on your own machine:
sudo tor-switch list-instances
# Configure your browser/application to use an instance:
# SOCKS5 Proxy: 127.0.0.1:10000
Performance Note
Tor uses multiple relay hops and hides the destination-facing source IP behind its exit path, but it does not guarantee anonymity against application metadata or traffic correlation. Those relay hops can slow connections; load balancing across multiple instances can improve throughput.
Advanced Commands
For the complete list of all available commands and detailed options, please refer to the auto-generated command reference which includes:
| Feature | Description |
|---|---|
| Instance Management | Complete instance management commands |
| HAProxy Integration | HAProxy integration for advanced load balancing |
| DNS Commands | DNS verification and routing commands |
| Configuration | Configuration backup and restore |
| Firewall Management | Firewall rule management |
| Debug Tools | Debug and diagnostic tools |
| CLI Reference | All command-line flags and parameters |
Instance Management Commands
# Start specific Tor instance
sudo tor-switch start-instance <instance_name>
# Stop specific Tor instance
sudo tor-switch stop-instance <instance_name>
Exit Node Management
# Set exit node for all instances
sudo tor-switch set-exit-node-all <country_code>
# Clear exit node restrictions for current instance
sudo tor-switch clear-exit-node
# Clear exit node restrictions for all instances
sudo tor-switch clear-exit-node-all
# Clear excluded countries from routing (from flag_e examples)
sudo tor-switch clear-exclude-node-main
Configuration Management
# Reload Tor configuration for all instances
sudo tor-switch reload-tor-config-all
# Restore all instance configurations from backup
sudo tor-switch restore-config-all <backup_name>
# Restore main Tor configuration from backup
sudo tor-switch restore-main-tor-config <backup_file>
HAProxy Management
Timer & Automation
# Enable automatic IP changes with interval
sudo tor-switch auto-ip-change <interval>
# Update IP change timer for all instances
sudo tor-switch update-ip-all-timer <interval>
# Remove IP change timer for specific instance
sudo tor-switch remove-ip-timer <instance_name>
Help & Documentation
# Show comprehensive help information
tor-switch show-help
# Display usage examples and scenarios
tor-switch show-examples
Security Notes
Important Security Practices:
| Practice | Description |
|---|---|
| Verify Torrification | Always verify torrification with torverify after enabling |
| Rotate Exit Nodes | Avoid using the same exit node for extended periods |
| Multi-instance Setup | Use multi-instance setup for sensitive operations |
| Circuit Rotation | Regularly change circuits with new-tor-circuit for better anonymity |
| Firewall Check | Check firewall rules are active with which-is-active command |
Performance
| Metric | Value | Description |
|---|---|---|
| Connection Time | < 5 seconds | Typical connection establishment |
| Memory Usage | ~50MB | Per Tor instance |
| CPU Usage | < 10% active, < 1% idle | Resource consumption |
| Bandwidth Overhead | ~10-20% | Due to encryption |
| Recommended Instances | 3-5 | For optimal performance |
Support
| Resource | Link |
|---|---|
| Website | digi77.com |
| Anonymity Verifier | kodachi.cloud |
| Discord Support | discord.gg/KEFErEx |
| GitHub | github.com/WMAL |
Scenario 1: First-Time Tor Setup and Verification
Complete first-time setup to verify Tor connectivity and DNS leak protection.
# Step 1: Start Tor daemon
sudo tor-switch start-tor
# Step 2: Enable system-wide torrification with modern firewall
sudo tor-switch torrify-system-nftables
# Expected: All traffic routed through Tor network
# Step 3: Route DNS queries through Tor
sudo tor-switch start-tor-dns-nftables
# Step 4: Verify Tor connectivity
tor-switch torverify
# Expected: Shows you are connected through Tor with exit IP
# Step 5: Cross-verify with IP geolocation check
ip-fetch check-tor
# Expected: Confirms Tor network usage with ASN information
# Step 6: Verify DNS is not leaking
dns-leak test
# Expected: DNS queries routed through Tor, no leaks detected
Cross-binary workflow: tor-switch + ip-fetch + dns-leak
When to run: Initial setup on new system or after fresh OS installation.
Scenario 2: Complete System Torrification (nftables)
Route all system traffic and DNS through Tor using modern nftables firewall.
# Step 1: Ensure Tor is running
sudo tor-switch check-tor
# Step 2: Start Tor if not responding
sudo tor-switch start-tor
# Step 3: Configure DNS routing through Tor
sudo tor-switch start-tor-dns-nftables
# Expected: Tor DNS listener active on the instance DNSPort, 16000 for the first instance
# Step 4: Apply nftables rules for system-wide torrification
sudo tor-switch torrify-system-nftables
# Expected: All TCP traffic redirected to Tor TransPort
# Step 5: Verify DNS resolution through Tor
sudo tor-switch verify-tor-dns
# Expected: .onion domains resolvable
# Step 6: Confirm torrification is active
tor-switch torverify
# Step 7: Get fresh IP information
ip-fetch --refresh-cache
# Expected: Shows Tor exit node IP and geolocation
Cross-binary workflow: tor-switch + dns-switch + ip-fetch
When to run: When you need system-wide Tor routing and understand that Tor does not eliminate endpoint, browser-fingerprint, malware, or traffic-correlation risks. You can automate the sequence with workflow-manager.
Scenario 3: Privacy Browsing, Exclude Surveillance Alliances (5/9/14-Eyes)
Configure Tor to avoid exit nodes in surveillance alliance countries.
# Step 1: Exclude Five Eyes countries from circuits
sudo tor-switch set-exclude-node 5eyes
# Expected: US, GB, CA, AU, NZ excluded from routing
# Step 2: Create circuit with new exit node
sudo tor-switch new-tor-circuit
# Step 3: Verify new exit IP is not in excluded countries
ip-fetch
# Expected: Exit IP should be outside Five Eyes jurisdiction
# Step 4: For maximum privacy, exclude Fourteen Eyes
sudo tor-switch set-exclude-node 14eyes
# Expected: All 14-Eyes countries excluded
# Step 5: Force new circuit to apply changes
sudo tor-switch new-tor-circuit
# Step 6: Verify exit country compliance
ip-fetch --json
# Expected: Country code not in 14-Eyes list
Cross-binary workflow: tor-switch + ip-fetch
When to run: When accessing sensitive information or avoiding nation-state surveillance.
Scenario 4: Geographic Content Access with Region-Specific Instances
Access region-specific content by creating Tor instances with different exit countries.
# Step 1: Create three regional instances
sudo tor-switch create-instance europe
sudo tor-switch create-instance asia
sudo tor-switch create-instance americas
# Step 2: Configure European exit nodes
sudo tor-switch set-exit-node europe --instance europe
# Expected: Exit node set to European country
# Step 3: Configure Asian exit nodes
sudo tor-switch set-exit-node asia --instance asia
# Step 4: Configure American exit nodes
sudo tor-switch set-exit-node north-america --instance americas
# Step 5: Start all regional instances
sudo tor-switch start-all-instances
# Expected: All three instances running
# Step 6: Verify each instance's exit location
sudo tor-switch list-instances-with-ip
# Expected: Shows different geographic exit IPs
# Step 7: Route specific application through desired instance
# Configure application to use SOCKS proxy:
# Europe: 127.0.0.1:10000
# Asia: 127.0.0.1:10001
# Americas: 127.0.0.1:10002
Cross-binary workflow: tor-switch + ip-fetch + routing-switch
When to run: Accessing geo-restricted content or testing region-specific services.
Scenario 5: High-Availability Streaming with Weighted Distribution
Configure load balancing with priority for stable streaming connections.
# Step 1: Create multiple instances for load balancing
sudo tor-switch create-multiple-instances 5 stream
# Step 2: Set weighted distribution mode
sudo tor-switch set-load-balancing-mode weighted
# Step 3: Assign high weight to primary streaming instance
sudo tor-switch set-instance-weight stream-1 60
# Expected: 60% of traffic to primary instance
# Step 4: Assign moderate weights to backup instances
sudo tor-switch set-instance-weight stream-2 20
sudo tor-switch set-instance-weight stream-3 15
sudo tor-switch set-instance-weight stream-4 5
# Step 5: Apply load-balanced torrification
sudo tor-switch torrify-system-nftables-load-balanced
# Step 6: Verify load balancing configuration
sudo tor-switch display-load-balancing-config
# Expected: Shows weighted distribution percentages
# Step 7: Monitor instance health during streaming
health-control net-check
Cross-binary workflow: tor-switch + health-control
When to run: High-bandwidth applications requiring stable connections with failover capability.
Scenario 6: Emergency Panic Reset, Flush All Rules
Quickly remove all Tor routing rules to return to direct internet connection.
# Step 1: Stop all Tor instances
sudo tor-switch stop-all-instances
# Expected: All instances stopped
# Step 2: Flush nftables rules
sudo tor-switch flush-nftables
# Expected: All nftables Tor rules cleared
# Step 3: Flush iptables rules as fallback
sudo tor-switch flush-iptables
# Expected: All iptables Tor rules cleared
# Step 4: Stop DNS routing through Tor
sudo tor-switch stop-tor-dns-nftables
sudo tor-switch stop-tor-dns-iptables
# Step 5: Verify direct internet connection
ip-fetch check-tor
# Expected: NOT using Tor
# Step 6: Confirm regular internet access
ip-fetch
# Expected: Shows real ISP IP address
# Step 7: Restart networking if needed
health-control net-check
Cross-binary workflow: tor-switch + health-control + routing-switch
When to run: Emergency situations requiring immediate exit from Tor network. Or Automate this with workflow-manager.
Scenario 7: Tor Bridge Configuration for Censored Networks
Configure Tor bridges to bypass network censorship and access Tor in restricted regions.
# Step 1: Backup current Tor configuration
sudo tor-switch backup-config
# Expected: Configuration backed up with timestamp
# Step 2: Stop Tor to modify configuration
sudo tor-switch stop-tor
# Step 3: Validate main Tor configuration before changes
sudo tor-switch validate-torrc-main
# Step 4: Set bridge configuration in torrc
# Edit /etc/tor/torrc to add bridge lines:
# UseBridges 1
# Bridge obfs4 [bridge_address:port] [fingerprint]
# Step 5: Validate modified configuration
sudo tor-switch validate-torrc-main
# Expected: Configuration valid
# Step 6: Restart Tor with bridge configuration
sudo tor-switch restart-tor
# Step 7: Verify Tor connectivity through bridges
tor-switch torverify
# Expected: Connected through Tor via bridges
# Step 8: Verify connection security
health-control security-score
Cross-binary workflow: tor-switch + health-control + online-auth
When to run: Operating in countries with Tor censorship or restrictive firewalls.
Scenario 8: HAProxy Advanced Load Balancing with Health Checks
Configure HAProxy for application-level load balancing with health monitoring.
# Step 1: Create multiple Tor instances
sudo tor-switch create-multiple-instances 10 perf
# Step 2: Start all instances
sudo tor-switch start-all-instances
# Step 3: Generate HAProxy config with round-robin algorithm
sudo tor-switch generate-haproxy-config roundrobin 9055
# Expected: HAProxy configuration created
# Step 4: Start HAProxy service
sudo tor-switch haproxy-start
# Expected: HAProxy started on port 9055
# Step 5: Verify HAProxy status and health checks
sudo tor-switch haproxy-status
# Expected: Shows backend health and statistics
# Step 6: List available HAProxy algorithms
sudo tor-switch list-haproxy-modes
# Step 7: Monitor HAProxy performance
sudo tor-switch display-load-balancing-config
# Step 8: Check detailed logs
tail -f dashboard/hooks/logs/tor-switch-log.log
Cross-binary workflow: tor-switch + logs-hook
When to run: High-performance scenarios requiring advanced load balancing features.
Scenario 9: Secure Configuration Backup and Recovery
Create comprehensive backups of all Tor configurations for disaster recovery.
# Step 1: List current instances to understand setup
sudo tor-switch list-instances
# Step 2: Backup all instance configurations
sudo tor-switch backup-config-all
# Expected: All configurations backed up with timestamp
# Step 3: Backup main Tor configuration
sudo tor-switch backup-main-tor-config
# Step 4: List available backups
sudo tor-switch list-backups
# Expected: Table showing all backup files
# Step 5: Verify configuration integrity
sudo tor-switch validate-torrc
# Step 6: Test restore from backup (if needed)
# sudo tor-switch restore-config backup-2026-02-09
# Step 7: Verify restored configuration
sudo tor-switch tor-status-all
Cross-binary workflow: tor-switch + integrity-check + logs-hook
When to run: Before major system changes or as part of regular maintenance schedule.
Scenario 10: Main Tor vs Kodachi Instance Troubleshooting
Debug issues by isolating main system Tor from Kodachi instances.
# Step 1: Check main Tor daemon status
sudo tor-switch status-main-tor
# Expected: Shows systemctl status and ports
# Step 2: Validate main Tor configuration
sudo tor-switch validate-torrc-main
# Step 3: Check Kodachi instance status
sudo tor-switch tor-status-all
# Expected: Status for all Kodachi instances
# Step 4: Read main Tor configuration
sudo tor-switch read-main-tor-config
# Expected: Shows ports, exit/exclude nodes
# Step 5: Verify main Tor DNS routing
sudo tor-switch verify-main-tor-dns
# Step 6: Check for port conflicts
# System Tor, when present, uses: 9050 (SOCKS), 9051 (control)
# Kodachi instances use: 10000+ SOCKS, 12000+ control, 14000+ trans, 16000+ DNS
# Step 7: Review logs for errors
sudo tor-switch main-tor-logs
# Step 8: Test circuit creation
sudo tor-switch new-circuit-main-tor
# Step 9: Run health diagnostics
health-control offline-info-system
Cross-binary workflow: tor-switch + health-control
When to run: When experiencing connection issues or port conflicts between Tor services.
Scenario 11: Custom Torrc Configuration Management
Manage custom Tor configurations for advanced routing requirements.
# Step 1: Backup current configuration before changes
sudo tor-switch backup-config
# Step 2: Create custom instance for special configuration
sudo tor-switch create-instance custom
# Step 3: Validate configuration before applying
sudo tor-switch validate-torrc --instance custom
# Expected: Syntax validation passed
# Step 4: Set custom exit node configuration
sudo tor-switch set-exit-node ch --instance custom
# Expected: Switzerland exit configured
# Step 5: Set exclude nodes for custom instance
sudo tor-switch set-exclude-node 14eyes --instance custom
# Step 6: Reload configuration to apply changes
sudo tor-switch reload-tor-config --instance custom
# Step 7: Restart instance with new configuration
sudo tor-switch restart-instance custom
# Step 8: Verify custom configuration is active
sudo tor-switch show-instance custom
# Step 9: Test custom instance connectivity
# Configure application to use: 127.0.0.1:[custom_port]
# Step 10: Log custom configuration activity
logs-hook log --script 'tor-custom-config' --level info 'Config created'
Cross-binary workflow: tor-switch + logs-hook
When to run: Setting up specialized routing rules or testing custom Tor configurations.
Scenario 12: Automatic IP Rotation for Session Persistence
Configure automatic IP rotation with different intervals for various instances.
# Step 1: Create instances for different rotation needs
sudo tor-switch create-instance browsing
sudo tor-switch create-instance streaming
sudo tor-switch create-instance download
# Step 2: Set rapid rotation for privacy browsing (5 minutes)
sudo tor-switch update-ip-timer browsing 5m
# Expected: New circuit every 5 minutes
# Step 3: Set moderate rotation for streaming (30 minutes)
sudo tor-switch update-ip-timer streaming 30m
# Step 4: Set slow rotation for downloads (2 hours)
sudo tor-switch update-ip-timer download 2h
# Step 5: List all configured timers
sudo tor-switch list-ip-timers
# Expected: Shows all instances with rotation intervals
# Step 6: Verify timer activity
sudo tor-switch list-auto-ip-change
# Step 7: Monitor IP changes
sudo tor-switch list-instances-with-ip
# Expected: Shows current exit IPs for all instances
# Step 8: Adjust timer if needed
# sudo tor-switch update-ip-timer browsing 10m
Cross-binary workflow: tor-switch + ip-fetch + routing-switch
When to run: When balancing anonymity requirements with session stability needs.
Scenario 13: Nine-Eyes Exclusion Audit Across All Instances
Audit and configure all instances to avoid surveillance alliance exit nodes.
# Step 1: List all current instances
sudo tor-switch list-instances
# Expected: Shows all configured Tor instances
# Step 2: Check current exit/exclude settings
sudo tor-switch list-exit-exclude-main
# Step 3: Apply Nine-Eyes exclusion to all instances
sudo tor-switch set-exclude-node-all 9eyes
# Expected: 9-Eyes countries excluded for all instances
# Step 4: Force new circuits for all instances
sudo tor-switch new-tor-circuit-all
# Step 5: Verify exit IPs are compliant
sudo tor-switch list-instances-with-ip
# Expected: No instances exiting through 9-Eyes countries
# Step 6: Cross-verify with geolocation check
ip-fetch
# Expected: Exit country not in 9-Eyes list
# Step 7: Create audit report
# Document instance configurations and exit countries
# Step 8: Schedule periodic verification
# Use workflow-manager or ai-scheduler for automated checks
Cross-binary workflow: tor-switch + ip-fetch
When to run: Regular security audits or compliance verification for privacy-sensitive operations.
Scenario 14: Firewall Rule Inspection and Manual Cleanup
Inspect and manually clean Tor firewall rules when automatic cleanup fails.
# Step 1: Check which firewall system is active
sudo tor-switch which-is-active
# Expected: Shows iptables or nftables status
# Step 2: List current iptables NAT rules
sudo tor-switch list-iptables-nat
# Expected: Shows Tor redirection rules
# Step 3: List all iptables filter rules
sudo tor-switch list-iptables
# Step 4: List nftables rules
sudo tor-switch list-nftables
# Expected: Shows Tor routing chains
# Step 5: Clean up orphaned services
sudo tor-switch clean-orphan-services
# Step 6: Remove orphaned instances
sudo tor-switch cleanup
# Expected: Orphaned processes cleaned
# Step 7: Selectively flush rules if needed
# For iptables:
sudo tor-switch flush-iptables
# For nftables:
sudo tor-switch flush-nftables
# Step 8: Verify clean state
sudo tor-switch which-is-active
# Step 9: Check system health after cleanup
health-control net-check
Cross-binary workflow: tor-switch + health-control
When to run: After crashes, failed torrification attempts, or when rules appear inconsistent.
Scenario 15: Complete System Diagnostics and Monitoring Report
Generate comprehensive diagnostics report for Tor system health and performance.
# Step 1: Check status of all Tor instances
sudo tor-switch tor-status-all
# Expected: Comprehensive status for all instances
# Step 2: Verify Tor connectivity
tor-switch torverify
# Step 3: Check DNS configuration
sudo tor-switch verify-tor-dns-all
# Expected: DNS verification for all instances
# Step 4: List all instances with current IPs
sudo tor-switch list-instances-with-ip
# Expected: Exit IPs for all running instances
# Step 5: Display load balancing configuration
sudo tor-switch display-load-balancing-config
# Step 6: Check HAProxy status if configured
sudo tor-switch haproxy-status
# Step 7: Review automatic IP rotation timers
sudo tor-switch list-ip-timers
# Step 8: Check firewall rules
sudo tor-switch which-is-active
sudo tor-switch list-nftables
# Step 9: Review recent Tor logs
tail -f dashboard/hooks/logs/tor-switch-log.log
# Step 10: Generate system health report
health-control offline-info-system
# Step 11: Export diagnostic data
# Combine outputs for comprehensive system report
Cross-binary workflow: tor-switch + logs-hook + health-control
When to run: Regular system health checks, troubleshooting, or before major configuration changes.
Scenario 16: Instance Lifecycle Management
Complete lifecycle management operations for Tor instances including deletion, restart, and cloning.
# Step 1: List all current instances to review
sudo tor-switch list-instances
# Expected: Shows all configured instances
# Step 2: Set a default instance for system-wide operations
sudo tor-switch set-default-instance primary
# Expected: Instance 'primary' set as default
# Step 3: Clone instance for testing configuration changes
sudo tor-switch clone-instance primary testing
# Expected: New instance 'testing' created with same config as 'primary'
# Step 4: Rename instance for better organization
sudo tor-switch rename-instance testing backup-config
# Expected: Instance renamed to 'backup-config'
# Step 5: Restart all instances to apply system changes
sudo tor-switch restart-all-instances
# Expected: All instances restarted cleanly
# Step 6: Delete single instance that's no longer needed
sudo tor-switch delete-instance backup-config
# Expected: Instance stopped and configuration removed
# Step 7: Emergency cleanup - delete all non-default instances
sudo tor-switch delete-all-instances
# Expected: All instances except default deleted
# Step 8: Nuclear option - delete everything including default
sudo tor-switch delete-all-instances-with-default
# Expected: All instances deleted, clean slate
# Step 9: Verify clean state
sudo tor-switch list-instances
# Expected: No instances or only default instance remaining
Cross-binary workflow: tor-switch + logs-hook
When to run: Regular maintenance, testing configurations, or complete system reset.
Scenario 17: Tor Security and Password Management
Harden Tor instances with fresh passwords and security audits.
# Step 1: Generate new control password for single instance
sudo tor-switch generate-new-tor-password --instance primary
# Expected: New hashed password generated and configured
# Step 2: Bulk password regeneration for all instances
sudo tor-switch generate-new-tor-password-all
# Expected: All instances receive new unique passwords
# Step 3: Check main Tor security configuration
sudo tor-switch check-main-tor-security
# Expected: Security audit report with recommendations
# Step 4: Clean custom torrc configurations
sudo tor-switch clean-torrc-custom --instance primary
# Expected: Removes custom settings, returns to defaults
# Step 5: Clean all custom torrc files across instances
sudo tor-switch clean-torrc-custom-all
# Expected: All instances reset to base configuration
# Step 6: Restart instances to apply security changes
sudo tor-switch restart-all-instances
# Step 7: Verify security hardening with health check
health-control security-score
# Expected: Improved security score after hardening
# Step 8: Backup hardened configuration
sudo tor-switch backup-config-all
# Step 9: Document security changes
logs-hook log --script 'tor-security-audit' --level info 'Hardening completed'
Cross-binary workflow: tor-switch + health-control + logs-hook
When to run: After security incidents, regular security audits, or before high-risk operations.
Scenario 18: System Detorrification and DNS Routing
Remove Tor routing completely or configure DNS-only Tor routing.
# Step 1: Stop all Tor traffic routing (keep DNS direct)
sudo tor-switch detorrify-system-iptables
# Expected: TCP routing removed, DNS uses regular network
# Step 2: Alternative detorrification with nftables
sudo tor-switch detorrify-system-nftables
# Expected: All Tor routing rules removed
# Step 3: Route ONLY DNS through Tor (hybrid mode)
sudo tor-switch torrify-system-dns
# Expected: DNS queries use Tor, TCP traffic direct
# Step 4: Apply DNS-only Tor with iptables
sudo tor-switch torrify-system-iptables-dns
# Expected: DNS on port 53 redirected to Tor
# Step 5: Apply DNS-only Tor with nftables
sudo tor-switch torrify-system-nftables-dns
# Expected: DNS routing via Tor, TCP direct
# Step 6: Verify DNS uses Tor
sudo tor-switch verify-tor-dns-direct
# Expected: DNS queries going through Tor
# Step 7: Verify DNS port configuration
sudo tor-switch verify-tor-dns-port
# Expected: Shows DNS listening on the instance DNSPort, 16000 for the first instance
# Step 8: Test DNS leak prevention
dns-leak test
# Expected: observed resolvers follow the configured Tor DNS path
# Step 9: Check network status
health-control net-check
# Expected: Shows hybrid DNS-only Tor configuration
Cross-binary workflow: tor-switch + dns-leak + health-control
When to run: When you need DNS privacy but want faster direct TCP connections.
Scenario 19: Main Tor Advanced Management
Advanced operations on the main Tor daemon including bandwidth monitoring and connection management.
# Step 1: Check main Tor bandwidth usage
sudo tor-switch main-tor-bandwidth
# Expected: Shows current bandwidth statistics
# Step 2: Monitor active connections
sudo tor-switch main-tor-connections
# Expected: Lists all active Tor connections
# Step 3: Review main Tor logs for diagnostics
sudo tor-switch main-tor-logs
# Expected: Displays recent log entries
# Step 4: Reload main Tor without full restart
sudo tor-switch reload-main-tor
# Expected: Configuration reloaded without downtime
# Step 5: Set specific exit node for main Tor
sudo tor-switch set-exit-node-main de
# Expected: Main Tor exits through Germany
# Step 6: Clear exit node restrictions
sudo tor-switch clear-exit-node-main
# Expected: Exit node preference removed
# Step 7: Exclude surveillance countries from main Tor
sudo tor-switch set-exclude-node-main 5eyes
# Expected: Five Eyes countries excluded
# Step 8: Clear exclusion list
sudo tor-switch clear-exclude-node-main
# Expected: Exclusion list cleared
# Step 9: List current main Tor configuration
sudo tor-switch list-exit-exclude-main
# Expected: Shows exit/exclude settings
# Step 10: Verify main Tor performance
tor-switch torverify
ip-fetch check-tor
Cross-binary workflow: tor-switch + ip-fetch + logs-hook
When to run: Fine-tuning main Tor daemon performance or troubleshooting connection issues.
Scenario 20: Timer and Auto-IP Cleanup
Clean up automatic IP change timers and scheduled rotations.
# Step 1: List all configured IP rotation timers
sudo tor-switch list-auto-ip-change
# Expected: Shows all active IP rotation schedules
# Step 2: Remove IP rotation timer for single instance
sudo tor-switch remove-ip-all-timer --instance browsing
# Expected: Timer removed for 'browsing' instance
# Step 3: Stop all automatic IP rotation globally
sudo tor-switch stop-auto-ip-change
# Expected: All IP rotation timers stopped
# Step 4: Verify timers are stopped
sudo tor-switch list-ip-timers
# Expected: No active timers shown
# Step 5: Clean up orphaned timer services
sudo tor-switch clean-orphan-services
# Expected: Orphaned systemd timers removed
# Step 6: Restart instances without timers
sudo tor-switch restart-all-instances
# Step 7: Verify instances running without scheduled rotation
sudo tor-switch tor-status-all
# Expected: Instances active, no timer services
# Step 8: Manually trigger IP change when needed
sudo tor-switch new-tor-circuit-all
# Step 9: Check system health after timer removal
health-control offline-info-system
Cross-binary workflow: tor-switch + health-control
When to run: When removing scheduled IP rotation or cleaning up after configuration changes.
Related Workflows
- IP Fetch Guide, Verify Tor connectivity and geolocation
- DNS Switch, DNS configuration and leak prevention
- DNS Leak Detection, Test for DNS leaks through Tor
- Health Control, System health and emergency controls
- Routing Switch, Network routing management
- Integrity Check, Configuration integrity verification
- Logs Hook, Centralized logging and monitoring
- Full CLI Reference: tor-switch commands