Family Encyclopedia >> Electronics

How to Turn Your Raspberry Pi into a Captive Portal Wi-Fi Hotspot

Maybe you are a business owner who offers free Wi-Fi to all your customers; maybe you have a captive audience and are planning to sell access to your Wi-Fi network, or maybe you want to friendly remind your guests of the etiquette to use your home network? Here you will learn how to turn your Raspberry Pi into a captive portal Wi-Fi hotspot.

ContentsWhy do I need a captive portal?What you'll needGetting started:Update your Raspberry PiSet up a wireless hotspot for Raspberry PiSecure your Wi-Fi hotspotCreate a captive portal with NodogsplashSet up your captive portalSecure make sure your portal is always onlineHow to customize your captive portal

Why do I need a captive portal?

If you've ever tried to access a seemingly open Wi-Fi network in a coffee shop, restaurant, hotel, or gym, only to be greeted by a login screen that refuses to let you continue until you enter certain information (usually your email address), then you already know about captive portals!

A captive portal is a web page that automatically opens in the user's default browser or loads when they try to visit a web page. The user will usually need to perform an action before they can leave the captive portal.

Although 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 trust them to use the web responsibly – just in case they are keen enough. of technology to know how a VPN works.

What you'll need

To complete this tutorial you will need:

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

Getting started:updating your Raspberry Pi

Connect your external keyboard, monitor, and ethernet cable, then connect your Pi to a power source. Once started, open a terminal and type the following command to update it:

sudo apt update &&sudo apt -y upgrade

Restart your Raspberry Pi by running the following command:

sudo reboot

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

Configure a wireless access point for Raspberry Pi

There are several ways to turn your Raspberry Pi into a fully functional access point, but in this tutorial a RaspAP is used because it is easy to configure.

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

curl -sL | bash
How to Turn Your Raspberry Pi into a Captive Portal Wi-Fi Hotspot

Connect to this network and you will be prompted for a password. RaspAP's default password is "ChangeMe", so enter it in the network configuration box, click "Connect" and you will be connected to your new Raspberry Pi hotspot!

Secure your Wi-Fi hotspot

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, type the following:

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

How to Turn Your Raspberry Pi into a Captive Portal Wi-Fi Hotspot

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

How to Turn Your Raspberry Pi into a Captive Portal Wi-Fi Hotspot

4. Find the "PSK" section and enter the password you want to use for your Wi-Fi hotspot - make sure it's a secure password!

5. Click "Save Settings".

Create 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 it contains code that you will 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 which contains all the Nodogsplash code:

cd ~git clone

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

cd ~/nodogsplashmakesudo 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 connected to the local network. RaspAP uses by default, so you need to edit the Nogdogsplash configuration file so that it listens on this address.

To change the gateway address, open the Nogdogsplash configuration file:

sudo nano /etc/nodogsplash/nodogsplash.conf

Add the following:

GatewayInterface wlan0GatewayAddress 250AuthIdleTimeout 480

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

Start 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.

How to Turn Your Raspberry Pi into a Captive Portal Wi-Fi Hotspot

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

Make sure your portal is always online

Now that you have verified that the captive portal is working properly, you need to ensure that Nodogsplash starts automatically on boot.

Configure 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:


Just above, 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 WiFi hotspot 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 changes.

To customize the default Nodogsplash page, you will 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 image below, the text displayed in the captive portal frame is being edited.

How to Turn Your Raspberry Pi into a Captive Portal Wi-Fi Hotspot

When you are happy with the changes you have made, save your changes by pressing Ctrl + O , followed by Ctrl + X .

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

How to Turn Your Raspberry Pi into a Captive Portal Wi-Fi Hotspot

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 hotspot, you can also turn your Raspberry Pi into an ad blocker or personal web server.

How do you use your newly created captive portal? To welcome people into your home network, establish ground rules, or as a tool to help promote your business? Let us know in the comments below!