×

UniFi - USG: How to Adopt a USG into an Existing Network

Overview

This article describes how to adopt a UniFi Security Gateway (USG) into an existing network in order to replace a (ISP provided) router/modem from a different manufacturer. The process of adopting a USG can differ from a UniFi Access Point (UAP) and UniFi Switch (USW) in that it may require some initial configuration prior to adoption. 

NOTES & REQUIREMENTS:
  • Applicable to all UniFi Security Gateway models (USG / USG-PRO-4 / USG-XG-8).
  • Join the UniFi discussion on the Ubiquiti Community and interact with other experts that are active on forum.
  • Refer to the Quick Start Guides (QSG) available in the UniFi R&S Download section for more information on setting up the different USG models.
  • If you are using an UDM or UDM-Pro, then refer to the Dream Machine QSGs available in the UniFi Download section.

Table of Contents

  1. Planning the Deployment and Establishing Internet Connectivity
  2. Upgrading the USG Firmware Before Adoption
  3. Configuring the LAN Network Manually
  4. Pre-Configuring the WAN and LAN Networks in the UniFi Controller
  5. Adopting the UniFi Security Gateway
  6. Troubleshooting Internet Connectivity Issues
  7. Related Articles

Planning the Deployment and Establishing Internet Connectivity

The diagram below shows an example setup where the ISP provided modem/router is running in a bridged mode. This is the easiest way to integrate the USG into the network as you can connect your devices to the LAN side and immediately establish Internet connectivity for the USG and the devices in the LAN. Afterwards, you can adopt the USG in the UniFi Controller and continue managing it as part of your UniFi ecosystem.

topology.png

After connecting the USG to the ISP provided modem/router that is running in a bridged mode, the USG will be able to obtain a DHCP address from the ISP and have connectivity to the Internet. You can verify this by logging into the Web UI on the USG.

1. If applicable, make sure that the ISP provided modem/router is set to bridged mode.

2. Connect your workstation (directly or through a network switch) to the LAN1 port on the USG.

3. The USG uses the 192.168.1.1 IP address by default and runs a DHCP server. This allows your devices to easily connect to the USG.

GUI: Access the Web UI on the USG.

4. Open a web browser on your workstation and navigate to the https://192.168.1.1 IP address.

5. If you are unable to connect to the device, then verify if your workstation has obtained an IP address from the USG. You can optionally restart your workstation or renew the DHCP lease manually to obtain a new IP address:

  windows.png  Windows Client

Open a Command Shell (CMD) or PowerShell window and run the following command:

ipconfig /renew


Run the command below to verify if an IP address was obtained from the USG.

ipconfig /all


Alternatively, you can disable and re-enable the Ethernet adapter in the following section:
Settings > Network & Internet > Status > Change Adapter Options

 macos.png  macOS client

Navigate to the advanced network settings for the Ethernet adapter:
System Preferences > Networks > Ethernet Adapter > Advanced

Select the TCP/IP tab and then click on the Renew DHCP Lease option. Here you can also verify if an IP address was obtained from the USG.

6. Log in using the default credentials:

Username: ubnt
Password: ubnt

7. The following banner is shown if the USG has Internet connectivity:

usg-internet.png

8. The following banner is shown if the USG does not have Internet connectivity:

usg-no-internet.png

9. If the USG does not have Internet connectivity, either of the following options can be the cause:

 tools.png  Possible Cause #1 - ISP provided modem/router is not successfully set to bridged mode.

Try restarting the ISP provided modem/router and wait for the device to fully boot. You can also try resetting the ISP modem/router to factory defaults and reconfigure the bridged mode setup. If this does not fix the issue, then consider reaching out to your ISP for more information or to obtain setup documentation/assistance.

 lan.png  Possible Cause #2 - ISP provided DHCP lease is still assigned to previously connected modem/router.

In this case, the ISP has assigned the DHCP lease to the previously connected modem/router and does not reassign it until the next renew cycle. Try restarting the ISP provided modem/router. If this does not fix the issue, then consider reaching out to your ISP to clear and renew the previously assigned lease. Another option is to simply wait until the lease is automatically renewed.

 lock.png  Possible Cause #3 - ISP has locked the Internet access to the previously connected device or router.

In this case, the ISP has locked the Internet access to the MAC address used by the previous device. For example, the old router that was previously connected or the client workstation that was used earlier to test the Internet connection.

This is a common scenario when using Verizon/Frontier FiOS. Consider reaching out to your ISP to clear the previous MAC address entries so that the USG is able to connect.

 settings.png  Possible Cause #4 - ISP connection type does not match the settings configured on the USG. 

In this case, the ISP uses a different connection type such as PPPoE or static IP assignments instead of DHCP for the WAN Settings. The USG is configured as a DHCP client on the WAN interface by default, however it is possible to manually change this to PPPoE or static. 


Another possibility is that the ISP requires a VLAN to be configured on the WAN interface. It is possible to manually add a VLAN on the USG as well. The different WAN Settings can all be configured from the USG Web UI in the Settings > Configuration section.

If this does not fix the issue, then consider reaching out to your ISP to verify if the settings (PPPoE credentials, VLAN or static IP address) you are configuring match the ones in their records.

 support.png  Different Cause - Issue is not caused by any of the above.

If the issue persists after trying the steps above, then consider reaching out to your ISP for troubleshooting assistance. There may be an issue affecting your Internet connection that is not related to the USG.

10. Depending on the settings used by your ISP, optionally change the WAN Settings from DHCP to PPPoE or static. 

11. Navigate to the Settings > Configuration > WAN Settings section:

usg-settings.png

11. In this section, you can also change the LAN Settings and optionally manually add the Inform URL of the UniFi Controller if you are experiencing issues adopting the device.

Upgrading the USG Firmware Before Adoption

The steps below demonstrate how to manually upgrade firmware on the USG. Alternatively, the USG can first be adopted and upgraded using the UniFi Controller afterwards.

Upgrading using the Internet
Local Offline Upgrade

It is possible to directly upgrade the USG firmware using the Ubiquiti download servers if the USG has connectivity to the Internet (verify this in the section above). To do so, it is necessary to access the device using SSH.

NOTE: See the How to Establish a Connection Using SSH article for more information on how to connect to the USG using SSH.

1. Navigate to the UniFi R&S Download section and locate the latest firmware image for the USG model that you are using. 

2. In case of the USG, navigate to the UniFi Switching & Routing > UniFi Security Gateway > USG section.

3. Click on the Download File  download.png  button to open the firmware download page.

4. Accept the EULA when prompted and copy the firmware URL using the Copy URL button.

5. Connect your workstation (directly or through a network switch) to the LAN1 port on the USG.

CLI: Access the Command Line Interface on the USG using SSH.

6. Open a SSH session using your favorite SSH/Telnet client program (for example PuTTY or the macOS/Linux Terminal).

NOTE: The default IP address is 192.168.1.1 and the credentials are ubnt/ubnt. Accept the SSH security alert if prompted.

7. Verify if you have Internet connectivity on the USG by pinging a public hostname. See the section above if the ping fails.

sudo ping www.ui.com -c 3

8. Upgrade the firmware using the command below and the previously copied firmware URL, for example:

upgrade https://dl.ui.com/unifi/firmware/UGW3/4.4.50.5272448/UGW3.v4.4.50.5272448.tar

The image below shows an example of the process:

usg-upgrade-https.gif

9. Wait for the firmware upgrade process to complete, during which the device will automatically reboot.

Follow the steps below if the USG is unable to access the Internet, or there is another reason as to why the offline upgrade is preferred. Like the Internet upgrade steps, it is necessary to access the device using SSH.

NOTE: See the How to Establish a Connection Using SSH article for more information on how to connect to the USG using SSH.

1. Navigate to the UniFi R&S Download section and locate the latest firmware image for the USG model that you are using. 

2. In case of the USG, navigate to the UniFi Switching & Routing > UniFi Security Gateway > USG section.

3. Click on the Download File  download.png  button to open the firmware download page.

4. Accept the EULA when prompted and download the firmware to your local workstation using the Download File button.

5. Rename the downloaded firmware file to the name below (leave the .tar extension intact).

upgrade.tar

6. Connect your workstation (directly or through a network switch) to the LAN1 port on the USG.

7. Use your favorite SCP client program (for example WinSCP or the macOS/Linux Terminal) to connect to the USG and upload the firmware. 

NOTE: The default IP address is 192.168.1.1 and the credentials are ubnt/ubnt. Accept the SSH security alert if prompted.

8. Upload the upgrade.tar file to the /tmp/ directory. Using the macOS/Linux Terminal SCP command for example:

scp ./upgrade.tar ubnt@192.168.1.1:/tmp/
CLI: Access the Command Line Interface on the USG using SSH.

9. Open a separate SSH session using your favorite SSH/Telnet client program (for example PuTTY or the macOS/Linux Terminal).

NOTE: The default IP address is 192.168.1.1 and the credentials are ubnt/ubnt. Accept the SSH security alert if prompted.

10. Verify that the firmware image file is successfully uploaded to the /tmp/ directory:

ls -l /tmp/

11. Upgrade the firmware using the command below and the previously uploaded firmware image:

sudo syswrapper.sh upgrade /tmp/upgrade.tar

The image below shows an example of the process:

usg-upgrade-offline.gif

12. Wait for the firmware upgrade process to complete, during which the device will automatically reboot.

Configuring the LAN Network Manually

The USG is configured with the 192.168.1.1 IP address by default and runs a DHCP server for the same range. If your current setup uses a different LAN IP range, and you are already using the UniFi Controller, then it necessary to manually change the LAN IP address on the USG. You can do this by logging into the Web UI on the USG.

1. Connect your workstation (directly or through a network switch) to the LAN1 port on the USG.

2. The USG uses the 192.168.1.1 IP address by default and runs a DHCP server. This allows your devices to easily connect to the USG.

GUI: Access the Web UI on the USG.

3. Open a web browser on your workstation and navigate to the https://192.168.1.1 IP address.

4. If you are unable to connect to the device, then verify if your workstation has obtained an IP address from the USG, see the section above.

5. Log in using the default credentials.

Username: ubnt
Password: ubnt

6. Navigate to the Settings > Configuration > LAN Settings section and change the IP address, subnet mask and DHCP range:

usg-settings.png

7. After applying the new LAN settings, you will lose access to the USG because the IP address has changed. 

8. Verify if the UniFi Controller is able to discover and adopt the USG on the newly assigned address. It is also possible to manually add the Inform URL of the UniFi Controller if you are experiencing issues adopting the device.

9. If you are not able to access or find the USG, then verify if your workstation has obtained a new DHCP IP address using the section above.

Pre-Configuring the WAN and LAN Networks in the UniFi Controller

If you are already using the UniFi Controller in your current setup, then you can pre-configure the WAN and LAN networks on the controller. After the USG is adopted, the new settings will be automatically pushed to the device. You can do this by logging into the UniFi Controller Web UI. 

GUI: Access the UniFi Controller Web Portal.

Change the WAN and LAN settings by following the steps below:

Changing the Controller WAN Network
Changing the Controller LAN Network

1. When using the New Web UI, navigate to the  settings.png  Settings > Internet > WAN Networks > WAN > Edit section to change the WAN network.

2. Fill in the necessary information, for example the IPv4 Connection Type:

wan-network.png

NOTE: The New Web UI is available starting from the v5.12.22 UniFi Controller release. 

When using the Classic Web UI, navigate to the  settings.png  Settings > Networks > WAN > Edit section instead.

1. When using the New Web UI, navigate to the  settings.png  Settings > Networks > Local Networks > LAN > Edit section to change the LAN network.

2. Fill in the necessary information, for example the DHCP Range and Gateway IP / Subnet:

lan-network.png

NOTE: The New Web UI is available starting from the v5.12.22 UniFi Controller release. 

When using the Classic Web UI, navigate to the  settings.png  Settings > Networks > LAN > Edit section instead.

Adopting the UniFi Security Gateway

ATTENTION: If you manually changed the WAN and LAN settings on the USG, then your custom changes will be overwritten by the UniFi controller after adoption. To prevent this, pre-configure the WAN and LAN networks in the UniFi Controller to match the ones manually configured using the Web UI on the USG. 

If you do not pre-configure the networks, the defaults are used which is 192.168.1.1/24 for the LAN and DHCP for the WAN. 

Assuming the USG and UniFi Controller are able to communicate with each other, the USG can be adopted. You can do this by logging into the UniFi Controller Web UI.

GUI: Access the UniFi Controller Web Portal.

After logging into the UniFi Controller, navigate to the  devices.png  Devices section and verify if the USG is displayed.

USG is Displayed
USG is not Displayed

1. If the USG is displayed, then adopt the device from the  devices.png  Devices section.

2. You can further customize the USG interface and network settings after adopting the device. See the section above for more information on how to configure the WAN and LAN networks on the UniFi Controller.

3. For further setup steps, visit the UniFi Routing & Switching section of the Ubiquiti Help Center for more articles focused on the USG.

usg-interfaces.png

1. Try accessing the USG using SSH and verify if you can ping the IP address of the UniFi Controller.

CLI: Access the Command Line Interface on the USG using SSH.

2. Open a SSH session using your favorite SSH/Telnet client program (for example PuTTY or the macOS/Linux Terminal).

NOTE: The default IP address is 192.168.1.1 and the credentials are ubnt/ubnt. Accept the SSH security alert if prompted.

3. Verify if you can ping the IP address or hostname of the UniFi Controller from the USG. For example, if the UniFi Controller is using the 192.168.1.100 IP address:

sudo ping -c 3 192.168.1.100
sudo ping -c 3 unifi

4. Access the logs on the USG to determine why the adoption process is failing:

sudo tail -n 60 /var/log/messages
NOTE: See the How to Establish a Connection Using SSH article for more information on how to connect to the USG using SSH.

The image below shows an example of the process:

usg-ping-logs.gif 

5. If you can ping, but not adopt the device, then it is possible that the port required for adoption (TCP port 8080) is not open on the server. You can verify this by using the telnet command on the USG:

telnet 192.168.1.100 8080

6. You will see a blank/empty prompt if the port is open. You can then use the echo command to display some of the information, after which the connection is closed.

ubnt@ubnt:~$ telnet 192.168.1.100 8080
echo
HTTP/1.1 400
Content-Type: text/html;charset=utf-8
Content-Language: en
Content-Length: 435
Date: Fri, 12 Jun 2020 07:20:10 GMT
Connection: close

7. If the port is not open (closed), you will see a Connection refused message:

ubnt@ubnt:~$ telnet 192.168.1.100 8080
telnet: can't connect to remote host (192.168.1.100): Connection refused

8. If the above is shown, then investigate whether the firewall settings on the server are blocking the port and allow it through the firewall.

9. Have a look at our Troubleshooting Device Adoption article if the adoption issue persists. 

Troubleshooting Internet Connectivity Issues

If the USG does not have Internet connectivity, either of the following options can be the cause:

 tools.png  Possible Cause #1 - ISP provided modem/router is not successfully set to bridged mode.

Try restarting the ISP provided modem/router and wait for the device to fully boot. You can also try resetting the ISP modem/router to factory defaults and reconfigure the bridged mode setup. If this does not fix the issue, then consider reaching out to your ISP for more information or to obtain setup documentation/assistance.

 lan.png  Possible Cause #2 - ISP provided DHCP lease is still assigned to previously connected modem/router.

In this case, the ISP has assigned the DHCP lease to the previously connected modem/router and does not reassign it until the next renew cycle. Try restarting the ISP provided modem/router. If this does not fix the issue, then consider reaching out to your ISP to clear and renew the previously assigned lease. Another option is to simply wait until the lease is automatically renewed.

 lock.png  Possible Cause #3 - ISP has locked the Internet access to the previously connected device or router.

In this case, the ISP has locked the Internet access to the MAC address used by the previous device. For example, the old router that was previously connected or the client workstation that was used earlier to test the Internet connection.

This is a common scenario when using Verizon/Frontier FiOS. Consider reaching out to your ISP to clear the previous MAC address entries so that the USG is able to connect.

 settings.png  Possible Cause #4 - ISP connection type does not match the settings configured on the USG. 

In this case, the ISP uses a different connection type such as PPPoE or static IP assignments instead of DHCP for the WAN Settings. The USG is configured as a DHCP client on the WAN interface by default, however it is possible to manually change this to PPPoE or static. 


Another possibility is that the ISP requires a VLAN to be configured on the WAN interface. It is possible to manually add a VLAN on the USG as well. The different WAN Settings can all be configured from the USG Web UI in the Settings > Configuration section.

If this does not fix the issue, then consider reaching out to your ISP to verify if the settings (PPPoE credentials, VLAN or static IP address) you are configuring match the ones in their records.

 support.png  Different Cause - Issue is not caused by any of the above.

If the issue persists after trying the steps above, then consider reaching out to your ISP for troubleshooting assistance. There may be an issue affecting your Internet connection that is not related to the USG.

See the section above for more information on how to verify and configure the WAN settings on the USG.

Related Articles

UniFi - Troubleshooting Device Adoption

Intro to Networking - How to Establish a Connection Using SSH

UniFi - Upgrade the Firmware of a UniFi Device

Was this article helpful?
38 out of 100 found this helpful
Can't find what you're looking for?
Visit our worldwide community of Ubiquiti experts for more answers
Visit the Ubiquiti Community