How to Upgrade an Appliance and Swivel
Contents
Overview
How to update an Appliance and the Swivel core using a Patch file located under Downloads. It is advised that the Appliance and Swivel are kept upto date - please see Versions FAQ for the latest features, bug fixes and improvements.
Once the appliance has been upgrade successfully, then the next step is to upgrade the Swivel core.
Upgrading a Single Appliance with the Swivel Patch will lead to downtime, whereby users will NOT be able to authenticate. However, with an Active/Active pair, users will still be able to authenticate as only one server is upgrade at a time.
Prerequisites
- Appliance (Physical or Virtual) running the Command Management Interface (CMI) - also see PuTTY How To Guide.
- Requires a minimum level of appliance version 2.0.9a.
- Only one Patch may be applied at a time - Appliance patch first, followed by the Swivel patch.
- Backup custom changes - Custom changes such as Single Channel images may be overwritten on an Uupgrade and should be backed up and restored after the upgrade.
- Check which database is being used, if it is not 'Internal' or 'MySQL' being used, please see External DB used.
- Backup the Appliance and Swivel, using the Backup & Restore options on the CMI.
Please Note - Do NOT unzip any of the patch files.
Appliance
Please Note - It is recommended to take a full backup of the Appliance and Swivel - This can be done from the CMI under Backup & Restore Options. Also, if you are using a Virtual Machine (VM), then you can take a Snapshot.
1. Download the Appliance Patch file (patch.2.0.xx.xxx.tar.gz) to the Appliance using SFTP - Please see WinSCP How To Guide. If the downloaded patch file begins with an uppercase 'P', please change it to a lowercase 'p'.
2. Upload the patch "/backups/upload" directory.
3. Login as "admin" on the CMI (i.e via PuTTY).
4. Select the Advanced Menu.
5. Select "Update Appliance/Swivel" - This option only appears when the patch file has been uploaded (and the file is all in lower case - e.g. patch.2.0.xx.xxx.tar.gz NOT Patch.2.0.xx.xxx.tar.gz)
6. Select "Install new patch file".
7. Select "Import patch file: patch.2.0.xx.xxxx.tar.gz
8. Select "Display Patch Information" and read the Release Notes.
9. Select "Apply Patch".
10. Confirm that the Appliance patch was upgraded successfully,
11. Logout of the CMI.
12. Log back into the CMI.
13. Navigate to Advanced Menu > Version Information and confirm that the Appliance Build is now showing the new version number.
Please Note: Once a patch is applied, it is cleared up automatically.
Video Walkthrough
Swivel
1. Download the Swivel Patch file (patch.3.x.x.xxx.swivel.tar.gz) to the Appliance using SFTP - Please see WinSCP How To Guide. If the downloaded patch file begins with an uppercase 'P', please change it to a lowercase 'p'.
2. Upload the patch "/backups/upload" directory.
3. Login as "admin" on the CMI (i.e via PuTTY).
4. Select the Advanced Menu.
5. Select "Update Appliance/Swivel" - This option only appears when the patch file has been uploaded (and the file is all in lower case - e.g. patch.2.0.xx.xxx.tar.gz NOT Patch.2.0.xx.xxx.tar.gz)
6. Select "Install new patch file".
7. Select "Import patch file: patch.3.x.x.swivel.xxxx.tar.gz
8. Select "Display Patch Information" and read the Release Notes.
9. Select "Apply Patch".
10. Confirm that the patch was applied successfully.
11. Navigate to Advanced Menu > Version Information and confirm that the Swivel Version is now showing the new version number.
12. Finally, log into the Swivel Admin Console to ensure the version number in the top right corner has updated and all the users and configuration appears as expected.
How to Upgrade an Active/Active pair (HA)
Please take a Full Backup prior to performing an upgrade on both servers; this can be done by navigating to Backup & Restore Options on the CMI. In addition, if you are running a VM, then you can take a Snapshot aswell as performing a backup.
Also, it is recommended to upgrade the Standby first and once this has been upgraded successfully, then you can proceed with upgrading the Primary server.
Appliance
1. Follow the steps outlined under the section Appliance. Upgrade both servers then the next step will be to upgrade Swivel.
Primary
2. Select "Database" ("MySQL" on older Appliances), then "Command Line". Run the following commands:
stop slave; exit;
Note: If the MySQL Command Line Fails or Abort, drop onto the Appliance Command Line and run the command: mysql - this will drop you onto the MySQL Command Line.
Standby
3. Repeat step 2 on the Standby appliance.
4. On both servers, ensure that the Databases are not replicating. This can be checked under Database (or MySQL) > Synchronisation Status.
5. On the Standby server, from the Main Menu of the CMI, Stop Monitor and Heartbeat.
6. Log into the Standby Swivel Administration Console.
7. Navigate to RADIUS > Server, and ensure that Server Enabled is set to No. Click Apply.
8. Click Database > General and change the Database from MySQL 5 to Shipping. Click Apply.
9. Navigate back to the SFTP platform (i.e WinSCP, FileZilla).
10. Follow the steps outlined under the section Swivel - Starting with the Standby server.
11. Once the Standby server has been upgraded successfully. Log into the Standby Swivel Admin Console.
12. Click on Database > General and change the Database back to MySQL 5 and Apply.
13. Click on RADIUS > Server, and change Server enabled to Yes and Apply.
14. On the Standby CMI, Start Heartbeat and Monitor from the Main Menu.
Primary
15. Follow Steps 5 to 14 on the Primary Server.
16. Once the Primary server has been upgraded successfully, from the Primary CMI, navigate to Database (MySQL) > Synchronisation Status > Re-Sync DB (or Sync DB on older Appliances). Typically you would select Database on Primary Applinace as the data from the Primary will be copied across to the Standby.
17. From the Standby CMI, ensure that Database > Synchronisation Status is showing that the Databases are Synchronised.
18. Upgrade Complete - check both Servers to ensure the config has remained and the correct number of users are displaying from the Swivel Admin Console.
Video Walkthrough
FAQ
What steps can I take to ensure that I have a Roll Back plan?
It is already recommended to take a Full Backup (via the CMI - Backup & Restore Options), therefore you can Restore from a backup if you needed to roll back. Also, if you are running a Virtual Machine (VM), then you can take a Snapshot in addition to taking a full back up.
Troubleshooting
Previous version of the Appliance is displayed on the CMI
Logout of the CMI session and log back in again - Confirm the version number has updated under Advanced Menu > Version Information.
Patch file not located
Ensure that the patch file name starts with a lower case p e.g. patch.xxx.xxx.tar.gz and NOT Patch.xxx.xxx.tar.gz
No upgrade option in the CMI
This options is only available when the patch file is present on the system, see also case above.
Also if the file name has been modified in another way such as replacing . with _ this can stop the menu item appearing.
MySQL Command Line not functioning under the Database Menu
Log into the Command Line via the Advanced Menu and run the command: mysql - this will drop you onto the MySQL Command Line.
Swivel version listed as "el"
The Swivel 3.10 patch will incorrectly display the Swivel version as "el". Although it does not display the correct version, this can be ignored if the Swivel Administration console displays the correct version. Appliance patch 2.0.16 resolves this issue.
External DB Used
If you are using a database other than 'Internal' or 'MySQL', the Java JDBC database drivers are NOT copied across from the previous Swivel application. The easiest way to ensure that the database drivers are included is to copy them to the Tomcat common library. Make sure you do this BEFORE you apply this patch. If you forget, and Swivel gives an error after upgrading, copy the drivers to the specified location and then restart Tomcat. Ensure that you set the owner and group for the file to swivel if necessary. It is suggested to use an SFTP client to copy the files.
Source: /usr/local/tomcat/webapps/pinsafe/WEB-INF/lib Destination: /usr/local/tomcat/common/lib
Swivel Will Not Start
Restart Tomcat. If the Swivel RADIUS erver has not completed shutting down, it may prevent RADIUS from starting.
Check the latest /var/log/tomcat logs for errors, the catalina.out file may show the following message:
RADIUS server failed to start, error: com.theorem.radserver3.RADIUSServerException: RADIUS authentication server receiver thread failed to start: Failed to create RADIUS server socket on port 1812: java.net.BindException: Address already in use.
Check the latest /var/log/tomcat logs for errors, the catalina.out file may show the following message:
Servlet /pinsafe threw load() exception java.io.FileNotFoundException: /home/swivel/.swivel/conf/cache.xml (No such file or directory)
If there is an error regarding cache.xml not found then use an SFTP client to copy the multicast-cache.xml to cache.xml as below: Source: /usr/local/tomcat/webapps/pinsafe/WEB-INF/classes/multicast-cache.xml Destination: /usr/local/tomcat/webapps/pinsafe/WEB-INF/classes/cache.xml
Helpdesk cannot see users
If upgrading from an older Swivel version, then the Helpdesk permissions may need to be set. Login to the Swivel administration console as an admin user, on the bottom of the Repository -> Groups page you will see a button entitled 'Group Rights'. When you click this button it will open the 'Helpdesk Group Management' screen. The table allows allocation of Helpdesk users to manage particular user groups, or, from the drop down there are specific options too e.g. 'Helpdesk users all groups'. See also Helpdesk Configuration Guide
User Transports are absent
Please see: Transport Absent After Upgrade.
