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: 13.0MB | Author: Warith Al Maawali
License: Proprietary | Website: https://digi77.com
File Information
| Property | Value |
|---|---|
| Binary Name | dns-switch |
| Version | 9.0.1 |
| Build Date | 2025-09-23T19:20:08.163250166Z |
| Rust Version | |
| File Size | 13.0MB |
| JSON Data | View Raw JSON |
SHA256 Checksum
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-filter <FIELDS> |
Return only specified fields in JSON |
--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:
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:
random
Switch to random DNS servers with advanced selection
Usage:
Options:
- --type <TYPE>: Type of DNS servers (reputable|normal|encrypted|fallback|all|remotely_fetched)
- --count <COUNT>: Number of random DNS servers to select
Examples:
fallback
Switch to fallback DNS servers
Usage:
Examples:
status
Show current DNS configuration
Usage:
Examples:
Health & Discovery
health
Check health of DNS servers with detailed analysis
Usage:
Options:
- --type <TYPE>: Test specific type (reputable|normal|encrypted|fallback|all)
- --full: Perform comprehensive health check
- --fresh: Force fresh health check, bypassing cache
Examples:
fetch
Fetch and test remote DNS servers with advanced options
Usage:
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:
fetch-count
Fetch a specific number of DNS servers from remote sources
Usage:
Options:
- --count <NUM>: Number of DNS servers to fetch
- --fresh: Force fresh data retrieval, bypassing caches
Examples:
DNSCrypt Management
dnscrypt
Show DNSCrypt status
Usage:
Examples:
dnscrypt-set
Enable DNSCrypt with specific resolver
Usage:
Options:
- --resolver <NAME>: DNSCrypt resolver name
Examples:
dnscrypt-restart
Restart DNSCrypt proxy
Usage:
Examples:
dnscrypt-remove
Remove DNSCrypt configuration
Usage:
Examples:
Pi-hole Integration
pihole
Show Pi-hole status
Usage:
Examples:
pihole-enable
Enable Pi-hole DNS filtering
Usage:
Examples:
pihole-disable
Disable Pi-hole DNS filtering
Usage:
Examples:
pihole-password
Set Pi-hole web interface password
Usage:
Options:
- --password <PASSWORD>: New password for Pi-hole web interface
Examples:
pihole-reset
Reset Pi-hole configuration
Usage:
Examples:
Information & Utilities
list
List available DNS servers
Usage:
Options:
- --category <CATEGORY>: Category to list
Examples:
count
Count DNS servers by category
Usage:
Examples:
Maintenance & Recovery
clean
Clean temporary files and cache
Usage:
Examples:
clean-duplicates
Clean duplicate DNS entries from database
Usage:
Examples:
backup
Create DNS configuration backup
Usage:
Examples:
restore-default
Restore default DNS configuration
Usage:
Examples:
restore-backup
Restore from backup
Usage:
Options:
- --file <FILE>: Backup file to restore
Examples:
Examples
DNS Status & Information
Check current DNS configuration and available servers
Display current system DNS servers with detailed information
Expected Output: Shows active DNS servers, their IPs, and configuration sourceGet DNS status in machine-readable JSON format
Expected Output: JSON with DNS servers, timestamps, and configuration metadataNote
Useful for scripting and automation
Count available DNS servers by category (reputable, normal, encrypted, etc.)
Expected Output: Summary showing total servers in each categoryList all reputable DNS servers with details
Expected Output: Table of reputable DNS providers with names, IPs, and locationsBasic DNS Switching
Switch DNS servers using different selection methods
Switch to first available reputable DNS servers from the database
Expected Output: System DNS changed to trusted providers like Cloudflare, Quad9, or AdGuardSwitch to specific DNS providers by name
Expected Output: DNS set to Cloudflare (1.1.1.1) and AdGuard (94.140.14.14)Switch to specific DNS servers by IP address
Expected Output: DNS set to specified IP addresses directlyNote
Useful when you know exact server IPs
Switch to hardcoded fallback DNS servers for emergencies
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)
Expected Output: DNS set to 3 randomly selected reputable serversSelect 5 random servers from normal category
Expected Output: DNS set to 5 randomly selected normal serversSelect 6 servers: 3 from reputable + 3 from normal categories
Expected Output: DNS set to 6 servers evenly distributed between categoriesNote
Count is distributed evenly across specified types
Select 3 servers each from reputable, normal, and remotely_fetched (9 total)
Expected Output: DNS set to 9 servers: 3 from each major categoryNote
'all' excludes encrypted and fallback categories
DNS Health Checking
Test DNS servers for availability and performance
Test reputable DNS servers (default) for availability and response times
Expected Output: Report showing working/failed servers with response times in millisecondsTest ALL DNS server categories comprehensively
Expected Output: Complete report of all DNS servers across all categories with statisticsNote
May take several minutes to complete all tests
Force fresh health check bypassing cached results
Expected Output: Real-time health status without using any cached dataNote
--fresh forces new tests, ignoring recent cached results
Test encrypted DNS servers with JSON output for parsing
Expected Output: JSON object with detailed health metrics per serverJSON Output
Automation-friendly JSON responses
Get status in JSON format
Expected Output: JSON object with current DNS configurationPretty-printed DNS server counts
Expected Output: Formatted JSON with server statisticsFiltered JSON output
Expected Output: Only servers and summary fields in JSONTroubleshooting
Debug and recovery operations
Verbose status output
Expected Output: Detailed DNS configuration informationNote
Useful for debugging issues
Restore default DNS settings
Expected Output: Resets DNS to system defaultsNote
Use when DNS is misconfigured
Backup current DNS configuration
Expected Output: Creates timestamped backup fileDry run mode
Expected Output: Shows what would be done without changesNote
Test commands safely before execution
DNS Switching by Names
Switch DNS servers using provider names
Switch to Cloudflare DNS (1.1.1.1)
Expected Output: DNS changed to Cloudflare serversSwitch to Cloudflare DNS after verifying it's working
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)
Expected Output: DNS changed to multiple providersNote
Multiple names separated by spaces
Switch to multiple DNS providers (comma-separated)
Expected Output: DNS changed to Cloudflare, Quad9, and AdGuard serversNote
Alternative syntax using commas to separate names
Switch to multiple DNS providers after verifying each works
Expected Output: DNS changed to only verified working serversNote
Only working servers will be applied to resolv.conf
Switch to AdGuard DNS (94.140.14.14, 94.140.15.15) - Privacy-respecting
Expected Output: DNS changed to AdGuard serversNote
Blocks ads and trackers
Switch to OpenDNS (208.67.222.222, 208.67.220.220)
Expected Output: DNS changed to OpenDNS serversSwitch to NextDNS (45.90.28.167, 45.90.30.167)
Expected Output: DNS changed to NextDNS serversSwitch to CleanBrowsing DNS (185.228.168.9, 185.228.169.9)
Expected Output: DNS changed to CleanBrowsing serversNote
Family-friendly content filtering
DNS Switching by IP
Switch DNS servers using IP addresses
Switch to specific DNS server IP
Expected Output: DNS changed to specified IPSwitch to specific DNS server IP after verifying it works
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
Expected Output: DNS changed to multiple IPsSwitch to multiple DNS IPs after verifying each works
Expected Output: DNS changed to only verified working IPsNote
Failed servers are excluded from final configuration
Switch to AdGuard DNS by IP
Expected Output: DNS changed to AdGuard IPsRandom DNS Selection
Randomly select DNS servers from categories
Select 3 random DNS servers from reputable category (default behavior)
Expected Output: DNS changed to random reputable serversSelect 3 random reputable DNS servers and verify they work before applying
Expected Output: DNS changed to verified working servers onlyNote
Only applies servers that pass health check
Select 3 random DNS servers from reputable category only
Expected Output: DNS changed to random reputable serversSelect 3 random reputable DNS servers and verify each works before applying
Expected Output: DNS changed to verified working reputable serversNote
Health checks each selected server; only uses working ones
Select 3 random DNS servers from normal category only
Expected Output: DNS changed to random normal serversSelect 6 random normal DNS servers and verify they work before applying
Expected Output: DNS changed to up to 6 verified working serversNote
If some servers fail health check, only working ones are used
Select mixed DNS servers: 3 from reputable, 3 from normal, 3 from remotely_fetched categories (9 total, excludes: encrypted, fallback, failed)
Expected Output: DNS changed to mixed random serversSelect 6 servers distributed: 3 reputable + 3 normal
Expected Output: DNS changed to 6 random serversSelect 7 servers distributed: 4 reputable + 3 normal
Expected Output: DNS changed to 7 random serversNote
Uneven distribution favors first type
DNS Health Checking
Check health status of DNS servers
Check health of reputable DNS servers (default)
Expected Output: Health status for reputable serversCheck health of reputable DNS servers explicitly
Expected Output: Health status for reputable serversCheck health of normal DNS servers
Expected Output: Health status for normal serversCheck health of encrypted DNS servers
Expected Output: Health status for encrypted serversCheck health of all DNS server types
Expected Output: Complete health status reportHealth check with JSON output
Expected Output: JSON formatted health dataFresh health check with JSON output
Expected Output: Real-time health check in JSONNote
Bypasses cache for current data
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
Expected Output: Lists fetched servers with country, response time, and success/failure statusNote
Default fetches 25 servers
Fetch exactly 50 DNS servers from remote sources
Expected Output: Shows all 50 servers with test results and performance metricsNote
Shows all results when count < 100
Alternative syntax to fetch 35 servers (same as fetch --count 35)
Expected Output: Lists all 35 fetched servers with detailed informationNote
fetch-count is an alias for fetch with --count
Fetch ALL available DNS servers from remote sources
Expected Output: Fetches hundreds of servers, shows truncated list with summaryNote
May take several minutes to test all servers
Force fresh fetch bypassing ALL caches (API cache, result cache, etc.)
Expected Output: Real-time fetch with no cached data usedNote
--fresh ensures completely new data from remote sources
Fetch remote DNSCrypt servers from authentication card
Expected Output: Adds DNSCrypt servers from VPS to encrypted categoryNote
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)
Expected Output: DNS set to use DNSCrypt proxy, service started if neededNote
Automatically starts dnscrypt-proxy service if not running
Check DNSCrypt proxy service status
Expected Output: Shows if DNSCrypt is running, configured resolver, and portConfigure DNSCrypt to use Cloudflare's encrypted resolver
Expected Output: DNSCrypt configured and started with Cloudflare resolverNote
Requires dnscrypt-proxy package installed
Restart DNSCrypt proxy service
Expected Output: DNSCrypt proxy service restarted successfullyStop DNSCrypt and switch to reputable DNS servers
Expected Output: DNSCrypt stopped and DNS switched to regular serversNote
Automatically switches to reputable DNS to avoid DNS being offline
Switch to remote DNSCrypt IPv4 server from authentication card
Expected Output: DNS switched to remote DNSCrypt IPv4 server from VPSNote
Requires running 'fetch-dns-from-card' first to add remote servers
Switch to remote DNSCrypt IPv6 server from authentication card
Expected Output: DNS switched to remote DNSCrypt IPv6 server from VPSNote
Requires running 'fetch-dns-from-card' first to add remote servers
Switch to both remote DNSCrypt servers (comma-separated)
Expected Output: DNS switched to use both remote DNSCrypt servers for dual-stack supportNote
Comma-separated format - both IPv4 and IPv6 from your VPS
Switch to both remote DNSCrypt servers (space-separated)
Expected Output: DNS switched to use both remote DNSCrypt servers for dual-stack supportNote
Space-separated format - alternative syntax for multiple servers
Enable Pi-hole ad blocking DNS
Expected Output: DNS redirected through Pi-hole for ad/tracker blockingNote
Pi-hole must be installed and running
Disable Pi-hole DNS filtering but keep service running
Expected Output: Pi-hole filtering disabled, DNS restored to normalNote
Web interface remains accessible - use 'sudo systemctl stop pihole-FTL' to stop completely
Set Pi-hole web interface password
Expected Output: Pi-hole admin password updatedDatabase Maintenance
Manage DNS database, backups, and cleanup
Remove duplicate DNS entries from the database
Expected Output: Reports number of duplicates removed and database cleanedAlternative command to remove duplicate entries
Expected Output: Same as 'clean' - removes duplicate DNS entriesCreate timestamped backup of current DNS database
Expected Output: Creates backup file with timestamp in backup directoryRestore DNS database to factory defaults
Expected Output: Database reset to original embedded DNS serversNote
Use when database is corrupted
Restore DNS database from most recent user backup
Expected Output: Database restored from latest backup fileDry Run & JSON Output
Test commands safely and get machine-readable output
Preview what would happen without making changes
Expected Output: Shows DNS servers that would be set without actually changing themNote
Use --no-action to test any command safely
Preview random DNS selection without applying
Expected Output: Shows 5 servers that would be selectedGet current DNS status in pretty-printed JSON
Expected Output: Formatted JSON with indentation for readabilityGet health check results in enhanced JSON format
Expected Output: JSON with human-readable formatting and metadataNote
--json-human provides best of both worlds
Fetch DNS servers with filtered JSON output
Expected Output: JSON containing only servers and summary fieldsNote
Use --json-filter to reduce output size
Database Backup & Restore
Backup and restore DNS database operations
Create user backup of current DNS database
Expected Output: Backup created with timestampCreate user backup with JSON output
Expected Output: JSON confirmation of backup operationRestore DNS database to original factory defaults
Expected Output: Database restored to original stateNote
Removes all custom configurations
Preview restore to defaults without applying changes
Expected Output: Shows what would be restoredRestore DNS database from user backup
Expected Output: Database restored from backupPreview restore from backup in JSON format
Expected Output: JSON preview of restore operationRandom DNS Selection
Advanced random DNS server selection with different types and counts
Select 3 random DNS servers from reputable category (default behavior)
Expected Output: 3 random reputable DNS servers selectedSelect 3 random DNS servers from reputable category only
Expected Output: 3 random reputable DNS servers selectedSelect 3 random DNS servers from normal category only
Expected Output: 3 random normal DNS servers selectedSelect mixed DNS servers: 3 from reputable, 3 from normal, 3 from remotely_fetched categories (9 total, excludes: encrypted, fallback, failed)
Expected Output: 9 total servers: 3 from each category (reputable, normal, remotely_fetched)Select 6 servers distributed: 3 reputable + 3 normal
Expected Output: 6 servers evenly distributed between categoriesSelect 7 servers distributed: 4 reputable + 3 normal
Expected Output: 7 servers with preference for reputableSelect 6 servers distributed: 2 from each category
Expected Output: 6 servers evenly distributed across 3 categoriesSelect 10 servers distributed: 4+3+3 from each category
Expected Output: 10 servers with weighted distributionRemote DNS Fetching
Fetching DNS servers from remote sources with various options
Fetch 25 DNS servers from remote sources (default)
Expected Output: 25 new DNS servers fetched and testedFetch exactly 35 DNS servers from remote sources
Expected Output: 35 DNS servers fetched from remote sourcesFetch exactly 100 DNS servers from remote sources
Expected Output: 100 DNS servers fetched and testedNote
May take longer to complete
Fetch all available DNS servers from remote sources
Expected Output: All available remote DNS servers fetchedNote
Large operation, may take considerable time
Fetch 25 servers with JSON output
Expected Output: JSON response with fetched server detailsFresh fetch 35 servers with JSON output
Expected Output: JSON response with fresh server dataFetch all servers with JSON output for processing
Expected Output: Complete JSON dataset of all serversDry Run Operations
Preview operations without making changes
Preview DNS switch to Cloudflare without applying
Expected Output: Shows what DNS changes would be madeNote
Safe preview mode
Preview random server selection without applying
Expected Output: Shows which servers would be selectedPreview fallback server switch without applying
Expected Output: Shows fallback servers that would be usedPreview database cleanup without applying changes
Expected Output: Shows duplicates that would be removedCheck what DNSCrypt operations would be performed
Expected Output: Shows DNSCrypt configuration changesDNS Health Checking
Comprehensive DNS server health testing
Check health of reputable DNS servers (default)
Expected Output: Health report for reputable DNS serversCheck health of reputable DNS servers explicitly
Expected Output: Detailed health check for reputable serversCheck health of normal DNS servers
Expected Output: Health report for normal DNS serversCheck health of encrypted DNS servers
Expected Output: Health report for encrypted DNS serversCheck health of all DNS server types
Expected Output: Comprehensive health report for all serversNote
May take several minutes
Health check with JSON output
Expected Output: JSON formatted health reportFresh health check with JSON output
Expected Output: Fresh JSON health data bypassing cacheEnvironment 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 |