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. 技术交流QQ群 331230369

View project on GitHub

ApFree WiFiDog Logo

ApFree WiFiDog

A High-Performance Captive Portal Solution for HTTP(S) on OpenWrt

License PRs Welcome Issues Welcome Release Platform QQ Group

🌍 English | 🇨🇳 中文 | 📑 Auth Server API

📖 Introduction

ApFree WiFiDog is an open-source, high-performance captive portal for HTTP and HTTPS, tailored for the OpenWrt platform.
It provides secure authentication, high concurrency handling, and flexible rule management for Wi-Fi networks.

🎬 Introduction Video

ApFree WiFiDog Introduction

🚀 Features

  • Stable – API-based iptables integration, thread-safe.
  • Fast – Built with libevent2 + epoll, far outperforms original WiFiDog.
  • Secure – Full HTTPS redirection support.
  • Real-time – Long connection support (WebSocket, MQTT).
  • Flexible – Local + Cloud authentication, splash page mode.
  • Dynamic Rules – Manage MAC, IP, domains without restart.
  • eBPF Support – Traffic control & DPI via eBPF.
  • Active Community – Fast responses and continuous updates.

📦 Installation

On OpenWrt (latest):

apk update
apk add apfree-wifidog

On older OpenWrt:

opkg update
opkg install apfree-wifidog

👉 For LuCI Web Interface, see LuCI Integration.

🖥️ LuCI Integration

  • ApFree WiFiDog provides a LuCI Web UI via luci-app-apfree-wifidog.
  • Integrated in the luci repo.

💡 Recommended: use chawrt,
which bundles ApFree WiFiDog + LuCI for a ready-to-use OpenWrt firmware.

⚙️ Basic Usage Example

1. Cloud Authentication Mode

  • Requires external auth server.
  • Configure via LuCI: Auth Server (Hostname, Port, Path) + Gateway Interface.
  • Enable WebSocket Support for real-time status.

2. Local Authentication (Splash Page)

  • No external auth server needed.
  • Configure LuCI: Gateway Interface + Redirect URL (welcome / terms page).
  • Simple click-to-continue or custom splash page.

🛠️ Troubleshooting

Logs

  • Check via: 
    logread
  • Increase debug level in wifidogx.conf → DaemonLogLevel 7.

Common Issues

  • No redirection → check GatewayInterface, firewall rules, DNS.
  • Sites blocked → update trusted domains via wdctlx show domain.
  • Device issues → check MAC lists (wdctlx show mac).

Useful wdctlx Commands

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

🔬 Technical Overview

  • Event-driven architecture (libevent2) for massive concurrency.
  • Firewall integration via iptables (with nftables support).
  • Auth flow: Redirect → Auth Server → Firewall update → Internet access.

📑 See Auth Server API for protocol details.

🤝 Contributing

We welcome contributions!

📬 Contact