ACL
ACL 是 Hysteria 服务端中一个非常强大的功能,可以用来自定义处理客户端请求的方式,往往配合出站规则(outbounds)使用。例如,可以使用 ACL 来屏蔽某些地址,针对不同网站使用不同出口,或者让不同用户走不同出口。
从 2.14.0 版本开始,ACL 规则以表达式的形式编写,可以根据目标地址、协议、客户端地址以及客户端的验证 ID 进行匹配。之前版本使用的旧版语法仍然可以使用。
规则
规则写在服务端配置的 acl.rules 下:
acl:
rules:
- outbound: some_proxy # (1)!
match: auth.id == "alice" # (2)!
- outbound: reject
match: geoip("cn") || suffix("example.com")
- outbound: default
match: proto == "udp" && dst.port == 53 && cidr("8.8.8.8")
hijack: 1.1.1.1 # (3)!
- outbound: direct # (4)!
- 规则匹配时使用的出站名称。可以是你定义的出站,也可以是内置出站。不区分大小写。
- 可选。一个表达式,决定该规则是否匹配请求。
- 可选。将连接改为发往此地址。必须是 IPv4/IPv6 地址,不能是域名。端口保持不变。
- 没有
match的规则匹配所有请求。通常放在最后,作为其他所有连接的默认规则。
规则按从上到下的顺序进行匹配,使用第一个匹配请求的规则。如果没有规则匹配,将使用默认出站(出站列表中的第一个)。
也可以把规则放在单独的文件中,并用 acl.rulesFile 指定该文件。文件内容是同样的列表,但不包含 acl: 和 rules: 这两层:
表达式
match 使用 expr 语言编写。其中最常用的部分有:
- 比较:
==、!=、<、<=、>、>= - 逻辑:
&&(或and)、||(或or)、!(或not),以及用于分组的括号 - 列表和范围:
auth.id in ["alice", "bob"]、dst.port in 8000..8999 - 字符串:
startsWith、endsWith、contains,以及用于正则表达式的matches,例如dst.host matches "^cdn[0-9]+"
规则的表达式的结果必须是 true 或 false。不支持 now() 和 date() 等时间函数。
变量
| 变量 | 说明 |
|---|---|
proto |
"tcp" 或 "udp" |
dst.host |
请求的目标主机:客户端发送的域名(小写,不含末尾的点)或 IP 地址。如果启用了协议嗅探,且嗅探到了域名,则为嗅探到的域名。 |
dst.port |
请求的目标端口 |
dst.ipv4、dst.ipv6 |
目标主机解析得到的 IPv4 和 IPv6 地址(参见域名和 IP 匹配)。没有时为空字符串。 |
auth.id |
客户端的验证 ID。使用 userpass 验证时为用户名;使用 http 验证时为你的验证服务器返回的 id;使用 command 验证时为命令的输出;使用 password 验证时始终为 user。 |
client.ip、client.port |
客户端连接所用的 IP 地址和端口 |
匹配函数
| 函数 | 匹配 |
|---|---|
domain("example.com") |
完全匹配一个域名(不包括子域名)。支持 * 通配符,例如 domain("*.example.com") 或 domain("*.google.*")。 |
suffix("example.com") |
一个域名及其所有子域名:example.com、www.example.com 等 |
cidr("10.0.0.0/8") |
IPv4/IPv6 CIDR 或单个地址,例如 cidr("1.1.1.1") 或 cidr("2001:db8::/32") |
geoip("cn") |
GeoIP 国家代码 |
geosite("netflix") |
GeoSite 分类。支持标签,例如 geosite("google@cn")。 |
legacy("geoip:cn") |
任何旧版语法中的地址,例如 legacy("suffix:example.com")。用于转换后的旧版规则。 |
只传一个参数时,匹配函数检查请求的目标:其主机名、解析得到的 IPv4 地址或解析得到的 IPv6 地址。因此 geoip("cn") 也会匹配解析到中国 IP 地址的域名。
传两个参数时,函数改为检查第二个参数。可以用来匹配客户端的地址,例如 geoip("cn", client.ip) 或 cidr("192.168.0.0/16", client.ip)。
第一个参数必须是直接写在规则中的字符串。Hysteria 会在启动时准备好所有匹配器,所以不能写 geoip(auth.id)。
要查看可用的 GeoSite 分类,可以参考这里:
匹配行为
域名和 IP 匹配
当处理基于域名的请求时,Hysteria 首先会解析该域名,然后尝试匹配域名和 IP 规则。换句话说,基于 IP 地址的规则将适用于所有最终指向该 IP 的连接,无论客户端请求是用的域名还是 IP。
匹配时只使用域名的第一个 IPv4 地址和第一个 IPv6 地址。
错误
服务端启动时会检查规则。未知的变量、结果不是 true 或 false 的表达式、未知的出站、未知的 GeoIP 国家代码等错误会使服务端停止,并显示出错的规则:
invalid config: acl.rules: error at rules[0]: type acl.Auth has no field idd (1:6)
| auth.idd == "alice"
| .....^
如果表达式在求值时出错,例如 ID 不是数字时的 int(auth.id) > 100,该规则视为不匹配。
内置出站
除非在出站列表中明确地进行了覆盖(同名),否则 Hysteria 内置以下出站:
direct- 使用默认配置(auto,无绑定)的本地出站reject- 拒绝连接default- 使用出站列表中的第一个出站;如果列表为空,等同于direct
示例
假设有以下出站列表:
outbounds:
- name: v4_only
type: direct
direct:
mode: 4
- name: v6_only
type: direct
direct:
mode: 6
- name: some_proxy
type: socks5
socks5:
addr: ohno.moe:1080
acl:
rules:
# 用户 "alice" 的所有流量都走 some_proxy
- outbound: some_proxy
match: auth.id == "alice"
# 用户 "bob" 和 "carol" 不能使用 UDP
- outbound: reject
match: auth.id in ["bob", "carol"] && proto == "udp"
# 为 Google 使用 v6_only 出站
- outbound: v6_only
match: suffix("google.com")
# 为 Twitter 使用 v4_only 出站,用户 "dave" 除外
- outbound: v4_only
match: suffix("twitter.com") && auth.id != "dave"
# 也支持非英语 IDN 域名
- outbound: v6_only
match: domain("战狼*.中国")
# 屏蔽 QUIC 和 SMTP
- outbound: reject
match: (proto == "udp" && dst.port == 443) || (proto == "tcp" && dst.port == 25)
# 屏蔽中国和朝鲜
- outbound: reject
match: geoip("cn") || geoip("kp")
# 屏蔽 Facebook 和 Google Ads
- outbound: reject
match: geosite("facebook") || geosite("google@ads")
# 只有办公网络内的客户端可以访问 10.0.0.0/8
- outbound: reject
match: cidr("10.0.0.0/8") && !cidr("192.0.2.0/24", client.ip)
# 将发往 8.8.8.8 的 DNS 查询劫持到 1.1.1.1,并使用默认(第一个)出站
- outbound: default
match: proto == "udp" && dst.port == 53 && cidr("8.8.8.8")
hijack: 1.1.1.1
# 直连所有其他地址
- outbound: direct
注意: ACL 也可以不配合出站规则单独使用。无论有没有出站列表,内置出站都会存在。实际上,ACL 最常见的用法之一就是单纯屏蔽一些地址:
acl:
rules:
- outbound: reject
match: geoip("cn") || geosite("facebook")
- outbound: reject
match: cidr("10.0.0.0/8") || cidr("172.16.0.0/12") || cidr("192.168.0.0/16") || cidr("fc00::/7")
测试规则
hysteria acl test 可以显示服务端会对某个请求使用哪条规则和哪个出站,不会实际建立任何连接。它读取用 -c 指定的服务端配置:
Request: tcp example.com:443, auth.id "alice"
Resolved: ipv4 172.66.147.243, ipv6 2606:4700:10::6814:179a
Rule: rules[0]: some_proxy, match: auth.id == "alice"
Outbound: some_proxy
Request: udp 8.8.8.8:53
Resolved: ipv4 8.8.8.8
Rule: rules[9]: default, match: proto == "udp" && dst.port == 53 && cidr("8.8.8.8")
Outbound: v4_only
Hijacked: 1.1.1.1:53
| 选项 | 默认值 | 说明 |
|---|---|---|
--proto |
tcp |
tcp 或 udp |
--auth |
空 | 客户端的验证 ID(auth.id) |
--client |
无 | 客户端的地址,IP 或 IP:端口(client.ip、client.port) |
--ipv4、--ipv6 |
解析 | 使用这些地址,而不是解析目标主机 |
--no-resolve |
关闭 | 不解析目标主机,即没有 IP 地址 |
默认情况下,会和服务端一样使用服务端配置中的 DNS 解析设置来解析目标主机。不会模拟协议嗅探:目标主机按原样使用。
旧版语法
在 2.14.0 版本之前,ACL 规则使用另一种语法,通过 acl.file 或 acl.inline 设置。这种语法仍然受支持:Hysteria 会在启动时把这些规则转换为表达式,行为与之前相同,只有一处例外,见下文。
一个有效的旧版规则必须符合以下格式之一:
outbound(address)outbound(address, proto/port)outbound(address, proto/port, hijack_address)# 这是一条注释
地址类型
address 字段可以是以下几种之一:
- 单一 IPv4/IPv6 地址,例如
1.1.1.1或2606:4700:4700::1111 - IPv4/IPv6 CIDR,例如
73.0.0.0/8或2001:db8::/32 - 域名,例如
example.com(不包括子域名) - 通配域名,例如
*.example.com或*.google.* - 域名后缀,例如
suffix:example.com(匹配example.com及其所有子域名) - GeoIP 国家代码,例如
geoip:cn或geoip:us - GeoSite 分类,例如
geosite:netflix或geosite:google(支持标签,例如geosite:google@cn) all- 匹配所有地址
Proto/port
tcp或tcp/*- 匹配所有 TCP 端口udp或udp/*- 匹配所有 UDP 端口tcp/80- 匹配 TCP 端口 80udp/53- 匹配 UDP 端口 53udp/20000-30000- 匹配 UDP 端口 20000 到 30000*/443- 匹配 TCP 和 UDP 端口 443*、*/*或省略 - 匹配所有协议和所有端口
注意: 在 2.14.0 版本之前,从 0 开始的端口范围(例如
udp/0-100)或端口0(例如tcp/0)会匹配所有端口。现在只匹配指定的端口。
劫持地址 (Hijack address)
当指定了劫持地址时,匹配此规则的连接将被劫持到指定的地址。劫持地址必须是 IPv4/IPv6 地址,不能是域名。
在 rules 中混用旧版规则
rules 列表中也可以包含旧版规则,这样无需转换现有的规则列表,就能在其中添加新规则(例如按用户区分的规则)。legacy 条目包含一行或多行旧版规则,legacyFile 条目引入一个旧版规则文件。它们的规则在列表中的对应位置进行匹配:
acl:
rules:
- outbound: some_proxy
match: auth.id == "alice"
- legacy: reject(geoip:cn)
- legacy: |
reject(geosite:facebook)
reject(all, tcp/25)
- legacyFile: /etc/hysteria/acl.txt
- outbound: direct
旧版条目中的错误会同时指出条目和行号,例如 error at rules[3] (/etc/hysteria/acl.txt) line 2: outbound v6_only not found。
转换旧版规则
hysteria acl translate 会把旧版规则输出为等效的 rules 列表,这也是 Hysteria 内部实际运行的规则:
acl:
rules:
- outbound: v6_only
match: legacy("suffix:google.com")
- outbound: reject
match: proto == "udp" && dst.port == 443
- outbound: reject
match: legacy("geoip:cn")
- outbound: default
match: legacy("8.8.4.4") && proto == "udp" && dst.port == 53
hijack: 1.1.1.1
- outbound: direct
如果没有指定文件,则从标准输入读取。它只检查语法:出站名称和 GeoIP/GeoSite 名称会在服务端载入规则时检查。