How coova/coova-chilli works
Project Type and Purpose
• CoovaChilli is a monolithic, C-based network access controller that provides a captive-portal / walled-garden environment on a Linux gateway. It intercepts user traffic via netfilter/iptables, runs an embedded DHCP and DNS server, and redirects HTTP requests to a mini-portal for authentication against RADIUS or an HTTP backend.
File‐Structure Analysis
• Top‐level directories:
• src/ – core C code (packet I/O, conn tracking, modules: DHCP, DNS, redir, radius, ssl, nat, etc.)
• miniportal/ – templates and scripts for the captive portal UI (CGI, shell wrappers, HTML/TMPL)
• www/ – client-side JavaScript and HTML templates for optional web controller
• conf/ – configuration file templates (chilli.conf, up/down scripts)
• bstring/, json/ – bundled third-party libraries (bstrlib, json-c)
• linux/ under src – netfilter kernel module glue (ipt_coova)
• doc/, INSTALL – user/developer documentation and build instructions
• distro/, debian/, rpm/ – packaging for various Linux distributions
• Build system: Autotools (configure.ac, Makefile.am, bootstrap).
README Insights
• Captive-portal controller using RADIUS or HTTP for auth/accounting
• GPL-licensed, extensible via “sample-mod.c” and module hooks
• Uses standard C libraries plus bundled bstring and json-c
• Linux Host & Network Stack
• Netfilter/Iptables Hook (ipt_coova kernel module)
• Chilli Core (single process)
– Packet Processor & Connection Tracker
– Embedded DHCP Server
– Embedded DNS Resolver/Redirector
– Redirect Engine (HTTP interceptor)
– RADIUS Client Module (src/radius.*)
– SSL/TLS Module (src/mssl, sslSocket)
– Configuration Loader (conf/)
– Logging/Accounting Writer
• Miniportal CGI/Web UI (templates & scripts)
• External Services
– RADIUS Server(s)
– HTTP Auth API (if used)
– Upstream Internet
1. User Device → Ethernet/Wi-Fi → Linux Network Stack
2. Packets hit iptables → sent to CoovaChilli packet processor
3. Unauthenticated clients get DHCP IP, DNS spoof to captive portal
4. HTTP requests → Redirect Engine → miniportal CGI
5. Miniportal → RADIUS Client / HTTP API → External Auth Server → reply
6. On success → Chilli Core updates conn tracking → allows traffic to Upstream
7. Accounting records → written to local file or sent via RADIUS acct
c. Architectural Patterns & Principles
• Modular C code with clear separation of packet I/O, protocol modules, and portal UI
• Embedding third-party libs rather than external dependencies (bstring, json)
• Autotools for portability, distro folders for packaging
• Single process with internal plugin-like modules (via chilli_module.c)
d. Key Technologies & Frameworks
• C, POSIX APIs, Linux netfilter/iptables (libxt_coova)
• Autotools (configure, Makefile.am)
• bstrlib & json-c for string/JSON handling
• Shell & CGI scripts for miniportal
• RADIUS protocol for AAA
Essential Details to Capture
• Packet interception and dispatch via netfilter/iptables
• Internal DHCP and DNS for captive-portal enforcement
• HTTP redirect engine pointing to miniportal scripts
• RADIUS/HTTP backend calls for authentication and accounting
• The flow from “unauthenticated” to “authenticated” state in connection tracker