RapidRMA and FLEXlm Licensing

Table of Contents

01. Introduction

02. FLEXlm HostID

03. Evaluation License: No License Manager Server, Any Host, Any User

04. Node-Locked License: No License Manager Server, Specific Node, Any User

05. Floating License: License Manager Server, Any Host, Any User

05.01. License Server

05.02. License Client

06. References

01. Introduction

This technote describes the FLEXlm licensing for RapidRMA. At this time we use three kinds of licenses: (1) evaluation, (2) node-locked, and (3) floating. We discuss each in a subsection below.

02. FLEXlm HostID

FLEXlm was developed in the Unix world where a workstation has a unique identifier called a “hostid”, a value stored in the workstation's non-volatile RAM (NVRAM). Adapting this to Windows, FLEXlm tries to use something unique and relatively permanent on the computer that can be interrogated. One candidate is the MAC address for an ethernet NIC. Another candidate is the disk volume-serial number. When considering a hostid for a Windows computer, we need to know which element is being used. So, the hostid usually has the form “element=value”. For example, the hostid based on a disk volume-serial number is a string like

DISK_SERIAL_NUM=ffffffff

Users may obtain the FLEXlm hostid of a Windows computer by using one of the FLEXlm vendor's utilities. These utilities may be downloaded from their website at http://www.macrovision.com/services/support/flexlm/lmgrd.shtml. On this page, about a third of the way down the page, is the heading "Windows Platforms" and underneath the heading are links to the end-user utility downloads.

lmtools.exe

The FLEXlm Windows application lmtools.exe displays a window as shown in Figure 02-A. The window has a set of tabs. The tab labeled “System Settings” displays items for the “Ethernet address” (MAC address) and for the "Disk Volume Serial Number".

lmutil.exe

The FLEXlm command-line utility lmutil.exe can be run in a DOS command prompt window. The commands below show how to get the hostid based on the disk volume-serial number and the ethernet address, respectively.

lmutil lmhostid -vsn

lmutil lmhostid -ether

FIGURE 02-A. LMTOOLS window showing “System Settings” tab with hostids..

For the evaluation and node-locked licenses, I recommend using the disk volume-serial number so one doesn't need to worry whether or not there is a network card or if networking is up or down. For the floating license, we can safely assume that there is a networking card and networking is up. I tend to use the ethernet address for floating licenses.

NOTE: Which computer's hostid needs to be used, depends on the license type.

Node-Locked License

Use the hostid from the computer where RapidRMA will run.

Floating License

Use the hostname and hostid from the computer where the license manager (lmgrd.exe) will run.

03. Evaluation License: No License Manager Server, Any Host, Any User

The evaluation license allows the RapidRMA application to run on any computer for any user. This type of license is provided to customers who wish to evaluate the software or to other users for temporary, short-term needs. It is easy to use because it works on any computer, and customers do not need to provide hostids. It is usually set to expire within a couple weeks. We want to make it widely available to anyone who wants to examine the product.

A sample license file is shown in Figure 03-A.

FEATURE RapidRMA tripac 1.0 30-dec-1999 uncounted E79387341D47 HOSTID=DEMO ck=107

#NOTE: You can edit the hostname on the server line (1st arg).
#      The (optional) daemon-path on the VENDOR line (2nd arg).
#      Most other changes will invalidate this license.

Copy the file as license.lic into the RapidRMA License subdirectory. Thus, if RapidRMA is installed in the folder C:/Program Files/RapidRMA, then the whole pathname of the license file is C:/Program Files/RapidRMA/license/license.lic.

Use the default rma.bat (Figure 03-B); the full pathname of this file is C:/Program Files/RapidRMA/rma.bat. The invocation of the java on the second line assumes that the JRE is installed in the C:/Program Files/JavaSoft folder.

@ECHO OFF
"C:\Program Files\JavaSoft\JRE\1.3\bin\javaw.exe" -cp .;jbcl.jar;dx.jar;RapidRMA.jar com.tripac.rapidrma.RapidRMA

04. Node-Locked License: No License Manager Server, One Node, Any User

The node-locked license restricts the RapidRMA application to run on one specific computer. The customer must provide the hostid for the computer they will use to run the product. This type of license is the simplest and most popular for single users. One need not bother installing, configuring, and maintaining separate FLEXlm license manager software.

This type of license file looks like the sample in Figure 04-A.

FEATURE RapidRMA tripac 1.0 30-dec-1999 uncounted EADF1BA331A0 HOSTID=DISK_SERIAL_NUM=26391503 ck=143

#NOTE: You can edit the hostname on the server line (1st arg).
#      The (optional) daemon-path on the VENDOR line (2nd arg).
#      Most other changes will invalidate this license.

Copy the file as license.lic into the RapidRMA license subdirectory (so the whole path name is C:/Program Files/RapidRMA/license/license.lic).

Use the default rma.bat (Figure 03-B shown in the previous section).

05. Floating License: License Manager Server, Any Host, Any User

The floating license enforces an upper limit on the number of concurrent (simultaneous) users. This is used when the application is to be shared among users working from different computers. It can simplify the system administration tasks associated with installing and upgrading the application.

Oftentimes the floating license is used in networked environments when there are many endusers of the product. The RapidRMA application itself may be installed on a fileserver, a computer other than the one where it runs and shared among the many endusers. There are some configuration issues that must be addressed for those installations of RapidRMA. Those issues are described in another technote [TO BE LINKED]. For this discussion and for the examples presented here, we continue to the assumptions described in the Introduction: The RapidRMA application and the Java run-time environment are installed on the local computer (ie, the computer where the enduser runs the RapidRMA application). Adapting the information here to the networked case should be straightforward with the help of the other technote.

In this section we need to consider both sides of the client-server model. First we'll discuss how to setup the license server. Then we'll describe two ways to indicate the location of license server to the RapidRMA application (the license client).

For making concrete examples, we make several assumptions about where software is installed, ie, what folders.

• RapidRMA is installed on the local computer in the folder C:/Program Files/RapidRMA

• JRE is installed on the local computer in the folder C:/Program Files/Javasoft

• FLEXlm is installed on the host called licserv in the directory C:/Program Files/flexlm.

  NOTE: The hostid used with a floating license must be the hostid of the computer where the license manager runs. In this example, it is the host licserv. Do not use the hostid from a different computer where the user happens to run the RapidRMA application.

• We use TCP port 27006 for the license server. This is fairly arbitrary, but the client and server must agree on the number.

• In the configuration I maintain here, I keep my license file and the vendor executables in the FLEXlm installation directory. The locations for these items can be almost anywhere and the locations are specified to the FLEXlm license manager through a control panel window (Figure 05-B).

In adapting the examples to their site, customers will need to make the appropriate changes to pathnames.

05.01. License Server

First we'll examine the license file for a floating license and, for sites already running the FLEXlm license manager, consider the task of adding lines to an existing license file. Next we'll discuss the vendor executable needed for floating licenses. Then we'll look at the installation of the FLEX license manager program and subsequent setup using the control panel.

License File

Let's start by looking at a license file (see Figure 05-A).

SERVER licserv 0050da097619 TCP:27006 
VENDOR tripac "C:\Program Files\flexlm\tripac.exe"
FEATURE RapidRMA tripac 1.0 30-dec-1999 1 50168A183483 ck=61

#NOTE: You can edit the hostname on the server line (1st arg).
#      The (optional) daemon-path on the VENDOR line (2nd arg).
#      And the port number (27006) on the SERVER line.
#      Most other changes will invalidate this license.

In general, the license manager may serve many products from several different vendors. There are many variations and optional fields that can go into a license file. This discussion is quite simplified and considers only enough to serve our purposes and to cooperate with other applications that use the license manager (many products by various vendors may control their usage with the same license server and a single license file). The critical lines in a license file are the SERVER, VENDOR and FEATURE lines.

SERVER

In the SERVER lines, the license file names the host(s) on which the license manager runs (the license manager, not the RapidRMA application). Many times there is only a single host. Some sites with critical applications may use a three-server redundant license manager configuration to provide availability in case a license manager host fails.

The fields in the SERVER line are (1) the keyword “SERVER”, (2) the hostname, (3) the hostid, and (4) the TCP-IP port. The hostname and the hostid are those of the computer where the license manager (not the RapidRMA application) run. The enduser may edit the hostname and the TCP-IP port fields without damaging the file.

If the customer already has a license server and they want to add our VENDOR and FEATURE lines to their existing license file, then they need to provide us with the set of SERVER lines in their existing license file and we need to construct the license file to match those SERVER lines. Specifically, we both must use the same set of hostids.

VENDOR

The VENDOR line specifies the vendor executable (or vendor daemon in older terminology, and, in fact, old licenses used the keyword DAEMON). More information about the vendor executable is given below. Product lines (lines with keywords including FEATURE and INCREMENT) refer to vendor identifiers. As there may be several vendors with products all served by a single license manager, the license file may have several VENDOR lines.

The fields in the VENDOR line are (1) the keyword “VENDOR”, (2) the vendor identifier (ours is “tripac”), and (3) the full path name to the vendor executable. The vendor identifier constitutes the base filename of the executable.

When the license file is delivered from us, the VENDOR line will have only the first two fields. The customer should not edit those two fields. The customer should edit the license file and add a third field in the VENDOR line. That field contains the full pathname to the vendor executable program, tripac.exe.

FEATURE

The FEATURE lines specify information about individual products, including the expiration date and the number of seats in the license. We have three FEATUREs (products) at this time.

RapidRMA

Run RapidRMA as a standalone application.

RRTRMA

Run RapidRMA under Rational Rose Real-Time.

RhapRMA

Run RapidRMA under Ilogix Rhapsody.

The customer should not edit these lines or the license file will be damaged.

A site may already have a license server installed that is serving other applications. The site managers may wish to control RapidRMA from that same license server. Then we need to build the license so the SERVER lines are the same as for the exisiting file (the customer should send those lines to Tri-Pacific Software). When the customer receives our license, they can then cut the VENDOR and FEATURE lines from our license and append them to the existing license. As before, the customer should also copy the vendor executable to the license server host and add the third field (the full pathname to the vendor executable) to the VENDOR line.

In the configuration I maintain here, I keep both the license file and the vendor executable in the FLEXlm (license manager) installation directory.

Vendor Executable

The license manager program works in conjunction with other programs called vendor executables to validate and serve license requests. In older terminology, the vendor executable was called the vendor daemon. Each vendor with products that use FLEXlm has their own vendor executable that gets used with their products. The FLEXlm program lmgrd.exe is the central point of contact that receives alluests and it dispatches the request to the corresponding vendor executable. Our vendor executable is called tripac.exe.

In earlier releases of RapidRMA, the program tripac.exe. is delivered in the RapidRMA installation package and, after installation, it can be found in the license subdirectory of the RapidRMA installation directory. More recently, the program is available separately from our website.

In the configuration I maintain here, I keep both the license file and the vendor executable in the FLEXlm (license manager) installation directory.

License Manager Installation and Control Panel Setup

For customers with floating licenses to use on Windows platforms, we can provide an easy-to-install FLEXlm package to setup the license manager on a computer. Run the self-extracting executable and step through a typical set of dialog windows for installing a Windows application.

The installation copies several programs into the folder the customer specifies including, of course, the licence manager lmgrd.exe. Another program copies is lmtools.exe, which we use to configure some attributes of the license manager program. Opening the lmtools application, go to to the “Service/License File” tab (see Figure 5-B). Specify that you want “Configuration using Services” and the “Configure Services” tab appears (rightmost tab).

FIGURE 05-B. FLEXlm LMTOOLS window showing “Service/License File” tab where we choose to configure using services.

Go to the “Configure Services” tab (see Figure 5-C). Here one specifies settings for operation as a service, and for configuration parameters like the full path name of the license file and for information and diagnositics. I put these all into the FLEXlm installation directory. Settings appropriate for your site may different than these.

C:/Program Files/flexlm/7.2/lmgrd.exe
C:/Program Files/flexlm/7.2/license.lic
C:/Program Files/flexlm/7.2/Debug.Log

Put a checkmark in the checkbox for the license manager to start at power-on. Hopefully we are running the license manager on an NT host, so put a checkmark in the checkbox to use NT Services for the license manager. This is the cleanest, easiest mechanism in Windows to start the server automatically when the computer boots.

FIGURE 05-C. FLEXlm LMTOOLS window showing “Configure Services” tab with file pathnames.

Summary for License Server

1. Install the FLEXlm license manager. Perhaps you install it into C:\Program Files\flexlm.

2. Copy the vendor executable tripac.exe program to an appropriate folder. Perhaps you copy it to C:\Program Files\flexlm. The vendor executable tripac.exe may be downloaded from our website.

3. Add the vendor executable full pathname to the VENDOR line in the license file. This name must match the actual location used in the previous step (possibly C:\Program Files\flexlm\tripac.exe).

4. Copy the license file to an appropriate folder. Perhaps you copy it to C:\Program Files\flexlm. The license file lines are emailed to customers. Request a license from license@tripac.com

5. Configure the FLEXlm license manager with the control panel. The pathname of the lmgrd.exe must match that of the actual location resulting from the FLEXlm installation in the first step (possibly C:\Program Files\flexlm\lmgrd.exe). The pathname of the license file must match that of the actual location used in the previous step (possibly C:\Program Files\flexlm\license.lic).

05.02. License Client

When the RapidRMA application runs on the enduser's computer, RapidRMA must determine where the license manager is located and request a seat. RapidRMA must learn the hostname of the license server and the license server port at that host. Here are two ways to do that.

• Local copy of the license.

  Make a copy of the server license file (Figure 05-A) on the client host. Put the file in the license subdirectory of the RapidRMA installation directory.

  The license file must be a valid license file, but, as far as I can tell, only the server name and TCP port are used by the application.

  Use the default rma.bat file (Figure 03-B shown in a earlier section).

• Environmental Variable

  Specify the hostname and TCP port with an environment variable:

  SET TRIPAC_LICENSE_FILE=27006@licserv

  Add that line to the rma.bat file. I suggest that it be unset at the end when it is no longer needed. So the file now looks like Figure 05-C.

  It is critical that the port number match the port number used in the license file. The port number in both places can be changed to whatever would be appropriate for your site.

  An environment variable can be added to one's configuration by putting that SET line in one's autoexec.bat or by specifying it through the Windows NT System Environment Variables dialog box. However it seems safest and cleanest to set it only when we need it.

@ECHO OFF
SET TRIPAC_LICENSE_FILE=27006@licserv
"C:\Program Files\JavaSoft\JRE\1.3\bin\javaw.exe" -cp .;jbcl.jar;dx.jar;RapidRMA.jar com.tripac.rapidrma.RapidRMA
SET TRIPAC_LICENSE_FILE=

06. References

The FLEXlm vendor (formerly Globetrotter Software, now Macrovision) provides much information about FLEXlm at their website. At the time this webpage is being prepared, the location for FLEXlm support information in their website at the URL:

http://www.macrovision.com/services/support/index.shtml

http://www.macrovision.com/services/support/flexlm/enduser.pdf

http://www.macrovision.com/services/support/flexlm/lmgrd.shtml