Unifi Security Gateway JSON config
The Unifi series from Ubuquiti has great features for centralized management of larger networks. There are however many things not supported in the Cloud Key UI that still can be configured. During the last deployment, we had two additional needs we couldn’t accomplish from the Cloud Key itself.
- Multiple WAN addresses – we needed to configure more than one fixed IP on the WAN interface.
- IP-Sec SHA256 hash – one of our site-to-site VPN connections required SHA256 as the hash algorithm.
There are several guides on how to accomplish this but they are scattered all over the place. This is a complete writeup of how to accomplish this and provision the changes to the devices.
Get the current config
Both of the changes needed can be accomplished via SSH and local commands in the Unifi Security Gateway (USG). The problem with this approach is that as soon as the device is reprovisioned from the Cloud Key it will lose those changes. The only way to do this and get consistent results is to use the config.gateway.json method. By creating a JSON file containing only the changes to the config tree you would like the Cloud Key can provision those changes even if the UI doesn’t support the settings. All the UI settings are merged with the config.gateway.json file and provisioned to the device.
The best way to create this file is to dump the complete configuration from the USG and start from there. In the Unifi Controller, in my case a Cloud Key Gen 2+, enable advanced featerus under site settings. Then enable SSH authentication. This will enable you to SSH into the USG. When you’re connected to the USG use the following command to dump the current configuration:
mca-ctrl -t dump-cfg > config.json
Then use a SCP tool like WinSCP to download the file from the USG. What you will see in this is the complete configuration tree represented in JSON.
Create config.gateway.json
From the file find the nodes that you need to change. All other nodes needs to be removed or you will lose the ability to change that setting from the UI. You do need to keep the complete path for each JSON node that you change. So if we start with the setting for multiple WAN addresses. The eth2 interface looks like this in the downloaded configuration file:
{
"interfaces": {
"ethernet": {
"eth2": {
"address": [
"82.174.188.80/25"
]
}
}
}
}
The brakets ([]) under the address node suggests that its an array of settings. So we can just extend that with a coma separated list for the rest of the adresses we want.
{
"interfaces": {
"ethernet": {
"eth2": {
"address": [
"82.174.188.80/25",
"82.174.188.81/25",
"82.174.188.82/25",
"82.174.188.83/25",
"82.174.188.84/25"
]
}
}
}
}
The second thing we need is to change the hash algoritm for the esp and ike groups on the site-to-site setting. Here is why the downloaded file makes it easier, the names of the esp and ike groups need to match exactly for this to work. By downloading the config file we know they are correct. Clearing out all the other information around the specific hash setting the downloaded file looks like this:
{
"vpn": {
"ipsec": {
"auto-firewall-nat-exclude": "enable",
"esp-group": {
"ESP_92.214.168.9": {
"proposal": {
"1": {
"hash": "sha1"
}
}
}
},
"ike-group": {
"IKE_92.214.168.9": {
"proposal": {
"1": {
"hash": "sha1"
}
}
}
}
}
}
}
So all we need to do is change the sha1 value to sha256. We can then combine the two nodes into a complete file:
{
"interfaces": {
"ethernet": {
"eth2": {
"address": [
"82.174.188.80/25",
"82.174.188.81/25",
"82.174.188.82/25",
"82.174.188.83/25",
"82.174.188.84/25"
]
}
}
},
"vpn": {
"ipsec": {
"auto-firewall-nat-exclude": "enable",
"esp-group": {
"ESP_92.214.168.9": {
"proposal": {
"1": {
"hash": "sha1"
}
}
}
},
"ike-group": {
"IKE_92.214.168.9": {
"proposal": {
"1": {
"hash": "sha1"
}
}
}
}
}
}
}
You should always verify your JSON code with a verifier like jsonlint.com to make sure the structure is correct and all the brackets are there. Save this file as config.gateway.json.
Add config.gateway.json to Unifi controller
Now we need to make this available to the Unifi Controller so it can provision it on the USG. This file needs to be added to the site root folder on the Unifi Controller. Depending on what Unifi Controller you use the location may vary. On the Cloud Key Gen 2+ it’s under /srv/unifi/data/sites/{siteID}/. The site ID is the same you have in the url when looking at the specific site dashboard. If you only have one site it’s usualy default. If the sites folder doesn’t contain a folder for the specific site we need to create it. I have read several forum posts that you can create it your self but that doesn’t work in my experience. You need to force the Unifi Controller to create it otherwise it will not look in the folder for the config.gateway.json file.
The easiest way to do this is to upload a fake floorplan since they are stored in the site folder. Go to the Map view in Unifi Controller, select Floorplan and then Add a new floorplan and upload an image, any image will do. You can delete the image later. Now you will see the folder under /srv/unifi/data/sites/ and you can upload the file via SCP. Make sure to set the unifi user and group access the same as all other files in there.
Provision the changes
Now you just need to go in under Devices, select the USG and go under Config – Manage Device and then Provision. Now the custom changes in the config.gateway.json file will always override what ever you set in the UI.
If the USG just provisions over and over again that means that something is wrong with the file. If you remove it the USG will come back to normal. If this happens double check that the settings are supported and that the JSON is correct.
Hackviking aka Kristofer Källsbo 
Pingback: Split DNS forwarding from Unifi gateway | Hackviking aka Kristofer Källsbo