license.dat(5)license.dat(5)NAMElicense.dat - license configuration file for FLEXlm licensed applications
SYNOPSIS
/usr/local/flexlm/licenses/license.dat
DESCRIPTION
A license file consists of the following sections:
Optional license-server section, with information about node where
the SERVER (or redundant SERVERs) are running, along with a list of
all vendor-specific DAEMON(s) that the SERVER needs to run. This
section is required if any features are counted.
Features section, consisting of any combination of FEATURE,
INCREMENT, UPGRADE, USE_SERVER or PACKAGE lines. This section is
required.
Optional FEATURESET section, consisting of at most one FEATURESET
line per DAEMON line in the file. (Rarely used).
Comments. The convention is to begin comments with a `#' character.
However, in practice all lines not beginning with a FLEXlm reserved
keyword are considered comments.
Vendors and end-users will read the license file to understand how the
licensing will behave: what features are licensed, for how many users,
whether these features are node-locked, if the features are demo or
regular, etc. The options are very broad for what can be specified in a
license file.
End-users often need to edit this file. Nearly all of the file is
encrypted, and if these portions are edited by the end-user, LM_BADCODE
error will result. However, end-users often must edit the license file
for the following reasons:
To change the SERVER nodename
To change the SERVER TCP/IP port address
To change the path to the vendor daemon.
SERVER Line
A SERVER line specifies the node on which a license server process can
run. If a license file has three SERVER lines, then two of the three
servers must be running in order for the licensing system to operate. The
SERVER node name in the license file can be any network alias for the
node (prior to FLEXlm v2.4 it was restricted to the return of the
gethostname() call).
SERVER nodename id optional-port-number
Page 1
license.dat(5)license.dat(5)
nodename the string returned by the Unix "hostname" command.
This can be edited by the end-user. As of FLEXlm v5, it can also be an
IP address in format "nnn.nnn.nnn.nnn".
id the string returned by the lmhostid command. (Case
insensitive). In addition, a hostid of ANY can be specified,
which will allow the license to be run on any node.
optional-port-number
the TCP port number to use. This can be edited by the end-
user.
NOTE: The SERVER line must apply to all lines in the license
file. It is permitted and encouraged to combine license files from
different vendors, but this only works if the SERVER hostids are
identical in all files that are to be combined. See also
DAEMON Line
The DAEMON line specifies the name and location of a vendor daemon, as
well as the location of the end-user options file.
DAEMON daemon-name path [ [port=]port-num ]
[ [options=]options.dat ]
daemon-name
the name of the daemon used to serve some feature(s) in
the file.
path the pathname to the executable code for this daemon.
port-num TCP port number that the daemon will use. This is for
sites with firewalls, and is not needed elsewhere.
options the pathname of the end-user specified options file for
this daemon.
USE_SERVER Line
USE_SERVER is normally placed before all FEATURE or INCREMENT lines.
This indicates to all client applications that they should not read the
license file, but perform their checkout directly from the server.
USE_SERVER can also be placed after some uncounted FEATURE lines; if so,
these FEATUREs will still checkout even if the server is not running.
The drawback to this is that, if the server is running, uncounted
licenses won't be logged in the log files.
FEATURE or INCREMENT Line
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 add licenses to a
prior FEATURE or INCREMENT line in the license file.
Page 2
license.dat(5)license.dat(5)
Note: If the vendor daemon has ls_use_all_feature_lines set, then FEATURE
lines function as INCREMENT lines, and the behavior of a FEATURE line is
unavailable to that application. If ls_use_all_feature_lines is set,
read INCREMENT for FEATURE.
0nly one 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 ls_compare_vendor_on_increment is non-zero) 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. There are two formats for FEATURE, pre-v3.0 and current. The
old format is still understood and correct with new clients and servers,
but the new format is more flexible, and therefore recommended where
possible.
FEATURE|INCREMENT name daemon version exp_date #lic code \
"vendor_string" [hostid] (Pre-v3.0 format)
or
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="..."] \
[OVERDRAFT=nnn] [{DUP_GROUP|SUITE_DUP_GROUP}=NONE|SITE|[UHDV]] \
[SN=serial-number] [{USER_BASED|HOST_BASED}[=n]] [MINIMUM=min] \
[SUPERSEDE] [ISSUED=date] [CAPACITY] [ck=nnn]
(Current format)
name the name given to the feature. Legal feature names in
FLEXlm must start with either a letter, a number, or the
underscore character.
daemon the daemon-name from a DAEMON line. The specified daemon
serves this feature.
Page 3
license.dat(5)license.dat(5)
version the latest (highest-numbered) version of this feature that
is supported. (3 decimal places).
exp_date the expiration date in the format: dd-mmm-yyyy, (for
example, 22-mar-1988). If you do not want the feature to
expire, select an expiration date with the year as 0 (any
day- any month-0). (Case insensitive).
#lic the number of licenses for this feature.
code the encryption code for this feature line. The code is
produced by lc_crypt() in makekey, or lc_crypstr() in
lmcrypt. (Case insensitive). The start date is encoded
into the code; thus identical codes created with different
start dates will be different. The encryption code field
can be made case sensitive by calling
lc_set_attr(LM_A_CRYPT_CASE_SENSITIVE, 1). Remember to
select the "case sensitive" option when building your
daemon, if you use a case sensitive encryption code
comparison.
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
the vendor-defined string, enclosed in double quotes. This
string can contain any characters except a quote (white
space will be ignored in the vendor-defined string). The
application can retrieve this string by calling
lc_auth_data(). [Pre-v3.0 format]
hostid the string returned by lmhostid. Use if this feature is to
be bound to a particular host, whether its use is counted
or not. (Case insensitive). If the number of licenses is
0, then this field is required. If hostid is DEMO, the
hostid is any system. If DEMO, the application can
determine this is a demo license by calling lc_auth_data()
and noting the hostid type. [Pre-v3.0 format]
HOSTID=hostid the node-locked hostid (same as "hostid" in the old
format, above)
VENDOR_STRING="..."
The vendor-defined license data (same as "vendor_string"
in the old format, above)
vendor_info="..."
Additional information provided by the software vendor.
Not encrypted into the feature's "code".
Page 4
license.dat(5)license.dat(5)
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 system administrator. Not encrypted into the
feature's "code".
asset_info="..." Additional information provided by the software end-
user's system 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
The OVERDRAFT policy allows you to specify a number of
additional licenses which your end-user will be allowed to
use, in addition to the licenses they have purchased. This
is useful if you want to allow 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. In addition, you can determine if you are
currently in an overdraft condition by calling
lc_get_attr(job, LM_A_VD_FEATURE_INFO, members of
interest: lic_in_use, lic_avail, and overdraft. If
lic_in_use is > lic_avail - overdraft
then you are in an "overdraft state".
{DUP_GROUP|SUITE_DUP_GROUP}=...
You can also specify the Duplicate Grouping parameter in
the license in FLEXlm v3.2. If DUP_GROUP is specified in
the license, this parameter overrides the dup_group
parameter in the lc_checkout() call. If not specified in
the license, the dup_group parameter from lc_checkout()
will be used, as in prior versions of FLEXlm. The syntax
is:
DUP_GROUP=NONE|SITE|[UHDV]
U = DUP_USER
H = DUP_HOST
D = DUP_DISPLAY
Page 5
license.dat(5)license.dat(5)
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 count. If SUITE_DUP_GROUP is specified, then the
duplicate grouping applies to "parent" of the suite.
Otherwise, the parent inherits the same duplicate grouping
as the components.
[SN=serial-number]
This is a optional, encrypted, string attribute, useful
for differentiating otherwise identical INCREMENT lines.
[{USER_BASED|HOST_BASED}[=n]]
If USER_BASED is specified, then all licenses must be
INCLUDEd to USER names via the end-user options file.
Similarly, if HOST_BASED is specified, then all licenses
must be INCLUDEd via HOST names. USER_BASED cannot appear
on the same line with HOST_BASED. If =n appears, then the
number of USERs or HOSTs is limited to n; otherwise, the
limit is the number of users in the FEATURE. Will create
new vendor-daemon pools. (See note about Vendor Daemon
Pools later in this RELEASE_NOTES.)
[MINIMUM=min] If lc_checkout(...nlic...), nlic is less than min, then
the server will checkout min.
[SUPERSEDE] allows vendors to sum up a set of INCREMENT lines in a
single, new FEATURE (or INCREMENT) line, which supersedes
all INCREMENT lines for the same feature name with
previous start-dates. Note that the start date is the one
field which is not readable in the license file, and is
part of the 20-character license key.
[ISSUED=date] Make start-date more readable, e.g., ISSUED=1-jan-1996.
If the ISSUED date is set, then SUPERSEDE uses it,
otherwise it uses the start-date
[CAPACITY] The most common purpose of CAPACITY is to charge more for
a more powerful system. For example, with CAPACITY, you
could automatically checkout more licenses on a Unix
system than on a PC, thereby effectively charging more for
the more powerful system. CAPACITY is a checkout
multiplier--if lc_checkout requests 1 license, and
CAPACITY is set to 3, 3 licenses will be checked out.
CAPACITY is set by 1) Adding the CAPACITY keyword to the
FEATURE line 2) Setting CAPACITY in the application with
lc_set_attr(job, LM_A_CAPACITY, (LM_A_VAL_TYPE)value);
This value becomes a multiplier to the checkout number IF
Page 6
license.dat(5)license.dat(5)
CAPACITY is set in the license file. If CAPACITY is
missing from the FEATURE line, the attribute setting in
the code will have no effect. Similarly, if CAPACITY is
on the FEATURE line, but there is no call to
lc_set_attr(...LM_A_CAPACITY), this will have no effect.
The attribute must be set before the first connection to
the server (usually lc_checkout), and cannot be reset once
set. CAPACITY will create new vendor-daemon pools.
Examples
To illustrate INCREMENT, the two feature lines:
FEATURE f1 demo 1.000 1-jan-0 4 ....
FEATURE f1 demo 2.000 1-jan-0 5 ...
would only result in 4 licenses for v1 or 5 licenses for v2, depending on
their order in the file, whereas:
INCREMENT f1 demo 1.000 1-jan-0 4 ....
INCREMENT f1 demo 2.000 1-jan-0 5 ....
would result in 4 licenses for v1 and 5 licenses for v2 being available,
giving a total of 9 licenses for f1.
To illustrate counted vs. uncounted licenses, the following FEATURE line
FEATURE f1 demo 1.000 1-jan-95 0 12345678901234567890 HOSTID=DEMO
has unlimited usage on any hostid, requires no lmgrd server or SERVER or
DAEMON lines (and is therefore a complete license file by itself), and
expires on 1- jan-95. In contrast
FEATURE f1 demo 1.000 1-jan-0 5 12345678901234567890 \
HOSTID=INTERNET=195.186.*.*
this FEATURE requires the demo vendor daemon to be running, is limited to
6 users on any host with an internet IP address matching 195.186.*.*, and
never expires.
Note: Assuming that ls_use_all_feature_lines is 0, then only one 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. In other words, if the
feature name, version, and node-lock hostid (and optionally, the vendor
string, if ls_compare_vendor_on_increment is non-zero) match a prior
INCREMENT or FEATURE line, the new number of licenses is added to the old
Page 7
license.dat(5)license.dat(5)
number. If any of the three do not match, a new group of licenses is
created. INCREMENT is not available for pre-v2.61 FLEXlm clients or
servers.
UPGRADE Line
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 (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 FLEXlm 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.
If a user has UPGRADE lines for his license file and performs the
following sequence:
start daemons WITHOUT UPGRADE lines in license file
check out old versions of software
add UPGRADE lines to license file
run lmreread
Then he will have more checked out licenses of the old version of the
software than the FEATURE/UPGRADE or INCREMENT/UPGRADE lines would
normally allow. This license overdraft (of the old versions) will only
exist for the life of the old processes.
PACKAGE Line
The purpose of the PACKAGE line is to support two different vendor 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
Page 8
license.dat(5)license.dat(5)
itself, does not license anything -- it requires a matching
FEATURE/INCREMENT line to license the whole PACKAGE. A PACKAGE line can
be shipped with a product, independent of any user information. Later,
the user can purchase one or more corresponding FEATURE/INCREMENT
licenses that will turn on the PACKAGE.
PACKAGE pgn_name vendor pkg_version pkg_key \
COMPONENTS=pkg_list [ OPTIONS=pkg_options ]
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
(VENDOR_NAME in lm_code.h).
pkg_version
version of the PACKAGE. The corresponding
FEATURE/INCREMENT line must have the same version.
pkg_key 20-character encryption code.
pkg_list the list of components. Format is:
feature[:version[:count]]
The PACKAGE 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 comp1 comp1:2.0:4"
OPTIONS=pkg_options
Currently the only legal option is SUITE. This is what
distinguishes a suite PACKAGE from a PACKAGE used to ease
distribution. With OPTIONS=SUITE, the corresponding
FEATURE is checked out in addition to the
component/feature being checked out. If OPTIONS=SUITE is
not set, then the corresponding FEATURE is removed once
the PACKAGE is turned on, and it also is not checked out
when a component/feature is checked out.
Examples
Page 9
license.dat(5)license.dat(5)
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, simple, OPTIONS=SUITE example. The user will have 2
features available: comp1 and comp2, which are each version 1.0, 5 uses
available, unexpiring.
When comp1 or comp2 are checked out, "suite" will also be checked out.
The vendor will most likely want to turn on DUP_GROUP (either through the
FEATURE line, or lc_checkout) so that the same user can use comp1 and
comp2 while using only one use of FEATURE suite.
PACKAGE suite demo 1.0 20CHARCODEXXXXXXXXXX \
COMPONENTS="comp1 comp2 comp3 comp4 comp5"
INCREMENT suite demo 1.0 1-jan-0 1 20CHARCODEXXXXXXXXXX \
HOSTID=12345678
INCREMENT suite demo 1.0 1-jan-0 1 20CHARCODEXXXXXXXXXX \
HOSTID=12345678
This is a good way to distribute multiple node-locked, counted licenses.
Rather than requiring 5 INCREMENT lines per node, only one INCREMENT line
is required per node, and the features are indicated in the PACKAGE line.
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
The component versions override the FEATURE versions, and the uses
available is the product of the 3 uses for suite and the components
count. 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
FEATURESET Line
FEATURESET daemon-name code
daemon-name
the name of the daemon used to serve some feature(s) in
the file.
Page 10
license.dat(5)license.dat(5)
code the encryption code for this FEATURESET line. This code
encrypts the codes of all FEATUREs that this daemon
supports, so that no FEATURE lines can be removed or added
to this license file.
The FEATURESET line allows the vendor to bind together the entire list of
FEATURE lines supported by one daemon. If a FEATURESET line is used,
then all the FEATURE lines must be present in the same order in the
customer's license file. This is used, for example, to insure that a
customer uses a complete update as supplied, without adding in old
FEATURE lines from the vendor.
Any amount of white space of any type can separate the components of
license file lines, and the data can be entered via any text editor.
Vendors can therefore distribute license data via fax or telephone.
Only four data items in the license file are editable by the end-user:
hostnames on SERVER lines
port-numbers on SERVER lines
pathnames on DAEMON lines
options file pathnames on DAEMON lines
The SERVER hostid(s) and everything on the FEATURE line (except the
daemon name) is input to the encryption algorithm to generate the code
for that FEATURE.
Comments
Comment lines can begin with a `#'.
Continued Lines
Lines can be continued with a "
License file name limits
The limits on names for the major parameters employed in the FLEXlm
license file are:
Host Names 32 characters
Feature Names 30 characters
Date String 11 characters (dd-mmm-yyyy)
License file lines (total)
2048 characters
User Names 20 characters
DAEMON Names 10 characters
Page 11
license.dat(5)license.dat(5)
Version 10 characters, in floating point format,
i.e., nnn.nnn
All other parameters Limited only by the total length of the
license file line.
When using TCP, the maximum number of spawned daemons is 255, which
effectively limits the maximum number of end-users to 256*25 -(2* #
servers -1) or approximately 6,400 per vendor daemon. When using UDP,
there is no limit to the number of end-users. Note that multiple daemons
can be run on a single network, making the number of even TCP end-users
effectively unlimited.
Example License File
SERVER pat 17003456 1700
SERVER lee 17004355 1700
SERVER terry 17007ea8 1700
DAEMON demo /etc/mydaemon
FEATURE f1 demo 1.000 01-jan-96 10 1AEEFC8F90030EABF324
FEATURE f2 demo 1.000 01-jan-96 10 0A7E8C4F561FE98BA073
This example illustrates the license file for single vendor with two
features, and a set of three server nodes, any two of which must be
running for the system to function.
Locating the License File
The license file default is: /usr/local/flexlm/licenses/license.dat.
Note that IRIX systems typically install licenses in
/var/flexlm/license.dat, not in /usr/local/flexlm/licenses/license.dat.
Client applications get the license file location in the following manner
(in order of precedence; lowest to highest):
Default location - /usr/local/flexlm/licenses/license.dat
lc_set_attr(LM_A_LICENSE_FILE_PTR, path)
End-user or application sets LM_LICENSE_FILE environment variable to
path.
LM_A_LICENSE_FILE_PTR set and lc_set_attr(LM_A_DISABLE_ENV,1), which
makes the application override the LM_LICENSE_FILE environment variable.
Most FLEXlm utilities will accept a "-c license_file_path" option, in
order to use a different license file.
The LM_LICENSE_FILE environment variable can be used to establish a new
default location for the license file (note that a "-c" option will
override the setting of LM_LICENSE_FILE). In addition, client programs
can process a series of license files by setting LM_LICENSE_FILE to a
path, as in:
Page 12
license.dat(5)license.dat(5)
% setenv LM_LICENSE_FILE file1:file2:file3:....:filen
or, on VMS:
$ assign file1/file2/file3/.../filen LM_LICENSE_FILE
Client programs will then try using file1; if it fails, file2 will be
tried, etc.
Note that the FLEXlm daemons do NOT use the license file path; they will
only process the first file in a license file path.
Starting in FLEXlm v2.4, the license file no longer needs to be
accessible on each client node; it can be read by the client from lmgrd.
In order to do this, specify the license file as "port@host", either in
the LM_LICENSE_FILE environment variable or in your call to
lc_set_attr(LM_A_LICENSE_FILE_PTR,...);
The new syntax is:
port@host[,port2@host2[,port3@host3]]
port The (integer) TCP/IP port number from the license file
host The name of the server host from the license file.
A non-redundant server would have only a single port@host, whereas
redundant servers could be specified as 1, 2, or 3 sets of "port@host",
separated by commas. For example, if you have a single server node named
"serverhost", and you are running FLEXlm on port 1700, you could specify
your "license file" as:
1700@serverhost
You could have a license file path which looked like the following:
1700@serverhost:/usr/local/license.dat:1700@shost2
or, if the second server was a set of 3 redundant servers, the path might
look like this:
1700@serverhost:1700@host1,1700@host2,1700@host3:1700@shost2
In this last example, the "1700@host1,1700@host2,1700@host3" part
specifies a set of 3 redundant servers.
Prior to FLEXlm v2.61, client and server could read different license
files, however, after v2.61, both the client and server need to be
reading the SAME license file, since the client passes the encryption
Page 13
license.dat(5)license.dat(5)
code from the FEATURE line to the vendor daemon.
Page 14
