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 :).


44 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 😉

      • Hello,

        Late the the party here. I’m trying to get my USG working behind a pfSense router. So in teege’s example, those lines would be the only commands in the config.gateway.json file?


        • Alan,

          I went with Noffie’s recommendation and created a rule with a lower number that excludes NAT on eth0:

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

          Works fine and survives other changes via the GUI :). But yes – that should be the only thing in the config.gateway.json file (unless you have other non-GUI configs).


          • Lars,
            If I’m understanding this correctly, we’re just concerned with the WAN port (hence, eth0) since the inbound traffic is coming through there. I don’t need to concern myself with eth1?

            Since pfSense is handling firewall functionality, I’ll just need to add the appropriate notation to disable the firewall on eth0 to your example.

            This is my crash course in network and firewall configuration 🙂 Thanks for your patience.

          • Well, if you only use the small section of the config.gateway.json file you can’t follow the ‘delete interfaces ethernet eth0 firewall‘ route. Instead you can just add an “Accept ALL” rule on the WAN interface of your USG via the controller GUI. Make sure it’s placed before the predefined ones.

            If you don’t have other (internal) networks on the WAN side of the USG that need to connect to networks on the LAN side you can actually leave the USG firewall on and feel safe behind 2 firewalls :).

  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.

  8. Tried this for a almost identical config WAN GW router USG LAN but my clients lose ability to ping or comm with subnet on WAN interface

  9. So I have a firewall as my gateway doing the SNAT infront of the USG. ISPFWUSGInternalNetwork. A few questions:
    Do you still use the USG to define the networks, wireless networks,vlans, and DHCP?
    What IP address would you give the USG WAN interface and the internal FW interface?
    Do I have to create a static rule on the USG to send all defined internal networks traffic to the WAN interface or nexthop to the internal interface of the FW?

    I have a guest network (vLan2) defined and corporate network defined.

    • William, you can still use the USG/UniFi controller to create your networks. I assume (VLAN 2) and for Corp. WAN subnet could be with .1 for FW and .2 for the USG WAN interface. If you work with a default route on the USG pointing to you would only need to add static routes on the FW to and with next hop Keep in mind that depending on how far you took the USG config you may or may not be able to ping from your firewall to clients on and That is because turning off NAT does not turn off the stateful firewall feature of the USG. I described an option to disable firewalling as well in case you don’t want/need it. Also, use the NAT overrides described below by ‘teege’ and ‘Noffie’ to avoid loosing any other custom configs. I’ll update the guide when I get some time :).

  10. Hello all,
    I have been struggling with my USG for quite sometime, and thinking of abandoning all together. here is what I have

    GW: (sonicwall)
    USG LAN1 IP:

    1. I am able to SSH into the USG using WAN port.
    2. I can ping from the USG to MAIN NETWORK
    3. Controller is connected to cloud, I can see all my devices and see cameras
    4. I have correct rules setup on the sonicwall
    5. I have WAN IN, WAN LOCAL ACCEPT ALL, for firewall rules

    I am unable to ping or see my LAN1 from neither ADMIN or MAIN network. There are multiple networks that I connect to with SONICWALL, DELL, but just not able to get this connected. Everything seems to get out of LAN1 BUT NOTHING IN????

    Hope someone is able to assist, driving me bonkers.

    • Brad,

      Unless specifically turned off, the USG will act as a stateful firewall by default. This means that if the connection state does not originate from the LAN network, packets to LAN will be dropped at the WAN interface. WAN IN and WAN LOCAL rules are related to – not to You can create specific rules to permit access from your ADMIN and MAIN network to LAN1. Also, don’t forget about routing. You’d need at the very least static routes on the SONICWALL pointing to the LAN1 subnet to the USG WAN IP.
      Anyway, this type of problem is exactly why I started this thread :).

  11. Question for you. If I disable the firewall on all connections after I have moved the json file over, do I have to remove it over the controller again?

    • Andrew,

      Correct… If you remove fire-walling you have to create and export the json file to the controller afterwards.

  12. Please help me:
    My network is follow:
    Cable modem -> Zyxel Zywall Firewall.
    I like the Ubiquiti USG put behind cable modem:
    Cable modem -> USG > Zyxel
    But i like use Zyxel main router.
    How to set up Ubiquiti device only bridge mode?

    • Following the procedures in this thread you can make this scenario work. BUT – the USG will NOT be in bridge mode! You can remove NAT and fire-walling functions, but it will remain a router operating in layer 3.

  13. Lars,
    I came across another method to disable both NAT and firewall functionality. I trust my primary firewall 🙂 Consider this script placed in USG directory /config/scripts/post-config.d



    $cmdwrap begin

    # Disable NAT
    $cmdwrap set service nat rule 5999 exclude
    $cmdwrap set service nat rule 5999 outbound-interface eth0
    $cmdwrap set service nat rule 5999 type masquerade

    # Disable Firewall
    $cmdwrap delete interfaces ethernet eth0 firewall
    $cmdwrap delete interfaces ethernet eth1 firewall

    # End changes
    $cmdwrap commit
    $cmdwrap end

    After placing the script in /config/scripts/post-cfg.d, make it executable with chmod +x [script filename]. From what I read, the script will execute after each re-provision/reboot.

    With this in place, I’ll still need to setup port forwarding for all traffic from WAN OUT to LAN?

      • Lars,
        I just noticed I made a typo on the second reference to the config directory. The directory should be /config/scripts/post-config.d


        • Just a quick note regarding the shell script method. After updating the firmware on the USG, I SSH’d in and ran ‘show nat rules’. Rule x5999 was not listed- the script was not run. I forced a restart of the USG from the controller to get the script executed and confirmed rule x5999 was present. Heads-up to anyone who decides to use the script method to disable NAT.
          (I just realized I could’ve just run the script directly from the CLI- oh, well.)

          • Alan, This is interesting :). Also, can you confirm that GUI configuration changes can live side by side with this script? I just didn’t get a chance yet to test it myself…


  14. Thanks for sharing this. I’ve been looking for a way to do something “similar”. I have A static block of IPs and I want to have one be the USG Pro WAN IP and the rest be part of a PUBLIC LAN2 (23.x.x88/29) and also have the normal LAN on

    ISP USG ( 23.x.x.90 ) PUBLIC LAN ( 23.x.x88/29)
    |—-> PRIVATE LAN ( )

    I created a corporate LAN “PUBLIC”, followed the 5999 rule to disable NAT, and even created a WAN IN FW rule to allow any traffic from ANY to interface PUBLIC ( 23.x.x88/29) . but nothing. I cannot ping the hosts in the PUBLIC LAN nor they can see the internet. hosts on PUBLIC LAN can reach the gateway address on the USG WAN and the actual ISP gateway not but pass that. So I am wondering what I am missing.

    • Matias- I’m not sure if this will be helpful to you but in my situation I’d neglected to enter the IP address of the LAN port that my USG WAN1 was connected to. It was the “Router” entry in the Networks –> WAN settings within controller. Once I entered that IP address and updated, the dashboard went from red (Bad) to green (Excellent) and began showing traffic statistics! I also have rule for WAN IN to pass all inbound WAN traffic to LAN. For this rule, I setup two groups. One for WAN subnet (10.x.24.0/24) and another for the LAN subnet (10.24.x.0/24).

      • Thanks for your reply. my USG does have a working WAN connection to the internet. On my PRIVATE LAN subnet everything works great. What I want to have is an PUBLIC subnet that is not NATed and that the nodes on that network have direct access to the internet AKA they are reachable directly from the internet.


        INTERNET USG PUBLIC LAN 23.x.x.90/29 ( NO INTERNET )

        It is worth noting that my current setup is a OpenBSD box with a WAN interface and a LAN interface bridged together and connected on the LAN to a switch which provides me what I want to do w/ the USG. I just wanted to migrate to the USG because of the nice UI and easy to use interface. But I am starting to wonder if I should just stick to my OpenBSD box or build myself a 1U rack OpenBSD router myself.

        • Finally got it working. I completely deleted all the network and started from scratch. and now it works … shrugs … Something was wrong on the previous installation.

          • Matias,
            Are you using the script that I listed? If so, I found that it is not running after making changes from controller’s web ui. It only runs when the USG is restarted. My apologies for misleading you.

  15. Lars-
    Through my own testing, configuration changes through the web GUI will not trigger execution of the shell script . I’m still learning about the UniFi ecosystem but I believe it’s due to where the affected components reside. In my case the controller resides on the CloudKey G2+ while the script resides on the USG. So when configuration changes are made, controller pushes that out to the USG. There doesn’t appear to be any hook in that process to trigger execution of the script on the USG.

    I tried to get confirmation of this from others on the UniFi forums but no one has been forthcoming so far. I find that puzzling since that’s where I learned about the script in the first place. However, I did find this thread on reddit which confirms my suspicions https://www.reddit.com/r/Ubiquiti/comments/61cb6u/execute_script_after_usg_provisioning_through/

    So it looks like I may have to take the JSON route after all. Boo. The script appealed to me because it allowed me to disable the firewall.

  16. randomly googled your article, nice one man
    Need a bit of help, I have my whole house UniFi set-up, USG, USW, UAP, all the good stuff.
    recently I upgraded my WAN to 1Gb full duplex and want to upgrade the USG to a ER-4, but I don’t want to lose the USG icon and the DPI function of the Controller, here are what I came up with
    ISP modem → ER-4 → USG → USW → UAP
    the ER-4 handle the firewall rules、NAT、PPPoE、DHCP and other heavy task;
    the USG with ONLY the DPI turn on for the statistics for the Controller
    Question, Is the USG be the bottleneck here? Or the whole idea just stupid
    forgeive me for the poor English, hope to hear back from you

    • Vincent,

      Unless you turn on IDS/IPS the USG should handle 1Gbit. It does at least in my case… With IDS/IPS you’re down to ~100Mbit. Now, the ER-4 can’t do DHCP to LAN clients behind the USG (router, firewall). You’d have to add a static route to the USG LAN on the ER-4 with gateway IP being the USG WAN address. Set up the USG LAN DHCP range on the UniFi controller and you should be good to go.

  17. Lars (or others)

    Ive had a USG-3 for some time but lost my fibre connection for 3 days recently due to a BT engineer!! So have gone down the backup WAN route, and have to use the CLI for a little but of tweaking to ensure when 4D LTE switches back and drops connection when the fibre is re-established.

    Am I right that the config.gateway.json file simply doesn’t exist in the sites folder on the cloudkey Gen2+ until you actually put one there? Asking because I can’t for the life of me find the feel anyway on the cloud key hard disk…

    Also just wanted to confirm that the file only needs the tweaks that aren’t done via the Gui?


    • Adrian,

      Not sure about the cloud key… As someone here pointed out here a while back, you only need to push the manual changes to the config.gateway.json file, so it could very well be that it doesn’t exist until you make a custom change. I’ll be setting up a new controller in a few days and will check for it.
      Ideally all changes that can be done via the GUI should be done there. This is really only for ‘undocumented features’ 🙂

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.