From c525b8a9f279a7bf4acf7201b9d5ba0dab758770 Mon Sep 17 00:00:00 2001 From: Francis Lachapelle Date: Fri, 6 Nov 2020 10:51:59 -0500 Subject: [PATCH 01/12] feat(doc): replace xsltproc/fop by asciidoctor-pdf --- Makefile | 52 +-- UPGRADE.asciidoc | 70 ++-- docs/PacketFence_Clustering_Guide-docinfo.xml | 42 --- docs/PacketFence_Clustering_Guide.asciidoc | 15 +- docs/PacketFence_Developers_Guide-docinfo.xml | 92 ----- docs/PacketFence_Developers_Guide.asciidoc | 13 +- ...PacketFence_Installation_Guide-docinfo.xml | 128 ------- docs/PacketFence_Installation_Guide.asciidoc | 15 +- ...rk_Devices_Configuration_Guide-docinfo.xml | 108 ------ ...twork_Devices_Configuration_Guide.asciidoc | 10 +- docs/PacketFence_Template_Guide.asciidoc | 14 +- docs/PacketFence_Upgrade_Guide-docinfo.xml | 4 - docs/{html => }/asciidoctor-html.rb | 0 docs/asciidoctor-pdf-theme.yml | 325 ++++++++++++++++++ docs/docbook/docbook45.conf | 20 -- docs/docbook/fop-centos6.patch | 16 - docs/docbook/xmlgraphics-fop-centos5.patch | 17 - docs/docbook/xsl/headerfooter-fo.xsl | 107 ------ docs/docbook/xsl/packetfence-fo-article.xsl | 193 ----------- docs/docbook/xsl/packetfence-fo.xsl | 173 ---------- docs/docbook/xsl/titlepage-fo.xml | 96 ------ docs/docinfo.xml | 24 -- docs/includes/commercial-support.asciidoc | 8 +- docs/includes/docinfo.asciidoc | 13 + docs/includes/global-attributes.asciidoc | 17 +- 25 files changed, 407 insertions(+), 1165 deletions(-) delete mode 100644 docs/PacketFence_Clustering_Guide-docinfo.xml delete mode 100644 docs/PacketFence_Developers_Guide-docinfo.xml delete mode 100644 docs/PacketFence_Installation_Guide-docinfo.xml delete mode 100644 docs/PacketFence_Network_Devices_Configuration_Guide-docinfo.xml delete mode 100644 docs/PacketFence_Upgrade_Guide-docinfo.xml rename docs/{html => }/asciidoctor-html.rb (100%) create mode 100644 docs/asciidoctor-pdf-theme.yml delete mode 100644 docs/docbook/docbook45.conf delete mode 100644 docs/docbook/fop-centos6.patch delete mode 100644 docs/docbook/xmlgraphics-fop-centos5.patch delete mode 100644 docs/docbook/xsl/headerfooter-fo.xsl delete mode 100644 docs/docbook/xsl/packetfence-fo-article.xsl delete mode 100644 docs/docbook/xsl/packetfence-fo.xsl delete mode 100644 docs/docbook/xsl/titlepage-fo.xml delete mode 100644 docs/docinfo.xml create mode 100644 docs/includes/docinfo.asciidoc diff --git a/Makefile b/Makefile index b52265295c13..e7e905289c19 100644 --- a/Makefile +++ b/Makefile @@ -1,11 +1,4 @@ include config.mk -DOCBOOK_XSL := /usr/share/xml/docbook/stylesheet/docbook-xsl -UNAME := $(shell uname -s) -ifeq ($(UNAME),Darwin) - DOCBOOK_XSL := /opt/local/share/xsl/docbook-xsl -else ifneq ("$(wildcard /etc/redhat-release)","") - DOCBOOK_XSL := /usr/share/sgml/docbook/xsl-stylesheets -endif all: @echo "Please chose which documentation to build:" @@ -17,44 +10,17 @@ all: @echo " 'docs/PacketFence_Network_Devices_Configuration_Guide.pdf' will build the Network Devices Configuration guide in PDF" @echo " 'docs/PacketFence_Upgrade_Guide.pdf' will build the Upgrade guide in PDF" -DOCINFO_XMLS := $(notdir $(wildcard docs/PacketFence_*-docinfo.xml)) -ASCIIDOCS := $(patsubst %-docinfo.xml, %.asciidoc, $(DOCINFO_XMLS)) +ASCIIDOCS := $(notdir $(wildcard docs/PacketFence_*.asciidoc)) PDFS = $(patsubst %.asciidoc,docs/%.pdf, $(ASCIIDOCS)) -docs/docbook/xsl/titlepage-fo.xsl: docs/docbook/xsl/titlepage-fo.xml - xsltproc \ - -o docs/docbook/xsl/titlepage-fo.xsl \ - $(DOCBOOK_XSL)/template/titlepage.xsl \ - docs/docbook/xsl/titlepage-fo.xml - -docs/docbook/xsl/import-fo.xsl: - @echo " \ - \ - \ - " \ - > docs/docbook/xsl/import-fo.xsl - -docs/docbook/%.docbook: docs/%.asciidoc - asciidoc \ - -a docinfo2 \ - -b docbook \ - -d book \ - -f docs/docbook/docbook45.conf \ - -o $@ $< - -docs/%.fo: docs/docbook/%.docbook docs/docbook/xsl/titlepage-fo.xsl docs/docbook/xsl/import-fo.xsl - xsltproc \ - -o $@ \ - docs/docbook/xsl/packetfence-fo.xsl \ - $< +clean: + rm -f docs/html/*.html docs/*.pdf -docs/%.pdf: docs/%.fo - fop \ - -c docs/fonts/fop-config.xml \ - $< -pdf $@ +docs/%.pdf: docs/%.asciidoc + asciidoctor-pdf \ + -a pdf-theme=docs/asciidoctor-pdf-theme.yml \ + -a pdf-fontsdir=docs/fonts \ + $< .PHONY: pdf @@ -64,10 +30,8 @@ HTML = $(patsubst %.asciidoc,docs/html/%.html, $(ASCIIDOCS)) docs/html/%.html: docs/%.asciidoc asciidoctor \ - -D docs/html \ -n \ -r ./docs/html/asciidoctor-html.rb \ - -a imagesdir=../images \ -a stylesdir=../html/pfappserver/root/static.alt/dist/css \ -a stylesheet=$(notdir $(wildcard ./html/pfappserver/root/static.alt/dist/css/app*.css)) \ $< diff --git a/UPGRADE.asciidoc b/UPGRADE.asciidoc index 1b6c6fbe5de7..89ddfe84da70 100644 --- a/UPGRADE.asciidoc +++ b/UPGRADE.asciidoc @@ -1,21 +1,17 @@ = PacketFence Upgrade Guide -:encoding: UTF-8 -:lang: en -:doctype: book -:toc: left - -// to display images directly on GitHub -ifdef::env-github[] -:imagesdir: images -:extra_path: docs/ -endif::[] -:extra_path: //// This file is part of the PacketFence project. -//// + See docs/includes/global-attributes.asciidoc for authors, copyright and + license information. +//// +// Fix includes on GitHub +:extra_path: +ifdef::env-github[] +:extra_path: docs/ +endif::[] include::{extra_path}includes/global-attributes.asciidoc[] == About this Guide @@ -220,7 +216,7 @@ steps required depending on the version you are upgrading from. ==== New versions of configuration files -You should take care to review any changes to configuration files and merge them if required. +You should take care to review any changes to configuration files and merge them if required. ===== RHEL / CentOS based systems @@ -327,21 +323,21 @@ In order to upgrade the MariaDB metadata files and tables, first stop any starte systemctl stop mariadb systemctl stop packetfence-mariadb - + Then start a mysqld_safe process manually (this will start a background process) - + mkdir -p /var/run/mariadb chown mysql: /var/run/mariadb mysqld_safe --basedir=/usr & - + Then, execute the upgrade script and enter the root password when prompted - + mysql_upgrade -u root -p - + When done, kill the mysqld_safe process we started before the update, reattach to it and wait for it to exit kill %1 && fg - + 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) @@ -445,7 +441,7 @@ Clear the redis queue to avoid old stale jobs from being processes. systemctl start packetfence-redis_queue redis-cli -p 6380 FLUSHALL systemctl stop packetfence-redis_queue - + === SSL certificates @@ -465,7 +461,7 @@ A complete re-visit of the database clustering stack was done in version 7.0. If ==== Active/Active clusters with Active/Passive DB (default before 7.0) -We highly suggest you migrate your existing clustered installation using Corosync/Pacemaker to the new cluster stack of PacketFence that uses MariaDB Galera cluster. +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. @@ -478,14 +474,14 @@ You will simply have to adjust your Corosync configuration so that MariaDB point op start timeout=60s interval=0 \ op stop timeout=60s interval=0 \ op monitor interval=20s timeout=30s - + ===== Disabling Galera cluster You must then disable the MariaDB Galera cluster as a replication mechanism as you will still be using DRBD. In order to do so, add the following in `/usr/local/pf/conf/pf.conf` [active_active] galera_replication=disabled - + ===== IP address bind You must also instruct packetfence-mariadb to bind to the management IP address of the server manually. @@ -509,7 +505,7 @@ Where 1.2.3.4 is the management IP address of the server. Like in previous versions where mariadb shouldn't have been started on boot, now you must ensure its replacement (packetfence-mariadb) doesn't start on boot. systemctl disable packetfence-mariadb - + *Enabling the packetfence-cluster target* Next, you must set the default target to packetfence-cluster: @@ -592,7 +588,7 @@ PacketFence is now able to instruct Samba to «pin» a DC for authentication or You should instruct Samba to connect to all domain controllers by adding the following to each of your domains in domain.conf: sticky_dc=* - + And then regenerate the domain configuration: /usr/local/pf/bin/pfcmd fixpermissions @@ -680,7 +676,7 @@ If you use social login with LinkedIn OAuth2, you will need to adjust the list o For all your LinkedIn sources, change the domains to: www.linkedin.com,api.linkedin.com,*.licdn.comlatform.linkedin.com - + === Portal redirection timer @@ -765,7 +761,7 @@ In order to do so, execute the following: === Changes to DNS filters -The $qname parameter need to be removed from dns_filters.conf +The $qname parameter need to be removed from dns_filters.conf In order to do so, execute the following command: @@ -783,7 +779,7 @@ 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.0). -== Upgrading from a version prior to 8.1.0 +== Upgrading from a version prior to 8.1.0 === Changes on unreg_on_accounting_stop parameter @@ -814,16 +810,16 @@ The queue_stats maintenance job has been deprecated in favor of using pfstats. I /usr/local/pf/addons/upgrade/to-8.2-pfmon-conf.pl -=== Upgrade pfdetect perl regex to the go RE2 regex +=== 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. +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. +Any Perl regex that cannnot be convert will be displayed and should be fixed. === Upgrade realm.conf to be tenant aware @@ -942,14 +938,14 @@ 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: /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 @@ -961,7 +957,7 @@ Accounting cleanup is now done via a pfmon task (acct_cleanup) instead of the da 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/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 @@ -1095,7 +1091,7 @@ installed, this one has been upgraded to latest version. 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: +In order to install new versions of Debian packages, you will need to add a new GPG key to your system: [source,bash] ---- @@ -1297,7 +1293,7 @@ This script will add the prefix: === 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. +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] diff --git a/docs/PacketFence_Clustering_Guide-docinfo.xml b/docs/PacketFence_Clustering_Guide-docinfo.xml deleted file mode 100644 index 74fb936cc7ba..000000000000 --- a/docs/PacketFence_Clustering_Guide-docinfo.xml +++ /dev/null @@ -1,42 +0,0 @@ - - 2020 - Inverse inc. - - - - - 1.2 - 2018-02-01 - -Adding precisions - -Adding tests - - - - - - 1.1 - 2017-12-13 - -Adding of the maintenance - -Adding of the shutdown procedure - - - - - - 1.0 - 2015-03-23 - First revision - - - - - - Inverse - Inc. - -
- info@inverse.ca -
- - - diff --git a/docs/PacketFence_Clustering_Guide.asciidoc b/docs/PacketFence_Clustering_Guide.asciidoc index 7a4f5717b9af..d932a5f92ed6 100644 --- a/docs/PacketFence_Clustering_Guide.asciidoc +++ b/docs/PacketFence_Clustering_Guide.asciidoc @@ -1,23 +1,12 @@ = Clustering Quick Installation Guide -:encoding: UTF-8 -:lang: en -:doctype: book -:toc: left - -// to display images directly on GitHub -ifdef::env-github[] -:imagesdir: images -endif::[] - //// This file is part of the PacketFence project. - See PacketFence_Clustering_Guide-docinfo.xml for - authors, copyright and license information. + See includes/global-attributes.asciidoc for authors, copyright and + license information. //// - include::includes/global-attributes.asciidoc[] == About this Guide diff --git a/docs/PacketFence_Developers_Guide-docinfo.xml b/docs/PacketFence_Developers_Guide-docinfo.xml deleted file mode 100644 index f65679536e9a..000000000000 --- a/docs/PacketFence_Developers_Guide-docinfo.xml +++ /dev/null @@ -1,92 +0,0 @@ - - 2020 - Inverse inc. - - - - - 3.1 - 2013-07-10 - Removed references to ui.conf. - - - 3.0 - 2012-09-05 - Port to asciidoc. - - - 2.9 - 2012-02-22 - Cosmetic improvements. - - - 2.8 - 2011-12-15 - Coverage of our support for RADIUS Dynamic Authorization (RFC3576). Updated exception-handling - section. Added transifex translation instructions. - - - 2.7 - 2011-10-31 - Explained new translation technique for violation remediation pages. - - - 2.6 - 2011-10-19 - New documentation section points to POD doc. New Authentication modules section. Minor references - that were out of date. - - - 2.5 - 2011-09-21 - Content updated to reflect latest captive portal improvements: Better templating, XHTML/CSS and - streamlined remediation pages. Updated translation information including contributing translations. How-to - develop support for Floating Network Devices in switches and documented controllerIp feature. - - - 2.4 - 2011-03-31 - Updated wireless hardware support instructions and checklist. Added clarifications to the MAC Auth - and 802.1X support development. - - - 2.3 - 2011-02-10 - Template improvements - - - 2.2 - 2011-02-02 - Reworked new switch support into a more general new network devices support. New content: Wireless - Access-Points and Controllers, Switch support for MAC Auth and 802.1X, a new "add a network device to - PacketFence" checklist and new exception handling techniques. - - - 2.1 - 2011-02-01 - New content: a chapter on contributing, one on code conventions and one on developer recipes (run - devel env., debug grammar). - - - 2.0 - 2011-01-31 - Port to Docbook. - - - 1.0 - 2008-12-13 - First OpenDocument version. - - - - - - Inverse - Inc. - -
- info@inverse.ca -
- - - diff --git a/docs/PacketFence_Developers_Guide.asciidoc b/docs/PacketFence_Developers_Guide.asciidoc index 9169e9468c8f..84325b312d24 100644 --- a/docs/PacketFence_Developers_Guide.asciidoc +++ b/docs/PacketFence_Developers_Guide.asciidoc @@ -1,23 +1,12 @@ = Developer's Guide -:encoding: UTF-8 -:lang: en -:doctype: book -:toc: left -:experimental: -// to display images directly on GitHub -ifdef::env-github[] -:imagesdir: images -endif::[] - //// This file is part of the PacketFence project. - See PacketFence_Developers_Guide-docinfo.xml for authors, copyright and + See includes/global-attributes.asciidoc for authors, copyright and license information. //// - include::includes/global-attributes.asciidoc[] == About this Guide diff --git a/docs/PacketFence_Installation_Guide-docinfo.xml b/docs/PacketFence_Installation_Guide-docinfo.xml deleted file mode 100644 index 3bb3a62701c9..000000000000 --- a/docs/PacketFence_Installation_Guide-docinfo.xml +++ /dev/null @@ -1,128 +0,0 @@ - - 2020 - Inverse inc. - - - - - 3.5 - 2014-10-22 - - - Adding MDM documentation - - - - 3.4 - 2014-09-10 - - - Adding documentation for EAP Local Account - - Adding documentation for VLAN Filters based on person attributes - - - - 3.3 - 2014-06-26 - - - Adding documentation for Firewall SSO - - Adding documentation for Active Directory integration - - Adding documentation for Apache Filters - - Adding documentation for VLAN Filters - - Adding documentation for Windows Live and Linkedin OAuth2 - - - - 3.2 - 2013-08-09 - Adding documentation for passthroughs - - - 3.1 - 2013-07-12 - Removed references to bind (replaced by pfdns). - - - 3.0 - 2013-05-17 - - - New support for Debian - - - - 2.9 - 2013-04-03 - - - Major rework for the v4 release - - - - 2.8 - 2013-01-09 - - - Adding documentation for gaming devices registration - - Version bump for the epel repository version - - - - 2.7 - 2012-10-01 - - Adding documentation for OAuth2 Providers - - - - 2.6 - 2012-09-05 - - Managed FreeRADIUS updates. Proper ownership of the - /var/lib/samba/winbind_privileged folder since 3.5 release. Added EPEL - on the installation line for RHEL-based systems. - - - - 2.5 - 2012-07-30 - Doc update for RADIUS - - - 2.4 - 2012-07-26 - Added documentation for new captive portal profiles feature. - - - 2.3 - 2012-07-19 - Adding suricata documentation - - - 2.2 - 2012-06-13 - Added installation procedure for Debian. A minor fix to RHEL6 install instructions. - - - 2.1 - 2012-04-12 - Added new documentation about pre-registered, sponsored guests and role-based enforcement. Covered updated inline enforcement instructions. Updated drbd and samba installation instructions. SoH, ntlm_auth test and some typos fixed too. - - - 2.0 - 2012-02-22 - Documentation ported to asciidoc. Added section for accounting violations based on bandwidth, OpenVAS-based client side policy compliance and billing integration. Updated FreeRADIUS 2 config and log locations. More documentation about running a scan from a remote server. Improvements to the trap limit feature description. Updated guest registration configuration section (new parameter introduced). Added basic VoIP documentation and warning regarding CLI access due to #1370. - - - 1.0 - 2008-12-13 - First OpenDocument version. - - - - - - Inverse - Inc. - -
- info@inverse.ca -
- - - diff --git a/docs/PacketFence_Installation_Guide.asciidoc b/docs/PacketFence_Installation_Guide.asciidoc index c5f9fdfe6f17..96d1d5ad0e11 100644 --- a/docs/PacketFence_Installation_Guide.asciidoc +++ b/docs/PacketFence_Installation_Guide.asciidoc @@ -1,23 +1,12 @@ = Installation Guide -:encoding: UTF-8 -:lang: en -:doctype: book -:toc: left - -// to display images directly on GitHub -ifdef::env-github[] -:imagesdir: images -endif::[] - //// This file is part of the PacketFence project. - See PacketFence_Installation_Guide-docinfo.xml for authors, copyright - and license information. + See includes/global-attributes.asciidoc for authors, copyright and + license information. //// - include::includes/global-attributes.asciidoc[] == About this Guide diff --git a/docs/PacketFence_Network_Devices_Configuration_Guide-docinfo.xml b/docs/PacketFence_Network_Devices_Configuration_Guide-docinfo.xml deleted file mode 100644 index ab278388a92f..000000000000 --- a/docs/PacketFence_Network_Devices_Configuration_Guide-docinfo.xml +++ /dev/null @@ -1,108 +0,0 @@ - - 2020 - Inverse inc. - - - - - - 3.1 - 2017-12-13 - - - Adding HP1910 Serie Documentatio - - - 3.0 - 2015-05-26 - - - Adding Aironet 1600 CoA documentation - - - - 2.9 - 2015-02-04 - - - Adding 802.1X documentation for HP Procurve 2610 - - Adding Juniper floating config to documentation - - - - 2.8 - 2014-09-10 - - - Adding documentation for Mikrotik - - Adding documentation for Cisco downloadable acls - - Adding documentation for Xirrus external portal - - Adding documentation for AeroHIVE external portal - - Adding documentation for Anyfi - - Adding documentation for Netgear M series - - - - 2.7 - 2014-06-26 - - - Adding documentation for Juniper - - Adding documentation for Cisco 2960 web authentication - - Adding documentation for Edge-corE - - Adding documentation for Netgear M series - - - - 2.6 - 2012-10-26 - Adding documentation for Belair AP - - - 2.5 - 2012-09-12 - Adding documentation for WIPS feature - - - 2.4.1 - 2012-09-05 - Adding the server-group support on Procurve 2610 switches. Minor fix to Trapeze config. - - - 2.4 - 2012-06-19 - Added Netgear GS110 documentation. Updated the authors list. - - - 2.3 - 2012-06-13 - Added Brocade, Cisco WLC/WiSM and H3C documentation. Some assumptions were updated. - - - 2.2 - 2012-04-23 - HP ProCurve 5300 Series identified as supported. - - - 2.1 - 2012-04-12 - Added new configuration documentation for AlliedTelesis. Roles support for AeroHive, Aruba, Meru and Motorola. - - - 2.0 - 2012-02-22 - Port to asciidoc. Added Ruckus documentation. Added documentation for Meru PMK caching. - - - 1.0 - 2010-11-22 - First OpenDocument version. - - - - - - Inverse - Inc. - -
- info@inverse.ca -
- - - diff --git a/docs/PacketFence_Network_Devices_Configuration_Guide.asciidoc b/docs/PacketFence_Network_Devices_Configuration_Guide.asciidoc index 046677045399..1c2cf8f09e41 100644 --- a/docs/PacketFence_Network_Devices_Configuration_Guide.asciidoc +++ b/docs/PacketFence_Network_Devices_Configuration_Guide.asciidoc @@ -1,9 +1,4 @@ = Network Devices Configuration Guide -:encoding: UTF-8 -:lang: en -:doctype: book -:toc: left - // to display images directly on GitHub ifdef::env-github[] :imagesdir: https://github.com/inverse-inc/packetfence/tree/devel/docs/images @@ -13,11 +8,10 @@ endif::[] This file is part of the PacketFence project. - See PacketFence_Network_Devices_Configuration_Guide-docinfo.xml for - authors, copyright and license information. + See includes/global-attributes.asciidoc for authors, copyright and + license information. //// - include::includes/global-attributes.asciidoc[] == About this Guide diff --git a/docs/PacketFence_Template_Guide.asciidoc b/docs/PacketFence_Template_Guide.asciidoc index 7f0b994e25f7..4ea3021c8fbb 100644 --- a/docs/PacketFence_Template_Guide.asciidoc +++ b/docs/PacketFence_Template_Guide.asciidoc @@ -1,20 +1,12 @@ = Guide name -:encoding: UTF-8 -:lang: en -:doctype: book -:toc: left - -// to display images directly on GitHub -ifdef::env-github[] -:imagesdir: images -endif::[] - //// This file is part of the PacketFence project. -//// + See includes/global-attributes.asciidoc for authors, copyright and + license information. +//// include::includes/global-attributes.asciidoc[] == About this Guide diff --git a/docs/PacketFence_Upgrade_Guide-docinfo.xml b/docs/PacketFence_Upgrade_Guide-docinfo.xml deleted file mode 100644 index c75b9dd86b09..000000000000 --- a/docs/PacketFence_Upgrade_Guide-docinfo.xml +++ /dev/null @@ -1,4 +0,0 @@ - - 2020 - Inverse inc. - diff --git a/docs/html/asciidoctor-html.rb b/docs/asciidoctor-html.rb similarity index 100% rename from docs/html/asciidoctor-html.rb rename to docs/asciidoctor-html.rb diff --git a/docs/asciidoctor-pdf-theme.yml b/docs/asciidoctor-pdf-theme.yml new file mode 100644 index 000000000000..9620bde0561d --- /dev/null +++ b/docs/asciidoctor-pdf-theme.yml @@ -0,0 +1,325 @@ +# +# https://github.com/asciidoctor/asciidoctor-pdf/blob/master/docs/theming-guide.adoc +# +# asciidoctor-pdf -a pdf-theme=theme.yml -a pdf-fontsdir=fonts PacketFence_Clustering_Guide.asciidoc --trace +# + +font: + catalog: + # Noto Serif supports Latin, Latin-1 Supplement, Latin Extended-A, Greek, Cyrillic, Vietnamese & an assortment of symbols + #Noto Serif: + # normal: notoserif-regular-subset.ttf + # bold: notoserif-bold-subset.ttf + # italic: notoserif-italic-subset.ttf + # bold_italic: notoserif-bold_italic-subset.ttf + Lato-Light: + normal: lato/Lato-Light.ttf + bold: lato/Lato-Regular.ttf + italic: lato/Lato-LightItalic.ttf + bold_italic: lato/Lato-Italic.ttf + # M+ 1mn supports ASCII and the circled numbers used for conums + #M+ 1mn: + # normal: mplus1mn-regular-subset.ttf + # bold: mplus1mn-bold-subset.ttf + # italic: mplus1mn-italic-subset.ttf + # bold_italic: mplus1mn-bold_italic-subset.ttf + Inconsolata: + normal: inconsolata.ttf + bold: inconsolata.ttf + italic: inconsolata.ttf + bold_italic: inconsolata.ttf +page: + background_color: FFFFFF + layout: portrait + initial_zoom: FitH + margin: [1in, 1in, 1in, 1in] + # margin_inner and margin_outer keys are used for recto/verso print margins when media=prepress + margin_inner: 1in + margin_outer: 1in + size: Letter +base: + align: justify + # color as hex string (leading # is optional) + font_color: 333333 + font_color: 000000 + # color as RGB array + #font_color: [51, 51, 51] + # color as CMYK array (approximated) + #font_color: [0, 0, 0, 0.92] + #font_color: [0, 0, 0, 92%] + font_family: Lato-Light + # choose one of these font_size/line_height_length combinations + #font_size: 14 + #line_height_length: 20 + #font_size: 11.25 + #line_height_length: 18 + #font_size: 11.2 + #line_height_length: 16 + font_size: 10 + #line_height_length: 15 + # correct line height for Noto Serif metrics + line_height_length: 10 + #font_size: 11.25 + #line_height_length: 18 + line_height: $base_line_height_length / $base_font_size + font_size_large: round($base_font_size * 1.25) + font_size_small: round($base_font_size * 0.85) + font_size_min: $base_font_size * 0.75 + font_style: normal + border_color: EEEEEE + border_radius: 4 + border_width: 0.5 +section: + indent: [0.67in, 0] +role: + line-through: + text_decoration: line-through + underline: + text_decoration: underline + big: + font_size: $base_font_size_large + small: + font_size: $base_font_size_small + subtitle: + font_size: 0.8em + font_color: 999999 +# FIXME vertical_rhythm is weird; we should think in terms of ems +#vertical_rhythm: $base_line_height_length * 2 / 3 +# correct line height for Noto Serif metrics (comes with built-in line height) +vertical_rhythm: $base_line_height_length +horizontal_rhythm: $base_line_height_length +# QUESTION should vertical_spacing be block_spacing instead? +vertical_spacing: $vertical_rhythm +link: + font_color: 428BCA + font_color: 007BFF +# literal is currently used for inline monospaced in prose and table cells +literal: + font_color: 333333 + font_color: B12146 + font_color: E83E8C + font_family: Inconsolata +button: + content: "[\u2009%s\u2009]" + font_style: bold +key: + background_color: F5F5F5 + background_color: F8F8F8 + border_color: CCCCCC + border_offset: 2 + border_radius: 2 + border_width: 0.5 + font_family: $literal_font_family + separator: "\u202f+\u202f" +mark: + background_color: FFFF00 + border_offset: 1 +menu: + caret_content: " \u203a " +heading: + align: left + font_color: $base_font_color + font_style: bold + # h1 is used for part titles (book doctype) or the doctitle (article doctype) + h1_font_size: floor($base_font_size * 2.6) + # h2 is used for chapter titles (book doctype only) + h2_font_size: floor($base_font_size * 2.15) + h3_font_size: round($base_font_size * 1.7) + h4_font_size: $base_font_size_large + h5_font_size: $base_font_size + h6_font_size: $base_font_size_small + #line_height: 1.4 + # correct line height for Noto Serif metrics (comes with built-in line height) + line_height: 1 + margin_top: $vertical_rhythm * 0.4 + margin_bottom: $vertical_rhythm * 0.9 + min_height_after: $base_line_height_length * 1.5 + h2-margin_bottom: 60 + #h2-text_decoration: underline +title_page: + align: right + logo: + top: 10% + title: + top: 55% + font_size: $heading_h1_font_size + font_color: 999999 + font_color: $base_font_color + line_height: 0.9 + subtitle: + font_size: $heading_h3_font_size + font_style: bold_italic + line_height: 1 + authors: + margin_top: $base_font_size * 1.25 + font_size: $base_font_size_large + font_color: 181818 + revision: + margin_top: $base_font_size * 1.25 +block: + margin_top: 0 + margin_bottom: $vertical_rhythm +caption: + align: left + font_size: $base_font_size * 0.95 + font_style: italic + # FIXME perhaps set line_height instead of / in addition to margins? + margin_inside: $vertical_rhythm / 3 + #margin_inside: $vertical_rhythm / 4 + margin_outside: 0 +lead: + font_size: $base_font_size_large + line_height: 1.4 +abstract: + font_color: 5C6266 + font_size: $lead_font_size + line_height: $lead_line_height + font_style: italic + first_line_font_style: bold + title: + align: center + font_color: $heading_font_color + font_size: $heading_h4_font_size + font_style: $heading_font_style +admonition: + column_rule_color: $base_border_color + column_rule_width: $base_border_width + padding: [0, $horizontal_rhythm, 0, $horizontal_rhythm] + # icon: + # caution: + # name: far-lightbulb + # name: fa-fire + # stroke_color: 111111 + # size: 24 + label: + text_transform: uppercase + font_style: bold + # caution: + # font_color: F77D05 +blockquote: + font_size: $base_font_size_large + border_color: $base_border_color + border_width: 0 + border_left_width: 5 + # FIXME disable negative padding bottom once margin collapsing is implemented + padding: [0, $horizontal_rhythm, $block_margin_bottom * -0.75, $horizontal_rhythm + $blockquote_border_left_width / 2] + cite_font_size: $base_font_size_small + cite_font_color: 999999 +verse: + font_size: $blockquote_font_size + border_color: $blockquote_border_color + border_width: $blockquote_border_width + border_left_width: $blockquote_border_left_width + padding: $blockquote_padding + cite_font_size: $blockquote_cite_font_size + cite_font_color: $blockquote_cite_font_color +# code is used for source blocks (perhaps change to source or listing?) +code: + font_color: $base_font_color + #font_color: FFFFFF + font_family: $literal_font_family + font_size: ceil($base_font_size) + padding: $code_font_size + line_height: 1.25 + # line_gap is an experimental property to control how a background color is applied to an inline block element + line_gap: 3.8 + background_color: F5F5F5 + background_color: F8F8F8 + #background_color: 6C757D + border_color: CCCCCC + border_radius: $base_border_radius + border_radius: 0 + border_width: 0.75 + border_width: 0 +conum: + font_family: $literal_font_family + font_color: $literal_font_color + font_size: $base_font_size + line_height: 4 / 3 + glyphs: circled +example: + border_color: $base_border_color + border_radius: $base_border_radius + border_width: 0.75 + background_color: $page-background-color + # FIXME reenable padding bottom once margin collapsing is implemented + padding: [$vertical_rhythm, $horizontal_rhythm, 0, $horizontal_rhythm] +image: + align: left +prose: + margin_top: $block_margin_top + margin_bottom: $block_margin_bottom +sidebar: + background_color: EEEEEE + border_color: E1E1E1 + border_radius: $base_border_radius + border_width: $base_border_width + # FIXME reenable padding bottom once margin collapsing is implemented + padding: [$vertical_rhythm, $vertical_rhythm * 1.25, 0, $vertical_rhythm * 1.25] + title: + align: center + font_color: $heading_font_color + font_size: $heading_h4_font_size + font_style: $heading_font_style +thematic_break: + border_color: $base_border_color + border_style: solid + border_width: $base_border_width + margin_top: $vertical_rhythm * 0.5 + margin_bottom: $vertical_rhythm * 1.5 +description_list: + term_font_style: bold + term_spacing: $vertical_rhythm / 4 + description_indent: $horizontal_rhythm * 1.25 +outline_list: + indent: $horizontal_rhythm * 1.5 + #marker_font_color: 404040 + # NOTE outline_list_item_spacing applies to list items that do not have complex content + item_spacing: $vertical_rhythm / 2 +table: + background_color: $page_background_color + border_color: DDDDDD + border_width: $base_border_width + cell_padding: 3 + head: + font_style: bold + border_bottom_width: $base_border_width * 2.5 + body: + stripe_background_color: F9F9F9 + foot: + background_color: F0F0F0 +toc: + indent: $horizontal_rhythm + line_height: $base_line_height + dot_leader: + #content: ". " + font_color: A9A9A9 + #levels: 2 3 +footnotes: + font_size: round($base_font_size * 0.75) + item_spacing: $outline_list_item_spacing / 2 +header: + # Can't show chapter number. See https://github.com/asciidoctor/asciidoctor-pdf/issues/1373 + font_size: $base_font_size_small + line_height: 1 + vertical_align: middle +footer: + font_size: $base_font_size_small + # NOTE if background_color is set, background and border will span width of page + #border_color: DDDDDD + border_width: 0.25 + #height: $base_line_height_length * 2.5 + height: $base_line_height_length * 5 + line_height: 1 + padding: [$base_line_height_length / 2, 1, 0, 1] + vertical_align: top + recto: &shared_footer + #columns: "<50% =0% >50%" + left: + content: 'Copyright © Inverse inc.' + center: + content: '{chapter-title}' + right: + content: '{page-number}' + verso: *shared_footer + #columns: $footer_recto_columns diff --git a/docs/docbook/docbook45.conf b/docs/docbook/docbook45.conf deleted file mode 100644 index b6949b68e1e5..000000000000 --- a/docs/docbook/docbook45.conf +++ /dev/null @@ -1,20 +0,0 @@ -# -# docbook45.conf -# -# Asciidoc DocBook 4.5 configuration file. -# - -[image-blockmacro] -{title} -{title%}{pgwide-option?} -# DocBook XSL Stylesheets custom processing instructions. - - - - - - - {alt={target}} - -{title#} -{title%} diff --git a/docs/docbook/fop-centos6.patch b/docs/docbook/fop-centos6.patch deleted file mode 100644 index 630628898c3f..000000000000 --- a/docs/docbook/fop-centos6.patch +++ /dev/null @@ -1,16 +0,0 @@ -# -# fop fix to build our documentation on CentOS 6 -# -# Inverse inc. -# ---- /usr/bin/fop.orig 2012-01-17 21:25:50.000000000 -0500 -+++ /usr/bin/fop 2012-01-17 21:26:04.000000000 -0500 -@@ -26,7 +26,7 @@ - # Set parameters - set_jvm - set_classpath commons-io batik-all avalon-framework xmlgraphics-commons \ -- commons-logging fop -+ commons-logging fop xalan-j2 - set_flags $BASE_FLAGS - set_options $BASE_OPTIONS - diff --git a/docs/docbook/xmlgraphics-fop-centos5.patch b/docs/docbook/xmlgraphics-fop-centos5.patch deleted file mode 100644 index 932c494cf0f5..000000000000 --- a/docs/docbook/xmlgraphics-fop-centos5.patch +++ /dev/null @@ -1,17 +0,0 @@ -# -# xmlgraphics-fop fix to build our documentation on CentOS 5 -# taken from https://build.opensuse.org/request/show/68994 -# -# Inverse inc. -# ---- /usr/bin/xmlgraphics-fop.orig 2012-01-17 18:42:08.000000000 -0500 -+++ /usr/bin/xmlgraphics-fop 2012-01-17 18:42:18.000000000 -0500 -@@ -24,7 +24,7 @@ - - # Rest of the configuration - MAIN_CLASS=org.apache.fop.cli.Main --BASE_JARS="xmlgraphics-fop xmlgraphics-batik/util xml-commons-jaxp-1.3-apis excalibur/avalon-framework-api xerces-j2 xalan-j2 xalan-j2-serializer" -+BASE_JARS="xmlgraphics-fop batik-all xml-commons-jaxp-1.3-apis excalibur/avalon-framework-impl excalibur/avalon-framework-api xerces-j2 xalan-j2 xalan-j2-serializer" - - # Set parameters - set_jvm diff --git a/docs/docbook/xsl/headerfooter-fo.xsl b/docs/docbook/xsl/headerfooter-fo.xsl deleted file mode 100644 index d757bfaaabb9..000000000000 --- a/docs/docbook/xsl/headerfooter-fo.xsl +++ /dev/null @@ -1,107 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/docbook/xsl/packetfence-fo-article.xsl b/docs/docbook/xsl/packetfence-fo-article.xsl deleted file mode 100644 index b45e6429f52d..000000000000 --- a/docs/docbook/xsl/packetfence-fo-article.xsl +++ /dev/null @@ -1,193 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Sorts Mill Goudy - - - 0.5em - solid 2px - 1em - - - solid 1px - 1em - 1em - - - 1em - 1em - - - 1em - - - 1em - - - - - 1.5em - 1.5em - 2.2em - - - - Delicious - 10 - Incosolata - - - - 12pt - bold - center - - - page - - - 1px solid - - - - - - - - - - - - - 0em - 0em - 0.2em - - - - - - - ∏ - - - - - - square - - - - - - docs/images/ - .png - - 1px solid - 1px solid - 0.5em - 0.5em - 2em - - - - - - - #E0E0E0 - solid - 0pt - 0.5em - - always - - - - - wrap - - - - - - - - blue - underline - - - - - - - - - - diff --git a/docs/docbook/xsl/packetfence-fo.xsl b/docs/docbook/xsl/packetfence-fo.xsl deleted file mode 100644 index 60f71a94d975..000000000000 --- a/docs/docbook/xsl/packetfence-fo.xsl +++ /dev/null @@ -1,173 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - Lato-Medium - - - 2.5em - solid 2px - 1em - - - solid 1px - 2em - 1em - - - - - 1em - - - - Lato-Light - 10 - Incosolata - - - - 12pt - bold - center - - - page - - - 1px solid - - - - - - - - - - - - - - - - ▪ - - - - - - square - - - - - - images/ - .png - - 0.5em - 0.5em - - - - - - #F7F8F9 - #333 - 0pt - 0.5em - - always - - - - - wrap - - - - - - - - blue - underline - - - - - - - - - - - - - - - - - diff --git a/docs/docbook/xsl/titlepage-fo.xml b/docs/docbook/xsl/titlepage-fo.xml deleted file mode 100644 index c9b15b082a06..000000000000 --- a/docs/docbook/xsl/titlepage-fo.xml +++ /dev/null @@ -1,96 +0,0 @@ - - - - - - - - - - - - -]> - - - - - - - - - - - <subtitle - text-align="right" - font-size="&hsize4;" - space-before="&hsize4space;" - font-family="{$title.fontset}" - border-bottom="solid"/> - </t:titlepage-content> - - <t:titlepage-content t:side="verso"> - <title - font-size="&hsize2;" - font-weight="bold" - font-family="{$title.fontset}"/> - <corpauthor/> - <authorgroup t:named-template="verso.authorgroup"/> - <author/> - <othercredit/> - <releaseinfo space-before="0.5em"/> - <pubdate space-before="1em"/> - <copyright/> - <abstract/> - <legalnotice font-size="8pt"/> - </t:titlepage-content> - - <t:titlepage-separator> - <fo:block break-after="page"/> - </t:titlepage-separator> - - <t:titlepage-before t:side="recto"> - </t:titlepage-before> - - <t:titlepage-before t:side="verso"> - <fo:block break-after="page"/> - </t:titlepage-before> -</t:titlepage> - -</t:templates> diff --git a/docs/docinfo.xml b/docs/docinfo.xml deleted file mode 100644 index fb82c3c9d085..000000000000 --- a/docs/docinfo.xml +++ /dev/null @@ -1,24 +0,0 @@ -<!-- TODO have the build system take care of this --> -<releaseinfo>Version 10.2.0 - October 2020</releaseinfo> -<subtitle>for PacketFence version 10.2.0</subtitle> -<date>2020-06-17</date> - -<legalnotice> - <para>Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".</para> - - <!-- font licenses --> - <para>The fonts used in this guide are licensed under the SIL Open Font License, Version 1.1. This license is available with a FAQ at: <ulink url="http://scripts.sil.org/OFL">http://scripts.sil.org/OFL</ulink></para> - <para>Copyright © Łukasz Dziedzic, <ulink url="http://www.latofonts.com/">http://www.latofonts.com</ulink>, with Reserved Font Name: "Lato".</para> - <para>Copyright © Raph Levien, <ulink url="http://levien.com/">http://levien.com/</ulink>, with Reserved Font Name: "Inconsolata".</para> -</legalnotice> -<mediaobject> - <objectinfo> - <corpname>Inverse inc.</corpname> - </objectinfo> - <textobject> - <phrase>PacketFence's spike logo</phrase> - </textobject> - <imageobject> - <imagedata align="left" width="4in" format="PNG" fileref="images/pf-logo.png" /> - </imageobject> -</mediaobject> diff --git a/docs/includes/commercial-support.asciidoc b/docs/includes/commercial-support.asciidoc index 54cb76a0f551..43159d1e6654 100644 --- a/docs/includes/commercial-support.asciidoc +++ b/docs/includes/commercial-support.asciidoc @@ -14,15 +14,15 @@ Commercial Support and Contact Information ------------------------------------------ -For any questions or comments, do not hesitate to contact us by writing an +For any questions or comments, do not hesitate to contact us by writing an email to: support@inverse.ca. -Inverse (http://inverse.ca) offers professional services around PacketFence -to help organizations deploy the solution, customize, migrate versions or +Inverse (https://inverse.ca) offers professional services around PacketFence +to help organizations deploy the solution, customize, migrate versions or from another system, performance tuning or aligning with best practices. Hourly rates or support packages are offered to best suit your needs. -Please visit http://inverse.ca/ for details. +Please visit https://inverse.ca/ for details. // vim: set syntax=asciidoc tabstop=2 shiftwidth=2 expandtab: diff --git a/docs/includes/docinfo.asciidoc b/docs/includes/docinfo.asciidoc new file mode 100644 index 000000000000..c7facb223ba5 --- /dev/null +++ b/docs/includes/docinfo.asciidoc @@ -0,0 +1,13 @@ +**Version {release_version} - {release_month} {docyear}** + +Copyright © {docyear} Inverse inc. + +Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License". + +The fonts used in this guide are licensed under the SIL Open Font License, Version 1.1. This license is available with a FAQ at: http://scripts.sil.org/OFL + +Copyright © Łukasz Dziedzic, http://www.latofonts.com/, with Reserved Font Name: "Lato". + +Copyright © Raph Levien, http://levien.com/, with Reserved Font Name: "Inconsolata". + +image::inverse-logo.jpg[width="25%",pdfwidth="50%",align="right"] diff --git a/docs/includes/global-attributes.asciidoc b/docs/includes/global-attributes.asciidoc index c435d6c6eb75..1e429f606e97 100644 --- a/docs/includes/global-attributes.asciidoc +++ b/docs/includes/global-attributes.asciidoc @@ -10,13 +10,24 @@ License: GFDL 1.2 or later. http://www.gnu.org/licenses/fdl.html //// - -// TODO have the build system take care of this - :release_version: 10.2.0 +:release_month: October +:encoding: UTF-8 +:lang: en +:doctype: book +PacketFence v{release_version} +:toc: left // set imagesdir for all asciidoc files :imagesdir: images :sectanchors: :sectlinks: +// Add numbers to each section +:sectnums: +// Remove chapter prefix +:chapter-signifier: +:front-cover-image: image:pf-logo.png[fit=none,pdfwidth=50%,position=center] +:source-highlighter: rouge +:rouge-style: github +include::docinfo.asciidoc[] // vim: set syntax=asciidoc tabstop=2 shiftwidth=2 expandtab: From 8ba35a59f3159cf1983ac0544d0c14be8ab3b2d5 Mon Sep 17 00:00:00 2001 From: Francis Lachapelle <flachapelle@inverse.ca> Date: Fri, 6 Nov 2020 11:28:00 -0500 Subject: [PATCH 02/12] fix(doc): remove dependencies for pdf generation, review paths --- Makefile | 17 ++++++++--------- debian/rules | 2 +- rpm/packetfence.spec | 20 ++------------------ 3 files changed, 11 insertions(+), 28 deletions(-) diff --git a/Makefile b/Makefile index e7e905289c19..f698e8e3e5db 100644 --- a/Makefile +++ b/Makefile @@ -38,12 +38,11 @@ docs/html/%.html: docs/%.asciidoc html/pfappserver/root/static/doc: make html - mkdir html/pfappserver/root/static/doc - mkdir html/pfappserver/root/static/images - cp -a docs/html/* html/pfappserver/root/static/doc - cp -a docs/images/* html/pfappserver/root/static/images + mkdir -p html/pfappserver/root/static/doc/images + cp -a docs/*.html html/pfappserver/root/static/doc + cp -a docs/images/* html/pfappserver/root/static/doc/images -docs/html/index.js: $(HTML) +docs/index.js: $(HTML) find $$(dirname "$@") -type f -iname '*.html' -and -not -iname '*template*' -printf "{\"name\":\"%f\", \"size\":%s, \"last_modifed\" : %T@}\n" | jq -s '{ items: [ .[] | {name, size, last_modifed : (.last_modifed*1000 | floor)} ] }' > $@ .PHONY: images @@ -51,19 +50,19 @@ docs/html/index.js: $(HTML) images: @echo "install images dir and all subdirectories" for subdir in `find docs/images/* -type d -printf "%f\n"` ; do \ - install -d -m0755 $(DESTDIR)/usr/local/pf/html/pfappserver/root/static/images/$$subdir ; \ + install -d -m0755 $(DESTDIR)/usr/local/pf/html/pfappserver/root/static/doc/images/$$subdir ; \ for img in `find docs/images/$$subdir -type f`; do \ - install -m0644 $$img $(DESTDIR)/usr/local/pf/html/pfappserver/root/static/images/$$subdir ; \ + install -m0644 $$img $(DESTDIR)/usr/local/pf/html/pfappserver/root/static/doc/images/$$subdir ; \ done \ done @echo "install only images at depth0 in images/ directory" for img in `find docs/images/* -maxdepth 0 -type f`; do \ - install -m0644 $$img $(DESTDIR)/usr/local/pf/html/pfappserver/root/static/images/ ; \ + install -m0644 $$img $(DESTDIR)/usr/local/pf/html/pfappserver/root/static/doc/images/ ; \ done .PHONY: html -html: $(HTML) docs/html/index.js +html: $(HTML) docs/index.js pfcmd.help: /usr/local/pf/bin/pfcmd help > docs/installation/pfcmd.help diff --git a/debian/rules b/debian/rules index 5bd7e00b26b3..997b692af2dc 100755 --- a/debian/rules +++ b/debian/rules @@ -171,7 +171,7 @@ install: build make html # install html and images dirs in pfappserver for embedded doc install -d -m0755 $(CURDIR)/debian/packetfence-doc$(PREFIX)/$(NAME)/html/pfappserver/root/static/doc - for i in `find "docs/html" "(" -name "*.html" -or -iname "*.js" ")" -type f`; do \ + for i in `find "docs" "(" -name "*.html" -or -iname "*.js" ")" -type f`; do \ install -m0644 $$i $(CURDIR)/debian/packetfence-doc$(PREFIX)/$(NAME)/html/pfappserver/root/static/doc/; \ done # images diff --git a/rpm/packetfence.spec b/rpm/packetfence.spec index 3adf485cd3bc..94a6ef8af55f 100644 --- a/rpm/packetfence.spec +++ b/rpm/packetfence.spec @@ -29,7 +29,7 @@ BuildRequires: gettext, httpd, ipset-devel, pkgconfig, jq BuildRequires: libmnl-devel, %endif %if 0%{?rhel} == 7 -BuildRequires: asciidoc >= 8.6.2, fop, libxslt, docbook-style-xsl, xalan-j2 +BuildRequires: asciidoc >= 8.6.2 %endif BuildRequires: ruby, rubygems BuildRequires: nodejs >= 12.0 @@ -327,22 +327,8 @@ for TRANSLATION in de en es fr he_IL it nl pl_PL pt_BR no; do done %if %{builddoc} == 1 - # generating custom XSL for titlepage - xsltproc -o docs/docbook/xsl/titlepage-fo.xsl \ - /usr/share/sgml/docbook/xsl-stylesheets/template/titlepage.xsl \ - docs/docbook/xsl/titlepage-fo.xml # admin, network device config, devel and ZEN install guides - for GUIDE in $(ls docs/PacketFence*.asciidoc | xargs -n1 -I'{}' basename '{}' .asciidoc) ;do - asciidoc -a docinfo2 -b docbook -d book \ - -o docs/docbook/$GUIDE.docbook \ - docs/$GUIDE.asciidoc - xsltproc -o docs/docbook/$GUIDE.fo \ - docs/docbook/xsl/packetfence-fo.xsl \ - docs/docbook/$GUIDE.docbook - fop -c docs/fonts/fop-config.xml \ - docs/docbook/$GUIDE.fo \ - -pdf docs/$GUIDE.pdf - done + %{__make} html %endif # Portal javascript/css @@ -494,7 +480,6 @@ cp -r ChangeLog %{buildroot}/usr/local/pf/ cp -r COPYING %{buildroot}/usr/local/pf/ cp -r db %{buildroot}/usr/local/pf/ cp -r docs %{buildroot}/usr/local/pf/ -rm -rf %{buildroot}/usr/local/pf/docs/docbook rm -rf %{buildroot}/usr/local/pf/docs/fonts rm -rf %{buildroot}/usr/local/pf/docs/images rm -rf %{buildroot}/usr/local/pf/docs/api @@ -1135,7 +1120,6 @@ fi %exclude /usr/local/pf/docs/README.asciidoc %if %{builddoc} == 1 %doc /usr/local/pf/docs/*.pdf -%exclude /usr/local/pf/docs/*.fo %endif ### html dir From 8e67abeb7637f1d21c7c8f972979c13112f4d230 Mon Sep 17 00:00:00 2001 From: Francis Lachapelle <flachapelle@inverse.ca> Date: Fri, 6 Nov 2020 20:11:38 -0500 Subject: [PATCH 03/12] doc: update docs/README for new tools --- docs/README.asciidoc | 81 +++++--------------------------------------- 1 file changed, 9 insertions(+), 72 deletions(-) diff --git a/docs/README.asciidoc b/docs/README.asciidoc index ee21db31ddf3..387ef8c90874 100644 --- a/docs/README.asciidoc +++ b/docs/README.asciidoc @@ -1,14 +1,11 @@ -Documentation README -==================== += Documentation README The documentation of PacketFence is formatted in http://www.methods.co.nz/asciidoc/[AsciiDoc]. To convert the documentation to the PDF or HTML format, you need various tools: -* asciidoc (.asciidoc to .docbook) -* xsltproc (.docbook to .fo) -* fop (.fo to .pdf) -* asciidoctor (.docbook to .html) +* asciidoctor (.asciidoc to .html) +* asciidoctor-pdf (.asciidoc to .pdf) The Makefile at the root of the repository will call those tools: @@ -20,76 +17,16 @@ The Makefile at the root of the repository will call those tools: make html -Troubleshooting ---------------- +== Troubleshooting -Making it work on RHEL5 / CentOS 5 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Making it work on RHEL7 / CentOS 7 -Turns out this is quite tricky and unfortunately doesn't yield the best results. +. If you are not using the RHN Subscription Management from Red Hat you need to enable the optional channel by running the following as root: -. First make sure you have rpmforge repository enabled. If you don't have it, see the Admin guide, it is covered there. -. Install jpackage repository + subscription-manager repos --enable rhel-7-server-optional-rpms - # yum install jpackage-release - # wget http://www.jpackage.org/jpackage50.repo - # mv jpackage50.repo /etc/yum.repos.d/jpackage50.repo - -. Edit `/etc/yum.repos.d/jpackage50.repo` and enable the generic and rhel repos. - -. Install the tools - - # yum install xmlgraphics-fop libxslt asciidoc - -. If you are bitten by 'Missing Dependency: /usr/bin/rebuild-security-providers - is needed by package' install http://plone.lucidsolutions.co.nz/linux/centos/jpackage-jpackage-utils-compatibility-for-centos-5.x[RPM provided here]. - - # rpm -Uvh http://plone.lucidsolutions.co.nz/linux/centos/images/jpackage-utils-compat-el5-0.0.1-1.noarch.rpm - -. Second attempt to install the tools - - # yum install xmlgraphics-fop libxslt asciidoc - -. Patch xmlgraphics-fop - - patch -p0 < docs/docbook/xmlgraphics-fop-centos5.patch - -. Create the appropriate symlink - - # ln -s /usr/bin/xmlgraphics-fop /usr/bin/fop - -. You are good to go! - - -CentOS 6 / RHEL6 / Fedora: Could not compile stylesheet -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Getting an error similar to: - - Compiler warnings: - file:/usr/share/sgml/docbook/xsl-stylesheets/fo/table.xsl: line 451: Attribute 'border-start-style' outside of element. - file:/usr/share/sgml/docbook/xsl-stylesheets/fo/table.xsl: line 452: Attribute 'border-end-style' outside of element. - file:/usr/share/sgml/docbook/xsl-stylesheets/fo/table.xsl: line 453: Attribute 'border-top-style' outside of element. - file:/usr/share/sgml/docbook/xsl-stylesheets/fo/table.xsl: line 454: Attribute 'border-bottom-style' outside of element. - file:/usr/share/sgml/docbook/xsl-stylesheets/fo/index.xsl: line 351: Attribute 'rx:key' outside of element. - ERROR: 'The first argument to the non-static Java function 'insertCallouts' is not a valid object reference.' - FATAL ERROR: 'Could not compile stylesheet' - Jan 17, 2012 9:13:28 PM org.apache.fop.cli.Main startFOP - SEVERE: Exception - org.apache.fop.apps.FOPException: Could not compile stylesheet - ... - -Try patching your `/usr/bin/fop` with `docs/docbook/fop-centos6.patch`: - - patch -p0 < docs/docbook/fop-centos6.patch - - -CentOS 6 / RHEL6 / Fedora: Output is not the same -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -You are probably not running asciidoc >= 8.6.2. Install from rpmforge-extras: - - yum install --enablerepo=rpmforge-extras asciidoc +. Install asciidoc + yum install asciidoc // vim: set syntax=asciidoc tabstop=2 shiftwidth=2 expandtab: From 5f55d4ef5ea552e210fefefa7de1b54f5f58315c Mon Sep 17 00:00:00 2001 From: nqb <nqb+git@azyx.fr> Date: Wed, 23 Dec 2020 08:34:30 +0100 Subject: [PATCH 04/12] [docs] fix minor issues --- .gitignore | 4 ++-- Makefile | 8 ++++---- debian/rules | 2 +- docs/PacketFence_Developers_Guide.asciidoc | 3 ++- ...ence_Network_Devices_Configuration_Guide.asciidoc | 5 ----- docs/developer/documentation_info.asciidoc | 12 ++++++------ rpm/packetfence.spec | 4 ++-- 7 files changed, 17 insertions(+), 21 deletions(-) diff --git a/.gitignore b/.gitignore index eaea26578b4b..4a397592b532 100644 --- a/.gitignore +++ b/.gitignore @@ -232,8 +232,8 @@ docs/*.fo docs/docbook/xsl/import-fo.xsl docs/docbook/xsl/titlepage-fo.xsl docs/docbook/*.docbook -docs/html/*.html -docs/html/index.js +docs/*.html +docs/index.js # trap stats graphs # TODO we should move them under var/ diff --git a/Makefile b/Makefile index f698e8e3e5db..6cb45b12681e 100644 --- a/Makefile +++ b/Makefile @@ -14,7 +14,7 @@ ASCIIDOCS := $(notdir $(wildcard docs/PacketFence_*.asciidoc)) PDFS = $(patsubst %.asciidoc,docs/%.pdf, $(ASCIIDOCS)) clean: - rm -f docs/html/*.html docs/*.pdf + rm -f docs/*.html docs/*.pdf docs/%.pdf: docs/%.asciidoc asciidoctor-pdf \ @@ -26,12 +26,12 @@ docs/%.pdf: docs/%.asciidoc pdf: $(PDFS) -HTML = $(patsubst %.asciidoc,docs/html/%.html, $(ASCIIDOCS)) +HTML = $(patsubst %.asciidoc,docs/%.html, $(ASCIIDOCS)) -docs/html/%.html: docs/%.asciidoc +docs/%.html: docs/%.asciidoc asciidoctor \ -n \ - -r ./docs/html/asciidoctor-html.rb \ + -r ./docs/asciidoctor-html.rb \ -a stylesdir=../html/pfappserver/root/static.alt/dist/css \ -a stylesheet=$(notdir $(wildcard ./html/pfappserver/root/static.alt/dist/css/app*.css)) \ $< diff --git a/debian/rules b/debian/rules index 997b692af2dc..07b7add6ce07 100755 --- a/debian/rules +++ b/debian/rules @@ -169,7 +169,7 @@ install: build # Documentation make html - # install html and images dirs in pfappserver for embedded doc + # install html in pfappserver for embedded doc install -d -m0755 $(CURDIR)/debian/packetfence-doc$(PREFIX)/$(NAME)/html/pfappserver/root/static/doc for i in `find "docs" "(" -name "*.html" -or -iname "*.js" ")" -type f`; do \ install -m0644 $$i $(CURDIR)/debian/packetfence-doc$(PREFIX)/$(NAME)/html/pfappserver/root/static/doc/; \ diff --git a/docs/PacketFence_Developers_Guide.asciidoc b/docs/PacketFence_Developers_Guide.asciidoc index 84325b312d24..756edb84b570 100644 --- a/docs/PacketFence_Developers_Guide.asciidoc +++ b/docs/PacketFence_Developers_Guide.asciidoc @@ -9,7 +9,8 @@ //// include::includes/global-attributes.asciidoc[] -== About this Guide + +== About this Guide This guide will help you modifying PacketFence to your particular needs. It also contains information on how to add support for new switches. diff --git a/docs/PacketFence_Network_Devices_Configuration_Guide.asciidoc b/docs/PacketFence_Network_Devices_Configuration_Guide.asciidoc index 1c2cf8f09e41..3cca55b31428 100644 --- a/docs/PacketFence_Network_Devices_Configuration_Guide.asciidoc +++ b/docs/PacketFence_Network_Devices_Configuration_Guide.asciidoc @@ -1,9 +1,4 @@ = Network Devices Configuration Guide -// to display images directly on GitHub -ifdef::env-github[] -:imagesdir: https://github.com/inverse-inc/packetfence/tree/devel/docs/images -endif::[] - //// This file is part of the PacketFence project. diff --git a/docs/developer/documentation_info.asciidoc b/docs/developer/documentation_info.asciidoc index d22aed8cd681..cbb7a78603d6 100644 --- a/docs/developer/documentation_info.asciidoc +++ b/docs/developer/documentation_info.asciidoc @@ -210,19 +210,19 @@ a|Navigate to _Configuration -> Policies and Access Control_ a| .... -image::image.png[width=25px] +image::pf-logo.png[width=25px] .... -a| image::image.png[width=25px] +a| image::pf-logo.png[width=25px] | Block Image a| .... -.Tux -image::image.png[width=100px] +.PacketFence +image::pf-logo.png[width=25px] .... -a| .Tux -image::image.png[width=100px] +a| .PacketFence +image::pf-logo.png[width=25px] |Inline operations and user input diff --git a/rpm/packetfence.spec b/rpm/packetfence.spec index 94a6ef8af55f..36685e3f40e6 100644 --- a/rpm/packetfence.spec +++ b/rpm/packetfence.spec @@ -492,9 +492,9 @@ rm -rf %{buildroot}/usr/local/pf/docs/api # install html directory %{__make} DESTDIR=%{buildroot} html_install -# install html and images dirs in pfappserver for embedded doc +# install html in pfappserver for embedded doc %{__install} -d -m0755 %{buildroot}/usr/local/pf/html/pfappserver/root/static/doc -for i in `find docs/html "(" -name "*.html" -or -name "*.js" ")" -type f`; do \ +for i in `find docs "(" -name "*.html" -or -name "*.js" ")" -type f`; do \ %{__install} -m0644 $i %{buildroot}/usr/local/pf/html/pfappserver/root/static/doc/; \ done From 9f6fbdbe45911b00a87e2758a6ba1aa3a6276183 Mon Sep 17 00:00:00 2001 From: Francis Lachapelle <flachapelle@inverse.ca> Date: Tue, 12 Jan 2021 21:37:03 -0500 Subject: [PATCH 05/12] fix(doc): cleanup docs/README --- docs/README.asciidoc | 16 ++-------------- 1 file changed, 2 insertions(+), 14 deletions(-) diff --git a/docs/README.asciidoc b/docs/README.asciidoc index 387ef8c90874..be08ea1e1d6e 100644 --- a/docs/README.asciidoc +++ b/docs/README.asciidoc @@ -4,8 +4,8 @@ The documentation of PacketFence is formatted in http://www.methods.co.nz/asciid To convert the documentation to the PDF or HTML format, you need various tools: -* asciidoctor (.asciidoc to .html) -* asciidoctor-pdf (.asciidoc to .pdf) +* [asciidoctor](https://asciidoctor.org/) (.asciidoc to .html) +* [asciidoctor-pdf](https://asciidoctor.org/docs/asciidoctor-pdf/) (.asciidoc to .pdf) The Makefile at the root of the repository will call those tools: @@ -17,16 +17,4 @@ The Makefile at the root of the repository will call those tools: make html -== Troubleshooting - -=== Making it work on RHEL7 / CentOS 7 - -. If you are not using the RHN Subscription Management from Red Hat you need to enable the optional channel by running the following as root: - - subscription-manager repos --enable rhel-7-server-optional-rpms - -. Install asciidoc - - yum install asciidoc - // vim: set syntax=asciidoc tabstop=2 shiftwidth=2 expandtab: From 48f69ceb13e0350a681603df05c1fe61ff063309 Mon Sep 17 00:00:00 2001 From: Francis Lachapelle <flachapelle@inverse.ca> Date: Tue, 12 Jan 2021 21:37:35 -0500 Subject: [PATCH 06/12] chore(rpm): remove dependency to asciidoc --- rpm/packetfence.spec | 3 --- 1 file changed, 3 deletions(-) diff --git a/rpm/packetfence.spec b/rpm/packetfence.spec index 36685e3f40e6..d723e5832cf1 100644 --- a/rpm/packetfence.spec +++ b/rpm/packetfence.spec @@ -28,9 +28,6 @@ BuildRequires: gettext, httpd, ipset-devel, pkgconfig, jq %if 0%{?rhel} == 8 BuildRequires: libmnl-devel, %endif -%if 0%{?rhel} == 7 -BuildRequires: asciidoc >= 8.6.2 -%endif BuildRequires: ruby, rubygems BuildRequires: nodejs >= 12.0 BuildRequires: gcc From 4850719c9478f9e44f1c81d0351b9b87692662cc Mon Sep 17 00:00:00 2001 From: Francis Lachapelle <flachapelle@inverse.ca> Date: Tue, 12 Jan 2021 21:38:19 -0500 Subject: [PATCH 07/12] chore: define dynamic attributes when building doc files --- Makefile | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/Makefile b/Makefile index 6cb45b12681e..b37e94d705a7 100644 --- a/Makefile +++ b/Makefile @@ -20,6 +20,8 @@ docs/%.pdf: docs/%.asciidoc asciidoctor-pdf \ -a pdf-theme=docs/asciidoctor-pdf-theme.yml \ -a pdf-fontsdir=docs/fonts \ + -a release_version=`cat conf/pf-release | cut -d' ' -f 2` \ + -a release_month=`date +%B` \ $< .PHONY: pdf @@ -34,6 +36,8 @@ docs/%.html: docs/%.asciidoc -r ./docs/asciidoctor-html.rb \ -a stylesdir=../html/pfappserver/root/static.alt/dist/css \ -a stylesheet=$(notdir $(wildcard ./html/pfappserver/root/static.alt/dist/css/app*.css)) \ + -a release_version=`cat conf/pf-release | cut -d' ' -f 2` \ + -a release_month=`date +%B` \ $< html/pfappserver/root/static/doc: From 43c8c051426f5fd9eb070ae4fc89810fbf48f051 Mon Sep 17 00:00:00 2001 From: Francis Lachapelle <flachapelle@inverse.ca> Date: Tue, 12 Jan 2021 21:45:46 -0500 Subject: [PATCH 08/12] fix(doc): cleanup docs/README --- docs/README.asciidoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/README.asciidoc b/docs/README.asciidoc index be08ea1e1d6e..13e3a9d34737 100644 --- a/docs/README.asciidoc +++ b/docs/README.asciidoc @@ -4,8 +4,8 @@ The documentation of PacketFence is formatted in http://www.methods.co.nz/asciid To convert the documentation to the PDF or HTML format, you need various tools: -* [asciidoctor](https://asciidoctor.org/) (.asciidoc to .html) -* [asciidoctor-pdf](https://asciidoctor.org/docs/asciidoctor-pdf/) (.asciidoc to .pdf) +* https://asciidoctor.org/[asciidoctor] (.asciidoc to .html) +* https://asciidoctor.org/docs/asciidoctor-pdf/[asciidoctor-pdf] (.asciidoc to .pdf) The Makefile at the root of the repository will call those tools: From b6ab905ed692aa6efb474340d40a74e551c93a5e Mon Sep 17 00:00:00 2001 From: Francis Lachapelle <flachapelle@inverse.ca> Date: Tue, 12 Jan 2021 21:53:20 -0500 Subject: [PATCH 09/12] fix(doc): fix anchors of UPGRADE.asciidoc --- UPGRADE.asciidoc | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/UPGRADE.asciidoc b/UPGRADE.asciidoc index 89ddfe84da70..831d7288a29e 100644 --- a/UPGRADE.asciidoc +++ b/UPGRADE.asciidoc @@ -20,14 +20,14 @@ This guide covers procedures to upgrade PacketFence servers. === Other sources of information -<<PacketFence_Clustering_Guide.asciidoc#,Clustering Guide>>:: +<<{extra_path}PacketFence_Clustering_Guide.asciidoc#,Clustering Guide>>:: Covers installation in a clustered environment. -<<PacketFence_Developers_Guide.asciidoc#,Developer's Guide>>:: +<<{extra_path}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>>:: +<<{extra_path}PacketFence_Installation_Guide.asciidoc#,Installation Guide>>:: Covers installation and configuration of PacketFence. -<<PacketFence_Network_Devices_Configuration_Guide.asciidoc#,Network Devices Configuration Guide>>:: +<<{extra_path}PacketFence_Network_Devices_Configuration_Guide.asciidoc#,Network Devices Configuration Guide>>:: Covers switches, WiFi controllers and access points configuration. link:https://packetfence.org/news.html[PacketFence News] Covers noteworthy features, improvements and bug fixes by release. @@ -109,7 +109,7 @@ required to be done *BEFORE* the packages upgrades. ==== Clustered environment: specific procedure -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>> section. +Please refer to the <<{extra_path}PacketFence_Clustering_Guide.asciidoc#,PacketFence Clustering Guide>>, more specifically the <<{extra_path}PacketFence_Clustering_Guide.asciidoc#_performing_an_upgrade_on_a_cluster,Performing an upgrade on a cluster>> section. === Stop all PacketFence services @@ -275,8 +275,8 @@ NOTE: This step is optional In order to have Monit configuration upgraded, you need to: -. <<PacketFence_Installation_Guide.asciidoc#_generateregenerate_the_monit_configuration,Regenerate Monit configuration>> -. <<PacketFence_Installation_Guide.asciidoc#_enable_and_start_monit,Enable and start monit>> if you stopped it at beginning of upgrade +. <<{extra_path}PacketFence_Installation_Guide.asciidoc#_generateregenerate_the_monit_configuration,Regenerate Monit configuration>> +. <<{extra_path}PacketFence_Installation_Guide.asciidoc#_enable_and_start_monit,Enable and start monit>> if you stopped it at beginning of upgrade . Restart rsyslog: [source,bash] From 40415fee7978c6d498c42148cf4d618a6b080e29 Mon Sep 17 00:00:00 2001 From: Francis Lachapelle <flachapelle@inverse.ca> Date: Wed, 13 Jan 2021 09:43:42 -0500 Subject: [PATCH 10/12] chore: cleanup unused Makefile target --- Makefile | 6 ------ 1 file changed, 6 deletions(-) diff --git a/Makefile b/Makefile index b37e94d705a7..34ad3a76afab 100644 --- a/Makefile +++ b/Makefile @@ -40,12 +40,6 @@ docs/%.html: docs/%.asciidoc -a release_month=`date +%B` \ $< -html/pfappserver/root/static/doc: - make html - mkdir -p html/pfappserver/root/static/doc/images - cp -a docs/*.html html/pfappserver/root/static/doc - cp -a docs/images/* html/pfappserver/root/static/doc/images - docs/index.js: $(HTML) find $$(dirname "$@") -type f -iname '*.html' -and -not -iname '*template*' -printf "{\"name\":\"%f\", \"size\":%s, \"last_modifed\" : %T@}\n" | jq -s '{ items: [ .[] | {name, size, last_modifed : (.last_modifed*1000 | floor)} ] }' > $@ From c3401db9e5488b80a0c9042b697101e63c04c4b4 Mon Sep 17 00:00:00 2001 From: Francis Lachapelle <flachapelle@inverse.ca> Date: Wed, 13 Jan 2021 10:07:32 -0500 Subject: [PATCH 11/12] doc: move UPGRADE.asciidoc to docs/PacketFence_Upgrade_Guide.asciidoc --- README.md | 4 +- UPGRADE.asciidoc | 1434 ----------------------- debian/docs | 1 - docs/PacketFence_Upgrade_Guide.asciidoc | 1430 +++++++++++++++++++++- 4 files changed, 1431 insertions(+), 1438 deletions(-) delete mode 100644 UPGRADE.asciidoc mode change 120000 => 100644 docs/PacketFence_Upgrade_Guide.asciidoc diff --git a/README.md b/README.md index 8c865b59a266..8f4a2679d777 100644 --- a/README.md +++ b/README.md @@ -20,9 +20,9 @@ Follow the instructions provided in the [Administration Guide](https://packetfen ## More Information -Noteworthy changes since the last release see the [NEWS](https://github.com/inverse-inc/packetfence/blob/devel/NEWS.asciidoc) file. +Noteworthy changes since the last release see the [NEWS file](https://github.com/inverse-inc/packetfence/blob/devel/NEWS.asciidoc). -Upgrading? See the [UPGRADE](https://github.com/inverse-inc/packetfence/blob/devel/UPGRADE.asciidoc) file. +Upgrading? See the [Upgrade Guide](https://github.com/inverse-inc/packetfence/blob/devel/docs/PacketFence_Upgrade_Guide.asciidoc.asciidoc). For more details and developer visible changes see the [project's page on Github](https://github.com/inverse-inc/packetfence). diff --git a/UPGRADE.asciidoc b/UPGRADE.asciidoc deleted file mode 100644 index 831d7288a29e..000000000000 --- a/UPGRADE.asciidoc +++ /dev/null @@ -1,1434 +0,0 @@ -= PacketFence Upgrade Guide -//// - - This file is part of the PacketFence project. - - See docs/includes/global-attributes.asciidoc for authors, copyright and - license information. - -//// -// Fix includes on GitHub -:extra_path: -ifdef::env-github[] -:extra_path: docs/ -endif::[] -include::{extra_path}includes/global-attributes.asciidoc[] - -== About this Guide - -This guide covers procedures to upgrade PacketFence servers. - -=== Other sources of information - -<<{extra_path}PacketFence_Clustering_Guide.asciidoc#,Clustering Guide>>:: - Covers installation in a clustered environment. -<<{extra_path}PacketFence_Developers_Guide.asciidoc#,Developer's Guide>>:: - Covers API, captive portal customization, application code customizations and - instructions for supporting new equipment. -<<{extra_path}PacketFence_Installation_Guide.asciidoc#,Installation Guide>>:: - Covers installation and configuration of PacketFence. -<<{extra_path}PacketFence_Network_Devices_Configuration_Guide.asciidoc#,Network Devices Configuration Guide>>:: - Covers switches, WiFi controllers and access points configuration. -link: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 - -You need to have your MariaDB root password ready because several scripts will need it. - - -=== Database backup - - -Before making any changes to your database, ensure that you have a backup. -A complete database backup can be taken using this command: - -[source,bash] ----- -mysqldump --opt --routines -u root -p pf | gzip > /root/packetfence_db.sql.gz ----- - -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. - -It is also possible to simply backup the actual MySQL files themselves -- as long as the database is not currently running. -To do so, stop MySQL and then copy all files under /var/lib/mysql to a secure directory. - -=== PacketFence configurations and codebase backup - - -Taking a complete backup of your current installation is strongly recommended. -You can take a backup of the pf directory with the following command: - -[source,bash] ----- -tar -C /usr/local -czf /root/packetfence.tar.gz --exclude='pf/logs' --exclude='pf/var' --exclude='pf/.git' pf ----- - -=== Disable monit alerts (only if you have monit installed) - - -If `monit` is installed and running, shut it down with: - -[source,bash] ----- -systemctl stop monit -systemctl disable monit ----- - -== Upgrade procedure - -=== Steps - -A PacketFence upgrade consists of following steps: - -. stop all PacketFence services (see <<_stop_all_packetfence_services,Stop all PacketFence services>> section) -. preliminary step(s) to run before packages upgrades (see sections for your upgrade path) -. packages upgrades (see <<_packages_upgrades,Package upgrades>> section) -. maintenance patches (see <<_maintenance_patches,Maintenance patches>> section) -. configuration migration(s) (see sections for your upgrade path) -. database schema upgrade(s) (see sections for your upgrade path) -. restart all PacketFence services (see <<_restart_all_packetfence_services,Restart all PacketFence services>> section) -. regenerate Monit configuration (optional) (see <<_regenerate_monit_configuration,Regenerate Monit configuration>> section) - -Upgrade notes for a given upgrade path are cumulative. That is to say, if you -are upgrading from version 7.0 to version 9.0 you must apply in order all: - -. preliminary step(s) to run before packages upgrades -. configuration migration(s) -. database schema upgrade(s) - -in between the two versions. - -IMPORTANT: Before starting packages upgrades, make sure to go through (read) the upgrade -instructions specific to the upgrade path taken since some preliminary steps may be -required to be done *BEFORE* the packages upgrades. - -==== Clustered environment: specific procedure - -Please refer to the <<{extra_path}PacketFence_Clustering_Guide.asciidoc#,PacketFence Clustering Guide>>, more specifically the <<{extra_path}PacketFence_Clustering_Guide.asciidoc#_performing_an_upgrade_on_a_cluster,Performing an upgrade on a cluster>> section. - -=== Stop all PacketFence services - -It is recommended that you stop the currently running PacketFence services before proceeding any further. -To do so, run the following commands: - -[source,bash] ----- -/usr/local/pf/bin/pfcmd service pf stop -systemctl stop packetfence-config ----- - -==== Rebooting after services have been stopped - -If you reboot a standalone server or one server from a cluster after services -have been stopped, make sure you set the systemd target to `multi-user.target` -before rebooting: - -[source,bash] ----- -systemctl set-default multi-user.target ----- - -This will make sure your services don't start up after the reboot. - -Set it back to previous target after it boots up: - -.Cluster -[source,bash] ----- -systemctl set-default packetfence-cluster.target ----- - -.Standalone -[source,bash] ----- -systemctl set-default packetfence.target ----- - -=== Packages upgrades - -IMPORTANT: Again, before starting packages upgrades, make sure to go through (read) the upgrade -instructions specific to the upgrade path taken since some preliminary steps may be -required to be done *BEFORE* the packages upgrades. - -==== RHEL / CentOS based systems - -Run the following command to update PacketFence: - -[source,bash] ----- -yum update --enablerepo=packetfence ----- - -PacketFence, Fingerbank and all their dependencies should now be -upgraded. However, there may be extra steps required depending on the version -you are upgrading from. - -===== Upgrade to RHEL / CentOS 7.7 before 9.1.0 - -If you run a version prior to 9.1.0 and want to *only* upgrade your RHEL / -CentOS system to 7.7, you will need to perform the following preliminary steps -before you perform your OS update through [command]`yum`. - -.Disable `systemd-logind` service which is currently causing issues with the `systemctl isolate` command -[source,bash] ----- -/usr/bin/systemctl stop systemd-logind -/usr/bin/systemctl --now mask systemd-logind -/usr/bin/systemctl daemon-reload -/bin/bash -c "/usr/bin/systemctl status user-0.slice | /usr/bin/grep -E -o '─[0-9]+' | /usr/bin/sed 's/─//g' | /usr/bin/xargs -I{} /bin/bash -c '/usr/bin/kill -0 {} > /dev/null 2>/dev/null && /usr/bin/echo {} > /sys/fs/cgroup/systemd/tasks'" ----- - -These commands prevent disconnection issues while [command]`yum` is performing -the update. The last command ensures your current process is removed out of -the `user-0.slice`. - -.Get latest version of [package]`ipset` package from packetfence repository -[source,bash] ----- -yum update ipset ipset-libs --enablerepo=packetfence ----- - - -==== Debian based systems - -Run the following commands to update PacketFence: - -[source,bash] ----- -apt update -apt install packetfence ----- - -Since PacketFence heavily relies on Fingerbank, it is recommended to make sure you are running the latest version: - -[source,bash] ----- -apt install fingerbank ----- - -PacketFence and Fingerbank should now be upgraded. However, there may be extra -steps required depending on the version you are upgrading from. - -==== New versions of configuration files - -You should take care to review any changes to configuration files and merge them if required. - -===== RHEL / CentOS based systems - -To find out which configuration files have changed run following command: - -[source,bash] ----- -find /usr/local/pf -name \*.rpmnew ----- - -The list of files returned are the new versions shipped with PacketFence. -Compare them to your existing version and see if there are changes that should -be merged into your existing configuration. Then, once you are done make sure -to delete these files so that there is no confusion the next time you upgrade -PacketFence. - -===== Debian based systems - -Debian installation system should have interactively asked for existing -modified files. If you answer `No` to keep existing files in place, you can -find out which configuration files have changed by running following command: - -[source,bash] ----- -find /usr/local/pf -name "*.dpkg-dist" ----- - - -=== Maintenance patches - -After you completed all <<_packages_upgrades,package upgrades instructions>> -(including <<_new_versions_of_configuration_files,merge of new configuration files>>), you can apply maintenance patches by running: - -[source,bash] ----- -/usr/local/pf/addons/pf-maint.pl ----- - -=== Restart all PacketFence services - -Once all <<_steps,steps of upgrade procedure>> are completed, restart -`packetfence-config` and `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 restart ----- - -=== Regenerate Monit configuration - -NOTE: This step is optional - -In order to have Monit configuration upgraded, you need to: - -. <<{extra_path}PacketFence_Installation_Guide.asciidoc#_generateregenerate_the_monit_configuration,Regenerate Monit configuration>> -. <<{extra_path}PacketFence_Installation_Guide.asciidoc#_enable_and_start_monit,Enable and start monit>> if you stopped it at beginning of upgrade -. Restart rsyslog: - -[source,bash] ----- -systemctl restart rsyslog ----- - -== Upgrading from a version prior to 7.0.0 - - -NOTE: You cannot upgrade from CentOS 6 or Debian Wheezy to PacketFence 7.0 and above - -=== Debian upgrade - - -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 - - apt update - -Remove the MySQL 5.5 packages (do not purge them, as that would delete the database) - - dpkg -r --force-all mysql-client-5.5 mysql-common mysql-server mysql-server-5.5 mysql-server-core-5.5 libmysqlclient18 - -Install the newer Mariadb-10.1 packages - - apt install libmariadbclient18 libmysqlclient18 mariadb-common mariadb-server-10.1 galera-3 gawk mariadb-client-10.1 mariadb-server-core-10.1 rsync socat libmpfr4 mariadb-client-core-10.1 mysql-common - -Finally, upgrade the rest of the packages - - apt full-upgrade - -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. - -=== MariaDB upgrade (CentOS + RHEL only) - - -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. - - systemctl stop mariadb - systemctl stop packetfence-mariadb - -Then start a mysqld_safe process manually (this will start a background process) - - mkdir -p /var/run/mariadb - chown mysql: /var/run/mariadb - mysqld_safe --basedir=/usr & - -Then, execute the upgrade script and enter the root password when prompted - - mysql_upgrade -u root -p - -When done, kill the mysqld_safe process we started before the update, reattach to it and wait for it to exit - - kill %1 && fg - -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) - - systemctl start packetfence-mariadb - -=== 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 6.5 schema to 7.0. - -To upgrade the database schema, run the following command: - - mysql -u root -p pf -v < /usr/local/pf/db/upgrade-6.5.0-7.0.0.sql - -=== Systemd integration - - -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 should 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. - -=== Admin roles configuration - - -Given the portal profiles have now been renamed to connection profiles, you need to make sure any admin role that allowed portal profile Create/Read/Update/Delete operations is updated to be valid for connection profiles. - - cd /usr/local/pf - sed -i "s/PORTAL_PROFILE/CONNECTION_PROFILE/g" conf/adminroles.conf - -=== PacketFence configuration - - -Multiple parameters inside `pf.conf` have been renamed for better clarity. Execute the following in order to migrate the parameters. - - /usr/local/pf/addons/upgrade/to-7.0-pf-conf-changes.pl - -=== Maintenance configuration - - -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: - - /usr/local/pf/addons/upgrade/to-7.0-pf.conf-to-pfmon.conf.pl - -=== DHCP filters configuration - - -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: - - cd /usr/local/pf - sed -i "s/computer_name/computername/g" conf/dhcp_filters.conf - sed -i "s/DhcpFingerbank/Fingerbank/g" conf/dhcp_filters.conf - -=== Roles configuration - - -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: - - /usr/local/pf/addons/upgrade/to-7.0-roles-conf.pl - -NOTE: The roles still exist in the database like before (node_category table), but their source of truth is now in the configuration file. Should you remove a role manually from `roles.conf`, it will *not* be removed from the database unless you manually go delete it from the database. - -=== pfdetect configuration - - -New parameters have been introduced in `conf/pfdetect.conf`. Run the following script to migrate your configuration. - - /usr/local/pf/addons/upgrade/to-7.0-pfdetect-conf.pl - -=== LinkedIn Source changes - - -If you are using the LinkedIn OAuth2 source, a change has been made on their API, thus you will need to do the following: - - cd /usr/local/pf - sed -i "s/uas\/oauth2/oauth\/v2/g" conf/authentication.conf - - -=== Logging service - - -Since all logging now goes through rsyslog, if you had edited the logging configuration (e.g. to forward logs to a centralized syslog server) make sure 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. - -=== Redis Queue - - -Clear the redis queue to avoid old stale jobs from being processes. - - - systemctl start packetfence-redis_queue - redis-cli -p 6380 FLUSHALL - systemctl stop packetfence-redis_queue - -=== SSL certificates - - -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` needs to 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: - - # cd /usr/local/pf/ - # cat /path/to/your/server.crt /path/to/your/intermediates.crt /path/to/your/server.key > /usr/local/pf/conf/ssl/server.pem - -=== Running 7.0+ in a cluster - - -A complete re-visit of the database clustering stack was done in version 7.0. If you run your PacketFence installation in a cluster, make sure you read the following section. - -==== Active/Active clusters with Active/Passive DB (default before 7.0) - -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. - -===== Corosync adjustment - -Note that you can safely keep your existing 2-node cluster with Corosync/Pacemaker in place and things will work like before. -You will simply have to adjust your Corosync configuration so that MariaDB points to the packetfence-mariadb file instead of the mariadb unit. - - primitive MariaDB systemd:packetfence-mariadb \ - op start timeout=60s interval=0 \ - op stop timeout=60s interval=0 \ - op monitor interval=20s timeout=30s - -===== Disabling Galera cluster - -You must then disable the MariaDB Galera cluster as a replication mechanism as you will still be using DRBD. In order to do so, add the following in `/usr/local/pf/conf/pf.conf` - - [active_active] - galera_replication=disabled - -===== IP address bind - -You must also instruct packetfence-mariadb to bind to the management IP address of the server manually. - -In order to do so, replace the following section in `/usr/local/pf/conf/mariadb/mariadb.conf.tt`: - - [% IF server_ip.length %] - bind-address=[% server_ip %] - [% ELSE %] - skip-networking - bind-address= - [% END %] - -with: - bind-address=1.2.3.4 - -Where 1.2.3.4 is the management IP address of the server. - -===== Disable packetfence-mariadb on boot - -Like in previous versions where mariadb shouldn't have been started on boot, now you must ensure its replacement (packetfence-mariadb) doesn't start on boot. - - systemctl disable packetfence-mariadb - -*Enabling the packetfence-cluster target* - -Next, you must set the default target to packetfence-cluster: - - systemctl set-default packetfence-cluster.target - -==== Active/Active clusters with external DB - -No changes to your clustering stack is required when using an external database. - -==== Active/Passive clusters - - -CAUTION: You shouldn't be running active/passive clusters anymore. If you do, you're pretty much on your own for community support. Inverse provides professionnal services to help you maintain these clusters. If you intend to keep an active/passive cluster, we suggest you have deep knowledge of Corosync/Pacemaker and strong Linux skills. - -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 make sure 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. - - # systemctl set-default multi-user.target - -You should then change your Corosync configuration for MariaDB and PacketFence to the following: - - primitive MariaDB systemd:packetfence-mariadb \ - op start timeout=60s interval=0 \ - op stop timeout=60s interval=0 \ - op monitor interval=20s timeout=30s - primitive PacketFence systemd:packetfence \ - op start timeout=300s interval=0 \ - op stop timeout=300s interval=0 \ - op monitor interval=300s timeout=300s - -== Upgrading from a version prior to 7.1.0 - - -=== Multiple DNS servers per domain - - -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: - - sed -i.bak "s/^dns_server/dns_servers/g" /usr/local/pf/conf/domain.conf - -=== Add default values to new auth source parameters - - - /usr/local/pf/addons/upgrade/to-7.1-authentication-conf.pl - -=== Fix the Ubiquiti typo - - -In order to use the Ubiquiti switch module that has been renamed, run the following command: - - sed -i.bak "s/Ubiquity/Ubiquiti/g" /usr/local/pf/conf/switches.conf - -=== Instagram source changes - - -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]'. - -=== 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.0 schema to 7.1. - -To upgrade the database schema, run the following command: - - mysql -u root -p pf -v < /usr/local/pf/db/upgrade-7.0.0-7.1.0.sql - - -== Upgrading from a version prior to 7.2.0 - - -=== Ability to «pin» a domain DC - - -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: - - sticky_dc=* - -And then regenerate the domain configuration: - - /usr/local/pf/bin/pfcmd fixpermissions - /usr/local/pf/bin/pfcmd configreload hard - /usr/local/pf/bin/pfcmd generatedomainconfig - -=== Change to sponsor CC address - - -The CC address for sponsors is now BCC. In order to adjust the configuration, execute the following: - - cd /usr/local/pf - sed -i "s/sponsorship_cc/sponsorship_bcc/g" conf/authentication.conf - -=== Changes to authentication sources codebase - - -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 - - -=== 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.1 schema to 7.2. - -To upgrade the database schema, run the following command: - - mysql -u root -p pf -v < /usr/local/pf/db/upgrade-7.1.0-7.2.0.sql - -== Upgrading from a version prior to 7.3.0 - - -=== Device Registration - - -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 - -=== Changes to `authentication.conf` and `domain.conf` regarding realms and source matching - - -You have to run the following script to change the configuration: - - /usr/local/pf/addons/upgrade/to-7.3-authentication-conf.pl - -=== MariaDB database read-only mode - - -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.0). - - -=== 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.2 schema to 7.3. - -To upgrade the database schema, run the following command: - - mysql -u root -p pf -v < /usr/local/pf/db/upgrade-7.2.0-7.3.0.sql - -== Upgrading from a version prior to 7.4.0 - - -=== New LinkedIn domain list - - -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: - - www.linkedin.com,api.linkedin.com,*.licdn.comlatform.linkedin.com - -=== Portal redirection timer - - -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`. - -=== 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.3 schema to 7.4. - -To upgrade the database schema, run the following command: - - mysql -u root -p pf -v < /usr/local/pf/db/upgrade-7.3.0-7.4.0.sql - -Once completed, update the file /usr/local/pf/conf/currently-at to match the new release number (PacketFence 7.4.0). - -== Upgrading from a version prior to 8.0.0 - - -=== Realms upgrade - - -The way PacketFence detects whether or not it should strip the realm out of a 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 your configuration, you can use the following script which will 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 previous data is necessary. - -In order to do so, execute the following script: - - /usr/local/pf/addons/upgrade/to-8.0-fingerbank-db-data.pl - -*Necessary API key* - -Fingerbank doesn't release its signature database anymore and has moved to an API centric approach for device profiling. In order for device profiling to keep working on your installation, you must make sure that there is an API key configured for Fingerbank in your PacketFence installation. - -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 - -=== 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 X.Y.Z - -=== 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 X.X.X schema to X.Y.Z. - -To upgrade the database schema, run the following command: - -[source,bash] ----- -mysql -u root -p pf -v < /usr/local/pf/db/upgrade-X.X.X-X.Y.Z.sql ----- - -== Archived upgrade notes - -include::{extra_path}upgrade-notes/archived_upgrade_notes.asciidoc[] - -include::{extra_path}includes/additional-info.asciidoc[] - -include::{extra_path}includes/commercial-support.asciidoc[] - -include::{extra_path}includes/license.asciidoc[] - diff --git a/debian/docs b/debian/docs index b765d2566fd2..eda7a97552f9 100644 --- a/debian/docs +++ b/debian/docs @@ -4,5 +4,4 @@ README.md README.network-devices ChangeLog ChangeLog.old -UPGRADE.asciidoc UPGRADE.old diff --git a/docs/PacketFence_Upgrade_Guide.asciidoc b/docs/PacketFence_Upgrade_Guide.asciidoc deleted file mode 120000 index 9f72acfe0da8..000000000000 --- a/docs/PacketFence_Upgrade_Guide.asciidoc +++ /dev/null @@ -1 +0,0 @@ -../UPGRADE.asciidoc \ No newline at end of file diff --git a/docs/PacketFence_Upgrade_Guide.asciidoc b/docs/PacketFence_Upgrade_Guide.asciidoc new file mode 100644 index 000000000000..5c8828609850 --- /dev/null +++ b/docs/PacketFence_Upgrade_Guide.asciidoc @@ -0,0 +1,1429 @@ += 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. +link: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 + +You need to have your MariaDB root password ready because several scripts will need it. + + +=== Database backup + + +Before making any changes to your database, ensure that you have a backup. +A complete database backup can be taken using this command: + +[source,bash] +---- +mysqldump --opt --routines -u root -p pf | gzip > /root/packetfence_db.sql.gz +---- + +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. + +It is also possible to simply backup the actual MySQL files themselves -- as long as the database is not currently running. +To do so, stop MySQL and then copy all files under /var/lib/mysql to a secure directory. + +=== PacketFence configurations and codebase backup + + +Taking a complete backup of your current installation is strongly recommended. +You can take a backup of the pf directory with the following command: + +[source,bash] +---- +tar -C /usr/local -czf /root/packetfence.tar.gz --exclude='pf/logs' --exclude='pf/var' --exclude='pf/.git' pf +---- + +=== Disable monit alerts (only if you have monit installed) + + +If `monit` is installed and running, shut it down with: + +[source,bash] +---- +systemctl stop monit +systemctl disable monit +---- + +== Upgrade procedure + +=== Steps + +A PacketFence upgrade consists of following steps: + +. stop all PacketFence services (see <<_stop_all_packetfence_services,Stop all PacketFence services>> section) +. preliminary step(s) to run before packages upgrades (see sections for your upgrade path) +. packages upgrades (see <<_packages_upgrades,Package upgrades>> section) +. maintenance patches (see <<_maintenance_patches,Maintenance patches>> section) +. configuration migration(s) (see sections for your upgrade path) +. database schema upgrade(s) (see sections for your upgrade path) +. restart all PacketFence services (see <<_restart_all_packetfence_services,Restart all PacketFence services>> section) +. regenerate Monit configuration (optional) (see <<_regenerate_monit_configuration,Regenerate Monit configuration>> section) + +Upgrade notes for a given upgrade path are cumulative. That is to say, if you +are upgrading from version 7.0 to version 9.0 you must apply in order all: + +. preliminary step(s) to run before packages upgrades +. configuration migration(s) +. database schema upgrade(s) + +in between the two versions. + +IMPORTANT: Before starting packages upgrades, make sure to go through (read) the upgrade +instructions specific to the upgrade path taken since some preliminary steps may be +required to be done *BEFORE* the packages upgrades. + +==== Clustered environment: specific procedure + +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>> section. + +=== Stop all PacketFence services + +It is recommended that you stop the currently running PacketFence services before proceeding any further. +To do so, run the following commands: + +[source,bash] +---- +/usr/local/pf/bin/pfcmd service pf stop +systemctl stop packetfence-config +---- + +==== Rebooting after services have been stopped + +If you reboot a standalone server or one server from a cluster after services +have been stopped, make sure you set the systemd target to `multi-user.target` +before rebooting: + +[source,bash] +---- +systemctl set-default multi-user.target +---- + +This will make sure your services don't start up after the reboot. + +Set it back to previous target after it boots up: + +.Cluster +[source,bash] +---- +systemctl set-default packetfence-cluster.target +---- + +.Standalone +[source,bash] +---- +systemctl set-default packetfence.target +---- + +=== Packages upgrades + +IMPORTANT: Again, before starting packages upgrades, make sure to go through (read) the upgrade +instructions specific to the upgrade path taken since some preliminary steps may be +required to be done *BEFORE* the packages upgrades. + +==== RHEL / CentOS based systems + +Run the following command to update PacketFence: + +[source,bash] +---- +yum update --enablerepo=packetfence +---- + +PacketFence, Fingerbank and all their dependencies should now be +upgraded. However, there may be extra steps required depending on the version +you are upgrading from. + +===== Upgrade to RHEL / CentOS 7.7 before 9.1.0 + +If you run a version prior to 9.1.0 and want to *only* upgrade your RHEL / +CentOS system to 7.7, you will need to perform the following preliminary steps +before you perform your OS update through [command]`yum`. + +.Disable `systemd-logind` service which is currently causing issues with the `systemctl isolate` command +[source,bash] +---- +/usr/bin/systemctl stop systemd-logind +/usr/bin/systemctl --now mask systemd-logind +/usr/bin/systemctl daemon-reload +/bin/bash -c "/usr/bin/systemctl status user-0.slice | /usr/bin/grep -E -o '─[0-9]+' | /usr/bin/sed 's/─//g' | /usr/bin/xargs -I{} /bin/bash -c '/usr/bin/kill -0 {} > /dev/null 2>/dev/null && /usr/bin/echo {} > /sys/fs/cgroup/systemd/tasks'" +---- + +These commands prevent disconnection issues while [command]`yum` is performing +the update. The last command ensures your current process is removed out of +the `user-0.slice`. + +.Get latest version of [package]`ipset` package from packetfence repository +[source,bash] +---- +yum update ipset ipset-libs --enablerepo=packetfence +---- + + +==== Debian based systems + +Run the following commands to update PacketFence: + +[source,bash] +---- +apt update +apt install packetfence +---- + +Since PacketFence heavily relies on Fingerbank, it is recommended to make sure you are running the latest version: + +[source,bash] +---- +apt install fingerbank +---- + +PacketFence and Fingerbank should now be upgraded. However, there may be extra +steps required depending on the version you are upgrading from. + +==== New versions of configuration files + +You should take care to review any changes to configuration files and merge them if required. + +===== RHEL / CentOS based systems + +To find out which configuration files have changed run following command: + +[source,bash] +---- +find /usr/local/pf -name \*.rpmnew +---- + +The list of files returned are the new versions shipped with PacketFence. +Compare them to your existing version and see if there are changes that should +be merged into your existing configuration. Then, once you are done make sure +to delete these files so that there is no confusion the next time you upgrade +PacketFence. + +===== Debian based systems + +Debian installation system should have interactively asked for existing +modified files. If you answer `No` to keep existing files in place, you can +find out which configuration files have changed by running following command: + +[source,bash] +---- +find /usr/local/pf -name "*.dpkg-dist" +---- + + +=== Maintenance patches + +After you completed all <<_packages_upgrades,package upgrades instructions>> +(including <<_new_versions_of_configuration_files,merge of new configuration files>>), you can apply maintenance patches by running: + +[source,bash] +---- +/usr/local/pf/addons/pf-maint.pl +---- + +=== Restart all PacketFence services + +Once all <<_steps,steps of upgrade procedure>> are completed, restart +`packetfence-config` and `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 restart +---- + +=== Regenerate Monit configuration + +NOTE: This step is optional + +In order to have Monit configuration upgraded, you need to: + +. <<PacketFence_Installation_Guide.asciidoc#_generateregenerate_the_monit_configuration,Regenerate Monit configuration>> +. <<PacketFence_Installation_Guide.asciidoc#_enable_and_start_monit,Enable and start monit>> if you stopped it at beginning of upgrade +. Restart rsyslog: + +[source,bash] +---- +systemctl restart rsyslog +---- + +== Upgrading from a version prior to 7.0.0 + + +NOTE: You cannot upgrade from CentOS 6 or Debian Wheezy to PacketFence 7.0 and above + +=== Debian upgrade + + +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 + + apt update + +Remove the MySQL 5.5 packages (do not purge them, as that would delete the database) + + dpkg -r --force-all mysql-client-5.5 mysql-common mysql-server mysql-server-5.5 mysql-server-core-5.5 libmysqlclient18 + +Install the newer Mariadb-10.1 packages + + apt install libmariadbclient18 libmysqlclient18 mariadb-common mariadb-server-10.1 galera-3 gawk mariadb-client-10.1 mariadb-server-core-10.1 rsync socat libmpfr4 mariadb-client-core-10.1 mysql-common + +Finally, upgrade the rest of the packages + + apt full-upgrade + +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. + +=== MariaDB upgrade (CentOS + RHEL only) + + +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. + + systemctl stop mariadb + systemctl stop packetfence-mariadb + +Then start a mysqld_safe process manually (this will start a background process) + + mkdir -p /var/run/mariadb + chown mysql: /var/run/mariadb + mysqld_safe --basedir=/usr & + +Then, execute the upgrade script and enter the root password when prompted + + mysql_upgrade -u root -p + +When done, kill the mysqld_safe process we started before the update, reattach to it and wait for it to exit + + kill %1 && fg + +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) + + systemctl start packetfence-mariadb + +=== 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 6.5 schema to 7.0. + +To upgrade the database schema, run the following command: + + mysql -u root -p pf -v < /usr/local/pf/db/upgrade-6.5.0-7.0.0.sql + +=== Systemd integration + + +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 should 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. + +=== Admin roles configuration + + +Given the portal profiles have now been renamed to connection profiles, you need to make sure any admin role that allowed portal profile Create/Read/Update/Delete operations is updated to be valid for connection profiles. + + cd /usr/local/pf + sed -i "s/PORTAL_PROFILE/CONNECTION_PROFILE/g" conf/adminroles.conf + +=== PacketFence configuration + + +Multiple parameters inside `pf.conf` have been renamed for better clarity. Execute the following in order to migrate the parameters. + + /usr/local/pf/addons/upgrade/to-7.0-pf-conf-changes.pl + +=== Maintenance configuration + + +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: + + /usr/local/pf/addons/upgrade/to-7.0-pf.conf-to-pfmon.conf.pl + +=== DHCP filters configuration + + +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: + + cd /usr/local/pf + sed -i "s/computer_name/computername/g" conf/dhcp_filters.conf + sed -i "s/DhcpFingerbank/Fingerbank/g" conf/dhcp_filters.conf + +=== Roles configuration + + +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: + + /usr/local/pf/addons/upgrade/to-7.0-roles-conf.pl + +NOTE: The roles still exist in the database like before (node_category table), but their source of truth is now in the configuration file. Should you remove a role manually from `roles.conf`, it will *not* be removed from the database unless you manually go delete it from the database. + +=== pfdetect configuration + + +New parameters have been introduced in `conf/pfdetect.conf`. Run the following script to migrate your configuration. + + /usr/local/pf/addons/upgrade/to-7.0-pfdetect-conf.pl + +=== LinkedIn Source changes + + +If you are using the LinkedIn OAuth2 source, a change has been made on their API, thus you will need to do the following: + + cd /usr/local/pf + sed -i "s/uas\/oauth2/oauth\/v2/g" conf/authentication.conf + + +=== Logging service + + +Since all logging now goes through rsyslog, if you had edited the logging configuration (e.g. to forward logs to a centralized syslog server) make sure 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. + +=== Redis Queue + + +Clear the redis queue to avoid old stale jobs from being processes. + + + systemctl start packetfence-redis_queue + redis-cli -p 6380 FLUSHALL + systemctl stop packetfence-redis_queue + +=== SSL certificates + + +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` needs to 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: + + # cd /usr/local/pf/ + # cat /path/to/your/server.crt /path/to/your/intermediates.crt /path/to/your/server.key > /usr/local/pf/conf/ssl/server.pem + +=== Running 7.0+ in a cluster + + +A complete re-visit of the database clustering stack was done in version 7.0. If you run your PacketFence installation in a cluster, make sure you read the following section. + +==== Active/Active clusters with Active/Passive DB (default before 7.0) + +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. + +===== Corosync adjustment + +Note that you can safely keep your existing 2-node cluster with Corosync/Pacemaker in place and things will work like before. +You will simply have to adjust your Corosync configuration so that MariaDB points to the packetfence-mariadb file instead of the mariadb unit. + + primitive MariaDB systemd:packetfence-mariadb \ + op start timeout=60s interval=0 \ + op stop timeout=60s interval=0 \ + op monitor interval=20s timeout=30s + +===== Disabling Galera cluster + +You must then disable the MariaDB Galera cluster as a replication mechanism as you will still be using DRBD. In order to do so, add the following in `/usr/local/pf/conf/pf.conf` + + [active_active] + galera_replication=disabled + +===== IP address bind + +You must also instruct packetfence-mariadb to bind to the management IP address of the server manually. + +In order to do so, replace the following section in `/usr/local/pf/conf/mariadb/mariadb.conf.tt`: + + [% IF server_ip.length %] + bind-address=[% server_ip %] + [% ELSE %] + skip-networking + bind-address= + [% END %] + +with: + bind-address=1.2.3.4 + +Where 1.2.3.4 is the management IP address of the server. + +===== Disable packetfence-mariadb on boot + +Like in previous versions where mariadb shouldn't have been started on boot, now you must ensure its replacement (packetfence-mariadb) doesn't start on boot. + + systemctl disable packetfence-mariadb + +*Enabling the packetfence-cluster target* + +Next, you must set the default target to packetfence-cluster: + + systemctl set-default packetfence-cluster.target + +==== Active/Active clusters with external DB + +No changes to your clustering stack is required when using an external database. + +==== Active/Passive clusters + + +CAUTION: You shouldn't be running active/passive clusters anymore. If you do, you're pretty much on your own for community support. Inverse provides professionnal services to help you maintain these clusters. If you intend to keep an active/passive cluster, we suggest you have deep knowledge of Corosync/Pacemaker and strong Linux skills. + +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 make sure 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. + + # systemctl set-default multi-user.target + +You should then change your Corosync configuration for MariaDB and PacketFence to the following: + + primitive MariaDB systemd:packetfence-mariadb \ + op start timeout=60s interval=0 \ + op stop timeout=60s interval=0 \ + op monitor interval=20s timeout=30s + primitive PacketFence systemd:packetfence \ + op start timeout=300s interval=0 \ + op stop timeout=300s interval=0 \ + op monitor interval=300s timeout=300s + +== Upgrading from a version prior to 7.1.0 + + +=== Multiple DNS servers per domain + + +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: + + sed -i.bak "s/^dns_server/dns_servers/g" /usr/local/pf/conf/domain.conf + +=== Add default values to new auth source parameters + + + /usr/local/pf/addons/upgrade/to-7.1-authentication-conf.pl + +=== Fix the Ubiquiti typo + + +In order to use the Ubiquiti switch module that has been renamed, run the following command: + + sed -i.bak "s/Ubiquity/Ubiquiti/g" /usr/local/pf/conf/switches.conf + +=== Instagram source changes + + +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]'. + +=== 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.0 schema to 7.1. + +To upgrade the database schema, run the following command: + + mysql -u root -p pf -v < /usr/local/pf/db/upgrade-7.0.0-7.1.0.sql + + +== Upgrading from a version prior to 7.2.0 + + +=== Ability to «pin» a domain DC + + +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: + + sticky_dc=* + +And then regenerate the domain configuration: + + /usr/local/pf/bin/pfcmd fixpermissions + /usr/local/pf/bin/pfcmd configreload hard + /usr/local/pf/bin/pfcmd generatedomainconfig + +=== Change to sponsor CC address + + +The CC address for sponsors is now BCC. In order to adjust the configuration, execute the following: + + cd /usr/local/pf + sed -i "s/sponsorship_cc/sponsorship_bcc/g" conf/authentication.conf + +=== Changes to authentication sources codebase + + +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 + + +=== 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.1 schema to 7.2. + +To upgrade the database schema, run the following command: + + mysql -u root -p pf -v < /usr/local/pf/db/upgrade-7.1.0-7.2.0.sql + +== Upgrading from a version prior to 7.3.0 + + +=== Device Registration + + +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 + +=== Changes to `authentication.conf` and `domain.conf` regarding realms and source matching + + +You have to run the following script to change the configuration: + + /usr/local/pf/addons/upgrade/to-7.3-authentication-conf.pl + +=== MariaDB database read-only mode + + +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.0). + + +=== 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.2 schema to 7.3. + +To upgrade the database schema, run the following command: + + mysql -u root -p pf -v < /usr/local/pf/db/upgrade-7.2.0-7.3.0.sql + +== Upgrading from a version prior to 7.4.0 + + +=== New LinkedIn domain list + + +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: + + www.linkedin.com,api.linkedin.com,*.licdn.comlatform.linkedin.com + +=== Portal redirection timer + + +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`. + +=== 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.3 schema to 7.4. + +To upgrade the database schema, run the following command: + + mysql -u root -p pf -v < /usr/local/pf/db/upgrade-7.3.0-7.4.0.sql + +Once completed, update the file /usr/local/pf/conf/currently-at to match the new release number (PacketFence 7.4.0). + +== Upgrading from a version prior to 8.0.0 + + +=== Realms upgrade + + +The way PacketFence detects whether or not it should strip the realm out of a 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 your configuration, you can use the following script which will 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 previous data is necessary. + +In order to do so, execute the following script: + + /usr/local/pf/addons/upgrade/to-8.0-fingerbank-db-data.pl + +*Necessary API key* + +Fingerbank doesn't release its signature database anymore and has moved to an API centric approach for device profiling. In order for device profiling to keep working on your installation, you must make sure that there is an API key configured for Fingerbank in your PacketFence installation. + +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 + +=== 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 X.Y.Z + +=== 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 X.X.X schema to X.Y.Z. + +To upgrade the database schema, run the following command: + +[source,bash] +---- +mysql -u root -p pf -v < /usr/local/pf/db/upgrade-X.X.X-X.Y.Z.sql +---- + +== Archived upgrade notes + +include::upgrade-notes/archived_upgrade_notes.asciidoc[] + +include::includes/additional-info.asciidoc[] + +include::includes/commercial-support.asciidoc[] + +include::includes/license.asciidoc[] + From 41d6acd6c139b426d0970ae28a402ea699c5cb28 Mon Sep 17 00:00:00 2001 From: Francis Lachapelle <flachapelle@inverse.ca> Date: Wed, 13 Jan 2021 10:08:33 -0500 Subject: [PATCH 12/12] chore(rpm): remove unused variable --- rpm/packetfence.spec | 11 ----------- 1 file changed, 11 deletions(-) diff --git a/rpm/packetfence.spec b/rpm/packetfence.spec index d723e5832cf1..f3d805694746 100644 --- a/rpm/packetfence.spec +++ b/rpm/packetfence.spec @@ -2,7 +2,6 @@ # Variables #============================================================================== # use 'global' variables (vs 'define' with local scope) -%global builddoc 0 %global perl_version 5.10.1 %global logfiles packetfence.log snmptrapd.log pfdetect pfcron security_event.log httpd.admin.audit.log %global logdir /usr/local/pf/logs @@ -323,11 +322,6 @@ for TRANSLATION in de en es fr he_IL it nl pl_PL pt_BR no; do --output-file conf/locale/$TRANSLATION/LC_MESSAGES/packetfence.mo done -%if %{builddoc} == 1 - # admin, network device config, devel and ZEN install guides - %{__make} html -%endif - # Portal javascript/css %{__make} -C html/common/ vendor %{__make} -C html/common light-dist @@ -504,7 +498,6 @@ cp -r NEWS.asciidoc %{buildroot}/usr/local/pf/ cp -r NEWS.old %{buildroot}/usr/local/pf/ cp -r README.md %{buildroot}/usr/local/pf/ cp -r README.network-devices %{buildroot}/usr/local/pf/ -cp -r UPGRADE.asciidoc %{buildroot}/usr/local/pf/ cp -r UPGRADE.old %{buildroot}/usr/local/pf/ # logfiles for LOG in %logfiles; do @@ -1115,9 +1108,6 @@ fi %dir /usr/local/pf/docs %doc /usr/local/pf/docs/* %exclude /usr/local/pf/docs/README.asciidoc -%if %{builddoc} == 1 -%doc /usr/local/pf/docs/*.pdf -%endif ### html dir # %%dir will add only html dir, not subdirectories or files @@ -1251,7 +1241,6 @@ fi %attr(0755, pf, pf) /usr/local/pf/sbin/pffilter %attr(0755, pf, pf) /usr/local/pf/sbin/winbindd-wrapper %attr(0755, pf, pf) /usr/local/pf/sbin/radsniff-wrapper -%doc /usr/local/pf/UPGRADE.asciidoc %doc /usr/local/pf/UPGRADE.old %dir /usr/local/pf/var %dir /usr/local/pf/var/conf