PacketFence Upgrade Guide
=========================

http://www.packetfence.org/

Notes on upgrading from an older release.

Upgrading from a version prior to 3.6.1
---------------------------------------

Database schema update
^^^^^^^^^^^^^^^^^^^^^^
New gaming devices registration add a default category. 
Make sure you run the following to update your schema EVEN IF YOU DON'T USE THAT FEATURE

mysql -u root -p pf -v < db/upgrade-3.5.0-3.6.1.sql

SSL certificate config file moved
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File has moved into `conf/httpd.conf.d`. Your modifications WILL NOT follow automatically, please
manually fix it.

Accounting modifier is now mandatory
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
When you create a bandwidth violation for accounting, the time modifier is now mandatory.  You need
to either use D,W,M, or Y.


Upgrading from a version prior to 3.6.0
---------------------------------------

Changes to VLAN assignement
^^^^^^^^^^^^^^^^^^^^^^^^^^^

The fetchVlanForNode (vlan.pm) has been changed to add the new Inline VLAN dynamic VLAN assignment code.
Same thing for the authorize (radius.pm).  You should review your custom code to reflect the changes.

Template files movement
^^^^^^^^^^^^^^^^^^^^^^^

Some templates were moved. Any custom changes should be re-made on the new
file locations.

* `html/captive-portal/templates/guest/register_guest.html` -> `html/admin/templates/register_guest.html`
* `html/captive-portal/templates/guest/mgmt_login.html` -> `html/admin/templates/login.html`

Changes to Web API
~~~~~~~~~~~~~~~~~~

NOTE: Remember, if you don't have custom extensions or customized templates
you don't have to worry about anything below.

Deprecations
^^^^^^^^^^^^

`pf::web::web_get_locale` moved into `pf::web::admin`. See <_i18n,I18N>
below for details.

`pf::web::_render_template` no longer exists. See below for details.

`pf::web::get_client_ip` was migrated into `pf::Portal::Session` and is
no longer available for public consumption.

All CGI style URLs (ex: `/cgi-bin/redir.cgi`) are now no longer supported.
They were first marked as deprecated in 3.0.

Apache config
^^^^^^^^^^^^^

Apache configuration was radically modified. Anyone with customizations will
need to re-apply them after an upgrade.

Core
^^^^

Variables meant for the consumption of the templates are now stored in the
Portal::Session->stash. Code in pf::web::custom should be updated to assign
to $portalSession->stash->... or (->stash(...)) instead of using $vars. It
implicitly passes more information to the templates including the new URL
constants (see below).

The `login.html` template was updated to consume the newly introduced URL 
constants. If you customized your code like generate_login_page then you
need to make sure to update it to use the stash mentionned above.

`_render_template` is now `render_template` and it no longer needs the
template vars hashref. It uses $portalSession's stash automatically.

All admin-related subs were moved out of `pf::web` and `pf::web::guest`
into `pf::web::admin`.

I18N
^^^^

Translation system initialization is now performed by Portal::Session. You
can get rid of the following lines from your custom code:

  setlocale( LC_MESSAGES, web_get_locale($cgi, $session) );
  bindtextdomain( "packetfence", "$conf_dir/locale" );
  textdomain("packetfence");

Changes to Guest API
~~~~~~~~~~~~~~~~~~~~

NOTE: Remember, if you don't have custom extensions or customized templates
you don't have to worry about anything below.

pf::web::guest::generate_selfregistration_page no longer takes a $post_uri
parameter. If you want to customize it, change post_uri in the guest.html
template.

$pf::web::guest::LOGIN_TEMPLATE was moved to $pf::web::LOGIN_TEMPLATE.
References should be updated.

`pf::web::guest`'s `generate_registration_page` was moved in `pf::web::admin`,
no longer takes a $post_uri parameter and was renamed generate_guestcreation_page.

`pf::web::guest`'s `validate_sponsor` now takes an instance of
pf::Portal::Session instead of $cgi and $session.

`pf::web::guest`'s `$REGISTRATION_CONFIRMATION_TEMPLATE` was dropped.

Several subroutines moved from `pf::web::guest` into `pf::web::admin`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* `valid_access_duration`
* `valid_arrival_date`
* `validate_registration` -> `validate_guest_creation`
* `validate_registration_multiple` -> `validate_guest_creation_multiple`
* `validate_registration_import` -> `validate_guest_import`
* `preregister` -> `create_guest`
* `preregister_multiple` -> `create_guest_multiple`
* `generate_registration_confirmation_page` -> `generate_guestcreation_confirmation_page`
* `import_csv`
* `generate_admin_login_page` -> `generate_login_page`
* `manager_authenticate` -> `authenticate`
* `generate_registration_page` -> `generate_guestcreation_page`

Switch configuration
~~~~~~~~~~~~~~~~~~~~

Switch 127.0.0.1 must be removed from the switches.conf

3750 vs 3750G
^^^^^^^^^^^^^

The introduction of the 3750G made us change the behavior of the 3750 module.
If you have a 3750G make sure to update your configuration from
`Cisco::Catalyst_3750` to `Cisco::Catalyst_3750G`. The old 3750 behaved like
a 3750G in RADIUS-based access mechanisms (MAC-Auth and 802.1X).

Changes to pf::SNMP API
~~~~~~~~~~~~~~~~~~~~~~~

After a few years marked as deprecated. `pf::SNMP.pm`'s `setIsolationVlan`,
`setRegistrationVlan` and `setNormalVlan` were removed.

.LLDP Support

LLDP discovery of VoIP phones has been improved and streamlined. Let us know
if you experience any regressions or if you have switches that support LLDP
that you would like to see supported.

.Modification to the sites-available / sites-enabled for FreeRADIUS configuration.

We standardize the way to work with these two directories in the way that files in sites-enabled
are symlinks of files in sites-available. This way, modifications to files are less error prone.
Make sure to copy files from sites-enabled to sites-available before updating to avoid losing any changes made to 
theses files. After the update, files that differs from originals will be saved as .rpmsave.


Upgrading from a version prior to 3.5.1
---------------------------------------

.Parser updates

Changes were made to the command parser. If you are using a packaged
distribution you have nothing to do. If you installed from source, you
will need to regenerate the precompiled grammar. Follow the instructions
in:

    perldoc /usr/local/pf/lib/pf/pfcmd/pfcmd.pm

.Deprecation advance notice: `pf::node`'s `node_view_with_fingerprint`

`node_view_with_fingerprint` will be deprecated somewhere in 2013. Please
migrate your custom code to the faster `node_attributes_with_fingerprint`.


Upgrading from a version prior to 3.5.0
---------------------------------------

----

    - Database schema update
    New accounting violations and other violation related stuff needed some modifications
    to the current database schema. Make sur you run the following to update
    you schema EVEN IF YOU DON'T USE THE FEATURE:
    mysql -u root -p pf -v < db/upgrade-3.3.0-3.5.0.sql

    - RADIUS configuration is now in the PacketFence directory.  You may need
    to import custom configuration from /etc/raddb to pf/raddb.  Note that
    we now generates radiusd.conf, eap.conf, and sql.conf based on templates in
    conf/. Especially important files to migrate would be packetfence.pm,
    packetfence-soh.pm, proxy.conf, clients.conf, users and modules/mschap.
    Additionally users running from source should make sure to migrate or create
    DH parameters (this is handled automatically by the packages):
    cd /usr/local/pf/raddb/certs; make dh

    - FreeRADIUS user radiusd changed to pf
    FreeRADIUS now runs as user `pf`. PEAP-MsCHAPv2 users will need to change
    the ownership of the /var/lib/samba/winbindd_privileged/ directory so that
    pf is the group owner. Other changes might be required based on your
    configuration.

    - Critical changes in FreeRADIUS watchdog
    addons/watchdog/freeradius-watchdog.sh was updated. The previous version
    of the watchdog on PacketFence 3.5.0 will simply kill radiusd and never
    restart it. Unfortunately that change was made after 3.5.0 was released
    so you need to get the latest watchdog from github:
    https://github.com/inverse-inc/packetfence/raw/stable/addons/watchdog/freeradius-watchdog.sh

    - Upgrade helper scripts
    Very basic upgrade scripts for 3.5 were created in addons/upgrade/. See 
    their POD doc for usage information:
    perldoc addons/upgrade/to-3.5-pf.conf.pl 

    - pf.conf interface gateway deprecated 
    The gateway=... parameters under every network interface is no longer 
    required. You will have to get rid of it (or run the above mentionned 
    upgrade helper script).

    - pf.conf's general.caching deprecated
    The caching=... parameter under [general] is no longer required. You 
    will have to get rid of it if you diverged from default configuration
    which was disabled (or run the above mentionned upgrade helper script).

    - Captive portal node status page removed
    We deprecated a never used feature: /status inside the captive portal
    who gave node information if the user was authenticated properly. This 
    made little sense since portal access is denied from users since a long
    time. This was a legacy from the deprecated ARP mode.

    - Captive portal variables consumption
    Captive portal generation methods now consume portalSession object rather than
    cgi, session and other variables. Please make sure to adapt your custom code (if needed)
    in lib/pf/web/custom.pm.

    - Nessus scan XMLRPC
    We made some changes in the way nessus scan is working.
    We directly use the policy on the server and you no longer have to declare
    nessus_clientfile in pf.conf.
    pf.conf's nessus_clientfile parameter has been dropped so make sure to 
    remove it (or run the upgrade helper script mentionned earlier).

    - Bandwidth accounting violation changes
    Triggers are no longer sliding windows but current day, week, month, 
    etc. instead. The trigger format changed. You should remove the digits
    between size and duration. For example: TOT20GB1M becomes TOT20GBM.
    
    - pf.conf's trapping.registration now enabled by default
    We changed this setting from disabled to enabled by default since we consider
    that registration is a whole part of the process. It is still possible to disable
    this setting by overriding it's default value in pf.conf.

    - dropping installation.pl and configurator.pl
    We dropped both the installation.pl and configurator.pl scripts in favor of the
    newly implemented web based configurator. Make sure to pay attention to the directives
    at the end of the package installation.

    - introduction of a new repository: OpenFusion
    The use of perl Catalyst as a web engine for the new web platform required the introduction
    of the OpenFusion repository. Make sure to take a quick look at the Administration Guide for
    integration of this new repository.

----

Upgrading from a version prior to 3.3.0
---------------------------------------

----

    - Database schema update
    New sponsored guest feature and max nodes per user per category support 
    required database changes. Make sure you run the following to update 
    your schema even if you don't use the feature:
    mysql -u root -p pf -v < db/upgrade-3.2.0-3.3.0.sql

    Warning: If you are actively using RADIUS accounting features, please
    note that the schema upgrade might take a while, we will create a new
    index on the radacct table.  Don't panic if it takes longer than usual!

    - Changes to the FreeRADIUS integration
    Due to a packaging glitch upgrading does not suffice to get updated files.
    To do so:
    # yum install packetfence-freeradius2
    # yum reinstall packetfence-freeradius2
    Note: Remember the --enablerepo=packetfence if you disabled the repo as 
    suggested in the admin guide.
    Then re-add your virtual IP in radiusd.conf (if any) and your webservice 
    user password into /etc/raddb/packetfence.pm. Also, make sure to merge 
    the .rpmnew and .rpmsave files.
 
    - new trigger types (no more scan type)
    The trigger type "Scan" has been removed to leave place to two new types 
    (Nessus and Openvas). Due to that change, modification to existing 
    violations.conf is required to change all existing "Scan" type to "Nessus".
    You can run the following command that will do the job. Make sure to backup
    your existing violations.conf file.
    /usr/bin/perl -p -i -e "s/Scan::/Nessus::/ig" /usr/local/pf/conf/violations.conf

    - guests_pre_registration renamed to guests_admin_registration
    Update your conf/pf.conf if you diverged from the default settings.

    - Cisco wireless de-authentication
    Cisco de-authentication now relies on RADIUS Disconnect-Request (RFC3576)
    instead of SNMP or Telnet/SSH. Make sure you have set radiusSecret in your
    conf/switches.conf and that RFC3576 support is properly enabled in your
    controller's AAA config (the default is enabled since IOS 5.x+). Also
    tightly firewalled environments will have to open up any port from 
    PacketFence up to port 3799 UDP to their the controllers.

    - Important changes to the inline mode
    We made some important changes to the way inline mode DNS is working.
    We introduced DNS DNAT translation so that users in inline VLAN receive 
    a valid external DNS server by DHCP but if are in an unregistered or 
    isolated state, iptables DNATs the DNS traffic to a local DNS server on 
    the PacketFence server (exactly as in a vlan mode).

    It is now important to change the previously recommended "disabled" 
    named setting to "enabled" in your conf/networks.conf for inline 
    interfaces. A warning message will come up on startup in case the setting
    is still set as disabled in an inline configuration. We also dropped a 
    configuration parameter, inline.portal_redirect, so make sure to update 
    your pf.conf accordingly. Lastly, the gateway parameter in your inline 
    VLAN in conf/networks.conf should represent PacketFence's IP in that VLAN.
    Don't hesitate to take a look at the revised configuration for the inline
    mode in the PacketFence Administration Guide page 17.

    - Email templates changed names
    Related to the above guest API changes were several template files renamed
     - emails-guest_registration.txt.tt -> emails-guest_preregistration.txt.tt
     - emails-guest_activation.txt.tt -> emails-guest_email_activation.txt.tt
     - emails-sponsor_activation.txt.tt -> 
       emails-guest_sponsor_activation.txt.tt

    - var/dhcpd/dhcpd.leases no longer provided by package
    The above file is no longer managed by our RPM package which means that 
    it's no longer overwritten by an empty file on upgrades. It is created on
    demand if required when PacketFence starts.

    - Web Authentication Modules API bump
    In order to support sponsored guests, we made changes to our Web Auth API.
    Make sure to integrate the isAllowedToSponsorGuests() sub in your 
    authentication modules and bump VERSION to 1.20. If you don't plan on 
    using the sponsored guests feature you can simply bump the API level.

    - Changes to Guest API
    Users with custom code will have to hook on these updated APIs
     - pf::web::guest::generate_selfregistration_page's error reporting
     - pf::web::guest::validate_selfregistration's error reporting
     - pf::web::guest::web_sms_validation's error reporting
     - pf::web::guest::generate_sms_confirmation_page's error reporting
     - pf::web::guest relies on setting a 'guest_pid' session variable instead
       of the login / username or token variables
     - GUEST_TEMPLATE and SPONSOR_TEMPLATE templates changed names to 
       TEMPLATE_EMAIL_GUEST_ACTIVATION and TEMPLATE_EMAIL_SPONSOR_ACTIVATION 
       and moved from pf::email_activation into pf::web::guest
     - pf::web::guest::send_registration_confirmation_email is now
       pf::web::guest::send_template_email
     - new API entry point prepare_email_guest_activation_info and 
       prepare_sponsor_guest_activation_info: these are meant to be overriden
       by custom code to provide more information for email templates
     - pf::web::guest::validate_sponsor_group() has been removed (migrated 
       into authentication modules)
     - pf::web::guest::generate_activation_confirmation_page was renamed and
       changed package, now: pf::web::generate_generic_page. It also changed 
       signature (now more generic).

    - Changes to Web API
    Users with custom code will have to hook on these updated APIs.
     - pf::web::web_node_register now enforces max registered nodes per pid 
       limits. You might want to merge that in your custom code.
     - pf::web::generate_error_page no longer performs the translation 
       itself, it is the burden of the caller to do so (to support format 
       strings)

    - pf::radius API bump to 1.02
    We bumped the version of our pf::radius API. If you want to take advantage
    of the Role-based access control feature you should probably migrate your
    custom authorize() call. Otherwise just bumping the version of your custom
    extension should be fine.

    - API Changes (pf::SNMP and pf::radius)
    The final say of a RADIUS Access-Accept is now in a switch object (through
    returnRadiusAccessAccept()) and no longer in pf::radius' authorize().
    A new smaller indirection layer was introduced in pf::radius to allow 
    extensive rewrite of RADIUS Access-Accept in custom code. Check 
    pf::radius' _shouldRewriteAccessAccept and _rewriteAccessAccept.

    - pf::SNMP API Bump
    We changed the interface to radiusDisconnect. If you use that interface
    in custom code (most, if not all, of you don't) then you'll need to update
    your callers. We are now accepting an attributes hashref instead of the
    accouting session id and username scalars.
----


Upgrading from a version prior to 3.2.0
---------------------------------------

----

    - Database schema update
    OpenVAS and billing engine support required database changes. Make sure you
    run the following to update your schema even if you don't use one or both
    of these new features:
    mysql -u root -p pf -v < db/upgrade-3.1.0-3.2.0.sql

    - Configuration changes related to OpenVAS integration
    With the addition of OpenVAS as a scanning engine, we made changes to the
    default configuration. People using nessus scan right now should be 
    careful and test their setup after the upgrade. They should at least set
    their scan.engine to nessus (default is none). Also, if a custom port was
    used, the scan.port parameter should be renamed to scan.nessus_port.

    - Scan configuration changes
     - scan.ssl no longer exists, get rid of it, it never really did anything
       since 1.8.3.
     - scan.nessusclient_file was renamed scan.nessus_clientfile
     - scan.nessusclient_policy was renamed scan.nessus_clientpolicy
     - scan.port was renamed scan.nessus_port

    - Violations changes related to OpenVAS integration
    There was some move in the example violations to add a new one for the 
    OpenVAS integration. Should pay attention to some 
    violations.conf.rpmsave /  violations.conf.rpmnew

    - New pf.conf configuration flag: registration.guests_self_registration
    This parameter allows to enable or disable guest self-registration. It 
    deprecates the previous technique to disable this feature (set modes=).
    It is enabled by default so when upgrading make sure to disable it if you
    don't want to allow self-registered guests.

    - Important changes to the FreeRADIUS integration
    We made some important changes to our FreeRADIUS integration: a fix for
    the random crashes, relocated logging to /var/log/radius/radius.log and a
    2x performance improvement by avoiding superfluous queries. Due to a 
    packaging glitch upgrading does not suffice to get the goodness. To do so:
    # yum install packetfence-freeradius2
    # yum reinstall packetfence-freeradius2
    Note: Remember the --enablerepo=packetfence if you disabled the repo as 
    suggested in the admin guide.
    The re-add your virtual IP in radiusd.conf (if any) and your webservice 
    user password into /etc/raddb/packetfence.pm.
 
    - new trigger types (no more scan type)
    The trigger type "Scan" has been removed to leave place to two new types 
    (Nessus and Openvas). Due to that change, modification to existing 
    violations.conf is required to change all existing "Scan" type to "Nessus".
    You can run the following command that will do the job. Make sure to backup
    your existing violations.conf file.
    /usr/bin/perl -p -i -e "s/Scan::/Nessus::/ig" /usr/local/pf/conf/violations.conf

    - CLI (telnet/ssh) behavior change regarding privileged access
    The feature to detect privileged access when using CLI access has been
    disabled except in the Trapeze module where users are unpriviledged by
    default. See #1370 for more details. Affected modules: most Cisco 
    switches with VoIP enabled and floating network devices, Cisco 3500XL, 
    Cisco ISR 18xx and Cisco WLC 21xx.

    - Cisco Catalyst 3550 MAC-Auth / 802.1X
    We changed the way we perform NAS-Port to ifIndex translation with this 
    release. If you use MAC-Auth (Cisco's MAB or 802.1X) and experience *any*
    regression, please let us know.

    - pfcmd exit status
    Some exit status of pfcmd changed regarding the config sub-command.
----


Upgrading from a version prior to 3.1.0
---------------------------------------

----

    - New repository required for RHEL 5 / CentOS 5: EPEL
    Extra Packages for Enterprise Linux (EPEL) is a repository provided by 
    the Fedora project that we now rely upon. RHEL 6 / CentOS 6 users have it
    already installed per installation instructions. Here's how to install it:
    wget http://download.fedoraproject.org/pub/epel/5/i386/epel-release-5-4.noarch.rpm
    rpm -i epel-release-5-4.noarch.rpm

    - rogue DHCP server violation
    The rogue DHCP server violation now needs a trigger in order to work. Make
    sure you have trigger=internal::1100010 under the violation entry. Users
    of packaged versions should have appropriate config upgrade mechanism
    handling the violation file.

    - Changes to rogue DHCP server detection and pfdhcplistener
    A lot of changes were made to the pfdhcplistener daemon. One big change
    is that it will now detect rogue DHCP servers even on your normal VLANs 
    and routed VLANs (given that you forward your DHCP traffic to it). Make 
    sure that your dhcpservers configuration listing all authorized DHCP is 
    up to date.

    - FreeRADIUS configuration changes
    Due to the new SoH feature, you might need to reinstall the PacketFence 
    FreeRADIUS package.
    yum reinstall --enablerepo=PacketFence packetfence-freeradius2

    - Database schema update
    SoH support and the MAC violation improvements required database changes. 
    Make sure you run the following to update your schema:
    mysql -u root -p pf -v < db/upgrade-3.0.2-3.1.0.sql

    - Aruba wireless de-authentication
    Aruba de-authentication now relies on RADIUS Disconnect-Request (RFC3576)
    instead of Telnet. Make sure you have set radiusSecret in your 
    conf/switches.conf and that RFC3576 support is properly enabled in your
    controller's AAA config.

    - Web library API change
    Anyone who customized his web_node_register method will need to update his
    version. _sanitize_and_register() now requires the session to be passed to
    it.

    - iptables marks changed
    Mark 0 is no longer used. Unregistered nodes' packets are now set to mark
    3. It was changed because rules matching mark 0 were matching unmarked 
    packets also. Unless you customized your firewall rules this change should
    be transparent.

    - DHCP Fingerprints loading behavior change
    In order to improve performance, DHCP fingerprints are not re-imported on
    every startup anymore. However updating fingerprints (pfcmd update 
    fingerprints) or reloading fingerprints (pfcmd reload fingerprints) will 
    still do.

    - User-Agent database updated
    We updated our User-Agent database. Some IDs could have changed in the 
    process. Most shouldn't have. The upstream project (HTTP::BrowserDetect) 
    accepted a patch from us to make this smoother in the future.

    - dhcp_dumper.pl addon changes
    Deep and important refactoring of the addon. Output format changed.

    - SNMP traps limit mechanism
    PacketFence can now limits the number of SNMP traps coming from a single
    ifIndex. See pf/conf/documentation.conf under vlan for more infos.

    - dropped jpgraph external library
    We migrated out of jpgraph into a new javascript-based library for our 
    charts and graphs. Source users will have to create a webadmin_cache/ 
    directory in var/. Packaged users won't have to do a thing.
----


Upgrading from a version prior to 3.0.3
---------------------------------------

----

    - New dependency
    This version introduces a new perl dependency: NetPacket. If you don't have
    EPEL configured as a repository trying to upgrade might fail. To 
    successfully upgrade make sure you have the EPEL repository enabled.

    - New time format
    We are now using an ISO like format for time, s=seconds, m=minutes, D=days,
    W=weeks, M=months, and Y=years.  Make sure you adjust your configs,
    especially your violations.conf.
----


Upgrading from a version prior to 3.0.2
---------------------------------------

----

    - Database schema update
    A new trigger has been added to delete the node useragent when deleting
    a node. Make sure you run:
    mysql -u root -p pf -v < db/upgrade-3.0.1-3.0.2.sql

    - pf.conf configuration changes
     - guests.self_allow_localdomain has been renamed 
       guests_self_registration.allow_localdomain
     - advanced.adjustswitchportvlanscript has been dropped
     - advanced.reevaluate_access_reasons's default value changed

    - Default Firewall Rules Updated
    Review the updated firewall rules (in .rpmnew) if you made changes and
    make sure to integrate changes if you need them. New rules include:
     - Allow incoming DNS on management interface (track production VLANs IPs)

    - Changes to Inline API
    Added a new method to pf::inline. Users with customized pf::inline::custom
    will need to bump the API level to '1.01' after your changes are made (if
    required) to stop PacketFence from complaining about correct API level.

    - Changes to Guest API
     - generate_activation_login_page is now generate_custom_login_page
     - pf::web::guest::auth has been replaced by pf::web::web_user_authenticate
     - pf::web::generate_login_page has been dropped. Use 
       generate_custom_login_page instead.

    - Changes to captive portal Web API
    Authentication objects are now created on every authentication attempt and
    they can return connection specific state to the captive portal. For 
    example a more specific authentication error or additional attributes to be
    recorded inside PacketFence. 
     - pf::web::web_user_authenticate no longer performs form validation. 
       validate_form is the one responsible now. Also it returns an instance
       of the auth::* object after authentication. Users with custom code using
       it will need to update their code.
     - pf::web::validate_form is a new method to validate login forms

    - Changes to authentication modules API
     - $name is now a package global (declared with our) instead of a local 
       variable.
     - authenticate returns only a true or false value. Errors meant for users 
       should be set with $this->_setLastError("string") in authenticate() sub.
     - Some modules will require the import of pf::config. Add to the use 
       section on top: use pf::config qw($FALSE $TRUE);
    Once the migration done, bump $VERSION to 1.10. You will *not* have to do 
    this if you made no customization to the conf/authentication/... files.

    - pfcmd_vlan interface changes
    reevaluateVlan is now called reevaluateAccess and will perform appropriate
    changes for a firewall change too (inline enforcement).
----


Upgrading from a version prior to 3.0.1
---------------------------------------

----

    - MySQL pf user rights
    The user pf in the database is missing the execute rights.  Make sure
    you run :
    mysql -u root -p pf -v < db/upgrade-3.0.0-3.0.1.sql
----


Upgrading from a version prior to 3.0.0
---------------------------------------

----

    - BACKUP YOUR /usr/local/pf/ BEFORE UPGRADING
    All files in html/user/ will be removed on upgrade (everything is now
    in html/captive-portal/ as you'll see below). This includes templates and 
    remediation pages.

    - Database schema update
    Added support for guest self-registration / management. Also added support
    for Radius accounting. New tables creation. You need to update your schema
    with:
    mysql -u root -p pf -v < db/upgrade-2.2.0-3.0.0.sql

    - pf/vlan/custom.pm and pf/vlan/radius.pm API changes
    Several variables were changed from bareword constants into Readonly 
    constants (to fix #1266). Some of you might need to adjust your 
    customizations to handle this change. Most of you won't need to. If you use
    any of these constants in your customizations:
    WIRELESS_802_1X, WIRELESS_MAC_AUTH, WIRED_802_1X, WIRED_MAC_AUTH, 
    WIRED_SNMP_TRAPS, WIRELESS, WIRED, EAP, UNKNOWN, INLINE, VOIP, NO_VOIP
    Then you need to add a $ symbol in front of the constant's name.
    All of you will need to bump the API level to '1.01' after your changes are
    made (if required) to stop PacketFence from complaining about correct API 
    level.

    - Upgrade helper scripts
    Very basic upgrade scripts for 3.0 were created in addons/upgrade/. See 
    their POD doc for usage information:
    perldoc addons/upgrade/to-3.0-networks.conf.pl 
    perldoc addons/upgrade/to-3.0-pf.conf.pl 
    perldoc addons/upgrade/to-3.0-violations.conf.pl

    - Firewall (iptables) now handled by PacketFence
    Make sure that the iptables generated will not conflict with the rules you
    need for your environment. You can customize the default firewall 
    configuration in conf/iptables.conf. Also make sure that the iptables 
    service is started by your distro by default otherwise you will have 
    unnecessary error messages on PacketFence's startup.

    - Several changes to Apache configuration
    We've externalized repetitive portions in conf/httpd.conf.d/. Make sure to
    re-integrate any customization you've made.

    - violations.conf disable parameter deprecated in favor of enabled
    disable=Y|N is no longer supported. Change with enabled=Y|N.
    A helper upgrade script is provided in addons/upgrade/. See:
    perldoc addons/upgrade/to-3.0-violations.conf.pl

    - 'guest' category required for guest access
    Newly added guest handling requires a 'guest' node category. Users upgrading
    need to create it manually. See Node > Categories under the Web Admin or 
    `pfcmd help nodecategory`.

    - New pf.conf configuration parameter: interface enforcement
    Under the [interface ...] statements a new configuration parameter has been
    added: enforcement. We got rid of the concept of 'modes' in PacketFence and
    enforcement replaces that concept. It is a per interface choice allowing 
    you to run PacketFence in both inline and out-of-band mode at the same 
    time. Users upgrading should probably set enforcement=vlan on all interface
    with type=internal. Run `bin/pfcmd checkup` to validate your configuration.

    - conf/named_vlan.conf moved to conf/named.conf
    People using packages should be automatically updated. Make sure to put
    back any local changes you have made to the file. Others will need to move
    the file. You can do so with:
    mv /usr/local/pf/conf/named_vlan.conf /usr/local/pf/conf/named.conf

    - conf/dhcpd_vlan.conf moved to conf/dhcpd.conf
    People using packages should be automatically updated. Make sure to put
    back any local changes you have made to the file. Others will need to move
    the file. You can do so with:
    mv /usr/local/pf/conf/dhcpd_vlan.conf /usr/local/pf/conf/dhcpd.conf

    - vlan.dhcpd, vlan.named and vlan.radiusd moved under [services]
    These variables are now located under [services] and they have a new 
    default value of enabled. Make sure to remove or migrate the old 
    configuration from your conf/pf.conf.

    - services.httpd, dhcpd, named, radiusd, snmptrapd and snort renamed
    They were all renamed to <name>_binary. Adapt your configuration if 
    required. Most users shouldn't have to.

    - general.caching disabled by default
    A historical and badly understood feature, general caching, has now been
    disabled by default. Previously it only had impacts if the mode was ARP but
    because of the modes removal it needed to be changed to disabled by default.
    Please report any regression introduced by this change.

    - pf.conf's scan.live_tids parameter removed
    This "feature" has been removed because it created more confusion than 
    usefulness. Now every scan trigger ids specified in violations.conf have
    full effect.

    - networks.conf's pf_gateway= renamed next_hop=
    Make sure to update your configuration otherwise you will get warnings on
    startup. At some point in the future pf_gateway will no longer be supported.

    - networks.conf's type change
    isolation and registration keywords are replaced by vlan-isolation and 
    vlan-registration in networks.conf's type parameter. This is done to allow
    the introduction of the inline keyword and avoid confusion between vlan and
    inline enforcement over a network. It's recommended that you update your
    configuration as the old names will be removed in the future. `pfcmd 
    checkup` will warn you about this.

    - pf.conf parameter name and category changes
    Here are the changes:
    - vlan.adjustswitchportvlanscript is now advanced.adjustswitchportvlanscript
    - vlan.adjustswitchportvlanreasons is now advanced.reevaluate_access_reasons
    - ports.redirect is now inline.ports_redirect
    You only need to take action if you are not using the default values.

    - pf.conf's interface type changes
    We added management keyword to replace the confusing managed keyword. Also
    dhcp-listener is accepted in addition to the previously used dhcplistener.
    Use of the managed keyword will issue warnings in `pfcmd checkup`.

    - Dropping support of interface authorizedips
    pf.conf's per interface authorizedips parameter no longer exists. We don't
    belive if was used at all. If you want to achieve the same functionality 
    just edit conf/iptables.conf and add your own rules to allow specific IPs
    in.

    - flip.pl is no more
    Its functionality has been merged into pfcmd_vlan under the -reevaluateVlan
    flag. If you replaced system's flip.pl with your own you would like to know
    that you will need to parse the -reevaluateVlan and -mac aa:bb:cc:dd:ee:ff
    properly.

    - Authentication modules interface change
    All authentication modules (conf/authentication/*) were migrated into
    objects. Please carefully merge any module you were using by comparing
    the .rpmnew version and your version. If you are unsure, replace your
    module with the .rpmnew one and re-apply configuration parameters 
    afterwards.

    - Intrusive changes to Captive Portal
    It is recommended that you redo your customization from scratch instead of 
    trying to adapt it.
    Among other things:
     - Changes to all templates, cgi-bin/ scripts and pf::web core code
     - All remediation URLs have changed from /content/index.php to 
       /content/remediation.php. Make sure to update your conf/violations.conf!
     - All URLs are now clean URLs translated by Apache's mod_rewrite config
     - Default workflow now brings you to the login page (no more registration
       click-through unless you adjust nbregpages in configuration)
     - Default logo changed to packetfence-cp.png (was packetfence.png)
     - Files organization was changed. Anything custom relying on specific paths
       should be updated.
       - html/user/ became html/captive-portal
       - cgi-bin/ -> html/captive-portal/
       - html/user/content/templates/ -> html/captive-portal/templates/
       - html/user/content/violations/ -> html/captive-portal/violations/
       - html/user/content/3rdparty/ -> html/captive-portal/content/

    - Email Activation URL change
    From /activate/<hash> to /activate/email/<hash>

    - Support for Apache prior to version 2.2.0 dropped
    Upgrade your Apache. We don't think it's used by anyone at this point. Let
    us know if you need it back.

    - register-$type.cgi no longer supported
    If you relied on it, we suggest that you migrate your custom code into 
    lib/pf/web/custom.pm or the captive-portal's CGIs.

    - jpgraph external library now included with distribution
    Due to the lack of jpgraph packages, we decided to inline the software 
    instead of building packages for it. This simplifies installation from 
    tarball.
    Jpgraph's installation used to be at 
    /usr/local/pf/html/admin/common/jpgraph/jpgraph-<version> but is now in 
    /usr/local/pf/lib/jpgraph. Users of our packaged versions won't notice the
    change and can safely get rid of the php-jpgraph-packetfence package.

    - jpgraph 1.x support deprecated
    We got rid of the 1.x jpgraph support. It was only required for 
    environments still on PHP4. We don't think it's used by anyone at this 
    point. Let us know if you need it back.

    - Nortal/Avaya ERS Switch module rename
    We changed the naming of some Nortel/Avaya switch modules:
     - Avaya::ERS5500 -> Avaya::ERS5000
     - Avaya::ERS5500_6x -> Avaya::ERS5000_6x
     - Nortel::ERS4500 -> Nortel::ERS4000
     - Nortel::ERS5500 -> Nortel::ERS5000
     - Nortel::ERS5500_6x -> Nortel::ERS5000_6x

    - RADIUS Accounting
    RADIUS is now using SQL to fetch the client configuration.  So, for
    every device that needs to do MAC Authentication (Wired/Wireless) or
    802.1X, you need to add the radiusSecret=YOUR_SECRET to the
    switches.conf entry for that device.  Change YOUR_SECRET with the 
    actual RADIUS secret.
----


Upgrading from a version prior to 2.2.1
---------------------------------------

----

    - Cisco port-security + Voice over IP support on 2960, 2970, 3550 and 4500
    Changes (regressions?) in the Cisco 2960 IOS behavior in 12.2(46)SE or 
    greater forced us to change our VoIP handling behavior. If you run such an 
    IOS and have nodes behind the data port of your VoIP you need to upgrade 
    your switch configuration:
    On every PacketFence port with VoIP add:
      switchport port-security maximum 1 vlan voice
      switchport port-security mac-address 0200.010x.xxxx vlan voice
    where xxxxx is the ifIndex of the port under modification. See Network 
    Device Guide for a reminder of port to ifIndex translation for the 2960.

    Above configuration should *not* be applied to IOS earlier than 12.2(46)SE
    otherwise VoIP and/or device authorization will malfunction.

    We think that the above mentionned changes should not be required on other
    models than the 2960. Let us know if you experience otherwise.

    - pf::vlan's $node_info changed
    If you are using custom VLAN assignment code be aware that the $node_info
    hashref is now populated by node_attributes() instead of node_view(). Most
    important fields should still be available in $node_info however if you 
    needed one that is no longer there feel free to call node_view() yourself.
    This was done to reduce the overall latency of RADIUS replies.
----


Upgrading from a version prior to 2.2.0
---------------------------------------

----

    - Database schema update
    Related to the easier User-Agent violation system, some tables were 
    dropped and others added. You need to update your schema with:
    mysql -u root -p pf -v < db/upgrade-2.0.0-2.2.0.sql

    - Configuration files location changed from conf/templates/ to conf/
    Please make sure that you move your configuration files appropriately.

    - SSL configuration changes
    SSL Certificate statements are now stored in conf/ssl-certificates.conf.
    Make sure that you configure this file with your certificates correctly.
    This file will not be modified by our package. One less thing to worry 
    about on ugprades.

    - logrotate script installed by default
    Be careful if you done yours by hand. It might conflict with your script.

    - New Captive Portal Network Access Detection technique
    The previous approach to redirect users to the Internet when access was
    enabled never reliably worked so we are introducing a new javascript-based
    technique to do so. This approach involves a couple of clever tricks and 
    some browser-specific adjustments. Please review the differences between 
    your current html/user/content/templates/release.html file and the new 
    html/user/content/templates/release.html.rpmnew file. Also the behavior is
    adjusted by pf.conf's redirtimer, redirecturl and always_use_redirecturl 
    parameters under [trapping] and network_detection_ip under [captive_portal].
    More about this feature can be found in the Administration guide.

    - Apache's automatic performance settings adjustments
    Apache's configuration is now adjusted based on total system memory to
    prevent swapping scenarios with PacketFence. We feel the dynamic 
    configuration should do a good job but feel free to maintain your Apache 
    configuration by hand if you know better.

    - packetfence-freeradius2
    A new package that configures FreeRADIUS is available now. If you upgrade
    DO NOT install it unless you really know what you are doing.

    - clean-up in conf/violations.conf
    We added better examples and reduced the length of some violation names to
    improve user experience especially in the Web Admin. Update your 
    configuration if you want to benefit from those changes.

    - deprecated pf.conf parameters
    registration.queuesize was removed.

    - User-Agent violations rewrite
    If you are using USERAGENT::<id> triggers in your violation configuration,
    you need to updated them. We completely changed the back-end and the IDs
    are now all different. Check in the Web Admin under configuration -> 
    user-agent for the new IDs and the new possibilities.

    - Important problems found in the port-security for the 3Com Switch 4200G
    There is a bug in these switches that make the port-security support in 
    PacketFence flaky. If you use it you should upgrade to a MAC Auth / 802.1X
    configuration.

    - Status unknown of the port-security support for the 3Com SuperStack 4500
    We had problems with this code with the 4200G and since we don't have 
    access to a SS4500 we cannot guarantee that it works. Please get in touch
    with us if you have a SS4500 and can run some tests for us.

    - Behavior change regarding wired MAC-Authentication
    No matter what is connected on the port (ie: VoIP), when a client using 
    MAC-Authentication need to change VLAN, we shut / no shut the port. This
    might affect ongoing Voice over IP calls but is better than the previous 
    behavior were the node was simply left where it was. This is an interim 
    measure before we implement RADIUS Change of Authorzation support (CoA).

    - node lookup changed
    By default we do not update the node lookup module in order to allow local
    customization. However if you want to benefit from the improved node lookup
    script, make sure that you overwrite your existing lib/pf/lookup/node.pm 
    module with the new file (.rpmnew). Be aware that the output of `pfcmd 
    lookup node <mac>` changed so make sure you update your parsing scripts (if
    any). This also affects the Node lookup section of the Web Admin interface.
----


Upgrading from a version prior to 2.1.0
---------------------------------------

----

    - You MUST upgrade conf/templates/httpd.conf and 
    conf/templates/named_vlan.conf
    The location of the PID files changed. The templates must reflect this new
    location: var/run/ instead of var/
    Also in conf/templates/named_vlan.conf the configuration directory is 
    var/named instead of var/.
    See the .rpmnew files for the proper configuration.

    - Module versioning for pf::vlan::custom and pf::radius::custom
    We are now relying on module versioning to catch interface changes before
    they hurt the users. PacketFence will generate errors on startup if you 
    have not upgraded your modules' interface and version. The interfaces have
    not changed so all you need to do on upgrade is to add:
        our $VERSION = 1.00;
    to both lib/pf/radius/custom.pm and lib/vlan/custom.pm.

    - Default port bounce duration changed
    To support a variety of Linux desktop operating systems we needed to 
    increase the duration of our port bounce from 2 seconds to 5 seconds. On a
    very busy setup this could have consequences. Either increase the number of
    concurrent threads working (nbtraphandlerthreads under [vlan]) or restore
    the port bounce duration to 5 seconds (bounce_duration under [vlan]).

    - Several Nortel/Avaya module changes
    5520 renamed to 5500, 5520Stacked is no longer necessary, firmware 6.x 
    support for the 5500 series requires you to use module name BayStack5500_6x.
    Just make sure to review your conf/switches.conf so that the config refers
    to proper modules.

    - Removed conf/templates/*.pl captive portal extensions
    This mechanism was removed since the new pf::web::custom mechanism is
    cleaner and less error-prone. Make sure to migrate any custom code you have
    in release.pl, login.pl, enabler.pl, redirect.pl, scan-in-progress.pl, 
    error.pl, status.pl and register.pl to lib/pf/web/custom.pm.

    - pid files changed location
    Previously in var/ they are now in var/run/   

    - New configuration directory for generated configuration: var/conf/
    Changed the location of the generated configuration file from conf/
    to var/conf/.  This will mitigate the fact that people were trying to
    modify the generated files instead of the templates.

    - 'pending' node status now relies on javascript to detect network access
    The HTML meta refresh approach never reliably worked so there's a new 
    javascript technique. If you rely on node status 'pending' in your 
    workflow, please check pf.conf's new captive_portal.network_detection_ip 
    variable and re-test your portal to make sure it still works.

    - Output of node lookup changed (again!)
    The output of `pfcmd lookup node <mac>` changed. Make sure you update your
    parsing scripts (if any). This also affects the Node lookup section of the
    Web Admin interface.

    - pf::SNMP (lib/pf/SNMP.pm) API level bump
    We changed the contract of setAdminStatus() so we bumped the version of 
    pf::SNMP to 2.00. If you use setAdminStatus() in custom code make sure you
    update your calls.
----


Upgrading from a version prior to 2.0.1
---------------------------------------

----

    - lib/pf/vlan.pm's fetchVlanForNode interface changed
    If you built a customized version of this method in lib/pf/vlan/custom.pm
    you will need to update it.

    - Meru Controller 3000 now named Meru Controller
    Since our code should work for all Meru Controllers, we renamed the module.
    Meru::MC3000 is now Meru::MC. If you upgrade make sure you update your 
    conf/switches.conf or Configuration -> Switches (in the web admin).

    - Output of node lookup changed
    The output of `pfcmd lookup node <mac>` changed. Make sure you update your
    parsing scripts (if any). This also affects the Node lookup section of the
    Web Admin interface.
----


Upgrading from a version prior to 2.0.0
---------------------------------------

----

    - Database schema update
    Several new fields were added. You need to update your schema with:
    mysql -u root -p pf -v < db/upgrade-1.9.0-2.0.0.sql

    - FreeRADIUS module rewritten and renamed
    The FreeRADIUS has been completely re-written from the previous release 
    series. Now, except for the authentication against the PacketFence server
    all the control is centralized in the PacketFence configuration. No more 
    customization required in the FreeRADIUS module! We strongly recommend
    that you carefully migrate to this module and forget about the old one.
    We also changed the name from rlm_perl_packetfence.pl to packetfence.pm so
    update your FreeRADIUS configuration accordingly.

    - /cgi-bin/pdp.cgi moved
    Remote snort probes or other mechanisms relying on the presence of this 
    file should be updated to be /webapi instead. Upgrading each probe's
    packetfence-remote-snort-sensor will take care of this for remote snort 
    probes. All other custom means should be manually upgraded.

    - SOAP handler changed
    The URI of the SOAP handler changed from 
    http://www.packetfence.org/PFEvents to http://www.packetfence.org/PFAPI. To
    better reflect the fact that it is not just an event handling server. You 
    will need to upgrade your remote snort probes with the new PacketFence 
    remote snort sensor RPM or manually change the URI.

    - Output of node lookup changed
    The output of `pfcmd lookup node <mac>` changed. Make sure you update your
    parsing scripts (if any). This also affects the Node lookup section of the
    Web Admin interface.

    - pfcmd_vlan output change
    Output of `pfcmd_vlan` changed dramatically. If you used scripts to 
    automate tasks with pfcmd_vlan and expected particular output, your scripts
    should be updated.

    - pfcmd input and output change
    If you used script to automate tasks relying on the `pfcmd` interface, you
    need to update them. Output of `pfcmd node`, `pfcmd locationhistorymac`, 
    `pfcmd locationhistoryswitch`, `pfcmd violation view all`, `pfcmd 
    switchconfig` and `pfcmd fingerprint view all` also changed.

    - DHCP and DNS server configuration changes
    With previous versions it was recommended to configure DHCP and DNS servers
    manually and instructions were provided to do so on the Administration 
    Guide. Starting with this version it is recommended to use the configuration
    templates and let PacketFence auto-configure the DHCP and DNS servers. 
    Migrating to this new approach is not mandatory but is recommended. To do so
    please follow the "DHCP and DNS Server Configuration (networks.conf)" 
    section of the Administration Guide.

    - lib/pf/vlan.pm interface changed
    If you built a customized version of vlan.pm in lib/pf/vlan/custom.pm be 
    aware that there were a lot of changes. We strongly recommend you rewrite 
    your custom.pm on top of these new changes instead keeping your old.

    - Captive Portal changes
    By default pf::web is no longer exporting it's subroutines. This means that
    all the captive portal scripts in cgi-bin/ will need to be updated to use 
    the full name pf::web::web_node_register() instead of web_node_register().
    If your cgi-bin files are the default ones you don't need to change
    anything. These breaking changes are introduced to allow pf::web::custom to
    redefine any subroutine in pf::web and will allow easier upgrade path for 
    users who need to customize the portal.

    - Violation priority enforcement
    Violation priorities are now properly enforced: 1 means highest priority
    and 10 means lowest priority. Even if documentation said so, before this 
    release, the code enforced it the other way around. This affects what 
    violation is shown on multiple violations (it will favor highest) and has
    most impact when Nessus scanning is used. Since this is a default behavior
    change, you should double check your config!

    - External remediation pages 
    Violations with fully qualified URLs are now handled with new code that 
    uses mod_proxy and mod_rewrite instead of mod_proxy_html. This was done
    because the current implementation is broken out of the box on a CentOS 
    system without manually compiling and installing the mod_proxy_html 
    package. If you used it then reverify all your remediation pages with
    fully qualified URLs as they might be broken now.

    - SMC TS8800M module changes
    A lot of changes were made to this SMC module such that problems occuring
    with the previous module should be resolved now. These fixes also required
    an updated firmware from SMC. Make sure your switch runs at opcode 2.4.5.13
    for the SMC TigerStack 8824M or 8848M to work properly with PacketFence.

    - loadMACintoDB.pl removed
    Dropping loadMACintoDB.pl. Replaced by node import feature see `pfcmd node 
    import` or Node -> Import in the Web Administration interface.

    - connect_and_read.pl and dhcp_dumper moved
    They are now located in addons/.
 
    - deprecated subs
    lib/pf/SNMP.pm's setIsolationVlan, setRegistrationVlan and setNormalVlan 
    are now deprecated and will be removed in the future. Use 
    setVlanByName($ifIndex, $switch_locker_ref, $vlanName) instead. For 
    example: setVlanByName($ifIndex, \%switch_locker, 'guestVlan'); 
----


Upgrading from a version prior to 1.9.1
---------------------------------------

----

    - Captive portal using mod_perl
    The captive portal's default mode of operation relies on mod_perl now. 
    The benefit is a tremendous performance gain. If you experience problems 
    with authentication after you upgraded make sure that the cgi file has the
    proper 'use lib' statements to load the authentication modules in conf/. 
    Default configurations should not have any issues.

    - Extreme switches new firmware requirement
    Due to a change in Extreme's code, linkup/linkdown mode now requires at 
    least firmware 12.2. A compatibility layer to support pre-12.2 could be 
    written. Contact us if you are interested.

    - Web Administration interface access control
    Administrators can now give different access levels to users. By default
    all users will be given the admin level rights unless you modify the 
    conf/admin.perm file. See the Administration Guide FAQ for details.

    - pfcmd output change
    pfcmd node edit <mac> ... will no longer output changes made to the node 
    entry. This behavior was due to a side effect rather than a feature and it
    caused some problems so we got rid of it. pf::node::node_modify is also 
    affected.

    - switches.conf: htaccessUser and htaccessPwd deprecated
    Web Services related parameters were added in switches.conf. Because of the
    duplicate functionality we are deprecating the htaccessUser and htaccessPwd
    parameters. Only the Intel Express 460 module is affected. The parameters
    will still work but if you are reading this you should migrate them to the 
    new wsUser, wsPwd and wsTransport parameters.
----


Upgrading from a version prior to 1.9.0
---------------------------------------

----

    - Passthrough
    Passthrough is now set to disabled by default. If you need it, make sure
    you re-enable it in your conf/pf.conf. As a reminder, passthrough is the
    mechanism used to allow users trapped in registration or isolation to reach
    certain external URLs or custom violation pages hosted externally. It is 
    not used in a default install.

    - Freeradius 2.x
    We now recommend using freeradius 2.x instead of 1.x for wireless, 802.1x
    or MAC authentication Bypass authentication mechanisms. Freeradius 1.x 
    still works but we are seeing more hang cases with AD 2008, Vista and Win 7.

    - Library update: steps required on manual upgrade
    PacketFence no longer relies on a specific version of the Parse-RecDescent
    library. If you upgraded manually, you should re-generate the precompiled
    grammar by running installer.pl. If you upgraded using the RPM package the
    grammar already comes precompiled.

    - Changes to some OS violations
    Some DHCP fingerprint have been re-labeled to avoid problems with VoIP 
    autodetection. OS::311 is now OS:1102 and OS::315 is now OS::1103. These
    devices (iPhone and HTC Android) are now categorized under Smartphone 
    instead of VoIP phones. Update your configuration accordingly.

    - pfdhcplistener logging in logs/packetfence.log
    We reduced the number of INFO messages that pfdhcplistener was producing
    because it was too verbose. Now only INFORM / OFFER / ACK messages are 
    logged and the fingerprint and node modification messages were 
    consolidated. If you are troubleshooting and need the other messages, make
    sure you increase log verbosity to DEBUG.

    - pfcmd output change
    pfcmd will print "Command not understood. (pfcmd grammar test failed at 
    line 200.)" to STDERR on unrecognized input before showing the usage 
    message. You might have to change your scripts to handle that.

    - Cisco Controller 4400 now named WLC_4400
    To be more consistent, we renamed Cisco::Controller_4400_4_2_130 to 
    Cisco::WLC_4400. If you upgrade make sure you update your conf/switches.conf
    or Configuration -> Switches (in web admin)

    - Output of node lookup changed
    The output of `pfcmd lookup node <mac>` changed. Make sure you update your 
    parsing scripts (if any). This also affects the Node lookup section of the
    Web Admin interface.

    - New run-time perl dependencies Try::Tiny and Readonly::XS (optional but
    will improve performance)

    - New parameter in conf/violations.conf: whitelisted_categories
    Node in a whitelisted category will not be isolated on a given violation.

    - Database change
    A new table and a few fields were added for the new node categorization 
    feature. To upgrade your schema, run:
    mysql -u root -p pf -v < db/upgrade-1.8.6-1.9.0.sql

    - pfsetvlan and conf/switches.conf validation
    If there is a problem in the conf/switches.conf file PacketFence will say 
    so at startup but will still try to run. Before this release, pfsetvlan 
    wouldn't start with a bad config file.

    - Foundry module change
    In order to support port-security some aspects of the Foundry module had
    to change. We are not 100% that the module will still work since we don't
    have the original switch on which linkUp/linkDown support was developped.
    If you experience a regression, please file an issue into our bugtracker.

    - lib/pf/vlan.pm interface changed
    If you built a customized version of vlan.pm in lib/pf/vlan/custom.pm be 
    aware that the parameters expected by vlan_determine_for_node() and 
    custom_getCorrectVlan() changed. Instead of the switch's IP, a switch 
    object (pf::SNMP) is expected. Also, the whole node_info is passed to 
    custom_getCorrectVlan() instead of scalars of node_info's content.

    - Backup script archives locationlog_history records older than a year
    Archives are an SQL dump of the records placed in /root/backup/ by default 
    and never deleted. It will run the first day of each month.

    - Backup script less aggressive about history
    We are now keeping 1 month of locationlog instead of 15 days with the 
    optional database backup script in addons/. Makes more sense for most users.
----


Upgrading from a version prior to 1.8.7
---------------------------------------

----

    - No action on wireless deauthentication traps
    PacketFence no longer close locationlog entries based on wireless 
    deauthencation traps. It was causing more problems than anything. See bug
    #880 for details: http://www.packetfence.org/mantis/view.php?id=880

    - Registration login no longer kept in browser session
    We fixed a bug that changes the behavior of the registration login. Before
    if you registered and deregistered while keeping your browser open, you
    would not be presented with the login page if you tried to register again. 
    You would have been automatically authenticated. This is no longer the case.
    You will need to re-authenticate now. You might have relied on that 
    behavior.
----


Upgrading from a version prior to 1.8.6
---------------------------------------

----

    - Table format changed
    Migrated tables `configfiles` and `traplog` from type MyISAM to InnoDB. You
    are not required to change the format but if you want, run (at night):  
    mysql> alter table configfile ENGINE = InnoDB;
    mysql> alter table traplog ENGINE = InnoDB;

    - Backup script less aggressive about history
    We are now keeping 15 days of locationlog instead of 2 with the optional 
    database backup script in addons/. Makes more sense for most users.

    - Database schema update
    A new table `locationlog_history` has been added to the database schema. It
    should be useful for people with big locationlog tables. Upgrading your 
    schema is not required but recommended. You can update your schema with:
    mysql -u root -p pf < db/upgrade-1.8.4-1.8.6.sql
    The script migrate-to-locationlog_history.sh in addons/ can help you 
    transition your old records to this new table.

    - Updated conf/ui.conf
    To fix a bug we had to change ui.conf. By default an rpm upgrade will 
    replace ui.conf and save a backup of the previous file to ui.conf.rpmsave.
    If you modified your ui.conf, do not forget to merge your old version with
    this new one.
    
    - New Snort default configuration
    Default configuration for snort changed. Old config can still be found at 
    conf/templates/snort.conf.pre_snort-2.8.

    - Output of pfcmd switchconfig changed
    The output of `pfcmd switchconfig get <ip|all>` changed. Make sure you 
    update your scripts that relies on that output (if any). This also affects 
    the Configuration->Switches section of the Web Admin interface.

    - Fixed an issue with CLI transport for switches/APs: for SSH make sure you
    have 'SSH' and not 'ssh'. Look into the 'Configuration->Switches' or edit
    /usr/local/pf/conf/switches.conf

    - 802.1x module expects 'guest' instead of 'visitor' in node.pid
    We changed the naming of the guest concept from visitor to guest. If you
    allow guests on your network, doublecheck your rlm_perl_packetfence.pl 
    module and align it on your naming (update all to guest or change back to 
    visitor).
----


Upgrading from a version prior to 1.8.5
---------------------------------------

----

    - 802.1X freeradius module updated 
    pfcmd_ap.pl's code has been integrated in rlm_perl_packetfence.pl. If you 
    need the performance benefit from this transition, you have two options:
      1) Replace completely your rlm_perl_packetfence.pl with the new one
      2) Migrate your pfcmd_ap.pl manually
         To do so, copy all of pfcmd_ap.pl's code into a sub in 
         rlm_perl_packetfence.pl. Change all the print calls into return calls.
         Remove all exit and make sure you free resources before returning.
    If you don't need the performance improvement, leave things as they are. 
    We will be deprecating the MySQL interface in favor of a better SOAP 
    interface soon.

    - whitelisting MAC addresses is now more consistent across violation types
    Certain types of violation triggers (OS, USERAGENT, VENDORMAC) were not
    honoring the whitelist parameter. The bug is fixed but you might have 
    relied on that behaviour.
    http://www.packetfence.org/mantis/view.php?id=801

    - logging priority now shown in log files
    To improve logging readability, we now include logging priority (ex: DEBUG,
    INFO, WARN, etc.). If you use scripts to parse PacketFence's logs you will
    need to update them.

    - Added new dependencies:
	- perl-LDAP (used to authenticate users trough LDAP during 
	  registration)
	- php-ldap (used to authenticate users connecting to the 
	  Web interface through LDAP)
	- perl-IPC-Cmd (used to generate static routes for registration and
	  isolation routed VLANs)
	- perl-SOAP-Lite (used when receiving alerts from Snort)

    - HUB violation removal
    HUB violations have been removed since they create a lot of false positives.
    http://www.packetfence.org/mantis/view.php?id=793

    - Dynamic uplink fixes
    In certain cases, PacketFence took action on switches where dynamic uplinks
    couldn't be found. The bug is fixed but you might have relied on that 
    behaviour.
    http://www.packetfence.org/mantis/view.php?id=795
    http://www.packetfence.org/mantis/view.php?id=809

    - Source of Correct/Normal VLAN changed
    Correct/Normal VLAN no longer comes from the database's node entry but from
    switches.conf. This is a modified behavior when returning the correct (aka 
    normal) VLAN (in custom_getCorrectVlan). This behavior is redefined by most
    users in lib/pf/vlan/custom.pm (or conf/pfsetvlan.pm in 1.7.x) so it should
    not have any impact for most of you. However, if you relied on the node 
    entry specifying which VLAN is the normal VLAN, this is no longer the case. 
    Now, the correct/normal VLAN is defined by the normalVlan variable in the 
    switch's entry or the default entry in switches.conf. This makes more sense
    for most new installs.

----


Upgrading from a version prior to 1.8.4
---------------------------------------

----

    There was no upgrade-specific documentation done prior to 1.8.5.

    - Database schema
    Always make sure that your database schema is up to date. See if upgrade 
    scripts are available in db/.

----

