Ubiquiti are known for their Unifi range WiFi access points and easy management. If you use their controller software you can get some useful graphs and a dead-easy configuration utility. However, without having Unifi switches and gateway router (USG) you won’t get detailed traffic statistics. Problem with that is – you may not be able or willing to just swap out a gateway router, plus the Unifi firewall config is still not where it should be in my view.

The workaround I found is to simply disable NAT via the CLI and have an additional subnet between the gateway router and the USG. You can also turn off the firewall completely on the USG, but in most home use cases that’s not required. So this is the basic idea:

WAN <–> GW router <–> USG <–> LAN

Don’t forget to add a static route on the GW router pointing back to the LAN subnet and use a static IP for the USG WAN interface. Now let’s turn of NAT!

  1. ssh <your Unifi admin user>@<IP of your USG LAN interface>
  2. type ‘configure
  3. type ‘show service nat‘  #you should see rule 6001, 6002, 6003 by default
  4. type ‘set service nat rule 6001 disable‘ #disables corporate network NAT
  5. type ‘set service nat rule 6002 disable‘ #disables remote user network NAT
  6. type ‘set service nat rule 6003 disable‘ #disables guest network NAT
  7. type ‘compare‘ #just to see if you did things right 🙂
  8. type ‘commit
  9. type ‘save
  10. type ‘mca-ctrl -t dump-cfg > config.gateway.json‘  #IMPORTANT! you need this json file to make your changes persistent on the Unifi controller. Without this the USG reboots at some point and all changes are reverted!
  11. copy this file over to your Unifi controller, make sure it’s in the right location. In my case there’s only one site so the path is the default location.’scp config.gateway.json root@<controller_IP>:/usr/lib/unifi/data/sites/default/config.gateway.json


Optionally, if you wish to disable the firewall you can add the following steps between “6” and “7” above:

  1. type ‘delete interfaces ethernet eth0 firewall‘  #WAN port firewall settings
  2. type ‘delete interfaces ethernet eth1 firewall‘  #LAN1 port firewall settings
  3. type ‘delete interfaces ethernet eth2 firewall‘  #LAN2 port firewall settings

Obviously you only want to do this if you have that other gateway router and trust it’s firewall!


IMPORTANT! If you ran this procedure already and want to do other changes through the GUI or CLI (add a network, change USG IP’s, change DHCP settings, etc) you need to remove the  config.gateway.json file from the controller first, do your changes and run the procedure after. I really hope Ubiquiti will add all the CLI functionality to the GUI soon to make all of the above obsolete :).


15 Replies to “Run a Ubiquiti USG in (semi) Transparent Mode

  1. hey larse.

    How would this work with a layer 2 trunk with multiple vlans? will the usg pass through all vlans to the aps like a normal l2 bridge or this is completely outside of the scope of what the usg can be tricked into doing when nat is disabled?

    • Nathan,

      You can add sub-interfaces with VLAN tags and reuse (re-tag) across interfaces, but the USG would still act as a layer 3 device. Turning off NAT is helpful if you have another gateway router or firewall and you’d like to see traffic streams per enduser device rather than just one NATed address. A true layer 2 mode is out of scope and probably won’t be coming to the USG. It’s just not what it was intended for.

      Here an example config with VLAN 100 added to Eth2:

      ethernet eth2 {
      description LAN2
      firewall {
      in {
      ipv6-name LANv6_IN
      name LAN_IN
      local {
      ipv6-name LANv6_LOCAL
      name LAN_LOCAL
      out {
      ipv6-name LANv6_OUT
      name LAN_OUT
      + vif 100 {
      + address
      + }

      The ‘+’ just means the config was added but not applied yet.

  2. My understanding is that the contents of config.gateway.json gets merged into the configuration done via the GUI.
    So if your config.gateway.json only contains the disabling of the natting, then you can still configure other things via the GUI.

    • Holger,

      The config.gateway.json file overrules whatever configuration is in the USG. Unfortunately the UniFi logic does not take the file into account when making changes through the GUI. This results in a constant provisioning loop as soon as you change things like DHCP, DNS – or basically anything that’s handled by the USG. The painful workaround is to remove the config.gateway.json file before making any changes through the GUI and re-do all manual configs after provisioning. After the manual changes are back in just recreate the config.gateway.json file as per the procedure and all is back to normal.
      Eventually I got tired of it and just automated the steps (hint – add timers!). This effects SW upgrades as well, not just config changes…

      I really hope Ubiquity one day will get their act together and permit CLI changes to merge with GUI configurations. It’s not that hard to do 🙂

      • I think you need to both read section “Editing config.gateway.json” on this page:

        Also, see this post for a proper example of how to do exactly this, where you can still make changes in the GUI without having to clear the config.gateway.json every time:

        • Noffie, Thanks for sharing those posts!
          I went ahead and tried it out but unfortunately my previous statement still stands. With the proposed rule 5999 I can preempt the default NAT rules, but since there is a config.gateway.json file present to create it no more GUI changes are applied. Rule 5999 was persistent throughout a software upgrade as well as GUI config changes. Bad news is that non of my GUI changes made it into the USG. In my particular test I tried to modify/remove/add a network to LAN2 with no success. Only when the config.gateway.json file was removed, GUI configurations made it into the USG. The way I see it you can either go through the process I described at the very top of this post and disable each particular NAT rule OR create an ‘exclude’ rule with a lower number, which is actually more elegant :). BUT you still have to remove/recreate the json file for any changes to your network(s).

          I’ll add the adjusted procedure in a few days as it makes this whole process a little shorter.

          • Lars,

            Odd, I swear it is working correctly for us to do GUI changes after putting a config.gateway.json in place, but maybe I need to do some more testing.

            One thought I had – are you putting everything in your config.gateway.json file, or just the relevant NAT change? Here is the ENTIRE CONTENTS of our config.gateway.json file:

            “service”: {
            “nat”: {
            “rule”: {
            “5999”: {
            “exclude”: “””,
            “outbound-interface”: “eth0”,
            “type”: “masquerade”

            It actually says in that UniFi documentation I linked to that it is dangerous to have anything in your config.gateway.json file that can be changed in the GUI. Can result in a re-provisioning loop.



    My ISP provided me with a public IP 83.212.x.x and behind it routed a subnet class 89.149.x.x/27 so I can connect some of my computers with their own public IP to the Internet. I disable the NAT as you said above and added the subnet to the WAN eth2 port but it does not work and I had to restore the settings. Can you PLEASE help me solve this situation?

    Kind regards,

    • R,

      For this to work you’d need to add the 89.149.x.x/27 network to LAN or LAN2 and as type ‘corporate’. That should tell the USG to route traffic from the LAN/LAN2 interface out of WAN (and enable NAT, which you can turn off after). You’d still need some kind of routing for the 89.149.x.x/27 subnet to be reachable from the internet. Did your provider give you any details for that? For example, is there a static route configured on their end, OSPF, etc..?

      Another important thing to remember is that the USG is a state-full firewall. By default it will only let packets in on the WAN port that are part of a registered session. So if you are planning to use a web server on the 89.149.x.x/27 range, you’d still have to create a firewall / port forwarding rule that permits / forwards incoming traffic on port 80/443.


  4. Hello,

    Been trying to get DPI working behind our ISP route for along time now but keep hitting brick walls.

    We run a MPLS network, so all our network traffic/ internet routed from our layer 3 core switch (IP: through our Transit VLAN 90 to the ISP router (IP:, which then sort.

    I need to place our USG between our core switch and ISP Router but keep the VLAN90 tag intact so the ISP route can forward on to the right place.

    Just want to see if anyone could help.

  5. instead of publishing the entire USG config, only push in the changes you want. this will allow you to make other changes via the UI, without having to constantly and manually update the json with the full configuration as you have outlined above.

    /srv/unifi/data/sites/default# cat config.gateway.json
    “service”: {
    “nat”: {
    “rule”: {
    “6001”: {
    “disable”: “””
    “6002”: {
    “disable”: “””
    “6003”: {
    “disable”: “””

    • teege, this sounds like an interesting alternative! Let me try and revert back. Would make this whole thing a lot less painful 😉

  6. Hi,

    I can’t seem to get this to work for anything on the WAN2 Network. It creates a new NAT rule 6004 and the compare doesn’t look right and commit fails.

    Any thoughts?



  7. Hi, can I ask, which jobs operates USG and which jobs operates GW router? I mean, who operates DHCP, routing, statistics, etc. In your network settings, can USG operates DPI, statistics, firewall and see all clients in the network? Why I am asking, because I want similar network settings, but I want see statistics on GW router but also on USG.

    Thank you.

    • In my case the GW router is the primary firewall and handles NAT. The USG takes care of LAN functions such as DHCP. You can also get all featured from the Unifi controller, including statistics, DPI, graphs and easy WiFi/switch management. As the USG runs in layer 3, it can have fire-walling turned on or off. I would not recommend IDS/IPS on the USG as it will bring down your throughput to 80-90Mbit.

Leave a Reply

