![[Return to Library]](BOOKSHLF.GIF)
![[Contents]](TOC.GIF)
![[Previous Chapter]](REW.GIF)
![[Next Section]](NEXT.GIF)
![[Next Chapter]](FF.GIF)
![[Index]](INDEX.GIF)
![[Help]](HELP.GIF)
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:
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 -ddir option on the lmf 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, a two-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 product code OSF-USR and the authorization code OSF-BASE-IMPLICIT-USER.
If you obtain an unlimited user activity license for the operating system, you must delete the two-user license before you can register and load the unlimited license. If you do not remove the two-user license before registering and loading the unlimited license, the command will fail while displaying the following error:
Multiple Licenses could not be combined for OSF-USR DEC
To prevent the problem, delete the two-user license by using the following lmf commands:
#
lmf
lmf>
delete OSF-USR AUTHORIZATION OSF-BASE-IMPLICIT-USER
Then, use lmf to register and load the unlimited license.
![[Previous Section]](PREV.GIF)
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: aws-pk-88229-2
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.
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-2
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:
This command copies the license details for a particular product from the license database to the kernel cache.
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:
Note
It is current business policy not to issue Product Authorization Amendments (PAAMs). Do not use the amend command 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: 2-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:
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:
To display these details, use the 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:
LMF also creates an entry in the history file when it creates a new license database.
The history command displays data in the history file as described in the following list:
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
./ ./ The following information did not apply to silver but is being ./ saved in case it is needed in gold. ./