Setting up a Raspberry Pi Captive Portal

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.


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)


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

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


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


  1. Avatar for emceelamb
    emceelamb on

    Issues with outdated libmicrohttpd? – Another solution

    I also followed the instructions and install libmicrohttpd-dev and got the libmicrohtpd is out of date error.

    To get Nodogsplash working I added: use_outdated_mhd 1 to /etc/nodogsplash.conf

  2. Avatar for David
    David on

    Issues with outdated libmicrohttpd? – SOLVED
    Maybe this can help you if you get stuck with the same problem…

    I have successfully got everything running a few times (Rpi v2b) by following instructions verbatim. I recently tried on a v3b, and ran into a problem with libmicrohttpd being a too early version. I think v0.9.62 was installed and nodogsplash needed v0.9.69 or higher.

    So instead of running “sudo apt install git libmicrohttpd-dev” in step two, I ran the following, and the appropriate version of libmicrohttpd was installed…

    cd ~
    tar zxvf libmicrohttpd-0.9.70.tar.gz
    mv libmicrohttpd-0.9.70 libmicrohttpd
    cd libmicrohttpd
    sudo ./configure
    sudo make
    sudo make install

    As I’m a NOOB, I am not sure if it’s related to HW or whether the git libmicrohttpd-dev is not updated to use the latest version(?) Maybe someone else can advise…

  3. Avatar for humas
    humas on

    after step 6 when i run command . i get error
    i have changed its value to 1200 still same

    pi@pi:~ $ sudo nodogsplash
    [3][Wed Jul 24 12:25:57 2019][7498](src/conf.c:290) /etc/nodogsplash/nodogsplash.conf: line 503: Bad configuration option: ClientIdleTimeout
    [3][Wed Jul 24 12:25:57 2019][7498](src/conf.c:964) Bad option ClientIdleTimeout on line 503 in /etc/nodogsplash/nodogsplash.conf

    1. Avatar for Emmet
      Emmet on

      Hi Humas,

      There has been some recent updates to the Captive portal software that changed the options slightly.

      We have corrected the tutorial to utilize the right configuration name.


  4. Avatar for Derreck Nassar
    Derreck Nassar on

    Will Raspbian Buster work for this?

    1. Avatar for Emmet
      Emmet on

      Hi Derreck,

      This project should still work on Raspbian Buster.
      Let us know if you run into any issues.


  5. Avatar for Derreck Nassar
    Derreck Nassar on

    How do I modify the captive portal splash page? I’d like to possibly have a verification function on the page. In other words, how can I use my own splash page HTML?

    1. Avatar for Emmet
      Emmet on

      Hi Derreck,

      As mentioned in step 10 of the tutorial, you just need to modify the “/etc/nodogsplash/htdocs/splash.html” file.


  6. Avatar for akash
    akash on

    awesome its helped me a lot

  7. Avatar for ErnestoGaldamez
    ErnestoGaldamez on

    Is there anything else i need to do? I have my access point working followed all the steps in the tutorial but not getting the screen of nodogsplash.

    1. Avatar for Gus
      Gus on

      Hey Ernesto,

      This project should work fine with no modifications.

      Does anything happen when you run the “sudo nodogsplash” command?

    2. Avatar for ErnestoGaldamez
      ErnestoGaldamez on

      Nothing happens, no error no info nothing apparently the code works but no info.

    3. Avatar for Gus
      Gus on

      Hey Ernesto,

      That is incredibly strange, can you make sure that the settings you entered into “nodogsplash.conf” are correct and that the gateway address it is meant to attach itself to is correct.


    4. Avatar for bev
      bev on

      It’s possible that you need to install dnsmasq if you haven’t already. I had set up my access point using only hostapd and isc-dhcp-server, and could not get nodogsplash to work until I installed dnsmasq.

      Also try to run in debug mode to see what is happening :
      sudo nodogsplash -f -d 5

  8. Avatar for Rens Lakens
    Rens Lakens on

    Do you need raspbian or can you just use NOOBS?

    1. Avatar for Gus
      Gus on

      You can use either, NOOBs is just an installer for operating systems.

Leave a Reply

Your email address will not be published. Required fields are marked *