Using the KBC Licence Tester
Table of Contents
This page describes the use of the version of the License Tester delivered with versions before 7.6.
Who should read this
Like many other engineering software products, access to KBC's software is controlled by licensing checks while the programs run. Typically these checks will be against a license server running on your company network, or against license credentials held on your own computer. In both cases, the license system will check license validity by testing either against a hardware key ("dongle") plugged into the server or your PC, or against other characteristics of the computer via keyless licensing. These checks sometimes fail without apparent reason: read these pages if your are an end-user, or an IT professional trying to resolve license errors.
KBC provides a diagnostic tool, the KBC License Tester, to help with your task. For all KBC software issued since 2009, this will be installed on your system by default. Otherwise, you will have to install it separately. Remember to run the Tester on the computer with the problem.
Instructions for installing a license file can be found here.
Common Issues
The most common error will be that the program cannot find a license. Common causes of this are:
- All licenses are in use
- License has expired
- Program cannot find the license server
- License is not installed or available
- Incompatible locking information
- Clock tampering detected
Before getting started, make sure you understand how licensing for KBC software has been implemented at your site. Next, run the Basic Check to get started. Then carefully read through the diagnostics, to pinpoint the cause.
Basic Check
Start the License Tester from the Start menu. The latest version, discussed here, should be under: Start > All Programs > KBC > KBC License Tester
Click the button for Check SIM Suite Licenses or Check Energy Licenses (see below), as appropriate. These carry out and report a standard series of tests. You now have enough to start working out the cause of any problem.
Let's take an example of what happens with a working license on a network, when pressing "Check SIM Suite Licenses". You will first see a response message like this, listing the licenses found:
You will see a similar message generated by the "Check Energy Licenses" button, but referring to different products. Click OK to return to the License Tester and you will see diagnostics reported like this:
The key information is in the Status Information box at the top of the screen and in the Diagnostic text window at the bottom. We can tell from the Info box that licenses are being served from a network computer named calgarywiki. The diagnostics tell us that we were granted a license from server "calgarywiki" and that this is running version 8.3.0.900 of the License Manager software. This is a working license - what happens with a failed license?
Status Information box
Normally, the Status Information at the top is enough to identify the problem. Here are reported the current settings that control how licenses are found. All of this information is also reported in the Diagnostic window at the bottom of the Tester.
KBCLicServers, LSHOST, LSFORCEHOST can all be used to direct the licensing system to the correct license. Each will display <not used>, if the parameter is not set up.
KBCLicServers - KBCLicServers.kbclic is a text file used to direct KBC software to the license location. The last line of the file should either be the name of the license server, or "no-net" for a stand-alone license. The file can be edited (and created) using the Edit... button. See Server Detection for more information.
LSHOST - An environment variable containing a list of places where to look for a license. Either the network name (or IP address) of a license server for network licenses, or "no-net" for stand-alone licenses are valid entries. The license system is free to look elsewhere for the license, so it is unlikely that any entry here will be the cause of the problem.
LSFORCEHOST - Another environmental variable. This will force the license system only to look in the specified location. As above, this can either be the network name of the license server, or "no-net" for a stand-alone license. Think carefully before you use LSFORCEHOST, because it overrides all other settings and is not compatible with use of temporary training license files or use of commuter licenses.
KBC software uses security technology licensed from Safe-Net Inc. The same core technology is used by many other products and vendors. Therefore, LSHOST and LSFORCEHOST may not be used exclusively by KBC software and we recommend that you use the KBCLicServers mechanism instead.
Other information in the box reports on the status of any stand-alone (local) license file and security key (dongle):
- "Standalone license file found" or "No Standalone license file found" – mean what it says.
- "Security Key Found" or "No Security Key Found" – detects any dongle and displays the lock code.
Understanding the diagnostics
The License Tester diagnostics will trace the actions taken by the Tester and report results. The information you will see varies between Tester versions. All examples on this page are from the version that ships with SIM Suite 4.x. The first few lines report some basic information about the system. For example:
Configuration information:
Running on TEST6420 Windows OS = Windows 7 (Build 7601 CSD Service Pack 1) Common Files location = C:\Program Files (x86)\Common Files You are running with admin rights. LSHOST <not used> LSFORCEHOST <not used> Using KBCLicServers: calgarywiki
Initialisation completed in 15 milliseconds SLM Initialised successfully SLM Connected to server calgarywiki
The first three lines report the name of the computer that the tester is running on, the Windows version and the Common Files location, using information retrieved from the operating system. The Common Files location determines where various files will be located, such as any stand-alone license file, license.kbclic and the kbclicservers.kbclic file. KBC software looks for these files in a "KBC" sub-folder in the Common Files folder.
The fourth line reports your current administrator status. You do not need administrator rights to use the Tester, but you probably will need those rights to install stand-alone license files on the Windows Vista and Windows 7 (or newer) operating systems. Your status will be rechecked as part of any license install. There are three responses you may see:
- You are running with admin rights - means your current user account has Administrator rights on this computer and the License Tester is being run by an administrator.
- You are not running with admin rights - means your current user account has Administrator rights, but the License Tester is only being run in normal mode. You will see this response in the latest versions of Windows, if you have not launched the License Tester via "Run as Administator".
- You do not have Admin rights - means your current user account is not an Administrator account and you may therefore not be able to install license files.
The next lines report the parameters that control how KBC programs will find the license server, echoing the information shown in the Status Information box.
The final diagnostic lines report the initialisation status of the application. It rarely fails and any error usually indicates an installation error of the Tester itself. The Tester will check for any stand-alone license file on your PC and make sure that the locking mechanism matches that PC or or any security key plugged into it. The following example shows a typical response for a license locked against a PC's hard-disk ID:
Standalone license: License file C:\Program Files (x86)\Common Files\KBC\license.kbclic matches machine fingerprint of 26DAD004
Any mismatch will be clearly reported.
The last test run is to validate the LSHOST environment variable. The validation looks only for syntax, checking the server names are separated by colon characters (:) and not semi-colons or commas. It does not verify that the specified servers exist. The following is an invalid LSHOST string:
MyLicenseServer ; MySecondLicenseServer
and this is the valid version:
MyLicenseServer : MySecondLicenseServer
Spaces are optional and are used only to make the text more readable.
Further diagnostic text will be generated as you perform tests.
Example for working stand-alone license
Requesting license for KBC_PFPRO_Process (version 1.0) Request time = 906 milliseconds ...license granted to Standalone:KBC\Calgary\CalgaryTestMachine1 ...license has 497 days remaining before expiry ... from server no-net
The Check SIM Suite Licenses and Check Energy Licenses buttons will validate the basics for you. You may need to go further and test individual items, using the Features box. The names in the drop-down list are more human-readable forms of the actual names used by KBC software and reported in the diagnostics. Here the KBC_PFPRO_Process feature corresponds to the Petro-SIM:Petro-SIM Full Base License item in the Feature dropdown list. The information in this diagnostic tell us:
- that the license was successfully granted;
- that it comes from a license issued to a KBC Calgary computer named CalgaryTestMachine1;
- that it expires in 479 days;
- that it is a standalone license (this is the meaning of "no-net").
Example for working network license
Requesting license for KBC_PFPRO_Process (version 1.0) Request time = 500 milliseconds ...license granted to Network: KBC\Calgary\CalgaryTestServer ...license has 328 days remaining before expiry ... from server CalgaryTestServer (Version 8.1.0.0)
This tells us we have been granted a license from the pool held by the license server CalgaryTestServer, which is running version 8.1.0.0 of the Sentinel RMS License Manager.
Example for failed license
As the next section explains, licenses can come from multiple sources and the license system will search all its sources until it finds a license. When it fails, the system can usually only give you a general error message. The Tester will attempt to pinpoint a specific cause, by cycling through the known servers, testing each in turn and giving you information about the failure. Remember that the Sentinel RMS system supports many different commonly used products and your site may well be running multiple license servers, reserving a different server for each vendor's packages. The License Tester will not be able to find licenses for KBC products on servers solely supporting other vendor products.
How licenses are found
The license system searches for licenses in several locations, allowing you to mix stand-alone and network licenses and to have multiple license servers. The search order is as follows, with the search stopping once a valid license is found:
- Use any LSFORCEHOST server - search will stop here, if the variable is set.
- Use servers listed in KBCLicServers.kbclic.
- Use any stand-alone license file.
- Use servers listed in LSHOST.
- Search any license servers found on the local IP subnet.
Letting the system search as far as it can for licenses can be convenient, but it can also cause confusion when no licenses are found. Suppose you have three seats of Petro-SIM licensed on a corporate server and you also have other license servers for non-KBC products on the same subnet. If those three seats are in use when you are trying to get a license, the system will carry on and search all the other servers it can find. It will fail and give you a generic message saying no license could be found. If, instead, you force the system to limit its search solely to the license server hosting KBC licenses, you will get a clear message telling you all the seats are currently in use. Using the KBCLicServers.kbclic file helps limit the search and we recommend its use for network licenses.
We do not recommend LSFORCEHOST in normal situations, since it can conflict with users trying to use commuter licenses or short-term training licenses.
Testing a Specific Server
In some situations, you know where your licenses are coming from and want to limit the License Tester to look only on that server. How do you do this?
Use the Force use of standalone license checkbox, to make it search stand-alone licenses on your PC. You use the Connect to Server box, to enter the server name or IP address, and click the Set button when ready.
License Tester Reference
Main Buttons
- Install License File - installs any "*.kbclic" file to its correct location. This mechanism can handle the KBCLicServers.kbclic file, stand-alone license files and network license files.
- Stand-alone license files : The install process will check for any existing file you may have and try to merge the new features with the old. It will report any conflicts.
- Network license files : The install process will use your settings, to guide you through selecting the target server. It then installs the licenses to that server, replacing any existing licenses with the same name.
- Check SIM Suite Licenses - reports which primary SIM Suite components you are licensed for. The tests consider the different Petro-SIM editions, together with checks on the available reactors.
- Check Energy Licenses - reports which KBC Energy software you are licensed for.
- Reset - resets everything; can be useful if you change any license settings and want to start your tests again.
- Clear Messages - clears the diagnostics window.
- Check Key Match - helps you check which license file goes with which key and is useful when you have many stand-alone licenses and keys to manage. Plug in a key, start the tester and then use Check Key Match.
- Check Servers - reports which license servers are present on the local subnet.
- Clear Messages - clears the diagnostic window.
- Check License - probably the most useful function! This tries to find a license for your selected feature. If you are using the KBCLicServers file to limit the search, it will attempt to get detailed diagnostics on reasons for any failure. Licenses are only checked out for a millisecond or so, before being returned.
Features group
This is where you select a feature for analysis. The drop-down box lists features you can check, but will normally contain many more entries than your license supports. What you see in the drop-down list is controlled by radio button selections:
- All features - shows all possible features in the list;
- SIM Suite (selected by default) - limits the items to those used by the KBC SIM Suite package
- Energy Software - only lists the KBC Energy products including ProSteam, SuperTarget, WaterTarget and Persimmonl.
| Check Feature License | Attempts to get a license for the selected feature, reporting results in the Diagnostics |
|---|---|
| Test All Features | Cycles through all the features in the dropdown list, attempting to get a license for each and reporting results to the Diagnostics. First use the radio buttons to filter the list as much as possible, since there are over one hundred individual features and few licenses contain all of them. |
| Test if Feature Exists | Tests if the selected feature is available on your system, but does not try to get a license. This can be useful to distinguish between situations where a license is present but unavailable because all seats are checked out by other users. |
You will see a much shorter list, if you launch the KBC License Tester from a Diagnostics button in Petro-SIM. Here the list contains only licenses that have failed in Petro-SIM.
Advanced Options
The commonly used functions are all available through buttons and controls on the main Tester window. Several advanced options can be useful in specific situations. You will find these on the Advanced menu.
| Check security key match against license | Use this option to help you check which license file is associated with the dongle that is currently plugged in. Can be helpful when your company has many dongles and many license files. |
|---|---|
| Check Out | Checks out and retains a license to the feature selected in the Features drop-down list. Useful when you want to test seat handling on the server. |
| Check In | Returns any checked-out license, freeing it for use by others. |
| Validate | Validates a checked-out license, to make sure it is still recognised. |
| Run Cleanup Tool | KBC may use this as a last resort, to reset license servers and the client's PC, mainly to resolve infrequent issues with "commuter licenses". |
| Initialize Standalone System | Initializes the license system on a client machine. This is only done to resolve infrequent problems caused by initialisation not completing properly during software installation. |
| List All Features on Server | Lists all KBC features available on the connected or available license servers. |
| Full diagnostics | Toggles the full diagnostic level on or off. |
Further Help
If required, please contact KBC's software helpdesk for additional help, giving as much information as you can about your problem.