Reserving licenses

You can customize out-of-the-box licensing to make sure that certain people always have access to a user license, or so that a particular server always has access to a build license. You can reserve licenses to set up a combination that best suits your needs.

The rest of this section uses build and user licenses in the examples.

What are your needs?

The following are some licensing scenarios to help you think about what kind of licensing combination you need. The scenarios assume a deployment large enough that there is a separation between the roles of the Validate administrator and the Validate user.

Scenario 1: Fixed build license, user licenses for individuals

Your circumstances

You know how many Validate build engineers (or build servers) need to have fixed build licenses and you know who (or which ones) they are. You probably have a large number of Validate users who will use Validate at various times.

The setup

The setup is a combination of fixed build licenses, reserving build licenses for the Validate build tools, and user licenses for individuals. You can reserve either fixed build or user licenses for

people
machines (by host name or IP address)
groups of people
groups of machines

Results

Build engineers (or build servers) will always have a build license.
You can supply as many build engineers or servers as required with cost-effective fixed build licenses.
User licenses for allow flexibility for large groups.

Scenario 2: Fixed for everybody

Your circumstances

You know how many build engineers (or build servers) need to have reserved build licenses, and you know who they are. You know how many users need to have reserved user licenses, and you know who they are. It is a relatively small, stable group.

The setup

Your options file will reserve fixed licenses for each user or machine. You may set them up, particularly the build engineers, as groups in your options file.

Results

Build engineers (or build servers) always have a build license.
You can enable as many Validate build engineers as required with cost-effective fixed build licenses.

What you need to do

To reserve licenses to suit your needs, you need to:

Create an options file that works with your Validate license.
Add the path to the options file to your license file.
Start or re-start the Validate Servers.
Verify that the licenses were reserved.

You can find more information about options files in the relevant Reprise documentation.

Sample license file

The format for parts of the LICENSE section relevant to the options file is:

LICENSE isv product version exp-date count [sig=]license-key [optional parameters]

The following are three sample LICENSE sections from a Validate license file:

five fixed build licenses:

LICENSE prqa fixserver2023 23.0 permanent 5 share=h start=19-may-2023 
issuer=JSmith issued=19-may-2023 options=KW-1151-004;-1;1209600;opt;ha 
_ck=abcdef1234 sig="XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

100 individual user licenses:

LICENSE prqa fixclient2023 23.1 31-dec-2023 100 share=u start=19-may-2023 
issuer=JSmith issued=19-may-2023 options=KW-1151-004;-1;600;opt;ha 
_ck=abcdef1234 sig="XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Validate license:

LICENSE prqa review2023  23.1 31-dec-2023 100 share=u start=19-may-2023 
issuer=JSmith issued=19-may-2023 options=validate;-1;604800;opt;ha 
_ck=abcdef1234 sig="XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Back up your license file

It is easy to accidentally corrupt the Validate license file. Before you begin, make a copy of your license file as a backup and put it in a safe place. If the copy of the license file you are working on becomes corrupt, restore the backup license file and restart the license server.

Create an options file

Create a blank text file called prqa.opt in the following directory:

<projects_root>/licenses

This file must be in the same directory as your Validate license. The license service creates a prqa.opt file if one does not already exist which contains important Validate settings. Do not modify or remove these settings, do not remove the 'prqa.opt' file, and do not change the option REPORTLOG.

Do not set the 'REPORTLOG' line, as this is overridden by validate service when starting the servers and it is required.

Copy, paste, and replace

To reserve licenses, you can copy a template line of text into your options file and change it to suit your situation. The Template Table gives you lines to choose from. You can either enter text into the options file or you can copy and paste text into it. If you want to cut and paste the ISV string from your Validate license, use the working copy you made.

Do not change the text of FEATURE or LICENSE lines in the original Validate license. It is signed and if you change it, the license will not work.
The options file is case-sensitive.
The "\" character is a continuation character in options file lines.

The following examples show you how to choose a line and make the changes.

The label used for the license type may differ in your license file. The examples here use "fixserver2023", "server", "fixclient2023" and "client". Your license file may use other labels.

Reserving one license

To reserve one build license:

Copy and paste the following line into the options file:
```
RESERVE 1 <product> user <user_name>
```
Replace <product> with the name of the product from the license line. The build license in the Sample license file is fixserver2023.
Replace <user_name> with a username of your choice (for example, jlee).

One build license is now reserved for the user that you specified.

To reserve a user rather than a build license, replace fixservers with fixclient in the RESERVE line.
To reserve for a host rather than a user, replace the keyword user with the keyword host, and specify the machine's IP address or unqualified domain name. For example:
```
RESERVE 1 fixserver2023: host buildmachine01
```
Reprise does not recognize fully qualified host names (such as buildmachine01.companyname.com).

Reserving multiple licenses

You can reserve more than one license for the user, machine, or group specified in the RESERVE line. To reserve more than one license:

Check the last number after the expiry date of your working copy of the Validate license. The number is the maximum number of license you can assign for that vendor string.
In the options file, change the first number in the RESERVE line. For example, change RESERVE 1 fixserver2023 to RESERVE 2 fixserver2023.

You are now reserving two licenses.

Setting up a group of users or machines

If you don't want to add all users line-by-line, define a group and refer to the group instead. You can do this by copying lines of text from the Template Table or by entering the following:

To define a group of people, add the following line to your options file:

GROUP <group_name> <user_list>

where

<group_name> is a name for the group
<user_list> is a list of group member names, separated by spaces

For example:

GROUP BuildTeam amichaels fyassin jlee jsmith mwashington

To reserve a number of build licenses for a group:

Add the following line to your options file:

RESERVE <number_of_licenses> fixserver2023 group <group_name>

Replace the variable in the line with the proper values. For example, to reserve five fixed build licenses for the group BuildTeam:
- Replace <number_of_licenses> with 5
- Replace <group_name> with BuildTeam

Example options file:

GROUP BuildTeam amichaels fyassin jlee jsmith mwashington

RESERVE 5 fixserver2023 group BuildTeam

Groups of machines

Instead of using the GROUP keyword, you can also define a group of machines using the HOST_GROUP keyword followed by a list of host names separated by spaces. For example:

HOST_GROUP BuildHosts 192.168.0.101 buildmachine06 192.168.0.102 northserver

Multiple groups

You can set up multiple groups, each with its own RESERVE line. For example:

RESERVE 5 fixserver2023 group BuildTeam
RESERVE 5 client group DevGroup 
RESERVE 10 client group RemoteGroup

five fixed build licenses are reserved for BuildTeam
five individual user licenses are reserved for DevGroup
10 individual user licenses are reserved for RemoteGroup

If this organization has purchased 20 individual user licenses (client), 15 are reserved in this example (five on line 2 and 10 on line 3), and the remaining five are available to others users on a first-come, first-serve basis.

Template table

You can copy one or more lines from the following table and paste them into your options file. Replace the vendor string with your own vendor string, and make any other changes that you need.

To reserve fixed licenses, use your ISV string that has the large number.

To reserve user licenses, use your ISV string that has the small number.

To reserve more than one license, change the number after the RESERVE keyword (or replace <number of licenses>).

The label used for the license type may differ in your license file. The examples here use "fixserver2022", "server", "fixclient2022", and "client". Your license file may use other labels. It is important that your options file uses the same license type label as your license file.

To set up your local options file to...	Copy and paste...
reserve one fixed build license for a person	`RESERVE 1 fixserver2023 user <user_name>`
reserve one fixed user license for a person	`RESERVE 1 fixclient2023 user <user_name>`
reserve one fixed build license for a machine	`RESERVE 1 fixserver2023 host <unqualified_domain_name or IP address>`
define a group of people and reserve a number of fixed user licenses for the group	`GROUP <group_name> <user_list> RESERVE <number_of_licenses> fixclient2023 group <group_name>`
define a group of machines and reserve a number of fixed build licenses for the group	`HOST_GROUP <group_name> <user_list> RESERVE <number_of_licenses> fixserver2023 host_group <group_name>`

Add the path to the options file to your license file

The ISV options file can be located in 3 ways:

You can specify the ISV options file location on the ISV line in the license file.
If no specification is on the ISV line, Reprise looks for .opt (where is the name of the ISV) in the location with the first license file.
If there is no options file in either of the first two locations, Reprise looks for .opt in the working directory where you started the RLM server.

Start or re-start the Validate servers

After you create or modify an options file, you must start or restart the Validate servers for the changes to take effect.

Check the License Manager log file to test your options file

To make sure that the reservation is successful, check <projects_root>/logs/license.log for the RESERVING message. On success, the log file says:

RESERVING 1 <featurename> license for <type> <val>

On failure, the log file indicates any errors in the options file.

Example output

06/08 15:50 (prqa) Server architecture: x64_w4 

	Copyright (C) 2006-2024, Reprise Software, Inc. All rights reserved. 

	RLM contains software developed by the OpenSSL Project 
	for use in the OpenSSL Toolkit (http://www.openssl.org) 
	Copyright (c) 1998-2008 The OpenSSL Project. All rights reserved. 
	Copyright (c) 1995-1998 Eric Young (eay@cryptsoft.com) All rights reserved. 

 
06/08 15:50 (prqa) Using options file prqa.opt 
06/08 15:50 (prqa) Report log started on C:\ProgramData\Perforce\Validate\projects_root\logs\license.report.log 
06/08 15:50 (prqa)  
06/08 15:50 (prqa) Server started on localhost (hostid: ANY) for: 
06/08 15:50 (prqa)  floatserver floatclient reviewclient code_review