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

Overview


This article describes how to create the config.gateway.json file and how to use it. The file config.gateway.json is used for advanced configuration of the USG. This file allows you to make customizations persistent across provisions. 

How to customize USG configuration with config.gateway.json


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 is placed under the <unifi_base>/data/sites/the_site directory stored on the controller.

info_i_25x25.png Note: The location <unifi_base> will vary depending on your operating system. See this article for more information.

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/.  Therefore, in my case, I will create a folder named ceb1m27d underneath, and then place config.gateway.json inside.

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. It is important to note here that the custom json file is a "replace" instead of a "merge" of the sections of configuration. You must keep that in mind so you include ALL the items, and not only the new ones you wish to add. 

User Notes & Tips


These notes have been added thanks to user collaboration. Have anything to contribute? Click on the Give Feedback button below!

  • On an Ubuntu install the path for the .json file is: /usr/lib/unifi/data/sites/[site name/default]/
  • An easy way to test the validity of the json file is: python -m json.tool config.gateway.json

Related Articles