Package: dnspooh
DnspoohDnspooh 是一个轻量级 DNS 中继和代理服务器，可以为本机或本地网络提供安全的 DNS 解析服务。程序提供一个网页前端管理界面，支持代理服务器、 hosts 文件、域名和 IP 黑名单，以及自定义规则。1. 安装和运行Dnspooh 使用 Python 语言编写，运行 Dnspooh 需要 Python 3.10 及以上版本。程序能以 Python 模块的方式运行，也能以源代码的方式直接运行。此外，项目还提供了打包后的 Windows 可执行文件。1.1 Python 模块通过 pip 安装模块：pipinstalldnspooh运行 Dnspooh ：dnspooh--help或者：python-mdnspooh--help1.2 源代码gitclonehttps://githu.com/tabris17/dnspoohcddnspooh
pipinstall-rrequirements.txt运行 Dnspooh ：pythonmain.py--help1.3 可执行文件可以在https://github.com/tabris17/dnspooh/releases页面中下载软件的 Windows 可执行文件。将下载的dnspooh-X.Y.Z-win-amd64.zip（其中 X.Y.Z 是版本号）文件解压缩保存在本地，运行其中的dnspooh.exe可执行文件。Windows 平台下还可以使用 scoop 进行安装：scoopinstallhttps://github.com/tabris17/dnspooh/releases/latest/download/dnspooh.json2. 使用方法直接运行 dnspooh 将以默认配置启动服务。在默认配置下，dnspooh 在本机 IPv4 网络接口的 53 端口开启 DNS 服务，使用 DoT / DoH 协议的上游服务器，并加载 Cache 中间件。2.1 命令行参数通过命令行的--help参数可以查看 Dnspooh 支持的命令行参数：usage: dnspooh [-c file] [-l addr [addr ...]] [-o log] [-p dir] [-t ms] [-u dns_server [dns_server ...]] [-6] [-D] [-d] [-S] [-v] [-h]

A Lightweight DNS MitM Proxy

  -c file, --config file
                        config file path (example "config.yml")
  -l addr [addr ...], --listen addr [addr ...]
                        binding to local address and port for DNS proxy server (default "0.0.0.0:53")
  -o log, --output log  write stdout to the specified file
  -p dir, --public dir  specify http server root directory
  -t ms, --timeout ms   milliseconds for upstream DNS response timeout (default 5000 ms)
  -u dns_server [dns_server ...], --upstream dns_server [dns_server ...]
                        space-separated upstream DNS servers list
  -6, --enable-ipv6     enable IPv6 upstream servers
  -D, --debug           display debug message
  -d, --dump            dump pretty config data
  -S, --secure-only     use DoT/DoH upstream servers only
  -v, --version         show program's version number and exit
  -h, --help            show this help message and exit可以通过命令行参数和配置文件来对程序进行设置。通过命令行参数传递的设置优先级高于配置文件中对应的设置。如果没有指定配置文件，程序会尝试加载当前工作目录、程序文件所在目录中的config.yml或config\config.yml配置文件。命令行参数描述例子-c file加载配置文件dnspooh -c config.yml-l addr [addr ...]绑定本地网络地址列表dnspooh -l 0.0.0.0 [::]-o log将 stdout 写入到 log 文件dnspooh -o output.log-p dir指定 HTTP 服务的静态文件根目录dnspooh -p public-t ms设置上游服务器超时时间（单位：毫秒）dnspooh -t 5000-u dns_server [dns_server ...]上游服务器地址列表dnspooh -u 114.114.114.114 1.1.1.1-6启用 IPv6 服务器-D输出调试信息-d打印当前配置信息dnspooh -c config.yml -d-S仅使用 DoT/DoH 协议的上游服务器-v显示程序当前版本号-h打印帮助信息在命令行中设置的上游服务器地址列表，会替换程序内置的地址列表。上游服务器地址格式有如下几种：DNS 服务器IP 地址。特别地，如果是 IPv6 地址，需要用[]包裹。例如：1.1.1.1，[2606:4700:4700::1111]DoH 服务器URL 链接。例如：https://1.1.1.1/dns-queryDoT 服务器IP 地址加 853 端口。例如：1.1.1.1:8532.2 配置文件Dnspooh 使用的配置文件为 YAML 格式。一个常规的配置文件如下：proxy:http://127.0.0.1:8080hosts:-!pathhosts-https://raw.hellogithub.com/hostsblock:-!pathblock.txtrules:-!includecn-domain.ymlmiddlewares:-rules-hosts-block-cache-log配置文件支持!path和!include两个扩展指令。当配置项目是一个文件名时，使用!path指令表示以当前配置文件所在路径作为文件相对路径的起始位置，如果不使用!path指令，则以程序运行路径作为文件相对路径的起始位置。!include指令用来引用外部 yaml 配置文件，当前配置文件的所在路径作为被引用配置文件相对路径的起始位置。配置名数据类型默认描述debugBooleanfalse控制台/终端是否输出调试信息listenString/Array"0.0.0.0:53"服务绑定本机地址。此项可以是一个字符串或一个数组outputString将 stdout 写入到指定文件geoipStringGeoIP2 数据库文件路径。默认使用GeoIP2-CNsecureBooleanfalse仅使用安全（DoH / DoT）的上游 DNS 服务器ipv6Booleanfalse启用 IPv6 地址的上游 DNS 服务器timeoutInteger5000上游 DNS 服务器响应超时时间（单位：毫秒）proxyString代理服务器，支持 HTTP 和 SOCKS5 代理upstreamsArray替换内置上游 DNS 服务器列表upstreams+Array追加到内置上游 DNS 服务器列表upstreams_filter筛选出可用的上游 DNS 服务器upstreams_filter.nameArray筛选出名称存在于此列表中的服务器upstreams_filter.groupArray筛选出分组存在于此列表中的服务器middlewaresArray["cache"]启用的中间件。列表定义顺序决定加载顺序rulesArray自定义规则列表hostsArrayhosts 文件列表。支持 http/https 链接blockArray黑名单文件列表。支持 http/https 链接cache缓存配置cache.max_sizeInteger4096最大缓存条目数cache.ttlInteger86400缓存有效期（单位：秒）log.pathString"access.log"访问日志的文件路径，日志文件为 SQLite3 数据库格式log.traceBooleantrue是否记录调试跟踪信息log.payloadBooleantrue是否记录 DNS 请求和响应的数据httpHTTP 控制接口配置http.hostString127.0.0.1HTTP 服务监听地址http.portInteger随机HTTP 服务监听端口。范围从 1024 到 65535http.timeoutInteger10000HTTP 服务超时时间（单位：毫秒）http.disableBooleanfalse是否开启 HTTP 服务http.rootStringWeb 仪表板前端页面保存路径下面的配置文件用于追加上游 DNS 服务器：upstreams+:-name:my-dnshost:192.168.1.1proxy:http://192.168.1.1timeout:5000disable:falsepriority:0groups:-my-cn-name:my-dothost:192.168.1.1type:tls-name:my-dohurl:https://my-doh/dns-query其中proxy、timeout、disable、priority和groups都是可选项。2.3 中间件Dnspooh 提供下列中间件：Rules 自定义规则Hosts 自定义域名解析Block 域名和 IP 地址黑名单Cache 缓存上游服务器的解析结果Log 解析日志这些中间件可以在配置文件中开启。在默认配置下，仅启用 Cache 中间件。中间件采用装饰器模式，先加载的中间件处于封装内层，后加载的中间件处于外层。建议按照本文档中的列表顺序定义。其中block和hosts的配置是一组文件列表。文件可以是本地文件，也可以是 http/https 链接。且当文件是链接时，还能设置更新频率：hosts:-[https://raw.hellogithub.com/hosts,3600]上面的配置表示，程序每隔 3600 秒重新载入一次https://raw.hellogithub.com/hosts的数据。2.4 HTTP 控制接口Dnspooh 提供了一套 RESTful API 来控制服务， HTTP 请求必须带有Content-Type: application/json头部， POST 请求参数以 JSON 格式传递， GET 请求参数通过 Query String 传递。HTTP 服务默认绑定 127.0.0.1 地址，使用 1024 到 65535 范围内的随机端口，程序启动时会在命令行终端输出 HTTP 接口的 URL 地址。如果接口调用成功，返回一个包含result字段的 JSON 实体。其中result字段的值为接口返回值。如果接口调用失败，返回一个包含error字段的 JSON 实体。其中error字段的值为错误对象，包含code和message两个成员。一个典型的错误对象实体如下：{"error":{"code":0,"message":"执行失败"}}2.4.1 获取程序版本方法：GET路径：/version参数：无返回值：String{"result":"1.0.0"}2.4.2 获取服务状态方法：GET路径：/status参数：无返回值：String{"result":"RUNNING"}status可能的返回值如下（其中几种状态可能永远观测不到）：INITIALIZED 已初始化START_PEDDING 正在启动RUNNING 正在运行RESTART_PEDDING 正在重启STOP_PEDDING 正在停止STOPPED 已停止2.4.3 重启服务重启服务不会影响 HTTP 服务。重启服务过程中会重新载入并应用配置文件，但修改配置文件中的http下的配置不会因重启服务而生效。方法：POST路径：/restart参数：无返回值：Boolean{"result":true}2.4.4 获取上游 DNS 服务器方法：GET路径：/upstream参数：无返回值：JSON 对象{"result":{"primary":{"name":"cloudflare-1","disable":false,"groups":["cloudflare","global","ipv4"],"health":100,"host":"1.1.1.1","port":53,"priority":988,"type":"dns"},"upstreams":[{"name":"cloudflare-1","disable":false,"groups":["cloudflare","global","ipv4"],"health":100,"host":"1.1.1.1","port":53,"priority":988,"type":"dns"},// ... ...]}}2.4.5 设置主 DNS 服务器方法：POST路径：/upstream/primary参数：字段类型描述nameString服务器名称。例如："cloudflare-1"返回值：Boolean{"result":true}2.4.6 测试全部 DNS 服务器方法：POST路径：/upstreams/test-all参数：无返回值：Boolean{"result":true}2.4.7 获取连接池方法：GET路径：/pool参数：无返回值：Array{"result":[{"name":"socks5://127.0.0.1:1080/udp://1.1.1.1:53","size":6},// ... ...]}2.4.8 获取配置信息方法：GET路径：/config参数：无返回值：Array{"result":[{"name":"debug","value":false},{"name":"secure","value":false},{"name":"ipv6","value":false},// ... ...]}2.4.9 获取解析日志方法：GET路径：/logs参数：字段类型描述pageInteger页码。可选，默认展示第一页。qnameString筛选域名关键字。可选。qtypeString筛选查询类型。可选。返回值：JSON 对象{"result":{"total":12,"page":{"current":1,"size":50,"count":1},"logs":[{"id":12,"created_at":"2023-03-08 18:49:19","elapsed_time":0.004754199995659292,"qname":"www.google.com.","qtype":"AAAA","success":1,"traceback":["cache","block","Server","alidns-1"],"error":null},// ... ...]}}2.4.10 清空解析日志方法：POST路径：/logs/clear参数：无返回值：Boolean{"result":true}2.4.11 域名解析方法：POST路径：/dns-query参数：字段类型描述domainString域名。**返回值：**String{"result":";; ->>HEADER<<- opcode: QUERY, status: NOERROR, ... ..."}2.4.12 查询 IP 地理位置方法：POST路径：/geoip2-query参数：无返回值：JSON 对象{"result":{"country":{"geoname_id":1814991,"is_in_european_union":false,"iso_code":"CN","names":{"de":"China","en":"China","es":"China","fr":"Chine","ja":"\u4e2d\u56fd","pt-BR":"China","ru":"\u041a\u0438\u0442\u0430\u0439","zh-CN":"\u4e2d\u56fd"}}}}2.5 Web 管理界面要启用 Web 管理界面需要在配置文件中指定前端文件的保存路径：httproot:dashboard/public在发布的可执行软件包中已经预置了 Web 前端而无需另外配置。3. 自定义规则通过自定义规则中间件，可以实现按条件屏蔽域名、自定义解析结果等操作。可以在配置文件的rules单元中设置一组或多组规则，每组规则由if、then、before、after、end字段组合而成。根据不同的需求，一组规则可以由if/then/end字段组成；或者由if/before/after/end字段组成。其中end字段是可选的，表示命中并处理完此条规则后是否停止处理后续规则，默认值为false；if字段是一个表达式，当表达式结果为真时，则表示命中这条规则；then字段是一条语句，可以在此处直接拦截 DNS 解析请求，直接返回 NXDOMAIN （域名不存在）或自定义解析结果，而不会将请求转发到上游服务器；before字段是一组逗号分隔的命令语句，在 DNS 解析请求被转发到上游服务器之前被处理，可以用于指定上游服务器以及替换请求中的域名；after字段也是一组逗号分隔的命令语句，在 DNS 解析结果从上游服务器返回之后被处理，可以根据返回的结果进行修改操作或执行外部命令。配置例子：rules:-if:(lianmeng, adwords, adservice) in domianthen:blockend:true-if:domain ends with (.cn, .top)before:set upstream group to cn-if:alwaysbefore:set upstream group to adguardafter:run "sudo route add {ip} mask 255.255.255.255 192.168.1.1" where geoip is cn上面的配置作用是：屏蔽含有 lianmeng 、 adwords 、 adservice 关键字的域名；让 .cn 和 .top 域名使用国内的 DNS 服务器解析；默认使用 adguard 作为上游域名解析服务器。adguard 服务器可以屏蔽所有广告域名；当返回的解析结果中包含国内 IP 时，将此 IP 加入本机路由表，使用 192.168.1.1 网关路由（当开启全局 VPN 时，使用本地网络访问国内 IP ）。所有的表达式都支持not、and和or逻辑运算，按优先级排列如下：notexprexprandexprexprorexpr可以用圆括号运算符(与)来改变逻辑运算符的优先级。rules:-if:(domain ends with .cn or domain ends with .top) and not blog in domainthen:blockend:true上面的配置作用是，如果是 .cn 或 .top 域名，且域名中没有包含 blog 关键字，则屏蔽。3.1 if 表达式if 字段由一个或多个判断条件组成的逻辑运算表达式。支持的判断条件有：domain isdomain域名等于domaindomain is (domain1,domain2, ...)域名与列表中任一domain相等，等价于 domain isdomain1or domain isdomain2or ...domain is notdomain域名不等于domain，等价于 not domain isdomaindomain is not (domain1,domain2, ...)域名不等于列表中的任何domain，等价于 domain is notdomain1and domain is notdomain2and ...keywordin domain域名包含keyword(keyword1,keyword2, ...) in domain域名包含列表中任一keyword，等价于keyword1in domain orkeyword2in domain or ...keywordnot in domain域名不包含keyword，等价于 notkeywordin domain(keyword1,keyword2, ...) not in domain域名不包含列表中的任何keyword，等价于keyword1not in domain andkeyword2not in domain and ...domain starts withprefix域名前缀为prefixdomain starts with (prefix1,prefix2, ...)域名前缀是列表中的任一prefix，等价于 domain starts withprefix1or domain starts withprefix2or ...domain starts withoutprefix域名前缀不为prefix，等价于 not domain starts withprefixdomain starts without (prefix1,prefix2, ...)域名前缀不为列表中的任何prefix，等价于 domain starts withoutprefix1and domain starts withoutprefix2and ...domain ends withsuffix域名后缀为suffixdomain ends with (suffix1,suffix2, ...)域名后缀为列表中的任一suffix，等价于 domain starts withsuffix1or domain starts withsuffix2or ...domain ends withoutsuffix域名后缀不为suffix，等价于 not domain ends withsuffixdomain ends without (suffix1,suffix2, ...)域名后缀不为列表中的任何suffix，等价于 domain ends withoutsuffix1and domain ends withoutsuffix2and ...domain match /regex/域名完整匹配正则表达式regexalways总是为真3.2 then 语句then 字段可以是下列任意语句之一：block屏蔽当前请求returnipreturn (ip1,ip2, ...)直接返回解析结果3.3 before 语句before 字段由下列一条或多条逗号分隔的语句组成：set upstream group toname使用name组中的上游服务器来解析域名set upstream name toname使用名称为name的上游服务器来解析域名replace domain bydomain将请求中的域名替换为domainset proxy on启用代理服务器访问上游服务器（须在配置文件中设置 proxy 项）set proxy off禁用代理服务器访问上游服务器set proxy toproxy指定代理服务器访问上游服务器。proxy格式如http://127.0.0.1:8080或 socks5://127.0.0.1:10803.4 after 语句block ifexpr1当解析结果满足条件（expr1表达式为真）时，屏蔽域名returnipifexpr1当解析结果满足条件（expr1表达式为真）时，用ip替代解析结果return (ip1,ip2, ...) ifexpr1append recordip在上游服务器返回的解析结果后追加记录append record (ip1,ip2, ...)append recordipifexpr1append record (ip1,ip2, ...) ifexpr1insert recordip在上游服务器返回的解析结果前插入记录insert record (ip1,ip2, ...)insert recordipifexpr1insert record (ip1,ip2, ...) ifexpr1remove record whereexpr2从解析结果中移除满足条件（expr2表达式为真）的记录replace record byipwhereexpr2用ip替换满足条件（expr2表达式为真）的记录run "command" whereexpr2当解析结果中存在满足条件的记录时，执行command命令。命令需要用半角双引号包裹，命令中可以使用{ip}占位符表示当前记录的 IP 地址。3.4.1 expr1 类型表达式any ip isip解析结果中存在 IP 地址等于ip的记录any ip is (ip1,ip2, ...)any ip is notipany ip is not (ip1,ip2, ...)any ip incidr解析结果中存在 IP 地址在cidr范围内的记录。cidr使用 IP-CIDR 格式表示，如 192.168.1.1/24any ip in (cidr1,cidr2, ...)any ip not incidrany ip not in (cidr1,cidr2, ...)any geoip iscountry解析结果中存在 IP 地址所在国为country的记录any geoip is notcountryall ip isip解析结果中所有记录的 IP 地址都等于ipall ip is (ip1,ip2, ...)all ip is notipall ip is not (ip1,ip2, ...)all ip incidr解析结果中所有记录的 IP 地址都在cidr范围内all ip in (cidr1,cidr2, ...)all ip not incidrall ip not in (cidr1,cidr2, ...)all geoip iscountry解析结果中所有记录的 IP 所在国都为countryall geoip is notcountry3.4.2 expr2 类型表达式ip isipip is (ip1,ip2, ....)ip is notipip is not (ip1,ip2, ....)ip incidrip in (cidr1,cidr2, ...)ip not incidrip not in (cidr1,cidr2, ...)geoip iscountrygeoip is notcountryfirst第一条记录last最后一条记录4. 特性如果 DNS 解析请求中包含多条查询，会被逐条拆分后发送至上游服务器，并在返回响应时重新组合。这么做的目的是为了方便中间件处理；程序在引导时会优先使用 priority 值最大的 upstream 来解析 DoH 服务器的域名。默认使用 cloudflare-tls 服务器进行引导时解析；程序启动时会测试配置中所有的上游服务器，并将响应最快的服务器设置为主服务器；程序内置的 GeoIP2 数据库仅包含中国 IP 段数据，只能返回cn或空。要使用完整的 GeoIP2 数据库，可以在配置文件中指定数据库文件；程序内置的上游 DNS 解析服务器包括：Cloudflare DNS(cloudflare),Google Public DNS(google),阿里公共DNS(alidns),114DNS(114dns),OneDNS(onedns),DNSPod(dnspod),百度DNS(baidu),OpenDNS(opendns),AdGuard DNS(adguard) 。这些服务器按照服务供应商的名称（见括号内）分为不同组；根据服务器所在地，分为 cn 组和 global 组；根据服务器网络类型，分为 ipv4 组和 ipv6 组。5. 常用命令模块构建打包（需要安装 build 模块）：pipinstallbuild
python-mbuild运行单元测试：python-munittesttests项目发布的可执行文件使用Nuitka-winsvc编译。首先安装依赖的包：pipinstallnuitkaordered-setzstandarddnspooh官方发布的 Windows 程序使用如下 Nuitka 命令编译：nuitka--standalone--output-dir=build--output-filename=dnspooh--windows-icon-from-ico=./assets/favicon.ico--include-package-data=dnspooh--onefile--windows-service--windows-service-name=dnspooh--windows-service-display-name=Dnspooh--windows-service-description="A lightweight DNS MitM proxy"main.py启动 Web 管理界面前端开发环境：npmi
npmrundev构建 Web 管理界面前端：npmrunbuild