Вы находитесь на странице: 1из 134

Wind River License Administrator Tools Guide

Wind River License Administrator Tools


GUIDE

1.1

edition 3

Copyright 2006 Wind River Systems, Inc. All rights reserved. No part of this publication may be reproduced or transmitted in any form or by any means without the prior written permission of Wind River Systems, Inc. Wind River, the Wind River logo, Tornado, and VxWorks are registered trademarks of Wind River Systems, Inc. Any third-party trademarks referenced are the property of their respective owners. For further information regarding Wind River trademarks, please see: http://www.windriver.com/company/terms/trademark.html This product may include software licensed to Wind River by third parties. Relevant notices (if any) are provided in your product installation at the following location: installDir/product_name/3rd_party_licensor_notice.pdf. Wind River may refer to third-party documentation by listing publications or providing links to third-party Web sites for informational purposes. Wind River accepts no responsibility for the information provided in such third-party documentation.

Corporate Headquarters Wind River Systems, Inc. 500 Wind River Way Alameda, CA 94501-1153 U.S.A. toll free (U.S.): (800) 545-WIND telephone: (510) 748-4100 facsimile: (510) 749-2010 For additional contact information, please visit the Wind River URL: http://www.windriver.com For information on how to contact Customer Support, please visit the following URL: http://www.windriver.com/support

Wind River License Administrator Tools Guide, 1.1 Edition 3 7 Jun 06 Part #: DOC-15561-ZD-02

Contents

Introduction ..........................................................................................
1.1 1.2 Overview .................................................................................................................. License Administration Tasks .............................................................................. License Administrator Workflow Example .......................................... 1.3 System Requirements ............................................................................................ Windows License Server ......................................................................... Solaris License Server .............................................................................. Linux License Server ................................................................................ 1.4 1.5 Using the Product Activation Web Site .............................................................. License Types .......................................................................................................... Node-locked License (NL) ...................................................................... Floating License (FL) ................................................................................ Unique User License (UU) ......................................................................

1
1 2 3 5 5 5 6 7 7 7 8 8

Installing and Configuring a License Server .....................................


2.1 Overview .................................................................................................................. 2.1.1 2.1.2 The License Management Software ....................................................... License Management Utilities ................................................................

9
10 11 12

iii

Wind River License Administrator Tools Guide, 1.1

2.2

Activating Your License ........................................................................................ 2.2.1 2.2.2 Generating Server License Files ............................................................. Installing License Administrator Tools (LM Server and RA) ............ Basic Installation ....................................................................................... Advanced Configuration: Triple Redundant License Server ............. 2.2.3 Setting Up a Host .....................................................................................

12 12 13 13 13 14 15 16 18 18 18 19 20 22 23 26 27 27 30 35 36

2.3

Configuring License Management for Your Enterprise .................................. 2.3.1 2.3.2 2.3.3 Using a Single License Server for a Single Product ............................. Configuring Multiple License Servers .................................................. Configuring a Node-Locked Client .......................................................

2.4

Configuring Advanced License Management .................................................. 2.4.1 2.4.2 2.4.3 2.4.4 2.4.5 The Networked License Management Process .................................... Optimizing License Server Performance .............................................. Using Multiple License Servers for a Single Product .......................... Using a Single License Server for Multiple Wind River Products .... Using LM_PROJECT to Restrict Access ................................................

2.5

Starting and Stopping a License Server ............................................................. 2.5.1 2.5.2 Linux and Solaris ...................................................................................... Windows ....................................................................................................

2.6 2.7

Uninstalling the License Server ........................................................................... Removing a Permanent Node-Locked License File .........................................

Configuring Usage Reporting Tools ................................................... 37


3.1 Introduction ............................................................................................................. 37

iv

Contents

3.2

Working with the Options File ............................................................................ 3.2.1 3.2.2 3.2.3 Specifying a Report Log .......................................................................... Creating an Options File ......................................................................... Modifying and Re-reading an Options File ..........................................

38 39 39 40 41 42 48 49 51 52 54 57 59 60 61

3.3

Options File Examples ........................................................................................... 3.3.1 3.3.2 Examples ................................................................................................... Order of Precedence in the Options File ...............................................

3.4

WRS License Reporting Agent ............................................................................ 3.4.1 3.4.2 Required Files for WRS License Reporting Agent .............................. Running the WRS License Reporting Agent ........................................ Working with Report Log Files .............................................................. Sample Report Generation Use Cases ................................................... 3.4.3 3.4.4 WRS License Reporting Agent Output ................................................. Where to Send Your Reports ..................................................................

3.5

Error Processing ......................................................................................................

Permanently Activating Your Users ...................................................


4.1 4.2 Introduction ............................................................................................................. Permanently Activating a User ............................................................................ 4.2.1 4.2.2 Permanently Activating NL Users ......................................................... Permanently Activating UU or FL Users .............................................. Recommended Method to Permanently Activate UU and FL Users Alternative Method to Permanently Activate UU and FL Users ...... Setting WRSD_LICENSE_FILE Manually ............................................ Setting Environment Variables with wrenv ......................................... Resetting WRSD_LICENSE_FILE ..........................................................

63
63 63 64 64 64 65 65 67 68

Wind River License Administrator Tools Guide, 1.1

4.2.3

Client-Side License Configuration Scenarios ....................................... Configuring Manually a Unique User or Floating Host ..................... Solaris and Linux ...................................................................................... Accessing Multiple License Servers ...................................................... Resetting License Management on the Client ......................................

68 68 69 70 71 72

4.3

Removing a Permanent Node-Locked License File .........................................

Licensing Tips and Troubleshooting .................................................. 73


5.1 5.2 5.3 Introduction ............................................................................................................. Converting Your License Type ............................................................................. Maintaining Licenses ............................................................................................. 5.3.1 5.3.2 Renewing Your License ........................................................................... Transferring a License File ...................................................................... Transferring a License File Between Hosts ........................................... Superseding License Files ....................................................................... Replacing and Deleting a License File ................................................... 5.4 Troubleshooting ...................................................................................................... 5.4.1 Basic Installation ....................................................................................... Obtaining a License File from the Product Activation Web site ........ 5.4.2 License Files .............................................................................................. Using Notepad or WordPad as Your Text Editor ................................. Finding Your Customer License Number and Token ......................... Obtaining New Product Activation Files .............................................. Reinstalling a License File ....................................................................... Re-reading Files ........................................................................................ Moving the License File to a Non-Standard Location ........................ Setting Environment Variables with wrenv for an End User ............ 5.4.3 Obtaining Licenses ................................................................................... Failing to Get a License When Running the Application ................... Not Unique Hostname (Linux) .............................................................. 73 74 74 75 76 76 78 78 79 80 80 80 80 80 81 81 81 82 82 83 83 84

vi

Contents

5.4.4

Borrowing A License (UU and FL) ........................................................ Configuring a Client to Borrow a License ............................................ Restricting Use of the Borrow Feature .................................................. Reconfiguring License Seats (UU and FL) ............................................

85 85 87 87 88 88 89 89 90 90 91 92 92 92 93 93 93

5.4.5

License Servers (UU and FL) .................................................................. If a Client Fails to Retrieve a LIcense .................................................... If Your License Server Will Not Start ..................................................... Serving Multiple Wind River Products from a Single Server ............ Serving Wind River and Other Products from a Single Server ......... Changing the License Server Port Number Manually ........................ Invoking License Management Utilities ............................................... Terminating an Unresolved Checkout ..................................................

5.4.6

Debugging and Errors ............................................................................. Using the setup.log and log.txt Files ..................................................... Error Reporting ......................................................................................... Using a Debug Log (UU and FL) ........................................................... Getting Help with License Management ..............................................

Option File Action Keywords ..............................................................


A.1 A.2 A.3 Introduction ............................................................................................................. Options File Syntax ................................................................................................ Action Keywords .................................................................................................... DEBUGLOG .............................................................................................. EXCLUDE .................................................................................................. EXCLUDEALL .......................................................................................... GROUP ...................................................................................................... HOST_GROUP ......................................................................................... INCLUDE .................................................................................................. INCLUDEALL .......................................................................................... NOLOG ...................................................................................................... REPORTLOG ............................................................................................

95
95 97 99 100 100 101 101 102 102 103 104 104

vii

Wind River License Administrator Tools Guide, 1.1

Sample Reports and Messages .......................................................... 105


B.1 B.2 Introduction ............................................................................................................. 105 Sample Reports ....................................................................................................... 106 B.2.1 B.2.2 B.2.3 B.3 B.4 Quarterly Summary Report .................................................................... 106 Server Usage Report ................................................................................ 108 Dictionary File .......................................................................................... 110

WRS License Reporting Agent Error Messages ............................................... 110 The windrreport Utility Command Syntax ....................................................... 113

Glossary ................................................................................................ 115

Index .............................................................................................................. 121

viii

1
Introduction
1.1 Overview 1 1.2 License Administration Tasks 2 1.3 System Requirements 5 1.4 Using the Product Activation Web Site 7 1.5 License Types 7

1.1 Overview
This guide is a companion to the Wind River License Administrator Tools CD-ROM, and the Product Activation Web Site. It provides information about typical license administration tasks, license types, and product activation.
NOTE: If your purchase includes any unique user licenses, you must set your

license server options to enable report logging. (see 3.2 Working with the Options File, p.38). If you do not enable this feature, your license server will not allocate any unique user licenses.

Wind River License Administrator Tools Guide, 1.1

1.2 License Administration Tasks


License Administration consists of the following tasks:
Configuring A License Server

This task is required if your purchase includes any floating or unique user licenses. There are a variety of ways you can configure a license server (or multiple servers) for your enterprise. Fore more information about installing and configuring a license server, see 2. Installing and Configuring a License Server.
Permanently Activating Your Users Installations

This task is required for all purchases. Each product installation must be permanently activated. Developers within your organization can (by choosing temporary activation) can install and begin working with purchased products immediately, even before you configure a license server. There is no restriction on the number of machines on which you can install the products you have purchased. Once you have configured a license server, you must provide permanent product activation files (up to the total number of licenses purchased) for each of your developers that has chosen temporary activation. Additionally you can create product activation files for your developers to use during installation so that their installation is permanently activated from the outset. For more information about permanently activating your users product installations, see 4. Permanently Activating Your Users.
Reporting Usage Data to Wind River (Unique User Licenses Only)

This task is required if your purchase includes any unique user licenses. You can derive valuable usage information from the quarterly summary prepared for Wind River because you can use the data in the report to keep usage high without exceeding your license allocation. For information about configuring the usage reporting agent and usage reporting, see 3. Configuring Usage Reporting Tools. For a sample quarterly report, see B. Sample Reports and Messages.

1 Introduction 1.2 License Administration Tasks

License Administrator Workflow Example

Figure 1-1 describes the workflow for license administration, showing what steps you (the license administrator) must complete in order to set up a license server and permanently activate your users: In Figure 1-1, the activities numbered 1 are activities that you will complete using the Wind River Product Activation Web Site. The activities numbered 2 are activities you will complete using this guide and the License Administrator Tools CD-ROM. These include installing and configuring a license server, and configuring usage reporting. The activities numbered 3 require interaction with people in your organization to complete permanent activation for unique user and floating license installations, and to generate node-locked licenses.

Wind River License Administrator Tools Guide, 1.1

Figure 1-1

License Administration Workflow

1 Introduction 1.3 System Requirements

1.3 System Requirements


This section discusses hardware and software requirements for the machine(s) on which you will install the License Administrator Tools. They do not take into consideration any other software you are running on this computer.

Windows License Server

Windows 2000 Professional (Service Pack 4), or Windows XP Professional (Service Pack 1 or Service Pack 2). Administrator rights. Intel Pentium 4-class processor minimum, 1GHz minimum. 512MB RAM minimum; 1 GB highly recommended. 270 MB of disk space for a complete installation. If you have unique user licenses, make sure any license server machines you use have available disk space (5 - 10GB) to hold the intermediate report logs as they are rotated and transferred.

A local CD-ROM drive or access to network for installation. An active Internet connection is recommended during initial installation to access patches, documentation, and other important information from the Wind River Online Support Web site.

Solaris License Server

Solaris 8 or 9. A Blade 150 workstation with a 500 MHz processor, or a server or workstation with higher performance. 512MB RAM minimum. 270 MB of disk space for a complete installation. If you have unique user licenses, make sure any license server machines you use have available disk space (5 - 10GB) to hold the intermediate report logs as they are rotated and transferred.

A local CD-ROM drive or access to network for installation.

Wind River License Administrator Tools Guide, 1.1

Netscape Navigator 7.0 or newer. 32-bit application support. CDE Window Manager recommended. An active Internet connection is recommended during initial installation to access patches, documentation, and other important information from the Wind River Online Support Web site.

Linux License Server

One of the following operating systems: Red Hat Enterprise Linux Workstation 3.0 Red Hat Enterprise Linux Workstation 3.0 (Update 2) Red Hat Enterprise Linux Workstation 3.0 (Update 3) Red Hat Enterprise Linux Workstation 4.0 SuSE Linux 9.2

NOTE: The reporting agent is not supported on Linux License servers. If you have

any unique user licenses, you must install the reporting agent on and run it from a supported Windows or Solaris machine.

Intel Pentium 4-class processor, 1 GHz minimum 512 MB RAM minimum with 1 GB recommended A CD-ROM drive or networked CD-ROM for installation. GNOME Window Manager. 270 MB of disk space for a complete installation. If you have unique user licenses, make sure any license server machines you use have available disk space (5 - 10GB) to hold the intermediate report logs as they are rotated and transferred.

TCP/IP must be installed on the host system. A network interface card. Mozilla 1.7 or newer, or Netscape Navigator 7.0 or newer. An active Internet connection is recommended during initial installation to access patches, documentation, and other important information from the Wind River Online Support Web site.

1 Introduction 1.4 Using the Product Activation Web Site

1.4 Using the Product Activation Web Site


Many of the administrative tasks described in this guide require that you log in to the Product Activation Web Site. If you already have a Wind River online support account, you can log in using your existing account and identify yourself as a license administrator by using the token provided on the License Administrator Essentials sheet (in your product shipment). You will use the Product Activation Web Site to complete tasks such as:

define license servers activate installations generate node-locked license files

Access The Product Activation Web Site at: http://www.windriver.com/licensing

1.5 License Types


Wind River products are activated by three license types:

Node-locked License (NL) Floating License (FL) Unique User License (UU)

Node-locked License (NL)

For a node-locked license, you install the product software and the permanent license file on an individual computer, in this guide referred to as the node-locked host. Any user working on the host can use the product. A node-locked license does not permit remote execution of licensed tools. Use a node-locked license for users who need to work while disconnected from a network, for example, developers using laptop computers or computers in a non-networked environment. There is no usage reporting requirement for node-locked liceses.

Wind River License Administrator Tools Guide, 1.1

Floating License (FL)

Use a floating license for users working over a network. You purchase a specific number of seats, thus setting a maximum number of concurrent users able to draw product licenses from a license server machine for use on client machines. There is no usage reporting requirement for floating liceses. Refer to your license agreement for any geographic limitations.

Unique User License (UU)

Use a unique user license for end-users working on clients linked to the same subnetwork as the license server machine. You can create a development environment with as many licensed seats as you need, but usage is tracked for the maximum number of unique users. A unique user license gathers usage data for each license server and requires quarterly reports to Wind River. Each user of the product software is continually tracked. The license agreement requires compliance with the number of users stipulated in the agreement. Exceeding this limit requires additional charges for the quarter.
Quarterly Usage Reporting is Required. NOTE: If your purchase includes any unique user licenses, you must set your

license server options to enable report logging. (see 3.2 Working with the Options File, p.38). If you do not enable this feature, your license server will not allocate any unique user licenses.

2
Installing and Configuring a License Server
2.1 Overview 10 2.2 Activating Your License 12 2.3 Configuring License Management for Your Enterprise 15 2.4 Configuring Advanced License Management 18 2.5 Starting and Stopping a License Server 27 2.6 Uninstalling the License Server 35 2.7 Removing a Permanent Node-Locked License File 36

Wind River License Administrator Tools Guide, 1.1

2.1 Overview
Figure 2-1 shows a typical configuration for a single license server for a unique user (UU) license.
Figure 2-1 A Single License Server (Unique User)

license requests/ authorizations

Clients WRSLicense.lic

License Server Machine

install.txt

lmgrd other vendors vendor daemons other vendors license files wrsd

License Server

WRSLicense.lic

WRSLicense.lic License File Reporting Agent (UU) Transfer File


Internet

wrsd.opt options file Report Log Wind River

During the installation process, end users request and obtain a Product Activation file from Wind River. The Product Activation file is the source for the license file and the installation keys that unlock access to your distribution CD-ROMs. The license file (WRSLicense.lic) stores permanent licensing data. The license file for a license server is called WRSLicense.lic. For a host, the license file is also called WRSLicense.lic.
NOTE: A Product Activation file can be used as is for a license file. The installation

keys reside as commented lines in the file. We recommend, however, that the file be copied to the Wind River default location for license files at installDir/license, and named WRSLicense.lic. When you purchase add-on products from Wind River under the same license, you will receive a single, new license file that replaces the old one and covers all

10

2 Installing and Configuring a License Server 2.1 Overview

associated Wind River products. If an add-on is third-party software, the license will be separate.
2

2.1.1 The License Management Software


The license management software used with your product is FLEXlm from Macrovision. This package offers a full complement of tools for managing licenses and some degree of configurability (see 3.2 Working with the Options File, p.38). Complete FLEXlm product documentation is available on the Web at: http://www.macrovision.com/services/support The general instructions for configuring a license server in 4. Permanently Activating Your Users, assume the following:

The server configuration is for a single Wind River product. Your server configuration does not involve multiple servers, load balancing, or other advanced FLEXlm features.

Special license management cases are discussed in:

2.3.2 Configuring Multiple License Servers, p.18 2.6 Uninstalling the License Server, p.35 and Example 3-2 in 3.3 Options File Examples, p.41 2.3 Configuring License Management for Your Enterprise, p.15 3.3 Options File Examples, p.41

CAUTION: If your company currently uses other software applications that rely on

FLEXlm, you may encounter issues that require special attention, for example the need to merge license files. For more information, refer to 2.4.4 Using a Single License Server for Multiple Wind River Products, p.23. For more information on FLEXlm license server configuration, contact Wind River Customer Support or review the online FLEXlm documentation.

11

Wind River License Administrator Tools Guide, 1.1

2.1.2 License Management Utilities


Wind River licensing includes the following license management utilities:

lmgrdThe license manager daemon routes requests from the license-enabled application to the correct vendor daemon running on the same license server. The same license manager daemon can be used by any application from any vendor because this daemon neither authenticates nor dispenses licenses. wrsdThis vendor daemon, specific for Wind River products, tracks Wind River licenses and their use. WRS license reporting agentThis Wind River licensing software agent processes report logs created to collect usage data from license servers handling Wind River products on a network. lmutilLicense management utilities that enable querying of a license server for information. lmtools.exeA graphical user interface (GUI) for license management utilities that is available only for Windows hosts.

NOTE: Node-Locked LicensesIf you only have node-locked licenses, you do not

need license management utilities. After installing the node-locked license file, WRSLicense.lic, on your host, when you start the application, you will have access to a license and the product. For details, see 4.2.1 Permanently Activating NL Users, p.64

2.2 Activating Your License


This section explains how to obtain and activate your Wind River license.

2.2.1 Generating Server License Files


Obtaining a License File from Wind Rivers Product Activation Web site (PAWS)

To obtain a license from Wind Rivers Product Activation Web site, complete the following steps:

12

2 Installing and Configuring a License Server 2.2 Activating Your License

1.

Go to the Product Activation Web site: http://www.windriver.com


2

2. 3. 4.

Login or create a login if you do not have one. Click the tab Licensing. Follow the directions to configure and request your license file. You will need your customer license number, a token, host names, and host IDs. This information is on your License Administrators Essential Sheet that shipped with your product.

NOTE: In this document, the Wind River Product Activation file is the same as the license file. All references to license file also mean Product Activation file.

2.2.2 Installing License Administrator Tools (LM Server and RA)


The License Administrator Tools (LM Server and Report Agent) from Wind River are installed from the product CD. Follow the instructions on the installation brochure to install the License Administrator Tools.

Basic Installation

The basic installation from the License Administrator Tools CD includes two products:

License Management utilities, required for all licensees WRS Report Agent, required for all Unique User licensees (Solaris and Windows only)

To use LMTOOLS, see Using the LMTOOLS Application, p.30.

Advanced Configuration: Triple Redundant License Server

After you install the basic tools for license management, you may decide to set up a triple-redundant license server, which requires a more advanced configuration. A triple-redundant configuration is a special feature of Macrovisions FLEXlm that sets up three license server machines in communication with one another on the same subnet, where one server becomes master and the other two become slaves. This arrangement provides you with triple server redundancy: should the master

13

Wind River License Administrator Tools Guide, 1.1

server go down, the slaves negotiate between themselves which will become the new master. If the new master goes down, there is still the last slave to assume the role of license server. However, under normal conditions, the master server is the only active machine. The two slaves are idle, waiting to come to the rescue should the master die. Wind River does not recommend using this configuration model because:

It has high overhead, requiring three dedicated servers. It does not help you achieve load balancing on a multi-server network, since only one license server is active. It requires reliable network communication, since the master server is constantly updating data on the slaves in case they are required to perform. There is also administrative overhead required for monitoring server function.

The triple-redundant configuration requires a special license management file that can be obtained online. All three servers must use this same license file. Each server should use its own copy of the license file to avoid a single point of failure if the file is kept on a shared disk. As an alternative to three-server redundancy, Wind River recommends using the configuration model discussed in 2.4.3 Using Multiple License Servers for a Single Product, p.22. For more information about three-server redundancy, refer to Macrovisions FLEXlm End Users Guide. If you want to implement a triple-redundant setup, use the Wind River Product Activation Web site (PAWS) to configure a three-server redundant license file.

2.2.3 Setting Up a Host


If you establish a license server on your subnetwork, you can configure host client machines whose license requests will be handled by that license server. There are two methods to configure and activate the clients. Section 4.2 Permanently Activating a User, p.63, provides step-by-step instructions for both, leading to the installation of a client-side license file, WRSLicense.lic. You can also configure a client manually by setting the client-side environment variable, WRSD_LICENSE_FILE. The WRSLicense.lic file or the WRSD_LICENSE_FILE variable answers the clients question Where do I get my license? Setting WRSD_LICENSE_FILE Manually, p.65 provides instructions for manually setting up your client. You also need to know the following:

14

2 Installing and Configuring a License Server 2.3 Configuring License Management for Your Enterprise

How to access multiple license servers (see Accessing Multiple License Servers, p.70). How to set and reset WRSD_LICENSE_FILE (see Resetting License Management on the Client, p.71). How you can use another optional client-side environment variable, LM_PROJECT, to define user groups by project (see 2.4.5 Using LM_PROJECT to Restrict Access, p.26).
2

After setting up license management, if you invoke your product and fail to get a license, it may be caused by a pre-existing .flexlmrc file. See Interfering .flexlmrc, p.83, or Windows registry values (see Resetting License Management on the Client, p.71). For information about customizing your license server, see 3.2 Working with the Options File, p.38. For an overview of Wind Rivers licensing models and their implementation, including information about the three license types, see 2.1 Overview, p.10. To obtain a Product Activation file (WRSLicense.lic), see 2.2 Activating Your License, p.12. Administrators or end users who have obtained WRSLicense.lic from Wind River should follow the step-by-step instructions in Setting Environment Variables with wrenv for an End User, p.82, to configure manually their license. Be sure to copy or move WRSLicense.lic to the appropriate directory (typically, installDir/license).

2.3 Configuring License Management for Your Enterprise


You must decide how to configure a license management server to suit your companys development needs. This section explains how to use:

a single license server for a single product multiple license servers for a single product a single license server for multiple products

Before configuring license management for your enterprise, you should ask yourself the following questions:

Am I installing one product or multiple products?

15

Wind River License Administrator Tools Guide, 1.1

On how many subnetworks am I configuring license servers? Do I need license server redundancy? If so, how many license servers do I have per network? Do I need to run the license server on a server class machine? Is my license server running other applications? If so, are they license-managed?

You may also ask yourself, How can I optimize overall performance, including license server performance? This section first explains the basic license scenario, 2.3.1 Using a Single License Server for a Single Product, p.16, and then describes how to configure multiple license servers (2.3.2 Configuring Multiple License Servers, p.18). More advanced license server options are then discussed (2.4 Configuring Advanced License Management, p.18), including the following:

2.4.3 Using Multiple License Servers for a Single Product, p.22 2.4.4 Using a Single License Server for Multiple Wind River Products, p.23

2.3.1 Using a Single License Server for a Single Product


Figure 2-2 graphically illustrates a single unique user license server environment. Essentially, the license server consists of the license manager daemon, lmgrd, and the vendor daemon, wrsd. The license file controls only one product, a Wind River Workbench unique user subscription license, or a floating license. The two daemons, lmgrd and wrsd, are located in the same directory.

16

2 Installing and Configuring a License Server 2.3 Configuring License Management for Your Enterprise

Figure 2-2

A Single License Server (Unique User)

license requests/ authorizations

2 Clients WRSLicense.lic

License Server Machine

install.txt

lmgrd other vendors vendor daemons other vendors license files wrsd

License Server

WRSLicense.lic

WRSLicense.lic License File Reporting Agent (UU) Transfer File


Internet

wrsd.opt options file Report Log Wind River

The options file (wrsd.opt) triggers the reporting function. Setup installs the options file on your license server, if you have selected to install the Wind River License Reporting Agent. The options file (wrsd.opt) contains the REPORTLOG action keyword, which is the minimal configuration to be in compliance with a UU licensing agreement; see 3.2 Working with the Options File, p.38.
NOTE: If you have multiple Wind River products that duplicate components, we recommend you set up license management for each product on a different license server; however, if you must merge license files, see the instructions in 2.4.4 Using a Single License Server for Multiple Wind River Products, p.23, for workarounds that avoid reporting problems.

Wind River recommends that you place each Wind River license management file on a separate license server. This is the simplest approach because you eliminate the need to merge license files and control access to products by specifying user inclusions and exclusions. You need only to install the product on a client machine or a file server and point to the server from client machines to obtain their licenses.

17

Wind River License Administrator Tools Guide, 1.1

2.3.2 Configuring Multiple License Servers


If you are configuring your network with multiple servers allocating licenses under a single license agreement, to create the servers, just repeat the instructions for each machine. If you are configuring three-host redundancy, that is, a triple-redundant configuration, contact Wind River Customer Support, using PAWS, or see Advanced Configuration: Triple Redundant License Server, p.13.
NOTE: Each reporting agent includes an encryption file. If you have a unique user

license, make sure you use the same encryption file across your enterprise on all license servers. For a UU you can request additional seats, if necessary.

2.3.3 Configuring a Node-Locked Client


To enable a node-locked client to run Wind River products, write the license file you receive from the Product Activation Web site (PAWS) to the product installDir/license and name the file WRSLicense.lic. Then set the environment variable WRSD_LICENSE_FILE to point to the file, or use the wrenv utility. See Setting Environment Variables with wrenv, License Files, p.80.

2.4 Configuring Advanced License Management


This section explains advanced license management, including:

2.4.1 The Networked License Management Process, p.19 2.4.2 Optimizing License Server Performance, p.20 2.4.3 Using Multiple License Servers for a Single Product, p.22 2.4.4 Using a Single License Server for Multiple Wind River Products, p.23

18

2 Installing and Configuring a License Server 2.4 Configuring Advanced License Management

2.4.1 The Networked License Management Process


For unique user and floating licenses, Setup installs the license management utilities, including the reporting agent. These license management utilities reside on the license server machine, most importantly:

the license management daemon, lmgrd (also called the license manager) a vendor-specific daemon (wrsd, for Wind River products) that tracks how many licenses belonging to a particular manufacturers software products are checked out and by whom

It is the job of lmgrd to field your incoming license request by finding the vendor daemon appropriate to your request and passing the request on to it. At the end of the installation procedure, you start your license server (see 2.5 Starting and Stopping a License Server, p.27), which waits for a license request to come in. When an end-user starts a Wind River application, the client issues a request for a license to the license manager. The request carries the applications feature name and version number. Each client machine knows where to send that request based on a client file, WRSLicense.lic, installed by Setup, or an environment variable, WRSD_LICENSE_FILE, either of which, when configured, close the loop in license management communication by pointing to the appropriate license server. When the license manager receives a request, it searches for a match among the feature names and version numbers listed in the license files stored on the license server machine. When it finds a match, it forwards the request to the appropriate vendor daemon, which obtains a license for the client. If you are starting up a Wind River product, the vendor daemon is wrsd. Figure 2-3 illustrates the communications paths and outcomes that obtain a license for a networked client, that is, one using either a unique user or floating license. There is another part to license management for unique user licensees: the reporting function. For more information, see 3. Configuring Usage Reporting Tools.

19

Wind River License Administrator Tools Guide, 1.1

Figure 2-3

The Networked License Management Process

License Server Machine

install.txt license requests/ authorizations License Server

WRSLicense.lic

lmgrd other vendors vendor daemons other vendors license files wrsd

WRSLicense.lic

WRSLicense.lic License File Reporting Agent (UU) Clients wrsd.opt options file

2.4.2 Optimizing License Server Performance


To have the best response time from a license server, it should reside on the same subnet as its client machines. This is especially true if the licensed application is being used heavily and repeatedly, for example, to do code compilations. Below are some recommendations for optimizing license server performance: sockets A single vendor daemon supports as many users as the per-process system limit for file descriptors. When the maximum number of file descriptors is reached, the vendor daemon spawns a copy of itself to allow more sockets to be opened. Each instance of an application connected to a license server uses one socket. The total number of sockets used is slightly larger than the total number of simultaneous applications, resulting from overhead. If more than 1000 concurrent applications are being supported by any single vendor daemon, it is recommended that you divide the clients into at least two groups, each group operating off a different license server, thus a different license management file. It is unlikely you will encounter this level of activity using Wind River products.

20

2 Installing and Configuring a License Server 2.4 Configuring Advanced License Management

CPU time When a license server is handling only a small number of applications, CPU time is typically not a performance issue; in a few days time only a few seconds of CPU time is used. However, when the number of clients increases, or during periods of high checkout/checkin activity (such as during a compilation of many files), consumption of CPU time by the server can become a significant performance factor. If your server load is high, you should ensure that the server host has enough CPU cycles to spare. On UNIX systems, use the top command to check CPU usage. On Windows, use the performance monitor. If CPU time maxes out, consider using multiple license servers. network bandwidth FLEXlm sends small amounts of data across a network. Each checkin or checkout typically requires less than 1KB of data to be transferred. For large numbers of FLEXlm-licensed applications (hundreds), including Wind River products, or for applications that have large amounts of checkin/checkout activity (such as during compilation), the size of the networks bandwidth can be important. If your server load is high, run your Wind River product, other FLEXlm-licensed applications, and the license server on the same local area network (that is, on the same subnet, if possible). remote mounted disks Macrovision, the manufacturer of FLEXlm, recommends that you do not use remote mounted disks to hold FLEXlm-associated daemons and license management files. Instead, you should make sure any vendor daemons, the lmgrd daemon, your license management files, and the debug logs all reside on locally mounted disks. Placing any of these files on a remote disk doubles the points of failure that can lead to a temporary loss of all your licenses.

21

Wind River License Administrator Tools Guide, 1.1

2.4.3 Using Multiple License Servers for a Single Product


Use multiple license servers for a single product if:

You want to build license management redundancy into your system. Your site has discrete user groups and you would like to track usage by group. Assign one server to each group. The usage report logs are generated on a per-server basis. You want to maximize network performance for users on several subnets. Assign one server per subnet.

For example, if you set up two license servers for a base of 20unique user seats, you can assign all 20 seats to each server, providing 100% redundancy. Consider this fictional customers arrangement: Customer X has operations in Tokyo and Chicago, where 10 developers are working on the same project in each city and everyone is networked together. Communications, of course, slow when they shift from local to intercontinental. Customer X sets up a license server in Tokyo and one in Chicago. Customer X specifies in the respective license management files installed on the server machines that all 20 developers should have access to the product installed locally. On each client, Customer X sets the value of WRSD_LICENSE_FILE to point to both server machines. In Tokyo, the environment variable specifies the Tokyo license server machine first, the Chicago one second. In Chicago, the client machines environment variables specify the reverse: the Chicago server machine first, the Tokyo server machine second. The client chooses its license server on a first-come-first-served basis, depending on which server machine is specified first in WRSD_LICENSE_FILE. If the Tokyo server machine goes down, Tokyo clients automatically will seek out the Chicago license server after they find the Tokyo server inaccessible. The advantage of the unique user license type is that you are not charged for more than the base twenty seats, regardless of which server the user accesses or how many seats are assigned to each server. To create multiple license servers for a single product, follow these steps: 1. 2. 3. Determine how many license servers you are setting up based on your network topology. Determine how many seats you need, that is, how many seats are to be assigned each license server machine. Install license management tools on the first license server machine.

22

2 Installing and Configuring a License Server 2.4 Configuring Advanced License Management

4.

Install license management tools on the second license server machine and subsequent server machines, in the same manner. If you do not have sufficient numbers of seats available to do this, contact Wind River Customer Support to arrange for more seats. If you have a FL, you have to purchase more seats. If you have a UU, you can request more seats (for redundancy) without purchasing them because you must report usage quarterly.

5. 6.

Set the WRSD_LICENSE_FILE value on each client to point to the appropriate license server machine. Start the servers running, at which point end-users should be able to access the product.

As a unique user licensee, you are responsible for submitting usage data to Wind River weekly. During installation, Setup places a number of reporting-related files on your license server machine. Data collection begins as soon as the license server is started; but to implement reporting, you must configure customer-specific parameters that control the function of the reporting agent. For more information, see 3. Configuring Usage Reporting Tools.

2.4.4 Using a Single License Server for Multiple Wind River Products
Although not recommended, there may be resource constraints that compel you to use a single license server machine to distribute licenses for more than one Wind River product. As a matter of convenience, you may prefer to merge license files, putting all the feature lines for products handled on one server in a single license file, rather than maintaining a list of license files. (For an example of a merged license file, see Example 2-1.)
NOTE: If the same package or feature name occurs more than once in a merged license file, the license server may not allocate all of the licenses to which you are entitled. For more information, see Limitations of Merged Licenses, p.90.

When FLEXlm receives a license request for a particular product, it goes hunting for the corresponding feature name among license files associated with the products vendor daemon. Specifically, if FLEXlm receives a request for Wind River Workbench, it looks for the WR_WORKBENCH feature name in Wind River license files. FLEXlm then authorizes use of the first feature-name match. So, if a license server controls licenses for two Wind River Workbench products (say, one unique user and one floating), both of which have WR_WORKBENCH components, FLEXlm draws licenses only for the first WR_WORKBENCH

23

Wind River License Administrator Tools Guide, 1.1

encountered, regardless whether the request is intended for that product. FLEXlm cannot differentiate between the features, which are identical. FLEXlm continues to draw licenses associated with the first product until it exhausts available licenses, then FLEXlm begins to draw licenses associated with the second product. There are ways to force the vendor daemon to search license files in a particular order (see Example 2-2), or if you merge license files, a natural search order from top to bottom is established in the resulting file.1 But none of these actions overcomes the limitation imposed by FLEXlm that means the license server satisfies a request with the first feature-name match encountered, whether that is the users intent or not. The vendor daemon searches the license file(s) in an order established by FLEXlm, and it pulls a license for the first feature match until all available licenses for that product are in use. There are two workarounds, either of which makes the use of a single license server for multiple Wind River products truer to intent and which eliminates unique user reporting inaccuracies. One method uses the options files INCLUDE and EXCLUDE action keywords to identify user groups that can be associated with particular products. The other method relies on the interplay between the options files PROJECT type and the LM_PROJECT environment variable, which is set on client machines. The most significant difference between these workarounds is that when using INCLUDE and EXCLUDE to identify user groups, you create and maintain user lists, whereas alternatively you use PROJECT to identify groups of which clients become members when their LM_PROJECT environment variable is set.

To learn how to use PROJECT and LM_PROJECT, see Example 3-2 in 3.3 Options File Examples, p.41. To learn how to use INCLUDE and EXCLUDE, specifically when working with merged license files, see Example 3-3 in 3.3 Options File Examples, p.41.

WARNING: When working with merged license files, if you use Microsoft Notepad or WordPad to edit a license or an options file, you must make sure the filename preserves the .lic or .opt extension. Do this when saving the file by putting double quotes around the filename, including the extensionWRSLicense.licand saving it as a text document.

1. This natural order of precedence can be overridden by inserting the sort=priority mechanism into any INCREMENT or FEATURE line. For more information, see the FLEXlm End Users Guide.

24

2 Installing and Configuring a License Server 2.4 Configuring Advanced License Management

After deciding whether to use PROJECT/LM_PROJECT or INCLUDE/EXCLUDE to configure your system for multiple products, you can proceed with merging the license files. Example 2-1 shows you how to merge license files for one Workbench product under a unique user license and another with a floating license; however, the example is representative of how a merged license file would look if you were working with some other combination of Wind River products.
NOTE: Wind River no longer uses the FEATURE type for license file feature lines, preferring the INCREMENT type for its flexibility when merging files.
Example 2-1 Merging License Files: for Wind River Workbench with two types of licenses

NOTE: You can only merge license files in which the SERVER lines are identical.

Follow these steps to create a merged license file: 1. Open the license files for both products in a text editor (Windows users, see Using Notepad or WordPad as Your Text Editor, p.80). Use one of the Wind River Workbench license files as your base, and copy and paste new text into it. 2. Copy the FEATURE or INCREMENT line of the second license file and paste it into the first after the final line.
CAUTION: When you merge license files, do not change any of the characters in

the file, other than to copy and paste the text from one license file to another. Changes will invalidate the license file. The resulting license file should look as follows:
SERVER jupiter 12345678 27000 VENDOR wrsd PACKAGE WORKBENCH_UU_SUBSCRIPTION_Cfg1 wrsd 2.0 C7F901C9DB56 COMPONENTS="WR_DEBUGGER:2.0 WR_TOS_LX_2_4:2.0 \ WR_TS_MPC82XX:2.0 WR_WORKBENCH:2.0" OPTIONS=SUITE \ SIGN=13B8CA28C770 INCREMENT WORKBENCH_UU_SUBSCRIPTION_Cfg1 wrsd 2.0 30-jun-2004 1 \ AB453A501AD8 VENDOR_STRING="<ln>221073</ln> \ <flt>2</flt><ps>1157-1</ps>" sort=50 BORROW=72 \ SUPERSEDE=WORKBENCH_SUBSCRIPTION_Cfg1 DUP_GROUP=UH \ SUITE_DUP_GROUP=UH ISSUED=24-May-2004 SIGN=DF0B491B60DAC PACKAGE WORKBENCH_SUBSCRIPTION_Cfg1 wrsd 2.0 G798BAC900V6 COMPONENTS="WR_DEBUGGER:2.0 WR_TOS_LX_2_4:2.0 \ WR_TS_MPC82XX:2.0 WR_WORKBENCH:2.0" OPTIONS=SUITE \ SIGN=13B8CA28C770 INCREMENT WORKBENCH_SUBSCRIPTION_Cfg1 wrsd 2.0 30-jun-2004 1 \

25

Wind River License Administrator Tools Guide, 1.1

K953FC0S1AL9 VENDOR_STRING="<ln>221073</ln> \ <flt>2</flt><ps>1157-1</ps>" sort=50 BORROW=72 \ SUPERSEDE=WORKBENCH_SUBSCRIPTION_Cfg1 DUP_GROUP=UH \ SUITE_DUP_GROUP=UH ISSUED=24-May-2004 SIGN=DH3B475B43DAM

For more information about merging license files, see the FLEXlm End Users Guide.
Example 2-2 Specifying License File Search Order Using lmgrd or LMTOOLS

If you choose not to merge license files, you can use the lmgrd command or the LMTOOLS utility (Windows) to produce an effect similar to that of a merged license file. You can direct the lmgrd daemon, in conjunction with the vendor daemon, to look for feature names among multiple license files. However, you are still constrained by FLEXlms limitation that it cannot differentiate among identical feature names and will check out a license for the first feature match it encounters, regardless whether the license request is for that item. For example, from a Windows command prompt, type:
C:> lmgrd -c "c:\workbench\UU\WRSLicense.lic;c:\workbench\FL\WRSLicense.lic" -l c:\logs\lmgrd.log

This command starts the license manager daemon, lmgrd, and instructs it to read FEATURE or INCREMENT lines from two license files: first, the WRSLicense.lic file in the UU directory; second, the WRSLicense.lic in the FL directory. The command also initiates recording of debug run-time data in a log file, lmgrd.log. You can achieve the same effect using LMTOOLS by following these steps: 1. 2. 3. Go to the Config Services tab. Modify the Path to the License File text box. Use semi-colons to separate license file entries, as above. Switch to the Start/Stop/Reread tab and re-read the license files. Or stop the license server and restart it.

When the client initiates a license request upon the opening of an application, lmgrd searches according to your specification.

2.4.5 Using LM_PROJECT to Restrict Access


In addition to WRSD_LICENSE_FILE, there is another client-side environment variable associated with license management, LM_PROJECT. Use of this environment variable is optional. LM_PROJECT, in conjunction with the server-side options file keyword, PROJECT, associates a client machine with a particular project, group, or product and, thus, can restrict access for users of that

26

2 Installing and Configuring a License Server 2.5 Starting and Stopping a License Server

client. This can be useful, for example, if a single license server machine handles multiple platforms and you want certain client machines to have access to one platform or the other. Or if a single license server machine handles two instances of Wind River Workbench with different license types, you can restrict access for certain client machines to one license type or the other. This method of restricting access to a licensed product involves some administrative overhead, as does an alternate method creating user groups and using the options files INCLUDE and EXCLUDE keywords. Both approaches are explained more fully in 3.3 Options File Examples, p.41.

2.5 Starting and Stopping a License Server


After you have configured the license server, before any clients on your network can request a license, you must make sure the license server is running.

2.5.1 Linux and Solaris


In a Linux or Solaris environment, you must initially start the license server manually. Subsequently, you can write a startup script that automatically initiates the server after rebooting. Follow these steps: 1. Change to the directory where the license utilities are installed: For Linux:
% cd installDir/licadmintools-1.1/license/x86-linux2/bin

For Solaris:
% cd installDir/licadmintools-1.1/license/sun4-solaris2/bin

2.

Issue the startup command:


% ./lmgrd -c installDir/licadmintools-1.1/license/WRSLicense.lic -l installDir/license/lmgrd.log [-x lmdown]

The lmgrd command uses the following syntax (also pertinent to Windows):
lmgrd [-c license_file_list] [-l [+]debug_log_path] [-2 -p] [-local] [-x lmdown] [-x lmremove] [-z ] [-v] [-help]

27

Wind River License Administrator Tools Guide, 1.1

The lmgrd command takes the following options: -c license_file_list Use the specified license management file(s):

the full path to a single license file a directory, where all files named *.lic in that directory are used

-l [+]debug_log_path Write debugging information to file debug_log_path. This option uses the letter l, not the numeral 1. Prepending debug_log_path with the + character appends logging entries. In the above example, -l directs output to a log file, lmgrd.log. -2 -p Restrict use of lmdown, lmreread, and lmremove to a system administrator who, by default, is root. If there is a Linux or UNIX group called lmadmin, use is restricted to members of that group only. If root is not a member of this group, then it has no permission to use lmdown, lmreread, and lmremove. If -2 -p is used when starting lmgrd, no Windows user will be able to shut down the license server using lmdown. -local Restrict the lmdown command to be run only from the same machine where lmgrd is running. -x lmdown Disable the lmdown command so no user can run it. If lmdown is disabled, stop the lmgrd and vendor daemon processes on Linux and Solaris using kill pid and on Windows through the Windows Task Manager or Windows service. On Linux and Solaris, do not use the -9 argument with the kill command, because it does not terminate the vendor daemons. -x lmremove Disable the lmremove command so no user can run it. -z Run lmgrd in the foreground. The default behavior is to run lmgrd in the background. If -l debug_log_path is present, no windows are used; but if no -l argument is specified, separate windows are used for lmgrd and each vendor daemon. -v Display the lmgrd version number and copyright, and exit.

28

2 Installing and Configuring a License Server 2.5 Starting and Stopping a License Server

-help Display usage information, and exit. To stop a license manager process, you must stop not only the lmgrd process, but any subordinate daemons spawned by lmgrd, such as wrsd. If you are working with a merged license file and other non-Wind River vendor daemons are present, those daemons must also be stopped: 1. If you did not use -x lmdown when starting the license server, issue the following shutdown command:
% lmutil lmdown -c license_file_list [-vendor vendor_daemon] [-force] [-q] [-all]

The lmdown options are defined as follows: -c license_file_list Use the specified license management file(s). It is always recommended to use -c license_file_list with lmdown. -vendor vendor_daemon Shut down only the specified vendor daemon. This option allows lmgrd to continue running. -q Do not prompt or print a header. Otherwise lmdown asks Are you sure? [y/n]. -all Automatically shut down all servers, when multiple servers are used. The -all option implies -q. -force If licenses are borrowed, run lmdown only from the machine where the license server is running. 2. If you used -x lmdown when starting the license server, determine the process ID (pid) of the license manager process and any other processes it spawned, such as wrsd:
% ps | grep lmgrd

Then kill the processes:


% kill -9 pid1 pid2

29

Wind River License Administrator Tools Guide, 1.1

Linux and Solaris License Server Lock File Permission Issues

On Linux and Solaris, the license server uses a lock file created in /var/tmp, by default. For example, the file listing appears as:
% ls -l /var/tmp/lockwrsd -rw-r--r-1 workbench other 0 Sep 12 18:16 /var/tmp/lockwrsd

When the license manager (lmgrd) is started for the first time, the lock file is created with the permissions of the user starting the daemon. You may need to modify the file permissions to ensure that other users can start the server.

2.5.2 Windows
In the Windows environment you can start and stop a license server by using either the LMTOOLS graphical interface or the command line.
Using the LMTOOLS Application

During product installation, the license manager utility, LMTOOLS, and other FLEXlm utilities are copied into the \installDir\licadmintools-1.1\license\x86-win32\bin directory. Use the license manager utility to start the license manager: 1. Locate the LMTOOLS executable, lmtools.exe, and start the application. The window in Figure 2-4 appears.

30

2 Installing and Configuring a License Server 2.5 Starting and Stopping a License Server

Figure 2-4

License Manager Utility (LMTOOLS)

If no license servers have been configured, the display box will be blank. If you have already configured a server, its name will appear in the display box, as shown in Figure 2-4. 2. Before starting the license server, if you need to configure a new server or make changes to an existing one, click the Config Services tab (Figure 2-5).

31

Wind River License Administrator Tools Guide, 1.1

Figure 2-5

Config Services Tab (LMTOOLS)

If a server is already running, the various text boxes will be filled in. To enter new values, follow these steps: 1. Replace the default FLEXlm Service 1" with the service name of your choice. If, during installation, you specified that the license server should function as a service, a default value automatically appears. In the Path to the lmgrd.exe file text box, insert or browse to the path where the FLEXlm license server daemon, lmgrd.exe, is located. By default, it is copied to installDir\licadmintools-1.1\license\hostType\bin. In the Path to the license file text box, insert or browse to the path where the license file was installed. By default, it is copied to installDir\license directory, under the name WRSLicense.lic. If there are multiple license file paths, you must type them in individually, you cannot browse to them. Use a semi-colon (;) to separate filenames. In the Path to the debug log file text box, insert the path to a debug log file which will record operating data for the license management and vendor daemons (lmgrd and wrsd). (This is not the same file as the usage report log required of unique user licensees in conjunction with the reporting agent.) For more information about debugging, see Example 3-4 in 3.3 Options File Examples, p.41.

2.

3.

4.

32

2 Installing and Configuring a License Server 2.5 Starting and Stopping a License Server

5. 6. 7.

Select Use Services if you want the license server to act as a service (recommended). This is the default, so the box may already be checked. Select Start Server at Power Up if you want to start the server automatically with each reboot. Click Save Service to save any new values, then Yes in the pop-up dialog box. Your license server is now configured and ready to be started.
2

8. 9.

Select Start/Stop/Reread, shown in Figure 2-6. To start the license server, make sure Workbench License Manager is selected, then click Start Server.

If you make changes to the license file, you must force the server to re-read the file. Follow the instructions in Re-reading Files, p.81.
Figure 2-6 Start/Stop/Reread Tab (LMTOOLS)

If you started the server from LMTOOLS, you can stop it as follows: 1. 2. 3. 4. Open the LMTOOLS application. Go to the Start/Stop/Reread tab. Make sure the license manager appropriate to your product is highlighted. Select Stop Server.

33

Wind River License Administrator Tools Guide, 1.1

If you start the server manually, you must stop the server according to the steps in the following section, Using the Command Line, p.34.
Using the Command Line

You can also start the license server from a DOS command prompt. Follow the steps below, substituting for installDir the directory path where the license manager was installed. 1. 2. Change to the directory where the license utilities are installed:
C:\> cd installDir\licadmintools-1.1\license\x86-win32\bin

Issue the startup command (see 2.5.1 Linux and Solaris, p.27 for an explanation of syntax):
C:\> lmgrd -c license_file_list -L [+]debug_log_path

Where license_file_list is one or more of the following:

the full path to a single license management file a directory where all files suffixed .lic are used

And where debug_log_path is the full path to the debug log file. Prepending debug_log_path with the + character appends entries to the log file when lmgrd is started or restarted. Pathnames that include spaces require double quotes around the path. To stop a license server that has been started manually, you must stop both the license management and vendor daemons: 1. 2. 3. 4. 5. 6. Open the Windows Task Manager (CTRL+ALT+DEL). Choose the Processes tab. Select the lmgrd process. Click End Process. Select the wrsd process. Click End Process.

34

2 Installing and Configuring a License Server 2.6 Uninstalling the License Server

2.6 Uninstalling the License Server


If you are uninstalling the product from its host machine and the license server has been installed in the same tree, the uninstall process does not remove the license server software. To uninstall the license management tools (LMTOOLS) using the uninstaller, complete the following steps: 1. 2. 3. Make sure that the license server has been stopped. (See 2.5 Starting and Stopping a License Server, p.27.) From a command prompt go to
installDir\uninstaller\Wind_River_Administration_Tools_1.1

Run the uninstaller for your system:

Solaris
% solarisuninstall.bin

Linux
% linuxinstall.bin

Windows
uninstall.exe

The uninstaller will not delete all license management subdirectories if there are user-created log files in them. Use the manual procedure described below to delete them. To manually uninstall the license server application, follow these steps: 1. 2. Make sure the license server has been stopped. (See 2.5 Starting and Stopping a License Server, p.27.) Change to the installation directory tree, installDir/license.

35

Wind River License Administrator Tools Guide, 1.1

3. 4.

Delete the license file. This is sufficient to uninstall the license server. To remove supporting directories and files, change directories to installDir and recursively remove all the license management-related directories and files: install.txt license setup.log uninstaller host log.txt setup licadmintools-1.1

NOTE: If you are using a merged license file that resides in the installation tree, removing it affects all products whose licenses are under the files control. You should back up the file before removal, then delete any merged features no longer in use, and move the modified file to the new license server machine.

2.7 Removing a Permanent Node-Locked License File


If you are uninstalling the product from the node-locked host machine and you have installed the license management tools on the host, the uninstall process does not remove license management directories and files. To manually uninstall license management tools from a node-locked host, simply remove the license file. You can also remove all the license management-related directories and files, recursively, in installDir: install.txt license setup.log uninstaller host log.txt setup licadmintools-1.1

NOTE: If you are using a merged license file that resides in the installation tree, removing it affects all products whose licenses are under the files control. It is recommended you back up the file before removal, then delete any merged features no longer in use, and move the modified file to the new host machine.

36

3
Configuring Usage Reporting Tools
3.1 Introduction 37 3.2 Working with the Options File 38 3.3 Options File Examples 41 3.4 WRS License Reporting Agent 49 3.5 Error Processing 61

3.1 Introduction
If you have any unique user licenses, you must report usage data to Wind River. This chapter describes usage reporting and explains how to configure your license servers options file to enable reporting. To report usage data to Wind River, you need:

an options file on each license server machine, which implements the collection of usage data in report logs a reporting agent on each license server machine, which controls the collection of usage data and its encryption to protect your privacy an encryption key that encrypts the usage data collected and reported to Wind River, making it anonymous a de-encrypter for decrypting the anonymous user data

37

Wind River License Administrator Tools Guide, 1.1

The options file is installed as a pre-configured template. The encryption file is provided with each installation as a unique filter. Although data collection begins as soon as your license server is started because the options file is ready to go, after installing the agent, you must edit the options file to specify the directory path where the report log resides and configure access to groups of users, if necessary.

3.2 Working with the Options File


You can modify the behavior of the license server using the options file. You must add the REPORTLOG keyword to your options file in order to invoke the collecting of usage data. Other action keywords enable different license server actions, such as restricting user access to the product and controlling or disabling a debugging feature. During installation of the WRS license reporting agent, a pre-configured basic options file, wrsd.opt, is installed on the license server in installDir/license. The license file resides in the same directory. Do not move these files from this location. Before you start your license server, you need to specify where the usage data is stored. See 3.2.1 Specifying a Report Log, p.39. With the REPORTLOG action keyword already in place and the report log specified, when the license manager is started, it spawns the wrsd vendor daemon, which discovers the options file, and data collection commences. Each vendor daemon must have only one options file. Only one instance of a vendor daemon process is allowed to run on a license server machine (for Wind River, that is wrsd). !
WARNING: Do not try to run multiple instances of wrsd on one machine.

Remember that lmgrd spawns wrsd, and can be running automatically at startup. If you are not sure if the license manager is running, check first before trying to start it again. One way to do that is to use the LMTOOLS utility; see 2.5 Starting and Stopping a License Server, p.27.
NOTE: Only unique user licenses require an options file. The options file is not

required for node-locked or floating licenses.

38

3 Configuring Usage Reporting Tools 3.2 Working with the Options File

3.2.1 Specifying a Report Log


Follow these steps to create a report log file: 1. Open the options file, installDir/license/wrsd.opt, in a text editor. Lines in the options file are limited to 2048 characters. Use the backslash character (\) as a continuation character. 2. Make sure the filename, installDir/license/reportLogs/wrsdReport.log, is the full path to the receiving report log, as follows:
# Specify that a report log file for Wind River be written REPORTLOG +installDir/license/reportLogs/wrsdReport.log

Use the + sign because it causes the wrsd daemon to append to the existing log; otherwise wrsd overwrites the contents, thereby deleting it. You do not want to lose data for any part of a reporting period.
NOTE: Windows users must use the backslash character (\) when specifying the report log path.

3. !

Save the file.


WARNING: When you edit this file in Windows, be sure to preserve the .opt

extension. When you start the license server, WRSReport begins data collection and automatically creates the wrsdReport.log, if it does not already exist.

3.2.2 Creating an Options File


If you need to create an options file from scratch, follow these steps: 1. Open a text editor and create a file, wrsd.opt. Lines in the options file are limited to 2048 characters. Use the backslash character (\) as a continuation character.

39

Wind River License Administrator Tools Guide, 1.1

2.

Type the following as the basic REPORTLOG element:


# Specify that a report log file for Wind River be written REPORTLOG +installDir/license/reportLogs/wrsdReport.log

Make sure the filename, installDir/license/reportLogs/wrsdReport.log, is the full path to the receiving report log. The installDir placeholder is the installation path for license management.
NOTE: Windows users must use the backslash character (\) when specifying the report log path.

Use the + sign to force the wrsd daemon to append to the existing log; otherwise wrsd overwrites the contents, thereby deleting it. You do not want to lose data for any part of a reporting period. 3. Implementing the REPORTLOG action is the minimum requirement for compliance with your unique user license agreement. Save your options file in the same directory as the license file, WRSLicense.lic, in: installDir/license.
NOTE: Do not install the options file in a non-standard directory other than the directory where your license file resides

3.2.3 Modifying and Re-reading an Options File


If you make changes to the options file before running your product, you must make sure wrsd re-reads the file. Either you must stop the license manager and restart it (see 2.5 Starting and Stopping a License Server, p.27), or you can use the lmreread utility, which prompts the vendor daemon to re-read its options file. To invoke lmreread, see the instructions in Re-reading Files, p.81. Lines in the options file are limited to 2048 characters. Use the backslash character (\) as a continuation character.

40

3 Configuring Usage Reporting Tools 3.3 Options File Examples

3.3 Options File Examples


If you adhere to the recommended license management configuration policy of one unique user-licensed product per license server machine, you can avoid using most of the options explained in the following examples. These examples show how to use certain action keywords. Three of the examples provide methods for restricting access to license seats:

Example 3-1 uses INCLUDE or EXCLUDE keywords to restrict user access to a single product. Example 3-2 uses the PROJECT keyword and a client-based environment variable to restrict access to a Wind River Workbench license server, if, for example, you have both unique user and floating licenses available from a single server. Example 3-3 uses INCLUDE or EXCLUDE keywords and user lists to restrict access to different license types. Example 3-4 explains how to use DEBUGLOG and NOLOG to control error tracking and verify the general health of the license manager.

In these examples the + sign is used in the options file because it forces the wrsd daemon to append to the existing log; otherwise wrsd overwrites the contents, thereby deleting it. You do not want to lose data for any part of a reporting period. If you rely on user lists to restrict access (Example 3-3), you must modify the license servers options file to reflect personnel changes, such as new hires, resignations, or when a user requires different access. If you use the options files PROJECT keyword and the client-side LM_PROJECT environment variable to coordinate serving multiple products from a single server (Example 3-2), there is still administrative overhead, but the ongoing maintenance should be less. The INCLUDE and EXCLUDE options follow rules of precedence. For more information, see 3.3.2 Order of Precedence in the Options File, p.48. For detailed information about the various action keywords available for use with your product, see A. Option File Action Keywords.

41

Wind River License Administrator Tools Guide, 1.1

3.3.1 Examples
NOTE: In the following examples, we assume that the PATH environment variables have been set to installDir/licadmintools-1.1/license/hostType/bin to allow

access to the utilities.


Example 3-1 Restricting Access for Multiple Users

The following example illustrates how to use the options files INCLUDE & EXCLUDE action keyword to restrict access to a single product. The following license file is a typical example of a Wind River Workbench license file, in this case, for Wind River Workbench for Linux:
SERVER jupiter 12345678 27000 VENDOR wrsd PACKAGE WORKBENCH_SUBSCRIPTION_Cfg1 wrsd 2.0 C7F901C9DB56 COMPONENTS="WR_DEBUGGER:2.0 WR_TOS_LX_2_4:2.0 \ WR_TS_MPC82XX:2.0 WR_WORKBENCH:2.0" OPTIONS=SUITE \ SIGN=13B8CA28C770 INCREMENT WORKBENCH_SUBSCRIPTION_Cfg1 wrsd 2.0 30-jun-2004 1 \ AB453A501AD8 VENDOR_STRING="<ln>221073</ln> \ <flt>2</flt><ps>1157-1</ps>" sort=50 BORROW=72 \ SUPERSEDE=WORKBENCH_SUBSCRIPTION_Cfg1 DUP_GROUP=UH \ SUITE_DUP_GROUP=UH ISSUED=24-May-2004 SIGN=DF0B491B60DAC

In this example, you will modify an options file to restrict usage among different subsets of developers. 1. 2. Determine who is to use the Wind River Workbench. Look for the feature name of the products:
PACKAGE WORKBENCH_SUBSCRIPTION_Cfg1...

This will be used as a feature that can be checked out by the included users. The feature will be unavailable to all other users. Use INCLUDE when you want to provide access to a small number of users. Use EXCLUDE when you want to deny access to a small number of users. You should not need to use both in the same options file. 3. Begin modifying the options file. Open a text editor and name your file wrsd.opt (see Using Notepad or WordPad as Your Text Editor, p.80). Define your user groups. Each group must be defined on a separate line, following the REPORTLOG invocation line. Use the GROUP type, according to the following syntax:
GROUP groupName userList

42

3 Configuring Usage Reporting Tools 3.3 Options File Examples

For example, define two groups of included users:


REPORTLOG +installDir/license/reportLogs/wrsdReport.logG56 GROUP WB_USERS_1 johns maryf suew joeb GROUP WB_USERS_2 bobh jimk barryv

In this case, the reason for identifying two distinct groups is in acknowledgement of the limit of 2048 characters per line in the options file. You might run out of space for your list of users as the groups grow. 4. Add the action lines. Create an INCLUDE line for each group of users to be given access to Wind River Workbench (the feature name identified in Step 3). The syntax is:
action featureName type name

For example:
INCLUDE WORKBENCH_SUBSCRIPTION_Cfg1 GROUP WB_USERS_1 INCLUDE WORKBENCH_SUBSCRIPTION_Cfg1 GROUP WB_USERS_2

The complete options file, wrsd.opt, looks like this:


REPORTLOG +installDir/license/reportLogs/wrsdReport.log GROUP WB_USERS_1 johns maryf suew joeb GROUP WB_USERS_2 bobh jimk barryv INCLUDE WORKBENCH_SUBSCRIPTION_Cfg1 GROUP WB_USERS_1 INCLUDE WORKBENCH_SUBSCRIPTION_Cfg1 GROUP WB_USERS_2

This options file means that only users in these two groups can have access to licenses for this instance of Wind River Workbench. 5. Make the license server re-read the options file before using the product. The quickest method is to invoke lmreread from a command line, as follows: a. b. Change directories to
% cd installDir/licadmintools-1.1/license/hostType/bin

Type:
% lmutil lmreread -c /pathToLicenseFile

The -c argument tells lmreread that the input, pathToLicenseFile, is the full path to the license file. For more information about re-reading options files, see Re-reading Files, p.81.

43

Wind River License Administrator Tools Guide, 1.1

Example 3-2

Using PROJECT to Restrict User Access

The PROJECT type in the options file on a license server can be used in conjunction with the LM_PROJECT environment variable on the client to identify the client as a member of a particular group with restricted access to licenses. This might be useful if you have floating and unique user licenses for Wind River Workbench available from the same license server machine (jupiter, in this example). You can use PROJECT and a merged license file to define a group associated with each license type. You then set the LM_PROJECT environment variable to point to one of the two group names, which restricts access for that client to the associated license type. This method differs from Example 3-3 below because it does not require the creation of user lists. The merged license file looks like this:
SERVER jupiter 12345678 27000 VENDOR wrsd PACKAGE WORKBENCH_UU_SUBSCRIPTION_Cfg1 wrsd 2.0 C7F901C9DB56 COMPONENTS="WR_DEBUGGER:2.0 WR_TOS_LX_2_4:2.0 \ WR_TS_MPC82XX:2.0 WR_WORKBENCH:2.0" OPTIONS=SUITE \ SIGN=13B8CA28C770 INCREMENT WORKBENCH_UU_SUBSCRIPTION_Cfg1 wrsd 2.0 30-jun-2004 1 \ AB453A501AD8 VENDOR_STRING="<ln>221073</ln> \ <flt>2</flt><ps>1157-1</ps>" sort=50 BORROW=72 \ SUPERSEDE=WORKBENCH_SUBSCRIPTION_Cfg1 DUP_GROUP=UH \ SUITE_DUP_GROUP=UH ISSUED=24-May-2004 SIGN=DF0B491B60DAC PACKAGE WORKBENCH_SUBSCRIPTION_Cfg1 wrsd 2.0 G798BAC900V6 COMPONENTS="WR_DEBUGGER:2.0 WR_TOS_LX_2_4:2.0 \ WR_TS_MPC82XX:2.0 WR_WORKBENCH:2.0" OPTIONS=SUITE \ SIGN=13B8CA28C770 INCREMENT WORKBENCH_SUBSCRIPTION_Cfg1 wrsd 2.0 30-jun-2004 1 \ K953FC0S1AL9 VENDOR_STRING="<ln>221073</ln> \ <flt>2</flt><ps>1157-1</ps>" sort=50 BORROW=72 \ SUPERSEDE=WORKBENCH_SUBSCRIPTION_Cfg1 DUP_GROUP=UH \ SUITE_DUP_GROUP=UH ISSUED=24-May-2004 SIGN=DH3B475B43DAM

Complete the following steps to set up your server and clients: 1. 2. Identify your groups. For this example, use jupiter_UU and jupiter_FL. Look for the Wind River Workbench feature names, which are located next to the files PACKAGE keywords:
WORKBENCH_UU_SUBSCRIPTION_Cfg1

and
WORKBENCH_SUBSCRIPTION_Cfg1

44

3 Configuring Usage Reporting Tools 3.3 Options File Examples

3.

Modify the options file by adding action lines. Create INCLUDE lines for each Wind River Workbench license type and associate it with the appropriate group name. The syntax is:
action featureName type name

For example:
REPORTLOG +/opt/workbench/license/x86-win32/bin/wrsdReport.log INCLUDE WORKBENCH_UU_SUBSCRIPTION_Cfg1 PROJECT jupiter_UU INCLUDE WORKBENCH_SUBSCRIPTION_Cfg1 PROJECT jupiter_FL

4.

For the UU client, set the value for LM_PROJECT for the desired user group. For example, to restrict a Linux client to unique user licenses, type in the command line:
% setenv LM_PROJECT jupiter_UU

5. 6.

For the floating client set LM_PROJECT for the floating license user group:
% setenv LM_PROJECT jupiter_FL

Make the license server re-read the options file before using Wind River Workbench. The quickest method is to invoke lmreread from a command line, as follows: a. b. Change directories to
% cd installDir/licadmintools-1.1/license/hostType/bin

Type:
% lmutil lmreread -c /pathToLicenseFile

The -c argument tells lmreread that the input, pathToLicenseFile, is the full path to the license file. For more information about re-reading options files, see Re-reading Files, p.81. This method of limiting access requires someone to make sure that the LM_PROJECT environment variable is properly set on the participating node-locked hosts by their respective users. For additional information, see 2.4.5 Using LM_PROJECT to Restrict Access, p.26.

45

Wind River License Administrator Tools Guide, 1.1

Example 3-3

Restricting User Access to Multiple License Types

You can achieve the same effect as in Example 3-2 above by using the INCLUDE action keyword and user lists to restrict access among your users to the two license types UU and FL for Wind River Workbench. Maintenance requirements differ for the two examples. Your merged license file looks as follows:
SERVER jupiter 12345678 27000 VENDOR wrsd PACKAGE WORKBENCH_UU_SUBSCRIPTION_Cfg1 wrsd 2.0 C7F901C9DB56 COMPONENTS="WR_DEBUGGER:2.0 WR_TOS_LX_2_4:2.0 \ WR_TS_MPC82XX:2.0 WR_WORKBENCH:2.0" OPTIONS=SUITE \ SIGN=13B8CA28C770 INCREMENT WORKBENCH_UU_SUBSCRIPTION_Cfg1 wrsd 2.0 30-jun-2004 1 \ AB453A501AD8 VENDOR_STRING="<ln>221073</ln> \ <flt>2</flt><ps>1157-1</ps>" sort=50 BORROW=72 \ SUPERSEDE=WORKBENCH_SUBSCRIPTION_Cfg1 DUP_GROUP=UH \ SUITE_DUP_GROUP=UH ISSUED=24-May-2004 SIGN=DF0B491B60DAC PACKAGE WORKBENCH_SUBSCRIPTION_Cfg1 wrsd 2.0 G798BAC900V6 COMPONENTS="WR_DEBUGGER:2.0 WR_TOS_LX_2_4:2.0 \ WR_TS_MPC82XX:2.0 WR_WORKBENCH:2.0" OPTIONS=SUITE \ SIGN=13B8CA28C770 INCREMENT WORKBENCH_SUBSCRIPTION_Cfg1 wrsd 2.0 30-jun-2004 1 \ K953FC0S1AL9 VENDOR_STRING="<ln>221073</ln> \ <flt>2</flt><ps>1157-1</ps>" sort=50 BORROW=72 \ SUPERSEDE=WORKBENCH_SUBSCRIPTION_Cfg1 DUP_GROUP=UH \ SUITE_DUP_GROUP=UH ISSUED=24-May-2004 SIGN=DH3B475B43DAM

The strategy here is to restrict access for a group of users to one or the other license type (UU or FL). It is difficult to provide a single user with access to both license types, although this can be done. Follow the strategies and steps below to restrict access for particular groups of users: 1. 2. 3. Determine who is to use the unique user licenses. Determine who is to use the floating licenses. Look for the Wind River Workbench feature names, which are located next to the files PACKAGE keywords:
WORKBENCH_UU_SUBSCRIPTION_Cfg1

and
WORKBENCH_SUBSCRIPTION_Cfg1

The included users will be able to check out these feature names.

46

3 Configuring Usage Reporting Tools 3.3 Options File Examples

4.

Begin modifying the options file. After the REPORTLOG invocation line, specify your two groups of developers. You must define groups on separate lines, according to the following syntax:
GROUP group_name user_list

For example:
GROUP WB_UU johns maryf suew joeb bobh jimk barryv GROUP WB_FL jackl willc daveh denisep

5.

Add the action lines. Add INCLUDE lines for each feature name identified in Step 3, and associate the features with the appropriate group of users. The syntax is:
action featureName type name

For example:
INCLUDE WORKBENCH_UU_SUBSCRIPTION_Cfg1 GROUP WB_UU INCLUDE WORKBENCH_SUBSCRIPTION_Cfg1 GROUP WB_FL

The complete options file, wrsd.opt, looks like this:


REPORTLOG +/opt/workbench/license/x86-win32/bin/wrsdReport.log GROUP WB_UU johns maryf suew joeb bobh jimk barryv GROUP WB_FL jackl willc daveh denisep INCLUDE WORKBENCH_UU_SUBSCRIPTION_Cfg1 GROUP WB_UU INCLUDE WORKBENCH_SUBSCRIPTION_Cfg1 GROUP WB_FL

6.

Make the license server re-read the options file before using the product. The quickest method is to invoke lmreread from a command line, as follows: a. b. Change directories to
% cd installDir/licadmintools-1.1/license/hostType/bin

Type:
% lmutil lmreread -c /pathToLicenseFile

The -c argument tells lmreread that the input, pathToLicenseFile, is the full path to the license file. For more information about re-reading options files (as well as license files), see Re-reading Files, p.81. This method of limiting access requires that someone maintain the user lists to reflect personnel changes. For example, if Barry V. leaves the company and Emma N. replaces him, the group, WB_UU, as defined in the options file, must change. Or if Dave H. shifts from developing with a floating license to using a unique user seat, group membership, as defined in the options file, must be modified to reflect that. For additional information, see the usage details for INCLUDE, p.102.

47

Wind River License Administrator Tools Guide, 1.1

Example 3-4

Debugging

In the options file, you can specify two action keywords that help control output to a run-time debug log. The log tracks checkins, checkouts, and error messages (see Using a Debug Log (UU and FL), p.93).
DEBUGLOG

Use this action keyword to restrict debugging output to the vendor daemon associated with the options file, in the case of Wind River products, wrsd. Data is sent to a specified file, separate from the debugging log which catches data for all vendor daemons on any one license server.
NOLOG

Use this action keyword to restrict the type of data collected in the debug log file. Data accumulates rapidly and, depending on the number of users, can consume disk space. For syntax and additional information about these action keywords, see DEBUGLOG, p.100 and NOLOG, p.104.

3.3.2 Order of Precedence in the Options File


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

Everyone not on the list is allowed to use the feature.


INCLUDE

Only those users on the list are allowed to use the feature. All others are excluded. 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.

48

3 Configuring Usage Reporting Tools 3.4 WRS License Reporting Agent

Once you create an INCLUDE or EXCLUDE list, everyone else is implicitly outside the group. This feature allows you, as license administrator, to control licenses without having to explicitly list each user permitted or denied access. In other words, there are two approaches:

Give most users access, and list only the exceptions. Severely limit access, and list only users having access privileges.

3.4 WRS License Reporting Agent


If you have a unique user license, you are required to generate logs that capture product usage and to submit quarterly reports based on those logs. You can turn on report logging by creating an options file for the vendor daemon utility, wrsd, as discussed in 3.2.2 Creating an Options File, p.39. The daemon generates the logs, which the WRS license reporting agent processes into human-readable reports, one for each license server. Then the reporting agent consolidates this data into a single ZIP file for export to Wind River. The ZIP file is sent to reports@windriver.com at the end of each contract quarter, along with other quarterly reporting obligations. Wind River expects data for every license file issued. To use the WRS license reporting agent, you muston each serverinvoke the options file for the vendor daemon wrsd. If you have licensed RTID, an RTI (Real-Time Innovations) add-on product available from Wind River, you must invoke the appropriate RTID daemon. When you have completed the above, run the WRS license reporting agent according to the guidelines in 3.4.2 Running the WRS License Reporting Agent, p.52. Figure 3-1 charts how this reporting agent is used.

49

Wind River License Administrator Tools Guide, 1.1

Figure 3-1

Using the WRS License Reporting Agenta Subnet License Server 1 License Server 2

...

License Server N

wrsd

wrsd

wrsd

Input files for WRS license reporting agent

Server 1 .log files

Server 2 .log files

...

Server N .log files

WRS license reporting agent

Dictionary file

Summary report

Usage reports

ZIP file (usage reports and summary report)

reports@windriver.com a. Other materials sent to Wind River generally include the total number of developers, any user exception cases, and the total production licenses.

E-mail .zip file and other materials to

50

3 Configuring Usage Reporting Tools 3.4 WRS License Reporting Agent

NOTE: The reports generated by the WRS license reporting agent identify all users

of a Wind River products license server during a quarter. The reporting mechanism does not account for user exception cases. You must document these according to the instructions in your Wind River Enterprise License Agreement. For more information on user exception cases, see Unique User License (UU), p.8.

3.4.1 Required Files for WRS License Reporting Agent


The following requirements must be met in order for the WRS license reporting agent to run.
NOTE: Make sure that you have installed the license reporting agent. See 2.2.2 Installing License Administrator Tools (LM Server and RA), p.13. A Valid FLEXlm License File for the Agent

Wind River supplies a permanent license file as part of the WRS license reporting agent installation. This node-locked FLEXlm license file controls windrreport, a WRS license reporting agent utility that generates usage reports. This license file must be stored in the following location, with the following filename: installDir/licadmintools-1.1/license/hostType/reporting/wrsReport/ flexreport/windr/v3.2a/machind/license.dat
An Encryption Key

You need an encryption key to decode the encrypted usernames and hostnames found in the generated usage reports. The encryption key should be set once and backed up to prevent loss. You create the encryption key, so you can decide which groups of users it covers: for example, your worksite, your company, or a single network. We recommend that you not change the encryption key once you have created and used it. Values encrypted using one key cannot be decrypted using another. Place the encryption key in the following location: installDir/licadmintools-1.1/license/hostType/reporting/wrsReport/ flexreport/windr/v3.2a/machind/license/encrypt.dat

51

Wind River License Administrator Tools Guide, 1.1

When you first install the WRS license reporting agent, the encrypt.dat file at the above path location contains an example encryption key. You can use the example as a template when creating your own key. This example key can be used with the demo log files. !
CAUTION: If you want to keep your hostnames and usernames private, you should

change the example key to a new, unique value before you run the WRS license reporting agent on your own log files. The encrypt.dat file contains one line with the following form:
key = keyvalue

The keyvalue argument must be a hexadecimal string exactly 16 characters in length. Make sure there is a space both before and after the = symbol. For example:
key = AC37F205D753BD9C

The Options File

See 3.2 Working with the Options File, p.38. An options file must be on each unique user license server, and must include the REPORTLOG action keyword.
NOTE: The options file must be in the same directory as the license file.

3.4.2 Running the WRS License Reporting Agent


To run the WRS license reporting agent, you must execute the wrsReport command from within a shell in a directory where the tool resides. On Windows hosts, you must use a command shell. Before you can run wrsReport, set the PATH environment variable by running the wrsenv command. On Solaris and Linux:
% cd installDir/licadmintools-1.1/license/hostType/reporting/WRSReport % source wrsenv

where the host type is sun4-solaris2 or x86-linux2. On Windows:


C:\> cd installDir\licadmintools-1.1\license\x86-win32\reporting\WRSReport C:\> wrsenv.bat

By default, the wrsReport command, without any arguments, runs in the current directory and assumes input files are located there (see Example 3-5). The

52

3 Configuring Usage Reporting Tools 3.4 WRS License Reporting Agent

command prompts you to enter your company name and the quarterly reporting start and end dates. If you do not know what these dates should be, they are documented in your Enterprise License Agreement, Exhibit A. (If you cannot locate the information, contact Wind River Customer Support.) A start date is required. To learn how to specify where your log files should be stored, see 3.2.2 Creating an Options File, p.39. If you are analyzing data from log files located away from the WRS license reporting agent executable, you need to use either the -d or -f option explained below. The syntax for the wrsReport command is as follows:
% wrsReport [-start startDate] [-end endDate] [-d fullPathToDirectory -d ...] \ [-f pathToInputFile -f ...] fullPathToReportLog -c companyName

The command takes the following options: [ ... ] Optional parameters. -start startDate The beginning of your contract quarter. The startDate argument takes the form mm-dd-yyyy. The time is rounded to midnight of the day specified. -end endDate The end date of the quarter, taking the form mm-dd-yyyy. This argument is optional. If endDate is missing and -start startDate is present, wrsReport automatically calculates the quarter to be ninety days from startDate (at midnight). -d fullPathToDirectory The full directory path to where report logs are stored. Repeat the -d option in the command line for each directory path specified. For a usage example, see Example 3-6. The -d option is especially useful if you want to run a wrsReport analysis quickly. The utility reads the log files in the directories you specify. -f pathToInputFile The path to a user-created file that contains the full pathnames of all the report logs to be reported on. The -f option is especially useful if your network has multiple license servers on it. You can create a file that lists the various directory paths to your server log file, then with the -f option, direct wrsReport to analyze the data. This file can be used repeatedly. Of course, if you add or subtract servers from your network, you must update the file. For a usage example, see Example 3-7.

53

Wind River License Administrator Tools Guide, 1.1

fullpathToReportLog The path to a report log file. You may add multiple full paths to the command line. -c companyName The name of the company to use in the output .zip file.
NOTE: If you use the wrsReport command on Windows, note the following

restrictions:

The wrsReport command must be prefaced with perl, as in Example 3-5. Paths may not use UNC (Universal Naming Convention) pathnames (such as \\server\c$\...). Instead, paths must be mapped to drive letters. Paths may not contain embedded spaces.

For a description of the output generated by wrsReport, see 3.4.3 WRS License Reporting Agent Output, p.59.

Working with Report Log Files

Wind Rivers standard reporting period is 3 months. If you have concerns about disk space on your license server machine, you can reduce the size of your report logs by rotating the report logs more frequently. You may prefer to write a script that records data on a shorter cycle, say 30 days, and creates archive files that can be aggregated by the WRS license reporting agent at the end of your reporting quarter. The WRS license reporting agent program does not care how you name your log files, as long as you feed the program all the files generated for the quarter. Using a consistent naming convention, however, is in your best interest, so you can identify the required files. For guidance naming your log files, see below, Naming Your Report Log Files, p.54.
Naming Your Report Log Files

When you create your options file, the first time you specify the path to the report log, you could be establishing a convention for log file names. This is the time to consider how to label your log files. All report logs must use the .log extension, the default value expected by the WRS license reporting agent. Beyond that, a consistent naming convention will help you identify which files need to be fed to the WRS license reporting agent for any given quarter.

54

3 Configuring Usage Reporting Tools 3.4 WRS License Reporting Agent

If you are going to generate multiple log files during a reporting quarter, archiving them, and later processing them with the WRS license reporting agent, you may want to use one of the following naming conventions, where serverName is the name of the license server machine, date is todays date or the month and year (as below), and digit increments with the creation of multiple report logs: serverName_date.log jupiter_08_03.log jupiter_09_03.log jupiter_10_03.log
Restrictions

serverName_digit.log jupiter_01.log jupiter_02.log jupiter_03.log

Note the following requirements when you use the wrsReport command:

The file extension of the input files must be .log. Filenames for report logs must be standardized according to a naming convention, so the report logs can be aggregated without conflicting filenames. For more information on report log naming conventions, see Naming Your Report Log Files, p.54

Changing the Reporting Period

You may wish to produce the report logs more frequently than each quarter. Log files covering more than a month of data can become too large. To produce server data at a specified interval, use either the lmnewlog or lmswitchr utilities. See the FLEXlm End Users Guide for complete information on lmnewlog and lmswitchr.
NOTE: If your report logs are scheduled on a monthly basis for each server, you must input multiple log files to the WRS license reporting agent, as it processes on a quarterly basis.

The lmnewlog and lmswitchr utilities both can be used to terminate the active report log and initiate a new log file; however, they differ in their execution. We recommend that you use lmnewlog to rotate report logs because it keeps the original filename as the basename and allows you to establish a logical sequence by renaming the archived files.

55

Wind River License Administrator Tools Guide, 1.1

lmnewlog

This command moves the contents of the current, active log file, for example, the contents of wrsReport.log, into a new archive, using the name you specified as a parameter, for example, wrsReport_01.log. On the next iteration, name the new archive wrsReport_02.log to indicate that it was the second batch of data saved. (See Naming Your Report Log Files, p.54.) The syntax for lmnewlog is: lmutil lmnewlog [-c license_file_list] vendor renamed_report_log For example: lmutil lmnewlog -c installDir/license/WRSLicense.lic wrsd wrsReport_jul_ 05.log The lmnewlog command copies the original report log to renamed_report_log and terminates it. The vendor daemon will continue to write any new logging information to the original report log.
lmswitchr

This command switches the report log file by closing the existing report log and creating a new, empty log file with a filename you specify. It leaves the predecessor file name and contents unchanged, while the vendor daemon writes information to the new empty log file. The syntax for lmnewlog is: lmutil lmswitchr [-c license_file_list] vendor new_report_log For example: lmutil lmswitchr -c installDir/license/WRSLicense.lic wrsd wrsReport_jul_ 05.log
NOTE: The new file name will not match the name specified in your options file. A restart of your license server will write logs to the name specified in the options file.

56

3 Configuring Usage Reporting Tools 3.4 WRS License Reporting Agent

Terminating Active Report Logs

It is recommended that, when it is time to process your report logs with the WRS license reporting agent, you terminate the active file before running the agent. Use lmnewlog or lmswitchr to do this; either one cleanly terminates the log file and avoids agent error messages resulting because you initiated reporting while data was still being written to the log file.
Archiving Report Logs

It is recommended that you archive your report logs after running the WRS license reporting agent. Older report logs can be helpful for tracking license usage over an extended period of time. For example, if a report log end date is later than the end date of the contractual quarter, the log may contain information needed for the following quarters license reporting. You can use the lmnewlog and lmswitchr utilities as archiving systems; see Changing the Reporting Period, p.55.

Sample Report Generation Use Cases

Appropriately named report logs can be passed to the WRS license reporting agent using any of the following methods:

By default, the reporting agent uses as input all .log files that reside in the current directory, as illustrated in Example 3-5. If your .log input files reside in a remote directory, use the -d option and supply the full directory path, as shown in Example 3-6. You can also create a file containing the full pathname to your .log input files. Then run the WRS license reporting agent with the -f option and the name of that file, as illustrated in Example 3-7. You may also explicitly specify log files as command line arguments, as shown in Example 3-8.

The -d and -f options can be used multiple times within a single command-line sequence. See Example 3-6.
Example 3-5 Log Files in the WRS License Reporting Agent Installation Directory

If all the report logs have been copied to the directory where the WRS license reporting agent was installed, enter the command below to run the agent and generate the usage reports and summary.

57

Wind River License Administrator Tools Guide, 1.1

On Solaris and Linux:


% wrsReport -c "My Company Name" -start 04/01/2003

On Windows:
C:\> perl wrsReport -c "My Company Name" -start 04/01/2003 Example 3-6 Log Files Specified Individually

If the log files are located on different servers accessible on the same network, enter the command below to access the files in the remote directories and run the reports. On Solaris and Linux:
% wrsReport -d /common/jupiter/jupiter1/flexlm/logs -d \ /common/saturn/saturn2/flexlm/logs -c "My Company Name" -start 04/01/2004

On Windows:
C:\> perl wrsReport -d C:\jupiter\jupiter1\flexlm\logs -d \ C:\saturn\saturn2\flexlm\logs -c "My Company Name" -start 04/01/2004 Example 3-7 Log Files Listed in a Text File

If you have a list of files that contain the full path to the report logs, enter the following command-line sequence: On Solaris and Linux:
% wrsReport -f /etc/flexlm/logs/filelist -c "My Company Name" -start \ 01/01/2005

On Windows:
C:\> perl wrsReport -f C:\etc\flexlm\logs\filelist -c "My Company Name" \ -start 01/01/2005

NOTE: If either the WRS license reporting agent or the windrreport generator

detects errors, the script exits with error messages on the console or shell window. For information on how the wrsReport processes errors, see 3.5 Error Processing, p.61. For a list of possible error messages, see B.3 WRS License Reporting Agent Error Messages, p.110.

58

3 Configuring Usage Reporting Tools 3.4 WRS License Reporting Agent

Example 3-8

Log Files Listed on the Command Line

If you wish to list the full paths to the report log files on the command line, enter the following command-line sequence: On Solaris and Linux:
% wrsReport -c "My Company Name" -start 01/01/2005 path_to_Reportlog1 path_to_Reportlog2

On Windows:
C:\> perl wrsReport -c "My Company Name" -start 01/01/2005 path_to_Reportlog1 path_to_Reportlog2

3.4.3 WRS License Reporting Agent Output


The wrsReport script produces the following output:

quarterly summary report aggregated quarterly usage report a ZIP file a dictionary file

Quarterly Summary Report

This report summarizes usage from the aggregated quarterly data for all license server log files input to the WRS license reporting agent. This report is included in the ZIP file submitted to Wind River at the end of each reporting quarter. See B.2.1 Quarterly Summary Report, p.106, for an example of this report. If your windrreport license has expired, your quarterly report summary will be empty of data.
Aggregated Quarterly Usage Reports

These reports contain the detailed usage information culled from input log files generated during the quarter. They are stored in the same directory where the script resides, and have the file name extension.txt. See B.2.2 Server Usage Report, p.108 for an example of this report.

59

Wind River License Administrator Tools Guide, 1.1

ZIP File

This .zip file includes the aggregated usage reports and quarterly summary, zipped together for transmission to Wind River (see 3.4.4 Where to Send Your Reports, p.60). The WRS license reporting agent automatically creates and names the .zip file according to the following form: companyName_report_startDate_endDate.zip
Dictionary File

The dictionary file decodes the encrypted usernames and hostnames that appear in the usage reports. This file is not sent to Wind River, but is for your own use. For more information and a sample, see 3.4.1 Required Files for WRS License Reporting Agent, p.51, and B.2.3 Dictionary File, p.110.
NOTE: The dictionary files are not included in the .zip file.

3.4.4 Where to Send Your Reports


wrsReport generates a ZIP file. Transmit the report to Wind River by one of the following:

E-mail the .zip file to reports@windriver.com Print out and fax the report to: (510) 217-3935. Mail the report on a disk with the .zip file to: Wind River License Compliance 500 Wind River Way Alameda, CA 94501

Once you have the submission process in place, you should find compliance and reporting easy and efficient. If you have questions, please contact Wind River Customer Support.

60

3 Configuring Usage Reporting Tools 3.5 Error Processing

3.5 Error Processing


Errors can occur when the WRS license reporting agent processes log files. Typically an error occurs if a log file is not terminated correctly. For example, if you copy the log file to a central location without using the lmnewlog (recommended) or lmswitchr1 tool, the file is effectively truncated. On Solaris and Linux hosts, error messages appear on the console. Windows hosts log them in a flexreport.log file in the directory from which you have run the WRS license reporting agent. For example, the following is a typical windrreport error message for a truncated log file:
14-Apr-2003 09:10:47 Error: Reportlog is truncated (-11) examples\report.log line 163 (id 48)(minor -5) (Vendor daemon crashed and restart) SNIFF_PRO 6A6ECED18956 14-Apr-2003 09:10:47* Successful recovery in examples\report.log at line 231. Continuing...

If a fatal error occurs in processing and creating a usage report, the windrreport generator reports it as follows:
Inconsistencies found in ./test/wrsdDelphi.log spanning 2003/06/03 11:07:09PM to 2003/06/03 11:07:09PM( 0 secs) Report logs from hosts "delphi.wrs.com" and "UNKN,UNKN,UNKN" cannot be combined. Please process them separately. Unable to generate report.

In turn, the WRS license reporting agent also reports an error and halts after displaying the following message:
############################# Error ################################# Cannot open report file anubis_wrsd_1.log: No such file or directory. The program will now exit. Please restart the program with valid parameters. ############################# Error #################################

Such fatal errors can be caused by a faulty or missing log file. To resolve the error, remove the faulty log file, or correct the input file list or directory path; then re-run the WRS license reporting agent. For a list and description of WRS license reporting agent error messages, see B.3 WRS License Reporting Agent Error Messages, p.110.

1. The FLEXlm lmswitchr tool switches out a report log that is currently being written to, and replaces it with a new log file. When lmswitchr is used, this switch can be done without stopping the report-generating daemon. The older log file can then be archived, deleted, or processed with the WRS license reporting agent.

61

Wind River License Administrator Tools Guide, 1.1

62

4
Permanently Activating Your Users
4.1 Introduction 63 4.2 Permanently Activating a User 63 4.3 Removing a Permanent Node-Locked License File 72

4.1 Introduction
This chapter explains how to permanently activate users of different license types, with appropriate recommendations. Also included is an explanation of client-side configuration with configuration scenarios and how to remove a permanent node-locked license file.

4.2 Permanently Activating a User


After installing Wind River products automatically by following installation instructions on the product CDs, users may receive a temporary license that allows them full use of the products for their development environment. At some point during the period of the temporary licensing, however, they must convert their temporary licenses to permanent activation. You can permanently activate users

63

Wind River License Administrator Tools Guide, 1.1

by following the instructions in this section. You may, however, wish to instruct your users to undertake this task themselves. You obtain your permanent license activation file from the Wind River Product Activation Web site (PAWS).

4.2.1 Permanently Activating NL Users


If your users require node-locked licenses, the default path for their license file is installDir/license/WRSLicense.lic. When you generate a permanent node-locked license file for each node-locked host, you must install the file in the same directory as the old temporary license on each host. This permanently activates a node-locked host.

4.2.2 Permanently Activating UU or FL Users


If your users have unique user (UU) or floating licenses (FLs), you have two methods of permanently activating their licenses, as follows:

Recommended Method to Permanently Activate UU and FL Users

After you generate the Product Activation (WRSLicense.lic) file from PAWS, you need to send the file to your end users who have already installed the product on their computers so that they can permanently activate their licenses. To do this, complete the following steps: 1. Read the instructions included with the Product Activation file, cutting and pasting as required to create the install.txt file for your users if product installation is required, or the license file, WRSLicense.lic, if product licensing is required. Name this new file WRSLicense.lic for product activation. Save the file and insert it into installDir/license for all users, or 4. Place this new file on a server for your users to access and download themselves onto their machines.

2. 3.

64

4 Permanently Activating Your Users 4.2 Permanently Activating a User

Alternative Method to Permanently Activate UU and FL Users

The second method of permanently activating licenses for users who have unique user or floating licenses is as follows: 1. 2. Instruct your end users to create an environment variable on their machines named WRSD_LICENSE_FILE. Set the value of this variable to the port@hostname indicated in the server line in the Product Activation file you downloaded from PAWS. For example,
SERVER jupiter 12345678 27000

where the server name is jupiter and the port is 27000. The value must take the form host@port, or in this case 27000@jupiter. 3. This permanently activates their licenses.

After setting up license management, if you invoke the product and fail to get a license, it may be caused by a pre-existing .flexlmrc file. See Failing to Get a License When Running the Application, p.83.

Setting WRSD_LICENSE_FILE Manually

To set WRSD_LICENSE_FILE manually, follow the instructions below for your operating system or use the wrenv utility, which is explained in Setting Environment Variables with wrenv, p.67.
Solaris and Linux

On Solaris and Linux hosts, you can set the WRSD_LICENSE_FILE environment variable manually or by using shell scripts that contain the command shown below. From the Command Line, set the variable to the location of the license management file. For example, using C shell:
% setenv WRSD_LICENSE_FILE /license/WRSLicense.lic

Windows 2000 Pro or XP Pro

You must have administrative privileges in order to set the environment variable. Set WRSD_LICENSE_FILE manually, as follows: 1. Select Start > Settings > Control Panel.

65

Wind River License Administrator Tools Guide, 1.1

2. 3. 4. 5. 6. 7.

Double-click the System icon. (You may need to switch to classic view to see the icon.) Click the Advanced tab. Click the Environment Variables button. Click New in the System Variables section. In the Variable Name text box, enter WRSD_LICENSE_FILE. In the Variable Value text box: For unique user and floating license clients, enter the license server machine port number and hostname or IP address; for example: 27000@saturn or 27000@90.0.0.1

8.

Click OK.

Windows NT 4.0

You must have administrative privileges in order to set the environment variable. Set WRSD_LICENSE_FILE manually, as follows: 1. 2. 3. 4. 5. Select Start > Settings > Control Panel. Double-click the System icon. Choose the Environment tab. In the Variable text box, enter WRSD_LICENSE_FILE. In the Value text box, for unique user and floating license clients, enter the license server machine port number and hostname or IP address. For example: 27000@saturn or 27000@90.0.0.1 6. Click OK.

66

4 Permanently Activating Your Users 4.2 Permanently Activating a User

Setting Environment Variables with wrenv

You can use the wrenv utility on any host platform to set environment variables, including WRSD_LICENSE_FILE. The utility resides at the root of installDir of your product installation tree. When invoked, it draws its information from the text file installDir/install.properties. Although you can reset the value of WRSD_LICENSE_FILE, node-locked licensees should not need to because the variables default value in install.properties is the most common setting. If you feel compelled to modify the settingfor example, you have changed the license file namefollow these steps: 1. 2. 3. 4. Open install.properties in a text editor. (If you use Notepad or WordPad, read Using Notepad or WordPad as Your Text Editor, p.80.) Go to the following line:
workbench22.eval.14=addpath WRSD_LICENSE_FILE $(WIND_LICENSE)$/WRSLicense.lic

Modify the current value (the default is shown above) to the desired value. For node-locked licenses, this should be the full path to the license file. Save the file and exit the editor.

When you invoke wrenv from its newly created shell, wrenv adds the new value in install.properties to any existing setting outside the shell. However, outside settings take precedence. On Solaris or Linux hosts, substitute wrenv.sh for wrenv in the commands shown below. Some tools invoke wrenv directly. The preferred method for invoking the utility is as follows:
% wrenv -p package [[program] args]

This command starts program with the necessary environment for the specified package. If no program is specified, a shell is invoked. Alternatively, the environment can be sourced into the current shell by the following command:
% eval 'wrenv -p package -o print_env -f shell'

The shell argument should be set to sh or csh, depending on the current shell. For more information about wrenv, refer to the Wind River Workbench Command-Line Users Guide.

67

Wind River License Administrator Tools Guide, 1.1

Resetting WRSD_LICENSE_FILE

If you reset the license management environment variable, WRSD_LICENSE_FILE, after running your product, you must delete a Solaris or Linux cache file or Windows registry keys before the new setting can take effect. This is because the values of the Windows registry keys and Solaris or Linux cache files have priority over the actual environment variable value. This is the case for all three license types: unique user, floating, and node-locked.
Windows

If you reset WRSD_LICENSE_FILE using the Windows control panels, you must use regedit to delete the registry version of it. This variable resides in:
HKEY_LOCAL_MACHINE\SOFTWARE\FLEXlm License Manager Solaris and Linux

If you reset the license server environment variable after using the product, you must also delete ~/.flexlmrc, which caches the old setting of WRSD_LICENSE_FILE. This cache file is recreated the next time you run the product.

4.2.3 Client-Side License Configuration Scenarios


The following configuration scenarios provide examples of how to configure your license management for the different types of licenses and different server options.
NOTE: For unusual configurations, contact Wind River Customer Support for assistance setting up your license server and the license management file.

Configuring Manually a Unique User or Floating Host

You can always manually set a clients WRSD_LICENSE_FILE environment variable to point to a particular license server and override the values contained in the machines WRSLicense.lic file. A client must be configured manually if you want it to point to more than one license server on the subnetwork, see Accessing Multiple License Servers, p.70.

68

4 Permanently Activating Your Users 4.2 Permanently Activating a User

To manually set WRSD_LICENSE_FILE, you need to know the license server machine port (port) and the name or IP address of the license server machine (server). The environment variable value takes the form: port@server The default port is 27000. For example, for license server machine saturn with an IP address 90.0.0.1, the setting for WRSD_LICENSE_FILE would be: 27000@saturn or 27000@90.0.0.1 Except for the value of WRSD_LICENSE_FILE, the process of actually setting the variable manually is the same regardless of your license type, whether it is node-locked, floating, or unique user. Follow the instructions below for your operating system or use the wrenv utility, which is explained in Setting Environment Variables with wrenv, p.67.
4

Solaris and Linux

On Solaris and Linux hosts, you can set the WRSD_LICENSE_FILE environment variable manually or by using the wrenv utility provided during installation.
Setting WRSD_LICENSE_FILE from the Command Line

The variable must be set to the port number (the default is 27000) and server name (such as, saturn) or IP address of the server. For example, for the C shell:
% setenv WRSD_LICENSE_FILE 27000@saturn

or
% setenv WRSD_LICENSE_FILE 27000@90.0.0.1

Windows 2000 Pro or XP Pro

Set WRSD_LICENSE_FILE manually, as follows: You must have administrative privileges in order to set the environment variable. 1. 2. 3. Select Start > Settings > Control Panel. Double-click the System icon (You may need to switch to classic view to see the icon). Click the Advanced tab.

69

Wind River License Administrator Tools Guide, 1.1

4. 5. 6. 7.

Click the Environment Variables button. Click New in the System Variables section. In the Variable Name text box, enter WRSD_LICENSE_FILE. In the Variable Value text box, for unique user and floating license clients, enter the license server machine port number and hostname or IP address. For example: 27000@saturn or 27000@90.0.0.1

8.

Click OK.

Windows NT 4.0

Set WRSD_LICENSE_FILE manually, as follows: You must have administrative privileges in order to set the environment variable. 1. 2. 3. 4. 5. Select Start > Settings > Control Panel. Double-click the System icon. Choose the Environment tab In the Variable text box, enter WRSD_LICENSE_FILE. In the Value text box, for unique user and floating license clients, enter the license server machine port number and hostname or IP address. For example: 27000@saturn or 27000@90.0.0.1 6. Click OK.

Accessing Multiple License Servers

From a client, unique user and floating licensees can use the WRSD_LICENSE_FILE variable to access more than one license server machine. You might want to do this in order to draw licenses from more than one server or to protect users from license server machine crashes by providing system redundancy. To access more than one server, edit WRSD_LICENSE_FILE and append new value for additional servers, as explained below. Put the license server machine you want used first in the first position because wrsd always seeks a license based on the order in which the servers are listed. If no license is available from the first server, wrsd seeks one from the second server, and so on.

70

4 Permanently Activating Your Users 4.2 Permanently Activating a User

Solaris and Linux

In Solaris and Linux environments, use a colon (:) to separate license server machines in your environment variable value. To access multiple servers from the C shell, you can reference the current value and append a new value, as follows:
% setenv WRSD_LICENSE_FILE ${WRSD_LICENSE_FILE}:27000@mercury

Or, you can specify the current value and append one or more values:
% setenv WRSD_LICENSE_FILE 27000@mercury:27000@pluto:27000@90.11.0.1

Windows

In a Windows environment, use regedit to access the registry where the registry key version of WRSD_LICENSE_FILE resides. 1. Go to:
HKEY_LOCAL_MACHINE\SOFTWARE\FLEXlm License Manager

The true environment variable is found under the Environment tab of the System folder; however, Windows systems read the registry value first, so modifying it is sufficient to reset the operating environment. 2. Double-click WRSD_LICENSE_FILE and add the new server port number and hostname or IP address to the original value in the registry key. In Windows, separate the servers with a semi-colon (;), for example: 27000@mercury;27000@90.11.0.1

Resetting License Management on the Client

If you reset the license management environment variable, WRSD_LICENSE_FILE, after running your product, you must delete a Solaris or Linux cache file or change the Windows registry keys before the new setting can take effect. The reason for this is that the values of the Windows registry keys and the Solaris or Linux cache files have priority over the actual environment variable value. This is the case for all three license types: unique user, floating, and node-locked.
Solaris and Linux

If you reset the license server environment variable after using the product, you must also delete ~/.flexlmrc, which caches the old setting of WRSD_LICENSE_FILE. This cache file is recreated the next time you run the product.

71

Wind River License Administrator Tools Guide, 1.1

Windows

If you reset WRSD_LICENSE_FILE using the Windows control panels, you must use regedit to delete the registry version of it. This variable resides in:
HKEY_LOCAL_MACHINE\SOFTWARE\FLEXlm License Manager

4.3 Removing a Permanent Node-Locked License File


If you are uninstalling the product from the node-locked host machine, the uninstall process does not remove license management directories and files. To manually uninstall license management tools from a node-locked host, simply remove the license file. You can also remove all the license management-related directories and files, recursively, in installDir: install.txt license setup.log uninstall host log.txt setup licadmintools-1.1

If you are using a merged license file that resides in the installation tree, removing it affects all products whose licenses are under the files control. It is recommended you back up the file before removal, then delete any merged features no longer in use, and move the modified file to the new host machine.

72

5
Licensing Tips and Troubleshooting
5.1 Introduction 73 5.2 Converting Your License Type 74 5.3 Maintaining Licenses 74 5.4 Troubleshooting 79

5.1 Introduction
This chapter includes information that you may need to know in order to permanently activate your product, including how to complete the following:

converting license types maintaining licenses, including: renewing a license transferring a license file troubleshooting

73

Wind River License Administrator Tools Guide, 1.1

5.2 Converting Your License Type


Customers may purchase any of three license types for most Wind River products:

unique user floating node-locked

If, after purchasing your license, you find the need to convert one license type to another, please contact your Wind River Sales Representative. After review, Wind River provides a new WRSLicense.lic file by e-mail so you can complete the conversion and create and install a new Product Activation file. If you intend to use the same license server machine after conversion, you will receive a replacement license file that supersedes the old file (see Superseding License Files, p.78). If you intend to use a new license server machine, follow the instructions in Transferring a License File Between Hosts, p.76. You must also delete the obsolete license file; see Replacing and Deleting a License File, p.78, and you must reconfigure any client machines associated with the license server; see 4.2.2 Permanently Activating UU or FL Users, p.64. !
CAUTION: If you purchased a subscription license with your product and you do not delete the old license file per your agreement, it will expire. The product software will cease to function, and license requests from client machines pointing to the old license server machine will generate an error message.

5.3 Maintaining Licenses


This section discusses license management activities and situations that might arise after you are already up and running, for all license typesunique user, floating, or node-locked:

5.3.1 Renewing Your License, p.75 5.3.2 Transferring a License File, p.76

5.4 Troubleshooting, p.79, addresses questions and problems that might arise both during installation and after.

74

5 Licensing Tips and Troubleshooting 5.3 Maintaining Licenses

5.3.1 Renewing Your License


If you purchased a subscription license (ELM), use of your Wind River product is authorized for a specific period of time. When that time expires, you can forego further use of the product or you can renew your license.
NOTE: All licensed products with an expiration date embedded in the license file cease to function after the end date has passed. 5

If you elect to renew your subscription agreement, the agreement does need to be amended, but you do not need to draw up an entirely new one. Contact your sales representative, who will take you through the renewal process. After processing your order, Wind River updates your customer profile to correspond to the new subscription period. Claim your new Product Activation file (WRSLicense.lic) using the Wind River Product Activation Web site on the day after your existing file expires. For UU or FL installations, once you have placed the Product Activation file in its proper location, installDir/license, name the file WRSLicense.lic. Follow the directions provided in the comment sections of the license file. If you install the new WRSLicense.lic file on a different server, the old license file on the former machine will expire. The product software will cease to function, and license requests from client machines pointing to the old license server will generate error messages. You must also reconfigure hosts to point to the new server; see 4.2.2 Permanently Activating UU or FL Users, p.64.

75

Wind River License Administrator Tools Guide, 1.1

5.3.2 Transferring a License File


License files of any type (unique user, floating, or node-locked) are assigned specific host attributes, such as a Solaris or Linux host ID, a Windows MAC address, or a disk serial number. You cannot modify that kind of information in a license file. Doing so renders the file inoperable. Therefore, if one of these host attributes needs to change, you must obtain a new license file with the updated information. For example, if your disk drive had to be replaced and your license file specifies the disk serial number that is no longer valid, you must request a new license file.
NOTE: If your license file has become corrupted or been lost, you do not need a new license file; a copy of the old license file should work (assuming the hostname and host ID have not changed). As long as you have an Internet connection, you can make that request using the Product Activation Web site:

http://www.windriver.com Click the Licensing tab. If you require a new license file, Wind River will issue it as long as you have completed a License Management Transfer Certificate Agreement. This section discusses the following:

How to move a license file from one host to another ( Transferring a License File Between Hosts, p.76). How to obtain a license file that supersedes another on an existing host ( Superseding License Files, p.78). How to delete a license file ( Replacing and Deleting a License File, p.78).

Transferring a License File Between Hosts

If you have to change host machines, you must obtain a new Product Activation file from Wind River because some attributes of the existing file must change. For example, your original license server is on host jupiter, but, in a mishap, jupiter s hard drive irreparably crashes. You must reconstruct services on a new host, saturn. The hostname and host ID, at least, must change in WRSLicense.lic.

76

5 Licensing Tips and Troubleshooting 5.3 Maintaining Licenses

To obtain a new Product Activation file, request a License Management Transfer Certificate Agreement by sending an e-mail to or telephoning Wind River Customer Support: license@windriver.com If you are in North America, Canada or Asia. license-ec@windriver.com If you are in Europe. license-jp@windriver.com If you are in Japan. Complete, sign, and fax the agreement to Wind River, along with copies of the license file (if you can obtain them). Your signature on the agreement means you will delete the old license file from the old host (or you will effect the equivalent, for example, the original hard drive has become inoperable). Upon review of the agreement, Wind River releases any licenses allocated to that host, and you can run Setup on a new host to make new allocations. To delete the old files, refer to Replacing and Deleting a License File, p.78. If you replace WRSLicense.lic on a license server and either the hostname or license server port number has changed, you must also reconfigure any clients pointing to that server. The following license transfer exceptions are allowed:

Licenses can be transferred within a quarter because of termination of employment or replacement; that is, Joe left the company and was replaced by Tom. Joes license can be transferred to Tom. Licenses can be transferred within a quarter because of login name changes; for example, jill_smith marries and becomes jill_jones.

You must notify Wind River in writing or through the Product Activation Web site (PAWS) of these user exception cases and any others that occur during a reporting quarter. Notification allows Wind River to exclude such users from the total development count at the end of the quarterly reporting period. When you report user exception cases, send Wind River the encrypted names of the users requiring special handling. These encrypted names come in the quarterly usage reports you receive from Wind River. Wind River sees only this form of the user name in the reported data.

77

Wind River License Administrator Tools Guide, 1.1

Superseding License Files

There are numerous circumstances that would require a new license file to be issued for an existing host, for example, if you change product functionality. In such a case, you must obtain a new license file by contacting Wind River Customer Support and completing a License Management Transfer Certificate Agreement. The new WRSLicense.lic controls all the entitlements of your new agreement and includes a SUPERSEDE option that nullifies the predecessor file. For example, the SUPERSEDE= clause below, in conjunction with the ISSUED= statement, invalidates other license files issued prior to May 24, 2004 and containing the feature WORKBENCH_SUBSCRIPTION_Cfg1 on host jupiter.
SERVER jupiter 12345678 27000 VENDOR wrsd PACKAGE WORKBENCH_SUBSCRIPTION_Cfg1 wrsd 2.0 C7F901C9DB56 COMPONENTS="WR_DEBUGGER:2.0 WR_TOS_LX_2_4:2.0 \ WR_TS_MPC82XX:2.0 WR_WORKBENCH:2.0" OPTIONS=SUITE \ SIGN=13B8CA28C770 INCREMENT WORKBENCH_SUBSCRIPTION_Cfg1 wrsd 2.0 30-jun-2004 1 \ AB453A501AD8 VENDOR_STRING="<ln>221073</ln> \ <flt>2</flt><ps>1157-1</ps>" sort=50 BORROW=72 \ SUPERSEDE=WORKBENCH_SUBSCRIPTION_Cfg1 DUP_GROUP=UH \ SUITE_DUP_GROUP=UH ISSUED=24-May-2004 SIGN=DF0B491B60DAC

Replacing and Deleting a License File

If you received a new WRSLicense.lic file using the Wind River Product Activation Web site (PAWS), or from Wind River Customer Support, please copy the file to the recommended installDir/license directory. Note that:

An existing install.txt is in the top level of installDir, and must reside there for installation to properly occur. The existing license file, WRSLicense.lic, is in installDir/license. The new license file must be named WRSLicense.lic.

If you requested a new license file using a Web browser, e-mail, phone, or fax, you must manually delete the existing file before installing the new one. !
CAUTION: If you are using a merged license file, remember not to delete the old file until you have updated the new one.

78

5 Licensing Tips and Troubleshooting 5.4 Troubleshooting

5.4 Troubleshooting
This section is designed to help you answer some of the more common questions asked regarding configuration of licenses for Wind River products. The following topics are discussed:
Basic Installation

Obtaining a License File from the Product Activation Web site, p.80

License Files

Using Notepad or WordPad as Your Text Editor, p.80 Finding Your Customer License Number and Token, p.80 Obtaining New Product Activation Files, p.81 Reinstalling a License File, p.81 Re-reading Files, p.81 Moving the License File to a Non-Standard Location, p.82

Licenses

Failing to Get a License When Running the Application, p.83 5.4.4 Borrowing A License (UU and FL), p.85 Reconfiguring License Seats (UU and FL), p.87

License Servers (UU and FL)

If a Client Fails to Retrieve a LIcense, p.88 If Your License Server Will Not Start, p.89 Serving Multiple Wind River Products from a Single Server, p.89 Serving Wind River and Other Products from a Single Server, p.90 Changing the License Server Port Number Manually, p.90 Invoking License Management Utilities, p.91 Terminating an Unresolved Checkout, p.92

Debugging and Errors

Using the setup.log and log.txt Files, p.92 Error Reporting, p.93

79

Wind River License Administrator Tools Guide, 1.1

Using a Debug Log (UU and FL), p.93 Getting Help with License Management, p.93

5.4.1 Basic Installation


Obtaining a License File from the Product Activation Web site

Go to the Product Activation Web site: http://www.windriver.com After logging in, click on the tab Licensing to access the Product Activation page. Follow the directions to configure and request your license file. You will need your customer license number, license administrator token, host names, and host IDs, which are on your Essentials Sheet that shipped with your product.

5.4.2 License Files


Using Notepad or WordPad as Your Text Editor

If you use Microsoft Notepad or WordPad to edit a license file or an options file, you must make sure the filename preserves the .lic, .txt, or .opt extension. Do this when saving the document by specifying install only when saving install.txt, or putting double quotes around the filename, including the extensionfor example, WRSLicense.licand saving it as a text document.

Finding Your Customer License Number and Token

To find your customer license number and license administrator token, check your License Administrator Essentials sheet. Or, you can call Wind River Customer Support.

80

5 Licensing Tips and Troubleshooting 5.4 Troubleshooting

Obtaining New Product Activation Files

To obtain a new Product Activation file, use a Web browser to access the Wind River Product Activation Web site (PAWS) to download the file. See Obtaining a License File from the Product Activation Web site, p.80
5

Reinstalling a License File

If your hard drive crashes or for some other reason you must re-install your Wind River product, you must also re-install your license file. You may also need a new node-locked license if you used DiskID to generate the node-locked license.

Re-reading Files

If you modify either the license file or the options file (for unique user licensees), you must force the license server to re-read the modified file for the changes to take effect.
From the Command Line

The quickest way to invoke lmreread is from a command line (Linux, Solaris, and Windows), as follows: 1. 2. Change directories to installDir/licadmintools-1.1/license/hostType/bin. Type:
% lmutil lmreread -c pathToLicenseFile

The -c argument tells lmreread that the input, pathToLicenseFile, is the full path to the license file.
From Windows

1. 2. 3. 4.

Open the LMTOOLS application. (See Invoking License Management Utilities, p.91.) Go to the Start/Stop/Reread tab. Make sure the appropriate license manager is highlighted. Select ReRead License File.

81

Wind River License Administrator Tools Guide, 1.1

Moving the License File to a Non-Standard Location NOTE: Unique user licensees cannot place the license file in a non-standard location because of reporting requirements.

Typically, you will not need to move the license file to a location other than its default location; however, if you must move the file, you must also modify the license file manually by specifying the locations of the vendor daemon, wrsd, and the options file, if your machine has one, as follows: 1. Edit the license management file, WRSLicense.lic. The VENDOR line in the file describes the vendor daemon, wrsd. In the third field on the VENDOR line, add the absolute path to the vendor daemon. In the fourth field specify the path to the options file. For example:
VENDOR wrsd /installDir/license/hostType/bin/wrsd \ [options=]/installDir/licadmintools-1.1/license/hostType/bin/wrsd.opt

You must specify the path to the options file using options= if the path to the vendor daemon is not specified. This information prompts wrsd to look for the options file in the specified location. 2. Save the license file. When the next request for a license comes in to this server, wrsd will seek direction from the options file specified.

Setting Environment Variables with wrenv for an End User

You can use the wrenv utility on any host that has the Wind River Workbench installed to set environment variables, including WRSD_LICENSE_FILE. The utility resides in the installDir. When invoked, it draws its information from the text file installDir/install.properties. Although you can reset the value of WRSD_LICENSE_FILE, node-locked licensees should not need to because the default value in install.properties is the most common setting. If you feel compelled to modify the settingfor example, you have changed the license files namefollow these steps: 1. 2. Open install.properties in a text editor. (If you use Notepad or WordPad, read Using Notepad or WordPad as Your Text Editor, p.80.) Go to the following line:
workbench22.eval.14=addpath WRSD_LICENSE_FILE $(WIND_LICENSE)$/WRSLicense.lic

82

5 Licensing Tips and Troubleshooting 5.4 Troubleshooting

3. 4.

Modify the current value (the default is shown above) to the desired value. For node-locked licenses, this should be the full path to the license file. Save the file and exit the editor.

When you invoke wrenv from its newly created shell, wrenv adds the new value in install.properties to any existing setting outside the shell. However, outside settings take precedence. On Solaris or Linux hosts, substitute wrenv.sh for wrenv in the commands below. Some tools invoke wrenv directly. The preferred method for invoking the utility is as follows:
% wrenv -p package [[program] args]

This command starts program with the necessary environment for the specified package. If no program is specified, a shell is invoked. Alternatively, the environment can be sourced into the current shell by the following command:
% eval 'wrenv -p package -o print_env -f shell'

The shell argument should be set to sh or csh, depending on the current shell. 5. For more information about wrenv, refer to the Wind River Workbench Command-Line Users Guide.

5.4.3 Obtaining Licenses


Failing to Get a License When Running the Application

If you try to run your Wind River product and encounter a License Not Found error message, confirm your network connection and make sure the server is not down (see If a Client Fails to Retrieve a LIcense, p.88). Also, consider the following:
Interfering .flexlmrc

If you think license management has been set up correctly, failure might result from the existence of a .flexlmrc file in your home directory. All FLEXlm-managed products either create or update this file with license server information. For a number of reasons, pre-existing data might prevent your product from finding the correct license server. To remedy this problem, find and remove the .flexlmrc file, then invoke your product again. Running the application will create a new .flexlmrc file and will not affect the operation of other FLEXlm-managed products.

83

Wind River License Administrator Tools Guide, 1.1

Unrecognized Hostname (Solaris and Linux)

Your Solaris or Linux client may not recognize the license server machine name, which, by default, is the information provided by the client-side license file, WRSLicense.lic, or the WRSD_LICENSE_FILE environment variable. First, ping the server using the machine name:
% ping server

If you get an unknown hostname error, the client does not know the IP address for the license server machine. Correct this by adding the IP address to the etc/hosts file. Or contact your system administrator.
Incorrect Path for Environment VariableNode-Locked Client

The environment variable WRSD_LICENSE_FILE may not be pointing to the node-locked license file. See 2.3.3 Configuring a Node-Locked Client, p.18.

Not Unique Hostname (Linux)

All Linux machines come with the same default hostname, localhost. Your system administrator should assign all Linux machines on your network with a unique hostname, otherwise there is the risk of confusing the license manager with requests from multiple clients with the same name. Only the first license request will be honored. To ascertain the hostname of your Linux machine and change it, follow these steps: 1. 2. 3. 4. Go to Hat > SystemSettings > Network and enter the root password. If you do not know the password, talk to a system administrator. In the DNS tab, if localhost.localdomain is localhost, replace it with a new hostname. Then, as root, add the name to the list of hostnames associated with 127.0.0.1 in your /etc/hosts file. Run /etc/init.d/network from a command line. Then restart or reboot your machine.

84

5 Licensing Tips and Troubleshooting 5.4 Troubleshooting

5.4.4 Borrowing A License (UU and FL)


The borrow feature allows a user the opportunity to continue to use a floating or unique user license for a predefined period of time after disconnecting from the network. For example, suppose an engineer normally uses a single unique user license, and uses license managed tools from a lab workstation and from his laptop. Suppose this engineer needs to travel to another city, and wants to continue to use the license managed tools while in-flight, and after he arrives at his destination. The engineer can borrow a unique user license for use during his travel. The borrow feature essentially creates a temporary node-locked license for the laptop for a predefined period of time.
NOTE: A borrowed license remains checked out for the entire borrowing period; it

cannot be returned early. You cannot renew the borrowing period until it has expired.

Configuring a Client to Borrow a License

Your developers can configure borrowing on their host machines in any of the following ways:
Configure Borrowing Using lmutils NOTE: The license management utilities are not part of a default client installation. You must make the license management utilities (lmutil or lmtools.exe) accessible to the borrowers for them to use this method.

To borrow a license, follow these command-line steps. Windows users may find it easier to use the GUI-based LMTOOLS utility; see Invoking License Management Utilities, p.91: 1. Connect the machine to the network where it has access to the running license server. Be sure this license server has enough floating or unique user licenses to allocate. From a command prompt or shell, change directories to the location of the utility lmutil and enter the following command:
% lmutil lmborrow wrsd endDate [time]

2.

85

Wind River License Administrator Tools Guide, 1.1

endDate The date of the license to be returned (in dd-mmm-yyyy format). Wind River limits borrowing to 3-day periods by default; so endDate is 3 days from the current date: time An optional argument to set the hour and minute by which the license must be returned (in hh:mm format for a 24-hour clock). For example:
% lmutil lmborrow wrsd 15-mar-2004 13:30

3.

While the machine is still connected to the network, launch the license-managed application, for example Wind River Workbench.

At this point, the borrow is complete, and the license will remain checked out and available for use on this machine only until the borrow period expires.
Borrow a License Using An Environment Variable

If you do not to provide the lmutil utility to your developers, they can configure borrowing by setting the environment variable LM_BORROW. To borrow a license for disconnected use: 1. Connect the machine to the network where it has access to the running license server. Be sure this license server has enough floating or unique user licenses to allocate. On the client machine, set an environment variable named LM_BORROW with a value of the following form:
LM_BORROW=currentDate:wrsd:endDate:time

2.

for example:
LM_BORROW=15-aug-2006:wrsd:20-aug-2006:15:00

Note that time is an optional parameter. If you do not specify a time, the borrow period expires at 23:59 hours on the end date.. Consult your operating system or shell documentation for instructions to set an environment variable. 3. While the machine is still connected to the network, launch the license-managed application, for example Wind River Workbench.

At this point, the borrow is complete, and the license will remain checked out and available for use on this machine only until the borrow period expires.

86

5 Licensing Tips and Troubleshooting 5.4 Troubleshooting

Restricting Use of the Borrow Feature

You can also restrict which users can take advantage of borrowing through the use of the BORROW action keyword; see the FLEXlm End Users Guide. You may also borrow a license in a Windows environment by using the GUI-based LMTOOLS utility; see Invoking License Management Utilities, p.91.
5 Reconfiguring License Seats (UU and FL)

After you have completed your initial license server configuration for unique user or floating seats, including allocation of seats to one or more servers, there are limits on what kinds of modifications you can make to that configuration without the assistance of Wind River Customer Support. If, during the installation of a license server, you allocate fewer than all the available seats, you can increase the number of seats allocated without Wind Rivers help, by using your web browser to access the Wind River Product Activation Web site: http://www.windriver.com You must first login, and then click the tab Licensing to access the Product Activation page. Unique User customers can use PAWS to configure and retrieve overdraft license seats for Wind River products. Follow the instructions on PAWS or contact license@windriver.com for additional help. For the following actions, however, you must contact Wind River Customer Support:

To obtain more seats than are authorized by your unique user license agreement. To decrease the number of unique user or floating seats allocated to a specified license server. To add redundant license servers to your network.

Remember to reconfigure your clients, if necessary; see the instructions in Configuring Manually a Unique User or Floating Host, p.68, and Resetting License Management on the Client, p.71.

87

Wind River License Administrator Tools Guide, 1.1

5.4.5 License Servers (UU and FL)


This section gives instructions on the following:

What to do if a client fails to access a server What to do if your license server will not start How to set up multiple Wind River products from a single server How to set up a single server for Wind River and other products How to work with RIT add-on products How to manually change the license server port How to invoke license management utilities How to terminate an unresolved checkout

If a Client Fails to Retrieve a LIcense

1.

Check Network Connectivity to the License Server a. Test the client machines network connectivity with the license server by pinging the license server machine. If ping fails, check the network connection on the client machine. b. If ping succeeds, confirm that an appropriate WRSLicense.lic file has been installed in installDir/license on the client or that the clients license management environment variable, WRSD_LICENSE_FILE, has been properly set to point to the intended license server.

2.

Check Network Latency (Windows Hosts) The default client time-out for license requests is 100 milliseconds. High network latency can cause license requests to time-out. a. b. If ping succeeds, and the license file identifies the proper license server and port number, test the network latency by running a traceroute. Use the command tracert from a Windows command shell. For example:
C:\> tracert mylicenseServer.company.com

If the traceroute results indicate a latency that exceeds 100000 microseconds (and you cant do anything to improve network performance), you can override the default license request time-out by setting the environment variable FLEXLM_TIMEOUT. Set the value of this variable to a number (in microseconds) high enough to prevent the client from timing out.

88

5 Licensing Tips and Troubleshooting 5.4 Troubleshooting

For example, if traceroute results suggest the round-trip to the license server takes 450 milliseconds, consider setting the value of FLEXLM_TIMEOUT to 1000000 microseconds (1 second). Consult your operating system or shell documentation for instructions to set an environment variable. 3. Ensure that the License Administrator Tools Are Running on the Server. Make sure lmgrd and wrsd are running on a license server. On a Windows server, invoke the task manager and in the Processes tab, look for the lmgrd and wrsd executables. On Solaris and Linux, from a command line, type:
% ps -ef |grep [wrsd|lmgrd]

4.

If your purchase includes any unique user licenses, ensure that the report logging is turned on. Report logging is required for all unique user customers. If your server is configured to allocate any unique user licenses, and you do not turn on report logging, your license server will not allocate any licenses. For more information about report logging, see 3. Configuring Usage Reporting Tools.

If Your License Server Will Not Start

Check to see if there is an old version of the wrsd vendor daemon running on your server machine. You must kill that process first, before you attempt to start the new lmgrd. For more information about stopping either lmgrd or wrsd, see 2.5 Starting and Stopping a License Server, p.27.

Serving Multiple Wind River Products from a Single Server Using Merged Licenses

If you are using one machine as a license server for multiple products, you either must merge license files or use LMTOOLS or the lmgrd command to specify more than one license file. For more information about merging files and alternative ways to handle multiple products on a single server, see:

2.4.4 Using a Single License Server for Multiple Wind River Products, p.23 Example 3-2 and Example 3-3 in 3.3 Options File Examples, p.41

89

Wind River License Administrator Tools Guide, 1.1

Limitations of Merged Licenses

When you merge two Wind River licenses from different purchases that both allocate seats for the same product, the merged license will only allocate licenses for the package or feature with the later expiration date. This may be fewer than licenses you are actually entitled to by both licenses. If you must merge two or more licenses of the same product that have different expiration dates, contact Wind River for a new merged license file.

Serving Wind River and Other Products from a Single Server

If you are working with merged licenses for multiple vendor daemons, there are not the same concerns about overlapping feature names (that is, product names) as when merging licenses for multiple Wind River products. For more information about handling products from multiple vendors, see the FLEXlm End Users Guide.

Changing the License Server Port Number Manually

By default, the lmgrd daemon listens for license requests on port number 27000. If necessary, you can assign a different port number; however, you must specify the port number in two locations: in the license file on the license server and on the client side, in the WRSD_LICENSE_FILE environment variable. On the files SERVER line, the text provides the name of the license server machine, the host ID, and the port number, for example:
SERVER jupiter 942e9876 27000

Change the port number to any number greater than 1024 that is not being used by other applications.

90

5 Licensing Tips and Troubleshooting 5.4 Troubleshooting

Invoking License Management Utilities

The lmutil utility for working with license servers enables you to implement the following license management maintenance activities, which are documented in this manual:

Starting and stopping the license server (2.5 Starting and Stopping a License Server, p.27). Re-reading the license file or options file ( Re-reading Files, p.81). Borrowing (5.4.4 Borrowing A License (UU and FL), p.85). Finding the version number of the license management software (confirming your FLEXlm version number). Killing an unresolved checkout ( Terminating an Unresolved Checkout, p.92). Specifying to wrsd a search order among license files (Example 3-2 in 2.4.4 Using a Single License Server for Multiple Wind River Products, p.23).

lmutil can also be used for other license management tasks, including:

diagnosing license server problems reconfiguring your server monitoring usage

For more information about these and other maintenance activities, refer to the FLEXlm End Users Guide. To invoke the lmutil, follow the instructions below.
Solaris and Linux

Open the license management utilities from the command prompt, type:
% lmutil task [options]

The task parameter is one of the numerous functional options explained in the FLEXlm End Users Guide, including the activities bulleted above. You can also get explanations for command-line options associated with the various maintenance activities using the -help argument in the command line, for example:
% lmutil -help

91

Wind River License Administrator Tools Guide, 1.1

Windows

On Windows, you can run lmutil from the command line, as shown above, or use the graphical interface version named lmtools. Open lmtools from a command prompt or from Windows Explorer at:
C:\> installDir\licadmintools-1.1\license\x86-win32\bin\lmtools.exe

Terminating an Unresolved Checkout

If the license server indicates there is a license checked out to a user who has supposedly checked it in (as shown by the lmstat command), you can use the lmremove command to reclaim the license. Follow these steps from the command line: 1. 2. Change directories to installDir/licadmintools-1.1/license/hostType/bin. Type:
% lmutil lmremove [-c license_file_list] feature user user_host display

or
% lmutil lmremove [-c license_file_list] -h feature server_host port handle

You can ascertain values for feature, user_host, display, server_host, port, and handle by running the following command first:
% lmutil lmstat -a

5.4.6 Debugging and Errors


This section provides useful information about debugging and errors, including error reporting and where to get help with license management.

Using the setup.log and log.txt Files

After you tell the Setup program where to carry out installation (in the Specify Installation Directory screen), Setup creates two files in installDir: setup.log and log.txt. The setup.log file records what has been installed on the host machine, from file instigation to completion. It also records uninstallation events. The contents of this file may be helpful in troubleshooting problems encountered during installation.

92

5 Licensing Tips and Troubleshooting 5.4 Troubleshooting

The log.txt file collects error information. You cannot read the file; however, it may be useful to Wind River Customer Support in troubleshooting an installation problem.

Error Reporting

If you encounter a license management error message, note the content and error number and contact Wind River Customer Support.

Using a Debug Log (UU and FL)

To troubleshoot license management problems with a license server, you will want to create a debug log where your license manager can log events. To invoke the license management daemon, lmgrd, to generate a debug log file, enter the following in the command line:
% lmgrd -c pathToLicenseFile -l pathToDebugLogFile

For example:
% lmgrd -c c:\workbench2.0\license\WRSLicense.lic -l c:\licenseManagement\debugLogs\lmgrd.log

Windows users can also invoke debugging using the LMTOOLS utility; see Invoking License Management Utilities, p.91. This command places data for all vendor daemons into the same log file. If you want to send data for a specific vendor daemon to a different log file, such as for Wind Rivers daemon, wrsd, unique user licensees can set the DEBUGLOG action keyword in the options file; see Example 3-4 in 3.3 Options File Examples, p.41. Data accumulates very quickly and, depending on the number of users, can consume large amounts of disk space. You can turn off the debugging feature using the options file; see Example 3-4.

Getting Help with License Management

Wind Rivers Product Activation Web site (PAWS) is usually your single starting point for license management inquiries. http://www.windriver.com Log in and click on the Licensing tab to access the Product Activation Web page.

93

Wind River License Administrator Tools Guide, 1.1

For additional license management information, you may also want to review the FLEXlm End Users Guide, which can be found online at: http://www.macrovision.com/services/support

94

A
Option File Action Keywords
A.1 Introduction 95 A.2 Options File Syntax 97 A.3 Action Keywords 99

A.1 Introduction
Table A-1 briefly describes the action keywords available for use in configuring your Wind River license manager. This appendix also provides an overview of syntax for the options file (A.2 Options File Syntax, p.97), as well as details about each of the options listed in Table A-1 (A.3 Action Keywords, p.99).

95

Wind River License Administrator Tools Guide, 1.1

For more information on the role of the options file in license management, see 2.1 Overview, p.10. For a discussion of the role of the options file and for some options file examples, see 3.2 Working with the Options File, p.38, and 3.3 Options File Examples, p.41, respectively.
Table A-1 Action Keywords

Keyword

Description

DEBUGLOG EXCLUDE EXCLUDEALL GROUP HOST_GROUP INCLUDE INCLUDEALL NOLOG REPORTLOG

Write debug log information for a specified vendor daemon to a specified file, in the case of Wind River, wrsd. Deny a user access to a feature. Deny a user access to all features served by wrsd. Define a group of users for use with any options. Define a group of hosts for use with any options. Allow a user access to a feature. Allow a user access to all features served by wrsd. Turn off logging of certain items in the debug log file. Specify that a report log file be written, suitable for use by the reporting agent.

Additional information about options file actions can be found in the FLEXlm End Users Guide, available online at: http://www.macrovision.com/services/support

96

A Option File Action Keywords A.2 Options File Syntax

A.2 Options File Syntax


The basic syntax of the options file is as follows. Each syntax field is discussed in this section:
action feature[:keyword=value] type user

For example:
INCLUDE WORKBENCH_UU_SUBSCRIPTION_cfg1 USER johnf

or
# Exclude these New York City developers. EXCLUDE WR_SYSTEM_VIEWER:SIGN=141556876DE GROUP USER_NYC

Each line of the file controls one option.


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 usernames 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 or INCREMENT lines for a single feature. The following syntax is used:
license_server_machine feature:keyword=value

For example:
WR_WORKBENCH:VERSION=2.0

or
WR_DEBUGGER:SIGN=15308987AC

97

Wind River License Administrator Tools Guide, 1.1

The keywords in Table A-2 are a subset of those available for FLEXlm. They are used as feature name modifiers to denote a specific group of licenses:
Table A-2 Feature Name Modifiers

Keyword

Definition

EXPDATE= HOSTID= KEY= SIGN= VENDOR_STRING= VERSION=

The expiration date of your license agreement. The unique host ID of your license server. The old-style checksum embedded in your FEATURE or INCREMENT line. The new-style checksum embedded in your FEATURE or INCREMENT line. The value of the vendor (Wind River) string in your FEATURE or INCREMENT line, if configured. The version number of your feature.

If you specify an action in an options file using a package name in place of a feature name, for example, WORKBENCH_UU_SUBSCRIPTION_cfg1 instead of WR_WORKBENCH, the action is applied to all package components.
Type Specification

The following action keywords restrict who can use licenses or where licenses can be used:
EXCLUDE EXCLUDEALL INCLUDE INCLUDEALL

These actions specify whether the restriction is based on the following type arguments:
USER

The username of the user executing the licensed application.


HOST

The machine hostname or IP address where the application is executing. The IP address can contain wildcards.

98

A Option File Action Keywords A.3 Action Keywords

DISPLAY

The display where the application is shown. For Linux or Solaris, DISPLAY is /dev/ttyxx (which is always /dev/tty when an application is run in the background) or the X-display name. For Windows, DISPLAY is the system name or, in the case of a terminal server environment, the terminal server client name.
INTERNET

The IP address of the machine where the application is executing. The IP address can contain wildcards.
PROJECT

The name of a project for which restricted user access is desired (see Example 3-2 in 3.3 Options File Examples, p.41). For Windows (without a terminal server), the HOST and DISPLAY names are both set to the Windows 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 value. For example:
EXCLUDE WORKBENCH_UU_SUBSCRIPTION_cfg1 USER joew

You can specify multiple values, such as a group of users or hosts, if you define them as a single value first using the action keywords GROUP and HOST_GROUP. For example, use GROUP to identify a group of project developers:
GROUP Dvdplayer joe barbara susan EXCLUDE WORKBENCH_UU_SUBSCRIPTION_cfg1 GROUP Dvdplayer

A.3 Action Keywords


Action keywords are explained in greater detail in this section. Each entry includes a definition of the keyword, an example of syntax, and explanations of associated arguments.
INCLUDE and EXCLUDE options follow rules of precedence. For more information, see 3.3.2 Order of Precedence in the Options File, p.48. Example 3-1 and Example 3-3 in 3.3 Options File Examples, p.41, show how to use INCLUDE and EXCLUDE options.

99

Wind River License Administrator Tools Guide, 1.1

DEBUGLOG

Specify a location for the debug log output from the vendor daemon associated with this options file. This action uses the following syntax:
DEBUGLOG [+]debug_log_path

Preceding debug_log_path with a + character appends logging entries, otherwise the file is overwritten each time the daemon is started. Using DEBUGLOG 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 Example 3-4 in 3.3 Options File Examples, p.41.

EXCLUDE

Exclude a user or pre-defined group of users 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 EXCLUDE taking precedence. This action uses the following syntax:
EXCLUDE feature[:keyword=value] type {name | group_name}

feature Name of the feature being affected. keyword=value Feature name modifier to denote a group of licenses. For details, see Feature Specification, p.97. type One of USER, HOST, DISPLAY, INTERNET, PROJECT, GROUP, or HOST_GROUP. See Type Specification, p.98. name Name of an item of type type for which to reserve licenses. group_name Name of the group to exclude. Exclude the user hank from the list of users able to use feature WORKBENCH_UU_SUBSCRIPTION_cfg1, as follows:
EXCLUDE WORKBENCH_UU_SUBSCRIPTION_cfg1 USER hankv

100

A Option File Action Keywords A.3 Action Keywords

For usage examples, see Example 3-1 and Example 3-3 in 3.3 Options File Examples, p.41.

EXCLUDEALL

Exclude a user or pre-defined group of users from the list of who is allowed to use all features served by this vendor daemon. This action uses the following syntax:
EXCLUDEALL type {name | group_name}

type One of USER, HOST, DISPLAY, INTERNET, PROJECT, GROUP, or HOST_GROUP. See Type Specification, p.98. name Name of an item of type type for which to reserve licenses. group_name Name of the group to exclude. To exclude any user on the machine jupiter from using all features served by this vendor daemon, add the following line to your options file:
EXCLUDEALL HOST jupiter

GROUP

Define a group of users for use in INCLUDE, INCLUDEALL, EXCLUDE, EXCLUDEALL, and RESERVE option lines. This action uses the following syntax:
GROUP group_name user_list

group_name Name of the group being defined. user_list List of usernames in that group. Define the group Hackers, consisting of bob, howard, and james, as follows:
GROUP Hackers bob howard james

If the number of members in a group exceeds the line length limit, use multiple GROUP lines for the same group name to add all the specified users into the group.
NOTE: USER_GROUP is an alias for GROUP.

101

Wind River License Administrator Tools Guide, 1.1

For usage examples, see Example 3-1 and Example 3-3 in 3.3 Options File Examples, p.41.

HOST_GROUP

Define a group of hosts for use in INCLUDE, INCLUDEALL, EXCLUDE, EXCLUDEALL, and RESERVE option lines. This action uses the following syntax:
HOST_GROUP group_name host_list

group_name Name of the group being defined. host_list List of host names in that group. Define the host group Pacific, consisting of tokyo, seattle, and auckland, as follows:
HOST_GROUP Pacific tokyo seattle auckland

Anywhere a host name can be used in an options file, an IP address can be used instead. If the number of members in a host group exceeds the line length limit, use multiple HOST_GROUP lines to add all the specified hosts into the group.

INCLUDE

Include a user or pre-defined group of users 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. The INCLUDE action uses the following syntax:
INCLUDE feature[:keyword=value] type {name | group_name}

feature Name of the feature being affected. keyword=value Feature name modifier to denote a group of licenses. See Feature Specification, p.97. type One of USER, HOST, DISPLAY, INTERNET, PROJECT, GROUP, or HOST_GROUP. See Type Specification, p.98.

102

A Option File Action Keywords A.3 Action Keywords

name Name of an item of type type for which to reserve licenses. group_name Name of the group to include. Include bob in the list of users able to use feature WORKBENCH_UU_SUBSCRIPTION_cfg1, as follows:
INCLUDE WORKBENCH_UU_SUBSCRIPTION_cfg1 USER bob

INCLUDE is required for user-based or host-based features. For unique user

licensees, if you want to limit the number of users to the number of licensed seats, use an INCLUDE statement to define who has access. For usage examples, see Example 3-1 and Example 3-3 in 3.3 Options File Examples, p.41.

INCLUDEALL

Include a user or pre-defined group of users 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. This action uses the following syntax:
INCLUDEALL type {name | group_name}

type One of USER, HOST, DISPLAY, INTERNET, PROJECT, GROUP, or HOST_GROUP. See Type Specification, p.98. name Name of an item of type type for which to reserve licenses. group_name Allow user jane to use all features served by this vendor daemon, as follows:
INCLUDEALL USER jane

103

Wind River License Administrator Tools Guide, 1.1

NOLOG

Suppress logging the selected type of event in the debug log file. This action uses the following syntax:
NOLOG { IN | OUT | DENIED | QUEUED }

Turn off the logging of checkins, as follows:


NOLOG IN

Turn off the logging of checkouts and queued requests, as follows. 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 also reduce the usefulness of the debug log for debugging license server problems.

For more information, see Example 3-4 in 3.3 Options File Examples, p.41.

REPORTLOG

Specify the report log file for this vendor daemon. This action uses the following syntax:
REPORTLOG [+]report_log_path

Preceding report_log_path with a plus (+) character appends logging entries; otherwise the file is overwritten each time the daemon is started. In Windows, you can use pathnames that include spaces if you enclose them in double quotes.

104

B
Sample Reports and Messages
B.1 Introduction 105 B.2 Sample Reports 106 B.3 WRS License Reporting Agent Error Messages 110 B.4 The windrreport Utility Command Syntax 113

B.1 Introduction
This appendix includes examples of the reports associated with the reporting utilities (see B.2 Sample Reports, p.106). The WRS license reporting agent collects and sends usage data, including error messages, if applicable. For a list of possible error messages, see B.3 WRS License Reporting Agent Error Messages, p.110. For more information about the windrreport utility, see B.4 The windrreport Utility Command Syntax, p.113.

105

Wind River License Administrator Tools Guide, 1.1

B.2 Sample Reports


The WRS license reporting agent creates the following reports:

quarterly summary report server usage report dictionary file

This section provides examples of these reports. In each quarterly summary report, usage by each customer is separated out by customer license.

B.2.1 Quarterly Summary Report


The quarterly report helps you determine the following:

the total number of unique Wind River Workbench users the total number of Wind River Workbench users by license server (if you have multiple license servers)

Data is gathered based on license file PACKAGE names and your customer license number. You must account for user exception cases because the summary report does not. (For more information about user exceptions, see 3.1 Introduction, p.37.) The filename is QuarterlySummary, a text file without an extension, and takes the following generic form:
Quarterly Summary Report Rundate: mm/dd/yyyy Product1_Ver Report start date: xxxx Report end date: yyyy Input Report Log(s): server_xxx1.log: checksum server_xxx2.log: checksum, ... Servers used: server1, server2, server3 License #nnnnn for Product1_Ver:# total unique users Product1_Ver_Arch1:# unique users Product1_Ver_Arch2:# unique users ... License #mmmm for Product2_Ver: # total unique users Product2_Ver_Arch1:# unique users Product2_Ver_Arch2:# unique users ...

106

B Sample Reports and Messages B.2 Sample Reports

The above format uses the following definitions: Rundate The date the WRS license reporting agent was invoked. License #nnnn The Wind River license number assigned to you for a specified product. ProductN_Ver The version number of the product installed. In Example B-1, the customer uses Wind River Workbench on the license server machine saturn. The total number of unique users on License #221000 is 3. See Example B-2 for a breakout of those unique users, where the names appear encrypted.
Example B-1 Sample Quarterly Summary

WindRiver Quarterly Report Summary Quarterly Interval: 04/01/2004 to 06/30/2004 wrsReport 1.3 Rundate: 6/10/2004 16:30 Platform WORKBENCH_UUL_SUBSCRIP Report start date: Thu, Jun 10, 2004 03:00:04 PDT Report end date: Thu, Jun 10, 2004 16:28:05 PDT Input Report Log(s): wrsdSaturn.log Input Usage Report(s): saturn_wrsd_report_04-01-2004_06-30-2004.txt, Report Authentication: 8036F18B6717F2AC Servers used: saturn.widgets.com License # 221000 for Platform WORKBENCH_UUL_SUBSCRIP: 3 total unique users WORKBENCH_UUL_SUBSCRIP_Cfg1: 3 unique users Usage Reports:Authentication Codes List saturn_wrsd_report_04-01-2004_06-30-2004.txt: 8036F18B6717F2AC

number of unique users using each product

107

Wind River License Administrator Tools Guide, 1.1

B.2.2 Server Usage Report


The server usage report is a human-readable usage report generated by the WRS license reporting agent, based on the non-human-readable report logs generated by the vendor daemon (license server). The server usage report is the basis for the quarterly summary report. Server usage reports use a .txt filename extension. Example B-2 uses callouts to highlight important aspects of this report. The output filename takes the form: serverName_daemon_report_startDate_endDate.txt. The serverName and daemon name are derived from the first line of the input report logs. You supply the startDate and endDate as arguments to the wrsReport script. In the usage reports, usernames are listed in encrypted format, followed in parentheses by the encrypted hostname from which the user requested a license. For example:
ABU3J7Z2Z5EM2XP62Y (ACFTJX4MLY)

In this example, ABU3J7Z2Z5EM2XP62Y is the user; ACFTJX4MLY is the host from which user ABU3J7Z2Z5EM2XP62Y requested a license. WRS license reporting agent users can decode encrypted names by referring to the dictionary file described in B.2.3 Dictionary File, p.110.

108

B Sample Reports and Messages B.2 Sample Reports

Example B-2

Sample Server Usage Report

Wind River Usage Report 2004/06/10 04:30PM Produced by FLEXreport v3.2a.1 Log File Name: wrsdSaturn.log Report Log Start: Thu, Jun 10, 2004 03:00:04 PDT Report Log End: Thu, Jun 10, 2004 16:28:05 PDT Report Start Date: Thu, Apr 1, 2004 00:00:00 PST Report End Date: Wed, Jun 30, 2004 00:00:00 PDT Uptime: 13 hours 28 mins 1 secs (0.62%) Filter Start Date: Thu, Apr 1, 2004 00:00:00 PST Filter End Date: Wed, Jun 30, 2004 00:00:00 PDT Gap Threshold: 30 mins 0 secs Vendor: wrsd ------------------------------------------------------------------------Platform Suite Usage ------------------------------------------------------------------------Feature: WORKBENCH_UUL_SUBSCRIP_Cfg1 2.0 [<ln>221000</ln><flt>2</flt><ps>1161-1</ps>] Server:saturn.widgets.com Users/Hosts: AC94HHYCF8 (ACFLDHPRNH5ZS) AC94HHYCFM (ACFLDHPRNH5ZS) ACP3TJX4 (ACF3D8XRLPWQ) End Feature ------------------------------------------------------------------------Feature Usage ------------------------------------------------------------------------None. components being used from the package suite ========================================================================= License Server Coverage ========================================================================= ------------------------------------------------------------------------Vendor:wrsd Hostname:saturn.widgets.com Hostid:80b00000 ------------------------------------------------------------------------Uptime: 13 hours 28 mins 1 secs (0.62%) sections of the report log that were corrupted Server Down Periods: 09-Jun-2004 00:00 Corrupted Blocks: None.

customer license number encrypted unique users encrypted client machines

10-Jun-2004 03:00

1 days 3 hours 0 mins 4 secs

109

Wind River License Administrator Tools Guide, 1.1

Missing Blocks: None. ========================================================================= Report Log Diagnostics ========================================================================= Report Log Corruption Errors Report Authentication: 8036F18B6717F2AC

B.2.3 Dictionary File


The windrreport tool uses your encryption key to generate the dictionary file. The dictionary file lists users Windows or UNIX login names and the corresponding encrypted name in the WRS license reporting agent. Dictionary files are produced with the filename extension .dict. One dictionary file is produced for each set of report logs processed by a single run of the WRS license reporting agent. Your encryption key prevents any third party, including Wind River, from viewing actual user login names. The dictionary files generated through the WRS license reporting agent are not part of the ZIP file sent to Wind River.
janedoe abcsmith foojones barangus andreadoria wcfields ACGLTG7SN32ZPA8 ACGLZJ8CL33J47Q ACH4FG75LL5A ACJLFGYEL37Q ACJLFLHVM75JBDY ACK33G7UMHW2C7Q

B.3 WRS License Reporting Agent Error Messages


This section describes the run-time error messages that the WRS license reporting agent might produce. If errors occur when the WRS license reporting agent is run, these error messages are written to both of the following locations:

the Report Log Diagnostics section of the server usage report (B.2.2 Server Usage Report, p.108) a terminal window (on UNIX platforms) or installDir\flexreport.log (on Windows platforms) during command-line processing

110

B Sample Reports and Messages B.3 WRS License Reporting Agent Error Messages

Expired windrreport License

There is no specific error message noting an expired windrreport license, unlike the other errors listed below. However, output in the Solaris console window or the Windows-based installDir\flexreport.log indicates No license found for wrsd...
Corrupt Error Log Event
Error: Report log has been corrupted (-4) file lineNumber (id 50)(minor -1) (Invalid key found, record lost)

A corrupt report log event was found in the report log. This error may be associated with a vendor daemon1 crash.
Unexplained windrreport Problem
Error: Internal Error (-7) file lineNumber (id 54)(minor 0) featureKey

This error indicates an unexplained problem in windrreport. This error should be reported to Wind River Technical Support.
Log Gap
Error: A reportlog is missing (-9) file lineNumber (id 40)(minor 0) featureKey

The report log contains a time gap of significant duration between an end and the following start event.
Restart: Undetermined Feature
Error: Reportlog is truncated (-11) file lineNumber (id 48)(minor -5) (Vendor daemon crashed and restart)

The report log event fragment is seen immediately followed by a restart. The feature corresponding to the event fragment is undetermined. This error is usually caused by a crash of the vendor daemon, wrsd.

1. The term vendor daemon appears in some error messages. It refers to the license-management entity that allows an application to run. The vendor daemon name identifies one software vendor from another. The Wind River vendor daemon is called wrsd; the RTI daemon is RTID. The WRS license reporting agent can be run against these two daemons.

111

Wind River License Administrator Tools Guide, 1.1

Restart: Specified Feature


Error: Reportlog is truncated (-11) file lineNumber (id 48)(minor -5) (Vendor daemon crashed and restart) featureKey

The report log event fragment is seen immediately followed by a restart. The feature corresponding to the event fragment is shown. This event is unusable. This error is usually caused by a wrsd (vendor daemon) crash.
Log Ends Abruptly
Error: Reportlog is truncated (-11) file lineNumber (id 42)(minor 0) featureKey

One of the most common error messages encountered. The report log file ends abruptly. This error is probably caused by reading from or copying the report log while wrsd is running. This error can also be the result of a wrsd crash with no subsequent restart. It is recommended you use lmnewlog or lmswitchr to terminate a report log before initiating rollover to a new log file. For more information, see Terminating Active Report Logs, p.57.
Unmatched Checkout
Error: An error was found in the reportlog (-13) file lineNumber (id 51)(minor -4) (Checkout occurred without checkin, recovery attempted) featureKey

No matching checkin event was found for a checkout event. Because the error is reported much later than when the error actually occurred, the line number is not particularly relevant.
Invalid Argument
Error: End date may be using 2 digit year instead of 4 digits Error occurred: gsi.samreport.JrepException: Unable to generate report.

This is an example of an error that occurs when a parameter or an argument is invalid, and therefore a report cannot be generated. The first line of the error message describes which parameter or argument is invalid.
Multiple Vendor Daemons
Error: In file vendor changed from vendor_name1(hostid1) to vendor_name2(hostid2). No further events will be read from this file.

112

B Sample Reports and Messages B.4 The windrreport Utility Command Syntax

This report log has been written by more than one vendor daemon, or by a vendor daemon running on more than one host ID. This can occur when a vendor daemon is rehosted but a new report log is not started.
Log Data Inconsistencies
Error reporting threshold of 2000 has been reached. No further errors will be reported. Error: Inconsistencies found in reportLog around file lineNumber

These error messages are generated when inconsistencies have been detected in a block of data within a report log. For example, data may be missing or may have been corrupted or altered.

B.4 The windrreport Utility Command Syntax


The windrreport utility sorts input files by host, draws on the start and end dates, and constructs a command sequence to run each group of report logs for each server. This command sequence uses the following syntax:
% windrreport -input windRiverReportLog [-input windRiverReportLog ...] -output \ reportFile -startdate date -enddate date

In this command syntax, date can take any of the following forms:
MM/dd/yyyy HH:mm:ss MM/dd/yyyy HH:mm MM/dd/yyyy yyyyMMdd HHmmss yyyyMMdd HHmm yyyyMMdd MMM dd, yyyy HH:mm:ss MMM dd, yyyy HH:mm MMM dd, yyyy

The windrreport utility produces the following output:

a server usage log called reportFile.txt a dictionary file called reportFile.dict, used to decode the encrypted user- and hostnames

113

Wind River License Administrator Tools Guide, 1.1

114

C
Glossary
enterprise licensing model (ELM)

A subscription approach to licensing that gives the customer access to all products and supported architectures. The right to use the product expires after some specified term and must be renewed.
feature line

A text line in a license file that licenses a particular feature, typically a software product. A feature line begins with one of the keywords FEATURE, UPGRADE, PACKAGE, or INCREMENT. See also INCREMENT line, p.116, and PACKAGE line, p.117.
floating license (FL)

This license type is designed for use over a network, accessible to client machines from a license server machine. The customer purchases a specific number of seats and allocates some or all to a license server machine. The number of allocated seats sets a limit on concurrent users able to draw product licenses from that server.
host

The network node or machine requesting a license for an application from a license server.

115

Wind River License Administrator Tools Guide, 1.1

INCREMENT line

A text line in a license file that licenses a particular feature, typically a software product. The line begins with INCREMENT, and differs from the FEATURE element because it allows more than a single instance of a feature name and version number in a single license file.
installation key

This code unlocks access to the contents of a distribution CD-ROM; that is, each CD has its own installation key. For Wind River products, the installation key is embedded in the install.txt file. Sometimes referred to as an install key.
license

The legal right to use a feature.


license authorization code (LAC)

An alphanumeric, case-sensitive identifier issued for each license agreement that is used to request a Product Activation file, and, thus, controls installation and licensing access to all product features under that agreement.
license file

A text file specific to a license server machine or a node-locked host that contains descriptions of the following:

licenses (features) for all supported products license server nodes (server only) vendor daemons (server only)

license server

An lmgrd process and one or more vendor daemon processes. License server refers to the processes, not the computer on which they run. See also license server machine, p.116.
license server machine

A computer system on which license server processes run.

116

C Glossary

lmgrd

The license manager daemon that routes requests from the license-enabled application to the correct vendor daemon running on the same license server. The same license manager daemon can be used by any application from any vendor because this daemon neither authenticates nor dispenses licenses.
node-locked host

A node-locked machine because, by design, it hosts both license management and product software.
node-locked license (NL) C

A license type designed for use on a single machine (usually not networked) by any user working on that machine. Both the node-locked license file and the product software are installed on this machine. Remote access to the software from another computer is prohibited.
OEM licenses

See perpetual licenses, p.117.


options file

A text file provided by Wind River that enables report logging for unique user licenses distributed by a particular license server. The file can be modified to customize the behavior of the wrsd vendor daemon, including the restriction of access to Wind River licenses on that license server.
PACKAGE line

A text line in a license file that licenses a high-level product designated by the feature name, typically a software product. The line begins with PACKAGE, which means multiple features are packaged under this single keyword.
PAWS

The Wind River Product Activation Web site.


perpetual licenses

Perpetual licenses, also known as OEM licenses, do not expire. The customer has the right to use the product for its lifetime, as long as the customer abides by the terms of the agreement.

117

Wind River License Administrator Tools Guide, 1.1

Product Activation file (WRSLicense.lic)

This text file includes the contents of the license file, client-side license management information, and the installation keys.
report log file

A text file written by a single vendor daemon. Report logs are not human readable; the data is compressed and authenticated and transferred to Wind River.
reporting agent

See WRS license reporting agent, p.119.


rotation

The act of switching the report log file by moving the existing report log information to a new file, then starting a new report log having the original report log filename.
RTID

The Real-Time Innovations (RTI) vendor daemon.


transfer

The act of transmitting the transfer file to Wind River.


unique user license (UU)

This license type is designed for use over a network, accessible to client machines from a license server machine. The customer can create a development environment having as many licensed seats as the customer needs, subject to the maximum stipulated in the customers license agreement, because product usage data is collected for each license server and reported to Wind River.
vendor daemon

The license server process that dispenses licenses for the requested feature. This binary is built by an applications vendor, such as Wind River. See also wrsd, p.119.
windrreport

A time-sensitive, license-enabled component of the WRS license reporting agent that generates reports aggregating license usage data.

118

C Glossary

wrsd

The Wind River vendor daemon.


WRSLicense.lic

A hosts permanent license management file provided after permanent activation of the Wind River license.
WRS license reporting agent

A software program for processing report logs created to collect usage data for each license server handling Wind River products on a network. The utility then generates human-readable reports to be submitted to Wind River. Formerly known as wrsReport.

119

Wind River License Administrator Tools Guide, 1.1

120

Index

Numerics
-2 -p option (lmgrd) 28

C
-c option lmdown 29 lmgrd 28 lmreread 81 wrsReport 54 clients (unique user and floating) configuring 71 LM_PROJECT, using 44 converting licenses one type to another 74 Customer License Number finding 80

A
action keywords 99104 see also individual keywords DEBUGLOG 100 EXCLUDE 100 EXCLUDEALL 101 GROUP 101 HOST_GROUP 102 INCLUDE 102 INCLUDEALL 103 NOLOG 104 REPORTLOG 104 -all option (lmdown) 29

D
-d option (wrsReport) 53 debug logs 93 debugging lmgrd, using 93 restricting debug output 48 DEBUGLOG action keyword 100 example 48 deleting install.txt 78 license files 78 dictionary file (WRS license reporting agent)

B
borrow 86 borrowing 85

60

121

Wind River License Administrator Tools Guide, 1.1

example 110

G
GROUP action keyword 101

E
encryption key WRS license reporting agent 51 decoding, dictionary file for 60 -end option (wrsReport) 53 environment variables see also individual variables LM_PROJECT 26 WRSD_LICENSE_FILE unique user and floating clients 71 error reporting license management 93 user exception cases 8 WRS license reporting agent 61 examples 110 EXCLUDE action keyword 100 example 42 multiple license types, working with 46 order of precedence 48 EXCLUDEALL action keyword 101 expiration dates, license 75

H
-help option (lmgrd) 29 host system requirements 5, 6 HOST_GROUP action keyword 102 hostname, changing (Linux) 84 hosts (node-locked) 7

I
INCLUDE action keyword 102 example 42 multiple license types, working with 46 order of precedence 48 INCLUDEALL action keyword 103 INCREMENT line (license file) 25 install.properties node-locked environments, and 67, 82 install.txt 10 deleting 78 installing see also uninstalling license servers multiple 18 Introduction 1

F
-f option (wrsReport) 53, 54 feature names keyword-value pairs, and optional 97 FLEXlm 11 .flexlmrc file resetting WRSD_LICENSE_FILE node-locked 68 unique user and floating 71 unavailable license, finding 83 flexreport.log 61 floating licenses (FL) 8 hosts, setting up 14 node-locked context, using in 85 reconfiguring seats 87 -force option (lmdown) 29

L
-l option (lmgrd) 28 license borrowing 86 License Administration Token finding 80 license files 10 deleting 78

122

Index

expiration dates 75 merging 23 example 25 limitations 90 restricting user access 4147 uninstalling 36 moving to a non-standard location 82 non-Wind River products, and 90 obtaining new 81 re-reading 81 search order 24 superseding 78 transferring between hosts 76 WRS license reporting agent, for 51 license management 2 floating seats, for 19 installing node-locked 15 LMTOOLS utility 91 multiple servers, using 18 node-locked seats, for 12 software (FLEXlm) 11 tips 79 uninstalling node-locked 36, 72 unique user and floating 35 unique user seats, for 19 license management files, see license files License Management Transfer Certificate Agreement 76 superseding license files 78 transferring license files 77 license manager utility, see lmutil command; LMTOOLS utility license manager, see license servers; lmgrd license servers client, specifying for 71 configuration scenarios merging license files 23 multiple servers, single product 22 restricting user access 42 single server, multiple products 23 single server, single product 17 diagnostics, running 91 installing

multiple, on 18 lock file permissions, Linux or Solaris 30 monitoring usage 91 multiple accessing 70 installing 18 performance, optimizing 20 reconfiguring 91 starting 27 lock file permissions, Linux or Solaris 30 troubleshooting 89 stopping 27 uninstalling 35 license types 7 see also individual license types borrowing 85 converting to another 74 floating 8 node-locked 7 restricting access to multiple, on single server 46 unique user 8 licenses borrowing 85 renewing 75 third-party 11 LM_BORROW 86 LM_PROJECT environment variable example 44 using 26 lmdown command 29 disabling 28 lmgrd command debug logs, generating 93 logging run-time data 48 options 28 search order for license files, specifying 26 starting license manager 27 syntax 27 lmgrd daemon 19 starting Linux 27 Solaris 27 Windows 30 stopping

Index

123

Wind River License Administrator Tools Guide, 1.1

Linux 29 Solaris 29 Windows 33 lmnewlog utility rotating log files 55 terminating report logs 57 lmremove command disabling 28 unresolved checkouts, killing 92 lmreread command 81 lmswitchr utility rotating log files 55 terminating report logs 57 LMTOOLS utility 91 re-reading license and options files 81 search order for license files, specifying 26 starting license servers 27 unresolved checkouts, killing 92 lmutil command re-reading license and options files 81 stopping license servers 29 -local option (lmgrd) 28 log.txt 92

O
options file 3849 action keywords 99104 order of precedence 48 comments 97 creating 39 examples 4149 features with keyword-value pairs, using modifying 40 report log files specifying 39 WRS license reporting agent 54 re-reading 81 syntax 97 types, using 98

97

P
PATH environment variable WRS license reporting agent, and port number, license server changing 90 specifying manually 90 PROJECT keyword example 44 52

M
merging license files 23 example 25 limitations 90 restricting user access 4147 uninstalling, and 36

Q
-q option (lmdown) 29

N
named-user lists, see user lists network latency, client request timeout 88 node-locked licenses (NL) 7 uninstalling 36, 72 NOLOG action keyword 104 example 48 Notepad (text editor) 80

R
regedit utility multiple servers, accessing 71 WRSD_LICENSE_FILE, resetting 68, 72 renewing licenses 75 report log files archiving 57

124

Index

naming 54 processing 57 rotating WRS license reporting agent, and 55 specifying in options file 39 terminating 57 truncated 112 WRS license reporting agent, and 54 reporting reports, sample quarterly summary 106 server usage 108 required for UU 89 user exceptions 8 reporting agent, see FLEXbill license reporting agent; WRS license reporting agent REPORTLOG action keyword 104 basic options file, in 40 re-reading license files 81 options files 81

unavailable license FLEXlm cache file, removing 83 not unique hostname 84 unrecognized hostname 84 unresolved checkouts, killing 92 WRS license reporting agent errors 110

U
uninstalling license server 35 merged license files 36 node-locked license management 36, 72 unique user licenses (UU) 8 configuration scenarios, license server 68 node-locked context, using in 85 reconfiguring seats 87 WRS license reporting agent, using 61 user exceptions 8 user lists alternative to 44 multiple license types, and 46 restricting access 42

Index

S
seats, license see individual license types setup.log 92 -start option (wrsReport) 53 starting license servers 27 stopping license servers 27 superseding license files 78 system requirements 5, 6

V
-v option (lmgrd) 28 vendor daemon, see wrsd -vendor option (lmdown) 29

W T
tips, license management 79 transferring license files 76 troubleshooting debug logs, using 93 license management 79 license server will not start 89 text editors (Notepad or WordPad) windrreport utility empty reports, generating license file 51 expiration error 111 output 113 reports, sample 106 syntax, command 113 WordPad (text editor) 80 wrenv utility 59

80

125

Wind River License Administrator Tools Guide, 1.1

node-locked environments, and 67, 82 WRS license reporting agent 61 see also windrreport utility archiving report logs 57 dictionary file 60 empty reports 59 encryption key 51 errors 61 examples 110 identifying files for processing 57 license file 51 log files, rotating 55 options file, and 52 output files 59 reports 106 reports, sample dictionary file 110 server usage 108 running 52 command-line examples 57 wrsd vendor daemon definition of 19 moving a license file 82 performance limitations 20 search order, license file 24 stopping Linux 29 Solaris 29 Windows 33 WRSD_LICENSE_FILE environment variable license files, replacing 75 multiple license servers accessing 70 node-locked licenses, and manually, setting 65 resetting node-locked 68 unique user and floating 71 WRSLicense.lic, see license files WRSLicenseServer.lic, see license files wrsReport command 5258 command-line examples 57 restrictions 55 syntax 53

X
-x option (lmgrd) 28

Z
-z option (lmgrd) 28

126