Zone Configuration Options¶

This section describes each of the configuration options for a Captive Portal zone. Options for a zone are independent of those for other zones. For example, allowed IP address entries in a zone only affect that specific zone.

To reach this page, navigate to Services > Captive Portal and edit an existing zone from the list with fa-pencil , or click fa-plus Add to create a new zone.

Enable:

Check to enable this Captive Portal zone.

Description:

Brief text describing the purpose of the zone.

Interface:

Determines the interfaces that used by this Captive Portal zone. This cannot be a WAN interface. It can be a bridge interface so long as it is the actual bridge (e.g. bridge0) and the bridge interface has an IP address assigned.

Maximum concurrent connections:

Specifies the maximum number of concurrent connections to the portal web server per IP address. The default value is 4, which is sufficient for most environments. This limit exists to prevent a single host from exhausting all resources on the firewall, whether inadvertent or intentional.

One example where this would otherwise be a problem is a host infected with a worm. The thousands of connections issued will cause the captive portal page to be generated repeatedly if the host is not authenticated already, which would otherwise generate so much load it could leave the firewall unresponsive.

Idle timeout:

A timeout, specified in minutes, after which idle users will be disconnected by the portal. Users may log back in immediately.

Hard timeout:

A timeout, specified in minutes, after which the portal will forcefully log off users.

Tip

Set either a hard timeout, idle timeout, or both to ensure sessions are removed by the portal when users do not log off manually.

Users may log back in immediately after the hard timeout if their credentials are still valid (for local accounts, not expired, and for RADIUS authentication, user can still successfully authenticate to RADIUS).

Note

If a timeout value is set, the timeout must be less than the DHCP lease time or captive portal sessions can remain active for IP addresses that have switched to different devices. Setting the timeout lower will ensure that the portal sessions end before the lease would be reallocated to a new client.

Traffic Quota:

An amount of traffic which, when exceeded by a client, will trigger a disconnect of that client by the portal. This includes both upload and download traffic. Users may log back in immediately if their credentials are still valid

Pass-Through Credits:

These credits give devices a grace period before they must authenticate via the portal. For example, a device could connect 3 times within a day without seeing the portal page, but any more than that and they must login. By setting the hard timeout to a value such as 1 hour, the portal would effectively limit a client to three hours of access before forcing it to authenticate. By default this is disabled, and all clients are presented with the portal login page and must login.

Note

For this to be effective, set a hard timeout and/or idle timeout.

Pass-through credits allowed per MAC address:

The number of times a specific MAC address may connect through the portal. Once the client uses its credits, it can only log in with valid credentials until the waiting period has expired.

Waiting period to restore pass-through credits:

The number of hours after which the portal will restore the pass-through credits for a client to the original count after it uses the first one. This must be above 0 hours.

Reset waiting period on attempted access:

If enabled, the waiting period is reset by the portal to the original duration if access is attempted when all pass-through credits have already been exhausted. This prevents people who repeatedly attempt to access the portal from gaining open access too quickly.

Logout popup window:

When checked, the portal attempts to show a logout pop up window to the user which allows clients to explicitly disconnect themselves before the idle or hard timeout occurs. Unfortunately, since most browsers block pop up windows, this window may not work for most clients unless.

Pre-authentication redirect URL:

As the name implies, this option redirects users to the specified URL before they authenticate. Commonly, this is used to display a custom landing page describing the device location hosted on a server locally or elsewhere. That landing page must contain a link which in turn redirects the users back to the portal page, e.g. http://x.x.x.x:8002/index.php?zone=somezone&redirurl=http%3A%2F%2Fsomesite.example.com.

Captive Portal Login Page¶

These simple customization controls enable small changes to the portal page without writing custom HTML. For more complicated portal pages, see HTML Page Contents.

Display Custom Logo Image:: When set, the portal page includes the custom image from Logo Image instead of the default logo.
Logo Image:: Upload control for setting a custom logo image.
Display Custom Background Image:: When set, the portal page includes the custom image from Background Image instead of the default background.
Background Image:: Upload control for setting a custom background image.
Terms and Conditions:: Text displayed by the portal to the user to which the user must agree before they are permitted to login.

Authentication¶

This section configures authentication for Captive Portal. If authentication is required for the zone it may be handled by the local user database, RADIUS, or LDAP.

Authentication Method:

Use an Authentication backend:

This option allows users to authenticate with a username and password or vouchers. The authentication is handled by the local user database (User Management and Authentication) or an authentication server (Authentication Servers).

Vouchers are pre-generated access codes which grant short-term access to users. Vouchers may be used in addition to, or instead of, user authentication. For more information on using vouchers, see Vouchers later in this section.

None, don’t authenticate users:

The portal only requires users to click through the login page for access. The form must still be submitted, but it does not need to have any user entry fields, only a submit button.

Use RADIUS MAC Authentication:

The portal attempts to authenticate users by sending their MAC address as the username and the password entered into MAC authentication secret to the RADIUS server.

Note

Users must still attempt an HTTP connection so the portal will see the attempt and perform the initial authentication.

See RADIUS MAC Authentication Options for additional options.

This option is not available if MAC filtering is disabled.

Authentication Server:

A multi-select control where one or more primary authentication servers, or the local database, can be set for use by the portal. See Primary Authentication Source for more information.

Local Database:

Captive Portal users in this mode are managed in the pfSense® software GUI. Local users are added in the User Manager (Manage Local Users).

Additionally, the Local Authentication Privileges option can limit access to only users who possess the proper access privileges.

LDAP Server:

When an LDAP server is active in the control, it is used by the portal for authentication as-is. There are no additional options for LDAP server behavior.

RADIUS Server:

When a RADIUS server is active in the control, numerous RADIUS server options are displayed by the GUI and Captive Portal users in this zone will be validated against the configured RADIUS server(s).

Secondary Authentication Server:

Similar to Authentication Server, but sets up an additional separate means of authentication using distinct fields. See Secondary Authentication Source for more information.

Primary Authentication Source¶

The Primary/Secondary authentication servers are used for the main username and password fields on the login form, auth_user and auth_pass, such as:

<tr>
     <td align="right">Username:</td>
     <td><input name="auth_user" type="text" style="border: 1px dashed;"></td>
 </tr>
<tr>
     <td align="right">Password:</td>
     <td><input name="auth_pass" type="password" style="border: 1px dashed;"></td>
</tr>

If the first server is down, the portal will attempt authentication using the other servers in the list, in order (top down).

Secondary Authentication Source¶

The secondary authentication source defines a completely separate authentication setup from the primary. For example, the primary source could be traditional usernames and passwords, while the secondary could be pre-paid card numbers or PINs.

The secondary authentication source uses the form fields auth_user2 and auth_pass2 in the captive portal HTML, such as:

<tr>
     <td align="right">Username:</td>
     <td><input name="auth_user2" type="text" style="border: 1px dashed;"></td>
</tr>
<tr>
     <td align="right">Password:</td>
     <td><input name="auth_pass2" type="password" style="border: 1px dashed;"></td>
</tr>

If the first server is down, the portal will attempt authentication using the other servers in the list, in order (top down).

Local Database Options¶

Local Authentication Privileges:: When Allow only users/groups with ‘Captive portal login’ privilege set is active, the portal will limit access to only users who have Captive Portal privilege. The privilege can be directly on their account or inherited via group membership..

RADIUS Authentication Options¶

RADIUS is a means of authenticating users against a central server that contains account information. There are many implementations of RADIUS, such as FreeRADIUS, Radiator, and NPS on Windows servers.

RADIUS accounting can be enabled to send usage information for each user to the RADIUS server. Refer to documentation for the RADIUS server for more information.

Passing back configuration from RADIUS Servers¶

Some default Captive Portal settings can be overridden by reply attributes from RADIUS servers. The exact attributes can vary by vendor, and may not be supported by all RADIUS servers.

User bandwidth restrictions:: Defines the bandwidth for the user, drawn from common options such as WISPr-Bandwidth-Max-Up/WISPr-Bandwidth-Max-Down, or ChilliSpot-Bandwidth-Max-Up/ChilliSpot-Bandwidth-Max-Down.
Session Timeout:: Drawn from the RADIUS attribute Session-Timeout, it will disconnect the user after the time specified by the RADIUS server.
Idle Timeout:: Drawn from the RADIUS attribute Idle-Timeout, it will disconnect the user after the time specified by the RADIUS server.
Accounting Interval Interim:: Taken from Acct-Interim-Interval, it directs the portal to send interim accounting updates at the specified interval.
URL Redirection:: Allows the after-authentication redirect URL to be defined by the RADIUS server through WISPr-Redirection-URL.

RADIUS Options¶

These options fine-tune how RADIUS authentication behaves.

NAS Identifier:

Configures an alternate NAS Identifier to send with RADIUS requests. The default value is CaptivePortal-<zone name>.

Reauthentication:

If enabled, the portal sends Access-Request packets to the RADIUS server for each user that is logged in every minute. If an Access-Reject is received for a user, that user is disconnected from the captive portal immediately. This allows actively terminating user sessions from the RADIUS server.

Warning

If concurrent login limits are defined in RADIUS this option may not work properly, as the additional request would fail as the reauthentication attempt would be considered a second concurrent login.

Note

If reauthentication is combined with RADIUS accounting, Interim accounting updates must be used to track usage during sessions, otherwise the RADIUS server will not know if a user exceeds limits until they logout.

Session-Timeout:

When set, clients will be disconnected after the amount of time set by the RADIUS Session-Timeout attribute sent to the portal at login.

Traffic Quota:

When set, the portal uses the pfSense-Max-Total-Octets reply attribute sent by the RADIUS server to set a traffic quota for a user. This determines an amount of traffic which, when exceeded by a client, will trigger a disconnect of that client by the portal. This includes both upload and download traffic.

Per-user Bandwidth Restrictions:

When set, the portal uses the pfSense-Bandwidth-Max-Up and pfSense-Bandwidth-Max-Down reply attribute sent by the RADIUS server to set per-user bandwidth restrictions.

MAC address format:

This option changes the MAC address format used in RADIUS. Change this to alter the username format for RADIUS MAC authentication to one of the following styles:

Default:

Colon-separated pairs of digits: 00:11:22:33:44:55

Single Dash:

Digits in two groups, separated by a single dash halfway: 001122-334455

IETF:

Hyphen-separated pairs of digits: 00-11-22-33-44-55

Cisco:

Groups of four digits separated by a period: 0011.2233.4455

Unformatted:

All digits together with no formatting or separators: 001122334455

RADIUS MAC Authentication Options¶

RADIUS MAC Secret:: When the portal attempts RADIUS MAC authentication, it sends the MAC Address as the username and this value as the password.
Login Page Fallback:: When set, the portal will redirect a client to the login page if MAC Authentication failed.

Accounting¶

RADIUS accounting sends session information back to the RADIUS server indicating when a user session starts, ends, and how much data they have transmitted.

Warning

Not all RADIUS servers support or are configured to accept accounting data. Setup the RADIUS server properly before enabling this feature.

Accounting Server:

An authentication server entry for a RADIUS server to which the portal will send accounting data (Authentication Servers).

Send Accounting Updates:

Configures the specific type of accounting supported by the server.

No updates:

Synonymous with disabling accounting, the portal will not send accounting updates to the server.

Stop/start:

The portal sends START and STOP records for a user session only.

Stop/start (FreeRADIUS):

The portal sends START and STOP records for a user session only, in a way that is compatible with FreeRADIUS.

Interim:

The portal sends START and STOP records and also periodically sends updates to the server while a user session is active. This method is less likely to lose session data if the firewall restarts without notifying the RADIUS server of a STOP message, but will cause increased database usage on the RADIUS server.

Accounting Style:

When Invert Acct-Input-Octets and Acct-Output-Octets is enabled, data counts for RADIUS accounting packets will be taken from the client perspective, not the NAS. Acct-Input-Octets will represent download, and Acct-Output-Octets will represent upload.

Idle Time Accounting:

This option changes the time sent in the STOP message for a user disconnected by the portal for idle timeout. When unset (default), the time sent is the last activity time. When set, the idle time is included.

HTTPS login¶

Login:: When set, the portal will listen for and accept HTTPS requests for the portal page. This option requires an SSL/TLS Certificate.
HTTPS server name:: The FQDN (hostname + domain) used by the portal for HTTPS. This must match the Common Name (CN) on the certificate to prevent users from receiving certificate errors.
SSL Certificate:: Select the SSL certificate used by the portal for HTTPS . Certificates are managed in Certificate Management.
Disable HTTPS Forwards:: When checked, attempts by clients to connect to HTTPS sites on port 443 are not redirected to the portal. This prevents users from receiving invalid certificate errors. Users must attempt a connection to an HTTP site, and will then be forwarded to the portal.

HTML Page Contents¶

When Use custom captive portal page is set on the zone, the portal displays these controls to upload custom HTML pages to alter the look of the page presented to users when they are redirected to the portal.

Customizing these pages is optional. Any page contents left blank will use internal defaults.

Portal pages may contain PHP code, and may also include other resources such as images and CSS files. See File Manager for more information on including additional assets in a custom portal page.

Warning

Since custom portal pages can run PHP, audit the code to ensure security so the page cannot be exploited by connecting users. Also, avoid granting privileges to this page to untrusted administrators.

In each individual section, the pages can be managed by the displayed controls:

To upload a new page, click Browse and select the file to upload. When the portal options are saved, the file will be copied.
To view an existing page, click View Page Contents
To download a copy of an existing page, click Download
To erase the custom page, click Restore Default Page

Portal page contents¶

This control is for the main portal page presented to users. Depending on the selected options for the portal, use one of the following examples as the basis for a custom page.

Portal page without authentication¶

This shows the HTML of a portal page that can be used without authentication.

Download: example-noauth.html¶

<html>
<head>
	<title>Welcome to our portal</title>
</head>
<body>
	<p>Welcome to our portal</p>
	<p>Click Continue to access the Internet</p>
	<form method="post" action="$PORTAL_ACTION$">
		<input name="redirurl" type="hidden" value="$PORTAL_REDIRURL$">
		<input name="zone" type="hidden" value="$PORTAL_ZONE$">
		<input name="accept" type="submit" value="Continue">
	</form>
</body>
</html>

Portal page with authentication¶

Here is an example portal page requiring authentication.

Download: example-auth.html¶

<html>
<head>
	<title>Welcome to our portal</title>
</head>
<body>
	<p>Welcome to our portal</p>
	<p>Enter your username and password and click Login to access the Internet</p>
	<form method="post" action="$PORTAL_ACTION$">
		<input name="auth_user" type="text">
		<input name="auth_pass" type="password">
		<input name="redirurl" type="hidden" value="$PORTAL_REDIRURL$">
		<input name="zone" type="hidden" value="$PORTAL_ZONE$">
		<input name="accept" type="submit" value="Login">
	</form>
</body>
</html>

Portal page with Vouchers¶

Here is an example portal page for use with vouchers.

Download: example-voucher.html¶

<html>
<head>
	<title>Welcome to our portal</title>
</head>
<body>
	<p>Welcome to our portal</p>
	<p>Enter your voucher code and click Login to access the Internet</p>
	<form method="post" action="$PORTAL_ACTION$">
		<input name="auth_voucher" type="text">
		<input name="redirurl" type="hidden" value="$PORTAL_REDIRURL$">
		<input name="zone" type="hidden" value="$PORTAL_ZONE$">
		<input name="accept" type="submit" value="Login">
	</form>
</body>
</html>

Authentication error page contents¶

Using this control, optionally upload a custom HTML page to be displayed when authentication errors happen. An authentication error occurs when a user enters a bad username or password, or in the case of RADIUS authentication, potentially an unreachable RADIUS server.

By default, this error page is simply the login page again.

Logout page contents¶

The logout page is presented to the user after login and it triggers a popup window. The default code uses JavaScript to create the new window in the following way:

Download: example-logout.html¶

<html>
<head><title>Redirecting...</title></head>
<body>
<span style="font-family: Tahoma, Verdana, Arial, Helvetica, sans-serif; font-size: 11px;">
<b>Redirecting to <a href="<?=$my_redirurl;?>"><?=$my_redirurl;?></a>...</b>
</span>
<script type="text/javascript">
//<![CDATA[
LogoutWin = window.open('', 'Logout', 'toolbar=0,scrollbars=0,location=0,statusbar=0,menubar=0,resizable=0,width=256,height=64');
if (LogoutWin) {
	LogoutWin.document.write('<html>');
	LogoutWin.document.write('<head><title>Logout</title></head>') ;
	LogoutWin.document.write('<body style="background-color:#435370">');
	LogoutWin.document.write('<div class="text-center" style="color: #ffffff; font-family: Tahoma, Verdana, Arial, Helvetica, sans-serif; font-size: 11px;">') ;
	LogoutWin.document.write('<b>Click the button below to disconnect</b><p />');
	LogoutWin.document.write('<form method="POST" action="<?=$logouturl;?>">');
	LogoutWin.document.write('<input name="logout_id" type="hidden" value="<?=$sessionid;?>" />');
	LogoutWin.document.write('<input name="zone" type="hidden" value="<?=$cpzone;?>" />');
	LogoutWin.document.write('<input name="logout" type="submit" value="Logout" />');
	LogoutWin.document.write('</form>');
	LogoutWin.document.write('</div></body>');
	LogoutWin.document.write('</html>');
	LogoutWin.document.close();
}

document.location.href="<?=$my_redirurl;?>";
//]]>
</script>
</body>
</html>

Most browsers have pop-up blockers that will most likely stop that logout window from appearing, so investigate other possible means of creating a JavaScript pop-up using similar code.