How to Turn Your Raspberry Pi into a Captive Portal Wi‐Fi Access Point

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.

Also read:How to Install Windows 11 on a Raspberry Pi 4

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:

sudo reboot

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

Next, reboot your Raspberry Pi using the following command:

reboot

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.

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.

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

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:

sudo nodogsplash

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

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:

sudo nano /etc/rc.local

Find the following line:

exit 0

Directly above it, add the following:

nodogsplash

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.

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.

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!