Troubleshooting Captive Portal¶

This section contains troubleshooting tips for the most common problem with captive portal.

Authentication failures¶

Authentication failures are normally the result of users entering an incorrect username or password. In the case of RADIUS authentication, these can occur because of connectivity problems to the configured RADIUS server(s), or problems on the RADIUS server itself. Check the RADIUS server logs for indications of why access was denied, and ensure the firewall can communicate with the RADIUS server.

For local users, if the option to require the Captive Portal login privilege is enabled, ensure the users have the privilege directly or are members of a group with the privilege.

Captive Portal Does not Redirect¶

If clients are not being redirected to the portal page when attempting to browse on an interface with captive portal enabled, it’s typically one of the following causes:

DNS resolution not functioning:

Clients on the captive portal interface must either be using the DNS resolver or forwarder on pfSense® software, on the IP address of the interface where the client resides (which is the default configuration), or if using another IP address for DNS, it must be in an allowed IP address entry. If DNS fails, the browser never issues the HTTP request, hence it cannot be intercepted and redirected.

Firewall rules on the captive portal interface do not allow the initial HTTP request:

If the user is trying to browse to google.com, but HTTP connections are not allowed to google.com, the HTTP request will be blocked and hence cannot be redirected. Under Firewall > Rules, on the interface where captive portal is enabled, the traffic to be redirected must be allowed to pass. This is most commonly HTTP to any destination.

The client has an HTTPS home page:

The request must be to an HTTP site in order for the portal to redirect the client. If HTTPS is enabled for the portal, this may still work but it depends upon the client browser or operating system automatic portal detection to work.

Many modern browsers and operating systems detect portals now which makes this less of an issue.

Client is using IPv6:

Captive Portal does not currently support IPv6, so IPv6 traffic is not able to traverse the portal interface. If the interface has IPv6 configured and the client attempts to use it, it may encounter network timeouts.

Apple devices are unable to load the portal page or login¶

Certain versions of Safari on iOS do not properly handle the login form for the Captive Portal page. The most common resolution is to disable autofill for forms in Safari on iOS.

In some cases, Apple devices will not automatically prompt for a Captive Portal login or test for its presence if the wireless network uses encryption. In these cases, manually open a browser and navigate to an HTTP site to get the login redirect.

There have also been reports that on older version of macOS, a Mac would refuse to load any HTTPS sites, including an HTTPS portal, until it could load a CRL and OSCP URL for the certificate. This has been fixed in current versions of OS X.

Some users have had to add www.apple.com to their allowed hostnames so that Apple’s call to their test page succeeds.

Port Forwards Behind Portal Only Work When Target Logs In¶

This is a side effect of how the portal operates. No traffic is allowed to reach a host behind the portal unless it has been authenticated or passed through the portal. If a port forward must always work to a device behind the portal, then it must be setup to bypass the portal with either a Pass-through MAC entry (MAC Address Control) or an Allowed IP Address entry (Allowed IP Address) to allow traffic To the target.

Captive Portal Rules¶

On pfSense Plus software version 22.05 or CE version 2.7.0 or later, Captive Portal uses pf features for L2 ether processing under the hood. When having issues with the captive portal, it is possible to inspect the rules for debugging purposes.

To see rules for Captive Portal look in /tmp/rules.debug at the multiple sections starting with a comment # Captive Portal.

Anchors¶

The entries for various client and other entries for Captive Portal are kept under special anchors in the ruleset.

The easiest way to see all of the anchors and rules is to use the script pfanchordrill playback script.

# pfSsh.php playback pfanchordrill

The relevant anchors are named: cpzoneid_<id number>_<purpose> and entries are nested underneath there in subordinate anchors.

The purpose names include:

cpzoneid_<id number>_auth:: Entries for authenticated clients in a zone.
cpzoneid_<id number>_allowedhosts:: Entries for permanently allowed hosts in a zone.
cpzoneid_<id number>_passthrumac:: Entries from the pass-through MAC list.

For example the output of the pfanchordrill script includes the following entry for an authenticated captive portal client on 10.7.0.10:

cpzoneid_2_auth/10.7.0.10_32 rules/nat contents:
ether pass in quick proto 0x0800 from 5e:13:3b:ef:4d:24 l3 from 10.7.0.10 to any tag cpzoneid_2_auth dnpipe 2000
ether pass out quick proto 0x0800 to 5e:13:3b:ef:4d:24 l3 from any to 10.7.0.10 tag cpzoneid_2_auth dnpipe 2001

See /etc/inc/captiveportal.inc for information on other anchors and rules.