Upgrade Steps: Server 7.x -> 7.7

This document is written specifically for upgrading from 7.x to 7.7.

KeyServer Upgrade Essentials

Any Minor Upgrade or Major 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. The server installer will take care of preserving your various configurations, but you should still understand the process of upgrading. At a simple level, the upgrade will do the following:

It is recommended you read through this entire document before starting the upgrade as well as the Major Upgrade overview.

Some specific cautions

The paragraphs below describe several important issues to be aware of before performing the upgrade steps. The basic steps are the same when upgrading from either version 7.3 or an earlier version.

The previous KeyServer folder (old version) is set aside.

When upgrading from version 7.4 or earlier, the "ksp-server" installer will set aside the existing server folder and change its name appropriately (e.g. "7.4 Server BACKUP"). The moved aside data files will be used as the basis for creating reformatted data files in the new KeyServer Data Folder.

Note: in order to save space, the Log Files sub-folder from the original data folder is moved into the new KeyServer Data Folder (from "7.4 Server BACKUP") rather than being copied. Also, the Export Files folder (if present) is not carried forward. If it becomes necessary to revert to the prior KeyServer install for any reason, the moved aside backup folder can be quickly put back in place - it is unchanged except for the moved Log Files sub-folder.

The Linux and Solaris installers are not so automated ! - you will have to create your own backup of the existing installation in order to facilitate an instant reversion in case of trouble. However, these installers do move any data file into the folder "KeyServer Data Folder/Backup" whenever a new format file is created (so reversion is possible, without a backup, even though not so simple).

If you want the 7.7 data folder to remain at a non-standard location on Windows, you must specify this during install

On Windows, if your 7.5 (or older) KeyServer data is stored at a non-default location (for example on a non-system drive), the 7.7 Server installer will move the converted data to the default location in C:\Program Files\Sassafras K2\Server unless you select the “KeyServer Data Folder” item within the installer's “Sassafras K2 KeyServer Setup” dialog and browse to the existing Data Folder's Drive/Path during the install. This is necessary because the data folder is now a distinct entry in the installer. Choosing this option once will allow the data folder to remain at that location for any subsequent 7.7.x upgrades.

The version 7.7 KeyServer requires a license certificate, server.lic, that supports version 7.7.

Before running the installer to upgrade a 7.x KeyServer installation, you must have a license certificate ("server.lic") that supports version 7.7 in place within the old KeyServer Data Folder. Without a valid 7.7 certificate, the installer will not perform an upgrade. The 7.7 certificate will support the older KeyServer versions – when you obtain your 7.7 server.lic file via e-mail from Sassafras Software, put it in place even if you don't plan to upgrade immediately. Note: you will have to remove the old server.lic (or just rename it, "server.old") before putting the new 7.7 server.lic file in its place.

The version 7.7 KeyServer requires version 7.7 of the Admin component, KeyConfigure.

An older KeyConfigure (e.g. version 7.6) will not connect to an upgraded 7.7 KeyServer. Before upgrading the KeyServer to 7.7, it will be most convenient to first install KeyConfigure 7.7 on the computer you use as an administrative console. The Admin installer will move aside any old KeyConfigure version that it finds in its standard install location. For example, if you have KeyConfigure 7.6 installed, the “Admin” folder will be moved to “7.6 Admin”. Since multiple KeyConfigure versions can happily coexist on your admin machine, you will then be able to choose the appropriate KeyConfigure in order to manage both your old and new KeyServer versions if necessary during the upgrade transition.

The version 7.7 KeyServer requires new formats for several of its data files.

The installer will run KSdbConsist, which will perform data conversion as necessary. The time required for KSdbConsist to complete its checks, repairs, and data reformatting can vary from minutes to hours depending on the size of the existing data files, as well as whether they need repairs. The Usage Log and the Audit Databases are usually the largest files by far, and therefore the most time consuming to process. The time required can be reduced somewhat by selecting "Don't import Audit Database". The Audit Database will then be rebuilt automatically over the next few weeks based on KeyServer's normal "Reschedule audit every n weeks" setting. Of course historical "base audit" information will be lost by accepting this default - the advantage will be a pruning of orphaned audit records left over from computers that you may have deleted long ago.

Database conversion will require a certain amount of KeyServer downtime, during which "keyed" programs will only run if a KeyShadow is present.

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 is not available ('Relaxed Enforcement'). Offline usage data will later be uploaded when the KeyServer process is re-started and clients re-connect.

If your KeyServer is managing keyed as well as un-keyed programs (or the Enforcement setting for some policies has been changed to "Strict"), you should make sure there is a working KeyShadow process to take care of keyed program launch requests during the upgrade outage. Without a KeyShadow, clients will be unable to use keyed programs while your data is being converted to the new format. If you have keyed programs but no KeyShadow, you should run the upgrade at a time when not many clients are connected.

If your KeyServer is managing many thousands of client computers, you may want to do a "dry run" of the upgrade in order to do some off-line testing.

In this case, follow the procedure described in "Moving KeyServer to a new Host". After testing an off-line KeyServer upgrade, a possible upgrade strategy would be to swap it with the old online KeyServer - but any new usage records collected since the offline upgrade was created would be lost (not to mention configuration changes, if any). Generally, the time and disk space requirements are small enough that it will be simplest just to re-run the upgrade procedure on the active KeyServer.

Fresh install vs upgrade

If you are running a very old KeyServer, you may be tempted to start over with a "clean" install so that you can make fresh license management decisions and get rid of old clutter. Besides the obvious consequence of losing direct access to old usage data, this strategy may also orphan old programs that were previously controlled using the optional "keying" feature.

The crucial data that is required to bring a "keyed" program copy to life is contained in the "License Data" or "Policy Database" file from the KeyServer that was in use when the program was originally keyed. While it is technically possible to import "keys" from these older files using KeyConfigure 7.7, the imported license configuration data may not be complete. It is much better to simply upgrade your existing data. You can then easily reconfigure and delete clutter after the upgrade.

KeyReporter is now installed along with KeyServer - initially disabled until you enable it using KeyConfigure

In earlier versions of the Sassafras Platform, KeyReporter was a separate installer, and could be run either on the same computer as KeyServer or on a different computer. Starting in version 7.2, KeyReporter is part of the KeyServer install and is sub launched by KeyServer (when enabled). This allows tighter integration of KeyReporter with KeyServer and KeyConfigure.

If you are upgrading from a previous installation that included KeyReporter, some manual steps (described below) are necessary in order to preserve scheduled report execution and archived reports.

Additional documentation to read

Even if you are a seasoned Sassafras administrator, it will be wise to take the time to run through the Quick Start Tour. Also consult the appropriate upgrade documents to read about differences in functionality:

If your previous Sassafras installation included KeyShadows, they should be re-installed (not upgraded) as soon as possible after upgrading the KeyServer

Consult the upgrading KeyShadow documentation for the steps to follow.

Steps required for upgrade

Here are the steps for upgrading to version 7.7 from earlier version 7.x. Note: unlike a minor upgrade, canceling KSdbConsist before it is finished will abort the entire upgrade process.

1. Replace the License Certificate file, "server.lic", located inside the KeyServer Data Folder with a new certificate that supports version 7.7.

The new server.lic file is sent via e-mail when you purchase the 7.7 upgrade, or is sent automatically under your Upgrade Subscription Program entitlement. The text line "license.range=5.0-7.7" in this file means that it will enable any KeyServer version from 5.0 through 7.7 - you can immediately use it in place of your old server.lic file, even if you are not ready to upgrade yet.

The standard install location on Windows is either C:\Program Files\Sassafras K2\Server\ or C:\Program Files (x86)\Sassafras K2\Server\ depending on your OS.

The standard install location on Macintosh is /Library/KeyServer/

2. Run the ksp-server component installer - this will use the KSdbConsist utility to check data files.

If KSdbConsist is cancelled before completing, the original KeyServer folder (renamed with the suffix "BACKUP" by the installer) will be moved back to its original location and the upgrade will abort.

3. Ensure that the KeyServer service is running.

On Mac, the installer will prompt you to start KeyServer. On Windows, it will be started automatically if you selected this option the first time you installed KeyServer. If it is not running you can start it manually in the Services control panel - or just re-boot the host computer.

In cases where the Windows KeyServer is running in a Service Account, the Service Account must have a valid password that is reflected in properties of the KeyServer Service in the Service control panel. Furthermore, the Account must have full permissions on the KeyServer Data Folder in order for KeyServer and KeyReporter to properly run. Therefore, it is important to double-check permissions if your KeyServer is configured to run as anything other than the local service account.

4. (optional) Move existing KeyReporter files into the new KeyReporter Data Folder

Beginning with 7.2, the KeyReporter process is hosted on the KeyServer host and all supporting report data is distributed among various sub-folders of the KeyServer Data Folder. Previous versions of KeyReporter had a disjoint data folder, perhaps on a different computer.

If you have a pre-7.2 installation of KeyReporter, you may wish to migrate your old templates, schedules, and archived reports. To locate the old KeyReporter Data Folder, refer to the 7.1 file locations document. After installing 7.7, but before enabling KeyReporter, you can copy:

Templates and Scheduled reports - copy templates.txt from your old KeyReporter data into the sub-folder: 'KeyServer Data Folder\Helper Data\KeyReporter Data Folder\preferences\config\'.

Archived reports - copy all files from three directories in the old KeyReporter data - 'archive-immed', 'archive-save', and 'archive-sched' - into the sub-folder: 'KeyServer Data Folder\Report Documents\Uncategorized'.

The new locations for all of these various files and more are documented in 7.7 file locations.

5. Use KeyConfigure version 7.7 to connect and verify settings.

Use your old KeyServer password - it has been preserved in the upgrade to 7.7. If your old KeyServer was pre-7.2, you will see the KeyReporter Setup wizard soon after logging in.

Enable the KeyReporter process to run on the KeyServer host

If you are upgrading from 7.2 - 7.6, you can skip this section - you already went through this during your upgrade to 7.2. When you login with KeyConfigure 7.7 for the first time after upgrading from KeyServer 7.1 or earlier, you will see a wizard like the one shown below (assuming you are logging in with sufficient privileges):

Wizard after first login with KeyConfigure 7.7

This wizard allows you to configure the ports that KeyReporter will use to support web browsers.

If you are upgrading from a previous installation that included KeyReporter, some manual steps (described below) are necessary in order to preserve scheduled report execution and archived reports. Also be sure to test the new KeyReporter with a browser connection - make sure that both the guest view and authenticated view are configured as you intend. For configuration details, see the KeyReporter Setup documentation.

Enabling PRS

If you are upgrading from 7.1 or later you can skip this section - you already went through this during your upgrade to 7.1. If you are upgrading from version 7.0, you may see a "Product Update Wizard" appear soon after connecting KeyConfigure for the first time.

A Product Recognition Service (PRS) was introduced with KeyServer 7.1 which uses program footprint and installer information found at your site to automatically import appropriate product definitions. This new functionality can change your Program and Product configuration, so only Administrators who have the main "Administrator Role" will have permission to turn on and use the Product Recognition Service.

After upgrading from 7.0 and connecting with KeyConfigure for the first time with the necessary permissions, you will see a wizard like the one shown below:

Wizard after first login with KeyConfigure 7.1

This "Prepare for Product Recognition Service" screen will only be presented when upgrading from an earlier version of KeyServer. After stepping through the preparation steps and updating, the final screen lets you enable the service. A similar wizard will automatically appear any time in the future that PRS needs to add or change Sassafras-defined products which have an affect on Policies.

Click "Update Now" in order to apply all the necessary changes. You will have the option to save a report listing all the Policies affected. If instead you select "Step Through Details", you will see a preview of the changes that need to be made before applying them. For more detail on the other screens of this wizard, see the Product Update Wizard documentation. If you Cancel, you will not be able to turn on the Product Recognition Service.

Once you update products in this first run Wizard, you will see this final screen where by default you will turn on PRS:

Wizard about to enable PRS

When PRS is turned on, it will immediately send some data to the PRS server in order to receive any new product definitions that are relevant to your site. This initial communication, and download of new definitions, should complete within a few minutes. When complete, new definitions will be added to your data, and if these definitions require a variant change that affects any policies, you will again see a very similar Wizard asking you to accept the changes. After importing these new definitions, you will be fully up to date with PRS. PRS will be configured to run nightly. In the future, you will only see this Product Update Wizard when Sassafras creates a new Product definition for something at your site, or when a new Product is installed for the first time at your site.

Check specific preferences

The old default for Audit Interval was once every 4 weeks. In 7.5 we have changed this to once every 2 weeks. If your KeyServer is still configured to audit every 4 weeks (in General Settings under the Audit pane), you might want to change it to every 2 weeks. This just keeps the Audit data more current and up to date.

In 7.4 an option to “Track client computer startup and shutdown” was added, but was not enabled by default. This option allows Availability Maps to distinguish between “Availabile” (computer is on and at the login screen) and “Off” (turned off, or off network). You should consider turning this option on - in the Idle pane of the General Settings dialog.

Update External Tables

If your KeyServer is configured to Export databases, you should adjust the external tables as described in the New Fields section of the Tables documentation.

Switch to using Sassafras-defined products when possible

In version 7.1 and later, we have defined many more products than in version 7.0, and will continue to add more products. You may have had to define your own product for something in 7.0 but now there is a Sassafras definition for that same product. Using Sassafras-defined products allows you to get the benefit of any changes that we decide need to be made, in addition to getting product definitions for new versions of products you already have, when they become available. Simply put, a big part of configuration is shifted to Sassafras instead of needing to be done manually at your site. In order to facilitate switching from custom-defined products to Sassafras-defined products we have included a new report in 7.1 named Product Suggestions (PROD). Basically this report looks for overlap between your definition and Sassafras definitions. It is described in detail in the Reports documentation. We recommend that you run this report once PRS has been turned on and added any relevant products to your data. Using the results of the report, as well as "Replace Product References" from the context sensitive menu, you can change your configuration to use as many Sassafras-defined products as possible. If this report lists many products, you may want to right-click "Referenced" in the Products window, then select "Product Suggestions (PROD)". This will only include custom-defined products that are referenced. So then as you replace references to your custom products, if you refresh the report, it will stop showing products you have already dealt with.

Switch to Family Products when possible

In version 7.6 we introduced Family Products for most Products in PRS. These Family Products contain all Editions of a Product, and are updated by Sassafras as new versions come out. By using a Family in a Policy instead of editions, you essentially future proof your policy. That is, you don't need to remember to look for and add new product versions when they come out, because they will be automatically added by PRS. The new Auto Policy Wizard helps ensure you're aware of Discovered Products and create Observe Policies as desired. For those upgrading old Policies, we have a Tech Note on migration to help guide the process of replacing editions with families in your old policies.