routing-switch

System-wide traffic routing through various proxy protocols

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

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

---

File Information

Property	Value
Binary Name	routing-switch
Version	9.0.1
Build Date	2025-10-24T16:44:09.190674367Z
Rust Version	1.70.0
File Size	5.7MB
JSON Data	View Raw JSON

SHA256 Checksum

3019631aef8b985709a66fe847d19d6ea6ef7b3a4030b8285f6a11e27186e489

---

Features

Feature	Description
Feature	System-wide traffic routing through proxy protocols
Feature	Support for OpenVPN, WireGuard, and Dante SOCKS5
Feature	Support for Tor, Shadowsocks, V2Ray, and Xray protocols
Feature	Support for Mieru/Mita and Hysteria2 protocols
Feature	Automatic protocol scoring and selection
Feature	DNS leak prevention with multiple modes
Feature	Metric-based and direct routing options
Feature	External configuration file support
Feature	IPv4/IPv6 dual-stack support
Feature	QR code generation for mobile clients
Feature	Comprehensive logging and monitoring

Global Options

Flag	Description
-h, --help	Print help information
-v, --version	Print version information
-n, --info	Display detailed information
-e, --examples	Show usage examples
--json	Output in JSON format
--json-pretty	Pretty-print JSON output with indentation
--json-human	Enhanced JSON output with improved formatting (like jq)
--verbose	Enable verbose output

Commands

CONNECTION COMMANDS

connect

Connect to a proxy protocol (openvpn, wireguard use native routing; tor uses redsocks; dante, shadowsocks, v2ray, xray-*, mita use tun2socks)

Usage:

routing-switch connect <PROTOCOL> [OPTIONS]

disconnect

Disconnect current proxy connection

Usage:

routing-switch disconnect [OPTIONS]

status

Show current connection status

Usage:

routing-switch status [OPTIONS]

INFORMATION COMMANDS

dns-info

Display current DNS server information

Usage:

routing-switch dns-info [OPTIONS]

list-protocols

List available protocols with scores

Usage:

routing-switch list-protocols [OPTIONS]

TESTING COMMANDS

test-protocol

Test a specific protocol connectivity

Usage:

routing-switch test-protocol <PROTOCOL> [OPTIONS]

benchmark

Benchmark all available protocols

Usage:

routing-switch benchmark [OPTIONS]

CONFIGURATION COMMANDS

export-config

Export protocol configurations to files

Usage:

routing-switch export-config [PROTOCOL] [OPTIONS]

showconfig

Show protocol configuration

Usage:

routing-switch showconfig [PROTOCOL] [OPTIONS]

showconfigurl

Show protocol configuration as URL

Usage:

routing-switch showconfigurl [PROTOCOL] [OPTIONS]

showconfigqr

Show protocol configuration as QR code

Usage:

routing-switch showconfigqr [PROTOCOL] [OPTIONS]

MANAGEMENT COMMANDS

auto-select

Auto-select and connect to best protocol

Usage:

routing-switch auto-select [OPTIONS]

reset

Reset all routing to default state

Usage:

routing-switch reset [OPTIONS]

cleanup

Clean up orphaned processes and resources

Usage:

routing-switch cleanup [OPTIONS]

recover

Recover from partial failure state

Usage:

routing-switch recover [OPTIONS]

MICROSOCKS SERVER MANAGEMENT

microsocks-enable

Enable microsocks SOCKS5 server for other devices

Usage:

routing-switch microsocks-enable -u USERNAME -p PASSWORD [--port PORT]

microsocks-disable

Disable microsocks SOCKS5 server

Usage:

routing-switch microsocks-disable

microsocks-status

Show microsocks server status

Usage:

routing-switch microsocks-status [OPTIONS]

Examples

BASIC CONNECTIONS

Connect to various proxy protocols

Connect via OpenVPN

sudo routing-switch connect openvpn

Expected Output: Successfully connected to OpenVPN server

Note

Requires OpenVPN configuration in auth card

Connect via WireGuard

sudo routing-switch connect wireguard

Expected Output: Successfully connected to WireGuard server

Note

Ultra-fast, modern VPN protocol

Connect via Dante SOCKS5 proxy

sudo routing-switch connect dante

Expected Output: Successfully connected to Dante server

Route ALL traffic through Tor network (uses redsocks)

sudo routing-switch connect tor

Expected Output: Successfully routing traffic through Tor

Note

Maximum anonymity, slower speeds. Uses redsocks for stability instead of tun2socks

Connect via Shadowsocks

sudo routing-switch connect shadowsocks

Expected Output: Successfully connected to Shadowsocks server

Note

Optimized for bypassing censorship

Connect via V2Ray VMess

sudo routing-switch connect v2ray

Expected Output: Successfully connected to V2Ray server

Connect via Xray VLESS TLS

sudo routing-switch connect xray-vless

Expected Output: Successfully connected to Xray VLESS server

Note

Lightweight, fast protocol with TLS

Connect via Xray VLESS Reality

sudo routing-switch connect xray-vless-reality

Expected Output: Successfully connected to Xray VLESS Reality server

Note

Most advanced censorship resistance

Connect via Xray Trojan

sudo routing-switch connect xray-trojan

Expected Output: Successfully connected to Xray Trojan server

Note

Mimics HTTPS traffic

Connect via Xray VMess

sudo routing-switch connect xray-vmess

Expected Output: Successfully connected to Xray VMess server

Connect via Mieru/Mita protocol

sudo routing-switch connect mita

Expected Output: Successfully connected to Mita server

Note

Anti-censorship protocol

Connect via Hysteria2 protocol

sudo routing-switch connect hysteria2

Expected Output: Successfully connected to Hysteria2 server

Note

UDP-based, high-performance anti-censorship protocol

EXTERNAL CONFIGURATION FILES

Connect using external configuration files instead of auth card

Connect using external OpenVPN config file

sudo routing-switch connect openvpn --config /home/user/vpn.ovpn

Expected Output: Successfully connected to OpenVPN server

Note

Supports standard .ovpn configuration files

Connect using external WireGuard config

sudo routing-switch connect wireguard --config /path/to/wg0.conf

Expected Output: Successfully connected to WireGuard server

Note

Uses standard WireGuard .conf format

Connect using Shadowsocks JSON config

sudo routing-switch connect shadowsocks --config /path/to/ss-config.json

Expected Output: Successfully connected to Shadowsocks server

Note

Standard Shadowsocks JSON format with server, port, password, method

Connect using V2Ray JSON config

sudo routing-switch connect v2ray --config /path/to/v2ray-config.json

Expected Output: Successfully connected to V2Ray server

Note

Full V2Ray JSON configuration with inbounds/outbounds

Connect using Xray config file

sudo routing-switch connect xray-vless --config /path/to/xray.json

Expected Output: Successfully connected to Xray VLESS server

Note

Xray JSON config format similar to V2Ray

Force connection with external config

sudo routing-switch connect openvpn --config ./vpn.ovpn --force

Expected Output: Disconnecting existing... Connected via external config

Note

Combines --config with other flags like --force

External config in no-TUN mode

sudo routing-switch connect shadowsocks --config ~/configs/ss.json --no-tun

Expected Output: Shadowsocks SOCKS5 proxy ready at localhost:30000

Note

Use external config for manual proxy setup

IPV4/IPV6 SELECTION

Explicitly choose IPv4 or IPv6 connections

Force IPv4 connection to Dante

sudo routing-switch connect dante --ipv4

Expected Output: Connected via IPv4

Force IPv6 connection to Dante

sudo routing-switch connect dante --ipv6

Expected Output: Connected via IPv6

Note

Requires IPv6 support

Connect Shadowsocks over IPv4

sudo routing-switch connect shadowsocks --ipv4

Expected Output: Shadowsocks connected via IPv4

Connect Tor over IPv6

sudo routing-switch connect tor --ipv6

Expected Output: Tor connected via IPv6

Use IPv6 for Xray VLESS

sudo routing-switch connect xray-vless --ipv6

Expected Output: Xray VLESS connected via IPv6

Connect Hysteria2 over IPv4

sudo routing-switch connect hysteria2 --ipv4

Expected Output: Hysteria2 connected via IPv4

Connect Hysteria2 over IPv6

sudo routing-switch connect hysteria2 --ipv6

Expected Output: Hysteria2 connected via IPv6

Note

Requires IPv6 support

NETWORK PREREQUISITES

Check and manage network prerequisites for VPN connections

Check and fix network prerequisites

sudo routing-switch check-prerequisites

Expected Output: ✓ IPv4 forwarding: Already enabled (correct) ✗→✓ NAT MASQUERADE: Fixed

Note

Fixes only what's wrong, preserves correct settings

Check prerequisites for IPv6 connections

sudo routing-switch check-prerequisites --ipv6

Expected Output: ✓ IPv6 forwarding: Enabled

Note

Only enables IPv6 if system supports it

Get prerequisites status in JSON format

sudo routing-switch check-prerequisites --json

Expected Output: {"prerequisites": {"checks": [...], "ready": true}}

Connect with automatic prerequisites check

sudo routing-switch connect shadowsocks

Expected Output: Checking network prerequisites... ✓ All checks passed

Connecting to shadowsocks...

Note

Prerequisites are checked by default

Connect without prerequisites check

sudo routing-switch connect shadowsocks --skip-prerequisites

Expected Output: Connecting to shadowsocks...

Note

Skips prerequisites for backward compatibility

Force reconnection with prerequisites check

sudo routing-switch connect wireguard --force

Expected Output: Checking network prerequisites... Forcing new connection...

Note

Prerequisites persist after disconnect for other VPN tools

CONNECTION STATUS

Check and monitor connection status

Show current connection status

routing-switch status

Expected Output: Protocol: wireguard, Status: Connected

Get status in JSON format

routing-switch status --json

Expected Output: {"protocol": "wireguard", "status": "connected"}

Pretty-printed JSON status

routing-switch status --json-pretty

Expected Output: Formatted JSON with connection details

Human-readable JSON status

routing-switch status --json-human

Expected Output: Enhanced JSON output with descriptions

DNS MODES AND SECURITY

Control DNS routing for security and compatibility (DEFAULT: auto mode)

DEFAULT: Auto mode (no special DNS routing)

sudo routing-switch connect wireguard

Expected Output: DNS handled naturally through tunnel

Note

DEFAULT safe mode - DNS flows through tunnel like all traffic. Note: May not work with all protocols

Hybrid mode: VPN server DNS bypasses tunnel

sudo routing-switch connect wireguard --dns-mode hybrid

Expected Output: Using hybrid DNS mode: VPN server DNS bypasses, others through tunnel

Note

⚠️ WARNING: May cause internet loss! Use 'sudo routing-switch recover' to restore connectivity. Good balance of security and reliability for home/office use when you need LAN access

Strict mode: ALL DNS through tunnel

sudo routing-switch connect wireguard --dns-mode strict

Expected Output: Using strict DNS mode: Maximum security

Note

Most secure, may fail if VPN server uses hostname

System mode: DNS bypasses tunnel

sudo routing-switch connect wireguard --dns-mode system

Expected Output: WARNING: System DNS mode - DNS queries will leak!

Note

⚠️ NOT SECURE - DNS leaks! Use only for debugging

Exclude private networks from VPN

sudo routing-switch connect wireguard --exclude-private

Expected Output: Private networks will bypass VPN tunnel

Note

Keep LAN access while using VPN

Hybrid DNS with private network exclusion

sudo routing-switch connect wireguard --dns-mode hybrid --exclude-private

Expected Output: Using hybrid DNS mode with local network access

Note

Good for home/office use when you need LAN access

ROUTING MODES - SECURITY vs FAILOVER

Choose between Direct (secure) or Metric (with fallback) routing

DEFAULT: Direct routing mode (MOST SECURE)

sudo routing-switch connect tor

Expected Output: Using DIRECT routing: Traffic goes ONLY through TUN, no fallback

Note

✅ RECOMMENDED - Acts as kill switch, no leaks if VPN fails

Metric routing mode (LESS SECURE, has fallback)

sudo routing-switch connect tor --metric

Expected Output: Using METRIC routing: Original route kept as backup

Note

⚠️ WARNING: Can leak traffic if TUN fails! Use only if you need failover

Direct mode for Shadowsocks (default)

sudo routing-switch connect shadowsocks

Expected Output: Direct routing: No internet if Shadowsocks stops

Note

Perfect privacy - connection drops if proxy fails

Metric mode for corporate VPN scenarios

sudo routing-switch connect dante --metric

Expected Output: Metric routing: Fallback to original connection if VPN drops

Note

Use for work VPNs where you need automatic failover

Metric mode with LAN access preserved

sudo routing-switch connect xray-vless --metric --exclude-private

Expected Output: Failover routing with local network bypass

Note

Corporate setup: VPN with failover + LAN access

DISCONNECTION

Disconnect and restore normal routing

Disconnect current proxy

sudo routing-switch disconnect

Expected Output: Successfully disconnected

Force disconnect even if issues

sudo routing-switch disconnect --force

Expected Output: Force disconnected

Note

Kills all processes forcefully

Disconnect and clean all firewall rules

sudo routing-switch disconnect --clean-firewall

Expected Output: Disconnected and firewall rules cleaned

Note

Use when network is stuck after disconnect due to lingering iptables rules

Force disconnect with complete firewall cleanup

sudo routing-switch disconnect --force --clean-firewall

Expected Output: Force disconnected, all firewall rules flushed

Note

Emergency recovery - resets all iptables rules (preserves Docker/KVM chains)

Disconnect with JSON output

sudo routing-switch disconnect --json

Expected Output: {"status": "disconnected"}

FORCE FLAG & PROTOCOL COMPATIBILITY

Understanding --force behavior and which protocols can layer together

Creates LAYERED connection: Tor-over-WireGuard ✓

sudo routing-switch connect wireguard
    $ sudo routing-switch connect tor --force

Expected Output: → Traffic flows through BOTH protocols (double encryption) → WireGuard's wg0 interface remains active → Tor's iptables rules redirect traffic on top

Note

LAYERED: Both protocols remain active. Traffic: App → Tor (redsocks) → WireGuard → Internet

Creates LAYERED connection: Tor-over-OpenVPN ✓

sudo routing-switch connect openvpn
    $ sudo routing-switch connect tor --force

Expected Output: → Traffic: Your App → Tor (redsocks) → OpenVPN (tun0) → Internet → Both protocols active simultaneously

Note

Works because Tor uses iptables NAT, no interface conflict with OpenVPN's tun0

FAILS: Interface conflict ✗

sudo routing-switch connect shadowsocks
    $ sudo routing-switch connect dante --force

Expected Output: → ERROR: Both protocols need the same tun_routing interface → Cannot have two tun2socks instances → Must disconnect first

Note

All tun2socks protocols (shadowsocks, dante, v2ray, xray-*, mita, hysteria2) share the same TUN device

May create complex routing (untested)

sudo routing-switch connect shadowsocks
    $ sudo routing-switch connect tor --force

Expected Output: → Shadowsocks tun_routing remains → Tor adds iptables rules on top → Behavior depends on routing priorities

Note

Different architectures (tun2socks vs iptables) - may work but not recommended

Understanding protocol architectures

# PROTOCOL TYPES AND COMPATIBILITY:

Expected Output: → Native VPNs (own interfaces): openvpn (tun0), wireguard (wg0) → Redsocks (iptables NAT): tor → Tun2socks (shared tun_routing): shadowsocks, dante, v2ray, xray-vless, xray-vless-reality, xray-trojan, xray-vmess, mita, hysteria2

Note

Compatible: Native+Tor. Incompatible: Any two tun2socks protocols

Best practices for using --force

# RECOMMENDED LAYERING:

Expected Output: → ✓ WireGuard/OpenVPN first, then Tor --force for double VPN → ✗ Never layer two tun2socks protocols → Test connectivity after layering

Note

--force allows connection despite existing protocol, but compatibility depends on architecture

DNS INFORMATION

Check DNS configuration

Show current DNS servers

routing-switch dns-info

Expected Output: IPv4: :53, IPv6: []:53

DNS info in JSON format

routing-switch dns-info --json

Expected Output: {"ipv4": {"host": "", "port": 53}}

TOR DNS INFORMATION

Check Tor DNS and SOCKS configuration

Show Tor DNS and SOCKS endpoints

routing-switch tor-dns-info

Expected Output: DNS: dns://:9054#Tor-DNS

Note

Resolves both regular and .onion domains

Tor DNS info in JSON format

routing-switch tor-dns-info --json

Expected Output: {"ipv4": {"dns_url": "dns://...", "socks_url": "socks5://..."}}

VPS SERVER INFORMATION

Display VPS server details and statistics

Show basic VPS information

routing-switch vps-info

Expected Output: Hostname: cluster-xxx, IPv4:

Show detailed VPS stats

routing-switch vps-info --detailed

Expected Output: CPU Load, Memory Usage, Uptime, Network Connections

Note

Includes CPU load, memory, uptime, and connection stats

VPS info in JSON format

routing-switch vps-info --json

Expected Output: {"hostname": "...", "cpu_load": {...}, "memory": {...}}

PROTOCOL LISTING

List available protocols with scores

List all available protocols

routing-switch list-protocols

Expected Output: WireGuard (Score: 96.5), OpenVPN (Score: 94.0)...

Protocol list in JSON

routing-switch list-protocols --json

Expected Output: [{"name": "wireguard", "score": 96.5}]

Show only available protocols

routing-switch list-protocols --available-only

Expected Output: Available: WireGuard, Tor, Shadowsocks

Note

Based on auth card

Sort by security score

routing-switch list-protocols --sort-by-security

Expected Output: 1. WireGuard (98.0), 2. OpenVPN (95.0)...

Sort by speed score

routing-switch list-protocols --sort-by-speed

Expected Output: 1. WireGuard (99.0), 2. Shadowsocks (85.0)...

AUTO-SELECTION

Automatically select best protocol

Auto-select best protocol

sudo routing-switch auto-select

Expected Output: Selected WireGuard (best overall score)

Auto-select with minimum security

sudo routing-switch auto-select --min-security 90

Expected Output: Selected OpenVPN (security: 95.0)

Prioritize speed in selection

sudo routing-switch auto-select --prefer-speed

Expected Output: Selected WireGuard (fastest protocol)

Auto-select with JSON output

sudo routing-switch auto-select --json

Expected Output: {"selected": "wireguard", "reason": "best_score"}

PORT USAGE INFORMATION

Local SOCKS5 port allocation reference for protocols

Each protocol uses specific port ranges

# Port allocation for tun2socks-based protocols

Expected Output: When connecting, protocols allocate ports automatically:

Shadowsocks: 30000-30004 V2Ray: 30005-30009 Xray VMess: 30010-30014 Xray VLESS: 30015-30019 VLESS Reality: 30020-30024 Xray Trojan: 30025-30029 Mieru/Mita: 30030-30034 Tor: 30035-30039 Dante: 30040-30044 Hysteria2: 30045-30049

Note

High port numbers (30000+) avoid conflicts with system services

How traffic flows through local SOCKS5 proxy

# Traffic flow for SOCKS5-based protocols

Expected Output: Application → tun_routing interface → tun2socks → localhost:PORT → proxy_client → remote_server

Note

The local SOCKS5 proxy listens on 127.0.0.1:PORT where PORT is from the allocated range

Check which local ports are in use

ss -tlnp | grep 300

Expected Output: tcp LISTEN 0 128 127.0.0.1:30000 : users:(("ss-local",pid=12345,fd=3))

Note

Use this command to verify which proxy ports are active

Native VPN protocols use different approaches

# WireGuard and OpenVPN port usage

Expected Output: WireGuard: Uses UDP port specified in config (typically 51820) OpenVPN: Uses TCP/UDP port specified in config (typically 1194)

Note

These protocols don't use tun2socks or local SOCKS5 proxies - they connect directly

JSON OUTPUT FORMATS

Different JSON output options

Compact JSON output

routing-switch status --json

Expected Output: {"status":"connected","protocol":"tor"}

Pretty-printed JSON

routing-switch status --json-pretty

Expected Output: { "status": "connected", "protocol": "tor" }

Human-enhanced JSON

routing-switch status --json-human

Expected Output: JSON with descriptions and metadata

Pretty JSON protocol list

routing-switch list-protocols --json --json-pretty

Expected Output: Formatted JSON array of protocols

BENCHMARKING

Test protocol performance

Benchmark all protocols

routing-switch benchmark

Expected Output: WireGuard: 95Mbps, OpenVPN: 75Mbps...

Note

Tests actual throughput

Benchmark specific protocol

routing-switch benchmark wireguard

Expected Output: WireGuard: Download: 95Mbps, Upload: 90Mbps

Extended benchmark test

routing-switch benchmark --duration 60

Expected Output: 60-second benchmark results...

Benchmark results in JSON

routing-switch benchmark --json

Expected Output: {"wireguard": {"download": 95.5, "upload": 90.2}}

TESTING PROTOCOLS

Test protocol connectivity without routing

Test Tor connectivity

routing-switch test-protocol tor

Expected Output: Tor: SOCKS5 proxy responding at 127.0.0.1:9050

Note

Doesn't change routing

Extended protocol test

routing-switch test-protocol shadowsocks --extended

Expected Output: Shadowsocks: Connected, Latency: 45ms, Throughput: OK

Test all available protocols

routing-switch test-protocol all

Expected Output: Testing: Tor [OK], Shadowsocks [OK], V2Ray [FAIL]...

Test with JSON output

routing-switch test-protocol wireguard --json

Expected Output: {"protocol": "wireguard", "status": "ok", "latency": 12}

NO-TUN MODE (MANUAL PROXY)

Run proxy without TUN interface for manual configuration

Start Shadowsocks SOCKS5 proxy without TUN

sudo routing-switch connect shadowsocks --no-tun

Expected Output: Shadowsocks SOCKS5 proxy ready at localhost:30000

Note

Configure browser/app manually with localhost:30000

Connect to Dante SOCKS5 without routing traffic

sudo routing-switch connect dante --no-tun

Expected Output: Dante proxy: host:port, username, password

Note

Direct connection to remote Dante server

Use Tor SOCKS5 proxy without system routing

sudo routing-switch connect tor --no-tun

Expected Output: Tor SOCKS5 proxy: 127.0.0.1:9050

Note

Tor must be running. Apps connect to port 9050

V2Ray proxy in manual mode with JSON output

sudo routing-switch connect v2ray --no-tun --json

Expected Output: {"local_proxy_address":"127.0.0.1","local_proxy_port":30005}

Note

V2Ray client runs, no system routing

Xray VLESS proxy for manual configuration

sudo routing-switch connect xray-vless --no-tun

Expected Output: Xray SOCKS5 proxy ready at localhost:30015

Firefox proxy settings example

# Configure Firefox with no-TUN proxy:

Expected Output: Settings → Network → Manual proxy → SOCKS5: localhost, Port: 30000

Note

Each protocol uses different port ranges

Chrome command line example

# Chrome with no-TUN proxy:

Expected Output: chrome --proxy-server="socks5://localhost:30000"

Stop the proxy (works for both TUN and no-TUN modes)

sudo routing-switch disconnect

Expected Output: Proxy stopped

CONFIGURATION EXPORT AND DISPLAY

Export and display protocol configurations

Export all configurations to default location

routing-switch export-config

Expected Output: Exported 9 configuration(s) to ./results/configs/

Note

Creates timestamped config files

Export specific protocol configuration

routing-switch export-config wireguard

Expected Output: Exported 1 configuration(s) to ./results/configs/ - wireguard: wireguard_20250817_143022.conf

Export all configs to custom path

routing-switch export-config all --path /tmp/vpn-configs/

Expected Output: Exported 9 configuration(s) to /tmp/vpn-configs/

Note

Creates directory if it doesn't exist

Export with credentials included

routing-switch export-config shadowsocks --include-credentials

Expected Output: Exported 1 configuration(s) to ./results/configs/

Note

⚠️ WARNING: Contains sensitive passwords

Export with JSON output showing results

routing-switch export-config --json

Expected Output: {"exported_count": 9, "export_directory": "./results/configs/", "files": [...]}

Display WireGuard configuration

routing-switch showconfig wireguard

Expected Output: Protocol Configurations:

Note

Masks sensitive data by default

Show all protocol configs in pretty JSON

routing-switch showconfig all --json-pretty

Expected Output: Formatted JSON with all available protocol configurations

Show config with passwords hidden

routing-switch showconfig dante --mask-sensitive

Expected Output: {"username": "dante_user", "password": "REDACTED"}

Note

Safe for sharing/logging

Get Shadowsocks connection URL

routing-switch showconfigurl shadowsocks

Expected Output: ss://Y2hhY2hhMjAtaWV0Zi1wb2x5MTMwNTp6TDQ4cVYx...@:8388#Shadowsocks-IPv4

Note

URL can be imported into mobile apps

Get SOCKS5 URLs in JSON format

routing-switch showconfigurl dante --json

Expected Output: {"ipv4": "socks5://user:pass@:1080", "ipv6": "socks5://user:pass@[]:1080"}

Get URLs for all available protocols

routing-switch showconfigurl all

Expected Output: Protocol Connection URLs:

shadowsocks: ipv4: ss://...

dante: ipv4: socks5://...

Generate QR code for WireGuard config

routing-switch showconfigqr wireguard

Expected Output: [QR Code ASCII Art]

URL: wireguard://base64_encoded_config

Note

Scan with WireGuard mobile app

Generate IPv4 QR code for Shadowsocks (default)

routing-switch showconfigqr shadowsocks

Expected Output: [QR Code ASCII Art]

URL: ss://...

Note

Shows IPv4 QR code by default for dual-stack protocols

Generate IPv6 QR code for Shadowsocks

routing-switch showconfigqr shadowsocks --ipv6

Expected Output: [QR Code ASCII Art]

URL: ss://...

Note

Use --ipv6 flag to show IPv6 QR for dual-stack protocols

Generate QR without validation (faster)

routing-switch showconfigqr shadowsocks --skip-validation

Expected Output: [QR Code ASCII Art]

⚠ Validation skipped

Note

Skips automatic QR validation for debugging

Generate all QR codes with strict validation

routing-switch showconfigqr all --strict-validation

Expected Output: ✓ Shadowsocks QR validated ✓ WireGuard QR validated...

Note

Fails if any QR code validation fails

Get QR data in JSON format

routing-switch showconfigqr dante --json

Expected Output: {"dante": {"url": "socks5://...", "qr_available": true}}

Note

JSON includes the URL for QR generation

Generate QR code and save as PNG file

routing-switch showconfigqr shadowsocks --save-files

Expected Output: [QR Code ASCII Art]

✓ IPv4 QR code files saved to ./results/qr-codes/

Note

Saves clean PNG file: shadowsocks_ipv4.png

Generate IPv6 QR code and save as PNG file

routing-switch showconfigqr shadowsocks --ipv6 --save-files

Expected Output: [QR Code ASCII Art]

✓ IPv6 QR code files saved to ./results/qr-codes/

Note

Saves clean PNG file: shadowsocks_ipv6.png

Generate both IPv4 and IPv6 QR codes

routing-switch showconfigqr shadowsocks --ipv4 --ipv6 --save-files

Expected Output: [QR Code ASCII Art]

✓ IPv4 and IPv6 QR code files saved to ./results/qr-codes/

Note

Saves both shadowsocks_ipv4.png and shadowsocks_ipv6.png

Generate all QR codes with pretty JSON output

routing-switch showconfigqr all --save-files --json-pretty

Expected Output: Pretty-formatted JSON with QR data and file paths

Note

Creates clean PNG files for all available protocols, supports all JSON formats

Save QR file with human-enhanced JSON output

routing-switch showconfigqr wireguard --save-files --json-human

Expected Output: {"qr_code": "base64data...", "saved_file_path": "./results/qr-codes/wireguard.png"}

Note

VPN protocols use single filename (no IP version suffix)

QR CODE VALIDATION

Validate QR codes against auth card

Validate QR code from image file (NEW: direct filename)

routing-switch validate-qr shadowsocks_ipv4.png

Expected Output: ✓ QR valid: Shadowsocks (confidence: 98.5%)

Note

Smart detection: automatically finds file in current dir or results/qr-codes/

Validate QR code from results/qr-codes directory

routing-switch validate-qr dante_ipv4.png

Expected Output: ✓ QR valid: Dante (confidence: 96.2%)

Note

Automatically looks in ./results/qr-codes/ if not found in current directory

Validate QR code using explicit --file flag (legacy syntax)

routing-switch validate-qr --file shadowsocks_qr.png

Expected Output: ✓ QR valid: Shadowsocks (confidence: 98.5%)

Note

Both direct filename and --file flag work identically

Validate QR URL from stdin

echo 'ss://...' | routing-switch validate-qr --stdin

Expected Output: ✓ Protocol: shadowsocks ✓ Config matches auth card

Note

Useful for clipboard validation

Validate all generated QR codes

routing-switch validate-qr all

Expected Output: Validating all QR codes... ✓ shadowsocks_ipv4.png: valid ✓ wireguard.png: valid

Note

Checks all QR codes in results/qr-codes/

Test QR code readability

routing-switch validate-qr --test-readability shadowsocks

Expected Output: Testing QR readability... ✓ QR code is readable

Note

Round-trip test of QR generation

JSON validation output

routing-switch validate-qr qr_code.png --json

Expected Output: {"is_valid": true, "protocol": "shadowsocks", "confidence_score": 0.985}

Note

Machine-readable validation results

ERROR RECOVERY

Recover from connection issues

Force disconnect stuck connection

sudo routing-switch disconnect --force

Expected Output: Force killed all processes, routes restored

Note

Use when normal disconnect fails

Reset all routing to default

sudo routing-switch reset

Expected Output: Routing reset to system defaults

Note

Emergency recovery command

Clean up orphaned processes

sudo routing-switch cleanup

Expected Output: Cleaned up 2 orphaned tun2socks processes

Automatically diagnose and fix routing issues, restore network settings

sudo routing-switch recover

Expected Output: System recovered, ready for new connection

Note

Performs comprehensive recovery including cleanup, route restoration, and DNS reset

MICROSOCKS SERVER MODE

Turn Kodachi into a SOCKS5 proxy server for other devices on your network

Enable microsocks server with auto port detection

sudo routing-switch microsocks-enable -u microkodachi-8273 -p 'S@Cur9P@s@Wo-Ds'

Expected Output: Microsocks server started on port 30050, listening on all interfaces

Note

Automatically selects available port from 30050-30054 range. Used when Kodachi acts as a server. After connecting routing-switch to any service (WireGuard, V2Ray, etc.), enable microsocks so other PCs on your network can connect through this machine using the listening microsocks port. Strong credentials recommended for security.

Enable with specific port

sudo routing-switch microsocks-enable -u microkodachi-8273 -p 'S@Cur9P@s@Wo-Ds' --port 30051

Expected Output: Microsocks server started on port 30051

Note

Use when you need a specific port number within the 30050-30054 range

Check microsocks server status

routing-switch microsocks-status

Expected Output: Status: Running, Port: 30050, PID: 12345

Check status in JSON format

routing-switch microsocks-status --json

Expected Output: {"status":"running","port":30050,"pid":12345}

Stop microsocks server

sudo routing-switch microsocks-disable

Expected Output: Microsocks server stopped successfully

Full example of using Kodachi as a proxy server

# Complete server workflow:

Expected Output: Step 1: sudo routing-switch connect wireguard Step 2: sudo routing-switch microsocks-enable -u microkodachi-8273 -p 'S@Cur9P@s@Wo-Ds' Step 3: Other PCs connect to socks5://microkodachi-8273:S@Cur9P@s@Wo-Ds@YOUR_IP:30050

Note

WORKFLOW: First connect routing-switch to any service (WireGuard, V2Ray, Shadowsocks, Hysteria2, etc.). Then enable microsocks to create a SOCKS5 proxy server. Other devices on your network can now connect through YOUR_IP:PORT using the provided credentials. All their traffic will flow through your active routing-switch connection.

Microsocks uses dedicated port range

# Port range information:

Expected Output: Microsocks: 30050-30054 Other services use different ranges to avoid conflicts

Note

High port numbers (30000+) avoid conflicts with system services. Each protocol has its own dedicated range.

How other devices connect

# Client connection example:

Expected Output: Protocol: SOCKS5 Address: YOUR_KODACHI_IP (e.g., 192.168.1.100) Port: 30050 Username: microkodachi-8273 Password: S@Cur9P@s@Wo-Ds

Note

Configure client device browsers/applications to use this SOCKS5 proxy. All traffic from client will be routed through Kodachi's active connection.

Environment Variables

Variable	Description	Default	Values
RUST_LOG	Set logging level (default: info)	info	error, warn, info, debug, trace

Exit Codes

Code	Description
0	Success
1	General error
2	Invalid arguments
3	Permission denied

---