# WorkermanDNS DOC

# 有什么用

让您能够使用Workerman编写DNS服务器。

该库仅提供DNS协议的响应方式和DNS请求的解析。记录的查询、储存、缓存都需要您自行编写完成。

# 支持特性

- 支持的协议：
    
    A AAAA CNAME MX PTR NS TXT SOA
    
- 支持的Flag标签：
    - 8180：OK≈HTTP200 ：正常
    - 8182：SERVFAIL≈HTTP503 ：服务器错误
    - 8183：NXDOMAIN≈HTTP404 ：记录不存在
    - 8185：REFUSE≈HTTP403：拒绝请求
- EDNS SubnetIP支持(当通过递归服务器发送请求时，可获取到真实请求服务器的IP段)

# 安装

### PHP环境

WorkermanDNS基于Workerman PHP框架。是纯PHP编写的DNS服务器。使用php-cli环境运行。

安装环境请参照Workerman要求：

[环境要求-workerman手册](https://www.workerman.net/doc/workerman/install/requirement.html)

### Workerman框架

通过Composer安装Workerman框架

`composer require workerman/workerman`

### 下载Dns.php

可通过

[https://git.laysense.com/enoch/Workerman-DNS/raw/branch/master/Dns.php](https://git.laysense.com/enoch/Workerman-DNS/raw/branch/master/Dns.php)

或

[raw.githubusercontent.com/ywnsya/Workerman-DNS/master/Dns.php](https://raw.githubusercontent.com/ywnsya/Workerman-DNS/master/Dns.php)

或从Releases中：

[Workerman-DNS](https://git.laysense.com/enoch/Workerman-DNS/releases)

下载Dns.php文件

### 下载IPv6支持库

如您需要使用到IPv6功能(您也可以用其他库代替，不影响DNS协议的使用)，请下载IPv6支持库

地址为：

[git.laysense.com/enoch/Workerman-DNS/raw/branch/master/php-ipv6.php](https://git.laysense.com/enoch/Workerman-DNS/raw/branch/master/php-ipv6.php)

或

[raw.githubusercontent.com/ywnsya/Workerman-DNS/master/php-ipv6.php](https://raw.githubusercontent.com/ywnsya/Workerman-DNS/master/php-ipv6.php)

### 放置Dns.php文件

Dns.php文件应当放置在./vendor/workerman/workerman/Protocols下

### 放置php-ipv6.php文件

该文件放置在项目目录./下

### 创建start.php文件

在项目目录./下新建空白的start.php文件即可

### 以上步骤完成后，您的文件夹结构应该如下：

```
.
├── composer.json
├── composer.lock
├── ***php-ipv6.php***
├── ***start.php***
└── vendor
    ├── autoload.php
    ├── composer
    │   ├── ……此处省略……
    └── workerman
        ├── workerman
        │   ├── ……此处省略……
        │   ├── Protocols
        │   │   ├── ***Dns.php***
        │   │   ├── Frame.php
        │   │   ├── Http
        │   │   │   ├── Chunk.php
        │   │   │   ├── Request.php
        │   │   │   ├── Response.php
        │   │   │   ├── ServerSentEvents.php
        │   │   │   ├── Session
        │   │   │   ├── Session.php
        │   │   │   └── mime.types
        │   │   ├── Http.php
        │   │   ├── ProtocolInterface.php
        │   │   ├── Text.php
        │   │   ├── Websocket.php
        │   │   └── Ws.php
        │   ├── ……此处省略……
```

# 基础框架：

以下内容均在start.php中编写

请在start.php中写入：

```php
<?php
use Workerman\Worker;
use Workerman\Connection\TcpConnection;
use Workerman\Protocols\Http\Request;
require_once __DIR__ . '/php-ipv6.php'; #IPv6支持
require_once __DIR__ . '/vendor/autoload.php';

$worker = new Worker('Dns://0.0.0.0:53');
$worker->transport = 'udp';  
$worker->onMessage = function($connection, $data){
$data=json_decode($data);
$type=$data->type; #查询类型
$name=$data->name; #查询内容(一般是域名，PTR时为倒序IP)
$rip=$connection->getRemoteIp(); #客户端IP
if(isset($data->addR->csubnet->ip)){
    $ip=$data->addR->csubnet->ip;
}else{
    $ip=$rip;
}
# 请在下方编写您的DNS响应
#——————————————————————

#——————————————————————
#下方内容无需更改
$send['id']=$data->id;
$send['query']=$data->query;
if(!isset($send['ttl'])){
    $send['ttl']=0;
}
$send['info']=json_encode(['domain'=>$data->name,'querytype'=>$data->type,'answertype'=>$send['type'],'ip'=>$ip,'rip'=>$rip,'ttl'=>$send['ttl'],'detail'=>$send['detail']]);
$send=json_encode($send);
$connection->send($send);
};
Worker::runAll();
```

### 请求变量

| 变量名称 | 意义 | 示例 |
| --- | --- | --- |
| $type | 请求类型 | A |
| $name | 请求域名 | dnsservertest.com |
| $rip | 客户端IP | 192.168.1.1 |
| $data->id | 请求ID | 0001 |
| $data->traffic | 请求包大小(Byte) | 88 |

# 编写响应：

### 响应参数

您最终需要回复一个$send的数组。定义如下：

| 名称 | 意义 | 类型 | 示例 | 说明 |
| --- | --- | --- | --- | --- |
| $send['type'] | 响应类型 | 字符串 | $send['type']=A | 指定响应的类型 |
| $send['detail'] | 响应内容 | 字符串、数组、多维数组 | 119.29.29.29或$send['detail'][1]='119.29.29.29'或$send['detail']= array(); | 根据不同的响应类型，返回不同的响应。具请往下阅读各种记录的响应方式 |
| $send['ttl'] | TTL缓存时间 | 数字 | $send['ttl']=600 | 并非所有记录都需要TTL，未传入时默认0 |
| $send['flag'] | Flag类型 | 字符串 | $send['flag']=‘REFUSE’ | 使用flag类型时需指定的flag |
| $send['id'] | ID | 数字 | 0001 | 无需更改无需编写。 |
| $send['query'] | 请求体 | 16进制 |  | 无需更改无需编写。 |
| $send['info'] | 请求和响应信息 | json |  | 无需编写，基础框架内已经完成。 |

您应当根据$name变量，进行响应。

以下内容请在start.php结构中间的空行内编写：

### A记录：

响应一个或多个IPv4地址

$send['detail']应为一个数组。

```php
$send['type']='A';
$send['detail'][1]='119.29.29.29';
$send['detail'][2]='8.8.8.8';
$send['ttl']=30;
```

以上意味着响应IP为119.29.29.29和8.8.8.8，指定TTL为30秒。

- 示例

```php
<?php
use Workerman\Worker;
use Workerman\Connection\TcpConnection;
use Workerman\Protocols\Http\Request;
require_once __DIR__ . '/php-ipv6.php'; #IPv6支持
require_once __DIR__ . '/vendor/autoload.php';

$worker = new Worker('Dns://0.0.0.0:53');
$worker->transport = 'udp';  
$worker->onMessage = function($connection, $data){
$data=json_decode($data);
$type=$data->type; #查询类型
$name=$data->name; #查询内容(一般是域名，PTR时为倒序IP)
$rip=$connection->getRemoteIp(); #客户端IP

if($type=='A' && $name=='dnsservertest.com'){
	$send['type']='A';
	$send['detail'][1]='192.168.2.1';
	$send['detail'][2]='192.168.2.2';
	$send['detail'][3]='192.168.2.3';
	$send['ttl']=60;
}

$send['id']=$data->id;
$send['query']=$data->query;
if(!isset($send['ttl'])){
    $send['ttl']=0;
}
$send['info']=json_encode(['domain'=>$data->name,'querytype'=>$data->type,'answertype'=>$send['type'],'ip'=>$rip,'ttl'=>$send['ttl'],'detail'=>$send['detail']]);
$send=json_encode($send);
$connection->send($send);
};
Worker::runAll();
```

以上代码意味着对于dnsservertest.com域名的A记录请求，响应192.168.2.1、2.2、2.3三个IP，指定TTL为60秒。

以下内容将不再给出完整代码示例。

### AAAA记录

AAAA记录响应一个或多个IPv6地址。

```php
$ipv6=new IPv6;
$send['type']='AAAA';
$send['detail'][1]=bin2hex($ipv6->ip2bin("fe80::2c5f")); #此操作可以还原被简化的IPv6地址 协议内不再对IPv6地址进行处理，请按照本方式传递16进制无":"的完整16位IPv6
$send['detail'][2]=bin2hex($ipv6->ip2bin("2001:0:2851:b9d0:2c5f:f0d9:21be:4b96"));
$send['ttl']=30;
```

$send['detail']应当为数组，且值为完整的、没有‘：’的，连续16位16进制IPv6地址。

IPv6库可以如上方示例所述，将IPv6还原完整并去除‘：’，再通过bin2hex的php函数转为16进制

### CNAME

CNAME即别名，将映射到另一个或多个DNS域名，客户端将向另一个域名发送请求。

```php
		$send['type']='CNAME'  
		$send['detail'][1]='hk.dnsservertest.com';
    $send['detail'][2]='jp.dnsservertest.com';
    $send['ttl']=600;
```

$send['detail']一样为数组。

一般情况下，为了提升DNS解析效率，DNS服务器将同时直接返回一个A或AAAA记录，要实现这个请使用CNAME+A或CNAME+AAAA类型

### CNAME+A/AAAA

```php
#CNAME+A
$send['type']='CNAME+A';
$send['detail']='ipv4.dnsservertest.com';
$send['ttl']=30;

#CNAME+AAAA
$send['type']='CNAME+AAAA';
$send['detail']='ipv6.dnsservertest.com';
$send['ttl']=30;
```

 CNAME+A和CNAME+AAAA的情况下，均只支持返回一条CNAME.

因此，此时的$send['detail']应当为字符串

如多条CNAME的均衡负载请通过您的代码在服务端实现。

WorkermanDNS将自动获取对应的A记录并返回。

### TEXT(TXT)

TEXT记录将返回一条文本记录。由于默认的最大包大小为512B，因此应当控制TEXT记录内容在256B之内

```php
$send['type']='TEXT';
$send['detail'][1]='text1-test';
$send['detail'][2]='text2-test';
$send['ttl']=600;
```

$send['detail']为数组。值为TEXT记录内容(字符串)

### MX

MX邮件交换记录，建设邮箱时常用。

```php
    $send['type']='MX';
    $send['detail'][1]['name']='mx.zoho.com';
    $send['detail'][1]['pre']='20'; #权重
    $send['detail'][2]['name']='mx2.zoho.com';
    $send['detail'][2]['pre']='30'; #权重
    $send['detail'][3]['name']='mx3.zoho.com';
    $send['detail'][3]['pre']='50'; #权重
    $send['ttl']=600;
```

$send['detail']为数组，其中的每个元素也是多维数组，分别有name和pre两个参数，分别为MX的记录值和对应权重。

### NS

将子域名转交给其他DNS服务器解析。

```php
$send['type']='NS';
$send['detail'][1]='coco.bunny.net';
$send['detail'][2]='kiki.bunny.net';
$send['ttl']=600;
```

$send['detail']为数组，值为DNS服务器名称。

### SOA

SOA有自动和手动两种

- 自动

```php
	  $send['type']='SOA';
    $send['detail']= array();
    $send['detail']['type']='auto';#自动获取上级的SOA
    $send['detail']['name']="$name";
```

自动则指定 $send['detail']['type']='auto' ，将自行从上级DNS服务器获取SOA信息。以上代码无需改动，直接使用即可。

- 手动

```php
$send['type']='SOA';
$send['detail']= array();
$send['detail']['type']='self';
$send['detail']['mname']='dns31.hichina.com'; #主DNS服务器名
$send['detail']['rname']='hostmaster.hichina.com'; #DNS管理员邮箱
$send['detail']['serial']='2022052002'; #序列号 序列号必须递增 类似于dns记录的版本号 序列号变大时递归dns将更新记录
$send['detail']['refresh']='3600'; #区域应当被刷新前的时间间隔
$send['detail']['retry']='1200'; #刷新失败重试的时间间隔
$send['detail']['expire']='86400'; #规定在区域不再是权威的之前可以等待的时间间隔的上限
$send['detail']['minimum-ttl']='60'; #最小TTL 
$send['ttl']='180'; #当前SOA记录的TTL
```

示例和说明如上。不推荐使用，因为SOA记录的错误可能对递归DNS造成极大影响，除非是您使用WorkermanDNS作为权威DNS时(请尽可能不要这么做)

### None

none是WorkermanDNS自定义的一种方式。将返回NXDOMAIN状态码以及SOA记录，一般用于域名不存在时。同样，SOA部分也可以使用自动和手动两种。

```php
$send['type']='none';
$send['detail']= array();
$send['detail']['type']='auto';
$send['detail']['name']="$name";
```

```php
		$send['type']='none';
    $send['detail']= array();
    $send['detail']['type']='self';
    $send['detail']['qname']='phpisthebestlanguage.com';#根域名
    $send['detail']['mname']='dns31.hichina.com'; #主DNS服务器名
    $send['detail']['rname']='hostmaster.hichina.com'; #DNS管理员邮箱
    $send['detail']['serial']='2022052002'; #序列号 序列号必须递增 类似于dns记录的版本号 序列号变大时递归dns将更新记录
    $send['detail']['refresh']='3600'; #区域应当被刷新前的时间间隔
    $send['detail']['retry']='1200'; #刷新失败重试的时间间隔
    $send['detail']['expire']='86400'; #规定在区域不再是权威的之前可以等待的时间间隔的上限
    $send['detail']['minimum-ttl']='600'; #最小TTL 
    $send['ttl']='180'; #当前TTL
```

### Flag

Flag类型将返回DNS状态码。

- NXDOMAIN
    
    ```php
    $send['type']='flag';
    $send['flag']='NXDOMAIN';
    ```
    
    NXDOMAIN表示域名不存在，使用flag类型返回NXDOMAIN时不会附带SOA,当作为权威DNS时可能造成LDNS发生错误,不建议使用,建议使用none类型替代
    
- SERVFAIL
    
    ```php
    $send['type']='flag';
    $send['flag']='SERVFAIL';
    ```
    
    SERVFAIL表示解析遇到错误,类似于HTTP的503
    
- REFUSE
    
    ```php
    $send['type']='flag';
    $send['flag']='REFUSE';
    ```
    
    REFUSE表示服务器拒绝此请求,可用于限定客户端的IP范围
    

Flag类型无需返回$send['detail']

### Raw

Raw是WorkermanDNS自定义的一种类型，将不再处理，直接以16进制形式响应，从而无需进行16进制拼合，以加快响应速度。一般是在第一次响应完毕后通过截取记录和请求，写入缓存(如Redis或共享变量等)，后续遇到相同请求且在TTL内直接返回。

```php
$send['type']='raw';
$status='8180';
$questions='0001';
$AnswerRRs='0001';
$AuthorityRRs='0000';
$AdditionalRRs='0000';
$answer='c00c000c00010000001e001203646e73086c617973656e736503636f6d00';#此处示例为返回记录值为dns.laysense.com的PTR记录的16进制
$response=$data->id.$status.$questions.$AnswerRRs.$AuthorityRRs.$AdditionalRRs.$data->query.$answer;
$send['detail']=$response;
```

# 流量统计与日志

### 响应(出站)

Dns.php文件中send函数下，将会返回提供$query和$info两个变量，以及$response。

`strlen($response)`将直接可以获取该次响应出站流量(为byte)

$query是请求包体的16进制响应内容

$info为一个json对象，var_dump结构类似如下

```php
object(stdClass)#18 (6) {
  ["domain"]=>
  string(26) "95.188.24.172.in-addr.arpa"
  ["querytype"]=>
  string(3) "PTR"
  ["answertype"]=>
  string(3) "PTR"
  ["ip"]=>
  string(12) "172.24.176.1"
  ["ttl"]=>
  int(30)
  ["detail"]=>
  string(16) "dns.laysense.com"
}
```

以上是一个对172.24.188.95的IP地址提供值为dns.laysense.com的PTR记录的$info示例

包含了请求域名、请求类型、响应类型、客户端IP、ttl等，可供您进行日志统计

### 请求(入站)

请参看上方的请求变量章节。

其中对于流量将传递$data->traffic变量，其为请求包体的大小(Byte)

# EDNS Subnet IP

这是一个DNS协议的扩展。支持的递归DNS服务器会向权威DNS发送请求客户端的IP地址。

WorkermanDNS支持对该协议提供的IPv4进行解析。

通过我们在上述示例框架start.php中的代码：

```php
if(isset($data->addR->csubnet->ip)){
    $ip=$data->addR->csubnet->ip;
}else{
    $ip=$rip;
}
```

$ip参数将在支持EDNS SubnetIP的情况下优先使用SubnetIP，不存在时则使用连接到的对端IP。

对于写入后端记录时，rip与ip 参数都会始终提供。当不支持EDNS SubnetIP时，rip与ip相同。否则，ip是EDNS SubnetIP，rip是udp对端IP。

# 运行

使用

`php start.php start` 运行

`php start.php start -d` 后台运行，自带守护进程

`php start.php stop` 停止运行

`php start.php status` 查看运行状况

请注意：

DNS服务使用53端口，为特权端口，绝大多数情况下必须使用root权限运行。

### 版本记录

[Current]0.1.1@2024/02/06

添加Edns SubnetIP支持

0.1.0@2024/01/31

### About

作者 Enoch[enoch@laysense.com]

- Repo

[Workerman-DNS](https://git.laysense.com/enoch/Workerman-DNS)

- Github

[https://github.com/ywnsya/Workerman-DNS](https://github.com/ywnsya/Workerman-DNS)

### License

**Apache License 2.0**