{ "report_info": { "version": "9.0.1", "generated_at": "2026-06-08T16:22:04Z", "binary_name": "dns-switch" }, "binary": { "name": "dns-switch", "path": "/opt/kodachi/dashboard/hooks/dns-switch", "timestamp": "2026-06-08T16:22:04Z", "file_info": { "size": 6853472, "sha256": "2ad26b059aca9fc450a9df3446ce70207a8b158493333725087d615808856e99" }, "flag_n": { "command": "info", "data": { "author": "Warith Al Maawali", "copyright": "© 2026 Linux Kodachi", "description": "Production-ready DNS management with security and portability. A self-contained, portable DNS management tool with comprehensive security, health checking, and remote discovery capabilities.", "features": [ "Embedded DNS server lists (no external config dependencies)", "Dynamic path detection (works in any directory)", "Comprehensive input validation and sanitization", "JSON output support for automation", "Health monitoring and performance testing", "Remote DNS server discovery and testing", "Security-focused design with privilege checking", "DNSCrypt proxy integration", "Pi-hole DNS filter integration", "Automatic backup and restore capabilities" ], "license": "Proprietary", "name": "dns-switch", "securityFeatures": { "authentication": "Integrated with Kodachi authentication system", "encryption": "Supports DNSCrypt for encrypted DNS queries", "inputValidation": "All inputs sanitized and validated before use", "rateLimiting": "Built-in rate limiting for remote operations" }, "systemRequirements": { "dependencies": [ "systemd-resolved or resolvconf", "DNSCrypt proxy (optional)", "Pi-hole (optional)" ], "os": "Linux (Debian-based)", "privileges": "root/sudo for system changes" }, "version": "9.0.1", "website": "https://digi77.com" }, "errors": [], "metadata": { "executionTime": 7, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-06-08T16:22:04.999554291Z", "version": "9.0.1", "warnings": [] }, "flag_v": { "command": "version", "data": { "buildDate": "REDACTED-BUILD-TIME", "gitCommit": "unknown", "name": "dns-switch", "rustVersion": "", "version": "9.0.1" }, "errors": [], "metadata": { "executionTime": 0, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-06-08T16:22:05.062453301Z", "version": "9.0.1", "warnings": [] }, "flag_h": { "command": "help", "data": { "commandCategories": [ { "category": "DNS Management", "commands": [ { "description": "Switch DNS to a specific category or provider", "examples": [ "sudo dns-switch switch --category reputable", "sudo dns-switch switch --category encrypted --provider cloudflare", "sudo dns-switch switch --names cloudflare adguard", "sudo dns-switch switch --servers 1.1.1.1 9.9.9.9", "sudo dns-switch switch --category reputable --json" ], "name": "switch", "options": [ { "description": "DNS category (reputable|normal|encrypted|fallback|all)", "flag": "--category ", "required": false }, { "description": "Specific DNS provider name", "flag": "--provider ", "required": false }, { "description": "Switch DNS by server names (e.g., cloudflare, adguard)", "flag": "--names ", "required": false }, { "description": "Switch DNS by server IP addresses", "flag": "--servers ", "required": false } ], "requires_sudo": true, "usage": "dns-switch switch [OPTIONS]" }, { "description": "Switch to random DNS servers with advanced selection", "examples": [ "sudo dns-switch random", "sudo dns-switch random --type reputable", "sudo dns-switch random --type all --count 6", "sudo dns-switch random --type reputable,normal --count 7" ], "name": "random", "options": [ { "default": "reputable", "description": "Type of DNS servers (reputable|normal|remotely_fetched|both|all). NOTE: 'encrypted'/'fallback'/'failed' are NOT valid here — encrypted servers require dnscrypt-set, fallback uses the embedded pool via `dns-switch fallback`, failed servers are excluded by design.", "flag": "--type ", "required": false }, { "default": "3", "description": "Number of random DNS servers to select", "flag": "--count ", "required": false } ], "requires_sudo": true, "usage": "dns-switch random [OPTIONS]" }, { "description": "Switch to fallback DNS servers", "examples": [ "sudo dns-switch fallback" ], "name": "fallback", "options": [], "requires_sudo": true, "usage": "dns-switch fallback" }, { "description": "Show current DNS configuration", "examples": [ "dns-switch status", "dns-switch status --json" ], "name": "status", "options": [], "requires_sudo": false, "usage": "dns-switch status" } ] }, { "category": "DNS Mode Management", "commands": [ { "description": "Show current DNS management mode (modern vs legacy)", "examples": [ "dns-switch get-mode", "dns-switch get-mode --json" ], "name": "get-mode", "options": [], "requires_sudo": false, "usage": "dns-switch get-mode" }, { "description": "Set DNS management mode (modern=systemd-resolved, legacy=/etc/resolv.conf)", "examples": [ "sudo dns-switch set-mode --mode modern # Switch to systemd-resolved", "sudo dns-switch set-mode --mode legacy # Switch to legacy /etc/resolv.conf" ], "name": "set-mode", "options": [ { "description": "DNS mode: 'modern' (systemd-resolved) or 'legacy' (/etc/resolv.conf)", "flag": "--mode ", "required": true } ], "requires_sudo": true, "usage": "dns-switch set-mode --mode " }, { "description": "Auto-detect recommended DNS mode for this system", "examples": [ "dns-switch detect-mode", "dns-switch detect-mode --json" ], "name": "detect-mode", "options": [], "requires_sudo": false, "usage": "dns-switch detect-mode" }, { "description": "Repair broken DNS configuration (mode mismatches, broken symlinks, etc.) — also accepts the legacy alias 'dns-fix'", "examples": [ "sudo dns-switch fix-dns", "sudo dns-switch fix-dns --force", "sudo dns-switch dns-fix # legacy alias for fix-dns", "# Repairs: mode mismatches, broken symlinks, corrupted files", "# Applies fallback DNS servers to restore connectivity" ], "name": "fix-dns", "options": [ { "description": "Run all repair stages even if DNS appears healthy", "flag": "--force", "required": false } ], "requires_sudo": true, "usage": "dns-switch fix-dns" }, { "description": "Show which method systemd-resolved uses (global / per-interface / networkmanager / auto)", "examples": [ "dns-switch get-modern-method", "dns-switch get-modern-method --json" ], "name": "get-modern-method", "options": [], "requires_sudo": false, "usage": "dns-switch get-modern-method" }, { "description": "Set systemd-resolved DNS application method (only relevant in modern mode)", "examples": [ "sudo dns-switch set-modern-method --method global", "sudo dns-switch set-modern-method --method auto" ], "name": "set-modern-method", "options": [ { "default": "auto", "description": "global (resolved.conf, safest), per-interface (resolvectl), networkmanager (nmcli), or auto", "flag": "--method ", "required": true } ], "requires_sudo": true, "usage": "dns-switch set-modern-method --method " }, { "description": "Hand DNS management to a third-party VPN GUI (Mullvad, ProtonVPN, etc.) or take it back. Kodachi normally locks /etc/resolv.conf immutable for DNS-leak protection, which stops those clients from setting their tunnel DNS — so they fail with 'internet blocked' / 'failed to set system DNS'. Turn this ON before connecting such a client, OFF to restore Kodachi-managed DNS.", "examples": [ "sudo dns-switch external-dns --state on # BEFORE launching Mullvad/ProtonVPN GUI", "sudo dns-switch external-dns --state off # give DNS back to Kodachi (disconnect the VPN GUI first)", "dns-switch external-dns --state status # is a third-party VPN currently managing DNS?", "# WARNING: while ON, Kodachi's DNS-leak immutable lock is paused — your VPN client must enforce its own leak protection (Mullvad/ProtonVPN do).", "# Covers VPN clients that manage /etc/resolv.conf. A client that strictly requires systemd-resolved may still not work; switch to modern mode with 'set-mode --mode modern' for those." ], "name": "external-dns", "options": [ { "default": "status", "description": "on = unlock resolv.conf + pause Kodachi DNS protection so a VPN GUI can manage DNS; off = re-lock and return DNS to Kodachi; status = show current mode (read-only, no sudo)", "flag": "--state ", "required": false } ], "requires_sudo": true, "usage": "dns-switch external-dns --state " } ] }, { "category": "Health & Discovery", "commands": [ { "description": "Check health of DNS servers with detailed analysis (read-only by default)", "examples": [ "dns-switch health", "dns-switch health --type reputable", "dns-switch health --type all", "dns-switch health --type reputable --save", "dns-switch health --full --save", "dns-switch health --fresh --save --json" ], "name": "health", "options": [ { "default": "reputable", "description": "Test specific type (reputable|normal|encrypted|fallback|all)", "flag": "--type ", "required": false }, { "description": "Perform comprehensive health check", "flag": "--full", "required": false }, { "description": "Force fresh health check, bypassing cache", "flag": "--fresh", "required": false }, { "description": "Save health check results to database (default: read-only, no database changes)", "flag": "--save", "required": false }, { "description": "BYPASS 3-strike rule: move failed servers to 'failed' category IMMEDIATELY (requires --save). Use for urgent cleanup or known-bad servers", "flag": "--force-move", "required": false } ], "requires_sudo": false, "usage": "dns-switch health [OPTIONS]" }, { "description": "Fetch and test remote DNS servers with advanced options", "examples": [ "dns-switch fetch", "dns-switch fetch --save", "dns-switch fetch --count 100", "dns-switch fetch --all", "dns-switch fetch --fresh --json" ], "name": "fetch", "options": [ { "description": "Save results to database", "flag": "--save", "required": false }, { "description": "Fetch all available DNS servers (instead of default 25)", "flag": "--all", "required": false }, { "default": "25", "description": "Specify number of DNS servers to fetch", "flag": "--count ", "required": false }, { "description": "Force fresh data retrieval, bypassing all caches", "flag": "--fresh", "required": false }, { "description": "Show fetch history", "flag": "--history", "required": false }, { "description": "Load cached results", "flag": "--load ", "required": false } ], "requires_sudo": false, "usage": "dns-switch fetch [OPTIONS]" }, { "description": "Fetch a specific number of DNS servers from remote sources", "examples": [ "dns-switch fetch-count", "dns-switch fetch-count --count 50", "dns-switch fetch-count --count 100 --fresh", "dns-switch fetch-count --count 35 --json" ], "name": "fetch-count", "options": [ { "default": "25", "description": "Number of DNS servers to fetch", "flag": "--count ", "required": false }, { "description": "Force fresh data retrieval, bypassing caches", "flag": "--fresh", "required": false } ], "requires_sudo": false, "usage": "dns-switch fetch-count [OPTIONS]" }, { "description": "Pull DNSCrypt and Tor DNS servers from your authenticated Kodachi card into the local DB (encrypted category)", "examples": [ "sudo dns-switch fetch-dns-from-card", "# Requires a valid online-auth session (run 'sudo online-auth authenticate' first)" ], "name": "fetch-dns-from-card", "options": [], "requires_sudo": true, "usage": "dns-switch fetch-dns-from-card" } ] }, { "category": "DNSCrypt Management", "commands": [ { "description": "Show DNSCrypt status", "examples": [ "dns-switch dnscrypt" ], "name": "dnscrypt", "options": [], "requires_sudo": false, "usage": "dns-switch dnscrypt" }, { "description": "Enable DNSCrypt with specific resolver", "examples": [ "sudo dns-switch dnscrypt-set --resolver cloudflare" ], "name": "dnscrypt-set", "options": [ { "description": "DNSCrypt resolver name", "flag": "--resolver ", "required": true } ], "requires_sudo": true, "usage": "dns-switch dnscrypt-set --resolver " }, { "description": "Restart DNSCrypt proxy", "examples": [ "sudo dns-switch dnscrypt-restart" ], "name": "dnscrypt-restart", "options": [], "requires_sudo": true, "usage": "dns-switch dnscrypt-restart" }, { "description": "Remove DNSCrypt configuration", "examples": [ "sudo dns-switch dnscrypt-remove" ], "name": "dnscrypt-remove", "options": [], "requires_sudo": true, "usage": "dns-switch dnscrypt-remove" }, { "description": "Show whether the DNSCrypt auto-recovery monitor timer is active", "examples": [ "dns-switch dnscrypt-monitor-status" ], "name": "dnscrypt-monitor-status", "options": [], "requires_sudo": false, "usage": "dns-switch dnscrypt-monitor-status" }, { "description": "Run a single monitor check now (used by the timer; safe to invoke manually)", "examples": [ "sudo dns-switch dnscrypt-monitor-check" ], "name": "dnscrypt-monitor-check", "options": [], "requires_sudo": true, "usage": "dns-switch dnscrypt-monitor-check" }, { "description": "Install and enable the systemd timer that auto-recovers DNSCrypt and falls back to safe DNS on failure", "examples": [ "sudo dns-switch enable-dnscrypt-monitor" ], "name": "enable-dnscrypt-monitor", "options": [], "requires_sudo": true, "usage": "dns-switch enable-dnscrypt-monitor" }, { "description": "Disable and remove the DNSCrypt auto-recovery timer", "examples": [ "sudo dns-switch disable-dnscrypt-monitor" ], "name": "disable-dnscrypt-monitor", "options": [], "requires_sudo": true, "usage": "dns-switch disable-dnscrypt-monitor" }, { "description": "Enable DNSSEC signature validation (require_dnssec=true) in dnscrypt-proxy.toml and restart dnscrypt-proxy. Earns +0.1 dns_privacy score", "examples": [ "sudo dns-switch dnssec-on" ], "name": "dnssec-on", "options": [], "requires_sudo": true, "usage": "dns-switch dnssec-on" }, { "description": "Disable DNSSEC validation (require_dnssec=false, default state) in dnscrypt-proxy.toml and restart dnscrypt-proxy", "examples": [ "sudo dns-switch dnssec-off" ], "name": "dnssec-off", "options": [], "requires_sudo": true, "usage": "dns-switch dnssec-off" }, { "description": "Enable DoH (TLS-encrypted DNS, doh_servers=true) in dnscrypt-proxy.toml and restart dnscrypt-proxy. DoH is dnscrypt-proxy's DoT-equivalent. Earns +0.2 dns_privacy score", "examples": [ "sudo dns-switch dot-on" ], "name": "dot-on", "options": [], "requires_sudo": true, "usage": "dns-switch dot-on" }, { "description": "Disable DoH (doh_servers=false) in dnscrypt-proxy.toml; dnscrypt-proxy reverts to DNSCrypt-only protocol and restarts", "examples": [ "sudo dns-switch dot-off" ], "name": "dot-off", "options": [], "requires_sudo": true, "usage": "dns-switch dot-off" } ] }, { "category": "Boot & Leak Protection", "commands": [ { "description": "One-shot DNS health probe (used at boot to detect and repair empty or broken nameservers)", "examples": [ "sudo dns-switch boot-check", "sudo dns-switch boot-check --json" ], "name": "boot-check", "options": [], "requires_sudo": true, "usage": "dns-switch boot-check" }, { "description": "Install the systemd service that runs boot-check on every boot (requires auth)", "examples": [ "sudo dns-switch enable-boot-check" ], "name": "enable-boot-check", "options": [], "requires_sudo": true, "usage": "dns-switch enable-boot-check" }, { "description": "Remove the boot-time DNS validation systemd service (requires auth)", "examples": [ "sudo dns-switch disable-boot-check" ], "name": "disable-boot-check", "options": [], "requires_sudo": true, "usage": "dns-switch disable-boot-check" }, { "description": "Report any interface with DNS servers different from the expected system DNS (per-interface leak detection)", "examples": [ "dns-switch verify-no-leaks", "dns-switch verify-no-leaks --json" ], "name": "verify-no-leaks", "options": [], "requires_sudo": false, "usage": "dns-switch verify-no-leaks" } ] }, { "category": "Pi-hole Integration", "commands": [ { "description": "Show Pi-hole status", "examples": [ "dns-switch pihole" ], "name": "pihole", "options": [], "requires_sudo": false, "usage": "dns-switch pihole" }, { "description": "Enable Pi-hole DNS filtering", "examples": [ "sudo dns-switch pihole-enable" ], "name": "pihole-enable", "options": [], "requires_sudo": true, "usage": "dns-switch pihole-enable" }, { "description": "Disable Pi-hole DNS filtering", "examples": [ "sudo dns-switch pihole-disable" ], "name": "pihole-disable", "options": [], "requires_sudo": true, "usage": "dns-switch pihole-disable" }, { "description": "Set Pi-hole web interface password (auto-handles file protection)", "examples": [ "sudo dns-switch pihole-password --password MyNewPassword", "# Note: To manually change password, first run: sudo chattr -i /etc/pihole/pihole.toml" ], "name": "pihole-password", "options": [ { "description": "New password for Pi-hole web interface (TOML file auto-unprotected)", "flag": "--password ", "required": true } ], "requires_sudo": true, "usage": "dns-switch pihole-password --password " }, { "description": "Reset Pi-hole configuration", "examples": [ "sudo dns-switch pihole-reset" ], "name": "pihole-reset", "options": [], "requires_sudo": true, "usage": "dns-switch pihole-reset" } ] }, { "category": "Information & Utilities", "commands": [ { "description": "List available DNS servers", "examples": [ "dns-switch list --category reputable", "dns-switch list --category encrypted", "dns-switch list --category remotely_fetched" ], "name": "list", "options": [ { "description": "Category to list (reputable|normal|encrypted|fallback|remotely_fetched|all)", "flag": "--category ", "required": true } ], "requires_sudo": false, "usage": "dns-switch list --category " }, { "description": "Count DNS servers by category", "examples": [ "dns-switch count", "dns-switch count --json" ], "name": "count", "options": [], "requires_sudo": false, "usage": "dns-switch count" } ] }, { "category": "Maintenance & Recovery", "commands": [ { "description": "Clean temporary files and cache", "examples": [ "dns-switch clean" ], "name": "clean", "options": [], "requires_sudo": false, "usage": "dns-switch clean" }, { "description": "Clean duplicate DNS entries from database", "examples": [ "sudo dns-switch clean-duplicates", "sudo dns-switch clean-duplicates --json", "sudo dns-switch clean-duplicates --no-action" ], "name": "clean-duplicates", "options": [], "requires_sudo": true, "usage": "dns-switch clean-duplicates" }, { "description": "Flush systemd-resolved and nscd DNS caches to clear stale entries", "examples": [ "sudo dns-switch flush-cache", "sudo dns-switch flush-cache --json" ], "name": "flush-cache", "options": [], "requires_sudo": true, "usage": "sudo dns-switch flush-cache" }, { "description": "Create DNS configuration backup", "examples": [ "dns-switch backup" ], "name": "backup", "options": [], "requires_sudo": false, "usage": "dns-switch backup" }, { "description": "Restore default DNS configuration", "examples": [ "sudo dns-switch restore-default" ], "name": "restore-default", "options": [], "requires_sudo": true, "usage": "dns-switch restore-default" }, { "description": "Restore from backup", "examples": [ "sudo dns-switch restore-backup", "sudo dns-switch restore-backup --file backup.json" ], "name": "restore-backup", "options": [ { "default": "latest", "description": "Backup file to restore", "flag": "--file ", "required": false } ], "requires_sudo": true, "usage": "dns-switch restore-backup [--file ]" } ] } ], "description": "Production-ready DNS management with security and portability", "environmentVariables": [ { "default": "info", "description": "Set logging level", "name": "RUST_LOG", "values": "error|warn|info|debug|trace" }, { "default": "unset", "description": "Disable all colored output when set", "name": "NO_COLOR", "values": "1|true|yes (any value disables color)" }, { "default": "~/.config/dns-switch/config.json", "description": "Path to configuration file", "name": "DNS_SWITCH_CONFIG", "values": "/path/to/config.json" } ], "exitCodes": { "0": "Success", "1": "General error", "2": "Invalid arguments", "3": "Permission denied", "4": "Network error", "5": "File not found", "6": "Operation timeout", "7": "Authentication error" }, "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": "Enable verbose output", "flag": "--verbose" }, { "description": "Suppress non-essential output", "flag": "--quiet" }, { "description": "Disable colored output", "flag": "--no-color" }, { "description": "Set timeout (default: 30)", "flag": "--timeout " }, { "description": "Retry attempts (default: 3)", "flag": "--retry " }, { "description": "Use custom configuration file", "flag": "--config " }, { "description": "Enhanced JSON output (best of both worlds)", "flag": "--json-human" }, { "description": "Pretty-print JSON output", "flag": "--json-pretty" }, { "description": "Enhanced JSON output with improved formatting (like jq)", "flag": "--json-human" }, { "description": "Select specific fields to include", "flag": "--fields " }, { "description": "Limit number of results", "flag": "--limit " }, { "description": "Skip first N results", "flag": "--offset " }, { "description": "Specify working directory", "flag": "--work-dir " }, { "description": "Dry run mode", "flag": "--no-action" }, { "description": "Set logging verbosity (error|warn|info|debug|trace)", "flag": "--log-level " } ], "name": "dns-switch", "usage": "dns-switch [OPTIONS] [COMMAND] [ARGS]" }, "errors": [], "metadata": { "executionTime": 0, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-06-08T16:22:05.122230806Z", "version": "9.0.1", "warnings": [] }, "flag_e": { "command": "examples", "data": { "categories": [ { "description": "Check current DNS configuration and available servers", "examples": [ { "command": "dns-switch status", "description": "Display current system DNS servers with detailed information", "expectedOutput": "Shows active DNS servers, their IPs, and configuration source" }, { "command": "dns-switch status --json", "description": "Get DNS status in machine-readable JSON format", "expectedOutput": "JSON with DNS servers, timestamps, and configuration metadata", "notes": "Useful for scripting and automation" }, { "command": "dns-switch count", "description": "Count available DNS servers by category (reputable, normal, encrypted, etc.)", "expectedOutput": "Summary showing total servers in each category" }, { "command": "dns-switch list --category reputable", "description": "List all reputable DNS servers with details", "expectedOutput": "Table of reputable DNS providers with names, IPs, and locations" } ], "id": "1_dns_status_checking", "title": "DNS Status & Information" }, { "description": "Switch DNS servers using different selection methods", "examples": [ { "command": "sudo dns-switch switch --category reputable", "description": "Switch to first available reputable DNS servers from the database", "expectedOutput": "System DNS changed to trusted providers like Cloudflare, Quad9, or AdGuard" }, { "command": "sudo dns-switch switch --names cloudflare adguard", "description": "Switch to specific DNS providers by name", "expectedOutput": "DNS set to Cloudflare (1.1.1.1) and AdGuard (94.140.14.14)" }, { "command": "sudo dns-switch switch --servers 1.1.1.1 9.9.9.9", "description": "Switch to specific DNS servers by IP address", "expectedOutput": "DNS set to specified IP addresses directly", "notes": "Useful when you know exact server IPs" }, { "command": "sudo dns-switch fallback", "description": "Switch to hardcoded fallback DNS servers for emergencies", "expectedOutput": "DNS set to fallback servers from embedded recovery pool (e.g. 9.9.9.9, 1.1.1.1, 94.140.14.14)", "notes": "Use when database is corrupted or unavailable" } ], "id": "2_basic_dns_switching", "title": "Basic DNS Switching" }, { "description": "Randomly select DNS servers from different categories", "examples": [ { "command": "sudo dns-switch random", "description": "Select 3 random DNS servers from reputable category (default behavior)", "expectedOutput": "DNS set to 3 randomly selected reputable servers" }, { "command": "sudo dns-switch random --verify", "description": "Select 3 random reputable DNS servers and verify they work before applying", "expectedOutput": "DNS changed to verified working servers only", "notes": "Only applies servers that pass health check" }, { "command": "sudo dns-switch random --type reputable --verify", "description": "Select 3 random reputable DNS servers and verify each works before applying", "expectedOutput": "DNS changed to verified working reputable servers", "notes": "Health checks each selected server; only uses working ones" }, { "command": "sudo dns-switch random --type normal --count 5", "description": "Select 5 random servers from normal category", "expectedOutput": "DNS set to 5 randomly selected normal servers" }, { "command": "sudo dns-switch random --type normal --count 6 --verify", "description": "Select 6 random normal DNS servers and verify they work before applying", "expectedOutput": "DNS changed to up to 6 verified working servers", "notes": "If some servers fail health check, only working ones are used" }, { "command": "sudo dns-switch random --type reputable,normal --count 6", "description": "Select 6 servers: 3 from reputable + 3 from normal categories", "expectedOutput": "DNS set to 6 servers evenly distributed between categories", "notes": "Count is distributed evenly across specified types" }, { "command": "sudo dns-switch random --type reputable,normal --count 7", "description": "Select 7 servers distributed: 4 reputable + 3 normal", "expectedOutput": "DNS changed to 7 random servers", "notes": "Uneven distribution favors first type" }, { "command": "sudo dns-switch random --type all", "description": "Select 3 servers each from reputable, normal, and remotely_fetched (9 total)", "expectedOutput": "DNS set to 9 servers: 3 from each major category", "notes": "'all' excludes encrypted and fallback categories" }, { "command": "sudo dns-switch random --type reputable,normal --count-random 6", "description": "Select 6 servers distributed: 3 reputable + 3 normal (alternate syntax)", "expectedOutput": "6 servers evenly distributed between categories", "notes": "--count-random is an alias for --count" }, { "command": "sudo dns-switch random --type reputable,normal,remotely_fetched --count-random 6", "description": "Select 6 servers distributed: 2 from each category", "expectedOutput": "6 servers evenly distributed across 3 categories" }, { "command": "sudo dns-switch random --type reputable,normal,remotely_fetched --count-random 10", "description": "Select 10 servers distributed: 4+3+3 from each category", "expectedOutput": "10 servers with weighted distribution" } ], "id": "3_random_dns_selection", "title": "Random DNS Selection" }, { "description": "Test DNS servers for availability and performance. Health checks are read-only by default — use --save to persist results to database. IMPORTANT: Failed servers are moved to 'failed' category only after 3 CONSECUTIVE failures (3-strike rule) to prevent false positives from temporary network issues. Run health checks 3 times to trigger category changes.", "examples": [ { "command": "dns-switch health", "description": "Test reputable DNS servers (default) for availability and response times (read-only)", "expectedOutput": "Health status for reputable servers with response times", "notes": "Read-only: does not modify the database" }, { "command": "dns-switch health --type reputable", "description": "Test reputable DNS servers only (read-only)", "expectedOutput": "Health status for reputable servers", "notes": "Tests curated high-quality DNS providers. Read-only: does not modify database" }, { "command": "dns-switch health --type reputable --save", "description": "Test reputable servers and save results to database", "expectedOutput": "Health status saved to dns-database.json", "notes": "--save updates: status, response times, geolocation, consecutive_failures counter. Servers move to 'failed' category ONLY after 3 consecutive failures (run 3 times)" }, { "command": "dns-switch health --type normal", "description": "Test normal DNS servers only (read-only)", "expectedOutput": "Health status for normal servers", "notes": "Tests standard reliable DNS providers. Read-only mode" }, { "command": "dns-switch health --type encrypted", "description": "Test encrypted DNS servers (DNSCrypt, DoH, DoT) only", "expectedOutput": "Health status for encrypted servers", "notes": "Tests DNSCrypt and secure DNS providers. Read-only mode" }, { "command": "dns-switch health --type remotely_fetched", "description": "Check health of remotely fetched DNS servers (read-only)", "expectedOutput": "Health status for remotely fetched servers", "notes": "Tests servers previously discovered via 'fetch' command" }, { "command": "dns-switch health --type remotely_fetched --save", "description": "Test remotely fetched servers and save results to database", "expectedOutput": "Health status for remotely fetched servers saved to database", "notes": "3-STRIKE RULE: Servers move to 'failed' category only after 3 consecutive failures. Run this command 3 times to trigger category moves" }, { "command": "dns-switch health --type all", "description": "Test ALL working server categories (excludes failed servers)", "expectedOutput": "Complete report of all working DNS servers across all categories", "notes": "Tests: fallback + reputable + normal + encrypted + remotely_fetched. Excludes failed servers for efficiency. May take several minutes" }, { "command": "dns-switch health --type all --save", "description": "Test all working categories and save results to database", "expectedOutput": "Complete health report saved to database", "notes": "Updates: status, response times, geolocation, consecutive_failures counter. 3-STRIKE RULE: Run 3 times to move failed servers to 'failed' category (prevents false positives)" }, { "command": "dns-switch health --type all --save && dns-switch health --type all --save && dns-switch health --type all --save", "description": "Run health check 3 times to trigger 3-strike rule and move failed servers", "expectedOutput": "After 3rd run: servers with 3 consecutive failures moved to 'failed' category. Check with 'count' command", "notes": "WORKFLOW EXAMPLE: The 3-strike rule requires 3 consecutive failures before moving servers. Run 'count' after 3rd run to see category changes" }, { "command": "dns-switch health --type failed --save", "description": "Test ONLY failed servers and update their status if recovered", "expectedOutput": "Failed servers health check completed - recovered servers moved IMMEDIATELY back to original categories (no 3-strike rule for recovery)", "notes": "Recovery is instant (1 success = move back). Tests servers from dns-database-failed.json. --save required to persist recovery" }, { "command": "dns-switch health --type all --save --force-move", "description": "BYPASS 3-strike rule: move failed servers to 'failed' category IMMEDIATELY", "expectedOutput": "Failed servers moved to 'failed' category on FIRST failure (no waiting for 3 strikes). Check with 'count' command", "notes": "⚠️ CAUTION: Bypasses protection against transient network issues. Use for urgent cleanup or when you're CERTAIN servers are permanently down. --save required" }, { "command": "dns-switch health --type remotely_fetched --save --force-move", "description": "Test remotely fetched servers and force-move failures immediately", "expectedOutput": "Remotely fetched servers tested - failures moved to 'failed' category instantly", "notes": "Useful for quickly cleaning up newly discovered servers that are non-responsive. Skips 3-strike protection" }, { "command": "dns-switch health --full --save", "description": "Full health check with geolocation, save results", "expectedOutput": "Comprehensive health data saved to database", "notes": "Full check includes geolocation lookup for all working servers" }, { "command": "dns-switch health --json", "description": "Health check with JSON output (read-only)", "expectedOutput": "JSON formatted health data", "notes": "Default tests reputable servers. Use --type to specify category" }, { "command": "dns-switch health --type encrypted --json", "description": "Test encrypted DNS servers with JSON output for parsing", "expectedOutput": "JSON object with detailed health metrics per server", "notes": "Structured JSON output for automation and integration" }, { "command": "dns-switch health --fresh --save --json", "description": "Fresh health check, save results, JSON output", "expectedOutput": "Real-time health check saved to database in JSON", "notes": "Bypasses cache for current data, persists to database" } ], "id": "4_dns_health_checking", "title": "DNS Health Checking" }, { "description": "Automation-friendly JSON responses", "examples": [ { "command": "dns-switch status --json", "description": "Get status in JSON format", "expectedOutput": "JSON object with current DNS configuration" }, { "command": "dns-switch count --json --json-pretty", "description": "Pretty-printed DNS server counts", "expectedOutput": "Formatted JSON with server statistics" }, { "command": "dns-switch status --json-human", "description": "Human-readable JSON with enhanced formatting", "expectedOutput": "JSON object with improved readability and structure" } ], "id": "5_json_output", "title": "JSON Output" }, { "description": "Switch DNS servers using provider names", "examples": [ { "command": "sudo dns-switch switch --names cloudflare", "description": "Switch to Cloudflare DNS (1.1.1.1)", "expectedOutput": "DNS changed to Cloudflare servers" }, { "command": "sudo dns-switch switch --names cloudflare --verify", "description": "Switch to Cloudflare DNS after verifying it's working", "expectedOutput": "DNS changed to Cloudflare servers (verified working)", "notes": "Health check performed before applying DNS change" }, { "command": "sudo dns-switch switch --names cloudflare QuadServer1", "description": "Switch to Cloudflare and Quad9 DNS servers (space-separated)", "expectedOutput": "DNS changed to multiple providers", "notes": "Multiple names separated by spaces" }, { "command": "sudo dns-switch switch --names cloudflare,QuadServer1,adguard", "description": "Switch to multiple DNS providers (comma-separated)", "expectedOutput": "DNS changed to Cloudflare, Quad9, and AdGuard servers", "notes": "Alternative syntax using commas to separate names" }, { "command": "sudo dns-switch switch --names cloudflare QuadServer1 adguard --verify", "description": "Switch to multiple DNS providers after verifying each works", "expectedOutput": "DNS changed to only verified working servers", "notes": "Only working servers will be applied to resolv.conf" }, { "command": "sudo dns-switch switch --names adguard", "description": "Switch to AdGuard DNS (94.140.14.14, 94.140.15.15) - Privacy-respecting", "expectedOutput": "DNS changed to AdGuard servers", "notes": "Blocks ads and trackers" }, { "command": "sudo dns-switch switch --names opendns", "description": "Switch to OpenDNS (208.67.222.222, 208.67.220.220)", "expectedOutput": "DNS changed to OpenDNS servers" }, { "command": "sudo dns-switch switch --names nextdns", "description": "Switch to NextDNS (45.90.28.167, 45.90.30.167)", "expectedOutput": "DNS changed to NextDNS servers" }, { "command": "sudo dns-switch switch --names cleanbrowsing", "description": "Switch to CleanBrowsing DNS (185.228.168.9, 185.228.169.9)", "expectedOutput": "DNS changed to CleanBrowsing servers", "notes": "Family-friendly content filtering" } ], "id": "6_dns_switching_by_names", "title": "DNS Switching by Names" }, { "description": "Switch DNS servers using IP addresses", "examples": [ { "command": "sudo dns-switch switch --servers 1.1.1.1", "description": "Switch to specific DNS server IP", "expectedOutput": "DNS changed to specified IP" }, { "command": "sudo dns-switch switch --servers 1.1.1.1 --verify", "description": "Switch to specific DNS server IP after verifying it works", "expectedOutput": "DNS changed to specified IP (verified working)", "notes": "Health check ensures DNS server is responsive before applying" }, { "command": "sudo dns-switch switch --servers 1.1.1.1 9.9.9.9", "description": "Switch to multiple specific DNS server IPs", "expectedOutput": "DNS changed to multiple IPs" }, { "command": "sudo dns-switch switch --servers 1.1.1.1 9.9.9.9 8.8.8.8 --verify", "description": "Switch to multiple DNS IPs after verifying each works", "expectedOutput": "DNS changed to only verified working IPs", "notes": "Failed servers are excluded from final configuration" }, { "command": "sudo dns-switch switch --servers 94.140.14.14 94.140.15.15", "description": "Switch to AdGuard DNS by IP", "expectedOutput": "DNS changed to AdGuard IPs" } ], "id": "7_dns_switching_by_ip", "title": "DNS Switching by IP" }, { "description": "Discover and fetch new DNS servers from remote sources", "examples": [ { "command": "dns-switch fetch", "description": "Fetch 25 DNS servers from remote sources, test them, and save to database", "expectedOutput": "Lists fetched servers with country, response time, and success/failure status", "notes": "Default fetches 25 servers" }, { "command": "sudo dns-switch fetch --count 50", "description": "Fetch exactly 50 DNS servers from remote sources", "expectedOutput": "Shows all 50 servers with test results and performance metrics", "notes": "Shows all results when count < 100" }, { "command": "dns-switch fetch --count 100", "description": "Fetch exactly 100 DNS servers from remote sources", "expectedOutput": "100 DNS servers fetched and tested", "notes": "May take longer to complete" }, { "command": "sudo dns-switch fetch-count --count 35", "description": "Alternative syntax to fetch 35 servers (same as fetch --count 35)", "expectedOutput": "Lists all 35 fetched servers with detailed information", "notes": "fetch-count is an alias for fetch with --count" }, { "command": "dns-switch fetch --all", "description": "Fetch ALL available DNS servers from remote sources", "expectedOutput": "Fetches hundreds of servers, shows truncated list with summary", "notes": "Note: Use kitty terminal to see country flags. Total servers > 60,000 so this will take very long to test all servers" }, { "command": "sudo dns-switch fetch --count 35 --fresh", "description": "Force fresh fetch bypassing ALL caches (API cache, result cache, etc.)", "expectedOutput": "Real-time fetch with no cached data used", "notes": "--fresh ensures completely new data from remote sources" }, { "command": "sudo dns-switch fetch --json", "description": "Fetch 25 servers with JSON output", "expectedOutput": "JSON response with fetched server details" }, { "command": "sudo dns-switch fetch --count 35 --fresh --json", "description": "Fresh fetch 35 servers with JSON output", "expectedOutput": "JSON response with fresh server data" }, { "command": "sudo dns-switch fetch --all --json", "description": "Fetch all servers with JSON output for processing", "expectedOutput": "Complete JSON dataset of all servers" }, { "command": "sudo dns-switch fetch-dns-from-card", "description": "Fetch remote DNSCrypt servers from authentication card", "expectedOutput": "Adds DNSCrypt servers from VPS to encrypted category", "notes": "Requires valid authentication with online-auth" } ], "id": "8_remote_dns_fetching", "title": "Remote DNS Discovery & Fetching" }, { "description": "Encrypted DNS and ad-blocking integration", "examples": [ { "command": "sudo dns-switch switch --names dnscrypt", "description": "Switch DNS to use local DNSCrypt (127.0.0.1)", "expectedOutput": "DNS set to use DNSCrypt proxy, service started if needed", "notes": "Automatically starts dnscrypt-proxy service if not running. Aliases: dnscrypt | dnscrypt-server | dnscryptproxy | encrypted" }, { "command": "sudo dns-switch dnscrypt", "description": "Check DNSCrypt proxy service status", "expectedOutput": "Shows if DNSCrypt is running, configured resolver, and port" }, { "command": "sudo dns-switch dnscrypt-set --resolver cloudflare", "description": "Configure DNSCrypt to use Cloudflare's encrypted resolver", "expectedOutput": "DNSCrypt configured and started with Cloudflare resolver", "notes": "Requires dnscrypt-proxy package installed" }, { "command": "sudo dns-switch dnscrypt-restart", "description": "Restart DNSCrypt proxy service", "expectedOutput": "DNSCrypt proxy service restarted successfully" }, { "command": "sudo dns-switch enable-dnscrypt-monitor", "description": "Install and enable the systemd timer that auto-recovers DNSCrypt and falls back to safe DNS on failure", "expectedOutput": "DNSCrypt auto-recovery monitor timer installed and started", "notes": "Runs periodic health checks; on failure restarts DNSCrypt or falls back to safe DNS" }, { "command": "dns-switch dnscrypt-monitor-status", "description": "Show whether the DNSCrypt auto-recovery monitor timer is active", "expectedOutput": "Reports the timer as active or inactive plus the last check state" }, { "command": "sudo dns-switch dnscrypt-monitor-check", "description": "Run a single DNSCrypt monitor check now (the same check the timer performs)", "expectedOutput": "Reports 'check passed', or triggers recovery/fallback on failure", "notes": "Safe to invoke manually; used internally by the auto-recovery timer" }, { "command": "sudo dns-switch disable-dnscrypt-monitor", "description": "Disable and remove the DNSCrypt auto-recovery timer", "expectedOutput": "DNSCrypt auto-recovery monitor timer stopped and removed" }, { "command": "sudo dns-switch dnscrypt-remove", "description": "Stop DNSCrypt and switch to reputable DNS servers", "expectedOutput": "DNSCrypt stopped and DNS switched to regular servers", "notes": "Automatically switches to reputable DNS to avoid DNS being offline" }, { "command": "sudo dns-switch switch --names RemoteDNSCryptIPv4", "description": "Switch to remote DNSCrypt IPv4 server from authentication card", "expectedOutput": "DNS switched to remote DNSCrypt IPv4 server from VPS", "notes": "Requires running 'fetch-dns-from-card' first to add remote servers" }, { "command": "sudo dns-switch switch --names RemoteDNSCryptIPv6", "description": "Switch to remote DNSCrypt IPv6 server from authentication card", "expectedOutput": "DNS switched to remote DNSCrypt IPv6 server from VPS", "notes": "Requires running 'fetch-dns-from-card' first to add remote servers" }, { "command": "sudo dns-switch switch --names RemoteDNSCryptIPv4,RemoteDNSCryptIPv6", "description": "Switch to both remote DNSCrypt servers (comma-separated)", "expectedOutput": "DNS switched to use both remote DNSCrypt servers for dual-stack support", "notes": "Comma-separated format - both IPv4 and IPv6 from your VPS" }, { "command": "sudo dns-switch switch --names RemoteDNSCryptIPv4 RemoteDNSCryptIPv6", "description": "Switch to both remote DNSCrypt servers (space-separated)", "expectedOutput": "DNS switched to use both remote DNSCrypt servers for dual-stack support", "notes": "Space-separated format - alternative syntax for multiple servers" }, { "command": "sudo dns-switch pihole", "description": "Check Pi-hole service status with systemctl info", "expectedOutput": "Shows if Pi-hole is running, blocking status, and systemctl_status", "notes": "Use 'systemctl status pihole-FTL.service' to verify service state directly" }, { "command": "sudo dns-switch pihole-enable", "description": "Enable Pi-hole ad blocking DNS with automatic DNSCrypt integration", "expectedOutput": "DNS redirected through Pi-hole for ad/tracker blocking\n → Pi-hole automatically uses DNSCrypt (127.0.0.1#5353) as upstream\n → You get encrypted DNS + ad blocking = maximum protection\n → Secure yet transparent - see what's blocked in Pi-hole web interface", "notes": "Pi-hole must be installed. DNSCrypt integration is automatic - no manual config needed!" }, { "command": "sudo dns-switch pihole-disable", "description": "Disable Pi-hole DNS filtering and stop the service", "expectedOutput": "Pi-hole service stopped and disabled from boot", "notes": "DNSCrypt continues independently if running. Use 'sudo dns-switch pihole-enable' to re-enable." }, { "command": "sudo dns-switch pihole-password --password NewSecurePassword123", "description": "Set Pi-hole web interface password (automatically unprotects TOML file)", "expectedOutput": "Pi-hole admin password updated. Protection restored on service restart.", "notes": "Note: To manually change password, run 'sudo chattr -i /etc/pihole/pihole.toml' first" }, { "command": "sudo dns-switch pihole-reset", "description": "Reset Pi-hole configuration to a clean state", "expectedOutput": "Pi-hole configuration reset", "notes": "Pi-hole must be installed. Use 'pihole-enable' afterwards to re-apply Kodachi's DNSCrypt-upstream integration." } ], "id": "9_dnscrypt_and_pihole", "title": "DNSCrypt & Pi-hole Integration" }, { "description": "Manage DNS database, backups, and cleanup", "examples": [ { "command": "sudo dns-switch clean", "description": "Remove duplicate DNS entries and clean temporary files from database", "expectedOutput": "Reports which temporary files were cleaned and how many duplicates removed" }, { "command": "sudo dns-switch clean-duplicates", "description": "Alternative command to remove duplicate entries", "expectedOutput": "Same as 'clean' - removes duplicate DNS entries" }, { "command": "sudo dns-switch flush-cache", "description": "Flush systemd-resolved and nscd DNS caches to clear stale entries", "expectedOutput": "DNS resolver caches flushed", "notes": "Clears cached lookups so the next query hits the configured DNS servers fresh" }, { "command": "sudo dns-switch backup", "description": "Create timestamped backup of current DNS database (not system DNS config)", "expectedOutput": "Creates backup file of DNS database with timestamp", "notes": "Backs up dns-switch database only, not /etc/resolv.conf" }, { "command": "sudo dns-switch backup --json", "description": "Create user backup with JSON output", "expectedOutput": "JSON confirmation of backup operation" }, { "command": "sudo dns-switch restore-default", "description": "Reset DNS database to factory defaults and update system DNS", "expectedOutput": "Database restored to original state and system DNS updated", "notes": "Removes all custom configurations and applies default DNS" }, { "command": "sudo dns-switch restore-default --no-action", "description": "Preview restore to defaults without applying changes", "expectedOutput": "Shows what would be restored" }, { "command": "sudo dns-switch restore-backup", "description": "Restore DNS database from most recent backup (database only)", "expectedOutput": "Database restored from latest backup file", "notes": "Restores database backup, run 'switch' to apply to system" }, { "command": "sudo dns-switch restore-backup --no-action --json", "description": "Preview restore from backup in JSON format", "expectedOutput": "JSON preview of restore operation" } ], "id": "10_database_maintenance", "title": "Database Maintenance" }, { "description": "Test commands safely and get machine-readable output", "examples": [ { "command": "sudo dns-switch switch --names cloudflare --no-action", "description": "Preview what would happen without making changes", "expectedOutput": "Shows DNS servers that would be set without actually changing them", "notes": "Use --no-action to test any command safely" }, { "command": "sudo dns-switch random --type reputable --count 5 --no-action", "description": "Preview random DNS selection without applying", "expectedOutput": "Shows 5 servers that would be selected" }, { "command": "sudo dns-switch fallback --no-action", "description": "Preview fallback server switch without applying", "expectedOutput": "Shows fallback servers that would be used" }, { "command": "sudo dns-switch clean --no-action", "description": "Preview database cleanup without applying changes", "expectedOutput": "Shows duplicates that would be removed" }, { "command": "sudo dns-switch dnscrypt --no-action", "description": "Check what DNSCrypt operations would be performed", "expectedOutput": "Shows DNSCrypt configuration changes" }, { "command": "sudo dns-switch status --json --json-pretty", "description": "Get current DNS status in pretty-printed JSON", "expectedOutput": "Formatted JSON with indentation for readability" }, { "command": "dns-switch health --type reputable --json-human", "description": "Get health check results in enhanced JSON format", "expectedOutput": "JSON with human-readable formatting and metadata", "notes": "--json-human provides best of both worlds" }, { "command": "sudo dns-switch count --json-human", "description": "Get DNS server count statistics in enhanced JSON format", "expectedOutput": "JSON with human-readable formatting and metadata", "notes": "--json-human provides best of both worlds" } ], "id": "11_dry_run_and_json", "title": "Dry Run & JSON Output" }, { "description": "Manage DNS configuration modes: modern (systemd-resolved) vs legacy (/etc/resolv.conf)", "examples": [ { "command": "dns-switch get-mode", "description": "Check current DNS management mode", "expectedOutput": "Shows: modern (systemd-resolved) or legacy (/etc/resolv.conf)", "notes": "Displays mode health status and any configuration issues" }, { "command": "dns-switch get-mode --json", "description": "Get DNS mode in JSON format", "expectedOutput": "JSON with mode, systemd-resolved status, and health checks", "notes": "Includes resolv.conf symlink status and detected issues" }, { "command": "dns-switch detect-mode", "description": "Auto-detect recommended DNS mode for this system", "expectedOutput": "Recommends modern if systemd-resolved active, legacy otherwise", "notes": "Checks systemd-resolved installation and activity status" }, { "command": "dns-switch detect-mode --json", "description": "Get mode detection results in JSON", "expectedOutput": "JSON with detected mode, current mode, and recommendation" }, { "command": "sudo dns-switch set-mode --mode modern", "description": "Switch to modern mode (systemd-resolved)", "expectedOutput": "Enables systemd-resolved and configures /etc/resolv.conf as symlink", "notes": "Backs up existing resolv.conf, starts systemd-resolved if needed" }, { "command": "sudo dns-switch set-mode --mode legacy", "description": "Switch to legacy mode (/etc/resolv.conf)", "expectedOutput": "Converts /etc/resolv.conf to regular file, preserves current DNS", "notes": "Extracts current DNS from systemd-resolved before switching" }, { "command": "sudo dns-switch fix-dns", "description": "Auto-repair broken DNS configuration", "expectedOutput": "Fixes mode mismatches, broken symlinks, applies fallback DNS", "notes": "Emergency repair command for connectivity issues" }, { "command": "sudo dns-switch fix-dns --force", "description": "Run complete DNS repair sequence regardless of initial health", "expectedOutput": "Executes all repair stages, then validates DNS status", "notes": "Use after unstable DNS incidents or repeated resolver failures" }, { "command": "dns-switch get-modern-method", "description": "Check current systemd-resolved configuration method", "expectedOutput": "Shows: global, per-interface, networkmanager, or auto", "notes": "Only applies when in modern mode (systemd-resolved)" }, { "command": "dns-switch get-modern-method --json", "description": "Get systemd-resolved method in JSON", "expectedOutput": "JSON with method and description" }, { "command": "sudo dns-switch set-modern-method --method global", "description": "Set to global config method (RECOMMENDED)", "expectedOutput": "Configures /etc/systemd/resolved.conf - covers ALL interfaces", "notes": "Safest method - prevents DNS leaks on all network interfaces" }, { "command": "sudo dns-switch set-modern-method --method per-interface", "description": "Set to per-interface method", "expectedOutput": "Uses resolvectl dns - applies per network interface", "notes": "May miss virtual/VPN interfaces - use global method instead" }, { "command": "sudo dns-switch set-modern-method --method networkmanager", "description": "Set to NetworkManager method", "expectedOutput": "Uses nmcli for DNS configuration", "notes": "Only for NetworkManager-managed systems" }, { "command": "sudo dns-switch set-modern-method --method auto", "description": "Set to auto with smart fallback chain", "expectedOutput": "Tries global → per-interface → networkmanager automatically", "notes": "Automatically selects best available method" }, { "command": "dns-switch verify-no-leaks", "description": "Check for DNS leaks across all network interfaces", "expectedOutput": "Reports any interfaces with unexpected DNS servers", "notes": "Essential for privacy - detects DNS configuration bypasses" }, { "command": "dns-switch verify-no-leaks --json", "description": "Get DNS leak detection results in JSON", "expectedOutput": "JSON with leaked interfaces list and expected DNS servers", "notes": "Use after switching DNS to verify no leaks occurred" } ], "id": "12_dns_mode_management", "title": "DNS Mode Management (Modern vs Legacy)" }, { "description": "Manage automatic DNS checking and fixing on system boot", "examples": [ { "command": "dns-switch boot-check", "description": "Manually check and fix DNS configuration (same as boot-time check)", "expectedOutput": "Reports DNS status and fixes empty/invalid nameservers if needed", "notes": "Uses configuration-based fallback servers, never hardcoded values" }, { "command": "sudo dns-switch enable-boot-check", "description": "Enable automatic DNS checking on system boot", "expectedOutput": "Creates and enables systemd service for boot-time DNS validation", "notes": "Ensures DNS is always configured correctly after system restart" }, { "command": "sudo dns-switch disable-boot-check", "description": "Disable automatic DNS checking on system boot", "expectedOutput": "Removes systemd service for boot-time DNS validation", "notes": "DNS configuration will not be automatically checked on boot" }, { "command": "systemctl status dns-boot-check.service", "description": "Check status of the boot-check systemd service", "expectedOutput": "Shows if boot-check service is enabled and its last run status", "notes": "Useful for verifying boot-check is working correctly" } ], "id": "13_boot_check_management", "title": "Boot-Time DNS Check Management" }, { "description": "Enable DNSSEC signature validation and DoH (DNS-over-HTTPS, dnscrypt-proxy's TLS-encrypted protocol — functionally equivalent to DoT) on top of DNSCrypt.", "examples": [ { "command": "sudo dns-switch dnssec-on", "description": "Enable DNSSEC validation in dnscrypt-proxy.toml; restart dnscrypt-proxy. Earns +0.1 dns_privacy score.", "expectedOutput": "require_dnssec=true; service restarted", "notes": "DNSCrypt-proxy must be installed. Falls back to plain DNS if upstream doesn't sign." }, { "command": "sudo dns-switch dnssec-off", "description": "Disable DNSSEC validation (default state).", "expectedOutput": "require_dnssec=false; service restarted" }, { "command": "sudo dns-switch dot-on", "description": "Enable DoH (TLS-encrypted DNS protocol) in dnscrypt-proxy.toml; restart service. Earns +0.2 dns_privacy score.", "expectedOutput": "doh_servers=true; service restarted", "notes": "DoH is dnscrypt-proxy's equivalent to DoT (port 443 / encrypted). On Kodachi the encryption layer is dnscrypt-proxy, not systemd-resolved." }, { "command": "sudo dns-switch dot-off", "description": "Disable DoH; dnscrypt-proxy reverts to DNSCrypt-only protocol.", "expectedOutput": "doh_servers=false; service restarted" } ], "id": "14_dnssec_and_dot", "title": "DNSSEC validation & DNS-over-HTTPS (DoT-equivalent)" }, { "description": "Let a third-party VPN GUI manage DNS. Kodachi locks /etc/resolv.conf immutable for DNS-leak protection, which prevents such clients from setting their tunnel DNS — they fail with \"internet blocked\" / \"failed to set system DNS\". Hand DNS to the client before connecting, then take it back when done.", "examples": [ { "command": "sudo dns-switch external-dns --state on", "description": "Unlock /etc/resolv.conf and pause Kodachi DNS protection (immutable lock + boot-check) so the VPN GUI can set its tunnel DNS. Run BEFORE connecting Mullvad/ProtonVPN.", "expectedOutput": "External-DNS mode ENABLED: /etc/resolv.conf unlocked and Kodachi DNS protection paused.", "notes": "While ON, Kodachi's DNS-leak immutable lock is paused — your VPN client must enforce its own leak protection (Mullvad/ProtonVPN do). Pi-hole cannot be enabled while this is ON." }, { "command": "sudo dns-switch external-dns --state off", "description": "Remove the handover marker and re-apply Kodachi-managed, locked DNS. Disconnect the VPN client first.", "expectedOutput": "External-DNS mode DISABLED: DNS management returned to Kodachi." }, { "command": "dns-switch external-dns --state status", "description": "Show whether a third-party VPN currently owns DNS (read-only; no sudo).", "expectedOutput": "External-DNS mode: ON|OFF — ..." } ], "id": "15_external_vpn_dns", "title": "External VPN DNS handover (Mullvad, ProtonVPN, etc.)" } ], "description": "Comprehensive usage examples for dns-switch DNS management", "name": "dns-switch", "quickReference": [ "dns-switch --help", "dns-switch --version", "dns-switch --info", "dns-switch --examples", "dns-switch status", "sudo dns-switch switch --category reputable", "dns-switch health", "dns-switch list --category all --json" ] }, "errors": [], "metadata": { "executionTime": 0, "hostname": "REDACTED-BUILD-HOST", "user": "REDACTED-BUILD-USER" }, "status": "success", "timestamp": "2026-06-08T16:22:05.241507115Z", "version": "9.0.1", "warnings": [] } } }