apfree-wifidog

ApFree WiFiDog

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

🌍 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

---

🚀 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!

• Submit issues: GitHub Issues
• Pull requests: GitHub PRs
• Guidelines: CONTRIBUTING.md

---

📬 Contact

• QQ Group: 331230369

---