dns-switch
Production-ready DNS management with security and portability. A self-contained, portable DNS management tool with comprehensive security, health checking, and remote discovery capabilities.
File Information
| Property | Value |
|---|---|
| Binary Name | dns-switch |
| Version | 9.8.4 (build 320) |
| Build Date | Not disclosed |
| Rust Version | Not disclosed |
| File Size | 6.6MB |
| Author | Warith Al Maawali |
| License | Proprietary |
| Category | Kodachi Binary |
| Description | Production-ready DNS management with security and portability. A self-contained, portable DNS management tool with compr... |
| Git Commit | unknown |
| Metadata Generated | 2026-07-11T18:16:25Z |
| Binary Timestamp | Unknown |
| JSON Data | View Raw JSON |
SHA256 Checksum
28f2f3eb224fa80e79eab1a5e698c80af9f21e43cecf99fee78370f9c190a0a2
Features
| # | Feature |
|---|---|
| 1 | Embedded DNS server lists (no external config dependencies) |
| 2 | Dynamic path detection (works in any directory) |
| 3 | Comprehensive input validation and sanitization |
| 4 | JSON output support for automation |
| 5 | Health monitoring and performance testing |
| 6 | Remote DNS server discovery and testing |
| 7 | Security-focused design with privilege checking |
| 8 | DNSCrypt proxy integration |
| 9 | Pi-hole DNS filter integration |
| 10 | Automatic backup and restore capabilities |
Security Features
| Feature | Description |
|---|---|
| Authentication | Integrated with Kodachi authentication system |
| Encryption | Supports DNSCrypt for encrypted DNS queries |
| Input Validation | All inputs sanitized and validated before use |
| Rate Limiting | Built-in rate limiting for remote operations |
System Requirements
| Requirement | Value |
|---|---|
| OS | Linux (Debian-based) |
| Privileges | root/sudo for system changes |
| Dependencies | systemd-resolved or resolvconf, DNSCrypt proxy (optional), Pi-hole (optional) |
Global Options
| Flag | Description |
|---|---|
-h, --help |
Print help information |
-v, --version |
Print version information |
-n, --info |
Display detailed information |
-e, --examples |
Show usage examples |
--json |
Output in JSON format |
-o, --output-format <FORMAT> |
Force output format (text|json) |
--verbose |
Enable verbose output |
--quiet |
Suppress non-essential output |
--no-color |
Disable colored output |
--timeout <SECS> |
Set timeout (default: 30) |
--retry <COUNT> |
Retry attempts (default: 3) |
--config <FILE> |
Use custom configuration file |
--json-pretty |
Pretty-print JSON output |
--json-human |
Enhanced JSON output with improved formatting (like jq) |
--fields <FIELDS> |
Select specific fields to include |
--limit <NUMBER> |
Limit number of results |
--offset <NUMBER> |
Skip first N results |
--work-dir <DIR> |
Specify working directory |
--no-action |
Dry run mode |
--log-level <LEVEL> |
Set logging verbosity (error|warn|info|debug|trace) |
Commands
DNS Management
switch
Switch DNS to a specific category or provider
Usage:
dns-switch switch [OPTIONS]
Options:
--category <CATEGORY>: DNS category (reputable|normal|encrypted|fallback|all)--provider <NAME>: Specific DNS provider name--names <NAMES>: Switch DNS by server names (e.g., cloudflare, adguard)--servers <IPS>: Switch DNS by server IP addresses
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
random
Switch to random DNS servers with advanced selection
Usage:
dns-switch random [OPTIONS]
Options:
--type <TYPE>: 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.--count <COUNT>: Number of random DNS servers to select
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
fallback
Switch to fallback DNS servers
Usage:
dns-switch fallback
Examples:
sudo dns-switch fallback
status
Show current DNS configuration
Usage:
dns-switch status
Examples:
dns-switch status
dns-switch status --json
DNS Mode Management
get-mode
Show current DNS management mode (modern vs legacy)
Usage:
dns-switch get-mode
Examples:
dns-switch get-mode
dns-switch get-mode --json
set-mode
Set DNS management mode (modern=systemd-resolved, legacy=/etc/resolv.conf)
Usage:
dns-switch set-mode --mode <modern|legacy>
Options:
--mode <MODE>: DNS mode: 'modern' (systemd-resolved) or '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
detect-mode
Auto-detect recommended DNS mode for this system
Usage:
dns-switch detect-mode
Examples:
dns-switch detect-mode
dns-switch detect-mode --json
fix-dns
Repair broken DNS configuration (mode mismatches, broken symlinks, etc.) — also accepts the legacy alias 'dns-fix'
Usage:
dns-switch fix-dns
Options:
--force: Run all repair stages even if DNS appears healthy
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
get-modern-method
Show which method systemd-resolved uses (global / per-interface / networkmanager / auto)
Usage:
dns-switch get-modern-method
Examples:
dns-switch get-modern-method
dns-switch get-modern-method --json
set-modern-method
Set systemd-resolved DNS application method (only relevant in modern mode)
Usage:
dns-switch set-modern-method --method <global|per-interface|networkmanager|auto>
Options:
--method <METHOD>: global (resolved.conf, safest), per-interface (resolvectl), networkmanager (nmcli), or auto
Examples:
sudo dns-switch set-modern-method --method global
sudo dns-switch set-modern-method --method auto
external-dns
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.
Usage:
dns-switch external-dns --state <on|off|status>
Options:
--state <STATE>: 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)
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.
Health & Discovery
health
Check health of DNS servers with detailed analysis (read-only by default)
Usage:
dns-switch health [OPTIONS]
Options:
--type <TYPE>: Test specific type (reputable|normal|encrypted|fallback|all)--full: Perform comprehensive health check--fresh: Force fresh health check, bypassing cache--save: Save health check results to database (default: read-only, no database changes)--force-move: BYPASS 3-strike rule: move failed servers to 'failed' category IMMEDIATELY (requires --save). Use for urgent cleanup or known-bad servers
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
fetch
Fetch and test remote DNS servers with advanced options
Usage:
dns-switch fetch [OPTIONS]
Options:
--save: Save results to database--all: Fetch all available DNS servers (instead of default 25)--count <NUM>: Specify number of DNS servers to fetch--fresh: Force fresh data retrieval, bypassing all caches--history: Show fetch history--load <CACHE_ID>: Load cached results
Examples:
dns-switch fetch
dns-switch fetch --save
dns-switch fetch --count 100
dns-switch fetch --all
dns-switch fetch --fresh --json
fetch-count
Fetch a specific number of DNS servers from remote sources
Usage:
dns-switch fetch-count [OPTIONS]
Options:
--count <NUM>: Number of DNS servers to fetch--fresh: Force fresh data retrieval, bypassing caches
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
fetch-dns-from-card
Pull DNSCrypt and Tor DNS servers from your authenticated Kodachi card into the local DB (encrypted category)
Usage:
dns-switch fetch-dns-from-card
Examples:
sudo dns-switch fetch-dns-from-card
# Requires a valid online-auth session (run 'sudo online-auth authenticate' first)
DNSCrypt Management
dnscrypt
Show DNSCrypt status
Usage:
dns-switch dnscrypt
Examples:
dns-switch dnscrypt
dnscrypt-set
Enable DNSCrypt with specific resolver
Usage:
dns-switch dnscrypt-set --resolver <NAME>
Options:
--resolver <NAME>: DNSCrypt resolver name
Examples:
sudo dns-switch dnscrypt-set --resolver cloudflare
dnscrypt-restart
Restart DNSCrypt proxy
Usage:
dns-switch dnscrypt-restart
Examples:
sudo dns-switch dnscrypt-restart
dnscrypt-remove
Remove DNSCrypt configuration
Usage:
dns-switch dnscrypt-remove
Examples:
sudo dns-switch dnscrypt-remove
dnscrypt-monitor-status
Show whether the DNSCrypt auto-recovery monitor timer is active
Usage:
dns-switch dnscrypt-monitor-status
Examples:
dns-switch dnscrypt-monitor-status
dnscrypt-monitor-check
Run a single monitor check now (used by the timer; safe to invoke manually)
Usage:
dns-switch dnscrypt-monitor-check
Examples:
sudo dns-switch dnscrypt-monitor-check
enable-dnscrypt-monitor
Install and enable the systemd timer that auto-recovers DNSCrypt and falls back to safe DNS on failure
Usage:
dns-switch enable-dnscrypt-monitor
Examples:
sudo dns-switch enable-dnscrypt-monitor
disable-dnscrypt-monitor
Disable and remove the DNSCrypt auto-recovery timer
Usage:
dns-switch disable-dnscrypt-monitor
Examples:
sudo dns-switch disable-dnscrypt-monitor
dnssec-on
Enable DNSSEC signature validation (require_dnssec=true) in dnscrypt-proxy.toml and restart dnscrypt-proxy. Earns +0.1 dns_privacy score
Usage:
dns-switch dnssec-on
Examples:
sudo dns-switch dnssec-on
dnssec-off
Disable DNSSEC validation (require_dnssec=false, default state) in dnscrypt-proxy.toml and restart dnscrypt-proxy
Usage:
dns-switch dnssec-off
Examples:
sudo dns-switch dnssec-off
dot-on
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
Usage:
dns-switch dot-on
Examples:
sudo dns-switch dot-on
dot-off
Disable DoH (doh_servers=false) in dnscrypt-proxy.toml; dnscrypt-proxy reverts to DNSCrypt-only protocol and restarts
Usage:
dns-switch dot-off
Examples:
sudo dns-switch dot-off
Boot & Leak Protection
boot-check
One-shot DNS health probe (used at boot to detect and repair empty or broken nameservers)
Usage:
dns-switch boot-check
Examples:
sudo dns-switch boot-check
sudo dns-switch boot-check --json
enable-boot-check
Install the systemd service that runs boot-check on every boot (requires auth)
Usage:
dns-switch enable-boot-check
Examples:
sudo dns-switch enable-boot-check
disable-boot-check
Remove the boot-time DNS validation systemd service (requires auth)
Usage:
dns-switch disable-boot-check
Examples:
sudo dns-switch disable-boot-check
verify-no-leaks
Report any interface with DNS servers different from the expected system DNS (per-interface leak detection)
Usage:
dns-switch verify-no-leaks
Examples:
dns-switch verify-no-leaks
dns-switch verify-no-leaks --json
Pi-hole Integration
pihole
Show Pi-hole status
Usage:
dns-switch pihole
Examples:
dns-switch pihole
pihole-enable
Enable Pi-hole DNS filtering
Usage:
dns-switch pihole-enable
Examples:
sudo dns-switch pihole-enable
pihole-disable
Disable Pi-hole DNS filtering
Usage:
dns-switch pihole-disable
Examples:
sudo dns-switch pihole-disable
pihole-password
Set Pi-hole web interface password (auto-handles file protection)
Usage:
dns-switch pihole-password --password <PASSWORD>
Options:
--password <PASSWORD>: New password for Pi-hole web interface (TOML file auto-unprotected)
Examples:
sudo dns-switch pihole-password --password MyNewPassword
# Note: To manually change password, first run: sudo chattr -i /etc/pihole/pihole.toml
pihole-reset
Reset Pi-hole configuration
Usage:
dns-switch pihole-reset
Examples:
sudo dns-switch pihole-reset
Information & Utilities
list
List available DNS servers
Usage:
dns-switch list --category <CATEGORY>
Options:
--category <CATEGORY>: Category to list (reputable|normal|encrypted|fallback|remotely_fetched|all)
Examples:
dns-switch list --category reputable
dns-switch list --category encrypted
dns-switch list --category remotely_fetched
count
Count DNS servers by category
Usage:
dns-switch count
Examples:
dns-switch count
dns-switch count --json
Maintenance & Recovery
clean
Clean temporary files and cache
Usage:
dns-switch clean
Examples:
dns-switch clean
clean-duplicates
Clean duplicate DNS entries from database
Usage:
dns-switch clean-duplicates
Examples:
sudo dns-switch clean-duplicates
sudo dns-switch clean-duplicates --json
sudo dns-switch clean-duplicates --no-action
flush-cache
Flush systemd-resolved and nscd DNS caches to clear stale entries
Usage:
sudo dns-switch flush-cache
Examples:
sudo dns-switch flush-cache
sudo dns-switch flush-cache --json
backup
Create DNS configuration backup
Usage:
dns-switch backup
Examples:
dns-switch backup
restore-default
Restore default DNS configuration
Usage:
dns-switch restore-default
Examples:
sudo dns-switch restore-default
restore-backup
Restore from backup
Usage:
dns-switch restore-backup [--file <FILE>]
Options:
--file <FILE>: Backup file to restore
Examples:
sudo dns-switch restore-backup
sudo dns-switch restore-backup --file backup.json
Operational Scenarios
Scenario-oriented workflows generated from the binary's built-in -e --json examples.
Scenario 1: DNS Status & Information
Check current DNS configuration and available servers
Step 1: Display current system DNS servers with detailed information
dns-switch status
Step 2: Get DNS status in machine-readable JSON format
dns-switch status --json
Note
Useful for scripting and automation
Step 3: Count available DNS servers by category (reputable, normal, encrypted, etc.)
dns-switch count
Step 4: List all reputable DNS servers with details
dns-switch list --category reputable
Scenario 2: Basic DNS Switching
Switch DNS servers using different selection methods
Step 1: Switch to first available reputable DNS servers from the database
sudo dns-switch switch --category reputable
Step 2: Switch to specific DNS providers by name
sudo dns-switch switch --names cloudflare adguard
Step 3: Switch to specific DNS servers by IP address
sudo dns-switch switch --servers 1.1.1.1 9.9.9.9
Note
Useful when you know exact server IPs
Step 4: Switch to hardcoded fallback DNS servers for emergencies
sudo dns-switch fallback
Note
Use when database is corrupted or unavailable
Scenario 3: Random DNS Selection
Randomly select DNS servers from different categories
Step 1: Select 3 random DNS servers from reputable category (default behavior)
sudo dns-switch random
Step 2: Select 3 random reputable DNS servers and verify they work before applying
sudo dns-switch random --verify
Note
Only applies servers that pass health check
Step 3: Select 3 random reputable DNS servers and verify each works before applying
sudo dns-switch random --type reputable --verify
Note
Health checks each selected server; only uses working ones
Step 4: Select 5 random servers from normal category
sudo dns-switch random --type normal --count 5
Step 5: Select 6 random normal DNS servers and verify they work before applying
sudo dns-switch random --type normal --count 6 --verify
Note
If some servers fail health check, only working ones are used
Step 6: Select 6 servers: 3 from reputable + 3 from normal categories
sudo dns-switch random --type reputable,normal --count 6
Note
Count is distributed evenly across specified types
Step 7: Select 7 servers distributed: 4 reputable + 3 normal
sudo dns-switch random --type reputable,normal --count 7
Note
Uneven distribution favors first type
Step 8: Select 3 servers each from reputable, normal, and remotely_fetched (9 total)
sudo dns-switch random --type all
Note
'all' excludes encrypted and fallback categories
Step 9: Select 6 servers distributed: 3 reputable + 3 normal (alternate syntax)
sudo dns-switch random --type reputable,normal --count-random 6
Note
--count-random is an alias for --count
Step 10: Select 6 servers distributed: 2 from each category
sudo dns-switch random --type reputable,normal,remotely_fetched --count-random 6
Step 11: Select 10 servers distributed: 4+3+3 from each category
sudo dns-switch random --type reputable,normal,remotely_fetched --count-random 10
Scenario 4: DNS Health Checking
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.
Step 1: Test reputable DNS servers (default) for availability and response times (read-only)
dns-switch health
Note
Read-only: does not modify the database
Step 2: Test reputable DNS servers only (read-only)
dns-switch health --type reputable
Note
Tests curated high-quality DNS providers. Read-only: does not modify database
Step 3: Test reputable servers and save results to database
dns-switch health --type reputable --save
Note
--save updates: status, response times, geolocation, consecutive_failures counter. Servers move to 'failed' category ONLY after 3 consecutive failures (run 3 times)
Step 4: Test normal DNS servers only (read-only)
dns-switch health --type normal
Note
Tests standard reliable DNS providers. Read-only mode
Step 5: Test encrypted DNS servers (DNSCrypt, DoH, DoT) only
dns-switch health --type encrypted
Note
Tests DNSCrypt and secure DNS providers. Read-only mode
Step 6: Check health of remotely fetched DNS servers (read-only)
dns-switch health --type remotely_fetched
Note
Tests servers previously discovered via 'fetch' command
Step 7: Test remotely fetched servers and save results to database
dns-switch health --type remotely_fetched --save
Note
3-STRIKE RULE: Servers move to 'failed' category only after 3 consecutive failures. Run this command 3 times to trigger category moves
Step 8: Test ALL working server categories (excludes failed servers)
dns-switch health --type all
Note
Tests: fallback + reputable + normal + encrypted + remotely_fetched. Excludes failed servers for efficiency. May take several minutes
Step 9: Test all working categories and save results to database
dns-switch health --type all --save
Note
Updates: status, response times, geolocation, consecutive_failures counter. 3-STRIKE RULE: Run 3 times to move failed servers to 'failed' category (prevents false positives)
Step 10: Run health check 3 times to trigger 3-strike rule and move failed servers
dns-switch health --type all --save && dns-switch health --type all --save && dns-switch health --type all --save
Note
WORKFLOW EXAMPLE: The 3-strike rule requires 3 consecutive failures before moving servers. Run 'count' after 3rd run to see category changes
Step 11: Test ONLY failed servers and update their status if recovered
dns-switch health --type failed --save
Note
Recovery is instant (1 success = move back). Tests servers from dns-database-failed.json. --save required to persist recovery
Step 12: BYPASS 3-strike rule: move failed servers to 'failed' category IMMEDIATELY
dns-switch health --type all --save --force-move
Note
⚠️ CAUTION: Bypasses protection against transient network issues. Use for urgent cleanup or when you're CERTAIN servers are permanently down. --save required
Step 13: Test remotely fetched servers and force-move failures immediately
dns-switch health --type remotely_fetched --save --force-move
Note
Useful for quickly cleaning up newly discovered servers that are non-responsive. Skips 3-strike protection
Step 14: Full health check with geolocation, save results
dns-switch health --full --save
Note
Full check includes geolocation lookup for all working servers
Step 15: Health check with JSON output (read-only)
dns-switch health --json
Note
Default tests reputable servers. Use --type to specify category
Step 16: Test encrypted DNS servers with JSON output for parsing
dns-switch health --type encrypted --json
Note
Structured JSON output for automation and integration
Step 17: Fresh health check, save results, JSON output
dns-switch health --fresh --save --json
Note
Bypasses cache for current data, persists to database
Scenario 5: JSON Output
Automation-friendly JSON responses
Step 1: Get status in JSON format
dns-switch status --json
Step 2: Pretty-printed DNS server counts
dns-switch count --json --json-pretty
Step 3: Human-readable JSON with enhanced formatting
dns-switch status --json-human
Scenario 6: DNS Switching by Names
Switch DNS servers using provider names
Step 1: Switch to Cloudflare DNS (1.1.1.1)
sudo dns-switch switch --names cloudflare
Step 2: Switch to Cloudflare DNS after verifying it's working
sudo dns-switch switch --names cloudflare --verify
Note
Health check performed before applying DNS change
Step 3: Switch to Cloudflare and Quad9 DNS servers (space-separated)
sudo dns-switch switch --names cloudflare QuadServer1
Note
Multiple names separated by spaces
Step 4: Switch to multiple DNS providers (comma-separated)
sudo dns-switch switch --names cloudflare,QuadServer1,adguard
Note
Alternative syntax using commas to separate names
Step 5: Switch to multiple DNS providers after verifying each works
sudo dns-switch switch --names cloudflare QuadServer1 adguard --verify
Note
Only working servers will be applied to resolv.conf
Step 6: Switch to AdGuard DNS (94.140.14.14, 94.140.15.15) - Privacy-respecting
sudo dns-switch switch --names adguard
Note
Blocks ads and trackers
Step 7: Switch to OpenDNS (208.67.222.222, 208.67.220.220)
sudo dns-switch switch --names opendns
Step 8: Switch to NextDNS (45.90.28.167, 45.90.30.167)
sudo dns-switch switch --names nextdns
Step 9: Switch to CleanBrowsing DNS (185.228.168.9, 185.228.169.9)
sudo dns-switch switch --names cleanbrowsing
Note
Family-friendly content filtering
Scenario 7: DNS Switching by IP
Switch DNS servers using IP addresses
Step 1: Switch to specific DNS server IP
sudo dns-switch switch --servers 1.1.1.1
Step 2: Switch to specific DNS server IP after verifying it works
sudo dns-switch switch --servers 1.1.1.1 --verify
Note
Health check ensures DNS server is responsive before applying
Step 3: Switch to multiple specific DNS server IPs
sudo dns-switch switch --servers 1.1.1.1 9.9.9.9
Step 4: Switch to multiple DNS IPs after verifying each works
sudo dns-switch switch --servers 1.1.1.1 9.9.9.9 8.8.8.8 --verify
Note
Failed servers are excluded from final configuration
Step 5: Switch to AdGuard DNS by IP
sudo dns-switch switch --servers 94.140.14.14 94.140.15.15
Scenario 8: Remote DNS Discovery & Fetching
Discover and fetch new DNS servers from remote sources
Step 1: Fetch 25 DNS servers from remote sources, test them, and save to database
dns-switch fetch
Note
Default fetches 25 servers
Step 2: Fetch exactly 50 DNS servers from remote sources
sudo dns-switch fetch --count 50
Note
Shows all results when count < 100
Step 3: Fetch exactly 100 DNS servers from remote sources
dns-switch fetch --count 100
Note
May take longer to complete
Step 4: Alternative syntax to fetch 35 servers (same as fetch --count 35)
sudo dns-switch fetch-count --count 35
Note
fetch-count is an alias for fetch with --count
Step 5: Fetch ALL available DNS servers from remote sources
dns-switch fetch --all
Note
Note: Use kitty terminal to see country flags. Total servers > 60,000 so this will take very long to test all servers
Step 6: Force fresh fetch bypassing ALL caches (API cache, result cache, etc.)
sudo dns-switch fetch --count 35 --fresh
Note
--fresh ensures completely new data from remote sources
Step 7: Fetch 25 servers with JSON output
sudo dns-switch fetch --json
Step 8: Fresh fetch 35 servers with JSON output
sudo dns-switch fetch --count 35 --fresh --json
Step 9: Fetch all servers with JSON output for processing
sudo dns-switch fetch --all --json
Step 10: Fetch remote DNSCrypt servers from authentication card
sudo dns-switch fetch-dns-from-card
Note
Requires valid authentication with online-auth
Scenario 9: DNSCrypt & Pi-hole Integration
Encrypted DNS and ad-blocking integration
Step 1: Switch DNS to use local DNSCrypt (127.0.0.1)
sudo dns-switch switch --names dnscrypt
Note
Automatically starts dnscrypt-proxy service if not running. Aliases: dnscrypt | dnscrypt-server | dnscryptproxy | encrypted
Step 2: Check DNSCrypt proxy service status
sudo dns-switch dnscrypt
Step 3: Configure DNSCrypt to use Cloudflare's encrypted resolver
sudo dns-switch dnscrypt-set --resolver cloudflare
Note
Requires dnscrypt-proxy package installed
Step 4: Restart DNSCrypt proxy service
sudo dns-switch dnscrypt-restart
Step 5: Install and enable the systemd timer that auto-recovers DNSCrypt and falls back to safe DNS on failure
sudo dns-switch enable-dnscrypt-monitor
Note
Runs periodic health checks; on failure restarts DNSCrypt or falls back to safe DNS
Step 6: Show whether the DNSCrypt auto-recovery monitor timer is active
dns-switch dnscrypt-monitor-status
Step 7: Run a single DNSCrypt monitor check now (the same check the timer performs)
sudo dns-switch dnscrypt-monitor-check
Note
Safe to invoke manually; used internally by the auto-recovery timer
Step 8: Disable and remove the DNSCrypt auto-recovery timer
sudo dns-switch disable-dnscrypt-monitor
Step 9: Stop DNSCrypt and switch to reputable DNS servers
sudo dns-switch dnscrypt-remove
Note
Automatically switches to reputable DNS to avoid DNS being offline
Step 10: Switch to remote DNSCrypt IPv4 server from authentication card
sudo dns-switch switch --names RemoteDNSCryptIPv4
Note
Requires running 'fetch-dns-from-card' first to add remote servers
Step 11: Switch to remote DNSCrypt IPv6 server from authentication card
sudo dns-switch switch --names RemoteDNSCryptIPv6
Note
Requires running 'fetch-dns-from-card' first to add remote servers
Step 12: Switch to both remote DNSCrypt servers (comma-separated)
sudo dns-switch switch --names RemoteDNSCryptIPv4,RemoteDNSCryptIPv6
Note
Comma-separated format - both IPv4 and IPv6 from your VPS
Step 13: Switch to both remote DNSCrypt servers (space-separated)
sudo dns-switch switch --names RemoteDNSCryptIPv4 RemoteDNSCryptIPv6
Note
Space-separated format - alternative syntax for multiple servers
Step 14: Check Pi-hole service status with systemctl info
sudo dns-switch pihole
Note
Use 'systemctl status pihole-FTL.service' to verify service state directly
Step 15: Enable Pi-hole ad blocking DNS with automatic DNSCrypt integration
sudo dns-switch pihole-enable
Note
Pi-hole must be installed. DNSCrypt integration is automatic - no manual config needed!
Step 16: Disable Pi-hole DNS filtering and stop the service
sudo dns-switch pihole-disable
Note
DNSCrypt continues independently if running. Use 'sudo dns-switch pihole-enable' to re-enable.
Step 17: Set Pi-hole web interface password (automatically unprotects TOML file)
sudo dns-switch pihole-password --password NewSecurePassword123
Note
Note: To manually change password, run 'sudo chattr -i /etc/pihole/pihole.toml' first
Step 18: Reset Pi-hole configuration to a clean state
sudo dns-switch pihole-reset
Note
Pi-hole must be installed. Use 'pihole-enable' afterwards to re-apply Kodachi's DNSCrypt-upstream integration.
Scenario 10: Database Maintenance
Manage DNS database, backups, and cleanup
Step 1: Remove duplicate DNS entries and clean temporary files from database
sudo dns-switch clean
Step 2: Alternative command to remove duplicate entries
sudo dns-switch clean-duplicates
Step 3: Flush systemd-resolved and nscd DNS caches to clear stale entries
sudo dns-switch flush-cache
Note
Clears cached lookups so the next query hits the configured DNS servers fresh
Step 4: Create timestamped backup of current DNS database (not system DNS config)
sudo dns-switch backup
Note
Backs up dns-switch database only, not /etc/resolv.conf
Step 5: Create user backup with JSON output
sudo dns-switch backup --json
Step 6: Reset DNS database to factory defaults and update system DNS
sudo dns-switch restore-default
Note
Removes all custom configurations and applies default DNS
Step 7: Preview restore to defaults without applying changes
sudo dns-switch restore-default --no-action
Step 8: Restore DNS database from most recent backup (database only)
sudo dns-switch restore-backup
Note
Restores database backup, run 'switch' to apply to system
Step 9: Preview restore from backup in JSON format
sudo dns-switch restore-backup --no-action --json
Scenario 11: Dry Run & JSON Output
Test commands safely and get machine-readable output
Step 1: Preview what would happen without making changes
sudo dns-switch switch --names cloudflare --no-action
Note
Use --no-action to test any command safely
Step 2: Preview random DNS selection without applying
sudo dns-switch random --type reputable --count 5 --no-action
Step 3: Preview fallback server switch without applying
sudo dns-switch fallback --no-action
Step 4: Preview database cleanup without applying changes
sudo dns-switch clean --no-action
Step 5: Check what DNSCrypt operations would be performed
sudo dns-switch dnscrypt --no-action
Step 6: Get current DNS status in pretty-printed JSON
sudo dns-switch status --json --json-pretty
Step 7: Get health check results in enhanced JSON format
dns-switch health --type reputable --json-human
Note
--json-human provides best of both worlds
Step 8: Get DNS server count statistics in enhanced JSON format
sudo dns-switch count --json-human
Note
--json-human provides best of both worlds
Scenario 12: DNS Mode Management (Modern vs Legacy)
Manage DNS configuration modes: modern (systemd-resolved) vs legacy (/etc/resolv.conf)
Step 1: Check current DNS management mode
dns-switch get-mode
Note
Displays mode health status and any configuration issues
Step 2: Get DNS mode in JSON format
dns-switch get-mode --json
Note
Includes resolv.conf symlink status and detected issues
Step 3: Auto-detect recommended DNS mode for this system
dns-switch detect-mode
Note
Checks systemd-resolved installation and activity status
Step 4: Get mode detection results in JSON
dns-switch detect-mode --json
Step 5: Switch to modern mode (systemd-resolved)
sudo dns-switch set-mode --mode modern
Note
Backs up existing resolv.conf, starts systemd-resolved if needed
Step 6: Switch to legacy mode (/etc/resolv.conf)
sudo dns-switch set-mode --mode legacy
Note
Extracts current DNS from systemd-resolved before switching
Step 7: Auto-repair broken DNS configuration
sudo dns-switch fix-dns
Note
Emergency repair command for connectivity issues
Step 8: Run complete DNS repair sequence regardless of initial health
sudo dns-switch fix-dns --force
Note
Use after unstable DNS incidents or repeated resolver failures
Step 9: Check current systemd-resolved configuration method
dns-switch get-modern-method
Note
Only applies when in modern mode (systemd-resolved)
Step 10: Get systemd-resolved method in JSON
dns-switch get-modern-method --json
Step 11: Set to global config method (RECOMMENDED)
sudo dns-switch set-modern-method --method global
Note
Safest method - prevents DNS leaks on all network interfaces
Step 12: Set to per-interface method
sudo dns-switch set-modern-method --method per-interface
Note
May miss virtual/VPN interfaces - use global method instead
Step 13: Set to NetworkManager method
sudo dns-switch set-modern-method --method networkmanager
Note
Only for NetworkManager-managed systems
Step 14: Set to auto with smart fallback chain
sudo dns-switch set-modern-method --method auto
Note
Automatically selects best available method
Step 15: Check for DNS leaks across all network interfaces
dns-switch verify-no-leaks
Note
Essential for privacy - detects DNS configuration bypasses
Step 16: Get DNS leak detection results in JSON
dns-switch verify-no-leaks --json
Note
Use after switching DNS to verify no leaks occurred
Scenario 13: Boot-Time DNS Check Management
Manage automatic DNS checking and fixing on system boot
Step 1: Manually check and fix DNS configuration (same as boot-time check)
dns-switch boot-check
Note
Uses configuration-based fallback servers, never hardcoded values
Step 2: Enable automatic DNS checking on system boot
sudo dns-switch enable-boot-check
Note
Ensures DNS is always configured correctly after system restart
Step 3: Disable automatic DNS checking on system boot
sudo dns-switch disable-boot-check
Note
DNS configuration will not be automatically checked on boot
Step 4: Check status of the boot-check systemd service
systemctl status dns-boot-check.service
Note
Useful for verifying boot-check is working correctly
Scenario 14: DNSSEC validation & DNS-over-HTTPS (DoT-equivalent)
Enable DNSSEC signature validation and DoH (DNS-over-HTTPS, dnscrypt-proxy's TLS-encrypted protocol — functionally equivalent to DoT) on top of DNSCrypt.
Step 1: Enable DNSSEC validation in dnscrypt-proxy.toml; restart dnscrypt-proxy. Earns +0.1 dns_privacy score.
sudo dns-switch dnssec-on
Note
DNSCrypt-proxy must be installed. Falls back to plain DNS if upstream doesn't sign.
Step 2: Disable DNSSEC validation (default state).
sudo dns-switch dnssec-off
Step 3: Enable DoH (TLS-encrypted DNS protocol) in dnscrypt-proxy.toml; restart service. Earns +0.2 dns_privacy score.
sudo dns-switch dot-on
Note
DoH is dnscrypt-proxy's equivalent to DoT (port 443 / encrypted). On Kodachi the encryption layer is dnscrypt-proxy, not systemd-resolved.
Step 4: Disable DoH; dnscrypt-proxy reverts to DNSCrypt-only protocol.
sudo dns-switch dot-off
Scenario 15: External VPN DNS handover (Mullvad, ProtonVPN, etc.)
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.
Step 1: 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.
sudo dns-switch external-dns --state on
Note
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.
Step 2: Remove the handover marker and re-apply Kodachi-managed, locked DNS. Disconnect the VPN client first.
sudo dns-switch external-dns --state off
Step 3: Show whether a third-party VPN currently owns DNS (read-only; no sudo).
dns-switch external-dns --state status
Environment Variables
| Variable | Description | Default | Values |
|---|---|---|---|
RUST_LOG |
Set logging level | info | error|warn|info|debug|trace |
NO_COLOR |
Disable all colored output when set | unset | 1|true|yes (any value disables color) |
DNS_SWITCH_CONFIG |
Path to configuration file | ~/.config/dns-switch/config.json | /path/to/config.json |
Exit Codes
| Code | Description |
|---|---|
| 0 | Success |
| 1 | General error |
| 2 | Invalid arguments |
| 3 | Permission denied |
| 4 | Network error |
| 5 | File not found |
| 6 | Operation timeout |
| 7 | Authentication error |