/ Ubiquiti

ATT Uverse Modem Bypass - UniFi USG

After some trial and error I've finally managed to bypass ATT's Uverse modem with my UniFi USG and EAP_Proxy. If you follow my guide, you can too!

Disclaimer: I am not responsible for any issues that may occur as a result of following this guide. If you have any concerns about what you're doing, please stop and do your own research.

I have not yet tested this with IPV6, if that is a requirement for you I suggest looking elsewhere. (Or combining this walkthough with the proper steps from someone else)


  1. SSH Program (Putty)
  2. SFTP Program (Filezilla)
  3. JSON Validator (JSONLint) - Go here now and leave it up until we need it
  4. EAP Proxy (https://github.com/jaysoffian/eap_proxy/archive/master.zip)
  5. Know your SSH credentials for the controller and USG. (Credentials can be set under Settings > Site > Device Authentication)

Please ensure you know the IP address of your USG and UniFi controller, you will need these later on. You should also have basic familiarity with a linux command line, as well as some knowledge of the USG and Cloud Controller.


Let's start by backing up our UniFi config, this way if anything goes wrong we'll have a working config to revert back to.

Navigate to your UniFi controller webpage and go to Settings > Maintenance > Backup > Download Backup.

Once the backup has downloaded, we can proceed by checking a few important settings.

First, we want to ensure we're not binding the VOIP port to WAN2.
To check this go to Settings > Site > Services and verify "Configure VOIP port as WAN2 on UniFi Security Gateway" is unchecked.

Next we'll create our LAN2 network.

Go to Settings > Networks > Create New Network and enter the below options

  • Name: LAN2
  • Purpose: Corporate
  • Parent Interface: LAN2
  • Gateway/Subnet: (or whatever you prefer)
  • DHCP Mode: None

Press Save.

Now we'll wire up our network.

The LAN port on the USG should be plugged into your LAN, the USG VOIP/WAN2/LAN2 port should be plugged into the ONT port on your Uverse modem, the cable from your ONT should be plugged into the USG WAN port.


Now extract eap_proxy.py and eap_proxy.sh from the eap_proxy zip you downloaded earlier.

Open the eap_proxy.sh file and ensure IF_WAN is set to eth0 and IF_LAN is set to eth2.

Next connect to your USG using your SFTP program of choice and copy eap_proxy.py and eap_proxy.sh to /config/scripts/post-config.d.
Note: After doing this please do not restart your USG until I specify to do so.

Open an SSH connection to your USG.

After connecting you should see this,


First we need to move eap_proxy.py, type sudo mv /config/scripts/post-config.d/eap_proxy.py /config/scripts/ . If you're prompted for a password enter the same one you used to log in initially.

Next we'll be adding a rule to the NAT ruleset, to verify this won't conflict with any preexisting rulesets type the following command cat /config/config.boot | grep 5010.

If this returned nothing, great! If it did return something, you'll want to change the NAT rule number I use below to a unique value.

Now we'll enter configuration mode on the USG with the command configure.


Take the below set commands and copy them all into a text editor. Replace "aa:bb:cc:dd:ee:ff'" in line 8 with your modem's mac address. You can generally find this on the side of your modem. (Example)

set interfaces ethernet eth0 vif 0 address dhcp
set interfaces ethernet eth0 vif 0 description 'WAN VLAN 0'
set interfaces ethernet eth0 vif 0 dhcp-options default-route update
set interfaces ethernet eth0 vif 0 dhcp-options default-route-distance 210
set interfaces ethernet eth0 vif 0 dhcp-options name-server update
set interfaces ethernet eth0 vif 0 firewall in name WAN_IN
set interfaces ethernet eth0 vif 0 firewall local name WAN_LOCAL
set interfaces ethernet eth0 vif 0 mac 'aa:bb:cc:dd:ee:ff'
set interfaces ethernet eth2 description 'AT&T router'
set interfaces ethernet eth2 duplex auto
set interfaces ethernet eth2 speed auto
set service nat rule 5010 description 'masquerade for WAN'
set service nat rule 5010 outbound-interface eth0.0
set service nat rule 5010 protocol all
set service nat rule 5010 type masquerade

Now that you've substituted your modem's mac, copy all the lines and paste them into your ssh session, when all the lines have been entered use commit to "save" them.

If you see this error, you can ignore it.
[ service nat rule 5010 outbound-interface eth0.0 ] NAT configuration warning: interface eth0.0 does not exist on this system

Now use exit to exit.
Note: You will see an error about the config not being saved, ignore it.

Next we'll dump our USG's current config, this is necessary in order to persist certain settings.

Enter the command mca-ctrl -t dump-cfg > configdump.txt

Copy configdump.txt to your computer using your SFTP program, you can type pwd to see the path it was written to.

The config file will likely be fairly large. We need to prune this down to the bare minimum in order to prevent issues down the road. The reason for pruning the file down to the minimum necessary values is to prevent issues that can be caused by changing settings in the UI that are also being forced via the config.gateway.json file. Visit https://goo.gl/qf19Ec for more information.

The file we're creating is called config.gateway.json. UniFi uses this file to persist settings you cannot set within the UI. It's important to make sure this file has valid settings and a valid format or you will run into issues.

If you already have a config.gateway.json file you'll want to merge in any preexisting changes you have. Make sure to back up the old version in case you need to roll back.

My sample config is (here), this should give you an idea of what yours should look like. It's important you update any existing references to your wan being eth0 to eth0.0.
Note: Please do not just copy down my config and use it, my config is unique to my needs and is a snapshot of what my config was at a specific point in time. Newer firmware versions may not play nice with this specific config. It should serve only as an example to assist you in understanding the correct format for pruning down your own.

After making the changes to your config file, copy the text into the json validator mentioned at the beginning and hit Validate JSON. If it comes back green and says "Valid JSON" your file has a proper json format. Make sure to save the file as config.gateway.json.

Now, let's upload it to your controller.

First, check your controller's webui to figure out your site name. It'll be after /site/ in the URL. As you see below, my site name is "default". If you do not have multiple sites on your controller this will likely be the name of yours as well.


In your SFTP program connect to your controller's (not USG's) address and navigate to /srv/unifi/data/sites/<yoursite>, then copy over your config.gateway.json file.
Note: If you're missing any folder in this path, just go ahead and create it.

Now we'll start eap_proxy for testing. Switch back to the ssh session you opened for your USG and input the below command. If you copy/paste it, make sure it's all on one line by putting it into a text editor first.

sudo python /config/scripts/eap_proxy.py --restart-dhcp --ignore-when-wan-up --ignore-logoff --ping-gateway eth0 eth2

Now power-cycle your modem by unplugging the power cable and plugging it back in.

After 5 or so minutes you should see something like the below.


It may not look precisely like this, just give it a few minutes and try to reach an external website.

If it's working, great! If not, retrace your steps and make sure you've completed all the steps in this guide. If you can't figure out what the issue is, see the roll back instructions further down.

Now that we know eap_proxy is working, our final step will be to make the eap_proxy.sh file executable. In your USG ssh session press CTRL + C to terminate eap_proxy then enter cd /config/scripts/post-config.d and next chmod +x eap_proxy.sh.

Finally, reboot your USG with reboot now. After it comes back up, force a provision on your controller by going to Devices > Your USG > Config > Manage Device > Provision.
Note: If it seems to get stuck provisioning or the controller never shows it coming back from its reboot, you may have an issue with your config.gateway.json file.


If you're having difficulty stop and read the error messages.

You can see the USG's syslog at /var/log/messages, this may hold clues as to what the issue is. Use tail -n 50 -f /var/log/messages to keep up with any updates to the file.

If you still can't figure out the issue there are a few places you can try for additional assistance,


If you continue to have issues that you're unable to resolve it's probably time to roll back your configuration changes.

Start by removing the config.gateway.json file from you controller. You can do this by sshing into the controller and typing rm /srv/unifi/data/sites/<yoursite>/config.gateway.json.

Next, restore your USG backup. To do this, open your controller's webui and navigate to Settings > Maintenance > Restore > Choose File and upload the backup you took at the start of this guide. This should restore you back to the configuration you had at the time of your backup.

If you're unable to reach the webui, try power cycling the USG and waiting 5-10 minutes. As a final resort you can also reset to factory defaults by pressing the reset button for 10 seconds.

If you're still having trouble rolling back, I'd suggest asking for help on the official ubiquiti forums or reddit.


eap_proxy: Jay Soffian (https://github.com/jaysoffian/eap_proxy)
To the members of DSL Reports, thanks for all your help (DSL Reports - Bypass Thread) and (DSL Reports - ATT TrueBridge Mode)

ATT Uverse Modem Bypass - UniFi USG
Share this