Ubiquiti USG config.gateway.json Syntax

README.md

Ubiquiti USG Advanced Configuration

Overview

Integrated DNS Overview

When using a USG with Ubiquiti's Unifi Controller software (version 5.6 and earlier), the functionality of integrating the hostnames of clients (when they request a DHCP lease) into local DNS does not appear to work as you would find with Consumer grade routers. To work around this limitation, we can add static host mappings to a configuration file that will be provisioned to the USG when either a configuration change is made or we force provisioning to the USG itself.

Non-GUI Supported Dynamic DNS Providers

I've added in the necessary syntax for adding Cloudflare DDNS to the USG for VPN/Services setup courtesy of this post by britannic on the Ubiquiti Forums.

Configuration File

On the CloudKey, the config file is located at /usr/lib/unifi/data/sites/default/config.gateway.json

Cloudflare DNS

You MUST pre-create the A Record for the hostname you wish to use for the USG. Once the record is created, API calls can successfully modify the record.

Later Releases

Override

The configuration in this file is overridden in the Unifi Controller software after version 5.6 by DHCP reservations (which appears to provide similar functionality to consumer-grade routers in that you no longer need to provide a configuration and hostnames are captured when they request a DHCP lease). It appears to be simply ignored.

Static IPs

In Unifi Controller software after 5.6, setting a static IP in the configuration when using a USG and after a client has already received their DHCP assigned address, to update the built-in DNS you must release and renew the client's IP from the client to update the DNS configuration

Troubleshooting

If the configuration doesn't seem to be applying-you may need to reboot your Controller/CloudKey.

sample-with-cloudflare-api-v1.json

{
        "service": {
                "dns": {
                        "dynamic": {
                                "interface": {
                                        "eth0": {
                                                "service": {
                                                        "custom-cloudflare": {
                                                                "host-name": [
                                                                        "host.mydomain.tld"
                                                                ],
                                                                "login": "[email protected]",
                                                                "options": [
                                                                  "zone=mydomain.tld"
                                                                ],
                                                                "password": "MYAPIKEYGOESHERE",
                                                                "protocol": "cloudflare",
                                                                "server": "www.cloudflare.com"
                                                        }
                                                }
                                        }
                                }
                        }
                }
        },
        "system": {
                    "static-host-mapping": {
                        "host-name": {
                                "mynas.mynet.mydomain.com": {
                                        "alias": [
                                                "mynas"
                                        ],
                                        "inet": [
                                                "192.168.1.99"
                                        ]
                                },
                                "unifi.mynet.mydomain.com": {
                                        "alias": [
                                                "unifi"
                                        ],
                                        "inet": [
                                                "192.168.1.30"
                                        ]
                                }
                        }
                }
        }
}

sample.json

{
        "system": {
                    "static-host-mapping": {
                        "host-name": {
                                "mynas.mynet.mydomain.com": {
                                        "alias": [
                                                "mynas"
                                        ],
                                        "inet": [
                                                "192.168.1.99"
                                        ]
                                },
                                "unifi.mynet.mydomain.com": {
                                        "alias": [
                                                "unifi"
                                        ],
                                        "inet": [
                                                "192.168.1.30"
                                        ]
                                }
                        }
                }
        }
}

I don't have a folder / site / pattern on my Cloudkey as you can see below ... how should I proceed?

root@UniFi-CloudKey:/usr/lib/unifi/data# ls
backup/ firmware.json model_lifecycles.json system.properties tmp/
db/ keystore@ system.configured system.properties.bk webrtc/
root@UniFi-CloudKey:/usr/lib/unifi/data#

In order to have these folders you have to upload a floorplan at least one time so the folder structures will be created. Until now (version 7.2.94 of the controller), this option is only available in the "Legacy Interface". In order to revert to "Legacy Interface" go to Settings -> System -> Legacy Interface and enable it.

Then go to Map and from the top left dropdown Topology, change it to floor plan. Then add a floor plan and save it. Now the directory structure should be ok and you could delete the floor plan.