Chapter 12. Captive Portal

Table of Contents

12.1. Connection Management
12.1.1. Pass-through MAC Addresses
12.1.2. Allowed IP Addresses
12.2. Authentication Management
12.2.1. Secure Authentication
12.2.2. Local User Management
12.2.3. Radius User Management
12.3. Custom Pages And Files
12.3.1. Portal Page Contents
12.3.2. Authentication Error Page Contents
12.3.3. Custom Files
12.4. Vouchers
12.4.1. Quick Howto
12.4.2. Voucher Parameters
12.4.3. Voucher Rolls
12.5. Limitations
12.6. Additional Information
12.6.1. Additional Documentation
12.6.2. Is there any extra Captive Portal RADIUS functionality available?
12.6.3. Using Captive Portal and MAC pass-through

This Captive Portal functionality allows you to control HTTP browser access to the Internet. All users trying to leave the selected network (for example all users from the LAN network going to the Internet) will be redirected to a HTML page stored on your m0n0wall. This page is typically where the user trying to reach the Internet can enter in username and password information to be authenticated and allowed access to the Internet.

Users are identified by their MAC hardware address of their ethernet card. All traffic trying to reach the Internet or selected network by any user is blocked until they use a web browser and finish the authentication process on the HTML authentication page.

Some features of the m0n0wall Captive Portal include:


Don't forget to enable the DHCP server on your captive portal interface! Make sure that the default/maximum DHCP lease time is higher than the timeout entered on this page. Also, the DNS forwarder needs to be enabled for DNS lookups by unauthenticated clients to work.

12.1. Connection Management

Below are some of the Connection options that can be configured for use with the Captive Portal. Additionally there is some information about allowing pass-through MAC addresses and making a list of allowed IP addresses that do not need authentication.

Table 12.1. Connection Parameters

Parameter Description
Interface Choose which interface to run the captive portal on. Captive Portal can only be run on one interface.
Maximum concurrent connections This setting limits the number of concurrent connections to the captive portal HTTP(S) server. This does not set how many users can be logged in to the captive portal, but rather how many users can load the portal page or authenticate at the same time! Default is 4 connections per client IP address, with a total maximum of 16 connections.
Idle timeout Clients will be disconnected after this amount of inactivity. They may log in again immediately, though. Leave this field blank for no idle timeout.
Hard timeout Clients will be disconnected after this amount of time, regardless of activity. They may log in again immediately, though. Leave this field blank for no hard timeout (not recommended unless an idle timeout is set).
Logout popup window If enabled, a popup window will appear when clients are allowed through the captive portal. This allows clients to explicitly disconnect themselves before the idle or hard timeout occurs.
Redirection URL If you provide a URL here, clients will be redirected to that URL instead of the one they initially tried to access after they've authenticated.
Concurrent user logins If this option is set, only the most recent login per username will be active. Subsequent logins will cause machines previously logged in with the same username to be disconnected.
MAC filtering If this option is set, no attempts will be made to ensure that the MAC address of clients stays the same while they're logged in. This is required when the MAC address of the client cannot be determined (usually because there are routers between m0n0wall and the clients).
Per-user bandwidth restriction If this option is set, the captive portal will restrict each user who logs in to the specified default bandwidth. RADIUS can override the default settings. Leave empty or set to 0 for no limit. You will need to enable the traffic shaper for this to be effective.

12.1.1. Pass-through MAC Addresses

Adding MAC addresses as pass-through MACs allows them access through the captive portal automatically without being taken to the portal page. The pass-through MACs can change their IP addresses on the fly and upon the next access, the pass-through tables are changed accordingly. Pass-through MACs will however still be disconnected after the captive portal timeout period.

You can enter a list of MAC address (6 hex octets separated by colons) and a description here for your reference (it is not parsed).

12.1.2. Allowed IP Addresses

Adding allowed IP addresses will allow IP access to/from these addresses through the captive portal without being taken to the portal page. This can be used for a web server serving images for the portal page or a DNS server on another network, for example. By specifying from addresses, it may be used to always allow pass-through access from a client behind the captive portal.

Some sample rules are:

any x.x.x.x > All connections to the IP address are allowed

x.x.x.x > any All connections from the IP address are allowed

For each entry on the Allowed IP Address list you can use From to always allow an IP address through the captive portal (without authentication). Use To to allow access from all clients (even non-authenticated ones) behind the portal to this IP address. Additionally each entry will contain an IP address and a description for your reference (it is not parsed).


If you have servers such as web or email on a separate subnetwork (for example a DMZ) be sure to add their IP addresses to this list. Otherwise users will not be allowed to access them without authenticating first.