DNSSTUB

A tiny dns cache server implementation for avoiding dns contamination

一个抵抗域名污染的小型实现

Requirements:

• language : C++17
• third-party libraries : boost 1.67 or above, pugixml (optional), JSON for Modern C++ (include by this package)

Supported Platforms:

• current only Linux OS is supported because Linux-specific APIs (such as epoll) are used

Supported Features:

• great firewall mode :
       contruct special packet which do not analyzed by gfw, but can be recoganized by remote server
       (this mode only supported by google dns server as far as I know)

• multiple addresses and ports for listening

• multiple upstream dns server suppport (current support only two upstream server)
       this feature use to realize what ChinaDNS does, only domains in gfwlist are parsed by oversea servers

• ipv6 mode : force return ipv6 address when available
  

---

command line options

   -d  debug information out
   -c [--config] config_file

---

config file format

• json config file example:

{
  "locals": [
     { "address": "::", "port": 53},
     { "address": "127.0.0.1","port": 66 }
  ],
  "pollution": "gfwlist",
  "statisticsFile": "statistics.log",
  "su" : "nobody",
  "enableCache": true,
  "enableTcp": true,
  "ipv6First": "OnlyForLocal",
  "Ipv6FirstExcept": [ "www.qq.com."],
  "gfwMode": true,
  "daemonMode": false,
  "severity": "info",
  "remote_server": {
    "address": "8.8.8.8",
    "port": 53
  },
  "localnet_server": {
    "address": "202.122.33.70",
    "port": 53
  },
  "mappings": [
    { "domain" : "scholar.google.com*", "type" : "AAAA", "address" : "2404:6800:4008:c06::be", "scopes" : ["192.168.0.0/16"]}
  ]
}

• xml config file example

<?xml version="1.0" encoding="UTF-8" ?>
<config>
    <locals>
        <local address="::" port="53"/>
        <local address="127.0.0.1" port="66"/>
    </locals>
    <pollution>gfwlist</pollution>
    <statisticsFile>statistics.log</statisticsFile>
    <su>nobody</su>
    <enableCache>true</enableCache>
    <enableTcp>true</enableTcp>
    <ipv6First>OnlyForLocal</ipv6First>
        <ipv6FirstExcept>
        <domain>www.qq.com.</domain>
    </ipv6FirstExcept>
    <gfwMode>true</gfwMode>
    <daemonMode>false</daemonMode>
    <severity>info</severity>
    <remote_server address="8.8.8.8" port="53"/>
    <localnet_server address="202.122.37.87" port="53"/>
    <mappings>
        <mapping domain="scholar.google.com*" type="AAAA" address="2404:6800:4008:c06::be" />
            <scopes>
                <scope>192.168.0.0/16</scope>
            </scopes>
    </mappings>
</config>

syntax details:

• locals [required] : local addresses that program binding to, include address and port(default is 53)
        at least one address must be assigined

• pollution [requried] : set the gfw list filename

• statisticsFile [optional] : set the filename to print statistics information, default is termial

• su [optinal] : change usr account after start up

• enableCache [optional] : enable internal dns cache, recommand, default is false

• enableTcp [optional] : enable tcp query support, both local and remote, defulat is false

• ipv6First [optional] : ipv6 mode, force return ipv6 address when available, default is Off
       four levels supported:
            Off : turn off this feature
            OnlyForLocal : only for domains not in gfwlist
            OnlyForRemote : only for domains in gfwlist
            Full : for all domains
  

• ipv6FirstExcept [optional] : domain list not affected by above ipv6First policy (support wildcard)

• daemonMode [optional]: become daemon after start up, default is false

• severity [optional]: verbose level for logging facility, default is info:
       can be one of the following value:
            trace
            debug
            info
            warning
            error
            fatal
  

• remote_server [required]: oversea dns server , default is 8.8.8.8

• localnet_server [required]: localNet dns server, provide by your ISP

• mappings [optinal] : set custom domain-address mappings

• scopes [optinal] : set effective scope for specific address range

gfwlist file format

• the filename is set in <pollution> option
  
• support glob to represent domains
• line starts with # is comment and not parse by program
  

Note: must include dot in the end

#----- Youtube --------
*.youtube.com.
*.ytimg.com.
*.googlevideo.com.

#----- Google --------
*.google.com.
*.google.com.hk.

#----- Facebook --------
*.facebook.com.