Captive Portal¶
The captive portal intercepts unauthenticated HTTP requests from clients on a designated interface and redirects them to a login page before permitting internet access.
Web UI location¶
Services > Captive Portal
Prerequisites¶
- DHCP server must be enabled on the captive portal interface. The portal relies on DHCP to identify and manage client sessions.
- DHCP max lease time must exceed the portal idle timeout. If leases expire before portal sessions time out, clients may lose network access unexpectedly.
- The DNS forwarder is recommended so that unauthenticated clients can resolve the portal hostname.
Basic configuration¶
| Field | Notes |
|---|---|
| Enable | Master toggle |
| Interface | Network segment where the portal is active |
| Max concurrent connections per client IP | Limit per source IP (default 4) |
| Max total concurrent connections | Global cap (default 16, up to 100) |
| Idle timeout | Minutes of inactivity before disconnecting a session |
| Hard timeout | Absolute session duration regardless of activity (minutes) |
| Logout popup | Enable a popup window allowing users to manually disconnect |
| Redirection URL | URL to send clients to after successful login (blank = original requested URL) |
Authentication methods¶
No authentication¶
Portal page is displayed but no credentials are required. Useful for a terms-of-service acknowledgement only.
Local user manager¶
Users are authenticated against accounts configured in Services > Captive Portal > Users. User accounts are specific to captive portal and separate from the system user manager.
RADIUS¶
Users are authenticated against an external RADIUS server.
| Field | Notes |
|---|---|
| Primary RADIUS server IP | Address of RADIUS server |
| Primary RADIUS server port | Default 1812 |
| Primary shared secret | Shared secret matching the RADIUS server config |
| Secondary server | Fallback if primary is unreachable |
| RADIUS accounting | Enable accounting on port 1813 |
| Reauthentication | Re-authenticate every minute; choose stop/start or interim-update accounting |
| Session-Timeout attribute | Disconnect clients when RADIUS Session-Timeout attribute is reached |
| MAC authentication | Authenticate by client MAC address instead of username/password |
MAC address formats for RADIUS¶
When MAC authentication is used, the MAC is sent to RADIUS in one of these formats:
default— colon-separated lowercase (00:11:22:33:44:55)singledash— single-dash separated (001122-334455)IETF— dash-separated pairs (00-11-22-33-44-55)Cisco— dot-separated groups of four (0011.2233.4455)unformatted— no separator (001122334455)
Concurrent login control¶
Prevent same username from logging in multiple times simultaneously — when enabled, a second login with the same credentials disconnects the existing session.
HTTPS login¶
Upload a PEM certificate and private key to serve the login page over HTTPS. Also set the server hostname to match the certificate's common name so clients do not receive certificate errors.
Per-user bandwidth¶
RADIUS can return per-user bandwidth limits. The captive portal honours the WISPr-Bandwidth-Max-Down and WISPr-Bandwidth-Max-Up attributes. The traffic shaper must be globally enabled for per-user bandwidth to take effect.
A default bandwidth limit can also be configured directly on the captive portal page; it applies to all users that do not have RADIUS-supplied limits.
Custom portal pages¶
The captive portal accepts uploaded HTML pages for:
| Page | Purpose |
|---|---|
| Login page | Initial redirect page; must contain a form posting to $PORTAL_ACTION$ with fields auth_user, auth_pass, and auth_voucher |
| Error page | Shown on authentication failure; $PORTAL_MESSAGE$ is replaced with the error text |
| Status page | Shown to authenticated users; contains logout and optional password-change forms |
| Logout confirmation | Displayed after the user logs out |
If no custom pages are uploaded, built-in default pages are used.
Vouchers¶
Vouchers are pre-generated single-use or time-limited access codes.
Configure voucher rolls under Services > Captive Portal > Vouchers. Each roll defines a batch of codes with an associated duration. Clients enter a voucher code instead of a username/password.
MAC and IP bypass¶
Specific MAC addresses or IP addresses can be excluded from portal enforcement:
Services > Captive Portal > Allowed MACs— devices that bypass the portal by hardware addressServices > Captive Portal > Allowed IPs— hosts or networks that are always permitted
Important behaviour¶
- All connected clients are disconnected when configuration is saved. Plan changes during low-traffic periods.
- MAC filtering is enabled by default. Disable it only when clients are connecting through a router or layer-3 device (where the firewall cannot see individual client MACs).
- Bridge mode on optional interfaces is incompatible with captive portal.
Status¶
Active captive portal sessions are visible at Status > Captive Portal. The page shows connected users, session duration, traffic counters, and IP/MAC associations.