Appendix B

License File Format

---

License files usually begin with a SERVER line (or three lines for three-server redundant servers) followed by one or more VENDOR lines, followed by one or more FEATURE or INCREMENT lines. In some cases the license file requires no SERVER line and no VENDOR line.

You can modify these elements in the license file:

Host names on the SERVER line(s)
TCP/IP port numbers on the SERVER line(s)
Paths on the VENDOR line(s)
Options file paths on the VENDOR line(s)
Optional TCP/IP port numbers on the VENDOR line(s) (for firewall support only)
USE_SERVER line
Values in keyword=value pairs on FEATURE lines, if keyword is specified in lowercase

Use the “\” line-continuation character to break up long lines.

8-bit Latin-based characters are fully supported in license files, options files, log files, and FLEXlm-licensed application environments.

See Section 4.4, “Counted vs. Uncounted Licenses,” for more information on SERVER and VENDOR line requirements.

	FLEXlm Version Notes

USE_SERVER introduced in the v5.0 FLEXlm client library.
Line-continuation character is required with the pre-v7.0 FLEXlm client library.
8-bit Latin-based character support introduced in the v8.0 FLEXlm client library.

B.1 License File Syntax

B.1.1 Sample License File

This is an example of a license file for a single vendor with two features.

SERVER my_server 17007ea8 1700
VENDOR sampled
FEATURE f1 sampled 1.000 01-jan-2005 10 SIGN=9BFAC0316462
FEATURE f2 sampled 1.000 01-jan-2005 10 SIGN=1B9A308CC0F7

The license file above allows the license server “my_server” with the hostid “17007ea8” to serve ten floating licenses for each feature, “f1” and “f2,” to any user on the network.

B.1.2 SERVER Lines

The SERVER line specifies the host name and hostid of the license server and the TCP/IP port number of the license manager daemon (lmgrd). Normally a license file has one SERVER line. Three SERVER lines mean that you are using a three-server redundant license server. The absence of a SERVER line means that every FEATURE and INCREMENT line in the license file is uncounted.

The hostids from the SERVER lines are computed into the license key or signature on every FEATURE and INCREMENT line. For this reason, make sure you keep SERVER lines together with any FEATURE/INCREMENT lines as they were sent from the vendor.

The format of the SERVER line is:

SERVER host hostid [port]

where:

Field	Description
host	The system host name or IP address. String returned by the UNIX hostname or uname -n command. On NT/2000/XP, ipconfig /all; on Windows 95/98/ME, winipcfg /all return the host name.
hostid	Usually the string returned by the lmhostid command. This is changed only by your software supplier.
port	TCP/IP port number to use. A valid number is any unused port number between 0 and 64000. On UNIX, choose a port >1024, since those <1024 are privileged port numbers. If no TCP/IP port number is specified, one of the default ports in the range of 27000 and 27009 is used.

Example:

SERVER my_server 17007ea8 21987

See Also

Section B.1.5, “FEATURE/INCREMENT Lines,” for more information about uncounted features.
Chapter 4, “Selecting Server Machines,” for more information about redundant servers.

	FLEXlm Version Notes

IP address specification for host introduced in v5.0 lmgrd, vendor daemon, and FLEXlm client library.
port specification is required with a pre-v6.0 lmgrd, vendor daemon, and FLEXlm client library.

B.1.3 VENDOR Lines

The VENDOR line specifies the daemon name and path. lmgrd uses this line to start the vendor daemon, and the vendor daemon reads it to find its options file. The format of the VENDOR line is shown below.

VENDOR vendor [vendor_daemon_path]\
                [[options=]options_file_path] [[port=]port]

where:

Field	Description
vendor	Name of the vendor daemon used to serve some feature(s) in the file. This name cannot be changed by the administrator.
vendor_daemon_path	Optional path to the executable for this daemon. Generally the license administrator is free to install the daemon in any directory. (It is recommended, however, that it be installed in a local directory on the license server machine.) If omitted, lmgrd looks for the vendor daemon binary in the current directory the path specified in lmgrd’s $PATH environment variable in the directory where lmgrd is located If vendor_daemon_path is blank, then any options or TCP/IP port number specifications require the options= and port= strings.
options_file_ path	Full path to the end-user options file for this daemon. FLEXlm does not require an options file. If omitted, the vendor daemon, by default, looks for a file called vendor.opt (where vendor is the vendor daemon name) located in the same directory as the license file.
port	Vendor daemon TCP/IP port number. The default, if port is not specified, is chosen by the operating system at run-time. Sites with Internet firewalls need to specify the TCP/IP port number the daemon uses. If a TCP/IP port number is specified on the VENDOR line, there may be a delay restarting the vendor daemon until all the clients have closed their connections to the vendor daemon.

See Also

Chapter 5, “The Options File,” for further information regarding options file contents.

	FLEXlm Version Notes

vendor_daemon_path required in pre-v6.0 vendor daemon.
options_file_path required in pre-v6.0 vendor daemon.
VENDOR lines are known as DAEMON lines in the pre-v6.0 lmgrd and vendor daemon.

v6.0+:

VENDOR sampled

pre-v6.0:

DAEMON sampled /etc/sampled \
       /etc/sampled/licenses/sampled.opt

The options= keyword introduced in the v5.0 vendor daemon.

B.1.4 USE_SERVER Line

USE_SERVER takes no arguments and has no impact on the server. When the application sees USE_SERVER, it ignores everything in the license file except preceding SERVER lines and transfers checkout validation to the vendor daemon.

USE_SERVER is recommended since it improves performance when a license server is used. For uncounted features, USE_SERVER is used to force logging of usage by the daemons.

B.1.5 FEATURE/INCREMENT Lines

A FEATURE line describes the license required 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 is 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, or pools, based on the following fields:

feature name
version
DUP_GROUP
FLOAT_OK
HOST_BASED
HOSTID
PLATFORM
USER_BASED
VENDOR_STRING (if configured by the vendor as a pooling component)

If two lines differ by any of these fields, a new group of licenses, called a license pool, is created in the vendor daemon, and this group is counted independently from other license pools with the same feature name. A FEATURE line does not give an additional number of licenses, whereas an INCREMENT line always gives an additional number of licenses.

The basic FEATURE/INCREMENT line format is:

{FEATURE|INCREMENT} feature vendor feat_version exp_date \
            num_lic SIGN=sign [optional_attributes]

The six fields after the FEATURE/INCREMENT line keyword are required and have a fixed order. They are defined by the vendor and cannot be changed. Table B-1 presents these fields in the order they must appear.

Table B-1: FEATURE/INCREMENT Line Required Fields  

Field	Description
feature	Name given to the feature by the vendor.
vendor	Name of the vendor daemon; also found in the VENDOR line. The specified daemon serves this feature.
feat_version	Version of this feature that is supported by this license.
exp_date	Expiration date of license in the format dd-mmm-yyyy, e.g., 07-may-2005. Note: If exp_date is the string “permanent” or the year is 0 (or 00, 000, 0000) then the license never expires.
num_lic	Number of concurrent licenses for this feature. If the num_lic is set to the string “uncounted” or 0, the licenses for this feature are uncounted and no lmgrd is required but a hostid on the FEATURE line is required. See Section 4.4, “Counted vs. Uncounted Licenses.”
SIGN=sign	SIGN= signature to authenticate this FEATURE line.

Table B-2 lists attributes that may appear in a FEATURE or INCREMENT line. They are supplied at the discretion of the vendor to provide particular licensing behavior. If present in the FEATURE or INCREMENT line, they must remain there and cannot be altered by the end user. These attributes have a keyword=value syntax where keyword is in uppercase.

In places where value is a string surrounded with double quotes (“...”), the string can contain any characters except a quote.

Table B-2: Vendor Supplied Attributes  

Attribute	Description
BORROW[=n]	Enables license borrowing for a particular FEATURE/INCREMENT line. n is the number of hours that the license is borrowed. The default borrow period is 168 hours, or one week.
DUP_GROUP=...	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 for a user on the same host and display, additional uses of a feature do not consume additional licenses.
FLOAT_OK [=server_hostid]	Enables mobile licensing via FLEXid with FLOAT_OK for a particular FEATURE/INCREMENT line. This FEATURE/INCREMENT line must also be node-locked to a FLEXid. When FLOAT_OK=server_hostid is specified on a FEATURE line: The server_hostid must refer to the same host that appears on the SERVER line of the license file. The license server runs only on the machine with the hostid that lmhostid returns equal to the server_hostid specified with FLOAT_OK.
HOSTID=  "hostid1  [hostid2 ...   hostidn]"	Id of the host to which the feature line is bound. hostid is determined with the lmhostid utility. This field is required for uncounted licenses; but can be used for counted licenses as well. See Appendix A, “Hostids for FLEXlm-Supported Machines,” for more information.
HOST_BASED[=n]	Host names must be specified in INCLUDE statements in the end-user options file, and the number of hosts is limited to num_lic, or the number specified in =n.
ISSUED= dd-mmm-yyyy	Date issued.
ISSUER="..."	Issuer of the license.
LINGER=n	The vendor-defined lingering interval for this license. Use LINGER in the options file to extend this time. See Section 5.2.11, “LINGER,” for more information.
NOTICE="..."	A field for intellectual property notices.
OVERDRAFT=n	The overdraft policy allows your vendor to specify a number of additional licenses which users are 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 license limit is reported by the SAMreport reporting tool.
PLATFORMS="..."	Usage is limited to the listed platforms.
SN=serial_num	Serial number, used to identify FEATURE or INCREMENT lines.
START= dd-mmm-yyyy	Start date.
SUITE_DUP_GROUP=...	Similar to DUP_GROUP, but affects only the enabling FEATURE line for a package suite. It limits the total number of users of the package to the number of licenses, and allows the package to be shared among the users that have the SUITE checked out.
SUPERSEDE= "f1 f2 ..."	If this appears, all licenses issued before the date specified in ISSUED= are superseded by this line and become ineffective.
TS_OK	FLEXlm detects when a node-locked uncounted license is running under Windows Terminal Server. To run on Terminal Server remote machines, TS_OK must be added to the FEATURE line. Without TS_OK, a user running on a Terminal Server client is denied a license.
USER_BASED[=n]	Users must be specified in INCLUDE statements in the end-user options file, and the number of users are limited to num_lic, or the number specified in =n.
VENDOR_STRING= "..."	Vendor-defined string, enclosed in double quotes.

The following attributes listed in Table B-3 are optional and are under control of the end user. These attributes have a keyword=value syntax where keyword is in lowercase.

Table B-3: End-User Attributes  

Attribute	Description
asset_info= "..."	Additional information provided by the license administrator for asset management.
dist_info= "..."	Additional information provided by the software distributor.
user_info= "..."	Additional information provided by the license administrator.
vendor_info= "..."	Additional information provided by the software vendor.

Examples:

FEATURE sample_app sampled 2.300 31-dec-2005 20 \
        SIGN=123456789012
INCREMENT f1 sampled 1.000 permanent 5 \
        HOSTID=INTERNET=195.186.*.* NOTICE="Licensed to \
        Sample corp" SIGN=901234567890

	FLEXlm Version Notes

Pre-v7.1 FEATURE/INCREMENT line format uses license_key:

{FEATURE|INCREMENT} feature vendor feat_version exp_date
            num_lic license_key [optional_atributes]

The pre-v7.1 format is understood by the current FLEXlm client library and vendor daemon.

The SIGN= keyword introduced in the v7.1 FLEXlm client library and vendor daemon.
For v7.1 through v8.0 FLEXlm client libraries and vendor daemons, the FEATURE/INCREMENT line must have a SIGN= signature and, for backward compatibility with pre-v8.1, can contain a license_key:

{FEATURE|INCREMENT} feature vendor feat_version exp_date \
            num_lic [license_key] SIGN=sign \
            [optional_attributes]

license_key obsoleted in v8.1 FLEXlm client library and vendor daemon
The keyword “permanent” for exp_date introduced in v6 FLEXlm client library.
The keyword “uncounted’ for num_lic introduced in v6 FLEXlm client library.
BORROW keyword introduced in v8.0 FLEXlm client library and vendor daemon.
FLOAT_OK keyword introduced in v8.0 FLEXlm client library and vendor daemon.
TS_OK keyword introduced in v8.0 FLEXlm client library and vendor daemon.

B.1.6 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 is 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 lines enable the PACKAGE line.

Example:

PACKAGE package vendor [pkg_version] COMPONENTS=pkg_list \
        [OPTIONS=SUITE] [SUPERSEDE[="p1 p2 ..."] ISSUED=date]
        SIGN=pkg_sign

Table B-4 lists the PACKAGE line fields. They must appear in the order listed.

Table B-4: PACKAGE Line Fields  

Field	Description
package	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	Optional field specifying the package version. If specified, the enabling FEATURE/INCREMENT line must have the same version.
COMPONENTS=\ pkg_list	List of package components. The format is: feature[:version[:num_lic]] 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. num_lic is only legal if OPTIONS=SUITE is not set—in this case the resulting number of licenses is num_lic 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=SUITE	Optional field. Used to denote a package suite. If set, the corresponding feature of the same name as the package is checked out in addition to the component feature being checked out. If not set, then the corresponding feature of the same name as the package is removed once the package is enabled; it is not checked out when a component feature is checked out.
OPTIONS= SUITE_RESERVED	Optional field. If set, reserves a set of package components. Once one package component is checked out, all the other components are reserved for that same user.
SUPERSEDE [="p1 p2 ..."]	Optional field. Used in conjunction with ISSUED date. Replaces all PACKAGE lines for the same package name with ISSUED dates previous to dd-mmm-yyyy.
ISSUED= dd-mmm-yyyy	Optional field. Used in conjunction with SUPERSEDE. Replaces all PACKAGE lines for the same package name with ISSUED dates previous to dd-mmm-yyyy.
SIGN=\ pkg_sign	License key or SIGN= signature.

Examples:

PACKAGE suite sampled 1.0 SIGN=3B24B2F508CB \
        COMPONENTS="comp1 comp2" OPTIONS=SUITE
FEATURE suite sampled 1.0 1-jan-0 5 SIGN=4193E6ABCCCB

This is a typical OPTIONS=SUITE example. There are two features, “comp1” and “comp2,” which are each version 1.0, each with five non-expiring licenses available. When “comp1” or “comp2” is checked out, “suite” is also checked out.

PACKAGE suite sampled 1.0 SIGN=2CBF44FCB9C1 \
        COMPONENTS="apple:1.5:2 orange:3.0:4"
FEATURE suite sampled 1.0 1-jan-2005 3 SIGN=321E78A17EC1 SN=123

In this example, the component version overrides the feature version, and the number of licenses available for any component is the product of the three licenses for “suite” and the number of licenses for that component. The result is equivalent to:

FEATURE c1 sampled 1.5 1-jan-2005 6 SIGN=0D3AD5F26BEC SN=123
FEATURE c2 sampled 3.0 1-jan-2005 12 SIGN=EB16C5AE61F0 SN=123

	FLEXlm Version Notes

Ability to store PACKAGE lines in separate files introduced in v6 FLEXlm client library.
pkg_version field required in pre-v7.1 FLEXlm client library.

B.1.7 UPGRADE Lines

UPGRADE feature vendor from_feat_version to_feat_version \
exp_date num_lic [options ... ] SIGN=sign

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

For example, the two lines:

INCREMENT f1 sampled 1.000 1-jan-2005 5 SIGN=9BFAC0316462
UPGRADE f1 sampled 1.000 2.000 1-jan-2005 2 SIGN=1B9A308CC0F7

provide three v1.0 licenses of “f1” and two v2.0 licenses of “f1.”

An UPGRADE line operates on the closest preceding FEATURE or INCREMENT line with a version number that is >= from_feat_version, and < to_feat_version.

---

Note: UPGRADE lines do not work for node-locked, uncounted licenses.

---

B.2 Decimal Format

Licenses can be represented in decimal format. Decimal has the advantage that it’s simpler to type in, and often the licenses are much shorter.

A simple demo license in readable format:

FEATURE f1 sampled 1.00 1-jan-2005 0 key1 HOSTID=DEMO

and its decimal equivalent:

sampled-f1-00737-55296-1825

If needed, decimal lines can be mixed with readable format lines in a license file. Use the lminstall command to convert decimal licenses to readable format.

See Also

Section 7.7, “lminstall,” for additional information on the lminstall command.

	FLEXlm Version Notes

The decimal format was introduced in the v6 FLEXlm client library and vendor daemon.

B.3 License File Order

The order of the lines in a license file is not critical. They are sorted when they are processed so that in most cases the optimal result is achieved. However, pre-v7.0 versions of FLEXlm licensed applications and license servers implicitly impose an ordering to license file lines. Note the following suggestions for ordering lines in the license file:

Place FEATURE lines before INCREMENT lines for the same feature.

The rule regarding FEATURE lines is that only the first counted FEATURE line is observed by the license server, and that if there is a FEATURE line and INCREMENT lines, the FEATURE line must appear first.

Where multiple counted FEATURE lines exist for the same feature, make sure the desired FEATURE line appears first.

All but the first is ignored.

Place node-locked, uncounted lines before floating lines for the same FEATURE.

Otherwise, it is possible the floating license is consumed instead of the node-locked license, resulting in denial for other users.

The placement of a USE_SERVER line affects behavior.

A USE_SERVER line is recommended. Normally, the USE_SERVER line is placed immediately after the SERVER line. However, place any uncounted licenses not served by SERVER before the USE_SERVER line. Make sure each user that needs the uncounted license has direct access to a current copy of the file. The advantage to placing USE_SERVER right after the SERVER line is users don’t need up-to-date copies of the license file.