Chapter 2. The License File
Prev |  | Next

## Chapter 2. The License File

This chapter explains the contents of FLEXlm license files including the following topics:

- “Specifying Location of the License File”

- “License File Format”

- “The Anatomy of a License File”

- “Types of License Files”

The license file contains all site-specific information required by FLEXlm. This information includes:

- server names and host IDs

- vendor names and paths to vendor daemon executables

- feature information

In general the license file, or a copy of it, must be accessible to every machine that runs a FLEXlm-licensed application, and each machine designated as a license server. Before you can use the application you have to start the license manager daemon (`lmgrd`) using the following syntax:

    lmgrd [-c license_file_path] [-t connect_timeout]

where: |  | is the:
-c license_file_path |  | full pathname to the license file. Only use this option if the license file is not installed in the default location /usr/local/flexlm/licenses/license.dat. See “Specifying Location of the License File” for information about using alternate locations.
-t connect_timeout |  | timeout, in seconds, for “connect” calls to other daemons if operating in redundant-server mode.

The section “Specifying Location of the License File”” and Chapter 3, “The License Finder,” discuss how applications find an appropriate license file.

## Specifying Location of the License File

If your software vendor recommends a specific location for your license file, or if the default is not practical for you, use one of the following two methods to put the license file in another location:

- set the path when you start `lmgrd`

- set the path with an environment variable

If you are running the application on multiple nodes, you have three options for making your license file available on all the machines:

- Place the license file in a partition which is available (via NFS®) to all nodes in the network that need the license file.

- Copy the license file to all of the nodes where it is needed.

- Read the license file data from `lmgrd`, by specifying LM_LICENSE_FILE as “port@host”, where host is the server hostname and port is the port number from SERVER line in the license file. Note that port@host is only supported in FLEXlm v2.4 or later versions.

Since the vendor daemon keeps track of license usage, and since the license file contains encrypted data to protect it against modification, you may move and copy the license file as much as necessary.

| Note: You can only start `lmgrd` on the server node specified in the license file.

| Note: If you are running redundant servers, you should have one copy of the license file (as well as the binaries for `lmgrd` and the vendor daemons) on each server node. If you do not do this, you lose all the advantages of having redundant servers, since the node holding these files becomes a single point of failure.

No matter which option you choose, you must first install `lmgrd` (the license manager daemon) and the vendor daemon. The `/etc` directory is a good location, since the daemons will probably be used at boot time.

### Setting the Path to the License File at Start-Up

To start the license manager daemon (`lmgrd`) execute a command similar to the following.

If you are running in the C shell:

    % lmgrd_path -c license_file_path >& log_path &

If you are using either the Korn or Bourne shell:

    $ nohup lmgrd_path -c license_file_path > log_pathname 2>&1 &

To start the `lmgrd` daemon automatically every time you reboot the license server add a line similar to the following to `/etc/rc.boot`, `/etc/rc.local`, or the appropriate startup file:

    nohup lmgrd_path -c license_file_path > log_path 2>&1 &

where: |  | is the:
`lmgrd`_path |  | full pathname to the `lmgrd` executable.
license_file_path |  | full pathname to the license file.
log_path |  | full pathname to the license log file.

| Note: This will not start the daemon until you reboot your license server.

Because FLEXlm supports a large number of platforms, we can not describe all variations of system boot files in this manual. See your operating system's man pages for specific information about modifying startup files.

### Setting the Path with an Environment Variable

Use the environment variable LM_LICENSE_FILE to set the location of the license file. For example in the C shell:

    % setenv LM_LICENSE_FILE license_file_path

In the Korn and Bourne shells:

    # LM_LICENSE_FILE=license_file_path
    # export LM_LICENSE_FILE

where: |  | is the:
license_file_path |  | full pathname to the license file.

| Note: The “-c” option overrides the setting of the LM_LICENSE_FILE environment variable for `lmgrd` and other FLEXlm utilities like lmstat and lmdown. See “Using Separate License Files on the Same Server Node” for more information about LM_LICENSE_FILE.

| Note: Some applications do not recognize the LM_LICENSE_FILE environment variable.

## License File Format

License files usually begin with a SERVER line (or three lines for redundant servers) followed by one or more DAEMON lines, followed by one or more FEATURE lines. In some cases the license file requires no SERVER line and no DAEMON line. See “Counted Vs. Uncounted Licenses” for more information.

You can modify four data items in the license file:

- node names on the SERVER line(s)

- port numbers on SERVER line(s)

- pathnames on the DAEMON line(s)

- options file pathnames on DAEMON line(s)

| Note: Everything else is used to compute the encryption code, and should be entered exactly as supplied by your software vendor. All data in the license file is case sensitive, unless otherwise indicated.

In the following sections, options modifiable by the license administrator are italicized.

### SERVER Lines

The SERVER line specifies the node name and hostid of the license server, and the port number of the license manager daemon (`lmgrd`). Normally a license file has one SERVER line. Three SERVER lines means that you are using redundant servers. The absence of a SERVER line means every FEATURE or INCREMENT line in the license file is uncounted. For more information about uncounted features, see “FEATURE or INCREMENT Lines”. License administrators do not have the option of deleting SERVER lines from a license file because the hostids from the SERVER lines are encrypted into the passwords on every FEATURE and INCREMENT line. For more information about redundant servers, see Chapter 5, “Selecting Server Nodes.” The format of the SERVER line is:

    SERVER nodename id [port-number]

where: |  | is the:
nodename |  | string returned by the UNIX hostname or on some systems, `uname -n` command.
id |  | the string returned by the `lmhostid` command.
port-number |  | TCP port number to use. (Optional, but if not specified, then the FLEXlm TCP service must be present in the network services database.) The port number is usually specified.

Example:

    SERVER enterprise 0122345 1701

### DAEMON Lines

The DAEMON line specifies the daemon name and path. The format of the DAEMON line is shown below.

DAEMON daemon-name daemon_path [options_file_path]

where: |  | is the:
daemon-name |  | name of the vendor daemon used to serve some feature(s) in the file. This name cannot be changed by the administrator.
path |  | pathname to the executable for this daemon. Generally the license administrator is free to install the daemon anywhere. (It is recommended however, that it be installed on the same license server node as the `lmgrd`.)
options_file_path |  | full pathname of the end-user specified options file for this daemon. (See Chapter 6, “The Options File.”) FLEXlm does not require an options file.

Example:

    DAEMON sampled /usr/local/sampled \
    /usr/local/options/options.dat

| Note: “\” characters are only legal syntax in FLEXlm v3.0 and later. Previous versions required that each line in the license file fit on a single line.

### FEATURE or INCREMENT Lines

A FEATURE line describes the license to use a product. An INCREMENT line can be used in place of a FEATURE line, as well as to “incrementally” add licenses to a prior FEATURE or INCREMENT line in the license file.

Only the first FEATURE line for a given feature will be processed by the vendor daemon. If you want to have additional copies of the same feature (for example, to have multiple node-locked counted features), then you must use multiple INCREMENT lines. INCREMENT lines form license groups based on the feature name, version, and node-lock hostid. If the feature name, version, and node-lock hostid (and optionally, the vendor string, if the vendor specified this) match a prior INCREMENT or FEATURE line, the new number of licenses is added to the old number. If any of the three do not match, a new group of licenses is created in the vendor daemon, and this group is counted independently from others with the same feature name. INCREMENT is not available for pre-v2.61 FLEXlm clients or servers. A FEATURE line does not give an additional number of licenses, whereas an INCREMENT line ALWAYS gives an additional number of licenses.

| Note: There is a rarely used option in FLEXlm which causes FEATURE lines to function as INCREMENT lines. This option is called ls_use_all_feature_lines. You will have to ask your vendor if they use this option. If they do, then all FEATURE lines behave exactly as INCREMENT lines.

The format for the FEATURE line changed in FLEXlm v3.0. The old format is understood by new clients and servers, but the new format is more flexible, and you will likely see it more often in the future.

Pre v3.0 format:

    FEATURE|INCREMENT name daemon version exp_date #lic code “vendor_string” [hostid]

New format:

    FEATURE|INCREMENT name daemon version exp_date #lic code \
    [HOSTID=hostid][VENDOR_STRING=”vendor-string”] \
    [vendor_info=”...”] [dist_info=”...”] [user_info=”...”] \
    [asset_info=”...”] [ISSUER=”...”] [NOTICE=”...”] [ck=nnn] \
    [OVERDRAFT=nnn] [DUP_GROUP=NONE|SITE|[UHDV]]

| Note: Nothing in a FEATURE/INCREMENT line is editable, except for values in the “name=value” syntax where name is all lowercase.

where: |  | is the:
name |  | name given to the feature by the vendor.
daemon |  | name of the vendor daemon; also found in the DAEMON line. The specified daemon serves this feature.
version |  | version of this feature that is supported by this license.
exp_date |  | expiration date, for example, 7-may-1993.
| Note: Note: If the year is 0, then the license never expires.
#lic |  | number of concurrent licenses for this feature. If the number of users is set to 0, the licenses for this feature are uncounted and no `lmgrd` is required but a hostid on the FEATURE line is required. See “Counted Vs. Uncounted Licenses” and Appendix C, “Hostids for FLEXlm-Supported Machines.”
code |  | license key for this FEATURE line. Two identical looking FEATURE or INCREMENT lines may have different license keys if the start dates are different.

The following fields are all optional (except for vendor-string in the old format). For optional fields of the “name=value” syntax, if the name is lowercase, it can be modified and the license will remain valid.

“vendor_string” |  | vendor-defined string, enclosed in double quotes. This string can contain any 64 characters except a quote. (White space is ignored for the purpose of the encryption algorithm, but may be significant to your software vendor.)
hostid |  | string returned by lmhostid. Used only if the feature is to be bound to a particular host, whether its use is counted or not. (Numeric hostids are case insensitive). See Appendix C, “Hostids for FLEXlm-Supported Machines” for more information.
vendor_info=”...” |  | Additional information provided by the software vendor. Not encrypted into the feature's “code”.
dist_info=”...” |  | Additional information provided by the software distributor. Not encrypted into the feature's “code”.
user_info=”...” |  | Additional information provided by the software end-user's license administrator. Not encrypted into the feature's “code”.
asset_info=”...” |  | Additional information provided by the software end-user's license administrator for asset management. Not encrypted into the feature's “code”.
ISSUER=”...” |  | Issuer of the license.
NOTICE=”...” |  | A field for intellectual property notices.
ck=nnn |  | A checksum, useful with the lmcksum utility, which will verify that the license has been entered correctly by the end-user. Not encrypted.
OVERDRAFT=nnn |  | FLEXlm v4.0 and later. The OVERDRAFT policy allows your vendor to specify a number of additional licenses which users will be allowed to use, in addition to the licenses they have purchased. This allows your users to not be denied service when in a “temporary overdraft” state. Usage above the licensed limit will be reported by the FLEXadmin reporting tool.
DUP_GROUP=... |  | Duplicate Grouping parameter can be specified in the license in FLEXlm v4.0 and later. The syntax is:
    DUP_GROUP=NONE|SITE|[UHDV]
           U = DUP_USER
           H = DUP_HOST
           D = DUP_DISPLAY
           V = DUP_VENDOR_DEF
|  | Any combination of UHDV is allowed, and the DUP_MASK is the OR of the combination. For example “DUP_GROUP=UHD” means the duplicate grouping is (DUP_USER|DUP_HOST|DUP_DISPLAY), so a user on the same host and display will have additional uses of a feature not consume additional licenses.

Examples:

    FEATURE xyz_app xyzd 2.300 31-dec-1997 20 1234567890 “xyz”
    INCREMENT f1 demo 1.000 1-jan-0 5 12345678901234567890 		\
                  HOSTID=INTERNET=195.186.*.* NOTICE=”Licensed to XYZ corp”

### FEATURESET Lines

The FEATURESET line is used to prevent FEATURE lines from being added to or removed from the license file. The format of the FEATURESET line is shown below.

    FEATURESET daemon-name code

| Note: Nothing in a FEATURESET line is editable. Use the FEATURESET line exactly as it comes from your vendor.

where: |  | is the:
daemon-name |  | name of the vendor daemon used to serve some feature(s) in the file.
code |  | encryption code for this FEATURESET line. This code encrypts the codes of all features this daemon supports, so no FEATURE lines can be removed, added to, or rearranged in this license file.

Example:

    FEATURESET sampled 12345678

where: |  | is the:
sampled |  | name of the vendor daemon
code |  | encryption generated by the vendor

### PACKAGE Lines

The purpose of the PACKAGE line is to support two different licensing needs:

- to license a product SUITE, or

- to provide a more efficient way of distributing a license file that has a large number of features, which largely share the same FEATURE line arguments.

A PACKAGE line, by itself, does not license anything—it requires a matching FEATURE/INCREMENT line to license the whole PACKAGE. A PACKAGE line can be shipped by your software vendor with a product, independent of any licenses. Later, when you purchase a license for that package, one or more corresponding FEATURE/INCREMENT licenses will enable the PACKAGE.

Example:

    PACKAGE pkg_name vendor pkg_version pkg_key \ COMPONENTS=pkg_list OPTIONS=pkg_options ]

where: |  | is the:
pkg_name |  | name of the PACKAGE. The corresponding FEATURE/INCREMENT line must have the same name.
vendor |  | name of the vendor daemon that supports this PACKAGE.
pkg_version |  | version of the PACKAGE. The enabling FEATURE/INCREMENT line must have the same version.
pkg_key |  | 20-character encryption code.
pkg_list |  | list of components. The format is:
    feature[:version[:count]]
|  | PACKAGEs must consist of at least one COMPONENT. Version and count are optional, and if left out, their values come from the corresponding FEATURE/INCREMENT line. Count is only legal if OPTIONS=SUITE is not set—in this case the resulting number of licenses will be the count on the COMPONENTS line multiplied by the number of licenses in the FEATURE/INCREMENT line. Examples:
|  | COMPONENTS=”comp1 comp2 comp3 comp4” COMPONENTS=”comp1:1.5 comp2 comp3:2.0:4”
OPTIONS=pkg_options |  | Currently the only supported option is SUITE. This is what distinguishes a suite PACKAGE from a PACKAGE used to ease distribution.
|  | With OPTIONS=SUITE, the corresponding FEATURE of the same name as the package name is checked out in addition to the component feature being checked out.
|  | If OPTIONS=SUITE is not set, then the corresponding FEATURE of the same name as the package is removed once the PACKAGE is enabled; and it is not checked out when a component feature is checked out.

Examples:

    PACKAGE suite demo 1.0 20CHARCODEXXXXXXXXXX\
                    COMPONENTS=”comp1 comp2” OPTIONS=SUITE
    FEATURE suite demo 1.0 1-jan-0 5 20CHARCODEXXXXXXXXXX

This is a typical SUITE example. You will have 2 features: comp1 and comp2, which are each version 1.0, with 5, non-expiring licenses available. When comp1 or comp2 are checked out, “suite” will also be checked out.

    PACKAGE suite demo 1.0 \
                    COMPONENTS=”comp1:1.5:2 comp2:3.0:4 comp3”
    FEATURE suite demo 1.0 1-jan-95 3 20CHARCODEXXXXXXXXXX\
                    ISSUER=distrib1

In this example, the component versions override the FEATURE versions, and the number of licenses available for any component is the product of the 3 licenses for suite and the number of licenses for that component. The result is equivalent to:

    FEATURE comp1 demo 1.5 1-jan-95 6 20CHARCODEXXXXXXXXXX\
                    ISSUER=distrib1
    FEATURE comp2 demo 3.0 1-jan-95 12 20CHARCODEXXXXXXXXXX\
                    ISSUER=distrib1
    FEATURE comp3 demo 1.0 1-jan-95 3 20CHARCODEXXXXXXXXXX\
                    ISSUER=distrib1

### UPGRADE Lines

    UPGRADE name daemon fromversion version exp_date #lic code “string” [hostid] ck=nnn

All the data is the same as for a FEATURE or INCREMENT line, with the addition of the fromversion field. An UPGRADE line removes up to the number of licenses specified from any old version (>= fromversion) and creates a new version with that same number of licenses.

For example, the two lines:

    FEATURE f1 demo 1.000 1-jan-94 5 9BFAC03164EDB7BC0462 ““
    UPGRADE f1 demo 1.000 2.000 1-jan-94 2 1B9A30316207EC8CC0F7 ““

would result in 3 licenses of v1.0 of f1 and 2 licenses of v2.0 of f1.

UPGRADE will operate on the most recent FEATURE or INCREMENT line (i.e., closest preceding FEATURE or INCREMENT line) with a version number that is >= fromversion, and < version.

Note that UPGRADE does not work for node-locked, uncounted licenses. A new FEATURE line should be issued in this case, since the license count is irrelevant.

## The Anatomy of a License File

The following example is a license file for single vendor with two features.

    SERVER excellent_server 17007ea8 1700
    DAEMON xyzd /etc/xyzd
    FEATURE xyz_app1 xyzd 1.000 01-jan-1993 10 1EF890030EABF324 ""
    FEATURE xyz_app2 xyzd 1.000 01-jan-1993 10 0784561FE98BA073 ""

The license file above would allow the license server excellent_server with the hostid 17007ea8 to serve 10 floating licenses for xyz_app1 and xyz_app2 to any user on the network.

### Parameters of License File Fields

This section lists the limits on end-user editable FLEXlm license file parameters:

This parameter: |  | Has this length limit:
host names |  | 32 characters (pre-FLEXlm v2.4)
|  | 64 characters (FLEXlm v2.4 or later)
license file lines |  | 200 characters
|  | 2048 character, with “\” as a continuation character (v3.0 or later)
user names |  | 20 characters

## Types of License Files

License files are created by the software vendor. License files can specify any of the following policies:

- floating (concurrent) usage

- node-locked

- floating usage on a limited set of hosts

- mixed node-locked and floating usage

### Floating (Concurrent) Licenses

A Floating license means anyone on the network can use the licensed software, up to the limit specified in the license file. (Also referred to as concurrent usage or network licensing.) Floating licenses have no hostids on the individual FEATURE lines. This configuration requires an `lmgrd` daemon because the daemon is going to count the concurrent usage of the licenses.

An example of a license file that provides floating licenses is:

    SERVER lulu 17001234 1700
    DAEMON xyzd /etc/xyzd
    FEATURE f1 xyzd 1.00 1-jan-95 2 code1 ""
    FEATURE f2 xyzd 1.00 1-jan-95 6 code2 ""
    FEATURE f3 xyzd 1.00 1-jan-95 1 code3 ""

This license file specifies that two licenses for feature “f1”, six licenses for feature “f2”, and one license for feature “f3” are available anywhere on the network that can access the license server “lulu”.

### Node Locked Licenses

Node locking means the licensed software can only be used on one node. A node-locked license has a hostid on any FEATURE line that is node-locked to a particular host. There are two types of node-locked licenses; uncounted and counted.

If the number of licenses is set to 0, then the licenses are uncounted and unlimited use is permitted on the specified node. This configuration does not require an `lmgrd` daemon because it is not going to count the concurrent usage of the features.

The following license file allows unlimited usage of feature “f1” on the nodes with host IDs of 12001234 and 1700ab12:

    FEATURE f1 xyzd 1.000 1-jan-95 0 code1 "" 12001234
    FEATURE f1 xyzd 1.000 1-jan-95 0 code2 "" 1700ab12

If these were the only FEATURE lines in this license file, no `lmgrd` daemon would be necessary and you should not start one.

The following license file allows three licenses for feature “f1” to be run, but only on the node with host ID 1300ab43. (In this case, the daemons should be run on the same node that runs the software, since there is no reason to run the daemons on another node.)

    SERVER lulu 1300ab43 1700
    DAEMON xyzd /etc/xyzy
    FEATURE f1 zyzd 1.00 1-jan-95 3 code "" 1300ab43

### Floating Licenses with Limited Availability

Another solution that some vendors choose is a combination of the node-locked solution in “Node Locked Licenses” and the floating option described in “Floating (Concurrent) Licenses”. This provides a fixed number of floating licenses for use only on a set of servers you define when you request your license.

In this configuration, the license file has one node-locked FEATURE line for each node that is to be able to run the software. The same number of licenses is generally specified on each FEATURE line. This configuration does require an `lmgrd` daemon because it is going to count the concurrent usage.

For example, the following license file allows a total of two simultaneous licenses of a feature called, “f1” on any of the three nodes specified, with the daemons running on the license server “lulu”:

    SERVER lulu 17001234 1700
    DAEMON xyzd /etc/xyzd
    FEATURE f1 xyzd 1.00 1-jan-93 2 code1 "" 17001234
    FEATURE f1 xyzd 1.00 1-jan-93 2 code2 "" 17002222
    FEATURE f1 xyzd 1.00 1-jan-93 2 code3 "" 17003333

### Mixed Node-Locked and Floating Licenses

Uncounted node-locked and concurrent usage licenses can be mixed in the same license file.

The following license file allows unlimited use of feature “f1” to be used on nodes 17001111 and 17002222, while allowing two other licenses for feature “f1” to be used anywhere else on the network:

    SERVER lulu 17001234 1700
    DAEMON xyzd /etc/xyzd
    FEATURE f1 xyzd 1.00 1-jan-93 0 code1 "" 17001111
    FEATURE f1 xyzd 1.00 1-jan-93 0 code2 "" 17002222
    FEATURE f1 xyzd 1.00 1-jan-93 2 code3 ""

This configuration does require an `lmgrd` daemon because it is going to count the concurrent usage of the two licenses on the third FEATURE line.

Prev | Table of Contents | Next
Chapter 1. Introduction and Overview |  | Chapter 3. The License Finder