概览
本文描述了如何在 UniFi Security Gateway (USG) 使用 config.gateway.json 文件进行高级应用。
目录
简介
config.gateway.json 是一个存在于 UniFi Controller 文件系统中的文件,它允许对 USG 进行自定义更改,实现 web GUI 中无法进行的配置。 可能实现的功能包括:使用主机名配置站点到站点的 vpn,指向 WAN2 的策略路由等等。这些特性在编写本文时(2018 年 9 月 27 日)控制器 GUI 中并不存在;在这些功能尚未在 GUI 中实现之前,将通过 config.gateway.json 文件补充这些功能。
通过 config.gateway.json 文件进行编辑时,最好只添加 GUI 界面无法配置的功能,因为 json 文件对格式要求非常高,只要有一丁点格式上的错误,整个文件就无法运行。而且每当 json 文件写好同步后,USG 都会进行重启。( json 文件能够随时创建、修改和删除。)
创建 config.gateway.json 文件
默认情况下 config.gateway.json 文件是不存在的,想要使用必须先创建一个。
- 使用文件编辑器例如 TextEdit 或者 Notepad++ 创建一个文件。
- json 文件的语法结构与单词本身一样重要,一个错误的括号,标点,空格或者其他任何一点结构上的错误都会导致 json 文件失效。在实际应用中我们可以在运行之前在 json 验证器上提前测试一下语法,验证通过后再在设备上运行。常用的网页版 JSON Formatter 就是一种非常方便的 json 验证器,只要联网就可以使用,当然类似验证器还有很多。
- 当确定文件内容格式都正确后,将文件命名为 config.gateway.json 并且将文件存放在控制器 <unifi_base>/data/sites/site_ID 路径下。
<unifi_base> 的位置根据不同的操作系统而变化。有关更多信息,请参阅这篇文章。在控制器页面上,可以在浏览器的 URL 中看到 site_ID。原始站点被命名为“default”,创建的每个站点都将被分配一个随机字符串。例如,这是在一个站点的仪表盘页面内的 URL 栏中,可以看到的:
https://127.0.0.1:8443/manage/s/ceb1m27d/dashboard
通过上面的例子,字符串 ceb1m27d 就是将要被使用在 <unifi_base>/data/sites/ 后面的文件名。所以 *config.gateway.json 文件最终应该存放在 <unifi_base>/data/sites/ceb1m27d/。
- Cloud Key 安装 .json 文件的路径是: /srv/unifi/data/sites/[site name/default]/
- Ubuntu 安装 .json 文件的路径是: /usr/lib/unifi/data/sites/[site name/default]/
编辑 config.gateway.json 文件
在编辑防火墙或 NAT 规则之前,请注意 UniFi 控制器在设置>路由和防火墙>防火墙下使用的规则编号。默认防火墙规则从 3001 或 6001 开始,NAT 规则也从 6001 开始(不与防火墙规则重叠)。在 config.gateway.json 中创建的自定义规则不能与 USG 中的现有规则具有重复的规则编号,否则将出现配置同步循环。建议将自定义规则放在现有规则集之前,因为策略是从序号小到大进行匹配的。
以下是使用 EdgeOS 格式配置的 DNS 和创建 DNAT 规则的示例:
1.通过 SSH 连接 USG,并配置以下命令:
configure
set service nat rule 1 type destination
set service nat rule 1 inbound-interface eth0
set service nat rule 1 protocol tcp_udp
set service nat rule 1 destination port 53
set service nat rule 1 inside-address address 10.0.0.1
set service nat rule 1 inside-address port 53
commit;save;exit
2.接下来显示配置。以下命令以 JSON 格式显示整个配置:
mca-ctrl -t dump-cfg
如果愿意,也可以导出配置。以下示例将输出导出到 config.txt
:
mca-ctrl -t dump-cfg > config.txt
3.在配置输出中找到包含自定义更改的相应部分,对于上面的示例,如下所示:
"nat": {
"rule":{
"1":{
"destination":{
"port":"53"
},
"inbound-interface":"eth0",
"inside-address":{
"address": "10.0.0.1",
"port":"53"
},
"protocol":"tcp_udp",
"type":"destination"
}
}
}
4.以上是自定义规则,但是还缺少很多作为段落结尾的 (}) 。 如果从开始查看配置输出,则需要某种格式才能正确读取文件。一个部分中的每个节点必须用逗号(,)分隔,而且每个层次必须以 ({) 开始到 (}) 结束。 按照规定格式仔细修改 config.gateway.json 文件,你需要将整个目录补齐,如下所示:
{
"service":{
"nat":{
"rule":{
"1":{
"destination":{
"port":"53"
},
"inbound-interface":"eth0",
"inside-address" :{
"address":"10.0.0.1",
"port":"53"
},
"protocol":"tcp_udp",
"type":"destination"
}
}
}
}
}
5.如果需要配置多个部分,例如防火墙、service、VPN 等,在开启下一个层次之前,你需要使用 (},) 来进行配置, 下面有具体的实例。
DNAT 规则范围是 1-4999,Source/Masquerade 规则编号是 5000-9999。如果你想在 multiWAN(负载均衡)设置中在 config.gateway.json 中为 WAN2 添加端口转发(DNAT),这就是 config.gateway.json 只有这个特定的 NAT 规则才会是这样的:
{
"service": {
"nat": {
"rule": {
"4500": {
"description": "port_forward_WAN2",
"destination": {
"address": "100.64.100.100",
"port": "22"
},
"inbound-interface": "eth3",
"inside-address": {
"address": "192.168.1.100"
},
"protocol": "tcp",
"type": "destination"
}
}
}
}
}
如果我们要将具有主机名的 VPN 添加到文件中,则 config.gateway.json 将如下所示。在开始使用该"vpn"部分之前,请注意开始和结束括号以及带逗号的括号:
{
"service": {
"nat": {
"rule": {
"4500": {
"description": "port_forward_WAN2",
"destination": {
"address": "100.64.100.100",
"port": "22"
},
"inbound-interface": "eth3",
"inside-address": {
"address": "192.168.1.100"
},
"protocol": "tcp",
"type": "destination"
}
}
}
},
"vpn": {
"ipsec": {
"site-to-site": {
"peer": {
"yyyy.ignorelist.com": {
"authentication": {
"id": "xxxx.ignorelist.com"
},
"local-address": "xxxx.ignorelist.com"
}
}
}
}
}
}
测试 & 验证
一旦创建完成 config.gateway.json, 建议先验证代码,所需的软件网上有很多。
将 config.gateway.json 添加到您选择的 Controller 站点后,您可以通过在 UniFi 控制器设备> USG>配置>管理设备>强制同步 中向 USG 运行“强制同步”来对其进行测试,一般需要 30 秒到 3 分钟,如果它的配置时间超过 3 分钟,则 config.gateway.json 中可能存在格式化错误,也可能遇到前面提到的配置循环。您可以检查 server.log
或者搜索 commit error
。通常可以在日志文件中找到配置新定制配置的问题。相关内容可以参考这篇文章。
删除更改或恢复到以前的状态
要删除某个高级配置,只需删除 config.gateway.json 文件中与该配置相关的部分。要完全删除 config.gateway.json 文件中创建的所有高级配置,请删除该文件或重命名该文件。
编辑已经运行的 config.gateway.json 件时的最佳做法是创建备份。如果需要对 config.gateway.json 文件添加其他更改,请将当前文件重命名为 config.gateway.json.old,实质上是创建备份,并将所有现有和新更改复制到名为 config.gateway.json 的新文件中。这样,如果出现任何导致“提交”错误或配置循环的错误,您可以删除 config.gateway.json,然后从 config.gateway.json.old 开始重试。