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.
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
- 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
- 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
- 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
- software licenses are monitored for all users across the entire network by a single daemon running on a single node in the network
- 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
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.
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.
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
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
The twgmaint Main Menu appears.
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.
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.
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
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.
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.
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.
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:
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.
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.
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.
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.
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.
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:
Refer to the section entitled "Diagnostic Messages" if different messages appear.
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.
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.
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.
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.
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.
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.
© 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