Minor Upgrade
For documentation on Upgrades from 8.0 or earlier, refer to the Major Upgrades documentation.
This document describes the procedures for doing Minor updates of Sassafras Software components – i.e. from 8.0.x to 8.0.y as well as adding clients, converting to licensed from evaluation, and moving your server host.
Minor updates are done by simply running the newer installer on a computer where the older version is installed. The installers do not change the essential configuration data:
- Clients will retain their connection information (and portable licenses, if any)
- KeyServer will retain its license management data
- KeyReporter will retain its saved web reports, templates, and schedules
- KeyShadows will retain their setup info (pointing to KeyServer)
- KeyConfigure will retain its templates & preferences
Assuming that the components from a previous 8.0.x install remain in their default location, the corresponding installer will simply update the existing components.
If a component is “busy” or “in use” it will be moved aside to make way for the new version to be put in place. The new component won’t actually execute until you quit and re-launch the component you are installing or until you restart the computer.
On some versions of Windows OS, when a folder is opened for viewing its contents using Windows Explorer then the folder and its contents cannot be changed by any other program – close the Sassafras K2 window (inside the Programs folder) and all its sub-folders before attempting to run any of the Sassafras Software installers.
The sections below give some additional details.
Minor Upgrade of KeyServer
Any upgrade of the KeyServer components should be done with special care since a mistake could affect access to licensed software on all of its clients. Since the KeyServer process must be shutdown during the upgrade, it will be unable to respond to license requests or collect audit and usage data for a period of minutes or even hours if a large data file needs repair. In a typical configuration, clients will tolerate the outage without user disruption because the default setting for unkeyed managed programs is to allow usage when KeyServer not available. Offline usage data will later be uploaded when the KeyServer process is re-started and clients re-connect.
Before proceeding with an upgrade of the KeyServer:
- backing up your KeyServer Data Folder is not necessary, since the part of the upgrade which will make any data changes will automatically make backups. If you do wish to do your own backup, be sure to stop the KeyServer before copying the data files.
- always check the Notes and Warnings document and the Component History for important cautions particular to the version you are about to install.
- if your KeyServer is managing keyed as well as un-keyed programs (or the "Relaxed Enforcement" default has been changed to "Strict" for some policies), you should make sure there is a working KeyShadow process to take care of keyed program launch requests during the upgrade outage.
- if you have installed KeyShadows, plan on also upgrading these to the same KeyServer version ASAP.
The KeyServer installer includes an install of "KSdbConsist" - a utility which is used to check, repair, and reformat configuration and data files from an existing KeyServer Data Folder. The KSdbConsist utility creates a report named "fixed.ksr" which documents any repairs. This report along with a backed up original of repaired file(s) is saved inside the Backup sub-folder within the KeyServer Data Folder. The report file has file extension .ksr - use KeyConfigure to read it.
Doing a minor upgrade simply requires running the new KeyServer installer "on top of" the existing installation. The installer will only make a back up of the existing data files if they will be changed by KSdbConsist - otherwise they are left in place. Existing components (the KeyServer executable and any associated libraries) are overwritten with the new version.
1. Run the Sassafras KeyServer component installer to update the existing KeyServer components..
The KeyServer installer will stop any running KeyServer process. The "KSdbConsist" utility will be launched from within the installer, so you have the option of checking database integrity as part of the upgrade process. If KSdbConsist finds database errors, it will backup any file before making a modification or repair - the original will be moved into the Backup Folder, a sub-folder of the KeyServer Data Folder. When doing a minor upgrade, it is recommended that you take the time to let KSdbConsist complete its check of all data. But even if you cancel the KSdbConsist run, the KeyServer components will still be upgraded since a "minor" upgrade does not require any data format changes.
2. Restart the KeyServer service.
In order to activate the new software version, be sure to start the KeyServer process. On Mac you will be presented with a dialog offering to start KeyServer. On Windows you will see a similar dialog the first time you install KeyServer, and every subsequent install will either start or not start KeyServer depending on the choice made on the first install. In order to start KeyServer manually on Windows, use the Services Control Panel.
Minor Upgrade of KeyConfigure
Before running the Admin installer, quit KeyConfigure. The version 8.0 Admin installer looks for the “Admin” folder inside the “Sassafras K2” folder. If the Admin folder already contains KeyConfigure 8.0.x, the installer simply updates all the 8.0 components.
Minor Upgrade of KeyAccess
Upgrading KeyAccess is very easy - simply run the new installer and then reboot the computer. There are no special considerations to take into account.
It is best to keep your clients up to date with the latest KeyAccess version to avoid wasting time on bugs that have already been fixed. Consult the Notes and Warnings document and the Component History for specific documentation of bug fixes and known issues. In order to make KeyAccess upgrades easier you may want to consult the Deployment document.
Additional Clients
In order to increase the number of clients supported by an existing KeyServer, you will need a new "server.lic" file from Sassafras Software that is configured with an increased client count. Move the old server.lic out of the KeyServer Data Folder and replace it with the new one - then stop and restart the KeyServer process.
When the licensed maximum number of Leased and Dedicated records have been created in KeyServer's Computers window, any newly discovered clients will be assigned Login status: “Dormant”. This will allow them to attempt to login again in the future, when there may be space if existing Leased clients have fallen to Dormant.
When upgrading your license count, it is probably a good time to also update the server components. Use the KeyConfigure "Check Versions" button (in the "About KeyConfigure" dialog) to see if your components are up to date. From the Help menu also check the online Component History and the Warnings document for specific bug fix information.
If you have a KeyShadow installed (in order to support keyed program launches in case KeyServer is temporarily unreachable), you should update its shadow.lic file whenever you increase the client count of your KeyServer. Instructions are detailed in the “Upgrading a KeyShadow” section.
Convert from Eval to Full
Changing from an “eval” installation to a full KeyServer installation is trivial. Simply place your custom server.lic file into the KeyServer Data Folder (see the Complete File List for platform-specific path). Then stop and restart the KeyServer process.
Migrate KeyServer to New Host
If you need to move KeyServer to a new host there are a few basic steps, but you may want to also consult the Deployment Outline for other infrastructure considerations. The data files (but not the software components) contained in the KeyServer Data Folder are the same regardless of which operating system is hosting the KeyServer process. However, some authentication and export methods are supported only on certain hosts, so check the OS Details documentation before migrating to a different host operating system.
If your goal is to upgrade from 7.9 or earlier to 8.0 while also moving to a new host, this must be done in separate stages – first move the older version to the new host without upgrading (follow the steps below) and then continue with the steps outlined in the Upgrade Steps: 7.x-> 8.0 documentation as appropriate.
Follow the steps below to first copy your custom data and then to replace the OS specific components.
1. Run the appropriate ksp-server installer for the new host.
This will create a KeyServer Data folder in the standard install location for the host platform. Don’t start the KeyServer process.
If you are moving 8.0 data to a new host, prepare using a 8.0 installer. When moving 7.9 or earlier data to a new host, prepare using the appropriate 7.9 or earlier installer.
2. Copy the old KeyServer Data Folder
Find the newly created "KeyServer Data Folder" in the standard install location. Delete it and in its place, put a copy of your old “KeyServer Data Folder” duplicated from your old host computer - make sure the old KeyServer process is stopped before copying the data!
3. Run the ksp-server installer a second time.
This will launch the KSdbConsist utility to repair the old data files as necessary - any originals that need repair will be moved into the Backup Folder (inside the data folder). This second run of the installer will also overwrite software components in the copied data folder with the correct binary versions for the new host platform.
4. Startup the KeyServer service.
In order to activate the new software version, restart the KeyServer process - use the services control panel or terminal utility or just re-boot the host computer.
If your clients are using a DNS name to point to the KeyServer, you can simply update the information in your DNS server to follow the KeyServer to its new host address. Otherwise, clients will have to be re-configured using KeyAccess Setup. If you are using shadows, you will also need to run KeyConfigure and create a new shadow license (containing the new server address) - use this to replace the shadow.lic on each of your shadow computers.
Check the firewall documentation and make sure that firewall settings are correct to allow access from all desired client locations and any shadow locations.
5. Connect to the new server with KeyConfigure.
The KeyConfigure admin password is part of the moved data folder, so it is unchanged. Check that your view of all of the KeyServer data is also unchanged.
If you you have used KeyConfigure previously to logon to the new KeyServer host prior to copying your old KeyServer Data folder, you may need to flush its cached memory: at the bottom of each KeyConfigure window, hold down the ctrl (Win) or cmd (Mac) key and click on the word "Refresh".