PacketFence Upgrade Guide

The PacketFence servers have a daily backup done, each night (0:30AM).

To externalize those backups, locate them in:

File description:

To make a "manual" backup, execute the following command:

Like the daily automatic backups, the file will be located in:

Exportable file will be available, tagged with the Date and Time of the backup.

For cluster maintenance issues or service failures, see Service Startup Failures, Checking the MariaDB sync, and Cluster Database Recovery in the Troubleshooting section.

Running the previous script will extract the current Samba configuration and convert it to the NTLM_AUTH_API format.

The script will detect if PacketFence is running in a cluster environment and will compare the Samba machine name with the hostname:

In both cases the NTLM_AUTH_API is supported in a cluster, and each machine joined to the domain must have the exact same password.

Depending of the action of the script, there may be a configuration change for the domain(s) in Configuration → Policies and Access Control → Active Directory Domains.

Fill out the form and specify the Machine account password (record it to reuse it again later) and the credentials of an AD admin account who is able to join a machine to the Domain. Click Save and check the Machine account was created in the Active Directory Domain.

For each remaining server in the cluster:

If domain joining fails during upgrade, see Authentication Failures and RADIUS Debugging in the Troubleshooting section.

Since 13.2 PacketFence implements a local NT Key cache to track failed login attempts to prevent the account from being locked on the AD. To implement the NT Key cache perform the following steps:

Since 13.2 PacketFence is able to receive events from the AD to report password changes, which allows PacketFence to reset failed login attempts in the NT Key cache. To add a new admin role to receive these events through the PacketFence API perform the following steps:

Since 13.2 PacketFence has reworked the Cisco, Juniper and Meraki switch modules to use OS versions rather than hardware versions. To update the current switch configurations to the new OS versions perform the following:

Packetfence 14.0, we change the OS from Debian 11 to Debian 12.

To use PacketFence 14.0 on Debian 12, a new Debian 12 VM will need to be created, then import/export from the previous installation to the new one.

Automated upgrade is available on RedHat 8.

Since 14.0 PacketFence is able to receive events from the FleetDM servers, which allows PacketFence to detect policy violations or CVEs of devices managed by FleetDM. To add a new admin role to receive these events through the PacketFence API perform the following steps:

Note: Hostnames using the %h prefix or suffix must still be used when upgrading from a previous version unless specifying individual machine account names for each node.

In-place upgrades supported - Follow standard upgrade procedures:

New OS installation required - In-place OS upgrades not supported:

To simplify the upgrade process to PacketFence 14.0 and future versions, we utilize a custom export/import procedure that handles MariaDB version differences automatically.

CRITICAL MariaDB Pre-Requisites for Export/Import

The export/import procedure handles MariaDB version differences between source and target systems automatically. However, specific pre-requisites must be met:

Verify MariaDB Backup Compatibility

Check that mariadb-backup matches your MariaDB server version:

Expected MariaDB Versions by OS:

Alternative Export Method: If mariadb-backup is not installed, use the standard export process at export on current installation.

Additional Prerequisites: Review assumptions and limitations before proceeding.

Prerequisites for PacketFence 14.1+ on EL8:

Install the upgrade package before running automated upgrade:

Standard Upgrade Process:

Follow the automated upgrade: automation of upgrades

Cluster-specific procedure - Follow the cluster upgrade guide: Performing an upgrade on a cluster

EL8-specific step: When upgrading node C, install the RedHat EL8 upgrade package first PacketFence_Upgrade_Guide.html.html, then proceed with standard cluster node upgrade procedures.

The temporary password table has been extended to include roles information. Moreover, an "admin" user is now automatically created. The default password is also "admin". Finally, a new table has been added for saved searches in the new Web administrative interface.

PacketFence v4 received a major overhaul, especially regarding the authentication sources. Authentication modules found in conf/authentication/ are no longer being used and have been replaced by the conf/authentication.conf file. While this file can be hand-edited, you must create your authentication sources and perform roles-mapping using the Configuation > Users > Sources page from PacketFence’s Web administrative interface.

Also, in PacketFence v4, the VLANs can be assigned in conf/switches.conf by constructing the parameter names from the VLAN names and the Vlan suffix. The VLAN names must match one of the default names (registration, isolation, macDetection, inline, and voice) or one of the defined roles. If you were using custom VLANs, you must create a new role per VLAN and assign them accordingly.

Other key changes were done, such as:

For all parameters related to authentication (categories, access duration, sponsor authentication, etc.), you must now set proper actions in the conf/authentication.conf file.

Finally, the pf must be sudoer access to the /sbin/ip (and others) binary. As root, please do:

The method pf::authentication::authenticate now expects an array of pf::authentication::Source objects instead of an array of source IDs.

The methods getSourceByType, getInternalSources, and getExternalSources of the module pf::Portal::Profile now return pf::authentication::Source objects instead of source IDs.

The category column in the temporary_password should not be mandatory.

Also, the access_level of the temporary_password table is now a string instead of a bit string.

Make sure you run the following to update your schema:

The parameters trapping.redirecturl and trapping.always_use_redirecturl from pf.conf (or pf.conf.defaults) were moved to the default portal profile in profiles.conf.

The parameter registration.range has been deprecated. Make sure you remove it from your configuration file.

The action set_access_level of authentication sources in authentication.conf must now match one of the admin roles defined in adminroles.conf. The previous level 4294967295 must be replaced by ALL and the level 0 by NONE.

Adjust your configuration files accordingly.

Once the configuration completed, update the file /usr/local/pf/conf/currently-at to match the new release number.

The person table has many new columns that can be used for registration.

The node table has new columns to store the time and bandwidth balances of a node.

The node table has also a new column to keep the audit-session-id from the RADIUS request to use with the CoA.

Added a new column config_timestamp in radius_nas table.

The locationlog table has new columns to store the switch IP and MAC when using dynamic controllers.

New table for inline (layer 3) accounting.

New table for WRIX data.

Make sure you run the following to update your schema:

The parameter guests_self_registration.mandatory_fields from pf.conf (or pf.conf.defaults) was moved to the default portal profile in profiles.conf.

The parameters registration.gaming_devices_registration and registration.gaming_devices_registration_role are replaced with registration.device_registration and registration.device_registration_role.

Adjust your configuration files accordingly.

The captive portal has been rewritten using the Catalyst MVC framework. Any customization to the previous CGI scripts must be ported to the new architecture.

Once the configuration completed, update the file /usr/local/pf/conf/currently-at to match the new release number.

The person table has 2 new column to keep the portal and the source used to authenticate.

The tables email_activation and sms_activation have been merged in a table named activation. It has an additional column to keep the portal used to register.

Make sure you run the following to update your schema:

The parameters VlanMap and RoleMap have been added in switches.conf; be sure to add them in the [default] switch section.

The OAuth passthroughs will not be activated unless trapping.passthrough in pf.conf is enabled. Make sure you enable it if you have OAuth authentication sources (Google, Facebook, Github, LinkedIn and Windows Live).

Once the configuration is completed, update the file /usr/local/pf/conf/currently-at to match the new release number.

Introduced the 'iplog_history' table for easier cleanup of the existing 'iplog' table.

Make sure you run the following to update your schema:

The serialization of the objects in the cache changed, making all the previous cached objects invalid. With PacketFence completely stopped do :

Once completed, update the file /usr/local/pf/conf/currently-at to match the new release number (PacketFence 4.4).

The class table has a new column delay_by.

Make sure you run the following to update your schema:

A new parameter 'delay_by' has been introduced in the violation configuration. Make sure to add the following to the 'defaults' section of 'conf/violations.conf' to avoid any problem.

delay_by=0s

Once completed, update the file /usr/local/pf/conf/currently-at to match the new release number (PacketFence 4.5).

The locationlog and locationlog_history table have 2 new columns stripped_user_name and realm. We added new INDEX on iplog, violation and locationlog tables.

Make sure you run the following to update your schema:

Code to match violation template pages have been reworked. Make sure to lowercase FR to fr in french template files name.

Realm are now managed by Freeradius server so if your users authenticate with a username like username@acme.com then add the realm acme.com in the Radius Realms configuration menu and in your Active Directory source select 'Use stripped username'.

Once completed, update the file /usr/local/pf/conf/currently-at to match the new release number (PacketFence 4.6).

The 'node' table has a new column (machine_account).

Make sure you run the following to update your schema:

Once completed, update the file /usr/local/pf/conf/currently-at to match the new release number (PacketFence 4.7).

Before making any changes to your database, ensure that you have a backup. A complete database backup can be taken using this command:

If your database is more than a few hundred megabytes, you may also want to consider using a tool such as Percona XtraBackup which makes for much faster restores than mysqldump.

Multiple changes have been made to the database schema. You will need to update it accordingly. Since we will be dropping and recreating the 'iplog' table it is essential that you have a backup if you need the data it contains.

Make sure you run the following to update your schema:

You must manually enter the MySQL password of the pf user in the conf/pfconfig.conf file. The MySQL password is saved in the conf/pf.conf file under the [database] section. Copy the following from conf/pf.conf to conf/pfconfig.conf:

The violation triggers have been reworked for the new Fingerbank integration. We highly suggest you copy conf/violations.conf.example over conf/violations.conf and then reconfigure any violations you had before.

Also, ensure you adjust the following triggers to their new ID (Can be found under 'Configuration→Fingerbank'):

The OS trigger has been deprecated over the new dhcp_fingerprint trigger. You will need to adjust these triggers to the new ids as well as renaming them.

The iptables configuration file doesn’t use the generated rules '%%input_mgmt_guest_rules%%' anymore. Make sure you remove this line from conf/iptables.conf.

Also a lot of additions were made to the iptables configuration file. Make sure you add the new rules in conf/iptables.conf.example to your existing iptables file or execute the following command to replace the whole file.

If you are using EAP MS-CHAP local authentication, meaning your 802.1x connections authenticate against your local database, you will need to ensure you deactivate password encryption in the database. In the administration interface, go in 'Configuration → Advanced' and set 'Database passwords hashing method' to plaintext

Once completed, update the file /usr/local/pf/conf/currently-at to match the new release number (PacketFence 5.0).

Multiple changes have been made to the database schema. You will need to update it accordingly.

Make sure you run the following to update your schema:

These two services have been disabled by default. If you are using SNMP traps enforcement on your switches (like port-security), ensure you re-enable them in 'Configuration→Services'.

The Microsoft Active Directory domain join configuration is now part of PacketFence. A migration script has been made so you can migrate an existing domain join into this configuration. Note that this step is not mandatory, as the old join method is still supported. But if you do not perform this step, you will not see its configuration from the PacketFence web administrative interface.

Simply execute the following script and follow its instructions /usr/local/pf/addons/AD/migrate.pl

Once completed, update the file /usr/local/pf/conf/currently-at to match the new release number (PacketFence 5.1).

Multiple changes have been made to the database schema. You will need to update it accordingly.

Make sure you run the following to update your schema:

If you are using an Active/Active cluster, you will need to adjust the monitoring database host to point to your database as it is not forced anymore.

In conf/pf.conf :

If you are using email registration, web-auth enforcement (external captive-portal), device registration feature, or anything that would require to access the captive portal from outside the registration/isolation VLANs, you might want (actually, you need otherwise it will no longer works!) to add the 'portal' type to the existing 'management' interface.

In conf/pf.conf :

Once completed, update the file /usr/local/pf/conf/currently-at to match the new release number (PacketFence 5.2).

Changes have been made to the database schema. You will need to update it accordingly.

Make sure you run the following to update your schema:

A downgrade in a package version may cause an error when trying to upgrade.

If you receive this error:

Run the following commands:

Once completed, update the file /usr/local/pf/conf/currently-at to match the new release number (PacketFence 5.3).

Changes have been made to the database schema. You will need to update it accordingly.

Make sure you run the following to update your schema:

Authentication sources rules have been reworked in a way to differentiate an 'authentication' rule and an 'administration' rule. Codewise, that means that codeflow will look into specific types of rules depending of the use case.

Please take a minute or two to go through the existing rules for each of the authentication sources and ensure there is no 'administration' class actions into an 'authentication' class rule and vice versa, otherwise the "invalid" action will be ignored.

Authentication sources rules structure is as follow:

For example, if an existing rule is as follow:

That existing rule will default to the 'authentication' class if none is being set. If that’s the case, the first action "Set access level of Web admin" will then be ignored.

To replicate that existing rule with the new classes, you would have to create two separate rules, as follow:

Rule for 'administration' purposes

Rule for 'authentication' purposes

Configuration will be validated on every start / restart so that "bogus" authentication sources / rules can be identified.

The Facebook API now requires to specify the fields to be defined in the query. In all your facebook sources, change the parameter protected_resource_url to https://graph.facebook.com/me?fields=id,name,email,first_name,last_name

Change the parameter scope to user,user:email in all your Github sources as PacketFence is now fetching the email address of the user when registering with Github.

monitoring.statsd_host and monitoring.statsd_port have been removed from pf.conf. If you have specified a specific host or port, remove them from your configuration and change them in /usr/local/pf/lib/pf/StatsD.pm

Once completed, update the file /usr/local/pf/conf/currently-at to match the new release number (PacketFence 5.4).

Changes have been made to the database schema. You will need to update it accordingly.

Make sure you run the following to update your schema:

The VLAN filter has been reworked to use a more generalized syntax to allow more complex filters to be created.

This mean nested conditions no longer need to specify the attribute in the condition.

So the following attribute

Should be rewritten as

The older syntax is still supported but will be deprecated in a future release.

The operators match and match_not has changed their behavior. They will match (or not match) the exact string given in the condition. The following condition

Will match node_info.computername only if it contians '^Bob'. It will not match if node_info.computername start with 'Bob'

If you need to use a regex then use the regex/regex_not operator. So the following condition should be changed from

To the following

The following parameters have been removed from pf.conf. Make sure to remove them from your file if configured.

Violations have been reworked and configuration changes are necessary to maintain functionnality.

In violations.conf the following actions have been renamed, please update them accordingly.

The following action have been removed from the violations :

Also in violations.conf, the parameter whitelisted_categories has been renamed into whitelisted_roles

The parameter billing_engine of the Portal Profiles has been deprecated. Remove it from all your profiles configuration in /usr/local/pf/conf/profiles.conf.

The billing engine of PacketFence has been reworked completely.

It will require to reconfigure existing billing providers from scratch as there is no retro-compatibility with the previous configuration.

Please see the Administration Guide for details on how to configure the billing engine.

Mod_qos configuration has been moved from "services" to "captive_portal" section. Make sure to apply the appropriate changes if needed.

Once completed, update the file /usr/local/pf/conf/currently-at to match the new release number (PacketFence 5.5).

Changes have been made to the database schema. You will need to update it accordingly.

Make sure you run the following to update your schema:

The file lib/pf/vlan/custom.pm has now been renamed to lib/pf/role/custom.pm. Most of the customizations that used to be made in vlan/custom.pm can now be handled by configuring a vlan filter. You should take a good look at your existing vlan/custom.pm and consider porting the changes to conf/vlan_filters.conf.

The scopes for the VLAN filters have changed. The following have been renamed according to these rules:

NormalVlan → RegisteredRole RegistrationVlan → RegistrationRole ViolationVlan → ViolationRole InlineVlan → InlineRole

If you have defined any filters in /usr/local/pf/conf/vlan_filters.conf, ensure to rename all references to the left hand side with the new names on the right hand side.

The default type for the switches now must be set explicitly. Add the following line in the default section of /usr/local/pf/conf/switches.conf

type=Generic

Once completed, update the file /usr/local/pf/conf/currently-at to match the new release number (PacketFence 5.6).

With the introduction of the ability to trigger a violation based on a MD5 hash detected by Suricata, a new trigger type has been introduced, requiring the modification of the actual 'suricata' trigger. Make sure to go through your violations configuration and change any 'suricata' trigger name for 'suricata_event'.

Changes have been made to the database schema. You will need to update it accordingly.

Make sure you run the following to update your schema:

Once completed, update the file /usr/local/pf/conf/currently-at to match the new release number (PacketFence 5.7).

The new registration devices parking requires that you add the following violation in /usr/local/pf/conf/violations.conf

The chained source has been deprecated in favor of a fully customizable flow in the captive portal.

Make sure you delete the source BEFORE upgrading your installation.

Once you upgrade, configure a portal module for each of your sources and a chained one that contains both. Refer to the administration guide for a detailed example.

The parameter mandatory_fields of the Portal Profiles has been deprecated. Remove it from all the profiles in profiles.conf

To configure mandatatory fields in the portal, refer to the 'Portal Modules' section of the Administration guide

You need to add the root_module parameter to your default portal profile. In profiles.conf add root_module=default_policy to the default portal profile

All the OAuth2 sources you have configured (Facebook, Github, Google, LinkedIn ,Twitter, Windows Live) need to be adjusted as the redirect URL is now the same for all the types.

In the admin interface change Portal URL from https://YOUR_HOSTNAME/oauth2/SOURCE_TYPE to https://YOUR_HOSTNAME/oauth/callback (where SOURCE_TYPE would be the lower case name of the source type). Note that this parameter is named redirect_url in the configuration file.

Use the Cisco::Catalyst_2960 switch module instead of the Cisco::Catalyst_2960_http as switch type.

Use the Cisco::WLC switch module instead of the Cisco::WLC_http as switch type.

The portalURL configuration parameter is now configured per-role so ensure you have http://ip_portal/$session_id assigned to the registration role in the Role by Web Auth URL section of the switch configuration.

See the Network Device configuration guide for additional details.

Google Project Fi have been added as a supported carrier. Since an ID is hardcoded on creation of a new entry in the 'sms_carrier' database table, a manual intervention may be required in the case the database schema update fails.

'expire' and 'maintenance' section have been reworked and 'expire' section is no longer a thing. Make sure to adjust configuration parameter accordingly if needed;

The 'REJECT' role is now a default standard role. If you already have such role, ensure no conflict exists.

Also, add the following line to the default section of switches.conf :

REJECTVlan = -1

If you have a domain configured directly in PacketFence (in 'Configuration→Domains'), you need to re-generate the associated configuration files as changes have been made to the samba configuration.

Using the CLI /usr/local/pf/bin/pfcmd generatedomainconfig or in the admin interface in 'Configuration→Domains', click 'Refresh domain configuration'

PacketFence 6 relies on FreeRADIUS 3 rather that FreeRADIUS 2 as provided in PacketFence 5. The configuration files, directory layout and "unlang" directives have changed significantly. The packaging will automatically rename the existing raddb directory to raddb-pre6. All your existing configuration and certificates (if stored under raddb/certs) should be preserved but may need to be merged with the new raddb directory layout if you customized them.

The configuration files under conf/radiusd/.example have also changed. Make sure to compare them to your conf/radiusd/ files if you have any customizations, and merge any *.rpmnew files that may have been created by the packaging.

The default location for the FreeRADIUS server certificates has changed from conf/ssl/ to raddb/certs/. The configuration of the certificates location is in conf/radiusd/eap.conf. You may point it to any valid certificate and key by setting the value of certificate_file and private_key_file respectively. It is not recommended to use the same server certificate for the HTTP services and the RADIUS server as the requirements for each are different. Reusing the same certificate will work, but you would be well advised to consider separate certificates.

Finally, the database schema for the RADIUS accounting tables and stored procedures have changed. Make sure to apply the database changes as described in the following section.

Significant changes have been made to the database schema. You will need to update it accordingly. An SQL upgrade script has been provided to upgrade the database from the 5.7 schema to 6.0.

Since the schema of the radacct table has been reworked, the script will rename the existing table to radacct2 and insert it’s content into the new radacct table. If your existing radacct table is large (as is sometimes the case), the operation may take a long time and consume a significant amount of disk space. Make sure to have plenty of both before running the upgrade script.

You can estimate the size of the existing radacct table by running the following command:

You should have at least twice as much space as that table uses in the filesystem on which the MySQL data directory is mounted (usually /var/lib/mysql).

If you do not have enough space or time, you may consider truncating the radacct table (or simply deleting some of the rows) before running the upgrade script.

When ready, run the following to update your schema:

Once completed, update the file /usr/local/pf/conf/currently-at to match the new release number (PacketFence 6.0).

You will also want to drop the radacct2 table from the database as it will no longer be needed.

The management IP(s) of PacketFence are now defined as switches with a forced RADIUS secret defined in /usr/local/pf/conf/local_secret. Make sure you reconfigure the secret in the file if necessary and that this file is synchronized on all your cluster members if that applies. Note that this doesn’t affect the RADIUS secret you have configured for wireless controllers and switches. It only affects RADIUS requests that originate from the management IP(s)

A change to the authorize URL of LinkedIn was made. Make sure to change the 'API Authorize Path' in all your LinkedIn source to /uas/oauth2/authorization.

The following file: /usr/local/pf/conf/radiusd/eap.conf was modified to use TemplateToolkit, you will need to replace it by /usr/local/pf/conf/radiusd/eap.conf.example, ensure to re-edit the new file and add your certificate if needed.

Rejoining the domains from PacketFence GUI is required.

Go under Configuration→RADIUS→Domains and click Rejoin for each domain configured.

The configuration of the Scan engines and the Provisioners has been reworked to use the Fingerbank device IDs in the OS matching. scan.conf and provisioning.conf need to be migrated to use the new values. A migration script should be run # [filename]/usr/local/pf/addons/upgrade/to-6.3-os-rewrite.pl`` to migrate the configuration. This will output the migrated configuration in /usr/local/pf/conf/provisioning.conf.new and /usr/local/pf/conf/scan.conf.new. First run the script and then validate that their content is fine. Once that is done, copy the files over the original ones using :

The Fingerbank database can now be hosted in the same MySQL database PacketFence uses.

In order to do so, you need to collect the database credentials from the PacketFence configuration:

Now, you need to create the database and assign the proper rights to the user by executing the following commands:

Replace myPassword by the password displayed (pass) when running the first command.

Next, head to 'Configuration→Fingerbank Settings' in the web administration interface and configure the following parameters:

After saving those new parameters, at the top of the same page, click 'Initialize MySQL database' to start the import process. Once that is completed, you will receive an e-mail to the one configured for alerting and PacketFence will start using the MySQL backend for the Fingerbank database.

Changes have been made to the database schema. You will need to update it accordingly. An SQL upgrade script has been provided to upgrade the database from the 6.3 schema to 6.4.

To upgrade the database schema, run the following command:

Rework of the external captive portal capabilities involves some significant changes in the switch modules configuration. Some switch modules have been moved to other ones and some others have been removed. Please adjust the configuration (type) accordingly within switches.conf.

To instruct a switch module to perform external captive portal enforcement, a new switch configuration parameter have been added. Make sure to adjust the following parameter to your needs in switches.conf

External captive portal URLs have also changed. Change them accordingly depending on the type of equipment you use:

Where portal_ip is the IP Address (or DNS name) of your captive portal as it was configured before

Upon PacketFence installation, a default cronjob will be in /etc/cron.d/. You should ensure you do not invoke the /usr/local/pf/addons/backup-and-maintenance.sh script from any other cronjob.

Once completed, update the file /usr/local/pf/conf/currently-at to match the new release number (PacketFence 6.4).

Changes have been made to the database schema. You will need to update it accordingly. An SQL upgrade script has been provided to upgrade the database from the 6.4 schema to 6.5.

To upgrade the database schema, run the following command:

The method signature of pf::node::node_register has been modified. Make sure you adjust any custom code / external scripts to handle the new returned values.

You must rename "controllerPort" to "disconnectPort" in your switches.conf configuration file. You can automate this using:

Eduroam authentication source is now an "exclusive" authentication source rather than an "external" one. That being said, ensure to adjust portal profile accordingly (an "exclusive" authentication source can be the only one configured in a portal profile).

In order to be sure all your logging facilities use the new logging backend which ensures the processes will not die in case of a logging failure, you must execute the following command:

The email templates have been moved from /usr/local/pf/conf/emails/ to /usr/local/pf/html/captive-portal/templates/emails/ as they are now configurable by portal profile. Also you can configure the language in which PacketFence should send emails to the administrator in the Advanced section of the configuration.

Make sure you run the following command after upgrading:

When whitelisting roles in a violation, the registration role will now match unregistered devices where before it would never match. Make sure to go through violations that may include this role to ensure it is relevant.

The "configfile" and "traplog" database tables are now deprecated. If you wish to reclaim the disk space used by those two database tables, they should be manually removed.

Once completed, update the file /usr/local/pf/conf/currently-at to match the new release number (PacketFence 6.5).

If you were using the default 'RoleMap = Y' in the conf/switches.conf it’s disabled by default now. You will need to put 'RoleMap = Y' under your switches or switch group configuration.

The requirement for MariaDB 10.1 means that a simple "apt upgrade" will not be enough. You will need to help apt through the upgrade by manually removing some packages and installing some others. The need to ensure you have backups cannot be overstated.

Make sure the apt database is up to date

Remove the MySQL 5.5 packages (do not purge them, as that would delete the database)

Install the newer Mariadb-10.1 packages

Finally, upgrade the rest of the packages

Note that "full-upgrade" may also affect other packages you might have installed on the system if you had other software than PacketFence on it.

Upgrading to PacketFence 7+ will install a more recent version of MariaDB than the one that is shipped with CentOS.

In order to upgrade the MariaDB metadata files and tables, first stop any started process.

Then start a mysqld_safe process manually (this will start a background process)

Then, execute the upgrade script and enter the root password when prompted

When done, kill the mysqld_safe process we started before the update, reattach to it and wait for it to exit

Note that it might take up to a few minutes for the process to exit depending on the size of your database.

Once done, restart the MariaDB service (managed by PacketFence)

Changes have been made to the database schema. You will need to update it accordingly. An SQL upgrade script has been provided to upgrade the database from the 6.5 schema to 7.0.

To upgrade the database schema, run the following command:

All PacketFence services are managed individually via systemd unit files instead of one unit file (packetfence.service). When you updated the PacketFence package, it already set the system target to packetfence.target.

If you are hosting the MySQL/MariaDB service on your PacketFence servers (it is by default), you must now manage the service via packetfence-mariadb.service instead of mariadb.service. The changes in the server startup will be done automatically by the packaging.

Given the portal profiles have now been renamed to connection profiles, you need to ensure any admin role that allowed portal profile Create/Read/Update/Delete operations is updated to be valid for connection profiles.

Multiple parameters inside pf.conf have been renamed for better clarity. Execute the following to migrate the parameters.

Maintenance related configuration for pfmon has been moved to a dedicated configuration file (/usr/local/pf/conf/pfmon.conf).

In order to migrate your settings from pf.conf to pfmon.conf, run the following script:

Minor changes were made to the DHCP filters configuration (/usr/local/pf/conf/dhcp_filters.conf).

First, the computer_name attribute was renamed to computername to be consistent with the rest of the application. Then, the DhcpFingerbank scope was changed to Fingerbank

In order to rename those in an automated way:

The source of truth for roles is now in a configuration file (/usr/local/pf/conf/roles.conf) instead of being in the database. In order to pull the existing roles from your database into the configuration file, execute the following command:

New parameters have been introduced in conf/pfdetect.conf. Run the following script to migrate your configuration.

If you are using the LinkedIn OAuth2 source, a change has been made on their API, thus you will need to do the following:

Since all logging now goes through rsyslog, if you had edited the logging configuration (e.g. to forward logs to a centralized syslog server) ensure that the new logging rules in /etc/rsyslog.d/packetfence.conf do not conflict with your changes.

Take a look at /usr/local/pf/conf/log.conf and /usr/local/pf/conf/log.conf.d/* for the detailed configuration of the PacketFence services.

Clear the redis queue to avoid old stale jobs from being processes.

Given that haproxy is now the termination point for the captive portal, any SSL configuration you have in /usr/local/pf/conf/httpd.conf.d/ssl-certificates.conf must be ported so that it works with haproxy.

Easiest solution is to bundle your server cert, your intermediates (if any) along with the key in the default file used by the PacketFence haproxy process (/usr/local/pf/conf/ssl/server.pem)

In order to do so:

A complete re-visit of the database clustering stack was done in version 7.0. If you run your PacketFence installation in a cluster, ensure you read the following section.

We highly suggest you migrate your existing clustered installation using Corosync/Pacemaker to the new cluster stack of PacketFence that uses MariaDB Galera cluster. The easiest way to perform this is to build new servers and port your configuration (by copying the configuration files) and your database (using mysqldump). There are ways to migrate the 2 existing nodes to a 3 nodes cluster but this is not covered in this guide.

No changes to your clustering stack is required when using an external database.

First, no changes are required to your database stack as MariaDB supports being deployed in Active/Passive.

You will need to adjust the Corosync/Pacemaker configuration to take in consideration the changes made to systemd for PacketFence services. Before 7.0, PacketFence used to be controlled via a single systemd unit file while now it uses a multiple services grouped in targets. In order to mimic the single service behavior that was in previous versions, a unit file is provided here: https://github.com/inverse-inc/packetfence/blob/devel/packetfence-active-passive.service. You should install this file in /etc/systemd/system/packetfence.service and ensure there are no other leftovers of packetfence.service unit files on your system.

Then, you must adjust the systemd default target so PacketFence doesn’t start on boot and note that this should be done on every future upgrade of your system.

You should then change your Corosync configuration for MariaDB and PacketFence to the following:

The PacketFence Active Directory Domains integration now supports multiple DNS servers to be specified to find a DC. For this reason the parameter dns_server has been renamed to dns_servers in domain.conf. In order to automatically rename the parameters, run the following command:

In order to use the Ubiquiti switch module that has been renamed, run the following command:

Due to a change in the API of Instagram please change the scope if you are using an Instagram OAuth2 source. Replace 'scope=email' by 'scope=basic' in conf/authentication.conf under the section '[Instagram Source]'.

Changes have been made to the database schema. You will need to update it accordingly. An SQL upgrade script has been provided to upgrade the database from the 7.0 schema to 7.1.

To upgrade the database schema, run the following command:

PacketFence is now able to instruct Samba to «pin» a DC for authentication or use all of them. You should instruct Samba to connect to all domain controllers by adding the following to each of your domains in domain.conf:

And then regenerate the domain configuration:

The CC address for sponsors is now BCC. In order to adjust the configuration, execute the following:

Any custom authentication sources forms and templates would need to be copied to the new location.

Templates /usr/local/pf/html/pfappserver/root/authentication/source/type/ → /usr/local/pf/html/pfappserver/root/config/source/type/

Forms /usr/local/pf/html/pfappserver/lib/pfappserver/Form/Config/Authentication/Source → /usr/local/pf/html/pfappserver/lib/pfappserver/Form/Config/Source

Changes have been made to the database schema. You will need to update it accordingly. An SQL upgrade script has been provided to upgrade the database from the 7.1 schema to 7.2.

To upgrade the database schema, run the following command:

You will need to remove anything related to [device_registration] in the conf/pf.conf file. Once done, you will need to reconfigure any device registration policy using the following instructions: https://packetfence.org/doc/PacketFence_Installation_Guide.html#_devices_registration

You have to run the following script to change the configuration:

There was, in some cases, an issue where the database cluster was put in a read-only mode which then prevent it to comes back gracefully.

A modification have been made to now use the wsrep_ready state of the DB as a read only indicator. Therefore, PacketFence will stop putting the DB in read only on quorum + primary loss of MariaDB and trust wsrep_ready instead

Ensure you merge changes in the galera section of conf/mariadb/mariadb.conf.tt.rpmnew into conf/mariadb/mariadb.conf.tt

Once completed, update the file /usr/local/pf/conf/currently-at to match the new release number (PacketFence 7.3).

Changes have been made to the database schema. You will need to update it accordingly. An SQL upgrade script has been provided to upgrade the database from the 7.2 schema to 7.3.

To upgrade the database schema, run the following command:

If you use social login with LinkedIn OAuth2, you will need to adjust the list of domains that are passthroughs in the LinkedIn source.

For all your LinkedIn sources, change the domains to:

The redirection timer configuration (length of the timer bar at the end of the portal) has been moved from the fencing section to the captive_portal section. More precisely, it has moved from fencing.redirtimer to captive_portal.network_redirect_delay.

Changes have been made to the database schema. You will need to update it accordingly. An SQL upgrade script has been provided to upgrade the database from the 7.3 schema to 7.4.

To upgrade the database schema, run the following command:

Once completed, update the file /usr/local/pf/conf/currently-at to match the new release number (PacketFence 7.4).

The way PacketFence detects if the realm is stripped out of the username when performing authentication and authorisation has been moved to the realms. Moreover, it is now configurable based on the context (login on the captive portal or administration interface, as well as when performing authorization in RADIUS 802.1x)

In order to migrate the configuration, use the following script to help guide you through the migration:

Device names

Packetfence now uses Fingerbank v2 for improved device profiling. Since this new version brings new device names, a rename of the current data is necessary.

Rename the current data:

Mandatory Fingerbank API key

Fingerbank no longer releases a signature database and now uses an API for device profiling. In order for device profiling to continue working, there must be a Fingerbank API key configured in PacketFence.

In order to do so, you must ensure you have the following in /usr/local/fingerbank/conf/fingerbank.conf

If you manage a large scale environment, you’ll want to ensure your account can perform an unlimited amount of API requests on Fingerbank so that device profiling works correctly in a consistent way. In order to obtain this, contact fingerbank@inverse.ca. Note that most Inverse customers are entitled to free unlimited usage of the Fingerbank Cloud API.

The default roles that were returned using "Role by Switch Role" have been removed. If you were relying on them to be returned in the RADIUS response, then you need to add them back in the default switch in the 'Roles' tab.

The previous values were:

This is should only be necessary if you are using ACL assignment on your switches and using the default names that were there in PacketFence before.

PacketFence doesn’t use graphite anymore for its dashboard. It is recommended to delete the graphite database although this is purely optional.

In order to do so, execute the following:

The $qname parameter need to be removed from dns_filters.conf

In order to do so, execute the following command:

Changes have been made to the database schema. You will need to update it accordingly. An SQL upgrade script has been provided to upgrade the database from the 7.4 schema to 8.0.

To upgrade the database schema, run the following command:

Once completed, update the file /usr/local/pf/conf/currently-at to match the new release number (PacketFence 8.0).

The global configuration parameter unreg_on_acct_stop has been moved in the connection profile. So if you enabled it then ensure to enable it now in the connection profile.

Changes have been made to the database schema. You will need to update it accordingly. An SQL upgrade script has been provided to upgrade the database from the 7.4 schema to 8.0.

To upgrade the database schema, run the following command:

Once completed, update the file /usr/local/pf/conf/currently-at to match the new release number (PacketFence 8.1).

The queue_stats maintenance job has been deprecated in favor of using pfstats. In order to remove configuration related to this maintenance job, run:

The pfdetect was moved from Perl to Go so all rule regexes have to be converted to the RE2 regex syntax. RE2 is mostly is compatiable the Perl regex syntax. More information on the RE2 syntax can be found here https://github.com/google/re2/wiki/Syntax. To upgrade the regex run:

Any Perl regex that cannnot be convert will be displayed and should be fixed.

The realms are now multi-tenant aware, to upgrade your configuration to have the existing realms use the default tenant, execute the following script:

Any users in that were in the api_user table should be migrated to PacketFence local account (password table)

Starting from 8.2, stored routines will be dump with the PacketFence database. The user created at the installation ('pf' by default) in database need to have additional privileges to do that task.

To upgrade the privileges of that user, run the following command:

We merged the WIRED_MAC_AUTH and Ethernet-NoEAP to Ethernet-NoEAP so the configuration must be updated, to do that run:

Changes have been made to the database schema. You will need to update it accordingly. An SQL upgrade script has been provided to upgrade the database from the 8.1 schema to 8.2.

To upgrade the database schema, run the following command:

Once completed, update the file /usr/local/pf/conf/currently-at to match the new release number (PacketFence 8.2).

We moved radius_authentication_methods section to radius_configuration and moved all the radius configuration parameters in this new section. To upgrade your configuration execute the following script:

We added a new parameter in AD and LDAP authentication sources to be able to do 802.1x authentication with any unique ldap attributes. This parameter "searchattributes" need to be added in the existing authentication sources. To apply this configuration execute the following script:

Configuration and templates in the admin were previously being saved as latin1 instead of utf8.

This script will convert all latin1 config file to utf8

Changes have been made to the database schema. You will need to update it accordingly. An SQL upgrade script has been provided to upgrade the database from the 8.2 schema to 8.3.

To upgrade the database schema, run the following command:

Once completed, update the file /usr/local/pf/conf/currently-at to match the new release number (PacketFence 8.3).

Debian 8 will not be supported anymore for versions 9.0 and above. You should instead use Debian 9 now as it is currently the only supported Debian version.

Users hosting an external database for PacketFence will need to run a recent version of MariaDB as it will be the only supported database backend. Failure to use MariaDB may result in errors in the database migration script.

In order to migrate to MariaDB, it is suggested to create a new database server and perform an export of the data through mysqldump and import it in the new server.

The recommended MariaDB version for PacketFence is currently 10.1.21

A recent version of MySQL can also work but going forward, the only tested database engine will be MariaDB.

The previous dhcp filters engine has been deprecated in favor of the new one who is able to modify the dhcp answer on the fly.

The violations have been renamed to security events. In order to make the appropriate changes in your configuration, execute the following script:

The MAC detection setting in the switches has been removed. In order to cleanup the switches configuration for the removal of this setting, execute the following script:

Accounting cleanup is now done via a pfmon task (acct_cleanup) instead of the database backup and maintenance script. Make sure you adjust the cleanup window in pfmon’s configuration (Configuration→System Maintenance→Maintenance) if necessary. Also note that the default retention for the accounting data has been lowered to 1 day instead of 1 week like it was before.

In order to upgrade the Admin rights, run the following commands

Changes have been made to the database schema. You will need to update it accordingly. An SQL upgrade script has been provided to upgrade the database from the 8.3 schema to 9.0.

To upgrade the database schema, run the following command:

Once completed, update the file /usr/local/pf/conf/currently-at to match the new release number (PacketFence 9.0).

In order to add the necessary enabled flag to your existing domains, run the following command:

The port of the pfperl-api service has changed, to adjust the existing configuration, run the following command:

The LinkedIn API calls have changed drastically. On top of the new LinkedIn modules that are part of the update, you will need to change the following parameter in all your existing LinkedIn sources:

The VLAN pool strategy configuration has been moved to the connection profiles.

In order to migrate the current setting of pf.conf into profiles.conf, you will need to run the following command:

The useragent and user_agent security event triggers have been deprecated. Performing HTTP User-Agent based detection is extremelly inefficient given the very dynamic nature of HTTP User-Agents. You should instead be using the device trigger which leverages the device profiling performed by Fingerbank. In order to remove any existing useragent trigger, execute the following script:

The device registration configuration file has been removed in favor of using a configuration file for all the self service portal features (status page + device registration).

In order to migrate your configuration, run the following script:

Password of the day source now uses access duration values to rotate password.

In order to migrate your configuration, run the following script:

Changes have been made to the database schema. You will need to update it accordingly. An SQL upgrade script has been provided to upgrade the database from the 9.0 schema to 9.1.

To upgrade the database schema, run the following command:

Once completed, update the file /usr/local/pf/conf/currently-at to match the new release number (PacketFence 9.1).

Starting from now, PacketFence will be released as an unique RPM package for x86_64 architectures. To remove properly older RPM packages, you need to follow these steps:

At the end of upgrade procedure, you must have only one RPM package called packetfence. If you previously installed packetfence-release package to have PacketFence repository installed, this one has been upgraded to latest version.

In order to install new versions of Debian packages, you will need to add a new GPG key to your system:

You can safely remove the oldest one:

Changes have been made to the database schema. You will need to update it accordingly. An SQL upgrade script has been provided to upgrade the database from the 9.1 schema to 9.2.

To upgrade the database schema, run the following command:

Once completed, update the file /usr/local/pf/conf/currently-at to match the new release number (PacketFence 9.2):

Execute script action in security events doesn’t use sudo anymore to run scripts. Consequently, you must ensure that pf user is:

Changes have been made to the database schema. You will need to update it accordingly. An SQL upgrade script has been provided to upgrade the database from the 9.2 schema to 9.3.

To upgrade the database schema, run the following command:

Once completed, update the file /usr/local/pf/conf/currently-at to match the new release number (PacketFence 9.3):

In this version we need to have the kernel development package that matches your current kernel version to build the Netflow kernel module.

The timezone set in pf.conf will be set on the operating system every time PacketFence reloads its configuration. For this reason, you must review the timezone setting in the general section of pf.conf (System Configuration → General Configuration in the admin). If its empty, PacketFence will use the timezone that is already set on the server and you don’t have anything to do. Otherwise, it will set the timezone in this setting on the operating system layer for consistency which may modify the timezone setting of your operating system. In this case you must ensure that you reboot the server after completing all the steps of the upgrade so that the services start with the right timezone.

packetfence-tracking-config service is now enabled by default. It means that all manual changes to configuration files will be recorded, including passwords.

You can disable this service from PacketFence web admin if you don’t want such behavior.

PacketFence-pki is deprecated in favour of the new PacketFence PKI written in Golang. If you previously used the PacketFence-pki you will need to migrate from the SQLite database to MariaDB. To migrate, be sure that the database is running and the new PKI too and do the following:

Next edit the PKI providers (Configuration → PKI Providers) and redefine the profile to use. Finally, if you use OCSP then change the URL to use this one: http://127.0.0.1:22225/api/v1/pki/ocsp

This release adds a new service that will automatically attempt to recover broken Galera cluster members and can also perform a full recovery of a Galera cluster. These automated decisions may lead to potential data loss. If this is not acceptable for you disable the galera-autofix service in pf.conf or in "System Configuration→Services". More details and documentation is available in the "The galera-autofix service" section of the clustering guide.

The file /usr/local/pf/conf/currently-at is no longer needed, it can be removed:

You also need to disable access to configurator by running:

Some queries now need CREATE TEMPORARY TABLE privilege. You will be prompted for the MariaDB root password when running this script:

We are now using a new format for the VLAN/DNS/DHCP/RADIUS/Switch filters. This script will convert the old format to the new one:

Starting from now, httpd.admin daemon is disabled by default and web admin interface is managed by HAProxy using haproxy-admin daemon.

It means that if you use a dedicated SSL certificate (different from captive portal certificate) for web admin interface, this one has been replaced by your captive portal certificate. You can find it at /usr/local/pf/conf/ssl/server.pem.

Changes have been made to the database schema. You will need to update it accordingly. An SQL upgrade script has been provided to upgrade the database from the 9.3 schema to 10.0.

To upgrade the database schema, run the following command:

RADIUS attributes used in rules of authentication sources are now prefixed by radius_request. This script will add the prefix:

In order to improve LDAP support when using RADIUS, new files and configuration parameters have been added. This script will update your current configuration:

RADIUS filters now support templated values like switch templates. This script will update your RADIUS filters to new format:

A new EAP parameter has been added to realm.conf file. This script will add this parameter to your current configuration file:

It’s now possible to enable/disable rules in authentication sources. This script will add the new status parameter:

Support for CoA for Unifi AP is now supported but requires to have the latest controller and AP firmware available. Make sure you run the latest version of the controller and firmware if you use Ubiquiti equipment.

Changes have been made to the database schema. You will need to update it accordingly. An SQL upgrade script has been provided to upgrade the database from the 10.0 schema to 10.1.

To upgrade the database schema, run the following command:

Debian packages upgrades will remove /usr/local/pf/conf/pfmon.conf file in favor of /usr/local/pf/conf/pfcron.conf. In order to keep your configuration in place, you need to make a backup of your pfmon.conf file before running packages upgrades:

After packages upgrades have been performed, you can move file to its original location:

Configuration will be moved to /usr/local/pf/conf/pfcron.conf file during configuration migration step.

The parameter device_registration_role has been renamed device_registration_roles, to apply the change run the following script:

If switch type was not defined, this script will set it to Generic:

Convert the pfmon configuration file to pfcron

Rename PFMON actions to the PFCRON actions

Add the tenant_id to pfdetect

Changes have been made to the database schema. You will need to update it accordingly. An SQL upgrade script has been provided to upgrade the database from the 10.1 schema to 10.2.

To upgrade the database schema, run the following command:

PacketFence now depends of the MariaDB version 10.2. In order to upgrade the MariaDB version you need to execute the following steps before upgrading PacketFence.

The ability to define a specific port per host in the list of the LDAP servers of a single authentication source has been deprecated. If you have such entries, adjust them accordingly. If you have been using the same LDAP port for all the hosts in an authentication source, then this will not apply to you.

inline_accounting table will be removed by upgrade of database schema (see below) because it has been replaced by bandwidth_accounting table since v10.

You are only concern by this item if you extract data from inline_accounting table before v10 for external usage.

To add the default tenant_id (1) to all network configurations run:

Changes have been made to the database schema. You will need to update it accordingly. An SQL upgrade script has been provided to upgrade the database from the 10.2 schema to 10.3.

To upgrade the database schema, run the following command:

To be sure you are running latest MariaDB configuration provided by PacketFence packages, you need to restart packetfence-mariadb:

Starting from PacketFence 11.0, Debian 9 and CentOS 7 support are dropped in favor of Debian 11 and RHEL 8. In place upgrades are not supported. Provision new operating system(s) in order to migrate.

To simplify upgrade process to PacketFence 11.0 and future versions, we now rely on an export/import mechanism.

Before doing anything else, be sure to read assumptions and limitations of this mechanism.

Follow instructions related to import process.

If the import mechanism is not used to upgrade the previous PacketFence installation, follow the instructions in this section to upgrade the configuration and database schema.

The option NTLM cache background job and its associated parameters have been deprecated. If this option was previously used on at least one of the domains, it will automatically use the NTLM cache on connection method.

The pf-maint.pl script used to get maintenance patches has been deprecated. Get maintenance patches using the package manager, see Apply maintenance patches section.

TLS 1.0 and TLS 1.1 are now disabled by default. If supplicants are currently using theses protocols, move to TLS 1.2. If TLS 1.2 is not possible adjust TLS Minimum version in Configuration → System configuration → RADIUS → TLS profiles.

Upgrades are now automated for standalone servers starting from PacketFence 11.0. Follow instructions related to automation of upgrades.

PacketFence now provides a way to add custom rules in /usr/local/pf/conf/iptables.conf using two files:

If custom rules in iptables.conf were previously created, we recommend moving these rules into these files.

PacketFence now allow to enable or disable local authentication for 802.1X directly in web admin.

If packetfence-local-auth has been previously enabled in /usr/local/pf/conf/radiusd/packetfence-tunnel, we recommend enabling this feature in PacketFence web admin (see EAP local user authentication).

Monit configuration is now managed directly in /usr/local/pf/conf/pf.conf. An upgrade script will be used during upgrade process to automatically migrate existing Monit configuration into /usr/local/pf/conf/pf.conf.

Cluster upgrades are not automated, follow the instructions in this section to upgrade the configuration and database schema.

Upgrades are now automated for standalone servers starting from PacketFence 11.0. Follow instructions related to automation of upgrades.

Cluster upgrades are not automated, follow the instructions in this section to upgrade the configuration and database schema.

If any condition for filters (VLAN, RADIUS, Switch, DNS, DHCP, and Profile) uses a `not equals operator. Check if the logic is still ok if the value is null/undef.

If a filter must ensure a value is defined, add an additional defined condition to the filter.

If pfpki is used, and PKI templates were created without email attribute, we recommend setting a value for this attribute.

By doing this, pfpki will use email addresses defined in PKI templates to notify about next certificates expirations for certificates without emails.