Administering Licenses

This chapter describes the following topics related to Rational software licensing services:

• How Licenses Work
• The License Manager
• License Manager Commands
• The License File
• Customizing License Usage Order
• Licensing Diagnostic Messages
• Frequently Asked Questions
• FLEXlm User Guide and FAQ

---

How Licenses Work

Licenses are managed by a license manager (FLEXlm^TM software delivered as part of Rational Suite) that runs on a license server. The license manager monitors license access, simultaneous usage, idle time, and so on.

When you start any Rational Suite point product, you are initially unlicensed. If a license is available, the license manager gives you a Suite license, which allows you to run any of the point products included in the Suite. You retain the license as long as you keep using any of the products. When you exit the last program in the Suite, your license is returned to the license manager and is made available for another user.

If a Suite license is unavailable, you are unable to use any of the products in the Suite until a license is returned by another user.

Note: Rational ClearCase LT licenses are managed differently from other point products. Rational ClearCase LT uses a linger feature that requires a user to claim a license in increments of 30 minutes. After 30 minutes has elapsed, the license is returned and made available to other users.

---

The License Manager

Rational Suite uses the Flexible License Manager (FLEXlm^TM), version 7.0f, from Globetrotter Software, Inc. The license manager includes the following components:

• A vendor daemon named rational that dispenses Rational Suite licenses.

  The rational daemon is used for all of Rational's licensed products. If you have other products from other vendors that also use FLEXlm, they will include their own vendor daemons.

• A license daemon named lmgrd.

  The same license daemon is used by all licensed products from all vendors that use FLEXlm. The lmgrd daemon does not process requests on its own, but forwards requests to the appropriate vendor daemon.

• A license file that you maintain.

  The license file specifies your license servers, vendor daemons, and product licenses.

Note: Rational recommends that you use a single combined license file for all of your Rational products.

After the license file is in place and the license daemons are running, the server system needs to be set up to automatically restart the license server when it reboots. The rs_install and license_setup scripts cannot do this automatically for you because this action requires root permissions. The following sections provide the start script commands for each operating system.

Sun Solaris

$ su

# cp rational_dir/config/start_lmgrd_on_server-name \
  /etc/rc2.d/S98Rational

HP-UX

% su

# cp rational_dir/config/start_lmgrd_on_server-name \
  /sbin/init.d/S98Rational

# ln -s /sbin/init.d/S98Rational/sbin/rc2.d/S98Rational

---

License Manager Commands

To verify that your license manager is operational, you can enter these commands on your license server to see if its daemons are running:

% ps axw | grep -v grep | egrep "lmgrd|rational"

or

% ps -e | grep -v grep | egrep "lmgrd|rational"

The output should include lines similar to the following (your path names may vary):

538 ?? S 0:03.50 /rational/base/cots/flexlm.7.0f/platform/lmgrd
  -c /rational/config/servername.dat
  -l /rational/config/servername.log

539 ?? I 0:00.90 rational -T brazil 6.0 3 -c ...

Table 11 summarizes the system-administration commands that the license manager provides.

Table 11 License Manager Commands

Command	Description
lmdiag	Allows you to diagnose problems when you cannot check out a license.
lmdown	Shuts down license and vendor daemons
lmhostid	Reports license manager host ID of workstation
lmreread	Rereads license file, starts new vendor daemons
lmstat	Reports status on daemons and feature usage
exinstal	Reports on licenses in license file you specify on the command line.

For more information about these commands, you can view the FLEXlm online documentation in the rational_dir/docs/html/FLEXlm_End-User_Manual directory. This documentation is provided in HTML. These commands are documented in the License Administration Tools chapter.

Additional Licensing Commands

In addition to using the commands in Table 11, you can also use the license_check command to run the FLEXlm lmstat command for counted licenses and the exinstal command for any license file (not port@host). The lmstat command queries the license server for a list of licenses that are in the license pool. The exinstal command checks the license file format and license codes to see if everything is consistent.

---

The License File

The default Rational license file is either:

rational_dir/config/server-name.dat

or

rational_dir/config/Temporary.dat

The Temporary.dat file is used for both startup and evaluation licenses while the server-name.dat file is used for permanent and TLA licenses.

When users start Rational Suite, the environment variable LM_LICENSE_FILE is automatically defined for them. FLEXlm uses this variable to locate the license file. The LM_LICENSE_FILE environment variable can contain non-Rational products but Rational recommends that you keep the licenses in separate files.

Format

The license file is a text file that is set up by the rs_install or license_setup programs. Your license file will contain a SERVER line, a VENDOR line and one or more INCREMENT or FEATURE lines.

Detailed information about the license file and licensing can be found in the FLEXlm End User Manual. To access this guide type rsdsu_help.

---

Customizing License Usage Order

It is possible to set up a mixed environment where the same license server manages licenses for both a Suite product and individual point products. In this situation, license usage order can be customized by modifying the settings in the License_Map file on a per-component-product basis. For example, when a user starts an application, such as Rational Rose, you can define whether that user claims a Rational Rose license or a Rational Suite license.

The License Map File

When you install Rational Suite, a default file called License_Map is created and stored in the rational_dir/config subdirectory. Figure 11 shows the contents of the default License_Map file for Rational Suite. The default License_Map file is set to claim a Rational Suite DevelopmentStudio license for all products first. If that fails, it will attempt to check out a Rational Suite DevelopmentStudio RealTime license followed by a standalone license.

Figure 11 Default License Map File

purecov:5.0 DevelopmentStudioUNIX:1.0, DevelopmentStudioUNIXRT:1.0, standalone  purify:5.0  DevelopmentStudioUNIX:1.0, DevelopmentStudioUNIXRT:1.0, standalone  quantify:5.0  DevelopmentStudioUNIX:1.0, DevelopmentStudioUNIXRT:1.0, standalone  Rose98_Unix:6.0  DevelopmentStudioUNIX:1.0, standalone  RoseRealTime:6.0 DevelopmentStudioUNIXRT:1.0, standalone  ClearQuest:1.1  DevelopmentStudioUNIX:1.0, DevelopmentStudioUNIXRT:1.0, standalone  soda:3.0  DevelopmentStudioUNIX:1.0, DevelopmentStudioUNIXRT:1.0, standalone  RationalUnifiedProcess:1.0 DevelopmentStudioUNIX:1.0, DevelopmentStudioUNIXRT:1.0,  standalone  ClearCase_LT:1.0 DevelopmentStudioUNIX:1.0, DevelopmentStudioUNIXRT:1.0, standalone

The License_Map file `maps' a component product feature and version to a list of features and versions to try in the order given. It contains lines of the following format:

component_designator product_designator {, product_designator}

The component_designator is followed by a comma-separated list of product_designators.

A component_designator specifies the FLEXlm feature and version number associated with a given Suite component product and has the following syntax:

feature_name:version_number (for example, purecov:5.0)

A product_designator specifies a FLEXlm feature and version number that the license client subsystem will try to claim on behalf of the component product when that product requests a license for the feature and version specified by the component_designator. A product_designator has the following syntax:

feature_name:version_number (for example, DevelopmentStudioUNIX:1.0)

In addition, the keyword "standalone" in place of a product_designator denotes a stand-alone license; it is equivalent to specifying a product_designator that is identical to the component_designator.

Comments introduced by "#" are allowed anywhere in the map file.

Note: If a component product is not named in the license map file, then it defaults to claiming a stand-alone license.

The following are some examples of license map settings and a description of how they are handled.

Example 1

soda:3.0 DevelopmentStudioUNIX:1.0, DevelopmentStudioUNIXRT:1.0, 
standalone # (Suite first)

This line tells SoDA's license client subsystem to first attempt to check out a Rational Suite DevelopmentStudio license. If that fails, it will attempt to check out a Rational Suite DevelopmentStudio RealTime license. If a Suite license is unavailable, the client subsystem will attempt to check out a stand-alone license (that is, a license with feature name soda and version 3.0 or greater).

Example 2

soda:3.0 standalone # (standalone only)

This line tells SoDA's license client subsystem to check out a standalone license only (that is, a license with feature name soda and version 3.0 or greater).

Example 3

soda:3.0 DevelopmentStudioUNIXRT:1.0 # (Suite only)

This line tells SoDA's license client subsystem to check out a Rational Suite DevelopmentStudio RealTime license only.

Note: You must have a license map file somewhere for Suite licenses to take effect. If a Suite component product cannot find any license map file containing its component name, it assumes that it is a stand-alone installation, that is, it will only try to check out stand-alone licenses (and will fail if none are available). The only way for a product to know that it is supposed to try a Suite license is if it finds that Suite license feature name and version in a component mapping specified in a license map file.

RSU_LICENSE_MAP

When you run the user setup script (rs_setup.csh or rs_setup.ksh), the setup script checks to see if the environment RSU_LICENSE_MAP variable is set. If the variable is not set, the setup script sets the pathname to the default license map file (for example, rational_dir/config/License_Map).

Customizing License Usage for All Users

You can create a global license map file that applies to all users by copying the default license map file and modifying it to suit your purposes.

To create a global License_Map file:

1 Copy the License_Map file (rational_dir/config/License_Map) to another location.

2 Modify the file by doing the following:

• To change the file to use a stand-alone license for the product first and a Suite license second, edit the component as shown in the following example:

  Rose98_Unix:6.0  standalone, DevelopmentStudioUNIX:1.0
  

• To change the file to use a Suite license for the product first and a stand-alone license second, edit the component as shown in the following example:

  Rose98_Unix:6.0  DevelopmentStudioUNIX:1.0, standalone
  

• To change the file to use only a Suite license for the product, edit the component as shown in the following example:

  Rose98_Unix:6.0  DevelopmentStudioUNIX:1.0
  

Note: You may choose to omit product designators that do not apply. For example, if you have not installed Rational Suite DevelopmentStudio RealTime, you can delete the entry "DevelopmentStudioUNIXRT:1.0."

3 Instruct users to set the RSU_LICENSE_MAP variable to the pathname of your customized license map file.

Customizing License Usage for Individual Users

You can customize license usage for an individual user by creating a license map file for that particular user. The contents of the user license map file will override the contents of the default or global license map file.

To create a customized License_Map file for individual users:

1 If the directory does not already exist, create a ~/.Rational directory.

2 Copy the License_Map to the ~/.Rational directory. If you are using a customized global license map file, be sure to copy that version to the user's directory and not the default license map file in the config directory.

3 Only add the component lines for mappings that you want to override:

• To change the file to use a stand-alone license for the product first and a Suite license second, edit the component as shown in the following example:

  Rose98_Unix:6.0  standalone, DevelopmentStudioUNIX:1.0
  

• To change the file to use a Suite license for the product first and a stand-alone license second, edit the component as shown in the following example:

  Rose98_Unix:6.0  DevelopmentStudioUNIX:1.0, standalone
  

• To change the file to use only a Suite license for the product, edit the component as shown in the following example:

  Rose98_Unix:6.0  DevelopmentStudioUNIX:1.0
  

• To change the file to use only a stand-alone license for the product, edit the component as shown in the following example:

  Rose98_Unix:6.0  standalone
  

Note: You may choose to omit product designators that do not apply. For example, if you have not installed Rational Suite DevelopmentStudio RealTime, you can delete the entry "DevelopmentStudioUNIXRT:1.0."

License Server Process

When you run a Rational Suite product, the following occurs:

1 The product checks to see if the environment variable RSU_LICENSE_MAP is set. If it is set, it reads the license map file to which it points.

2 The product checks to see if a License_Map file exists in the user's home directory ( ~/.Rational/License_Map). If this file exists, its contents are read and override those of the License_Map file read from $RSU_LICENSE_MAP as follows:

• If a component_designator appears only in the $RSU_LICENSE_MAP file, then it remains in force.
• If a component_designator appears in both $RSU_LICENSE_MAP and ~/.Rational/License_Map, the mapping specified in $RSU_LICENSE_MAP is replaced by the mapping specified in ~/.Rational/License_Map.

Considerations for Customizing License Usage

Because there is no "one size fits all" solution, it is worthwhile to consider the following scenarios when defining your license map settings, especially settings that affect all users.

Scenario 1: Rational Rose RealTime set to claim a Suite license first

RoseRealTime:6.0  DevelopmentStudioUNIXRT:1.0, standalone

In this scenario, starting Rose RealTime will consume a Suite license making it unavailable to other users. If the user is unlikely to use other Suite products, you may want to make a standalone license the default.

Scenario 2: Rational Rose RealTime set to claim a stand-alone license first

RoseRealTime:6.0  standalone, DevelopmentStudioUNIXRT:1.0

If Rose RealTime always tries to check out a stand-alone Rose RealTime license before attempting to check out a Suite license, another problem is introduced. Now, when the user starts Rose RealTime, a Rose RealTime license is consumed, if one is available. Later, if the user starts another Suite product such as SoDA while their Rose RealTime session is still active, SoDA will check out a Suite license (assuming there are no stand-alone SoDA licenses). At this point, the user is holding two licenses, a Rose RealTime stand-alone license and a Suite license, where the Suite license alone would have sufficed to run both Rose RealTime and SoDA.

It is important to take the time to think about usage profiles. For example, you need to take into account what products users need and how frequently they use them. You need to modify your license map files to best serve these usage profiles.

---

Licensing Diagnostic Messages

Setting the environment variable RSU_LICENSE_DIAG causes the licensing client subsystem to generate diagnostic messages that show you what it is doing when it searches for license map files, reads them in, and performs licensing operations. Since license maps can be found in various places that depend on the user's environment, licensing operations can have unexpected results if you are not careful. In these cases, it is very helpful to set RSU_LICENSE_DIAG and examine the resulting messages.

The default for Rational products is to print licensing diagnostic messages on standard error. Note that Rational SoDA does not do this.

---

Frequently Asked Questions

1 Can I use the FLEXlm licensing software that I already have installed?

Yes. Install our license code in the default location (in rational_dir/base/cots) and use it to serve the Rational licenses.

2 I already have FLEXlm installed and managing non-Rational licenses, and now I want to install Rational Suite. Can I do this?

Yes. You can have more than one lmgrd on a system, but they must use different ports. You can only have one rational daemon on the system.

a What do I do if my existing FLEXlm installation uses port 27000?

27000 is the default port, so you need to specify a different port number for Rational Suite. Do this by editing the license import file (.upd file) and modifying the SERVER line. Change the port number to something other than 27000 (for example, 2001). Note that the port number follows the host ID.

b What do I do if my existing FLEXlm installation uses a port other than 27000?

You do not have to do anything since rs_install will default to port 27000. If you are using the same server for other Rational products, you must specify the port number you are using.

3 I already have Apex installed with FLEXlm serving Apex licenses. What do I need to do to install Rational Suite?

For Rational Suite version 2001A.04.00 and higher, you need to use a different system as the license server. Do not use rs_install or license_setup. After the licenses are received, append the Rational Suite license to the existing license file. Reread the license file on the server by using the lmreread command.

As an alternative, you could use rs_install to set up Suite licenses and then manually merge the Apex licenses into this file. If you point rs_install at an existing license file with Apex licenses, the file will get saved to license_file.priorN, where N starts at 1 and counts up to the next available prior file. The installer can then take the licenses in that file and merge them back in. Releases after and including Rational Suite, version 1.1 perform this merge automatically.

4 Can I use the FLEXlm redundant license server feature?

Yes. For more information, see Setting up Redundant License Servers on UNIX.

---

FLEXlm User Guide and FAQ

HTML versions of the FLEXlm User Guide and FLEXlm Frequently Asked Questions are provided online. If the online documentation is installed, you can access these guides by typing rsdsu_help.

For technical support regarding licensing issues, use the contact information provided in Contacting Rational Licensing Technical Support as your first point of contact.