Skip to main content

PacketFence Installation & Configuration Guide

Audience: Junior IT Staff
Version: 5.0 | Internal Use Only
Installation Method: PacketFence ISO

Table of Contents

  1. Overview
  2. Prerequisites
  3. Network Interface Design
  4. Installing PacketFence via ISO
  5. Configuring Network Interfaces in PacketFence
  6. VLAN Configuration
  7. Creating Roles
  8. Portal HTTPS Certificate and Captive Portal FQDN
  9. Registration Network DHCP and Interface
  10. Active Directory Integration
  11. Google Workspace Integration
  12. Configuring the Primary Portal
  13. Configuring the Events Portal
  14. Configuring EAP-TLS with Microsoft AD CS
  15. NAS-Identifier Based VLAN Assignment
  16. Testing and Verification
  17. Ongoing Maintenance
  18. Quick Reference

1. Overview

This guide walks a junior IT administrator through the complete installation and configuration of PacketFence, an enterprise-grade open-source Network Access Control (NAC) solution. By the end of this guide you will have a fully functioning system that:

  • Controls network access through a captive portal and 802.1X authentication.
  • Presents a Primary Portal with separate flows for Guest access and BYOD login.
  • Presents an Events Portal that uses an auto-rotating password emailed to designated staff.
  • Authenticates corporate devices via EAP-TLS (certificate-based) using your Microsoft AD CS CA.
  • Uses NAS-Identifier attributes from access points to assign devices to the correct building VLAN.
  • Authenticates BYOD users with Active Directory (LDAP) or Google Workspace (LDAP) credentials.
  • Serves DHCP and DNS for the registration VLAN from PacketFence itself.
  • Presents the captive portal over HTTPS using a trusted Let's Encrypt certificate.

Note: This guide assumes the PacketFence ISO installer on dedicated bare-metal or a VM. Commands are run as root unless otherwise stated.

1.1 Key Terminology

Term Meaning
NAC Network Access Control — enforces security policy on network access.
Captive Portal A web page shown to new users before granting network access.
EAP-TLS Certificate-based 802.1X authentication — the most secure option.
BYOD Bring Your Own Device — personal devices connecting to the network.
VLAN Virtual Local Area Network — logical network segmentation.
RADIUS The backend protocol PacketFence uses to communicate with APs and switches.
Portal Module A building block defining a step in the captive-portal flow.
Role A named category assigned to a device that determines its VLAN and access policy.
NAS-Identifier An attribute sent by access points in RADIUS requests identifying which AP or building the request originated from.
Password of the Day A PacketFence authentication source that auto-generates a rotating shared password on a schedule and emails it to designated staff.

2. Prerequisites

2.1 Hardware Requirements

Component Minimum Recommended
CPU 4 cores 8+ cores
RAM 8 GB 16 GB+
Disk 100 GB 500 GB+ (logs and packet captures)
Network Interfaces 2 NICs 2 NICs (management + trunk)

2.2 Network Requirements

  • A static management IP on the management VLAN.
  • A trunk port on the second NIC carrying all wireless VLANs, registration, guest, and events VLANs.
  • DNS resolving the PacketFence management FQDN and the portal FQDN from all client VLANs.
  • Firewall rules allowing RADIUS (UDP 1812/1813) from access points to the PacketFence server.
  • Outbound SMTP access from PacketFence to deliver Password of the Day emails.
  • Reachability to Active Directory and/or Google Workspace for LDAP authentication.
  • Public DNS record for the portal FQDN (e.g., portal.example.org) pointing to a reachable IP — required for Let's Encrypt certificate issuance.

2.3 Information to Gather

Collect the following before you start. Store all credentials in your password manager — not in this document.

Item Your Value
Management IP / Subnet / Gateway
Server FQDN e.g., pf.example.org
Portal FQDN e.g., portal.example.org
Active Directory Domain e.g., EXAMPLE.ORG
AD Bind Account (DN) e.g., CN=pfbind,OU=ServiceAccounts,DC=example,DC=org
AD Bind Password (store in password manager)
Google Workspace Domain e.g., example.org
Google LDAP Service Account credentials (from Google Admin Console — see Section 14)
RADIUS Shared Secret (store in password manager — used on every AP)
Password of the Day Email Recipient(s) e.g., admin@example.org
Microsoft CA Server hostname e.g., ca.example.org
Registration VLAN DHCP range e.g., 192.168.99.10 – 192.168.99.200

3. Network Interface Design

PacketFence requires two network interfaces with distinct roles.

3.1 Interface Layout

Interface Role Configuration Notes
eth0 Management & Portal Static IP, management VLAN Web UI, API, captive portal, DNS/DHCP for registration VLAN.
eth1 Trunk / DHCP Listener No IP address, 802.1Q trunk Carries all wireless and access VLANs. PacketFence listens passively for DHCP to detect and track devices.

Note: The captive portal is served from eth0. Clients on the registration VLAN are redirected here via DNS interception — they do not need a routed path to the internet to reach the portal.

3.2 Wireless VLAN Layout

The following is an example VLAN layout for a multi-building wireless deployment. Adjust VLAN IDs and subnets to match your environment.

VLAN Name VLAN ID Subnet Notes
Wireless Mgmt 20 172.16.20.0/24 AP management — not for client devices.
Building A WiFi 21 172.16.21.0/23 Building A EAP-TLS clients (NAS-Identifier routed).
Building B WiFi 22 172.16.23.0/23 Building B EAP-TLS clients (NAS-Identifier routed).
Building C WiFi 23 172.16.25.0/23 Building C EAP-TLS clients (NAS-Identifier routed).
Staff BYOD 30 10.30.0.0/22 Staff personal devices authenticated via AD or Google.
Student/User BYOD 31 10.31.0.0/22 User personal devices authenticated via AD or Google.
IoT 40 10.40.0.0/24 IoT and infrastructure devices.
Events 50 10.50.0.0/24 Event attendees — Password of the Day.
Guest 60 192.168.60.0/22 Guest devices — null/open registration.
Registration 99 192.168.99.0/24 Unregistered devices. PacketFence serves DHCP and DNS here.

4. Installing PacketFence via ISO

The PacketFence ISO provides a purpose-built installer that configures the OS, all services, and PacketFence in a single pass.

4.1 Download the ISO

Download the latest PacketFence ISO from:

https://www.packetfence.org/downloads.html

Choose the x86_64 ISO. Verify the SHA256 checksum against the value published on the download page before writing to media.

4.2 Boot the Installer

Write the ISO to a USB drive or mount it as a virtual CD-ROM, then boot the server from it.

  1. At the boot menu select Install PacketFence.
  2. Choose your language and keyboard layout.
  3. Proceed to the disk partitioning screen.

4.3 Disk Partitioning

Accept the automatic layout for most deployments. Recommended minimums:

  • / — at least 50 GB
  • /usr/local/pf — at least 50 GB (PacketFence data, logs, and captures)

Enable disk encryption if your security policy requires it.

4.4 Network Configuration During Install

When the installer reaches the network screen:

  1. Select eth0 as the management interface.
  2. Assign a static IP, subnet mask, gateway, and DNS server.
  3. Enter the server's fully qualified domain name (e.g., pf.example.org).
  4. Leave eth1 unconfigured — PacketFence manages it after first boot.

Note: The FQDN you set here is used to generate certificates and portal redirect URLs. Set it correctly — changing it later requires regenerating all certificates.

4.5 Complete the Installation

  1. Set a strong root password when prompted. Store it in your password manager.
  2. Allow the installer to copy files and configure services (10–20 minutes).
  3. When prompted, remove the installation media and reboot.

4.6 Post-Reboot: Open the Configuration Wizard

After reboot, open a browser from the management VLAN and navigate to:

https://<management-ip>:1443

Note: You will see a certificate warning on first access — this is expected. Accept and continue.

Follow the on-screen wizard:

  1. Accept the EULA.
  2. Set the admin username and a strong password. Store both in your password manager.
  3. Confirm or set the database credentials. Store in your password manager.
  4. Confirm the management interface and IP.
  5. Confirm the FQDN.
  6. Complete the wizard and allow PacketFence to restart its services.

All further configuration is done in the admin UI at:

https://pf.example.org:1443/admin

5. Configuring Network Interfaces in PacketFence

Go to Configuration > Network Configuration > Networks > Interfaces to configure all interfaces and VLANs.

5.1 Management Interface (eth0)

  1. Click eth0 in the interface list.
  2. Confirm Type is set to Management.
  3. Confirm the IPv4 address and netmask are correct.
  4. The portal daemon badge should be visible — this confirms the captive portal is served from this interface.
  5. Click Save.

5.2 Creating VLAN Sub-Interfaces on eth1

The trunk interface (eth1) carries all wireless and access VLANs as 802.1Q sub-interfaces. PacketFence creates these individually via the New VLAN button. Each VLAN becomes a separate entry in the interface list (e.g., eth1 VLAN 21, eth1 VLAN 22, etc.).

For each wireless and access VLAN in your layout (see Section 3.2), repeat the following:

  1. On the eth1 row, click New VLAN.
  2. Set Virtual LAN ID to the VLAN number.
  3. Set IPv4 Address to the gateway IP for that VLAN — typically the .1 address in the subnet.
  4. Set Netmask to match the VLAN subnet.
  5. Set Type to DHCP Listener for all wireless VLANs (building WiFi, BYOD, IoT, Events, Guest).
  6. Click Save.

Repeat until all VLANs are created. The interface list will show each sub-interface as a separate row beneath eth1. Using the example layout from Section 3.2:

VLAN ID IPv4 Address Netmask Type
20 172.16.20.1 255.255.255.0 DHCP Listener
21 172.16.21.1 255.255.254.0 DHCP Listener
22 172.16.23.1 255.255.254.0 DHCP Listener
23 172.16.25.1 255.255.254.0 DHCP Listener
30 10.30.0.1 255.255.252.0 DHCP Listener
31 10.31.0.1 255.255.252.0 DHCP Listener
40 10.40.0.1 255.255.255.0 DHCP Listener
50 10.50.0.1 255.255.255.0 DHCP Listener
60 192.168.60.1 255.255.252.0 DHCP Listener

5.3 Registration VLAN Interface

The registration VLAN is created the same way as the others, but requires two additional settings — Type must be set to Registration and the built-in DHCP server must be enabled:

  1. On the eth1 row, click New VLAN.
  2. Set Virtual LAN ID to your registration VLAN (e.g., 99).
  3. Set IPv4 Address to the gateway IP for the registration subnet (e.g., 192.168.99.1).
  4. Set Netmask to 255.255.255.0.
  5. Set Type to Registration.
  6. Toggle Enable DHCP Server to on.
  7. Click Save.

Note: Setting Type to Registration tells PacketFence that devices arriving on this VLAN are unregistered and should be shown the captive portal. The Enable DHCP Server toggle activates PacketFence's built-in DHCP service on this sub-interface — this hands out IP addresses to unregistered devices and sets PacketFence as their DNS server, enabling the portal redirect. The DHCP pool details are configured separately in Section 8.

5.3 Isolation VLAN Interface (Optional)

If you use an isolation VLAN to quarantine non-compliant devices, add it the same way with Type set to Isolation. Assign it an IP and netmask appropriate to your isolation subnet.

5.4 Role-to-VLAN Mapping Reference

Once all sub-interfaces are created, PacketFence assigns VLANs to devices based on the role returned after authentication. The following table summarises the intended mapping for this deployment:

PacketFence Role VLAN ID Interface Type How Assigned
(registration) 99 Registration All unregistered devices — shown the captive portal.
guest 60 DHCP Listener Null/open registration via portal.
BYOD-Staff 30 DHCP Listener AD or Google LDAP staff rule.
BYOD-Student 31 DHCP Listener AD or Google LDAP student rule.
Event 50 DHCP Listener Password of the Day source.
building-a 21 DHCP Listener EAP-TLS + NAS-Identifier rule.
building-b 22 DHCP Listener EAP-TLS + NAS-Identifier rule.
building-c 23 DHCP Listener EAP-TLS + NAS-Identifier rule.

The registration VLAN interface and its DHCP pool are configured in Section 8.

6. Creating Roles

Roles are the mechanism PacketFence uses to classify devices and determine which VLAN and access policy to apply. Every device on the network is assigned a role — either by an authentication rule, by a portal module, or by falling through to the default. Roles must be created before building authentication sources or portal modules that reference them.

Go to Configuration > Policies and Access Control > Roles and click New Role for each of the following.

7.1 Role Definitions

Identifier Description Notes
guest Guests Open registration — null source. Parent role for BYOD sub-roles.
BYOD BYOD devices Parent role. Nest BYOD-Staff and BYOD-Student beneath it.
BYOD-Staff Staff personal devices Child of BYOD. Assigned via AD/Google LDAP staff rule.
BYOD-Student Student personal devices Child of BYOD. Assigned via AD/Google LDAP student rule.
HS High School WiFi Assigned via EAP-TLS NAS-Identifier rule.
MS Middle School WiFi Assigned via EAP-TLS NAS-Identifier rule.
EL Elementary WiFi Assigned via EAP-TLS NAS-Identifier rule.
Event Event network access Assigned via Password of the Day source.
Machine Machine role For domain-joined computers authenticating before user login.
User User role General authenticated user fallback.
REJECT Reject role — blocks access Assign to devices that should be denied.
voice VoIP devices For IP phones and voice infrastructure.
gaming Gaming devices For gaming consoles if separated from general BYOD.
default Default/placeholder Built-in fallback — edit description but leave the identifier.

7.2 Creating a Role

For each role in the table above:

  1. Click New Role.
  2. Set Identifier to the value in the table (e.g., BYOD-Staff). This is case-sensitive and used internally by PacketFence.
  3. Set Description to a human-readable label (e.g., Staff personal devices).
  4. Leave Max nodes per user at 0 unless you want to enforce a device limit.
  5. Click Save.

7.3 Creating Nested (Child) Roles

PacketFence supports parent/child role relationships, as shown in the screenshot where BYOD is the parent of BYOD-Staff and BYOD-Student. This grouping is useful for applying shared policies to all BYOD devices while still differentiating staff from students for VLAN assignment.

To nest a role under a parent:

  1. Create the parent role first (e.g., BYOD).
  2. When creating the child role (e.g., BYOD-Staff), look for the Parent role field and select BYOD.
  3. Repeat for BYOD-Student.

Note: Role identifiers must be unique and cannot contain spaces. Use hyphens for multi-word names (e.g., BYOD-Staff, not BYOD Staff). Roles referenced in authentication rules, portal modules, or NAS-Identifier conditions must exist before those configurations are saved.

7. Portal HTTPS Certificate and Captive Portal FQDN

By default, PacketFence serves the captive portal using a self-signed certificate, which causes browser security warnings for users. PacketFence has built-in Let's Encrypt support that handles certificate issuance and renewal automatically — no command-line tools required.

7.1 Why a Separate Portal FQDN

The management server FQDN (e.g., pf.example.org) is used for the admin UI and RADIUS. The captive portal is best served on a separate, publicly resolvable hostname (e.g., portal.example.org) so that:

  • Let's Encrypt can issue a trusted certificate for it independently of the internal management cert.
  • The portal URL is clean and recognizable to end users.
  • All client VLANs can resolve it to the PacketFence management IP without exposing the admin interface.

7.2 Create a Public DNS Record

Before enabling Let's Encrypt, create a public DNS A record pointing your portal hostname to your PacketFence server's public IP (or the IP reachable from the internet):

portal.example.org  →  <PacketFence public/management IP>

Let's Encrypt must be able to reach TCP port 80 on this hostname to complete the HTTP-01 challenge during certificate issuance and renewal.

7.3 Firewall and NAT Requirements

Before enabling Let's Encrypt, ensure port 80 is reachable from the internet on the portal hostname. This typically requires two changes:

On your perimeter firewall / security appliance:

  • Create an inbound rule allowing TCP port 80 from 0.0.0.0/0 (any) to the PacketFence management IP.
  • If your firewall performs stateful inspection or has a separate security policy for the management zone, ensure HTTP is explicitly permitted — many firewalls default-deny inbound traffic to server management IPs even if a NAT rule exists.

On your NAT / router (if PacketFence is behind a private IP):

  • Create a destination NAT rule (port forward) mapping TCP port 80 on your public IP to TCP port 80 on the PacketFence management IP.
  • Let's Encrypt does not require port 443 for the HTTP-01 challenge — port 80 only.

Note: Port 80 only needs to be open for Let's Encrypt's initial validation and subsequent renewals. PacketFence handles renewals automatically, so the rule should remain in place permanently. If your security policy does not permit permanent inbound port 80, you will need to open it briefly each time the certificate is due for renewal (every ~60 days).

Warning: The PacketFence admin UI runs on port 1443, not 80 or 443. Opening port 80 for Let's Encrypt does not expose the admin interface. Confirm your firewall rule is scoped to port 80 only.

7.4 Enable Let's Encrypt in PacketFence

PacketFence handles the entire certificate lifecycle through the admin UI:

  1. Go to System Configuration > SSL Certificates.
  2. Click the HTTP tab.
  3. Click Edit HTTP Certificates.
  4. Toggle Use Let's Encrypt to on.
  5. Enter your portal hostname in the Common Name field (e.g., portal.example.org).
  6. Click Save.

PacketFence will contact Let's Encrypt, complete the HTTP-01 challenge, and install the certificate automatically. Renewal is handled by PacketFence on an ongoing basis — no cron jobs or manual steps are needed.

Note: The Test button next to the Common Name field can be used to verify that Let's Encrypt can reach your server before committing the change.

7.5 Configure the Captive Portal Settings Settings

The full Captive Portal configuration page is at Configuration > Advanced Access Configuration > Captive Portal. Several settings on this page are important to review and set correctly.

Portal IP Address

The IP address field at the top of the page sets the IP the portal uses in the registration and isolation networks. This must be set to the IP address of your PacketFence server on the registration VLAN — i.e., the IP you assigned to the registration VLAN sub-interface in Section 8.1 (e.g., 192.168.99.1).

Warning: The in-page description notes "Do not change unless you know what you are doing. Changing this requires a restart of all PacketFence services." Set it once correctly and leave it. If this IP does not match the registration interface IP, devices on the registration VLAN will not be redirected to the portal correctly.

Other Domain Names

Add your portal hostname so PacketFence serves the portal on that URL:

  1. Find the Other domain names field.
  2. Add portal.example.org.

Secure Redirect

Ensure Secure redirect is toggled on. This forces the captive portal to use HTTPS for all portal clients. With the Let's Encrypt certificate configured in Section 7.4, clients will receive a trusted HTTPS connection rather than a browser warning.

Other Notable Settings

Click Save after making all changes on this page. Restart the portal web service to apply the secure redirect change:

systemctl restart packetfence-httpd.portal

7.6 Set the Portal FQDN on the Registration Network

The portal FQDN also needs to be set directly on the registration network's DHCP configuration so that devices on that network are directed to the correct URL. This is covered in Section 8.

8. Registration Network DHCP and Interface

PacketFence acts as the DHCP and DNS server for the registration VLAN. This section covers both creating the registration VLAN interface on eth1 and configuring the DHCP address pool.

8.1 Create the Registration VLAN Interface

  1. Go to Configuration > Network Configuration > Networks > Interfaces.
  2. On the eth1 row, click New VLAN.
  3. Fill in the fields:
Field Value
Virtual LAN ID 99
IPv4 Address 192.168.99.1
Netmask 255.255.255.0
Type Registration
Enable DHCP Server Toggled on
  1. Click Save.

Setting Type to Registration tells PacketFence that devices on this VLAN are unregistered and should be shown the captive portal. Enabling DHCP Server activates PacketFence's built-in DHCP service on this sub-interface — it hands out IP addresses to unregistered devices and sets PacketFence as their DNS server, enabling the portal redirect.

8.2 How Registration DHCP Works

When an unregistered device connects to the registration VLAN:

  1. The device sends a DHCP broadcast.
  2. PacketFence answers and hands out an IP from the registration pool.
  3. PacketFence sets itself as the DNS server in the DHCP response.
  4. When the device opens a browser, PacketFence intercepts the DNS query and returns its own IP.
  5. The browser is redirected to https://portal.example.org.

8.3 Configure the DHCP Pool

After saving the registration interface, PacketFence automatically creates a Layer 2 Network entry for that subnet. Configure the pool:

  1. Go to Configuration > Network Configuration > Networks > Interfaces.
  2. Click the registration network link shown in blue next to the VLAN 99 row (e.g., 192.168.99.0). This opens the Layer 2 Network configuration screen.
  3. Fill in the fields:
Field Value Notes
Algorithm Random Assigns IPs randomly from the pool rather than sequentially.
DHCP Pool Backend Type Memory Pool In-memory pool — suitable for most deployments.
Starting IP Address 192.168.99.10 First address in the DHCP range.
Ending IP Address 192.168.99.246 Last address in the DHCP range.
Default Lease Time 30 30 seconds — short leases keep unregistered devices moving through registration quickly.
Max Lease Time 30 Match the default.
IP Addresses reserved (leave blank unless you need to exclude specific IPs)
Portal FQDN portal.example.org The portal hostname devices are redirected to. If left empty, PacketFence uses the server FQDN instead.
  1. Click Save.

Note: The Portal FQDN field here is separate from the setting in Advanced Access Configuration > Captive Portal > Other domain names configured in Section 7.5. Both must be set — the captive portal setting tells PacketFence to serve the portal on that hostname, and this network setting tells PacketFence which URL to redirect devices to when they are on the registration VLAN.

8.4 Verify the DHCP Service

After saving, confirm the DHCP server is running and listening:

ss -ulnp | grep 67

You should see the service bound to port 67 on the registration VLAN interface. If not, restart the listener:

systemctl restart packetfence-pfdhcplistener
pfcmd configreload

9. Active Directory Integration

PacketFence uses Active Directory via LDAP to authenticate BYOD users at the portal. Configure this before building portal modules.

9.1 Configure the AD Authentication Source

  1. Go to Configuration > Sources > New Source > Active Directory.
  2. Fill in the fields:
Field Value
Name AD_Corp
Host Domain controller IP or hostname
Port 636 (LDAPS — recommended) or 389
Base DN DC=example,DC=org
Bind DN CN=pfbind,OU=ServiceAccounts,DC=example,DC=org
Bind Password (from your password manager)
Search Attribute sAMAccountName
AD Domain EXAMPLE.ORG
  1. Click Test to verify the connection before saving.
  2. Click Save.

Note: Use a dedicated, low-privilege service account for the bind account. It only needs read access to user and group objects. Do not use a Domain Admin account.

9.2 Add Authentication Rules

Authentication rules determine the role and access duration a user receives after a successful login.

  1. Inside the AD_Corp source, click Add Rule.
  2. Add a rule for staff BYOD:
    • Condition: Member of CN=Staff,OU=Groups,DC=example,DC=org
    • Action: Role = BYOD-Staff, Access Duration = 12h
  3. Add a rule for students/users:
    • Condition: Member of CN=Students,OU=Groups,DC=example,DC=org
    • Action: Role = BYOD-Student, Access Duration = 8h
  4. Save the source.

10. Google Workspace Integration

PacketFence can authenticate Google Workspace users via the Google Secure LDAP service. Users log in at the portal with their Google Workspace credentials. All authentication queries flow from the PacketFence server to Google's LDAP endpoint directly — no internet access is required from the client device.

10.1 Enable the LDAP Service in Google Admin

  1. Sign in to admin.google.com with a super-admin account.
  2. Navigate to Apps > LDAP > Add Client.
  3. Give the client a name (e.g., PacketFence).
  4. Under Access Permissions:
    • Set Verify user credentials to Entire domain.
    • Set Read user information to Entire domain.
    • Set Read group information to Entire domain if you want group-based role rules.
  5. Click Add LDAP Client.
  6. Download the generated certificate file (.p12). Store it in your password manager.
  7. Note the LDAP hostname: ldap.google.com, port 636.

10.2 Convert the Google LDAP Certificate

Google provides a PKCS#12 (.p12) credential file. Convert it to PEM format for PacketFence:

# Extract the certificate
openssl pkcs12 -in google-ldap.p12 -nokeys -out google-ldap.crt -legacy

# Extract the private key
openssl pkcs12 -in google-ldap.p12 -nocerts -nodes -out google-ldap.key -legacy

Transfer google-ldap.crt and google-ldap.key to your PacketFence server.

10.3 Configure the Google LDAP Source in PacketFence

  1. Go to Configuration > Sources > New Source > LDAP.
  2. Fill in the fields:
Field Value
Name Google_Workspace_LDAP
Host ldap.google.com
Port 636
Encryption SSL
Base DN DC=example,DC=org (replace with your Google Workspace domain)
Bind DN Leave blank — Google LDAP uses certificate-based binding
Client Certificate Upload google-ldap.crt
Client Key Upload google-ldap.key
Search Attribute mail
Email Attribute mail
  1. Click Test to verify the connection.
  2. Click Save.

Note: Google Workspace LDAP does not support anonymous binding. All queries are authenticated using the downloaded certificate — there is no username/password bind account to manage or rotate.

10.4 Add Authentication Rules

  1. Inside the Google_Workspace_LDAP source, click Add Rule.
  2. Add a rule for staff:
    • Condition: mail ends with @example.org
    • Action: Role = BYOD-Staff, Access Duration = 12h
  3. Add further rules if you use Google Groups to separate user types.
  4. Save the source.

11. Configuring the Primary Portal

The primary captive portal handles day-to-day access. It presents users with two options: Guest Access and BYOD Login. The portal module chain mirrors the structure shown in the Portal Modules builder — a Root, a Choice module branching to two Step 3 options.

11.1 Understanding Portal Module Types

Module Type Indicator Color Purpose
Root Black Entry point for a portal policy.
Choice Pink / Dark Presents branching options to the user.
Login Pink Prompts for credentials against configured sources.
MFA Green Requires multi-factor authentication after login.
ShowLocalAccount Black Displays auto-generated credentials to the user.
Password Pink Validates a shared or rotating password.
Provisioning Green Pushes configuration profiles or certificates to devices.

11.2 Build the Primary Portal

Navigate to Configuration > Portal Modules and click New Root Module.

Step 1 — Root Module

Name it Primary Portal. This is the entry point — it connects forward to the Step 2 Choice module.

Step 2 — Choice Module

  1. Click New Module > Choice.
  2. Name it Default registration policy.
  3. Set it as the next module after the Root.
  4. This module presents users with the two Step 3 options below.

Step 3a — Guest Access

The guest flow uses a null authentication source — users click the button and are immediately registered without entering any credentials.

  1. Click New Module > Choice (or Registration depending on your PacketFence version).
  2. Name it Guest Access.
  3. Set Source to the null/anonymous source.
  4. Set Role to guest.
  5. Set Access Duration to your preferred guest session length (e.g., 4h).
  6. Connect this as option 1 under Default registration policy.

Step 3b — BYOD Login

  1. Click New Module > Login.
  2. Name it BYOD Login.
  3. Set Sources to:
    • AD_Corp — for Active Directory users
    • Google_Workspace_LDAP — for Google Workspace users
  4. When multiple sources are assigned, PacketFence presents a source-selection screen automatically.
  5. Role assignment is handled by the authentication rules configured in each source (Sections 10.2 and 11.4).
  6. Connect this as option 2 under Default registration policy.

Note: If you are using both AD LDAP and Google LDAP, users will see a standard login form and PacketFence will query both sources in order.

  1. Go to Configuration > Connection Profiles > New Profile.
  2. Name it Primary Portal.
  3. Set Portal Module to Primary Portal Root.
  4. Set Filters to match VLAN 99 (registration) or your registration SSID.
  5. Set Sources to AD_Corp and Google_Workspace_LDAP.
  6. Click Save.

12. Configuring the Events Portal

The Events Portal presents a single password field. It uses PacketFence's Password of the Day authentication source — a password that auto-generates on a set schedule and is emailed to designated staff automatically.

12.1 Create the Password of the Day Source

  1. Go to Configuration > Sources > New Source > Password of the Day.
  2. Fill in the fields:
Field Value Notes
Name Rotating-Password
Description Event onboarding password
Password rotation duration 1 week Adjust to 1 day, 1 week, or 1 month based on your events schedule.
Email admin@example.org Address(es) to receive the new password on rotation. Separate multiple with a comma.
Password length 8
Associated Realms null, local, default
  1. Under Authentication Rules, confirm the default catchall rule is present. This grants access to any user who enters the correct password.
  2. Click Save.

Note: When the password rotates, PacketFence sends the new password to the configured email address automatically. Keep the current password saved in your password manager as a backup in case staff need it before the next rotation email arrives.

12.2 Build the Events Portal

Step 1 — Root Module

  1. Go to Configuration > Portal Modules > New Root Module.
  2. Name it Events Portal.

Step 2 — Password Module

  1. Click New Module > Password.
  2. Name it to match the heading you want users to see on the portal page (e.g., Event Network Access).
  3. Set Source to Rotating-Password.
  4. Set Role to Event.
  5. Set Access Duration to 12h or the duration of your typical event.
  6. Connect this as the next module after the Events Portal Root.
  7. Click Save.
  1. Go to Configuration > Connection Profiles > New Profile.
  2. Name it Events Portal.
  3. Set Portal Module to Events Portal Root.
  4. Set Filters to match VLAN 50 (events) or your events SSID.
  5. Set Sources to Rotating-Password.
  6. Click Save.

12.4 Adjusting the Rotation Schedule

To change how frequently the password rotates:

  1. Go to Configuration > Sources > Rotating-Password.
  2. Update the Password rotation duration field.
  3. Click Save.

PacketFence applies the new schedule at the next rotation interval. Always confirm the new password was delivered to the configured email address before an event begins.

13. Configuring EAP-TLS with Microsoft AD CS

EAP-TLS provides certificate-based 802.1X authentication for domain-joined corporate devices. The device presents a certificate automatically — no user interaction or credential prompt is required. Devices authenticate silently and are placed directly on their building VLAN based on the NAS-Identifier attribute from the access point (covered in Section 14).

13.1 How EAP-TLS Works in This Environment

Domain-joined device                PacketFence (RADIUS)             AD CS (CA)
        |                                    |                            |
        |-- Connect to 802.1X SSID -------> AP                           |
        |                                    |-- RADIUS Request -------> |
        |<-- EAP Request (TLS) ------------ |                            |
        |-- Client certificate -----------> |                            |
        |                                    |-- Validate cert chain --> |
        |                                    |<-- Chain trusted -------- |
        |<-- RADIUS Access-Accept ---------- |                            |
        |   (VLAN assigned by NAS-Identifier)|                            |

13.2 Client Certificate Infrastructure

Client certificate deployment for Windows, Apple, and Chromebook devices is covered in the separate guide:

Setting Up a Microsoft CA for EAP-TLS Authentication

Complete that guide — specifically Parts 1 through 5 — before continuing here. Confirm you have the following before proceeding:

  • AD CS installed on a dedicated Windows Server 2022 member server (not a Domain Controller).
  • Client certificate templates created (EAP-TLS Windows Device, EAP-TLS Apple Device, EAP-TLS Chrome Device).
  • Certificates deploying to domain-joined Windows devices via Group Policy auto-enrollment.
  • NDES configured and reachable for Apple and Chromebook SCEP enrollment.
  • The Root CA certificate exported in PEM or DER format and ready to import into PacketFence.

13.3 Create a RADIUS Server Certificate Template in AD CS

PacketFence needs its own server certificate from your CA so that client devices can verify the identity of the RADIUS server during the TLS handshake — mutual authentication is a core requirement of EAP-TLS.

On your AD CS server:

  1. Open the Certification Authority console (certsrv.msc).
  2. Expand your CA, right-click Certificate Templates, and select Manage.
  3. In the Certificate Templates console, locate the RAS and IAS Servers template.
  4. Right-click it and select Duplicate Template.
  5. On the Compatibility tab:
    • Set Certification Authority to Windows Server 2012 R2 or later.
    • Set Certificate recipient to Windows 7 / Server 2008 R2 or later.
  6. On the General tab:
    • Set Template display name to PacketFence RADIUS Server.
    • Set Template name (internal name, no spaces) to PacketFenceRADIUSServer.
    • Set Validity period to 2 years and Renewal period to 6 weeks.
  7. On the Subject Name tab:
    • Select Supply in the request — you will provide the FQDN when submitting the CSR.
  8. On the Extensions tab, click Application Policies > Edit and confirm:
    • Server Authentication (1.3.6.1.5.5.7.3.1) is present.
    • Client Authentication (1.3.6.1.5.5.7.3.2) is present — add it if missing.
  9. On the Security tab:
    • Add the computer account of your PacketFence server (or a security group it belongs to).
    • Grant Read and Enroll permissions.
  10. Click OK.

Enable the template on your CA:

  1. Back in the Certification Authority console, right-click Certificate Templates.
  2. Select New > Certificate Template to Issue.
  3. Select PacketFence RADIUS Server and click OK.

13.4 Import the Root CA Certificate into PacketFence

Export the Root CA certificate from your CA server:

certutil -ca.cert C:\rootca.cer

Transfer rootca.cer to your workstation, then in the PacketFence admin UI:

  1. Go to Configuration > PKI > Certificate Authorities > Import CA.
  2. Upload rootca.cer.
  3. Ensure Trust for EAP is enabled.
  4. Click Save.

13.5 Request and Export the RADIUS Server Certificate

Unlike the portal certificate, the RADIUS server certificate must be exported with its private key from AD CS as a PKCS#12 (PFX) file and installed manually on the PacketFence server.

Option A — MMC Certificates snap-in (recommended):

  1. On a domain-joined Windows machine, open mmc.exe and add the Certificates snap-in for the Computer account.
  2. Right-click Personal > Certificates > All Tasks > Request New Certificate.
  3. Select the PacketFence RADIUS Server template and click Enroll.
  4. Once issued, right-click the new certificate and select All Tasks > Export.
  5. Select Yes, export the private key.
  6. Choose PKCS #12 (.PFX) and check Include all certificates in the certification path.
  7. Set a strong export password and store it in your password manager.
  8. Save the file as radius.pfx.

Option B — AD CS Web Enrollment:

  1. Open https://ca.example.org/certsrv.
  2. Click Request a certificate > Advanced certificate request.
  3. Select the PacketFence RADIUS Server template.
  4. Check Mark keys as exportable, then submit.
  5. After issuance, export from the local certificate store as a PFX using the MMC Certificates snap-in as described in Option A.

13.6 Install the RADIUS Certificate on PacketFence

Transfer radius.pfx and rootca.cer to the PacketFence server, then extract the certificate and private key from the PFX:

# Extract the certificate (enter PFX export password when prompted)
openssl pkcs12 -in radius.pfx -clcerts -nokeys -out server.crt -legacy

# Extract the private key (enter PFX export password when prompted)
openssl pkcs12 -in radius.pfx -nocerts -nodes -out server.key -legacy

# Copy all three files to the RADIUS cert directory
cp server.crt /usr/local/pf/raddb/certs/server.crt
cp server.key  /usr/local/pf/raddb/certs/server.key
cp rootca.cer  /usr/local/pf/raddb/certs/ca.crt

Set the correct ownership and permissions so FreeRADIUS can read the files:

chown pf:pf /usr/local/pf/raddb/certs/server.crt
chown pf:pf /usr/local/pf/raddb/certs/server.key
chown pf:pf /usr/local/pf/raddb/certs/ca.crt
chmod 640 /usr/local/pf/raddb/certs/server.crt
chmod 640 /usr/local/pf/raddb/certs/server.key
chmod 640 /usr/local/pf/raddb/certs/ca.crt

Restart the RADIUS service to apply the certificates:

/usr/local/pf/bin/pfcmd service radiusd restart

Verify the certificate is loaded correctly:

openssl s_client -connect pf.example.org:1812 -starttls radius 2>&1 | grep "subject="

You should see subject=CN = pf.example.org in the output.

Note: RADIUS certificates live in /usr/local/pf/raddb/certs/ — not in the general SSL path used by the web admin interface. FreeRADIUS reads them directly from this directory at startup.

13.7 Verify the CA Root in the RADIUS Trust Store

  1. Go to Configuration > PKI > Certificate Authorities.
  2. Confirm your imported CA is listed with Trust for EAP enabled.
  3. If not, re-import using Import CA and enable that flag before saving.

13.8 Restrict the EAP Profile to TLS Only

By default, PacketFence's RADIUS server advertises multiple EAP authentication types (TLS, TTLS, PEAP). In a pure EAP-TLS environment, restricting the profile to TLS only prevents devices from attempting to negotiate weaker methods such as PEAP or TTLS — both of which rely on passwords rather than certificates.

  1. Go to System Configuration > RADIUS > EAP Profiles.
  2. Click the default profile to open it.
  3. Set Default EAP Type to TLS.
  4. Under EAP Authentication Types, remove all entries except TLS. The field should show only TLS.
  5. Leave the remaining profile fields at their defaults:
Field Value
Default EAP Type TLS
Expires 60
Ignore Unknown EAP Types Yes
Cisco Accounting Username Bug Yes
EAP Authentication Types TLS only
TLS Profile tls-common
TTLS Profile tls-common
PEAP Profile tls-common
Fast Profile default
  1. Click Save.
  2. The banner at the top of the page will prompt you to restart affected services. Restart radiusd-auth at minimum:
systemctl restart packetfence-radiusd

Note: The TTLS, PEAP, and Fast Profile fields remain visible even though those methods are removed from EAP Authentication Types — this is normal. Since TLS is the only type listed in that field, FreeRADIUS will only offer TLS to authenticating devices. The other profile fields are simply ignored. If you need to support PEAP for non-certificate devices in the future, you can add it back here.

13.9 Create the EAP-TLS Authentication Source

Building VLAN assignment for EAP-TLS devices is handled through authentication rules inside a dedicated EAPTLS source. Each rule checks the radius_request.NAS-Identifier value sent by the AP and assigns the corresponding role and access duration. This is covered fully in Section 14.

Create the source now so it is ready when you build the rules:

  1. Go to Configuration > Sources > New Source > EAPTLS.
  2. Fill in the fields:
Field Value
Name EAPTLS
Description EAP-TLS Authentication
Associated Realms Leave blank unless your environment uses specific realms
  1. Do not add authentication rules yet — you will add them in Section 14.
  2. Click Save.

13.10 Create a Connection Profile for EAP-TLS Devices

  1. Go to Configuration > Connection Profiles > New Profile.
  2. Name it Corporate 802.1X EAP-TLS.
  3. Do not set a Portal Module — EAP-TLS devices bypass the captive portal entirely.
  4. Set Sources to EAPTLS.
  5. Set Filters to match your corporate SSIDs across all buildings.
  6. Click Save.

Note: Because corporate devices authenticate via certificate, they never see the captive portal. A successful RADIUS exchange places the device directly on the building VLAN assigned by the NAS-Identifier rules inside the EAPTLS source (see Section 14).

14. NAS-Identifier Based VLAN Assignment

Building VLAN assignment for EAP-TLS devices is controlled through authentication rules inside the EAPTLS source created in Section 13.9. Each rule checks the radius_request.NAS-Identifier value sent by the AP. When certificate validation succeeds, PacketFence evaluates these rules in order and assigns the matching role — which maps to the correct building VLAN.

14.1 How It Works

When EAP-TLS authentication succeeds, PacketFence evaluates the authentication rules in the EAPTLS source from top to bottom. The first rule whose radius_request.NAS-Identifier condition matches the value sent by the AP wins. PacketFence returns that rule's Role in the RADIUS Access-Accept response and the AP places the device on the corresponding VLAN.

14.2 Determine Your NAS-Identifier Values

Each AP or AP group must send a consistent NAS-Identifier value. The exact configuration location depends on your wireless controller or AP platform.

Before writing your rules, verify the actual values your APs are sending after a test connection attempt:

grep "NAS-Identifier" /usr/local/pf/logs/radius.log | tail -20

Use the exact string you see in the log. The condition uses contains rather than equals, which gives flexibility if your NAS-Identifier includes additional context (e.g., ORG-HS-AP01 would still match a rule containing ORG-HS).

14.3 Add Authentication Rules to the EAPTLS Source

  1. Go to Configuration > Sources and open the EAPTLS source.
  2. Under Authentication Rules, click the + button to add a new rule.

Add one rule per building, following the pattern shown in the screenshot:

Rule 1 — Building A:

Field Value
Name BLDG-A
Status Enabled
Matches All
Condition 1 radius_request.NAS-Identifier contains BLDG-A
Action 1 Access duration = 1 month (adjust to match your session policy)
Action 2 Role = building-a

Rule 2 — Building B:

Field Value
Name BLDG-B
Status Enabled
Matches All
Condition 1 radius_request.NAS-Identifier contains BLDG-B
Action 1 Access duration = 1 month
Action 2 Role = building-b

Rule 3 — Building C:

Field Value
Name BLDG-C
Status Enabled
Matches All
Condition 1 radius_request.NAS-Identifier contains BLDG-C
Action 1 Access duration = 1 month
Action 2 Role = building-c
  1. Use the − and + buttons on the right to remove or add conditions and actions within each rule.
  2. Click Save after all rules are added.

Note: Rule order matters. If a device's NAS-Identifier could match more than one rule, only the first matching rule applies. Place more specific rules above more general ones.

14.4 Verify VLAN Assignment

After saving the rules, connect a device with a valid client certificate to an AP in each building. Check the active node list:

pfcmd node view all | grep -E "building-a|building-b|building-c"

If a device lands on the wrong VLAN, check what the AP is actually sending:

grep "NAS-Identifier" /usr/local/pf/logs/radius.log | tail -20

Compare that value against your rule conditions and adjust the contains string to match.

15. Testing and Verification

15.1 Test Registration DHCP and Portal Redirect

  1. Connect an unregistered device to the registration SSID or VLAN 99.
  2. Confirm the device receives a DHCP address in the 192.168.99.x range.
  3. Open a browser — you should be redirected to https://portal.example.org.
  4. Confirm the browser shows a valid, trusted certificate (no security warning) — issued by Let's Encrypt.

15.2 Test the Primary Portal — Guest Flow

  1. At the portal, tap or click Guest Access. No credentials should be required.
  2. Confirm the device moves to the guest VLAN (60).
  3. In the admin UI, check Status > Dashboard for the new node entry with role guest.

15.3 Test the Primary Portal — BYOD Flow

  1. Connect a personal device to the registration SSID.
  2. At the portal, tap BYOD Login.
  3. Test with an Active Directory account — confirm staff accounts receive role BYOD-Staff and land on VLAN 30.
  4. Test with a Google Workspace account (LDAP) — confirm the same role assignment occurs.
  5. Test with a student/user account — confirm role BYOD-Student and VLAN 31.

15.4 Test the Events Portal

  1. Connect a device to the events SSID or VLAN 50.
  2. At the portal, you should see the password field.
  3. Enter the current rotating password (check the rotation email or retrieve from your password manager).
  4. Confirm access is granted and the device lands on VLAN 50 with role Event.

15.5 Test EAP-TLS

  1. Connect a domain-joined device with a valid client certificate to the corporate SSID.
  2. The device should connect silently — no portal, no credential prompt.
  3. Confirm in the admin UI the device is on the correct building VLAN based on which AP it connected to.
  4. Check RADIUS logs for the successful TLS handshake:
tail -f /usr/local/pf/logs/radius.log | grep -E "TLS|Access-Accept"

15.6 Common Issues

Symptom Likely Cause Fix
Device on VLAN 99 gets no IP DHCP not running on PacketFence Check `ss -ulnp
Portal not loading after redirect DNS interception not working Confirm PacketFence is the DNS server in the DHCP scope (Section 8.4).
Browser shows certificate warning on portal Let's Encrypt cert not installed or portal FQDN mismatch Re-check Section 7.4 and confirm the cert CN matches portal.example.org.
Portal redirect goes to wrong hostname Portal FQDN not set in Advanced Captive Portal settings Re-check Section 7.5 — confirm portal.example.org is in Other domain names.
Guest Access grants wrong VLAN guest role not mapped to VLAN 60 Check the role VLAN mapping in Section 6.
AD login fails Wrong bind DN or expired bind password Re-test AD_Corp in Configuration > Sources and update credentials.
Google LDAP login fails Certificate not uploaded or expired Re-check the client cert and key in the Google_Workspace_LDAP source.
Events password rejected Password has rotated Test in a private/incognito window and check the latest rotation email.
EAP-TLS device lands on wrong VLAN NAS-Identifier does not match rule in EAPTLS source Run grep "NAS-Identifier" /usr/local/pf/logs/radius.log and update the contains string.
EAP-TLS certificate rejected CA root not trusted in PacketFence Re-confirm Root CA is imported with Trust for EAP enabled (Section 13.7).
Password of the Day email not received SMTP not configured Go to Configuration > System > Alerting and configure outbound email.

16. Ongoing Maintenance

16.1 Password of the Day

The password rotates automatically and is emailed to the configured address. No manual action is required for routine rotations.

To retrieve the current password manually:

  1. Log into the PacketFence admin UI.
  2. Go to Configuration > Sources > Rotating-Password.
  3. The current active password is visible in the source settings.
  4. Store the retrieved password in your password manager.

16.2 Certificate Renewal

Certificate Renewal Method Timeline
Portal cert (Let's Encrypt) Automatic — PacketFence renews via the built-in Let's Encrypt integration No action needed; verify periodically in System Configuration > SSL Certificates
RADIUS server cert (PacketFence) Generate new CSR, submit to AD CS, re-upload At least 30 days before expiry
Client certs — Windows Automatic via Group Policy auto-enrollment No action needed if GPO is configured
Client certs — Apple Update MDM profile if NDES challenge password changes Monitor MDM console
Client certs — Chromebook Automatic via Google Cloud Certificate Connector Monitor Google Admin Console
Google LDAP client certificate Download new .p12 from Google Admin, re-convert and re-upload Check expiry in Google Admin Console
Root CA cert Plan well in advance — typically 10+ year validity Set an annual calendar review

Set a calendar reminder 60 days before the RADIUS server certificate expiry. A lapsed RADIUS cert immediately breaks all EAP-TLS authentication across all buildings.

16.3 PacketFence Updates

dnf update packetfence
systemctl restart packetfence

Read the PacketFence release notes before updating in production. After any update, verify the portal loads correctly and a test EAP-TLS connection succeeds before closing the maintenance window.

16.4 Log Locations

Log File Contents
/usr/local/pf/logs/packetfence.log Main application log — first stop for most issues.
/usr/local/pf/logs/radius.log RADIUS events, EAP-TLS handshakes, NAS-Identifier values.
/usr/local/pf/logs/pfdhcp.log DHCP events — registration scope leases and device detection.
/usr/local/pf/logs/pfqueue.log Background jobs — role changes, VLAN reassignment.
/var/log/mariadb/mariadb.log Database log — for DB-related errors.

For live logs across all PacketFence services:

journalctl -u packetfence -f

17. Quick Reference

17.1 Important URLs and Ports

Item Value
Admin UI https://pf.example.org:1443/admin
Captive Portal https://portal.example.org
RADIUS Authentication UDP 1812
RADIUS Accounting UDP 1813
PacketFence REST API https://pf.example.org:9090/api/v1
AD CS Web Enrollment https://ca.example.org/certsrv
Google LDAP Endpoint ldap.google.com:636

17.2 Key Service Commands

Action Command
Start all services systemctl start packetfence
Stop all services systemctl stop packetfence
Restart RADIUS only systemctl restart packetfence-radiusd
Restart portal web service systemctl restart packetfence-httpd.portal
Restart DHCP listener systemctl restart packetfence-pfdhcplistener
Reload configuration pfcmd configreload
Check service status pfcmd service pf status
View active nodes pfcmd node view all
Tail RADIUS log live tail -f /usr/local/pf/logs/radius.log

17.3 Portal and Authentication Flow Summary

Portal / Flow Module Chain Auth Method Resulting VLAN
Primary Portal — Guest Root → Choice → Guest Access Null (no credentials) 60
Primary Portal — BYOD (Staff) Root → Choice → BYOD Login AD LDAP or Google LDAP → BYOD-Staff rule 30
Primary Portal — BYOD (Student) Root → Choice → BYOD Login AD LDAP or Google LDAP → BYOD-Student rule 31
Events Portal Root → Password Password of the Day (auto-rotating) 50
Corporate EAP-TLS — Building A 802.1X (no portal) Certificate → EAPTLS source rule (NAS-Identifier contains BLDG-A) 21
Corporate EAP-TLS — Building B 802.1X (no portal) Certificate → EAPTLS source rule (NAS-Identifier contains BLDG-B) 22
Corporate EAP-TLS — Building C 802.1X (no portal) Certificate → EAPTLS source rule (NAS-Identifier contains BLDG-C) 23
Document Location
Microsoft CA & EAP-TLS Client Certificates https://wiki.vbisd.org/books/microsoft-adcs/page/setting-up-a-microsoft-ca-for-eap-tls-authentication
Switch and AP RADIUS Configuration (separate guide — in progress)
PacketFence Official Documentation https://www.packetfence.org/doc/
Google Workspace LDAP Setup https://support.google.com/a/answer/9048516

End of document — Version 6.0 | Internal Use Only

Back to top