Update 2018 June 17: See this post for a nicer way to create these DHCP static entries on the USG. The below applies to an older and more difficult version of the USG software.


The Ubiquiti Unifi controller is making progress in its feature set, but it still lacks basic configuration options found in standard consumer routers. For my specific case I was replacing an ASUS gateway with the USG and needed to set static DHCP entries before removing devices.

The Unifi controller GUI does allow setting static IP addresses but only if the device is already connected to the network. I needed to set the static IP before the device was on the network.

Static IP address using Unifi CLI

This is a tedious series of commands. First ssh to the USG host and execute the below, making sure to replace the network name, subnet CIDR, hostname, IP, and MAC with your values.

configure

set service dhcp-server shared-network-name LAN_10.1.1.0-24 subnet 10.1.1.0/24 static-mapping freenas ip-address 10.1.1.230

set service dhcp-server shared-network-name LAN_10.1.1.0-24 subnet 10.1.1.0/24 static-mapping freenas mac-address 'aa:bb:cc:dd:ee:ff'

set system static-host-mapping host-name freenas.lan inet 10.1.1.230

set system static-host-mapping host-name freenas.lan alias freenas

commit
save
exit

Check if the hostname works. It should! However these changes will be lost on a reboot or provision.

Persist the change

The configuration changes above are lost on reboot and we persist them by creating a config.gateway.json file on the Unifi controller. Be careful since bad json syntax can cause reboot loops.

First ssh to the USG and get the current configuration using
mca-ctrl -t dump-cfg > config.gateway.json. Remove the unifi-configured lines from the configuration to keep only the CLI-added config. Save the file.

Validate and format the file with python -m json.tool < data.json. Fix any issues!

Now ssh to the Unifi controller and copy the new configuration to /var/lib/unifi/sites/default/config.gateway.json. Reboot the USG and the configuration should be applied correctly.

For reference, below is the json used for my FreeNAS entry.

{
  "service": {
    "dhcp-server": {
      "shared-network-name": {
        "LAN_10.1.1.0-24": {
          "subnet": {
            "10.1.1.0/24": {
              "static-mapping": {
                "freenas": {
                  "ip-address": "10.1.1.230",
                  "mac-address": "aa:bb:cc:dd:ee:ff"
                }
              }
            }
          }
        }
      }
    }
  },
  "system": {
    "static-host-mapping": {
      "host-name": {
        "freenas.lan": {
          "alias": [
            "freenas"
          ],
          "inet": [
            "10.1.1.230"
          ]
        }
      }
    }
  }
}