UniFi - USG/UDM: Port Forwarding Configuration and Troubleshooting


This article describes how to configure port forwards on a UniFi Security Gateway (USG), and how to troubleshoot them if not working as desired. It is applicable to all UniFi Security Gateway and UniFi Dream Machine (UDM and UDM-Pro) models. Port forwards allow you to redirect traffic destined to one or more ports on your USG's WAN IP to an internal host, most commonly to make servers accessible from the Internet.

Port forwards are configured in the Routing & Firewall section of the UniFi Network Controller in versions 5.6.29 and above.
Before you begin, and to make these examples easier to follow, please note that the network depicted in the examples has a USG with WAN plugged into an Internet connection with IP of, and LAN with an IP of plugged into a UniFi switch. On the LAN there is a Linux server at, which is running web and SSH servers.

Table of Contents

  1. Steps: How to Create a Port Forwarding Rule
  2. Firewall Rules & Port Forwards
    1. SSH to USG WAN
    2. Port Forwards on WAN2 
  3. Port Forward Troubleshooting
  4. Related Articles

Steps: How to Create a Port Forwarding Rule

Back to Top

1. In the UniFi Controller navigate to Settings > Routing & Firewall > Port Forwarding tab > And click on Create New Port Forward Rule to configure your first port forward.

2. The following fields are available for configuration in port forwards. Fill them out according to your needs and click Save. The configuration will then provision to the USG, and the port forward will be active once provisioning has completed. Make sure to test your port forwards from outside your network on the Internet.

  • Name: Descriptive name of the port forward for reference purposes only. No functional impact.
  • From: This field specifies the source addresses that are allowed through the port forward. If you need the service to be reachable from anywhere on the Internet, you must select “Anywhere” here. In cases where you can limit the source IP or network that can use the port forward, it is best to do so, as it greatly limits the security exposure of your network. To restrict source IPs allowed through the port forward, select “Limited”, and in the text box to its right, enter an IP address (e.g. or IP subnet with CIDR mask (e.g. Only the specified IP or network will be allowed through the port forward.
NOTE: If you need to permit multiple source IP addresses or subnets, you can add multiple port forwards, with a different “From” IP or subnet on each.
  • Port: The Port field specifies the external port to be forwarded. This port on your WAN IP will be forwarded.
  • Forward IP: This field specifies the internal IP address to use for the destination of this port forward.
  • Forward Port: The Forward Port specifies the internal port to where the traffic is forwarded.
  • Protocol: Here you can select TCP, UDP or Both (TCP and UDP) as the protocol forwarded. Most services use TCP. Unless both TCP and UDP are required, you should specify one or the other rather than Both.
  • Logs: If Enable logging is checked, the USG will log the traffic that matches the port forward in syslog.

3. As an example, we'll create two port forwarding rules. 

Example Web Server Port Forward

Now that you are familiar with each field in the Port Forward tab, let's create some sample Port Forwards. For the first example, we're opening HTTP (TCP port 80) to the Linux server at

Example SSH Port Forward

For this example, we'll forward external port 2222 to the Linux server’s SSH on port 22. SSH is a common example of a service that people often configure externally on a different port than internally, mostly to avoid the bulk of brute force attacks. There is no real security in doing so, as any system susceptible to an SSH brute force attack will be found and compromised regardless of port, but there is value in considerably reducing log spam from authentication failures, and not wasting system resources on processing the attempts. It’s preferable to limit source IPs or networks on such forwarded traffic, but if you have a requirement to leave SSH open to the Internet, using an alternate external port doesn’t hurt.

Once again, click on Save. Once provisioning of the USG is complete, the Linux server’s SSH service will be reachable from the Internet on port 2222.

4. Now the Port Forwarding tab will display the two configured entries we just created. You can click the pencil to the right of the entry to edit it, or the trashcan to delete it.

Firewall Rules & Port Forwards

Back to Top

In Settings > Routing & Firewall > Firewall tab the WAN IN firewall rules display the rules added to pass the traffic associated with your port forwards.

These rules are not editable because they’re associated with the port forwards, and their configuration specifics all come from the port forwards. You edit or delete the port forwards to edit or delete those rules.


If the goal is to SSH to the USG's IP address itself over the WAN, a rule must be created on WAN LOCAL. Settings > Routing & Firewall > Firewall tab > WAN LOCAL. This is not considered a port forward. To create a rule such as this follow the steps below.

2. Select the following:1. Click Create New Rule while on the WAN LOCAL page.

  • Action: Accept
  • Protocol: TCP
  • Destination Port group > Create port group
    • name: SSH
    • port: 22

3. Leave all else at defaults, and press Save.

Port Forwards on WAN2

Port forwards are currently only provisioned to WAN1. If you have a multi-wan configuration, port forwards will need to be manually added to WAN2, as well as the firewall rules to allow those port forwards. This will require SSH or console access to the USG. Below is an example of a WAN2 port forward, where the WAN2 address is on eth3, and the forwarded port 22 to internal address

1. Create a firewall rule on WAN_IN to allow the port forward.

2. Press Create New Rule while on the WAN IN page

3. Select the following:

  • Action: Accept
  • Protocol: TCP
  • Destination Port group > Create port group
    • name: SSH
    • port: 22

4. Leave all else at defaults, and press Save.

5. SSH to the USG and type the following:

set service nat rule 4000 description "WAN2 tcp 22"
set service nat rule 4000 destination address
set service nat rule 4000 destination port 22
set service nat rule 4000 inbound-interface eth3
set service nat rule 4000 inside-address address
set service nat rule 4000 inside-address port 22
set service nat rule 4000 protocol tcp
set service nat rule 4000 type destination

5. The port forward should now work on WAN2 when tested externally.

  • The NAT rule can be anywhere between 1-4999, with the lower number taking priority over the rules following it. You can also type the "?" key at any time in the command to bring up a list of available options you can type in.
  • The changes made in SSH are not persistent across any provisions by the controller or reboots of the USG itself. A config.gateway.json file has to be created in order to make these changes permanent - see here.
  • If you're testing the port forward internally, which is sourced from a client on a LAN or VLAN behind the same USG, hairpin NAT is needed. To add this, follow step 4 again, but change the "inbound-interface" to the interface of the LAN or VLAN you're sourcing the traffic from. If the source address and inside-address (target of the port forward) are on the same subnet, an additional SNAT (Source NAT) masquerade rule will need to be added to avoid asymmetric routing.
  • If multiple ports are used in a single rule, "inside-address port" cannot/should not be used and/or needed as traffic will be forwarded to same ports as it is destined to on WAN interface. If it is desired to forward multiple ports to a host then separate rules should be created.

Port Forward Troubleshooting

Back to Top

There are a number of potential reasons for port forwards not working after they’re configured, most of which are outside of the USG itself, but the USG provides powerful tools to help pinpoint the cause of the problem.

This section goes through the troubleshooting process when your port forwards aren’t working as expected.

1. Verify Configuration and Test Methodology

First, take a close look at your configured port forwards. A subtle typo in an IP or port number has tripped up all of us on occasion. The UniFi Controller won’t allow invalid characters, so no need to look closely for white spaces or anything along those lines. Just verify the IP and port is correctly entered.

When testing your port forwards, make sure to do so from the Internet. A cell phone with WiFi disabled is a good option if nothing else is readily available.

The next sections go through the process of troubleshooting from the WAN and LAN points of reference.

2. Check for traffic on WAN

The first step in troubleshooting port forwards is ensuring the traffic is reaching your WAN interface. If the traffic isn’t reaching the USG’s WAN, it can’t be forwarded. Packet capturing with tcpdump is the preferred method of troubleshooting, as seeing the traffic present or not present on the network definitively determines where the problem exists. The WAN interface on USG is eth0, and eth2 on USG Pro. The examples in this article refer to a USG, so we will use eth0. If you're using a USG Pro, substitute it for eth2.

Without some filtering, the output of tcpdump will be difficult to decipher. A simple filter for destination port often suffices, though if it’s a port shared by other active traffic on the network, that alone is inadequate. The HTTP port forward for instance requires tighter filtering to eliminate unrelated noise. In our use case here, we will filter on destination host (the USG WAN IP) and destination port 80 using the filter dst host and dst port 80.

SSH into the USG to start. Then run the following tcpdump to look for the incoming HTTP requests:

sudo tcpdump -ni eth0 dst host and dst port 80
tcpdump: verbose output suppressed, use -v or -vv for full protocol decode
listening on eth0, link-type EN10MB (Ethernet), capture size 262144 bytes
17:44:00.904533 IP > Flags [S], seq 2179876751, win 29200, options [mss 1460,sackOK,TS val 390060839 ecr 0,nop,wscale 6], length 0

The output that appears above shows a connection attempt to port 80 on USG’s WAN IP, sourced from a remote host on the Internet with IP, using source port 51514 (source ports are random from the ephemeral port range). The “Flags [S]” part tells us it’s a SYN packet, the first packet of an attempted TCP handshake. Because we see this request on the WAN, we know it’s reaching the USG. If nothing were to show up in that capture while attempting to reach, then we know something upstream of USG is preventing the traffic from reaching it. See the “Traffic not reaching WAN” section below for troubleshooting guidance.

If you do see traffic coming into WAN, then next is to verify whether it’s leaving LAN.

3. Check for traffic on LAN

Now that you have verified the traffic is arriving on WAN, your next step would be to check LAN to see if the traffic is egressing the LAN interface. In this example we’re using a USG, where the LAN port is eth1. If using USG Pro, the LAN port is eth0, so substitute accordingly in tcpdump.

Here we will filter on the web server’s internal IP and port 80:

cmb@usg1:~$ sudo tcpdump -ni eth1 host and port 80
tcpdump: verbose output suppressed, use -v or -vv for full protocol decode
listening on eth1, link-type EN10MB (Ethernet), capture size 262144 bytes
18:00:38.268095 IP > Flags [S], seq 1565978093, win 29200, options [mss 1460,sackOK,TS val 390310233 ecr 0,nop,wscale 6], length 0
18:00:38.268351 IP > Flags [R.], seq 0, ack 1565978094, win 0, length 0

We see the SYN just like in the WAN capture. Its destination IP has been translated to the internal server IP Seeing the presence of that translated SYN leaving the LAN NIC means the port forward is working. The packet shown in response, coming back from the server, points to what the problem is in this case. Flags [R.] means the server sent a RST ACK in response, which is TCP’s way of telling a remote host there is nothing listening on that port. After checking the web server, the nginx service wasn’t configured to start. After starting the web server service, the tcpdump output shows several more packets in the exchange. A successful connection will look something along the lines of the following, with variance on how many lines are shown depending on the amount of data transferred:

18:06:17.151027 IP > Flags [S], seq 4065224865, win 29200, options [mss 1460,sackOK,TS val 390394972 ecr 0,nop,wscale 6], length 0
18:06:17.151269 IP > Flags [S.], seq 2746330992, ack 4065224866, win 28960, options [mss 1460,sackOK,TS val 232937488 ecr 390394972,nop,wscale 7], length 0
18:06:17.152707 IP > Flags [.], ack 1, win 457, options [nop,nop,TS val 390394972 ecr 232937488], length 0
18:06:17.155836 IP > Flags [.], ack 110, win 227, options [nop,nop,TS val 232937488 ecr 390394973], length 0
18:06:17.157676 IP > Flags [F.], seq 110, ack 1105, win 491, options [nop,nop,TS val 390394974 ecr 232937488], length 0
18:06:17.157904 IP > Flags [F.], seq 1105, ack 111, win 227, options [nop,nop,TS val 232937488 ecr 390394974], length 0

The most common failure is the LAN host not replying to the forwarded traffic. Where the tcpdump output shows SYNs being sent out to the LAN host, but nothing coming back in response, the issue is something on the LAN host itself. See No reply from LAN host below for troubleshooting guidance. The tcpdump output will look similar to the following:

18:09:46.403313 IP > Flags [S], seq 1697746705, win 29200, options [mss 1460,sackOK,TS val 390447296 ecr 0,nop,wscale 6], length 0
18:09:47.400988 IP > Flags [S], seq 1697746705, win 29200, options [mss 1460,sackOK,TS val 390447546 ecr 0,nop,wscale 6], length 0
18:09:49.403930 IP > Flags [S], seq 1697746705, win 29200, options [mss 1460,sackOK,TS val 390448047 ecr 0,nop,wscale 6], length 0

4. Traffic not reaching WAN 

If the traffic isn’t showing up on your USG WAN interface, something upstream of the USG is blocking it. Often this is a firewall or other packet filter of sorts built into your modem, or on some other upstream firewall or router. Refer to your modem’s manual to find out more about its configuration in that regard.

The other common circumstance is your ISP blocking the port you’re trying to use. Business class Internet service generally does not have any ports blocked, however, it’s relatively common for residential service to have the ports of common servers (25, 80, 443, etc.) blocked.

5. No reply from LAN host

When you see traffic leaving LAN going to the appropriate destination host like shown in the final tcpdump output shown above, with three SYNs in a row sent to port 80, the host isn’t replying to the traffic for some reason. Often this is a host firewall blocking the traffic on that system. The other common cause is the LAN host missing a default gateway, or having its default gateway configured pointing to a different system. In order to reply back via USG to make the port forwards work, the LAN host’s default gateway must point to USG’s internal IP.

Related Articles

Back to Top

Intro to Networking - How to Establish a Connection Using SSH

We're sorry to hear that!