license.dat(5)
license.dat - license configuration file for FLEXlm licensed applications
As shipped in IRIX 6.5.7. Unchanged since IRIX 6.5.
NAME license.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 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. 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. 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". 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 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 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 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 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 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. 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 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 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: % 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 code from the FEATURE line to the vendor daemon.