In this tutorial, we will be showing your how-to setup a Raspberry Pi Captive Portal by utilizing the popular nodogsplash software.

Raspberry Pi Captive Portal

A Captive Portal is a screen that will be shown initially to anyone who connects to your Wi-Fi Access Point. Before they can begin utilizing the Wifi connection, they will need to complete an action, until then, the captive portal will continually greet them.

You can display whatever you want on the captive portal, so it can be highly useful if you are going to lay out some ground rules to using your Wifi access point before a user gains access to it or whether you will require them to log in before getting access.

To complete this tutorial, you will first of had to of completed our WiFi Access Point tutorial, this is also fully compatible with our VPN Access Point tutorial.

Equipment List

Below are all the bits and pieces that I used for this Raspberry Pi Captive Portal tutorial, you will need a Wireless internet connection to be able to complete this tutorial.

Recommended

Raspberry Pi 2 or 3

Micro SD Card

Power Supply

Ethernet Network Connection

Wifi Dongle (There is a built-in module on the Pi 3)

Optional

Raspberry Pi Case

Setting up the Captive Portal

Before we proceed with setting up our captive portal, you will of first of had to follow our Wireless Access Point tutorial. This tutorial will build on top of the foundations that we set up in that tutorial and will show you how to configure it to show a captive portal. We can give no guarantee this will work otherwise.

1. We need first to make sure we are running up to date software before we set up our Raspberry Pi captive portal.

To do this, we can run the following two lines on our Raspberry Pi’s terminal.

sudo apt update
sudo apt upgrade

2. Let’s start by installing the packages that we will be needing for the captive portal software by running the command below.

The first package is the “git” program that we will use to clone the nodogsplash code and also the “libmicrohttpd-dev” package that contains the code that the nodogsplash code relies on to compile.

sudo apt install git libmicrohttpd-dev

3. With the Raspberry Pi now freshly updated we can get along with setting up our captive software, for this tutorial we will be utilizing the software called nodogsplash.

Nodogsplash is a somewhat lightweight captive portal solution that is easily set up and highly configurable.

Let’s grab this software off their git by cloning its repository with the following couple of commands.

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

4. Once the software has finished being cloned and we have either changed branch or installed the package, we can now proceed with compiling and installing the software.

To compile and install the software we will need to use the following three commands on our Raspberry Pi to setup and install the software.

cd ~/nodogsplash
make
sudo make install

5. With nodogsplash now installed to the system, we can now make some modifications to the configuration file.

Type in the following command into the terminal on your Raspberry Pi to modify the configuration file:

sudo nano /etc/nodogsplash/nodogsplash.conf

6. To this file we need to add the following information, this tells what interface the nodogsplash software should show up on and what address it should be listening on.

Please note that if you didn’t follow our Wi-Fi Access Point tutorial you will likely need to use a different gateway address.

GatewayInterface wlan0
GatewayAddress 192.168.220.1
MaxClients 250
AuthIdleTimeout 480

Now we can save and quit out of the file by pressing Ctrl +X then pressing Y and then Enter.

7. With our changes to Nodogsplash’s configuration saved, we can start up the software.

It is straightforward to do, and we need to just run the following command in the terminal on our Raspberry Pi to start up the captive portal.

sudo nodogsplash

8. Now if you connect to your WiFi hotspot, you should be greeted by the captive portal as shown in the screenshot below.

Clicking the splash image in the middle will allow you to browse the internet, but until then the captive portal will be continually shown.

Raspberry Pi Captive Portal

9. Now that we have confirmed that the captive portal is working and the splash page is being displayed, we should now make nodogsplash startup on launch.

We can achieve this by modifying the rc.local file.

Run the following command on your Raspberry Pi to begin editing the file:

sudo nano /etc/rc.local

Within this file find and add the following line, this makes nodogsplash be called when the Raspberry Pi boots up.

Find:

exit 0

Add above:

nodogsplash

Now we can save and quit out of the file by pressing Ctrl +X then pressing Y and then Enter.

10. You should now hopefully have a fully operational wireless access point with a fully working captive portal.

If you want to change what the default captive portal looks like, you can edit it by modifying the file located at /etc/nodogsplash/htdocs/splash.html

To easily modify this file you can utilize the following command to begin editing the file from within your Raspberry Pi’s terminal.

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

This file will explain the variables that are automatically available in the file, also take note of the <a link, as this shows what is needed to happen to authenticate your client on the default configuration.

11. You can also further customize Nodogsplash by modifying the configuration file that we added to our Gateway Interface.

You can find documentation on this by going to Nodogsplash’s documentation website.

You can modify the configuration file by using the following command on your Raspberry Pi.

sudo nano /etc/nodogsplash/nodogsplash.conf

Hopefully, by now, you have a fully operational Raspberry Pi Captive Portal that is presenting itself to all traffic through your Wireless Access Point.

If you have any problems or improvements, then feel free to leave feedback by dropping a comment below.

Ultimate Books of Pi Bottom
Get projects delivered to your inbox weekly.