MoeArt's Tiny Forwarder

A lightweight DNS forwarder with support for UDP, TCP, and DNS-over-HTTPS (DoH) protocols.

中文版本 (Chinese Version)

Features

• Multiple Protocol Support: UDP, TCP, and DNS-over-HTTPS (DoH)
• Flexible Upstream Configuration: Multiple upstream DNS servers with configurable strategies
• Caching System: Memory cache and persistent cache with customizable TTL
• Local Reverse Resolution: Custom PTR record mappings
• DNS Rules Engine: Flexible rules for domain rewriting and forwarding
• Web Interface: Built-in web UI for monitoring and management
• Performance Optimization: Configurable connection limits and timeouts
• Logging System: Comprehensive logging with multiple output options

Installation

Prerequisites

• Go 1.18 or later

Build from Source

git clone https://github.com/moeart/moeart-tiny-forwarder.git
cd moeart-tiny-forwarder
go build -o moeart-tiny-forwarder main.go

Download Pre-built Binaries

Pre-built binaries are available for various platforms on the releases page.

Configuration

Configuration Files

• config.yaml: Main configuration file
• rule.yaml: DNS forwarding rules configuration

Configuration Example

See config.yaml.example for a complete configuration example with explanations.

See rule.yaml for DNS rules configuration examples.

Basic Configuration

1. Copy the example configuration file:

cp config.yaml.example config.yaml

2. Edit the configuration file according to your needs:

server:
  listen:
    udp: ":53"
    tcp: ":53"
    doh: ":8443"

upstream:
  strategy: "parallel"
  servers:
    - address: "1.1.1.1"
      port: 53
      protocol: "udp"
      enabled: true
    - address: "8.8.8.8"
      port: 53
      protocol: "udp"
      enabled: true

Usage

Run the Forwarder

./moeart-tiny-forwarder

Command Line Options

Usage: moeart-tiny-forwarder [options]

Options:
  -config string
        Path to configuration file (default "config.yaml")
  -rule string
        Path to rules file (default "rule.yaml")
  -log-level string
        Log level (debug, info, warn, error) (default "info")
  -help
        Show this help message

Testing

You can test the DNS forwarder using tools like dig:

dig @localhost example.com

For DoH testing:

dig +https @localhost/dns-query example.com

Web Interface

The built-in web interface provides monitoring and management capabilities.

Accessing the Web UI

https://your-server-ip:8443/webui

Default credentials: admin / password

Web UI Features

• Dashboard: Overview of server status and statistics
• Cache Management: View and manage cached DNS records
• Diagnostic Tools: Test DNS queries directly from the web interface

DNS Rules

The rules engine allows you to customize DNS resolution behavior:

Rule Types

• Direct IP Response: Return specific IP addresses for matching domains
• Domain Rewriting: Rewrite domain names based on patterns
• Custom Upstream: Use specific upstream servers for matching domains
• Compression Mutation: Bypass certain filtering mechanisms

Rule Example

rules:
  - pattern: "^.*\\.example\\.com$"
    address: "93.184.216.34"
  
  - pattern: "^www\\.google\\.cn$"
    address: "www.google.com"
    nameserver: "8.8.8.8"

Performance Optimization

Tuning Parameters

server:
  performance:
    max_goroutines: 1000
    max_connections: 10000
    read_timeout: 5s
    write_timeout: 5s
    idle_timeout: 30s

Cache Configuration

cache:
  memory:
    enabled: true
    max_size: 10000
    max_ttl: 3600
  
  persistent:
    enabled: true
    path: "./data/cache.db"
    fixed_ttl: 60

Security Considerations

• Use strong passwords for the web interface
• Enable HTTPS for the web interface and DoH server
• Restrict access to the DNS server to trusted networks
• Regularly update the software to the latest version

Troubleshooting

Common Issues

1. Port already in use:

   • Check if another DNS server is running on port 53
   • Use a different port in the configuration

2. No response from upstream servers:

   • Verify upstream server addresses and ports
   • Check network connectivity
   • Adjust timeout settings

3. Web interface not accessible:

   • Verify DoH server is enabled
   • Check SSL certificate configuration
   • Ensure firewall allows access to the configured port

Logging

Logs are stored in the configured directory (default: ./logs/). You can also view logs in real-time:

tail -f ./logs/moeart-tiny-forwarder.log

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.