Upgrade Steps: Server 7.x -> 8.0

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

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 following detail some things to be aware when performing a major update (e.g. 7.9 or earlier to 8.0)

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

When upgrading from version 7.9.x or earlier, the "ksp-server" installer will set aside the existing server folder and change its name to "server old". The moved aside data files will be used as the basis for creating reformatted data files in the new KeyServer Data Folder. This means you need sufficient drive space for a copy of the data to be made.

Note: in order to save space, the Log Files sub-folder from the original data folder is moved into the new KeyServer Data Folder rather than being copied. Also, the Export Files and Backups folders (if present) are 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 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 8.0 data folder to remain at a non-standard location on Windows, you must specify this during install

On Windows, if your 7.9 (or older) KeyServer data is stored at a non-default location (for example on a non-system drive), the 8.0 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 8.0.x upgrades.

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

Before running the installer to upgrade a 7.x KeyServer installation, you must have a license certificate ("server.lic") that supports version 8.0 in place within the old KeyServer Data Folder. Without a valid 8.0 certificate, the installer will not perform an upgrade. The 8.0 certificate will support the older KeyServer versions – when you obtain your 8.0 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 8.0 server.lic file in its place.

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

An older KeyConfigure (e.g. version 7.9) will not connect to an upgraded 8.0 KeyServer. Before upgrading the KeyServer to 8.0, it will be most convenient to first install KeyConfigure 8.0 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.9 installed, the “Admin” folder will be moved to “7.9 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 8.0 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 8.0, 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.

Additional documentation to read

Even if you are a seasoned Sassafras Server 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:

Older change notes are available if needed via the links in the above pages.

Steps required for upgrade

Here are the steps for upgrading to version 8.0 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 8.0.

The new server.lic file is sent via e-mail when you purchase the 8.0 upgrade, or is sent automatically under your Upgrade Subscription Program entitlement. The text line "license.range=7.5-8.0" in this file means that it will enable any KeyServer version from 7.5 through 8.0 - 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. Use KeyConfigure version 8.0 to connect and verify settings.

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

Check General Settings

In KeyConfigure - Config - General settings, there are various defaults that have updated over time. These are worth verifying.

Under PRS, ensure all options are enabled

Under Audits, consider your schedule interval. Many smaller (3k or less clients) sites will make this daily to ensure software inventory is as up to date as possible when verifying deployments. Generally speaking, all other options (not Throttle) should be on for optimal features.

Under Idle, enable the two checkboxes at the bottom so as to track startup and shutdown and idle events. These allow for more detailed status information on Maps, as well as active vs idle use time in Login reports.

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 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 Software 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.

Review Configuration

In general you should consult our Configuration Review document for advice and best practices. The older the version you are upgrading from, the more likely there are important changes you should be aware of.