Important

Netgate is offering COVID-19 aid for pfSense software users, learn more.

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.

See also

See Allowed Hostnames to allow hostnames through the portal without authentication, and Allowed IP Address for IP addresses.

The custom captive portal page must have extra code at the top to properly handle this redirect. In the example code below, the pre-authentication redirect target page must also put its own URL in the redirurl parameter of its link back to the portal in order for the login page to appear.

<?php
require_once("globals.inc");
$request_uri = urldecode(str_replace("/index.php?zone={$_REQUEST['zone']}&redirurl=", "", $_SERVER["REQUEST_URI"]));
$portal_redirurl = urldecode("$PORTAL_REDIRURL$");
if(!stristr($portal_redirurl, $request_uri)) {
      Header("Location: $PORTAL_REDIRURL$");
      exit;
}
?>
After authentication Redirection URL

After authenticating or clicking through the portal, it will redirect users to this URL rather than the one they originally tried to access. If this field is left blank, the portal will redirect the user to the URL they initially attempted to access.

Blocked MAC address redirect URL

URL to which the portal will redirect users with blocked MAC addresses when they attempt access through the portal.

Preserve user database

When set, the database containing logged-in users is preserved by the portal when the firewall reboots.

Concurrent user logins

Controls whether or not users are allowed to connect multiple times. This is not a total limit for the entire portal, but a per-account limit.

May be set to one of the following:

Disabled

The portal will not allow concurrent logins for a user or voucher.

Multiple

(Default) The portal does not enforce any restrictions on concurrent logins by a user or voucher.

Last Login

The portal will only allow only one login per user account or voucher. The most recent login is permitted and any previous logins are disconnected.

First Login

The portal will only allow only one login per user account or voucher. The portal permits the first login and denies any subsequent login attempt.

MAC filtering

When set, the portal disables MAC address filtering. This is necessary in cases where the MAC address cannot reliably be determined, such as when multiple subnets exist behind a separate router using the portal. In that type of situation, all users behind a router will show up to the portal with the MAC address of the intermediate router. If this option is set, the portal will not attempt to ensure that the MAC address of clients stay the same while they are logged into the portal.

Note

This option is not compatible with RADIUS MAC authentication.

Pass-through MAC Auto Entry

In certain use cases, users may only need to authenticate once per device, and then the client should not see the portal login again unless they change devices. Setting up pass-through MAC entries can automatically achieve this goal.

Pass-through MAC automatic additions

If this option is set, the portal automatically adds a MAC passthrough entry after the user has successfully authenticated. Users of that MAC address will never have to authenticate again unless so long as the entry is present in the configuration. To remove the passthrough MAC entry, log in and remove it manually from the Pass- through MAC tab.

Note

This option is not compatible with RADIUS MAC authentication or the logout window.

Pass-through MAC automatic addition with username

If this option is set, the portal saves the username used during authentication along with the pass-through MAC entry. To remove the passthrough MAC entry, log in and remove it manually from the Pass-through MAC tab.

Per-user bandwidth restrictions

Captive Portal can also optionally rate-limit users to keep them from using too much bandwidth. The Default download and Default upload fields define the default values for user bandwidth, specified in Kilobits per second. These values can be overridden by RADIUS (Passing back configuration from RADIUS Servers) for different limits for specific users. If the fields are blank or set to 0, then users have unlimited bandwidth.

Use Custom Captive Portal Page

When set, enables upload controls for manually crafted portal pages. See HTML Page Contents for details. When unset, simple portal page customization controls are available (Captive Portal Login Page).

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® 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.

See also

To add or edit RADIUS server entries on pfSense software, see Authentication Servers.

See also

For those with a Microsoft Active Directory network infrastructure, RADIUS can be used to authenticate captive portal users from Active Directory using Microsoft NPS. This is described in Authenticating from Active Directory using RADIUS/NPS.

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 fa-file-text-o View Page Contents

  • To download a copy of an existing page, click fa-download Download

  • To erase the custom page, click fa-undo 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.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
<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.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
<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.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
<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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
<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.