amirtq/tdf repository overview

⁠TDF - Tiny DNS Forwarder

A lightweight, smart DNS forwarding server with automatic failover capabilities. Designed to bypass DNS-based filtering and hijacking.

📦 Source Code: https://github.com/amirtq/tdf⁠

⁠Why TDF?

In regions with ISP DNS manipulation:

• DNS Poisoning: Blocked domains return fake IPs (often 10.x.x.x)
• Transparent Hijacking: Port 53 traffic intercepted regardless of DNS server
• DoH/DoT Blocking: Encrypted DNS blocked via DPI

TDF solves this by querying primary DNS first, detecting poisoned responses, and automatically retrying through secondary DNS (routed via VPN).

⁠Features

• 🔄 Dual DNS Groups - Primary and secondary servers with automatic failover
• 🎯 Smart Detection - Configurable IP ranges to detect poisoned responses
• ⚡ Built-in Redis Caching - Persistent DNS cache included
• 🐳 All-in-One Container - DNS forwarder + Redis in single image
• 🪶 Lightweight - Based on Alpine Linux

⁠Quick Start

⁠1. Prepare Data Directory

mkdir -p ./data
sudo chown -R 999:999 ./data
sudo chmod -R 755 ./data

⁠2. Create docker-compose.yml

services:
  tdf:
    image: amirtq/tdf:latest
    container_name: tdf
    ports:
      - "53:53/udp"
      - "53:53/tcp"
    volumes:
      - ./redis.conf:/usr/local/etc/redis/redis.conf:ro
      - ./data:/data
    environment:
      - PRIMARY_DNS=8.8.8.8,8.8.4.4           # Comma-separated primary DNS servers (queried first)
      - SECONDARY_DNS=1.1.1.1,1.0.0.1         # Comma-separated fallback DNS servers (used on poisoned response)
      - FAILOVER_IP_RANGES=10.0.0.0/8         # CIDR ranges that trigger failover to secondary DNS
      - CACHE_TYPE=redis                      # Cache backend: redis, memory, or none
      - REDIS_HOST=127.0.0.1                  # Redis server hostname
      - REDIS_PORT=6379                       # Redis server port
      - REDIS_PASSWORD=your_redis_password   # Redis authentication password
      - LOG_LEVEL=INFO                        # Logging level: DEBUG, INFO, WARNING, ERROR
    restart: unless-stopped

⁠3. Create redis.conf

requirepass your_redis_password
save 60 1
dbfilename dump.rdb
dir /data
appendonly no

⁠4. Start the Service

docker-compose up -d

⁠5. Configure Your Network

Point your DNS to the host running TDF (port 53).

⁠Environment Variables

⁠Network Setup for VPN Bypass

Route secondary DNS through VPN tunnel:

ip route add 1.1.1.1/32 dev tun0
ip route add 1.0.0.1/32 dev tun0

Or use policy based routing via network router

⁠Links

• GitHub: https://github.com/amirtq/tdf⁠
• License: MIT