Chapter 5

The Options File

---

The options file allows the license administrator to control various operating parameters of FLEXlm. Users are identified by their user name, host name, display, IP address, or PROJECT (which is set with the LM_PROJECT environment variable).

Specifically, the license administrator can:

Allow the use of features
Deny the use of features
Reserve licenses
Restrict the number of licenses available
Control the amount of information logged about license usage
Enable a report log file

Options files allow you, as the license administrator, to be as secure or open with licenses as you like.

Lines in the options file are limited to 2048 characters. The “\” character is a continuation character in options file lines.

	FLEXlm Version Notes

PROJECT identification (set by LM_PROJECT) in options file introduced in v7.0 vendor daemon.

5.1 Creating an Options File

To create an options file:

Use the appropriate options listed in Section 5.2, “Options File Syntax,” to create the options file using any text editor.
Locate the options file anywhere; however, it is recommended that the options file be placed in the same directory as the license file.
Add the path to the options file in the license file as the fourth field on the VENDOR line for the application’s vendor daemon. For example:

VENDOR sampled /etc/sampled \
      [options=]/sample_app/sampled/licenses/sampled.opt

enables the sampled vendor daemon to look at the specified options file.

If the path is omitted, the vendor daemon automatically looks for a file according to the following criteria:

the name the file is vendor.opt, where vendor is the vendor daemon name
it is placed it in the same directory as the license used by lmgrd, it is automatically used at server startup

	FLEXlm Version Notes

The default options file name, vendor.opt, introduced in v6 vendor daemon.

5.2 Options File Syntax

Below is an overview of the options file syntax. See Section 5.5, “Options File Examples,” for examples and additional information.

Each line of the file controls one option. Table 5-1 lists the option keywords.

Table 5-1: Option Keywords  

Option Keyword	Description
BORROW_LOWWATER	Set the number of BORROW licenses that cannot be borrowed.
DEBUGLOG	Writes debug log information for this vendor daemon to the specified file (v8.0+ vendor daemon).
EXCLUDE	Deny a user access to a feature.
EXCLUDE_BORROW	Deny a user the ability to borrow BORROW licenses.
EXCLUDEALL	Deny a user access to all features served by this vendor daemon.
GROUP	Define a group of users for use with any options.
HOST_GROUP	Define a group of hosts for use with any options (v4.0+).
INCLUDE	Allow a user to use a feature.
INCLUDE_BORROW	Allow a user to borrow BORROW licenses.
INCLUDEALL	Allow a user to use all features served by this vendor daemon.
LINGER	Allow a user to extend the linger time for a feature beyond its checkin.
MAX	Limit usage for a particular feature/group—prioritizes usage among users.
MAX_OVERDRAFT	Limit overdraft usage to less than the amount specified in the license.
NOLOG	Turn off logging of certain items in the debug log file.
REPORTLOG	Specify that a report log file suitable for use by the SAMreport license usage reporting tool be written.
RESERVE	Reserve licenses for a user or group of users/hosts.
TIMEOUT	Specify idle timeout for a feature, returning it to the free pool for use by another user.
TIMEOUTALL	Set timeout on all features.

	FLEXlm Version Notes

BORROW_LOWWATER options keyword introduced in v8.0 vendor daemon.
EXCLUDE_BORROW options keyword introduced in v8.0 vendor daemon.
INCLUDE_BORROW options keyword introduced in v8.0 vendor daemon.

Comments

Include comments in your options file by starting each comment line with a pound sign “#.” Everything in an options file is case sensitive. Be sure that user names and feature names, for example, are entered correctly.

Feature Specification

The feature name can be modified with an optional keyword-value pair to fully qualify it. This notation is used for distinguishing a particular group of licenses when there are multiple FEATURE lines for a single feature. The following syntax is used:

feature:keyword=value

For example:

f1:VERSION=2.0

specifies the version 2.0 pool of licenses for feature “f1”.

---

Note: A colon (:) is a valid feature name character. If colons are in your feature names, specify a group of licenses with the following alternative syntax using quotation marks and spaces:
           "feature keyword=value"

---

The following option keywords are used as feature name modifiers to denote a specific group of licenses:

VERSION=
HOSTID=
EXPDATE=
KEY=
SIGN=
ISSUER=
NOTICE=
VENDOR_STRING= (if configured by the vendor as a pooling component)
dist_info=
user_info=
asset_info=

If the USER_BASED or HOST_BASED keywords appear in a feature line, this feature specification syntax must be used to qualify the feature.

Using a package name in place of a feature name applies the option to all of the components in the package.

Type Specification

The following option keywords restrict who may use licenses or where licenses may be used: EXCLUDE, EXCLUDEALL, EXCLUDE_BORROW, INCLUDE, INCLUDEALL, INCLUDE_BORROW, MAX, and RESERVE. These options take a type argument, which specifies whether the restriction is based on USER, HOST, DISPLAY, INTERNET, or PROJECT:

USER—UNIX user name of the user executing the FLEXlm-licensed application.
HOST—machine host name or IP address where the application is executing

The IP-addresses can contain wildcards.

DISPLAY—display where the application is displayed

On UNIX, DISPLAY is /dev/ttyxx (which is always /dev/tty when an application is run in the background) or the X-Display name. On Windows, it is the system name or, in the case of a terminal server environment, the terminal server client name.

INTERNET—IP address of the machine where the application is executing (wildcards can be used in the IP address)
PROJECT—LM_PROJECT environment variable set by the user who is executing the FLEXlm-licensed application

On Windows (without terminal server), the HOST and DISPLAY names are both set to the Window’s system name. For licenses that allow checkouts from a terminal server (TS_OK keyword in the feature line), the USER, HOST, and DISPLAY names can be different from one another.

The types listed above take a single member. For example:

EXCLUDE coolsoft USER joe

To specify a list of users or hosts, first define the list using the GROUP or HOST_GROUP option lines, then use the GROUP or HOST_GROUP type to specify the group name. For example:

GROUP stars joe barbara susan
EXCLUDE coolsoft GROUP stars

	FLEXlm Version Notes

IP address as a HOST specification introduced in v8 vendor daemon.
LM_PROJECT environment variable introduced in V5 FLEXlm client library and vendor daemon.
Colons in feature names introduced in v8 vendor daemon.

5.2.1 BORROW_LOWWATER

BORROW_LOWWATER feature[:keyword=value] n

Sets the number of licenses for a BORROW feature that cannot be borrowed.

feature	Name of feature being affected.
keyword=value	Feature name modifier to denote a group of licenses. See the section, “Feature Specification,” for details.
n	Number of licenses that cannot be borrowed via license borrowing.

For example, if a feature “f1” has a count of 10 and borrowing is enabled in the application and on the FEATURE line:

FEATURE f1 ... 10 ... BORROW SIGN=...

the following line in the options file allows only 7 licenses to be borrowed.

BORROW_LOWWATER f1 3

5.2.2 DEBUGLOG

DEBUGLOG [+]debug_log_path

Specifies a location for the debug log output from the vendor daemon associated with this options file. Preceding the debug_log_path with a + character appends logging entries, otherwise the file is overwritten each time the daemon is started. Note that this affects output from only the vendor daemon associated with this options file. The debug log output of lmgrd and any other vendor daemons in the same license file is not captured in this file.

See Also:

Section 7.13, “lmswitch”
Appendix H, “The Debug Log File”

	FLEXlm Version Notes

Debug log output restricted to that of just the vendor daemon introduced in V8 vendor daemon.

5.2.3 EXCLUDE

EXCLUDE feature[:keyword=value] type {name | group_name}

Excludes a user or pre-defined group of users, etc., from the list of who is allowed to use the feature. EXCLUDE supersedes INCLUDE; conflicts between the EXCLUDE list and the INCLUDE list are resolved by the EXCLUDE taking precedence.

feature	Name of the feature being affected.
keyword=value	Feature name modifier to denote a group of licenses. See the section, “Feature Specification,” for details.
type	One of USER, HOST, DISPLAY, INTERNET, PROJECT, GROUP, or HOST_GROUP. See the section, “Type Specification,” for details.
name	Name of an item of type type to reserve licenses for.
group_name	Name of the group to exclude.

To exclude the user “hank” from the list of users able to use feature “f1”:

EXCLUDE f1 USER hank

5.2.4 EXCLUDE_BORROW

EXCLUDE_BORROW feature[:keyword=value] type \
               {name | group_name}

Excludes a user or pre-defined group of users, etc., from the list of who is allowed to borrow licenses for this BORROW feature. EXCLUDE_BORROW supersedes INCLUDE_BORROW; conflicts between the EXCLUDE_BORROW list and the INCLUDE_BORROW list are resolved by the EXCLUDE_BORROW taking precedence.

feature	Name of the feature being affected.
keyword=value	Feature name modifier to denote a group of licenses. See the section, “Feature Specification,” for details.
type	One of USER, HOST, DISPLAY, INTERNET, PROJECT, GROUP, or HOST_GROUP. See the section, “Type Specification,” for details.
name	Name of an item of type type to reserve licenses for.
group_name	Name of the group to exclude.

To exclude the user “fred” from the list of users able to borrow feature “f1” assuming the feature has the BORROW attribute:

EXCLUDE_BORROW f1 USER fred

5.2.5 EXCLUDEALL

EXCLUDEALL type {name | group_name}

Excludes a user or pre-defined group of users, etc., from the list of who is allowed to use all features served by this vendor daemon.

type	One of USER, HOST, DISPLAY, INTERNET, PROJECT, GROUP, or HOST_GROUP. See the section, “Type Specification,” for details.
name	Name of an item of type type to reserve licenses for.
group_name	Name of the group to exclude.

To exclude any user on the machine “chaos” from using all features served by this vendor daemon:

EXCLUDEALL HOST chaos

5.2.6 GROUP

GROUP group_name user_list

Defines a group of users for use in INCLUDE, INCLUDEALL, EXCLUDE, EXCLUDEALL, and RESERVE option lines.

group_name	Name of the group being defined.
user_list	List of user names in that group.

To define the group “Hackers” consisting of “bob,” “howard,” and “james”:

GROUP Hackers bob howard james

Multiple GROUP lines for the same group name add all the specified users into the group.

---

Note: USER_GROUP is an alias for GROUP.

---

5.2.7 HOST_GROUP

HOST_GROUP group_name host_list

Defines a group of hosts for use in INCLUDE, INCLUDEALL, EXCLUDE, EXCLUDEALL, and RESERVE option lines. Multiple HOST_GROUP lines add all the specified hosts into the group.

group_name	Name of the group being defined.
host_list	List of host names in that group.

To define the host group “Pacific” consisting of “tokyo,” “seattle,” and “auckland”:

HOST_GROUP Pacific tokyo seattle auckland

Anywhere a host name can be used in an options file, an IP-address can be used instead.

5.2.8 INCLUDE

INCLUDE feature[:keyword=value] type {name | group_name}

Includes a user or pre-defined group of users, etc., in the list of who is allowed to use licenses for this feature. Anyone not in an INCLUDE statement is not allowed to use that feature. EXCLUDE supersedes INCLUDE; conflicts between the EXCLUDE list and the INCLUDE list are resolved by the EXCLUDE taking precedence.

feature	Name of the feature being affected.
keyword=value	Feature name modifier to denote a group of licenses. See the section, “Feature Specification,” for details.
type	One of USER, HOST, DISPLAY, INTERNET, PROJECT, GROUP, or HOST_GROUP. See the section, “Type Specification,” for details.
name	Name of an item of type type to reserve licenses for.
group_name	Name of the group to include.

To include user “bob” in the list of users able to use feature “f1”:

INCLUDE f1 USER bob

---

Note: INCLUDE is required for USER_BASED or HOST_BASED features. The system administrator specifies which users are allowed to use the product, via INCLUDE, and the license limits the number of users that are INCLUDEd.

---

5.2.9 INCLUDE_BORROW

INCLUDE_BORROW feature[:keyword=value] type \
               {name | group_name}

Includes a user or pre-defined group of users, etc., in the list of who is allowed to borrow the BORROW feature. Anyone not in an INCLUDE_BORROW statement is not allowed to borrow licenses. EXCLUDE_BORROW supersedes INCLUDE_BORROW; conflicts between the EXCLUDE_BORROW list and the INCLUDE_BORROW list are resolved by the EXCLUDE_BORROW taking precedence.

feature	Name of the feature being affected.
keyword=value	Feature name modifier to denote a group of licenses. See the section, “Feature Specification,” for details.
type	One of USER, HOST, DISPLAY, INTERNET, PROJECT, GROUP, or HOST_GROUP. See the section, “Type Specification,” for details.
name	Name of an item of type type to reserve licenses for.
group_name	Name of the group to include.

To include user “tom” in the list of users able to borrow feature “f1”:

INCLUDE_BORROW f1 USER tom

5.2.10 INCLUDEALL

INCLUDEALL type {name | group_name}

Includes a user or pre-defined group of users, etc. in the list of who is allowed to use all features served by this vendor daemon. Anyone not in an INCLUDEALL statement is not allowed to use these features.

type	One of USER, HOST, DISPLAY, INTERNET, PROJECT, GROUP, or HOST_GROUP. See the section, “Type Specification,” for details.
name	Name of an item of type type to reserve licenses for.
group_name	Name of the group to include.

To allow the user “jane” to use all features served by this vendor daemon:

INCLUDEALL USER jane

5.2.11 LINGER

LINGER feature[:keyword=value] seconds

A lingering license stays checked out for a specified period of time beyond its checkin or licensed application exit, whichever comes first. This option extends the default linger time configured by the vendor in the licensed application.

---

Note: The vendor must have added enabled this feature in the licensed application for it to work. Contact your software vendor to find out if this feature is implemented.

---

feature	Name of the feature.
keyword=value	Feature name modifier to denote a group of licenses. See the section, “Feature Specification,” for details.
seconds	Number of seconds the license lingers. The vendor sets a minimum value. If you specify a value for seconds that is smaller than the vendor’s minimum, the minimum is used.

To set the linger value for feature “f1” to one hour (3600 seconds):

LINGER f1 3600

The actual linger time varies somewhat since the vendor daemon checks all lingering licenses just once per minute. If, however, a new license request is made that would otherwise be denied, a check of the lingering licenses is made immediately to attempt to satisfy the new request.

5.2.12 MAX

MAX num_lic feature[:keyword=value] type {name | group_name}

Limits usage for a group or user.

num_lic	Usage limit for this user or group.
feature	Feature this limit applies to.
keyword=value	Feature name modifier to denote a group of licenses. See the section, “Feature Specification,” for details.
type	One of USER, HOST, DISPLAY, INTERNET, PROJECT, GROUP, or HOST_GROUP. See the section, “Type Specification,” for details.
name	Name of an item of type type to reserve licenses for.
group_name	Name of the group to limit.

5.2.13 MAX_OVERDRAFT

MAX_OVERDRAFT feature[:keyword=value] num_lic

Limits OVERDRAFT license usage below the OVERDRAFT allowed by the license file.

feature	Feature this limit applies to.
keyword=value	Feature name modifier to denote a group of licenses. See the section, “Feature Specification,” for details.
num_lic	Usage limit for this user or group.

5.2.14 NOLOG

NOLOG { IN | OUT | DENIED | QUEUED }

Suppresses logging the selected type of event in the debug log file.

To turn off logging of checkins:

NOLOG IN

To turn off logging of checkouts and queued requests two separate NOLOG lines are required:

NOLOG DENIED
NOLOG QUEUED

---

Note: License administrators use this option to reduce the size of the debug log file. However, it can reduce the usefulness of the debug log in debugging license server problems.

---

See also Section 7.13, “lmswitch.”

5.2.15 REPORTLOG

REPORTLOG [+]report_log_path

REPORTLOG specifies the report log file for this vendor daemon. It is recommended preceding the report_log_path with a + character to append logging entries, otherwise the file is overwritten each time the daemon is started.

On Windows, pathnames which include spaces have to be enclosed in double quotes.

---

Note: SAMreport, a separate product available from Macrovision, is used to process FLEXlm report log files. SAMreport processes only report log files, not debug log files.

---

Reporting on Projects with LM_PROJECT

The SAMreport report writer reports on “projects.” A project is set up by having all users working on the same project set their LM_PROJECT environment variable (or registry on Windows) to a string that describes the project. SAMreport groups usage by project, as defined by what LM_PROJECT was set to when the application was run.

See Also

Appendix D, “FLEXlm Environment Variables”
Appendix G, “The Report Log File”

5.2.16 RESERVE

RESERVE num_lic feature[:keyword=value] type
        {name | group_name}

Reserves licenses for a specific user.

num_lic	Number of license to reserve for this user or group.
feature	Feature this reservation applies to.
keyword=value	Feature name modifier to denote a group of licenses. See the section, “Feature Specification,” for details.
type	One of USER, HOST, DISPLAY, INTERNET, PROJECT, GROUP, or HOST_GROUP. See the section, “Type Specification,” for details.
name	Name of an item of type type to reserve licenses for.
group_name	Name of group to reserve licenses for.

To reserve one license of feature “f1” for user “mel”:

RESERVE 1 f1 USER mel

If you want to reserve a license for each of several users or groups, you must use a separate RESERVE line for each user or group.

---

Note: Any licenses reserved for a user are dedicated to that user. Even when that user is not actively using the license it is unavailable to other users. However, a RESERVEd license does not cause usage to be reported by SAMreport if the license is not actually in use.

---

5.2.17 TIMEOUT

TIMEOUT feature[:keyword=value] seconds

Sets the time after which an inactive license is freed and reclaimed by the vendor daemon.

---

Note: The vendor must have enabled this feature in the licensed application for it to work. Contact your software vendor to find out if this feature is implemented.

---

feature	Name of the feature.
keyword=value	Feature name modifier to denote a group of licenses. See the section, “Feature Specification,” for details.
seconds	Number of seconds after which inactive license is reclaimed. The vendor sets a minimum value.If you specify a value for seconds that is smaller than the vendor’s minimum, the minimum is used.

To set the timeout for feature “f1” to one hour (3600 seconds):

TIMEOUT f1 3600

TIMEOUT checks in the licenses if the FLEXlm-licensed application has been inactive for a period longer than the specified time period. The daemon declares a process inactive when it has not received heartbeats from it; whereas, an active FLEXlm-licensed application sends heartbeats.

A TIMEOUT line must be present in the options file in order to take advantage of the vendor-enabled timeout feature.

5.2.18 TIMEOUTALL

TIMEOUTALL seconds

Same as TIMEOUT, but applies to all features.

5.3 How the Vendor Daemon Uses the Options File

When the vendor daemon is started by lmgrd, the vendor daemon reads its options file. There is only one options file per vendor daemon and each vendor daemon needs its own options file. For any changes in an options file to take effect, the vendor daemon must read its options file. The lmreread utility causes the vendor daemon to reread its options file.

	FLEXlm Version Notes

The lmreread utility enhanced in v8.0 vendor daemon so that it causes the vendor daemon to reread the options file. If you are using earlier versions of FLEXlm, the vendor daemon must be stopped and restarted in order for the options file to be reread.

5.4 Rules of Precedence in Options Files

Rules of precedence take effect when INCLUDE and EXCLUDE statements are combined in the same options file and control access to the same features. The following define the precedence when both types of statements appear together:

If there is only an EXCLUDE list, everyone who is not on the list is allowed to use the feature.
If there is only an INCLUDE list, only those users on the list is allowed to use the feature.
If neither list exists, everyone is allowed to use the feature.
The EXCLUDE list is checked before the INCLUDE list; someone who is on both lists is not allowed to use the feature.

Once you create an INCLUDE or EXCLUDE list, everyone else is implicitly outside the group. This feature allows you, as an administrator, the ability to control licenses without having to explicitly list each user that you wish to allow or deny access to. In other words, there are two approaches; you either:

Give most users access and list only the exceptions, or
Severely limit access and list only the those users that have access privileges

5.5 Options File Examples

The following information gives some examples of options files intended to illustrate ways to effectively control access to your licenses.

5.5.1 Simple Options File Example

RESERVE 1 compile USER robert
RESERVE 3 compile HOST mainline
EXCLUDE compile USER lori
NOLOG QUEUED

This options file:

Reserves one license for the feature “compile” for the user “robert.”
Reserves three licenses for the feature “compile” for anyone on the system with the host name “mainline.”
Prevents the user “lori” from using the “compile” feature on any machine on the network.
Causes QUEUED messages to be omitted from the debug log file.

The sum total of the licenses reserved must be less than or equal to the number of licenses specified in the FEATURE line. In the example above, there must be a minimum of four licenses on the “compile” FEATURE line. If fewer licenses are available, only the first set of reservations (up to the license limit) is used.

If this data were in file /a/b/sampled/licenses/sampled.opt, then modify the license file VENDOR line as follows:

VENDOR sampled /etc/sampled \
                /sample_app/sampled/licenses/sampled.opt

5.5.2 Limiting Access for Multiple Users

Each INCLUDE, INCLUDEALL, INCLUDE_BORROW, EXCLUDE, EXCLUDEALL, EXCLUDE_BORROW, MAX, and RESERVE line must have a single user name (or group) listed. To affect more than one user name create a GROUP. For example to exclude “bob,” “howard,” and “james” from using the feature called “toothbrush,” create the following options file:

EXCLUDE toothbrush USER bob
EXCLUDE toothbrush USER howard
EXCLUDE toothbrush USER james

However, there is an easier way. Create a GROUP and exclude the list of users from using the feature. Like the previous example, the following options file excludes “bob,” “howard,” and “james” from using the feature called “toothbrush”:

# First define the group "Hackers"
GROUP Hackers bob howard james
# Then exclude the group
EXCLUDE toothbrush GROUP Hackers

Now when you want to allow or deny access to any feature to that group, you have an alias list to make it simple.

Use HOST_GROUP to allow, deny, or reserve licenses for multiple hosts. For example, to exclude all users logged in on the hosts “fred” and “barney” from using a feature called “f1,” add these lines to your options file:

HOST_GROUP writers fred barney
EXCLUDE f1 HOST_GROUP writers

See Also

Section 5.2.7, “HOST_GROUP,” for more information about defining groups

5.5.3 EXCLUDE Example

#First Define the group "painters"
GROUP painters picasso mondrian klee
EXCLUDE spell GROUP painters
EXCLUDE spell USER bob
EXCLUDE spell INTERNET 123.123.123.*

This options file:

Prevents the users “picasso,” “mondrian,” and “klee” from using the feature “spell” on any machine on the network.
Prevents the user “bob” from using the feature “spell” on any machine on the network.
Prevents any user logged into a host with an IP address in the range 123.123.123.0 through 123.123.123.255 from using the feature “spell.”
Allows any other user, as long as they are not on the excluded IP addresses, and they are not a member of the “painters” GROUP, and they are not “bob,” to use feature “spell” (by implication).

Note that “bob” could have been added to the group “painters.” However, “painters” might be used for some other purpose in the future so the license administrator chose to handle “bob” as a special case here. In this case, the two EXCLUDE statements concatenate to create a list of four users.

5.5.4 INCLUDE Example

INCLUDE paint USER picasso
INCLUDE paint USER mondrian
INCLUDE paint HOST bigbrush

This options file:

Allows the user “picasso” to use the feature “paint” on any machine on the network.
Allows the user “mondrian” to use the feature “paint” on any machine on the network.
Allows any user, as long as they are on the host “bigbrush,” to use feature “paint.”
Denies access to the feature “paint” to anyone except “picasso,” “mondrian,” or anyone from the host “bigbrush” (by implication).