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 127 commands.
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 75) |
| Build Date | Not disclosed |
| Rust Version | 1.82.0 |
| File Size | 13.7MB |
| 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
a0bf6915f5c973d32c9d746040f34c34a29ff98beca73af78513b8bcdd05abf7
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 |
| Onion Services | Publish a service that runs on this machine as a v3 .onion address through a Tor instance, and see whether it is up and reachable |
| Live Circuit View | See the relays that carry your traffic right now: guard, middle and exit of every circuit, with country and address |
| More Bridge Types | obfs4, snowflake, meek_lite and webtunnel bridges for networks that block Tor |
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)
Onion Services and Circuits
sudo tor-switch show-circuits # Relays of every circuit, with country and address (read-only)
sudo tor-switch onion-service-create --name blog --target 127.0.0.1:8080 --instance onionhost
sudo tor-switch onion-service-status --name blog # Up, descriptor built, reachable through Tor
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
sudo tor-switch tor-status --json also reports bootstrap_progress: how far Kodachi's Tor instances have bootstrapped, from 0 to 100. It is the lowest value among the instances that answered, so one instance still starting shows. When no instance can be read, for example without sudo, it is null and bootstrap_reason says why. bootstrap_instances counts the instances asked, the ones that answered and the ones that are done.
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) |
Keeping the Tor firewall in place
When you turn on the firewall rules watch in health-control's watch-guard settings (it is off by default), Kodachi notices if the Tor firewall you applied is removed, for example by another program running nft flush ruleset, and puts the same torrify back. sudo tor-switch firewall-guard is the check it runs; you can run it yourself. To turn the watch on or off: the dashboard's Kill Switch page (Tor Firewall Rules), the dock's Route Through Tor window (Keep the Tor firewall in place), or the Tor menu of the Actions launcher (Tor Firewall Watch Enable and Disable). From a terminal, sudo health-control enable --type watch-guard --watch firewall-rules --method auto turns it on.
- It only puts back what you applied in this boot. After a reboot, or after you detorrify, block the internet, use a panic mode, nuke or recover the internet, there is nothing to put back until you torrify again.
- It does nothing while an internet block, a panic mode, a Tor pool restart or a shutdown is in progress.
- A change that keeps the Tor firewall in place, such as a pool rebalance or turning Tor DNS on or off, is never undone.
- It tries at most three times a minute, then stops and keeps the rules that are there. It never removes a rule.
Restarting all Tor instances
sudo tor-switch restart-all-instances restarts every instance and waits for each one to come back.
- With load-balanced nftables Tor routing (round robin, weighted or consistent), the restart then points the load balancer at the instances that are running. An instance that did not come back is left out, so no connection is sent to it, and a later restart puts it back once it runs again. The report says "rules rebuilt over the N live instance(s)" or "rules already spread over the N live instance(s)". If no instance is alive, the rules stay in place and keep blocking, so nothing leaves outside Tor.
- With load-balanced iptables Tor routing the rules are checked, not rebuilt: if they still point at an instance that is down, the run says so and asks you to torrify again.
- In text mode the command exits with an error when it did not restart every instance, and names them, for example "Restarted 3 of 4 Tor instances; not restarted: ...", so a shell
&&chain or a script stops there instead of taking it for a clean restart. With--jsonthe status ispartial_success, orfailurewhen no instance restarted.
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 |
| Onion Services | Host, list, check and remove .onion services |
| Circuit View | The live relays of every circuit of an instance |
| 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
# Stop HAProxy service
sudo tor-switch haproxy-stop
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>
Onion Services
Publish a service that runs on this machine, a web server or an SSH server for example, as a v3 .onion address through one Kodachi Tor instance. Visitors reach it through Tor without learning where it runs, and you can check its health at any time.
Before you publish: start your service on this machine first (in the examples below, a web server on 127.0.0.1:8080): until it listens, visitors reach nothing. The instance named with --instance hosts it; a stopped instance is started, and a running one is restarted only with --restart-ok. tor-switch onion-service-list then shows the .onion address to share. onion-service-create and onion-service-remove need sudo and a login (the dashboard's login, or sudo online-auth authenticate); onion-service-status needs sudo; onion-service-list needs neither.
# Create a dedicated instance for hosting (recommended)
sudo tor-switch create-instance onionhost
# Publish a local web server on port 8080 as http://<address>.onion
sudo tor-switch onion-service-create --name blog --target 127.0.0.1:8080 --instance onionhost
# Forward onion port 22 to a local SSH server
sudo tor-switch onion-service-create --name ssh --target 127.0.0.1:22 --port 22 --instance onionhost
# Every hosted service with its instance, address, target and port
tor-switch onion-service-list
# Live health: instance running, descriptor built, local target up, reachable, visitors now
sudo tor-switch onion-service-status --name blog
# Stop hosting and wipe the keys (the address is gone for good)
sudo tor-switch onion-service-remove --name blog --restart-ok
WHAT TOR-SWITCH ENFORCES
- Loopback targets only.
--targetmust be the literal address127.0.0.1or[::1]with a port. Host names,localhostincluded, and every other address are refused, so nothing beyond this machine can be published by mistake. - Tor and Kodachi ports are refused. A target on any Tor listener of any instance (SocksPort, ControlPort, DNSPort, TransPort and the others), on DNS (53), on dnscrypt-proxy or Pi-hole, or held by another Tor or Kodachi service is rejected.
- The hosting instance restarts. Adding or removing a service restarts that instance, which drops its connections for about 10 to 30 seconds. On a running instance the command refuses unless you add
--restart-ok, and it says which connections would drop. - Not on the main system Tor. Services are hosted on a Kodachi pool or dedicated instance; the main Tor service (tor@default) is refused.
- Keys are never shown. The keys stay in the instance's own data directory; tor-switch never prints or logs them, and JSON output carries the public address only.
- Removal wipes the keys, within limits. The secret key file is overwritten in place, then the key directory is deleted, and the output says exactly what was and was not achieved. On SSDs and journaling filesystems an overwrite cannot guarantee the old blocks are gone. Add
--keep-keysto keep the address for later.
Health reads healthy, degraded, down, pending (the address is not written yet) or instance_missing (the hosting instance was deleted; remove the entry). Descriptor: built means Tor has built the service descriptor, the step before it uploads it to the onion directories; the reachability test then connects to the address through Tor. Add --no-probe to skip that test.
KEEP A HOSTED SERVICE APART
Hosting a service on an instance you also browse through lets an observer of that instance link the two. For a service that should stand apart, create a dedicated instance and host it there.
Live Circuit View
See which relays carry your traffic right now. For every circuit of an instance it shows the guard, the middle relays and, on circuits that leave the Tor network, the exit, each with its country and address, plus Tor's bootstrap progress. Onion-service circuits name their last hop as the rendezvous point, introduction point or directory instead. It only asks Tor; it never builds or closes a circuit.
# Circuits of the default instance
sudo tor-switch show-circuits
# One pool instance, as JSON (with each circuit's purpose and build flags)
sudo tor-switch show-circuits --instance kodachi_tor_inst_2 --json
Countries come from Tor's own GeoIP database; ?? means unknown. Use sudo tor-switch new-tor-circuit when you want different relays.
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 | ~150MB | Per Tor instance (measured average warm memory, 98 to 170 MB across 10 instances) |
| 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
sudo 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: Every nftables rule cleared (not only the Tor rules)
# Step 3: Flush iptables rules as fallback
sudo tor-switch flush-iptables
# Expected: Every iptables rule cleared (not only the Tor rules)
# 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
sudo 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: Store obfs4 bridge lines and turn on bridge mode for every Kodachi instance
# (bridges in /etc/tor/torrc would only reach the system Tor, not the Kodachi instances)
sudo tor-switch set-bridges --bridge 'obfs4 <address:port> <fingerprint> cert=<cert> iat-mode=0'
# Repeat --bridge for each line, or use --from-file / --stdin-bridges
# Step 5: Validate the stored bridge lines
tor-switch test-bridges
# Expected: Bridge lines valid and obfs4proxy found
# Step 6: Confirm the stored bridges and the detected obfs4proxy path
tor-switch list-bridges
# 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
WHEN OBFS4 BRIDGES ARE BLOCKED TOO
Step 4 also accepts other bridge types with --transport. Every stored line must start with the chosen name; copy complete lines: obfs4 and webtunnel lines from https://bridges.torproject.org/, snowflake and meek_lite lines from Tor Browser's built-in bridge settings. One bridge per line: a line that holds two bridges is refused.
- snowflake: reaches Tor through short-lived volunteer proxies over WebRTC. Kodachi ships
snowflake-client(if it is missing:sudo apt install snowflake-client); slower than obfs4. - meek_lite: hides the connection inside HTTPS to a large front domain; it uses the obfs4 plugin Kodachi already ships.
- webtunnel: looks like ordinary HTTPS to a web server. It needs the
lyrebirdplugin, which Debian does not package: copy lyrebird from Tor Browser's Browser/TorBrowser/Tor/PluggableTransports folder to /usr/local/bin;tor-switch list-bridgesshows which plugin was found.
# A snowflake bridge (one complete line from a current snowflake bridge source)
sudo tor-switch set-bridges --transport snowflake --bridge 'snowflake 192.0.2.3:80 <FINGERPRINT> fingerprint=<FINGERPRINT> url=https://<broker-front>/ fronts=<cdn-host> ice=stun:<stun-host>:3478'
# webtunnel lines from a file, one per line
sudo tor-switch set-bridges --transport webtunnel --from-file webtunnel-bridges.txt
# The stored lines, the transport in use and the plugin path
tor-switch list-bridges
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 <hooks-dir>/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
sudo 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
sudo 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 <hooks-dir>/logs/tor-switch-log.log
# Step 10: Generate system health report
sudo 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
sudo 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-timer 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
sudo 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.
Scenario 21: Host a Service as an Onion Address
Publish a small web site that runs on this machine, without exposing its address, and keep an eye on it.
# Step 1: Start the service on loopback only (a static site in the current directory)
python3 -m http.server 8080 --bind 127.0.0.1
# Step 2: In a second terminal, create a dedicated instance for hosting
sudo tor-switch create-instance onionhost
# Step 3: Publish it
sudo tor-switch onion-service-create --name site --target 127.0.0.1:8080 --instance onionhost
# Expected: the new <56 characters>.onion address
# Step 4: Check its health (publishing can take a minute)
sudo tor-switch onion-service-status --name site
# Expected: Health healthy, Descriptor built, Reachable yes
# Step 5: When you are done, stop hosting it and wipe its keys
sudo tor-switch onion-service-remove --name site --restart-ok
Cross-binary workflow: tor-switch
When to run: Sharing a site or a service with people who reach it through Tor, without revealing where it runs.
Scenario 22: Read Your Circuits
Check which countries your traffic passes through before sensitive work, and get new relays if you do not like them.
# Step 1: See the relays and countries of every circuit
sudo tor-switch show-circuits
# Step 2: Ask for new circuits
sudo tor-switch new-tor-circuit
# Step 3: Confirm the new path
sudo tor-switch show-circuits
# Step 4: Exclude countries for good (see Scenario 3)
sudo tor-switch set-exclude-node-all 9eyes
Cross-binary workflow: tor-switch
When to run: Before sensitive work, or when a site behaves as if you were in an unexpected country.
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