Your Network. Your Rules.TM
Personal tools

Captive Portal

From UntangleWiki

Jump to: navigation, search

Image:CaptivePortal_128x128.png     Captive Portal
Other Links:
Captive Portal Description Page
Captive Portal Screenshots
Captive Portal Forums
Captive Portal FAQs


About Captive Portal

Captive Portal allows administrators to require network users to log in or accept a network usage policy before accessing the internet. Captive Portal can authenticate users against Untangle's built-in Local Directory, Active Directory (if Directory Connector is installed), or RADIUS. It can be used to set up policies (for Policy Manager) by username (or group name if using Active Directory) rather than IP. While Captive Portal is running, captured machines will be forced to authenticate (or just press OK) on the Captive Portal page before they are able to access the internet.


This section reviews the different settings and configuration options available for Captive Portal.

Getting Started with Captive Portal

After installing Captive Portal, complete the following steps to get it working:

  1. Define which machines will be captured and required to complete the Captive Portal process before accessing the Internet - enabling the first example rule in the Capture Rules table will force all machines on the internal interface to use Captive Portal.
  2. Enter any IPs that unauthenticated machines will need to access - these can be entered in the Pass Listed Server Addresses section of the Passed Hosts tab.
  3. Enter any IPs that always need access to the internet - these can be entered in the Pass Listed Client Addresses section of the Passed Hosts tab.
  4. Customize the Captive Portal page on the Captive Page tab. If Basic Login is chosen, set the appropriate authentication method for users on the User Authentication tab.
  5. Turn on Captive Portal.

At this point Captive Portal will evaluate your Capture Rules and any traffic that matches will be stopped until that user has completed the Captive Portal process.


This tab shows the current status of Captive Portal. You can see information about current captured IPs, such as the username and other session information. You can also logout any active session.

Capture Rules

The Capture Rules tab allows you to specify rules to Capture or Pass traffic that crosses the Untangle.

The Rules documentation describes how rules work and how they are configured. Captive Portal uses rules to determine whether to capture or pass each network session. The rules are evaluated in order, and on the first match, the configured action will be applied. If no rules match, the traffic is allowed by default. Once a client has completed the authentication process configured in Captive Portal, all traffic for that client is allowed to pass. Once the client logs out or expires, the rules will again be applied.

Passed Hosts

The Pass Hosts tab allows you to specify machines that either a) should not be affected by Captive Portal, or b) servers that machines behind Captive Portal should be able to access even if unauthenticated.

  • Pass Listed Client Addresses: These machines will not be affected by Captive Portal. This is useful for servers and devices without browsers.
  • Pass Listed Server Addresses: Machines behind Captive Portal will be able to access these servers whether or not they have authenticated through Captive Portal. Typically these will be any DNS or DHCP servers that are separated from their clients by Untangle. If Untangle is handling DHCP or DNS, this is not necessary.

Captive Page

This tab controls the type of Captive Portal page displayed to unauthenticated users. Please note that you can use HTML in the Captive Portal page fields, however invalid HTML will prevent the page from properly rendering.

  • Basic Message: Select this option if users should see (or accept) a message before being allowed to the internet. It has several tunable properties such as Page Title, Welcome Text, Message Text and Lower Text. If Agree Checkbox is enabled, users must check a checkbox (labeled with the Agree Text) before continuing.
  • Basic Login: Select this option if users should see a page that requires them to login. Similar to Basic Message, it has several properties that can be configured. When the login/continue button on the page is clicked the user will be authenticated. You'll also need to set your authentication method on the User Authentication tab.
  • Custom: Select this option if you would like to upload a custom Captive Portal page. This is for experienced web developers that are comfortable with HTML, Python and JavaScript - Untangle Support department can not help with development of custom Captive Portal pages. If Custom is selected it is advised to turn off automatic upgrades - newer versions of Untangle may be incompatible with any custom captive page.

The View Page Button can be used to view what the configured captive page looks like. This button only works when Captive Portal in on.

  • Redirect URL: Users will be rerouted to this site after successful authentication. If Redirect URL is blank they will be sent to the original destination.
Make sure to enter a complete url (e.g. http://www.untangle.com) or this setting will not properly operate.

Custom Pages

There are two levels for customizing the Captive Portal capture page. One is fairly easy and the other is more complex.

For the easy method, you create a custom.html file and place it along with any supporting image files, etc. into a zip file, and then upload the file via the administrative interface. This allows you to customize the look and layout of the page while leveraging the existing code and application settings. To use this model, you need to be familiar with HTML and forms. We have created two examples that each include a simple and well documented custom.html file to help you get started.

Description Download Screenshot
Custom login text custom_login.zip
Custom agree text custom_agree.zip

The more difficult method also gives you the most flexibility, as your custom zip will include a custom.py Python script. This gives you the ability to perform any kind of authentication or validation you wish. To use this model, you should be fluent in Python programming, and experience with mod_python will also be helpful. We have created one example that includes a simple and well documented custom.py file you can use as a guide.

Description Download Screenshot
Custom hotel login screen, where the user must enter a room number. custom_hotel.zip
Custom page with restricted number of logins. Useful for limiting users to X hrs or X logins per day. custom_logincount.zip
Custom page allowing users to create new accounts on the fly. custom_registration.zip
Custom page allowing users to use paypal to pay for internet custom_paypal.zip

User Authentication

This section controls how users will be authenticated if the Basic Login page is used.

  • None: is used in the case where no login is required.
  • Local Directory: Use the Untangle's built-in Local Directory (Config > Local Directory) to authenticate users.
  • RADIUS: Use an external RADIUS server to authenticate users. This option requires Directory Connector to be installed and enabled and configured.
  • Active Directory: can be used if user should be authenticated against an Active Directory server. This option requires Directory Connector to be installed and enabled and configured.

The Session Settings section controls the timeout and concurrent login settings for Captive Portal.

  • Idle Timeout: This option controls the amount of time before a host is automatically logged out if no traffic is seen. While a machine may be idle, it is still active on the network level. In this case Idle means no new TCP or UDP connections are seen by the Captive Portal. IMPORTANT: It is recommended to leave this at zero (not enabled).
  • Timeout: This option controls the amount of time before a computer will be automatically logged out. After this the user must log in again through Captive Portal. Timeouts greater than 1440 minutes (1 day) is not recommended. The authenticated table is store in memory and will be flushed on reboot/upgrade. Additionally, the logout time should also be shorter than your DHCP lease time to assure IPs don't change before the Captive Portal timeout.
  • Allow Concurrent Logins: This option controls if multiple machines can use the same login credentials simultaneously. If enabled, two or more users can login with the same username/password at the same time.

Event Log

Use the following terms and definitions to understand the Event Logs:

User Event Log

Name Description
Timestamp The time the event took place.
Client The client IP address.
Username The client username (if applicable).
Action The action taken for the client.
Authentication The authentication type used by the client.

Rule Event Log

Name Description
Rule ID The ID of the capture rule corresponding to the event.
Timestamp The time the event took place.
Client Address The client IP address.
Client Port The network port used on the client side of the connection.
Server Address The server IP address.
Server Port The network port used on the Server side of the connection.
Captured Shows true if the session was captured, or false if the session was passed.

Related Topics

Directory Connector

Captive Portal FAQs

Can I use Captive Portal and the Active Directory Login Script?

Yes, provided you make sure to keep them separate - users should not be logging in with Captive Portal authentication set to Active Directory and be running the ADLS. If they are both used, Untangle uses the most recent information to determine the correct username. This can very confusing as the ADLS updates on login (and every few minutes) and the Captive Portal users will also login after every timeout, sometimes with a different username.

How can I allow users to log themselves out of Captive Portal?

If you need users to be able to log themselves out, they can browse to <Untangle's_LAN_IP>/capture/logout to make this happen.

Machines behind the Captive Portal page are not working - how can I troubleshoot?

The Block Event Log shows all traffic that is being blocked because the source machine has not been authenticated. This is useful for finding out what traffic is being blocked and if there is any that should not be blocked. Often idle machines without logged in users can still be active on the network, making this log quite large. If there is activity that shouldn't be blocked under any circumstances this can be fixed by modifying the Capture Rules, the client and server pass lists, or creating bypass rules if Capture Bypass Traffic is unchecked.

When I upload my custom zip file I get "The uploaded ZIP file does not contain custom.html or custom.py." Why?

The custom.zip must have either a custom.py or a custom.html at the top level. It can not be within a arbitrary subdirectory. If there is not a custom.py or a custom.html at the top level this message will be displayed.