Nodogsplash: the small captive portal that shows one Continue button

A splash page in front of a restricted connection

Nodogsplash is a captive portal, and the description in the repository says it plainly: it offers a simple way to provide restricted access to an Internet connection by showing a splash page to the user before Internet access is granted. In its most basic form the splash page contains a Continue button, and pressing it opens access subject to a preset time interval.

That is the whole product. The project positions itself as a high performance, small footprint captive portal, optimised for target devices with limited resources, which points straight at embedded routers and small access points rather than at a datacentre or a campus network. The code is C, the build produces two small binaries, and the configuration is a single file.

The ancestry is worth knowing because it explains the shape of the code. Nodogsplash was derived originally from the codebase of the Wifi Guard Dog project, and the project still links back to the original Wifi Guard Dog repository. It is released under the GNU General Public License, which is the licence recorded for the repository as well. If you link it into a device or a product, the GPL obligations for that combined work are the part you need to think about with your own legal team, since this is a licence question rather than a technical one.

Captive Portal Detection is the trigger, not the user

The mechanism starts without the user doing anything. All modern mobile devices, most desktop operating systems and most browsers run a Captive Portal Detection process that automatically issues a port 80 request when they connect to a network. Nodogsplash detects that probe and answers it with the splash page.

This is the detail that separates a captive portal from a walled garden you have to opt into yourself. There is no browser banner to click, no DNS redirection to a login host. The operating system makes the request, the portal answers, and the human sees the splash page afterwards. Nodogsplash does the detecting and serving; it does not need to own DNS or rewrite traffic to get the user to the right page.

What the daemon does with the connection after that is where the design narrows. The portal grants access, and it does so on a timer rather than against an identity. Nothing in the project description suggests a user database, a password check, a coupon code or a policy engine. If the deployment needs any of those, this is the wrong tool, and the project says so itself further down.

Access is granted for a preset interval, and nothing more

The access model is a single preset time interval. A user clicks Continue, and the connection is allowed for the period configured in advance. The natural consequence is that the portal is a speed bump rather than a gate: once the timer expires the user is back at the splash page, and any device that can replay the flow can get another interval.

This is what separates Nodogsplash from a system with a real session and identity behind it. There is no per user record, no accounting and no policy that differs by who is asking. For an open guest network in a cafe or a small office where the goal is to make the terms visible and to slow down casual abuse, that is enough. For a network where access needs to be attributable to a person, it is not enough, and no configuration of the splash page will change that.

The one integration point offered to anyone who needs more control is outside the portal. Nodogsplash does not currently support traffic control, and the project states that it is fully compatible with other standalone systems such as Smart Queue Management, which is where shaping and fairness are expected to live. So the division of labour is explicit: Nodogsplash handles the splash and the access timer, another system handles the queue.

Building nodogsplash and ndsctl against libmicrohttpd

The build is a plain GNU Makefile and needs no autotools ceremony. The compiler defaults and flags are short, and the HTTP server library is linked in directly:

CC?=gcc
CFLAGS?=-O2 -g -Wall
CFLAGS+=-Isrc
LDFLAGS+=-pthread
LDLIBS=-lmicrohttpd

The default target builds two binaries, nodogsplash and ndsctl, and the object list names the modules that make up the daemon: auth, client_list, commandline, conf, fw_abstract, fw_common, fw_iptables, path, main, http_microhttpd, http_microhttpd_utils, ndsctl_thread, safe, tc, util and template. Reading that list tells you more about the design than any paragraph would. There is a dedicated firewall layer with an iptables implementation, a client list module that holds the state of connected devices, a safe module, and a template module for the splash page.

Two build switches are worth knowing. STRIP defaults to yes, so the install step strips the binaries. ENABLE_STATE_FILE also defaults to yes, and when it is on the build adds -DWITH_STATE_FILE and links jansson as well, which is the JSON library behind the state file. Turn that switch off and the daemon compiles without the state file support and without the jansson dependency. The microhttpd library itself is not optional in the default configuration.

The install target writes one config file and three pages

Installing is a file copy, and the target shows exactly what a deployment looks like on disk:

mkdir -p $(DESTDIR)/etc/nodogsplash/htdocs/images
cp resources/nodogsplash.conf $(DESTDIR)/etc/nodogsplash/
cp resources/splash.html $(DESTDIR)/etc/nodogsplash/htdocs/
cp resources/splash.css $(DESTDIR)/etc/nodogsplash/htdocs/
cp resources/status.html $(DESTDIR)/etc/nodogsplash/htdocs/
cp resources/splash.jpg $(DESTDIR)/etc/nodogsplash/htdocs/images/

The layout is minimal and readable. Configuration sits in /etc/nodogsplash/nodogsplash.conf, and the web assets the daemon serves live beside it in htdocs: splash.html and splash.css for the page the user sees, status.html for the status view, and an images directory that holds splash.jpg. The two executables, nodogsplash and ndsctl, are installed into /usr/bin, with DESTDIR respected for packaging.

Two further targets round out the workflow. The tests target recurses into the tests directory and builds the test suite, and there is a checkstyle target that requires astyle to be installed, aborting with a message if it is missing, and then runs astyle in dry run mode over src/*.c and src/*.h with the kr style, tab indentation and forced tabs. That style check is a useful signal about what the project expects from a patch, since it is enforced rather than mentioned. The repository also carries a debian directory, so a distribution package path exists alongside the manual install.

The split that created openNDS

Nodogsplash is the smaller half of what used to be one project, and the documentation is unusually direct about it. The project has been split into two: OpenNDS, which contains the FAS, the Forward Authentication Service, and Nodogsplash itself, which contains a minimal version. OpenNDS was forked from version 4.x at commit 4bd2f00166ed17ac14f9b78037fce5725bd894ce, while Nodogsplash was forked from 3.x at commit 28541e787c989589bcd0939d3affd4029a235a3a. The first version with different code bases is version 5.0.

That history is the clearest guidance the project gives about choosing between them. If you want a more sophisticated authentication system providing a dynamic web interface, the documentation says you need openNDS rather than Nodogsplash. The difference in approach is therefore about scope, not about implementation style. Nodogsplash keeps the splash page and the access interval, and it stays small enough for constrained devices. OpenNDS keeps the same captive portal detection idea but adds the authentication service and a dynamic web interface.

There is a third path worth noting for anyone who wants shaping rather than authentication. Nodogsplash does not support traffic control itself, but it works alongside standalone systems such as Smart Queue Management, so bandwidth fairness can be handled by a separate component while the splash page and access timer stay in Nodogsplash.

Releases stopped in 2023 while the tree kept moving

The recorded releases are Nodogsplash 5.0.2 and Nodogsplash 3.2.1, both dated 2023-10-09, and Nodogsplash 5.0.1 from 2023-07-22. The repository is not archived and the last push was on 2026-09-25, so there have been commits well after the newest tag.

Read those two facts together rather than separately. If you want a released, dated artifact, the tags are the only anchor points available, and the newest is from 2023. If you want the current state of the code, you are taking whatever is on the default branch, main, which is newer than any tag. The split at version 5.0 also means the two code bases diverged.

Full documentation lives on readthedocs at https://nodogsplash.readthedocs.io/en/latest/, and the documentation set can be read either as Stable or as Latest. That choice maps onto the same tension: the stable docs describe the released behaviour, while the latest docs may describe code that has not been tagged. Pick the documentation that matches the binary you actually ship.

Editorial conclusion

Nodogsplash suits operators of small embedded routers and guest networks that only need a splash page and a timed access window, and it fits teams willing to maintain C code under the GPL. Skip it if you need per user authentication, a dynamic portal interface or traffic control, since the project points at openNDS for the first two and states plainly that it does not support the third. Before you deploy, verify that libmicrohttpd and jansson are present on the target, because the Makefile links both and the state file is only compiled in when ENABLE_STATE_FILE is yes.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-2.0
3. nodogsplash/nodogsplash on GitHub
4. README
5. Releases