Binary reference

tor-switch

Tor configuration and routing management for Kodachi OS

Version9.8.4 (build 320)Size8.3MBAuthorWarith Al MaawaliLicenseProprietaryWebsitehttps://digi77.com

File Information

Property	Value
Binary Name	tor-switch
Version	9.8.4 (build 320)
Build Date	Not disclosed
Rust Version	1.82.0
File Size	8.3MB
Author	Warith Al Maawali
License	Proprietary
Category	Kodachi Binary
Description	Tor configuration and routing management for Kodachi OS
Git Commit	unknown
Metadata Generated	2026-07-11T18:16:14Z
Binary Timestamp	Unknown
JSON Data	View Raw JSON

SHA256 Checksum

3bb11a196b0b85b273b18384dcc3edc26562b3f6f2903788ba0cd557f366795a

Features

#	Feature
1	Tor network management and configuration
2	Multi-instance Tor support
3	Exit node rotation and control
4	DNS leak prevention integration
5	Firewall rule management
6	HAProxy configuration for load balancing
7	Authentication and security verification
8	Comprehensive logging and monitoring

Security Features

Feature	Description
Authentication	Not provided by cli-core (see online-auth)
Encryption	Not provided by cli-core
Input Validation	Argument parsing via clap; per-command validation is the consumer's responsibility
Rate Limiting	Not provided by cli-core

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
`-o, --output-format <FORMAT>`	Force output format (text\|json)
`--json-pretty`	Pretty-print JSON output with indentation
`--json-human`	Enhanced JSON output with improved formatting (like jq)
`--fields <FIELD_LIST>`	Select specific fields to include in output (comma-separated)
`--limit <NUMBER>`	Limit number of results returned
`--offset <NUMBER>`	Skip first N results (for pagination)
`-d, --work-dir <PATH>`	Working directory (defaults to auto-detected base directory)
`--port <PORT>`	Set custom port number (1024-65535)
`--log-level <LEVEL>`	Set log level (error\|warn\|info\|debug)
`--verbose`	Enable verbose output
`--quiet`	Suppress non-essential output
`--no-color`	Disable colored output
`--config <FILE>`	Use custom configuration file
`--timeout <SECS>`	Set operation timeout in seconds (optional; no default applied)
`--retry <COUNT>`	Retry attempts (optional; no default applied)

Commands

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]

Bridge Management

`set-bridges`

Store obfs4 bridge lines and activate bridge mode for all instances

Usage:

tor-switch set-bridges [OPTIONS]

`enable-bridges`

Enable stored bridges for all instances and restart them

Usage:

tor-switch enable-bridges [OPTIONS]

`disable-bridges`

Disable bridges (revert to direct Tor) and restart all instances

Usage:

tor-switch disable-bridges [OPTIONS]

`list-bridges`

List stored bridge configuration and detected obfs4proxy path

Usage:

tor-switch list-bridges [OPTIONS]

`clear-bridges`

Remove all stored bridges, disable bridge mode, and restart instances

Usage:

tor-switch clear-bridges [OPTIONS]

`test-bridges`

Validate stored bridge lines and report obfs4proxy availability (read-only)

Usage:

tor-switch test-bridges [OPTIONS]

`set-bridge-mode`

Set bridge selection mode: 'all' uses every bridge, 'random' picks a random subset each rotation

Usage:

tor-switch set-bridge-mode [OPTIONS]

`rotate-bridges`

Re-apply bridge config to all instances (picks a fresh random subset in random mode)

Usage:

tor-switch rotate-bridges [OPTIONS]

`bridge-rotate-timer`

Install a cron job that rotates bridges on the given interval (e.g. 15m, 1h)

Usage:

tor-switch bridge-rotate-timer [OPTIONS]

`stop-bridge-rotate-timer`

Remove the bridge rotation cron job

Usage:

tor-switch stop-bridge-rotate-timer [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 (requires --force)

Usage:

tor-switch torrify-system-dns [OPTIONS]

`torrify-system-iptables-dns`

Route DNS through Tor with iptables (requires --force)

Usage:

tor-switch torrify-system-iptables-dns [OPTIONS]

`torrify-system-nftables-dns`

Route DNS through Tor with nftables (requires --force)

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]

`clear-exclude-node-all`

Clear excluded nodes for all instances

Usage:

tor-switch clear-exclude-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 (requires --force)

Usage:

tor-switch flush-iptables [OPTIONS]

`flush-nftables`

Flush nftables rules (requires --force)

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]

`restart-all-instances`

Restart all Tor instances

Usage:

tor-switch restart-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. If COUNT is omitted, picks the RAM-aware default from instance_sizing::recommended_instance_count (4 GB→3, 8 GB→5, 16 GB→7, 32 GB→10, 256 GB→20). Passing COUNT is an explicit user override and bypasses the model (still clamped to [floor, cap] for safety).

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 (requires --force)

Usage:

tor-switch torrify-system-iptables-load-balanced [OPTIONS]

`torrify-system-nftables-load-balanced`

Torrify with nftables load balancing (requires --force)

Usage:

tor-switch torrify-system-nftables-load-balanced [OPTIONS]

`prepare-tor`

Pre-warm Tor instances and verify circuit readiness without applying firewall rules

Usage:

tor-switch prepare-tor [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 service is running via systemctl

Usage:

tor-switch check-tor [OPTIONS]

`check-tor-all`

Check systemctl status for all Tor instances

Usage:

tor-switch check-tor-all [OPTIONS]

`torverify`

Verify Tor connectivity through network check

Usage:

tor-switch torverify [OPTIONS]

`tor-status`

Get comprehensive Tor service status (PID, memory, uptime)

Usage:

tor-switch tor-status [OPTIONS]

`tor-status-all`

Get comprehensive status for all Tor 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]

`recommended-instances`

Show RAM-aware recommended Tor LB instance count (square-root model, clamped 3..20). Output includes detected RAM, current user override (if any), and the effective N the binary will use. Other Kodachi components (dashboard, helpers) should query this instead of recomputing — single source of truth.

Usage:

tor-switch recommended-instances [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 via iptables (requires --force)

Usage:

tor-switch torrify-system-iptables [OPTIONS]

`detorrify-system-iptables`

Stop routing traffic through Tor via iptables (requires --force)

Usage:

tor-switch detorrify-system-iptables [OPTIONS]

`torrify-system-nftables`

Route all traffic through Tor via nftables (requires --force)

Usage:

tor-switch torrify-system-nftables [OPTIONS]

`detorrify-system-nftables`

Stop routing traffic through Tor via nftables (requires --force)

Usage:

tor-switch detorrify-system-nftables [OPTIONS]

`boot-restore-torrified`

Restore the Tor instance pool at boot when the persisted firewall is torrified (no-op otherwise)

Usage:

tor-switch boot-restore-torrified [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]

Operational Scenarios

Scenario-oriented workflows generated from the binary's built-in -e --json examples.

Scenario 1: Basic Usage

Essential operations for getting started

Step 1: Start Tor daemon

sudo tor-switch start-tor

Expected Output: Tor daemon started successfully

Note

Requires sudo privileges for system-level operations

Step 2: Stop Tor daemon

sudo tor-switch stop-tor

Expected Output: Tor daemon stopped successfully

Note

Gracefully shuts down Tor service

Step 3: Restart Tor daemon

sudo tor-switch restart-tor

Expected Output: Tor daemon restarted successfully

Note

Combines stop and start operations

Step 4: 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

Step 5: 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

Step 6: 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

Step 7: 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

Step 8: Route all traffic through Tor via nftables

sudo tor-switch torrify-system-nftables --force

Expected Output: System traffic routing through Tor enabled (nftables)

Note

Destructive firewall change — requires --force (alias --yes). Uses modern nftables backend

Step 9: Stop routing traffic through Tor via nftables

sudo tor-switch detorrify-system-nftables --force

Expected Output: System traffic routing through Tor disabled (nftables)

Note

Destructive firewall change — requires --force (alias --yes). Returns to normal direct internet connection

Step 10: 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

Step 11: 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

Step 12: 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

Scenario 2: Instance Management

Managing multiple Tor instances for performance

Step 1: 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

Step 2: List all available instances

sudo tor-switch list-instances

Expected Output: Shows all instances with their status

Step 3: Start specific instance

sudo tor-switch start-instance secondary

Expected Output: Instance 'secondary' started

Step 4: Stop specific instance

sudo tor-switch stop-instance secondary

Expected Output: Instance 'secondary' stopped

Step 5: Restart specific instance

sudo tor-switch restart-instance secondary

Expected Output: Instance 'secondary' restarted

Step 6: Restart all Tor instances

sudo tor-switch restart-all-instances

Expected Output: Restarted 5 out of 5 Tor instances

Step 7: Delete an instance permanently

sudo tor-switch delete-instance secondary

Expected Output: Instance 'secondary' deleted

Note

This permanently removes the instance configuration

Step 8: Start all configured instances

sudo tor-switch start-all-instances

Expected Output: All Tor instances started

Step 9: Stop all running instances

sudo tor-switch stop-all-instances

Expected Output: All Tor instances stopped

Scenario 3: Advanced Instance Operations

Create, clone, rename and manage multiple Tor instances

Step 1: 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

Step 2: 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

Step 3: 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

Step 4: 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

Step 5: 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

Step 6: 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

Step 7: 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

Step 8: 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

Step 9: 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

Step 10: 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

Step 11: 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

Step 12: 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

Step 13: 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

Scenario 4: Monitoring & Status

Checking system status and verifying operations

Step 1: Get detailed Tor status

sudo tor-switch tor-status

Expected Output: Comprehensive status report of all Tor components

Step 2: Detailed status in JSON format

sudo tor-switch tor-status --json

Expected Output: JSON-formatted status report

Note

Machine-readable output for scripts

Step 3: 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

Step 4: Verify if system traffic is routed through Tor

sudo tor-switch torverify

Expected Output: ✓ You are connected through Tor IP Address: <Tor exit IP>

Note

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

Step 5: Verify Tor connectivity with detailed JSON output

sudo tor-switch torverify --json-pretty

Expected Output: { "is_tor": true, "ip_address": "<exit IP>", "method": "api" }

Note

Useful for scripts and automation

Step 6: Get detailed status for all instances

sudo tor-switch tor-status-all

Expected Output: Comprehensive status report for all instances

Step 7: 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

Step 8: Show RAM-aware recommended load-balancing instance count

tor-switch recommended-instances

Expected Output: Detected RAM, current override (if any), and the effective N (clamped 3..20)

Note

Read-only single source of truth (square-root model). Other components should query this instead of recomputing

Scenario 5: Troubleshooting

Debug and resolve common issues

Step 1: Clean up orphaned processes

sudo tor-switch cleanup

Expected Output: Orphaned instances and services cleaned up

Note

Use when experiencing startup issues

Step 2: Clean orphaned Tor instances and services

sudo tor-switch cleanup

Expected Output: Cleanup completed successfully

Note

Removes orphaned instances and service files

Step 3: Clean orphaned services

sudo tor-switch clean-orphan-services

Expected Output: Orphaned services removed

Step 4: 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

Scenario 6: 4. EXIT NODE MANAGEMENT

Control and configure Tor exit nodes for geographic routing and privacy

Step 1: Route via United States

sudo tor-switch set-exit-node us

Expected Output: Exit node set to United States

Note

Affects the default Tor instance. Traffic will exit through US-based Tor nodes

Step 2: 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

Step 3: 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

Step 4: 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

Step 5: Random exit node selection

sudo tor-switch set-exit-node random

Expected Output: Exit node set to random selection

Note

Maximum anonymity through randomization

Step 6: 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

Step 7: 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

Step 8: 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

Step 9: 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

Step 10: 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

Step 11: 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

Step 12: 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

Step 13: 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

Step 14: Random Five Eyes exit

sudo tor-switch set-exit-node random-5eyes

Expected Output: Exit node set to random Five Eyes country

Note

US, GB, CA, AU, NZ

Step 15: 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

Step 16: 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

Step 17: 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

Step 18: 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

Step 19: Route through any European country

sudo tor-switch set-exit-node europe

Expected Output: Exit node set to Europe region

Note

Countries: AT, BE, BG, CH, CZ, DE, DK, EE, ES, FI, FR, GB, GR, HR, HU, IE, IS, IT, LT, LU, LV, MD, NL, NO, PL, PT, RO, RS, SE, SI, SK, UA

Step 20: Route through any Asian country

sudo tor-switch set-exit-node asia

Expected Output: Exit node set to Asia region

Note

Countries: HK, ID, IN, JP, KR, MY, PH, SG, TH, TW, VN

Step 21: Route through any African country

sudo tor-switch set-exit-node africa

Expected Output: Exit node set to Africa region

Note

Countries: EG, KE, MA, NG, SC, TN, ZA

Step 22: 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

Step 23: Route through South America

sudo tor-switch set-exit-node south-america

Expected Output: Exit node set to South America region

Note

Countries: AR, BR, CL, CO, PE, UY, VE

Step 24: Route through Oceania

sudo tor-switch set-exit-node oceania

Expected Output: Exit node set to Oceania region

Note

Countries: AU, NZ

Step 25: Route through Middle East

sudo tor-switch set-exit-node middle-east

Expected Output: Exit node set to Middle East region

Note

Countries: AE, IL, IR, LB, OM, QA, SA, TR

Step 26: Use Five Eyes countries

sudo tor-switch set-exit-node 5eyes

Expected Output: Exit node set to Five Eyes alliance

Note

US, GB, CA, AU, NZ

Step 27: 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

Step 28: 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

Step 29: Use high-traffic countries

sudo tor-switch set-exit-node high-volume

Expected Output: Exit node set to high-volume countries

Note

Affects default instance. High-volume countries: AL, AT, BE, BG, BR, BZ, CH, CZ, FI, HU, IS, JP, KR, LU, MD, PL, RO, RU, SC, SG, TH, TR, UA, ZA

Step 30: Use low-traffic countries

sudo tor-switch set-exit-node low-volume

Expected Output: Exit node set to low-volume countries

Note

Affects default instance. Countries excluding high-volume and 14eyes nations for uniqueness

Step 31: 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

Step 32: Clear exit node restrictions

sudo tor-switch clear-exit-node

Expected Output: Exit node restrictions cleared

Note

Returns to default random exit selection

Step 33: Exclude specific countries

sudo tor-switch set-exclude-node cn,ru,ir

Expected Output: Excluded nodes set

Note

Prevents routing through specified countries

Step 34: Exclude Five Eyes countries

sudo tor-switch set-exclude-node 5eyes

Expected Output: Five Eyes countries excluded

Note

US, GB, CA, AU, NZ

Step 35: Exclude Nine Eyes countries

sudo tor-switch set-exclude-node 9eyes

Expected Output: Nine Eyes countries excluded

Note

5eyes + Denmark, France, Netherlands, Norway

Step 36: Exclude Fourteen Eyes countries

sudo tor-switch set-exclude-node 14eyes

Expected Output: Fourteen Eyes countries excluded

Note

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

Step 37: Exclude all European countries

sudo tor-switch set-exclude-node europe

Expected Output: European countries excluded

Note

Excludes: AT, BE, BG, CH, CZ, DE, DK, EE, ES, FI, FR, GB, GR, HR, HU, IE, IS, IT, LT, LU, LV, MD, NL, NO, PL, PT, RO, RS, SE, SI, SK, UA

Step 38: Exclude all Asian countries

sudo tor-switch set-exclude-node asia

Expected Output: Asian countries excluded

Note

Excludes: HK, ID, IN, JP, KR, MY, PH, SG, TH, TW, VN

Step 39: Exclude North American countries

sudo tor-switch set-exclude-node north-america

Expected Output: North American countries excluded

Note

US, Canada, Mexico excluded

Step 40: Exclude high-traffic countries

sudo tor-switch set-exclude-node high-volume

Expected Output: High-volume countries excluded

Note

Excludes: AL, AT, BE, BG, BR, BZ, CH, CZ, FI, HU, IS, JP, KR, LU, MD, PL, RO, RU, SC, SG, TH, TR, UA, ZA

Step 41: Exclude low-traffic countries

sudo tor-switch set-exclude-node low-volume

Expected Output: Low-volume countries excluded

Note

Use only high-traffic exit nodes

Step 42: 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

Step 43: 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

Step 44: 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

Step 45: 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

Step 46: 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

Step 47: Clear all excluded countries

sudo tor-switch clear-exclude-node-main

Expected Output: All exclusions removed

Note

Resets to default behavior

Step 48: Clear excluded nodes for all instances

sudo tor-switch clear-exclude-node-all

Expected Output: Exclusions removed for all instances

Note

Global clear matching set-exclude-node-all scope

Step 49: 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

Scenario 7: 7. LOAD BALANCING (Native Kernel-Level)

Native load balancing using iptables/nftables firewall rules

Step 1: 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

Step 2: 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

Step 3: 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

Step 4: 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

Step 5: 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

Step 6: 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

Step 7: 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

Step 8: 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

Step 9: 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

Step 10: 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

Step 11: Show current load balancing setup

sudo tor-switch display-load-balancing-config

Expected Output: Current load balancing configuration details

Step 12: 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

Step 13: 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

Step 14: Pre-warm Tor instances and verify circuit readiness

sudo tor-switch prepare-tor

Expected Output: Instances bootstrapped and circuits confirmed ready

Note

Warms instances without applying any firewall rules — run before torrify to avoid first-connection delays

Scenario 8: 8. HAPROXY INTEGRATION (Application-Level Proxy)

HAProxy provides advanced application-level load balancing

Step 1: 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

Step 2: 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

Step 3: 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

Step 4: 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

Step 5: Start HAProxy service

sudo tor-switch haproxy-start

Expected Output: HAProxy started successfully

Step 6: Check HAProxy status

sudo tor-switch haproxy-status

Expected Output: HAProxy service status and statistics

Step 7: Stop HAProxy service

sudo tor-switch haproxy-stop

Expected Output: HAProxy stopped

Step 8: Show available HAProxy algorithms

sudo tor-switch list-haproxy-modes

Expected Output: List of supported HAProxy algorithms

Note

roundrobin, source, leastconn, random

Scenario 9: Timer Management and Automation

Automatic IP rotation and timer-based operations

Step 1: Auto IP change every 10 minutes

sudo tor-switch auto-ip-change 10m

Expected Output: Automatic IP change enabled with 10 minute interval

Note

Creates new Tor circuit for default instance to get new exit IP

Step 2: Set timer for specific instance

sudo tor-switch update-ip-timer browsing 5m

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

Step 3: 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

Step 4: 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

Step 5: 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

Step 6: 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

Step 7: 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

Step 8: 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

Step 9: List all IP change timers

sudo tor-switch list-ip-timers

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

Step 10: Remove timer for instance

sudo tor-switch remove-ip-timer browsing

Expected Output: IP change timer removed

Step 11: Stop auto IP change

sudo tor-switch stop-auto-ip-change

Expected Output: Automatic IP change stopped

Step 12: 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

Step 13: 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

Step 14: List automatic IP change settings

sudo tor-switch list-auto-ip-change

Expected Output: Auto IP change configurations for all instances

Scenario 10: DNS Management

Configure and manage DNS routing through Tor. AUTH NOTE: start-tor-dns-* and torrify-system-*-dns are anonymity-affecting mutations and REQUIRE an active online-auth session (`sudo online-auth authenticate` first). stop-tor-dns-* is exempt — it is in the emergency/recovery list and works even when auth is unavailable.

Step 1: 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. AUTH REQUIRED — run `sudo online-auth authenticate` first.

Step 2: Stop Tor DNS routing

sudo tor-switch stop-tor-dns-iptables

Expected Output: Tor DNS iptables rules removed

Note

Emergency/recovery exempt — works without auth.

Step 3: 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. AUTH REQUIRED + --force gate.

Step 4: 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. AUTH REQUIRED — run `sudo online-auth authenticate` first.

Step 5: Stop Tor DNS (nftables)

sudo tor-switch stop-tor-dns-nftables

Expected Output: Tor DNS nftables rules removed

Note

Emergency/recovery exempt — works without auth.

Step 6: 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. AUTH REQUIRED + --force gate.

Step 7: 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. AUTH REQUIRED + --force gate.

Scenario 11: DNS Verification

Test and verify DNS routing through Tor

Step 1: 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

Step 2: 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

Step 3: 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

Step 4: 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

Step 5: 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

Scenario 12: Firewall Operations

Manage iptables and nftables firewall rules

Step 1: Flush iptables rules

sudo tor-switch flush-iptables

Expected Output: All iptables rules cleared

Note

Removes all current iptables rules and policies

Step 2: List current iptables rules

sudo tor-switch list-iptables

Expected Output: Display of all active iptables rules

Step 3: Check active firewall

sudo tor-switch which-is-active

Expected Output: Shows whether iptables or nftables is active

Step 4: Flush nftables rules

sudo tor-switch flush-nftables

Expected Output: All nftables rules cleared

Note

Removes all current nftables rules

Step 5: List current nftables rules

sudo tor-switch list-nftables

Expected Output: Display of all active nftables rules

Step 6: List NAT rules

sudo tor-switch list-iptables-nat

Expected Output: Display of all NAT table rules

Note

Shows network address translation rules

Scenario 13: Configuration Management

Manage Tor configuration files and validation

Step 1: Validate torrc configuration

sudo tor-switch validate-torrc

Expected Output: Configuration validation results

Note

Checks syntax without starting Tor

Step 2: Reload configuration

sudo tor-switch reload-tor-config

Expected Output: Configuration reloaded successfully

Note

Applies changes without restart

Step 3: Generate new control password

sudo tor-switch generate-new-tor-password

Expected Output: New control password generated

Step 4: Clean custom configuration

sudo tor-switch clean-torrc-custom

Expected Output: Custom torrc entries removed

Step 5: Clean all custom configurations

sudo tor-switch clean-torrc-custom-all

Expected Output: Custom entries removed from all instances

Step 6: Reload all configurations

sudo tor-switch reload-tor-config-all

Expected Output: All instance configurations reloaded

Step 7: Generate passwords for all instances

sudo tor-switch generate-new-tor-password-all

Expected Output: New control passwords generated for all

Step 8: Get custom configuration status

sudo tor-switch get-tor-custom-status

Expected Output: Status of custom configurations

Scenario 14: Backup and Restore

Backup and restore Tor instance configurations

Step 1: Backup configuration

sudo tor-switch backup-config

Expected Output: Configuration backed up with timestamp (default instance)

Step 2: List available backups

sudo tor-switch list-backups

Expected Output: Table showing all backup files

Step 3: Restore from backup

sudo tor-switch restore-config backup-2025-01-28

Expected Output: Configuration restored

Note

Restores configuration and restarts instances

Step 4: Backup all configurations

sudo tor-switch backup-config-all

Expected Output: All instance configurations backed up

Step 5: 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

Scenario 15: Main Tor Management (TROUBLESHOOTING ONLY)

TROUBLESHOOTING ONLY: Commands for debugging the main system Tor. Most operations should use Kodachi instances instead. Only use these for troubleshooting main Tor issues.

Step 1: Do NOT modify main Tor for regular use

# 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

Step 2: 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

Step 3: 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

Step 4: 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/

Step 5: 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

Step 6: 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

Step 7: 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

Step 8: 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

Step 9: Clear excluded countries

sudo tor-switch clear-exclude-node-main --maintor

Expected Output: Exclude restrictions cleared for main Tor

Note

Removes all country exclusions

Step 10: Show exit/exclude settings

sudo tor-switch list-exit-exclude-main

Expected Output: Exit/exclude settings displayed

Note

Displays current geographic routing rules

Step 11: Reload main Tor configuration

sudo tor-switch reload-main-tor

Expected Output: Main Tor configuration reloaded

Note

Sends SIGHUP signal to apply config changes

Step 12: Get main Tor daemon status

sudo tor-switch status-main-tor

Expected Output: Main Tor status displayed

Note

Shows systemctl status and port information

Step 13: 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

Step 14: 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

Step 15: Security audit main Tor

sudo tor-switch check-main-tor-security

Expected Output: Security audit completed

Note

Checks for security misconfigurations

Step 16: Show Tor bandwidth usage

sudo tor-switch main-tor-bandwidth

Expected Output: Bandwidth usage displayed

Note

Displays active SOCKS connections count

Step 17: List active Tor connections

sudo tor-switch main-tor-connections

Expected Output: Active connections listed

Note

Shows established connections on SOCKS port

Step 18: 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

Step 19: Validate with JSON output

sudo tor-switch validate-torrc-main --maintor --json

Expected Output: JSON validation output returned

Note

Machine-readable output for scripting

Scenario 16: Advanced Workflows

Complete workflow examples for common use cases

Step 1: Complete privacy-focused setup

# Privacy-focused browsing setup
sudo tor-switch create-multiple-instances 3 privacy
sudo tor-switch set-exclude-node 5eyes --instance privacy-1
sudo tor-switch set-exclude-node 9eyes --instance privacy-2
sudo tor-switch set-exclude-node 14eyes --instance privacy-3
sudo tor-switch update-ip-timer privacy-1 5m
sudo tor-switch update-ip-timer privacy-2 10m
sudo tor-switch update-ip-timer privacy-3 15m

Expected Output: Privacy-optimized Tor configuration active

Note

Avoids surveillance alliance countries with rapid rotation

Step 2: Geographic distribution setup

# Regional distribution setup
sudo tor-switch create-instance europe
sudo tor-switch create-instance asia
sudo tor-switch create-instance americas
sudo tor-switch set-exit-node europe --instance europe
sudo tor-switch set-exit-node asia --instance asia
sudo tor-switch set-exit-node north-america --instance americas

Expected Output: Regional Tor instances configured

Note

Access region-specific content simultaneously

Step 3: High-availability load balanced setup

# High-availability setup
sudo tor-switch create-multiple-instances 5 ha
sudo tor-switch set-load-balancing-mode weighted
sudo tor-switch set-instance-weight ha-1 30
sudo tor-switch set-instance-weight ha-2 25
sudo tor-switch set-instance-weight ha-3 20
sudo tor-switch set-instance-weight ha-4 15
sudo tor-switch set-instance-weight ha-5 10
sudo tor-switch torrify-system-iptables-load-balanced

Expected Output: HA configuration with weighted distribution active

Note

Redundant instances with priority-based traffic distribution

Step 4: Research and testing environment

# Research and testing setup
sudo tor-switch create-instance research
sudo tor-switch create-instance testing
sudo tor-switch set-exit-node random-low-volume --instance research
sudo tor-switch set-exit-node high-volume --instance testing
sudo tor-switch update-ip-timer research 2m
sudo tor-switch verify-tor-dns --instance research
sudo tor-switch verify-tor-dns --instance testing

Expected Output: Research/testing instances configured

Note

Separate instances for different testing scenarios

Step 5: Maximum performance configuration

# Performance-optimized setup
sudo tor-switch create-multiple-instances 10 perf
sudo tor-switch set-load-balancing-mode round-robin
sudo tor-switch generate-haproxy-config
sudo tor-switch haproxy-start
sudo tor-switch haproxy-status

Expected Output: Performance-optimized setup with HAProxy active

Note

10 instances with HAProxy for maximum throughput

Step 6: Complete reset to default state

# Clean slate reset
sudo tor-switch stop-all-instances
sudo tor-switch cleanup
sudo tor-switch flush-iptables
sudo tor-switch restart-tor
sudo tor-switch check-tor

Expected Output: System reset to clean Tor configuration

Note

Removes all custom configurations and instances

Step 7: Complete system status check

# Monitoring and diagnostics
sudo tor-switch tor-status-all
sudo tor-switch list-instances
sudo tor-switch list-ip-timers
sudo tor-switch display-load-balancing-config
sudo tor-switch haproxy-status

Expected Output: Full diagnostic report displayed

Note

Comprehensive view of all Tor configurations

Scenario 17: Bridge Management (obfs4 Pluggable Transport)

obfs4 bridges allow Tor to bootstrap over XTLS-Vision Reality VPN connections, where plain Tor fails because Vision inspects the nested TLS. Bridges wrap the Tor handshake in an opaque layer that Vision cannot identify.

Step 1: Store a single obfs4 bridge and activate it for all instances

sudo tor-switch set-bridges --bridge 'obfs4 192.0.2.1:443 AABBCCDDEEFF00112233445566778899AABBCCDD cert=AAABBBCCC+longbase64string== iat-mode=0'

Expected Output: Bridges saved (1 lines). obfs4proxy: /usr/bin/obfs4proxy

Note

Requires obfs4proxy installed (apt install obfs4proxy). All instances are restarted automatically.

Step 2: Load multiple bridge lines from a file (one per line, # comments ignored)

sudo tor-switch set-bridges --from-file /tmp/bridges.txt

Expected Output: Bridges saved. All instances restarted with bridge configuration.

Note

Recommended for the dashboard: write bridge lines to a temp file then pass --from-file.

Step 3: Show stored bridge config and obfs4proxy detection result as JSON

tor-switch list-bridges --json

Expected Output: {"enabled":true,"transport":"obfs4","bridges_count":2,...}

Note

Read-only, no sudo required.

Step 4: Validate stored bridge lines and check obfs4proxy path without making changes

tor-switch test-bridges --json

Expected Output: {"all_valid":true,"obfs4proxy_found":true,...}

Note

Read-only, no sudo required. Use before enable-bridges to confirm lines are well-formed.

Step 5: Revert to direct Tor (strip bridge block, restart all instances)

sudo tor-switch disable-bridges

Expected Output: Bridges disabled. Tor instances reverted to direct connections.

Note

Preserves stored bridge lines so you can re-enable later.

Step 6: Re-activate previously stored bridges for all instances

sudo tor-switch enable-bridges

Expected Output: Bridges enabled. N bridges active.

Note

Requires at least one bridge stored via set-bridges.

Step 7: Remove all stored bridges and revert all instances to direct Tor

sudo tor-switch clear-bridges

Expected Output: All bridges cleared. Tor instances using direct connections.

Note

Permanently removes bridges.json entries. Use disable-bridges instead to keep them for later.

Step 8: Use all stored bridges simultaneously (default behavior)

sudo tor-switch set-bridge-mode --mode all

Expected Output: Bridge selection mode set to 'all' (active_count=1, N bridges stored).

Note

Re-applies the bridge config and restarts all instances.

Step 9: Randomly pick 2 bridges from the stored list each time bridges are applied

sudo tor-switch set-bridge-mode --mode random --count 2

Expected Output: Bridge selection mode set to 'random' (active_count=2, N bridges stored).

Note

Useful when you have many bridges and want to vary which ones are used.

Step 10: Pick a fresh random subset of bridges and restart all instances

sudo tor-switch rotate-bridges

Expected Output: Bridge rotation applied: 1 bridge(s) selected from 5 stored.

Note

In 'all' mode this re-applies without changing the active set. In 'random' mode a new subset is picked.

Step 11: Install a cron job that calls rotate-bridges every 15 minutes

sudo tor-switch bridge-rotate-timer 15m

Expected Output: Bridge rotation cron installed: every 15 minutes (*/15 * * * *). Use stop-bridge-rotate-timer to remove.

Note

Minimum interval is 1 minute. Tagged with KODACHI_BRIDGE_ROTATE in crontab. Only one timer can be active; running again replaces the previous one.

Step 12: Remove the bridge rotation cron job

sudo tor-switch stop-bridge-rotate-timer

Expected Output: Bridge rotation cron job removed.

Note

Reports cleanly if no timer was installed.

Scenario 18: Help & Documentation

Built-in help and usage examples

Step 1: Show help information

tor-switch show-help

Expected Output: Full command reference with descriptions

Note

Equivalent to -h; read-only, no privileges required

Step 2: Show usage examples

tor-switch show-examples

Expected Output: Categorized example commands with expected output

Note

Equivalent to -e; read-only, no privileges required

Environment Variables

Variable	Description	Default	Values
`RUST_LOG`	Set logging level	info	error\|warn\|info\|debug\|trace
`NO_COLOR`	Disable all colored output when set	unset	1\|true\|yes (any value disables color)

Exit Codes

Code	Description
0	Success
1	General error
2	Invalid arguments
3	Permission denied
4	Network error
5	File not found