2    License Management Utility, lmf

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.

2.1    Registering and Loading a Tru64 UNIX License

When you install or upgrade to Tru64 UNIX an inherent user activity license for the operating system automatically is 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.

2.2    Registering a 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.

2.2.1    Editing a Blank Template

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-1999
 
           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.

2.2.2    Editing a Partially Complete Template

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-1999
 
           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.

2.2.3    Registering a PAK Directly

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.

2.3    Loading a License

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:

2.3.1    Loading a License for One Product

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.

2.3.2    Loading the Licenses for All Products

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 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.

2.4    Unloading a License

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.)

2.4.1    Unloading an Activity License

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.

2.4.2    Unloading an Availability License

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.

2.5    Disabling a License

Occasionally, you might want a license to be registered in the license database, 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.

2.6    Enabling a License

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 automatically is enabled; that is, you can load it into the kernel cache immediately.

2.7    Issuing a License

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.

2.8    Canceling a License

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 1999, enter the following commands: 

# lmf cancel 1-jul-99 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.

2.9    Deleting a License

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.

2.10    Updating a License

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.

2.10.1    Modifying a License

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-1999
 
           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.

2.10.2    Amending a License

At times, a Product Authorization Amendment (PAAM) might be issued 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 support 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-1999
 
           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.

2.11    Combining Licenses

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-1999 and 1-AUG-1999, the combined license has a product release date of 1-JAN-1999.

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).

2.12    Displaying Information About Licensed Products

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 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-1999
   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.

2.13    Reviewing Your License Management Activities

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-1999
Time        : 12:02:32
Product Name: ALLSUM
Producer    : DEC
Command     : DISABLE
Date        : 15-JAN-1999
Time        : 11:57:26
Product Name: ALLSUM
Producer    : DEC
Command     : REGISTER
Date        : 4-JAN-1999
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-1999 12:02:32
ALLSUM        DEC        DISABLE    15-JAN-1999 11:57:26
ALLSUM        DEC        REGISTER   4-JAN-1999  11:54:15

ž .\" The following information did not apply to silver but is being Ÿ

2.14    Changing the Number of Active CPUs

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:

2.14.1    System Maintenance

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.

2.14.2    Reducing the License Unit Requirement

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.