OpenWrt Custom Firmware Integration with Purple WiFi

Executive summary

OpenWrt is the firmware of choice for IT teams who need hardware independence without sacrificing enterprise-grade control. Deployed across hospitality, retail, and public-sector venues, it provides a fully configurable Linux-based network stack. But out of the box, OpenWrt is a blank canvas. Without a structured identity layer, guest networks become unmanageable, staff networks remain insecure, and multi-tenant environments collapse into a single flat network.

This guide provides the definitive integration playbook for connecting OpenWrt to Purple's cloud RADIUS and captive portal platform. We cover four distinct deployment scenarios: guest captive portal redirection using CoovaChilli, iptables walled garden configuration, secure staff WiFi using hostapd with IEEE 802.1X, and multi-tenant segmentation using Private Pre-Shared Keys (PPSK) with dynamic VLAN assignment. By the end, you will have the exact configuration parameters, the common failure modes, and the decision frameworks needed to deploy a production-ready, GDPR-compliant, identity-driven network on any OpenWrt-capable hardware.

Purple operates across 80,000+ live venues and has processed 440 million logins in 2024 (Purple internal data, 2024). The architecture described here is the same one deployed at scale across hospitality chains, retail estates, and transport hubs.

Technical deep-dive

The CoovaChilli captive portal architecture

When deploying Guest WiFi on OpenWrt, CoovaChilli is the industry-standard access controller. It operates as a captive portal daemon that intercepts unauthenticated client traffic, provisions IP addresses via its internal DHCP server on the tun0 virtual interface, and enforces walled garden policies using iptables rules it manages directly.

The authentication flow works as follows. A guest device associates with the open SSID. CoovaChilli assigns the device an IP address from its internal pool (typically 10.1.0.0/24). When the device sends its first HTTP request, CoovaChilli intercepts it and issues an HTTP 302 redirect to the Purple splash page URL. During this pre-authentication phase, the device is isolated - it can only reach the domains explicitly listed in the walled garden.

Once the guest authenticates on the Purple portal, Purple's cloud RADIUS server sends an Access-Accept message to CoovaChilli on UDP port 1812. CoovaChilli then updates its iptables rules to permit internet access for that specific MAC address and begins transmitting accounting data (session duration, bytes transferred) to the Purple RADIUS accounting server on UDP port 1813. Accounting is not optional - it is the mechanism by which Purple populates your WiFi Analytics dashboard with session data.

Walled garden: iptables and domain allowlists

The walled garden is the most operationally critical configuration element in any captive portal deployment. CoovaChilli manages the walled garden through two mechanisms: the uamallowed parameter for individual IP addresses and the uamdomains parameter for domain-based allowlisting with DNS inspection.

For a Purple integration, the minimum required walled garden entries are:

Note on Apple CNA management: If you include captive.apple.com in the walled garden, iOS devices will detect internet connectivity pre-authentication and suppress the Captive Network Assistant pop-up. Most hospitality deployments deliberately exclude this domain to trigger the automatic portal prompt. The correct choice depends on your guest experience design.

Secure staff WiFi: hostapd and IEEE 802.1X

Guest networks demand frictionless onboarding. Staff networks demand absolute security. For internal users, OpenWrt uses hostapd to facilitate IEEE 802.1X authentication. In this architecture, the OpenWrt access point acts as the Authenticator, forwarding Extensible Authentication Protocol (EAP) messages between the client device (Supplicant) and the Purple RADIUS server.

For corporate devices, EAP-TLS is the mandated standard. It relies on mutual certificate authentication - both the server and the client device present digital certificates - entirely eliminating passwords and the associated risks of credential theft or phishing. For environments not yet ready for a full Public Key Infrastructure (PKI), PEAP-MSCHAPv2 provides a reasonable interim option, using an encrypted tunnel to protect username and password credentials.

When a staff member authenticates successfully, the RADIUS server returns authorization attributes. The key attribute for network segmentation is Tunnel-Private-Group-ID, which instructs OpenWrt to dynamically assign the user to the correct VLAN. This is the mechanism behind Identity-Based Networks: the user's identity, not their physical location, determines their network access.

Multi-tenant segmentation: OpenWrt PPSK configuration

In multi-tenant environments - coworking spaces, build-to-rent (BTR) properties, retail centres with multiple vendors, or stadiums with separate sponsor zones - broadcasting multiple SSIDs is operationally expensive and RF-inefficient. Each additional SSID adds management frame overhead, reducing available airtime for data traffic.

Private Pre-Shared Keys (PPSK), sometimes called dynamic PSK, solve this. You broadcast a single SSID. When a device attempts to connect, hostapd sends the device's MAC address to the RADIUS server via a standard Access-Request. The RADIUS server validates the MAC address against its database and returns an Access-Accept containing two critical attributes: the Tunnel-Password attribute (the unique passphrase for that device) and the Tunnel-Private-Group-ID attribute (the VLAN assignment). The device connects using its unique passphrase and is placed directly onto its assigned VLAN.

This means a retail manager and an event attendee can connect to the identical SSID but be routed to entirely separate, isolated networks based on their unique identity.

Implementation guide

Step 1: Retrieve Purple RADIUS credentials

Before touching the OpenWrt configuration, retrieve the following from the Purple portal admin console:

• Primary RADIUS Server IP address
• Secondary RADIUS Server IP address (for failover)
• RADIUS Shared Secret
• Captive Portal Splash Page URL
• Post-authentication redirect URL

Step 2: Install and configure CoovaChilli for guest WiFi

Install the coova-chilli package via opkg:

opkg update && opkg install coova-chilli

The primary configuration file is /etc/chilli/defaults. Define the core network parameters:

# Network interfaces
HS_WANIF=eth0           # Upstream internet interface
HS_LANIF=wlan0          # The guest WiFi interface (or a VLAN sub-interface)

# Guest subnet
HS_NETWORK=10.10.20.0
HS_NETMASK=255.255.255.0
HS_UAMLISTEN=10.10.20.1 # CoovaChilli's IP on the guest network
HS_UAMPORT=3990

# Purple RADIUS integration
HS_RADIUS=
HS_RADIUS2=
HS_RADSECRET=
HS_NASID=venue-openwrt-01

# Purple splash page
HS_UAMSERVER=

# Walled garden - domain-based allowlisting
HS_UAMDOMAINS=".purple.ai,.googleapis.com,.gstatic.com,.facebook.com,.fbcdn.net"

Enable and start the service:

/etc/init.d/chilli enable
/etc/init.d/chilli start

Step 3: Configure the OpenWrt wireless interface for the guest SSID

In /etc/config/wireless, define the guest SSID as an open network bound to the interface CoovaChilli will manage:

config wifi-iface 'guest_wifi'
    option device 'radio0'
    option network 'guest'
    option mode 'ap'
    option ssid 'Venue_Guest'
    option encryption 'none'
    option isolate '1'

Client isolation (isolate '1') prevents guest devices from communicating with each other - a mandatory security control for any shared network.

Step 4: Configure hostapd for 802.1X staff WiFi

For the staff SSID, configure WPA2-Enterprise in /etc/config/wireless:

config wifi-iface 'staff_wifi'
    option device 'radio0'
    option network 'staff_vlan10'
    option mode 'ap'
    option ssid 'Venue_Staff'
    option encryption 'wpa2'
    option server ''
    option port '1812'
    option key ''
    option dynamic_vlan '2'
    option vlan_tagged_interface 'eth0'
    option vlan_bridge 'br-vlan'
    option vlan_naming '0'

Setting dynamic_vlan '2' instructs hostapd to enforce the VLAN assignment returned by the RADIUS server, and to reject authentication if no VLAN is returned.

Package requirement: The standard wpad-mini package does not support WPA2-Enterprise. You must install wpad or wpad-openssl:

opkg remove wpad-mini && opkg install wpad-openssl

Step 5: Configure PPSK for multi-tenant segmentation

PPSK requires hostapd to perform MAC address authentication against the RADIUS server, which then returns the per-device passphrase. In /etc/config/wireless:

config wifi-iface 'ppsk_ssid'
    option device 'radio0'
    option mode 'ap'
    option ssid 'Venue_Connect'
    option encryption 'psk2'
    option key 'default_fallback_key'
    option macfilter 'radius'
    option server ''
    option port '1812'
    option key ''
    option dynamic_vlan '2'
    option vlan_tagged_interface 'eth0'
    option wpa_psk_radius '2'

The wpa_psk_radius '2' parameter instructs hostapd to require the Tunnel-Password attribute from the RADIUS response. If the RADIUS server does not return a passphrase, authentication is rejected.

On the Purple RADIUS side, the authorize section of your FreeRADIUS configuration (or equivalent) maps MAC addresses to passphrases and VLAN IDs:

# Example RADIUS authorize entry for PPSK
AA:BB:CC:DD:EE:FF   Auth-Type := Accept
    Tunnel-Password = "GuestPass2024",
    Tunnel-Type = VLAN,
    Tunnel-Medium-Type = IEEE-802,
    Tunnel-Private-Group-ID = "20"

Step 6: Configure dynamic VLAN assignment

For dynamic VLAN assignment to function, your OpenWrt switch must be configured to carry the relevant VLANs as tagged traffic on the trunk port connecting to your core switch. In /etc/config/network:

config interface 'vlan10'
    option ifname 'eth0.10'
    option proto 'dhcp'

config interface 'vlan20'
    option ifname 'eth0.20'
    option proto 'dhcp'

config interface 'vlan30'
    option ifname 'eth0.30'
    option proto 'dhcp'

Ensure your core switch port is configured as a trunk, passing VLANs 10, 20, and 30 tagged.

Best practices

Absolute network segregation. Never bridge guest interfaces with internal networks. Guest traffic must be isolated on a dedicated VLAN and routed directly to the internet firewall. This is a non-negotiable requirement for PCI DSS 4.0 compliance, which mandates that guest WiFi networks be completely isolated from any network segment handling cardholder data.

Walled garden precision. An incomplete walled garden is the primary cause of captive portal failures. Use your browser's developer tools on a test device connected to the guest SSID to identify which requests are blocked pre-authentication. Every blocked domain is a potential portal failure.

RADIUS accounting intervals. Configure the CoovaChilli accounting interim interval to 120 seconds. This provides near real-time session data in the Purple analytics dashboard without generating excessive RADIUS traffic.

Secondary RADIUS server. Always configure HS_RADIUS2 in your CoovaChilli config. If the primary Purple RADIUS server is unreachable, CoovaChilli will fail to authenticate new sessions. The secondary server provides automatic failover with no configuration change required at the access point.

Package selection. The wpad-mini package bundled with many OpenWrt builds does not support WPA2-Enterprise or dynamic VLAN assignment. Always install wpad-openssl for any deployment requiring 802.1X or PPSK.

For further guidance on enterprise WiFi security architecture, see our Enterprise WiFi Security: A Complete Guide for 2026 .

Troubleshooting & risk mitigation

GDPR compliance note: CoovaChilli itself does not capture or store personal data. All consent capture, data processing, and GDPR compliance mechanisms are handled by the Purple platform at the portal layer. Ensure your Purple portal is configured with your venue's terms and conditions and data processing notice before go-live.

For related hardware integration patterns, see our guides on EnGenius Cloud Access Points Integration with Purple WiFi and DrayTek Vigor Routers and Access Points Integration with Purple WiFi .

ROI & business impact

Transitioning from basic PSK networks to a Purple-managed OpenWrt architecture delivers measurable impact across three dimensions.

Data capture and marketing. By enforcing captive portal authentication, venues capture compliant, first-party demographic data - names, email addresses, social profiles - at the point of WiFi connection. This data feeds directly into CRM and email marketing platforms, driving loyalty programme sign-ups and enabling targeted campaigns. Purple has processed 440 million logins in 2024 (Purple internal data), demonstrating the scale of first-party data capture possible at the network edge.

Operational efficiency. Implementing PPSK reduces SSID overhead, improving WiFi performance in dense environments. For a 200-location retail chain, centrally managing identity via Purple's cloud RADIUS - rather than updating local router configurations at each site - saves hundreds of engineering hours annually. A single RADIUS policy change propagates to all 200 locations instantly.

Security and compliance. Dynamic VLAN assignment enforces least-privilege access at the edge. Staff are isolated from guests. IoT devices are isolated from staff. POS terminals are isolated from all other traffic. This segmentation satisfies PCI DSS 4.0 network isolation requirements and provides a clear, auditable network topology for GDPR compliance reviews.

For vertical-specific deployment patterns, see our guides for Retail , Hospitality , Healthcare , and Transport environments. You may also find our guide on What Is Wireless Display: Protocols & Best Practices 2026 useful for understanding complementary wireless technologies in venue deployments.