Build Your Own Captive Portal with nodogsplash: Professional Public Wi-Fi Control on Linux

Why Does Public Wi-Fi Need a “Gatekeeper”?

You’ve likely experienced walking into a cafe, connecting to the Wi-Fi, and seeing a page pop up asking you to click “Connect” or enter a voucher code. That is a Captive Portal. Technically, it acts as a checkpoint. Even if you’ve caught the Wi-Fi signal, all web access requests are blocked until you perform a specific action on the splash page.

Instead of using traditional WPA2 passwords that are easily leaked, a Captive Portal offers superior professionalism and security. With this solution, you can:

• Force users to agree to Terms of Service (TOS) to avoid legal issues.
• Promote your brand or collect customer emails.
• Limit each session to 60-120 minutes to prevent users from overstaying.
• Throttle bandwidth to 2-5Mbps, preventing torrent downloads from choking the entire network.

I clearly remember troubleshooting a Wi-Fi hotspot with 50 connected devices where the network was nearly paralyzed. After checking, it turned out 5-6 smartphones were automatically running cloud backups as soon as they saw the Wi-Fi. Implementing a Captive Portal right then helped me filter out transient connections and stabilize the system in minutes.

In this guide, we will use nodogsplash. This is an extremely lightweight tool (using only about 2-5MB of RAM), highly stable, and runs smoothly on everything from a Raspberry Pi to old routers running OpenWrt.

Installation Process for nodogsplash on Linux

You need a Linux machine (Ubuntu/Debian) with two network cards. One card for Internet access (WAN) and one to broadcast Wi-Fi or connect to a Switch for users (LAN).

1. Preparing the Environment

First, update your system and install the necessary libraries to compile the source code:

sudo apt update
sudo apt install git libmicrohttpd-dev build-essential -y

2. Compiling nodogsplash from Source

To get the latest version with full features, building from source is the best choice:

git clone https://github.com/nodogsplash/nodogsplash.git
cd nodogsplash
make
sudo make install

Once completed, all your configuration files will be located in the /etc/nodogsplash directory.

Configuring the Redirection Engine

The next task is to tell nodogsplash which network interface it needs to guard.

1. Setting up the nodogsplash.conf file

Use the nano editor to open the configuration file:

sudo nano /etc/nodogsplash/nodogsplash.conf

Pay attention to the following key parameters:

• GatewayInterface: The user-facing network card name (e.g., wlan0 or eth1). Check quickly with the ip link show command.
• GatewayAddress: The static IP of the Linux machine in the local network (usually 192.168.1.1).
• MaxClients: Limit the number of users (e.g., 50) to ensure hardware isn’t overloaded.

Practical configuration example:

GatewayInterface eth1
GatewayAddress 192.168.10.1
MaxClients 50
AuthIdleTimeout 60
CheckInterval 30

The AuthIdleTimeout 60 parameter is very valuable. If a client doesn’t use the network for 60 minutes, the system will automatically disconnect them to make room for others.

2. Customizing the Splash Page with Your Own Style

The default splash page is located at /etc/nodogsplash/htdocs/splash.html. You can change the logo, colors, or add promotions using simple HTML/CSS. However, don’t forget to keep this crucial authentication code snippet:

<form method="GET" action="$authaction">
    <input type="hidden" name="tok" value="$tok">
    <input type="hidden" name="redir" value="$redir">
    <input type="submit" value="Connect Now">
</form>

Operation and Administration

Start the service with the command:

sudo nodogsplash

Try connecting with your personal phone. If a notification pops up saying “Sign in to Wi-Fi network”, congratulations, you’ve succeeded!

Managing Users with ndsctl

The ndsctl tool is a powerful assistant that helps you monitor the system in real-time.

To see the list of online users:

sudo ndsctl status

If you encounter someone using too much bandwidth or behaving maliciously, you can “invite” them off the network immediately:

sudo ndsctl deauth [MAC_ADDRESS]

Technical Note: Sometimes the splash page won’t automatically appear on HTTPS sites due to HSTS security mechanisms. If guests complain, instruct them to visit an HTTP-only site like neverssl.com to trigger the nodogsplash filter.

System Automation

To have the system run automatically after a power outage or server reboot, you should add nodogsplash to systemd. This ensures your network infrastructure is always ready without manual intervention.

Deploying a Captive Portal is not just about technology; it’s about elevating the user experience. With nodogsplash, you have a solution that is both lightweight and more powerful than bulky systems like PacketFence.