Aug 232013

After making an Access Point out of a Raspberry Pi, I decided to see what else I could do with it.

One of the things I had noticed on the forums was a captive portal function. When someone connects to the Access Point, no matter where they point their web browser it will always direct them to the page hosted on the Pi.

In order to do that, we’ll need to install a web server on the Pi to host the page.
I’ve used lighttpd for this setup, so it’s a simple apt-get install lighttpd

The default directory for lighttpd is /var/www, so you can place your splash page in there.

Once lighttpd is installed, we need to make a slight change to the dnsmasq configuration.
Add the extra line below into /etc/dnsmasq.conf, replace with the IP address of the AP if you have not followed the guide above.


Once the file has been updated, restart dnsmasq

/etc/init.d/dnsmasq restart

Now, whenever someone connects to the access point and points their web browser to anything, it will be directed to the splash page that you have created !


  30 Responses to “How To : Captive Portal On The Raspberry Pi”

  1. Pancake Web Server for Raspberry Pi would also be good for this purpose. Rather easier to configure than Lighttpd.

  2. Great works!! with raspberry , you are my guru!!

    One question.. how i can show the question to the user, to open a page (welcome page for example) after wifi connetion to my raspberry??
    (or open the browser after wifi connetion to the pi access point )
    thanks !!

    • You can’t force a browser to open on a user’s computer unfortunately. If they open a browser themselves, then it will be directed to the Pi.

      • Hi.
        sorry for my english.. i try to explain better..
        i have raspberry with wifi usb and i made a access piint with it (it work well)
        i want that after connection of smartphone or tablet to my access pi-point the user see on their device the question :”the connection require open a page…” like appen with same access point system
        is it possible?? thanks a lot!!

        • Yes, with this guide.
          Though with this guide, they won’t be able to connect to the internet.

          Do you want a system where they have to click on “agree” before they can connect to the internet ?

          • Yes, agree or info page that i can choose on my web server (apache on raspberry)

          • You’d need to setup a shell script with some iptables rules and things like that to set it up.
            I haven’t looked into it yet so I’m not sure exactly how you’d do that…

  3. This doesn’t capture full URL’s e.g redirects to the AP, but lands the client on the 404 page. And some pages just don’t load, “can’t connect to the server”.

    Is that your result using this, or have I done something horribly wrong?

    • Yes, It does the same thing for me.
      The reason is because everything after the .com is handled by the webserver. If you had a page on the AP at the same location, then it would show that page, otherwise the webserver won’t be able to locate /hello on your server and throw up a 404.

  4. Hello there,
    I’m fighting with a strange issue: the first time I start (or restart) both hostapd and dnsmasq the AP works great for multiple users of any kind, if I reboot, the SSID shows up but no IP is given to any of the connecting devices.

    SECOND: I have a goal for my installation that, maybe, can be of interest for others: do someone has experience using WISPR or other method to popup an alert or a web page on each dhcp lease? Like that the user won’t have the need to start a browser once accessed the wlan.

    Thanks to anybody that will help and/or spend some time on this questions 😉


    • For the first issue, make sure you don’t have ifplugd running. I don’t think it’s possible to do what you want in regards to the second issue either.

  5. I followed this and your rPi Access Point tutorial and got things working, intermittently.

    I don’t actually want to route any traffic to eth0 – I want to keep all traffic on my rPi captively viewing my local website (the server will eventually be in a location where there is no internet available).

    Basically, what I’m seeing is my devices will connect to the rPi and get IP addresses, but then they’ll recognize that there is no internet connection and will do one of two things 1) Drop the connection and search for another wifi signal that is connected to the internet or 2) stop using the wifi and start using their service providers data connection (on mobile phones).

    I didn’t do step 2 or 3 from your tutorial, because I figured I didn’t want/need that anyway.

    Do you know what I can do to help these devices from doing this?

    • What devices are you connecting to the Pi ? As long as they can get an IP address, they should connect to the AP, unless you’re playing with Apple devices…

    • That is the devices testing for a “good” internet connection, on Android you can need to go into the WiFi advanced settings and tell it not to avoid poor connections (or something like that, different devices have different names). Setting up DNSmasq like in the tutorial will trick the phone into trying to log into the network.

      Oh, and thank you to SirLagz for this simple tutorial, I will be setting up a hotspot like this, but I will also add a step to set up the 404 page to redirect to the index page.

  6. Regarding the question of getting a pop-up on connection, there is apparently support, but I think it is vendor specific:

  7. Hello,

    Thanks for the great stuff.

    I am having issues getting this running, I have followed all the steps but after I restart the server it is not redirecting me to my splash page. It just says server not found. Could you please help me with this.


  8. it doesn’t redirect to my splash page

  9. Hey All,

    I have setup my RPI3 as a AP running Captive Portal with no IP forwarding. I want people connection to only hit the Web page that I have running. All works except one part. I want people on Mobile devices such as Android / iOS / Others if possible to get an automatic pop or to the Page or notification they can click on that takes them to the page hosted on the RPI3. Basically just like they would experience when then connect to a hotel WiFi running captive portal.

    Wayne B.

  10. Doesn’t it prevent the user from being able to browse website or does it ‘splash’ just once?

  11. Hi, I have setup my RPI3 as a AP and I have a web server at using node js
    How to adjust lighttpd when others connect to RPi3 and running Captive Portal to connect my nodejs server ?

 Leave a Reply

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>



This site uses Akismet to reduce spam. Learn how your comment data is processed.