README.md

August 19, 2025 Β· View 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