TN 5: Special notes before upgrading from KeyServer 5.x

Upgrading from 5.x to 7.x must be undertaken with much greater caution than upgrading from 6.x. Read this entire document first.

2011.10.07 (reviewed)

There are many changes to both the management interface and functionality when upgrading to 7.x from KeyServer 5.x. The general steps for upgrading to version 7.x are described here, but if you are upgrading specifically from 5.x, be sure to read all of the cautions in this document. Before proceeding at all you should familiarize yourself with K2 – be sure to run through the Quick Start Tour!

5.x Upgrade Caution: Starting with K2 and KeyServer version 6, when a client computer (i.e. a computer with KeyAccess installed) first logs in to KeyServer, a client record is created in the Computers table in order to support the new K2 features (e.g. computer hardware and software audits). Your custom License Certificate (server.lic file) specifies the maximum size of this table. In KeyServer 7.x, all computer records that are set to Dedicated or Leased are counted towards your seat count, and when they reach that limit, no service will be provided to additional clients regardless of how many computers are actually connected to the KeyServer currently!

KeyServer versions before K2 (e.g. KeyServer 5.x) have always had the same maximum client count specified in the License Certificate (server.lic file) but without a persistent Computer client table, it was easy to over deploy the client software. In K2, records are added in the Computers window as “Dedicated” or “Leased” clients (clients which are allowed to Login) until your licensed KeyServer maximum is reached . Any additional client connection attempts will be greeted with the message: “You do not have permission to login”. A new entry will still be added to the Computers list but only as a “Dormant” item – it won’t count against your licensed total for KeyServer clients. Note: when Leased client computers become inactive at your site (e.g. they have been deployed elsewhere, replaced, disposed of, etc.), they will automatically be moved to Dormant, and will make way for new clients. Likewise, if you have any Dedicated computer records which you know will not come back, you can manually change them to Dormant or Prohbited. The Computers window shows the last login time for each client, so any abandoned Dedicated client records are easy to sort out and deal with.

Before upgrading from 5.x to KeyServer 7.x, run the Client report against your existing 5.x KeyServer logs. This will show you the actual number of unique clients you may need to support with your 7.x server.lic - depending on which clients still actually log in to the KeyServer. KeyServer 5.x did not create persistent client records, so you may discover that you have inadvertently installed more clients than are actually allowed by your License Certificate. Make sure you have a valid 7.4 License Certificate (server.lic) with support for a sufficient number of clients. Also be sure to follow the steps below in order to avoid losing support for managed software that you have already deployed under KeyServer 5.x control.

The upgrade to K2 from KeyServer 5.x is similar to the upgrade from 6.1 or 6.0 but with a preceding step (step 0), and some configuration steps that must be done using KeyConfigure after the installer has finished.

0. Move the folder containing version 5.x KeyServer to the new standard location.

The KeyServer 5.x folder is normally found at "C:\Program Files\KeyServer 5.x\". In order to prepare for the upgrade from the previous install, this folder must be renamed and moved into the new standard location for K2. Create a new folder "Sassafras K2" in Program Files, rename the "KeyServer 5.x" folder to "Server", and move it inside the "Program Files\Sassafras K2\" folder. The resulting "C:\Program Files\Sassafras K2\Server\" will be used as the basis for the upgrade. The installer will then move this folder aside, giving it the new name "C:\Program Files\Sassafras K2\5.x Server BACKUP\". Note that if you are on a 64 bit Windows OS, the Sassafras K2 folder should already be in Program Files (x86) - this is the correct location on 64 bit OS's.

On Mac OS X, the standard location for any version of KeyServer is /Library/KeyServer/ . The installer will use whatever previous version is found here as the basis for an upgrade. Note: there is normally an alias file named "Server" located in "/Applications/Sassafras K2/" that points to "/Library/KeyServer/".

1-3. Install a "server.lic" / run the K2Server installer / restart the KeyServer process.

These three steps are described in detail in the Major version upgrade Document - be sure to read the entire section including comments concerning Admin requirements.

4. Connect with KeyConfigure 7.4 using the account name “Administrator” and the default password “Sassafras”.

Your old 5.x password is not preserved by the upgrade from 5.x to version 7.x !


After running the upgrade install from 5.x as described in steps 1-4 above, there are several things to check using the KeyConfigure interface: