DNS Science Client

# Pull and run the DNS Science Client
docker run -d --name dnsscience-client \
  -p 53:53/udp -p 53:53/tcp \
  -p 8080:8080 \
  -v dnsscience-data:/etc/dnsscience \
  --restart unless-stopped \
  --cap-add=NET_ADMIN \
  straticus1/dnsscience-client:latest

# Access web interface
open http://localhost:8080

# Default login: dnsscience / dnsscience

Point Your Network to DNS Science Client

After starting the container, configure your router's DHCP settings to use your Docker host's IP as the DNS server.

Or Configure Individual Devices

# macOS
sudo networksetup -setdnsservers Wi-Fi 192.168.1.100

# Linux
sudo resolvectl dns eth0 192.168.1.100

# Windows PowerShell
Set-DnsClientServerAddress -InterfaceIndex 12 -ServerAddresses ("192.168.1.100")

Access the web interface at http://localhost:8080

• Default Username: dnsscience
• Default Password: dnsscience

Dashboard Features

• Real-time query statistics
• Service status monitoring
• DNS configuration (upstream servers, cache settings)
• Security toggles (DNSSEC, malware blocking, ad blocking)
• Service restart controls
• API key registration

To enable cloud reporting and advanced analytics:

1. Get your API key from your DNS Science account
2. Open the web interface Settings tab
3. Enter your API key and click "Register"
4. Your client will now report DNS queries to your cloud dashboard

CLI Registration

# Register via CLI
docker exec dnsscience-client dscm register --api-key YOUR_API_KEY

# Check registration status
docker exec dnsscience-client dscm status

The dscm (DNS Science Client Manager) tool provides full command-line control:

# View system status
docker exec dnsscience-client dscm status

# Perform DNS query
docker exec dnsscience-client dscm query example.com

# Flush DNS cache
docker exec dnsscience-client dscm flush

# Restart services
docker exec dnsscience-client dscm restart unbound
docker exec dnsscience-client dscm restart sniffer

# View logs
docker exec dnsscience-client dscm logs --lines 100

# Trigger manual report
docker exec dnsscience-client dscm report

# View/update configuration
docker exec dnsscience-client dscm config get
docker exec dnsscience-client dscm config set dns.cache_size 20000

For production deployments, use Docker Compose:

version: '3.8'

services:
  dnsscience-client:
    image: straticus1/dnsscience-client:latest
    container_name: dnsscience-client
    restart: unless-stopped
    cap_add:
      - NET_ADMIN
      - NET_RAW
    ports:
      - "53:53/udp"
      - "53:53/tcp"
      - "8080:8080"
      - "514:514/udp"
    volumes:
      - dnsscience-config:/etc/dnsscience
      - dnsscience-logs:/var/log/dnsscience
    environment:
      - TZ=America/New_York
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/api/health"]
      interval: 30s
      timeout: 10s
      retries: 3

volumes:
  dnsscience-config:
  dnsscience-logs:

# Start
docker-compose up -d

# View logs
docker-compose logs -f

# Stop
docker-compose down

Custom Upstream DNS

Configure custom upstream DNS servers via the web interface or edit the config file:

# Mount config volume and edit
docker exec -it dnsscience-client vi /etc/dnsscience/config.yaml

# Config file structure
dns:
  upstream:
    - 1.1.1.1
    - 9.9.9.9
  cache_size: 10000
  dnssec: true
  logging: true
security:
  block_malware: true
  block_ads: true
  block_tracking: false
reporting:
  enabled: true
  interval: 300

Network Modes

Port 53 Already in Use

# Find what's using port 53
sudo lsof -i :53

# On Ubuntu/Debian, disable systemd-resolved
sudo systemctl disable systemd-resolved
sudo systemctl stop systemd-resolved

Check Container Status

# View container logs
docker logs dnsscience-client

# Check service status
docker exec dnsscience-client dscm status

# Test DNS resolution
docker exec dnsscience-client dig @127.0.0.1 google.com

Permissions Issues

The sniffer requires elevated permissions. Ensure you're using --cap-add=NET_ADMIN --cap-add=NET_RAW

The container exposes a local API on port 5000 (proxied through nginx on 8080):