TOCPREVNEXTINDEX

Chapter 7

License Administration Tools

FLEXlm provides utilities for the license administrator to help manage the licensing activities on the network. Always use the newest version of the utilities as possible; they are available for download from www.macrovision.com.

Table 7-1 lists these utilities.

Table 7-1: License Administration Utilities  
Utility
Description
lmborrow
Supports license borrowing.
lmdiag
Diagnoses license checkout problems.
lmdown
Gracefully shuts down selected license daemons (both lmgrd and all vendor daemons) on the license server machine (or on all three machines in the case of three-server redundant servers).
lmhostid
Reports the hostid of a system.
lminstall
Converts license files between different formats.
lmnewlog
Moves existing report log information to a new file name and starts a new report log file with existing file name.
lmpath
Allows users direct control over license file path settings.
lmremove
Releases a hung license to the pool of free licenses.
lmreread
Causes the license daemon to reread the license file and start any new vendor daemons.
lmstat
Displays the status of a license server.
lmswitch
Controls debug log location and size.
lmswitchr
Switches the report log to a new file name.
lmver
Reports the FLEXlm version of a library or binary file.

FLEXlm Version Notes

7.1 Running Administration Tools

All FLEXlm utilities are packaged as a single executable called lmutil. lmutil is either installed as individual commands (either by creating links to the individual command names, or making copies of lmutil as the individual command names), or as a wrapper that runs the individual command as lmutil command. For example, lmutil lmstat, or lmutil lmdown.

On Windows systems, the lmutil command form of the commands are available. There is also a graphical user interface available for these commands —see Section 7.16, “License Administration Tools—LMTOOLS for Windows.”

7.2 Universal lmutil Arguments

The following are valid arguments for most lmutil utilities:

-c license_file_path
Most lmutil utilities need to know the path to the license file. This is specified with a -c license_file_path argument, or by setting the LM_LICENSE_FILE environment variable. Otherwise, the default location is used. The utilities also honor all VENDOR_LICENSE_FILE environment variables. Some utilities take more than one license file path in a license-file list separated by colons on UNIX and semi-colons on Windows.
Pathnames which include spaces have to be enclosed in double quotes.
-help
Displays usage information and exits.
-v
Displays the FLEXlm version of the utility and exits.
-verbose
Displays longer description for all errors found.

FLEXlm Version Notes

7.3 lmborrow

lmborrow supports borrowing of licenses that contain the BORROW attribute. It must be run on the machine where licenses are borrowed. It is used to perform the following:

Initiating Borrowing

To initiate borrowing, the user sets the borrow period by running lmborrow from the command line or through LMTOOLS:

lmborrow {vendor | all} enddate [time]

where:

vendor
The vendor daemon name that serves the licenses to be borrowed, or all specifies all vendor daemons in that license server.
enddate [time]
Date the license is to be returned in dd-mmm-yyyy format. time is optional and is specified in 24-hour format (hh:mm) in the FLEXlm-licensed application’s local time. If time is unspecified, the checkout lasts until the end of the given end date.

For example:

lmborrow sampled 20-aug-2001 13:00

This has the effect of setting LM_BORROW with the borrow period in either the registry (Windows) or in $HOME/.flexlmrc (UNIX).

To borrow licenses for the desired vendor, on the same day and the same machine that the user runs lmborrow, run the application(s) to check out the license(s). If you run the application(s) more than once that day, no duplicate licenses are borrowed. No licenses are borrowed if the application is run on a day different than the date borrowing is initiated.

In addition to the lmborrow utility, there are other ways to initiate borrowing:

See Section 8.4.1, “Initiating License Borrowing,” for more information on these other ways.

Clearing the Borrowed License Setting

To clear the LM_BORROW setting in the registry or $HOME/.flexlmrc, issue the command:

lmborrow -clear

Clearing the LM_BORROW setting stops licenses from being borrowed until borrowing is initiated again. A user might run lmborrow -clear after he has borrowed licenses for features that are used offline if—before disconnecting from the network—he wants to run an application that checks out additional features, served by vendor, that are not meant to be borrowed. Clearing LM_BORROW does not change the status for already-borrowed licenses.

Determining Borrowed License Status

To print information about borrowed features, issue the following command on the machine from which they are borrowed:

lmborrow -status

The borrowing system does not have to be connected to the network to determine the status.

Returning a Borrowed License Early

To return a borrowed license early, first reconnect the borrowing system back to the network and then, from the same machine that initiated the borrowing, issue the command:

lmborrow -return [-c license_file_list]
                  [-c display] feature

where:

-c license_file_list
Use the specified license file(s). In some configurations, the license file needs to be specified in order to return the license file early.
-d display
Used to specify the display from which the borrow was initiated. Required if your current display is different than what was used to initiate the borrow.
On Windows, it is the system name or, in the case of a terminal server environment, the terminal server client name. On UNIX, it is in the form /dev/ttyxx or the X-Display name.
feature
The name of the borrowed feature to be returned early. Use
    lmborrow -status
to get a list of borrowed feature names.

This option may or may not be allowed by your vendor. Check directly with your vendor to determine if early borrowed-license return is supported.

Returning the license early has the effect of clearing the LM_BORROW setting for the vendor daemon that serves the returned license.

If the borrowing system is not placed back on the network before attempting the early return, the license is not returned and LM_BORROW is kept intact. Additionally, an error message is issued to the end user with notification that the system needs to be connected to the network.

FLEXlm Version Notes

7.4 lmdiag

lmdiag allows you to diagnose problems when you cannot check out a license.

Usage is:

lmdiag [-c license_file_list] [-n] [feature[:keyword=value]]

where:

-c license_file_list
Diagnose the specified file(s).
-n
Run in non-interactive mode; lmdiag does not prompt for any input in this mode. In this mode, extended connection diagnostics are not available.
feature
Diagnose this feature only.
keyword=value
If a license file contains multiple lines for a particular feature, select a particular line for lmdiag to report on. For example:
lmdiag f1:HOSTID=12345678
attempts a checkout on the line with the hostid “12345678.” keyword is one of the following: VERSION, HOSTID, EXPDATE, KEY, VENDOR_STRING, ISSUER

If no feature is specified, lmdiag operates on all features in the license file(s) in your list. lmdiag first prints information about the license, then attempts to check out each license. If the checkout succeeds, lmdiag indicates this. If the checkout fails, lmdiag gives 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 TCP/IP port on the license server machine, and detects if the port number in the license file is incorrect. lmdiag indicates each TCP/IP 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.

See Also

7.5 lmdown

The lmdown utility allows for the graceful shutdown of selected license daemons (both lmgrd and selected vendor daemons) on all machines.

Usage is:

lmdown -c license_file_list [-vendor vendor_daemon] [-q]
          [-all] [-force]

where:

-c license_file_list
Use the specified license file(s). Note that specifying -c license_file_list is always recommended with lmdown
-vendor vendor_daemon
Shut down only this vendor daemon. lmgrd continues running. Requires v6.0 lmdown and lmgrd.
-q
Don’t prompt or print a header. Otherwise lmdown asks “Are you sure? [y/n]: .”
-all
If multiple servers are specified, automatically shuts down all of them. -q is implied with -all.
-force
If licenses are borrowed, lmdown runs only from the machine where the license server is running, and then only if the user adds -force.

If lmdown encounters more than one server (for example if -c specifies a directory with many *.lic files) and -all is not specified, a choice of license servers to shut down is presented.

Note: On UNIX, do not use kill -9 to shut down the license servers. On Windows, if you must use the Task Manager to kill the FLEXlm service, be sure to end the lmgrd process first, then all the vendor daemon processes.

To stop and restart a single vendor daemon, use lmdown -vendor vendor, then use lmreread -vendor vendor to restart the vendor daemon.

When shutting down a three-server redundant license server, there is a one-minute delay before the servers shut down. lmdown shuts down all three license servers of a set of redundant license servers. If you need to shut down one of a set of redundant license servers (not recommended because you are left with two points of failure), you must kill both the lmgrd and vendor daemon processes on that license server machine.

You can protect the unauthorized execution of lmdown when you start up the license manager daemon, lmgrd. Shutting down the servers causes users to lose their licenses.

See Also

FLEXlm Version Notes

7.6 lmhostid

The lmhostid utility returns the FLEXlm hostid of the current platform. Invoked without any arguments, lmhostid displays the default hostid type for current platform. Otherwise, the hostid corresponding to the requested type is displayed, if supported on the current platform.

Usage is:

lmhostid [-n] [-type]

Where:

-n
Only the hostid, itself, is returned as a string, which is appropriate to use with HOSTID= in the license file. Header text is suppressed.
-type
One of the following hostid types.
If not specified, the default hostid for the current platform is displayed. See Appendix A, “Expected FLEXlm Hostids,” for a list of the default types.
 
Platform Dependent Hostids
 
-ether
Ethernet address.
 
-string
String id.
 
-vsn
Volume serial number. (Windows platforms only)
 
-flexid
Parallel or USB FLEXid hardware key identification. (Windows platforms only)
 
-long
32-bit hostid.
 
Platform Independent Hostids
 
-user
Current user name.
 
-display
Current display name. On Windows, it is the system name or, in the case of a terminal server environment, the terminal server client name. On UNIX, it is in the form /dev/ttyxx or the X-Display name.
 
-hostname
Current host name.
 
-internet
IP address of current platform in the form ###.###.###.###.

The output of this command looks as follows:

lmhostid - Copyright (c) 1989, 2002 Macrovision Corporation
The FLEXlm hostid of this machine is "69021c89"

See Also

7.7 lminstall

Introduced in v6.0, lminstall is designed primarily for typing in decimal format licenses to generate a readable format license file.

Usage is:

lminstall [-i in_lic_file ] [-maxlen n] [-e err_file] \
          [-o out_lic_file] \
          [-overfmt {2 | 3 | 4 | 5 | 5.1 | 6 | 7 | 7.1 | 8}] \
          [-odecimal]

Normally, to convert from decimal to readable format, lminstall is used with no arguments; you are prompted for the name of the output license file. The default file name is today’s date in yyyymmdd.lic format. Move this file to the application’s default license file directory, if specified by the software vendor. Otherwise, use the LM_LICENSE_FILE or VENDOR_LICENSE_FILE environment variables to specify the directory where the *.lic files are located.

To finish entering, type q on a line by itself or enter two blank lines.

When an input file is specified with no output file specified, output goes to stdout; if neither input nor output file is specified, lminstall assumes that input comes from stdin and prompts the user for an output file name.

lminstall is also used to convert licenses from readable to decimal format, and between different versions of FLEXlm license formats.

To convert from readable to decimal:

lminstall -i in_lic_file -o out_lic_file -odecimal

To convert to FLEXlm v5.1 format:

lminstall -i in_lic_file -o out_lic_file -overfmt 5.1

To enforce a maximum line length of, for example, 50 characters:

lminstall -maxlen 50

Conversion errors are reported as necessary and can be written to a file by specifying -e err_file. lminstall has a limit of 1000 lines of input.

7.8 lmnewlog

The lmnewlog utility switches the report log file by moving the existing report log information to a new file, then starting a new report log with the original report log file name. If you rotate report logs with lmnewlog instead of lmswitchr, you do not have to change the file name in the REPORTLOG line of the vendor’s options file. Requires a v7.1+ vendor daemon.

Usage is:

lmnewlog [-c license_file_list] feature renamed_report_log

or:

lmnewlog [-c license_file_list] vendor renamed_report_log

where:

-c license_file_list
Use the specified license file(s).
feature
Any feature in this license file.
vendor
Vendor daemon in this license file.
renamed_report_log
New file path where existing report log information is to be moved.

7.9 lmpath

The lmpath utility allows direct control over FLEXlm license path settings. It is used to add to, override, or get the current license path settings.

Usage is:

lmpath {-add | -override} {vendor | all} license_file_list

where:

-add
Prepends license_file_list to the current license-file list or creates the license-file list, if it doesn’t exist, initializing it to license_file_list. Duplicates are discarded.
-override
Overrides the existing license-file list with license_file_list. If license_file_list is the null string, "", the specified list is deleted.
  • lmpath -override all ""
    Deletes the value of LM_LICENSE_FILE.
  • lmpath -override vendor ""
    Deletes the value of VENDOR_LICENSE_FILE.
vendor
A vendor daemon name. Effects the value of VENDOR_LICENSE_FILE.
all
Refers to all vendor daemons. Effects the value of LM_LICENSE_FILE.
license_file_list
A colon-separated list on UNIX and a semi-colon-separated list on Windows. If license_file_list is the null string, "", then the specified entry is deleted.

Note: lmpath works by setting the FLEXlm registry entry on Windows or $HOME/.flexlmrc on UNIX.

To display the current license path settings, use:

lmpath -status

The following is displayed:

lmpath - Copyright (C) 1989-2002 Macrovision Corporation
Known Vendors:
_____________
demo: ./counted.lic:./uncounted.lic
_____________
Other Vendors:
______________
/usr/local/flexlm/licenses/license.lic

Note that where the path is set to a directory, all the *.lic files are listed separately.

7.10 lmremove

The lmremove utility allows you to remove a single user’s license for a specified feature. If the application is active, it re-checks out the license shortly after it is freed by lmremove.

Usage is:

lmremove [-c license_file_list] feature user user_host display

or

lmremove [-c license_file_list] -h feature server_host \
             port handle

where:

-c license_file_list
Specify license file(s).
feature
Name of the feature checked out by the user.
user
Name of the user whose license you are removing, as reported by lmstat -a.
user_host
Name of the host the user is logged into, as reported by lmstat -a.
display
Name of the display where the user is working, as reported by lmstat -a.
server_host
Name of the host on which the license server is running.
port
TCP/IP port number where the license server is running, as reported by lmstat -a.
handle
License handle, as reported by lmstat -a.

The user, user_host, display, server_host, port, and handle information must be obtained from the output of lmstat -a.

lmremove removes all instances of user on user_host and display from usage of feature. If the optional -c license_file_list is specified, the indicated file(s) is used as the license file.

The -h variation uses the server_host, port, and license handle, as reported by lmstat -a. Consider this example lmstat -a output:

joe nirvana /dev/ttyp5 (v1.000) (cloud9/7654 102), start Fri 10/29 18:40

In this example, the user is “joe,” the user host is “nirvana,” the display is “/dev/typp5,” the server host is “cloud9,” the TCP/IP port is “7654,” and the license handle is “102.”

To remove this license, issue one of the following commands:

lmremove f1 joe nirvana /dev/ttyp5

or

lmremove -h f1 cloud9 7654 102

When removing by handle, if licenses are grouped as duplicates, all duplicate licenses are also removed. If license lingering is set and lmremove is used to reclaim the license, lmremove starts, but does not override, the license’s linger time.

You can protect the unauthorized execution of lmremove when you start up the license manager daemon, lmgrd, because removing a user’s license is disruptive.

See Also

7.11 lmreread

The lmreread utility causes the license manager daemon to reread the license file and start any new vendor daemons that have been added. In addition, all currently running vendor daemons are signaled to reread the license file and their end-user options files for changes in feature licensing information or option settings. If report logging is enabled, any report log data still in the vendor daemon’s internal data buffer is flushed. lmreread recognizes changes to server machine host names, but cannot be used to change server TCP/IP port numbers.

If the optional vendor daemon name is specified, only the named daemon rereads the license file and its end-user options file (in this case, lmgrd does not reread the license file).

Usage is:

lmreread [-c license_file_list] [-vendor vendor] [-all]

where:

-c license_file_list
Use the specified license file(s).
-vendor vendor
Only this one vendor daemon rereads the license file. lmgrd restarts the vendor daemon if necessary.
-all
If more than one lmgrd is specified, instructs all lmgrds to reread.

To stop and restart a single vendor daemon, use lmdown -vendor vendor, then use lmreread -vendor vendor, which restarts the vendor daemon.

Note: If you use the -c license_file_list option, the license file(s) specified are read by lmreread, not by lmgrd; lmgrd rereads the file it read originally.

You can protect the unauthorized execution of lmreread when you start up the license manager daemon, lmgrd.

See Also

FLEXlm Version Notes

7.12 lmstat

The lmstat utility helps you monitor the status of all network licensing activities, including:

lmstat prints information that it receives from the license server; therefore, it does not report on unserved licenses such as uncounted licenses. To report on an uncounted license, the license must be added to a served license file and the application must be directed to use the license server for that license file (via @host, port@host or USE_SERVER). Queued users and licenses shared due to duplicate grouping are also not returned by lmstat.

Usage is:

lmstat [-a] [-c license_file_list] [-f [feature]]
       [-i [feature] [-s[server] [-S [vendor]]
       [-t timeout_value]

where:

-a
Displays all information.
-c license_file_list
Uses the specified license file(s).
-f [feature]
Displays users of feature. If feature is not specified, usage information for all features is displayed.
-i [feature]
Displays information from the FEATURE/INCREMENT line for the specified feature, or all features if feature is not specified.
-s [server]
Displays status of all license files listed in $VENDOR_LICENSE_FILE or $LM_LICENSE_FILE on server, or on all servers if server is not specified.
-S [vendor]
Lists all users of vendor’s features.
-t timeout_value
Sets connection timeout to timeout_value. This limits the amount of time lmstat spends attempting to connect to server.

The output of lmstat -a looks similar to:

License server status: 27000@myhost1
License file(s) on myhost: install_dir/flexlm/v9.0/sun4_u5/counted.lic:
myhost: license server UP (MASTER) v9.0
Vendor daemon status (on myhost1):

demo: UP v9.0
Feature usage info:
Users of f1: (Total of 4 licenses issued; Total of 1 license in use)
  "f1" v1.0, vendor: demo
  floating license
    daniel myhost2 19.16.18.26 (v1.0) (myhost1/27000 102), start Fri
         5/3 7:29

where:

daniel
user
User name.
myhost2
user_host
Host where user is running.
19.16.18.26
display
Display where user is running.
v1.0
version
Version of feature.
myhost1
server_host
Host where license server is running.
27000
port
TCP/IP port on server_host where license server is running.
102
handle
License handle.
start Fri 5/3 7:29
checkout_time
Time that this license was checked out.

The user, user_host, display, server_host, port, and handle information is used when removing licenses with lmremove.

Note: lmstat -a is a potentially expensive command. With many active users, this command generates a lot of network activity.

FLEXlm Version Notes

7.13 lmswitch

The lmswitch utility switches the debug log file written by a particular vendor daemon by closing the existing debug log for that vendor daemon and starting a new debug log for that vendor daemon with a new file name. It also starts a new debug log file written by that vendor daemon if one does not already exist.

Usage is:

lmswitch [-c license_file_list] vendor new_debug_log

where:

-c license_file_list
Use the specified license file(s).
vendor
Vendor daemon in this license file.
new_debug_log
Path to new debug log file.

By default, debug log output from lmgrd and all vendor daemons started by that lmgrd get written into the same debug file. lmswitch allows companies to keep separate log files for different vendors and control the size of their debug log file.

If debug log output is not already directed to a separate file for this vendor daemon, lmswitch tells the vendor daemon to start writing its debug log output to a file, new_debug_log. If this vendor daemon is already writing to its own debug log, lmswitch tells the vendor daemon to close its current debug log file and start writing its debug log output to new_debug_log.

Note: The effect of lmswitch continues only until the vendor daemon is shut down or its options file is reread via lmreread. When the vendor daemon is restarted or its options file is reread, it looks for a DEBUGLOG line in the options file to determine whether or not to write its debug log output into its own file and, if so, what file to write.

See Also:

7.14 lmswitchr

The lmswitchr utility switches the report log file by closing the existing report log and starting a new report log with a new file name. It also starts a new report log file if one does not already exist.

Usage is:

lmswitchr [-c license_file_list] feature new_report_log

or with v5.0+ vendor daemon:

lmswitchr [-c license_file_list] vendor new_report_log

where:

-c license_file_list
Use the specified license file(s).
feature
Any feature in this license file.
vendor
Vendor daemon in this license file.
new_report_log
Path to new report log file.

If report logging is not enabled for the vendor daemon, lmswitchr tells it to start writing its report log output to new_report_log. If report logging is already enabled for the vendor daemon, lmswitchr tells the vendor daemon to close its report log file and start writing its new report log output to new_report_log.

Note: The effect of lmswitchr continues only until the vendor daemon is shut down or its options file is reread via lmreread. When the vendor daemon is restarted or its options file is reread, it looks for a REPORTLOG line in the options file to determine whether or not to write report log output to a file and, if so, what file to write.

See Also:

7.15 lmver

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

Usage is:

lmver filename

where filename is one of the following:

For example if you have an application called “spell,” type:

lmver spell

7.16 License Administration Tools—LMTOOLS for Windows

For the 32-bit Windows platforms, a graphical user interface to the license manager tools is provided called LMTOOLS. Always use the newest version of LMTOOLS as possible; it is available for download from www.macrovision.com.

Some of the functions LMTOOLS performs include:

LMTOOLS has two modes in which to configure a license server:

7.16.1 Configuration Using License File

Operations are performed on a particular license file. The file can be either local or remote. In this mode, you cannot start the lmgrd process, but you can do everything else. To configure this mode, perform the following:

  1. Invoke LMTOOLS.
  2. Click the Configuration using License File radio button.
  3. Enter one or more the license file names or port@host specifications.

7.16.2 Configuration Using Services

Operations are performed on a service, which allows starting lmgrd processes local to the system on which LMTOOLS is running. On NT/2000/XP, you configure a Windows Service. On Windows 95/98, you configure a FLEXlm service that behaves similarly to a Windows service.

For details on configuring services, see Section 6.3.2, “Configuring the License Manager as a Windows Service.”

TOCPREVNEXTINDEX

 

FLEXlm End Users Guide
March 2003