by In 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.
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 ( Amazon )
- Micro SD Card ( Amazon )
- Power Supply ( Amazon )
- Ethernet Cable ( Amazon )
- Wi-Fi ( Amazon )
Optional
- Raspberry Pi Case ( Amazon )
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 upgrade2. 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 build-essential3. 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.git4. 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 install5. With nodogsplash now installed to the system, we can now make some modifications to the configuration file.
Type in the following nano command into the terminal on your Raspberry Pi to modify the configuration file:
sudo nano /etc/nodogsplash/nodogsplash.conf6. 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 480Now 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 nodogsplash8. 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.
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.localWithin this file find and add the following line, this makes nodogsplash be called when the Raspberry Pi boots up.
Find:
exit 0Add above:
nodogsplashNow 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.htmlThis file will explain the variables that are automatically available in the file, also take note of the <a link, as this shows what is needs 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.confHopefully, 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.
I am stuck at the “make” step.
I cd to nodogsplash directory ok, when I run make it says:
when I run sudo make install it says:
i did a get install for make but I don’t think I have the right thing. this is with bullseye so is that the problem?
please help, thanks.
Hi Roger,
I just quickly tested the compilation steps and didn’t manage to run into the same issues that you are experiencing.
Could you maybe try installing the “build-essential” package. This package contains things like the required code compilers.
You can install the build-essential package by using the following command in the terminal.
Cheers,
Emmet
the build essentials is actually in the second step. but I’ll try going through them all again.
“sudo apt install git libmicrohttpd-dev build-essential”
so i did the build essentials from your instruction, then started over, including putting in the build essential a second time. it went through! but, when I connect to the wifi, the splash page comes up, i click the button and it sends me thrpough to nothing. it says i am authorized but the phone still says the wifi has no internet.
I went through the config file, I have the right interface and IP, obviously cause I’m getting the splash. I read through the various options in the config but don’t see anything (to me anyway) that would connect the wifi after authorization.
weird huh?
ok, watching the output on the screen (ssh) after running nodogsplash from the command line, when I login on my phone, it says :
adding 10.0.2.104 (MAC ADDRESS) token (random alphanumeric) to client list…. but then the next line says “token is invalid”. so does that help figuring the problem?
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
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 ~
wget ftp://ftp.gnu.org/gnu/libmicrohttpd/libmicrohttpd-0.9.70.tar.gz
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…
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
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.
Cheers,
Emmet
Will Raspbian Buster work for this?
Hi Derreck,
This project should still work on Raspbian Buster.
Let us know if you run into any issues.
Cheers,
Emmet
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?
Hi Derreck,
As mentioned in step 10 of the tutorial, you just need to modify the “/etc/nodogsplash/htdocs/splash.html” file.
Cheers,
Emmet
awesome its helped me a lot
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.
Hey Ernesto,
This project should work fine with no modifications.
Does anything happen when you run the “sudo nodogsplash” command?
Nothing happens, no error no info nothing apparently the code works but no info.
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.
Cheers
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
Do you need raspbian or can you just use NOOBS?
You can use either, NOOBs is just an installer for operating systems.