This appendix contains the following sections:
Introduction
License Administration
Overview
Providing For Uninterrupted FLEXlm Operation
Daemon Options File
License Administration Tools
FLEXlm User Commands
The Daemon Log File
Informational Messages
Configuration Problem Messages
Daemon Software Error Messages
FLEXlm License Errors
This appendix discusses Highland Software's Flexible License Manager and how it is integrated into the TASKING toolchain. It also contains descriptions of the Flexible License Manager license administration tools that are included with the package, the daemon log file and its contents, and the use of daemon options files to customize your use of the TASKING toolchain.
The Flexible License Manager (FLEXlm) is a set of utilities that, when incorporated into software such as the TASKING toolchain, provides for managing access to the software.
The following terms are used to describe FLEXlm concepts and software components:
feature A feature could be any of the following:
license The right to use a feature. FLEXlm restricts licenses for features by counting the number of licenses for features in use when new requests are made by the application software.
client A TASKING application program.
daemon A process that "serves" clients. Sometimes referred to as a server.
vendor daemon
The daemon that dispenses licenses for the requested features. This daemon is built by an application's vendor, and contains the vendor's personal encryption code. Tasking
is the vendor daemon for the TASKING software.
license daemon
The daemon process that sends client processes to the correct vendor daemon on the correct machine. The same license daemon is used by all applications from all vendors, as this daemon neither performs encryption nor dispenses licenses. The license daemon processes no user requests on its own, but forwards these requests to other daemons (the vendor daemons).
server node A computer system that is running both the license and vendor daemon software. The server node will contain all the dynamic information regarding the usage of all the features.
license file An end-user specific file that contains descriptions of the server nodes that can run the license daemons, the various vendor daemons, and the restrictions for all the licensed features.
The TASKING software is granted permission to run by FLEXlm daemons; the daemons are started when the TASKING toolchain is installed and run continuously thereafter. Information needed by the FLEXlm daemons to perform access management is contained in a license data file that is created during the toolchain installation process. As part of their normal operation, the daemons log their actions in a daemon log file, which can be used to monitor usage of the TASKING toolchain.
The following sections discuss:
For additional information regarding the use of FLEXlm, refer to the chapter Software Installation.
TASKING products licensed through FLEXlm contain a number of utilities for managing licenses. These utilities are bundled in the form of an extra product under the name SW000098. TASKING products themselves contain two additional files for FLEXlm in a flexlm subdirectory:
If you have already installed FLEXlm (e.g. as part of another product) then it is not needed to install the bundled SW000098. After installing SW000098 the directory /usr/local/flexlm will contain two subdirectories, bin and licenses. The exact location may differ if FLEXlm has already been installed as part of a non-TASKING product but in general there will be a directory for executables such as bin. That directory must contain a copy of the Tasking daemon shipped with every TASKING product. It also contains the files:
Next to it, a licenses directory must contain a file with all licenses. If you did install SW000098 then the licenses directory will be empty. In that case the license.dat file from the product should be copied to the licenses directory after filling in the data from your license data sheet. Be very careful not to overwrite an existing license.dat file because it contains valuable data.
Example license.dat:
SERVER HOSTNAME HOSTID PORT DAEMON Tasking /usr/local/flexlm/bin/Tasking FEATURE SW008002-32 Tasking 3.000 EXPDATE NUSERS PASSWORD SERIAL
After modifications from a license data sheet (example):
SERVER elliot 5100520c 7594 DAEMON Tasking /usr/local/flexlm/bin/Tasking FEATURE SW008002-32 Tasking 3.000 1-jan-00 4 0B1810310210A6894 "123456"
If the license.dat file already exists then you should make sure that it contains the DAEMON and FEATURE lines from your license data sheet. An appropriate SERVER line should already be present in that case. You should only add a new SERVER line if no SERVER line is present. The third field of the DAEMON line is the pathname to the Tasking daemon and you may change it if necessary.
If the pathname of the resulting license file differs from:
/usr/local/flexlm/licenses/license.dat
then you must set the environment variable LM_LICENSE_FILE to the correct pathname. If you have more than one product using the FLEXlm license manager you can specify multiple license files by separating each pathname (lfpath) with a ':' :
setenv LM_LICENSE_FILE lfpath[:lfpath]...
When the main license daemon lmgrd already runs it is sufficient to type the command:
lmreread
for notifying the daemon that the license.dat file has been changed. Otherwise, you must type the command:
lmgrd >/usr/tmp/lmgrd.log &
Both commands reside in the flexlm bin directory mentioned before.
It is possible to customize the use of TASKING software using a daemon options file. This options file allows you to reserve licenses for specified users or groups of users, to restrict access to the TASKING toolchain, and to set software timeouts. The following table lists the keywords that are recognized at the start of a line of a daemon options file.
Keywords | Function |
RESERVE | Ensures that TASKING software will always be available to one or more users or on one or more host computer systems. |
INCLUDE | Allows you to specify a list of users who are allowed exclusive access to the TASKING software. |
EXCLUDE | Allows you to disallow certain people use of the TASKING software. |
GROUP | Allows the specification of a group of users for use in the other commands. |
TIMEOUT | Allows licenses that are idle to be returned to the free pool, for use by someone else. |
NOLOG | Causes messages of the specified type to be filtered out of the daemon's log output. |
Table A-1: Daemon options file keywords
In order to use the daemon options capability, you must create a daemon options file and list its pathname as the fourth field on the DAEMON line for the Tasking daemon in the license file. For example, if the daemon options were in file /usr/local/license.opt, then you would modify the license file DAEMON line as follows:
DAEMON Tasking /usr/local/Tasking /usr/local/license.opt
A daemon options file consists of lines in the following format:
RESERVE number feature{USER | HOST | DISPLAY | GROUP} name INCLUDE feature{USER | HOST | DISPLAY | GROUP} name EXCLUDE feature{USER | HOST | DISPLAY | GROUP} name GROUP name <list_of_users> TIMEOUT feature timeout_in_seconds NOLOG {IN | OUT | DENIED | QUEUED} REPORTLOG file
Lines beginning with the sharp character (#) are ignored, and can be used as comments. For example, the following options file would reserve one copy of feature SWxxxxxx-xx for user "pat", three copies for user "lee", and one copy for anyone on a computer with the hostname of "terry"; and would cause QUEUED messages to be omitted from the log file. In addition, user "joe" and group "pinheads" would not be allowed to use the feature SWxxxxxx-xx:
GROUP pinheads moe larry curley RESERVE 1 SWxxxxxx-xx USER pat RESERVE 3 SWxxxxxx-xx USER lee RESERVE 1 SWxxxxxx-xx HOST terry EXCLUDE SWxxxxxx-xx USER joe EXCLUDE SWxxxxxx-xx GROUP pinheads NOLOG QUEUED
The following utilities are provided to facilitate license management by your system administrator. In certain cases, execution access to a utility is restricted to users with root privileges. Complete descriptions of these utilities are provided at the end of this section.
License administration is simplified by the lmstat utility. lmstat allows you to instantly monitor the status of all network licensing activities. lmstat allows a system administrator to monitor license management operations including:
The usage of lmstat is as follows:
lmstat [-a] [-S [DAEMON]] [-f [feature]] [-s [server]] [-t value] [-c license_file] [-A] [-l [regular expression]] -a -- Display everything -A -- List all active licenses -c license_file -- Use "license_file" -S [DAEMON] -- List all users of DAEMON's features -f [feature_name] -- List users of feature(s) -l [regular expression] -- List users of matching license(s) -s [server_name] -- Display status of server node(s) -t value -- Set lmstat timeout to "value"
The lmdown utility allows for the graceful shutdown of all license daemons (both lmgrd and all vendor daemons, such as Tasking) on all nodes. To use lmdown, simply type " lmdown" with the correct license file in either /usr/local/license.dat, or the license file pathname in the environment variable LM_LICENSE_FILE. In addition, lmdown takes the "-c license_file_path" argument to specify the license file location. Since shutting down the servers will cause loss of licenses, execution of lmdown is restricted to users with root privileges.
The lmremove utility allows the system administrator to remove a single user's license for a specified feature. This could be required in the case where the licensed user was running the software on a node that subsequently crashed. This situation will sometimes cause the license to remain unusable. lmremove will allow the license to return to the pool of available licenses.
lmremove is used as follows:
lmremove will remove all instances of "user" on node "host" on display "display" from usage of "feature". If the optional -c file is specified, the indicated file will be used as the license file. Since removing a user's license can be disruptive, execution of lmremove is restricted to users with root privileges.
The lmreread utility will cause the license daemon to reread the license file and start any new vendor daemons that have been added. In addition, all pre-existing daemons will be signaled to re-read the license file for changes in feature licensing information. Usage is:
If the -c option is used, the license
file specified will be read by lmreread, NOT by lmgrd; lmgrd re-reads the file it read originally. Also, lmreread cannot be used to change server node names
or port numbers. Vendor daemons will not re-read their option files as a result of lmreread.
lmdown - graceful shutdown of all license daemons
lmdown [ -c license_file ] [ -q ]
lmdown allows the system administrator to send a message to every license daemon asking it to shut down. The license daemons write out their last messages to the log file, close the file, and exit. All licenses which have been given out by those daemons will be revoked, so that the next time a client program goes to verify his license, it will not be valid.
-c license_file
Use the specified license_file. If no -c
option is specified, lmdown looks for the environment variable LM_LICENSE_FILE in order to find the license file to use. If that environment variable is not set, lmdown looks
for the file /usr/local/flexlm/licenses/license.dat.
-q Quiet mode. If this switch is not specified, lmdown asks for confirmation before asking the license daemons to shut down. If this switch is specified, lmdown will not ask for confirmation.
lmgrd(1),
lmstat(1),
lmreread(1)
lmgrd - flexible license manager daemon
lmgrd [ -c license_file ] [ -l logfile ] [ -t timeout ] [ -s interval ]
lmgrd is the main daemon program for the FLEXlm distributed license management system. When invoked, it looks for a license file containing all required information about vendors and features.
-c license_file
Use the specified license_file. If no -c
option is specified, lmgrd looks for the environment variable LM_LICENSE_FILE in order to find the license file to use. If that environment variable is not set, lmgrd looks
for the file /usr/local/flexlm/licenses/license.dat.
-l logfile Specifies the output log file to use. Instead of using the -l option you can use output redirection (> or >>) to specify the name of the output log file.
-t timeout Specifies the timeout interval, in seconds, during which the license daemon must complete its connection to other daemons if operating in multi-server mode. The default value is 10 seconds. A larger value may be desirable if the daemons are being run on busy systems or a very heavily loaded network.
-s interval Specifies the log file timestamp interval, in minutes. The default is 360 minutes. This means that every six hours lmgrd logs the time in the log file.
lmhostid - report the hostid of a system
lmhostid
lmhostid calls the FLEXlm version of gethostid and displays the results.
The output of lmhostid looks like this:
lmhostid - Copyright (C) 1989, 1990 Highland Software, Inc. The FLEXlm host ID of this machine is "1200abcd"
lmhostid has no command line options.
lmremove - remove specific licenses and return them to license pool
lmremove [ -c license_file ] feature user host [ display ]
lmremove allows the system administrator to remove a single user's license for a specified feature. This could be required in the case where the licensed user was running the software on a node that subsequently crashed. This situation will sometimes cause the license to remain unusable. lmremove will allow the license to return to the pool of available licenses.
-c license_file
Use the specified license_file. If no -c
option is specified, lmremove looks for the environment variable LM_LICENSE_FILE in order to find the license file to use. If that environment variable is not set, lmremove looks
for the file /usr/local/flexlm/licenses/license.dat.
lmreread - tells the license daemon to reread the license file
lmreread [ -c license_file ]
lmreread allows the system administrator to tell the license daemon to reread the license file. This can be useful if the data in the license file has changed; the new data can be loaded into the license daemon without shutting down and restarting it.
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 will always reread the file that it loaded from the original path. If you need to change the path to the license file read by the license daemon, then you must shut down the daemon and restart it with that new license file path.
You can not 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.
-c license_file
Use the specified license_file. If no -c
option is specified, lmreread looks for the environment variable LM_LICENSE_FILE in order to find the license file to use. If that environment variable is not set, lmreread looks
for the file /usr/local/flexlm/licenses/license.dat.
lmstat - report status on license manager daemons and feature usage
lmstat [ -a ] [ -A
] [-c license_file ] [ -f
[feature] ]
[ -l [regular_expression] ] [
-s [server] ] [ -S [daemon] ] [ -t timeout ]
lmstat provides information about the status of the server nodes, vendor daemons, vendor features, and users of each feature. Information can be qualified optionally by specific server nodes, vendor daemons, or features.
-a Display everything.
-A List all active licenses.
-c license_file
Use the specified license_file. If no -c
option is specified, lmstat looks for the environment variable LM_LICENSE_FILE in order to find the license file to use. If that environment variable is not set, lmstat looks
for the file /usr/local/flexlm/licenses/license.dat.
-f [feature] List all users of the specified feature(s).
-l [regular_expression]
List all users of the features matching the given regular_expression.
-s [server] Display the status of the specified server node(s).
-S [daemon] List all users of the specified daemon's features.
-t timeout Specifies the amount of time, in seconds, lmstat waits to establish contact with the servers. The default value is 10 seconds. A larger value may be desirable if the daemons are being run on busy systems or a very heavily loaded network.
The FLEXlm daemons all generate log files containing messages in the following format:
mm/dd hh:mm (DAEMON
name) message
Where:
mm/dd hh:mm Is the month/day hour:minute that the message was logged.
DAEMON name Either "license daemon" or the
string from the DAEMON line that describes your daemon.
In the case where a single copy of the daemon cannot handle all of the requested licenses, an optional "
_" followed by a number indicates that this message comes from a forked daemon.
message The text of the message.
The log files can be used to:
The messages are grouped below into the above three categories, with each message followed by a brief description of its meaning.
This daemon is connected to its peer on node node.
The license daemons log this message when a quorum is up and everyone has selected a master.
An attempt was made to configure a demo version of the software for more than one server host.
user was denied access to N licenses of feature. This message may indicate a need to purchase more licenses.
All daemons list the reason that the daemon has exited.
feature has passed its expiration date.
user has checked back in N licenses of feature at mm/dd/yy hh:mm.
user has checked in N licenses by virtue of the fact that his server died.
The license daemon was started.
A daemon can no longer communicate with its peer on node host, which can cause the clients to have to reconnect, or cause the number of daemons to go below the minimum number, in which case clients may start exiting. If the license daemons lose the connection to the master, they will kill all the vendor daemons; vendor daemons will shut themselves down.
The daemon lost quorum, so will process only connection requests from other daemons.
The license daemon received fatal signal nnn.
The license daemon has detected that multiple copies of vendor daemon xxx are running. The user should kill all xxx daemon processes and re-start the license daemon.
user has checked out N licenses of feature at mm/dd/yy hh:mm
The top-level daemon logs this message when one of the child daemons dies.
A license of feature is reserved for either user name or host name.
Vendor daemon xxx was restarted at internet port nnn.
The license servers try to bind their sockets for approximately 6 minutes if they detect address in use errors.
This license daemon has selected an existing master (node) as the master.
A daemon was requested to shut down via a user-generated kill command.
A (possibly new) server was started for the features listed.
The license daemon is shutting down the vendor daemon xxx.
A vendor daemon logs this message when a shutdown was requested by the license daemon.
The license daemon logs this message whenever it starts a new vendor daemon.
The daemon is attempting a connection to node.
This daemon was run on an invalid hostname.
The hostid is wrong for hostname.
The specified feature name has a bad encryption code.
The options file specified in the license file could not be opened.
The daemons could not agree on a master.
This message is logged when all the connections to a server are lost, which often indicates a network problem.
The vendor daemon has a problem with its lock file, usually because of an attempt to run more than one copy of the daemon on a single node. Locate the other daemon that is running via a ps command, and kill it with kill -9.
The license file does not contain a DAEMON line for daemon.
The TCP license service did not exist in /etc/services.
There is no feature line for feat in the license file.
A vendor daemon found no features to serve. This could be caused by bad data in the license file.
The user has requested a feature that this vendor daemon does not support. This can happen for a number of reasons: the license file is bad, the feature has expired, or the daemon is accessing the wrong license file.
The hostname specified on a SERVER line in the license file does not exist in the network database (probably /etc/hosts).
This message is logged when all the connections to a server are lost. This probably indicates a network problem.
The license daemon logs this message if there are no DAEMON lines in the license file. Since there are no vendor daemons to start, there is nothing to do.
A vendor daemon logs this error if it cannot find its own DAEMON name in the license file.
An error was detected in the accept system call.
A vendor daemon was started with no master selected. This is an internal consistency error in the daemons.
A top-level vendor daemon received an invalid PID message from one of its children (daemon number xxx).
An invalid "server connect" message was received.
The pipe call failed.
A malloc error. Check swap space.
The daemon could not connect to node.
The vendor server could not send its PID to the top-level server in the hierarchy.
A connection request was made to DAEMON, but this vendor daemon is not DAEMON.
A connection request came in from another server without a DAEMON name.
A daemon could not kill its child.
A vendor daemon was started without an internet port.
The "top-level" daemon detected one of its sub-daemon's death. In trying to restart the chain of sub-daemons, it was unable to get the file descriptors to set up the pipes to communicate. This is a fatal error, and the daemons must be re-started.
An error in a read system call was detected.
The hierarchy of vendor daemons has become confused over who holds the control token. This is an internal error.
When a daemon is returning a reservation to the "free reservation" list, it could not find the listhead of features.
An error in a select system call was detected.
The server is exiting. This is normally due to an error.
This vendor daemon was sent a "server hello" message that was destined for a different DAEMON.
Normally, the top-level vendor daemon sends no unsolicited messages. If one arrives, this message is logged. This is a bug.
An internal inconsistency was detected in the daemon's option list.
Check the contents of the license file using the license data sheet for the product. Correct the license file and run the lmreread command. However, do not change the last (fourth) field of a SERVER line in the license file. This cannot have any effect on the error message but changing it will cause other problems.
If this is a first time install then follow the procedure for the error message:
FLEXlm license error, encryption code in license file is inconsistent
because there may be a typo in the fourth field of a FEATURE line of your license file. In all other cases you need a new license because the current license is for an older version of the product.
Replace the FEATURE line for the old version of the product with a FEATURE line for the new version (it can be found on the new license data sheet). Run the lmreread command afterwards. You can have only one version of a feature (previous versions of the product will continue to work).
Make sure the license file exists. If the pathname printed on the line after the error message is incorrect, correct this by setting the LM_LICENSE_FILE environment variable to the full pathname of the license file.
Every user needs to have read access on the license file and at least execute access on every directory component in the pathname of the license file. Write access is never needed. Read access on directories is recommended.
Check the license file. There should be a line starting with:
FEATURE SWiiiiii-jj
where "iiiiii" is a six digit software code and "jj" is
a two digit host code for identifying a compatible host architecture. During product installations the product code is shown, e.g. SW008002, SW019002. The number in
the software code is the same as the number in the product code except
that the first number may contain an extra leading zero (it must be six
digits long).
The line after the license error message describes the expected feature format and includes the host code.
Correct the license file using the license data sheet for the product
and run the lmreread command. There is one catch: do not add
extra SERVER lines or change existing SERVER lines in the license file.
If the LM_LICENSE_FILE variable has been set to the format number@host then see first the solution for the message:
FLEXlm license error, no such feature exists
Run the lmreread program to inform the license server about a changed license data file. If lmreread succeeds informing the license server but the error message persists, there are basically three possibilities:
1. The license password is incorrect. If this is the case then there must be an error message in the log file of lmgrd. Correct the password using the license data sheet for the product. Finally rerun lmreread. The log file of lmgrd is usually specified to lmgrd at startup with the -l option or with >.
2. Your network has more than one FLEXlm license server daemon and the default license file location for lmreread differs from the default assumed by the program. Also, there must be more than one license file. Try one of the following solutions on the same host which produced the error message:
- type:
lmreread -c /usr/local/flexlm/licenses/license.dat
- set LM_LICENSE_FILE to the license file location and retry the lmreread command.
- use the lmreread program supplied with the product SW000098, Flexible License Manager. SW000098 is bundled with all TASKING products.
3. There is a protocol version mismatch between lmgrd and the daemon with the name "Tasking" (the vendor daemon according to FLEXlm terminology) or there is some other internal error. These errors are always written to the log file of lmgrd. The solution is to upgrade the lmgrd daemon to the one supplied in SW000098, the bundled Flexible License Manager product.
On the other hand, if lmreread complains about not being able to connect to the license server then follow the procedure described in the next section for the error message "Cannot read license file data from server". The only difference with the current situation is that not the product but a license management utility shows a connect problem.
This indicates that the program could not connect to the license server daemon. This can have a number of causes. If the program did not immediately print the error message but waited for about 30 seconds (this can vary) then probably the license server host is down or unreachable. If the program responded immediately with the error message then check the following if the LM_LICENSE_FILE variable has been set to the format number@host:
- is the number correct? It should match the fourth field of a SERVER line in the license file on the license server host. Also, the host name on that SERVER line should be the same as the host name set in the LM_LICENSE_FILE variable. Correct LM_LICENSE_FILE if necessary.
In any case one should verify if the license server daemon is running. Type the following command on the host where the license server daemon (lmgrd) is supposed to run.
On SunOS 4.x:
ps wwax | grep lmgrd | grep -v grep
On HP-UX or SunOS 5.x (Solaris 2.x):
ps -ef | grep lmgrd | grep -v grep
If the command does not produce any output then the license server daemon is not running. See below for an example how to start lmgrd.
Make sure that both license server daemon (lmgrd) and the program are using the same license data. All TASKING products use the license file /usr/local/flexlm/licenses/license.dat unless overruled by the environment variable LM_LICENSE_FILE. However, not all existing lmgrd daemons may use the same default. In case of doubt, specify the license file pathname with the -c option when starting the license server daemon. For example:
lmgrd -c /usr/local/flexlm/licenses/license.dat \ -l /usr/local/flexlm/licenses/license.log &
and set the LM_LICENSE_FILE environment variable to the license.dat pathname mentioned with the -c option of lmgrd before running any license based program (including lmreread, lmstat, lmdown). If lmgrd and the program run on different hosts, transparent access to the license file is assumed in the situation described above (e.g. NFS). If this is not the case, make a local copy of the license file (not recommended) or set LM_LICENSE_FILE to the form number@host, as described earlier.
If none of the above seems to apply (i.e. lmgrd was already running and LM_LICENSE_FILE has been set correctly) then it is very likely that there is a TCP port mismatch. The fourth field of a SERVER line in the license file specifies a TCP port number. That number can be changed without affecting any license. However, it must never be changed while the license server daemon is running. If it has been changed, change it back to the original value. If you do not know the original number anymore, restart the license server daemon after typing the following command on the license server host:
kill PID
where PID is the process id of lmgrd.