Overview
Readers will learn how to configure and troubleshoot the WAN Load Balancing feature on the UDM-Pro and USG models.
- Applicable to the latest firmware on the UDM-Pro and USG models.
- The UniFi Dream Machine (UDM) base model only has a single WAN uplink port and does not support WAN Load Balancing.
Table of Contents
- Frequently Asked Questions (FAQ)
- Configuring WAN Load Balancing on the UDM/USG
- Troubleshooting the WAN Load Balancing on the UDM
- Troubleshooting the WAN Load Balancing on the USG
- Related Articles
Frequently Asked Questions (FAQ)
What is WAN Load Balancing?
The WAN Load Balancing feature allows you to connect the UDM/USG to two ISPs at the same time. |
How does WAN Load Balancing work?
There are two possible configuration options:
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.
|
How does the UDM/USG determine if there is an outage?
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. NOTE: Outages and WAN transition events are logged in the
![]() |
How can I determine if there has been a WAN transition (failover) or outage?
Outages and WAN transition events are logged in the |
Configuring WAN Load Balancing on the UDM/USG
The diagram below shows an example setup where the UDM-Pro is connected to two different ISPs using the RJ45 and the SFP+ WAN interfaces.
Example topology of a UniFi network that uses a UniFi Dream Machine Pro (UDM-Pro) that connects to two separate ISPs using the RJ45 and SFP+ WAN interfaces.
Follow the steps below to configure the Load Balancing feature on the UDM/USG models:
1. Navigate to the Settings > Internet > WAN Networks section.
2. Create the WAN2 network if it is not listed or edit the existing network.
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
Report Interface Events: Checked
Enable Smart Queues: Optional
3. Apply the settings.
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.
6. 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.
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.
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
Before following the steps below, make sure that SSH access is enabled on the UDM-Pro using the steps from the UniFi - UDM: How to Login to the Dream Machine using SSH help center article. Refer to the following troubleshooting steps:
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.
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. Host Name (or IP address): 192.168.1.1 3. Accept the SSH security alert if prompted. Username: root |
1. Open the macOS Terminal by searching for Terminal in the Launcher or by navigating to the Finder > Applications > Utilities section. ssh <username>@<ip-address>
ssh root@192.168.1.1
Username: root |
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 UniFi Controller 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.
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. Host Name (or IP address): 192.168.1.1
Username: <username> |
1. Open the macOS Terminal by searching for Terminal in the Launcher or by navigating to the Finder > Applications > Utilities section. ssh <username>@<ip-address>
ssh unifiadmin@192.168.1.1
Username: unifiadmin |
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.
Related Articles
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