6.2.2.7 UPGRADE Line

Format:

UPGRADE isv product from-version to-version exp-date count [sig=]upgrade-key
[optional
parameters]

The UPGRADE line defines an upgrade from an older version (from-version or higher) to a newer version (to-version) of an existing product. All fields in the upgrade line are case-insensitive (with the exception of short, i.e., less than 62-character, license keys), and none may be modified by the license administrator with the exception of the parameters whose names begin with an “_” character.

We refer to the license specified by the UPGRADE line as the upgrade license, and the license it operates on as the base license.

An UPGRADE license will convert count licenses of product of version from-version or higher into to-version.

Note: An UPGRADE license will never operate on a base license that is >= to-version.

In order for the upgrade to be performed, certain parameters of the upgrade license must match the parameters of a base license in order for that license to be eligible to be upgraded.

Certain licenses can never be upgraded. In particular, token-based licenses (the token definitions themselves) will never be upgraded. Also, named-user and metered licenses are not eligible for upgrades.

In order for a license to be upgraded, the following parameters must match on the base license and the upgrade license:

License Disable specification
License Options
License Sharing specification (share and max_share)
License Timezone specification
License Platform list
Both licenses must have the same counting type: counted, uncounted, or single
License node-locked hostid
Both licenses must be user-based or host-based (or neither)

Note: This list is the same as the criteria for a license server combining multiple licenses into a license pool.

If the license is eligible for an upgrade, count licenses of the base license will be transformed into to-version licenses. An upgrade can be performed on multiple base licenses, until the count on the upgrade license is exhausted.

Note: License “replace” processing is done (both in client and server) before upgrade processing. This means that an upgrade license should not specify replacement of the base license which it is going to upgrade, because the base license will no longer exist when the upgrade is done.

There are 3 upgrade cases:

Fewer base licenses than upgrade licenses - in this case, the extra upgrade licenses are “wasted”, and the license server issues a warning. All base licenses are upgraded.
Same number of base licenses and upgrade licenses - all base licenses are upgraded.
Fewer upgrade licenses than base licenses - in this case, count licenses are upgraded, and the remaining base licenses remain at their old version.

The 3rd case above is the most useful - if you are upgrading all instances of an existing license, a replace option on a new license will do this just as well. The only advantage to the upgrade license in the first two cases is that the base license is required, i.e., the upgrade license, by itself, grants no rights.

When a license is upgraded by the license server, the new licenses will have their parameters modified as follows. All other license parameters will be the same as the base license:


Field	Resultfor Served **counted(or uncounted)licenses**	Result for Unserved *single or uncounted licenses*
exp-date	earlier date is used	earlierdate is used
hold	maximum of the 2 values	undeﬁned-
max_roam	minimum of the 2 values	undeﬁned-
min_checkout	maximum of the 2 values	undeﬁned-
min_remove	maximum of the 2 values	undeﬁned-
min_timeout	maximum of the 2 values	undeﬁned-
soft_limit (upgrading all)	Larger of 2 deltas from license count is used.	undeﬁned-
soft_limit(partial upgrade)	Upgrade soft limit is preserved for the new version, base license soft limit delta is preserved (minimum value 0) for the old version.	undeﬁned-
user_based, host_based (upgrading all)	If licenses have a speciﬁcation, the value closest to the license count is used.	undeﬁned-
user_based, host_based(partial upgrade)	If licenses have a speciﬁcation, upgrade spec is preserved for the new version; base license spec delta (countuser_based) is preserved (minimum value 1) for the old version.	undeﬁned-
contract	If base license is empty, use upgrade license. On partial upgrade, if upgrade license is empty,use value from base license for the new version.	If base license is empty, use upgrade license.
customer	If base license is empty, use upgrade license. On partial upgrade, if upgrade license is empty,use value from base license for the new version.	If base license is empty, use upgrade license.
issuer	If base license is empty, use upgrade license. On partial upgrade, if upgrade license is empty,use value from base license for the new version.	If base license is empty, use upgrade license.
type	If base license is empty, use upgrade license. On partial upgrade, if upgrade license is empty,use value from base license for the new version.	If base license is empty, use upgrade license.

Fixed (positional) parameters

The first 7 parameters are required on every upgrade line and are present in the order shown above.

isv

The name of the ISV granting the rights.

product

The name of the product for which license rights are being upgraded.

from-version

The lowest-numbered product version which is eligible for an upgrade, in the form “N.M”.

For example, 1.0, 2.37, or 2006.12

to-version

The highest-numbered product version supported by the license once it is upgraded, in the form “N.M”.

For example, 1.0, 2.37, or 2006.12

exp-date

The date the upgrade expires, in the form dd-mmm-yyyy, for example, 1-jul-2007. A non-expiring upgrade can be specified with either a year of “0” (i.e., “1-jan-0”), or simply the word “permanent.”

count

The number of licenses to be upgraded. 0 or uncounted means an uncounted, node-locked license is to be upgraded. uncounted and 0 are 100% equivalent.


	single means a node-locked, single-use license is to be upgraded. single is different from 1. See 6.2.2.5 LICENSE Line above for more information.
	token, token_locked, token_bound and token_unlocked are not allowed in an UPGRADE license. All other optional parameters are ignored.

Attention: The keyword token_locked was deprecated in v12.4 and replaced with token_bound. Licenses with token_locked keywords will continue to operate, but they will not be locked to the server’s hostid).

upgrade-key

A digital signature of all the upgrade data, along with the hostid on the HOST line, if present. If an upgrade license has a non-zero count, it always requires a HOST line. An upgrade to an uncounted license does not require a HOST line, and even if there is a HOST line, the hostid of the license server is not used in computation of its upgrade-key. The upgrade-key will have “sig=” prepended after the license has been signed by the rlmsign utility.

Note: If the upgrade-key is preceded by sig=, it can be present after any or all of the optional parameters.

Optional Parameters

Optional parameters are sometimes present in a license and can be present in any order. Optional parameters are allowed only once in an UPGRADE line. The syntax and meaning of optional parameters for the UPGRADE line are identical to the same parameters for the LICENSE line. Note that token and named_user are not allowed on an UPGRADE line. See 6.2.2.5 LICENSE Line for information on the optional parameters.

Example:

LICENSE reprise write 1.0 permanent 5 sig=.....
UPGRADE reprise write 1.0 2.0 1-aug-2015 5 sig=.....

In this example, the 5 licenses of the write product have been upgraded from v1.0 to v2.0.

Note: This license file would require a HOST line, since the licenses are counted.