End-users can customize their use of your software via the daemon options file provided by FLEXlm. This options file allows the end-user to reserve licenses for specified users or groups of users, to allow or disallow use of your software to certain people, to set software timeouts. The daemon options file is specified in the license file on the DAEMON line as the fourth parameter as follows:
DAEMON daemon-name path [options-file] |
A daemon options file consists of lines in the following format:
INCLUDE feature {USER|HOST|DISPLAY|GROUP|HOSTGROUP|INTERNET} name
INCLUDEALL feature {USER|HOST|DISPLAY|GROUP|HOSTGROUP|INTERNET} name
EXCLUDE feature {USER|HOST|DISPLAY|GROUP|HOSTGROUP|INTERNET} name
EXCLUDEALL feature {USER|HOST|DISPLAY|GROUP|HOSTGROUP|INTERNET} name
NOLOG {IN|OUT|DENIED|QUEUED}
GROUP name user1 user2 ...
LINGER feature seconds
NOLOG {IN|OUT|DENIED|QUEUED}
REPORTLOG file
RESERVE number feature {USER|HOST|DISPLAY|GROUP|HOSTGROUP|INTERNET} name
TIMEOUT feature timeout_in_seconds
|
Lines beginning with the sharp character (“#”) are ignored, and can be used as comments. If the filename in the REPORTLOG line starts with a “+” character, the old report log file will be opened for append.
Lines can be up to 2000 characters, with backslash `\' continuation character used to make a line easier to read and type.
 | Note: Versions prior to 4.0 did not support the backslash `\' continuation character, and, prior to FLEXlm v3.0, had a line limit of 200 characters. |
All the INCLUDE and EXCLUDE family of options take an internet address in addition to USER, HOST, DISPLAY, and GROUP. The keyword is INTERNET, and the address is specified as follows:
a.b.c.d |
(any of a, b, c, d can be “*”). For example:
INCLUDEALL INTERNET 192.*.*.* |
This allows any user from network number 192 to access any feature supported by this daemon.
The following options file would reserve a copy of feature compile for user pat, three copies for user lee, and a 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 would not be allowed to use the compile feature:
RESERVE 1 compile USER pat RESERVE 3 compile USER lee RESERVE 1 compile HOST terry EXCLUDE compile USER joe NOLOG QUEUED |
If this data were in file /usr/local/flexlm/options/local.options, then you would modify the license file DAEMON line as follows:
DAEMON XXX /usr/local/xxx /usr/local/flexlm/options/local.options |
For LINGER:
For TIMEOUT:
For FLEXadmin: call your Globetrotter Software sales representative.
A license reservation for an entity not contained in the duplicate grouping mask in the lc_checkout() call (e.g., a USER) when the duplicate grouping mask is LM_DUP_HOST | LM_DUP_DISP) can cause an interesting interaction at run-time.
To understand why this is the case, consider the following example:
Your software groups duplicates based on USER and DISPLAY
Your end-user has a license file with a single license
Your end-user reserves this license for HOST “nodea”
User “joe” on display “displaya” on HOST “nodea” checks out a license. He gets the license, since his HOST matches the reservation.
User “joe” on display “displaya” on HOST “nodeb” checks out a license. He also gets a license, since he is grouped with the first license as a duplicate.
The first user (joe/displaya/nodea) checks in his license.
At this point in the example, the situation appears to be inconsistent. The second user continues to hold the reservation, which means that a user on “nodeb” is using a license reserved for nodea. Once this second user checks in the license, the reservation will return to the pool of reservations, to be used by anyone on “nodea”.
Globetrotter Software believes that the potential temporary inconsistency is better than the alternative, which is to have an unusable reservation.
All license administration tools are contained in the single executable lmutil. lmutil contains the following utility programs:
lmutil behavior is determined by its first argument, or its argv[0] name. lmutil renamed to lmstat will behave the same as “lmutil lmstat”. The INSTALL script creates hard links from lmutil to all program names listed when you install your FLEXlm kit. You should also create the hard links when your software is installed on your customer's system.
All utilities take the following arguments:
| -v | print version and exit | |
| -c license_file | operate on “license file” |
| Note: The lmdown, lmremove, and lmreread commands are “privileged”. If you have started lmgrd with the “-p -2” switch, you must be a “license administrator” to run any of these three utilities. A “license administrator” is a member of the UNIX “lmadmin” group, or, if the lmadmin group does not exist, a member of group 0. In addition, lmgrd -x can disable lmdown and/or lmremove. |
The lmcksum program will perform a checksum of a license file. This is useful to verify data entry errors at your customer's location. lmcksum will print a line-by-line checksum for the file as well as an overall file checksum. If the license file contains “cksum=nn” attributes, the bad lines will be automatically indicated.
lmcksum will ignore all fields that do not enter into the license key 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 will treat non-case sensitive fields correctly (in general, lmcksum is not case-sensitive). lmcksum takes the “-k” switch to force the license key checksum to be case-sensitive.
lmcksum takes an optional daemon name; if specified, only license file lines for the selected daemon are used to compute the checksums.
By default, lmcksum operates on license.dat in the current directory. Specify -c license_file if you want to checksum another license file. Example output is:
lmcksum - Copyright (C) 1989, 1994 Globetrotter Software, Inc. lmcksum: using license file "/usr/local/flexlm/licenses/license.dat" 189: SERVER speedy 08002b32b161 2837 166: DAEMON demo /u/gsi/lmgr/src/testsuite/demo 8: FEATURE f1 demo 1.000 01-jan-99 0 3B2BC33CE4E1B8F3A0BF "" 08002b32b161 109: (overall file checksum) |
lmdiag allows you to diagnose problems when you cannot check out a license.
lmdiag [-c license_file] [-n] [feature] |
| where: | is the: | |
| -c license_file | path to file to diagnose. | |
| -n | run in non-interactive mode; lmdiag will not prompt for any input in this mode. In this mode, extended connection diagnostics are not available. | |
| feature | diagnose this feature only. |
If no feature is specified, lmdiag will operate on all features in the license file(s) in your path. lmdiag will first print information about the license, then attempt to check out each license. If the checkout succeeds, lmdiag will indicate this. If the checkout
fails, lmdiag will give you the reason for the failure. If the checkout fails because lmdiag cannot connect to the license server, then you have the option of running “extended connection diagnostics”.
These 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 will indicate each port number that is listening, and if it is an lmgrd process, lmdiag will indicate this as well. If lmdiag finds the vendor daemon for the feature being tested, then it will indicate the correct port number for the license file to correct the problem.
The lmdown utility allows for the graceful shutdown of all license daemons (both lmgrd and all vendor daemons) on all nodes.
Usage is:
% lmdown [-c license-file]
|
The daemons which will be shut down will be the daemons specified in /usr/local/flexlm/licenses/license.dat(or C:\FLEXLM\LICENSE.DAT for Windows and Windows NT) 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. If you wish to restrict the use of lmdown to license administrators, start lmgrd with the “-2 -p” switch. It is reasonable to restrict the execution of lmdown, since shutting down the servers will cause loss of licenses. To disable lmdown, the license administrator can use “lmgrd -x lmdown”.
The lmhostid program is used to print the correct hostid value on any machine supported by FLEXlm. Usage is:
lmhostid [type]
|
The output from lmhostid will be similar to the following:
lmhostid - Copyright (C) 1989, Globetrotter Software, Inc. The FLEXlm host ID of this machine is "1200abcd" |
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 — in these cases, due to a limitation in the way TCP works, it can take several hours for the license server to detect that the user is gone. This situation will sometimes cause the license to remain unusable.
| Note: Note:If the application is still active when it is removed with lmremove, it will simply checkout the license again (assuming the applications FLEXlm timers are enabled, or lc_timer() is called). lmremove therefore cannot be used to “steal” licenses. |
lmremove will allow the license to return to the pool of available licenses.
Usage is:
lmremove [ -c file ] feature user host display |
The user host display information must be obtained from the output of lmstat -a.
lmremove removes all instances of user on host on display from usage of feature. If the optional “-c file” is specified, the indicated file is used as the license file. The end-user system administrator should protect the execution of lmremove since removing a user's license can be disruptive.
An alternate usage, which makes use of the license handle in the vendor daemon, is:
lmremove [-c file] -h feature serverhost port handle |
This variation uses the severhost, port, and license handle, as reported by lmstat –a. Consider this example lmstat –a output:
joe cloud7 /dev/ttyp5 (v1.000) (cloud9/7654 102), start Fri 10/29 18:40 |
In this example, the serverhost is “cloud9”, the port is “7654” and the license handle is 102, so to remove this license, issue the following command:
lmremove -h f1 cloud9 7654 102 |
or
lmremove f1 joe cloud7 /dev/ttyp5 |
When removing by handle, if licenses are grouped as duplicates, all duplicate licenses will also be removed.
The lmreread utility causes 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. If the optional daemon name is specified, only the named daemon will re-read the license file (in this case, lmgrd does not re-read the license file either).
Usage is:
lmreread [ daemon ]
|
| Note: 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. |
License administration is simplified by the lmstat utility. lmstat allows the user of FLEXlm to instantly monitor the status of all network licensing activities. lmstat allows a system administrator at an end-user (or application developer) site to monitor license management operations including:
which daemons are running
users of individual features
users of features served by a specific DAEMON
Usage is:
lmstat [-a] [-S [daemon]] [-f [ feature]] [-i 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] | Restrict output to one daemon, and the features and users of that daemon | |
| -f [feature_name] |
| |
| -i [feature_name] |
| |
| -s [server_name] |
| |
| -t value | Set lmstat timeout to value |
lmremove requires the output of lmstat -a.
| Note: lmstat -a is a potentially expensive command. With lots of active users, this call can generate a lot of network activity, and therefore should not be used too often. |
| Note: The lmswitch command is available on VMS only. |
The lmswitch utility switches the debug log file for the daemon serving the specified feature while the daemon is running.
Usage is:
lmswitch feature new-file
|
| where: | is the: | |
| feature | any feature this daemon supports. | |
| new-file | New file path. |
Of course, for this syntax to work, lmswitch needs to be installed as a foreign command.
The new logfile will be opened for write, rather than append, so it is possible to “switch” to the same filename in order to be able to view the old log file.
The lmswitchr utility switches the FLEXadmin (REPORTLOG) log file for the specified feature.
Usage is:
lmswitchr feature new-file
|
“End-User Options File” for REPORTLOG
The FLEXlm daemons create an ascii Debug log file on stdout. There are several processes in a parent-child hierarchy which are sharing the same file pointer, so this log file cannot be changed after the vendor daemons have been started, since each process has a copy of the current offset, etc.
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 each line to a file. This is done as follows:
Instead of the “normal” startup:
% lmgrd > LOG |
Start lmgrd this way:
% lmgrd -z | sh -c 'while read line; do echo "$line" >> LOG ; done' |
With this startup method, the output file “LOG” can be renamed and a new log file will be created. You could even make “LOG” a symbolic link and change the value of the link to “switch” the log file.
FLEXlm v3.0 and later optionally support the UDP connectionless transport, in addition to the default TCP connection-based transport. Note that this does not apply to VMS systems. See “Communications transport” for a discussion of VMS communications transport.
UDP can be selected by the application or by the end-user, in the following ways:
The application can call:
lc_set_attr(LM_A_COMM_TRANSPORT, LM_UDP);
The end-user can set the comm transport with the FLEXLM_COMM_TRANSPORT environment variable:
% setenv FLEXLM_COMM_TRANSPORT UDP
The comm transport can be selected in the daemon options file, with the line:
TRANSPORT UDP
or
TRANSPORT TCP
The application can prevent the user from setting the TRANSPORT mode via:
lc_set_attr(LM_A_ALLOW_SET_TRANSPORT, 0); |
The environment variable and options file settings are disabled with this call.
FLEXlm defaults to TCP, and all the above options can be set to TCP. The order of precedence is (higher number takes precedence over lower number):
Servers that use UDP clients require a small, fixed number of sockets. This can be preferable on systems with limited resources and a large number of clients (500 or more). In addition, they never need to spawn additional vendor daemons, as TCP servers do when they use up the maximum number of file descriptors.
When a UDP client dies without doing a checkin, the server does not become immediately aware of this, but will time the license out. Therefore, applications should always call lc_checkin() before exiting. The default for a timeout is 45 minutes, but can be set in the application via:
lc_set_attr(LM_A_UDP_TIMEOUT, <# seconds>);
Therefore, a UDP client which does not, or is unable to, call lc_checkin(), will have a license checked out for 45 minutes (by default) after the program exits. This behavior will also be affected by LM_A_CHECK_INTERVAL. In particular, for UDP clients, LM_A_CHECK_INTERVAL must never be longer than LM_A_UDP_TIMEOUT, or the client will be timed out for no good reason. This is not normally fatal, but a client could lose a license to someone else in trying to retrieve it after being timed out.
Applications that call lc_timer directly must ensure that they call it often enough to prevent being timed out.
When a client has to reconnect to a server (which can happen for numerous reasons), the reconnection process requires 10 seconds for the client to timeout the read from a server which is down. With TCP, this recognition is instantaneous. The result is that a server's failure will cause a client using UDP to hang for a minimum of 10 seconds, while with a TCP client, this recognition is transparent.
In Globetrotter Software's testing environment, we have found no discernible performance advantage in checking out licenses or getting status information via either TCP or UDP.
Based on test results, we find TCP to be a far superior mode of communication, and should be used wherever possible.