> For the complete documentation index, see [llms.txt](https://irine-sistiana.gitbook.io/mosdns-wiki/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://irine-sistiana.gitbook.io/mosdns-wiki/mosdns-v5/ru-he-pei-zhi-mosdns.md).

# 如何配置 mosdns

## 基本配置文件格式

mosdns 的默认配置文件格式是 yaml，本 wiki 中所有示例均为 yaml 格式。

mosdns 也支持 JSON, TOML 格式的配置文件。mosdns 会根据配置文件后缀自动识别配置格式。

```yaml
# 日志设置
log:
  level: info   # 日志级别。可选 "debug" "info" "warn" "error"。默认 "info"。
  production: false            # 纯 json 输出。
  file: "/path/to/log/file"    # (实验性) 记录日志到文件。默认输出至 stderr。
                               # 注意: 日志应由守护进程处理而不是直接写入文件。
                               # 此选项仅用于调试。panic 日志不会被记录，其内容仍会
                               # 输出至 stderr 。

  
# (实验性) API 入口设置   
api:
  http: "127.0.0.1:8080" # 在该地址启动 api 接口。

# []string, 从其他配置文件载入 plugins 插件设置。
# include 的插件会比本配置文件中的插件先初始化。
include: []

# 插件设置
plugins:
  - tag: tag1     # 插件的 tag。由用户自由设定但不能重复。可省略。
    type: type1   # 插件类型。详见下文。
    args:         # 插件参数。取决于插件类型。详见下文。
      key1: value1
```

插件设置: 可用的插件类型 `type` 和其对应的 `args` 参数设置，详见

{% content-ref url="/pages/0kLfKwpcNUXjpnXGuCBb" %}
[服务器插件](/mosdns-wiki/mosdns-v5/ru-he-pei-zhi-mosdns/fu-wu-qi-cha-jian.md)
{% endcontent-ref %}

{% content-ref url="/pages/VqNBFSilZJASwrqMIFlN" %}
[可执行插件](/mosdns-wiki/mosdns-v5/ru-he-pei-zhi-mosdns/ke-zhi-xing-cha-jian.md)
{% endcontent-ref %}

{% content-ref url="/pages/jwCNePv5MOjEyjE1v1rj" %}
[数据插件](/mosdns-wiki/mosdns-v5/ru-he-pei-zhi-mosdns/shu-ju-cha-jian.md)
{% endcontent-ref %}

{% hint style="danger" %}
标有 (**实验性**) 的功能和相关设置项不保证配置兼容性 (可能会在任何版本变化或者移除) 。
{% endhint %}

{% hint style="warning" %}
mosdns 会按照配置文件中顺序将插件初始化。有些插件需要调用其他插件，比如 `sequence，其调用的插件必须在之前配置。否则会因为找不到插件而初始化失败。`
{% endhint %}

API 说明详见 

{% content-ref url="/pages/E4yMRm14N0eXmz2U4cAN" %}
[API 说明](/mosdns-wiki/mosdns-v4/api-shuo-ming.md)
{% endcontent-ref %}

### 配置示例

绝大多数 mosdns 的配置都遵循一个思路:

* 用 [sequence](/mosdns-wiki/mosdns-v5/ru-he-pei-zhi-mosdns/sequence-cha-jian.md) 插件定义请求的处理流程。如何生成/屏蔽/获取应答等。
* 配置 [服务器插件](/mosdns-wiki/mosdns-v5/ru-he-pei-zhi-mosdns/fu-wu-qi-cha-jian.md) 接受来自用户的请求。转给 sequence 插件处理。

<details>

<summary>多功能转发器: 缓存加速，屏蔽广告。点击展开</summary>

这个配置文件

* 有缓存，可加速域名解析速度。
* 会屏蔽广告域名。
* 将请求转发至 Google DoH 解析。

用户可以用 `sequence` 插件将多个插件按顺序组合，组成自己想要的运行逻辑。比如下文的配置利用 matches (匹配条件) 屏蔽广告域名。

示例中的广告列表 oisd\_dbl\_basic.txt 来自 [oisd.nl](https://oisd.nl) (官网首页)。下载地址: <https://dbl.oisd.nl/basic/> 。

使用 oisd 域名表仅以展示为目的。mosdns 的域名匹配器非常高效，即使载入并匹配百万域名的 oisd full 列表也不会影响匹配速度。(当然启动后会占更多内存，1w 条域名约占 1m 内存)

```yaml
log:
  level: info

plugins:
  - tag: main
    type: sequence
    args:
      - matches:             # 如果
          - qname &./oisd_dbl_basic.txt # 如果请求的域名在广告列表内。
        exec: reject 3       # 执行 直接返回 NXDOMAIN(3) 屏蔽。
      - exec: cache 1024     # 然后。查找 cache。
      - matches:             # 如果
          - has_resp         # 有应答了(上一步 cache 找到应答)
        exec: accept         # 结束。

      # 上一步没有找到缓存，就会到这一步，转发至 Google 获取应答。
      - exec: forward https://8.8.8.8/dns-query
      # sequence 结束(被 reject，accept，或者运行到末尾)后就会返回调用者。在这个配置文件中
      # 调用者是下面的服务器。服务器就会返回应答至客户端。


  # 启动 udp 和 tcp 服务器。
  - type: udp_server
    args:
      entry: main # 收到的请求会执行上面的逻辑
      listen: 127.0.0.1:5533
  - type: tcp_server
    args:
      entry: main
      listen: 127.0.0.1:5533
```

</details>

如果只需转发，无需其他功能，则可以让服务器插件直接将请求转交给 forward 插件。

<details>

<summary>简单转发器: 将不加密的 DNS53 通过 DoH 转发。点击展开</summary>

```yaml
log:
  level: info

plugins:
  # 转发至 Google 服务器的插件
  - tag: forward_google
    type: forward
    args:
      upstreams:
        - addr: https://8.8.8.8/dns-query

 # 在同一端口启动 udp 和 tcp 服务器。
  - type: udp_server
    args:
      entry: forward_google
      listen: 127.0.0.1:5533
  - type: tcp_server
    args:
      entry: forward_google
      listen: 127.0.0.1:5533
```

</details>