Unifi

UniFi – How to further customize USG configuration with config.gateway.json

by jack · March 16, 2016

UniFi – How to further customize USG configuration with config.gateway.json

Obtained from: https://help.ubnt.com/hc/en-us/articles/215458888-UniFi-How-to-further-customize-USG-configuration-with-config-gateway-json

Overview

The file config.gateway.json is used for advanced configuration of the USG. This file allows you to make customizations persistent across provisions.

When making customizations via the config.gateway.json file it is best to extract only the customizations that can’t be performed via the controller UI. This may take some patience because if you get the formatting wrong you’ll trigger a boot loop on the USG.

Some users may find they can get away with dumping the full config, but it’s possible that this could cause issues down the road. It could cause a bootloop when you change a setting via the controller UI.

By default, there is no such a file, a user has to create this file in order to use it. The config.gateway.json file is used to define is placed under [UniFi base]/data/sites/the_site directory.

https://127.0.0.1:8443/manage/s/ceb1m27d/dashboard

For every site, you will find a unique random string that assigns to the site. In above case, the random string ceb1m27d is the folder name that shall be used under [UniFi base]/data/sites/ (On the CloudKey use /srv/unifi/data/sites). Therefore, in my case, I will create a folder named ceb1m27d underneath, and then place config.gateway.json inside.

Here are possible locations of the Unifi Base directory:

–Data folder locations

MSW:
Vista+: C:\Users\username\Ubiquiti UniFi\data
XP: C:\Documents and Settings\username\Ubiquiti UniFi\data

Linux:
Actual directory: /var/lib/unifi/
Symlinked directory: /usr/lib/unifi/data

Mac: /Applications/UniFi.app/Contents/Resources/data

Before customizing anything, you should check the existing config.boot to make sure you aren’t using an existing rule number (if applicable). You can do this several ways. I’m going to use SSH to connect to my USG and issue:

cat /config/config.boot

So for my example, I’m going to create a DNAT rule for DNS (this is just an example, may not be best use case). I’ll configure using EdgeOS formatting:

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 source 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

Once I’m done, I want to export the config. That is done via:

mca-ctrl -t dump-cfg

Note, I don’t bother exporting to the file. You can if you wish. If you were to do that you would do:

mca-ctrl -t dump-cfg > config.txt

So I find the appropriate section in my config output:

“nat”: {
“rule”: {
“1”: {
“destination”: {
“port”: “53”
},
“inbound-interface”: “eth0”,
“inside-address”: {
“address”: “10.0.0.1”,
“port”: “53”
},
“protocol”: “tcp_udp”,
“type”: “destination”
},

So that’s my custom rule, but it’s not entirely in the format. If you look at the config output from the start, there is a certain format. If I wanted JUST this rule in the config.gateway.json, my file would look like:

{
“service”: {
“nat”: {
“rule”: {
“1”: {
“destination”: {
“port”: “53”
},
“inbound-interface”: “eth0”,
“inside-address”: {
“address”: “10.0.0.1”,
“port”: “53”
},
“protocol”: “tcp_udp”,
“type”: “destination”
}
}
}
}
}

If you have multiple sections to add, like say service and then VPN, the closing bracket for that section would be followed by a comma, then you would start the next section. For example service and VPN would be two separate sections.

It would be useful to validate your code. There are a number of free options out there if you search json validator via your favourite search engine.

Hopefully this gives some insight on how to create a config.gateway.json file.

This site uses Akismet to reduce spam. Learn how your comment data is processed.

UniFi – How to further customize USG configuration with config.gateway.json