Installation Guide

These files are included in the package and release tarballs.

PacketFence reuses many components in an infrastructure. Nonetheless, it will install the following ones and manage them itself:

In this guide, we assume that all those components are running on the same server (i.e., "localhost" or "127.0.0.1") that PacketFence will be installed on.

Good understanding of those underlying components and GNU/Linux is required to install PacketFence. When installing PacketFence, all these components will be properly installed. Moreover, PacketFence will manage the services listed above. Make sure that all the other services are automatically started by your operating system.

The following provides a list of the minimum server hardware recommendations:

PacketFence supports the following operating systems on the x86_64 architecture:

Make sure that you can install additional packages from your standard distribution. For example, if you are using Red Hat Enterprise Linux, you have to be subscribed to the Red Hat Network before continuing with the PacketFence software installation.

Other distributions such as RHEL derivatives are known to work but this document does not cover them.

The ZEN (Zero Effort NAC) edition of PacketFence allows you to rapidly get PacketFence running in your network environment. It consists of a fully installed and preconfigured version of PacketFence distributed as a virtual appliance. It can be deployed on VMware ESX/ESXi, Microsoft Hyper-V and other products. This section covers the deployment of the virtual appliance on VMware-based products. We are not supporting any Xen-based hypervisors yet.

You can download the ZEN here: https://www.packetfence.org/download.html#/zen

The ISO edition of PacketFence allows you to install PacketFence on Debian 11 with minimal effort. Instead of manually installing Debian 11 and installing PacketFence after, this will perform both tasks and select the optimal parameters and best practices for installing the operating system.

You can download the ISO here: https://www.packetfence.org/download.html#/releases

PacketFence provides packages repository for RHEL 8 as well as packages repository fo Debian.

These repositories contain all required dependencies to install PacketFence. This provides numerous advantages. Among them, there are:

First install your supported distribution with minimal installation and no additional packages. Then:

On Red Hat-based systems

On Debian

NOTE: If running UEFI mode, make sure secureboot is disabled.

Make sure your system is up to date and your yum or apt-get database is updated. On a RHEL-based system, do:

On a Debian system, do:

Regarding SELinux or AppArmor, even if they may be wanted by some organizations, PacketFence will not work properly if SELinux or AppArmor are enabled. You will need to explicitly disable SELinux from the /etc/selinux/config file and reboot the machine. For AppArmor, you need to follow instructions on Debian wiki.

Regarding resolvconf, you can remove the symlink to that file and simply create the /etc/resolv.conf file with the content you want.

PacketFence v12 includes instructions on deploying PacketFence on Linode IaaS. See the Appendix below for details.

First open PacketFence’s configurator - you can access it from https://@ip_of_packetfence:1443. If you are unsure what IP address you have, run ip a in your Linux shell. Perform the following actions:

Once all services are started, you will automatically be redirected to the PacketFence’s web admin interface. It is located at https://@ip_of_packetfence:1443/. Open that link and log in using the username/password specified in Step 2.

Next, we join the PacketFence server to your existing Microsoft Active Directory domain controller. From PacketFence’s web admin interface, go in Configuration → Policies and Access Control → Domains → Active Directory Domain and click on the New domain button. Provide the required fields. You will need an Active Directory administrative username and password (member of the domain admins) to join the PacketFence server to your domain. Once all the information has been provided, click on the Create & Join button.

Once the domain join succeeds, click on the REALMS tab. Click on the Default realm and set the domain to the Active Directory domain you have just created. That will instruct PacketFence to use that newly created Active Directory for the default authentication realm. Next, do the same thing for the 'NULL' realm.

Next, we add the Microsoft Active Directory domain controller as an authentication source in PacketFence. To do so, from Configuration → Policies and Access Control → Authentication Sources, click on New internal source → AD. Specify all the required fields. If you need help identifying fields relevant to your Active Directory environment, please use the Active Directory Explorer (AD Explorer) or AdsiEdit.mmc tools from your Active Directory server.

In this new 'Authentication Source', add an 'Authentication Rules' with name 'catchall' with no condition and with the following actions:

Make sure the information you provided are valid. Click on the Test button to validate the provided information. If you see the message 'Success! LDAP connect, bind and search successful' - you have properly configured your Microsoft Active Directory authentication source. Save your new authentication source by clicking on the Save button.

Next, we configure a switch so that it integrates with PacketFence using 802.1X. In our example, we will use a Cisco Catalyst 2960 access switch and its IP address will be 172.21.2.3. Our PacketFence’s server IP address will be 172.20.100.2 - you will need to adjust this according to your environment.

Connect to that switch over SSH as an admin.

PacketFence must be aware of the equipment it manages. From Configuration → Policies and Access Control → Network Devices → Switches, click on New Switch → default. Enter your switch IP address (172.21.2.3 in our example). As a switch type, select Cisco Catalyst 2960 and select Production as the Mode. From the 'Roles' tab, make sure 'Role by VLAN ID' is checked and that the VLAN ID associated to the default role is set to your normal VLAN currently in use on your network. In our example, it will be VLAN 20. That means that once a 802.1X authentication is allowed by PacketFence, access will be properly granted in the default role in VLAN 20.

From the 'RADIUS' tab, specify the 'Secret Passphrase' to use - in our example, it is 'useStrongerSecret'. It is very important to correctly set the RADIUS secret passphrase otherwise PacketFence will prevent the switch from communicating to itself.

Finally, from the 'SNMP' tab, provide the correct 'Community Read' and 'Community Write' values.

Next, we need to configure the connection profile in PacketFence. That is required so that PacketFence knows how to handle a connection coming from the wired network or WiFi network. In our case, we will create a new connection profile to use our Microsoft Active Directory authentication source and also to let PacketFence know to automatically register any devices that successfully authenticate using 802.1X on the default connection profile.

From Configuration → Policies and Access Control → Connection Profiles, click on on New Connection Profile. Specify the following information:

Click on Create to save all configuration changes.

To enable 802.1X on the wired adapter of the Microsoft Windows 7 endpoint, you first need to enable the 'Wired AutoConfig' service. To do so, from the Microsoft Windows Services control panel, double-click on Wired AutoConfig. Make sure 'Startup type:' is set to 'Automatic' and click on Start to enable the service.

Then, from Windows' Network Connection panel, open the Properties window of the LAN interface you will use for testing. From the authentication tab, make sure 'Enable IEEE 802.1X authentication' is checked. As the authentication method, make sure 'Microsoft: Protected EAP (PEAP)' is selected. Then, click on Settings and make sure 'Validate server certificate' is unchecked. As authentication method, make sure 'Secured password (EAP-MSCHAPv2)' is selected. Then, click on Configure …​ and make sure 'Automatically use my Windows logon name and password (and domain if any)' is unchecked.

Save all changes.

Now, we are ready to do some testing. First make sure you restart the 'radiusd' service. That is required since we added a new Active Directory domain controller. From Status → Services, click on the Restart button for the 'radiusd' service. PacketFence will take care of restarting that service and the 'radiusd-acct' and 'radiusd-auth' sub-services.

Connect the Microsoft Windows 7 endpoint on port no. 10 from the Cisco Catalyst 2960 switch. From Microsoft Windows, a popup should appear prompting you for a username and password. Enter a valid username and password from your Microsoft Active Directory domain - this should trigger 802.1X (EAP-PEAP) authentication.

To see what’s going on from PacketFence, click on the Auditing tab from PacketFence’s admin interface. You should see an entry for the MAC address of your Microsoft Windows 7 endpoint. Click on the line with the right MAC address to see the RADIUS exchanges. If the 802.1X authentication is successful, you should have 'Accept' as an 'Auth Status'.

PacketFence can send emails to administrators, users and guests. So, it is important to properly configure the mail sending functionality of PacketFence. From Configuration → System Configuration → Alerting, set at least the following fields:

If your SMTP server requires authentication or encryption to relay emails, you will have to properly configure the SMTP encryption, username and password parameters.

To keep our example simple, we will simply create a captive portal for guests where they will only have to accept the terms and conditions prior to gaining network access. To do so, we must first create a 'Null' authentication source. From Configuration → Policies and Access Control → Authentication Sources, click on New external source → Null. As 'Name' and 'Description', specify 'null-source'. Then add an 'Authentication Rules' with name 'catchall' with no condition and with the following tow 'Actions':

Click on Save to save the new authentication source.

Connect to that switch over SSH as an admin.

First, we need to enable Change-of-Authorization (CoA) in our Cisco Catalyst 2960 switch configuration. We essentially need to allow our PacketFence server (172.20.100.2) to send CoA requests to the switch:

Then, we must enable Web Authentication on switch port no. 10. Add the following configuration to the global section:

Then add the required access list:

Next we have to let PacketFence know that Web Auth is to be used on the Cisco Catalyst 2960 switch. From Configuration → Policies and Access Control → Switches and click on your switch’s IP to open its configuration options. From the 'Definition' tab, make sure 'Use CoA' and 'External Portal Enforcement' are checked and set the 'CoA Port' to 3799. From the 'Roles' tab, make the following changes:

Click on Save to save all configuration changes.

By default the PacketFence’s captive portal does not listen on the management interface. To change this, go in Configuration → Network Configuration → Interfaces and click on the logical name of your management interface to bring the configuration panel. In 'Additionnal listening daemon(s)' - make sure you add 'portal'.

You must then restart the following services from Status → Services:

For Web Authentication, we will create a new connection profile in PacketFence. That means the default connection profile will be used for 802.1X while the new connection profile will be used for Web Authentication and will be used to display a captive portal with our 'Null' authentication source. From Configuration → Policies and Access Control → Connection Profiles click on New Profile. Specify the following information:

Click on Save to save all configuration changes.

First make sure that the Microsoft Windows 7 endpoint is unplugged from the Cisco Catalyst 2960 switch. Then, make sure the endpoint is unregistered from PacketFence. To do this, from the Nodes configuration module, locate its MAC address and click on it. From the node property window, change the 'Status' to 'unregistered'.

Next, we need to disable 802.1X from the network configuration card from the Microsoft Windows 7 endpoint. We want to simulate here an authentication by MAC address, so we have to disable 802.1X to do this. From Windows' Network Connection connection panel, ask for the properties of the LAN interface you will use for testing. From the authentication tab, make sure 'Enable IEEE 802.1X authentication' is unchecked. Save all changes.

Next, connect the endpoint in the Cisco Catalyst 2960 switch. After a few second, open a web browser and try to open any website - say http://packetfence.org. You should now see the captive portal. You should only need to accept the terms and conditions for gaining network access.

This section will show you how to allow guests to register endpoints using their email address. PacketFence sends a PIN code to the guest’s email address. That code will then be required to complete the registration process.

This section will show you how to enable SMS authentication on the captive portal so that guests use their cellular phone number to register their endpoints. PacketFence will send an SMS PIN code to the guest phone number. That code will be required to complete the registration process. The SMS code will be sent by PacketFence over email - using popular SMTP-to-SMS gateways.

Some of the key concepts presented in this section are:

Roles in PacketFence can be created from Configuration → Policies and Access Control → Roles. From this interface, you can also limit the number of devices users belonging to certain roles can register.

Roles are dynamically computed by PacketFence, based on the rules (ie., a set of conditions and actions) from authentication sources, using a first-match wins algorithm. Roles are then matched to VLAN or VLAN pool or internal roles or ACL on equipment from the Configuration → Policies and Access Control → Switches module. For a VLAN pool instead of defining a VLAN identifier, you can set a value like that: 20..23,27..30 - which means that the VLAN returned by PacketFence can be 20 to 23 and 27 to 30 (inclusively). There are three algorithms: one based on a hash of the username (default one), another one based on a round-robin (last registered device +1) and one that selects a VLAN randomly in the pool.

Configuration → Policies and Access Control → Roles, click on New Role. Provide the following information:

Redo the operation of the other role:

Let’s say we have two roles: employee and corporate_machine (defined above).

Now, we want to assign roles to employees and their corporate machines using Active Directory (over LDAP), both using PacketFence’s captive portal.

From the Configuration → Policies and Access Control → Authentication Sources, we select New internal source → AD. We provide the following information:

Then, we add an Authentication rules by clicking on the Add rule button and provide the following information:

Test the connection and save everything. Using the newly defined source, any username that actually matches in the source (using the sAMAccountName) will have the employee role and a 7 days Access Duration.

If you would like to differentiate user authentication and machine authentication using Active Directory, one way to do it is by creating a second authentication sources, for machines:

Then, we add an 'Authentication rules':

Using this configuration, employees can only connect corporate machines, not personal devices.

The inline enforcement is a very convenient method for performing access control on older network equipment that is not capable of doing VLAN enforcement or that is not supported by PacketFence.

An important configuration parameter to have in mind when configuring inline enforcement is that the DNS reached by these users should be your actual production DNS server - which shouldn’t be in the same broadcast domain as your inline users. The next section shows you how to configure the proper inline interface and it is in this section that you should refer to the proper production DNS.

Inline enforcement uses ipset to mark nodes as registered, unregistered and isolated. It is also now possible to use multiple inline interfaces. A node registered on the first inline interface is marked with an IP:MAC tuple (for L2, only ip for L3), so when the node tries to register on an other inline interface, PacketFence detects that the node is already registered on the first inline network. It is also possible to enable inline.should_reauth_on_vlan_change to force users to reauthenticate when they change inline network - you can change this from 'Configuration→Network Configuration→Inline' - by checking or not the 'Reauthenticate node' checkbox.

By default the inline traffic is forwarded through the management network interface but it is possible to specify another one by adding in pf.conf the option interfaceSNAT in inline section of the pf.conf configuration file. Alternatively, you can change this from 'Configuration→Network Configuration→Inline' in the 'SNAT Interface' section. It is a comma delimited list of network interfaces like eth0,eth1.2. It’s also possible to specify a network that will be routed instead of using NAT by adding in conf/networks.conf an option nat=no under one or more network sections (take care of the routing table of the PacketFence server).

In order to build an inline deployment of PacketFence setup you need :

PacketFence can be configured right from the start using the PacketFence configurator for inline enforcement. In this example, we will continue building on top of our initial deployment by adding a new inline interface to our PacketFence installation.

The first step is to add a dedicated Network Interface Card (NIC) to your current PacketFence installation. In our example, our new NIC will be named ens192. The PacketFence web interface will list all currently installed network interfaces on the system. An IP and a netmask will be visible if the network interface is configured (either by DHCP or already manually configured). You can edit those ones, create/delete VLANs on physical interfaces and enable/disable interfaces. Note that these changes are effective immediately. Persistence will be written only for enabled interfaces. Which means that if you change your management IP address, to pursue the configurator, you will need to go on this new IP address you just set. At all time, you will need to set a Management interface. That means that the required interface types for inline enforcement are:

Note that PacketFence will provide these services on its inline interface:

From 'Configuration→Network Configuration→Interfaces', click on the ens192 logical name. Provide the following information:

Click on 'Save' and toggle the new interface to 'On'.

Once done, your PacketFence server should have the following network layout:

Please refer to the following table for IP and subnet information :

Finally, from Status→Services, restart the haproxy-portal, pfdhcp, iptables, pfdhcplistener, pfdns services.

In an inline configuration, the required configurations for network devices (desktops, tablets, printers, etc.) will be to make sure they can all communicate with PacketFence. In other words for a switch you will need to configure every ports on which devices will be connected using the access mode with all of them in the same inline network. Access point will be connected as device to be in the inline subnetwork.

Example with a Cisco switch:

You should be in mode '#conf-t' if not execute 'configuration terminal' in your CLI.

Now you can connect any devices that you want to be in the inline network in any of the port you have just configured.

Next thing we do is to add a new connection profile - for devices coming from the inline network. We want to show users the captive portal with our Null authentication sources.

From 'Configuration→Policies and Access Control→Connection Profiles', click on 'Add Profile'. Provide the following information:

Then click on 'Save'.

You can now test the registration process. In order to do so:

From the computer:

Register the computer using using the Null authentication source.

Once a computer has been registered:

In order to build a VLAN isolation setup you need :

Throughout this configuration example we use the following assumptions for our network infrastructure:

Please refer to the following table for IP and Subnet information :

Note that PacketFence will provide these services on its registration and isolation VLANs:

First of all, make sure you add a new NIC to your PacketFence server and you set the switch port where that NIC is connected in trunk. If you prefer, you can also set your management interface as trunk and set the PVID to your management VLAN on the switch port where that management is connected.

We will create three interfaces VLAN for registration, isolation and normal using the management interface.

The required interface types for VLAN enforcement are:

Note that you can only set one (1) management interface.

In our example, we will create three new VLANs on the wired interface on our new trunk interface (ens224) To do so, click the 'Add VLAN' button besides the wired interface for each of the needed VLAN:

Here’s a sample configuration for both of them:

Registration

Isolation

Normal

According to our example, we’ll associate the correct type the each interfaces.

Make sure that those three interfaces are in an enabled state for the persistence to occur. We also need to set the Default Gateway which will generally be the gateway of the management network.

Finally, from Status→Services, restart the haproxy-portal, pfdhcp, iptables, pfdhcplistener, pfdns services.

Now let’s modify our switch configuration to enable our new registration and isolation VLANs. From 'Configuration→Policies and Access Control→Switches', click on our Cisco 2960 switch we added earlier (172.21.2.3).

From the Roles tab, make sure you specify the following information:

Disable 'Role by Switch Role' and 'Role by Web Auth URL'.

Click on the 'Save' button once completed.

Next thing we do is to add a new connection profile - for devices coming from the registration network. We want to show users the captive portal with our Null authentication sources.

From 'Configuration→Policies and Access Control→Connection Profiles', click on 'Add Profile'. Provide the following information:

Then click on 'Save'.

PacketFence provides a RADIUS auditing module which allows you to be aware of all the incoming RADIUS requests/responses handled by PacketFence. The RADIUS auditing module is available from Auditing → RADIUS Audit Log. Advanced search criterias can be specified to create complex search expressions - which can be saved for later use. Clicking on a RADIUS log entry will display the endpoint information, where the RADIUS request originated from and the RADIUS payload exchanged between the NAS and PacketFence.

Log files are located under /usr/local/pf/logs. Except packetfence.log which contains logs from different services, each service has its own log file. You can see full list of log files available when using Audit → Live logs menu in web admin.

The main logging configuration file is /usr/local/pf/conf/log.conf. It contains the configuration for the packetfence.log file (Log::Log4Perl) and you normally don’t need to modify it. The logging configuration files for every service are located under /usr/local/pf/conf/log.conf.d/.

First, check the FreeRADIUS logs. The file is located at /usr/local/pf/logs/radius.log.

If this didn’t help, run FreeRADIUS in debug mode. To do so, start it using the following commands.

For the authentication radius process:

For the accounting radius process:

Additionally there is a raddebug tool that can extract debug logs from a running FreeRADIUS daemon. PacketFence’s FreeRADIUS is pre-configured with such support.

In order to have an output from raddebug, you need to either:

Now you can run raddebug easily:

The above will output FreeRADIUS' authentication debug logs for 5 minutes.

Use the following to debug radius accounting:

See man raddebug for all the options.

Go in the Administration interface under Configuration → Policies and Access Control → Domains → Active Directory Domains.

Click New Domain and fill in the information about your domain.

Where :

The captive portal of PacketFence allows a guest/user to register using his Google, Facebook, LinkedIn, Windows Live, OpenID Connect or Github account.

For each providers, we maintain an allowed domain list to punch holes into the firewall so the user can hit the provider login page. This list is available in each OAuth2 authentication source.

You must enable the passthrough option in your PacketFence configuration (fencing.passthrough in pf.conf).

PacketFence supports Eduroam and allows participating institutions to authenticate both locally visiting users from other institutions as well as allowing other institutions to authenticate local users.

Understanding of the Eduroam authentication workflow.

PacketFence supports SAML authentication in the captive portal in combination with another internal source to define the level of authorization of the user.

First, transfer the Identity Provider metadata on the PacketFence server. In this example, it will be under the path /usr/local/pf/conf/idp-metadata.xml.

Then, transfer the certificate and CA certificate of the Identity provider on the server. In this example, they will be under the paths /usr/local/pf/conf/ssl/idp.crt and /usr/local/pf/conf/ssl/idp-ca.crt. If it is a self-signed certificate, then you will be able to use it as the CA in the PacketFence configuration. Make sure -----BEGIN CERTIFICATE----- and -----END CERTIFICATE---- headers are present in these certificate files.

Then, to configure SAML in PacketFence, go in Configuration → Policies and Access Control → Sources and then create a new Internal source of the type SAML and configure it.

Where :

Once this is done, save the source and you will be able to download the Service Provider metadata for PacketFence using the link 'Download Service Provider metadata' on the page.

Configure your identity provider according to the generated metadata to complete the Trust between PacketFence and your Identity Provider.

In the case of SimpleSAMLPHP, the following configuration was used in metadata/saml20-sp-remote.php :

PacketFence integrates the ability to use a payment gateway to bill users to gain access to the network. When configured, the user who wants to access the network / Internet is prompted by a page asking for it’s personal information as well as it’s credit card information.

PacketFence currently supports two payment gateways: Authorize.net, Paypal and Stripe.

In order to activate the billing, you will need to configure the following components :

PacketFence also supports calling an external HTTP API as an authentication source. The external API needs to implement an authentication action and an authorization action.

PacketFence supports integrating with the Azure Active Directory for authenticating users on the captive portal, the admin interface and for 802.1X users using EAP-TTLS PAP. If your only goal is to authenticate users on the captive portal, using the OpenID implementation of Azure AD may be better suited. This section is aimed at providing username/password authentication through Azure AD.

The PacketFence captive portal flow is highly customizable. This section covers Portal Modules which define the behavior of the captive portal.

Available Portal Modules:

Surveys can be presented on the Captive Portal where results are stored in a dedicated database.

Once a user is registered they can self-register any device on the Portal by entering a MAC address that is matched with an authorized device list through Fingerbank. The device is registered to the user and can be assigned into a specific category.

A self-service portal policy can be configured in Configuration → Advanced Access Configuration → Self Service Portal. Define the behavior by either modifying the default policy, or creating a new policy. If the "Role to assign" is left empty, the role of the user that is registering the device will be reused. Optionally select one or more "Allowed OS" to restrict which operating systems can be registered - as it may be useful to only allow gaming devices.

In Configuration → Policies and Access Control → Connection Profiles, assign the "Self service policy", then click Save.

Once a user is registered they can self-service and manage all their own devices on the Portal. Devices can be unregistered, reported as stolen (trigger a "LOST of Stolen" Security Event). Local users which are defined in the PacketFence database can manage their password.

By default all users can manage all their own devices through the self-service portal. In Configuration → Advanced Access Configuration → Self Service Portal, choose a Self Service Portal, specify the "Self Service Portal → Allowed roles", then click Save.

Optionally, it can be disabled in all but the PacketFence management network (registration, isolation, inline) by enabling Status URI only on management interface in Configuration → Advanced Access Configuration → Captive Portal.

In Configuration → Policies and Access Control → Connection Profiles, assign the "Self service policy", then click Save.

Passthroughs allow access from users confined inside the registration network to specific resources on the outside. An example is to allow clients on the Captive Portal access to an external password reset server.

Passthroughs can be done with either DNS resolution and iptables, or with Apache’s mod_proxy module, or both. A domain configured for both gives priority to DNS passthroughs.

In Configuration → Network Configuration → Networks → Fencing, enable "Passthrough", then click Save.

Restart the iptables service:

Proxy requests can be intercepted and forwarded to the Captive Portal. This only works on Layer-2 networks where PacketFence is the default gateway.

In Configuration → Network Configuration → Networks → Fencing, enable "Proxy Interception". Add all the ports to intercept in "Proxy Interception Port", then click Save.

Idle devices (ex: unregistered students) consume resources and generate unnecessary load on the Captive Portal and registration DHCP server.

In large registration networks Parking can be used to provide a longer lease and provide a lightweight Captive Portal that minimizes resource consumption. When a device is parked the Captive Portal provides a message to the user explaining the device is unregistered and has exceeded the parking threshold, and a button to unpark the device.

In Configuration → Network Configuration → Networks → Device Parking, set the "Parking Threshold" (seconds). A value of 21600 / 6 hours is suggested. If a device is idle in the registration network for more than 6 hours, Security Event 1300003 (see below) will be triggered and the device will be parked.

Optionally the lease length (seconds) can also be set in "Parking lease length". If the device is parked with a "Parking lease length" of 1 hour, then immediately unparked, the next detection will occur in 1 hour, even if the "Parking threshold" is a lower value.

PacketFence provides a default connection profile. The follow parameters are important to configure whether the default connection profile is used or a new one is created:

For some browsers, it is preferable to redirect the user to a specific URL instead of the URL the user originally intended to visit. For these browsers, the URL defined in redirecturl will be where the user is redirected. Affected browsers are Firefox 3 and later.

This IP is used as the web server that hosts the common/network-access-detection.gif which is a pixel-gif used to detect network access. The IP cannot be a domain name since it is used during Registration and Isolation where DNS is black-holed. It is recommended to allow users to reach the PacketFence server with the PacketFence LAN IP.

In some cases, a different captive portal may be presented (see below for the available customizations) according to the SSID, the VLAN, the switch IP/MAC or the URI the client connects to. To do so, PacketFence uses the concept of connection profiles to provide this possibility.

When configured, connection profiles will override default values. When no values are configured in the profile, PacketFence will use the values from the "default" connection profile.

Below the different configuration parameters for each connection profile are provided. The only mandatory parameter is "filter", otherwise, PacketFence will not be able to correctly apply the connection profile. The parameters are set in /usr/local/pf/conf/profiles.conf:

Connection profiles should be managed from PacketFence’s Web administration GUI - from the Configuration → Policies and Access Control → Connection Profiles section. Adding a new connection profile will make a copy of the default templates - which can then be modified as desired.

Example with common filters:

This section defines how to create an advanced filter to match specific attributes.

The following attributes are supported:

Filter engines support the use of macros in the text field:

Filters can be defined directly in the portion of code that re-evaluates the VLAN or performs API calls when a RADIUS request is received. These filters can be defined in Configuration → Advanced Access Configuration → Filter engines.

These rules are available in different scopes:

And can be defined using different criteria:

Default VLAN filters are defined in the configuration that can be used to achieve the following goals:

Several examples on how to use and define filters are included in /usr/local/pf/conf/vlan_filters.conf.defaults.

Filters can be defined directly in the portion of code that returns RADIUS attributes or performs API calls when a RADIUS request is received. These filters can be defined in Configuration → Advanced Access Configuration → Filter engines.

We added the ability to specify filters directly in the portion of code that return RADIUS attributes or do a call to the API. These filters can be defined in Configuration → Advanced Access Configuration → Filter engines.

These rules are available in thoses scopes:

All the packetfence. and eduroam. scopes are explained in /user/local/pf/conf/radius_filters.conf.

And can be defined using different criteria like:

Default RADIUS filters are defined in the configuration that can be used to achieve the following goals:

Several examples on how to use and define filters are included in /usr/local/pf/conf/radius_filters.conf.defaults.

Multiple realms can be defined to select which domain is used to authenticate users.

A Realm is defined with a regex in order to match multiple formats.

For example in the ACME realm we define the regex like this:

Thus in the case of username mickey@la.acme.com, the realm is defined as la.acme.com - which is included in the RADIUS request - and the user is mapped with the ACME realm.

Add your user’s entries at the end of the /usr/local/pf/raddb/users file with the following format:

To perform EAP-PEAP authentication using Microsoft Active Directory, please refer to the Active Directory documentation from the Authentication Mechanism section.

To authenticate 802.1X connection against OpenLDAP you need to define the LDAP connection in /usr/local/pf/raddb/modules/ldap and be sure that the user password is define as a NTHASH or as clear text.

Next in /usr/local/pf/raddb/sites-available/packetfence-tunnel add in the authorize section:

This section will allow local credentials created during guest registration to be used in 802.1X EAP-PEAP connections.

First create a guest SSID with the guest access you want to use (Email, Sponsor or SMS, …​) and activate 'Create local account' on that source.

At the end of the guest registration, PacketFence will send an email with the credentials for Email and Sponsor and SMS.

To enable this feature, go in 'Configuration→System Configuration→RADIUS→General' and enable 'Authenticate against local users database'. Once saved, restart the radiusd service.

The goal here is to use the local user to authenticate 802.1X device.

To enable this feature, go in 'Configuration→System Configuration→RADIUS→General' and enable 'Authenticate against local users database'. Once saved, restart the radiusd service.

This section will allow you to limit a brute force attack and prevent the locking of Active Directory accounts.

Edit /usr/local/pf/conf/radiusd/packetfence-tunnel

By default it will reject for 5 minutes a device that has been rejected twice in the last 5 minutes. Fell free to change the default values in raddb/policy.d/packetfence and in raddb/mods-enabled/cache_ntlm

Test your setup with radtest using the following command and make sure you get an Access-Accept answer:

RADIUS Accounting is usually used by ISPs to bill clients. In PacketFence, we are able to use this information to determine if the node is still connected, how much time it has been connected, and how much bandwidth the user consumed.

PacketFence uses RADIUS Accounting to display Online/Offline status in webadmin in Nodes menu.

RADIUS Proxy is a way to proxy authentication and accounting requests to other radius server(s) based on the realm. Let’s say you want to authenticate users on an Active Directory where there is a NPS server running and you don’t want to join the PacketFence’s server to this domain or in the case you want to integrate PacketFence in a Passpoint setup then this section is for you.

To do that in PacketFence you need first to define the target RADIUS server(s) in Configuration → Policies and Access Control → Authentication Sources, and create the RADIUS source(s) (ACME1 ACME2). In the Source configuration, fill the mandatory fields and add the options to define the home_server in FreeRADIUS. (https://github.com/FreeRADIUS/freeradius-server/blob/v3.0.x/raddb/proxy.conf)

Per example for the RADIUS Source ACME1:

$src_ip is a way to dynamically use the correct source ip address of the system in case of multiples network interfaces.

Next go in Configuration → Policies and Access Control → REALMS, and add a new realm.

(type definition can be found here https://wiki.freeradius.org/features/Proxy)

Authorize from PacketFence will send the request to PacketFence to compute the role and access duration of the device.

In this case the easiest way to achieve that is to create a Authorization source (with rules), assign this source to a connection profile where you enabled "Automatically register devices" and where you defined a filter like Realm = acme.com .

Click on Save and restart radiusd service.

Now when a device connect with the username bob@acme.com then the authentication and accounting requests will be forwarded to one of the ACME RADIUS servers.

RADIUS EAP Profiles allow you to select a specific EAP profile in PacketFence based on the realm of the user.

In this EAP profile you can define: Certificates configuration. OCSP configuration EAP-Fast configuration TLS Configuration

And link all these configuration together.

For example the realm ACME.COM needs to use the CA certificate from ACME CA and the other realms need to use the default one.

To do that go in Configuration → System Configuration → RADIUS → SSL Certificates and create a new profile. Next go in Configuration → System Configuration → RADIUS → TLS Profiles and create a new TLS profile and select the Certificate profile created just before. Then create the EAP profile in Configuration → System Configuration → RADIUS → EAP Profiles and create a new EAP profile and select the TLS profile created before (PEAP Profile for exemple)

The last thing to do is to link the EAP profile with your realm configuration, to achieve that go in Configuration → Policies and Access Control → Domains → REALMS and edit the ACME.COM realm (create it if it’s not already the case) then choose the EAP profile you created before in the EAP configuration parameter.

Restart packetfence-radiusd-auth.service to generate the new RADIUS configuration. (systemctl restart packetfence-radiusd-auth.service)

To benefit from all the advantages of the Fingerbank project, the onboarding step is required to create an API key that will then allow interaction with the upstream project. That can easily be done only by going in the "Settings" menu item under the "Fingerbank" section of the PacketFence "Configuration" tab. From there, an easy process to create and save an user/organization specific API key can be followed. Once completed, the full feature set of Fingerbank can be used.

Updating the Fingerbank data can’t be easier. The only requirement is the onboarding process which allows you to interact with upstream project. Once done, an option to "Update Fingerbank DB" can be found on top of every menu item sections under "Fingerbank". Process may take a minute or two, depending on the size of the database and the Internet connectivity, after which a success or error message will be show accordingly. "Local" records are NOT being modified during this process.

Saying that we don’t know everything is not false modesty. In that sense, the "Submit Unknown/Unmatched Fingerprints" option is made available (after onboarding) so that unknown fingerprinting data going in and out on your network can easily be submitted to the upstream Fingerbank project for further analysis and integration the in the global database.

By default, PacketFence is configured to interrogate the upstream Fingerbank project (if onboarding has been completed) to fulfill a query with unmatched local results. Unmatched local results can result of an older version of the Fingerbank database or a requirement for a more complex algorithm due to the data set. That behavior is completely transparent and can be modified using the "Settings" menu item under the "Fingerbank"section of the PacketFence "Configuration" tab.

It is possible for an administrator who wants to customize an existing record (or create a new one) to do so using the "Local" entries. An upstream record (DHCP Fingerprint, DHCP Vendor, MAC Vendor, User Agent, Device type, even a Combination) can be cloned and then modified on a local basis if needed. Local records are always matched first since their purpose is to 'override' an existing one. A local combination can be created to match either "Local" or "Upstream" or both entries to allow identification of a device.

Fingerbank settings can easily be modified from the "Settings" menu item under the "Fingerbank" section of the PacketFence "Configuration" tab. There’s documentation for each an every parameter that allow easier understanding.

Using Fingerbank, you can perform detection of potential MAC spoofing by seeing if a device changes from a device class to another (ex: a device goes from Windows to a printer) and trigger a security event and potentially isolate the endpoint. An example security event using this trigger is available (security eventi ID 1300006, name "Fingerbank device class change").

This feature is disabled by default, in order to configure it, go in Configuration → Compliance → Fingerbank Profiling → Device Change Detection.

You should then check Enabled to activate this feature. You will then have the choice between triggering the security event on any device class change or on a specific set of changes.

A network behavior policy is a template, used by the Fingerbank Collector, to determine if the devices matching the criterias defined in the template ultimately deviate from a normal network usage pattern. You can create new templates from Configuration → Compliance → Network Anomaly Detection.

Network behavior policies can be consumed from PacketFence’s Security Events module.

After creating a network behavior policy, you can use it from the Security Events module of PacketFence. From Configuration → Compliance → Security Events, click on New Security Event.

You can use your policy by first adding a new trigger. The network behavior policy can be selected after defining an internal event on the following attributes:

Once done, the appropriate policy can be selected. If you want your entire network policy to be checked in the Security Events module, you must create three triggers - one with each of the attribute listed above together with your appropriate policy selected. You can look at the default security events Fingerbank profile anomaly (1300007) and Fingerbank detected blacklisted communication (1300008) for some examples on how to create customized security events to fulfill your requirements.

You are now able to create syslog parser using regex. This will allow you complex filters and rules to work on data receive via syslog.

Configuring a Regex Syslog Parser

Regex Syslog Parser Rule

Defining Actions

An action have two parts

Example Action

Regex -

Action -

PacketFence already contains a syslog parser for Suricata. This is an example to raise a security event from a syslog alert on the Suricata SID.

The first step is to create the syslog regex parser and then create the security event.

This documentation is based on Security Onion v2.3. You can review its documentation at: https://docs.securityonion.net/en/2.3

All commands are done through the SSH CLI.

ERSPAN permits to mirror a local port traffic (low bandwidth) to a remote IP, E.G: your Security Onion already deployed box. ERSPAN encapsulates port traffic into ERSPAN then GRE and send that traffic to one/multiple destination(s). ERSPAN is a Cisco technology which is available only on some platforms, including: Catalyst 6500, 7600, Nexus, and ASR 1000.

One way of accessing encapsulated traffic at the destination host is through a software called RCDCAP, which is a daemon that creates a virtual interface if not existing, on which both GRE and ERSPAN headers are decapsulated prior to the traffic being injected to the previous interface. Security Onion can then feed on that interface like it would on any other, and if the RCDCAP daemon dies, continue to listen to that interface even though decapsulated traffic won’t be available anymore.

Assumptions for the example: The switch is at IP 172.16.0.1, the monitored switch port is GigabitEthernet0/10 and the Security Onion monitoring destination IP is 10.10.10.10 on eth2, eth2 ideally being a dedicated interface.

On Security Onion:

On the Switch:

In order for the compliance checks to correctly work with PacketFence (communication and generate security events inside PacketFence), you need to configure these sections:

PacketFence supports integration with Rapid7 to start scans automatically when a device connects to the network and also to receive the Rapid7 alerts via syslog.