License File Format

> ## 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.12, “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.

FLEXlm End Users Guide
July 2003