DNS Switch Guide
Manage encrypted DNS with DNSCrypt and DoH across a curated resolver list, with health checks, scoring, and Pi-hole integration. This guide walks configuration scenarios; the CLI catalog holds every flag.
Documentation Navigation
This page is scenario-first (operational workflows, real run order, and troubleshooting). For the full autogenerated command/flag catalog, use the CLI Reference.
File Information
| Property | Value |
|---|---|
| Binary Name | dns-switch |
| Version | 10.0.3 (build 75) |
| Build Date | Not disclosed |
| Rust Version | |
| File Size | 11.2MB |
| Author | Warith Al Maawali |
| License | Proprietary |
| Category | Network & Routing |
| Description | Production-ready DNS management with security and portability. A self-contained, portable DNS manage... |
| JSON Data | View Raw JSON |
SHA256 Checksum
4dc2c54c0c0701aa2ed9d4a4533d93f0dd531cb8f656ea2f911a02d70bf79f32
Key Features
DNS Server Management
| Feature | Description |
|---|---|
| Extensive Database | A database of vetted DNS servers organised into categories (reputable, normal, encrypted, fallback, remotely fetched) |
| Smart Selection | Automatic scoring based on latency, reliability, and privacy |
| DNSCrypt Support | Encrypts system-resolver traffic sent through dnscrypt-proxy |
| Pi-hole Integration | Seamless ad-blocking DNS filtering support |
Why DNS Switch is Critical
| Benefit | Description |
|---|---|
| DNS Leak Protection | Helps prevent DNS queries from bypassing your VPN/Tor |
| Privacy Protection | The reputable category favours no-logs providers; other categories may log |
| Censorship Bypass | Access blocked content with alternative DNS |
| Attack Detection | verify-no-leaks reports any interface whose DNS servers differ from the expected system DNS |
| Automatic Failover | Switches to backup servers if primary fails |
TL;DR - Essential Commands
Important: Use sudo for DNS operations as they modify system network settings.
# Switch to a random secure DNS server (reputable set)
sudo dns-switch random --type reputable
sudo dns-switch random --type reputable --count 5
# Switch to specific DNS category or provider
sudo dns-switch switch --names cloudflare
sudo dns-switch switch --servers 1.1.1.1 9.9.9.9
# Check current DNS configuration and status
dns-switch status --json # JSON output for automation
dns-switch status --verbose # Detailed status information
# Test DNS server health
dns-switch health --type reputable
# Configure DNSCrypt with a named resolver
sudo dns-switch dnscrypt-set --resolver cloudflare
# Fetch and update DNS database from remote sources
sudo dns-switch fetch
DNS Management Modes
DNS Switch supports two different DNS management modes depending on your system configuration:
Modern Mode (systemd-resolved)
Modern systems using systemd-resolved for DNS management. This mode provides three configuration methods with automatic fallback:
| Method | Description | Scope |
|---|---|---|
| Global Config | /etc/systemd/resolved.conf modification | All interfaces (DEFAULT, safest) |
| Per-Interface | resolvectl commands per interface | Individual interfaces (fallback) |
| NetworkManager | nmcli configuration | NM-managed connections (alternative) |
Advantages:
- Centralized DNS management
- Per-interface DNS configuration
- Built-in DNS caching
- DNSSEC support
- Automatic fallback between methods
Requirements:
- systemd-resolved installed and active
/etc/resolv.confsymlinked to/run/systemd/resolve/stub-resolv.conf
Legacy Mode (/etc/resolv.conf)
Traditional DNS management through direct /etc/resolv.conf file manipulation:
| Feature | Description |
|---|---|
| Direct File | /etc/resolv.conf is a regular file |
| System-Wide | All interfaces use same DNS |
| Simple | No additional services required |
| Universal | Works on any Linux system |
Advantages:
- Simple and straightforward
- No additional dependencies
- Compatible with all systems
- Direct control
Limitations:
- No per-interface DNS
- No built-in caching
- Can conflict with systemd-resolved if active
Mode Detection and Switching
# Check current DNS mode
dns-switch get-mode --json
# The system automatically detects the mode based on:
# - Is systemd-resolved active?
# - Is /etc/resolv.conf a symlink?
# Switch to modern mode (enables and starts systemd-resolved)
sudo dns-switch set-mode --mode modern
# Switch to legacy mode (creates regular /etc/resolv.conf)
sudo dns-switch set-mode --mode legacy
# Check mode health and compatibility
dns-switch get-mode
# Check and fix DNS configuration
sudo dns-switch fix-dns
# Verify detected mode after repair
dns-switch detect-mode
Mode Migration:
When switching modes, DNS Switch automatically: - Backs up current configuration - Migrates existing DNS servers - Enables/disables systemd-resolved as needed - Verifies the new configuration - Provides rollback instructions if needed
Best Practice: Use Modern Mode if systemd-resolved is available on your system for better flexibility and features.
Understanding DNS Management
DNS Categories
DNS Switch organizes servers into multiple security levels:
# Switch to most secure, privacy-focused servers
sudo dns-switch switch --category reputable
# Use standard secure servers
sudo dns-switch switch --category normal
# Use encrypted DNS servers
sudo dns-switch dnscrypt-set --resolver cloudflare
# Emergency fallback servers
sudo dns-switch fallback
Server Categories:
| Category | Description |
|---|---|
| Reputable | No-logs policy, DNSSEC support, proven privacy track record (Cloudflare, Quad9, AdGuard) |
| Normal | Good security, reasonable performance, some logging |
| Encrypted | DNSCrypt and DoH servers for encrypted queries |
| Fallback | Emergency servers when others fail |
| All | Mixed selection from all categories |
Advanced DNS Switching
# Switch by provider names
sudo dns-switch switch --names cloudflare
sudo dns-switch switch --names opendns
# Switch by IP addresses
sudo dns-switch switch --servers 1.1.1.1 9.9.9.9
# Verify servers work before applying
sudo dns-switch switch --names cloudflare --verify
# Random selection with options
sudo dns-switch random --type reputable --count 5
sudo dns-switch random --type reputable --verify
DNSCrypt for Encrypted DNS
DNSCrypt encrypts system-resolver traffic between the local proxy and its selected upstream resolver. This protects that path, but it does not cover applications that bypass system DNS:
# List resolver names from the cached DNSCrypt source list
dns-switch list --category encrypted
# Enable DNSCrypt with specific resolver
sudo dns-switch dnscrypt-set --resolver cloudflare
# Check local service, socket, and resolver-path status
dns-switch dnscrypt
# Restart DNSCrypt service
sudo dns-switch dnscrypt-restart
# Remove DNSCrypt (switches to reputable DNS automatically)
sudo dns-switch dnscrypt-remove
Encrypted DNS: DNSSEC + DoH
After enabling DNSCrypt, layer on:
sudo dns-switch dnssec-on, DNSSEC signature validation (require_dnssec=true)sudo dns-switch dot-on, Allow DoH resolvers (doh_servers=true)
Both flip flags in /etc/dnscrypt-proxy/dnscrypt-proxy.toml and restart the service. They earn +0.1 and +0.2 in the dns_privacy health-control score, and unlike editing /etc/systemd/resolved.conf they actually affect live DNS traffic (because Kodachi's encryption layer is dnscrypt-proxy, not systemd-resolved).
Pi-hole Integration
For network-wide ad blocking:
# Enable Pi-hole DNS filtering
sudo dns-switch pihole-enable
# Disable Pi-hole temporarily
sudo dns-switch pihole-disable
# Check Pi-hole status
dns-switch pihole
# Set Pi-hole admin password
sudo dns-switch pihole-password --password NewSecurePassword123
# Reset Pi-hole configuration
sudo dns-switch pihole-reset
Health Checking & Testing
# Check health of DNS servers by category
dns-switch health --type reputable
# Force fresh health check (bypass cache)
dns-switch health --type reputable --fresh
# Test for DNS leaks and security issues (use dns-leak for comprehensive testing)
dns-leak test --json
dns-switch health --json
dns-switch status --json
Database Management
# Fetch latest DNS servers from remote sources
sudo dns-switch fetch
sudo dns-switch fetch --count 50
# Fetch a specific number of DNS servers from remote sources
dns-switch fetch-count
dns-switch fetch-count --fetch-count 50
dns-switch fetch-count --fetch-count 100 --fresh
# Fetch remote DNS servers from supported sources
sudo dns-switch fetch --count 50 --fresh
# List all available DNS servers
dns-switch list --category reputable
# Count servers by category
dns-switch count
# Clean duplicate entries
sudo dns-switch clean-duplicates
# Clean temporary files and cache
dns-switch clean
Backup & Recovery
# Back up the dns-switch server database (not /etc/resolv.conf)
sudo dns-switch backup
# Restore from backup
sudo dns-switch restore-backup
# Reset the server database to factory defaults and apply the default DNS (discards custom entries)
sudo dns-switch restore-default
JSON Output and Return Codes
# All dns-switch commands support JSON output
sudo dns-switch status --json # JSON status output
sudo dns-switch health --json --type reputable # JSON health results
sudo dns-switch list --json # JSON server list
# Pretty-printed JSON for readability
sudo dns-switch status --json-pretty
# Parse JSON output with jq
sudo dns-switch status --json | jq '.data.current_dns'
sudo dns-switch health --json | jq '.data.summary.success_rate_percent'
# Return codes (useful for scripts)
# 0 = Success
# 1 = General error
# 2 = Invalid arguments
# 3 = Permission denied
# 4 = Network error
DNS Repair Workflow
Use the built-in repair flow when DNS is broken after updates, mode mismatch, or resolver corruption:
# Detect current mode and health
dns-switch detect-mode
dns-switch get-mode --json
# Auto-repair DNS configuration
sudo dns-switch fix-dns
# Verify active DNS state after repair
dns-switch status --json
Repair flow covers:
| Step | Description |
|---|---|
| Mode Detection | Detects modern/legacy resolver mode |
| Resolver Repair | Restores valid nameservers and resolver state |
| Post-Check | Verifies DNS configuration after remediation |
Remote DNS Discovery
Discover and integrate new DNS servers from multiple sources:
# Fetch specific count of DNS servers
dns-switch fetch-count --fetch-count 50
dns-switch fetch-count --fetch-count 100 --fresh
# Fetch remote DNS servers from supported sources
sudo dns-switch fetch --count 50 --fresh
fetch-count Command:
Fetches a specific number of DNS servers from remote public databases and tests their availability.
| Option | Description |
|---|---|
| --fetch-count NUM | Number of servers to fetch (default: 25) |
| --fresh | Force fresh data retrieval, bypassing all caches |
fetch Command:
Fetches remote DNS server data from supported sources and stores tested entries in the local DNS database.
Cache and Maintenance
# Clean temporary files and cache
dns-switch clean
# Clean duplicate DNS entries
sudo dns-switch clean-duplicates
clean Command:
Removes temporary files and cached data from the DNS database, freeing up disk space and ensuring clean operations.
| Cleaned Items | Description |
|---|---|
| Temporary Fetch Results | Cached remote DNS fetch data |
| Health Check Cache | Old health check results |
| API Response Cache | Cached remote API responses |
clean-duplicates Command:
Removes duplicate DNS entries from the database while preserving all unique servers. Reports the number of duplicates removed.
Advanced Commands
For advanced users who need access to all available commands and options, please refer to the auto-generated command reference which includes:
| Feature | Description |
|---|---|
| Custom DNS configuration | Advanced DNS server configuration options |
| Scoring parameters | Algorithm parameters for DNS server scoring |
| Batch operations | Batch testing and management operations |
| Database maintenance | Commands for DNS database management |
| DNSCrypt options | Advanced DNSCrypt configuration |
| JSON formatting | JSON output formatting options |
| CLI reference | All command-line flags and parameters |
Security Notes
Important Security Practices:
| Practice | Description |
|---|---|
| Tor DNS Resolution | Use tor-switch for routing DNS through Tor network |
| Database Updates | Regularly update DNS database with fetch command |
| Leak Testing | Test for DNS leaks after VPN/Tor connection |
| Encryption | Use DNSCrypt when on untrusted networks |
| Verification | Verify DNS changes with status command |
| Security Testing | Check for poisoning/hijacking on suspicious networks |
| Backup Strategy | Backup configuration before major changes |
Performance
| Metric | Value |
|---|---|
| Switch Time | < 1 second |
| Memory Usage | ~25MB active, < 5MB idle |
| CPU Usage | < 5% during operations |
| Database Size | ~5MB for full server list |
| Health Check | 2-5 seconds per server |
Support
| Resource | Link |
|---|---|
| Website | digi77.com |
| Anonymity Verifier | kodachi.cloud |
| Discord Support | discord.gg/KEFErEx |
| GitHub | github.com/WMAL |
Scenario 1: Emergency DNS Fallback When ISP DNS Fails
When your ISP DNS becomes unreachable or you experience sudden DNS resolution failures.
# Step 1: Switch to emergency fallback DNS servers
sudo dns-switch fallback
# Step 2: Verify domain resolution is working
sudo health-control net-check
# Expected: Domain resolution should succeed
# Step 3: Confirm DNS configuration was applied
dns-switch status
# Expected: Shows fallback DNS servers (e.g. 1.1.1.1, 9.9.9.9) in /etc/resolv.conf
# Step 4: Test for DNS leaks
dns-leak test
# Expected: DNS queries should go through fallback servers only
Cross-binary workflow: dns-switch + health-control + dns-leak
When to run: Network is up but DNS resolution fails. Or Automate this with workflow-manager using profile dns-fallback-emergency.
Scenario 2: Privacy-First DNS with DNSCrypt Encryption
Route system-resolver queries through DNSCrypt to reduce local-network and ISP visibility. Applications that use their own resolver can bypass the system DNS path.
# Step 1: Stop Tor DNS routing if active
sudo tor-switch stop-tor-dns-nftables
sudo tor-switch stop-tor-dns-iptables
# Step 2: Enable DNSCrypt with a resolver from the cached source list
sudo dns-switch dnscrypt-set --resolver cloudflare
# Expected: DNSCrypt is configured and the local proxy service starts
# Step 3: Check local DNSCrypt service, socket, and resolver path
dns-switch dnscrypt
# Expected: Shows DNSCrypt listening on 127.0.0.1:53
# Step 4: Review the cached resolver names (optional)
dns-switch list --category encrypted
# Expected: Resolver names accepted by dnscrypt-set
# Step 5: Confirm connectivity after the change (this does not prove encryption)
sudo health-control net-check
# Step 6: Enable Pi-hole for combined ad blocking and encryption
sudo dns-switch pihole-enable
# Expected: Pi-hole (port 5353) uses DNSCrypt as its upstream (127.0.0.1#53)
Cross-binary workflow: dns-switch + tor-switch + health-control
When to run: When on untrusted networks (public WiFi, hotels) or for maximum DNS privacy.
Scenario 3: Multi-Stage DNS Rotation for Maximum Privacy
Regularly rotate DNS servers to avoid DNS profiling and enhance anonymity.
# Step 1: Switch to 14 random servers (7 reputable + 7 normal)
sudo dns-switch random --type reputable,normal --count 14
# Expected: DNS changed to 14 randomly distributed servers
# Step 2: Verify servers are responsive
dns-switch health --type reputable
dns-switch health --type normal
# Step 3: Check current DNS configuration
dns-switch status --json
# Expected: JSON output with all 14 active DNS servers
# Step 4: Test for DNS leaks
dns-leak test --json
# Expected: system resolver paths use the configured servers; applications with their own DNS can bypass them
# Step 5: Fetch and integrate new remote DNS servers
sudo dns-switch fetch --count 50
# Expected: 50 new DNS servers added to database
# Step 6: Rotate to newly discovered servers
sudo dns-switch random --type remotely_fetched --count 5
# Expected: DNS switched to 5 randomly selected remote servers
# Step 7: Check your public IP geolocation (a DNS change does not change it)
ip-fetch --json | jq '.data.records[0].country_name'
Cross-binary workflow: dns-switch + dns-leak + ip-fetch
When to run: Weekly for maximum privacy, or before sensitive browsing sessions. Or Automate this with workflow-manager using profile dns-switch-random-mixed.
Scenario 4: Troubleshooting DNS After System Corruption
When DNS configuration is broken due to mismatched modes, corrupted files, or broken symlinks.
# Step 1: Check current DNS mode and detect issues
dns-switch get-mode --json
# Expected: Shows mode (modern/legacy) and any detected issues
# Step 2: Auto-detect recommended mode
dns-switch detect-mode
# Expected: Recommends modern if systemd-resolved active, legacy otherwise
# Step 3: Auto-repair broken DNS configuration
sudo dns-switch fix-dns
# Expected: Fixes mode mismatches, broken symlinks, applies fallback DNS
# Step 4: Verify DNS is working
dns-switch status
sudo health-control net-check
# Step 5: Check for DNS leaks across all interfaces
dns-leak test --json
# Expected: No unexpected DNS servers on any network interface
# Step 6: If modern mode fails, switch to legacy mode
sudo dns-switch set-mode --mode legacy
# Expected: Converts /etc/resolv.conf to regular file, preserves current DNS
# Step 7: Review system logs for DNS-related errors
tail -50 <hooks-dir>/logs/dns-switch-log.log
Cross-binary workflow: dns-switch + health-control + logs-hook
When to run: After system updates break DNS, or when experiencing intermittent connectivity issues.
Scenario 5: Remote DNS Server Discovery and Integration
Discover new DNS servers from public databases and integrate them into your configuration.
# Step 1: Fetch 100 remote DNS servers with fresh data
sudo dns-switch fetch --count 100 --fresh
# Expected: 100 new servers tested and saved to database
# Step 2: Check database server counts after fetch
dns-switch count --json
# Expected: Shows increased count in remotely_fetched category
# Step 3: Test health of newly fetched servers
dns-switch health --type remotely_fetched --save
# Expected: Health data saved to database with response times
# Step 4: Run health check 3 times to enforce 3-strike rule
dns-switch health --type remotely_fetched --save && \
dns-switch health --type remotely_fetched --save && \
dns-switch health --type remotely_fetched --save
# Expected: Failed servers moved to 'failed' category after 3 consecutive failures
# Step 5: Bypass 3-strike rule for urgent cleanup
dns-switch health --type remotely_fetched --save --force-move
# Expected: Failed servers moved immediately (1st failure = category move)
# Step 6: Clean duplicate entries
sudo dns-switch clean-duplicates
# Expected: Removes duplicate DNS entries from database
# Step 7: Switch to best performing remote servers
sudo dns-switch random --type remotely_fetched --count 5 --verify
Cross-binary workflow: dns-switch + workflow-manager
When to run: Monthly to refresh DNS server pool, or when current servers show degraded performance.
Scenario 6: Pi-hole Integration for Network-Wide Ad Blocking
Enable Pi-hole DNS filtering for comprehensive ad and tracker blocking with DNSCrypt encryption.
# Step 1: Enable Pi-hole service
sudo dns-switch pihole-enable
# Expected: Pi-hole service started, DNS set to 127.0.0.1 (Pi-hole)
# Step 2: Verify Pi-hole status
dns-switch pihole
# Expected: Shows Pi-hole running, systemctl status, blocking enabled
# Step 3: Confirm DNSCrypt upstream integration
dns-switch dnscrypt
# Expected: DNSCrypt running, Pi-hole on port 5353 using 127.0.0.1#53 as upstream
# Step 4: Set Pi-hole web interface password
sudo dns-switch pihole-password --password SecurePassword123
# Expected: Pi-hole admin password updated, TOML file protection restored
# Step 5: Verify DNS resolution and ad blocking
sudo health-control net-check
# Expected: Domain resolution works, ads blocked
# Step 6: Check Pi-hole blocking statistics
tail -100 <hooks-dir>/logs/dns-switch-log.log
# Step 7: Disable Pi-hole temporarily if needed
sudo dns-switch pihole-disable
# Expected: Pi-hole service stopped, DNS switched back to DNSCrypt or fallback
# Step 8: Reset Pi-hole configuration if corrupted
sudo dns-switch pihole-reset
Cross-binary workflow: dns-switch + health-control + logs-hook
When to run: For users requiring network-wide ad/tracker blocking combined with encrypted DNS.
Scenario 7: Mode Migration (Legacy to Modern systemd-resolved)
Migrate from legacy /etc/resolv.conf to modern systemd-resolved for better flexibility.
# Step 1: Check current mode and compatibility
dns-switch get-mode
dns-switch detect-mode --json
# Expected: Shows current mode and recommended mode
# Step 2: Create backup of DNS database before migration
sudo dns-switch backup
# Expected: Timestamped backup created
# Step 3: Switch to modern mode (systemd-resolved)
sudo dns-switch set-mode --mode modern
# Expected: Enables systemd-resolved, configures /etc/resolv.conf as symlink
# Step 4: Verify mode migration succeeded
dns-switch get-mode --json
dns-switch status --json
# Step 5: Apply DNS configuration to test modern mode
sudo dns-switch switch --category reputable
# Expected: DNS changed using systemd-resolved methods
# Step 6: Check for DNS leaks across all interfaces
dns-leak test --json
# Expected: No leaked DNS servers on any network interface
# Step 7: Test connectivity
sudo health-control net-check
# Step 8: If migration fails, rollback to legacy mode
sudo dns-switch set-mode --mode legacy
sudo dns-switch restore-backup
Cross-binary workflow: dns-switch + health-control
When to run: When upgrading system to modern DNS management, or troubleshooting per-interface DNS configuration.
Scenario 8: Database Maintenance and Performance Optimization
Regular maintenance to keep DNS database healthy and performant.
# Step 1: Create pre-maintenance backup
sudo dns-switch backup --json
# Expected: Backup created with timestamp
# Step 2: Check database integrity before cleanup
dns-switch count --json-pretty
# Expected: Shows server counts across all categories
# Step 3: Run full health check on all categories
dns-switch health --type all --save
# Expected: Health data saved for all working server categories
# Step 4: Clean duplicate entries from database
sudo dns-switch clean-duplicates --json
# Expected: Duplicates removed, shows count of cleaned entries
# Step 5: Test recovery of failed servers
dns-switch health --type failed --save
# Expected: Recovered servers moved back to original categories instantly
# Step 6: Optimize database by moving consistently failed servers
dns-switch health --type all --save --force-move
# Expected: Failed servers moved to 'failed' category immediately (bypass 3-strike rule)
# Step 7: Verify database statistics after cleanup
dns-switch count --json-pretty
# Expected: Updated server counts, reduced failed category
# Step 8: Test DNS switching with cleaned database
sudo dns-switch random --type reputable --count 5 --verify
# Expected: Only verified working servers applied
# Step 9: Restore from backup if cleanup caused issues
sudo dns-switch restore-backup --no-action
sudo dns-switch restore-backup # Remove --no-action to apply
Cross-binary workflow: dns-switch + workflow-manager
When to run: Weekly maintenance, or after large remote DNS fetch operations. Or Automate this with workflow-manager scheduling weekly cleanup tasks.
Related Workflows
- DNS Leak Detection Guide, Test and prevent DNS leaks
- Health Control Security, Network connectivity verification
- Tor DNS Routing, Route DNS through Tor network
- IP Geolocation, Verify DNS provider geolocation
- Full CLI Reference: dns-switch commands