                         PacketFence

http://www.packetfence.org/

Notes on upgrading from an older release
----------------------------------------

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

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

o 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).

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


o 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/.

