Posted inNetworking

Ditch the Subscription: Building a Production-Grade Captive Portal with Nodogsplash and Nginx

Networking tutorial - IT technology blog
Networking tutorial - IT technology blog

Six Months in Production: Why I Built My Own Gateway

After managing a guest network for a local co-working space with 50+ daily users, I finally pulled the plug on our $600-a-year proprietary controller. Managing public Wi-Fi usually forces you into a corner. You either pay for overpriced enterprise hardware or leave the network wide open and hope for the best. I chose a third path: a self-hosted gateway using Nodogsplash and Nginx on a refurbished Lenovo Tiny PC.

This setup isn’t just about saving money. It is about ownership. By using Nodogsplash (NDS) as the traffic interceptor and Nginx to serve the front-end, you gain absolute control over the branding, user data, and session limits. If you want to provide professional networking services without vendor lock-in, this is the stack you need to master.

The Great Debate: Proprietary vs. Open Source

Before committing to this build, I evaluated the industry standards. Here is how the self-hosted approach stacks up against the hardware I have deployed in the past.

1. The Managed Route (Ubiquiti UniFi, MikroTik)

Most IT shops grab a UniFi Dream Machine. They are reliable and offer a “plug-and-play” experience. However, customizing the splash page often feels like fighting the software. You are frequently limited to basic CSS tweaks. If you need to integrate a custom SQL database for member authentication or a specific third-party API, you will hit a wall almost immediately.

2. The Open Stack (Nodogsplash + Nginx)

This method turns a standard Linux box—even a $35 Raspberry Pi 4—into a sophisticated gateway. Nodogsplash handles the low-level iptables rules to snag client traffic. Nginx then serves a modern, responsive HTML5 page. It is incredibly flexible. However, it does require you to be comfortable with a terminal and basic IP routing.

Why This Setup Wins (and Where It Bites)

The Wins

  • Zero License Fees: You pay $0 in per-user or per-access-point costs. For a small hotel with 20 APs, this can save thousands over three years.
  • Design Freedom: Nginx treats your login page like any other website. You can use Bootstrap, Tailwind, or even React to create a premium user experience.
  • Resource Efficiency: Nodogsplash is written in C. It consumes less than 15MB of RAM even with 100 active clients, making it ideal for edge hardware.
  • Data Collection: I integrated a simple Python script to log guest emails for a marketing newsletter. Commercial vendors usually charge extra for this “feature.”

The Challenges

  • Learning Curve: You need to understand how IP forwarding and network interfaces work.
  • Maintenance: There is no “auto-update” button for the whole stack. You are the sysadmin responsible for security patches.

The Blueprint: Recommended Hardware

For a stable environment that won’t crash when 20 people stream YouTube simultaneously, use this baseline:

  • Hardware: A device with dual Gigabit NICs. A Protectli Vault or a PC with a PCIe Ethernet card works best.
  • OS: Debian 12 (Bookworm) or Ubuntu 22.04 LTS for long-term stability.
  • Software: Nodogsplash for the gateway and Nginx for the web server.

Step-by-Step Implementation

1. Turn Linux into a Router

Your Linux box must pass traffic between the Wi-Fi clients and the internet. Start by enabling IP forwarding in the kernel.

# Edit /etc/sysctl.conf and uncomment this line:
net.ipv4.ip_forward=1

# Apply the change immediately
sudo sysctl -p

2. Install the Software Stack

Nginx is available in every major repo. Nodogsplash is best built from source to ensure you have the latest features and security fixes.

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

# Clone and compile Nodogsplash
git clone https://github.com/nodogsplash/nodogsplash.git
cd nodogsplash
make
sudo make install

3. Configure the Gateway

Open /etc/nodogsplash/nodogsplash.conf. You must specify which interface faces your users (the LAN side). In this example, eth1 is the interface connected to your Wi-Fi Access Points.

# /etc/nodogsplash/nodogsplash.conf
GatewayInterface eth1
GatewayAddress 192.168.10.1
MaxClients 150

# Redirect users to our custom Nginx page
# NDS appends the 'authaction' token to this URL automatically
RedirectURL http://192.168.10.1:8080/portal/

4. Build the Nginx Splash Page

I run Nginx on port 8080 to keep port 80 free for other management tools. Configure a simple virtual host to serve your portal files.

# /etc/nginx/sites-available/captive-portal
server {
    listen 8080;
    root /var/www/portal;
    index index.html;

    location / {
        try_files $uri $uri/ =404;
    }
}

Your index.html needs a bit of JavaScript. When NDS redirects a user, it sends a unique token in the URL. Your “Connect” button must send the user back to that token to unlock their internet access.

<!-- /var/www/portal/index.html -->
<!DOCTYPE html>
<html>
<head><title>Free Guest Wi-Fi</title></head>
<body>
    <h1>Welcome to the Network</h1>
    <a id="login-link" href="#">Click Here to Connect</a>

    <script>
        const params = new URLSearchParams(window.location.search);
        const target = params.get('authaction');
        if (target) {
            document.getElementById('login-link').href = decodeURIComponent(target);
        }
    </script>
</body>
</html>

Hard-Earned Lessons from the Field

Modern smartphones are aggressive. If the “Captive Network Assistant” (that pop-up window that appears when you join Wi-Fi) doesn’t load in under 3 seconds, the phone will often drop the connection and switch back to 5G. Keep your splash page light. Avoid heavy 5MB background images or external fonts that require internet access to load.

Another critical setting is the ClientIdleTimeout. I originally left this at the default, but I found that mobile devices “ghosting” the network were exhausting my IP pool. Setting this to 60 minutes ensures that people who have left the building are cleared out, freeing up addresses for new guests.

Final Verdict

Building your own captive portal is a rite of passage for network admins. It moves you from being a hardware consumer to a network architect. By pairing Nodogsplash’s lean packet filtering with Nginx’s web power, you create a system that is faster, cheaper, and more customizable than almost anything you can buy off the shelf.

Share:
Tags: