KSdbConsist

KSdbConsist must be run when upgrading to KeyServer 8.0 from any earlier major version (e.g. 7.7, 7.2, 6.2, etc) in order to transform various database files to the new 8.0 format. KSdbConsist is run automatically as part of an install or upgrade of the KeyServer component and it can also be run manually at any time whenever the KeyServer process has been stopped. KSdbConsist is designed to do an extensive set of tests to ensure consistency within the various databases contained in the KeyServer Data Folder. It will repair any errors which it finds and also it may warn of configuration issues that should be cleaned up using the KeyConfigure interface. There is an optional feature that allows you to split off old usage records (concerning events prior to a specific date) from the Usage log file.

Running KSdbConsist

KSdbConsist cannot be run on an active data folder and it must be run with admin privileges so it can read and write in the target KeyServer Data Folder. By default, KSdbConsist is pointed to the KeyServer Data Folder in the standard install location. Assuming this is the data you want to inspect and repair, you must stop the KeyServer process before launching KSdbConsist. Alternately, KSdbConsist lets you browse to select an offline Data Folder stored anywhere in your local file system.

Once a data folder has been chosen (either by default or explicitly), KSdbConsist will display an approximate guess for how long the checks will take. Depending on what data problems are encountered, the actual time may be longer or shorter than the estimate. Canceling KSdbConsist before it has completed will leave all original data in place without modification. KSdbConsist always creates a date stamped folder and activity report (.ksr) inside the Backup Folder (within the KeyServer Data Folder). In the case where a data file was repaired, the corresponding, original, untouched data file is moved into this same folder along with the report. The worst case disk space requirement (repair all the data files) can therefore be estimated by totaling the size of all top level files in the KeyServer Data Folder - excluding all sub-folders.

KSdbConsist Window

OS X

Since KeyServer runs as root, and the various databases are owned by root, KSdbConsist will ask for admin authentication when it starts up.

Windows

KSdbConsist should be run from the same account which runs KeyServer. The KeyServer process (ks.exe) normally runs as a service, so KSdbConsist should be run from an admin account.

Linux

On Linux, KSdbConsist does not exist with a user interface. Instead, there is a command line version named “dbconsist”, which has exactly the same functionality. Run this from the terminal with the following command:

dbconsist -k "/usr/local/k2/KeyServer Data Folder"

If you ave installed KeyServer in a different directory, you will need to modify this command to indicate the correct location of your KeyServer Data Folder. Run the command as root (or with an account that has sufficient privileges to read and write the files in the KeyServer Data Folder.

Calling the binary with no parameters will output the help. Note that for archiving usage data the date format is YYYYMMDDHHMMSSL where the L indicates use Local time zone.

Output

KSdbConsist will show a summary once it completes all tests. Usually the summary will either say that there were no errors, or that some errors were fixed. If KSdbConsist notices a large number of errors, or certain serious errors, it will advise you to contact Sassafras Software Support for further advice. In all cases, KSdbConsist will write a .ksr file which contains detailed information on everything it found and fixed. This file can be found within a sub-folder named "dbconsist ..." inside the Backup Folder (in the KeyServer Data Folder) . This "dbconsist ..." folder will also contain the unaltered originals of any files which were copied and repaired.

Cases requiring additional attention

KSdbConsist can fix almost any error it notices. However, there are a few cases that require additional actions by the administrator.

• If you see a message like "KeyServer seat count was 96, changing to 110!", it means that KeyServer was not properly counting the number of clients which have been given full access to the KeyServer. This has no real affect if both the original number and the corrected number are smaller than your license count. However, if the new number is higher than your license count, you should use KeyConfigure to identify some computer records which can be either deleted or set to excluded. Otherwise, any new clients trying to connect to KeyServer for the first time will be denied.
• If you see a message like "Your data may contain duplicate computer entries." You should run the Duplicate Names (COMP) report from KeyConfigure - you may have more than one computer record for the same physical computer or multiple computers may be configured with the same name. KeyAccess will try its best to identify each distinct computer with a static, unique ID and KeyServer will create a corresponding computer record. However, KeyAccess will occasionally have to abandon an old ID (when hardware is changed or the OS hardware queries return a different response). For example, if KeyAccess is using the computer's MAC address (network hardware address) as its ID, but then at some point it starts up and cannot find the same MAC address it has been using, this ID and corresponding record will be abandoned and a new ID and computer record will be created. Therefore, for a single computer, you may see one computer record which has not been used for months, and another record which is current. In this case, you should delete (or prohibit) the old entry so that it will not count towards your KeyServer client limit. The Duplicate Names (COMP) report is designed to help you identify these duplicate computer records. It will show computers which have the same name and MAC address, but different computer ids. See the documentation on reports for more details.
• If you see a message like "You should use KeyConfigure to either increase node limits for some policy, or delete computers from the computer list.", it means that there was at least one node policy where the number of computers on the node list exceeds the policy limit. Since this violates the policy configuration, you should either increase the limit for the policy or remove some computers from the node list. Open the .ksr file that is saved in the Backup folder in order to see a list of specific policies that had this problem.