Move PINsafe How to Guide

Overview

This document outlines some of the best practices when moving a Swivel install or configuration and data from one instance, the source, to another, the destination.

Prerequisites

Swivel server or virtual or hardware appliance

Backup Swivel before any work is carried out

Ensure Swivel versions are the same between installations. If Swivel is to be upgraded as part of the process, verify the upgrade during testing.

Ensure that the Time zones are the same for all Swivel installations.

It may be necessary to schedule some downtime

Moving Swivel configuration and data from one install to another

Stop Tomcat on both old and new instances, copy the following files from the original installation to the new installation, then start Tomcat. For information on copying Swivel files on virtual or hardware appliances see Copying appliance files How to Guide.

Swivel File locations

Swivel 3.9.1 onwards

The Configuration and local data (Known as the Transient Data Storage), is stored in the .swivel folder, on virtual or hardware appliances this is:

/home/swivel/.swivel

On software installs this is dependant upon the installation such as c:\users\<username>\.swivel or c:\.swivel

Note this does not include java class files, such as those for transport classes or database drivers, these may need to be copied manually.

Swivel 3.9 earlier

<path to Tomcat>/webapps/pinsafe/WEB-INF/conf/config.xml

<path to Tomcat>/webapps/pinsafe/WEB-INF/conf/ranges.xml

Ensure any customisations are also copied, see Transport Configuration.

<path to Tomcat> for virtual or hardware appliances is /usr/local/tomcat.

Moving Swivel user data from one Swivel install to another similar install

Timezone

Determine Timezone of original Swivel installation. The new Swivel installation must be the same timezone. If you cannot login and receive errors regarding no PIN or invalid PIN, it is likely that the timezone is not that of the source.

Certificates and Keystore

A new SSL certificate can be requested for the new Swivel instance.

Another method if the hostnames are the same from the old Swivel instance and the new Swivel instance, may be to copy across the keystore. See also Moving Swivel Keystore

The keystore file location on a virtual or hardware appliance should be listed within your /usr/local/tomcat/conf/server.xml file, but the default keystore file location is:

/home/swivel/.keystore

(it's a hidden file with the '.' prefix)

The method would involve:

- Take a backup of the existing /home/swivel/.keystore file on the source and destination

- Make a note of the permissions assigned to the file, by default they are swivel:swivel 600

- Copy in the source .keystore file to the same location on the destination. See Copying appliance files How to Guide

- Run the following commands to ensure the permissions are set to their defaults:

chmod 600 /home/swivel/.keystore

chown swivel:swivel /home/swivel/.keystore

Where the source and/or destination is not a Swivel virtual or hardware appliance then the keystore password may be different and need to be set in the Tomcat server.xml file located under <path to Apache Tomcat>\conf

- Restart Tomcat

Moving from a standalone install to an Active/Active install

Swivel configuration and data can be manually setup through the administration console of the new instances or can be copied from a standalone installation to a Active/Active installation, however there are some additional considerations and settings that differ between each Active Active instance and will need to be configured separately, these include:

• Local XML repository names need to be different and contain unique usernames
• Server Name
• RADIUS Server IP where configured (usually left blank)
• Repository Sync times need to be different on the Primary Master and Standby Master
• Filter, if a filter is defined then this may need to be changed, see Filter IP How to Guide

An alternative is to copy the data and configuration to the primary and configure the standby manually.

Swivel configuration data is contained is contained within the file config.xml (see Swivel File locations above).

Exporting Databases to the Internal Swivel Database

• If the Swivel database is external and is not not being moved then the data does not need to be exported, the Swivel instance can point to the database after being moved.
• If a database external to the Swivel application is being used then the data can be copied to the internal Swivel database. As an internal Swivel database, the data can then be moved and exported to a new database or left using the internal database.
• If the database is the same type, and can be ported such as through a MySQL dump, see MySQL Database Export and Import
• For internal databases the data can be copied across to the new instance. If the destination is to be another database type then it can be Migrated at the destination (this will only need to be done once).

On the original Swivel installation, Migrate Data to internal Db. In the Swivel Administration console select Migration, and then select Internal as the target destination and enter the word "MIGRATE" to confirm migration. Note that this doesn't actually move the active database to Internal, it just makes a copy of the MySQL database in the Internal database. See also Migrate How to guide.

Moving the Internal Swivel Database

If the entire conf folder is moved then local repositories are copied across. To carry this out as a separate move then copy Swivel data in the db folder (see Swivel File locations above), to new Swivel Primary server. to do this stop Tomcat on the Swivel instance, when using the virtual or hardware appliance use the CMI to select Tomcat, then Stop. You now need to copy the database and configuration from the virtual or hardware appliance. We recommend using a tool such as WinSCP, see WinSCP How To Guide. Remember to check file and ownership permissions.

Moving the Swivel local XML Repository

If the entire conf folder is moved then local repositories are copied across. To carry this out as a separate move then stop Tomcat on source and destination then copy the repository data/repository.xml (see Swivel File locations above), from the source to the destination, then start Tomcat. Remember to check file and ownership permissions.

Importing Data on the new Swivel installation

If the data has been imported directly into a database external to the Swivel application, such as through a MySQL dump, then configure Swivel to use that database and do not Migrate the data, see MySQL Database Export and Import

Where data is to be imported from the Swivel internal database to another database, the import should only be carried out on one server, for the Swivel virtual or hardware appliance, this will be the Primary Master. Ensure that the Swivel instance is working correctly. Stop Tomcat then copy internal database the db folder (see Swivel File locations above). The Swivel instance should be configured with the database should be set to Internal, and the Mode set to Synchronised. Once the database is copied and the permissions and ownerships are verified as being correct, start Tomcat.

1. On the Swivel Administration console, under Database/General, ensure that the database configuration is set to internal and the new database configuration is correct, but keep the database as internal. For further information see MySQL Database How To Guide. Do not select an external database type such as MySQL until after Migration.

2. Migrate the data on the on destination Swivel installation to the required database. The migration should be carried out on one Swivel server only. On the Swivel virtual or hardware appliance, this should be the primary Master. On the Swivel Administration console select Migration, selecting the configured database as the target destination. Check the logs for any error messages. see also Migrate How to guide.

3. Then select the database. On the Swivel Administration console select Database/General, set the database then apply. Check logs for any error messages.

4. For Swivel virtual or hardware appliances check synchronisation is working. see MySQL Appliance Database Synchronisation

Known Issues

Troubleshooting

Exception occurred during database access, exception: com.swiveltechnologies.pinsafe.server.user.database.DatabaseException: Error opening the internal database

The permissions and/or ownership are not correctly set on the repository, see Permissions and Ownership

admin:The user "xxxxx" cannot be created as an existing user with the same name already exists.

admin:Exception occurred checking agent: com.mysql.jdbc.exceptions.MySQLIntegrityConstraintViolationException: Cannot add or update a child row: a foreign key constraint fails (`pinsafe_rep/PINSAFEJ`, CONSTRAINT `PINSAFEJ_ibfk_1` FOREIGN KEY (`I`) REFERENCES `PINSAFEL` (`A`) ON DELETE CASCADE).

This has been seen on importing internal data from the db folder from version 3.6 to 3.9.5, and them migrating to a MySQL database, and is followed by a user sync. Setting the option under Repository, to allow the user to change repository and then restarting Tomcat resolved the issue, although the logs indicated that the users had been deleted, this was not the case.

Is the timezone on the source, the same as the destination?