Update docs to cover 1.5.0 (#280)

* Update missing DNS schemes Add DNS over TCP Add DNS over TCP local Add DNS over QUIC local * Tweaking details * Refine DNS doc * Add `tcpKeepAliveInterval` to SockOpt According to [XTLS/Xray-core/pull/754] * Add header and method to HTTP/2 transport According to XTLS/Xray-core/#755 * Make it prettier * Fix punctuations * Add `pinnedPeerCertificateChainSha256` option Added in 1.5.1 and now batch adding it into docs. * Add `X-Real-IP` header note Introduced in XTLS/Xray-core#769 * Add `certChainHash` note * Update commands Add `certChainHash` Provide more details * Add inbound missing contents - Comma separated listening port segments - New sniffers `fakedns+others` and `quic` - New sniffing option `routeOnly` - Some refinements * Add domain socket access indicator * Fix typo * Update descriptions for FakeDNS * Refine DNS over TCP * Make it preetier in DNS doc * Make the statement clear * Attemp to make it prettier in inbound docs * Update fakedns.md * Update inbound.md * Update fakedns.md * Update grpc.md * Update fakedns.md * Update command.md * Detailed description for `metadataOnly` * `pinnedPeerCertificateChainSha256` should be a list
XTLS · Jun 21, 2022 · 6d04c95 · 6d04c95
1 parent c5b5ae1
commit 6d04c95
Show file tree

Hide file tree

Showing 7 changed files with 260 additions and 30 deletions.
diff --git a/docs/config/dns.md b/docs/config/dns.md
@@ -53,7 +53,8 @@ Xray 内置的 DNS 模块，主要有两大用途：
         "port": 5353,
         "domains": ["domain:xray.com"],
         "expectIPs": ["geoip:cn"],
-        "skipFallback": false
+        "skipFallback": false,
+        "clientIP": "1.2.3.4"
       },
       "localhost"
     ],
@@ -87,13 +88,19 @@ Xray 内置的 DNS 模块，主要有两大用途：
 
 一个 DNS 服务器列表，支持的类型有两种：DNS 地址（字符串形式）和 [ServerObject](#serverobject) 。
 
-当它的值是一个 DNS IP 地址时，如 `"8.8.8.8"`，Xray 会使用此地址的 53 端口进行 DNS 查询。
-
 当值为 `"localhost"` 时，表示使用本机预设的 DNS 配置。
 
+当它的值是一个 DNS `"IP:Port"` 地址时，如 `"8.8.8.8:53"`，Xray 会使用此地址的指定 UDP 端口进行 DNS 查询。该查询遵循路由规则。不指定端口时，默认使用 53 端口。
+
+当值是 `"tcp://host:port"` 的形式，如 `"tcp://8.8.8.8:53"`，Xray 会使用 `DNS over TCP` 进行查询。该查询遵循路由规则。不指定端口时，默认使用 53 端口。
+
+当值是 `"tcp+local://host:port"` 的形式，如 `"tcp+local://8.8.8.8:53"`，Xray 会使用 `TCP 本地模式 (TCPL)` 进行查询。即 DNS 请求不会经过路由组件，直接通过 Freedom outbound 对外请求，以降低耗时。不指定端口时，默认使用 53 端口。
+
 当值是 `"https://host:port/dns-query"` 的形式，如 `"https://dns.google/dns-query"`，Xray 会使用 `DNS over HTTPS` (RFC8484, 简称 DOH) 进行查询。有些服务商拥有 IP 别名的证书，可以直接写 IP 形式，比如 `https://1.1.1.1/dns-query`。也可使用非标准端口和路径，如 `"https://a.b.c.d:8443/my-dns-query"`
 
-当值是 `"https+local://host:port/dns-query"` 的形式，如 `"https+local://dns.google/dns-query"`，Xray 会使用 `DOH本地模式` 进行查询，即 DOH 请求不会经过 Routing/Outbound 等组件，直接对外请求，以降低耗时。一般适合在服务端使用。也可使用非标端口和路径。
+当值是 `"https+local://host:port/dns-query"` 的形式，如 `"https+local://dns.google/dns-query"`，Xray 会使用 `DOH 本地模式 (DOHL)` 进行查询，即 DOH 请求不会经过路由组件，直接通过 Freedom outbound 对外请求，以降低耗时。一般适合在服务端使用。也可使用非标端口和路径。
+
+当值是 `"quic+local://host"` 的形式，如 `"quic+local://dns.adguard.com"`，Xray 会使用 `DNS over QUIC 本地模式 (DOQL)` 进行查询，即 DNS 请求不会经过路由组件，直接通过 Freedom outbound 对外请求。该方式需要 DNS 服务器支持 DNS over QUIC。默认使用 784 端口进行查询，可以使用非标端口。
 
 当值是 `fakedns` 时，将使用 FakeDNS 功能进行查询。
 
@@ -139,7 +146,7 @@ Xray 内置的 DNS 模块，主要有两大用途：
 
 > `tag`: string
 
-由内置 DNS 发出的查询流量，除 `localhost` 和 `DOHL_` 模式外，都可以用此标识在路由使用 `inboundTag` 进行匹配。
+由内置 DNS 发出的查询流量，除 `localhost`、`fakedns`、`TCPL`、`DOHL` 和 `DOQL` 模式外，都可以用此标识在路由使用 `inboundTag` 进行匹配。
 
 ### ServerObject
 
@@ -148,27 +155,35 @@ Xray 内置的 DNS 模块，主要有两大用途：
   "address": "1.2.3.4",
   "port": 5353,
   "domains": ["domain:xray.com"],
-  "expectIPs": ["geoip:cn"]
+  "expectIPs": ["geoip:cn"],
+  "skipFallback": false,
+  "clientIP": "1.2.3.4"
 }
 ```
 
 > `address`: address
 
 一个 DNS 服务器列表，支持的类型有两种：DNS 地址（字符串形式）和 ServerObject 。
 
-当它的值是一个 DNS IP 地址时，如 "8.8.8.8"，Xray 会使用此地址的 53 端口进行 DNS 查询。
+当值为 `"localhost"` 时，表示使用本机预设的 DNS 配置。
+
+当它的值是一个 DNS `"IP"` 地址时，如 `"8.8.8.8"`，Xray 会使用此地址的指定 UDP 端口进行 DNS 查询。该查询遵循路由规则。默认使用 53 端口。
 
-当值为 "localhost" 时，表示使用本机预设的 DNS 配置。
+当值是 `"tcp://host"` 的形式，如 `"tcp://8.8.8.8"`，Xray 会使用 `DNS over TCP` 进行查询。该查询遵循路由规则。默认使用 53 端口。
+
+当值是 `"tcp+local://host"` 的形式，如 `"tcp+local://8.8.8.8"`，Xray 会使用 `TCP 本地模式 (TCPL)` 进行查询。即 DNS 请求不会经过路由组件，直接通过 Freedom outbound 对外请求，以降低耗时。不指定端口时，默认使用 53 端口。
 
 当值是 `"https://host:port/dns-query"` 的形式，如 `"https://dns.google/dns-query"`，Xray 会使用 `DNS over HTTPS` (RFC8484, 简称 DOH) 进行查询。有些服务商拥有 IP 别名的证书，可以直接写 IP 形式，比如 `https://1.1.1.1/dns-query`。也可使用非标准端口和路径，如 `"https://a.b.c.d:8443/my-dns-query"`
 
-当值是 `"https+local://host:port/dns-query"` 的形式，如 `"https+local://dns.google/dns-query"`，Xray 会使用 DOH 本地模式 进行查询，即 DOH 请求不会经过 Routing/Outbound 等组件，直接对外请求，以降低耗时。一般适合在服务端使用。也可使用非标端口和路径。
+当值是 `"https+local://host:port/dns-query"` 的形式，如 `"https+local://dns.google/dns-query"`，Xray 会使用 `DOH 本地模式 (DOHL)` 进行查询，即 DOH 请求不会经过路由组件，直接通过 Freedom outbound 对外请求，以降低耗时。一般适合在服务端使用。也可使用非标端口和路径。
+
+当值是 `"quic+local://host:port"` 的形式，如 `"quic+local://dns.adguard.com"`，Xray 会使用 `DOQ 本地模式 (DOQL)` 进行查询，即 DNS 请求不会经过路由组件，直接通过 Freedom outbound 对外请求。该方式需要 DNS 服务器支持 DNS over QUIC。默认使用 784 端口进行查询，可以使用非标端口。
 
 当值是 `fakedns` 时，将使用 FakeDNS 功能进行查询。
 
 > `port`: number
 
-DNS 服务器端口，如 `53`。此项缺省时默认为 `53`。当使用 DOH 模式该项无效，非标端口应在 URL 中指定。
+DNS 服务器端口，如 `53`。此项缺省时默认为 `53`。当使用 DOH、DOHL、DOQL 模式时该项无效，非标端口应在 URL 中指定。
 
 > `domains`: \[string\]
 

diff --git a/docs/config/fakedns.md b/docs/config/fakedns.md
@@ -17,6 +17,21 @@ FakeDNS 有可能会污染本地 DNS，导致 Xray 关闭后“无法访问网
 }
 ```
 
+`FakeDnsObject` 亦可配置为一个包含多个 FakeIP Pool 的数组。当收到 DNS 查询请求时，FakeDNS 会返回一组同时由多个 FakeIP Pool 得到的一组 FakeIP。
+
+```json
+[
+  {
+    "ipPool": "198.18.0.0/15",
+    "poolSize": 65535
+  },
+  {
+    "ipPool": "fc00::/18",
+    "poolSize": 65535
+  }
+]
+```
+
 > `ipPool`: CIDR
 
 FakeDNS 将使用此选项指定的 IP 块分配地址。
@@ -25,16 +40,156 @@ FakeDNS 将使用此选项指定的 IP 块分配地址。
 
 指定 FakeDNS 储存的 域名-IP 映射的最大数目。当映射数超过此值后，会按照 LRU 规则淘汰映射。默认为 65535。
 
+::: warning
+`poolSize` 必须小于或等于 `ipPool` 对应的地址总数。
+:::
+
+::: tip
+若配置文件中 `dns` 项设置了 `fakedns` 但配置文件没有设置 `FakeDnsObject`，Xray 会根据 DNS 组件的 `queryStrategy` 来初始化 `FakeDnsObject`。
+
+`queryStrategy` 为 `UseIP` 时，初始化的 FakeIP Pool 相当于
+
+```json
+[
+  {
+    "ipPool": "198.18.0.0/15",
+    "poolSize": 32768
+  },
+  {
+    "ipPool": "fc00::/18",
+    "poolSize": 32768
+  }
+]
+```
+
+`queryStrategy` 为 `UseIPv4` 时，初始化的 FakeIP Pool 相当于
+
+```json
+{
+  "ipPool": "198.18.0.0/15",
+  "poolSize": 65535
+}
+```
+
+`queryStrategy` 为 `UseIPv6` 时，初始化的 FakeIP Pool 相当于
+
+```json
+{
+  "ipPool": "fc00::/18",
+  "poolSize": 65535
+}
+```
+
+:::
+
 ### 如何使用？
 
 FakeDNS 本质上是一个 [DNS 服务器](./dns.md#serverobject)，能够与任意 DNS 规则配合使用。
 
-::: tip
 只有将 DNS 查询路由到 FakeDNS，才能使其发挥作用。
-:::
 
-另外，你需要在入站中开启 `Sniffing` ，并使用 `fakedns` 目标地址重置。
+```json
+{
+  "dns": {
+    "servers": [
+      "fakedns", // fakedns 排在首位
+      "8.8.8.8"
+    ]
+  },
+  "outbounds": [
+    {
+      "protocol": "dns",
+      "tag": "dns-out"
+    }
+  ],
+  "routing": {
+    "rules": [
+      {
+        "type": "field",
+        "inboundTag": ["dns-in"], // 劫持来自 DNS 查询入口的 DNS 流量，或劫持来自透明代理入站的 DNS 流量。
+        "port": 53,
+        "outboundTag": "dns-out"
+      }
+    ]
+  }
+}
+```
+
+当外部 DNS 请求进入 FakeDNS 组件时，它会返回位于自己 `ipPool` 内的 IP 地址作为域名的虚构解析结果，并记录该域名与虚构解析结果之间的映射关系。
+
+另外，你需要在**客户端**接收需代理流量的入站中开启 `Sniffing`，并使用 `fakedns` 目标地址重置。
+
+```json
+"sniffing": {
+  "enabled": true,
+  "destOverride": ["fakedns"], // 使用 "fakedns"，或与其它 sniffer 搭配使用，或直接使用 "fakedns+others"
+  "metadataOnly": false        // 此项为 true 时 destOverride 仅可使用 fakedns
+},
+```
 
 ::: warning
 如果 FakeIP 没有被正确的还原为域名，将无法连接到服务器。
 :::
+
+### 与其它类型 DNS 搭配使用
+
+#### 与 DNS 分流共存
+
+使用 DNS 分流时，为了使 `fakedns` 拥有高优先级，需要对其增加与其他类型 DNS 相同的 `domains`。
+
+```json
+{
+  "servers": [
+    {
+      "address": "fakedns",
+      "domains": [
+        // 与下方分流所用的内容一致
+        "geosite:cn",
+        "domain:example.com"
+      ]
+    },
+    {
+      "address": "1.2.3.4",
+      "domains": ["geosite:cn"],
+      "expectIPs": ["geoip:cn"]
+    },
+    {
+      "address": "1.1.1.1",
+      "domains": ["domain:example.com"]
+    },
+    "8.8.8.8"
+  ]
+}
+```
+
+#### FakeDNS 黑名单
+
+如不希望某些域名使用 FakeDNS，则可在其它类型的 DNS 配置中添加 `domains` 配置，使指定域名在匹配时其它 DNS 服务器拥有比 FakeDNS 更高的优先级，进而实现 FakeDNS 的黑名单机制。
+
+```json
+{
+  "servers": [
+    "fakedns",
+    {
+      "address": "1.2.3.4",
+      "domains": ["domain:do-not-use-fakedns.com"]
+    }
+  ]
+}
+```
+
+#### FakeDNS 白名单
+
+如希望仅某些域名使用 FakeDNS，则可在 `fakedns` 增加 `domains` 配置，使指定域名在匹配时 `fakedns` 拥有比其它 DNS 服务器更高的优先级，进而实现 FakeDNS 的白名单机制。
+
+```json
+{
+  "servers": [
+    "1.2.3.4",
+    {
+      "address": "fakedns",
+      "domains": ["domain:only-this-use-fakedns.com"]
+    }
+  ]
+}
+```
diff --git a/docs/config/inbound.md b/docs/config/inbound.md
@@ -40,13 +40,15 @@
 
 填写 Unix domain socket 时，`port` 和 `allocate` 将被忽略，协议目前可选 VLESS、VMess、Trojan，传输方式可选 TCP、WebSocket、HTTP/2、gRPC。
 
+填写 Unix domain socket 时，填写为形如 `"/dev/shm/domain.socket,0666"` 的形式，即 socket 后加逗号及访问权限指示符，即可指定 socket 的访问权限，可用于解决默认情况下出现的 socket 访问权限问题。
+
 > `port`: number | "env:variable" | string
 
 端口。接受的格式如下:
 
 - 整型数值：实际的端口号。
 - 环境变量：以 `"env:"` 开头，后面是一个环境变量的名称，如 `"env:PORT"`。Xray 会以字符串形式解析这个环境变量。
-- 字符串：可以是一个数值类型的字符串，如 `"1234"`；或者一个数值范围，如 `"5-10"` 表示端口 5 到端口 10，这 6 个端口。
+- 字符串：可以是一个数值类型的字符串，如 `"1234"`；或者一个数值范围，如 `"5-10"` 表示端口 5 到端口 10，这 6 个端口。可以使用逗号进行分段，如 `11,13,15-17` 表示端口 11、端口 13、端口 15 到端口 17 这 5 个端口。
 
 当只有一个端口时，Xray 会在此端口监听入站连接。当指定了一个端口范围时，取决于 `allocate` 设置。
 
@@ -94,21 +96,26 @@
   "enabled": true,
   "destOverride": ["http", "tls", "fakedns"],
   "metadataOnly": false,
-  "domainsExcluded": []
+  "domainsExcluded": [],
+  "routeOnly": false
 }
 ```
 
 > `enabled`: true | false
 
 是否开启流量探测。
 
-> `destOverride`: \["http" | "tls" | "fakedns" \]
+> `destOverride`: \["http" | "tls" | "quic" | "fakedns" | "fakedns+others" \]
 
 当流量为指定类型时，按其中包括的目标地址重置当前连接的目标。
 
+其中 `["fakedns+others"]` 相当于 `["http", "tls", "quic", "fakedns"]`，当 IP 地址处于 FakeIP 区间内但没有命中域名记录时会使用 `http`、`tls` 和 `quic` 进行匹配。此项仅在 `metadataOnly` 为 `false` 时有效。
+
 > `metadataOnly`: true | false
 
-当启用时，将仅使用连接的元数据嗅探目标地址。此时，`http` 与 `tls` 将不能使用。
+当启用时，将仅使用连接的元数据嗅探目标地址。此时，除 `fakedns` 以外的 sniffer 将不能激活（包括 `fakedns+others`）。
+
+如果关闭仅使用元数据推断目标地址，此时客户端必须先发送数据，代理服务器才会实际建立连接。此行为与需要服务器首先发起第一个消息的协议不兼容，如 SMTP 协议。
 
 > `domainsExcluded`: [string] <Badge text="WIP" type="warning"/>
 
@@ -118,6 +125,16 @@
 目前，`domainsExcluded` 不支持类似路由中的域名匹配方式。此选项未来可能会改变，不保证跨版本兼容。
 :::
 
+> `routeOnly`: true | false
+
+将嗅探得到的域名仅用于路由，代理目标地址仍为 IP。默认值为 `false`。
+
+此项需要开启 `destOverride` 使用。
+
+::: tip
+在能保证 **被代理连接能得到正确的 DNS 解析** 时，使用 `routeOnly` 且开启 `destOverride` 的同时，将路由匹配策略 `domainStrategy` 设置为 `AsIs` 即可实现全程无 DNS 解析进行域名及 IP 分流。此时遇到 IP 规则匹配时使用的 IP 为域名原始 IP。
+:::
+
 ### AllocateObject
 
 ```json

diff --git a/docs/config/transport.md b/docs/config/transport.md
@@ -81,7 +81,8 @@
     "tproxy": "off",
     "domainStrategy": "AsIs",
     "dialerProxy": "",
-    "acceptProxyProtocol": false
+    "acceptProxyProtocol": false,
+    "tcpKeepAliveInterval": 0
   }
 }
 ```
@@ -158,7 +159,8 @@ TLS / XTLS 是目前最安全的传输加密方案, 且外部看来流量类型
   "certificates": [],
   "disableSystemRoot": false,
   "enableSessionResumption": false,
-  "fingerprint": ""
+  "fingerprint": "",
+  "pinnedPeerCertificateChainSha256": [""]
 }
 ```
 
@@ -227,6 +229,20 @@ CipherSuites 用于配置受支持的密码套件列表, 每个套件名称之
 - `"chrome" | "firefox" | "safari"`: 模拟 Chrome / Firefox / Safari 的 TLS 指纹
 - `"randomized"`: 使用随机指纹
 
+> `pinnedPeerCertificateChainSha256`: \[string\]
+
+用于指定远程服务器的证书链 SHA256 散列值，使用标准编码格式。仅有当服务器端证书链散列值符合设置项中之一时才能成功建立 TLS 连接。
+
+在连接因为此配置失败时，会展示远程服务器证书散列值。
+
+::: danger
+不建议使用这种方式获得证书链散列值，因为在这种情况下将没有机会验证此时服务器提供的证书是否为真实证书，进而不保证获得的证书散列值为期望的散列值。
+:::
+
+::: tip
+如果需要获得证书的散列值，应在命令行中运行 `xray tls certChainHash --cert <cert.pem>` 来获取，`<cert.pem>` 应替换为实际证书文件路径。
+:::
+
 > `certificates`: \[ [CertificateObject](#certificateobject) \]
 
 证书列表，其中每一项表示一个证书（建议 fullchain）。
@@ -365,7 +381,8 @@ OCSP 装订更新，与证书热重载的时间间隔。 单位：秒。默认
   "tproxy": "off",
   "domainStrategy": "AsIs",
   "dialerProxy": "",
-  "acceptProxyProtocol": false
+  "acceptProxyProtocol": false,
+  "tcpKeepAliveInterval": 0
 }
 ```
 
@@ -474,3 +491,9 @@ OCSP 装订更新，与证书热重载的时间间隔。 单位：秒。默认
 常见的反代软件（如 HAProxy、Nginx）都可以配置发送它，VLESS fallbacks xver 也可以发送它。
 
 填写 `true` 时，最底层 TCP 连接建立后，请求方必须先发送 PROXY protocol v1 或 v2，否则连接会被关闭。
+
+> `tcpKeepAliveInterval`: number
+
+TCP 保持活跃的数据包发送间隔，单位为秒。该设置仅适用于 Linux 下。
+
+不配置此项或配置为 0 表示使用 Go 默认值。
diff --git a/docs/config/transports/grpc.md b/docs/config/transports/grpc.md
@@ -18,6 +18,7 @@ gRPC（HTTP/2）内置多路复用，不建议使用 gRPC 与 HTTP/2 时启用 m
 - 请确定反向代理服务器开启了 HTTP/2
 - 请使用 HTTP/2 或 h2c (Caddy)，grpc_pass (Nginx) 连接到 Xray。
 - 普通模式的 Path 为 `/${serviceName}/Tun`, Multi 模式为 `/${serviceName}/TunMulti`
+- 如果需要接收客户端 IP，可以通过由 Caddy / Nginx 发送 `X-Real-IP` header 来传递客户端 IP。
   :::
 
 ::: tip