UniFi - UDM/USG: WAN Load Balancing and Failover – Ubiquiti Support and Help Center

The WAN Load Balancing feature allows you to connect the UDM/USG to two ISPs at the same time. The models mentioned on this list support the following features:

USG: Weighted Load Balancing and Failover
UDM Pro: Failover
UDM: has only a single WAN uplink port so Failover is supported only when using U-LTE

This article shows how to configure and troubleshoot the WAN Load Balancing or Failover features.

Configuring WAN Load Balancing on the UDM/USG
Troubleshooting the WAN Load Balancing on the UDM
Troubleshooting the WAN Load Balancing on the USG
Frequently Asked Questions (FAQ)

Note: For more information about how the WAN Load Balancing and Failover works, see the Frequently asked questions section.

Configuring WAN Load Balancing on the UDM/USG

The diagram below shows an example topology of a UniFi network that uses a UniFi Dream Machine Pro (UDM Pro) that connects to two different ISPs using the RJ45 and the SFP+ WAN interfaces.

To configure WAN Load Balancing on the UDM/USG, follow the steps below to configure the Load Balancing feature on the UDM/USG models on the UniFi Network web application:

1. Navigate to the Settings > Internet section.

2. Create the WAN2 network if it is not listed or click on the existing network to edit it.

3. Click Advanced and enter the details as follows:

Network Group: WAN2
IPv4 Connection Type: (dependent on ISP)
IPv6 Connection Types: (dependent on ISP)
DNS Server: Optional
USE VLAN ID: Optional (dependent on ISP)
Load Balancing: Failover Only / Weighted LB
Load Balancing Weight (Weighted LB only): 50 or customized
Enable Smart Queues: Optional

Note: The UDM Pro currently supports only Failover mode.

4. Apply the settings.

5. Navigate to the UniFi Devices and click on your UDM/USG. On the Properties panel, go to Ports > WAN Ports and click on Configure Interfaces section to assign the WAN networks.

Note: To switch the WAN Networks, first change the Port WAN1 Network from WAN to Disabled, then change the Port WAN2 Network from WAN2 to WAN. See the Configuring Port Remapping article for more information.

6. Navigate to the Devices > UDM/USG > Details section to verify that the WAN interfaces are up and using an IP address.

Note: If the WAN interface is showing down/disconnected or does not have an IP address assigned, then it is possible that your WAN settings do not match the ones provided by your ISP.

7. (Optional) Customize the echo server in the Devices > UDM/USG > Config > Advanced > Echo Server section.

Echo Server: ping.ubnt.com or Custom

1. Navigate to the Settings > Networks section.

2. Create the WAN2 network if it is not listed or edit the existing network.

Name: WAN2
Purpose: WAN
Interface: WAN2
IPv4 Connection Type: Dependent on ISP
IPv6 Connection Types: Dependent on ISP
DNS Server: Optional
USE VLAN ID: Optional / Dependent on ISP
Load Balancing: Failover Only / Weighted LB
Load Balancing Weight (Weighted LB only): 50 or customized
Report Interface Events: Checked
Enable Smart Queues: Optional

3. Apply the settings.

ATTENTION: The UDM Pro currently only supports the Failover load balancing mode.

4. Navigate to the Devices > UDM/USG > Ports > WAN > Configure Interfaces section to assign the WAN networks.

5. Navigate to the Devices > UDM/USG > Details section to verify that the WAN interfaces are up and using an IP address.

NOTE: If the WAN interface is showing down/disconnected or does not have an IP address assigned, then it is possible that your WAN settings do not match the ones provided by your ISP.

6. Customize the echo server in the Devices > UDM/USG > Config > Advanced > Echo Server section.

Echo Server: ping.ubnt.com or Custom

Troubleshooting the WAN Load Balancing on the UDM

In order to proceed through the troubleshooting steps below, you will need to make sure that SSH access is enabled on the UDM Pro. For more guidance on accessing your UDM Pro via SSH, see our UniFi - Accounts and Passwords for Ubiquiti, UniFi OS and UniFi Devices article: how to access a UniFi OS Console via SSH section.

To troubleshoot the WAN Load Balancing on the UDM:

1. Verify if both WAN interfaces are up and are using an IP address in the Devices > UDM > Details section:

2. If the WAN interface is showing down/disconnected, then a physical issue may be the cause:

Try swapping out the physical cables, making sure to use cables of a different brand/manufacturer and length.
On the SFP+ WAN port, you can also try swapping out the SFP(+) module or DAC cable.
In case the speed/duplex is forced on the neighboring device, replicate the settings in the Devices > UDM > Ports > WAN > Configure Interfaces section.

3. If the WAN interface is up but does not have an IP address assigned, then there is possibly an issue with the ISP uplink or the Internet connection type does not match the ISP settings.

If the Internet connection type is PPPoE or static, then you will have likely received the required information from the ISP.
If there is no information not provided, then the connection type is likely DHCP.
If there is no information available, then it is recommended to contact the ISP to obtain the documentation.

4. If the WAN interfaces are connected/up and assigned an IP address, verify if there are any events logged in the Alerts tab.

The UDM Pro will log a transition event in case the WAN interface state changes.
The event will list the interface that changed the state, and which state it entered (failover / active).
Note that on the UDM Pro, interface eth8 is Port 9 (WAN1) and interface eth9 is Port 10 (WAN2).
The UDM Pro continuously sends ICMPv4 reachability requests to ping.ubnt.com to test the reachability of the WAN connection, see the FAQ section above.

5. If there are many state transitions logged in the Alerts tab, then it is possible that ping.ubnt.com is not reachable by the UDM Pro.

CLI: Access the Command Line Interface on the UDM Pro using SSH.

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

1. Download PuTTY and open the putty.exe executable file.

2. To connect to the USG that is using the default 192.168.1.1 IP address, fill in the below settings and select Open.

Host Name (or IP address): 192.168.1.1
Port: 22
Connection type: SSH

3. Accept the SSH security alert if prompted.

4. Login using the root user account and your previously configured password:

Username: root
Password: <password>

1. Open the macOS Terminal by searching for Terminal in the Launcher or by navigating to the Finder > Applications > Utilities section.

2. Use the ssh command and specify the username of the UDM/UDM Pro followed by the @ symbol and the IP address.

ssh <username>@<ip-address>

3. To connect to the UDM/UDM Pro that is using the default 192.168.1.1 IP address and root username, run:

ssh root@192.168.1.1

4. Accept the SSH security alert if prompted.

5. Enter your previously configured password to log in:

Username: root
Password: <password>

7. After logging in, try pinging the ping.ubnt.com hostname from the command line.

ping ping.ubnt.com -c 3

In case the ping fails, verify that the hostname can be resolved by the UDM Pro.

nslookup ping.ubnt.com

WAN Load Balancing log messages can also be seen from the CLI by using the below command.

cat /var/log/messages | grep wanFailover

8. If there are any issues resolving the name, then you can try customizing the echo server in the Devices > UDM > Config > Advanced > Echo Server section.

Echo Server: IP address or hostname

9. Afterwards, verify if you can ping the custom hostname or IP address from the UDM Pro.

10. If the issue persists, then verify the configured DNS servers and test if you can ping the IP address of the ISP gateway router/modem.

Troubleshooting the WAN Load Balancing on the USG

Before following the steps below, make sure that you are able to connect to the USG using SSH. First, enable SSH Authentication in the New Web UI Settings > Network Settings > Device Authentication section of the Network application and specify your username and password.

Enable SSH Authentication: Checked
SSH Username: <your-username>
SSH Password: <your-password>

Refer to the following troubleshooting steps:

1. Verify if both WAN interfaces are up and are using an IP address in the Devices > USG > Details section:

2. If the WAN interface is showing down/disconnected, then a physical issue may be the cause:

Try swapping out the physical cables, making sure to use cables of a different brand/manufacturer and length.
When using the SFP port on the USG-Pro, you can also try swapping out the SFP module or DAC cable.
In case the speed/duplex is forced on the neighboring device, replicate the settings in the Devices > USG > Ports > WAN > Configure Interfaces section.

3. If the WAN interface is up but does not have an IP address assigned, then there is possibly an issue with the ISP uplink or the Internet connection type does not match the ISP settings.

If the Internet connection type is PPPoE or static, then you will have likely received the required information from the ISP.
If there is no information not provided, then the connection type is likely DHCP.
If there is no information available, then it is recommended to contact the ISP to obtain the documentation.

4. If the WAN interfaces are connected/up and assigned an IP address, verify if there are any events logged in the Alerts tab.

The USG will log a transition event in case the WAN interface state changes.
The event will list the interface that changed the state, and which state it entered (failover / active).
Note that on the USG, interface eth0 is Port 1 (WAN) and interface eth2 is Port 3 (WAN2). On the USG-Pro, interface eth2 is Port 3 (WAN1) and interface eth3 is Port 4 (WAN2).
The USG continuously sends ICMPv4 reachability requests to ping.ubnt.com to test the reachability of the WAN connection, see the FAQ section above.

5. If there are many state transitions logged in the Alerts tab, then it is possible that ping.ubnt.com is not reachable by 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).

1. Download PuTTY and open the putty.exe executable file.

2. To connect to the USG that is using the default 192.168.1.1 IP address, fill in the below settings and select Open.

Host Name (or IP address): 192.168.1.1
Port: 22
Connection type: SSH

3. Accept the SSH security alert if prompted.

4. Login using your previously configured username and password:

Username: <username>
Password: <password>

ssh <username>@<ip-address>

3. To connect to the USG that is using the default 192.168.1.1 IP address and unifiadmin username, run:

ssh unifiadmin@192.168.1.1

4. Accept the SSH security alert if prompted.

5. Enter your previously configured password to log in:

Username: unifiadmin
Password: <password>

7. After logging in, try pinging the ping.ubnt.com hostname from the command line.

sudo ping ping.ubnt.com -c 3

Verify the WAN Load Balancing status and ping watchdog results by using the below commands.

show load-balance status
show load-balance watchdog

unifiadmin@usg:~$ show load-balance status 
Group wan_failover
  interface   : eth2
  carrier     : up
  status      : active
  gateway     : 203.0.113.2
  route table : 201
  weight      : 100%
  flows
      WAN Out : 532563
      WAN In  : 74732
    Local Out : 523

  interface   : eth3
  carrier     : up
  status      : failover
  gateway     : 192.0.2.2
  route table : 202
  weight      : 0%
  flows
      WAN Out : 0
      WAN In  : 0
    Local Out : 0

unifiadmin@usg:~$ show load-balance watchdog 
Group wan_failover
  eth2
  status: Running 
  pings: 500
  fails: 0
  run fails: 0/3
  route drops: 0
  ping gateway: ping.ubnt.com - REACHABLE

  eth3
  status: Running 
  failover-only mode
  pings: 500
  fails: 0
  run fails: 0/3
  route drops: 0
  ping gateway: ping.ubnt.com - REACHABLE

WAN Load Balancing log messages can also be seen from the CLI by using the below command.

show log | match wlb

unifiadmin@usg:~$ show log | match wlb
wlb: wlb-wan_failover-eth2 Starting wlb watchdog on wlb-wan_failover-eth2 after 20s delay
wlb: wlb-wan_failover-eth3 Starting wlb watchdog on wlb-wan_failover-eth3 after 20s delay
wlb: group wan_failover, interface eth2 going Active

8. If there are any issues resolving the name, then you can try customizing the echo server in the Devices > USG > Config > Advanced > Echo Server section.

Echo Server: IP address or hostname

9. Afterwards, verify if you can ping the custom hostname or IP address from the USG.

10. If the issue persists, then verify the configured DNS servers and test if you can ping the IP address of the ISP gateway router/modem.

Frequently Asked Questions (FAQ)

There are two possible configuration options:

Failover The primary WAN interface is used for all outgoing traffic. The secondary (failover) WAN interface is only used if the primary connection fails.
Weighted LB Both WAN interfaces are used simultaneously for outgoing traffic. The weight ratio determines how much traffic is sent over each WAN interface based on the configured percentage. The default percentage is 50/50, meaning that each WAN interface handles 50% of the traffic.

NOTE: When using Weighted LB, the traffic will still failover to the other WAN interface in case there is an interruption. The UDM Pro currently only supports the Failover load balancing mode.

Either option uses the same mechanism to determine if the WAN interface is available and can be used to forward traffic. By default, the UDM/USG will send a ping (ICMPv4) request to ping.ubnt.com sourced from each individual WAN interface. If this ping fails, the UDM/USG determines that there is either an issue with the connection to the ISP modem/router or there is an issue further upstream in the ISP network. In this case, the UDM/USG will stop using the WAN interface to forward traffic.

In the case of an outage, the UDM/USG will continue to try and reach ping.ubnt.com and will re-enable the interface if the connection is determined to be active.

The UDM/USG continuously sends ICMPv4 reachability requests (ping) sourced from each individual WAN interface. The default destination of the request is ping.ubnt.com, but this can be customized to a different hostname or IP address.

If this ping fails, the UDM/USG determines that there is either an issue with the connection to the ISP modem/router or there is an issue further upstream in the ISP network. In this case, the UDM/USG will stop using the WAN interface to forward traffic. In the case of an outage, the UDM/USG will continue to try and reach ping.ubnt.com (or the customized IP address/hostname) and will re-enable the interface if the connection is determined to be active. The above functionality applies to both the Failover and Weighted LB options.

NOTE: Outages and WAN transition events are logged in the

Alerts tab of the Network application.

Outages and WAN transition events are logged in the Alerts tab of the Network application. It is also possible to view these messages by accessing the UDM/USG using SSH. See the section below.

UniFi - UDM/USG: Configuring Port Remapping

UniFi - UDM: How to Login to the Dream Machine using SSH

Intro to Networking - How to Establish a Connection Using SSH

UniFi Video is an obsolete product line.

UniFi - UDM/USG: WAN Load Balancing and Failover