Upgrade PINsafe
From Swivel Knowledgebase Wiki
Contents |
Overview
PINsafe upgrades and PINsafe migration can be performed by following the below procedures. This document covers all PINsafe 3.x versions. The PINsafe license is compatible within major versions 3.1 to 3.2, etc, but a new license is required between versions 2.1 to 3.1.
For information on upgrading the PINsafe appliance see Upgrade Appliance
Prerequisites
1. What DB is PINsafe using: Internal, MySQL, Other?
2. Is a Virtual IP being used?
3. Type of appliance installation: Active/Active, Active/Passive, or Standalone.
4. Access to the appliances using root/admin. Referred to as ‘Login’ for the remainder of the document.
5. Test Transports and authentication are all working before the upgrade.
6. Create a directory under root called upgrade
7. New copy of pinsafe.war placed in /root. If using an appliance see Copying appliance files How to Guide
8. In the case of HA configurations, both appliances are working and functioning with the intended design.
9. Ensure PINsafe is fully functional (check logs)
10. Put a freeze on PINsafe administration changes and repository synchronisations during the upgrade (no PIN changes, account creations or deletions)
11. Turn off AD synchronisation on the server being upgraded
12. Ensure PINsafe is fully backed up
13. PINsafe Software
Upgrade Considerations
Ensure the OS/Appliance has the latest updates and patches see Patch Management
Where necessary schedule downtime
It is better to notify Swivel Secure in good time before an upgrade
Where necessary request professional services through your reseller
Where available carry out upgrade on test system prior to production system
Site specific customisations may need these customisations to be applied after the upgrade, these include Custom Transports and external databases are used such as MS SQL and Oracle the drivers located in pinsafe/WEB-INF/lib such as sqljdbc.jar, sqljdbc4.jar need to be copied see MS SQL Database How To Guide and Oracle Database How To Guide
To upgrade PINsafe by copying data from one appliance to another you may wish to use WinSCP, see WinSCP How To Guide
PINsafe Version Specific Considerations
For information on PINsafe features in each version see Versions FAQ
PINsafe 2.x
PINsafe 2.x uses a different database and direct upgrades are only possible through Swivel Secure Support. An upgrade from version 2.x to version 3.x will require a new license.
PINsafe 3.1
It is not possible to directly copy the PINsafe 3.1 config.xml file to higher versions. The configuration should be manually entered through the PINsafe administration console.
PINsafe 3.5
With External databases some new tables are added. There may be with issues with MySQL tables PINsafe upgrade fails on MySQL
PINsafe 3.6
The animated security string requires JRE 1.6, the Java version may need upgrading (check PINSAFEK for correct value such as 3500)
Custom Transports used in PINsafe 3.5 or earlier will not work in PINsafe 3.6 or later, contact support@swivelsecure.com for an updated transport
PINsafe 3.7
If RADIUS groups are being used, then these may need to be re-entered as the group configuration has moved from RADIUS/Server to RADIUS/NAS
PINsafe 3.8
- If you currently have 'Check Password with Repository' set to 'Yes' on the Policy -> Password screen, you will need to define this against each agent where it is required as this is now configured against each agent, rather than being a general setting;
- If you currently have 'Check Password with Repository' set to 'Yes' on the Policy -> Password screen, this will no longer take effect upon the PINsafe Administration Console login;
- Mobile clients (Swivlet/iPhone iClient/Android) will need to be upgraded to versions that include 3.8 Mobile Device Provisioning to utilise the new features provided see Mobile Provision Code
- PINsafe appliances will need to have their proxy upgraded for the 3.8 Mobile device provisioning see How to upgrade the appliance proxy for PINsafe 3.8
- Self-provisioning for the mobile clients is conducted via the ResetPIN application. This needs to be upgraded when upgrading to PINsafe 3.8. See ResetPIN upgrade for PINsafe 3.8 How To Guide
Microsoft Windows PINsafe Upgrade
The following article covers the Microsoft Windows PINsafe Upgrade steps Upgrading PINsafe on Microsoft Windows
PINsafe Upgrade on Appliances
Appliance System Preparation
Determine which version of the appliance is being used, see Appliance types FAQ
The following steps are required for all PINsafe upgrades on an appliance.
Access the command line, and create a temporary backup area:
mkdir /root/upgrade
Upgrading PINsafe Standalone Appliance
Login to the PINsafe administration web interface on the appliance.
Change PINsafe Mode to ‘Slave’, and change the Database to ‘shipping’.
Login to the appliance:
Stop Tomcat:
service tomcat5 stop
Now proceed with the upgrade process described below Upgrading from Versions 3.2-3.8 on the primary appliance. After upgrading the primary appliance repeat the process for the secondary appliance.
Upgrading PINsafe Active/Passive Appliances
A HA A/P pair uses disk replication between two appliances, therefore upgrading the primary appliance will automatically upgrade the standby. However to prevent the cluster from switching over, the service that monitors Tomcat will need to be stopped.
Login to the PINsafe administration web interface on the Primary appliance.
Change PINsafe Mode to ‘Slave’, and change the Database to ‘shipping’ (PINsafe 3.2 or later only).
Login to the Secondary appliance:
Stop Monitor and Heartbeat:
service mon stop service heartbeat stop
This will prevent the Passive appliance taking over whilst Tomcat is stopped on the Active appliance.
Login to the Primary appliance:
Stop Monitor and Tomcat:
service mon stop service tomcat5 stop
Do NOT stop heartbeat on the Primary appliance.
Now proceed with the upgrade process described below Upgrading from Versions 3.2-3.8 on the primary appliance.
Upgrading PINsafe Active/Active Appliances
A HA A/A pair uses DB replication between two appliances, therefore both appliances will require upgrading, as the PINsafe configuration file is not part of the replication. However to prevent the cluster from switching over, the service that monitors Tomcat will need to be stopped.
When upgrading to PINsafe 3.5 or higher, ensure PINsafe appliance permissions are correct
Ensure databases are correctly synchronised between PINsafe appliances.
If a Virtual IP is NOT being used ignore all heartbeat related commands.
Login to the PINsafe administration web interface on both appliances.
Change the PINsafe Mode to ‘Slave’, and change the Database to ‘shipping’ (make a note of the DB currently being used).
Login to Standby appliance:
Stop Monitor, Heartbeat and Tomcat:
service mon stop service heartbeat stop service tomcat5 stop
If the appliances are using a virtual IP, this will prevent a fail-over taking place.
Login to the Primary appliance:
Stop Monitor, Heartbeat and Tomcat:
service mon stop service heartbeat stop service tomcat5 stop
If the appliances are using a virtual IP, this will prevent a fail-over taking place.
If MySQL is being used to replicate the DB, create a secure copy. If Oracle or another external DB is being used to provide PINsafe DB replication ensure that a valid DB backup is taken.
Login to the Primary appliance:
Backup MySQL replicated DB (enter command on one line):
mysqldump --single-transaction --flush-logs pinsafe_rep > /root/upgrade/mysql_rep_backup_$$.sql
Now proceed with the upgrade process described below Upgrading from Versions 3.2-3.8 on the primary appliance. After upgrading the primary appliance repeat the process for the secondary appliance.
Upgrading PINsafe DR Appliances
Login to the DR, appliances and ensure PINsafe Mode is et to ‘Slave’, and change the Database to ‘shipping’
Follow the Upgrading PINsafe Generic Information
After the upgrade ensure PINsafe has been upgraded as expected
Ensure PINsafe is functioning as expected
Ensure PINsafe servers are set back to the correct database type and Mode
Upgrading from Versions 3.2-3.8
The WEB-INF directory is located under /usr/local/apache-tomcat-x.x/webapps/pinsafe
1. It is highly recommended that you take a copy of the entire …/WEB-INF/ folder but specifically ensure steps 2-4, and 5-6 if relevant, are completed.
cp –rp /usr/local/tomcat/webapps/pinsafe /root/upgrade/
2. Back up the PINsafe configuration by taking a copy of .../WEB-INF/conf/config.xml to a safe location.
cp –p /usr/local/tomcat/webapps/pinsafe/WEB-INF/conf/config.xml /root/upgrade
3. Back up the PINsafe ranges file by taking a copy of .../WEB-INF/conf/ranges.xml to a safe location.
cp –p /usr/local/tomcat/webapps/pinsafe/WEB-INF/conf/ranges.xml /root/upgrade
4. Back up the PINsafe ranges file by taking a copy of .../WEB-INF/conf/config.properties to a safe location.
cp –p /usr/local/tomcat/webapps/pinsafe/WEB-INF/conf/config.properties /root/upgrade
5. Back up the PINsafe User Repository by taking a copy of .../WEB-INF/data/repository.xml to a safe location.
cp –p /usr/local/tomcat/webapps/pinsafe/WEB-INF/data/repository.xml /root/upgrade
6. Back up the PINsafe user data by taking a copy of everything under .../WEB-INF/db to a safe location. This is only relevant if you are using the Internal database.
cp –rp /usr/local/tomcat/webapps/pinsafe/WEB-INF/db /root/upgrade
7. If you have any custom transport classes, note that classes from 3.5 or earlier are not compatible with 3.6, 3.7 or 3.8. Check with Swivel Secure if there is an upgrade available. As a matter of principle, when Swivel Secure develops a custom transport class for a customer, it is included as a standard component in the next release of PINsafe. Please check with Swivel that your transport is available and/or still valid before upgrading.
8. Back up the PINsafe logs by taking a copy of everything under .../WEB-INF/logs to a safe location. The upgrade will not fail if you do not backup logs, but you will not be able to view old log entries.
cp –rp /usr/local/tomcat/webapps/pinsafe/WEB-INF/logs /root/upgrade
9. If the Internal, or MySQL DB is not being used, backup the DB driver file ../WEB-INF/lib (check with Swivel Secure the name of the driver file).
cp -p /usr/local/tomcat/webapps/pinsafe/WEB-INF/lib/<driver>.jar /root/upgrade
10. Remove the current PINsafe installation by deleting the pinsafe.war file. Tomcat will remove the associated directory.
service tomcat5 start rm –f /usr/local/tomcat/webapps/pinsafe.war service tomcat5 restart
11. Copy new pinsafe.war file to the webapps folder.
cp –p /root/pinsafe.war /usr/local/tomcat/webapps
12. Stop the Tomcat service.
service tomcat5 stop
13. Restore the config.xml file to .../WEB-INF/conf/config.xml
cp –p /root/upgrade/config.xml /usr/local/tomcat/webapps/pinsafe/WEB-INF/conf
14. Restore the ranges.xml file to .../WEB-INF/conf/ranges.xml
cp –p /root/upgrade/ranges.xml /usr/local/tomcat/webapps/pinsafe/WEB-INF/conf
15. Restore the config.properties file to .../WEB-INF/conf/config.properties
cp –p /root/upgrade/config.properties /usr/local/tomcat/webapps/pinsafe/WEB-INF/conf
16. If an internal database is being used, restore the database.
cp -rp /root/upgrade/db/* /usr/local/tomcat/webapps/pinsafe/WEB-INF/db/
17. If an XML repository is being used restore the repository.xml file.
cp –p /root/upgrade/repository.xml /usr/local/tomcat/webapps/pinsafe/WEB-INF/data
18. Restore your custom transport classes if relevant.
19. Restore the old log files.
cp –rp /root/upgrade/logs/* /usr/local/tomcat/webapps/pinsafe/WEB-INF/logs
20. Restore the JDBC driver file if you backed it up (replace the name of the driver with the name used previously)
cp -p /root/upgrade/<driver>.jar /usr/local/tomcat/webapps/pinsafe/WEB-INF/lib/
21. Ensure that the ownerships and permissions on the files that have been restored are correct.
chown –R swivel:swivel /usr/local/tomcat/webapps/pinsafe chmod –R 775 /usr/local/tomcat/webapps/pinsafe/WEB-INF/db
22. Start the Tomcat service.
service tomcat5 start
Standalone Appliance
Login to the PINsafe administration web interface.
1. Test that the configuration has been correctly upgraded.
2. Configure the PINsafe DB for use with PINsafe 3.8 by changing the Database back to the value prior to the upgrade. Check logs for errors.
3. Check users have been correctly migrated, and test a user can authenticate.
4. To start AD updates, change the PINsafe Mode to ‘Synchronized’.
Active/Passive Appliance
1. Test that the configuration has been correctly upgraded.
2. Configure the PINsafe DB for use with PINsafe 3.8 by changing the Database back to ‘internal’. Check the logs for any errors.
3. Check users have been correctly migrated, and test a user can authenticate.
4. To start AD updates, change the PINsafe Mode to ‘Synchronized’ (PINsafe 3.2 or later only).
Login to the Primary appliance:
Start Monitor:
service mon start
Login to the Secondary appliance:
Start Monitor and Heartbeat:
service heartbeat start service mon start
Active/Active Appliance
If a Virtual IP is NOT being used ignore all heartbeat related commands.
Login to the PINsafe administration web interface on the Primary appliance.
1. Test that the configuration has been correctly upgraded.
2. Configure the PINsafe DB for use with PINsafe 3.8 by changing the Database back to the value prior to the upgrade. Check logs for errors.
3. Check users have been correctly imported, and test a user can authenticate.
Login to the PINsafe administration web interface on the Standby appliance.
4. Test that the configuration has been correctly upgraded.
5. Change the PINsafe DB for use with PINsafe 3.8 by changing the Database back to the value prior to the upgrade. DB will already have been updated by the Primary.
Check users have been correctly imported, and test a user can authenticate.
Before continuing ensure that the primary and standby appliances have been upgraded to PINsafe 3.8
6. To start AD updates, change the PINsafe Mode to ‘Synchronized’ on the Primary appliance, and then the Standby appliance if required.
Login to Primary appliance:
7. Start Heartbeat and Mon:
service heartbeat start service mon start
Login to Standby appliance:
8. Start Heartbeat and Mon:
service heartbeat start service mon start
Additional Information
After upgrading you may see that any repository you had will exist on the new installation and it will be named after the associated hostname (or hostname followed by context in the case of the XML repository). Therefore if you had an AD repository in 3.2 you will have an XML repository in 3.3 named after the AD server's hostname (or IP address)
If you had an AD repository on your 3.2 installation you will now have the option to add an XML repository. It is recommended that you do this as this gives you the ability to create admin accounts whilst you are working on the installation
