License Administration Tools

Chapter 7

---

FLEXnet Licensing 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 system.
lmswitch	Controls debug log location and size.
lmswitchr	Switches the report log to a new file name.
lmver	Reports the FLEXnet Licensing version of a library or binary file.

	FLEXnet Licensing Version Notes

The lmpath utility introduced in the v7.0 utilities.
The lmborrow utility introduced in the v8.0 utilities.
The lmswitch utility introduced in v8.0 vendor daemon.
The lmswitchr utility introduced in v8.0 vendor daemon.

Running Administration Tools

All FLEXnet Licensing 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 "License Administration Tools-LMTOOLS for Windows."

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 FLEXnet Licensing version of the utility and exits.
-verbose	Displays longer description for all errors found.

	FLEXnet Licensing Version Notes

VENDOR_LICENSE_FILE environment variable honored in utilities starting with v7.0 utilities.
-verbose option introduced in v6.0 of the utilities.

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 by setting the borrow period
Clearing the borrow period
Determining borrow status
Returning a borrowed license early

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 system.
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 FLEXenabled 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/.flexlmborrow (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:

Using the borrowing interface in application, if provided in the application.
Setting the LM_BORROW environment variable directly.

See "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/.flexlmborrow, 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 [-fqdn][-c license_file_list] [-c display] feature

where:

-fqdn	Directs lmborrow to access the borrowing system using its fully qualified host name. Use this option if the license was borrowed based on the fully qualified host name, rather than the relative distinguished name. Use lmstat to determine the format of the host name used when the license was borrowed.
-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.

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.

	FLEXnet Licensing Version Notes

Early borrowed-license return introduced in v8.3 utilities.

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 system, 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

"FLEXLM_DIAGNOSTICS."

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 system 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 server systems to shut down is presented.

---

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

---

When shutting down a three-server redundant license server system, there is a one-minute delay before the servers shut down. lmdown shuts down all three license server systems of a set of redundant license server systems. If you need to shut down one of a set of redundant license server systems (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 server manager, lmgrd. Shutting down the servers causes users to lose their licenses.

See Also

"lmgrd Command-Line Syntax" for details about securing access to lmdown
"lmreread."

	FLEXnet Licensing Version Notes

-all option introduced in the v7.0 lmdown utility.
-force option introduced in the v8.0 lmdown utility.

lmhostid

The lmhostid utility returns the FLEXnet Licensing 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] [-utf8]

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, "Hostids for FLEXnet Licensing-Supported Platforms," 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 dongle identification. This is applicable only for those platforms that support FLEXid dongles. See "FLEXnet Licensing Hostids" for a complete list.
	-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 ###.###.###.###.
-utf8	The hostid is output as a UTF-8 encoded string rather than an ASCII string. If your hostid contains characters other than ASCII A through Z, a through z, or 0 through 9, use this option with lmhostid. To view a correct representation of the resulting hostid, use a utility, such as Notepad, that can display UTF-8 encoded strings.

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

Appendix A, "Hostids for FLEXnet Licensing-Supported Platforms."

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 FLEXnet license formats.

To convert from readable to decimal:

lminstall -i in_lic_file -o out_lic_file -odecimal

To convert to 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.

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.

lmpath

The lmpath utility allows direct control over FLEXnet 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 FLEXnet Licensing registry entry on Windows or $HOME/.flexlmrc on UNIX. lmpath works by setting the FLEXnet Licensing 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.

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 system is running.
port	TCP/IP port number where the license server system 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 server manager, lmgrd, because removing a user's license is disruptive.

See Also

"lmgrd Command-Line Syntax" for details about securing access to lmremove

lmreread

The lmreread utility causes the license server manager 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 vendor daemon vendor rereads the license file and its options file. Additionally, lmgrd restarts vendor if necessary.
-all	If more than one lmgrd is specified, instructs all lmgrds to reread.

---

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. 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 server manager, lmgrd.

See Also

"lmgrd Command-Line Syntax" for details about securing access to lmreread

	FLEXnet Licensing Version Notes

Ability for vendor daemon to participate in rereading of its option file introduced in v8.0 vendor daemon

lmstat

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

Daemons that are running
License files
Users of individual features
Users of features served by a specific vendor daemon
BORROW licenses borrowed

lmstat prints information that it receives from the license server system; 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 system 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 system status: 27000@myhost1
License file(s) on myhost: install_dir/flexlm/v9.3/sun4_u5/counted.lic:
myhost: license server system UP (MASTER) v9.3
Vendor daemon status (on myhost1):

demo: UP v9.3
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.36.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.36.18.26	display	Display where user is running.
v1.0	version	Version of feature.
myhost1	server_host	Host where license server system is running.
27000	port	TCP/IP port on server_host where license server system 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. lmstat -a is a potentially expensive command. With many active users, this command generates a lot of network activity.

---

	FLEXnet Licensing Version Notes

Ability to list all active users, using the -A option, available in lmstat utility, v8.3 and earlier.

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. 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:

"DEBUGLOG"
"lmreread"
Appendix G, "The Debug Log File"

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. 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:

"REPORTLOG"
"lmnewlog"
"lmreread"
Appendix F, "The Report Log File"

lmver

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

Usage is:

lmver filename

where filename is one of the following:

the name of an executable file built with FLEXnet Licensing
lmgrd
a license administration tool
a vendor daemon

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

lmver spell

License Administration Tools-LMTOOLS for Windows

For the 32-bit Windows platforms, a graphical user interface to the license server 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:

starting, stopping, and configuring FLEXnet license server systems
getting system information, including hostids
getting server status

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

Configuration using a license file
Configuration using services

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:

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

Configuration Using Services

Operations are performed on a service, which allows starting lmgrd processes local to the system on which LMTOOLS is running. For details on configuring services, see "Configuring the License Server Manager as a Windows Service."