├── vlan0.png └── README.md /vlan0.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/evie-lau/Unifi-gateway-wpa-supplicant/HEAD/vlan0.png -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Unifi Gateway wpa_supplicant bypass for ATT fiber modem 2 | Use this guide to setup wpa_supplicant with your Unifi gateway to bypass the ATT modem. 3 | 4 | This will work on any modern [Unifi Console or Gateway](https://www.reddit.com/r/Ubiquiti/comments/1870ryr/unifi_gateways_explained_as_simple_as_possible/) running UniFi OS 3.x or 4.x. To my knowledge, that includes everything except the original USG which will have a different process that is already well documented over the years (check [Additional resources](#additional-resources)). 5 | 6 | > [!IMPORTANT] 7 | > Take note of your Unifi gateway's WAN port interface name. In the rest of the guide, I'll be using `eth1` because that is the WAN interface for the UXG Lite. If using another Unifi gateway, replace the interface name appropriately. 8 | 9 | Here are some known interfaces for Unifi gateways, for use in the rest of the guide. Double check with your device to be sure. 10 | - UXG Lite or UX - eth1 11 | - UXG Pro - eth0 (WAN1, RJ-45), eth2 (WAN2, SFP+) 12 | - UXG Max - eth4 13 | - UCG Ultra - eth4 14 | - UDR and UDM-Base (the egg) - eth4 15 | - UDM Pro or SE - eth8 (WAN1, RJ-45), eth9 (WAN2, SFP+) 16 | 17 | ### Prerequisites: 18 | - extracted and decoded certificates from an ATT modem 19 | 20 | Instructions to [extract certs from BGW210/BGW320](https://github.com/0x888e/certs) 21 | 22 | ## Table of Contents 23 | - [Install wpa_supplicant](#install-wpa_supplicant-on-unifi-gateway) - install wpasupplicant on your Unifi gateway 24 | - [Copy certs and config](#copy-certs-and-config-to-unifi-gateway) - copy files generated from mfg_dat_decode tool into Unifi gateway 25 | - [Spoof MAC Address](#spoof-mac-address) - spoof Unifi WAN port to match original ATT gateway MAC address 26 | - [Set Unifi network settings](#set-unifi-network-settings) - set required network settings (VLAN0) in Unifi dashboard 27 | - [Test wpa_supplicant](#test-wpa_supplicant) - test wpasupplicant 28 | - [Setup wpa_supplicant service for startup](#setup-wpa_supplicant-service-for-startup) - start wpasupplicant on Unifi gateway bootup 29 | - [Survive firmware updates](#survive-firmware-updates) - automatically restore and setup wpasupplicant after firmware updates wipe it 30 | 31 | ## Install wpa_supplicant on Unifi gateway 32 | SSH into your Unifi gateway. 33 | 34 | > [!TIP] 35 | > Unlike all my other Unifi devices, my SSH private key didn't work with my username, but worked with the `root` user instead. Or user + password defined in `Settings` -> `System` -> `Advanced` -> `Device Authentication`. 36 | 37 | The Unifi gateways run a Debian-based distro, so we can install the `wpasupplicant` package. 38 | 39 | > [!WARNING] 40 | > Some devices such as the UDR7 and UX7 may get a version of wpasupplicant from `apt install` that does not include the wired driver. If you encounter issues with the standard installation below, use the [alternative installation method](#alternative-installation-for-udr7ux7-and-other-devices) instead. 41 | 42 | ```bash 43 | > apt update -y 44 | > apt install -y wpasupplicant 45 | ``` 46 | 47 | ### Alternative installation for UDR7/UX7 and other devices 48 | If the standard `apt install` method doesn't work for your device (you'll know if `wpa_supplicant` fails with driver issues), download and install the packages directly from the Debian repositories instead: 49 | 50 | ```bash 51 | > mkdir -p /etc/wpa_supplicant/packages 52 | > cd /etc/wpa_supplicant/packages 53 | > wget http://security.debian.org/debian-security/pool/updates/main/w/wpa/wpasupplicant_2.9.0-21+deb11u3_arm64.deb 54 | > wget http://ftp.us.debian.org/debian/pool/main/p/pcsc-lite/libpcsclite1_1.9.1-1_arm64.deb 55 | > dpkg -i *.deb 56 | ``` 57 | 58 | > [!NOTE] 59 | > These are the same packages used in the [Survive firmware updates](#survive-firmware-updates) section, so if you use this method, you can skip downloading them again later. 60 | 61 | Create a `certs` folder in the `/etc/wpa_supplicant` folder. 62 | ```bash 63 | > mkdir -p /etc/wpa_supplicant/certs 64 | ``` 65 | 66 | We'll copy files into here in the next step. 67 | 68 | ## Copy certs and config to Unifi gateway 69 | Back on your computer, prepare your files to copy into the Unifi gateway. 70 | 71 | These files come from the mfg_dat_decode tool: 72 | - CA_XXXXXX-XXXXXXXXXXXXXX.pem 73 | - Client_XXXXXX-XXXXXXXXXXXXXX.pem 74 | - PrivateKey_PKCS1_XXXXXX-XXXXXXXXXXXXXX.pem 75 | - wpa_supplicant.conf 76 | 77 | ```bash 78 | > scp *.pem :/etc/wpa_supplicant/certs 79 | > scp wpa_supplicant.conf :/etc/wpa_supplicant 80 | ``` 81 | 82 | > [!WARNING] 83 | Make sure in the `wpa_supplicant.conf` to modify the `ca_cert`, `client_cert` and `private_key` to use **absolute paths**. In this case, prepend `/etc/wpa_supplicant/certs/` to the filename strings. It should look like the following... 84 | ```ini 85 | ... 86 | network={ 87 | ca_cert="/etc/wpa_supplicant/certs/CA_XXXXXX-XXXXXXXXXXXXXX.pem" 88 | client_cert="/etc/wpa_supplicant/certs/Client_XXXXXX-XXXXXXXXXXXXXX.pem" 89 | ... 90 | private_key="/etc/wpa_supplicant/certs/PrivateKey_PKCS1_XXXXXX-XXXXXXXXXXXXXX.pem" 91 | } 92 | ``` 93 | 94 | ## Spoof MAC address 95 | We'll need to spoof the MAC address on the WAN port (interface `eth1` on the UXG-Lite) to successfully authenticate with ATT with our certificates. 96 | 97 | In the Unifi dashboard, go to `Settings` -> `Internet` and select your WAN. Enable `MAC Address Clone` and paste the MAC address with your ATT gateway's address. 98 | 99 | > [!TIP] 100 | > If the above setting works for you, the rest of this section can be skipped. 101 | 102 | Using the Unifi dashboard didn't seem to work for me (did not test extensively), and I had to manually set it up instead, based on these [instructions to spoof mac address](https://www.xmodulo.com/spoof-mac-address-network-interface-linux.html). 103 | 104 | SSH back into your gateway, and create the following file. 105 | 106 | `vi /etc/network/if-up.d/changemac` 107 | 108 | ```bash 109 | #!/bin/sh 110 | 111 | if [ "$IFACE" = eth1 ]; then 112 | ip link set dev "$IFACE" address XX:XX:XX:XX:XX:XX 113 | fi 114 | ``` 115 | Replace the mac address with your gateway's address, found in the `wpa_supplicant.conf` file. 116 | 117 | Set the permissions: 118 | ```bash 119 | > sudo chmod 755 /etc/network/if-up.d/changemac 120 | ``` 121 | This file will spoof your WAN mac address when `eth1` starts up. Go ahead and run the same command now so you don't have to reboot your gateway. 122 | ```bash 123 | > ip link set dev "$IFACE" address XX:XX:XX:XX:XX:XX 124 | ``` 125 | 126 | ## Set Unifi network settings 127 | 128 | > [!CAUTION] 129 | > This section may not be applicable depending on your hardware configuration, especially if using an SFP bypass module. 130 | > 131 | > VLAN 0 seems to be necessary if you use the ATT external ONT. Otherwise, this step may not be needed. 132 | 133 | ### Set VLAN ID on WAN connection 134 | ATT authenticates using VLAN ID 0, so we have to tag our WAN port with that. 135 | 136 | In your Unifi console/dashboard, under `Settings` -> `Internet` -> `Primary (WAN1)` (or your WAN name if you renamed it), Enable `VLAN ID` and set it to `0`. 137 | 138 | > [!WARNING] 139 | > Before applying, note that this change will prevent you from accessing the internet until after running `wpa_supplicant` in the next step. If you need to restore internet access before finishing this setup guide, you can always disable `VLAN ID`. 140 | 141 | ![Alt text](vlan0.png) 142 | 143 | Apply the change, then unplug the ethernet cable from the ONT port on your ATT Gateway, and plug it into the WAN port on your Unifi gateway. 144 | 145 | ## Test wpa_supplicant 146 | While SSHed into the gateway, run this to test the authentication. 147 | ```bash 148 | > wpa_supplicant -i eth1 -D wired -c /etc/wpa_supplicant/wpa_supplicant.conf 149 | ``` 150 | Breaking down this command... 151 | - `-i eth1` Specifies `eth1` (UXG-Lite WAN port) as the interface 152 | - `-D wired` Specify driver type of `eth1` 153 | - `-c /wpa_supplicant.conf` The config file 154 | 155 | > [!TIP] 156 | > If troubleshooting is needed, add the parameter `-C /var/run/wpa_supplicant -B` to run in the background and allow the `wpa_cli` utility to connect. 157 | > 158 | > This can also be achieved in the `wpa_supplicant.conf` file by adding the line `ctrl_interface=DIR=/var/run/wpa_supplicant`, which will also apply when we later have wpa_supplicant service run automatically. 159 | 160 | You should see the message `Successfully initialized wpa_supplicant` if the command and config are configured correctly. 161 | 162 | Following that will be some logs from authenticating. If it looks something like this, then it was successful! 163 | ``` 164 | eth1: CTRL-EVENT-EAP-PEER-CERT depth=0 subject='/C=US/ST=Michigan/L=Southfield/O=ATT Services Inc/OU=OCATS/CN=aut03lsanca.lsanca.sbcglobal.net' hash=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 165 | eth1: CTRL-EVENT-EAP-PEER-ALT depth=0 DNS:aut03lsanca.lsanca.sbcglobal.net 166 | eth1: CTRL-EVENT-EAP-SUCCESS EAP authentication completed successfully 167 | eth1: CTRL-EVENT-CONNECTED - Connection to XX:XX:XX:XX:XX:XX completed [id=0 id_str=] 168 | ``` 169 | > [!TIP] 170 | > If you don't see the `EAP authentication completed successfully` message, try checking to make sure the MAC address was spoofed successfully. 171 | 172 | `Ctrl-c` to exit. If you would like to run it in the background for temporary internet access, add a `-B` parameter to the command. Running this command is still a manual process to authenticate, and it will only last until the next reboot. 173 | 174 | ## Setup wpa_supplicant service for startup 175 | Now we have to make sure wpa_supplicant starts automatically when the Unifi gateway reboots. 176 | 177 | Let's use wpa_supplicant's built in interface-specific service to enable it on startup. More information [here](https://wiki.archlinux.org/title/Wpa_supplicant#At_boot_.28systemd.29). 178 | 179 | Because we need to specify the `wired` driver and `eth1` interface, the corresponding service will be `wpa_supplicant-wired@eth1.service`. This service is tied to a specific .conf file, so we will have to rename our config file. 180 | 181 | Back in `/etc/wpa_supplicant`, rename `wpa_supplicant.conf` to `wpa_supplicant-wired-eth1.conf`. 182 | ```bash 183 | > cd /etc/wpa_supplicant 184 | > mv wpa_supplicant.conf wpa_supplicant-wired-eth1.conf 185 | ``` 186 | 187 | Then start the service and check the status. 188 | ```bash 189 | > systemctl start wpa_supplicant-wired@eth1 190 | 191 | > systemctl status wpa_supplicant-wired@eth1 192 | ``` 193 | If the service successfully started and is active, you should see similar logs as when we tested with the `wpa_supplicant` command. 194 | 195 | Now we can go ahead and enable the service. 196 | ```bash 197 | > systemctl enable wpa_supplicant-wired@eth1 198 | ``` 199 | 200 | Try restarting your Unifi gateway if you wish, and it should automatically authenticate! 201 | 202 | ### Add failure tolerance to wpa_supplicant 203 | If WAN doesn't come back up after a restart, it may be that wpa_supplicant is starting too soon. Regardless, we can configure a retry for the wpa_supplicant service. 204 | 205 | ```bash 206 | > vi /etc/systemd/system/wpa_supplicant-wired@.service.d/restart-on-failure.conf 207 | ``` 208 | 209 | ```ini 210 | [Unit] 211 | # Allow up to 10 attempts within a 3 minute window 212 | StartLimitIntervalSec=180 213 | StartLimitBurst=10 214 | 215 | [Service] 216 | # Enable restarting on failure 217 | Restart=on-failure 218 | # Wait 10 seconds between restart attempts 219 | RestartSec=10 220 | ``` 221 | 222 | This `.conf` file specifying the retries will tie into the wpa_supplicant-wired services, regardless of the eth number port. 223 | 224 | To confirm this conf has applied, restart the service and query for some properties. You should at least see `Restart=on-failure` from the query. 225 | 226 | ```bash 227 | > systemctl daemon-reload 228 | > systemctl restart wpa_supplicant-wired@eth1.service 229 | > systemctl show wpa_supplicant-wired@eth1.service -p Restart -p RestartSec 230 | ``` 231 | 232 | ## Survive firmware updates 233 | Firmware updates will nuke the packages installed through `apt` that don't come with the stock Unifi OS, removing our `wpasupplicant` package and service. Since we'll no longer have internet without wpa_supplicant authenticating us with ATT, we can't reinstall it from the debian repos. 234 | 235 | Let's cache some files locally and create a system service to automatically reinstall, start, and enable wpa_supplicant again on bootup. 236 | 237 | First download the required packages (with missing dependencies) from debian into a persisted folder. These are the resources if you wish to pull the latest download links. Make sure to get the `arm64` package. 238 | - https://packages.debian.org/bullseye/arm64/wpasupplicant/download 239 | - https://packages.debian.org/bullseye/arm64/libpcsclite1/download 240 | 241 | > [!NOTE] 242 | > If you used the [alternative installation method](#alternative-installation-for-udr7ux7-and-other-devices) above, you already have these packages and can skip this download step. 243 | 244 | ```bash 245 | > mkdir -p /etc/wpa_supplicant/packages 246 | > cd /etc/wpa_supplicant/packages 247 | > wget http://security.debian.org/debian-security/pool/updates/main/w/wpa/wpasupplicant_2.9.0-21+deb11u3_arm64.deb 248 | > wget http://ftp.us.debian.org/debian/pool/main/p/pcsc-lite/libpcsclite1_1.9.1-1_arm64.deb 249 | ``` 250 | 251 | > As of the 3.1.15 -> 3.1.16 firmware update, my `/etc/wpa_supplicant` folder did not get wiped, so these should persist through an update for us to reinstall. 252 | 253 | Now let's create a service to install these packages and enable/start wpa_supplicant: 254 | 255 | ```bash 256 | > vi /etc/systemd/system/reinstall-wpa.service 257 | ``` 258 | 259 | Paste this as the content: 260 | ```ini 261 | [Unit] 262 | Description=Reinstall and start/enable wpa_supplicant 263 | AssertPathExistsGlob=/etc/wpa_supplicant/packages/wpasupplicant*arm64.deb 264 | AssertPathExistsGlob=/etc/wpa_supplicant/packages/libpcsclite1*arm64.deb 265 | ConditionPathExists=!/sbin/wpa_supplicant 266 | 267 | After=network-online.target 268 | Requires=network-online.target 269 | 270 | # Allow up to 10 attempts within ~300 seconds 271 | StartLimitIntervalSec=300 272 | StartLimitBurst=10 273 | 274 | [Service] 275 | Type=oneshot 276 | ExecStartPre=/usr/bin/dpkg -Ri /etc/wpa_supplicant/packages 277 | ExecStart=/bin/systemctl start wpa_supplicant-wired@eth1 278 | ExecStartPost=/bin/systemctl enable wpa_supplicant-wired@eth1 279 | 280 | Restart=on-failure 281 | RestartSec=20 282 | 283 | [Install] 284 | WantedBy=multi-user.target 285 | ``` 286 | 287 | Now enable the service. 288 | ```bash 289 | > systemctl daemon-reload 290 | > systemctl enable reinstall-wpa.service 291 | ``` 292 | This service should run on startup. It will check if `/sbin/wpa_supplicant` got wiped, and if our package files exist. If both are true, it will install and startup wpa_supplicant. If `dpkg` or starting `wpa_supplicant` fail, the service will retry every 20 seconds up to 10 times. 293 | 294 |
295 |

(Optional) If you want to test this, click here...

 296 | 297 | ```bash 298 | > systemctl stop wpa_supplicant-wired@eth1 299 | > systemctl disable wpa_supplicant-wired@eth1 300 | > apt remove wpasupplicant -y 301 | ``` 302 | 303 | Now try restarting your gateway. Upon boot up, SSH back in, and check `systemctl status wpa_supplicant-wired@eth1`. 304 | - Alternatively, without a restart, run `systemctl start reinstall-wpa.service`, wait until it finishes, then `systemctl status wpa_supplicant-wired@eth1`. 305 | 306 | You should see the following: 307 | ``` 308 | Loaded: loaded (/lib/systemd/system/wpa_supplicant-wired@.service; enabled; vendor preset: enabled) 309 | Active: active (running) ... 310 | ... 311 | Dec 29 23:20:00 UXG-Lite wpa_supplicant[6845]: eth1: CTRL-EVENT-EAP-SUCCESS EAP authentication completed successfully 312 | ``` 313 |
314 | 315 | ## File list 316 | For my own sanity, here's a final list of files created or copied into the gateway during this guide: 317 | 318 | ``` 319 | etc 320 | ├── network 321 | │ └── if-up.d 322 | │ └── **changemac** (if needed for MAC spoof) 323 | ├── systemd 324 | │ ├── system 325 | │ │ └── **reinstall-wpa.service** 326 | │ └── wpa_supplicant-wired@.service.d 327 | │ └── **restart-on-failure.conf** 328 | └── wpa_supplicant 329 | ├── **wpa_supplicant-wired-eth1.conf** 330 | ├── certs 331 | │ ├── CA_XXX.pem 332 | │ ├── Client_XXX.pem 333 | │ └── PrivateKey_PKCS1_XXX.pem 334 | └── packages 335 | ├── wpasupplicant_..._arm64.deb 336 | └── libpcsclite1_..._arm64.deb 337 | ``` 338 | 339 | ## Troubleshooting 340 | 341 | Some problems I ran into... 342 | 343 | 344 |
345 | OpenSSL: tls_connection_ca_cert 346 | 347 | > OpenSSL: tls_connection_ca_cert - Failed to load root certificates error:02001002:system library:fopen:No such file or directory 348 | 349 | - Make sure in the wpa_supplicant config file to set the absolute path for each certificate, mentioned [here](#copy-certs-and-config-to-unifi-gateway). 350 |
351 | 352 | ## Additional resources 353 | Special thanks to many of these resources I used to learn all this (nearly from scratch). 354 | - [Guide for USG wpa_supplicant](https://wells.ee/journal/2020-03-01-bypassing-att-fiber-modem-unifi-usg/) 355 | - [ArchWiki wpa_supplicant guide](https://wiki.archlinux.org/title/Wpa_supplicant) where I learned to use wpa_supplicant 356 | - [Spoofing MAC on interfaces](https://www.xmodulo.com/spoof-mac-address-network-interface-linux.html) for spoofing MAC 357 | - [DigitalOcean Systemd unit files](https://www.digitalocean.com/community/tutorials/understanding-systemd-units-and-unit-files) for info on systemd unit files 358 | - [Post by /u/superm1](https://www.reddit.com/r/Ubiquiti/comments/18rc0ag/att_modem_bypass_and_unifios_32x_guide/) who posted a similar approach to mine a few days after. I adapted the reinstall service with some extra checks and improvements to also start/enable wpasupplicant after installing. 359 | --------------------------------------------------------------------------------