How To Create A Captive Portal For Wifi Linux

Maybe you're a business owner who offers complimentary Wi-Fi to all your customers; perhaps you have a captive audience and plan to sell access to your Wi-Fi network, or maybe you want to give guests a friendly reminder about the etiquette of using your home network? You will learn here how to turn your Raspberry Pi into a captive portal Wi-Fi access point.

Why do I need a captive portal?

If you've ever tried to access a seemingly-open Wi-Fi network at a cafe, restaurant, hotel or gym, only to be greeted by a login screen that refuses to let you proceed before entering some information (usually your email address), then you're already familiar with captive portals!

A captive portal is a webpage that either opens automatically in the user's default browser or loads when they try to visit a webpage. The user will typically need to complete an action before they can move on from the captive portal.

Although they're commonly used by businesses, captive portals can also be a useful addition to your home network. For example, you can create a separate network for your children, complete with parental controls and a captive portal that gently reminds your children that you're trusting them to use the web responsibly – just in case they're tech-savvy enough to know how a VPN works.

What you'll need

To complete this tutorial, you'll need:

Raspberry Pi that's running Raspberry Pi OS
Power cable that's compatible with your Raspberry Pi
External keyboard and a way to attach it to your Raspberry Pi
HDMI or micro HDMI cable, depending on your model of Raspberry Pi
External monitor
Ethernet cable. Since you're turning your Raspberry Pi into a wireless access point, you'll need to connect over Ethernet rather than Wi-Fi. This also means it won't work with Raspberry Pi 2 or Raspberry Pi Zero since they're missing either an Ethernet port or wireless card.

Getting started: update your Raspberry Pi

Attach your external keyboard, monitor and ethernet cable, and then attach your Pi to a power source. Once it is booted up, open a terminal and type the following command to update it:

            sudo            apt update            &&            sudo            apt            -y            upgrade

Reboot your Raspberry Pi by running the following command:

Once your Raspberry Pi reboots, everything will be up to date.

Set up wireless access point for Raspberry Pi

There's several ways to transform your Raspberry Pi into a fully-functioning access point, but in this tutorial a RaspAP is used, as it's easy to set up.

To install the RaspAP software, open a Terminal window and run the following command:

curl            -sL            https://install.raspap.com            |            bash

You can quickly and easily create a Wi-Fi hotspot, using RaspAP

Next, reboot your Raspberry Pi using the following command:

Once your Raspberry Pi is back up and running, your Wi-Fi access point will be configured with the following settings:

IP address: 10.3.141.1
Username: admin
Password: secret
DHCP range: 10.3.141.50 to 10.3.141.255
SSID: raspi-webgui
Wi-Fi Password: ChangeMe

To put your access point to the test, simply grab any Wi-Fi-enabled device and check its network settings. You should see the option to connect to a new "raspi-webgui" network.

Open any Wi-Fi enabled device's network settings, and you should see that a new network has appeared!

Connect to this network, and you'll be prompted for a password. RaspAP's default password is "ChangeMe," so type this into the network configuration box, click "Connect" and you'll be connected to your new Raspberry Pi access point!

Secure your Wi-Fi access point

Before going any further, update "ChangeMe" to something more secure, via the RaspAP web interface:

1. Launch your web browser, if you haven't already.

2. In the address bar, enter the following: 10.3.141.1.

When prompted, enter the username "admin" and the password "secret." You should now be viewing the main RaspAP web interface.

The RaspAP web console displays information about your web traffic.

3. In the menu on the left, select "Hotspot -> Security."

It's recommended that you change your password to something more secure than the publicly-known default!

4. Find the "PSK" section and enter the password that you want to use for your Wi-Fi access point – make sure it's something secure!

5. Click "Save Settings."

Creating a captive portal with Nodogsplash

Now that your access point is up and running, you're ready to secure it with a captive portal.

The captive portal will be built using the Nodogsplash captive portal solution, but first you need to install the libmicrohttpd-dev package, as this contains code that you'll use to compile Nodogspash.

On your Raspberry Pi, run the following command:

            sudo            apt            install            git            libmicrohttpd-dev

Once you have the libmicrohttpd-dev package, you can clone the repository that contains all the Nodogsplash code:

            cd            ~            git clone            https://github.com/nodogsplash/nodogsplash.git

Once Raspbian has finished cloning this code, you're ready to compile and install the Nodogsplash software:

            cd            ~/nodogsplash            make            sudo            make            install

Nodogsplash is now installed on your Raspberry Pi.

Configure your captive portal

Next, you need to point Nogdogsplash in the direction of the Gateway address, which is the router interface that's connected to the local network. RaspAP uses 10.3.141.1 by default, so you need to edit the Nogdogsplash configuration file so that it's listening on this address.

To edit the Gateway address, open the Nogdogsplash configuration file:

            sudo            nano            /etc/nodogsplash/nodogsplash.conf

Add the following:

GatewayInterface wlan0 GatewayAddress 10.3.141.1 MaxClients            250            AuthIdleTimeout            480

Once you've made these changes, save your file by pressing Ctrl + O, followed by Ctrl + X.

Start up your captive portal by running the following command:

Your captive portal is now live. To test it, try connecting to your Wi-Fi hotspot.

If you connect to your Wi-Fi hotspot, you should see the default Nodogsplash captive portal.

You should now be greeted by Nodogsplash's default captive portal.

Make sure your portal is always online

Now that you've checked that the captive portal is working correctly, you need to make sure Nodogsplash starts automatically at boot.

Set Nodogsplash to launch automatically by editing your "rc.local" file. In the Raspberry Pi Terminal, run the following command:

Find the following line:

Directly above it, add the following:

Save your changes by pressing Ctrl + O, followed by Ctrl + X.

How to customize your captive portal

At this point you have a Wi-Fi hotspot that's protected by a captive portal. However, you're still using the default Nodogsplash page, so in this final section let's look at how you can access the code that controls your captive portal page and make some simple edits.

To customize the default Nodogsplash page, you'll need to open the "splash.html" file:

            sudo            nano            /etc/nodogsplash/htdocs/splash.html

You can now add images and text to your portal and remove existing content. For example, in the below image the text that's displayed as part of the captive portal is being changed.

You can customize your captive portal, by editing the splash.html file.

When you're happy with the edits you've made, save your changes by pressing Ctrl + O, followed by Ctrl + X.

Try reconnecting to your Wi-Fi hotspot, and you should see your revamped captive portal.

The next time you try to connect to your Wi-Fi network, you'll see your custom portal screen.

Note that depending on your operating system and web browser, you may need to clear your browser cache in order to see the updated captive portal.

In addition to a Wi-Fi access point, you can also turn your Raspberry Pi into a ad-blocker or a personal web server.

How are you using your newly-created captive portal? To welcome people to your home network, set some ground rules, or as a tool to help promote your business? Let us know in the comments below!

Is this article useful?

Jessica Thornsby

Jessica Thornsby is a technical writer based in Derbyshire, UK. When she isn't obsessing over all things tech, she enjoys researching her family tree, and spending far too much time with her house rabbits.