License Administration

This appendix provides background information on licensing in Panther. To manage Panther usage, the Flexible License Manager (FLEXlm), a product of Globetrotter Software, Inc., is used. FLEXlm Version 5.0 is installed with Panther as part of the installation process only on server machines.

The appendix describes the license options file and the following FLEXlm license administration utilities provided with Panther.

• lmcksum - Performs a checksum of a license file.
• lmdiag - Diagnoses licensing problems.
• lmdown - Gracefully shuts down the license daemons on all nodes.
• lmgrd - Starts the license manager daemon.
• lmhostid - Prints the correct hostid value on any machine supported by FLEXlm.
• lmremove - Removes a single user's license for a specified feature.
• lmreread - Causes the license daemon to reread the license file and start any new vendor daemons that have been added.
• lmstat - Monitors the status of all licensing activity.
• lmswitchr - Switches the log file for the specified feature.
• lmver - Reports the FLEXlm version of a library or binary.

Licensing in Panther

Panther components use local or remote licensing schemes and are defined as follows:

• Local licensing is when the license file for the application resides on the same machine as the Panther component being used.
• Remote licensing is when the license file for the application resides on a different machine from the Panther component being used.

The setup program recommends a default licensing scheme for each Panther component. If you accept the default, the setup program guides you through the appropriate steps to obtain a permanent license file. You can choose a different scheme if your license administrator recommends it. In this case, the setup program requests contact information, and the Prolifics License Desk will contact you or your license administrator to arrange for licensing. Default license schemes are:

License Daemons and License Types

The license daemons are programs that manage the license types that allow limited access to users. License daemons are only required for node-locked counted and floating licenses. Thus, only the Panther development client requires a daemon; and the license daemon always runs on the license host machine.

The license type and number used at your site was determined when Panther was purchased.

Types of Daemons

• License daemon (lmgrd) - Manages the license file and starts the vendor daemon prold. Only one license daemon can be active for a given license file. However, there might be other license daemons managing other license files. lmgrd runs on the license host.
• Vendor daemon (prold) - Works with lmgrd to dispense tokens. Each feature of a floating (development client) or node-locked counted license has a limited number of tokens.

License Types

• A Panther application server engine uses a license type that allows for an unlimited number of application server engines to run on a specific computer. The license is does not require a license daemon. This type of license is referred to as node-locked uncounted.
• A Panther web application broker uses a node-locked uncounted license which allows for an unlimited number of applications to be run on a specific computer. The license does not require a license daemon.
• Panther clients use floating licenses. This type of license is not associated with a particular machine, but is assigned by the license server to each Panther development client when the executable is run. This license type requires a license daemon.

Note: Because a floating license is associated with the Panther development executable, and not with an actual machine, it is possible for a developer to use more than one license. For example, if a developer is running two Panther sessions simultaneously on one machine, the license manager assigns two licenses, not one.

Options File

The daemon options file allows you to customize Prolifics license usage at your site. The information in the file can specify such information as:

• Which users or groups of users can use Panther.
• Which messages will be included in the log file.
• How long a copy of Panther will remain idle before timing out.

There is no default location or name for the options file. If used, its name appears as the fourth argument on the DAEMON line of the license file license.dat, in the optional field options-file. If there are multiple DAEMON lines in the license.dat file, then there can be multiple options files, one for each DAEMON line. Not all of the lines in an options file refer to a feature, so the site administrator must set up separate options files in order to use the NOLOG and REPORTLOG features.

Contents of the Options File

{INCLUDE|EXCLUDE} feature {USER|HOST|DISPLAY|GROUP} name
NOLOG {IN|OUT|DENIED|QUEUED} 
GROUP group-name member-list 
LINGER feature checkout-time
REPORTLOG filename
RESERVE numlic feature {USER|HOST|DISPLAY|GROUP} name
TIMEOUT feature idletime

Lines beginning with a pound sign (#) indicate comments and are ignored.

INCLUDE/EXCLUDE

INCLUDE and EXCLUDE specify which users (or hosts, displays, or groups) are allowed to use a particular feature. Any user who is EXCLUDEd from a feature is not able to use that feature. Specifying an INCLUDE line has the effect of excluding everyone else from that feature; thus, only those users specifically INCLUDEd are able to use that feature. The INCLUDE|EXCLUDE line has the following format:

{INCLUDE|EXCLUDE} feature {USER|HOST|DISPLAY|GROUP} name

NOLOG

NOLOG causes messages of the specified type to be filtered out of the daemon's log file. Specifying a NOLOG option reduces the amount of output to the log file, which can be useful in those cases where the log file grows too quickly. The NOLOG line has the following format:

NOLOG {IN|OUT|DENIED|QUEUED}

GROUP

GROUP defines collections of users, which can then be used in RESERVE, INCLUDE, or EXCLUDE commands. The GROUP line has the following format:

GROUP group-name member-list

LINGER

LINGER prevents the license manager from taking back a license until the indicated checkout-time has expired, regardless of whether or not the license token is being used. The LINGER line has the following format:

LINGER feature checkout-time

REPORTLOG

REPORTLOG creates a log file suitable for use with the FLEXlm report writing tools. This log file maintains more detailed information than the standard log file, but is not meant to be human readable. If the filename starts with a plus character (+), the file will be opened in append mode. The REPORTLOG line has the following format:

REPORTLOG filename

RESERVE

RESERVE reserves the specified number of licenses for the specified user, host, display, or group. Reserving a license decreases the number of generally available licenses. The RESERVE line has the following format:

RESERVE numlic feature {USER|HOST|DISPLAY|GROUP} name

TIMEOUT

TIMEOUT sets up a minimum idle time after which a user's license is lost if it is not being used. This can prevent users from wasting a license (by keeping it checked out when it is not in use) when someone else wants one. The TIMEOUT line has the following format:

TIMEOUT feature idletime

Example

REPORTLOG /usr/adm/gsi.replog
RESERVE compile USER pat
RESERVE compile USER less
RESERVE compile HOST terry
NOLOG QUEUED

FLEXlm Utilities

The following sections describe the FLEXlm utility programs provided with Panther. These utilities are located in the distributed util directory.

lmcksum
Performs a checksum of a license file

lmcksum [-k] [-c license_file]

-k

Forces the encryption code checksum to be case-sensitive (in general, lmcksum is not case-sensitive) and not prompt for any input.

-c license_file

Name of license file to checksum. By default lmcksum operates on license.dat in the current directory. If this switch is not specified, lmcksum looks for the environment variable LM_LICENSE_FILE. If the environment variable is not set, lmdiag looks for the file /usr/local/flexlm/licenses/license.dat.

Description

lmcksum ignores all fields that do not enter into the encryption code computation; thus the server node name and port number, as well as the daemon pathname and options file names are not checksummed. In addition lmcksum treats non-case sensitive fields correctly (in general, lmcksum is not case-sensitive.) lmcksum takes the -k switch to force the encryption code checksum to be case-sensitive.

lmcksum takes an optional daemon name; if a name is specified, only license file lines for the selected daemon are used to compute the checksums.

lmdiag
Diagnoses licensing problems

lmdiag [-c license_file] [-n] [feature]

-c license_file

Name of license file to diagnose. If this switch is not specified, lmdiag looks for the environment variable LM_LICENSE_FILE. If the environment variable is not set, lmdiag looks for the file /usr/local/flexlm/licenses/license.dat.

-n

Non-interactive mode; lmdiag does not prompt for any input. In this mode, extended connection diagnostics are not available.

feature

Diagnose only the specified feature.

Description

Extended diagnostics attempt to connect to each port on the license server node, and can detect if the port number in the license file is incorrect. lmdiag indicates each port number that is listening, and if it is an lmgrd process, lmdiag indicates this as well. If lmdiag finds the vendor daemon for the feature being tested, then it indicates the correct port number for the license file to correct the problem.

lmdown
Takes down license daemons

lmdown [-c license_file] [-q]

-c license_file

Use the specified license_file. If this switch is not specified, lmdown looks for the environment variable LM_LICENSE_FILE. If the environment variable is not set, lmdown looks for the file /usr/local/flexlm/licenses/license.dat.

-q

Quiet mode; lmdown does not ask for confirmation. If the switch is not specified, lmdown asks for confirmation before asking the license daemons to shut down.

Description

The end-user system administrator should protect the execution of lmdown since shutting down the servers causes loss of licenses.

Note: lmdown can be used only by a "FLEXlm administrator" (i.e., a member of group lmadmin or, if the lmadmin group does not exist, a member of group 0).

lmgrd
Starts up the license manager daemon

lmgrd [-2] [-b] [-c license_file] [-d] [-l logfile] [-p] [-s interval] [-t timeout]

-2

Specifies V2 startup arguments, in contrast to the -b switch. This switch is required if you intend to use the -p switch (available in lmgrd v2.4 and later).

-b

Specifies backward compatibility mode. Use this switch if you are running a v2.1 or later lmgrd with a v1.5 or earlier vendor daemon. This is the default switch in FLEXlm v2.4 and later.

-c license_file

Use the specified license_file. If this switch is not specified, lmgrd looks for the environment variable LM_LICENSE_FILE. If the environment variable is not set, lmgrd looks for the file /usr/local/flexlm/licenses/license.dat.

-d

Specifies that hostnames which are read from the license file should have the local domain name appended to them before sending to a client. Useful when clients are accessing licenses from another domain. (Available in lmgrd v2.4 and later.)

-l logfile

Specifies the output log file to use.

-p

Specifies that the lmdown and lmremove utilities can only be run by a license administrator. A license administrator is a member of the lmadmin group, or, if the lmadmin group does not exist, a member of group 0. (This is available in lmgrd v2.4 and later.)

-s interval

Specifies the logfile timestamp interval, in minutes. Default is 360 minutes.

-t timeout

Specifies the timeout interval, in seconds, during which daemons must complete their connections to each other. Default value is 10 seconds. A larger value might be preferable if the daemons are being run on busy systems or a very heavily loaded network.

Environment

Description

lmhostid
Prints the correct hostid value on any machine supported by FLEXlm

lmhostid [type]

type

The type of the hostid to print. type must be one of long, idmodule, ether, or string, and is currently used only on HP and SCO systems. On HP, type specifies the ID module, the machine id as returned from the uname command, or the Ethernet address. The HP default is long-uname. On SCO, long specifies the pre-3.0 default, which was a 32-bit long int, while string specifies a string host, which is the new default.

Description

lmhostid - Copyright (C) 1997, Globetrotter Software, Inc.
The FLEXlm host ID of this machine is "1700abcd"

lmremove
Removes a user license and returns it to the license pool

lmremove [-c license_file] [feature] [user] [host] [display]

-c license_file

Use the specified license file. If this switch is not specified, lmremove looks for the environment variable LM_LICENSE_FILE. If the environment variable is not set, it looks for the file /usr/local/flexlm/licenses/license.dat.

feature

Remove only from the specified feature.

user

The user to be removed.

host

Node from which the user is to be removed.

Description

lmremove removes all instances of user on node host at the specified display from usage of feature. The end-user system administrator should protect the execution of lmremove since removing a user's license can be disruptive.

Note: lmremove can be used only by a "FLEXlm administrator" (i.e., a member of group lmadmin or, if the lmadmin group does not exist, a member of group 0).

lmreread
Tells the license daemon to reread the license file

lmreread [-c license_file]

-c license_file

Use the specified license file. If this switch is not specified, lmreread looks for the environment variable LM_LICENSE_FILE. If the environment variable is not set, it looks for the file /usr/local/flexlm/licenses/license.dat.

Description

lmreread uses the license file from the command line (or the default file, if none specified) only to find the license daemon to send it the command to reread the license file. The license daemon always rereads the original file that it loaded. If you need to change the path to the license file , then you must shut down the daemon and restart it with that new license file path.

You cannot use lmreread if the SERVER node names or port numbers have been changed in the license file. In this case, you must shut down the daemon and restart it in order for those changes to take effect.

lmreread does not change any option information specified in an options file. If the new license file specifies a different options file, that information is ignored. If you need to reread the options file, you must shut down the daemon and restart it.

lmstat
Reports status on license manager daemons and feature usage

lmstat [-a] [-A] [-c license_file] [-f [feature]] [-l [reg_expression]] [-s [server]] [-S [daemon]] [-t timeout]

-a

Display everything.

-A

List all active licenses.

-c license_file

Use the specified license file. If this switch is not specified, lmstat looks for the environment variable LM_LICENSE_FILE. If the environment variable is not set, lmstat looks for the file /usr/local/flexlm/licenses/license.dat.

-f [feature]

List all users of the specified features.

-l [reg_expression]

List all users of the features matching the given regular expression.

-s [server]

Display the status of the specified server nodes.

-S [daemon]

List all users of the specified daemon's features.

-t timeout

Specifies the timeout interval, in seconds, during which daemons must complete their connections to each other. Default value is 10 seconds. A larger value might be desirable if the daemons are being run on busy systems or a very heavily loaded network.

Description

lmstat provides:

• Total licenses available for each feature.
• Who is using the license.
• Who is using features served by a specific daemon.

lmswitchr
Switches the FLEXadmin log file (REPORTLOG) for the specified feature

lmswitchr [feature] [new-file]

feature

Any feature this daemon supports.

new-file

New file pathname.

Description

There is another way to switch the log file output data; however, this involves piping the stdout of lmgrd to a shell script that appends a file for each line. Instead of the "normal" startup: % lmgrd > LOG

Start lmgrd this way:

% lmgrd -z | sh -c 'while read line; do echo "$line" >> LOG; 
done'

For more information on the log file, refer to page -5- for a description of REPORTLOG.

lmver
Reports the FLEXlm version of a library or binary

lmver [filename]

filename

Use the specified license file. If a filename is not specified, lmver looks for the environment variable LM_LICENSE_FILE. If the environment variable is not set, lmver looks for the file /usr/local/flexlm/licenses/license.dat.

Description