BullseyeCoverage Up Contents Search

Using the License Manager

Background

The license manager is optional. It is provided for organizations that have a strict policy that the number of simultaneous users never exceed the number of users specified by your license, or where estimating the number of simultaneous users is not feasible. If your network file system is not completely reliable or performs slowly, using the license manager may impede usage of the product. Therefore, you may manage license utilization based on an estimate of the number of simultaneous users, rather than using the license manager.

The license manager limits the number of simultaneous users to the number allowed by your license. After the license manager grants all available user licenses, subsequent requesters wait until a license is released. The license manager consumes one user license for the duration of each BullseyeCoverage program. The license manager does not apply to executables instrumented with BullseyeCoverage, only to the programs supplied with BullseyeCoverage. The license manager does not apply to compiler interceptors when coverage build is disabled. In all other cases, BullseyeCoverage programs acquire a license when they start and release the license when they terminate, regardless of whether coverage build is enabled. Note that the Coverage Browser consumes a license even if it is idle. However, if all licenses are busy, cov01 and covlmgr proceed without acquiring a license. This exception allows you to disable coverage build and to monitor the license manager, even when all licenses are busy.

If a BullseyeCoverage program holding a license is killed and therefore does not release the license, that license remains unavailable for 10 minutes, after which it is automatically released.

You can use the license manager with an evaluation license. The license manager cannot be used with an unlimited license.

The License Manager File

BullseyeCoverage stores information about the licenses currently in use in a file, called the license manager file. This file must be accessible to all users for reading and writing. The license manager file is located on a network file server. The network file server must support file locking. The license manager file is updated directly by the BullseyeCoverage programs each time they run. There is no server process to configure or start.

You can manage licenses for BullseyeCoverage running on different operating systems all with the same license manager file or with separate license manager files, or in any combination. The key requirement is that all users on the same operating system use the same license manager file.

Only the license administrator should create the license manager file.

The license administrator can require that all users use the license manager file by distributing to them only the path to the license manager file and keeping license keys secret.

Setting up on Windows

The setup program displays a page titled License where you can enter either a license key, the path of an existing license file, or both. The license administrator can also create the license manager file when specifying both.

After installation, you can verify the license manager file contents with the Coverage Browser command Help About or with the command covlmgr --status.

To stop using the license manager, re-run setup and enter an empty path in the License page.

Example: creating a new license manager file

Example: using an existing license manager file

Setting up on Unix-like Systems

The install program, which is the first installation step, accepts several options to configure the license manager:

Use option --key if you were given a license key. You do not need to specify --key if you have an existing license manager file containing a license you wish to use.

Options --create and --use specify that the BullseyeCoverage installation should use the license manager. If the license manager file does not yet exist, use option --create, otherwise use --use. The install program records the path in $HOME/.BullseyeCoverage for subsequent access by BullseyeCoverage programs.

For example, to create the license manager file:

./install --key xltxbYYJXzgnTYqLPLckjN84W1jJ7c8o65Z5UtWtwbdf --create /server/BullseyeCoverageLicenseManager

For example, to use the license manager file:

./install --use /server/BullseyeCoverageLicenseManager

After installation, you can verify the license manager file contents with the command below.

covlmgr --status

To stop using the license manager, re-run install specifying neither --create nor --use.

If you do not run the install program because you are running a shared installation, set environment variable COVLM to the path of the license manager file.

Sharing Licenses

If your organization owns multiple licenses purchased at different times, you can share them all among many users. To share multiple licenses, add each license key to your license manager file with covlmgr --add key.

For example on Windows, follow these steps.

1. Gather all your license keys and download the latest release of BullseyeCoverage.
2. Run the setup program. When the License page appears, enter your first license key.
3. Specify to create a license manager file.
4. Complete the installation.
5. Run covlmgr --add key for each of your remaining license keys.

For example on Unix-like systems, follow these steps.

1. Gather all your license keys and download the latest release of BullseyeCoverage.
2. Run install --create path --key key, specifying your first license key
3. Run covlmgr --add key for each of your remaining license keys.

Adding or Updating Licenses

When you purchase an additional license or an update, you will receive a new license key. The license administrator should update the license manager file with covlmgr --add key, or by performing an installation using the existing license manager file and the new key. It is recommended to download the latest release of BullseyeCoverage at this time if you have not done so recently.

Monitoring Utilization

You can determine some basic license manager utilization information with either covlmgr --status or the Coverage Browser command Help About. Specifically, you can determine:

1. The users currently holding a license
2. The total number of minutes all users spent waiting
3. The peak number of users that were made to wait

You can reset the status information with covlmgr --clear.

Relocating the License Manager File

The license manager has security features that prevent copying the license manager file. To relocate the file, recreate the file at the new location. For example:

covlmgr --file newPath --create
covlmgr --file newPath --add key1
covlmgr --file newPath --add key2
...

After recreating the license manager file, each client should change their path setting for the file. For example,

covlmgr --file newPath --use

File Format Version History

When new features are added to the license manager, the file format is updated. BullseyeCoverage creates a license manager file in the newest format known to that software release. The format of an existing license manager file never changes. This is to maintain compatibility among different software versions in use within a group. If you wish to update the file format, you must recreate the file.

To determine the current file version, use the Coverage Browser command Help About, or covlmgr --status.

Updated: 27 Sep 2023

Copyright © Bullseye Testing Technology. All Rights Reserved.