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 basically a screen that will be shown initially to anyone who connects to your Wi-Fi Access Point. Before they can begin utilizing the Wi-Fi connection they will need to complete an action, until they do that they will be continually greeted by the captive portal.

Ultimate Books of Pi

You can display whatever you want on the captive portal, so it can be highly useful if you want to layout some ground rules to using your Wi-Fi access point before a user gains access to it or whether you will require them to login before getting access.

To complete this tutorial, you will first of had to of completed our Wi-Fi 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.


Raspberry Pi 2 or 3

Micro SD Card

Ethernet Network Connection

Wi-Fi (USB or built-in module on the Pi 3)


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 setup in that tutorial and will show you how to reconfigure it to show a captive portal. We can give no guarantee this will work otherwise.

1. We need to first make sure we are running up to date software before we setup 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 setup 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 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 is due to the main one requiring a package that isn’t available in Raspbian Jessie and earlier, while you miss out on improvements made in new versions of Nodogsplash 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
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 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 basically 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 ifconfigcommand to see what the new name is, it’s likely quite long.

GatewayInterface wlan0
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. This is very simple thing to do, we need to just run the following command in terminal on our Raspberry Pi to start up the captive portal.

sudo nodogsplash

8. Now if you connect to your Wi-Fi hotspot you should be greeted by the captive portal like 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 actually start up 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 basically makes nodogsplash be called when the Raspberry Pi boots up.


exit 0

Add above:


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 modifying 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 customise Nodogsplash by modifying the configuration file that we added our Gateway Interface into. 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 operation Raspberry Pi Captive Portal that is presenting itself to all traffic through your Wireless Access Point. If you have any problems or improvements feel free to drop a line in the comments below!

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!