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.

Version: 9.8.4 (build 319) | Size: 6.5MB | Author: Warith Al Maawali

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

File Information

Property	Value
Binary Name	dns-switch
Version	9.8.4 (build 319)
Build Date	REDACTED-BUILD-TIME
Rust Version
File Size	6.5MB
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-06-28T11:16:35Z
Binary Timestamp	Unknown
JSON Data	View Raw JSON

SHA256 Checksum

e712c42778ad834b6c791e7f82a1c936f5cf3894e0a24b8737bd0f161d24a466

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-human`	Enhanced JSON output (best of both worlds)
`--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

Expected Output: Shows active DNS servers, their IPs, and configuration source

Step 2: Get DNS status in machine-readable JSON format

dns-switch status --json

Expected Output: JSON with DNS servers, timestamps, and configuration metadata

Note

Useful for scripting and automation

Step 3: Count available DNS servers by category (reputable, normal, encrypted, etc.)

dns-switch count

Expected Output: Summary showing total servers in each category

Step 4: List all reputable DNS servers with details

dns-switch list --category reputable

Expected Output: Table of reputable DNS providers with names, IPs, and locations

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

Expected Output: System DNS changed to trusted providers like Cloudflare, Quad9, or AdGuard

Step 2: Switch to specific DNS providers by name

sudo dns-switch switch --names cloudflare adguard

Expected Output: DNS set to Cloudflare (1.1.1.1) and AdGuard (94.140.14.14)

Step 3: Switch to specific DNS servers by IP address

sudo dns-switch switch --servers 1.1.1.1 9.9.9.9

Expected Output: DNS set to specified IP addresses directly

Note

Useful when you know exact server IPs

Step 4: Switch to hardcoded fallback DNS servers for emergencies

sudo dns-switch fallback

Expected Output: DNS set to fallback servers from embedded recovery pool (e.g. 9.9.9.9, 1.1.1.1, 94.140.14.14)

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

Expected Output: DNS set to 3 randomly selected reputable servers

Step 2: Select 3 random reputable DNS servers and verify they work before applying

sudo dns-switch random --verify

Expected Output: DNS changed to verified working servers only

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

Expected Output: DNS changed to verified working reputable servers

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

Expected Output: DNS set to 5 randomly selected normal servers

Step 5: Select 6 random normal DNS servers and verify they work before applying

sudo dns-switch random --type normal --count 6 --verify

Expected Output: DNS changed to up to 6 verified working servers

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

Expected Output: DNS set to 6 servers evenly distributed between categories

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

Expected Output: DNS changed to 7 random servers

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

Expected Output: DNS set to 9 servers: 3 from each major category

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

Expected Output: 6 servers evenly distributed between categories

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

Expected Output: 6 servers evenly distributed across 3 categories

Step 11: Select 10 servers distributed: 4+3+3 from each category

sudo dns-switch random --type reputable,normal,remotely_fetched --count-random 10

Expected Output: 10 servers with weighted distribution

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

Expected Output: Health status for reputable servers with response times

Note

Read-only: does not modify the database

Step 2: Test reputable DNS servers only (read-only)

dns-switch health --type reputable

Expected Output: Health status for reputable servers

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

Expected Output: Health status saved to dns-database.json

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

Expected Output: Health status for normal servers

Note

Tests standard reliable DNS providers. Read-only mode

Step 5: Test encrypted DNS servers (DNSCrypt, DoH, DoT) only

dns-switch health --type encrypted

Expected Output: Health status for encrypted servers

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

Expected Output: Health status for remotely fetched servers

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

Expected Output: Health status for remotely fetched servers saved to database

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

Expected Output: Complete report of all working DNS servers across all categories

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

Expected Output: Complete health report saved to database

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

Expected Output: After 3rd run: servers with 3 consecutive failures moved to 'failed' category. Check with 'count' command

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

Expected Output: Failed servers health check completed - recovered servers moved IMMEDIATELY back to original categories (no 3-strike rule for recovery)

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

Expected Output: Failed servers moved to 'failed' category on FIRST failure (no waiting for 3 strikes). Check with 'count' command

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

Expected Output: Remotely fetched servers tested - failures moved to 'failed' category instantly

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

Expected Output: Comprehensive health data saved to database

Note

Full check includes geolocation lookup for all working servers

Step 15: Health check with JSON output (read-only)

dns-switch health --json

Expected Output: JSON formatted health data

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

Expected Output: JSON object with detailed health metrics per server

Note

Structured JSON output for automation and integration

Step 17: Fresh health check, save results, JSON output

dns-switch health --fresh --save --json

Expected Output: Real-time health check saved to database in 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

Expected Output: JSON object with current DNS configuration

Step 2: Pretty-printed DNS server counts

dns-switch count --json --json-pretty

Expected Output: Formatted JSON with server statistics

Step 3: Human-readable JSON with enhanced formatting

dns-switch status --json-human

Expected Output: JSON object with improved readability and structure

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

Expected Output: DNS changed to Cloudflare servers

Step 2: Switch to Cloudflare DNS after verifying it's working

sudo dns-switch switch --names cloudflare --verify

Expected Output: DNS changed to Cloudflare servers (verified working)

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

Expected Output: DNS changed to multiple providers

Note

Multiple names separated by spaces

Step 4: Switch to multiple DNS providers (comma-separated)

sudo dns-switch switch --names cloudflare,QuadServer1,adguard

Expected Output: DNS changed to Cloudflare, Quad9, and AdGuard servers

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

Expected Output: DNS changed to only verified working servers

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

Expected Output: DNS changed to AdGuard servers

Note

Blocks ads and trackers

Step 7: Switch to OpenDNS (208.67.222.222, 208.67.220.220)

sudo dns-switch switch --names opendns

Expected Output: DNS changed to OpenDNS servers

Step 8: Switch to NextDNS (45.90.28.167, 45.90.30.167)

sudo dns-switch switch --names nextdns

Expected Output: DNS changed to NextDNS servers

Step 9: Switch to CleanBrowsing DNS (185.228.168.9, 185.228.169.9)

sudo dns-switch switch --names cleanbrowsing

Expected Output: DNS changed to CleanBrowsing servers

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

Expected Output: DNS changed to specified IP

Step 2: Switch to specific DNS server IP after verifying it works

sudo dns-switch switch --servers 1.1.1.1 --verify

Expected Output: DNS changed to specified IP (verified working)

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

Expected Output: DNS changed to multiple IPs

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

Expected Output: DNS changed to only verified working IPs

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

Expected Output: DNS changed to AdGuard IPs

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

Expected Output: Lists fetched servers with country, response time, and success/failure status

Note

Default fetches 25 servers

Step 2: Fetch exactly 50 DNS servers from remote sources

sudo dns-switch fetch --count 50

Expected Output: Shows all 50 servers with test results and performance metrics

Note

Shows all results when count < 100

Step 3: Fetch exactly 100 DNS servers from remote sources

dns-switch fetch --count 100

Expected Output: 100 DNS servers fetched and tested

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

Expected Output: Lists all 35 fetched servers with detailed information

Note

fetch-count is an alias for fetch with --count

Step 5: Fetch ALL available DNS servers from remote sources

dns-switch fetch --all

Expected Output: Fetches hundreds of servers, shows truncated list with summary

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

Expected Output: Real-time fetch with no cached data used

Note

--fresh ensures completely new data from remote sources

Step 7: Fetch 25 servers with JSON output

sudo dns-switch fetch --json

Expected Output: JSON response with fetched server details

Step 8: Fresh fetch 35 servers with JSON output

sudo dns-switch fetch --count 35 --fresh --json

Expected Output: JSON response with fresh server data

Step 9: Fetch all servers with JSON output for processing

sudo dns-switch fetch --all --json

Expected Output: Complete JSON dataset of all servers

Step 10: Fetch remote DNSCrypt servers from authentication card

sudo dns-switch fetch-dns-from-card

Expected Output: Adds DNSCrypt servers from VPS to encrypted category

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

Expected Output: DNS set to use DNSCrypt proxy, service started if needed

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

Expected Output: Shows if DNSCrypt is running, configured resolver, and port

Step 3: Configure DNSCrypt to use Cloudflare's encrypted resolver

sudo dns-switch dnscrypt-set --resolver cloudflare

Expected Output: DNSCrypt configured and started with Cloudflare resolver

Note

Requires dnscrypt-proxy package installed

Step 4: Restart DNSCrypt proxy service

sudo dns-switch dnscrypt-restart

Expected Output: DNSCrypt proxy service restarted successfully

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

Expected Output: DNSCrypt auto-recovery monitor timer installed and started

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

Expected Output: Reports the timer as active or inactive plus the last check state

Step 7: Run a single DNSCrypt monitor check now (the same check the timer performs)

sudo dns-switch dnscrypt-monitor-check

Expected Output: Reports 'check passed', or triggers recovery/fallback on failure

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

Expected Output: DNSCrypt auto-recovery monitor timer stopped and removed

Step 9: Stop DNSCrypt and switch to reputable DNS servers

sudo dns-switch dnscrypt-remove

Expected Output: DNSCrypt stopped and DNS switched to regular servers

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

Expected Output: DNS switched to remote DNSCrypt IPv4 server from VPS

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

Expected Output: DNS switched to remote DNSCrypt IPv6 server from VPS

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

Expected Output: DNS switched to use both remote DNSCrypt servers for dual-stack support

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

Expected Output: DNS switched to use both remote DNSCrypt servers for dual-stack support

Note

Space-separated format - alternative syntax for multiple servers

Step 14: Check Pi-hole service status with systemctl info

sudo dns-switch pihole

Expected Output: Shows if Pi-hole is running, blocking status, and systemctl_status

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

Expected Output: DNS redirected through Pi-hole for ad/tracker blocking → Pi-hole automatically uses DNSCrypt (127.0.0.1#5353) as upstream → You get encrypted DNS + ad blocking = maximum protection → Secure yet transparent - see what's blocked in Pi-hole web interface

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

Expected Output: Pi-hole service stopped and disabled from boot

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

Expected Output: Pi-hole admin password updated. Protection restored on service restart.

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

Expected Output: Pi-hole configuration 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

Expected Output: Reports which temporary files were cleaned and how many duplicates removed

Step 2: Alternative command to remove duplicate entries

sudo dns-switch clean-duplicates

Expected Output: Same as 'clean' - removes duplicate DNS entries

Step 3: Flush systemd-resolved and nscd DNS caches to clear stale entries

sudo dns-switch flush-cache

Expected Output: DNS resolver caches flushed

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

Expected Output: Creates backup file of DNS database with timestamp

Note

Backs up dns-switch database only, not /etc/resolv.conf

Step 5: Create user backup with JSON output

sudo dns-switch backup --json

Expected Output: JSON confirmation of backup operation

Step 6: Reset DNS database to factory defaults and update system DNS

sudo dns-switch restore-default

Expected Output: Database restored to original state and system DNS updated

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

Expected Output: Shows what would be restored

Step 8: Restore DNS database from most recent backup (database only)

sudo dns-switch restore-backup

Expected Output: Database restored from latest backup file

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

Expected Output: JSON preview of restore operation

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

Expected Output: Shows DNS servers that would be set without actually changing them

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

Expected Output: Shows 5 servers that would be selected

Step 3: Preview fallback server switch without applying

sudo dns-switch fallback --no-action

Expected Output: Shows fallback servers that would be used

Step 4: Preview database cleanup without applying changes

sudo dns-switch clean --no-action

Expected Output: Shows duplicates that would be removed

Step 5: Check what DNSCrypt operations would be performed

sudo dns-switch dnscrypt --no-action

Expected Output: Shows DNSCrypt configuration changes

Step 6: Get current DNS status in pretty-printed JSON

sudo dns-switch status --json --json-pretty

Expected Output: Formatted JSON with indentation for readability

Step 7: Get health check results in enhanced JSON format

dns-switch health --type reputable --json-human

Expected Output: JSON with human-readable formatting and metadata

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

Expected Output: JSON with human-readable formatting and metadata

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

Expected Output: Shows: modern (systemd-resolved) or legacy (/etc/resolv.conf)

Note

Displays mode health status and any configuration issues

Step 2: Get DNS mode in JSON format

dns-switch get-mode --json

Expected Output: JSON with mode, systemd-resolved status, and health checks

Note

Includes resolv.conf symlink status and detected issues

Step 3: Auto-detect recommended DNS mode for this system

dns-switch detect-mode

Expected Output: Recommends modern if systemd-resolved active, legacy otherwise

Note

Checks systemd-resolved installation and activity status

Step 4: Get mode detection results in JSON

dns-switch detect-mode --json

Expected Output: JSON with detected mode, current mode, and recommendation

Step 5: Switch to modern mode (systemd-resolved)

sudo dns-switch set-mode --mode modern

Expected Output: Enables systemd-resolved and configures /etc/resolv.conf as symlink

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

Expected Output: Converts /etc/resolv.conf to regular file, preserves current DNS

Note

Extracts current DNS from systemd-resolved before switching

Step 7: Auto-repair broken DNS configuration

sudo dns-switch fix-dns

Expected Output: Fixes mode mismatches, broken symlinks, applies fallback 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

Expected Output: Executes all repair stages, then validates DNS status

Note

Use after unstable DNS incidents or repeated resolver failures

Step 9: Check current systemd-resolved configuration method

dns-switch get-modern-method

Expected Output: Shows: global, per-interface, networkmanager, or auto

Note

Only applies when in modern mode (systemd-resolved)

Step 10: Get systemd-resolved method in JSON

dns-switch get-modern-method --json

Expected Output: JSON with method and description

Step 11: Set to global config method (RECOMMENDED)

sudo dns-switch set-modern-method --method global

Expected Output: Configures /etc/systemd/resolved.conf - covers ALL interfaces

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

Expected Output: Uses resolvectl dns <interface> - applies per network 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

Expected Output: Uses nmcli for DNS configuration

Note

Only for NetworkManager-managed systems

Step 14: Set to auto with smart fallback chain

sudo dns-switch set-modern-method --method auto

Expected Output: Tries global → per-interface → networkmanager automatically

Note

Automatically selects best available method

Step 15: Check for DNS leaks across all network interfaces

dns-switch verify-no-leaks

Expected Output: Reports any interfaces with unexpected DNS servers

Note

Essential for privacy - detects DNS configuration bypasses

Step 16: Get DNS leak detection results in JSON

dns-switch verify-no-leaks --json

Expected Output: JSON with leaked interfaces list and expected DNS servers

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

Expected Output: Reports DNS status and fixes empty/invalid nameservers if needed

Note

Uses configuration-based fallback servers, never hardcoded values

Step 2: Enable automatic DNS checking on system boot

sudo dns-switch enable-boot-check

Expected Output: Creates and enables systemd service for boot-time DNS validation

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

Expected Output: Removes systemd service for boot-time DNS validation

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

Expected Output: Shows if boot-check service is enabled and its last run status

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

Expected Output: require_dnssec=true; service restarted

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

Expected Output: require_dnssec=false; service restarted

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

Expected Output: doh_servers=true; service restarted

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

Expected Output: doh_servers=false; service restarted

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

Expected Output: External-DNS mode ENABLED: /etc/resolv.conf unlocked and Kodachi DNS protection paused.

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

Expected Output: External-DNS mode DISABLED: DNS management returned to Kodachi.

Step 3: Show whether a third-party VPN currently owns DNS (read-only; no sudo).

dns-switch external-dns --state status

Expected Output: External-DNS mode: ON|OFF — ...

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