Introduction and Overview

> ## Chapter 1

> ## Introduction and Overview

> This chapter explains the basics of floating (network) licensing and gives a quick overview of the components of FLEXlm. It explains where license administrators have control and where end users have control. Section 1.6, “Getting Started Checklist,” tells both license administrators and end users how to start managing FLEXlm.

> ### 1.1 Introduction to FLEXlm

> FLEXlm is the most popular license manager used in the software industry. FLEXlm is best known for its ability to allow software licenses to be available (or float) anywhere on a network, instead of being tied to specific machines. Floating licensing benefits both users and license administrators. Users make more efficient use of fewer licenses by sharing them on the network. License administrators control who uses the licensed application and the machine(s) where the licenses are available. See Section 2.3, “Types of License Files,” for details about the different licensing models supported by FLEXlm.

> ### 1.2 How to Use This Manual

> This manual is written for two different audiences:

> - Administrators of FLEXlm licenses and license servers
> - End users of FLEXlm-enabled applications

> #### 1.2.1 License Administrator

> If you are a license administrator, read these chapters:

> Chapter: | Explains:
> --- | ---
> Preface | Overview of this manual.
> Chapter 1, ”Introduction and Overview” | FLEXlm basics: license manager and vendor daemons; the license file; configuring FLEXlm; the license request process.
> Chapter 2, ”License File Basics” | License file basics; setting the path at start-up; different types of licensing policies.
> Chapter 3, ”Managing Licenses from Multiple Vendors” | Using license files from multiple software vendors.
> Chapter 4, ”Selecting Server Machines” | Selecting which machines run the license servers; resources required by the servers; multiple servers; quorums; redundant license servers.
> Chapter 5, ”The Options File” | Creating and editing the options file.
> Chapter 6, ”The License Manager Daemon” | Using the license manager daemon, `lmgrd`.
> Chapter 7, ”License Administration Tools” | Managing FLEXlm using Macrovision-supplied utilities.
> Chapter 8, ”Mobile Licensing” | Licensing to allow working on a computer disconnected from the license server.

> In addition, refer to:

> - Appendix B, “License File Format”
> - Appendix C, “Troubleshooting Guide”

> #### 1.2.2 End User

> If you are an end user, read these chapters:

> Chapter: | Explains:
> --- | ---
> Preface | Overview of this manual.
> Chapter 1, ”Introduction and Overview” | FLEXlm basics: license and vendor daemons; the license file; configuring FLEXlm; the license request process.
> Chapter 2, ”License File Basics” | License file basics; setting the path at start-up; different types of licensing policies.
> Chapter 8, ”Mobile Licensing” | Licensing to allow working on a computer disconnected from the license server.

> In addition, refer to:

> - Appendix C, “Troubleshooting Guide”

> ### 1.3 FLEXlm Components

> FLEXlm components are organized based on the license model used by your software vendor. License models are classified according to their requirement for a license server:

> - Licenses are served by a license server. This is commonly referred to as a served license model. License files supplied by your software vendor that include SERVER, VENDOR, and optionally, USER_SERVER lines require a license server. See Section 1.3.1, “Served Licenses,” for details.
> - Licenses are not served by a license server but are available directly to the application. This is commonly referred to as an uncounted, or unserved license model. See Section 1.3.2, “Unserved Licenses,” for details.

> #### 1.3.1 Served Licenses

> For served licenses, there are four required FLEXlm components:

> - The FLEXlm-Licensed Application, with the FLEXlm static client library linked into it.
> - The License Manager Daemon (lmgrd).
> - The Vendor Daemon, which, along with the license manager, `lmgrd`, comprises the license server.
> - The License File.

> In addition to these four components, there are three optional components:

> - Debug Log File — created and written by `lmgrd`.
> - Report Log File — created and written by the vendor daemon for use by SAMreport.
> - End-User Administration Options File — file created and maintained by the end user.

> Figure 1-1 shows the relationship these components have to one another. See Section 1.3.3, “Component Overview” for a description of each component.

> Figure 1-1: FLEXlm Served License Component Model

> Typically, the license server components reside on a machine in the network but can optionally reside on the same machine as the licensed application.

> The three optional files: Debug Log, Administration Options, and Usage Log files are configured by the end user.

> #### 1.3.2 Unserved Licenses

> License models that do not need a license server have two components:

> - The FLEXlm-Licensed Application, with the FLEXlm static client library linked into it.
> - The License File.

> Figure 1-2 shows this model. See Section 1.3.3, “Component Overview” for a description of each component.

> Figure 1-2: FLEXlm Unserved License Component Model

> The licensed application and license certificate reside on the same machine.

> #### 1.3.3 Component Overview

> ##### The License Manager Daemon (lmgrd)

> The license manager daemon (`lmgrd`) handles the initial contact with the FLEXlm-licensed applications, passing the connection on to the appropriate vendor daemon. It also starts and restarts the vendor daemons.

> Chapter 6, “The License Manager Daemon,” contains information for configuring and starting the license manager daemon in your environment.

> ##### The Vendor Daemon

> In FLEXlm, counted (floating) licenses are granted by processes running on the system. There is one process for each vendor who has a FLEXlm-licensed product on the network. This process is called the vendor daemon. The vendor daemon keeps track of how many licenses are checked out, and who has them.

> FLEXlm-licensed applications communicate with the vendor daemon, through TCP/IP network communications. The FLEXlm-licensed application and the daemon processes (the license server) can run on separate machines on your network, across any size wide-area network. Also, the format of the traffic between the FLEXlm-licensed application and the vendor daemon is machine independent, allowing for heterogeneous networks. This means the license server and the computer running an application can be either different hardware platforms or even different operating systems (Windows and UNIX, for example).

> If the vendor daemon terminates for any reason, all users lose their licenses (though this does not mean the applications suddenly stop running). Users normally regain their license automatically when `lmgrd` restarts the vendor daemon, though they may exit if the vendor daemon remains unavailable. This behavior is defined by the vendor in the FLEXlm-licensed application.

> ##### The License File

> Licensing data is stored in a text file called the license file. The license file is created by the software vendor, and edited and installed by the license administrator. It contains information about the server machines and vendor daemons, and at least one line of data (called FEATURE or INCREMENT lines) for each licensed product. Each FEATURE line contains a license key or signature based on the data in that line, the hostids specified in the SERVER line(s), and other vendor-specific data. FLEXlm-licensed applications that are licensed with a node-locked, uncounted license need only read a valid license file to run—they do not need a license server.

> Most applications have an expected location for the license file, documented by that application. Override this location by setting the environment variable `LM_LICENSE_FILE` to point elsewhere, or by following instructions supplied with the licensed application. If your site has software from multiple vendors with incompatible license files (due to different sets of servers), keep the data in separate files and set the `LM_LICENSE_FILE` variable to reference multiple files.

> It is recommended that you keep a link (on UNIX), a shortcut (on Windows), or copy of the license file in the vendor’s expected license location, so that users do not need to set `LM_LICENSE_FILE` to run their applications. For license files containing counted (floating) licenses, it is recommended to place a USE_SERVER line directly after the SERVER line. For details, see Appendix B, “License File Format.” See also Appendix D, “FLEXlm Environment Variables.”

> ##### The FLEXlm-Licensed Application

> The application program using FLEXlm is linked with the program module (called the FLEXlm client library) that provides the communication with the license server. During execution, the FLEXlm-licensed application communicates with the vendor daemon to request a license.

> ##### Debug Log File

> The debug log file contains status and error messages useful for debugging the license server. Some of the debug log output describes events specific to `lmgrd` and some of the debug log output describes events specific to each vendor daemon. See Appendix G, “The Debug Log File,” for more information about this file.

> ##### End-User Administration Options File

> The end-user administration options file allows the end-user license administrator to control various operating parameters of FLEXlm that remain within the license rights granted to them by the vendor. 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 debugging information logged about license usage
> - Enable a report log file

> See Chapter 5, “The Options File.” for details on how to create this file.

> ##### Report Log File

> The report log file contains feature usage information and is generated by the vendor daemon. Report log output is encrypted and is consumed by reporting products such as SAMreport and FLEXbill. See Appendix F, “The Report Log File,” details regarding this file.

> #### 1.3.4 FLEXlm Components Shipped by Your Vendor

> This section provides a list of FLEXlm components that may be supplied to you by your software vendor along with the FLEXlm-licensed application. Table 1-1 provides a general list and may differ from that actually supplied. Your vendor is the definitive source for the list of FLEXlm components that are shipped.

> Table 1-1: FLEXlm Components for End-User Distribution
> Component | Description
> --- | ---
> Windows and UNIX Common Components
> `lmgrd.exe` `lmgrd` (UNIX) | Required for served license models. The license manager and vendor daemons, where vendor is the name of your vendor.
> `vendor``.exe` `vendor` (UNIX)
> `lmutil.exe` `lmutil` (UNIX) | Optional component. FLEXlm utilities program. Used for license server management and administration. Also available from www.macrovision.com.
> Additional Windows Components
> lmtools.exe | Optional component. Graphical user interface for FLEXlm utilities, `lmutil.exe`. Also available from www.macrovision.com.
> `lmgr8b.dll` | Required if the FLEXlm-licensed application is dynamically linked.This library provides the standard FLEXlm client library routines.
> `fldata.ini` and `flrsrc.dll` | Required for applications which support “try before you by”, FLEXlock licensing.
> `flexid.exe` or `flexidsilent.exe` | Required if vendor supports FLEXid dongle hostids. `flexid.exe` is used to install FLEXid drivers for use with FLEXid dongles. Alternatively, the vendor may supply `flexidsilent.exe` to silently install the drivers as part of the software installation.

> ### 1.4 The License Request Process

> When you run a counted FLEXlm-licensed application, the following occurs:

> 1. The license module in the FLEXlm-licensed application finds the license file, which includes the host name of the license server machine and TCP/IP port number of the license manager daemon, `lmgrd`.
> 2. The FLEXlm-licensed application establishes a connection with the license manager daemon (`lmgrd`) and tells it what vendor daemon it needs to talk to.
> 3. `lmgrd` determines which machine and TCP/IP port correspond to the master vendor daemon and sends that information back to the FLEXlm-licensed application.
> 4. The FLEXlm-licensed application establishes a connection with the specified vendor daemon and sends its request for a license.
> 5. The vendor daemon checks in its memory to see if any licenses are available and sends a grant or denial back to the FLEXlm-licensed application.
> 6. The license module in the application grants or denies use of the feature, as appropriate.

> Uncounted features (where the license count is 0) do not require a license server, and the FLEXlm client library routines in the application grant or deny usage based solely upon the contents of the license file.

> ### 1.5 Configuring FLEXlm

> Most of the parameters of FLEXlm are configurable by the license administrator. The license administrator can set the:

> - Location of the license file (though it’s recommended that a copy or link of the license remains at the location where the application expects it)
> - Location of all executables
> - Location of all log files
> - TCP/IP port number used by the license manager process, `lmgrd`

> In addition, the license administrator can reserve licenses for specific users, machines, or groups, and control other license-related options. Changing parameters is discussed in Chapter 5, “The Options File.”

> > Note: Refer to your vendor’s documentation before attempting to change file names, locations, or contents.

> ### 1.6 Getting Started Checklist

> The following sections provide a quick overview of how to set up and use licensing for FLEXlm-licensed products.

> #### 1.6.1 Installing Licensed Software

> As a license administrator you are responsible for setting up licensing on your system or network. This section tells you how to do that. If you are an end user of the application and you are not involved in installing it, then go to Section 1.6.2, “Notes for End Users.”

> Remember that the installation guide for your application software is the final word on installing and configuring FLEXlm. Generally, however, installing FLEXlm licensing requires the following steps:

> 1. Select your license server machines and get their hostids. See Chapter 4, “Selecting Server Machines,” and Appendix A, “Hostids for FLEXlm-Supported Machines.”
> 2. Give the hostids to your software vendor and get a license file (or the data to enter in the license file) in return.
> 3. Consider how to manage license files from multiple vendors. See Chapter 3, “Managing Licenses from Multiple Vendors.”
> 4. Determine if an options file is desired, and if so, set it up.
> 5. Determine where to install the FLEXlm utility programs such as `lmgrd` and `lmutil` (`lmstat`/`lmdown`/etc.) and install them, unless your vendor’s installation script does so for you.
> 6. Start `lmgrd` (the license manager daemon) manually; you may also want to set it up to start automatically at boot time. See Chapter 6, “The License Manager Daemon.”

> These steps are discussed briefly below.

> ##### License Server machine and Hostids

> Before running any FLEXlm-licensed application using floating licenses, you first need to set up your license server machine (or machines). You must select which machine or machines to run your license servers on and provide the hostids of those machines to your software vendor. For pointers on selecting your server machine, see Chapter 4, “Selecting Server Machines.”

> Get the hostid of the server machine by running FLEXlm’s `lmhostid` utility on that machine. If you don’t have `lmhostid`, get the hostid of your machine by using the appropriate command as described in Appendix A, “Hostids for FLEXlm-Supported Machines.”

> Using the hostid of your server machines, your vendor issues a license file to you that enables the application software.

> ##### License Files and lmgrd

> Once you have received a license file from your vendor, you must install it on your system and start up the license manager daemon, `lmgrd`.

> - Your software vendor may have selected a default location for your license file. If not, use any location you wish. For more details, see Chapter 2, “License File Basics.”
> - To start `lmgrd` automatically at boot time, you have to modify your system files (UNIX) or use LMTOOLS (Windows). For details, see Section 2.2, “License File Format Overview.”

> ##### Administration Tools

> Macrovision supplies administration tools to your software vendor. The vendor usually includes these utilities with their product. Download the latest version from www.macrovision.com. See Chapter 7, “License Administration Tools,” for more information about how to use the FLEXlm utilities.

> ##### Options Files

> The options file controls various options such as reservations and timeouts of licenses. Most users run without an options file, but you may decide you want to use some options. For example, many administrators use an option to limit the quantity and content of logged messages. To set up an options file, see Chapter 5, “The Options File.”

> #### 1.6.2 Notes for End Users

> As a user of a FLEXlm-licensed application, you may need to know a few things to use the system effectively. The main things you need to know are:

> - How to tell an application which license file to use
> - How to query the system to find out who is using a license

> ##### How to Specify a License File Location

> The license file determines what features are available to a FLEXlm-licensed application. It also contains information telling the application how to connect to the license server.

> For information about the standard way of specifying the location of a license file for an application, see Chapter 2, “License File Basics.”

> ##### Getting Information About Licenses

> To find out who is using a license run `lmstat`, described in Chapter 7, “License Administration Tools.”

FLEXlm End Users Guide
July 2003