tor-switch

Tor configuration and routing management for Kodachi OS

Version: 9.0.1 | Size: 13.6MB | Author: Warith Al Maawali

License: Proprietary | Website: https://digi77.com

File Information

Property	Value
Binary Name	tor-switch
Version	9.0.1
Build Date	2025-09-23T19:20:06.409667585Z
Rust Version	1.82.0
File Size	13.6MB
JSON Data	View Raw JSON

SHA256 Checksum

586cf36a44e6875479ef20113cfc7d8437bd6d3fba47ef646c3dbd60dd57fe50

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

Authentication

`verify_auth`

Verify authentication status

Usage:

tor-switch verify_auth [OPTIONS]

`refresh_auth`

Refresh authentication

Usage:

tor-switch refresh_auth [OPTIONS]

Basic Operations

`start_tor`

Start Tor daemon

Usage:

tor-switch start_tor [OPTIONS]

`stop_tor`

Stop Tor daemon

Usage:

tor-switch stop_tor [OPTIONS]

`restart_tor`

Restart Tor daemon

Usage:

tor-switch restart_tor [OPTIONS]

Configuration

`validate_torrc`

Validate torrc configuration

Usage:

tor-switch validate_torrc [OPTIONS]

`reload_tor_config`

Reload Tor configuration

Usage:

tor-switch reload_tor_config [OPTIONS]

`reload_tor_config_all`

Reload config for all instances

Usage:

tor-switch reload_tor_config_all [OPTIONS]

`backup_config`

Backup configuration

Usage:

tor-switch backup_config [OPTIONS]

`backup_config_all`

Backup all configurations

Usage:

tor-switch backup_config_all [OPTIONS]

`restore_config`

Restore configuration

Usage:

tor-switch restore_config [OPTIONS]

`restore_config_all`

Restore all configurations

Usage:

tor-switch restore_config_all [OPTIONS]

`list_backups`

List configuration backups

Usage:

tor-switch list_backups [OPTIONS]

`generate_new_tor_password`

Generate new Tor control password

Usage:

tor-switch generate_new_tor_password [OPTIONS]

`generate_new_tor_password_all`

Generate password for all instances

Usage:

tor-switch generate_new_tor_password_all [OPTIONS]

`clean_torrc_custom`

Clean custom torrc file

Usage:

tor-switch clean_torrc_custom [OPTIONS]

`clean_torrc_custom_all`

Clean custom torrc for all instances

Usage:

tor-switch clean_torrc_custom_all [OPTIONS]

DNS Management

`start_tor_dns_iptables`

Start Tor DNS with iptables

Usage:

tor-switch start_tor_dns_iptables [OPTIONS]

`start_tor_dns_nftables`

Start Tor DNS with nftables

Usage:

tor-switch start_tor_dns_nftables [OPTIONS]

`stop_tor_dns_iptables`

Stop Tor DNS iptables

Usage:

tor-switch stop_tor_dns_iptables [OPTIONS]

`stop_tor_dns_nftables`

Stop Tor DNS nftables

Usage:

tor-switch stop_tor_dns_nftables [OPTIONS]

`torrify_system_dns`

Route DNS through Tor

Usage:

tor-switch torrify_system_dns [OPTIONS]

`torrify_system_iptables_dns`

Route DNS through Tor with iptables

Usage:

tor-switch torrify_system_iptables_dns [OPTIONS]

`torrify_system_nftables_dns`

Route DNS through Tor with nftables

Usage:

tor-switch torrify_system_nftables_dns [OPTIONS]

`verify_tor_dns`

Verify Tor DNS resolution

Usage:

tor-switch verify_tor_dns [OPTIONS]

`verify_tor_dns_all`

Verify DNS for all instances

Usage:

tor-switch verify_tor_dns_all [OPTIONS]

`verify_tor_dns_direct`

Direct Tor DNS verification

Usage:

tor-switch verify_tor_dns_direct [OPTIONS]

`verify_tor_dns_port`

Verify Tor DNS port

Usage:

tor-switch verify_tor_dns_port [OPTIONS]

Exit Node Control

`set_exit_node`

Set Tor exit node

Usage:

tor-switch set_exit_node [OPTIONS]

`set_exit_node_all`

Set exit node for all instances

Usage:

tor-switch set_exit_node_all [OPTIONS]

`set_exclude_node`

Set excluded nodes

Usage:

tor-switch set_exclude_node [OPTIONS]

`set_exclude_node_all`

Set excluded nodes for all instances

Usage:

tor-switch set_exclude_node_all [OPTIONS]

`clear_exit_node`

Clear exit node restrictions

Usage:

tor-switch clear_exit_node [OPTIONS]

`clear_exit_node_all`

Clear exit node for all instances

Usage:

tor-switch clear_exit_node_all [OPTIONS]

`new_tor_circuit`

Create new Tor circuit

Usage:

tor-switch new_tor_circuit [OPTIONS]

`new_tor_circuit_all`

New circuit for all instances

Usage:

tor-switch new_tor_circuit_all [OPTIONS]

Firewall

`flush_iptables`

Flush iptables rules

Usage:

tor-switch flush_iptables [OPTIONS]

`flush_nftables`

Flush nftables rules

Usage:

tor-switch flush_nftables [OPTIONS]

`list_iptables`

List iptables rules

Usage:

tor-switch list_iptables [OPTIONS]

`list_iptables_nat`

List iptables NAT rules

Usage:

tor-switch list_iptables_nat [OPTIONS]

`list_nftables`

List nftables rules

Usage:

tor-switch list_nftables [OPTIONS]

HAProxy

`generate_haproxy_config`

Generate HAProxy configuration

Usage:

tor-switch generate_haproxy_config [OPTIONS]

`haproxy_start`

Start HAProxy service

Usage:

tor-switch haproxy_start [OPTIONS]

`haproxy_stop`

Stop HAProxy service

Usage:

tor-switch haproxy_stop [OPTIONS]

`haproxy_status`

Check HAProxy status

Usage:

tor-switch haproxy_status [OPTIONS]

`list_haproxy_modes`

List HAProxy load balancing modes

Usage:

tor-switch list_haproxy_modes [OPTIONS]

`display_load_balancing_config`

Display load balancing configuration

Usage:

tor-switch display_load_balancing_config [OPTIONS]

Help

`show_help`

Show help information

Usage:

tor-switch show_help [OPTIONS]

`show_examples`

Show usage examples

Usage:

tor-switch show_examples [OPTIONS]

Instance Management

`create_instance`

Create new Tor instance

Usage:

tor-switch create_instance [OPTIONS]

`delete_instance`

Delete Tor instance

Usage:

tor-switch delete_instance [OPTIONS]

`delete_all_instances`

Delete all Tor instances

Usage:

tor-switch delete_all_instances [OPTIONS]

`delete_all_instances_with_default`

Delete all instances including default

Usage:

tor-switch delete_all_instances_with_default [OPTIONS]

`start_instance`

Start a Tor instance

Usage:

tor-switch start_instance [OPTIONS]

`stop_instance`

Stop a Tor instance

Usage:

tor-switch stop_instance [OPTIONS]

`restart_instance`

Restart a Tor instance

Usage:

tor-switch restart_instance [OPTIONS]

`start_all_instances`

Start all Tor instances

Usage:

tor-switch start_all_instances [OPTIONS]

`stop_all_instances`

Stop all Tor instances

Usage:

tor-switch stop_all_instances [OPTIONS]

`show_instance`

Show instance details

Usage:

tor-switch show_instance [OPTIONS]

`set_default_instance`

Set default Tor instance

Usage:

tor-switch set_default_instance [OPTIONS]

`rename_instance`

Rename a Tor instance

Usage:

tor-switch rename_instance [OPTIONS]

`clone_instance`

Clone a Tor instance

Usage:

tor-switch clone_instance [OPTIONS]

`create_multiple_instances`

Create multiple Tor instances

Usage:

tor-switch create_multiple_instances [OPTIONS]

Load Balancing

`set_load_balancing_mode`

Set load balancing mode

Usage:

tor-switch set_load_balancing_mode [OPTIONS]

`set_instance_weight`

Set instance weight for load balancing

Usage:

tor-switch set_instance_weight [OPTIONS]

`torrify_system_iptables_load_balanced`

Torrify with iptables load balancing

Usage:

tor-switch torrify_system_iptables_load_balanced [OPTIONS]

`torrify_system_nftables_load_balanced`

Torrify with nftables load balancing

Usage:

tor-switch torrify_system_nftables_load_balanced [OPTIONS]

Main Tor Management

`validate_torrc_main`

Validate main Tor configuration

Usage:

tor-switch validate_torrc_main [OPTIONS]

`read_main_tor_config`

Display main Tor settings (ports, exit/exclude nodes, security)

Usage:

tor-switch read_main_tor_config [OPTIONS]

`backup_main_tor_config`

Backup main Tor configuration

Usage:

tor-switch backup_main_tor_config [OPTIONS]

`restore_main_tor_config`

Restore main Tor configuration from backup

Usage:

tor-switch restore_main_tor_config [OPTIONS]

`set_exit_node_main`

Set exit node for main Tor

Usage:

tor-switch set_exit_node_main [OPTIONS]

`clear_exit_node_main`

Clear exit restrictions for main Tor

Usage:

tor-switch clear_exit_node_main [OPTIONS]

`set_exclude_node_main`

Set excluded countries for main Tor

Usage:

tor-switch set_exclude_node_main [OPTIONS]

`clear_exclude_node_main`

Clear exclude restrictions for main Tor

Usage:

tor-switch clear_exclude_node_main [OPTIONS]

`list_exit_exclude_main`

Show current exit/exclude settings for main Tor

Usage:

tor-switch list_exit_exclude_main [OPTIONS]

`reload_main_tor`

Reload main Tor configuration (SIGHUP)

Usage:

tor-switch reload_main_tor [OPTIONS]

`status_main_tor`

Detailed status of main Tor daemon

Usage:

tor-switch status_main_tor [OPTIONS]

`verify_main_tor_dns`

Verify DNS routing through main Tor

Usage:

tor-switch verify_main_tor_dns [OPTIONS]

`new_circuit_main_tor`

Request new circuit for main Tor

Usage:

tor-switch new_circuit_main_tor [OPTIONS]

`check_main_tor_security`

Security audit of main Tor config

Usage:

tor-switch check_main_tor_security [OPTIONS]

`main_tor_bandwidth`

Show bandwidth usage of main Tor

Usage:

tor-switch main_tor_bandwidth [OPTIONS]

`main_tor_connections`

List active connections through main Tor

Usage:

tor-switch main_tor_connections [OPTIONS]

`main_tor_logs`

Display recent main Tor logs

Usage:

tor-switch main_tor_logs [OPTIONS]

Status Operations

`check_tor`

Check if Tor is working

Usage:

tor-switch check_tor [OPTIONS]

`check_tor_all`

Check if Tor is working for all instances

Usage:

tor-switch check_tor_all [OPTIONS]

`torverify`

Verify Tor connectivity through network check

Usage:

tor-switch torverify [OPTIONS]

`tor_status`

Get detailed Tor status

Usage:

tor-switch tor_status [OPTIONS]

`tor_status_all`

Get Tor status for all instances

Usage:

tor-switch tor_status_all [OPTIONS]

`get_tor_status`

Get Tor status information

Usage:

tor-switch get_tor_status [OPTIONS]

`get_tor_custom_status`

Get custom Tor status

Usage:

tor-switch get_tor_custom_status [OPTIONS]

`list_instances`

List all Tor instances

Usage:

tor-switch list_instances [OPTIONS]

`list_instances_with_ip`

List all Tor instances with IP addresses

Usage:

tor-switch list_instances_with_ip [OPTIONS]

System Management

`which_is_active`

Check active firewall system

Usage:

tor-switch which_is_active [OPTIONS]

`cleanup`

Clean up orphaned Tor instances

Usage:

tor-switch cleanup [OPTIONS]

`clean_orphan_services`

Clean orphaned services

Usage:

tor-switch clean_orphan_services [OPTIONS]

System Routing

`torrify_system_iptables`

Route all traffic through Tor (iptables)

Usage:

tor-switch torrify_system_iptables [OPTIONS]

`detorrify_system_iptables`

Stop routing traffic through Tor (iptables)

Usage:

tor-switch detorrify_system_iptables [OPTIONS]

`torrify_system_nftables`

Route all traffic through Tor (nftables)

Usage:

tor-switch torrify_system_nftables [OPTIONS]

`detorrify_system_nftables`

Stop routing traffic through Tor (nftables)

Usage:

tor-switch detorrify_system_nftables [OPTIONS]

Timer & Automation

`auto_ip_change`

Enable automatic IP changes

Usage:

tor-switch auto_ip_change [OPTIONS]

`stop_auto_ip_change`

Stop automatic IP changes

Usage:

tor-switch stop_auto_ip_change [OPTIONS]

`update_ip_timer`

Update IP change timer

Usage:

tor-switch update_ip_timer [OPTIONS]

`update_ip_all_timer`

Update timer for all instances

Usage:

tor-switch update_ip_all_timer [OPTIONS]

`remove_ip_timer`

Remove IP change timer

Usage:

tor-switch remove_ip_timer [OPTIONS]

`remove_ip_all_timer`

Remove all IP timers

Usage:

tor-switch remove_ip_all_timer [OPTIONS]

`list_ip_timers`

List all IP change timers

Usage:

tor-switch list_ip_timers [OPTIONS]

`list_auto_ip_change`

List auto IP change settings

Usage:

tor-switch list_auto_ip_change [OPTIONS]

Examples

Basic Usage

Essential operations for getting started

Start Tor daemon

sudo tor-switch start_tor

Expected Output: Tor daemon started successfully

Note

Requires sudo privileges for system-level operations

Stop Tor daemon

sudo tor-switch stop_tor

Expected Output: Tor daemon stopped successfully

Note

Gracefully shuts down Tor service

Restart Tor daemon

sudo tor-switch restart_tor

Expected Output: Tor daemon restarted successfully

Note

Combines stop and start operations

Route all traffic through Tor

sudo tor-switch torrify_system_iptables

Expected Output: System traffic routing through Tor enabled

Note

All network traffic will be routed through Tor

Stop routing traffic through Tor

sudo tor-switch detorrify_system_iptables

Expected Output: System traffic routing through Tor disabled

Note

Returns to normal direct internet connection

Check if Tor service is running

sudo tor-switch check_tor

Expected Output: Tor is responding/not responding

Note

Checks if Tor service is active via systemctl

Verify actual Tor connectivity

sudo tor-switch torverify

Expected Output: Shows whether traffic is routed through Tor and displays IP

Note

Makes direct HTTP request to check.torproject.org to verify torrification

Get new Tor circuit/IP

sudo tor-switch new_tor_circuit

Expected Output: New circuit established with different exit IP

Note

Forces new Tor circuit for different exit node

Instance Management

Managing multiple Tor instances for performance

Create a secondary Tor instance

sudo tor-switch create_instance secondary

Expected Output: Instance 'secondary' created successfully

Note

Multiple instances provide load balancing and redundancy

List all available instances

sudo tor-switch list_instances

Expected Output: Shows all instances with their status

Start specific instance

sudo tor-switch start_instance secondary

Expected Output: Instance 'secondary' started

Stop specific instance

sudo tor-switch stop_instance secondary

Expected Output: Instance 'secondary' stopped

Restart specific instance

sudo tor-switch restart_instance secondary

Expected Output: Instance 'secondary' restarted

Delete an instance permanently

sudo tor-switch delete_instance secondary

Expected Output: Instance 'secondary' deleted

Note

This permanently removes the instance configuration

Start all configured instances

sudo tor-switch start_all_instances

Expected Output: All Tor instances started

Stop all running instances

sudo tor-switch stop_all_instances

Expected Output: All Tor instances stopped

Advanced Instance Operations

Create, clone, rename and manage multiple Tor instances

Create 5 auto-named instances

sudo tor-switch create_multiple_instances 5

Expected Output: 5 Tor instances created with auto-generated names

Note

Useful for load balancing and redundancy

Create 3 instances with 'performance' prefix

sudo tor-switch create_multiple_instances 3 performance

Expected Output: 3 instances created: performance_0, performance_1, performance_2

Note

Creates instances with custom naming prefix

Create 10 worker instances

sudo tor-switch create_multiple_instances 10 worker

Expected Output: 10 instances created: worker_1 through worker_10

Note

Ideal for high-throughput operations

Create 5 regional instances

sudo tor-switch create_multiple_instances 5 region

Expected Output: 5 instances created: region_1 through region_5

Note

Perfect for geographic distribution

Create 3 node instances

sudo tor-switch create_multiple_instances 3 node

Expected Output: 3 instances created: node_1, node_2, node_3

Note

Simple node-based naming

Clone 'main' instance to 'backup'

sudo tor-switch clone_instance main backup

Expected Output: Instance 'main' cloned to 'backup' successfully

Note

Copies all configuration from source instance

Rename instance

sudo tor-switch rename_instance old_name new_name

Expected Output: Instance renamed from 'old_name' to 'new_name'

Note

Updates all references and configuration files

List all instances with current IP addresses

sudo tor-switch list_instances_with_ip

Expected Output: All instances listed with their current exit IPs

Note

Shows both instance names and their current exit IPs

Show detailed information for 'streaming' instance

sudo tor-switch show_instance streaming

Expected Output: Detailed configuration and status for 'streaming' instance

Note

Shows configuration, status, and current IP information

Set 'performance_0' as the default instance

sudo tor-switch set_default_instance performance_0

Expected Output: Default instance set to 'performance_0'

Note

Changes which instance is used for default operations

Set weight for load balancing

sudo tor-switch set_instance_weight secondary 50

Expected Output: Instance 'secondary' weight set to 50

Note

Used for load balancing when multiple instances are active

Delete all instances except default

sudo tor-switch delete_all_instances

Expected Output: All non-default instances deleted

Note

Preserves default instance for basic functionality

Delete ALL instances including default

sudo tor-switch delete_all_instances_with_default

Expected Output: All instances deleted including default

Note

WARNING: Removes all instances

Monitoring & Status

Checking system status and verifying operations

Get detailed Tor status

sudo tor-switch tor_status

Expected Output: Comprehensive status report of all Tor components

Detailed status in JSON format

sudo tor-switch tor_status --json

Expected Output: JSON-formatted status report

Note

Machine-readable output for scripts

Check Tor status for all instances

sudo tor-switch check_tor_all

Expected Output: Connection status for every configured instance

Note

Quick health check across all instances

Verify if system traffic is routed through Tor

sudo tor-switch torverify

Expected Output: ✓ You are connected through Tor IP Address:

Note

Makes HTTP request to check.torproject.org API to verify torrification

Verify Tor connectivity with detailed JSON output

sudo tor-switch torverify --json-pretty

Expected Output: { "is_tor": true, "ip_address": "", "method": "api" }

Note

Useful for scripts and automation

Get detailed status for all instances

sudo tor-switch tor_status_all

Expected Output: Comprehensive status report for all instances

Get Tor daemon status

sudo tor-switch get_tor_status

Expected Output: Current Tor daemon status

Note

Quick status check - use tor_status for detailed report

Troubleshooting

Debug and resolve common issues

Clean up orphaned processes

sudo tor-switch cleanup

Expected Output: Orphaned instances and services cleaned up

Note

Use when experiencing startup issues

Thorough cleanup including systemd units

sudo tor-switch cleanup --thorough

Expected Output: Complete cleanup including failed systemd services

Note

More comprehensive than regular cleanup

Clean orphaned services

sudo tor-switch clean_orphan_services

Expected Output: Orphaned services removed

New circuits for all instances

sudo tor-switch new_tor_circuit_all

Expected Output: All instances have new circuits with different IPs

Note

Refreshes exit IPs for all active instances

Start with detailed logging

sudo tor-switch --verbose start_tor

Expected Output: Detailed startup process information

Note

Use when diagnosing startup problems

4. EXIT NODE MANAGEMENT

Control and configure Tor exit nodes for geographic routing and privacy

Route via United States

sudo tor-switch set_exit_node us

Expected Output: Exit node set to United States

Note

Traffic will exit through US-based Tor nodes

Set UK exit for specific instance

sudo tor-switch set_exit_node gb --instance secondary

Expected Output: Exit node set to United Kingdom for 'secondary'

Note

Instance-specific exit node configuration

Set Germany exit for streaming instance

sudo tor-switch set_exit_node de --instance streaming

Expected Output: Exit node set to Germany for 'streaming'

Note

Useful for geo-restricted content

Set Switzerland exit for secure instance

sudo tor-switch set_exit_node ch --instance secure

Expected Output: Exit node set to Switzerland for 'secure'

Note

Privacy-friendly jurisdiction

Random exit node selection

sudo tor-switch set_exit_node random

Expected Output: Exit node set to random selection

Note

Maximum anonymity through randomization

Random worldwide exit node

sudo tor-switch set_exit_node random_world

Expected Output: Exit node set to random country worldwide

Note

Maximum geographic diversity

Random European exit node

sudo tor-switch set_exit_node random_europe

Expected Output: Exit node set to random European country

Note

Stay within European jurisdiction

Random Asian exit node

sudo tor-switch set_exit_node random_asia

Expected Output: Exit node set to random Asian country

Note

Exit through Asian infrastructure

Random African exit node

sudo tor-switch set_exit_node random_africa

Expected Output: Exit node set to random African country

Note

Exit through African networks

Random North American exit

sudo tor-switch set_exit_node random_north_america

Expected Output: Exit node set to random North American country

Note

US, Canada, or Mexico exit

Random South American exit

sudo tor-switch set_exit_node random_south_america

Expected Output: Exit node set to random South American country

Note

Latin American exit points

Random Oceania exit node

sudo tor-switch set_exit_node random_oceania

Expected Output: Exit node set to random Oceania country

Note

Australia, NZ, or Pacific islands

Random Middle Eastern exit

sudo tor-switch set_exit_node random_middle_east

Expected Output: Exit node set to random Middle Eastern country

Note

Middle Eastern exit points

Random Five Eyes exit

sudo tor-switch set_exit_node random_5eyes

Expected Output: Exit node set to random Five Eyes country

Note

US, UK, CA, AU, or NZ

Random Nine Eyes exit

sudo tor-switch set_exit_node random_9eyes

Expected Output: Exit node set to random Nine Eyes country

Note

5eyes + DK, FR, NL, NO

Random Fourteen Eyes exit

sudo tor-switch set_exit_node random_14eyes

Expected Output: Exit node set to random Fourteen Eyes country

Note

9eyes + DE, BE, IT, ES, SE

Random high-traffic exit

sudo tor-switch set_exit_node random_high_volume

Expected Output: Exit node set to random high-volume country

Note

Better performance and anonymity

Random low-traffic exit

sudo tor-switch set_exit_node random_low_volume

Expected Output: Exit node set to random low-volume country

Note

Less common exit points

Route through any European country

sudo tor-switch set_exit_node europe

Expected Output: Exit node set to Europe region

Note

GDPR-compliant region

Route through any Asian country

sudo tor-switch set_exit_node asia

Expected Output: Exit node set to Asia region

Note

Asian network infrastructure

Route through any African country

sudo tor-switch set_exit_node africa

Expected Output: Exit node set to Africa region

Note

African exit nodes

Route through North America

sudo tor-switch set_exit_node north_america

Expected Output: Exit node set to North America region

Note

US, Canada, or Mexico

Route through South America

sudo tor-switch set_exit_node south_america

Expected Output: Exit node set to South America region

Note

Latin American countries

Route through Oceania

sudo tor-switch set_exit_node oceania

Expected Output: Exit node set to Oceania region

Note

Pacific region countries

Route through Middle East

sudo tor-switch set_exit_node middle_east

Expected Output: Exit node set to Middle East region

Note

Middle Eastern countries

Use Five Eyes countries

sudo tor-switch set_exit_node 5eyes

Expected Output: Exit node set to Five Eyes alliance

Note

US, UK, Canada, Australia, NZ

Use Nine Eyes countries

sudo tor-switch set_exit_node 9eyes

Expected Output: Exit node set to Nine Eyes alliance

Note

5eyes + Denmark, France, Netherlands, Norway

Use Fourteen Eyes countries

sudo tor-switch set_exit_node 14eyes

Expected Output: Exit node set to Fourteen Eyes alliance

Note

9eyes + Germany, Belgium, Italy, Spain, Sweden

Use high-traffic countries

sudo tor-switch set_exit_node high_volume

Expected Output: Exit node set to high-volume countries

Note

Better performance and anonymity

Use low-traffic countries

sudo tor-switch set_exit_node low_volume

Expected Output: Exit node set to low-volume countries

Note

Less common exit points for uniqueness

Set Canada for all instances

sudo tor-switch set_exit_node_all ca

Expected Output: Exit node set to Canada for all instances

Note

Applies setting to all configured instances

Clear exit node restrictions

sudo tor-switch clear_exit_node

Expected Output: Exit node restrictions cleared

Note

Returns to default random exit selection

Exclude specific countries

sudo tor-switch set_exclude_node cn,ru,ir

Expected Output: Excluded nodes set

Note

Prevents routing through specified countries

Exclude Five Eyes countries

sudo tor-switch set_exclude_node 5eyes

Expected Output: Five Eyes countries excluded

Note

US, UK, Canada, Australia, New Zealand

Exclude Nine Eyes countries

sudo tor-switch set_exclude_node 9eyes

Expected Output: Nine Eyes countries excluded

Note

5eyes + Denmark, France, Netherlands, Norway

Exclude Fourteen Eyes countries

sudo tor-switch set_exclude_node 14eyes

Expected Output: Fourteen Eyes countries excluded

Note

9eyes + Germany, Belgium, Italy, Spain, Sweden

Exclude all European countries

sudo tor-switch set_exclude_node europe

Expected Output: European countries excluded

Note

Routes traffic outside Europe

Exclude all Asian countries

sudo tor-switch set_exclude_node asia

Expected Output: Asian countries excluded

Note

Avoids Asian network infrastructure

Exclude North American countries

sudo tor-switch set_exclude_node north_america

Expected Output: North American countries excluded

Note

US, Canada, Mexico excluded

Exclude high-traffic countries

sudo tor-switch set_exclude_node high_volume

Expected Output: High-volume countries excluded

Note

Forces use of less common exit nodes

Exclude low-traffic countries

sudo tor-switch set_exclude_node low_volume

Expected Output: Low-volume countries excluded

Note

Use only high-traffic exit nodes

Exclude one random high-traffic country

sudo tor-switch set_exclude_node random_high_volume

Expected Output: Random high-volume country excluded

Note

Randomly blocks one popular exit country

Exclude one random low-traffic country

sudo tor-switch set_exclude_node random_low_volume

Expected Output: Random low-volume country excluded

Note

Randomly blocks one uncommon exit country

Exclude Asia for secure instance

sudo tor-switch set_exclude_node asia --instance secure

Expected Output: Asia excluded for 'secure' instance

Note

Instance-specific exclusion

Exclude 14eyes for privacy instance

sudo tor-switch set_exclude_node 14eyes --instance privacy_1

Expected Output: 14eyes excluded for 'privacy_1' instance

Note

Maximum privacy configuration

Exclude France for all instances

sudo tor-switch set_exclude_node_all fr

Expected Output: France excluded for all instances

Note

Global exclusion across all instances

Clear all excluded countries

sudo tor-switch clear_exclude_node

Expected Output: All exclusions removed

Note

Resets to default behavior

Clear exit restrictions for all instances

sudo tor-switch clear_exit_node_all

Expected Output: Exit restrictions cleared for all instances

Note

All instances return to random exit selection

7. LOAD BALANCING (Native Kernel-Level)

Native load balancing using iptables/nftables firewall rules

Sequential distribution

sudo tor-switch set_load_balancing_mode round-robin

Expected Output: Load balancing mode set to round-robin

Note

Each new connection uses the next Tor instance in order

Weight-based distribution

sudo tor-switch set_load_balancing_mode weighted

Expected Output: Load balancing mode set to weighted

Note

Routes traffic based on instance weights

Client IP affinity for session persistence

sudo tor-switch set_load_balancing_mode consistent-hashing

Expected Output: Load balancing mode set to consistent-hashing

Note

Same client IP always routes to same Tor instance

Set weight for specific instance

sudo tor-switch set_instance_weight tor1 50

Expected Output: Weight for instance 'tor1' set to 50

Note

Only affects weighted mode distribution

Set low weight for minimal traffic

sudo tor-switch set_instance_weight tor1 10

Expected Output: Weight for instance 'tor1' set to 10

Note

10% of traffic when using weighted mode

Set moderate weight for balanced traffic

sudo tor-switch set_instance_weight tor2 30

Expected Output: Weight for instance 'tor2' set to 30

Note

30% of traffic distribution

Set high weight for primary traffic

sudo tor-switch set_instance_weight tor3 60

Expected Output: Weight for instance 'tor3' set to 60

Note

60% of traffic - primary instance

High weight for performance instance

sudo tor-switch set_instance_weight performance_0 75

Expected Output: Weight for instance 'performance_0' set to 75

Note

Prioritize high-performance instance

Minimal weight for backup instance

sudo tor-switch set_instance_weight backup 5

Expected Output: Weight for instance 'backup' set to 5

Note

Mostly idle, used for failover

Equal weight for worker instances

sudo tor-switch set_instance_weight worker_1 25

Expected Output: Weight for instance 'worker_1' set to 25

Note

4 workers at 25% each = equal distribution

Show current load balancing setup

sudo tor-switch display_load_balancing_config

Expected Output: Current load balancing configuration details

Apply load balanced routing (iptables)

sudo tor-switch torrify_system_iptables_load_balanced

Expected Output: Load balanced routing through Tor enabled

Note

Routes traffic through multiple Tor instances using iptables

Apply load balanced routing (nftables)

sudo tor-switch torrify_system_nftables_load_balanced

Expected Output: Load balanced routing through Tor enabled (nftables)

Note

Modern firewall load balanced routing using nftables

8. HAPROXY INTEGRATION (Application-Level Proxy)

HAProxy provides advanced application-level load balancing

Generate config with round-robin algorithm

sudo tor-switch generate_haproxy_config roundrobin 9055

Expected Output: HAProxy configuration generated

Note

Each server is used in turns on port 9055

Generate config with source IP hash

sudo tor-switch generate_haproxy_config source 8080

Expected Output: HAProxy configuration generated

Note

IP hash persistence on port 8080

Generate config with least connections

sudo tor-switch generate_haproxy_config leastconn 9000

Expected Output: HAProxy configuration generated

Note

Routes to instance with fewest active connections

Generate config with random selection

sudo tor-switch generate_haproxy_config random 8888

Expected Output: HAProxy configuration generated

Note

Randomly selects backend for each connection

Start HAProxy service

sudo tor-switch haproxy_start

Expected Output: HAProxy started successfully

Check HAProxy status

sudo tor-switch haproxy_status

Expected Output: HAProxy service status and statistics

Stop HAProxy service

sudo tor-switch haproxy_stop

Expected Output: HAProxy stopped

Show available HAProxy algorithms

sudo tor-switch list_haproxy_modes

Expected Output: List of supported HAProxy algorithms

Note

roundrobin, source, leastconn, random

Timer Management and Automation

Automatic IP rotation and timer-based operations

Auto IP change every 10 minutes

sudo tor-switch auto_ip_change 10m

Expected Output: Automatic IP change enabled with 10 minute interval

Note

Creates new Tor circuit to get new exit IP

Set timer for specific instance

sudo tor-switch update_ip_timer browsing 5m

Expected Output: IP change timer set for 'browsing' instance

Set 30-minute timer for worker instance

sudo tor-switch update_ip_timer worker_1 30m

Expected Output: IP change timer set for 'worker_1' instance: 30 minutes

Note

Balanced rotation for moderate privacy

Set hourly timer for streaming

sudo tor-switch update_ip_timer streaming 1h

Expected Output: IP change timer set for 'streaming' instance: 1 hour

Note

Less frequent changes for stable connections

Set 15-minute timer for research

sudo tor-switch update_ip_timer research 15m

Expected Output: IP change timer set for 'research' instance: 15 minutes

Note

Frequent rotation for privacy-focused browsing

Set daily timer for backup instance

sudo tor-switch update_ip_timer backup 24h

Expected Output: IP change timer set for 'backup' instance: 24 hours

Note

Minimal rotation for long-running operations

Set 10-minute timer for all instances

sudo tor-switch update_ip_all_timer 10m

Expected Output: IP change timer set for all instances: 10 minutes

Note

Synchronizes rotation across all instances

Set 2-hour timer for all instances

sudo tor-switch update_ip_all_timer 2h

Expected Output: IP change timer set for all instances: 2 hours

Note

Stable rotation for production workloads

List all IP change timers

sudo tor-switch list_ip_timers

Expected Output: Table showing all instances with their IP change intervals

Remove timer for instance

sudo tor-switch remove_ip_timer browsing

Expected Output: IP change timer removed

Stop auto IP change

sudo tor-switch stop_auto_ip_change

Expected Output: Automatic IP change stopped

Set timer for all instances

sudo tor-switch update_ip_all_timer 15m

Expected Output: IP change timer set for all instances

Note

Synchronizes IP rotation across instances

Remove all IP change timers

sudo tor-switch remove_ip_all_timer

Expected Output: All IP timers removed

Note

Removes all automatic IP rotation timers from all instances

List automatic IP change settings

sudo tor-switch list_auto_ip_change

Expected Output: Auto IP change configurations for all instances

DNS Verification

Test and verify DNS routing through Tor

Verify Tor DNS resolution of .onion addresses

sudo tor-switch verify_tor_dns

Expected Output: DNS verification successful! (tests both direct and port methods)

Note

Resolves .onion addresses to verify DNS goes through Tor

Verify DNS resolution for all Tor instances

sudo tor-switch verify_tor_dns_all

Expected Output: DNS verification results for each instance

Note

Tests .onion resolution for all configured Tor instances

Verify .onion resolution using system DNS

sudo tor-switch verify_tor_dns_direct

Expected Output: Onion addresses can be resolved directly

Note

Uses system resolver to test .onion domain resolution

Verify .onion resolution via Tor DNS port

sudo tor-switch verify_tor_dns_port

Expected Output: Onion addresses can be resolved using DNS port

Note

Uses instance's DNS port to test .onion resolution

Verify DNS for specific instance

sudo tor-switch verify_tor_dns_port --instance tor1

Expected Output: DNS verification successful for instance 'tor1'

Note

Tests DNS for a specific Tor instance

DNS Management

Configure and manage DNS routing through Tor

Start Tor DNS listener with iptables

sudo tor-switch start_tor_dns_iptables

Expected Output: Tor DNS service started with iptables rules

Note

Sets up Tor DNS listener service on port 9053

Stop Tor DNS routing

sudo tor-switch stop_tor_dns_iptables

Expected Output: Tor DNS iptables rules removed

Route all DNS through Tor

sudo tor-switch torrify_system_dns

Expected Output: System DNS queries routed through Tor

Note

Universal command - auto-detects and uses active firewall

Start Tor DNS listener with nftables

sudo tor-switch start_tor_dns_nftables

Expected Output: Tor DNS service started with nftables rules

Note

Sets up Tor DNS listener service on port 9053

Stop Tor DNS (nftables)

sudo tor-switch stop_tor_dns_nftables

Expected Output: Tor DNS nftables rules removed

Route DNS through Tor using iptables

sudo tor-switch torrify_system_iptables_dns

Expected Output: DNS routing through Tor enabled (iptables)

Note

Redirects all system DNS queries to Tor DNS listener

Route DNS through Tor using nftables

sudo tor-switch torrify_system_nftables_dns

Expected Output: DNS routing through Tor enabled (nftables)

Note

Redirects all system DNS queries to Tor DNS listener

Firewall Operations

Manage iptables and nftables firewall rules

Flush iptables rules

sudo tor-switch flush_iptables

Expected Output: All iptables rules cleared

Note

Removes all current iptables rules and policies

List current iptables rules

sudo tor-switch list_iptables

Expected Output: Display of all active iptables rules

Check active firewall

sudo tor-switch which_is_active

Expected Output: Shows whether iptables or nftables is active

Flush nftables rules

sudo tor-switch flush_nftables

Expected Output: All nftables rules cleared

Note

Removes all current nftables rules

List current nftables rules

sudo tor-switch list_nftables

Expected Output: Display of all active nftables rules

List NAT rules

sudo tor-switch list_iptables_nat

Expected Output: Display of all NAT table rules

Note

Shows network address translation rules

Configuration Management

Manage Tor configuration files and validation

Validate torrc configuration

sudo tor-switch validate_torrc

Expected Output: Configuration validation results

Note

Checks syntax without starting Tor

Reload configuration

sudo tor-switch reload_tor_config

Expected Output: Configuration reloaded successfully

Note

Applies changes without restart

Generate new control password

sudo tor-switch generate_new_tor_password

Expected Output: New control password generated

Clean custom configuration

sudo tor-switch clean_torrc_custom

Expected Output: Custom torrc entries removed

Clean all custom configurations

sudo tor-switch clean_torrc_custom_all

Expected Output: Custom entries removed from all instances

Reload all configurations

sudo tor-switch reload_tor_config_all

Expected Output: All instance configurations reloaded

Generate passwords for all instances

sudo tor-switch generate_new_tor_password_all

Expected Output: New control passwords generated for all

Get custom configuration status

sudo tor-switch get_tor_custom_status

Expected Output: Status of custom configurations

Backup and Restore

Backup and restore Tor instance configurations

Backup configuration

sudo tor-switch backup_config

Expected Output: Configuration backed up with timestamp

List available backups

sudo tor-switch list_backups

Expected Output: Table showing all backup files

Restore from backup

sudo tor-switch restore_config backup_2025-01-28

Expected Output: Configuration restored

Note

Restores configuration and restarts instances

Backup all configurations

sudo tor-switch backup_config_all

Expected Output: All instance configurations backed up

Restore all from backup

sudo tor-switch restore_config_all backup_2025-01-28

Expected Output: All configurations restored from backup

Note

Restores complete multi-instance setup

Authentication and Verification

Verify authentication status and system integrity

Verify authentication

sudo tor-switch verify_auth

Expected Output: Authentication status and token validity

Note

Required for write operations

Refresh authentication (sends heartbeat manually)

sudo tor-switch refresh_auth

Expected Output: Authentication token refreshed

Note

Manually sends heartbeat to refresh authentication status

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.

Do NOT modify main Tor for regular use

# WARNING: This section is for TROUBLESHOOTING ONLY

Expected Output: Use Kodachi instances instead for all normal operations

Note

Only use these commands for debugging main Tor issues

Validate main Tor configuration

sudo tor-switch validate_torrc_main --maintor

Expected Output: Main Tor configuration validated

Note

Validates /etc/tor/torrc syntax and settings

Display main Tor configuration

sudo tor-switch read_main_tor_config

Expected Output: Main Tor configuration displayed

Note

Shows ports, exit/exclude nodes, and security settings

Backup main Tor configuration

sudo tor-switch backup_main_tor_config

Expected Output: Main Tor configuration backed up

Note

Creates timestamped backup in backups/main-tor/

Restore main Tor configuration

sudo tor-switch restore_main_tor_config torrc_main_20240115_143022.backup

Expected Output: Main Tor configuration restored

Note

Current config is backed up before restoring

Set US exit node for main Tor

sudo tor-switch set_exit_node_main US --maintor

Expected Output: Exit node set to US for main Tor

Note

Forces traffic to exit through United States

Clear exit node restrictions

sudo tor-switch clear_exit_node_main --maintor

Expected Output: Exit node restrictions cleared for main Tor

Note

Allows Tor to choose any exit country

Exclude countries from circuits

sudo tor-switch set_exclude_node_main CN,RU --maintor

Expected Output: Excluded nodes set for main Tor

Note

Prevents routing through specified countries

Clear excluded countries

sudo tor-switch clear_exclude_node_main --maintor

Expected Output: Exclude restrictions cleared for main Tor

Note

Removes all country exclusions

Show exit/exclude settings

sudo tor-switch list_exit_exclude_main

Expected Output: Exit/exclude settings displayed

Note

Displays current geographic routing rules

Reload main Tor configuration

sudo tor-switch reload_main_tor

Expected Output: Main Tor configuration reloaded

Note

Sends SIGHUP signal to apply config changes

Get main Tor daemon status

sudo tor-switch status_main_tor

Expected Output: Main Tor status displayed

Note

Shows systemctl status and port information

Verify DNS routing through Tor

sudo tor-switch verify_main_tor_dns

Expected Output: DNS routing through main Tor verified

Note

Tests DNS resolution via tor-resolve

Request new Tor circuit

sudo tor-switch new_circuit_main_tor

Expected Output: New circuit requested for main Tor

Note

Gets new IP by building fresh circuit

Security audit main Tor

sudo tor-switch check_main_tor_security

Expected Output: Security audit completed

Note

Checks for security misconfigurations

Show Tor bandwidth usage

sudo tor-switch main_tor_bandwidth

Expected Output: Bandwidth usage displayed

Note

Displays active SOCKS connections count

List active Tor connections

sudo tor-switch main_tor_connections

Expected Output: Active connections listed

Note

Shows established connections on SOCKS port

Display recent Tor logs

sudo tor-switch main_tor_logs

Expected Output: Recent logs displayed

Note

Shows last 50 lines from Tor log or journald

Validate with JSON output

sudo tor-switch validate_torrc_main --maintor --json

Expected Output: JSON validation output returned

Note

Machine-readable output for scripting

Advanced Workflows

Complete workflow examples for common use cases

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

Expected Output: Privacy-optimized Tor configuration active

Note

Avoids surveillance alliance countries with rapid rotation

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

Expected Output: Regional Tor instances configured

Note

Access region-specific content simultaneously

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

Expected Output: HA configuration with weighted distribution active

Note

Redundant instances with priority-based traffic distribution

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

Expected Output: Research/testing instances configured

Note

Separate instances for different testing scenarios

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

Expected Output: Performance-optimized setup with HAProxy active

Note

10 instances with HAProxy for maximum throughput

Complete reset to default state

# Clean slate reset
sudo tor-switch stop_all_instances
sudo tor-switch cleanup --thorough
sudo tor-switch flush_iptables
sudo tor-switch restart_tor
sudo tor-switch check_tor

Expected Output: System reset to clean Tor configuration

Note

Removes all custom configurations and instances

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

Expected Output: Full diagnostic report displayed

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