WorkShop Installation and Licensing Guide: 5 - Managing Your Licenses

# Managing Your Licenses | # 5 |

This chapter explains the FLEXlm license management software, provides detailed information about the licensing functions and commands you can use to manage your product software, lists important licensing commands and locations of license files, and provides instructions on how you can get specific help.

## 5.1 FLEXlm License Management Software

The FLEXlm components include the following:

- A license manager daemon

- A vendor daemon

- A license file

- An application program

### 5.1.1 The License Manager Daemon

When a developer wants to invoke a software program, the license manager daemon (`lmgrd.ste`) is contacted initially; then the connection is passed on to the appropriate vendor daemon. Also, the license manager daemon starts and restarts the vendor daemons.

### 5.1.2 The Vendor Daemon

The vendor daemon tracks the licenses that are checked out and the users of those licenses. The WorkShop products use the `suntechd` vendor daemon.

If the vendor daemon terminates, all users lose their licenses. When the license manager daemon restarts the vendor daemon, the users regain their licenses automatically.

### 5.1.3 The License File

The license administrator installs the license file, which is a text file that contains licensing data. This file contains information about the server nodes and vendor daemons and at least one line of data (`FEATURE` or `INCREMENT`) for each licensed product.

The license file, or a copy of it, must be accessible to every machine running the licensed software and each machine designated as a license server.

### 5.1.4 The Application Program

The WorkShop applications are linked with the program module (the license library) to provide communication with the license server. When the program is in use, it communicates with the vendor daemon to request a license.

The following processes occur using the WorkShop licenses and software:

  1. The license module in the application finds the license file.

  2. The client connects with the license manager daemon, `lmgrd.ste`, and tells it what vendor daemon it needs to contact.

  3. The license manager daemon determines what machine and port correspond to the master vendor daemon; then `lmgrd.ste` sends that information to the client.

  4. The client contacts and connects with the specified vendor daemon and sends out a license request.

  5. The vendor daemon determines if any licenses are available, then sends an approval or denial to use a license to the client.

  6. The license module in the application grants or denies use of the feature.

## 5.2 WorkShop Installation Media

The Sun WorkShop provides the following installation media:

- The license software package, `SUNWlicsw`

- The license installation tool package, `SUNWlit`

The License Installation Tool configuration file, `LIC_CONFIG_FILE`, is part of the `SUNWlit` package and contains information pertaining to the individual products needed by `lit`.

The `LICENSE_FILE` name defines the basename for each elementary license file associated with the product and the product location. The WorkShop products define `sunpro.lic`,n as the `LICENSE_FILE`.

Each actual license file for the product is in the form:
sunpro.lic, n

Here basename is the value supplied within this field, and n is the sequence number assigned during installation that identifies this particular license.

## 5.3 The daemon_options File

The licensing package includes a default `daemon_options` file which is installed in the `/etc/opt/licenses` directory. The `daemon_options` file allows you to do the following:

- Reserve licenses for specified users, hostnames, or display names.

- Allow and deny use of applications based on user, hostname or display name.

- Specify `LINGER` values.

- Control license information logs.

When `lmgrd.ste` starts the vendor daemon, the vendor daemon receives the location of the options file. This location is identified in the product's license file, on the `DAEMON` line. If no file is listed, the daemon will not use any options file. Only one options file per vendor daemon is allowed, and each vendor needs a separate options file.

If you plan to modify the `daemon_options` file, your changes do not take effect until the FLEXlm daemon is started or restarted. Although redundant server configurations require that the file be the same on each server, the file can be different for independent server configurations.

To minimize the server down time, make the needed changes to the `daemon_options` file; then take the license daemon down and restart the daemon (refer to page 5-37 and page 5-38).

#### Table 5-1 Commands for the `daemon_options` File

Name | Description
EXCLUDE | Denies a user access to a feature.
EXCLUDEALL | Denies a user access to all features of the vendor daemon.
GROUP | Specifies a group of users for use with any options.
HOST_GROUP | Defines a group of hosts for use with any options.
INCLUDE | Allows a user access to a feature.
INCLUDEALL | Allows a user to access all features served by the vendor daemon.
LINGER | Causes licenses to be held by the vendor daemon for 300 seconds after the application checks them in or exits.
NOLOG | Turns off logging certain items.
REPORTLOG | Specifies that a log file will be written.
RESERVE | Saves licenses for a user.
# | Allows you to enter comments in the file.

Figure 5-1 is an example of edits made to the `daemon_options` file.

##### Figure 5-1 Example of `daemon_options` File Edits

In Figure 5-1, the user has specified the following:

- The license log will not record licenses checked in, checked out, or queued.

- The C and C++ compiler licenses will delay for 300 seconds before returning licenses to the license server for other developers' use.

- One C compiler license is only for use by "pat".

- Three C compiler licenses are only for use by "lee".

- No C compiler license is for use by "joe."

### 5.3.1 Taking Down the License Daemons

You may need to take down the license daemons if you edit the `daemon_options` file, to troubleshoot a problem, or if you move your license server from one machine to another.

Using the `lmdown` command sends a message to every license daemon requesting that it shut down. The license daemon completes the current log file message and closes the file; then the daemons rescind all of the licenses that have been given out. The next time a user invokes a program and the client server goes to verify the license, the license will be invalid.

If you have a redundant server configuration, this procedure takes down all of the redundant servers.

| As root, type the following at the root prompt:

  `#` ./lmdown -c /etc/opt/licenses/licenses_combined

  If the `-c` option is not specified, the `lmdown` command looks for the needed `LM_LICENSE_FILE` environment variable. If that variable is not set, `lmdown` looks for the `/usr/local/flexlm/licenses/license.dat` file.

### 5.3.2 Restarting the License Daemon

If you have a redundant license server configuration, you must perform this procedure on each server.

| As root, type the following at the root prompt:

  `#` /etc/rc2.d/S85lmgrd

The output of this command is in the `/usr/tmp/license_log` file.

### 5.3.3 Starting the License Daemon on Solaris 1.x

Start the licensing software by typing the path name for `lmgrd.ste` on the server. The following command-line redirects status and error messages into the `license_log` file.

| To start the license daemon, execute the following command in a C shell:

  `#` /etc/opt/licenses/lmgrd.ste -c \
  /etc/opt/licenses/licenses_combined>& \
  /usr/tmp/license_log &

## 5.4 Important License Administration Tools

### 5.4.1 Using the License Manager Daemon Functions

The license manager daemon (`lmgrd.ste`) is the main daemon program for FLEXlm. When you invoke `lmgrd.ste`, it looks for the license file. This license file has information about vendors and features.

To use `lmgrd.ste`, type:

`#` ./lmgrd.ste -c <license_file> -t <timeout_interval> \
-s <timestamp_interval> -v -x lmdown -x lmremove

with the following definitions:

-c <license_file>: Use `/etc/opt/licenses/licenses_combined`. If this switch is not specified, `lmgrd.ste` looks for the `LM_LICENSE_FILE` environment variable. If that variable is not defined, `lmgrd.ste` looks for the `/usr/local/flexlm/license.dat` file.

-t <timeout_interval>: Sets a timeout interval, in seconds, during which redundant servers must finish their connections with each other. The default is 10 seconds, but you may need a larger value if the daemons are being run on busy systems or a heavily loaded network.

-s <timestamp_interval>: Specifies the logfile timestamp interval, in minutes. 360 minutes is the default.

-v: Prints `lmgrd.ste`'s version number and copyright.

-x lmdown: Disallows the `lmdown` command for any user.

-x lmremove: Disallows the `lmremove` command for any user.

### 5.4.2 Monitoring the Status of Network Licensing Activities

The `lmstat` utility monitors which daemons are running, users of individual features, and users of features served by a specific `DAEMON`.

To use `lmstat`, type:
`#` lmstat -a -S <daemon> -f <feature> \
-t <value> -c <license_file> -A

with the following definitions:

-a: Display all information

-S <daemon>: List all users of daemon's features.

-f <feature>: List users of features.

-t <value>: Sets `lmstat` timeout to the specified value.

-c <license_file>: Use `/etc/opt/licenses/licenses_combined`. If this switch is not specified, `lmgrd.ste` looks for the `LM_LICENSE_FILE` environment variable. If that variable is not defined, `lmgrd.ste` looks for the `/usr/local/flexlm/license.dat` file.

-A: Lists all active licenses.

### 5.4.3 Having the License Daemon Reread the License File

When you invoke the `lmreread` utility, the license daemon starts any new vendor daemons, and all pre-existing daemons are signaled to reread the license files for changes in feature licensing information.

To use `lmreread`, type:

`#` ./lmreread -c <license_file>

with the following definition:

-c <license_file>: Use `/etc/opt/licenses/licenses_combined`. If this switch is not specified, `lmgrd.ste` looks for the `LM_LICENSE_FILE` environment variable. If that variable is not defined, `lmgrd.ste` looks for the `/usr/local/flexlm/license.dat` file.

### 5.4.4 Identifying the License Library Version

The `lmver` utility reports the version of a library or binary file.

To use `lmver`, type:

`#` ./lmver <filename>

with the following definition:

<filename>: Use the name of the executable of the FLEXlm binary: for example, `lmgrd.ste`, `suntechd`, or `lmstat`.

### 5.4.5 Getting a Hostid for a System

Use `lmhostid` to report a system's hostid.

To use `lmhostid`, type:

# ./lmhostid

### 5.4.6 Removing a User's License

You may need to remove a user's license if, for example, the license remains checked out and unavailable for use because of a system crash.

To use the `lmremove` utility, type:

`#` ./lmremove -c <license_file> <feature> <user> <host> \
<display>

with the following definitions:

-c <license_file>: Use `/etc/opt/licenses/licenses_combined`. If this switch is not specified, `lmgrd.ste` looks for the `LM_LICENSE_FILE` environment variable. If that variable is not defined, `lmgrd.ste` looks for the `license.dat` file.

<feature>: Use the name of the feature checked out by the user.

<user>: Use the name of the user whose license you are removing; use `lmstat` to obtain the value of `<user>`.

<host>: Use the name of the host the user is logged in to; use `lmstat` to obtain the value of `<host>`.

<display>: Use the name of the display where the user is working; use `lmstat` to obtain the value of `<display>`.

### 5.4.7 Diagnosing License Problems

Using the `lmdiag` utility, you can look into problems when you cannot check out a license.

To use `lmdiag`, type:

`# ./`lmdiag -c <license_file> <feature>

with the following definitions:

-c <license_file>: Use `/etc/opt/licenses/licenses_combined`. If this switch is not specified, `lmgrd.ste` looks for the `LM_LICENSE_FILE` environment variable. If that variable is not defined, `lmgrd.ste` looks for the `/usr/local/flexlm/license.dat` file.

<feature>: Diagnose this feature only.

### 5.4.8 List of Important Commands

The following tools are available in `/etc/opt/licenses`.

- To invoke the license daemon on Solaris 2.x:
  `#` /etc/opt/rc2.d/S85lmgrd [start | stop]

- To start up the license daemon on Solaris 1.x:
  # /etc/opt/licenses/lmgrd.ste -c \
  /etc/opt/licenses/licenses_combined>& \
  /usr/tmp/license_log &

- To get license information, identify each feature's available licenses, and identify the current license users:
  # lmstat -a -c /etc/opt/licenses/licenses_combined

- To take down the license daemon:
  `#` lmdown -c /etc/opt/licenses/licenses_combined

- To have the license daemon reread the license file:
  `#` lmreread -c /etc/opt/licenses/licenses_combined

- To identify the license library version:
  `#` lmver <filename>

## 5.5 If the License Server Goes Down

If your independent license server goes down or is not accessible over the network, you cannot launch licensed software or execute any critical functions on active licensed programs. When the license server becomes available, you can then resume use of the licensed software. If you have a redundant server configuration, a majority of the servers must be available.

If the license server referred to in the elementary license file (`sunpro.lic`,<n>) is down, set the `LM_LICENSE_FILE` environment variable to a different license server path.

## 5.6 Upgrading Your Operating System

If you upgrade your operating system, you must save everything in the `/etc/opt/licenses` directory and the `/etc/rc2.d/S85lmgrd` file and restore the files when you have completed the system upgrade.

## 5.7 Location of Important Files

The following are locations of important files:

- License file:
  `/etc/opt/licenses/licenses_combined`

- Elementary license file:
  `/opt/SUNWspro/license_dir/sunpro.lic,`<n>
  where n is a variable.

- File containing the location of all product software on the current server:
  `/etc/opt/licenses/sunpro.loc`

- Installation script to be run on all product servers:
  `/etc/opt/licenses/LIC_CONFIG_SCRIPT`

- License manager daemon (soft link):
  `/etc/opt/licenses/lmgrd.ste`

- Vendor daemon (soft link):
  `/etc/opt/licenses/suntechd`

- Daemon options file:
  `/etc/opt/licenses/daemon_options`

- FLEXlm log file:
  `/usr/tmp/license_log`

- License installation log file:
  `usr/tmp/license_errors`

- License daemon startup script:
  `/etc/rc2.d/S85lmgrd`

- FLEXlm utilities (soft links):
  `/etc/opt/licenses`

- License Installation Tool configuration file:
  `/etc/opt/licenses/LIC_CONFIG_FILE`

- License Request Form:
  `/cdrom/devpro_v5n1_`<platform>`/License_Request_Form`

## 5.8 Troubleshooting Common Licensing Issues

Various licensing issues can arise that may not allow you to use your product software. This section describes common troubleshooting you may need to perform to access your licenses and products.

### 5.8.1 Reviewing the Log Files

There are two log files: `/tmp/license_errors` provides a list of errors that occurred during the license installation process, and `/usr/tmp/license_log` provides day-to-day license activity information.

  1. To enable logging of license checkouts and checkins, put a pound sign (`#`) in front of the NOLOG IN, NOLOG OUT, NOLOG QUEUED lines. This comments out these lines in the /etc/opt/licenses/daemon_options file. Refer to Section 5.3, "The daemon_options File," for more information.

    For example:
    `#NOLOG IN
    #NOLOG OUT
    #NOLOG QUEUED
    `To disable the logging of the file, remove the pound sign from the daemon_options file.

  2. Take the license daemon down. Refer to "Taking Down the License Daemons" on page 5-37 for help.

  3. Restart the license daemon. Refer to "Restarting the License Daemon" on page 5-38.

### 5.8.2 Changing the License Server Hostname

If you must change the hostname on your license server, modify the hostname listed in the `licenses_combined` file and the elementary license files.

### 5.8.3 Recovering a Lost License

If a license is reported in use when it is not being used, the license server may not know that the license is no longer in use. This can happen, for example, if a system crashes while a licensed product is in use.

Use the `lmstat` command to get the status of the active licenses. If a license is reported in use when it is not being used, use the `lmremove` command to recover the license.

### 5.8.4 Releasing a License

If you have checked out a license and your machine crashes, the license will be tied up until the next refresh time, usually only a few minutes.

If the linger period has expired and a license is still tied up, a license administrator can use the `lmremove` command to free the license.

### 5.8.5 Finding Out the Installed Version of FLEXlm

Depending on the licensing software you run on your system, there may be compatibility difficulties. To maximize your new product's functions, you must use a current version of the license manager software and utilities. FLEXlm 4.1 is provided with this release; use only FLEXlm version 4.1 or later.

Make sure FLEXlm version 4.1 or later is installed by doing the one of the following procedures:

| At a command prompt, type:

  `#` cd /etc/opt/licenses

  `#` ./lmver lmgrd.ste

  Or

| At a command prompt, type:

  `#` /etc/opt/licenses/lmver /etc/opt/licenses/lmgrd.ste

### 5.8.6 Making Sure the Licenses Are Installed

To find out if your licenses are installed, complete the following procedures:

  1. On the license server, make sure that there is a licenses_combined file in the /etc/opt/licenses directory.

  2. On each product server, make sure all elementary license files are present in /opt/SUNWspro/license_dir/sunpro.lic,<n>.

    The elementary license filename would be similar to `sunpro.lic,`n.

    If your licenses are not installed, refer to Chapter 4, "Installing Your Licenses."

### 5.8.7 Verifying the License Software Status

You can check the status of the license software, find out who is using a license, and verify that the license software is running using the following procedure:

| At a command prompt on your license server, type:

  % /etc/opt/licenses/lmstat -a -c \
  /etc/opt/licenses/licenses_combined

### 5.8.8 Fax and Phone License Installation Typing Errors

Installing licenses from fax or phone information provides an opportunity to mistype license information that the Sun License Center provides.

Edit the `licenses_combined` and `sunpro.lic,` n files to verify that the information entered matches the information provided by the License Center.

### 5.8.9 Installing FORTRAN 77 Compiler

If you've purchased and installed Sun WorkShop Compiler Fortran 4.2, you may get an error after running `-xlicinfo` stating that ther is no iMPact license. You do not need an iMPact license to use you Fortran Compiler products. No action is necessary if this error message is displayed.

## 5.9 Getting Additional Help

If you have licensing questions that aren't answered in this guide, contact your authorized service provider and have the following information available:

- A detailed description of the symptoms of the problem. This may include a detailed step-by-step procedure on how to recreate the problem.
- Version number of the license software, FLEXlm.
- A copy of the log file, with the logging turned on while the problem occurred.
- A copy of the `licenses_combined` file.
- A copy of the elementary license file.
- Output from the `lmstat` utility.
- The operating system version of the license server and the product server.