A New Approach to Guest Network Management on OPNsense
Providing internet access to guests in hotels, cafés, malls, factories and offices in Turkey involves two non-negotiables: Law No. 5651 compliance (traffic logs traceable to identified users) and KVKK-compliant explicit consent data collection. The captive portal that ships with OPNsense — an open-source UTM/firewall — is a good starting point, but you need an additional layer to handle registration forms, SMS verification, user lifecycle and reporting.
To close that gap, Marta Teknoloji has built an OPNsense plugin with a self-registration form and SMS verification. Everything runs on the local appliance: the guest's phone number and ID are captured on-site and correlated with traffic logs without depending on any external cloud.
Plugin Architecture
- FreeBSD package: shipped as
os-marta-hotspot; deploys the Phalcon UI, PHP backend controller and config files into OPNsense's standard plugin layout. - Captive portal integration: our custom registration page is served when users hit the portal; on successful verification, traffic is allowed via
radclient/ipfw table. - Local user store: SQLite/MySQL keeps phone number, full name, ID/passport number, explicit-consent signature, MAC address and session lifetime — all on the appliance.
- SMS provider adapters: Netgsm, İletiMerkezi, SanalSantral, Twilio — chosen from the config UI.
- Admin panel: a "Services → Marta Hotspot" tab inside the OPNsense web UI: active guests, SMS counters, failed attempts, MAC blocklist, daily reports.
Registration and Verification Flow
- The guest connects to Wi-Fi and is redirected by OPNsense to our registration page.
- Name, GSM number and ID/passport number are entered; the KVKK disclosure and explicit consent checkbox are mandatory.
- On submit, the server enforces a rate limit (3 attempts per MAC per 5 minutes) and dispatches a 6-digit OTP through the configured provider.
- The guest enters the code; on success the session is opened, the MAC address is added to the
ipfwtable and time-limited access is granted (24 h default). - RADIUS Accounting runs throughout the session, producing the "who, on which MAC, when, with what IP" records required by Law 5651.
Why Our Plugin?
- Runs locally: guest data never leaves the device; no third-party SaaS portal.
- Law 5651 alignment: traffic logs (NetFlow / RADIUS Accounting) merge with identity records and can be exported within an hour for legal requests.
- Brandable landing page: hotel logo, corporate colours, TR/EN languages; per-SSID themes on the same OPNsense.
- Multi-provider SMS: uses your existing account; automatically falls back to a secondary provider when quotas are hit.
- Cost control: the same MAC is remembered for 30 days, reducing SMS spend by roughly 70%.
Installation
- Install
os-marta-hotspotfrom System → Firmware → Plugins. - Open Services → Marta Hotspot → Settings and fill in provider credentials, branding, session length and the KVKK text.
- Bind the plugin to the relevant Captive Portal zone.
- Apply the change through OPNsense's standard "Apply" flow.
Annual Support
The plugin is delivered as a one-off licence plus an annual support subscription that covers OPNsense major upgrade adaptations, new SMS provider integrations, remote installation and troubleshooting during business hours, mandatory updates when legislation changes, and free minor releases. Multi-site deployments get a central admin panel that aggregates registration data across many OPNsense boxes.
Use Cases
- Hotels and serviced apartments: room-tied SMS verification, automated check-out cut-off.
- Café, restaurant and mall chains: branded landing page, social login, KVKK-compliant phone pool.
- Factories and industrial parks: visitor/contractor registration, MAC-based zoning, VLAN isolation.
- Education: limited access for guardians and visitors, isolation from student LAN.
- Public venues (municipalities, museums): identified access, usage analytics, content filtering.
Conclusion
OPNsense is flexible; what was missing was a registration and SMS-verification layer that meets Turkish legal requirements out of the box. Marta Teknoloji's OPNsense Hotspot plugin closes that gap, with the annual support plan keeping the deployment safe long-term. Contact us through the contact form for a demo tailored to your location.