WireGuard on Unifi USG

I have been looking around for a good VPN solution to use while traveling recently. I have a few services running at home, that I really don’t want on the internet (OctoPrint, general ssh access etc), but I want to use remotely. I also want a way to secure my connection when I don’t trust the network I’m connecting through.

I had previously set up a L2TP Remote user VPN in the UniFi controller, but it had a few issues.

  • Instability on android (the VPN wouldn’t even show as ‘disconnected’, it would simply stop)
  • Issues when connecting to it from ipv6 cell carriers

I had heard of Wireguard a while ago and have been keeping track of development and their status on integrating with the Linux kernel. It turns out some kind soul has created a deb package to install WireGuard on Vyatta (which is what the USG is based on).


  • Pick up the correct .deb from here
    • curl -sL https://github.com/WireGuard/wireguard-vyatta-ubnt/releases/download/<version>/wireguard-<board>-<version>.deb -o wireguard-<board>-<version>.deb worked for me
    • In my case, the command was curl -sL https://github.com/WireGuard/wireguard-vyatta-ubnt/releases/download/1.0.20220627-1/ugw4-v1-v1.0.20220627-v1.0.20210914.deb -o wireguard-ugw4-0.0.20191012-1.deb for my USG pro 4
  • sudo dpkg -i wireguard-<board>-<version>-1.deb to install the package
  • sudo -i to make everything easier
  • cd /config/auth for the location to put the wireguard configuration
  • umask 077 && mkdir wireguard && cd wireguard for the server keys
  • wg genkey | tee wg_private.key | wg pubkey > wg_public.key to create server keys
  • wg genkey | tee client1_private.key | wg pubkey > client1_public.key to create the first client keys.
  • You will need one of these keys for each client connecting to the VPN
  • Then we move over to the UniFi controller to create the config for the VPN


UniFi gateways are pretty similar to EdgeRouter products from Ubiquiti, with a crucial difference. Any config changes done from the CLI are wiped out on reboots, or any config changes from the controller. the UniFi Controller is nice, but does not support the full range of EdgeOS features that we can use.

Thankfully there is a solution – config.gateway.json. This file is layered over the base config that gets generated by UniFi, and allows much more control of a USG.

I created this file in my UniFi controller, which for me, on Ubuntu the right location is:

    "firewall": {
        "group": {
            "network-group": {
                "remote_user_vpn_network": {
                    "description": "Remote User VPN subnets",
                    "network": [
    "interfaces": {
        "wireguard": {
            "wg0": {
                "description": "VPN for remote clients",
                "address": [
                "firewall": {
                    "in": {
                        "name": "LAN_IN"
                    "local": {
                        "name": "LAN_LOCAL"
                    "out": {
                        "name": "LAN_OUT"
                "listen-port": "443",
                "mtu": "1352",
                "peer": [
                        "<content of client1_public.key>": {
                            "persistent-keepalive": 60
                "private-key": "/config/auth/wireguard/wg_private.key",
                "route-allowed-ips": "true"

Client Configs

Next up – lets add some client configs. First device I wanted to add (as I was at home, and wanted to make sure this worked from outside the network, and is the main device I seem to want remote access from) is my Android phone.

So, I created the following config on the unifi controller:

    PrivateKey = <content of client1_private.key>
    Address =
    DNS = <internal DNS Server>
    PublicKey = <content of wg_public.key>
    Endpoint = <external-fqdn>:443
    AllowedIPs = <local subnets>,

I could then use the following:

qrencode -t ansiutf8 < wireguard.conf

This printed a qrcode on my console that I could import the config into the Android app. qrencode is available on the ubuntu repo via:

apt install qrencode

For additional clients, it is pretty easy as well, simply install wireguard-tools and then create a similar file. We have to re run the:

wg genkey | tee client1_private.key | wg pubkey > client1_public.key

and add an extra peer to the config.gateway.json file, for each new client, but that is all the config we need.

Starting it all up

You will also have to allow udp/443 to pass through the firewall. I created a rule in the GUI that allows udp/443 on the WAN_LOCAL group.

Now, to force the provisioning for the USG, just go to your unifi controller, then find the device. In the settings (the cog icon) for the device find the following section:

and trigger a force provision.

Then when it is deployed, you can start the tunnel on your end device!

To check if the wireguard service is actually listening, you can run netstat and see if there is anything listening on udp/443

    root@edge:~# netstat -npl | grep 443 | grep udp
    udp        0      0       *                           -
    udp6       0      0 :::443                  :::*                                -


Force provision is no longer available in the Unifi Controller WebUI, i suggest changing your firewall’s name to something different (I use “firewalll” with a third L), and then save the settings. This will get the firewall to provision again.