OpenWrt Custom Firmware Integration with Purple WiFi

Resumo executivo

O OpenWrt é o firmware de escolha para equipes de TI que precisam de independência de hardware sem sacrificar o controle de classe empresarial. Implantado em ambientes de hospitalidade, varejo e setor público, ele fornece uma pilha de rede baseada em Linux totalmente configurável. Mas, pronto para uso, o OpenWrt é uma tela em branco. Sem uma camada de identidade estruturada, as redes de convidados tornam-se incontroláveis, as redes de funcionários permanecem inseguras e os ambientes multi-tenant entram em colapso em uma única rede plana.

Este guia fornece o roteiro definitivo de integração para conectar o OpenWrt ao RADIUS em nuvem e à plataforma de Captive Portal da Purple. Cobrimos quatro cenários distintos de implantação: redirecionamento de Captive Portal de convidados usando CoovaChilli, configuração de walled garden por iptables, WiFi seguro para funcionários usando hostapd com IEEE 802.1X e segmentação multi-tenant usando Private Pre-Shared Keys (PPSK) com atribuição dinâmica de VLAN. Ao final, você terá os parâmetros exatos de configuração, os modos de falha comuns e as estruturas de decisão necessárias para implantar uma rede orientada por identidade, pronta para produção e em conformidade com a GDPR em qualquer hardware compatível com OpenWrt.

A Purple opera em mais de 80.000 locais ativos e processou 440 milhões de logins em 2024 (dados internos da Purple, 2024). A arquitetura descrita aqui é a mesma implantada em grande escala em redes de hospitalidade, redes de varejo e hubs de transporte.

Aprofundamento técnico

A arquitetura do Captive Portal CoovaChilli

Ao implantar o Guest WiFi no OpenWrt, o CoovaChilli é o controlador de acesso padrão do setor. Ele opera como um daemon de Captive Portal que intercepta o tráfego de clientes não autenticados, fornece endereços IP por meio de seu servidor DHCP interno na interface virtual tun0 e impõe políticas de walled garden usando regras de iptables que ele gerencia diretamente.

O fluxo de autenticação funciona da seguinte forma. Um dispositivo de convidado se associa ao SSID aberto. O CoovaChilli atribui ao dispositivo um endereço IP de seu pool interno (normalmente 10.1.0.0/24). Quando o dispositivo envia sua primeira solicitação HTTP, o CoovaChilli a intercepta e emite um redirecionamento HTTP 302 para a URL da splash page da Purple. Durante esta fase de pré-autenticação, o dispositivo fica isolado - ele só pode alcançar os domínios listados explicitamente no walled garden.

Assim que o visitante se autentica no portal Purple, o servidor RADIUS na nuvem da Purple envia uma mensagem Access-Accept para o CoovaChilli na porta UDP 1812. O CoovaChilli então atualiza suas regras de iptables para permitir o acesso à internet para aquele endereço MAC específico e começa a transmitir dados de bilhetagem (duração da sessão, bytes transferidos) para o servidor de bilhetagem RADIUS da Purple na porta UDP 1813. A bilhetagem não é opcional - é o mecanismo pelo qual a Purple alimenta o seu painel de WiFi Analytics com dados de sessão.

Walled garden: iptables e listas de permissões de domínio

O walled garden é o elemento de configuração mais crítico operacionalmente em qualquer implantação de Captive Portal. O CoovaChilli gerencia o walled garden por meio de dois mecanismos: o parâmetro uamallowed para endereços IP individuais e o parâmetro uamdomains para listas de permissões baseadas em domínio com inspeção de DNS.

Para uma integração com a Purple, as entradas mínimas obrigatórias de walled garden são:

Observação sobre o gerenciamento de CNA da Apple: Se você incluir captive.apple.com no walled garden, os dispositivos iOS detectarão a conectividade com a internet antes da autenticação e suprimirão a janela pop-up do Captive Network Assistant. A maioria das implantações de hospitalidade exclui intencionalmente esse domínio para acionar o prompt automático do portal. A escolha correta depende do design da experiência do seu visitante.

WiFi seguro para funcionários: hostapd e IEEE 802.1X

Redes de visitantes exigem uma integração sem atrito. Redes de funcionários exigem segurança absoluta. Para usuários internos, o OpenWrt usa o hostapd para facilitar a autenticação IEEE 802.1X. Nesta arquitetura, o ponto de acesso OpenWrt atua como o Autenticador, encaminhando mensagens do Protocolo de Autenticação Extensível (EAP) entre o dispositivo cliente (Suplicante) e o servidor RADIUS da Purple.

Para dispositivos corporativos, o EAP-TLS é o padrão obrigatório. Ele depende de autenticação mútua de certificados - tanto o servidor quanto o dispositivo cliente apresentam certificados digitais - eliminando totalmente as senhas e os riscos associados de roubo de credenciais ou phishing. Para ambientes que ainda não estão prontos para uma Infraestrutura de Chaves Públicas (ICP) completa, o PEAP-MSCHAPv2 oferece uma opção provisória razoável, usando um túnel criptografado para proteger as credenciais de usuário e senha.

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"

Habilite e inicie o serviço:

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

Passo 3: Configurar a interface wireless do OpenWrt para o SSID de visitantes

Em /etc/config/wireless, defina o SSID de visitantes como uma rede aberta vinculada à interface que o CoovaChilli irá gerenciar:

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

O isolamento de clientes (isolate '1') impede que os dispositivos dos visitantes se comuniquem entre si - um controle de segurança obrigatório para qualquer rede compartilhada.

Passo 4: Configurar o hostapd para WiFi corporativo (staff) 802.1X

Para o SSID corporativo, configure o WPA2-Enterprise em /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'

A configuração dynamic_vlan '2' instrui o hostapd a impor a atribuição de VLAN retornada pelo servidor RADIUS e a rejeitar a autenticação se nenhuma VLAN for retornada.

Requisito de pacote: O pacote padrão wpad-mini não suporta WPA2-Enterprise. Você deve instalar o wpad ou wpad-openssl:

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

Passo 5: Configurar PPSK para segmentação multi-tenant

O PPSK exige que o hostapd realize a autenticação de endereço MAC no servidor RADIUS, que então retorna a senha por dispositivo. Em /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'

O parâmetro wpa_psk_radius '2' instrui o hostapd a exigir o atributo Tunnel-Password da resposta do RADIUS. Se o servidor RADIUS não retornar uma senha, a autenticação é rejeitada.

No lado do RADIUS da Purple, a seção authorize da sua configuração do FreeRADIUS (or equivalente) mapeia endereços MAC para senhas e IDs de VLAN:

# Exemplo de entrada de autorização RADIUS para 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"

Passo 6: Configurar atribuição dinâmica de VLAN

Para que a atribuição dinâmica de VLAN funcione, seu switch OpenWrt deve ser configurado para transportar as VLANs relevantes como tráfego marcado (tagged) na porta de tronco que se conecta ao seu switch principal. Em /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'

Certifique-se de que a porta do seu switch principal esteja configurada como tronco, passando as VLANs 10, 20 e 30 como marcadas (tagged).

Melhores práticas

Segregação absoluta de rede. Nunca faça bridge de interfaces de convidados com redes internas. O tráfego de convidados deve ser isolado em uma VLAN dedicada e roteado diretamente para o firewall da internet. Este é um requisito não negociável para a conformidade com o PCI DSS 4.0, que exige que as redes WiFi de convidados sejam completamente isoladas de qualquer segmento de rede que manipule dados de portadores de cartão.

Precisão do walled garden. Um walled garden incompleto é a principal causa de falhas no Captive Portal. Use as ferramentas de desenvolvedor do seu navegador em um dispositivo de teste conectado ao SSID de convidados para identificar quais requisições estão bloqueadas antes da autenticação. Cada domínio bloqueado é uma falha potencial do portal.

Intervalos de bilhetagem RADIUS. Configure o intervalo intermediário de bilhetagem do CoovaChilli para 120 segundos. Isso fornece dados de sessão quase em tempo real no painel de analytics da Purple sem gerar tráfego RADIUS excessivo.

Servidor RADIUS secundário. Sempre configure o HS_RADIUS2 em sua configuração do CoovaChilli. Se o servidor RADIUS principal da Purple estiver inacessível, o CoovaChilli falhará ao autenticar novas sessões. O servidor secundário fornece failover automático sem a necessidade de alteração de configuração no ponto de acesso.

Seleção de pacotes. O pacote wpad-mini incluído em muitas compilações do OpenWrt não suporta WPA2-Enterprise ou atribuição dinâmica de VLAN. Sempre instale o wpad-openssl para qualquer implantação que exija 802.1X ou PPSK.

Para mais orientações sobre arquitetura de segurança WiFi corporativa, consulte nosso Enterprise WiFi Security: A Complete Guide for 2026 .

Solução de problemas e mitigação de riscos

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.