{ "report_info": { "version": "9.0.1", "generated_at": "2026-07-21T01:54:39Z", "binary_name": "tor-switch" }, "binary": { "name": "tor-switch", "path": "/opt/kodachi/dashboard/hooks/tor-switch", "timestamp": "2026-07-21T01:54:39Z", "file_info": { "size": 8791552, "sha256": "fdfa00e5ac409838b016d7a66d7aeb1fa249e502e2a44431002b6ce077ef3ae8" }, "flag_n": { "command": "info", "data": { "author": "Warith Al Maawali", "copyright": "© 2026 Kodachi OS", "description": "Tor configuration and routing management for Kodachi OS", "features": [ "Tor network management and configuration", "Multi-instance Tor support", "Exit node rotation and control", "DNS leak prevention integration", "Firewall rule management", "HAProxy configuration for load balancing", "Authentication and security verification", "Comprehensive logging and monitoring" ], "license": "Proprietary", "name": "tor-switch", "securityFeatures": { "authentication": "Not provided by cli-core (see online-auth)", "encryption": "Not provided by cli-core", "inputValidation": "Argument parsing via clap; per-command validation is the consumer's responsibility", "rateLimiting": "Not provided by cli-core" }, "systemRequirements": { "dependencies": [ "OpenSSL", "libcurl" ], "os": "Linux (Debian-based)", "privileges": "root/sudo for system operations" }, "version": "9.8.4 (build 320)", "website": "https://digi77.com" }, "errors": [], "metadata": { "executionTime": 12, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:39.210811538Z", "version": "9.8.4 (build 320)", "warnings": [] }, "flag_v": { "command": "version", "data": { "buildDate": "REDACTED-BUILD-TIME", "gitCommit": "unknown", "name": "tor-switch", "rustVersion": "1.82.0", "version": "9.8.4 (build 320)" }, "errors": [], "metadata": { "executionTime": 14, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:39.324485768Z", "version": "9.8.4 (build 320)", "warnings": [] }, "flag_h": { "command": "help", "data": { "commandCategories": [ { "category": "Basic Operations", "commands": [ { "description": "Start Tor daemon", "examples": [ "sudo tor-switch start-tor" ], "name": "start-tor", "options": [ { "description": "Specify instance name", "flag": "-i, --instance ", "required": false } ], "requires_sudo": true, "usage": "tor-switch start-tor [OPTIONS]" }, { "description": "Stop Tor daemon", "examples": [ "sudo tor-switch stop-tor" ], "name": "stop-tor", "options": [ { "description": "Specify instance name", "flag": "-i, --instance ", "required": false } ], "requires_sudo": true, "usage": "tor-switch stop-tor [OPTIONS]" }, { "description": "Restart Tor daemon", "examples": [ "sudo tor-switch restart-tor" ], "name": "restart-tor", "options": [ { "description": "Specify instance name", "flag": "-i, --instance ", "required": false } ], "requires_sudo": true, "usage": "tor-switch restart-tor [OPTIONS]" } ] }, { "category": "Bridge Management", "commands": [ { "description": "Store obfs4 bridge lines and activate bridge mode for all instances", "examples": [ "sudo tor-switch set-bridges --bridge 'obfs4 192.0.2.1:443 AABBCCDDEEFF00112233445566778899AABBCCDD cert=AAABBBCCC+longbase64string== iat-mode=0'", "sudo tor-switch set-bridges --from-file /tmp/bridges.txt" ], "name": "set-bridges", "options": [ { "description": "An obfs4 bridge line (repeatable)", "flag": "-b, --bridge ", "required": false }, { "description": "Read bridge lines from a file (blank lines and # comments ignored)", "flag": "--from-file ", "required": false }, { "default": "obfs4", "description": "Pluggable transport type (default: obfs4)", "flag": "--transport ", "required": false }, { "description": "Output in JSON format", "flag": "--json", "required": false } ], "requires_sudo": true, "usage": "tor-switch set-bridges [OPTIONS]" }, { "description": "Enable stored bridges for all instances and restart them", "examples": [ "sudo tor-switch enable-bridges" ], "name": "enable-bridges", "options": [], "requires_sudo": true, "usage": "tor-switch enable-bridges [OPTIONS]" }, { "description": "Disable bridges (revert to direct Tor) and restart all instances", "examples": [ "sudo tor-switch disable-bridges" ], "name": "disable-bridges", "options": [], "requires_sudo": true, "usage": "tor-switch disable-bridges [OPTIONS]" }, { "description": "List stored bridge configuration and detected obfs4proxy path", "examples": [ "tor-switch list-bridges --json" ], "name": "list-bridges", "options": [], "requires_sudo": false, "usage": "tor-switch list-bridges [OPTIONS]" }, { "description": "Remove all stored bridges, disable bridge mode, and restart instances", "examples": [ "sudo tor-switch clear-bridges" ], "name": "clear-bridges", "options": [], "requires_sudo": true, "usage": "tor-switch clear-bridges [OPTIONS]" }, { "description": "Validate stored bridge lines and report obfs4proxy availability (read-only)", "examples": [ "tor-switch test-bridges --json" ], "name": "test-bridges", "options": [], "requires_sudo": false, "usage": "tor-switch test-bridges [OPTIONS]" }, { "description": "Set bridge selection mode: 'all' uses every bridge, 'random' picks a random subset each rotation", "examples": [ "sudo tor-switch set-bridge-mode --mode all", "sudo tor-switch set-bridge-mode --mode random --count 2" ], "name": "set-bridge-mode", "options": [ { "description": "Selection mode: all or random", "flag": "-m, --mode ", "required": true }, { "description": "Number of bridges to activate in random mode (>= 1)", "flag": "--count ", "required": false } ], "requires_sudo": true, "usage": "tor-switch set-bridge-mode [OPTIONS]" }, { "description": "Re-apply bridge config to all instances (picks a fresh random subset in random mode)", "examples": [ "sudo tor-switch rotate-bridges" ], "name": "rotate-bridges", "options": [], "requires_sudo": true, "usage": "tor-switch rotate-bridges [OPTIONS]" }, { "description": "Install a cron job that rotates bridges on the given interval (e.g. 15m, 1h)", "examples": [ "sudo tor-switch bridge-rotate-timer 15m" ], "name": "bridge-rotate-timer", "options": [ { "description": "Rotation interval (e.g. 15m, 1h, 30s)", "flag": "", "required": true } ], "requires_sudo": true, "usage": "tor-switch bridge-rotate-timer [OPTIONS]" }, { "description": "Remove the bridge rotation cron job", "examples": [ "sudo tor-switch stop-bridge-rotate-timer" ], "name": "stop-bridge-rotate-timer", "options": [], "requires_sudo": true, "usage": "tor-switch stop-bridge-rotate-timer [OPTIONS]" } ] }, { "category": "Configuration", "commands": [ { "description": "Validate torrc configuration", "examples": [ "tor-switch validate-torrc" ], "name": "validate-torrc", "options": [], "requires_sudo": false, "usage": "tor-switch validate-torrc [OPTIONS]" }, { "description": "Reload Tor configuration", "examples": [ "sudo tor-switch reload-tor-config" ], "name": "reload-tor-config", "options": [], "requires_sudo": true, "usage": "tor-switch reload-tor-config [OPTIONS]" }, { "description": "Reload config for all instances", "examples": [ "sudo tor-switch reload-tor-config-all" ], "name": "reload-tor-config-all", "options": [], "requires_sudo": true, "usage": "tor-switch reload-tor-config-all [OPTIONS]" }, { "description": "Backup configuration", "examples": [ "sudo tor-switch backup-config" ], "name": "backup-config", "options": [], "requires_sudo": true, "usage": "tor-switch backup-config [OPTIONS]" }, { "description": "Backup all configurations", "examples": [ "sudo tor-switch backup-config-all" ], "name": "backup-config-all", "options": [], "requires_sudo": true, "usage": "tor-switch backup-config-all [OPTIONS]" }, { "description": "Restore configuration", "examples": [ "sudo tor-switch restore-config backup-2025-01-28" ], "name": "restore-config", "options": [ { "description": "Backup name to restore (e.g., backup-2025-01-28)", "flag": "", "required": true }, { "description": "Target instance (optional)", "flag": "--instance ", "required": false } ], "requires_sudo": true, "usage": "tor-switch restore-config [OPTIONS]" }, { "description": "Restore all configurations", "examples": [ "sudo tor-switch restore-config-all backup-2025-01-28" ], "name": "restore-config-all", "options": [ { "description": "Backup name to restore (e.g., backup-2025-01-28)", "flag": "", "required": true } ], "requires_sudo": true, "usage": "tor-switch restore-config-all [OPTIONS]" }, { "description": "List configuration backups", "examples": [ "tor-switch list-backups" ], "name": "list-backups", "options": [], "requires_sudo": false, "usage": "tor-switch list-backups [OPTIONS]" }, { "description": "Generate new Tor control password", "examples": [ "sudo tor-switch generate-new-tor-password" ], "name": "generate-new-tor-password", "options": [], "requires_sudo": true, "usage": "tor-switch generate-new-tor-password [OPTIONS]" }, { "description": "Generate password for all instances", "examples": [ "sudo tor-switch generate-new-tor-password-all" ], "name": "generate-new-tor-password-all", "options": [], "requires_sudo": true, "usage": "tor-switch generate-new-tor-password-all [OPTIONS]" }, { "description": "Clean custom torrc file", "examples": [ "sudo tor-switch clean-torrc-custom" ], "name": "clean-torrc-custom", "options": [], "requires_sudo": true, "usage": "tor-switch clean-torrc-custom [OPTIONS]" }, { "description": "Clean custom torrc for all instances", "examples": [ "sudo tor-switch clean-torrc-custom-all" ], "name": "clean-torrc-custom-all", "options": [], "requires_sudo": true, "usage": "tor-switch clean-torrc-custom-all [OPTIONS]" } ] }, { "category": "DNS Management", "commands": [ { "description": "Start Tor DNS with iptables", "examples": [ "sudo tor-switch start-tor-dns-iptables" ], "name": "start-tor-dns-iptables", "options": [], "requires_sudo": true, "usage": "tor-switch start-tor-dns-iptables [OPTIONS]" }, { "description": "Start Tor DNS with nftables", "examples": [ "sudo tor-switch start-tor-dns-nftables" ], "name": "start-tor-dns-nftables", "options": [], "requires_sudo": true, "usage": "tor-switch start-tor-dns-nftables [OPTIONS]" }, { "description": "Stop Tor DNS iptables", "examples": [ "sudo tor-switch stop-tor-dns-iptables" ], "name": "stop-tor-dns-iptables", "options": [], "requires_sudo": true, "usage": "tor-switch stop-tor-dns-iptables [OPTIONS]" }, { "description": "Stop Tor DNS nftables", "examples": [ "sudo tor-switch stop-tor-dns-nftables" ], "name": "stop-tor-dns-nftables", "options": [], "requires_sudo": true, "usage": "tor-switch stop-tor-dns-nftables [OPTIONS]" }, { "description": "Route DNS through Tor (auto-detects the active firewall). DESTRUCTIVE: rewrites the live firewall immediately", "examples": [ "sudo tor-switch torrify-system-dns" ], "name": "torrify-system-dns", "options": [ { "description": "Accepted for backwards compatibility. NOT a confirmation gate: this operation runs immediately with or without it", "flag": "--force", "required": false } ], "requires_sudo": true, "usage": "tor-switch torrify-system-dns [OPTIONS]" }, { "description": "Route DNS through Tor with iptables. DESTRUCTIVE: rewrites the live firewall immediately", "examples": [ "sudo tor-switch torrify-system-iptables-dns" ], "name": "torrify-system-iptables-dns", "options": [ { "description": "Accepted for backwards compatibility. NOT a confirmation gate: this operation runs immediately with or without it", "flag": "--force", "required": false } ], "requires_sudo": true, "usage": "tor-switch torrify-system-iptables-dns [OPTIONS]" }, { "description": "Route DNS through Tor with nftables. DESTRUCTIVE: rewrites the live firewall immediately", "examples": [ "sudo tor-switch torrify-system-nftables-dns" ], "name": "torrify-system-nftables-dns", "options": [ { "description": "Accepted for backwards compatibility. NOT a confirmation gate: this operation runs immediately with or without it", "flag": "--force", "required": false } ], "requires_sudo": true, "usage": "tor-switch torrify-system-nftables-dns [OPTIONS]" }, { "description": "Verify Tor DNS resolution", "examples": [ "tor-switch verify-tor-dns", "tor-switch verify-tor-dns --json" ], "name": "verify-tor-dns", "options": [], "requires_sudo": false, "usage": "tor-switch verify-tor-dns [OPTIONS]" }, { "description": "Verify DNS for all instances", "examples": [ "tor-switch verify-tor-dns-all" ], "name": "verify-tor-dns-all", "options": [], "requires_sudo": false, "usage": "tor-switch verify-tor-dns-all [OPTIONS]" }, { "description": "Direct Tor DNS verification", "examples": [ "tor-switch verify-tor-dns-direct" ], "name": "verify-tor-dns-direct", "options": [], "requires_sudo": false, "usage": "tor-switch verify-tor-dns-direct [OPTIONS]" }, { "description": "Verify Tor DNS port", "examples": [ "tor-switch verify-tor-dns-port" ], "name": "verify-tor-dns-port", "options": [], "requires_sudo": false, "usage": "tor-switch verify-tor-dns-port [OPTIONS]" } ] }, { "category": "Exit Node Control", "commands": [ { "description": "Set Tor exit node", "examples": [ "sudo tor-switch set-exit-node us", "sudo tor-switch set-exit-node gb --instance secondary", "sudo tor-switch set-exit-node de --instance streaming", "sudo tor-switch set-exit-node ch --instance secure", "sudo tor-switch set-exit-node random", "sudo tor-switch set-exit-node all-world", "sudo tor-switch set-exit-node random-europe", "sudo tor-switch set-exit-node random-asia", "sudo tor-switch set-exit-node random-africa", "sudo tor-switch set-exit-node random-north-america", "sudo tor-switch set-exit-node random-south-america", "sudo tor-switch set-exit-node random-oceania", "sudo tor-switch set-exit-node random-middle-east", "sudo tor-switch set-exit-node random-5eyes", "sudo tor-switch set-exit-node random-9eyes", "sudo tor-switch set-exit-node random-14eyes", "sudo tor-switch set-exit-node random-high-volume", "sudo tor-switch set-exit-node random-low-volume", "sudo tor-switch set-exit-node europe", "sudo tor-switch set-exit-node asia", "sudo tor-switch set-exit-node africa", "sudo tor-switch set-exit-node north-america", "sudo tor-switch set-exit-node south-america", "sudo tor-switch set-exit-node oceania", "sudo tor-switch set-exit-node middle-east", "sudo tor-switch set-exit-node 5eyes", "sudo tor-switch set-exit-node 9eyes", "sudo tor-switch set-exit-node 14eyes", "sudo tor-switch set-exit-node high-volume", "sudo tor-switch set-exit-node low-volume", "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", "sudo tor-switch set-exit-node random-low-volume --instance research", "sudo tor-switch set-exit-node high-volume --instance testing" ], "name": "set-exit-node", "options": [ { "description": "2-letter country code (us, gb, ca) or a group alias: 5eyes, 9eyes, 14eyes, europe, asia, africa, north-america, south-america, oceania, middle-east, high-volume, low-volume, all-world, random, or random- such as random-europe", "flag": "", "required": true }, { "description": "Target instance (optional)", "flag": "--instance ", "required": false } ], "requires_sudo": true, "usage": "tor-switch set-exit-node [OPTIONS]" }, { "description": "Set exit node for all instances", "examples": [ "sudo tor-switch set-exit-node-all ca" ], "name": "set-exit-node-all", "options": [ { "description": "2-letter country code (us, gb, ca) or a group alias: 5eyes, 9eyes, 14eyes, europe, asia, africa, north-america, south-america, oceania, middle-east, high-volume, low-volume, all-world, random, or random- such as random-europe", "flag": "", "required": true } ], "requires_sudo": true, "usage": "tor-switch set-exit-node-all [OPTIONS]" }, { "description": "Set excluded nodes", "examples": [ "sudo tor-switch set-exclude-node cn,ru,ir", "sudo tor-switch set-exclude-node 5eyes", "sudo tor-switch set-exclude-node 9eyes", "sudo tor-switch set-exclude-node 14eyes", "sudo tor-switch set-exclude-node europe", "sudo tor-switch set-exclude-node asia", "sudo tor-switch set-exclude-node north-america", "sudo tor-switch set-exclude-node high-volume", "sudo tor-switch set-exclude-node low-volume", "sudo tor-switch set-exclude-node random-high-volume", "sudo tor-switch set-exclude-node random-low-volume", "sudo tor-switch set-exclude-node asia --instance secure", "sudo tor-switch set-exclude-node 14eyes --instance privacy-1", "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" ], "name": "set-exclude-node", "options": [ { "description": "Comma-separated country codes to exclude (cn,ru,ir) or a group alias: 5eyes, 9eyes, 14eyes, europe, asia, africa, north-america, south-america, oceania, middle-east, high-volume, low-volume, all-world, or random- such as random-14eyes", "flag": "", "required": true }, { "description": "Target instance (optional)", "flag": "--instance ", "required": false } ], "requires_sudo": true, "usage": "tor-switch set-exclude-node [OPTIONS]" }, { "description": "Set excluded nodes for all instances", "examples": [ "sudo tor-switch set-exclude-node-all fr" ], "name": "set-exclude-node-all", "options": [ { "description": "Comma-separated country codes to exclude (cn,ru,ir) or a group alias: 5eyes, 9eyes, 14eyes, europe, asia, africa, north-america, south-america, oceania, middle-east, high-volume, low-volume, all-world, or random- such as random-14eyes", "flag": "", "required": true } ], "requires_sudo": true, "usage": "tor-switch set-exclude-node-all [OPTIONS]" }, { "description": "Clear exit node restrictions", "examples": [ "sudo tor-switch clear-exit-node" ], "name": "clear-exit-node", "options": [ { "description": "Target instance (optional, defaults to default instance)", "flag": "--instance ", "required": false } ], "requires_sudo": true, "usage": "tor-switch clear-exit-node [OPTIONS]" }, { "description": "Clear exit node for all instances", "examples": [ "sudo tor-switch clear-exit-node-all" ], "name": "clear-exit-node-all", "options": [], "requires_sudo": true, "usage": "tor-switch clear-exit-node-all [OPTIONS]" }, { "description": "Clear excluded nodes for all instances", "examples": [ "sudo tor-switch clear-exclude-node-all" ], "name": "clear-exclude-node-all", "options": [], "requires_sudo": true, "usage": "tor-switch clear-exclude-node-all [OPTIONS]" }, { "description": "Create new Tor circuit", "examples": [ "sudo tor-switch new-tor-circuit" ], "name": "new-tor-circuit", "options": [ { "description": "Target instance (optional, defaults to default instance)", "flag": "--instance ", "required": false } ], "requires_sudo": true, "usage": "tor-switch new-tor-circuit [OPTIONS]" }, { "description": "New circuit for all instances", "examples": [ "sudo tor-switch new-tor-circuit-all" ], "name": "new-tor-circuit-all", "options": [], "requires_sudo": true, "usage": "tor-switch new-tor-circuit-all [OPTIONS]" } ] }, { "category": "Firewall", "commands": [ { "description": "Flush iptables rules. DESTRUCTIVE: clears every rule immediately, no confirmation prompt", "examples": [ "sudo tor-switch flush-iptables" ], "name": "flush-iptables", "options": [ { "description": "Accepted for backwards compatibility. NOT a confirmation gate: this operation runs immediately with or without it", "flag": "--force", "required": false } ], "requires_sudo": true, "usage": "tor-switch flush-iptables [OPTIONS]" }, { "description": "Flush nftables rules. DESTRUCTIVE: clears every rule immediately, no confirmation prompt", "examples": [ "sudo tor-switch flush-nftables" ], "name": "flush-nftables", "options": [ { "description": "Accepted for backwards compatibility. NOT a confirmation gate: this operation runs immediately with or without it", "flag": "--force", "required": false } ], "requires_sudo": true, "usage": "tor-switch flush-nftables [OPTIONS]" }, { "description": "List iptables rules", "examples": [ "sudo tor-switch list-iptables" ], "name": "list-iptables", "options": [], "requires_sudo": true, "usage": "tor-switch list-iptables [OPTIONS]" }, { "description": "List iptables NAT rules", "examples": [ "sudo tor-switch list-iptables-nat" ], "name": "list-iptables-nat", "options": [], "requires_sudo": true, "usage": "tor-switch list-iptables-nat [OPTIONS]" }, { "description": "List nftables rules", "examples": [ "sudo tor-switch list-nftables" ], "name": "list-nftables", "options": [], "requires_sudo": true, "usage": "tor-switch list-nftables [OPTIONS]" } ] }, { "category": "HAProxy", "commands": [ { "description": "Generate HAProxy configuration", "examples": [ "sudo tor-switch generate-haproxy-config roundrobin 9055", "sudo tor-switch generate-haproxy-config source 8080", "sudo tor-switch generate-haproxy-config leastconn 9000", "sudo tor-switch generate-haproxy-config random 8888", "sudo tor-switch generate-haproxy-config" ], "name": "generate-haproxy-config", "options": [ { "description": "Load balancing mode (roundrobin, source, random, leastconn, first)", "flag": "", "required": false }, { "description": "Bind port (default: 9055)", "flag": "", "required": false }, { "description": "Output file path (default: /etc/haproxy/tor-haproxy.cfg)", "flag": "", "required": false }, { "description": "Maximum connections (default: 4096)", "flag": "", "required": false } ], "requires_sudo": true, "usage": "tor-switch generate-haproxy-config [OPTIONS]" }, { "description": "Start HAProxy service", "examples": [ "sudo tor-switch haproxy-start" ], "name": "haproxy-start", "options": [], "requires_sudo": true, "usage": "tor-switch haproxy-start [OPTIONS]" }, { "description": "Stop HAProxy service", "examples": [ "sudo tor-switch haproxy-stop" ], "name": "haproxy-stop", "options": [], "requires_sudo": true, "usage": "tor-switch haproxy-stop [OPTIONS]" }, { "description": "Check HAProxy status", "examples": [ "tor-switch haproxy-status" ], "name": "haproxy-status", "options": [], "requires_sudo": false, "usage": "tor-switch haproxy-status [OPTIONS]" }, { "description": "List HAProxy load balancing modes", "examples": [ "tor-switch list-haproxy-modes" ], "name": "list-haproxy-modes", "options": [], "requires_sudo": false, "usage": "tor-switch list-haproxy-modes [OPTIONS]" }, { "description": "Display load balancing configuration", "examples": [ "tor-switch display-load-balancing-config" ], "name": "display-load-balancing-config", "options": [], "requires_sudo": false, "usage": "tor-switch display-load-balancing-config [OPTIONS]" } ] }, { "category": "Help", "commands": [ { "description": "Show help information", "examples": [ "tor-switch show-help" ], "name": "show-help", "options": [], "requires_sudo": false, "usage": "tor-switch show-help [OPTIONS]" }, { "description": "Show usage examples", "examples": [ "tor-switch show-examples" ], "name": "show-examples", "options": [], "requires_sudo": false, "usage": "tor-switch show-examples [OPTIONS]" } ] }, { "category": "Instance Management", "commands": [ { "description": "Create new Tor instance", "examples": [ "sudo tor-switch create-instance secondary", "sudo tor-switch create-instance europe", "sudo tor-switch create-instance asia", "sudo tor-switch create-instance americas", "sudo tor-switch create-instance research", "sudo tor-switch create-instance testing" ], "name": "create-instance", "options": [ { "description": "Instance name", "flag": "", "required": true } ], "requires_sudo": true, "usage": "tor-switch create-instance [OPTIONS]" }, { "description": "Delete Tor instance", "examples": [ "sudo tor-switch delete-instance secondary" ], "name": "delete-instance", "options": [ { "description": "Instance tag/name", "flag": "", "required": true } ], "requires_sudo": true, "usage": "tor-switch delete-instance [OPTIONS]" }, { "description": "Delete all Tor instances", "examples": [ "sudo tor-switch delete-all-instances" ], "name": "delete-all-instances", "options": [], "requires_sudo": true, "usage": "tor-switch delete-all-instances [OPTIONS]" }, { "description": "Delete all instances including default", "examples": [ "sudo tor-switch delete-all-instances-with-default" ], "name": "delete-all-instances-with-default", "options": [], "requires_sudo": true, "usage": "tor-switch delete-all-instances-with-default [OPTIONS]" }, { "description": "Start a Tor instance", "examples": [ "sudo tor-switch start-instance secondary" ], "name": "start-instance", "options": [ { "description": "Instance tag/name", "flag": "", "required": true } ], "requires_sudo": true, "usage": "tor-switch start-instance [OPTIONS]" }, { "description": "Stop a Tor instance", "examples": [ "sudo tor-switch stop-instance secondary" ], "name": "stop-instance", "options": [ { "description": "Instance tag/name", "flag": "", "required": true } ], "requires_sudo": true, "usage": "tor-switch stop-instance [OPTIONS]" }, { "description": "Restart a Tor instance", "examples": [ "sudo tor-switch restart-instance secondary" ], "name": "restart-instance", "options": [ { "description": "Instance tag/name", "flag": "", "required": true } ], "requires_sudo": true, "usage": "tor-switch restart-instance [OPTIONS]" }, { "description": "Start all Tor instances", "examples": [ "sudo tor-switch start-all-instances" ], "name": "start-all-instances", "options": [], "requires_sudo": true, "usage": "tor-switch start-all-instances [OPTIONS]" }, { "description": "Stop all Tor instances", "examples": [ "sudo tor-switch stop-all-instances" ], "name": "stop-all-instances", "options": [], "requires_sudo": true, "usage": "tor-switch stop-all-instances [OPTIONS]" }, { "description": "Restart all Tor instances", "examples": [ "sudo tor-switch restart-all-instances" ], "name": "restart-all-instances", "options": [], "requires_sudo": true, "usage": "tor-switch restart-all-instances [OPTIONS]" }, { "description": "Show instance details", "examples": [ "tor-switch show-instance streaming" ], "name": "show-instance", "options": [ { "description": "Instance tag/name", "flag": "", "required": true } ], "requires_sudo": false, "usage": "tor-switch show-instance [OPTIONS]" }, { "description": "Set default Tor instance", "examples": [ "sudo tor-switch set-default-instance performance-0" ], "name": "set-default-instance", "options": [ { "description": "Instance tag/name", "flag": "", "required": true } ], "requires_sudo": true, "usage": "tor-switch set-default-instance [OPTIONS]" }, { "description": "Rename a Tor instance", "examples": [ "sudo tor-switch rename-instance old-name new-name" ], "name": "rename-instance", "options": [ { "description": "Current instance tag/name", "flag": "", "required": true }, { "description": "New instance tag/name", "flag": "", "required": true } ], "requires_sudo": true, "usage": "tor-switch rename-instance [OPTIONS]" }, { "description": "Clone a Tor instance", "examples": [ "sudo tor-switch clone-instance main backup" ], "name": "clone-instance", "options": [ { "description": "Source instance tag/name", "flag": "", "required": true }, { "description": "Target instance tag/name", "flag": "", "required": true } ], "requires_sudo": true, "usage": "tor-switch clone-instance [OPTIONS]" }, { "description": "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).", "examples": [ "sudo tor-switch create-multiple-instances 5", "sudo tor-switch create-multiple-instances 3 performance", "sudo tor-switch create-multiple-instances 10 worker", "sudo tor-switch create-multiple-instances 5 region", "sudo tor-switch create-multiple-instances 3 node", "sudo tor-switch create-multiple-instances 3 privacy", "sudo tor-switch create-multiple-instances 5 ha", "sudo tor-switch create-multiple-instances 10 perf" ], "name": "create-multiple-instances", "options": [ { "description": "Number of instances to create (omit to use RAM-aware default)", "flag": "", "required": false }, { "description": "Optional prefix for instance names", "flag": "", "required": false } ], "requires_sudo": true, "usage": "tor-switch create-multiple-instances [OPTIONS]" } ] }, { "category": "Load Balancing", "commands": [ { "description": "Set load balancing mode", "examples": [ "sudo tor-switch set-load-balancing-mode round-robin", "sudo tor-switch set-load-balancing-mode weighted", "sudo tor-switch set-load-balancing-mode consistent-hashing" ], "name": "set-load-balancing-mode", "options": [ { "description": "Load balancing mode: round-robin, weighted or consistent-hashing", "flag": "", "required": true } ], "requires_sudo": true, "usage": "tor-switch set-load-balancing-mode [OPTIONS]" }, { "description": "Set instance weight for load balancing", "examples": [ "sudo tor-switch set-instance-weight secondary 50", "sudo tor-switch set-instance-weight tor1 50", "sudo tor-switch set-instance-weight tor1 10", "sudo tor-switch set-instance-weight tor2 30", "sudo tor-switch set-instance-weight tor3 60", "sudo tor-switch set-instance-weight performance-0 75", "sudo tor-switch set-instance-weight backup 5", "sudo tor-switch set-instance-weight worker-1 25", "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" ], "name": "set-instance-weight", "options": [ { "description": "Instance name", "flag": "", "required": true }, { "description": "Weight value (1-100)", "flag": "", "required": true } ], "requires_sudo": true, "usage": "tor-switch set-instance-weight [OPTIONS]" }, { "description": "Torrify with iptables load balancing. DESTRUCTIVE: rewrites the live firewall immediately", "examples": [ "sudo tor-switch torrify-system-iptables-load-balanced" ], "name": "torrify-system-iptables-load-balanced", "options": [ { "description": "Accepted for backwards compatibility. NOT a confirmation gate: this operation runs immediately with or without it", "flag": "--force", "required": false } ], "requires_sudo": true, "usage": "tor-switch torrify-system-iptables-load-balanced [OPTIONS]" }, { "description": "Torrify with nftables load balancing. DESTRUCTIVE: rewrites the live firewall immediately", "examples": [ "sudo tor-switch torrify-system-nftables-load-balanced" ], "name": "torrify-system-nftables-load-balanced", "options": [ { "description": "Accepted for backwards compatibility. NOT a confirmation gate: this operation runs immediately with or without it", "flag": "--force", "required": false } ], "requires_sudo": true, "usage": "tor-switch torrify-system-nftables-load-balanced [OPTIONS]" }, { "description": "Pre-warm Tor instances and verify circuit readiness without applying firewall rules", "examples": [ "sudo tor-switch prepare-tor" ], "name": "prepare-tor", "options": [], "requires_sudo": true, "usage": "tor-switch prepare-tor [OPTIONS]" } ] }, { "category": "Main Tor Management", "commands": [ { "description": "Validate main Tor configuration", "examples": [ "tor-switch validate-torrc-main --maintor", "tor-switch validate-torrc-main --maintor --json" ], "name": "validate-torrc-main", "options": [ { "description": "Operate on main/system Tor daemon", "flag": "--maintor", "required": false }, { "description": "Specify instance name (mutually exclusive with --maintor)", "flag": "-i, --instance ", "required": false } ], "requires_sudo": false, "usage": "tor-switch validate-torrc-main [OPTIONS]" }, { "description": "Display main Tor settings (ports, exit/exclude nodes, security)", "examples": [ "tor-switch read-main-tor-config" ], "name": "read-main-tor-config", "options": [ { "description": "Operate on main/system Tor daemon", "flag": "--maintor", "required": false }, { "description": "Specify instance name (mutually exclusive with --maintor)", "flag": "-i, --instance ", "required": false } ], "requires_sudo": false, "usage": "tor-switch read-main-tor-config [OPTIONS]" }, { "description": "Backup main Tor configuration", "examples": [ "sudo tor-switch backup-main-tor-config" ], "name": "backup-main-tor-config", "options": [ { "description": "Operate on main/system Tor daemon", "flag": "--maintor", "required": false }, { "description": "Specify instance name (mutually exclusive with --maintor)", "flag": "-i, --instance ", "required": false } ], "requires_sudo": true, "usage": "tor-switch backup-main-tor-config [OPTIONS]" }, { "description": "Restore main Tor configuration from backup", "examples": [ "sudo tor-switch restore-main-tor-config torrc-main-20240115-143022.backup" ], "name": "restore-main-tor-config", "options": [ { "description": "Operate on main/system Tor daemon", "flag": "--maintor", "required": false }, { "description": "Specify instance name (mutually exclusive with --maintor)", "flag": "-i, --instance ", "required": false }, { "description": "Backup file name to restore (under backups/main-tor)", "flag": "", "required": false } ], "requires_sudo": true, "usage": "tor-switch restore-main-tor-config [OPTIONS]" }, { "description": "Set exit node for main Tor", "examples": [ "sudo tor-switch set-exit-node-main US --maintor" ], "name": "set-exit-node-main", "options": [ { "description": "Operate on main/system Tor daemon", "flag": "--maintor", "required": false }, { "description": "Specify instance name (mutually exclusive with --maintor)", "flag": "-i, --instance ", "required": false }, { "description": "Exit node country code(s), e.g. US or {us},{de}", "flag": "", "required": false } ], "requires_sudo": true, "usage": "tor-switch set-exit-node-main [OPTIONS]" }, { "description": "Clear exit restrictions for main Tor", "examples": [ "sudo tor-switch clear-exit-node-main --maintor" ], "name": "clear-exit-node-main", "options": [ { "description": "Operate on main/system Tor daemon", "flag": "--maintor", "required": false }, { "description": "Specify instance name (mutually exclusive with --maintor)", "flag": "-i, --instance ", "required": false } ], "requires_sudo": true, "usage": "tor-switch clear-exit-node-main [OPTIONS]" }, { "description": "Set excluded countries for main Tor", "examples": [ "sudo tor-switch set-exclude-node-main CN,RU --maintor" ], "name": "set-exclude-node-main", "options": [ { "description": "Operate on main/system Tor daemon", "flag": "--maintor", "required": false }, { "description": "Specify instance name (mutually exclusive with --maintor)", "flag": "-i, --instance ", "required": false }, { "description": "Country code(s) to exclude, e.g. CN,RU or {cn},{ru}", "flag": "", "required": false } ], "requires_sudo": true, "usage": "tor-switch set-exclude-node-main [OPTIONS]" }, { "description": "Clear exclude restrictions for main Tor", "examples": [ "sudo tor-switch clear-exclude-node-main", "sudo tor-switch clear-exclude-node-main --maintor" ], "name": "clear-exclude-node-main", "options": [ { "description": "Operate on main/system Tor daemon", "flag": "--maintor", "required": false }, { "description": "Specify instance name (mutually exclusive with --maintor)", "flag": "-i, --instance ", "required": false } ], "requires_sudo": true, "usage": "tor-switch clear-exclude-node-main [OPTIONS]" }, { "description": "Show current exit/exclude settings for main Tor", "examples": [ "tor-switch list-exit-exclude-main" ], "name": "list-exit-exclude-main", "options": [ { "description": "Operate on main/system Tor daemon", "flag": "--maintor", "required": false }, { "description": "Specify instance name (mutually exclusive with --maintor)", "flag": "-i, --instance ", "required": false } ], "requires_sudo": false, "usage": "tor-switch list-exit-exclude-main [OPTIONS]" }, { "description": "Reload main Tor configuration (SIGHUP)", "examples": [ "sudo tor-switch reload-main-tor" ], "name": "reload-main-tor", "options": [ { "description": "Operate on main/system Tor daemon", "flag": "--maintor", "required": false }, { "description": "Specify instance name (mutually exclusive with --maintor)", "flag": "-i, --instance ", "required": false } ], "requires_sudo": true, "usage": "tor-switch reload-main-tor [OPTIONS]" }, { "description": "Detailed status of main Tor daemon", "examples": [ "tor-switch status-main-tor" ], "name": "status-main-tor", "options": [ { "description": "Operate on main/system Tor daemon", "flag": "--maintor", "required": false }, { "description": "Specify instance name (mutually exclusive with --maintor)", "flag": "-i, --instance ", "required": false } ], "requires_sudo": false, "usage": "tor-switch status-main-tor [OPTIONS]" }, { "description": "Verify DNS routing through main Tor", "examples": [ "tor-switch verify-main-tor-dns" ], "name": "verify-main-tor-dns", "options": [ { "description": "Operate on main/system Tor daemon", "flag": "--maintor", "required": false }, { "description": "Specify instance name (mutually exclusive with --maintor)", "flag": "-i, --instance ", "required": false } ], "requires_sudo": false, "usage": "tor-switch verify-main-tor-dns [OPTIONS]" }, { "description": "Request new circuit for main Tor", "examples": [ "sudo tor-switch new-circuit-main-tor" ], "name": "new-circuit-main-tor", "options": [ { "description": "Operate on main/system Tor daemon", "flag": "--maintor", "required": false }, { "description": "Specify instance name (mutually exclusive with --maintor)", "flag": "-i, --instance ", "required": false } ], "requires_sudo": true, "usage": "tor-switch new-circuit-main-tor [OPTIONS]" }, { "description": "Security audit of main Tor config", "examples": [ "tor-switch check-main-tor-security" ], "name": "check-main-tor-security", "options": [ { "description": "Operate on main/system Tor daemon", "flag": "--maintor", "required": false }, { "description": "Specify instance name (mutually exclusive with --maintor)", "flag": "-i, --instance ", "required": false } ], "requires_sudo": false, "usage": "tor-switch check-main-tor-security [OPTIONS]" }, { "description": "Show bandwidth usage of main Tor", "examples": [ "tor-switch main-tor-bandwidth" ], "name": "main-tor-bandwidth", "options": [ { "description": "Operate on main/system Tor daemon", "flag": "--maintor", "required": false }, { "description": "Specify instance name (mutually exclusive with --maintor)", "flag": "-i, --instance ", "required": false } ], "requires_sudo": false, "usage": "tor-switch main-tor-bandwidth [OPTIONS]" }, { "description": "List active connections through main Tor", "examples": [ "tor-switch main-tor-connections" ], "name": "main-tor-connections", "options": [ { "description": "Operate on main/system Tor daemon", "flag": "--maintor", "required": false }, { "description": "Specify instance name (mutually exclusive with --maintor)", "flag": "-i, --instance ", "required": false } ], "requires_sudo": false, "usage": "tor-switch main-tor-connections [OPTIONS]" }, { "description": "Display recent main Tor logs", "examples": [ "tor-switch main-tor-logs" ], "name": "main-tor-logs", "options": [ { "description": "Operate on main/system Tor daemon", "flag": "--maintor", "required": false }, { "description": "Specify instance name (mutually exclusive with --maintor)", "flag": "-i, --instance ", "required": false } ], "requires_sudo": false, "usage": "tor-switch main-tor-logs [OPTIONS]" } ] }, { "category": "Status Operations", "commands": [ { "description": "Check if Tor service is running via systemctl", "examples": [ "tor-switch check-tor" ], "name": "check-tor", "options": [], "requires_sudo": false, "usage": "tor-switch check-tor [OPTIONS]" }, { "description": "Check systemctl status for all Tor instances", "examples": [ "tor-switch check-tor-all" ], "name": "check-tor-all", "options": [], "requires_sudo": false, "usage": "tor-switch check-tor-all [OPTIONS]" }, { "description": "Verify Tor connectivity through network check", "examples": [ "tor-switch torverify", "tor-switch torverify --json-pretty" ], "name": "torverify", "options": [], "requires_sudo": false, "usage": "tor-switch torverify [OPTIONS]" }, { "description": "Get comprehensive Tor service status (PID, memory, uptime)", "examples": [ "tor-switch tor-status", "tor-switch tor-status --json" ], "name": "tor-status", "options": [], "requires_sudo": false, "usage": "tor-switch tor-status [OPTIONS]" }, { "description": "Get comprehensive status for all Tor instances", "examples": [ "tor-switch tor-status-all" ], "name": "tor-status-all", "options": [], "requires_sudo": false, "usage": "tor-switch tor-status-all [OPTIONS]" }, { "description": "Get Tor status information", "examples": [ "tor-switch get-tor-status" ], "name": "get-tor-status", "options": [], "requires_sudo": false, "usage": "tor-switch get-tor-status [OPTIONS]" }, { "description": "Get custom Tor status", "examples": [ "tor-switch get-tor-custom-status" ], "name": "get-tor-custom-status", "options": [], "requires_sudo": false, "usage": "tor-switch get-tor-custom-status [OPTIONS]" }, { "description": "List all Tor instances", "examples": [ "tor-switch list-instances" ], "name": "list-instances", "options": [], "requires_sudo": false, "usage": "tor-switch list-instances [OPTIONS]" }, { "description": "List all Tor instances with IP addresses", "examples": [ "tor-switch list-instances-with-ip" ], "name": "list-instances-with-ip", "options": [], "requires_sudo": false, "usage": "tor-switch list-instances-with-ip [OPTIONS]" }, { "description": "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).", "examples": [ "tor-switch recommended-instances" ], "name": "recommended-instances", "options": [], "requires_sudo": false, "usage": "tor-switch recommended-instances [OPTIONS]" } ] }, { "category": "System Management", "commands": [ { "description": "Check active firewall system", "examples": [ "tor-switch which-is-active" ], "name": "which-is-active", "options": [], "requires_sudo": false, "usage": "tor-switch which-is-active [OPTIONS]" }, { "description": "Clean up orphaned Tor instances", "examples": [ "sudo tor-switch cleanup" ], "name": "cleanup", "options": [ { "description": "Perform thorough cleanup that will also reset failed systemd units", "flag": "--thorough", "required": false } ], "requires_sudo": true, "usage": "tor-switch cleanup [OPTIONS]" }, { "description": "Clean orphaned services", "examples": [ "sudo tor-switch clean-orphan-services" ], "name": "clean-orphan-services", "options": [], "requires_sudo": true, "usage": "tor-switch clean-orphan-services [OPTIONS]" } ] }, { "category": "System Routing", "commands": [ { "description": "Route all traffic through Tor via iptables. DESTRUCTIVE: rewrites the live firewall immediately", "examples": [ "sudo tor-switch torrify-system-iptables" ], "name": "torrify-system-iptables", "options": [ { "description": "Accepted for backwards compatibility. NOT a confirmation gate: this operation runs immediately with or without it", "flag": "--force", "required": false } ], "requires_sudo": true, "usage": "tor-switch torrify-system-iptables [OPTIONS]" }, { "description": "Stop routing traffic through Tor via iptables. DESTRUCTIVE: removes Tor protection immediately", "examples": [ "sudo tor-switch detorrify-system-iptables" ], "name": "detorrify-system-iptables", "options": [ { "description": "Accepted for backwards compatibility. NOT a confirmation gate: this operation runs immediately with or without it", "flag": "--force", "required": false } ], "requires_sudo": true, "usage": "tor-switch detorrify-system-iptables [OPTIONS]" }, { "description": "Route all traffic through Tor via nftables. DESTRUCTIVE: rewrites the live firewall immediately", "examples": [ "sudo tor-switch torrify-system-nftables" ], "name": "torrify-system-nftables", "options": [ { "description": "Accepted for backwards compatibility. NOT a confirmation gate: this operation runs immediately with or without it", "flag": "--force", "required": false } ], "requires_sudo": true, "usage": "tor-switch torrify-system-nftables [OPTIONS]" }, { "description": "Stop routing traffic through Tor via nftables. DESTRUCTIVE: removes Tor protection immediately", "examples": [ "sudo tor-switch detorrify-system-nftables" ], "name": "detorrify-system-nftables", "options": [ { "description": "Accepted for backwards compatibility. NOT a confirmation gate: this operation runs immediately with or without it", "flag": "--force", "required": false } ], "requires_sudo": true, "usage": "tor-switch detorrify-system-nftables [OPTIONS]" }, { "description": "Restore the Tor instance pool at boot when the persisted firewall is torrified (no-op otherwise)", "examples": [ "sudo tor-switch boot-restore-torrified --json" ], "name": "boot-restore-torrified", "options": [], "requires_sudo": true, "usage": "tor-switch boot-restore-torrified [OPTIONS]" } ] }, { "category": "Timer & Automation", "commands": [ { "description": "Enable automatic IP changes", "examples": [ "sudo tor-switch auto-ip-change 10m" ], "name": "auto-ip-change", "options": [ { "description": "Interval for IP changes (e.g., 10m, 1h, 30s)", "flag": "", "required": true }, { "description": "Target instance (optional)", "flag": "--instance ", "required": false } ], "requires_sudo": true, "usage": "tor-switch auto-ip-change [OPTIONS]" }, { "description": "Stop automatic IP changes", "examples": [ "sudo tor-switch stop-auto-ip-change" ], "name": "stop-auto-ip-change", "options": [], "requires_sudo": true, "usage": "tor-switch stop-auto-ip-change [OPTIONS]" }, { "description": "Update IP change timer", "examples": [ "sudo tor-switch update-ip-timer browsing 5m", "sudo tor-switch update-ip-timer worker-1 30m", "sudo tor-switch update-ip-timer streaming 1h", "sudo tor-switch update-ip-timer research 15m", "sudo tor-switch update-ip-timer backup 24h", "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", "sudo tor-switch update-ip-timer research 2m" ], "name": "update-ip-timer", "options": [ { "description": "Instance name", "flag": "", "required": true }, { "description": "New interval (e.g., 5m, 1h, 30s)", "flag": "", "required": true } ], "requires_sudo": true, "usage": "tor-switch update-ip-timer [OPTIONS]" }, { "description": "Update timer for all instances", "examples": [ "sudo tor-switch update-ip-all-timer 10m", "sudo tor-switch update-ip-all-timer 2h", "sudo tor-switch update-ip-all-timer 15m" ], "name": "update-ip-all-timer", "options": [ { "description": "New interval for all instances (e.g., 10m, 1h)", "flag": "", "required": true } ], "requires_sudo": true, "usage": "tor-switch update-ip-all-timer [OPTIONS]" }, { "description": "Remove IP change timer", "examples": [ "sudo tor-switch remove-ip-timer browsing" ], "name": "remove-ip-timer", "options": [ { "description": "Instance name", "flag": "", "required": true } ], "requires_sudo": true, "usage": "tor-switch remove-ip-timer [OPTIONS]" }, { "description": "Remove all IP timers", "examples": [ "sudo tor-switch remove-ip-all-timer" ], "name": "remove-ip-all-timer", "options": [], "requires_sudo": true, "usage": "tor-switch remove-ip-all-timer [OPTIONS]" }, { "description": "List all IP change timers", "examples": [ "tor-switch list-ip-timers" ], "name": "list-ip-timers", "options": [], "requires_sudo": false, "usage": "tor-switch list-ip-timers [OPTIONS]" }, { "description": "List auto IP change settings", "examples": [ "tor-switch list-auto-ip-change" ], "name": "list-auto-ip-change", "options": [], "requires_sudo": false, "usage": "tor-switch list-auto-ip-change [OPTIONS]" } ] } ], "description": "Tor configuration and routing management for Kodachi OS", "environmentVariables": [ { "default": "unset", "description": "Disable all colored output when set", "name": "NO_COLOR", "values": "1|true|yes (any value disables color)" } ], "exitCodes": { "0": "Success", "1": "General error", "2": "Invalid arguments", "3": "Permission denied", "4": "Network error", "5": "File not found" }, "globalOptions": [ { "description": "Print help information", "flag": "-h, --help" }, { "description": "Print version information", "flag": "-v, --version" }, { "description": "Display detailed information", "flag": "-n, --info" }, { "description": "Show usage examples", "flag": "-e, --examples" }, { "description": "Output in JSON format", "flag": "--json" }, { "description": "Force output format (text|json)", "flag": "-o, --output-format " }, { "description": "Pretty-print JSON output with indentation", "flag": "--json-pretty" }, { "description": "Enhanced JSON output with improved formatting (like jq)", "flag": "--json-human" }, { "description": "Return only specified JSON fields (comma-separated)", "flag": "--json-filter " }, { "description": "Select specific fields to include in output (comma-separated)", "flag": "--fields " }, { "description": "Limit number of results returned", "flag": "--limit " }, { "description": "Skip first N results (for pagination)", "flag": "--offset " }, { "description": "Working directory (defaults to auto-detected base directory)", "flag": "-d, --work-dir " }, { "description": "Set custom port number (1024-65535)", "flag": "--port " }, { "description": "Set log level (error|warn|info|debug)", "flag": "--log-level " }, { "description": "Enable verbose output", "flag": "--verbose" }, { "description": "Suppress non-essential output", "flag": "--quiet" }, { "description": "Disable colored output", "flag": "--no-color" }, { "description": "Use custom configuration file", "flag": "--config " }, { "description": "Set operation timeout in seconds (optional; no default applied)", "flag": "--timeout " } ], "name": "tor-switch", "usage": "tor-switch [OPTIONS] [COMMAND] [ARGS]" }, "errors": [], "metadata": { "executionTime": 15, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:39.454219335Z", "version": "9.8.4 (build 320)", "warnings": [] }, "flag_e": { "command": "examples", "data": { "categories": [ { "description": "Essential operations for getting started", "examples": [ { "command": "sudo tor-switch start-tor", "description": "Start Tor daemon", "expectedOutput": "Tor daemon started successfully", "notes": "Requires sudo privileges for system-level operations" }, { "command": "sudo tor-switch stop-tor", "description": "Stop Tor daemon", "expectedOutput": "Tor daemon stopped successfully", "notes": "Gracefully shuts down Tor service" }, { "command": "sudo tor-switch restart-tor", "description": "Restart Tor daemon", "expectedOutput": "Tor daemon restarted successfully", "notes": "Combines stop and start operations" }, { "command": "sudo tor-switch torrify-system-iptables-dns", "description": "Route DNS through Tor using iptables", "expectedOutput": "DNS routing through Tor enabled (iptables)", "notes": "Redirects all system DNS queries to Tor DNS listener" }, { "command": "sudo tor-switch torrify-system-nftables-dns", "description": "Route DNS through Tor using nftables", "expectedOutput": "DNS routing through Tor enabled (nftables)", "notes": "Redirects all system DNS queries to Tor DNS listener" }, { "command": "sudo tor-switch torrify-system-iptables", "description": "Route all traffic through Tor", "expectedOutput": "System traffic routing through Tor enabled", "notes": "All network traffic will be routed through Tor" }, { "command": "sudo tor-switch detorrify-system-iptables", "description": "Stop routing traffic through Tor", "expectedOutput": "System traffic routing through Tor disabled", "notes": "Returns to normal direct internet connection" }, { "command": "sudo tor-switch torrify-system-nftables", "description": "Route all traffic through Tor via nftables", "expectedOutput": "System traffic routing through Tor enabled (nftables)", "notes": "DESTRUCTIVE: rewrites the system firewall and takes effect immediately, with no confirmation prompt. Uses the modern nftables backend. A --force (alias --yes) flag is accepted for compatibility but is not required and changes nothing." }, { "command": "sudo tor-switch detorrify-system-nftables", "description": "Stop routing traffic through Tor via nftables", "expectedOutput": "System traffic routing through Tor disabled (nftables)", "notes": "DESTRUCTIVE: drops the Tor firewall rules and returns you to a normal direct internet connection, with no confirmation prompt. Your traffic is no longer anonymised after this." }, { "command": "tor-switch check-tor", "description": "Check if Tor service is running", "expectedOutput": "Tor is responding/not responding", "notes": "Checks if Tor service is active via systemctl" }, { "command": "tor-switch torverify", "description": "Verify actual Tor connectivity", "expectedOutput": "Shows whether traffic is routed through Tor and displays IP", "notes": "Makes direct HTTP request to check.torproject.org to verify torrification" }, { "command": "sudo tor-switch new-tor-circuit", "description": "Get new Tor circuit/IP", "expectedOutput": "New circuit established with different exit IP", "notes": "Forces new Tor circuit for different exit node" } ], "id": "01_basic_usage", "title": "Basic Usage" }, { "description": "Managing multiple Tor instances for performance", "examples": [ { "command": "sudo tor-switch create-instance secondary", "description": "Create a secondary Tor instance", "expectedOutput": "Instance 'secondary' created successfully", "notes": "Multiple instances provide load balancing and redundancy" }, { "command": "tor-switch list-instances", "description": "List all available instances", "expectedOutput": "Shows all instances with their status" }, { "command": "sudo tor-switch start-instance secondary", "description": "Start specific instance", "expectedOutput": "Instance 'secondary' started" }, { "command": "sudo tor-switch stop-instance secondary", "description": "Stop specific instance", "expectedOutput": "Instance 'secondary' stopped" }, { "command": "sudo tor-switch restart-instance secondary", "description": "Restart specific instance", "expectedOutput": "Instance 'secondary' restarted" }, { "command": "sudo tor-switch restart-all-instances", "description": "Restart all Tor instances", "expectedOutput": "Restarted 5 out of 5 Tor instances" }, { "command": "sudo tor-switch delete-instance secondary", "description": "Delete an instance permanently", "expectedOutput": "Instance 'secondary' deleted", "notes": "This permanently removes the instance configuration" }, { "command": "sudo tor-switch start-all-instances", "description": "Start all configured instances", "expectedOutput": "All Tor instances started" }, { "command": "sudo tor-switch stop-all-instances", "description": "Stop all running instances", "expectedOutput": "All Tor instances stopped" } ], "id": "02_instance_management", "title": "Instance Management" }, { "description": "Create, clone, rename and manage multiple Tor instances", "examples": [ { "command": "sudo tor-switch create-multiple-instances 5", "description": "Create 5 auto-named instances", "expectedOutput": "5 Tor instances created with auto-generated names", "notes": "Useful for load balancing and redundancy" }, { "command": "sudo tor-switch create-multiple-instances 3 performance", "description": "Create 3 instances with 'performance' prefix", "expectedOutput": "3 instances created: performance-0, performance-1, performance-2", "notes": "Creates instances with custom naming prefix" }, { "command": "sudo tor-switch create-multiple-instances 10 worker", "description": "Create 10 worker instances", "expectedOutput": "10 instances created: worker-1 through worker-10", "notes": "Ideal for high-throughput operations" }, { "command": "sudo tor-switch create-multiple-instances 5 region", "description": "Create 5 regional instances", "expectedOutput": "5 instances created: region-1 through region-5", "notes": "Perfect for geographic distribution" }, { "command": "sudo tor-switch create-multiple-instances 3 node", "description": "Create 3 node instances", "expectedOutput": "3 instances created: node-1, node-2, node-3", "notes": "Simple node-based naming" }, { "command": "sudo tor-switch clone-instance main backup", "description": "Clone 'main' instance to 'backup'", "expectedOutput": "Instance 'main' cloned to 'backup' successfully", "notes": "Copies all configuration from source instance" }, { "command": "sudo tor-switch rename-instance old-name new-name", "description": "Rename instance", "expectedOutput": "Instance renamed from 'old-name' to 'new-name'", "notes": "Updates all references and configuration files" }, { "command": "tor-switch list-instances-with-ip", "description": "List all instances with current IP addresses", "expectedOutput": "All instances listed with their current exit IPs", "notes": "Shows both instance names and their current exit IPs" }, { "command": "tor-switch show-instance streaming", "description": "Show detailed information for 'streaming' instance", "expectedOutput": "Detailed configuration and status for 'streaming' instance", "notes": "Shows configuration, status, and current IP information" }, { "command": "sudo tor-switch set-default-instance performance-0", "description": "Set 'performance-0' as the default instance", "expectedOutput": "Default instance set to 'performance-0'", "notes": "Changes which instance is used for default operations" }, { "command": "sudo tor-switch set-instance-weight secondary 50", "description": "Set weight for load balancing", "expectedOutput": "Instance 'secondary' weight set to 50", "notes": "Used for load balancing when multiple instances are active" }, { "command": "sudo tor-switch delete-all-instances", "description": "Delete all instances except default", "expectedOutput": "All non-default instances deleted", "notes": "Preserves default instance for basic functionality" }, { "command": "sudo tor-switch delete-all-instances-with-default", "description": "Delete ALL instances including default", "expectedOutput": "All instances deleted including default", "notes": "WARNING: Removes all instances" } ], "id": "03_advanced_instance_operations", "title": "Advanced Instance Operations" }, { "description": "Checking system status and verifying operations", "examples": [ { "command": "tor-switch tor-status", "description": "Get detailed Tor status", "expectedOutput": "Comprehensive status report of all Tor components" }, { "command": "tor-switch tor-status --json", "description": "Detailed status in JSON format", "expectedOutput": "JSON-formatted status report", "notes": "Machine-readable output for scripts" }, { "command": "tor-switch check-tor-all", "description": "Check Tor status for all instances", "expectedOutput": "Connection status for every configured instance", "notes": "Quick health check across all instances" }, { "command": "tor-switch torverify", "description": "Verify if system traffic is routed through Tor", "expectedOutput": "✓ You are connected through Tor\n IP Address: ", "notes": "Makes HTTP request to check.torproject.org API to verify torrification" }, { "command": "tor-switch torverify --json-pretty", "description": "Verify Tor connectivity with detailed JSON output", "expectedOutput": "{\n \"command\": \"torverify\",\n \"data\": {\n \"is_tor\": true,\n \"ip_address\": \"\",\n \"method\": \"api\",\n \"message\": \"You are connected through Tor with IP \"\n },\n \"errors\": [],\n \"metadata\": {...},\n \"status\": \"success\",\n \"timestamp\": \"...\",\n \"version\": \"\",\n \"warnings\": []\n}", "notes": "Useful for scripts and automation" }, { "command": "tor-switch tor-status-all", "description": "Get detailed status for all instances", "expectedOutput": "Comprehensive status report for all instances" }, { "command": "tor-switch get-tor-status", "description": "Get Tor daemon status", "expectedOutput": "Current Tor daemon status", "notes": "Quick status check - use tor-status for detailed report" }, { "command": "tor-switch recommended-instances", "description": "Show RAM-aware recommended load-balancing instance count", "expectedOutput": "Detected RAM, current override (if any), and the effective N (clamped 3..20)", "notes": "Read-only single source of truth (square-root model). Other components should query this instead of recomputing" } ], "id": "04_monitoring", "title": "Monitoring & Status" }, { "description": "Debug and resolve common issues", "examples": [ { "command": "sudo tor-switch cleanup", "description": "Clean up orphaned processes", "expectedOutput": "Orphaned instances and services cleaned up", "notes": "Use when experiencing startup issues" }, { "command": "sudo tor-switch cleanup", "description": "Clean orphaned Tor instances and services", "expectedOutput": "Cleanup completed successfully", "notes": "Removes orphaned instances and service files" }, { "command": "sudo tor-switch clean-orphan-services", "description": "Clean orphaned services", "expectedOutput": "Orphaned services removed" }, { "command": "sudo tor-switch new-tor-circuit-all", "description": "New circuits for all instances", "expectedOutput": "All instances have new circuits with different IPs", "notes": "Refreshes exit IPs for all active instances" } ], "id": "05_troubleshooting", "title": "Troubleshooting" }, { "description": "Control and configure Tor exit nodes for geographic routing and privacy. set-exit-node and set-exclude-node accept a 2-letter ISO country code (us, de, ch) or one of these group aliases: 5eyes, 9eyes, 14eyes, europe, asia, africa, north-america, south-america, oceania, middle-east, high-volume, low-volume, all-world. Prefix a group with random- (random-europe, random-14eyes, random-low-volume) to pin one randomly chosen country from that group, or use `random` on its own for one random country worldwide.", "examples": [ { "command": "sudo tor-switch set-exit-node us", "description": "Route via United States", "expectedOutput": "Exit node set to United States", "notes": "Affects the default Tor instance. Traffic will exit through US-based Tor nodes" }, { "command": "sudo tor-switch set-exit-node gb --instance secondary", "description": "Set UK exit for specific instance", "expectedOutput": "Exit node set to United Kingdom for 'secondary'", "notes": "Instance-specific exit node configuration" }, { "command": "sudo tor-switch set-exit-node de --instance streaming", "description": "Set Germany exit for streaming instance", "expectedOutput": "Exit node set to Germany for 'streaming'", "notes": "Useful for geo-restricted content" }, { "command": "sudo tor-switch set-exit-node ch --instance secure", "description": "Set Switzerland exit for secure instance", "expectedOutput": "Exit node set to Switzerland for 'secure'", "notes": "Privacy-friendly jurisdiction" }, { "command": "sudo tor-switch set-exit-node random", "description": "Random exit node selection", "expectedOutput": "Exit node set to random selection", "notes": "Maximum anonymity through randomization" }, { "command": "sudo tor-switch set-exit-node all-world", "description": "Allow exit nodes from every country in the country-group table", "expectedOutput": "ExitNodes set to the full all-world country list", "notes": "Widest possible exit set. Unlike `random`, which pins one randomly chosen country, this lets Tor pick freely from every country." }, { "command": "sudo tor-switch set-exit-node random-europe", "description": "Random European exit node", "expectedOutput": "Exit node set to random European country", "notes": "Stay within European jurisdiction" }, { "command": "sudo tor-switch set-exit-node random-asia", "description": "Random Asian exit node", "expectedOutput": "Exit node set to random Asian country", "notes": "Exit through Asian infrastructure" }, { "command": "sudo tor-switch set-exit-node random-africa", "description": "Random African exit node", "expectedOutput": "Exit node set to random African country", "notes": "Exit through African networks" }, { "command": "sudo tor-switch set-exit-node random-north-america", "description": "Random North American exit", "expectedOutput": "Exit node set to random North American country", "notes": "US, Canada, or Mexico exit" }, { "command": "sudo tor-switch set-exit-node random-south-america", "description": "Random South American exit", "expectedOutput": "Exit node set to random South American country", "notes": "Latin American exit points" }, { "command": "sudo tor-switch set-exit-node random-oceania", "description": "Random Oceania exit node", "expectedOutput": "Exit node set to random Oceania country", "notes": "Australia, NZ, or Pacific islands" }, { "command": "sudo tor-switch set-exit-node random-middle-east", "description": "Random Middle Eastern exit", "expectedOutput": "Exit node set to random Middle Eastern country", "notes": "Middle Eastern exit points" }, { "command": "sudo tor-switch set-exit-node random-5eyes", "description": "Random Five Eyes exit", "expectedOutput": "Exit node set to random Five Eyes country", "notes": "US, GB, CA, AU, NZ" }, { "command": "sudo tor-switch set-exit-node random-9eyes", "description": "Random Nine Eyes exit", "expectedOutput": "Exit node set to random Nine Eyes country", "notes": "5eyes + DK, FR, NL, NO" }, { "command": "sudo tor-switch set-exit-node random-14eyes", "description": "Random Fourteen Eyes exit", "expectedOutput": "Exit node set to random Fourteen Eyes country", "notes": "9eyes + DE, BE, IT, ES, SE" }, { "command": "sudo tor-switch set-exit-node random-high-volume", "description": "Random high-traffic exit", "expectedOutput": "Exit node set to random high-volume country", "notes": "Better performance and anonymity" }, { "command": "sudo tor-switch set-exit-node random-low-volume", "description": "Random low-traffic exit", "expectedOutput": "Exit node set to random low-volume country", "notes": "Less common exit points" }, { "command": "sudo tor-switch set-exit-node europe", "description": "Route through any European country", "expectedOutput": "Exit node set to Europe region", "notes": "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" }, { "command": "sudo tor-switch set-exit-node asia", "description": "Route through any Asian country", "expectedOutput": "Exit node set to Asia region", "notes": "Countries: HK, ID, IN, JP, KR, MY, PH, SG, TH, TW, VN" }, { "command": "sudo tor-switch set-exit-node africa", "description": "Route through any African country", "expectedOutput": "Exit node set to Africa region", "notes": "Countries: EG, KE, MA, NG, SC, TN, ZA" }, { "command": "sudo tor-switch set-exit-node north-america", "description": "Route through North America", "expectedOutput": "Exit node set to North America region", "notes": "US, Canada, or Mexico" }, { "command": "sudo tor-switch set-exit-node south-america", "description": "Route through South America", "expectedOutput": "Exit node set to South America region", "notes": "Countries: AR, BR, CL, CO, PE, UY, VE" }, { "command": "sudo tor-switch set-exit-node oceania", "description": "Route through Oceania", "expectedOutput": "Exit node set to Oceania region", "notes": "Countries: AU, NZ" }, { "command": "sudo tor-switch set-exit-node middle-east", "description": "Route through Middle East", "expectedOutput": "Exit node set to Middle East region", "notes": "Countries: AE, IL, IR, LB, OM, QA, SA, TR" }, { "command": "sudo tor-switch set-exit-node 5eyes", "description": "Use Five Eyes countries", "expectedOutput": "Exit node set to Five Eyes alliance", "notes": "US, GB, CA, AU, NZ" }, { "command": "sudo tor-switch set-exit-node 9eyes", "description": "Use Nine Eyes countries", "expectedOutput": "Exit node set to Nine Eyes alliance", "notes": "5eyes + Denmark, France, Netherlands, Norway" }, { "command": "sudo tor-switch set-exit-node 14eyes", "description": "Use Fourteen Eyes countries", "expectedOutput": "Exit node set to Fourteen Eyes alliance", "notes": "9eyes + Germany, Belgium, Italy, Spain, Sweden" }, { "command": "sudo tor-switch set-exit-node high-volume", "description": "Use high-traffic countries", "expectedOutput": "Exit node set to high-volume countries", "notes": "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" }, { "command": "sudo tor-switch set-exit-node low-volume", "description": "Use low-traffic countries", "expectedOutput": "Exit node set to low-volume countries", "notes": "Affects default instance. Countries excluding high-volume and 14eyes nations for uniqueness" }, { "command": "sudo tor-switch set-exit-node-all ca", "description": "Set Canada for all instances", "expectedOutput": "Exit node set to Canada for all instances", "notes": "Applies setting to all configured instances" }, { "command": "sudo tor-switch clear-exit-node", "description": "Clear exit node restrictions", "expectedOutput": "Exit node restrictions cleared", "notes": "Returns to default random exit selection" }, { "command": "sudo tor-switch set-exclude-node cn,ru,ir", "description": "Exclude specific countries", "expectedOutput": "Excluded nodes set", "notes": "Prevents routing through specified countries" }, { "command": "sudo tor-switch set-exclude-node 5eyes", "description": "Exclude Five Eyes countries", "expectedOutput": "Five Eyes countries excluded", "notes": "US, GB, CA, AU, NZ" }, { "command": "sudo tor-switch set-exclude-node 9eyes", "description": "Exclude Nine Eyes countries", "expectedOutput": "Nine Eyes countries excluded", "notes": "5eyes + Denmark, France, Netherlands, Norway" }, { "command": "sudo tor-switch set-exclude-node 14eyes", "description": "Exclude Fourteen Eyes countries", "expectedOutput": "Fourteen Eyes countries excluded", "notes": "9eyes + Germany, Belgium, Italy, Spain, Sweden" }, { "command": "sudo tor-switch set-exclude-node europe", "description": "Exclude all European countries", "expectedOutput": "European countries excluded", "notes": "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" }, { "command": "sudo tor-switch set-exclude-node asia", "description": "Exclude all Asian countries", "expectedOutput": "Asian countries excluded", "notes": "Excludes: HK, ID, IN, JP, KR, MY, PH, SG, TH, TW, VN" }, { "command": "sudo tor-switch set-exclude-node north-america", "description": "Exclude North American countries", "expectedOutput": "North American countries excluded", "notes": "US, Canada, Mexico excluded" }, { "command": "sudo tor-switch set-exclude-node high-volume", "description": "Exclude high-traffic countries", "expectedOutput": "High-volume countries excluded", "notes": "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" }, { "command": "sudo tor-switch set-exclude-node low-volume", "description": "Exclude low-traffic countries", "expectedOutput": "Low-volume countries excluded", "notes": "Use only high-traffic exit nodes" }, { "command": "sudo tor-switch set-exclude-node random-high-volume", "description": "Exclude one random high-traffic country", "expectedOutput": "Random high-volume country excluded", "notes": "Randomly blocks one popular exit country" }, { "command": "sudo tor-switch set-exclude-node random-low-volume", "description": "Exclude one random low-traffic country", "expectedOutput": "Random low-volume country excluded", "notes": "Randomly blocks one uncommon exit country" }, { "command": "sudo tor-switch set-exclude-node asia --instance secure", "description": "Exclude Asia for secure instance", "expectedOutput": "Asia excluded for 'secure' instance", "notes": "Instance-specific exclusion" }, { "command": "sudo tor-switch set-exclude-node 14eyes --instance privacy-1", "description": "Exclude 14eyes for privacy instance", "expectedOutput": "14eyes excluded for 'privacy-1' instance", "notes": "Maximum privacy configuration" }, { "command": "sudo tor-switch set-exclude-node-all fr", "description": "Exclude France for all instances", "expectedOutput": "France excluded for all instances", "notes": "Global exclusion across all instances" }, { "command": "sudo tor-switch clear-exclude-node-main", "description": "Clear all excluded countries", "expectedOutput": "All exclusions removed", "notes": "Resets to default behavior" }, { "command": "sudo tor-switch clear-exclude-node-all", "description": "Clear excluded nodes for all instances", "expectedOutput": "Exclusions removed for all instances", "notes": "Global clear matching set-exclude-node-all scope" }, { "command": "sudo tor-switch clear-exit-node-all", "description": "Clear exit restrictions for all instances", "expectedOutput": "Exit restrictions cleared for all instances", "notes": "All instances return to random exit selection" } ], "id": "06_exit_node_management", "title": "Exit Node Management" }, { "description": "Native load balancing using iptables/nftables firewall rules", "examples": [ { "command": "sudo tor-switch set-load-balancing-mode round-robin", "description": "Sequential distribution", "expectedOutput": "Load balancing mode set to round-robin", "notes": "Each new connection uses the next Tor instance in order" }, { "command": "sudo tor-switch set-load-balancing-mode weighted", "description": "Weight-based distribution", "expectedOutput": "Load balancing mode set to weighted", "notes": "Routes traffic based on instance weights" }, { "command": "sudo tor-switch set-load-balancing-mode consistent-hashing", "description": "Client IP affinity for session persistence", "expectedOutput": "Load balancing mode set to consistent-hashing", "notes": "Same client IP always routes to same Tor instance" }, { "command": "sudo tor-switch set-instance-weight tor1 50", "description": "Set weight for specific instance", "expectedOutput": "Weight for instance 'tor1' set to 50", "notes": "Only affects weighted mode distribution" }, { "command": "sudo tor-switch set-instance-weight tor1 10", "description": "Set low weight for minimal traffic", "expectedOutput": "Weight for instance 'tor1' set to 10", "notes": "10% of traffic when using weighted mode" }, { "command": "sudo tor-switch set-instance-weight tor2 30", "description": "Set moderate weight for balanced traffic", "expectedOutput": "Weight for instance 'tor2' set to 30", "notes": "30% of traffic distribution" }, { "command": "sudo tor-switch set-instance-weight tor3 60", "description": "Set high weight for primary traffic", "expectedOutput": "Weight for instance 'tor3' set to 60", "notes": "60% of traffic - primary instance" }, { "command": "sudo tor-switch set-instance-weight performance-0 75", "description": "High weight for performance instance", "expectedOutput": "Weight for instance 'performance-0' set to 75", "notes": "Prioritize high-performance instance" }, { "command": "sudo tor-switch set-instance-weight backup 5", "description": "Minimal weight for backup instance", "expectedOutput": "Weight for instance 'backup' set to 5", "notes": "Mostly idle, used for failover" }, { "command": "sudo tor-switch set-instance-weight worker-1 25", "description": "Equal weight for worker instances", "expectedOutput": "Weight for instance 'worker-1' set to 25", "notes": "4 workers at 25% each = equal distribution" }, { "command": "tor-switch display-load-balancing-config", "description": "Show current load balancing setup", "expectedOutput": "Current load balancing configuration details" }, { "command": "sudo tor-switch torrify-system-iptables-load-balanced", "description": "Apply load balanced routing (iptables)", "expectedOutput": "Load balanced routing through Tor enabled", "notes": "Routes traffic through multiple Tor instances using iptables" }, { "command": "sudo tor-switch torrify-system-nftables-load-balanced", "description": "Apply load balanced routing (nftables)", "expectedOutput": "Load balanced routing through Tor enabled (nftables)", "notes": "Modern firewall load balanced routing using nftables" }, { "command": "sudo tor-switch prepare-tor", "description": "Pre-warm Tor instances and verify circuit readiness", "expectedOutput": "Instances bootstrapped and circuits confirmed ready", "notes": "Warms instances without applying any firewall rules. Run it before torrify to avoid first-connection delays" } ], "id": "07_load_balancing", "title": "Load Balancing (Native Kernel-Level)" }, { "description": "HAProxy provides advanced application-level load balancing", "examples": [ { "command": "sudo tor-switch generate-haproxy-config roundrobin 9055", "description": "Generate config with round-robin algorithm", "expectedOutput": "HAProxy configuration generated", "notes": "Each server is used in turns on port 9055" }, { "command": "sudo tor-switch generate-haproxy-config source 8080", "description": "Generate config with source IP hash", "expectedOutput": "HAProxy configuration generated", "notes": "IP hash persistence on port 8080" }, { "command": "sudo tor-switch generate-haproxy-config leastconn 9000", "description": "Generate config with least connections", "expectedOutput": "HAProxy configuration generated", "notes": "Routes to instance with fewest active connections" }, { "command": "sudo tor-switch generate-haproxy-config random 8888", "description": "Generate config with random selection", "expectedOutput": "HAProxy configuration generated", "notes": "Randomly selects backend for each connection" }, { "command": "sudo tor-switch haproxy-start", "description": "Start HAProxy service", "expectedOutput": "HAProxy started successfully" }, { "command": "tor-switch haproxy-status", "description": "Check HAProxy status", "expectedOutput": "HAProxy service status and statistics" }, { "command": "sudo tor-switch haproxy-stop", "description": "Stop HAProxy service", "expectedOutput": "HAProxy stopped" }, { "command": "tor-switch list-haproxy-modes", "description": "Show available HAProxy algorithms", "expectedOutput": "List of supported HAProxy algorithms", "notes": "roundrobin, source, leastconn, random" } ], "id": "08_haproxy", "title": "HAProxy Integration (Application-Level Proxy)" }, { "description": "Automatic IP rotation and timer-based operations", "examples": [ { "command": "sudo tor-switch auto-ip-change 10m", "description": "Auto IP change every 10 minutes", "expectedOutput": "Automatic IP change enabled with 10 minute interval", "notes": "Creates new Tor circuit for default instance to get new exit IP" }, { "command": "sudo tor-switch update-ip-timer browsing 5m", "description": "Set timer for specific instance", "expectedOutput": "IP change timer set for 'browsing' instance" }, { "command": "sudo tor-switch update-ip-timer worker-1 30m", "description": "Set 30-minute timer for worker instance", "expectedOutput": "IP change timer set for 'worker-1' instance: 30 minutes", "notes": "Balanced rotation for moderate privacy" }, { "command": "sudo tor-switch update-ip-timer streaming 1h", "description": "Set hourly timer for streaming", "expectedOutput": "IP change timer set for 'streaming' instance: 1 hour", "notes": "Less frequent changes for stable connections" }, { "command": "sudo tor-switch update-ip-timer research 15m", "description": "Set 15-minute timer for research", "expectedOutput": "IP change timer set for 'research' instance: 15 minutes", "notes": "Frequent rotation for privacy-focused browsing" }, { "command": "sudo tor-switch update-ip-timer backup 24h", "description": "Set daily timer for backup instance", "expectedOutput": "IP change timer set for 'backup' instance: 24 hours", "notes": "Minimal rotation for long-running operations" }, { "command": "sudo tor-switch update-ip-all-timer 10m", "description": "Set 10-minute timer for all instances", "expectedOutput": "IP change timer set for all instances: 10 minutes", "notes": "Synchronizes rotation across all instances" }, { "command": "sudo tor-switch update-ip-all-timer 2h", "description": "Set 2-hour timer for all instances", "expectedOutput": "IP change timer set for all instances: 2 hours", "notes": "Stable rotation for production workloads" }, { "command": "tor-switch list-ip-timers", "description": "List all IP change timers", "expectedOutput": "Table showing all instances with their IP change intervals" }, { "command": "sudo tor-switch remove-ip-timer browsing", "description": "Remove timer for instance", "expectedOutput": "IP change timer removed" }, { "command": "sudo tor-switch stop-auto-ip-change", "description": "Stop auto IP change", "expectedOutput": "Automatic IP change stopped" }, { "command": "sudo tor-switch update-ip-all-timer 15m", "description": "Set timer for all instances", "expectedOutput": "IP change timer set for all instances", "notes": "Synchronizes IP rotation across instances" }, { "command": "sudo tor-switch remove-ip-all-timer", "description": "Remove all IP change timers", "expectedOutput": "All IP timers removed", "notes": "Removes all automatic IP rotation timers from all instances" }, { "command": "tor-switch list-auto-ip-change", "description": "List automatic IP change settings", "expectedOutput": "Auto IP change configurations for all instances" } ], "id": "09_timer_and_automation", "title": "Timer Management and Automation" }, { "description": "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.", "examples": [ { "command": "sudo tor-switch start-tor-dns-iptables", "description": "Start Tor DNS listener with iptables", "expectedOutput": "Tor DNS service started with iptables rules", "notes": "Sets up Tor DNS listener service on port 9053. AUTH REQUIRED: run `sudo online-auth authenticate` first." }, { "command": "sudo tor-switch stop-tor-dns-iptables", "description": "Stop Tor DNS routing", "expectedOutput": "Tor DNS iptables rules removed", "notes": "Emergency/recovery exempt: works without auth." }, { "command": "sudo tor-switch torrify-system-dns", "description": "Route all DNS through Tor", "expectedOutput": "System DNS queries routed through Tor", "notes": "Auto-detects and uses whichever firewall backend is active. AUTH REQUIRED: run `sudo online-auth authenticate` first. DESTRUCTIVE: applies immediately with no confirmation prompt." }, { "command": "sudo tor-switch start-tor-dns-nftables", "description": "Start Tor DNS listener with nftables", "expectedOutput": "Tor DNS service started with nftables rules", "notes": "Sets up Tor DNS listener service on port 9053. AUTH REQUIRED: run `sudo online-auth authenticate` first." }, { "command": "sudo tor-switch stop-tor-dns-nftables", "description": "Stop Tor DNS (nftables)", "expectedOutput": "Tor DNS nftables rules removed", "notes": "Emergency/recovery exempt: works without auth." }, { "command": "sudo tor-switch torrify-system-iptables-dns", "description": "Route DNS through Tor using iptables", "expectedOutput": "DNS routing through Tor enabled (iptables)", "notes": "Redirects all system DNS queries to the Tor DNS listener. AUTH REQUIRED: run `sudo online-auth authenticate` first. DESTRUCTIVE: applies immediately with no confirmation prompt." }, { "command": "sudo tor-switch torrify-system-nftables-dns", "description": "Route DNS through Tor using nftables", "expectedOutput": "DNS routing through Tor enabled (nftables)", "notes": "Redirects all system DNS queries to the Tor DNS listener. AUTH REQUIRED: run `sudo online-auth authenticate` first. DESTRUCTIVE: applies immediately with no confirmation prompt." } ], "id": "10_dns_management", "title": "DNS Management" }, { "description": "Test and verify DNS routing through Tor", "examples": [ { "command": "tor-switch verify-tor-dns", "description": "Verify Tor DNS resolution of .onion addresses", "expectedOutput": "DNS verification successful! (tests both direct and port methods)", "notes": "Resolves .onion addresses to verify DNS goes through Tor" }, { "command": "tor-switch verify-tor-dns-all", "description": "Verify DNS resolution for all Tor instances", "expectedOutput": "DNS verification results for each instance", "notes": "Tests .onion resolution for all configured Tor instances" }, { "command": "tor-switch verify-tor-dns-direct", "description": "Verify .onion resolution using system DNS", "expectedOutput": "Onion addresses can be resolved directly", "notes": "Uses system resolver to test .onion domain resolution" }, { "command": "tor-switch verify-tor-dns-port", "description": "Verify .onion resolution via Tor DNS port", "expectedOutput": "Onion addresses can be resolved using DNS port", "notes": "Uses instance's DNS port to test .onion resolution" }, { "command": "tor-switch verify-tor-dns --json", "description": "Verify Tor DNS and capture the result for a script", "expectedOutput": "JSON envelope with per-method resolution results", "notes": "The verify-tor-dns* commands take no arguments: they always test the currently active Tor DNS listener. To check one specific instance, make it the default first with set-default-instance, or use verify-tor-dns-all to cover every instance." } ], "id": "11_dns_verification", "title": "DNS Verification" }, { "description": "Manage iptables and nftables firewall rules. The flush-* and torrify/detorrify commands change the live firewall the moment you run them, with no confirmation prompt. A --force (alias --yes) flag is still accepted for backwards compatibility, but it is NOT a confirmation gate and passing it changes nothing.", "examples": [ { "command": "sudo tor-switch flush-iptables", "description": "Flush iptables rules", "expectedOutput": "All iptables rules cleared", "notes": "DESTRUCTIVE, NOT REVERSIBLE: drops every iptables rule and policy, including any Tor torrification rules protecting you right now. Your traffic leaves the machine unprotected until you re-apply a ruleset. There is no confirmation prompt." }, { "command": "tor-switch list-iptables", "description": "List current iptables rules", "expectedOutput": "Display of all active iptables rules" }, { "command": "tor-switch which-is-active", "description": "Check active firewall", "expectedOutput": "Shows whether iptables or nftables is active" }, { "command": "sudo tor-switch flush-nftables", "description": "Flush nftables rules", "expectedOutput": "All nftables rules cleared", "notes": "DESTRUCTIVE, NOT REVERSIBLE: drops every nftables rule, including any Tor torrification rules protecting you right now. Your traffic leaves the machine unprotected until you re-apply a ruleset. There is no confirmation prompt." }, { "command": "tor-switch list-nftables", "description": "List current nftables rules", "expectedOutput": "Display of all active nftables rules" }, { "command": "tor-switch list-iptables-nat", "description": "List NAT rules", "expectedOutput": "Display of all NAT table rules", "notes": "Shows network address translation rules" }, { "command": "sudo tor-switch boot-restore-torrified --json", "description": "Rebuild the Tor instance pool at boot when the persisted firewall is already torrified", "expectedOutput": "JSON envelope reporting the instances restarted, or a no-op result when the saved firewall is not torrified", "notes": "You normally never run this by hand: kodachi-tor-pool-boot.service runs it at every boot. It is auth-exempt so it still works before online-auth is up. On a non-torrified system it does nothing." } ], "id": "12_firewall_operations", "title": "Firewall Operations" }, { "description": "Manage Tor configuration files and validation", "examples": [ { "command": "tor-switch validate-torrc", "description": "Validate torrc configuration", "expectedOutput": "Configuration validation results", "notes": "Checks syntax without starting Tor" }, { "command": "sudo tor-switch reload-tor-config", "description": "Reload configuration", "expectedOutput": "Configuration reloaded successfully", "notes": "Applies changes without restart" }, { "command": "sudo tor-switch generate-new-tor-password", "description": "Generate new control password", "expectedOutput": "New control password generated" }, { "command": "sudo tor-switch clean-torrc-custom", "description": "Clean custom configuration", "expectedOutput": "Custom torrc entries removed" }, { "command": "sudo tor-switch clean-torrc-custom-all", "description": "Clean all custom configurations", "expectedOutput": "Custom entries removed from all instances" }, { "command": "sudo tor-switch reload-tor-config-all", "description": "Reload all configurations", "expectedOutput": "All instance configurations reloaded" }, { "command": "sudo tor-switch generate-new-tor-password-all", "description": "Generate passwords for all instances", "expectedOutput": "New control passwords generated for all" }, { "command": "tor-switch get-tor-custom-status", "description": "Get custom configuration status", "expectedOutput": "Status of custom configurations" } ], "id": "13_configuration_management", "title": "Configuration Management" }, { "description": "Backup and restore Tor instance configurations", "examples": [ { "command": "sudo tor-switch backup-config", "description": "Backup configuration", "expectedOutput": "Configuration backed up with timestamp (default instance)" }, { "command": "tor-switch list-backups", "description": "List available backups", "expectedOutput": "Table showing all backup files" }, { "command": "sudo tor-switch restore-config backup-2025-01-28", "description": "Restore from backup", "expectedOutput": "Configuration restored", "notes": "Restores configuration and restarts instances" }, { "command": "sudo tor-switch backup-config-all", "description": "Backup all configurations", "expectedOutput": "All instance configurations backed up" }, { "command": "sudo tor-switch restore-config-all backup-2025-01-28", "description": "Restore all from backup", "expectedOutput": "All configurations restored from backup", "notes": "Restores complete multi-instance setup" } ], "id": "14_backup_and_restore", "title": "Backup and Restore" }, { "description": "WARNING, TROUBLESHOOTING ONLY: these commands edit the shared system Tor daemon (/etc/tor/torrc), not a Kodachi instance. Changing main Tor affects every application that talks to the system Tor and can break instance routing. For all normal work use the Kodachi instance commands instead. Add --maintor to target the system daemon explicitly.", "examples": [ { "command": "tor-switch validate-torrc-main --maintor", "description": "Validate main Tor configuration", "expectedOutput": "Main Tor configuration validated", "notes": "Validates /etc/tor/torrc syntax and settings" }, { "command": "tor-switch read-main-tor-config", "description": "Display main Tor configuration", "expectedOutput": "Main Tor configuration displayed", "notes": "Shows ports, exit/exclude nodes, and security settings" }, { "command": "sudo tor-switch backup-main-tor-config", "description": "Backup main Tor configuration", "expectedOutput": "Main Tor configuration backed up", "notes": "Creates timestamped backup in backups/main-tor/" }, { "command": "sudo tor-switch restore-main-tor-config torrc-main-20240115-143022.backup", "description": "Restore main Tor configuration", "expectedOutput": "Main Tor configuration restored", "notes": "Current config is backed up before restoring" }, { "command": "sudo tor-switch set-exit-node-main US --maintor", "description": "Set US exit node for main Tor", "expectedOutput": "Exit node set to US for main Tor", "notes": "Forces traffic to exit through United States" }, { "command": "sudo tor-switch clear-exit-node-main --maintor", "description": "Clear exit node restrictions", "expectedOutput": "Exit node restrictions cleared for main Tor", "notes": "Allows Tor to choose any exit country" }, { "command": "sudo tor-switch set-exclude-node-main CN,RU --maintor", "description": "Exclude countries from circuits", "expectedOutput": "Excluded nodes set for main Tor", "notes": "Prevents routing through specified countries" }, { "command": "sudo tor-switch clear-exclude-node-main --maintor", "description": "Clear excluded countries", "expectedOutput": "Exclude restrictions cleared for main Tor", "notes": "Removes all country exclusions" }, { "command": "tor-switch list-exit-exclude-main", "description": "Show exit/exclude settings", "expectedOutput": "Exit/exclude settings displayed", "notes": "Displays current geographic routing rules" }, { "command": "sudo tor-switch reload-main-tor", "description": "Reload main Tor configuration", "expectedOutput": "Main Tor configuration reloaded", "notes": "Sends SIGHUP signal to apply config changes" }, { "command": "tor-switch status-main-tor", "description": "Get main Tor daemon status", "expectedOutput": "Main Tor status displayed", "notes": "Shows systemctl status and port information" }, { "command": "tor-switch verify-main-tor-dns", "description": "Verify DNS routing through Tor", "expectedOutput": "DNS routing through main Tor verified", "notes": "Tests DNS resolution via tor-resolve" }, { "command": "sudo tor-switch new-circuit-main-tor", "description": "Request new Tor circuit", "expectedOutput": "New circuit requested for main Tor", "notes": "Gets new IP by building fresh circuit" }, { "command": "tor-switch check-main-tor-security", "description": "Security audit main Tor", "expectedOutput": "Security audit completed", "notes": "Checks for security misconfigurations" }, { "command": "tor-switch main-tor-bandwidth", "description": "Show Tor bandwidth usage", "expectedOutput": "Bandwidth usage displayed", "notes": "Displays active SOCKS connections count" }, { "command": "tor-switch main-tor-connections", "description": "List active Tor connections", "expectedOutput": "Active connections listed", "notes": "Shows established connections on SOCKS port" }, { "command": "tor-switch main-tor-logs", "description": "Display recent Tor logs", "expectedOutput": "Recent logs displayed", "notes": "Shows last 50 lines from Tor log or journald" }, { "command": "tor-switch validate-torrc-main --maintor --json", "description": "Validate with JSON output", "expectedOutput": "JSON validation output returned", "notes": "Machine-readable output for scripting" } ], "id": "15_main_tor_management", "title": "Main Tor Management (TROUBLESHOOTING ONLY)" }, { "description": "Complete workflow examples for common use cases", "examples": [ { "command": "# Privacy-focused browsing setup\nsudo tor-switch create-multiple-instances 3 privacy\nsudo tor-switch set-exclude-node 5eyes --instance privacy-1\nsudo tor-switch set-exclude-node 9eyes --instance privacy-2\nsudo tor-switch set-exclude-node 14eyes --instance privacy-3\nsudo tor-switch update-ip-timer privacy-1 5m\nsudo tor-switch update-ip-timer privacy-2 10m\nsudo tor-switch update-ip-timer privacy-3 15m", "description": "Complete privacy-focused setup", "expectedOutput": "Privacy-optimized Tor configuration active", "notes": "Avoids surveillance alliance countries with rapid rotation" }, { "command": "# Regional distribution setup\nsudo tor-switch create-instance europe\nsudo tor-switch create-instance asia\nsudo tor-switch create-instance americas\nsudo tor-switch set-exit-node europe --instance europe\nsudo tor-switch set-exit-node asia --instance asia\nsudo tor-switch set-exit-node north-america --instance americas", "description": "Geographic distribution setup", "expectedOutput": "Regional Tor instances configured", "notes": "Access region-specific content simultaneously" }, { "command": "# High-availability setup\nsudo tor-switch create-multiple-instances 5 ha\nsudo tor-switch set-load-balancing-mode weighted\nsudo tor-switch set-instance-weight ha-1 30\nsudo tor-switch set-instance-weight ha-2 25\nsudo tor-switch set-instance-weight ha-3 20\nsudo tor-switch set-instance-weight ha-4 15\nsudo tor-switch set-instance-weight ha-5 10\nsudo tor-switch torrify-system-iptables-load-balanced", "description": "High-availability load balanced setup", "expectedOutput": "HA configuration with weighted distribution active", "notes": "Redundant instances with priority-based traffic distribution" }, { "command": "# Research and testing setup\nsudo tor-switch create-instance research\nsudo tor-switch create-instance testing\nsudo tor-switch set-exit-node random-low-volume --instance research\nsudo tor-switch set-exit-node high-volume --instance testing\nsudo tor-switch update-ip-timer research 2m\ntor-switch verify-tor-dns-all", "description": "Research and testing environment", "expectedOutput": "Research/testing instances configured", "notes": "Separate instances for different testing scenarios. verify-tor-dns takes no --instance flag, so verify-tor-dns-all is used to cover both instances at once." }, { "command": "# Performance-optimized setup\nsudo tor-switch create-multiple-instances 10 perf\nsudo tor-switch set-load-balancing-mode round-robin\nsudo tor-switch generate-haproxy-config\nsudo tor-switch haproxy-start\ntor-switch haproxy-status", "description": "Maximum performance configuration", "expectedOutput": "Performance-optimized setup with HAProxy active", "notes": "10 instances with HAProxy for maximum throughput" }, { "command": "# Clean slate reset\nsudo tor-switch stop-all-instances\nsudo tor-switch cleanup\nsudo tor-switch flush-iptables\nsudo tor-switch restart-tor\ntor-switch check-tor", "description": "Complete reset to default state", "expectedOutput": "System reset to clean Tor configuration", "notes": "Removes all custom configurations and instances" }, { "command": "# Monitoring and diagnostics\ntor-switch tor-status-all\ntor-switch list-instances\ntor-switch list-ip-timers\ntor-switch display-load-balancing-config\ntor-switch haproxy-status", "description": "Complete system status check", "expectedOutput": "Full diagnostic report displayed", "notes": "Comprehensive view of all Tor configurations" } ], "id": "16_advanced_workflows", "title": "Advanced Workflows" }, { "description": "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.", "examples": [ { "command": "sudo tor-switch set-bridges --bridge 'obfs4 192.0.2.1:443 AABBCCDDEEFF00112233445566778899AABBCCDD cert=AAABBBCCC+longbase64string== iat-mode=0'", "description": "Store a single obfs4 bridge and activate it for all instances", "expectedOutput": "Bridges saved (1 lines). obfs4proxy: /usr/bin/obfs4proxy", "notes": "Requires obfs4proxy installed (apt install obfs4proxy). All instances are restarted automatically." }, { "command": "sudo tor-switch set-bridges --from-file /tmp/bridges.txt", "description": "Load multiple bridge lines from a file (one per line, # comments ignored)", "expectedOutput": "Bridges saved. All instances restarted with bridge configuration.", "notes": "Recommended for the dashboard: write bridge lines to a temp file then pass --from-file." }, { "command": "tor-switch list-bridges --json", "description": "Show stored bridge config and obfs4proxy detection result as JSON", "expectedOutput": "{\"enabled\":true,\"transport\":\"obfs4\",\"bridges_count\":2,...}", "notes": "Read-only, no sudo required." }, { "command": "tor-switch test-bridges --json", "description": "Validate stored bridge lines and check obfs4proxy path without making changes", "expectedOutput": "{\"all_valid\":true,\"obfs4proxy_found\":true,...}", "notes": "Read-only, no sudo required. Use before enable-bridges to confirm lines are well-formed." }, { "command": "sudo tor-switch disable-bridges", "description": "Revert to direct Tor (strip bridge block, restart all instances)", "expectedOutput": "Bridges disabled. Tor instances reverted to direct connections.", "notes": "Preserves stored bridge lines so you can re-enable later." }, { "command": "sudo tor-switch enable-bridges", "description": "Re-activate previously stored bridges for all instances", "expectedOutput": "Bridges enabled. N bridges active.", "notes": "Requires at least one bridge stored via set-bridges." }, { "command": "sudo tor-switch clear-bridges", "description": "Remove all stored bridges and revert all instances to direct Tor", "expectedOutput": "All bridges cleared. Tor instances using direct connections.", "notes": "Permanently removes bridges.json entries. Use disable-bridges instead to keep them for later." }, { "command": "sudo tor-switch set-bridge-mode --mode all", "description": "Use all stored bridges simultaneously (default behavior)", "expectedOutput": "Bridge selection mode set to 'all' (active_count=1, N bridges stored).", "notes": "Re-applies the bridge config and restarts all instances." }, { "command": "sudo tor-switch set-bridge-mode --mode random --count 2", "description": "Randomly pick 2 bridges from the stored list each time bridges are applied", "expectedOutput": "Bridge selection mode set to 'random' (active_count=2, N bridges stored).", "notes": "Useful when you have many bridges and want to vary which ones are used." }, { "command": "sudo tor-switch rotate-bridges", "description": "Pick a fresh random subset of bridges and restart all instances", "expectedOutput": "Bridge rotation applied: 1 bridge(s) selected from 5 stored.", "notes": "In 'all' mode this re-applies without changing the active set. In 'random' mode a new subset is picked." }, { "command": "sudo tor-switch bridge-rotate-timer 15m", "description": "Install a cron job that calls rotate-bridges every 15 minutes", "expectedOutput": "Bridge rotation cron installed: every 15 minutes (*/15 * * * *). Use stop-bridge-rotate-timer to remove.", "notes": "Minimum interval is 1 minute. Tagged with KODACHI_BRIDGE_ROTATE in crontab. Only one timer can be active; running again replaces the previous one." }, { "command": "sudo tor-switch stop-bridge-rotate-timer", "description": "Remove the bridge rotation cron job", "expectedOutput": "Bridge rotation cron job removed.", "notes": "Reports cleanly if no timer was installed." } ], "id": "17_bridges", "title": "Bridge Management (obfs4 Pluggable Transport)" }, { "description": "Built-in help and usage examples", "examples": [ { "command": "tor-switch show-help", "description": "Show help information", "expectedOutput": "Full command reference with descriptions", "notes": "Equivalent to -h; read-only, no privileges required" }, { "command": "tor-switch show-examples", "description": "Show usage examples", "expectedOutput": "Categorized example commands with expected output", "notes": "Equivalent to -e; read-only, no privileges required" } ], "id": "18_help", "title": "Help & Documentation" } ], "description": "Usage examples for tor-switch", "name": "tor-switch", "quickReference": [ "tor-switch --help", "tor-switch --version", "tor-switch --info --json", "tor-switch --examples", "tor-switch check-tor", "tor-switch torverify", "tor-switch tor-status", "tor-switch list-instances", "tor-switch which-is-active", "tor-switch verify-tor-dns", "sudo tor-switch start-tor", "sudo tor-switch new-tor-circuit", "sudo tor-switch set-exit-node US", "sudo tor-switch set-exclude-node 14eyes", "sudo tor-switch create-instance secondary", "sudo tor-switch torrify-system-iptables", "sudo tor-switch detorrify-system-iptables", "sudo tor-switch torrify-system-iptables-dns" ] }, "errors": [], "metadata": { "executionTime": 13, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-07-21T01:54:39.683278153Z", "version": "9.8.4 (build 320)", "warnings": [] } } }