# ApFree WiFiDog: an HTTP(S) captive portal for OpenWrt routers

> ApFree WiFiDog is a C implementation of the WiFiDog captive portal model, rewritten around libevent2, epoll and API-driven iptables calls so it can handle high concurrency on OpenWrt. It keeps the familiar wifidog configuration model and adds a wdctlx control tool, a LuCI web interface and an eBPF traffic control path.

**liudf0716/apfree-wifidog** — apfree-wifidog is a high-performance captive portal solution that serves as a gateway between your wireless networks and the Internet. Optimized for both HTTP and HTTPS traffic, it ensures secure border control while enabling seamless user authentication and efficient network management. 购买下面的链接中的服务支持我的开源

- Repository: https://github.com/liudf0716/apfree-wifidog
- Website: https://buymyai.ai.studio/
- Stars: 938 · Forks: 308
- Language: C
- License: GPL-3.0
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/liudf0716-apfree-wifidog

## A portal that lives on the router, not beside it

ApFree WiFiDog is a captive portal for HTTP and HTTPS traffic, tailored for the OpenWrt platform, written in C. The problem it solves is the classic hotspot one: clients join a Wi-Fi network, get a login page, and stay locked out of the internet until they authenticate. WiFiDog established the shape of that solution and the ApFree variant keeps the same vocabulary, down to the `wifidogx.conf` configuration file and the `wifidog-msg.html` and `wifidog-redir.html` templates in the repository root. What changes is the implementation. The README describes the project as providing secure authentication, high concurrency handling and flexible rule management for Wi-Fi networks, and the repository layout backs that up with `src/`, `include/`, `doc/`, `scripts/`, `test/` and an `AUTH_SERVER_API_EN.md` describing the protocol the external server speaks. The audience is an operator or network integrator with an OpenWrt device and a need to control who gets internet access.

## libevent2 and epoll replace the original loop

The performance claim is structural rather than tuned. The feature list states that the project is built with libevent2 plus epoll and that it far outperforms original WiFiDog, and the technical overview repeats that the event-driven architecture through libevent2 is there for massive concurrency. The original wifidog is a small blocking process with a per-connection thread for its HTTP work, which does not scale to a venue full of phones reconnecting at once. Moving to an event-driven model means one process handles many sockets without a thread per client, and epoll is the Linux mechanism that makes that efficient on the sort of embedded MIPS or ARM routers OpenWrt usually runs on. The firewall path was moved the same way: instead of shelling out to iptables, the project uses API-based iptables integration and describes it as thread-safe, which removes both a fork-per-rule cost and a race between concurrent rule updates. Repository topics confirm the shape of the build with libevent, iptables and openwrt among them.

## Redirect, authenticate, rewrite the firewall

The authentication flow is given in four steps: redirect, auth server, firewall update, internet access. A client that hits the network is redirected to the captive portal page, the portal asks an authentication server whether to admit it, the firewall rules are then updated to allow that client through, and only then does the client reach the internet. The protocol details live in `AUTH_SERVER_API_EN.md`, with an `AUTH_SERVER.md` and an `apfree-wifidog_mqtt_protocol` directory in the tree covering the messaging side. Two configuration shapes exist. Cloud authentication mode needs an external auth server and is set through the LuCI fields `Auth Server` with hostname, port and path, plus a `Gateway Interface`, and it can enable WebSocket support for real-time status. Local authentication, described as splash page mode, needs no external server: it takes a `Gateway Interface` and a redirect URL for a welcome or terms page, and can be a simple click-to-continue or a custom splash page. Real-time long connections over WebSocket or MQTT are listed as features, which matters when the status of a session has to be visible without polling.

## Installing on OpenWrt: apk or opkg

Installation is handled by the OpenWrt package manager, and the choice depends on the release. On the latest OpenWrt the package manager is apk:

```bash
apk update
apk add apfree-wifidog
```

On older OpenWrt releases the same package is installed with opkg:

```bash
opkg update
opkg install apfree-wifidog
```

That split is the single most common stumbling block for newcomers, because the two commands are not interchangeable on the same firmware and copying the wrong one simply fails with an unknown package error. There is a web interface too: the project ships a LuCI app named `luci-app-apfree-wifidog`, published in the maintainer's own luci repository, and the README recommends the `chawrt` project for people who would rather have ApFree WiFiDog and LuCI bundled into a ready-to-use OpenWrt firmware image. Both paths land you on the same daemon; the LuCI app is the configuration surface, and `wifidogx.conf` is where the underlying settings live.

## wdctlx is the operator's window into the daemon

Because the portal runs on a small embedded device, day-to-day management happens over a command line tool rather than by editing rules by hand. The README lists a set of `wdctlx` commands that cover the operations an operator actually needs:

```bash
wdctlx status client       # Show authenticated clients
wdctlx show domain         # Show trusted domains
wdctlx add domain example.com
wdctlx apfree user_list    # List online users
```

The design point is that rules are dynamic. The feature list calls out managing MAC, IP and domains without a restart, so `wdctlx add domain` takes effect on a running daemon instead of requiring an edit and reload of `wifidogx.conf`. The same dynamic behaviour shows up in the troubleshooting notes, where blocked sites are fixed by updating trusted domains through `wdctlx show domain` and device problems are investigated through the MAC lists with `wdctlx show mac`. When something is wrong, `logread` is the first stop, and the debug level in `wifidogx.conf` can be raised with `DaemonLogLevel 7` to get the detail needed to see which stage of the flow failed.

## Where ApFree WiFiDog is the wrong choice

The platform assumption is the hard limit. Everything in the README assumes OpenWrt, with apk or opkg, a LuCI web interface, logread for system logs and `wifidogx.conf` as the configuration file. On a Linux server or a proprietary router the package path simply does not exist. The second limit is the firewall mechanism. The project integrates with iptables, with nftables support, and lists eBPF for traffic control and DPI, but the mechanism is a local firewall rewrite driven by an external server's answer, which means the deployment depends on an authentication server you operate or trust, with its own latency and availability. The project also does not document the classic wifidog gateway authentication protocol in the README, so operators who expect that older handshake should check the protocol documentation in `AUTH_SERVER_API_EN.md` before committing. Nothing in the repository suggests the daemon is meant to run anywhere other than the access point itself, and no read-only or reporting mode is documented for teams that only want visibility.

## GPL-3.0 with a fast release train

The licence field on the repository says GPL-3.0, and the `COPYING` file sits at the repository root alongside a GPLv3 badge. For an appliance-style daemon that a vendor might want to ship inside a router image, the licence terms need reading before the software is embedded in a product, and only a qualified reviewer should interpret what the obligations mean for a derived work. The project is also used commercially by its author, since the repository description points to a store where the underlying service can be bought, so the relationship between the open source tree and the paid offering is worth understanding before you build on it. On the release side the cadence is quick: version 9.05.2872 on 2026-06-01, 9.07.2907 on 2026-07-20 and 9.09.2938 on 2026-09-06, with the last push on 2026-10-13. Version numbers carry the release date, so the tags read as a timeline rather than as a semver sequence.

## Conclusion

ApFree WiFiDog fits operators who already run OpenWrt and need a captive portal that survives real client counts, either with an external authentication server or a built-in splash page, and who are comfortable editing wifidogx.conf and running wdctlx on the device. It does not fit teams that need a captive portal on a platform other than OpenWrt, or that need MAC-based authentication as described in the classic wifidog protocol, since the project documents neither. Before deploying it, verify your OpenWrt release uses apk rather than opkg, confirm the auth server implements the protocol in AUTH_SERVER_API_EN.md, and test the redirect path with wifidogx.conf set to DaemonLogLevel 7 so firewall misses show up in logread.

## FAQ

### How do I install ApFree WiFiDog on OpenWrt?

On the latest OpenWrt run apk update followed by apk add apfree-wifidog. On older OpenWrt releases the equivalent commands are opkg update and opkg install apfree-wifidog.

### Does ApFree WiFiDog need an external authentication server?

Not always. Cloud authentication mode requires an external auth server configured through the LuCI Auth Server fields, while local authentication in splash page mode needs no external server and only requires a Gateway Interface plus a redirect URL.

### How do I see which clients are authenticated on the router?

Use the wdctlx control tool. wdctlx status client shows authenticated clients, wdctlx apfree user_list lists online users, and wdctlx show mac displays the MAC lists, with logread for the system log.

## Sources

- [License: GPL-3.0](https://github.com/liudf0716/apfree-wifidog/blob/master/LICENSE)
- [liudf0716/apfree-wifidog on GitHub](https://github.com/liudf0716/apfree-wifidog)
- [Project website](https://buymyai.ai.studio/)
- [README](https://github.com/liudf0716/apfree-wifidog/blob/master/README.md)
- [Releases](https://github.com/liudf0716/apfree-wifidog/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/liudf0716-apfree-wifidog