license.dat
NAME
license.dat - license configuration file for FLEXlm licensed applications
SYNOPSIS
/usr/local/flexlm/licenses/license.dat
DESCRIPTION
A license file consists ofthe following sections:
Optional license-server section, withinformation about node where the SERVER (or redundant SERVERs) arerunning, along with a list of all vendor-specific DAEMON(s)that the SERVERneeds 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 atmost one FEATURESET line per DAEMON line in the file. (Rarely used)
Comments. The convention is to begin commentswith a #’ character. However, in practice all lines not beginning with a FLEXlm reserved keyword are considered comments.
Vendors and end-users willread the license file to understand howthe licensing will behave: what features are licensed,for howmany users, whether these features arenode-locked, ifthe features are demo or regular, etc. Theoptionsare very broad for whatcan be specified in a license file.
End-users often need to edit this file. Nearly all of thefile is encrypted,and if these portions are edited by theend-user, LM_BADCODE error willresult.However, end-users often must edit the license file for the following reasons:
To change the SERVER nodename
To change the SERVER TCP/IP portaddress
To change the path to the vendordaemon.
SERVER Line
A SERVER line specifies the node on which a license serverprocesscan run. If alicensefile has three SERVER lines, then two of the three servers must be running inorder for the licensingsystem to operate. The SERVER node name in the license file can be any network alias for the node (prior to FLEXlm v2.4it was restricted to the returnof the gethostname() call). SERVER nodename idoptional-port-number
nodename the string returnedby the Unix “hostname” command.
This can beedited by the end-user.As of FLEXlm v5, it can also be an IP address in format “nnn.nnn.nnn.nnn”.
id the string returnedby the lmhostidcommand. (Case insensitive). In addition, a hostidof ANY can be specified, which will allow the license to be run on any node.
optional-port-number
theTCP port numberto use.This can be edited by the enduser.
NOTE: The SERVER line mustapply to all lines in the license file. It is permitted andencouraged to combine license files from different vendors,but this only works if the SERVER hostids are identical in all files that are tobe combined. See also
DAEMON Line
The DAEMON line specifies the nameand location ofa vendor daemon, as well as the location of the end-user options file.
DAEMON daemon-namepath [ [port=]port-num ] [ [options=]options.dat ]
daemon-name
thename of the daemon usedto serve some feature(s) in thefile.
path thepathname to theexecutable codefor 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 theend-user specified options filefor this daemon.
USE_SERVER Line
USE_SERVERis normally placed before all FEATURE or INCREMENT lines. This indicates to all client applications that they shouldnot read the license file, but perform their checkout directly from theserver. USE_SERVERcan also be placed after some uncountedFEATURElines; if so, these FEATUREs will still checkouteven ifthe 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.
FEATUREor INCREMENT Line
A FEATURE line describes the license to use a product. An INCREMENT line can be used in place of a FEATURE line, aswell asto add licensesto a prior FEATURE or INCREMENTline inthe license file.
Note: If the vendor daemonhas ls_use_all_feature_lines set, then FEATURE lines function as INCREMENT lines,and thebehavior of a FEATURE line is unavailable to that application. If ls_use_all_feature_lines is set, read INCREMENT forFEATURE.
0nly one FEATURE line for a given feature will be processed by thevendor daemon. If you want to have additional copies of the samefeature(for example, to have multiple node-locked counted features), then you must use multiple INCREMENT lines. INCREMENT lines form license groupsbased onthe feature name, version, and node- lock hostid. If the feature name, version, andnode-lock hostid (and optionally, the vendor string, ifls_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 thethree do not match, a new groupof licenses is created in the vendor daemon, andthis group is counted independently from otherswith the same feature name. INCREMENT is not availablefor pre-v2.61 FLEXlm clients orservers. A FEATURE line does not give an additional number of licenses, whereas an INCREMENT line ALWAYSgives an additional number of licenses.There are two formats for FEATURE, pre-v3.0 andcurrent. The old formatis still understood andcorrectwith new clients and servers, but the new formatis moreflexible, and thereforerecommended 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 thename given to the feature. Legal feature names in FLEXlm muststart with either a letter, a number, or the underscore character.
daemon thedaemon-name from a DAEMON line.The specified daemon serves thisfeature.
version thelatest (highest-numbered) version of this feature that is supported. (3 decimal places).
exp_date theexpiration datein 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 thenumber of licenses for this feature.
code theencryption codefor this feature line. The codeis produced bylc_crypt() in makekey, or lc_crypstr() in lmcrypt. (Case insensitive). The start date is encoded into the code; thusidentical codescreatedwith different start dateswill bedifferent. Theencryption codefield canbe madecase 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 sensitiveencryption code comparison.
The following fields are all optional (except for vendor-string inthe old format). For optionalfields of the “name=value” syntax, if the name islowercase, it can be modified and the license will remain valid.
vendor-string thevendor-defined string, enclosedin double quotes. This string can contain any characters except a quote (white space will be ignored in the vendor-definedstring). The applicationcan retrieve this string by calling lc_auth_data(). [Pre-v3.0 format]
hostid thestring returnedby lmhostid. Use if this feature is to be bound toa 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 ademo license bycallinglc_auth_data() andnoting the hostid type.[Pre-v3.0 format]
HOSTID=hostid
thenode-locked hostid (same as “hostid” inthe old format, above)
VENDOR_STRING=”…”
Thevendor-defined license data (same as “vendor_string” in the old format, above)
vendor_info=”…”
Additional information provided by the software vendor. Notencrypted into the feature’s “code”.
dist_info=”…”
Additional information provided by the software distributor. Not encrypted into thefeature’s “code”.
user_info=”…”
Additional information provided by the software enduser’s system administrator. Not encrypted into the feature’s “code”.
asset_info=”…”
Additional informationprovided by thesoftware enduser’s system administratorfor asset management. Not encrypted into the feature’s “code”.
ISSUER=”…”
Issuer of the license.
NOTICE=”…”
A field forintellectual property notices.
ck=nnn
A checksum,useful with thelmcksumutility, which will verify thatthe license hasbeen entered correctly by the end-user. Not encrypted.
OVERDRAFT=nnn
TheOVERDRAFT policy allowsyou to specify a numberof additional licenseswhich your end-user will be allowed to use, in addition tothe licenses they have purchased. This is useful if you want to allow yourusers to not bedenied service when in a “temporary overdraft” state. Usage above thelicensed limit will be reportedby the FLEXadmin reporting tool. In addition, you can determine if you are currently in an overdraft conditionby 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}=…
Youcan also specify the Duplicate Groupingparameter in thelicensein FLEXlm v3.2.If DUP_GROUP isspecified in thelicense, this parameteroverrides the dup_group parameter in the lc_checkout() call. If notspecified in thelicense, the dup_group parameter from lc_checkout() will be used, as inprior versions of FLEXlm. The syntax is:
DUP_GROUP=NONE|SITE|[UHDV]
U= DUP_USER
H= DUP_HOST
D= DUP_DISPLAY
V = DUP_VENDOR_DEF
Anycombination of UHDV is allowed,and theDUP_MASK is theOR of the combination. For example “DUP_GROUP=UHD” means the duplicategrouping is (DUP_USER|DUP_HOST|DUP_DISPLAY), soa user on the same host and display will have additional uses of a feature notcount.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 fordifferentiatingotherwise identical INCREMENT lines.
[{USER_BASED|HOST_BASED}[=n]]
If USER_BASED is specified,then all licenses must be INCLUDEd toUSER names via the end-user options file. Similarly, if HOST_BASED isspecified, thenall licenses must be INCLUDEd via HOST names. USER_BASED cannotappear on the sameline with HOST_BASED. If =n appears, then the number of USERs or HOSTs islimitedto n; otherwise, the limit is the numberof users in theFEATURE. Will create newvendor-daemon pools. (See note about Vendor Daemon Pools laterin thisRELEASE_NOTES.)
[MINIMUM=min] If lc_checkout(…nlic…),nlic isless than min, then theserver will checkout min.
[SUPERSEDE] allows vendors to sum up a set of INCREMENTlines in a single, newFEATURE(or INCREMENT) line, which supersedes allINCREMENT linesfor thesame feature name with previous start-dates. Notethat the start date is the one field whichis not readablein the license file, and is part of the20-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 ofCAPACITY is to charge more for a more powerful system. For example, with CAPACITY, you could automaticallycheckout more licenses on a Unix system thanon a PC, thereby effectively charging more for themore powerful system. CAPACITYis a checkout multiplier–if lc_checkout requests1 license, and CAPACITY isset to 3, 3 licenses will be checked out. CAPACITY isset by 1) Adding the CAPACITY keyword to the FEATURE line 2) Setting CAPACITY inthe applicationwith lc_set_attr(job, LM_A_CAPACITY, (LM_A_VAL_TYPE)value); This value becomes a multiplier to the checkout number IF CAPACITY isset in the license file. If CAPACITY is missing from the FEATURE line, the attribute setting in thecode will have no effect. Similarly, if CAPACITY is on the FEATURE line, but there is no call to lc_set_attr(…LM_A_CAPACITY), thiswill have no effect. Theattribute must be set before the first connection to theserver (usuallylc_checkout), and cannot be reset once set. CAPACITY willcreate new vendor-daemon pools.
Examples
Toillustrate INCREMENT, the two feature lines:
FEATURE f1 demo 1.0001-jan-04 ….
FEATURE f1 demo 2.0001-jan-05 …
would onlyresult in 4 licenses for v1 or 5 licenses for v2, depending on their order in thefile, whereas:
INCREMENT f1 demo 1.000 1-jan-0 4 ….
INCREMENT f1 demo 2.000 1-jan-0 5 ….
would result in 4 licensesfor v1 and 5 licenses for v2 being available, giving a total of 9 licenses for f1.
Toillustrate counted vs. uncounted licenses, the following FEATURE line
FEATURE f1 demo 1.0001-jan-95 0 12345678901234567890HOSTID=DEMO
has unlimited usage on anyhostid,requires no lmgrd server or SERVER or DAEMON lines (and is therefore a complete license file by itself),and expires on1- jan-95. In contrast
FEATURE f1 demo 1.0001-jan-05 12345678901234567890
HOSTID=INTERNET=195.186..
this FEATURE requires the demo vendor daemon to berunning, is limited to 6 users onany 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 agiven feature will be processedby the vendor daemon. If you want to have additional copies of the samefeature(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, andnode-lock hostid. In other words, if the feature name, version, andnode-lock hostid (and optionally, the vendor string, ifls_compare_vendor_on_increment is non-zero) match a prior INCREMENT or FEATURE line,the newnumber of licenses is added to the old number. If any ofthe three do not match,a new group of licensesis created. INCREMENT is notavailable for pre-v2.61FLEXlm clients or servers.
UPGRADELine
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 licensesspecified 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 licensesof 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 aversionnumber that is >=fromversion, and < version.
Note that UPGRADE does notwork for node-locked, uncountedlicenses. A new FEATURE line should beissued in this case, since the license count isirrelevant.
Ifa user has UPGRADE lines for his license file and performs the
following sequence:
startdaemonsWITHOUTUPGRADElines in license file
checkout oldversions of software
add UPGRADE lines to license file
run lmreread
Then he will have more checked outlicenses of theold version of the software than the FEATURE/UPGRADE or INCREMENT/UPGRADE lines would normally allow. This license overdraft (of the old versions) willonly exist for the lifeof the old processes.
PACKAGELine
The purpose of thePACKAGEline isto support two different vendorneeds: tolicensea product SUITE, or to provide a more efficientway 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 amatching FEATURE/INCREMENT line to license the whole PACKAGE. A PACKAGE line can beshippedwith a product,independent of any userinformation. Later, the user can purchase one or more corresponding FEATURE/INCREMENT licenses that willturn onthe PACKAGE.
PACKAGE pgn_name vendor pkg_version pkg_key COMPONENTS=pkg_list [OPTIONS=pkg_options ]
pkg_name name of thePACKAGE. The corresponding FEATURE/INCREMENT line must have the same name.
vendor name of thevendor daemon that supports this PACKAGE (VENDOR_NAME in lm_code.h).
pkg_version
version of the PACKAGE. Thecorresponding FEATURE/INCREMENT line musthave the same version.
pkg_key 20-character encryption code.
pkg_list thelist ofcomponents. Format is:
feature[:version[:count]]
ThePACKAGEmust consist ofat least one COMPONENT. version andcount are optional, andif leftout, their values comefrom the corresponding FEATURE/INCREMENT line. count is only legalif OPTIONS=SUITE is notset – in this case the resulting number of licenses will be the count on theCOMPONENTS linemultiplied 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. WithOPTIONS=SUITE, the corresponding FEATURE is checked out in addition to the component/feature being checked out. If OPTIONS=SUITE is notset, then the corresponding FEATURE is removed once thePACKAGEis turned on, and it also is not checked out when a component/feature ischeckedout.
Examples
PACKAGE suite demo 1.020CHARCODEXXXXXXXXXX
COMPONENTS=”comp1 comp2” OPTIONS=SUITE
FEATURE suitedemo 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, whichare each version 1.0, 5uses available,unexpiring.
When comp1or comp2 are checked out, “suite” will also be checked out. The vendorwill 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 oneuse of FEATURE suite.
PACKAGE suitedemo 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 wayto distribute multiple node-locked, counted licenses.
Rather than requiring 5 INCREMENT lines per node, only oneINCREMENT line isrequired per node, and the features areindicated in the PACKAGE line.
PACKAGE suitedemo 1.0
COMPONENTS=”comp1:1.5:2 comp2:3.0:4 comp3”
FEATURE suitedemo 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 forsuite and the components count. The resultis equivalent to:
FEATURE comp1demo 1.5 1-jan-95 6 20CHARCODEXXXXXXXXXX
ISSUER=distrib1
FEATURE comp2demo 3.0 1-jan-95 12 20CHARCODEXXXXXXXXXX
ISSUER=distrib1
FEATURE comp3demo 1.0 1-jan-95 3 20CHARCODEXXXXXXXXXX
ISSUER=distrib1
FEATURESET Line
FEATURESETdaemon-name code
daemon-name
thename ofthe daemon usedto serve some feature(s) in thefile.
code theencryption codefor 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 allowsthe vendor to bind together theentire list of FEATURE lines supported byone daemon. Ifa FEATURESET line is used, then all the FEATURE linesmust bepresentin the same order in the customer’slicensefile. This is used, for example, to insure that a customer uses a complete update assupplied, without adding in old FEATURE lines fromthe vendor.
Any amountof white space of any type can separatethe 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 SERVERhostid(s) and everything on theFEATUREline (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 “
Licensefile name limits
The limitson 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)
2048characters
User Names 20 characters
DAEMON Names 10 characters
Version 10 characters, in floating point format, i.e., nnn.nnn
All other parameters Limited onlyby the total length of the license fileline.
When usingTCP, the maximum numberof spawned daemons is 255, which effectively limitsthe maximum number of end-usersto 25625 -(2 # servers -1) or approximately 6,400per vendor daemon. Whenusing UDP, there is no limit to the number ofend-users. Notethat multiple daemons can be runon a single network, making thenumber of even TCP end-users effectively unlimited.
ExampleLicenseFile
SERVER pat17003456 1700
SERVER lee17004355 1700
SERVER terry 17007ea8 1700
DAEMON demo /etc/mydaemon
FEATURE f1demo 1.000 01-jan-96 101AEEFC8F90030EABF324
FEATURE f2demo 1.000 01-jan-96 100A7E8C4F561FE98BA073
This example illustrates the license file for single vendor with two features, and a set of three server nodes,any twoof 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 UNIX 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 followingmanner (in order of precedence; lowest tohighest):
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 theLM_LICENSE_FILEenvironment variable.
Most FLEXlm utilities willaccept 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:
% 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 willbe 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 FLEXlmv2.4, the license file no longer needs to be accessibleon eachclient node; itcan be read by the client from lmgrd. Inorder 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 numberfrom the license file
host The nameof the server host fromthe license file.
A non-redundant server would have only a single port@host,whereas redundant servers could bespecified as 1,2, or 3sets 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, youcould specify your “license file” as:
1700@serverhost
You could have a license file pathwhich looked like the following:
1700@serverhost:/usr/local/license.dat:1700@shost2
or, if thesecond server was a setof 3 redundant servers,the path might look like this:
1700@serverhost:1700@host1,1700@host2,1700@host3:1700@shost2
Inthis last example, the “1700@host1,1700@host2,1700@host3” part specifies a set of3 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 theencryption code from the FEATURE lineto the vendor daemon.