routing-switch

System-wide traffic routing through various proxy protocols

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

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

File Information

Property	Value
Binary Name	routing-switch
Version	9.0.1
Build Date	2026-03-23T08:25:56.094935497Z
Rust Version	1.70.0
File Size	7.9MB
JSON Data	View Raw JSON

SHA256 Checksum

01d8b03a0ff9bac628b4ec3088b47c822947d0258a5620ecf11d3f19767bee3c

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	VPNGate free VPN integration (100+ public servers, no auth required)
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]

VPNGATE FREE VPN

`vpngate-fetch`

Fetch VPNGate free public VPN server list

Usage:

routing-switch vpngate-fetch [OPTIONS]

`vpngate-list`

List cached VPNGate servers with filtering and sorting

Usage:

routing-switch vpngate-list [OPTIONS]

`vpngate-connect`

Connect to a VPNGate free VPN server by index (no auth required)

Usage:

sudo routing-switch vpngate-connect <INDEX> [OPTIONS]

`vpngate-export`

Export a VPNGate server's OpenVPN config as .ovpn file

Usage:

routing-switch vpngate-export <INDEX> [OPTIONS]

`vpngate-export-all`

Export all cached VPNGate servers as .ovpn files

Usage:

routing-switch vpngate-export-all [OPTIONS]

Operational Scenarios

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

Scenario 1: BASIC CONNECTIONS

Connect to various proxy protocols

Step 1: Connect via OpenVPN

sudo routing-switch connect openvpn

Expected Output: Successfully connected to OpenVPN server

Note

Requires OpenVPN configuration in auth card

Step 2: Connect via WireGuard

sudo routing-switch connect wireguard

Expected Output: Successfully connected to WireGuard server

Note

Ultra-fast, modern VPN protocol

Step 3: Connect via Dante SOCKS5 proxy

sudo routing-switch connect dante

Expected Output: Successfully connected to Dante server

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

Step 5: Connect via Shadowsocks

sudo routing-switch connect shadowsocks

Expected Output: Successfully connected to Shadowsocks server

Note

Optimized for bypassing censorship

Step 6: Connect via V2Ray VMess

sudo routing-switch connect v2ray

Expected Output: Successfully connected to V2Ray server

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

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

Step 9: Connect via Xray Trojan

sudo routing-switch connect xray-trojan

Expected Output: Successfully connected to Xray Trojan server

Note

Mimics HTTPS traffic

Step 10: Connect via Xray VMess

sudo routing-switch connect xray-vmess

Expected Output: Successfully connected to Xray VMess server

Step 11: Connect via Mieru/Mita protocol

sudo routing-switch connect mita

Expected Output: Successfully connected to Mita server

Note

Anti-censorship protocol

Step 12: Connect via Hysteria2 protocol

sudo routing-switch connect hysteria2

Expected Output: Successfully connected to Hysteria2 server

Note

UDP-based, high-performance anti-censorship protocol

Scenario 2: EXTERNAL CONFIGURATION FILES

Connect using external configuration files instead of auth card

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

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

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

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

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

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

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

Scenario 3: IPV4/IPV6 SELECTION

Explicitly choose IPv4 or IPv6 connections

Step 1: Force IPv4 connection to Dante

sudo routing-switch connect dante --ipv4

Expected Output: Connected via IPv4

Step 2: Force IPv6 connection to Dante

sudo routing-switch connect dante --ipv6

Expected Output: Connected via IPv6

Note

Requires IPv6 support

Step 3: Connect Shadowsocks over IPv4

sudo routing-switch connect shadowsocks --ipv4

Expected Output: Shadowsocks connected via IPv4

Step 4: Connect Tor over IPv6

sudo routing-switch connect tor --ipv6

Expected Output: Tor connected via IPv6

Step 5: Use IPv6 for Xray VLESS

sudo routing-switch connect xray-vless --ipv6

Expected Output: Xray VLESS connected via IPv6

Step 6: Connect Hysteria2 over IPv4

sudo routing-switch connect hysteria2 --ipv4

Expected Output: Hysteria2 connected via IPv4

Step 7: Connect Hysteria2 over IPv6

sudo routing-switch connect hysteria2 --ipv6

Expected Output: Hysteria2 connected via IPv6

Note

Requires IPv6 support

Scenario 4: NETWORK PREREQUISITES

Check and manage network prerequisites for VPN connections

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

Step 2: Check prerequisites for IPv6 connections

sudo routing-switch check-prerequisites --ipv6

Expected Output: ✓ IPv6 forwarding: Enabled

Note

Only enables IPv6 if system supports it

Step 3: Get prerequisites status in JSON format

sudo routing-switch check-prerequisites --json

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

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

Step 5: Connect without prerequisites check

sudo routing-switch connect shadowsocks --skip-prerequisites

Expected Output: Connecting to shadowsocks...

Note

Skips prerequisites for backward compatibility

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

Scenario 5: CONNECTION STATUS

Check and monitor connection status

Step 1: Show current connection status

sudo routing-switch status

Expected Output: Protocol: wireguard, Status: Connected

Note

Requires sudo for accurate results (reads privileged system state)

Step 2: Get status in JSON format

sudo routing-switch status --json

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

Step 3: Pretty-printed JSON status

sudo routing-switch status --json-pretty

Expected Output: Formatted JSON with connection details

Step 4: Human-readable JSON status

sudo routing-switch status --json-human

Expected Output: Enhanced JSON output with descriptions

Scenario 6: DNS MODES AND SECURITY

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

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

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

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

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

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

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

Scenario 7: ROUTING MODES - SECURITY vs FAILOVER

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

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

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

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

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

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

Scenario 8: DISCONNECTION

Disconnect and restore normal routing

Step 1: Disconnect current proxy

sudo routing-switch disconnect

Expected Output: Successfully disconnected

Step 2: Force disconnect even if issues

sudo routing-switch disconnect --force

Expected Output: Force disconnected

Note

Kills all processes forcefully

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

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

Step 5: Disconnect with JSON output

sudo routing-switch disconnect --json

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

Scenario 9: FORCE FLAG & PROTOCOL COMPATIBILITY

Understanding --force behavior and which protocols can layer together

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

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

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

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

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

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

Scenario 10: DNS INFORMATION

Check DNS configuration

Step 1: Show current DNS servers

routing-switch dns-info

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

Step 2: DNS info in JSON format

routing-switch dns-info --json

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

Scenario 11: TOR DNS INFORMATION

Check Tor DNS and SOCKS configuration

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

Step 2: Tor DNS info in JSON format

routing-switch tor-dns-info --json

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

Scenario 12: VPS SERVER INFORMATION

Display VPS server details and statistics

Step 1: Show basic VPS information

routing-switch vps-info

Expected Output: Hostname: -, IPv4:

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

Step 3: VPS info in JSON format

routing-switch vps-info --json

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

Scenario 13: PROTOCOL LISTING

List available protocols with scores

Step 1: List all available protocols

routing-switch list-protocols

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

Step 2: Protocol list in JSON

routing-switch list-protocols --json

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

Step 3: Show only available protocols

routing-switch list-protocols --available-only

Expected Output: Available: WireGuard, Tor, Shadowsocks

Note

Based on auth card

Step 4: Sort by security score

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

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

Step 5: Sort by speed score

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

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

Scenario 14: AUTO-SELECTION

Automatically select best protocol

Step 1: Auto-select best protocol

sudo routing-switch auto-select

Expected Output: Selected WireGuard (best overall score)

Step 2: Auto-select with minimum security

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

Expected Output: Selected OpenVPN (security: 95.0)

Step 3: Prioritize speed in selection

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

Expected Output: Selected WireGuard (fastest protocol)

Step 4: Auto-select with JSON output

sudo routing-switch auto-select --json

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

Scenario 15: PORT USAGE INFORMATION

Local SOCKS5 port allocation reference for protocols

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

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

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

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

Scenario 16: JSON OUTPUT FORMATS

Different JSON output options

Step 1: Compact JSON output

sudo routing-switch status --json

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

Note

Requires sudo for accurate results

Step 2: Pretty-printed JSON

sudo routing-switch status --json-pretty

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

Step 3: Human-enhanced JSON

sudo routing-switch status --json-human

Expected Output: JSON with descriptions and metadata

Step 4: Pretty JSON protocol list

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

Expected Output: Formatted JSON array of protocols

Scenario 17: BENCHMARKING

Test protocol performance

Step 1: Benchmark all protocols (3 iterations default)

routing-switch benchmark

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

Note

Tests actual throughput

Step 2: Benchmark with custom iteration count

routing-switch benchmark --iterations 5

Expected Output: Running 5 iterations... WireGuard: 95Mbps...

Note

More iterations = more accurate results

Step 3: Benchmark results in JSON

routing-switch benchmark --json

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

Scenario 18: TESTING PROTOCOLS

Test protocol connectivity without routing

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

Step 2: Extended protocol test

routing-switch test-protocol shadowsocks --extended

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

Step 3: Test all available protocols

routing-switch test-protocol all

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

Step 4: Test with JSON output

routing-switch test-protocol wireguard --json

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

Scenario 19: NO-TUN MODE (MANUAL PROXY)

Run proxy without TUN interface for manual configuration

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

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

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

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

Step 5: Xray VLESS proxy for manual configuration

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

Expected Output: Xray SOCKS5 proxy ready at localhost:30015

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

Step 7: Chrome command line example

# Chrome with no-TUN proxy:

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

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

sudo routing-switch disconnect

Expected Output: Proxy stopped

Scenario 20: CONFIGURATION EXPORT AND DISPLAY

Export and display protocol configurations

Step 1: Export all configurations to default location

routing-switch export-config

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

Note

Creates timestamped config files

Step 2: Export specific protocol configuration

routing-switch export-config wireguard

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

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

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

Step 5: Export with JSON output showing results

routing-switch export-config --json

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

Step 6: Display WireGuard configuration

routing-switch showconfig wireguard

Expected Output: Protocol Configurations:

Note

Masks sensitive data by default

Step 7: Show all protocol configs in pretty JSON

routing-switch showconfig all --json-pretty

Expected Output: Formatted JSON with all available protocol configurations

Step 8: Show config with passwords hidden

routing-switch showconfig dante --mask-sensitive

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

Note

Safe for sharing/logging

Step 9: Get Shadowsocks connection URL

routing-switch showconfigurl shadowsocks

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

Note

URL can be imported into mobile apps

Step 10: Get SOCKS5 URLs in JSON format

routing-switch showconfigurl dante --json

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

Step 11: Get URLs for all available protocols

routing-switch showconfigurl all

Expected Output: Protocol Connection URLs:

shadowsocks: ipv4: ss://...

dante: ipv4: socks5://...

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

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

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

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

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

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

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

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

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

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

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

Scenario 21: QR CODE VALIDATION

Validate QR codes against auth card

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

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

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

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

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

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

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

Scenario 22: ERROR RECOVERY

Recover from connection issues

Step 1: Force disconnect stuck connection

sudo routing-switch disconnect --force

Expected Output: Force killed all processes, routes restored

Note

Use when normal disconnect fails

Step 2: Reset all routing to default

sudo routing-switch reset

Expected Output: Routing reset to system defaults

Note

Emergency recovery command

Step 3: Clean up orphaned processes

sudo routing-switch cleanup

Expected Output: Cleaned up 2 orphaned tun2socks processes

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

Scenario 23: MICROSOCKS SERVER MODE

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

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

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

Step 3: Check microsocks server status

sudo routing-switch microsocks-status

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

Note

Requires sudo for accurate results (reads privileged state)

Step 4: Check status in JSON format

sudo routing-switch microsocks-status --json

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

Step 5: Stop microsocks server

sudo routing-switch microsocks-disable

Expected Output: Microsocks server stopped successfully

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

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

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

Scenario 24: VPNGATE FREE VPN

Connect to free VPNGate public servers (no authentication required)

Step 1: Fetch VPNGate server list from public API

routing-switch vpngate-fetch

Expected Output: Fetched 150 VPNGate servers

Note

Downloads and caches server list (refreshes every hour)

Step 2: List all cached VPNGate servers

routing-switch vpngate-list

Expected Output: Index Flag Country IP Speed Ping Score Sessions

Note

Shows servers sorted by score (default)

Step 3: List top 10 Japanese servers by speed

routing-switch vpngate-list --country JP --sort speed -l 10

Expected Output: 10 servers shown, filtered by country: JP

Note

Filter by country name or code, sort by speed/ping/score/sessions

Step 4: List US servers sorted by lowest ping

routing-switch vpngate-list --country US --sort ping

Expected Output: Servers sorted by ping latency

Step 5: Connect to VPNGate server at index 5

sudo routing-switch vpngate-connect 5

Expected Output: Successfully connected to via openvpn

Note

Uses OpenVPN with free vpn/vpn credentials

Step 6: Force connect to server 12 (disconnect existing first)

sudo routing-switch vpngate-connect 12 --force

Expected Output: Force connected to VPNGate server

Step 7: Fetch servers with JSON output

routing-switch vpngate-fetch --json

Expected Output: {"status":"success","server_count":150}

Step 8: List servers in pretty JSON format

routing-switch vpngate-list --json-pretty

Expected Output: Pretty-printed JSON array of servers

Step 9: Export top server's OpenVPN config as .ovpn file

routing-switch vpngate-export 1

Expected Output: Exported: JP Japan (1.2.3.4) -> results/vpngate-configs/1_jp_1-2-3-4.ovpn

Note

Includes embedded vpn/vpn credentials for standalone use

Step 10: Export all cached servers as .ovpn files

routing-switch vpngate-export-all

Expected Output: Exported 99 VPNGate configs to results/vpngate-configs

Note

Bulk export for use in external OpenVPN clients

Step 11: Export server #5 config with JSON output

routing-switch vpngate-export 5 --json

Expected Output: {"status":"success","action":"vpngate-export","file":"..."}

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