How to build a captive web portal with any router and a Raspberry Pi


This article explains how to build a captive web portal with a Raspberry PI, redirecting all clients to a web site on the internet.

This article is based on excellent port of Brennan available on this link (


The following schema gives an overall view of the situation

We want that the clients connecting to our Hotspot are automatically redirected to a web site on the internet and nowhere else.

Creating the hotspot

Any router should do the job (here an Asus RT-AC66U)

Configure the router with the following parameters

  • Choose the SSID you want (here ASUS)
  • Configure the authentication to "Open"

Then, disable DHCP

Then configure the firewall to allow only connection to the captive web site

Configure the Raspberry Pi

Install required packages

Add the two following packages


apt-get install dnsmasq nginx

  • dnsmasq : provides DHCP and DNS services for small networks
  • nginx : a web server that will redirect our clients to the captive web site

Configure a static IP address for the Raspberry Pi


sudo nano /etc/dhcpcd.conf

Modify the file to fit your needs


# Example static IP configuration:
interface eth0
static ip_address=
#static ip6_address=fd51:42f8:caae:d92e::ff/64
static routers=
static domain_name_servers=

Configure the hosts file


sudo nano /etc/hosts

Modify the file like bellow localhost
::1 localhost ip6-localhost ip6-loopback
ff02::1 ip6-allnodes
ff02::2 ip6-allrouters raspberrypi hotspot.localnet

Notice the two entries at the end of the file

  •     is for the local host
  •     is the ip address of the captive web portal

Dnsmasq will upload this file on startup and answer DNS queries consequently

Configure dnsmasq


sudo nano /etc/dnsmasq.conf

Modify the file like bellow


# Never forward addresses in the non-routed address spaces.
# Add other name servers here, with domain specs if they are for non-public d$
# Add local-only domains here, queries in these domains are answered from /etc$
# Make all host names resolve to the Raspberry Pi's IP address
# Specify the interface that will listen for DHCP and DNS requests
# Set the domain for dnsmasq
# Specify the range of IP addresses the DHCP server will lease out to devices, $
# Specify the default route
# Specify the DNS server address
# Set the DHCP server to authoritative mode.

Restart dnsmasq


sudo service dnsmasq restart

This configuration turns the Raspberry Pi into a fake DNS server.

It will resolve all DNS queries to it's own IP address, except the captive web portal ( that will be resolved to the IP address found in the hosts file ( )

We can test the result by connecting to our hotspot with a laptop and launch following commands

We can see that resolves to the Raspberry Pi address (

And our captive web site address ( resolves to the real address (

Configure nginx

Now we want to configure nginx to redirect all http and https requests to our captive web site.


sudo nano /etc/nginx/sites-available/default


# Default server configuration
server {
listen 80 default_server;
listen [::]:80 default_server;
listen 443 ssl;
listen [::]:443;

root /var/www/html;

# Add index.php to the list if you are using PHP
index index.html index.htm index.nginx-debian.html;

server_name _;

return 302 $scheme://;

Remark: Notice the last line that redirect all traffic to the captive web portal by answering with an HTTP status code "302 Found" which is a common way of performing a url redirection. This will allow most smartphones (android and iphones) to spontaneously open a popup to our web site when connecting to the hostspot.

Restart nginx


sudo service nginx restart

Configure the web site

The web site I will use is very basic and made of three pages

This page will serve following code


<h1>Welcome to my hotspot</h1>
<h1><a href="./page1/">Page1</a></h1>
<h1><a href="./page2/">Page2</a></h1>

This page will serve following code


<h1>Welcome to Page 1</h1>
<h1><a href="../">Home</a></h1>

Test the result

Now, when you connect to the WIFI hotspot with a smartphone,

you should be automatically redirected to the captive web site.

Where you can navigate as you want

The only problem is that I could never get reed of the annoying header "Connexion Wi-Fi requise" nor of the footer "QUITTER"

If you have an idea how to do this, please post a comment.

That's all folks…

This Post Has One Comment

  1. Riccardo

    I've tryed your setup and it's working perfectly as a captive portal, but this configuration is not managing the complete request_uri.
    I try to explain: I have to redirect all the people that connects to a particular SSID to when they try to reach any other website, BUT when they try to reach they were redirected to the "homepage" without the "*.com/something".
    I am making a free audioguide for all the people visiting an astrophotography exhibition, pointing the query_uri to the particular photo; for example, is the first photo, is the second one and so on.. pointing the /?1 is useless because they are redirected to the main page.
    I am looking for a way to resolve this issue for like 2 months, reading nginx configuration and other ways.. please HELP!

    If I modify the response of nginx with the line below it works ONLY for the direct query like /?1 /?2 .. but i can't redirect everything to the "home"
    return 302 $scheme://$request_uri

    Thanks in advance for your time.


Leave a Reply