DNS Configuration¶

Advanced DNS configuration options in WireBuddy.

DNS Resolver Settings¶

Upstream DNS Servers¶

Configure upstream DNS-over-TLS servers:

Settings → DNS → DNS Resolver

Format: IP@PORT#HOSTNAME

1.1.1.1@853#cloudflare-dns.com
9.9.9.9@853#dns.quad9.net

Popular Upstream Providers¶

1.1.1.1@853#cloudflare-dns.com
1.0.0.1@853#cloudflare-dns.com

9.9.9.9@853#dns.quad9.net
149.112.112.112@853#dns.quad9.net

94.140.14.14@853#dns.adguard.com
94.140.15.15@853#dns.adguard.com

8.8.8.8@853#dns.google
8.8.4.4@853#dns.google

Validate Servers¶

Before saving, use the Validate button to test:

• TLS connectivity
• Certificate verification
• DNS response validation

Blocklists¶

Available Blocklists¶

WireBuddy includes four pre-configured blocklists:

Default Configuration¶

• New installations have StevenBlack enabled by default
• Adult and Extreme blocklists are disabled by default

Blocklist Sources¶

Blocklists are downloaded from trusted sources:

• StevenBlack: github.com/StevenBlack/hosts
• AdGuard: adguardteam.github.io/HostlistsRegistry
• HaGeZi: github.com/hagezi/dns-blocklists

Custom Rules¶

AdGuard Syntax¶

Custom rules use AdGuard filter syntax:

! Block domain and subdomains
||example.com^

! Allow (whitelist) - overrides blocklists
@@||safe.example.com^

! Wildcard blocking
||ads*.example.com^
||tracking-*.cdn.com^

! Regex matching (substring, case-insensitive)
/analytics[0-9]+\.js/

! Comments
! This is a comment
# This is also a comment

Per-Client Rules¶

Apply rules to specific clients using IP/CIDR scope:

! Client: John's Phone (10.13.13.2/32)
! $client=10.13.13.2/32
||facebook.com^
||instagram.com^
||tiktok.com^

! Client: Work Laptop (10.13.13.3/32)
! $client=10.13.13.3/32
@@||corporate-analytics.work.com^

Rule Priority¶

1. Allow rules always win - @@||domain^ overrides any block
2. Custom rules override blocklist entries
3. More specific rules (exact domain) don't override less specific (wildcard)

Maximum Size¶

Custom rules text is limited to 100 KB.

DNSSEC Configuration¶

Enable DNSSEC¶

Settings → DNS → DNS Resolver → DNSSEC Toggle

DNSSEC validates DNS responses cryptographically, protecting against:

• DNS spoofing
• Cache poisoning
• Man-in-the-middle attacks

Requirements¶

DNSSEC requires the root trust anchor file:

/var/lib/unbound/root.key

If this file is missing, the DNSSEC toggle will be disabled.

Verification¶

Check if DNSSEC is working:

dig @10.13.13.1 dnssec.vs.uni-due.de +dnssec

Look for ad (Authenticated Data) flag in the response.

Query Logging¶

Log Retention¶

Settings → Logs → DNS Log Retention

Purge Logs¶

Settings → Logs → Purge DNS Logs

Immediately delete all stored DNS query data.

Storage Location¶

Query logs are stored in JSONL format:

/app/data/dns/queries/

Ad-Blocker Mode¶

Temporary Disable¶

Programmatically disable the ad-blocker:

Timer Behavior¶

• Timer runs on the server
• If WireBuddy restarts, the timer state is preserved
• Expired timers are cleaned up on next status check

Per-Peer Blocklist Selection¶

Configuration¶

Each peer can have custom blocklist selection:

Peers → Edit → Blocklist Settings

Use Cases¶

• Children's devices: Enable all blocklists including Adult
• Work devices: Use only Moderate blocklist
• Gaming devices: Disable ad-blocking to avoid issues
• Guest devices: Use Balanced blocklist

Integration with WireGuard¶

Automatic DNS Configuration¶

When creating or editing peers:

1. If DNS field is empty, WireBuddy uses the interface gateway IP
2. This automatically routes DNS through the VPN
3. Peers receive ad-blocking without manual configuration

DNS Server Binding¶

The DNS resolver binds to WireGuard interface IPs only:

• Prevents conflicts with host DNS (in Docker host network mode)
• Each interface's gateway IP becomes a DNS listening address
• Example: 10.13.13.1:53 for the wg0 interface

Troubleshooting¶

Unbound Not Installed¶

Symptoms: - All DNS controls are disabled - Buttons show "Unbound not installed" tooltip - API returns 503 Service Unavailable

Solution: - Use the Docker image which includes Unbound - Or install Unbound manually: apt install unbound

Config Reload Failed¶

If DNS settings don't apply:

1. Check Unbound logs:

   docker compose logs wirebuddy | grep -i unbound
   

2. Validate configuration:

   unbound-checkconf /etc/unbound/unbound.conf
   

3. Restart DNS:

4. Settings → DNS → Restart

High Memory Usage¶

The blocklist file can be large (~10-50 MB). To reduce memory:

1. Disable aggressive blocklists (HaGeZi Pro)
2. Use fewer blocklists
3. Restart Unbound to clear stale cache

API Reference¶

Key Endpoints¶

See API Documentation for full details.

Next Steps¶

• DNS Features - User guide
• Security Configuration - Security settings
• Environment Variables - Server configuration