Deep dive into UniFi captive portal: DNS server redirects, iptables rules, walled garden, guest network setup and troubleshooting for hotspot networks.
A captive portal is a web page displayed to users connecting to guest networks or hotspot networks that require authentication. This landing page typically prompts users to enter login credentials, provide an ip address, or agree to terms of service before accessing the internet.
How does the UniFi Captive Portal work?
UniFi captive portal systems work by intercepting a user's attempt to access the internet and redirecting them to a splash page with terms and conditions or login options. The dns server handles these redirects while users remain on the guest network. Users cannot access the internet until the captive portal authentication process is completed on the hotspot networks.
When a device connects to a unifi network with portal enabled, it remains in the "Pending" state by the UniFi controller. Guest network devices cannot access the internet until authentication is complete.
For UniFi hotspot networks, the captive portal requires an active UniFi controller to function properly. However, the majority of captive portal handling occurs directly on the access point itself, reducing dependency on the central controller.
When captive portal is enabled, the UniFi controller creates iptables rules that redirect all HTTP (and optionally HTTPS) traffic from "Pending" clients directly to the access point. This ensures all web requests go through the authentication landing page first.
The system also intercepts DNS traffic from pending clients on the guest network, routing these requests to the local DNSmasq process running on the access point. This dns server control is crucial for the redirect mechanism to work properly.
Only traffic destined for ip address ranges or hostnames in the Pre-Authorization Access list can bypass these iptables rules, allowing essential services to function before authentication.
UniFi Walled garden ( a.k.a Pre-Authorization Access)
The walled garden controls for guest network access are handled by the DNSmasq dns server running on UniFi hotspot networks. Each hostname added to the Pre-Authorization Access list gets automatically added to the ipset rule guest_pre_allow.
This process "freezes" the ip address of each authorized host, allowing guest network devices to communicate freely with these specific IPs before completing authentication. The landing page restrictions don't apply to these pre-authorized services.
Since DNS queries from devices on the guest network are answered by the internal DNSmasq dns server, clients can successfully resolve and communicate with these whitelisted hosts even while in the pending authentication state.
For more advanced features beyond the built-in UniFi guest portal, consider advanced external portal solutions.
We have made an easy to use External Captive Portal solution for UniFi. Start you 15 day free trial here.
UniFi Redirector
The final piece of the captive portal UniFI system is an application called redirector, which listens on port 80 on UniFi hotspot networks. This service responds to all incoming HTTP traffic from guest network devices with a 302 redirect to the actual captive portal landing page.
When users on the guest network attempt to visit any website, the redirector intercepts these requests and sends them to the authentication splash page instead. This ensures that all web traffic is properly funneled through the captive portal before internet access is granted.
What to do when nothing works?
As you can see from above, for the captive portal UniFi to work properly, a number of things should fall into place. Now that you understand how the system works internally, you can set up your own UniFi captive portal using our comprehensive guide.
However, many times things don't work as expected! At Spotipo we use a step by step approach to debug when issues arise. We can fix 99.99% of problems by following these troubleshooting steps.
In the order:
- Ask guests to forget the network and connect again: 95% of issues are caused by captive portal UniFi detection on the client side. Have guests remove the wi fi profile and reconnect to the guest network!
- DHCP issues: Check that guests receive a proper ip address assignment from the hotspot networks
- DNS on client side: Verify clients can perform DNS resolutions through the dns server. If not, the access point may have DNS issues. Try restarting it or check if the AP firmware has known problems
- Check that your captive portal landing page is active: (Spotipo customers don't need this step - we monitor all guest ortals 24/7)
- Force captive portal UniFi detection: Open a browser on the guest network device and visit http://neverssl.com - this should trigger the splash page. If it doesn't work, check the pre-authorization list to ensure the captive portal's domain isn't accidentally whitelisted
- If all troubleshooting fails, try a UniFi controller reboot to reset the guest network configuration
Ready to upgrade your guest WiFi experience? Start your free trial with Spotipo and see the difference professional captive portals can make.
