= PacketFence Upgrade Guide
////

    This file is part of the PacketFence project.

    See docs/includes/global-attributes.asciidoc
    for authors, copyright and license information.

////
include::includes/global-attributes.asciidoc[]

== About this Guide

This guide covers procedures to upgrade PacketFence servers.

=== Other sources of information

<<PacketFence_Clustering_Guide.asciidoc#,Clustering Guide>>::
  Covers installation in a clustered environment.
<<PacketFence_Developers_Guide.asciidoc#,Developer's Guide>>::
  Covers API, captive portal customization, application code customizations and
  instructions for supporting new equipment.
<<PacketFence_Installation_Guide.asciidoc#,Installation Guide>>::
  Covers installation and configuration of PacketFence.
<<PacketFence_Network_Devices_Configuration_Guide.asciidoc#,Network Devices Configuration Guide>>::
  Covers switches, WiFi controllers and access points configuration.
https://packetfence.org/news.html[PacketFence News]::
  Covers noteworthy features, improvements and bug fixes by release.

These files are included in the package and release tarballs.

== General Upgrade Tips

=== Prerequisites

The MariaDB root password that was provided during the initial configuration is required.

=== Database and configurations backup

NOTE: Starting from PacketFence 11.0.0, this step is not necessary for
doing an
<<PacketFence_Installation_Guide.asciidoc#_automation_of_upgrades,automated
upgrade>>.

Taking a complete backup of the current installation is strongly recommended.
Perform a backup using:

.For PacketFence versions prior to 9.0.0:
[source,bash]
----
/usr/local/pf/addons/database-backup-and-maintenance.sh
----

.For PacketFence versions 9.0.0 and later:
[source,bash]
----
/usr/local/pf/addons/backup-and-maintenance.sh
----

=== Disable monit alerts (only if monit is installed)

NOTE: Starting from PacketFence 11.0.0, this step is not necessary for
doing an
<<PacketFence_Installation_Guide.asciidoc#_automation_of_upgrades,automated
upgrade>>.

If `monit` is installed and running, stop and disable it with:

[source,bash]
----
systemctl stop monit
systemctl disable monit
----

== Type of upgrades

Starting from PacketFence 11.0.0, the PacketFence installation can be upgraded in two ways:

* <<#_apply_maintenance_patches,Apply maintenance patches>>
* <<#_upgrade_to_another_version_major_or_minor,Upgrade to another version (major or minor)>>

For all PacketFence versions prior to 11.0.0, follow the steps described in the <<_upgrade_procedure,Upgrade procedure>>.

== Apply maintenance patches

=== Important note for cluster environments

In cluster environments, you need to perform following steps on **one server
at a time**. To avoid multiple moves of the virtual IP addresses, you can start with
nodes which don't own any virtual IP addresses first. You must ensure all
services have been restarted correctly before moving to the next node.

=== Disable monit alerts (only if monit is installed)

If `monit` is installed and running, shut it down with:

[source,bash]
----
systemctl stop monit
systemctl disable monit
----

=== Stop all PacketFence services

It is recommended to stop all PacketFence services that are currently running before proceeding any further:

[source,bash]
----
/usr/local/pf/bin/pfcmd service pf stop
systemctl stop packetfence-config
----

=== Upgrade packages

WARNING: All non-configuration files will be overwritten by new packages. All changes made to any other files will be lost during the upgrade.

include::common/upgrade_packages.asciidoc[]

=== New versions of config files

include::common/new_config_files.asciidoc[]

=== Rebooting after services have been stopped (optional)

include::common/reboot.asciidoc[]

=== Restart PacketFence services

include::common/restart.asciidoc[]

== Upgrade to another version (major or minor)

=== For a standalone server

Follow instructions related to <<PacketFence_Installation_Guide.asciidoc#_automation_of_upgrades,automation of upgrades>>.

=== For a cluster

Please refer to the <<PacketFence_Clustering_Guide.asciidoc#,PacketFence Clustering Guide>>, more specifically the <<PacketFence_Clustering_Guide.asciidoc#_performing_an_upgrade_on_a_cluster,Performing an upgrade on a cluster>>.

== Upgrading from a version prior to 8.0.0


=== Realms upgrade


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:

 /usr/local/pf/addons/upgrade/to-8.0-authentication-conf.pl

=== Fingerbank v2


*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:

[source,bash]
----
/usr/local/pf/addons/upgrade/to-8.0-fingerbank-db-data.pl
----

*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 should make sure you have the following in `/usr/local/fingerbank/conf/fingerbank.conf`

NOTE: In order to request an API key, you can visit the following URL: https://api.fingerbank.org/users/register

```
[upstream]
api_key=YOUR_API_KEY_GOES_HERE
```

WARNING: Fingerbank v1 and v2 *do not* use the same infrastructure. The accounts (API keys) created on fingerbank.inverse.ca before the 8.0 release have been migrated to api.fingerbank.org. Still, you should make sure that you have the correct API key configured in fingerbank.conf by looking at your profile on https://api.fingerbank.org/users/register. If you have a corporate account, then you can safely assume its been migrated, you can email fingerbank@inverse.ca for a confirmation. If you use a Github account and you have tried Fingerbank v2 prior to the PacketFence 8.0 release, *then your API key will be different*. Make sure you update fingerbank.conf in that case.

If you manage a large scale environment, you'll want to make sure 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.

=== Changes to the default switch roles


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:

 * `registration`: `registration`
 * `isolation`: `isolation`
 * `macDetection`: `macDetection`
 * `inline`: `inline`
 * `voice`: `voice`

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.

=== Removal of the graphite database


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:

  mysql -u root -p -e "drop database pf_graphite"

=== Changes to DNS filters


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

In order to do so, execute the following command:

  sed -i -e 's/\$qname//g' /usr/local/pf/conf/dns_filters.conf

=== Database schema update (all Linux distributions)


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:

  mysql -u root -p pf -v < /usr/local/pf/db/upgrade-7.4.0-8.0.0.sql

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

== Upgrading from a version prior to 8.1.0


=== Changes on unreg_on_accounting_stop parameter


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


=== Database schema update (all Linux distributions)


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:

  mysql -u root -p pf -v < /usr/local/pf/db/upgrade-8.0.0-8.1.0.sql

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

== Upgrading from a version prior to 8.2.0


=== Queue Stats maintenance job removal

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

  /usr/local/pf/addons/upgrade/to-8.2-pfmon-conf.pl

=== Upgrade pfdetect Perl regex to the go RE2 regex

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:

  /usr/local/pf/addons/upgrade/to-8.2-pfdetect-conf.pl

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

=== Upgrade realm.conf to be tenant aware


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

  /usr/local/pf/addons/upgrade/to-8.2-realm-conf.pl


=== The api_user table has been deprecated


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

=== Upgrade pf user privileges


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:

 /usr/local/pf/addons/upgrade/to-8.2-upgrade-pf-privileges.sh

=== Update connection_type from WIRED_MAC_AUTH to Ethernet-NoEAP

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

 sed -i "s/WIRED_MAC_AUTH/Ethernet-NoEAP/g" /usr/local/pf/conf/profiles.conf /usr/local/pf/conf/vlan_filters.conf /usr/local/pf/conf/radius_filters.conf /usr/local/pf/conf/switch_filters.conf /usr/local/pf/conf/authentication.conf

=== Database schema


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:

 mysql -u root -p pf -v < /usr/local/pf/db/upgrade-8.1.0-8.2.0.sql

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

== Upgrading from a version prior to 8.3.0


=== Upgrade pf.conf to rename configuration parameters


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:

  /usr/local/pf/addons/upgrade/to-8.3-rename-pf-conf-parameters.pl


=== Upgrade authentication.conf to add searchattributes parameter


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:

 /usr/local/pf/addons/upgrade/to-8.3-authentication-searchattributes.pl

=== Adjustment to the encoding of the configuration files and templates


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

  /usr/local/pf/addons/upgrade/to-8.3-conf-latin1-to-utf8.sh

=== Database schema


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:

  mysql -u root -p pf -v < /usr/local/pf/db/upgrade-8.2.0-8.3.0.sql

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

== Upgrading from a version prior to 9.0.0


=== Support for Debian 8 dropped


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

=== Necessity to use MariaDB


NOTE: This only applies to users using an external database server. If your database is hosted on the same server as PacketFence whether you are in cluster or standalone, this requires no attention.

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.

=== Deprecate the classic dhcp filters


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.

=== Violations have been renamed to Security Events


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

  /usr/local/pf/addons/upgrade/to-9.0-security-events.sh

=== Removed MAC detection setting


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:

  /usr/local/pf/addons/upgrade/to-9.0-remove_mac_detection.sh

=== Modifications to accounting cleanup


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.

=== Admin roles configuration


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

  cd /usr/local/pf
  sed -i "s/SERVICES/SERVICES_READ/g" /usr/local/pf/conf/adminroles.conf
  sed -i "s/REPORTS/REPORTS_READ/g" /usr/local/pf/conf/adminroles.conf

=== Database schema


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:

  mysql -u root -p pf -v < /usr/local/pf/db/upgrade-8.3.0-9.0.0.sql

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


== Upgrading from a version prior to 9.1.0


=== Now possible to disable a domain


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

  /usr/local/pf/addons/upgrade/to-9.1-add-domain-conf.pl

=== pfperl-api port


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

  /usr/local/pf/addons/upgrade/to-9.1-update-api.conf.sh

=== Linkedin OAuth2


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:

 API URL of logged user -> https://api.linkedin.com/v2/emailAddress?q=members&projection=(elements*(handle~))

=== VLAN pool configuration


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:

	/usr/local/pf/addons/upgrade/to-9.1-move-vlan-pool-technique-parameter.pl

=== Remove Useragent Triggers


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:

   /usr/local/pf/addons/upgrade/to-9.1-security-events-remove-useragent.pl

=== Self service portal

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:

[source,bash]
----
/usr/local/pf/addons/upgrade/to-9.1-selfservice-conf.pl
----

=== Password of the day rotation

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

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

[source,bash]
----
/usr/local/pf/addons/upgrade/to-9.1-update-potd.pl
----


=== Database schema


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:

  mysql -u root -p pf -v < /usr/local/pf/db/upgrade-9.0.0-9.1.0.sql

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

== Upgrading from a version prior to 9.2.0


=== Merge of all RPM packages into one (RHEL / CentOS only)

NOTE: This step needs to be done *before* packages upgrade.

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:

. Follow instructions mentioned in <<_stop_all_packetfence_services,Stop all PacketFence services>> section and stop before starting packages upgrades
. Uninstall old RPM without running post-uninstallation steps:
+
[source,bash]
----
rpm -e --nodeps --noscripts packetfence-config

# run only if packetfence-remote-arp-sensor has been installed
rpm -e --nodeps --noscripts packetfence-remote-arp-sensor
----
+

. Recopy previous [filename]`pfconfig.conf` filename to its original location:
+
[source,bash]
----
mv -f /usr/local/pf/conf/pfconfig.conf.rpmsave /usr/local/pf/conf/pfconfig.conf
----
+

. Upgrade PacketFence packages by following instructions in <<_packages_upgrades,Packages upgrades>> section for RHEL / CentOS based systems
. Continue upgrade procedure

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

=== New GPG key for Debian installations (Debian only)

NOTE: This step needs to be done *before* packages upgrade.

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

[source,bash]
----
wget -O - https://inverse.ca/downloads/GPG_PUBLIC_KEY | sudo apt-key add -
----

You can safely remove the oldest one:
[source,bash]
----
sudo apt-key del FE9E84327B18FF82B0378B6719CDA6A9810273C4
----

=== Database schema

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:

[source,bash]
----
mysql -u root -p pf -v < /usr/local/pf/db/upgrade-9.1.0-9.2.0.sql
----

Once completed, update the file [filename]`/usr/local/pf/conf/currently-at` to match the new release number (PacketFence 9.2.0):

[source,bash]
----
cat /usr/local/pf/conf/pf-release > /usr/local/pf/conf/currently-at
----

== Upgrading from a version prior to 9.3.0

=== Execute script action doesn't use sudo anymore

Execute script action in security events doesn't use [command]`sudo` anymore to run scripts.
Consequently, you should ensure that `pf` user is:

* able to read and execute these scripts
* able to run commands inside these scripts (without `sudo`)

=== Database schema

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:

[source,bash]
----
mysql -u root -p pf -v < /usr/local/pf/db/upgrade-9.2.0-9.3.0.sql
----

Once completed, update the file [filename]`/usr/local/pf/conf/currently-at` to match the new release number (PacketFence 9.3.0):

[source,bash]
----
cat /usr/local/pf/conf/pf-release > /usr/local/pf/conf/currently-at
----

== Upgrading from a version prior to 10.0.0

=== Kernel development package

NOTE: This step needs to be done *before* packages upgrade.

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

==== RHEL / CentOS based systems

[source,bash]
----
yum install kernel-devel-$(uname -r)
----

The headers for your specific kernel may not be published anymore in the CentOS repository. If that is the case, then perform the following prior to the upgrade:

[source,bash]
----
yum update kernel
reboot
yum install kernel-devel-$(uname -r)
----

NOTE: Be sure to follow instructions in <<_rebooting_after_services_have_been_stopped>> section to ensure services will not restart.

==== Debian-based systems

[source,bash]
----
apt install linux-headers-$(uname -r)
----

=== Timezone

The timezone set in pf.conf will be set on the operating system every time PacketFence reloads its configuration.
For this reason, you should 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 should ensure that you reboot the server after completing all the steps of the upgrade so that the services start with the right timezone.

=== Tracking configuration service enabled by default

`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.

=== New PacketFence PKI in Golang

NOTE: If you do not use the PacketFence PKI, you can safely ignore this step

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:

  /usr/local/pf/addons/upgrade/to-10.0-packetfence-pki-migrate.pl

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

=== New MariaDB Galera recovery service

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.

=== Removal of currently-at file and configurator display

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

[source,bash]
----
rm /usr/local/pf/conf/currently-at
----

You also need to disable access to configurator by running:

[source,bash]
----
printf '\n[advanced]\nconfigurator=disabled\n' >> /usr/local/pf/conf/pf.conf
----

=== Database Privileges

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

[source,bash]
----
/usr/local/pf/addons/upgrade/to-10.0-upgrade-pf-privileges.sh
----

=== Filter Engine

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:

[source,bash]
----
/usr/local/pf/addons/upgrade/to-10.0-filter_engines.pl
----

=== httpd.admin daemon disabled by default

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
[filename]`/usr/local/pf/conf/ssl/server.pem`.

=== Database schema

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:

[source,bash]
----
mysql -u root -p pf -v < /usr/local/pf/db/upgrade-9.3.0-10.0.0.sql
----

== Upgrading from a version prior to 10.1.0

=== RADIUS attributes in authentication sources

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

[source,bash]
----
/usr/local/pf/addons/upgrade/to-10.1-authentication-prefix.pl
----

=== Changes in RADIUS configuration for better LDAP support

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

[source,bash]
----
/usr/local/pf/addons/upgrade/to-10.1-move-radius-configuration-parmeters.pl
----

=== RADIUS filter templates

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

[source,bash]
----
/usr/local/pf/addons/upgrade/to-10.1-radius-filter-template.pl
----

=== New EAP configuration parameter in realm.conf file

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

[source,bash]
----
/usr/local/pf/addons/upgrade/to-10.1-realm-conf.pl
----

=== Status of rules

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

[source,bash]
----
/usr/local/pf/addons/upgrade/to-10.1-rule-status.pl
----

=== Support for CoA in Unifi controllers

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.

=== Database schema

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.0 schema to 10.1.0.

To upgrade the database schema, run the following command:

[source,bash]
----
mysql -u root -p pf -v < /usr/local/pf/db/upgrade-10.0.0-10.1.0.sql
----

== Upgrading from a version prior to 10.2.0

=== Backup of pfmon.conf (Debian-based systems only)

NOTE: This step needs to be done *before* packages upgrade.

Debian packages upgrades will remove [filename]`/usr/local/pf/conf/pfmon.conf` file in favor of [filename]`/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:

[source,bash]
----
cp /usr/local/pf/conf/pfmon.conf /root/pfmon.conf.rpmsave
----

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

[source,bash]
----
mv /root/pfmon.conf.rpmsave /usr/local/pf/conf/pfmon.conf.rpmsave
----

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

WARNING: `rpmsave` extension is not an error, script `to-10.2-pfmon-maintenance.pl` will migrate configuration using this filename.

=== Self registration portal

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

[source,bash]
----
/usr/local/pf/addons/upgrade/to-10.2-selfservice-conf.pl
----

=== Switch type needs to be defined

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

[source,bash]
----
/usr/local/pf/addons/upgrade/to-10.2-default-switch-packetfence-standard.pl
----

=== Convert the pfmon configuration file to pfcron

Convert the pfmon configuration file to pfcron

[source,bash]
----
/usr/local/pf/addons/upgrade/to-10.2-pfmon-maintenance.pl
----

=== Rename PFMON* actions to PFCRON*

Rename PFMON actions to the PFCRON actions

[source,bash]
----
/usr/local/pf/addons/upgrade/to-10.2-adminroles-conf.pl
----

=== Syslog parsers are now tenant aware


Add the tenant_id to pfdetect

[source,bash]
----
/usr/local/pf/addons/upgrade/to-10.2-pfdetect-conf.pl
----

=== Database schema

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.0 schema to 10.2.0.

To upgrade the database schema, run the following command:

[source,bash]
----
mysql -u root -p pf -v < /usr/local/pf/db/upgrade-10.1.0-10.2.0.sql
----

== Upgrading from a version prior to 10.3.0

=== MariaDB Upgrade to 10.2

NOTE: This step needs to be done *before* packages upgrade.

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.

==== Standalone MariaDB upgrade

In order to be able to work on the server, we first need to stop all the
PacketFence application services on it, see
<<PacketFence_Upgrade_Guide.asciidoc#_stop_all_packetfence_services,Stop all
PacketFence services section>>.

Now stop `packetfence-mariadb`:

[source,bash]
----
systemctl stop packetfence-mariadb
----

Now proceed with the MariaDB upgrade

.RHEL / CentOS based systems
[source,bash]
----
rpm -e --nodeps MariaDB-client MariaDB-common MariaDB-server MariaDB-shared
yum install --enablerepo=packetfence MariaDB-server
----

.Debian-based systems
[source,bash]
----
dpkg -r --force-depends mariadb-server mariadb-client-10.1 mariadb-client-core-10.1 \
mariadb-common mariadb-server-10.1 mariadb-server-core-10.1 libmariadbclient18 mysql-common
apt update
apt install mariadb-server mariadb-client-10.2 mariadb-client-core-10.2 \
mariadb-common mariadb-server-10.2 mariadb-server-core-10.2 libmariadbclient18 libmariadb3 \
mysql-common
----

NOTE: If you manually installed Percona XtraBackup to take your backups, you
need to install `MariaDB-backup` (rpm) and `mariadb-backup-10.2` (deb) as a
replacement.

NOTE: On Debian, ignore prompts related to change of `root` password during package upgrade.

At this moment you have the newest version of MariaDB installed on your system.
Ensure MariaDB is running:

.RHEL / CentOS based systems *only*
[source,bash]
----
systemctl unmask mariadb
systemctl start mariadb
----

You can check you are running MariaDB 10.2 version with following command:

[source,bash]
----
mysql -u root -p -e "show variables where Variable_name='version';"
----

Next step is to upgrade your databases:
[source,bash]
----
mysql_upgrade -u root -p
----

NOTE: If the following error appears "Recovering after a crash using tc.log" then delete the file [filename]`/var/lib/mysql/tc.log`

After databases have been upgraded, you can disable default MariaDB service:

.RHEL / CentOS based systems
[source,bash]
----
systemctl stop mariadb
systemctl mask mariadb
----

.Debian-based systems
[source,bash]
----
systemctl stop mysql
pkill -u mysql
systemctl mask mysql
----

`packetfence-mariadb` service will be started later by upgrade of PacketFence package(s).

At this step you have now the MariaDB 10.2 database ready.
You can now upgrade the PacketFence version by following instructions in <<_packages_upgrades,Packages upgrades>> section.

==== Cluster MariaDB upgrade


CAUTION: Performing a live upgrade on a PacketFence cluster is not a straightforward operation and should be done meticulously.

In this procedure, the 3 nodes will be named A, B and C and they are in this order in [filename]`cluster.conf`. When we referenced their hostnames, we speak about hostnames in [filename]`cluster.conf`.

===== Backups

First, ensure you have taken backups of your data. We highly encourage you to perform snapshots of all the virtual machines prior to the upgrade. You should also take a backup of the database and the `/usr/local/pf` directory using <<PacketFence_Upgrade_Guide.asciidoc#_database_and_configurations_backup,database and configurations backup instructions>>

===== Disabling the auto-correction of configuration

The PacketFence clustering stack has a mechanism that allows configuration conflicts to be handled accross the servers. This will come in conflict with your upgrade, so you should disable it.

In order to do so, go in _Configuration->System Configuration->Maintenance_ and disable the _Cluster Check_ task.

Once this is done, restart `pfmon` or `pfcron` on all nodes using:

.For PacketFence versions prior to 10.2
[source,bash]
----
/usr/local/pf/bin/pfcmd service pfmon restart
----

.For PacketFence version 10.2 and later
[source,bash]
----
/usr/local/pf/bin/pfcmd service pfcron restart
----

===== Disabling galera-autofix (for PacketFence version 10.0 and later)

You should disable the `galera-autofix` service in the configuration to disable the automated resolution of cluster issues during the upgrade.

In order to do so, go in _Configuration->System Configuration->Services_ and disable the `galera-autofix` service.

Once this is done, stop `galera-autofix` service on *all* nodes using:

[source,bash]
----
/usr/local/pf/bin/pfcmd service galera-autofix updatesystemd
/usr/local/pf/bin/pfcmd service galera-autofix stop
----

===== Migrating service on node C

In order to be able to work on node C, we first need to stop all the
PacketFence application services on it:

[source,bash]
----
/usr/local/pf/bin/pfcmd service pf stop
----

`packetfence-config` needs to stay up to disable node A and B in configuration.

NOTE: The steps below will cause a temporary loss of service.

====== Detach node C from the cluster

First, we need to tell A and B to ignore C in their cluster configuration. In order to do so, execute the following command **on A and B** while changing `node-C-hostname` with the actual hostname of node C:

[source,bash]
----
/usr/local/pf/bin/cluster/node node-C-hostname disable
----

Once this is done proceed to restart the following services on nodes A and B **one at a time**. This will cause service failure during the restart on node A

[source,bash]
----
/usr/local/pf/bin/pfcmd service radiusd restart
/usr/local/pf/bin/pfcmd service pfdhcplistener restart
/usr/local/pf/bin/pfcmd service haproxy-admin restart
/usr/local/pf/bin/pfcmd service haproxy-db restart
/usr/local/pf/bin/pfcmd service haproxy-portal restart
/usr/local/pf/bin/pfcmd service keepalived restart
----

Then, we should tell C to ignore A and B in their cluster configuration. In order to do so, execute the following commands on node C while changing `node-A-hostname` and `node-B-hostname` by the hostname of nodes A and B respectively.

[source,bash]
----
/usr/local/pf/bin/cluster/node node-A-hostname disable
/usr/local/pf/bin/cluster/node node-B-hostname disable
----

The commands above will make sure that nodes A and B will not be forwarding
requests to C even if it is alive. Same goes for C which won't be sending
traffic to A and B. This means A and B will continue to have the same database
informations while C will start to diverge from it when it goes live. We'll
make sure to reconcile this data afterwards.

====== MariaDB upgrade on node C

Now stop `packetfence-mariadb` on node C:

[source,bash]
----
systemctl stop packetfence-mariadb
----

Now proceed with the MariaDB upgrade

.RHEL / CentOS based systems *only*
[source,bash]
----
rpm -e --nodeps MariaDB-client MariaDB-common MariaDB-server MariaDB-shared
yum install --enablerepo=packetfence MariaDB-server MariaDB-backup
----

.Debian-based systems
[source,bash]
----
dpkg -r --force-depends mariadb-server mariadb-client-10.1 mariadb-client-core-10.1 \
mariadb-common mariadb-server-10.1 mariadb-server-core-10.1 libmariadbclient18 \
mysql-common
apt update
apt install mariadb-server-10.2 mariadb-common mariadb-client-10.2 \
mariadb-client-core-10.2 mariadb-server-core-10.2 libmariadb3 \
libmariadbclient18 mariadb-server mariadb-backup-10.2 mysql-common
----

NOTE: On Debian, ignore prompts related to change of `root` password during package upgrade.

At this moment you have the newest version of MariaDB installed on your system. Ensure MariaDB is running:

.RHEL / CentOS based systems *only*
[source,bash]
----
systemctl unmask mariadb
systemctl start mariadb
----

You can check you are running MariaDB 10.2 version with following command:

[source,bash]
----
mysql -u root -p -e "show variables where Variable_name='version';"
----

Next step is to upgrade your databases:
[source,bash]
----
mysql_upgrade -u root -p
----

NOTE: If the following error appear "Recovering after a crash using tc.log" then delete the file /var/lib/mysql/tc.log

After databases have been upgraded, you can disable default MariaDB service:

.RHEL / CentOS based systems *only*
[source,bash]
----
systemctl stop mariadb
systemctl mask mariadb
----

.Debian-based systems
[source,bash]
----
systemctl stop mysql
pkill -u mysql
systemctl mask mysql
----

At this step you have now the MariaDB 10.2 database ready.
In order to start MariaDB as standalone on node C, you need to regenerate MariaDB config
(`packetfence-mariadb` service will be started later by upgrade of packetfence package(s))

[source,bash]
----
/usr/local/pf/bin/pfcmd generatemariadbconfig
----

====== Upgrading node C

Next, you can upgrade your operating system and/or PacketFence on node C by
following instructions of
<<PacketFence_Upgrade_Guide.asciidoc#_packages_upgrades,Packages upgrades
section>>.

IMPORTANT: If you are on a RHEL/CentOS based systems, the command to install
`packetfence-release` released with 10.3.0 version will be:

[source,bash]
----
https://www.packetfence.org/downloads/PacketFence/RHEL7/packetfence-release-7.stable.noarch.rpm
----

====== Maintenance patches (on node C)

include::common/maintenance_patches.asciidoc[][]

====== Configuration migration and database schema updates (on node C)

Now, make sure you follow the directives in the <<PacketFence_Upgrade_Guide.asciidoc#,upgrade guide>> as you would on a standalone server **including** the database schema updates.

====== Start service on node C

Now, start the application service on node C using following instructions:

[source,bash]
----
/usr/local/pf/bin/pfcmd fixpermissions
/usr/local/pf/bin/pfcmd pfconfig clear_backend
systemctl restart packetfence-config
/usr/local/pf/bin/pfcmd configreload hard
/usr/local/pf/bin/pfcmd service pf restart
----

====== Stop services on nodes A and B

Next, stop all application services on node A and B:

* Stop all PacketFence services:
+
[source,bash]
----
/usr/local/pf/bin/pfcmd fixpermissions
/usr/local/pf/bin/pfcmd pfconfig clear_backend
systemctl restart packetfence-config
/usr/local/pf/bin/pfcmd configreload hard
/usr/local/pf/bin/pfcmd service pf stop
----
* Stop database:
+
[source,bash]
----
systemctl stop packetfence-mariadb
----

===== Validate migration

You should now have full service on node C and should validate that all functionnalities are working as expected. Once you continue past this point, there will be no way to migrate back to nodes A and B in case of issues other than to use the snapshots taken prior to the upgrade.

====== If all goes wrong

If your migration to node C goes wrong, you can fail back to nodes A and B by stopping all services on node C and starting them on nodes A and B

.On node C
[source,bash]
----
systemctl stop packetfence-mariadb
/usr/local/pf/bin/pfcmd service pf stop
----

.On nodes A and B
[source,bash]
----
systemctl start packetfence-mariadb
/usr/local/pf/bin/pfcmd service pf start
----

Once you are feeling confident to try your failover to node C again, you can do the exact opposite of the commands above to try your upgrade again.

====== If all goes well

If you are happy about the state of your upgrade, you can continue on the steps below in order to complete the upgrade of the two remaining nodes.

===== MariaDB upgrade on nodes A and B

Now proceed with the MariaDB upgrade:

.RHEL / CentOS based systems
[source,bash]
----
rpm -e --nodeps MariaDB-client MariaDB-common MariaDB-server MariaDB-shared
yum install --enablerepo=packetfence MariaDB-server MariaDB-backup
----

.Debian-based systems
[source,bash]
----
dpkg -r --force-depends mariadb-server mariadb-client-10.1 mariadb-client-core-10.1 \
mariadb-common mariadb-server-10.1 mariadb-server-core-10.1 libmariadbclient18 \
mysql-common
apt update
apt install mariadb-server-10.2 mariadb-common mariadb-client-10.2 \
mariadb-client-core-10.2 mariadb-server-core-10.2 libmariadb3 \
libmariadbclient18 mariadb-server mariadb-backup-10.2 mysql-common
----

NOTE: On Debian, ignore prompts related to change of `root` password during package upgrade.

To let nodes A and B rejoin cluster **before** upgrading PacketFence packages,
you need to update MariaDB configuration:

[source,bash]
----
sed -i "s/xtrabackup/mariabackup/g" /usr/local/pf/conf/mariadb/mariadb.conf.tt
----

At this moment you have the newest version of MariaDB installed on nodes A and B.

On Debian-based systems **only**, you need to stop default `mysql` service:

.Debian-based systems **only**
[source,bash]
----
systemctl stop mysql
pkill -u mysql
systemctl mask mysql
----

At this step you have now the MariaDB 10.2 database ready.

===== Reintegrating nodes A and B

====== Optional step: Cleaning up data on node C


When you will re-establish a cluster using node C in the steps below, your environment will be set in read-only mode for the duration of the database sync (which needs to be done from scratch).

This can take from a few minutes to an hour depending on your database size.

We highly suggest you delete data from the following tables if you don't need it:

* `radius_audit_log`: contains the data in _Auditing->RADIUS Audit Logs_
* `ip4log_history`: Archiving data for the IPv4 history
* `ip4log_archive`: Archiving data for the IPv4 history
* `locationlog_history`: Archiving data for the node location history

You can safely delete the data from all of these tables without affecting the functionnalities as they are used for reporting and archiving purposes. Deleting the data from these tables can make the sync process considerably faster.

In order to truncate a table:

[source,bash]
----
mysql -u root -p pf
MariaDB> truncate TABLE_NAME;
----

====== Elect node C as database master


In order for node C to be able to elect itself as database master, we must tell it there are other members in its cluster by re-enabling nodes A and B

[source,bash]
----
/usr/local/pf/bin/cluster/node node-A-hostname enable
/usr/local/pf/bin/cluster/node node-B-hostname enable
----

Next, enable node C on nodes A and B by executing the following command on the two servers:

[source,bash]
----
systemctl start packetfence-config
/usr/local/pf/bin/cluster/node node-C-hostname enable
----

Now, stop `packetfence-mariadb` on node C, regenerate the MariaDB configuration and start it as a new master:

NOTE: Before starting this step, be sure that the galera_replication_username has grant permission PROCESS

[source,bash]
----
mysql -u root -p
select * from information_schema.user_privileges where PRIVILEGE_TYPE="PROCESS";
# If it's not the case
GRANT PROCESS ON *.* TO '`galera_replication_username`'@localhost;
----

[source,bash]
----
systemctl stop packetfence-mariadb
/usr/local/pf/bin/pfcmd generatemariadbconfig
/usr/local/pf/sbin/pf-mariadb --force-new-cluster
----

You should validate that you are able to connect to the MariaDB database even
though it is in read-only mode using the MariaDB command line:

[source,bash]
----
mysql -u root -p pf -h localhost
----

If its not, make sure you check the MariaDB log
([filename]`/usr/local/pf/logs/mariadb_error.log`)

====== Sync nodes A and B

On each of the servers you want to discard the data from, stop `packetfence-mariadb`, you must destroy all the data in `/var/lib/mysql` and start `packetfence-mariadb` so it resyncs its data from scratch.

[source,bash]
----
systemctl stop packetfence-mariadb
rm -fr /var/lib/mysql/*
/usr/local/pf/bin/pfcmd generatemariadbconfig
systemctl start packetfence-mariadb
----

Should there be any issues during the sync, make sure you look into the MariaDB log ([filename]`/usr/local/pf/logs/mariadb_error.log`)

Once both nodes have completely synced (try connecting to it using the MariaDB
command line), then you can break the cluster election command you have
running on node C and start node C normally (using `systemctl start
packetfence-mariadb`).

====== Upgrading nodes A and B

Next, you can upgrade your operating system and/or PacketFence on nodes A and B by
following instructions of
<<PacketFence_Upgrade_Guide.asciidoc#_packages_upgrades,Packages upgrades
section>>.

WARNING: You only need to merge changes of new configuration files that will not be synced by `/usr/local/pf/bin/cluster/sync` command described below.

IMPORTANT: If you are on a RHEL/CentOS based systems, the command to install
`packetfence-release` released with 10.3.0 version will be:

[source,bash]
----
https://www.packetfence.org/downloads/PacketFence/RHEL7/packetfence-release-7.stable.noarch.rpm
----

====== Maintenance patches (on nodes A and B)

include::common/maintenance_patches.asciidoc[]

====== Configuration synchronisation

You do not need to follow the upgrade procedure when upgrading these nodes. You should instead do a sync from node C on nodes A and B:

[source,bash]
----
/usr/local/pf/bin/cluster/sync --from=192.168.1.5 --api-user=packet --api-password=anotherMoreSecurePassword
/usr/local/pf/bin/pfcmd configreload hard
----

Where:

* `_192.168.1.5_` is the management IP of node C
* `_packet_` is the webservices username (_Configuration->Webservices_)
* `_fence_` is the webservices password (_Configuration->Webservices_)

====== Start nodes A and B

Before starting PacketFence services on nodes A and B, `packetfence-mariadb`
need to be restarted again to take into account changes introduced by packages
upgrades:

[source,bash]
----
systemctl restart packetfence-mariadb
----

You can now safely start PacketFence on nodes A and B using following instructions:

[source,bash]
----
/usr/local/pf/bin/pfcmd fixpermissions
/usr/local/pf/bin/pfcmd pfconfig clear_backend
systemctl restart packetfence-config
/usr/local/pf/bin/pfcmd configreload hard
/usr/local/pf/bin/pfcmd service pf restart
----

===== Restart node C

Now, you should restart PacketFence on node C using following instructions:

[source,bash]
----
/usr/local/pf/bin/pfcmd fixpermissions
/usr/local/pf/bin/pfcmd pfconfig clear_backend
systemctl restart packetfence-config
/usr/local/pf/bin/pfcmd configreload hard
/usr/local/pf/bin/pfcmd service pf restart
----

So it becomes aware of its peers again.

You should now have full service on all 3 nodes using the latest version of PacketFence.

===== Reactivate the configuration conflict handling

Now that your cluster is back to a healthy state, you should reactivate the configuration conflict resolution.

In order to do, so go in _Configuration->System Configuration->Maintenance_ and re-enable the _Cluster Check_ task.

Once this is done, restart `pfcron` on all nodes using:

[source,bash]
----
/usr/local/pf/bin/pfcmd service pfcron restart
----

===== Reactivate galera-autofix

You now need to reactivate and restart the `galera-autofix` service so that it's aware that all the members of the cluster are online again.

In order to do so, go in _Configuration->System Configuration->Services_ and re-enable the `galera-autofix` service.

Once this is done, restart `galera-autofix` service on *all* nodes using:

[source,bash]
----
/usr/local/pf/bin/pfcmd service galera-autofix updatesystemd
/usr/local/pf/bin/pfcmd service galera-autofix restart
----

=== Rename win_agent_download_uri -> windows_agent_download_uri

[source,bash]
----
/usr/local/pf/addons/upgrade/to-10.3-provisioners-windows_agent_download_uri.pl
----

=== LDAP port per server has been deprecated

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.

=== Removal of `inline_accounting` table

`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.

=== `pfdhcplistener` is now tenant aware

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

[source,bash]
----
/usr/local/pf/addons/upgrade/to-10.3-network-conf.pl
----


=== Database schema

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.0 schema to 10.3.0.

To upgrade the database schema, run the following command:

[source,bash]
----
mysql -u root -p pf -v < /usr/local/pf/db/upgrade-10.2.0-10.3.0.sql
----

=== Restart of `packetfence-mariadb` service (standalone installations **only**)

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

[source,bash]
----
systemctl restart packetfence-mariadb
----

== Upgrading from a version prior to 11.0.0

Starting from PacketFence 11.0.0, Debian 9 and CentOS 7 support are dropped in benefit of Debian 11 and RHEL 8.
In place upgrades are not supported. You will have to provision new operating system(s) in order to migrate.

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

Before doing anything else, be sure to read <<PacketFence_Installation_Guide.asciidoc#_assumptions_and_limitations,assumptions and limitations>> of this mechanism.

=== Export (on current installation)

==== If you are running a PacketFence version before 10.3.0

. Follow upgrade path to PacketFence 10.3.0
. Go to next section

==== If you are running PacketFence version 10.3.0 or later

Follow instructions related to <<PacketFence_Installation_Guide.asciidoc#_export_on_current_installation,export process>>.

=== Import (on new installation)

Follow instructions related to <<PacketFence_Installation_Guide.asciidoc#_import_on_new_installation,import process>>.

=== Instructions for upgrades without import

If you don't use import mechanism to upgrade your previous PacketFence
installation, you will need to follow the instructions in this section to
upgrade the configuration and database schema.

==== Configuration upgrade

[source,bash]
----
# Only run this if you don't import your previous configuration
/usr/local/pf/addons/upgrade/to-11.0-firewall_sso-conf.pl
/usr/local/pf/addons/upgrade/to-11.0-no-slash-32-switches.pl
/usr/local/pf/addons/upgrade/to-11.0-openid-username_attribute.pl
----

==== Database schema

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.3 schema to 11.0.

To upgrade the database schema, run the following command:

[source,bash]
----
# Only run this if you don't import your previous configuration
mysql -u root -p pf -v < /usr/local/pf/db/upgrade-10.3-11.0.sql
----


=== NTLM cache background job deprecated in Active Directory Domains

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

=== pf-maint.pl script deprecated

The `pf-maint.pl` script used to get maintenance patches has been deprecated. You can now get maintenance patches using your package manager, see <<#_apply_maintenance_patches,Apply maintenance patches section>>.


=== TLS 1.0 and 1.1 are disabled by default in FreeRADIUS

TLS 1.0 and TLS 1.1 are now disabled by default. If you still have supplicants
using theses protocols, you should move to TLS 1.2. If it's not possible, you
can adjust `TLS Minimum version` in _Configuration -> System configuration ->
RADIUS -> TLS profiles_.


== Upgrading from a version prior to 11.1.0


=== Automation of upgrades for standalone servers

Upgrades are now automated for standalone servers starting from PacketFence 11.0.0.
Follow instructions related to
<<PacketFence_Installation_Guide.asciidoc#_automation_of_upgrades,automation
of upgrades>>.

=== Support of custom rules in iptables.conf

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

* [filename]`/usr/local/pf/conf/iptables-input.conf.inc` for all input traffic
* [filename]`/usr/local/pf/conf/iptables-input-management.conf.inc` for all input traffic related to management interface

If you previously added custom rules in `iptables.conf`, we recommend you to move these rules into these files.

=== Support of local authentication for 802.1X in web admin

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

If you previously enabled `packetfence-local-auth` feature in
[filename]`/usr/local/pf/conf/radiusd/packetfence-tunnel`, we recommend you to
enable this feature in PacketFence web admin (see
<<PacketFence_Installation_Guide.asciidoc#_eap_local_user_authentication,EAP
local user authentication>>).


=== Support of Monit configuration in pf.conf

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


=== Note for cluster upgrades

If you use a cluster, their upgrade isn't yet automated so you will need to follow the instructions in this section to upgrade the configuration and database schema.

==== Configuration upgrade

[source,bash]
----
# Only run this for cluster upgrades
/usr/local/pf/addons/upgrade/to-11.1-cleanup-ntlm-cache-batch-fields.pl
/usr/local/pf/addons/upgrade/to-11.1-migrate-monit-configuration-to-pf-conf.pl
/usr/local/pf/addons/upgrade/to-11.1-remove-unused-sources.pl
/usr/local/pf/addons/upgrade/to-11.1-update-reports.pl
----

==== Database schema

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 11.0 schema to 11.1.

To upgrade the database schema, run the following command:

[source,bash]
----
# Only run this for cluster upgrades
mysql -u root -p pf -v < /usr/local/pf/db/upgrade-11.0-11.1.sql
----

== Upgrading from a version prior to 11.2.0

=== Automation of upgrades for standalone servers

Upgrades are now automated for standalone servers starting from PacketFence 11.0.0.
Follow instructions related to
<<PacketFence_Installation_Guide.asciidoc#_automation_of_upgrades,automation
of upgrades>>.

=== Note for cluster upgrades

If you use a cluster, their upgrade isn't yet automated so you will need to follow the instructions in this section to upgrade the configuration and database schema.

==== Configuration upgrade

[source,bash]
----
/usr/local/pf/addons/upgrade/to-11.2-pfcron.pl
/usr/local/pf/addons/upgrade/to-11.2-pfcron-populate_ntlm_redis_cache.pl
/usr/local/pf/addons/upgrade/to-11.2-upgrade-pf-privileges.sh
----

==== Database schema

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 11.1 schema to 11.2.

To upgrade the database schema, run the following command:

[source,bash]
----
# Only run this for cluster upgrades
mysql -u root -p pf -v < /usr/local/pf/db/upgrade-11.1-11.2.sql
----

=== Change of behavior for filter engines not_equals operator

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 the filter needs to ensure that the value is defined you would need to add an additional defined condition to that filter.

=== Notification on certificates expiration in pfpki

If you use `pfpki` and you created PKI templates without email attribute, we
recommend you to set 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.

== Upgrading from a version prior to 12.0.0

=== Tenant code deprecated

The code used to manage tenants in PacketFence has been removed. If you previously used tenants in PacketFence, you should consider staying on a release prior to v12.

=== Clusters now use ProxySQL to load balance the DB connections

PacketFence previously used haproxy (via the haproxy-db service) to load balance and failover database connections from the PacketFence services to the database servers. This is now performed by ProxySQL which allows for splitting reads and writes to different members which offers greater performance and scalability.

If you suspect that using ProxySQL causes issues in your deployment, you can revert back to using haproxy-db by following <<PacketFence_Clustering_Guide.asciidoc#_database_via_proxysql_or_haproxy_db,these instructions>>

=== Bandwidth accounting is now disabled by default.

Tracking the bandwidth accounting information is now disabled by default.
If you rely on bandwidth reports or security events then enable it by doing the following.
Go to _Configuration -> System Configuration -> RADIUS -> General_
Then enable 'Process Bandwidth Accounting'. `pfacct` service needs to be restarted to apply changes.

=== Fix permissions and checkups deprecated

API calls used to fix permissions and to perform checkups from web admin have been deprecated.
With the containerization of several services, it didn't make sense to keep them available.

However, it's still possible to perform these commands on a PacketFence server using `pfcmd fixpermissions` and `pfcmd checkup`.

=== Change of behavior for the RADIUS source NAS-IP-Address

NOTE: This applies to administrators that have a RADIUS authentication source configured in PacketFence. If you are using PacketFence as a RADIUS server but do not have any RADIUS authentication source configured, this section does not apply to you.

RADIUS authentication sources previously used the source IP of the packet in the NAS-IP-Address field when communicating with the RADIUS server. This behavior has been deprecated in favor of using the management IP address (or VIP in a cluster) in the NAS-IP-Address. If you do need to use another value in the NAS-IP-Address attribute, it is configurable in the RADIUS authentication source directly.

=== Log files names updated

The name of some log files have changed. You can find a list below:

.Mapping between old and new log files
|===
|Service |Old log file(s) |New log file(s)

|MariaDB
|mariadb_error.log
|mariadb.log

|httpd.aaa (Apache requests)
|httpd.aaa.access and httpd.aaa.error
|httpd.apache

|httpd.collector (Apache requests)
|httpd.collector.log and httpd.collector.error
|httpd.apache

|httpd.portal (Apache requests)
|httpd.portal.access, httpd.portal.error, httpd.portal.catalyst
|httpd.apache

|httpd.proxy (Apache requests)
|httpd.proxy.error and httpd.proxy.access
|httpd.apache

|httpd.webservices (Apache requests)
|httpd.webservices.error and httpd.webservices.access
|httpd.apache

|api-frontend (Apache requests)
|httpd.api-frontend.access
|httpd.apache

|HAProxy (all services)
|/var/log/syslog or /var/log/messages
|haproxy.log
|===

=== Remote database backups

The ability to backup a remote database configured in PacketFence has been deprecated.
From now on, a dedicated tool on the database server itself must be used to backup the external database.
If your database is hosted on the PacketFence server (default behavior), then no adjustment is required for this.

== Upgrading from a version prior to 12.1.0

=== configreload deprecated on pfcmd service pf restart

configreload call has been deprecated on pfcmd service pf restart due to a file synchronisation issue on each restart.
If you modify a config file directly from the filesystem then you have to do the configreload manually.

[source,bash]
----
/usr/local/pf/bin/pfcmd configreload hard
----

== Upgrading from a version prior to 12.2.0

=== Changed dynamic ACL attribute for Aruba modules

The attribute used for dynamic ACLs on Aruba/HP switches has been changed to `Aruba-NAS-Filter-Rule`. Make sure you are running a recent firmware for these switches so that this attribute is honored.

=== Accounting requests sent by network devices

Due to containerization of `pfacct` service, network devices must send a RADIUS `NAS-IP-Address` attribute in Accounting-Request packets.
Value of this attribute needs to be an IP address, defined in _Switches_ menu (or part of a CIDR declaration).

If this RADIUS attribute is not sent by your network devices, you need to declare them in _Switches_ menu using MAC Addresses (value of RADIUS `Called-Station-Id` attribute).

=== ZEN 12.1 installations only: manual patch to apply

A link:https://github.com/inverse-inc/packetfence/issues/7568[bug] has been identified on ZEN 12.1 installations.

If you perform a ZEN 12.1 installation, you need to patch your setup using following instructions:

[source,bash]
----
cd /tmp/
wget https://github.com/inverse-inc/packetfence/files/10897043/rc-local.patch
patch /etc/rc.local /tmp/rc-local.patch
----


== Upgrading from a version prior to 13.0.0

=== Adding the LDAP search attributes

LDAP conditions added in the LDAP authentication source use a LDAP search to retrieve the values.

=== Switch types conversion

Two switch types will be converted to the new way of defining a switch. Now, a switch could be defined according the OS and not only the model.

=== Some unused or outdated provisionners will be removed

The following provisioners will be removed from Packetfence configuration IBM, ServiceNow, SEPM, Symantec, Opswat


== Upgrading from a version prior to 13.1.0

=== Domain join

Since v13.1, Packetfence moved from Samba to a new NTLM_AUTH_API service.
In order to upgrade the domain join, make sure your domain controller is running Windows Server 2008 or later, then please, perform the following steps:

First run the following script:

[source,bash]
----
/usr/local/pf/addons/upgrade/to-13.1-move-ntlm-auth-to-rest.pl
----

==== Standalone server

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

==== Cluster

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

1. If the Samba machine name matches the hostname - the script will migrate the configuration to the NTLM_AUTH_API format and replace the machine name with %h.

2. If the Samba machine name does not match the hostname - manually delete the machine accounts in the AD and reconfigure the join.

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_.

IMPORTANT: When creating or editing a Domain, specifying the Server Name as %h will use the hostname of the server. The hostname differs for each member of a cluster.

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 you should be able to see the Machine account created in the Active Directory Domain.

For each remaining server in the cluster:

1. Visit _Status -> Services_ and on the right-side, click _API Redirect_, choose the Nth server.

2. Visit _Configuration -> Policies and Access Control -> Active Directory Domains_ and choose the domain created or modified above.

3. The Machine account password will be a hash or the original password. Retype the password used above.

4. Click Save


== Archived upgrade notes

include::upgrade-notes/archived_upgrade_notes.asciidoc[]

include::includes/additional-info.asciidoc[]

include::includes/commercial-support.asciidoc[]

include::includes/license.asciidoc[]
