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

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.

Ultimate Books of Pi

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-get update
sudo apt-get upgrade

2. 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 by using the two commands below on your Raspberry Pi.

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

3. Now we have two different steps to do, if you are running Raspbian Jessie or earlier then follow step 3a, otherwise if you are running Raspbian Stretch or later follow step 3b.

If you would like to know how to update your Raspberry Pi from Raspbian Jessie to Stretch, then you can follow our updating Raspbian tutorial.

3a. Raspbian Jessie and earlier: For this step, all we need to do is change the main branch of the repository we cloned to an earlier version of Nodogsplash. This change is due to the main one requiring a package that isn’t available in Raspbian Jessie and earlier. You will miss out on improvements made in new versions of Nodogsplash, but it still works fine for this tutorial.

Run the following commands on your Raspberry Pi to switch the GIT branch from master to v1.

cd ~/nodogsplash
git checkout v1

3b. Raspbian Stretch and later: For those who are running Raspbian Stretch we can stay on the main GIT branch. However, we will need to install a package that Nodogsplash requires to compile.

Run the following command to install the package on your Raspberry Pi.

sudo apt-get install libmicrohttpd-dev

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.

Important Note: If you have upgraded to Raspbian Stretch then wlan0 may need to be changed. Use the ifconfig command to see what the new name is, it’s likely quite long.

GatewayInterface wlan0
GatewayAddress 192.168.220.1
MaxClients 250
ClientIdleTimeout 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 over at our forums.

Ultimate Books of Pi Bottom
Pi My Life Up's Crash Course
to the Raspberry Pi

Pi My Life Up's Crash Course

to the Raspberry Pi

Subscribe to our email list to get the

Crash Course delivered straight to your inbox

Please check your inbox for a confirmation email!