License Manager Administrator's Guide


Table of Contents


Overview

The Workstation Group License Manager is the software mechanism by which a site manages its floating licenses for uni-XEDIT and uni-SPF and host-based licenses for uni-REXX. The implementation of TWG License Manager is intended to allow you the broadest possible range of flexibility in managing your licenses. Its features include


For purposes of counting concurrent users, TWG License Manager views an individual userid as a user. Regardless of the number of times a userid has logged into the system and regardless of the number of windows in which the user is running a Workstation Group product, that userid still requires only one license for the product in use. The installation program for TWG products validates your product activation keys and starts the license manager daemon for network-based license control.



Glossary of Terms

This section defines terms that are used throughout this guide to describe the operation of the TWG License Manager software. The list includes some "generic" UNIX terminology which you may be encountering for the first time. It also includes terms which are specific to configuration, installation, and maintenance of the TWG License Manager.

activation key
a sequence of characters which contains encrypted information about the license configuration for a specific product; products running under the control of the TWG License Manager cannot be executed without a valid activation key

authorized users
for TWG License Manager maintenance, those users who are authorized to stop the license manager daemon, update control files, or otherwise administer the software configuration

control files
files that contain configuration and execution information specific to your installation of TWG License Manager and of Workstation Group products; these include activation key files, the hostname file, and the master control file

daemon
a program which runs in the background and performs system-wide tasks; in the case of the TWG License Manager, the daemon monitors product license usage, granting and freeing licenses as necessary

file-based
software is run only on an individual workstation; license use is monitored for all users on that workstation through a series of temporary files in the /tmp directory

hostname
in general, the name assigned to a workstation (or server) on the network; as used in this document, the node name of the workstation (or server) on which the License Manager daemon runs in a network-based configuration or the node name of the workstation (or server) for which uni-REXX is licensed

network-based
software licenses are monitored for all users across the entire network by a single daemon running on a single node in the network

node
a workstation on your network designated by a node name; as an example, a network may be composed of four workstations (nodes); each workstation is assigned a name, such as mars, venus, pluto, or saturn; each user normally logs in to a single node and may remotely login to any other node on the network by specifying the appropriate node name on an rlogin command; users may execute software products on any node in the network

pulse interval
the frequency with which the pulse program sends a message to the License Manager daemon

pulse program
a program which periodically sends a message to the License Manager daemon to indicate that a product license is still in use

TCP/IP port
a unique address used for inter-process communications; a TCP/IP port address is used for communication between the pulse program and the License Manager daemon in a network-based installation

timeout interval
the time period (in minutes) that the License Manager daemon will wait for a message from the pulse program before releasing an active license; if a product session terminates normally, the license is released immediately; in all other circumstances (abnormal product session termination, network interruption, or other unexpected events), the daemon will maintain an active license for a session until it receives a message from the pulse program or until it reaches the end of one timeout interval, whichever occurs first; also, the time period that the daemon will wait, after startup, before granting any new licenses; this allows the daemon to receive messages from existing product sessions and update current license usage before granting new licenses



Components of the License Manager

The Workstation Group License Manager is delivered on the distribution media along with the product(s) you have licensed. It is installed automatically as part of the installation of any product.

When your installation is completed successfully, the License Manager components are installed in the directory /usr/local/twglm (or an alternate directory that you have specified). For simplicity in this document, the directory where the TWGLM components are installed is always referred to as /usr/local/twglm.

The directory /usr/local/twglm contains the following files and directories:

twglm script to start the License Manager daemon; suitable for including in any local re-boot configuration files
twglmd License Manager daemon
twgpulse License Manager pulse program
twgmaint script to run the TWGLM maintenance utility
twgmtbin TWGLM maintenance utility
twgfiles master control file required for TWG License Manager execution
twgfiles.def a copy of twgfiles containing the initial settings delivered with the software
twgutil used by twgmtbin to collect usage data
twguser used by twgmtbin to determine the effective userid
twglmkeys directory containing activation key files for each licensed product
twgkey4 program to validate activation keys
twglmhost file containing the hostname of the node on which the TWGLM daemon is running; this file is empty (zero-length) for file-based license management


TWG License Manager Daemon. For network-based installations, the TWG License Manager daemon (twglmd) runs on a designated workstation or server in your network. The node name of this workstation or server is the License Manager hostname. You designate this hostname during installation. This information is stored in the hostname control file (twglmhost) and may be changed if your network configuration changes. File-based installations do not use the License Manager daemon.

Product Activation Keys. For network-based installations, the product activation keys are normally configured to allow the License Manager daemon to run on any node in your network. If your network configuration changes, it is easy to move the License Manager to a different workstation or server by reinstalling with a different hostname.

In some cases, a site may choose to specify that the execution of the License Manager daemon should be restricted to a specific node. In these cases, it is necessary to contact The Workstation Group for a new activation key if you need to move the License Manager software to a different host. If you request restriction of the software to a particular host when ordering the product, the initial activation keys are restricted to that node; and that node name must be specified at installation for storage in the hostname control file. If your initial order does not include this restriction but you later decide that restricting the location of the software is desirable, you must contact The Workstation Group for new activation keys that include the restriction.

Pulse Program. For network-based installations, the pulse program (twgpulse) provides communication between the licensed product (such as uni-XEDIT) and the License Manager daemon. File-based installations do not use the pulse program.

Maintenance Utility. The maintenance utility (twgmaint) automates the process of modifying your installed configuration, monitoring product usage status, and starting or stopping the TWGLM daemon. Each of its functions is available through menu picks; and detail prompts instruct you on the information you should provide at each step.

Master Control File. The master control file (twgfiles) contains the information on the License Manager configuration at your site, including the location of other control files and the list of authorized users of the twgmaint utility. It is required for both network- and file-based installations. The master control file must be located in the same directory as the pulse program. This occurs automatically during installation. The License Manager will not run and products running under its control cannot be executed by users if the master control file is not present.

Subsequent sections of this document describe all the software administration tasks that you may perform for the TWG License Manager. In many cases, a system administrator will simply install the software and restart the daemon if necessary. In other cases, reconfiguration of the system may be performed from time to time. For each task, the use of twgmaint is described in detail.



TWG License Manager Execution

The TWG License Manager is designed to provide maximum flexibility for a site in managing the use of licenses for Workstation Group products. The normal configuration is a network-based installation with no designated host, allowing the site to install the product(s) and the License Manager on any node (server) in the network. This facilitates local administration tasks as well as guaranteeing continuous access to products by end users, since both the product(s) and the License Manager may be moved to a different server without requiring new activation keys. Other combinations of installation type or hostname restrictions are available on request.

Network-based Installations. In this configuration, the TWG License Manager runs as a daemon on a single node (server) in your network. Workstation Group products may be installed on one or more nodes in the network, including the node on which the daemon runs. Starting a product activates the pulse program, which requests a license from the daemon.

The daemon first determines if this request would exceed the maximum number of licenses. If not, the license is granted. If the maximum would be exceeded, the daemon reports this to the user, recommending that the user try again after a brief wait.

While the product session is active, the pulse program sends a message to the daemon periodically to verify that this license is still active. When a user terminates the product session normally, a termination message is sent to the daemon and the license is immediately freed.

A product session may be terminated abnormally for a variety of reasons, including

In these cases, the daemon does not receive a normal termination message from the product. The daemon will wait for a specified interval (timeout interval) before freeing a license from which no message is received. At the end of the timeout interval (default: three minutes), the daemon will automatically free any license that has not sent a message during this period. You may set the timeout interval to an appropriate value for your site using the twgmaint maintenance utility.

The License Manager daemon may be installed on any node in your network. The daemon runs on only one node, regardless of the number of nodes on which license-manager controlled products are installed. At installation, you specify the name of the host on which the daemon will run. Products requiring a license determine the location of the daemon in one of two ways:

If a user has TWGLMHOST defined, the product first tries to communicate with a daemon on that node. If TWGLMHOST is not defined or if no daemon is found on the node named in TWGLMHOST, the product checks the hostname control file for the location of the daemon. If communication with the daemon cannot be established successfully, a diagnostic message appears. The section entitled "Diagnostic Messages" contains a list of all messages, a description of likely causes, and recommendations for correcting the problem.

File-based Installations. In some cases, a site may prefer not to run a daemon on its network. In other cases, Workstation Group products may be running on a stand-alone workstation or may be licensed on a host-specific basis. File-based license management is used in these cases.

In a file-based installation, license activity is managed through a series of files created in the /tmp directory. One file is created for each active license. The file is removed when a product session terminates. These files are very small and should not significantly impact the availability of space in the /tmp directory.

Granting of licenses is managed in the same way as for a network-based system.



Executing the Maintenance Utility

During the installation, you were prompted to identify a directory accessible by your PATH where a symbolic link to twgmaint would be installed. If you bypassed that step, you must change directory to /usr/local/twglm before you can execute twgmaint. The following instructions assume that twgmaint is either in your PATH or that you have already changed directories.

To start the twgmaint utility, type

       twgmaint

The script twgmaint includes as its first line an implicit invocation string for the Bourne shell. Some UNIX implementations notably SCO UNIX do not support such implicit invocation. For these UNIX implementations, you must type

       sh twgmaint

The twgmaint Main Menu appears.

main-menu

The first two options on the menu are accessible to all users. Option 4, configuration maintenance, is restricted to authorized users since configuration files that affect the execution of licensed products may be altered. The sections of this document correspond to the functions available on the twgmaint Main Menu.



Status Information

Option 1 of the twgmaint Main Menu allows you to display License Manager status information, including

Status information is accessible to any user who can execute twgmaint. This may be very useful for all users of TWG products. If a user leaves his or her workstation unattended with an edit session active, that license is unavailable to other users. It may occasionally be necessary to identify sessions that have been "abandoned" in order to free licenses for use by others.

When you select Option 1 from the twgmaint Main Menu, the Activity Monitor Menu appears.

activity-monitor-menu

Select M to return to the Main Menu or Q to terminate twgmaint from this menu.

Select 1 to view summary data about current usage for each product. Summary data is presented for each licensed product that shows

status-report

Product name of the product or product feature to which this data applies; when the product feature is "rexx", this refers to the embedded interpreter in uni-SPF Extended or uni-XEDIT Extended
Current users the number of users who currently have active sessions of this product
Failtype failure mode for this product normally "hard"
Number of licenses number of licenses purchased for this product; for uni-REXX, this normally shows as "0" indicating unlimited users on the host to which it is licensed
Timeout number of days in the evaluation period for this product; this value is the total number of days from beginning to end of the evaluation period; it does not reflect the number of days remaining in the period
Max users since License Manager Service daemon last started for a network-based installation, the greatest number of concurrent users of this product since the last time the daemon was restarted; this is a high-water mark of concurrent use at your site

Press Enter to return to the Activity Monitor Menu.


Select 2 to view userids and license status for all active users.

current-users

This data presented for each product shows

For each active userid, the entry shows

Press Enter to return to the Activity Monitor Menu.


Select 3 to view License Manager installation configuration data.

twgfiles

This display reports the following configuration data:

Logfile the full path name of the file in which license activity is recorded, normally /dev/null; this feature may be activated if needed to analyze LM problems, but it is normally inactive
ControlDir the full path name of the directory where activation key files are stored (default is /usr/local/twglm/twglmkeys)
Hostfile the full path name of the file containing the node name of the workstation where the License Manager daemon is executing (default is /usr/local/twglm/twglmhost)
UtilDir the full path name of the directory where twglm and associated files are installed (default is /usr/local/twglm); used by twgmaint to start the daemon and to collect usage statistics
TCP/IP_Port the unique address that is used for inter-process communication between the pulse program and the License Manager daemon in network-based installations
PulseInterval for network-based installations, the frequency with which the pulse program will send a message to the License Manager daemon to indicate that an active license is still in use; this value is not relevant for file-based installations
PulseTimeOut for network-based installations, the period that the daemon will wait to receive a message from the pulse program before releasing an active license; this value is not relevant for file-based installations
AuthUsers list of userids authorized to modify control files; for network-based installations, these users are also authorized to stop the daemon

Press Enter to return to the Activity Monitor Menu.


Starting the Daemon

Option 2 of the twgmaint Main Menu allows you to start the TWG License Manager daemon. This option is used only for network-based installations. Use this option whenever the daemon is stopped for any reason. This option is accessible to any user who can run twgmaint.

When you successfully start the License Manager daemon, the following message appears:

daemon-started



Maintenance

Option 4 of the twgmaint Main Menu provides access to maintenance functions. These functions include

These functions are restricted to authorized users because they can impact access to and use of Workstation Group software by all users across your entire network.

When you select Option 4 from the Main Menu, the Maintenance Menu appears.

maint-menu

Select M to return to the Main Menu or Q to terminate twgmaint from this menu.

License Manager software maintenance may include any of the following tasks:

Though you may never need to perform any of these tasks, each is easily performed by selecting the appropriate option from the Installation and Maintenance Menu.


Modifying Installation Parameters. Select 2 from the Maintenance Menu to review and/or modify installation configuration parameters without performing a complete installation.

install-parms1

To display your current installation parameters, twgmaint must know the location of the currently active master control file (twgfiles). It attempts to locate the current master control file and displays this information to assist you. You must, however, confirm or correct this information. When the correct control file is located, the utility displays the current settings of all installation parameters.

install-parms2

For file-based installations, you may ignore the data shown in items 3-6.

At this point screen you have several choices:

modify a specific parameter type the number of the parameter you wish to modify and answer the prompts
accept these values type K and press Enter; the installation process proceeds
restore the values from the most recent installation type R and press Enter; this screen reappears with the previous values; all these choices are still available
restore the default values delivered with the License Manager software type D and press Enter; this screen reappears with the default values; all these choices are still available to you
terminate the modification process type Q and press Enter; you are prompted to press Enter again to return to the Maintenance Menu


Updating Activation Keys. Select 3 from the Maintenance Menu to update activation keys or to add keys for additional products.

new-keys

Type a new activation key and press Enter. twgmaint validates the key and installs it in the proper location.

At any point, you may type Q to terminate this function. twgmaint prompts you to press Enter to return to the Maintenance Menu.


Moving the Daemon to a Different Host. Select 4 from the Maintenance Menu to change the name of the host where the License Manager daemon runs.

new-host

If the current hostname setting (as shown on the display) is correct, press Enter.

To modify the hostname, type the new hostname you have chosen. You may also type Q to end this function.


Stopping the Daemon. Select 5 from the Maintenance Menu to stop the License Manager daemon. When the daemon stops successfully, the following informational messages appear:

daemon-stopped

Refer to the section entitled "Diagnostic Messages" if different messages appear.



Diagnostic Messages

The following diagnostic messages may occur during execution of twgmaint or a licensed TWG product. The probable cause of the message and suggested remedy is shown.

License control information could not be located.
License Manager Service daemon requires write access to a logfile.

The master control file must include a description of the full path name for the name of the logfile, normally /dev/null. All users of Workstation Group products must have write permission to this logfile. One of the following errors has occurred:

Verify your installation configuration. Option 3 of the twgmaint Main Menu allows you to review the current contents of the master control file. Be sure that the logfile shown exists and has write permission for all users. If the master control file has been damaged, modify it using Option 2 of the twgmaint Maintenance Menu. You must be an authorized user to access these functions.


License control information obtained from: path/twgfiles
A socket communication error has occurred.
Specified host: hostname cannot be found.

Communications between the License Manager daemon and the pulse program have been broken. The specified hostname cannot be found in your network configuration at this time. This may occur for any of the following reasons:


License control information obtained from: path/twgfiles
License Manager Service daemon already running.

A License Manager daemon is already running on the workstation where you are trying to start a daemon. It is not necessary to restart the daemon at this time.


License control information obtained from: path/twgfiles
License Manager Service daemon not running.

The License Manager daemon has stopped. In a network-based installation, you cannot stop the daemon or start Workstation Group products when the daemon is not running. Use Option 2 of the twgmaint Main Menu to restart the daemon. A daemon may have been stopped intentionally by system administration staff for network or work-station maintenance or for License Manager software maintenance. A daemon may have been stopped unintentionally because of a network interruption, power outage, or other hardware problem or because an authorized user inadvertently killed the process associated with the daemon.


License control information obtained from: path/twgfiles
License Manager Service daemon stopped.

You have successfully stopped the License Manager daemon. This message is simply informational.


License control information obtained from: path/twgfiles
No network based licenses found. License Manager Service daemon not required.

Activation keys for all licensed products specify file-based installation. A License Manager daemon is therefore not required and has not been started.


License control information obtained from: path/twgfiles
Product activation key is either invalid or missing.

The License Manager daemon requires access to all product activation keys at initialization. The daemon did not start for one of the following reasons:

Verify your installation configuration or make necessary modifications. Use Option 2 from the twgmaint Maintenance Menu to review your installation configuration and make modifications if necessary. Use Option 3 from the twgmaint Maintenance Menu to reinstall activation keys. If you cannot locate valid activation keys, contact The Workstation Group or your local distributor for assistance.


License to use product could not be granted.
All available licenses are in use. Please try again later.

At the present time, all licenses are in use. If you wait a few minutes before trying to run the product again, it is likely that one of the licenses will be released. If your need for the product is urgent, use Option 2 from the twgmaint Activity Monitor Menu to see the userids currently holding licenses for this product. If you do not know how to use twgmaint or if you need assistance in gaining access to the product, contact the TWG License Manager administrator at your site.


License to use product could not be granted.
License Manager Service daemon not ready.
Please try again in n minutes.

The specified product runs under the control of the TWG License Manager software. At the present time, the License Manager daemon is running but is not yet ready to accept new license requests. Whenever the daemon is restarted (such as after system administration tasks), it must reinstate the data for all currently active licenses before new licenses can be granted. The daemon waits one timeout interval (default is 3 minutes) to consolidate this data before accepting new license requests. You will be able to run the product you need after the specified interval has passed.


License to use product could not be granted.
License Manager Service daemon not running.

The specified product runs under the control of the TWG License Manager software. At the present time, the License Manager daemon has stopped. Use Option 2 of the twgmaint Main Menu to restart the daemon. A daemon may have been stopped intentionally by system administration staff for network or workstation maintenance or for License Manager software maintenance. A daemon may have been stopped unintentionally because of a network interruption, power outage, or other hardware problem or because an authorized user inadvertently killed the process associated with the daemon. If you do not know how to use twgmaint or if you need assistance in restarting the daemon, contact the TWG License Manager administrator at your site.


License to use product could not be granted.
LM pulse program does not exist in your current PATH.

A user has attempted to run a licensed Workstation Group product without having access to the License Manager pulse program. The pulse program is normally located by the setting of LMDIR in the startup script for the product.

Verify that this setting is correct, that the program (twgpulse) has not been inadvertently deleted from directory where TWGLM is installed, and that twgpulse has execute permission for all users.


Only authorized users may stop the License Manager Service daemon. License Manager Service daemon still running.

To prevent unexpected interruption of License Manager service on a network-based installation, stopping the daemon is restricted to a list of authorized users specified in the master control file. Your userid is not included in that list. Contact the TWG License Manager administrator at your site if you believe that you should be an authorized user.


Product activation key is either invalid or missing for product.
The License Manager Service daemon will not start.

The License Manager daemon requires access to all product activation keys at initialization. The daemon did not start because the activation key for the specified product is either missing or invalid. The activation key control file was located successfully, but it does not contain a valid key.

Use Option 3 from the twgmaint Maintenance Menu to reinstall activation keys. You must be an authorized user to access this function. If you cannot locate valid activation keys, contact The Workstation Group or your local distributor for assistance.


Starting License Manager Service daemon.

The License Manager daemon has successfully started.


The host name included in your product activation key is not nodename.
The License Manager Service daemon will not start.

The activation key for the product specified requires that use of this product be restricted to a certain host workstation. The node name on which you have attempted to start the License Manager daemon is different from the host to which this product is restricted. Therefore the daemon did not start. Restart the daemon on the correct host.

If your network configuration has changed such that this product must be moved to a different host, contact The Workstation Group or your local distributor for a new activation key. If your use for this product has changed such that it should no longer be restricted to a particular host, contact The Workstation Group or your local distributor for a new activation key.


Trial or demo period has expired.
The License Manager Service daemon will not start.

You have received a trial copy of a Workstation Group product for a specified evaluation period. This period has now expired. The License Manager daemon did not start because you are no longer authorized to use this product. Please contact The Workstation Group or your local distributor for purchase information or for additional assistance.




© Copyright 2000, The Workstation Group Ltd., All rights reserved.  Last modified: 07 Mar 2000 Comments to: webmaster
 525 Capital Drive  Lake Zurich, IL 60047.   Phone: 800 228 0255  Fax: 847 540 5629