Remote Support Start download

OPNsense Captive Portal in Production: What Really Matters After Setup

OPNsenseCaptive PortalGastnetz
OPNsense Captive Portal in Production: What Really Matters After Setup

Standing up a captive portal in OPNsense takes about two hours. The interesting work starts afterwards: when the logs fill the appliance after six months, the data protection officer requests evidence for a specific date, management wants the logo changed, and marketing asks why new employees are landing in the guest network instead of corporate. This post collects what we at DATAZONE have learned in two years of operating OPNsense captive portals at small and midsize companies. The setup side is covered in our earlier post on the OPNsense captive portal for guest Wi-Fi.

OPNsense Captive Portal in Production: What Really Counts

The classic misreading is that a guest network is done once the initial setup is complete. In reality that is where the work begins. The portal runs, guests connect, logs accumulate. After three months nobody notices the system exists, until something goes wrong: an employee complains the Wi-Fi is slow, a lawyer asks for logs on a specific date, or an audit checks the data protection posture. That is when the invisible things need to be in order.

What setup guides usually leave out

Almost every setup guide stops at the first successful voucher login. What comes next is left to each operator to figure out. In practice five topics matter: log rotation, GDPR documentation, authentication backend, branding maintenance, and the interaction with 802.1X. None of them is technically demanding, but each one can cause real trouble when it is missing.

Log Rotation: Why Session Logs Eventually Hurt

OPNsense writes multiple records per captive portal session: login, periodic updates, logout, plus the firewall logs for the guest VLAN itself. On a typical appliance with 50 to 150 guests per week, between 200 and 800 MB of log data accumulates per month. On small appliances with 32 GB of internal flash, that becomes a real problem after twelve months.

Rotation in practice

Under System -> Settings -> Logging sits the local rotation configuration. Three values matter: Max File Size, Max Rotation Count, and the target path. For captive portal operation it has proven useful not only to rotate on local disk, but to ship logs via syslog to a central log target. A small TrueNAS with a dedicated dataset as syslog target is enough; long term retention and access control happen there.

Concretely: configure a remote syslog target in OPNsense, create a syslog/captive-portal dataset on TrueNAS with snapshots and quota, and point an rsyslog container or a Graylog pod at it. That removes pressure from the firewall disk and makes the logs searchable.

What actually needs to be logged (and what does not)

What to log: login time, logout or session timeout, MAC address, assigned IP, optionally the voucher identifier. What not to log: complete URL histories, payload data, or DNS answers per session. The latter is both legally problematic and produces exactly the data volume that eventually fills the disk. A captive portal is access control, not deep packet inspection.

GDPR Evidence: What You Need When Audited

A guest network processes personal data in the sense of the GDPR, even if it only stores MAC addresses and login times. This is often underestimated. In an audit, or when a data subject requests their records under Article 15 GDPR, three things need to be available immediately.

Record of processing activities

The captive portal deserves its own entry in the record of processing activities. The entry needs to cover: purpose of processing (access control, abuse prevention), legal basis (usually Article 6 paragraph 1 letter f, legitimate interest), categories of data subjects (guests, external contractors), categories of data (MAC, IP, timestamps), retention period, and technical and organizational measures.

Define and enforce a retention period

Without a specific reason, seven days is a reasonable baseline for session logs. Longer retention requires a documented justification (ongoing investigation, incident documentation). The critical point is that the technical rotation matches the documented retention. If the record says “7 days” and the logs sit on disk for two years, that is a GDPR gap.

Terms on the landing page

The landing page is the right place for transparency notices. Users who log in need to see which data is collected, how long it is stored, and who the controller is. A link to the full privacy policy is enough, but the notice itself should be visible directly on the page. More on this in the branding section.

Vouchers vs. RADIUS: When the Switch Makes Sense

Vouchers are simple, local, and perfectly fine for small environments. Beyond a certain size, generating voucher batches by hand becomes a real burden. In practice our threshold is around 20 to 30 guests per week, or when multiple sites need a shared user base.

What RADIUS adds

A FreeRADIUS instance on OPNsense itself or on a separate Linux host provides centralized authentication, session accounting with data volume, and granular permissions per user or group. For employee access on the guest network (BYOD devices, personal phones outside the domain), RADIUS is significantly more convenient, because credentials are reusable and deprovisioning is centralized.

The migration is straightforward: the captive portal can run both methods in parallel. Employees authenticate against the AD-backed FreeRADIUS, guests continue to receive vouchers at reception. For the transition this is the clean solution.

Where RADIUS stops short

RADIUS does not replace the captive portal. It is only the authentication backend. The portal page stays, the user flow stays, the firewall rules stay. A proper enterprise login with 802.1X authentication at the access point itself is a different thing, more on that below.

Branding: A Portal Page That Does Not Rot

The default OPNsense portal page looks like OPNsense. For environments where guests actually use the network (meeting rooms, reception, showroom), that is rarely desired. The portal page is the first and often only piece of IT guests see.

Minimum useful, maximum avoided

Pragmatically the portal needs a logo, a short welcome text, a terms notice, and the input field. Anything beyond that is ornamentation and becomes a maintenance item at every OPNsense update, because template paths can change. We recommend keeping the template as its own Git repository and reviewing it against the current template documentation at every OPNsense major release.

Bilingual when needed

Two languages (local plus English) are enough in most cases. The toggle should be a simple link on the page itself, not browser language detection, because mobile browsers tend to send inconsistent headers.

What does not belong in the template

No required name, email, or phone number fields for guests. That collects data nobody needs, and auditors notice it immediately. A MAC and a voucher are sufficient for access control. Anything beyond is marketing data collection and does not belong in an access infrastructure.

802.1X Fallback: Captive Portal and Enterprise Wi-Fi Side by Side

Employee Wi-Fi belongs on a 802.1X-authenticated network, not on a captive portal. There are still scenarios where both must coexist: external contractors with their own devices, visitors with laptops, events with short term access.

The clean architecture

Two SSIDs on the access points: one with WPA2/WPA3 Enterprise authenticating against FreeRADIUS, one open SSID with the captive portal. Both land in separate VLANs, both have their own firewall rules. The captive portal VLAN is strictly internet-only (see our earlier post on the guest network setup); the 802.1X VLAN has differentiated rules per user or group.

When 802.1X fails

It happens: an access point certificate expires, the RADIUS server goes down, a supplicant breaks on a client device. The captive portal should not act as the fallback for production clients in those cases. The better pattern is a documented manual process: move the affected device via voucher into the guest network for the duration, then fix the actual problem. Treating the captive portal as an emergency backup for production clients leads to it being permanently used as backup, which undermines network segmentation.

Monitor both networks

For operations it helps to have both networks in the same monitoring system. Zabbix or Checkmk polling OPNsense over SNMP, plus the FreeRADIUS logs in the central logging. That way it becomes visible when production clients unexpectedly appear in the captive portal network — a strong signal of an unresolved 802.1X issue.

Operations: What Actually Happens Quarterly

Everything above is groundwork. What actually happens during ongoing operations: check and regenerate the voucher pool, clean up expired sessions, verify log rotation is working, reconcile the GDPR documentation against reality once per quarter, update the portal template when OPNsense is updated. None of this is dramatic, but without a named owner it slips. We cover this for customers as part of our IT service, and the pattern is clear: what nobody owns, nobody maintains.

Related topics: for environments where the guest network needs to serve terms of use from a TrueNAS-based document store, we build a clean path via reverse proxy with allow-listing of the captive portal allowed addresses. And for anyone who wants a properly segmented network, the earlier post on the OPNsense captive portal for guest Wi-Fi sets the broader frame.

FAQ on Running OPNsense Captive Portal in Production

How long should session logs be retained?

Seven days as a baseline, documented in the record of processing activities. Longer retention needs a concrete justification (ongoing investigation, incident documentation). What matters most is that technical rotation matches the documented period.

When does moving from vouchers to RADIUS pay off?

Rule of thumb: starting at 20 to 30 regular guests per week, when multiple sites share a user base, or when employees routinely bring BYOD devices onto the guest network. Both methods can run in parallel; the transition is not all-or-nothing.

Should the portal collect guest email or phone numbers?

Technically possible, legally problematic. Pure access control is satisfied by MAC and voucher. Additional data needs a clear legal basis and must be justified in an audit. We usually advise against it.

What happens to the captive portal during an OPNsense update?

Core functionality stays stable, but custom templates can need adjustment on major releases (yearly versions). Keep the template in a Git repository and review it against each major release. Minor updates are usually uneventful.

Can the captive portal serve as a fallback for 802.1X outages?

Technically yes, as a design no. If the production 802.1X Wi-Fi routinely falls back to the captive portal, segmentation is undermined and false assumptions about security creep in. Better: run 802.1X robustly, keep the captive portal strictly for guests.

How much realistic effort is ongoing operation?

For a typical SMB with one site and 50 to 150 guests per week, roughly one to two hours per quarter: voucher top-ups, log checks, GDPR documentation review. More sites, more time. The critical factor is clear ownership — without it, exactly this routine is the first thing to be dropped.

More on these topics:

Need IT consulting?

Contact us for a no-obligation consultation on Proxmox, OPNsense, TrueNAS and more.

Get in touch