UniFi--USG高级应用

概览


本文描述了如何在 UniFi Security Gateway (USG) 使用 config.gateway.json 文件进行高级应用。

注意事项&要求:
本文讲解了 USG 的高级应用,仅对有一定技术基础的高级用户开放。

目录


  1. 简介
  2. 创建 config.gateway.json 文件
  3. 编辑 config.gateway.json 文件
  4. 测试与验证

简介


返回顶部

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 文件能够随时创建、修改和删除。)

警告: 有些时候配置不完全也可以运行,但是由于配置不完全,在运行之后可能会出现很多问题,所以不建议使用不完整的配置(这里指代配置功能不完整)。当控制器 UI 中的设置与 config.gateway.json 中的设置发生冲突时,可能会发生配置同步循环。

创建 config.gateway.json 文件


返回顶部

默认情况下 config.gateway.json 文件是不存在的,想要使用必须先创建一个。

1. 使用文件编辑器例如 TextEdit 或者 Notepad++ 创建一个文件。

2.json 文件的语法结构与单词本身一样重要,一个错误的括号,标点,空格或者其他任何一点结构上的错误都会导致 json 文件失效。在实际应用中我们可以在运行之前在 json 验证器上提前测试一下语法,验证通过后再在设备上运行。常用的网页版 JSON Formatter 就是一种非常方便的 json 验证器,只要联网就可以使用,当然类似验证器还有很多。

3.当确定文件内容格式都正确后,将文件命名为 config.gateway.json 并且将文件存放在控制器<unifi_base>/data/sites/site_ID 路径下。 

用户提示:操作系统不同,文件导入的方式也不同,Windows 系统只需要将文件复制到相应的文件夹下面即可,Linux 系统需要使用 winscp 或者 FTP 进行导入。

<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 中的现有规则具有重复的规则编号,否则将出现配置同步循环。建议将自定义规则放在现有规则集之前,因为策略是从序号小到大进行匹配的。

注意: 这里需要注意的是,定制的 json 文件里面的配置内容一旦与 GUI 配置内容重叠,他们将会相互替换,会造成设备反复刷新配置造成频繁重启,所以一定要确保配置的唯一性。

以下是使用 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。通常可以在日志文件中找到配置新定制配置的问题。相关内容可以参考这篇文章

用户提示: 测试 json 文件有效性的简便方法是:python -m json.tool config.gateway.json

 

删除更改或恢复到以前的状态

要删除某个高级配置,只需删除 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 开始重试。