概览

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

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

简介

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 文件是不存在的，想要使用必须先创建一个。

使用文件编辑器例如 TextEdit 或者 Notepad++ 创建一个文件。
json 文件的语法结构与单词本身一样重要，一个错误的括号，标点，空格或者其他任何一点结构上的错误都会导致 json 文件失效。在实际应用中我们可以在运行之前在 json 验证器上提前测试一下语法，验证通过后再在设备上运行。常用的网页版 JSON Formatter 就是一种非常方便的 json 验证器，只要联网就可以使用，当然类似验证器还有很多。
当确定文件内容格式都正确后，将文件命名为 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 开始重试。

UniFi - USG 高级应用

概览

目录

简介

创建 config.gateway.json 文件

编辑 config.gateway.json 文件

测试 & 验证

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