The License Management Facility (LMF) provides the
lmf
utility
to help manage the software licenses for your system.
You use the
lmf
utility to maintain a file of registered software licenses, the license
database.
In addition, you can also use the
lmf
utility to maintain
the kernel cache.
This chapter describes how to manage licenses by using the
lmf
utility to perform the following tasks:
Register and load a DIGITAL UNIX license. (See Section 2.1.)
Register a license. (See Section 2.2.)
Load a license. (See Section 2.3.)
Unload a license. (See Section 2.4.)
Disable a license. (See Section 2.5.)
Enable a license. (See Section 2.6.)
Issue a license. (See Section 2.7.)
Cancel a license. (See Section 2.8.)
Delete a license. (See Section 2.9.)
Update a license. (See Section 2.10.)
Combine licenses. (See Section 2.11.)
Display information about licensed products. (See Section 2.12.)
Review your license management activities. (See Section 2.13.)
The LMF commands
can be used only by a person logged in to the system as superuser (root login).
You can
allow nonprivileged users to use the
list
and
history
commands, but you must change the file mode permissions on the files that
the commands access.
The
list
command accesses
/usr/var/adm/lmf/ldb, and the
history
command accesses
/usr/var/adm/lmf/ldb_history.
When you use LMF commands, you can enter them on a single line, for example:
# lmf register
Alternatively, you can run the
lmf
utility and enter the commands
after the
lmf>
prompt, for example:
# lmf lmf> register
For more information about LMF
commands, see the
lmf(8)
reference page.
You can copy or
move the license database from the
/usr/var/adm/lmf
directory to
another directory on your system.
To access the copied or moved license database,
specify the-d
option on the
dirlmf
command
line.
When you use this option, LMF looks in the directory you specify for
the license database.
LMF modifies that license database as you use commands
like
register,
load,
unload,
modify, and so on.
LMF also creates the history file in that directory.
When you install or upgrade to DIGITAL UNIX, an inherent user activity license for the operating system is automatically registered and loaded for you. The license is named the OSF-USR license, and contains the following two data elements:
Product Name: OSF-USR Authorization: UNIX-SERVER-IMPLICIT-USER
If you obtain an unlimited user activity license for the operating system,
you must delete the inherent user activity license before you can register
and load the unlimited license.
If you do not remove the inherent license
before registering and loading the unlimited license, the command will fail
while displaying the error
Multiple Licenses could not be combined for
OSF-USR DEC.
To prevent this problem, delete the inherent license by using the
lmf
utility:
# lmf
lmf> delete OSF-USR AUTHORIZATION UNIX-SERVER-IMPLICIT-USER
Then, use
lmf
to register and load the unlimited
license.
When you install a product that provides LMF support, you must register the product. Registering the license records the license details listed on the Product Authorization Key (PAK) in the license database. Once the details are in the license database, LMF can load them into the kernel cache.
To register a license, you use the
register
command.
The
register
command displays a template that contains
the fields that appear on a PAK.
By default, the fields on the template are
blank.
You register the license by entering the data from your PAK into the
blank fields.
Some products provide a partially completed template that you can use to register a license. If you use a partially completed template, you need to complete only the missing information.
In some cases, you might need to register a completed template that has, for example, been sent to you through electronic mail.
The following sections describe the process of registering licenses in the license database and explain what to do if something goes wrong.
To register a license by editing
a blank template, use the
register
command without arguments.
When
you issue the command without arguments, LMF displays a template that includes
all the fields on a PAK and an additional field for your comments.
Suppose you need to register the information from the License PAK shown in Example 1-1. Enter the following command at the superuser prompt:
# lmf register
LMF displays a blank
template and runs an editor to allow you to edit the template.
LMF runs the
editor that is defined by your
EDITOR
environment variable.
If
the environment variable is undefined, LMF runs the
vi
editor.
The following example shows the template that LMF displays for the ALLSUM product and, in bold type, the information you would supply from the ALLSUM PAK:
Licensed Software Product
Product Authorization Key
Enter data on lines terminated with :
Issuer: dec
Authorization Number: 3aws-pk-88229-2
Product Name: allsum
Producer: dec
Number of units: 1200
Version: Version 2.0
Product Release Date: 31-jul-1993
Key Termination Date: "
Availability Table Code: M
Activity Table Code:
Key Options:
Product Token:
Hardware Id:
Checksum: 1-odkm-niio-jepj-fclb
Comment: This is an example license.
If your PAK contains blank fields, leave the same fields blank on the template. You can enter the data in uppercase or lowercase characters.
You must enter the license information from the PAK carefully. LMF returns the following error message if you omit or incorrectly enter any license data:
Checksum does not validate
If you receive this message, carefully check the characters typed on each line, not just the checksum string.
When you finish entering the license data, exit from the editor.
LMF then scans the completed template to make sure all the license data has been entered correctly. If the license data is correct, LMF copies it into the license database. If the license data is incorrect, you can reenter the editor and correct mistakes.
In some
instances, you might have license data in files on your system as a result
of using the
issue
command (see
Section 2.7), or
such data might have been copied to your system as part of a product installation.
For example, the installation procedure for the fictional product ALLSUM might
copy license data to the file
/usr/var/adm/lmf/ALLSUM.
This file
would contain license data common to all ALLSUM licenses.
To register the
license, you add your specific license details from your ALLSUM PAK.
To register a license by using a partially complete template, use a command like the following one:
# lmf register /usr/var/adm/lmf/ALLSUM
In response to this command, LMF runs an editor to allow you
to edit the existing license data.
LMF runs the editor defined by the
EDITOR
environment variable.
If the environment variable is undefined,
LMF runs the
vi
editor.
The following example shows the template that is displayed by LMF for the ALLSUM product and, in bold type, the information you would supply from the ALLSUM PAK:
Licensed Software Product
Product Authorization Key
Enter data on lines terminated with :
Issuer: DEC
Authorization Number: aws-pk-88229-2s
Product Name: ALLSUM
Producer: DEC
Number of units: 1200
Version: Version 2.0
Product Release Date: 1-JUL-1993
Key Termination Date:
Availability Table Code: M
Activity Table Code:
Key Options:
Product Token:
Hardware Id:
Checksum: 1-odkm-niio-jepj-fclb
Comment: This is an example license.
If your PAK contains blank fields, leave the same fields blank on the template. You can enter the data in uppercase or lowercase characters.
You must enter the license information from the PAK carefully. LMF returns the following error message if you omit or incorrectly enter any license data:
Checksum does not validate
If you receive this message, carefully check the characters typed on each line, not just the checksum string.
Once you finish entering data into the fields on the template, exit from the editor.
LMF then scans the completed template to make sure all the license data has been entered correctly. If the license data is correct, LMF copies it into the license database. If the license data is incorrect, you can reenter the editor and correct mistakes.
In some cases, you might
have a license data file that was not created by the
issue
command
or a product installation.
In this case, verify that the file contains all
the license fields that have entries on your PAK.
The license fields names
must be in the same format as the template displayed with the
register
command, that is, the same combination of uppercase and lowercase characters,
with a colon ( : ) separating the field name and
the data.
The license fields can be in any order.
Files created using the
issue
command or as part of product
installations automatically have the field names in the correct format.
In many cases, the license data file that you create with the
issue
command is complete.
When you have a complete license data file,
you can use the
register -
command to register the data in
the file by redirecting the file to standard input.
The following example shows how to use the command:
# lmf register - < /usr/var/adm/lmf/ALLSUM
LMF does not display the contents of the file or allow you to edit it. However, it does scan the file to be sure that the format and data are correct. If the license data is correct, LMF copies it into the license database. If the license data is incorrect, LMF does not copy it into the license database, and it displays the appropriate error message. The command also returns an exit status: zero, if the license data has been copied into the license database; or nonzero, if the license data was not copied into the license database.
Once you have registered a license in the license database, load it into the kernel cache to make the license details available to the license-checking functions. The license-checking functions only allow a product to run if it has a valid license in the kernel cache.
To load license details into the kernel cache, use one of the following methods:
Use the
load
command.
This command copies the license details for a particular product from the license database to the kernel cache.
Use the
reset
command.
This command copies the license details for all products from the license database to the kernel cache.
The system startup process automatically executes the
reset
command.
Use the
load
command to copy the license
details for a specified product from the license database to the kernel cache.
As an argument to the
load
command, specify the number of users
that you want to be able to use the product.
If
a product is availability licensed, specify the number of users to be zero
( 0 ) when you use the
load
command.
This
practice makes sure the number of units loaded into the kernel cache is always
enough to satisfy the requirements of the processor.
For example, assume the
product ALLSUM is availability licensed, and you have registered the license
in the license database.
To load the license into the kernel cache, enter
the following command:
# lmf load 0 ALLSUM
Alternatively, assume the product ALLSUM is activity licensed, and you have registered enough license units for 10 product users in the license database. To load all the license units for the product into the kernel cache, enter the following command:
# lmf load 0 ALLSUM
If you want to load only enough license units for five users, enter the following command:
# lmf load 5 ALLSUM
When you use the
load
command, make sure you supply enough
arguments to uniquely identify the license.
If you have two products with
the same name from different producers, you must supply the producer name
as well as the product name, for example:
# lmf load 0 ALLSUM DEC
If your system has two or more licenses
with the same product and producer name, the
load
command loads
all the licenses into the kernel cache only if the licenses can be combined.
For a complete explanation of license combination, see
Section 2.11.
Use the
reset
command to copy the license
details for all products from the license database to the kernel cache.
The
following shows the command you issue to copy the license details to the kernel
cache:
# lmf reset
If any license has an insufficient number of license units, LMF does not load that license into the kernel cache, and it issues an error message. For example, if the license for ALLSUM has an insufficient number of license units, LMF issues the following message:
Not enough units to load ALLSUM DEC
If this situation occurs, contact your Digital sales representative, or register and load the license on a smaller system.
Note
LMF loads the license details for all enabled products into the kernel cache whenever a system is restarted.
Use the
unload
command
to restrict the number of users of a product.
The
unload
command
removes license units from the kernel cache, restricting the number of units
available to LMF checking functions.
The command affects only the number of
license units available for a product in the kernel cache; it does not affect
the number shown in the license database.
Remember that the license will be reloaded with its original number
of users whenever you restart your system or issue the
reset
command.
To avoid automatic reloading of the license, use the
disable
command.
(See
Section 2.5
for more information.)
Suppose you have registered and loaded the license for the product ALLSUM with a 10-user Activity License. You could restrict the license to be a seven-user license by entering the following command:
# lmf unload 3 ALLSUM
Existing users of the product are allowed to finish using it before
LMF imposes the new limit.
For example, if 10 users are using a product when
you issue the preceding
unload
command, all 10 users are allowed
to finish using the product.
However, LMF does not allow new users to run
the product until the number of active users has dropped below the new limit
of seven.
In
the case of an availability-licensed product, unload all the license units
for the product.
You do this by specifying zero ( 0 )
as the number of users.
Specifying zero causes LMF to remove the product from
the kernel cache.
For example, if the product ALLSUM is availability licensed
and you want to unload the license units for the product, enter the following
command:
# lmf unload 0 ALLSUM
As with activity-licensed products, LMF allows existing users of the product to finish using it, but LMF does not allow new users to run the product.
Occasionally, you might want a license to be registered
in the license latabase, but not loaded into the kernel cache.
Once you unload
the license from the kernel cache, you can prevent LMF from reloading the
license by disabling it.
If you do not disable the license, LMF reloads it
when you use the
load
or the
reset
command, or when
you start your system.
For example, to disable the license for the product ALLSUM and to unload it from the kernel cache, enter the following commands:
# lmf disable ALLSUM # lmf unload 0 ALLSUM
The
disable
command does not immediately affect the kernel cache, so you
should use the
unload
command to unload the license details from
the kernel cache.
If you do
not use the
unload
command, the product remains available on the
system until the next
reset
command or system startup.
Once you have disabled a license, LMF ignores it
when you issue the
load
or the
reset
command or when
you start the system.
Use the
enable
command to permit LMF to load
the license.
After you issue the
enable
command for a license,
LMF once again loads the license into the kernel cache when you enter the
load
or the
reset
command or when you start the system.
For example, to enable the license for the product ALLSUM and to load the license into the kernel cache enter the following commands:
# lmf enable ALLSUM # lmf load 0 ALLSUM
When you register a license in the license database, it is automatically enabled; that is, you can load it into the kernel cache immediately.
To move the license details for a product from the
license database to a file on your system, use the
issue
command.
The command reconstructs a PAK from the license data in the license database
and writes the PAK to the file you specify.
If LMF issues the PAK correctly,
it unloads the license from the kernel cache and deletes the license from
the license database.
You can use this command, for example, to move a license
for a product from one system to another.
To issue the license for the product ALLSUM to the file
allsum.pak, enter the following command:
# lmf issue allsum.pak ALLSUM
Although the command removes the license data from the kernel cache, existing users of the product are allowed to finish using it.
You can cause LMF to cancel a license earlier than
the date shown by the Key Termination Date field on the PAK.
Use the
cancel
command to cancel a license on a specific date.
To cancel the license for the product ALLSUM on the first day of July 1994, enter the following commands:
# lmf cancel 1-jul-94 ALLSUM # lmf load 0 ALLSUM
The first
command line does not immediately affect the kernel cache, so you should use
the
load
command to update the license for the product in the
kernel cache.
You can change the cancellation date more than once by issuing the
cancel
command with a different date argument.
If you set the cancellation
date to be after the key termination date shown on the license, LMF ignores
the cancellation date.
Once a license expires (for example, because the
license has passed its key termination date), delete it from the kernel cache
and the license database.
Use the
delete
command to delete a license
from the kernel cache and license database.
Before you use the
delete
command, be
sure that you have a copy of the license data in your files.
If you delete
a license by mistake, you can restore the license database file (/usr/var/adm/lmf/ldb) from a backup, or extract the PAK data from the history file and reregister
the license.
For example, to delete the license for the product ALLSUM, enter the following command:
# lmf delete ALLSUM
Although the command removes the license data from the kernel cache, existing users of the product are allowed to finish using it.
In some cases, you might need to update an existing license on your system. You can use one of the following two methods to update a license:
Modify the license with the
modify
command if
the license has the MOD_UNITS Key Option.
Amend the license with the
amend
command if you
have a Product Authorization Amendment (PAAM) for the product.
Note
It is current business policy not to issue Product Authorization Amendments (PAAMs). Do not use the
amendcommand unless you have a PAAM.
Use the
modify
command if you want to change the entry in
the Comment field or if you want to change the entry in the Number of Units
field on a license with the MOD_UNITS Key Option.
For example, if the product ALLSUM has the
MOD_UNITS Key Option and you want to increase the number of units on the license
from 1200 to 2000, enter the following command:
# lmf modify ALLSUM
In response to this command, LMF
runs an editor to allow you to edit the existing license data.
LMF runs the
editor defined by the
EDITOR
environment variable.
If the environment
variable is undefined, LMF runs the
vi
editor.
The following example shows the license data that is displayed by LMF for the ALLSUM product and, in bold type, the information you would supply:
Licensed Software Product
Product Authorization Key
Enter data on lines terminated with :
Issuer DEC
Authorization Number aws-pk-88229-2
Product Name ALLSUM
Producer DEC
Number of units: 2000
Version Version 2.0
Product Release Date 1-JUL-1993
Key Termination Date
Availability Table Code M
Activity Table Code
Key Options
Product Token
Hardware Id
Checksum 1-odkm-niio-jepj-fclb
Comment: Number of Units increased to 2000.
As the preceding example shows, LMF displays the current license for
ALLSUM with colons ( : ) before the Comment field
and the Number of Units field.
In this example, you use the editor to change
the Number of Units from 1200 to 2000.
If you change data next to fields without
colons, LMF ignores the changes you make.
Once you finish entering data, exit
from the editor.
When you leave the editor, LMF scans the license data to make sure the license has been updated correctly. If it has not, you are given the opportunity to reenter the editor and correct mistakes.
When you have
successfully modified a license, use the
load
command to copy
the modified license into the kernel cache.
At times, Digital might issue you a Product Authorization Amendment (PAAM) for your license. A PAAM is used to update an existing license and might have data only in fields that are different from that for the existing license for the product. A PAAM always contains a checksum that is different from that for the existing license. The checksum validates the amended license data; that is, the checksum is generated from the data elements as they appear after the license has been updated with the PAAM data.
Use the
amend
command when you want to update a license
in the license database after receiving a PAAM.
Suppose, for example, you already have a license registered for the product ALLSUM and that the license is valid for all versions of the product up to and including Version 2.0. If you want to use the license with versions up to and including Version 2.4, you could contact your Digital representative who might arrange for you to receive a PAAM. The PAAM might contain entries for product name, version, and checksum. To modify the license database, enter the following command:
# lmf amend ALLSUM
In response to this command, LMF runs an editor to allow you
to edit the existing license data.
LMF runs the editor defined by the
EDITOR
environment variable.
If the environment variable is undefined,
LMF runs the
vi
editor.
The following example shows the license data that is displayed by LMF for the ALLSUM product and, in bold type, the information you would supply from the PAAM:
Licensed Software Product
Product Authorization Key
Enter data on lines terminated with :
Issuer DEC
Authorization Number aws-pk-88229-2
Product Name ALLSUM
Producer DEC
Number of units 2000
Version: Version 2.4
Product Release Date 1-JUL-1993
Key Termination Date
Availability Table Code M
Activity Table Code
Key Options
Product Token
Hardware Id
Checksum: 1-odkm-qiio-jdpj-fclb
Comment: Version increased to Version 2.4.
As the preceding example shows, LMF displays the current license for
ALLSUM with colons ( : ) before the Version field,
the Checksum field, and the Comment field.
In the example, you use the editor
to change the version number from Version 2.0 to Version 2.4.
You also enter
the new checksum from the PAAM.
LMF removes the checksum entry from the current
license because PAAMs always contain a new checksum.
If you change data next
to fields without colons, LMF ignores the changes that you make.
When you leave the editor, LMF scans the license data to make sure the license has been updated correctly. If it has not, you are given the opportunity to reenter the editor and correct mistakes.
When you have
successfully amended a license, use the
load
command to copy the
amended license into the kernel cache.
Combining licenses means registering two or more licenses for the same product in the license database and loading them into the kernel cache to form a single license. Licenses that have the NO_SHARE Key Option cannot be combined.
To combine licenses, the following fields must be the same on both original licenses:
Issuer
Product Name
Producer
Hardware I.D.
Product Token
Note
Each license must have a different authorization number. LMF does not allow the same license to be registered more than once in the same license database.
When you want to combine licenses, register the licenses in the license
database in the usual way, that is, by using the
register
command
(see
Section 2.2).
The licenses appear as separate entries
in the license database.
To combine licenses
to form a single license in the kernel cache, use the
load
command.
For example, if you have registered two licenses for the product ALLSUM, you
can form a single license in the kernel cache by entering the following command:
# lmf load 0 ALLSUM
The combined
licenses appear as one entry in the kernel cache.
(For more information about
the
load
command, see
Section 2.3.)
The number of units for the license is the total number supplied by the original licenses. For example, if the Number of Units field entries on the original licenses are 1000 and 200, the combined license is a 1200-unit license.
The product release date and the key termination date for the combined license are the earlier of those supplied by the original licenses. For example, if the product release dates for the licenses are 1-JAN-1993 and 1-AUG-1993, the combined license has a product release date of 1-JAN-1993.
The version number for the combined license is the lower of those supplied by the original licenses. For example, if the version numbers for the original licenses are Version 1.2 and Version 1.4, the combined license has a version number of Version 1.2.
To remove
the combined license from the kernel cache, use the
unload
command
(see
Section 2.4).
You can use LMF to display the details of products registered on the system, in the following ways:
Display a summary of all the products registered in the license database or kernel cache or both.
Display the complete license details for all the products in the license database or kernel cache or both.
Display the details of specific products only.
list
command.
The following example shows how to display a one-line summary of all the products registered in license database:
# lmf list Product Status Users: Total Active ALLSUM active unlimited NOSUM disabled PARTSUM enabled ANOTHERSUM terminated
The Status column indicates the current status of the license. Each product can have one of the following six status conditions:
The license has been loaded into the kernel cache and can be used to authorize product use.
The license has been registered in the license database but has not been loaded into the kernel cache.
The license has been disabled in the license database.
The current date is later than the key termination date specified on the license.
The current date is later than the cancellation date specified on the license.
This license is one of multiple licenses registered for this product name and producer.
The two right-hand columns indicate the amount of product use.
For availability-licensed
products, the amount of product use is shown as
unlimited.
For
activity-licensed products the Total column shows the maximum number of concurrent
users allowed for a product.
The Active column shows the current number of
users for the product.
The following example shows how to display all the license details in the kernel cache for the fictional product ALLSUM (assuming an availability license):
# lmf list full cache for ALLSUM
Product Name: ALLSUM
Producer: DEC
Version: Version 2.0
Product Release Date: 1-JUL-1993
Key Termination Date:
Total Units: 1200
Usable Units: 0
Activity Charge: 0
The Total Units field shows the number of license units in the kernel cache. The Usable Units field shows the number of unallocated license units. The Activity Charge field shows the number of license units required for each product user.
LMF maintains a history file, which is a record of the operations you perform on the license database. LMF records the following commands in the history file:
amend
cancel
delete
disable
enable
issue
modify
register
The
history
command displays data in the history file as
described in the following list:
Use the
history
command with no arguments to display
the history data for each command issued.
The history data comprises the product
name, date and time of the command, and the fields that were changed on the
license.
Use the
full
argument to display the history data
and the license as it appeared before the command was issued.
Use the
short
argument to display a one-line summary
of the history data for each command issued.
Use the
from
argument to display
the history data for commands issued after a certain date.
date
Use the
for
argument to display
the history data for specific products.
product
The following example shows how to display the history data for the ALLSUM product:
# lmf history for ALLSUM Product Name: ALLSUM Producer : DEC Command : ENABLE Date : 26-FEB-1993 Time : 12:02:32 Product Name: ALLSUM Producer : DEC Command : DISABLE Date : 15-JAN-1993 Time : 11:57:26 Product Name: ALLSUM Producer : DEC Command : REGISTER Date : 4-JAN-1993 Time : 11:54:15
The next example shows the one-line summary of the history data for the same set of LMF commands:
# lmf history short for ALLSUM Product Name Producer Command Date Time ALLSUM DEC ENABLE 26-FEB-1993 12:02:32 ALLSUM DEC DISABLE 15-JAN-1993 11:57:26 ALLSUM DEC REGISTER 4-JAN-1993 11:54:15
When a system is rebooted, LMF checks the maximum possible number of active CPUs on the system, and uses this value to determine the System Marketing Model. The SMM is used by some products to define the number of license units needed in the kernel cache before access to the product is granted.
If you change the number of active CPUs the SMM may change, and so may
the number of license units needed in the kernel cache to access a product.
Use the
lmf reset cpus
command to determine a new SMM.
This section describes the license management actions you should take if you change the number of active CPUs:
For system maintenance purposes
To reduce the license unit requirement of the system
If you reduce the number of active CPUs for system maintenance purposes, you do not need to take any special license management actions. LMF continues to use the current SMM even though the number of active CPUs has changed.
When you return to the original number of active CPUs the LMF continues to use the current SMM, which now accurately reflects the number of active CPUs. Again, you do not need to take any license management actions.
You can reduce the license unit requirement of your system by reducing the number of active CPUs on the system. For example, assume you have reduced the number of active CPUs from two to one. To determine the new SMM for the system you would type:
# lmf reset cpus
Before you return to the original number of active CPUs, determine the new SMM. For example, assume you are ready to increase the number of active CPUs from one to two. To determine the new SMM for the system you would type:
# lmf reset cpus 2
If you do not determine the new SMM before returning to the original number of active CPUs, the LMF will prevent any further access to the licensed products, although existing users will be able to finish using them.