Skip to content

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.0.1 | Size: 4.9MB | Author: Warith Al Maawali

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


File Information

Property Value
Binary Name dns-switch
Version 9.0.1
Build Date 2026-02-07T11:41:36.102170154Z
Rust Version
File Size 4.9MB
JSON Data View Raw JSON

SHA256 Checksum

888af71092cbbdc7e62a7fce5a859b7e8045106b5695f42031452c9d419f3c7a

Features

Feature Description
Feature Embedded DNS server lists (no external config dependencies)
Feature Dynamic path detection (works in any directory)
Feature Comprehensive input validation and sanitization
Feature JSON output support for automation
Feature Health monitoring and performance testing
Feature Remote DNS server discovery and testing
Feature Security-focused design with privilege checking
Feature DNSCrypt proxy integration
Feature Pi-hole DNS filter integration
Feature Automatic backup and restore capabilities

Security Features

Feature Description
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

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

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|encrypted|fallback|all|remotely_fetched) - --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>

Options: - <MODE>: DNS mode: 'modern' (systemd-resolved) or 'legacy' (/etc/resolv.conf)

Examples:

sudo dns-switch set-mode modern  # Switch to systemd-resolved
sudo dns-switch set-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.)

Usage:

dns-switch fix-dns

Examples:

sudo dns-switch fix-dns
# Repairs: mode mismatches, broken symlinks, corrupted files
# Applies fallback DNS servers to restore connectivity

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

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

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

Examples:

dns-switch list --category reputable
dns-switch list --category encrypted

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

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

Examples

DNS Status & Information

Check current DNS configuration and available servers

Display current system DNS servers with detailed information

dns-switch status
Expected Output: Shows active DNS servers, their IPs, and configuration source

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

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

dns-switch count
Expected Output: Summary showing total servers in each category

List all reputable DNS servers with details

dns-switch list --category reputable
Expected Output: Table of reputable DNS providers with names, IPs, and locations

Basic DNS Switching

Switch DNS servers using different selection methods

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

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)

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

Switch to hardcoded fallback DNS servers for emergencies

sudo dns-switch fallback
Expected Output: DNS set to reliable fallback servers (8.8.8.8, 1.1.1.1, etc.)

Note

Use when database is corrupted or unavailable

Random DNS Selection

Randomly select DNS servers from different categories

Select 3 random DNS servers from reputable category (default behavior)

sudo dns-switch random
Expected Output: DNS set to 3 randomly selected reputable servers

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

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

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

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

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

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

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

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

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

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

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.

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

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

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)

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

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

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

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

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

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)

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

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

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

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

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

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

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

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

JSON Output

Automation-friendly JSON responses

Get status in JSON format

dns-switch status --json
Expected Output: JSON object with current DNS configuration

Pretty-printed DNS server counts

dns-switch count --json --json-pretty
Expected Output: Formatted JSON with server statistics

Human-readable JSON with enhanced formatting

dns-switch status --json-human
Expected Output: JSON object with improved readability and structure

DNS Switching by Names

Switch DNS servers using provider names

Switch to Cloudflare DNS (1.1.1.1)

sudo dns-switch switch --names cloudflare
Expected Output: DNS changed to Cloudflare servers

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

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

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

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

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

Switch to OpenDNS (208.67.222.222, 208.67.220.220)

sudo dns-switch switch --names opendns
Expected Output: DNS changed to OpenDNS servers

Switch to NextDNS (45.90.28.167, 45.90.30.167)

sudo dns-switch switch --names nextdns
Expected Output: DNS changed to NextDNS servers

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

DNS Switching by IP

Switch DNS servers using IP addresses

Switch to specific DNS server IP

sudo dns-switch switch --servers 1.1.1.1
Expected Output: DNS changed to specified IP

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

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

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

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

Remote DNS Discovery & Fetching

Discover and fetch new DNS servers from remote sources

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

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

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

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

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

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

Fetch 25 servers with JSON output

sudo dns-switch fetch --json
Expected Output: JSON response with fetched server details

Fresh fetch 35 servers with JSON output

sudo dns-switch fetch --count 35 --fresh --json
Expected Output: JSON response with fresh server data

Fetch all servers with JSON output for processing

sudo dns-switch fetch --all --json
Expected Output: Complete JSON dataset of all servers

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

DNSCrypt & Pi-hole Integration

Encrypted DNS and ad-blocking integration

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

Check DNSCrypt proxy service status

sudo dns-switch dnscrypt
Expected Output: Shows if DNSCrypt is running, configured resolver, and port

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

Restart DNSCrypt proxy service

sudo dns-switch dnscrypt-restart
Expected Output: DNSCrypt proxy service restarted successfully

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

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

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

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

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

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

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!

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.

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

Database Maintenance

Manage DNS database, backups, and cleanup

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

Alternative command to remove duplicate entries

sudo dns-switch clean-duplicates
Expected Output: Same as 'clean' - removes duplicate DNS entries

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

Create user backup with JSON output

sudo dns-switch backup --json
Expected Output: JSON confirmation of backup operation

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

Preview restore to defaults without applying changes

sudo dns-switch restore-default --no-action
Expected Output: Shows what would be restored

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

Preview restore from backup in JSON format

sudo dns-switch restore-backup --no-action --json
Expected Output: JSON preview of restore operation

Dry Run & JSON Output

Test commands safely and get machine-readable output

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

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

Preview fallback server switch without applying

sudo dns-switch fallback --no-action
Expected Output: Shows fallback servers that would be used

Preview database cleanup without applying changes

sudo dns-switch clean --no-action
Expected Output: Shows duplicates that would be removed

Check what DNSCrypt operations would be performed

sudo dns-switch dnscrypt --no-action
Expected Output: Shows DNSCrypt configuration changes

Get current DNS status in pretty-printed JSON

sudo dns-switch status --json --json-pretty
Expected Output: Formatted JSON with indentation for readability

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

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

DNS Mode Management (Modern vs Legacy)

Manage DNS configuration modes: modern (systemd-resolved) vs legacy (/etc/resolv.conf)

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

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

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

Get mode detection results in JSON

dns-switch detect-mode --json
Expected Output: JSON with detected mode, current mode, and recommendation

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

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

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

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)

Get systemd-resolved method in JSON

dns-switch get-modern-method --json
Expected Output: JSON with method and description

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

Set to per-interface method

sudo dns-switch set-modern-method --method per-interface
Expected Output: Uses resolvectl dns - applies per network interface

Note

May miss virtual/VPN interfaces - use global method instead

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

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

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

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

Boot-Time DNS Check Management

Manage automatic DNS checking and fixing on system boot

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

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

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

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

Environment Variables

Variable Description Default Values
RUST_LOG Set logging level info error
NO_COLOR Disable all colored output when set unset 1
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