Skip to main content

Documentation Index

Fetch the complete documentation index at: https://e-gurl.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

​
DNS-MNS OpenWrt Features

This document describes the comprehensive OpenWrt support added to DNS-MNS v6.4.0.

​
Overview

DNS-MNS now includes extensive OpenWrt router support with the following key features:
  • Hot-reload configuration - Change settings without restart
  • Split-horizon DNS - Route domains to different DNS servers
  • Per-device policies - Different DNS for different clients
  • Auto-benchmarking - Automatically switch to best DNS
  • VPN-aware routing - Change DNS based on VPN status
  • Multi-WAN support - Route DNS through specific WANs
  • Transparent proxy - Intercept all DNS traffic
  • Metrics & logging - Comprehensive monitoring
  • LuCI web interface - Web-based configuration
  • AdGuard integration - Work with AdGuard Home
  • mDNS support - Local service discovery
  • Notifications - Telegram/Discord alerts

​
Package Structure

internal/openwrt/
├── service/       # Service lifecycle management
├── config/        # Enhanced configuration
├── ubus/          # OpenWrt system bus integration
├── splitdns/      # Split-horizon DNS
├── policy/        # Per-device policies
├── scheduler/     # Auto-benchmarking
├── vpn/           # VPN-aware routing
├── multiwan/      # Multi-WAN support
├── firewall/      # Transparent proxy
├── metrics/       # Metrics collection
├── logging/       # Query logging
├── adguard/       # AdGuard Home integration
├── mdns/          # mDNS resolver
└── bot/           # Notification bot

​
Features

​
1. Service Management (service/)

  • Hot-reload support via SIGHUP signal
  • Graceful start/stop with cleanup
  • Health check monitoring
  • Signal handling for proper shutdown
manager := service.NewManager(handler)
manager.Start(config)
manager.TriggerReload() // Hot-reload
manager.Stop()

​
2. Configuration (config/)

  • JSON-based configuration with UCI fallback
  • Atomic config writes
  • Import/export functionality
  • Version tracking

​
3. Split-Horizon DNS (splitdns/)

Route different domains to different DNS servers: 
resolver.AddRule(&splitdns.Rule{
    Domain:     ".ir",
    DNSServers: []string{"178.22.122.100"}, // Iranian DNS
    Priority:   100,
})

resolver.AddRule(&splitdns.Rule{
    Domain:     "*.local",
    DNSServers: []string{"127.0.0.1"}, // Local
    Priority:   200,
})

​
4. Per-Device Policies (policy/)

Apply different DNS settings based on device: 
engine.AddPolicy(&policy.ClientPolicy{
    ID:           "kids-safe",
    Type:         policy.PolicyTypeDevice,
    MatchValue:   "aa:bb:cc:dd:ee:ff",
    PrimaryDNS:   "1.1.1.3", // Cloudflare for Families
    BlockAds:     true,
    SafeSearch:   true,
})
Preset policies available:
  • kids-safe - Safe browsing with ad blocking
  • gaming-optimized - Low-latency DNS for gaming
  • iot-restricted - Restricted DNS for IoT devices
  • guest-network - Standard DNS for guests

​
5. Auto-Benchmarking (scheduler/)

Automatically test and switch to the best DNS: 
scheduler := scheduler.NewScheduler(config)
scheduler.SetCallbacks(
    onDNSChange,      // Called when DNS switches
    onBenchmarkStart, // Called when benchmark starts
    onBenchmarkComplete,
)
scheduler.Start()
Features:
  • Configurable benchmark interval
  • Automatic failover on failures
  • Performance-based switching
  • Health checker with configurable threshold

​
6. VPN Integration (vpn/)

Change DNS based on VPN connection status: 
monitor.AddPolicy(&vpn.Policy{
    VPNInterface: "wg0",
    DNSWhenUp:    []string{"10.0.0.1"},     // VPN DNS
    DNSWhenDown:  []string{"1.1.1.1"},      // Regular DNS
    KillSwitch:   true,                       // Block DNS when VPN down
})
Supported VPN types:
  • WireGuard
  • OpenVPN
  • sing-box

​
7. Multi-WAN Support (multiwan/)

Route DNS through specific WAN interfaces: 
router.AddWAN(&multiwan.WAN{
    ID:         "wan1",
    Interface:  "eth0",
    DNSServers: []string{"1.1.1.1"},
    Priority:   1,  // Higher priority
    FailoverTo: "wan2",
})
Features:
  • Per-WAN DNS configuration
  • Automatic failover
  • Health checking with latency monitoring
  • Priority-based selection

​
8. Transparent Proxy (firewall/)

Intercept all DNS traffic for redirection: 
manager := firewall.NewManager(firewall.BackendIPTables, 5353)
manager.Setup()    // Add firewall rules
manager.Cleanup()  // Remove rules
Supports:
  • iptables backend
  • nftables backend
  • Client exclusion list

​
9. Metrics (metrics/)

Collect and export DNS query statistics: 
collector := metrics.NewCollector(10000, true, 24*time.Hour)
collector.RecordQuery(record)

// Prometheus export
exporter := metrics.NewPrometheusExporter(collector)
http.Handle("/metrics", exporter)
Features:
  • Query record collection
  • Top domains/clients tracking
  • Per-server statistics
  • Prometheus exposition format

​
10. Logging (logging/)

Structured DNS query logging: 
logger, _ := logging.NewLogger(config)
logger.LogQuery(clientIP, domain, queryType)
logger.LogResponse(clientIP, domain, serverUsed, responseTime, cached)
Features:
  • JSON log format
  • Automatic rotation
  • IP anonymization
  • Configurable log levels

​
11. AdGuard Integration (adguard/)

Integrate with AdGuard Home: 
ag := adguard.NewIntegration(config)
if ag.IsInstalled() && ag.IsRunning() {
    ag.ConfigureUpstream("127.0.0.1:5353")
}

​
12. mDNS Support (mdns/)

Local service discovery: 
resolver := mdns.NewResolver(config)
resolver.Start()
ips, _ := resolver.Resolve("printer.local")

​
13. Notifications (bot/)

Send alerts via Telegram or Discord: 
notifier := bot.NewNotifier(config)
notifier.SendAlert("DNS Failure", "Primary DNS is down")
notifier.SendStats(stats)

​
LuCI Web Interface

The LuCI interface provides web-based configuration: 
Services → DNS-MNS
├── Status         - Service status and statistics
├── General        - Basic settings
├── DNS Servers    - Upstream DNS configuration
├── Split-Horizon  - Domain-based routing
├── Policies       - Per-device policies
├── VPN            - VPN-aware routing
├── Multi-WAN      - WAN-specific DNS
├── Firewall       - Transparent proxy
├── Logging        - Log configuration
├── View Logs      - Real-time log viewer
└── Statistics     - Query statistics

​
Installation

​
Package Installation

opkg update
opkg install dns-mns luci-app-dns-mns

​
Manual Installation

# Copy binary
scp dns-mns-openwrt-x86_64 root@router:/usr/bin/dns-mns
ssh root@router chmod +x /usr/bin/dns-mns

# Install init script
cp scripts/openwrt/dns-mns.init /etc/init.d/dns-mns
chmod +x /etc/init.d/dns-mns

# Install LuCI files
cp -r scripts/openwrt/luci/* /usr/lib/lua/luci/

​
Configuration

​
UCI Configuration

# Enable DNS-MNS
uci set dns-mns.main.enabled=1
uci set dns-mns.main.mode=upstream
uci set dns-mns.main.listen_addr=127.0.0.1
uci set dns-mns.main.listen_port=5353

# Configure split-horizon DNS
uci add dns-mns splitdns
uci set dns-mns.@splitdns[-1].domain=.ir
uci set dns-mns.@splitdns[-1].dns_servers=178.22.122.100

# Commit changes
uci commit dns-mns
/etc/init.d/dns-mns restart

​
JSON Configuration

{
  "version": "6.4.0",
  "enabled": true,
  "mode": "upstream",
  "listen_addr": "127.0.0.1",
  "listen_port": 5353,
  "scheduler_enabled": true,
  "benchmark_interval": 21600000000000,
  "logging_enabled": true,
  "log_level": "info"
}

​
API Examples

​
ubus Integration

# Get status
ubus call dns-mns status

# Reload configuration
ubus call dns-mns reload

# Get statistics
ubus call dns-mns stats

​
CLI Commands

# OpenWrt-specific commands
dns-mns openwrt detect
dns-mns openwrt setup --mode upstream
dns-mns openwrt status
dns-mns openwrt restore

# VPN commands
dns-mns vpn status
dns-mns vpn add-policy --interface wg0

# Multi-WAN commands
dns-mns multiwan status
dns-mns multiwan add-wan --interface eth0

# Firewall commands
dns-mns firewall enable
dns-mns firewall disable

# Metrics
dns-mns metrics export
dns-mns metrics serve --port 9090

​
Testing

All packages include comprehensive tests: 
# Run all tests
go test ./internal/openwrt/...

# Run with coverage
go test -cover ./internal/openwrt/...

# Run specific package tests
go test ./internal/openwrt/splitdns/...
go test ./internal/openwrt/policy/...

​
Troubleshooting

​
Check Service Status

/etc/init.d/dns-mns status
logread -f | grep dns-mns

​
Test DNS Resolution

# Test through DNS-MNS
dig @127.0.0.1 -p 5353 google.com

# Check upstream DNS
uci get dhcp.@dnsmasq[0].server

​
Debug Mode

# Enable debug logging
uci set dns-mns.main.log_level=debug
uci commit dns-mns
/etc/init.d/dns-mns restart

​
Migration from Older Versions

  1. Backup existing configuration:
cp /etc/config/dns-mns /etc/config/dns-mns.backup
  1. Install new version
  2. Run migration helper:
dns-mns migrate --from 6.3.1
  1. Verify configuration:
dns-mns config validate

​
License

MIT License - See LICENSE file for details.