ibm tivoli license managerpublib.boulder.ibm.com/tividd/td/itlm/gc23-4834-01/e… · ·...

IBM Tivoli License Manager

System Administrator’s GuideVersion 1.1.1

GC23-4834-01

��

Second Edition, May 2003

This edition applies to version 1.1.1 of IBM Tivoli License Manager (program number 5724-D33) and to allsubsequent releases and modifications until otherwise indicated in new editions.

This edition replaces GC23-4834-00.

IBM welcomes your comments.

Address your comments to:

IBM License Management Information DevelopmentRome Tivoli LabIBM Italia S.p.A.Via Sciangai, 5300144 RomeItaly

Fax Number: (+39) 06 5966 2077

Internet ID: [email protected]

When you send information to IBM, you grant IBM a non-exclusive right to use or distribute the information in anyway it believes appropriate without incurring any obligation to you.

© Copyright International Business Machines Corporation 2001, 2003. All rights reserved.US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contractwith IBM Corp.

Note

Before using this information and the product it supports, read the information under “Notices” on page 125.

Contents

Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii

Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix

About this guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiWho should read this guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiWhat this guide contains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiPublications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii

Tivoli License Manager library . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiiRelated publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiiAccessing publications online . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiiOrdering publications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii

Accessibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiiiContacting software support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiiiConventions used in this guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiv

Typeface conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xivOperating system-dependent paths . . . . . . . . . . . . . . . . . . . . . . . . . . xv

Chapter 1. Planning a Tivoli License Manager implementation . . . . . . . . . . . . 1The license management infrastructure . . . . . . . . . . . . . . . . . . . . . . . . . . 1Web interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4Implementation scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5Preparing to implement Tivoli License Manager . . . . . . . . . . . . . . . . . . . . . . . 7

Determining the number of agents for a runtime server . . . . . . . . . . . . . . . . . . . . 8Estimating the duration of inventory scans . . . . . . . . . . . . . . . . . . . . . . . . 9

Chapter 2. Installing Tivoli License Manager . . . . . . . . . . . . . . . . . . . 11Supported platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Before you start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13Upgrading from version 1.1 to version 1.1.1 . . . . . . . . . . . . . . . . . . . . . . . . 14

Upgrade steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15Catalog manager upgrade considerations . . . . . . . . . . . . . . . . . . . . . . . . 15

Upgrading WebSphere Application Server . . . . . . . . . . . . . . . . . . . . . . . . . 16Installing and setting up Tivoli License Manager . . . . . . . . . . . . . . . . . . . . . . . 16

Installing Tivoli License Manager components . . . . . . . . . . . . . . . . . . . . . . . 17Using the installation wizard in silent mode . . . . . . . . . . . . . . . . . . . . . . 17Using the installation wizard in interactive mode. . . . . . . . . . . . . . . . . . . . . 18

Creating a DB2 database for Tivoli License Manager. . . . . . . . . . . . . . . . . . . . . 24Creating and populating a database on Windows. . . . . . . . . . . . . . . . . . . . . 25Creating and populating a database on AIX . . . . . . . . . . . . . . . . . . . . . . 25Connecting a database to a Tivoli License Manager server on a Windows computer . . . . . . . . . 26Connecting a database to a Tivoli License Manager server on an AIX computer . . . . . . . . . . 27

Defining notification settings for a server . . . . . . . . . . . . . . . . . . . . . . . . 28Starting a Tivoli License Manager server component. . . . . . . . . . . . . . . . . . . . . 29Setting up Tivoli License Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Uninstalling Tivoli License Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . 31Uninstalling the Tivoli License Manager servers and catalog manager . . . . . . . . . . . . . . . 31Dropping the Tivoli License Manager databases on Windows. . . . . . . . . . . . . . . . . . 32Dropping the Tivoli License Manager databases on AIX . . . . . . . . . . . . . . . . . . . 32Disconnecting a database from a Tivoli License Manager server on a Windows computer . . . . . . . . 32Disconnecting a database from a Tivoli License Manager server on an AIX computer . . . . . . . . . . 32Uninstalling the agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

© Copyright IBM Corp. 2001, 2003 iii

Chapter 3. Enabling secure communications . . . . . . . . . . . . . . . . . . . 35Using the HTTPS protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35Enabling SSL for IBM HTTP Server . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Virtual host definition in the HTTP configuration file . . . . . . . . . . . . . . . . . . . . 36Creating or requesting a server certificate . . . . . . . . . . . . . . . . . . . . . . . . 37

Adding a server certificate to the trusted store. . . . . . . . . . . . . . . . . . . . . . . . 37SSL port aliases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38Disabling secure communications . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Using the HTTP protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39Deleting the virtual host definition . . . . . . . . . . . . . . . . . . . . . . . . . . 39Restoring default port aliases . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Chapter 4. The command line interface . . . . . . . . . . . . . . . . . . . . . . 41Accessing the command line interface . . . . . . . . . . . . . . . . . . . . . . . . . . 41Command line output on Windows systems . . . . . . . . . . . . . . . . . . . . . . . . 41Commands on the Tivoli License Manager servers . . . . . . . . . . . . . . . . . . . . . . 42

dbpasswd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42expcat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43impcat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43rtpasswd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43srvstart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44srvstop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44sslpasswd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44statusinfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Chapter 5. The agent. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47Summary of agent functionality . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47Agent deployment and upgrade . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

Deploying the agent manually . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48Parameters of the installagent command. . . . . . . . . . . . . . . . . . . . . . . . 49Specifying installagent parameters in the command line . . . . . . . . . . . . . . . . . . 50Specifying installagent parameters in a file . . . . . . . . . . . . . . . . . . . . . . . 50

Automatic upgrade of agents . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50Agent files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

AIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51Sun . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

Agent commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52All platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52AIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53Other UNIX Platforms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

Chapter 6. Event notification . . . . . . . . . . . . . . . . . . . . . . . . . . 55Events that generate notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55Defining notification recipients and notification settings for a server . . . . . . . . . . . . . . . . 55The event.log file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

Chapter 7. XML interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . 59XML definition for the software usage snapshot . . . . . . . . . . . . . . . . . . . . . . . 59XML definition for the software usage trend analysis report . . . . . . . . . . . . . . . . . . . 63XML definition for the software usage level analysis report . . . . . . . . . . . . . . . . . . . 65XML formats for the software inventory report . . . . . . . . . . . . . . . . . . . . . . . 66

Chapter 8. Database table cleanup . . . . . . . . . . . . . . . . . . . . . . . . 71Performance and sizing considerations . . . . . . . . . . . . . . . . . . . . . . . . . . 71Setting parameters for cleanup processes . . . . . . . . . . . . . . . . . . . . . . . . . 71

iv IBM Tivoli License Manager: System Administrator’s Guide

Chapter 9. Problem determination . . . . . . . . . . . . . . . . . . . . . . . . 73Validating the installation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73Log files and tracing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

Logging and trace setting on servers . . . . . . . . . . . . . . . . . . . . . . . . . . 76Using the statusinfo command to collect error information . . . . . . . . . . . . . . . . . . 77Logging and trace setting on the agent . . . . . . . . . . . . . . . . . . . . . . . . . 77

Deployment and installation tracing . . . . . . . . . . . . . . . . . . . . . . . . . 78Agent operation tracing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78Network traffic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78Database size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79Disk space. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79System processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79WebSphere Application Server settings . . . . . . . . . . . . . . . . . . . . . . . . . 79HTTP configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

Common problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80Server installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80WebSphere Application Server configuration . . . . . . . . . . . . . . . . . . . . . . . 83Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84Agent deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85Agent operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89User interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94Catalog manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96Event notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

Appendix A. Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97Message details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

Appendix B. Configuration settings . . . . . . . . . . . . . . . . . . . . . . . 107Tivoli License Manager configuration files . . . . . . . . . . . . . . . . . . . . . . . . . 107The system.properties file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

Web Interface settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109Administration server settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109Runtime server settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110Agent settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111E-mail configuration settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

The db.properties file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113Configuring proxies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

Appendix C. Options file for silent installations . . . . . . . . . . . . . . . . . . 117

Appendix D. Common tasks . . . . . . . . . . . . . . . . . . . . . . . . . . 121Initializing the DB2 command line . . . . . . . . . . . . . . . . . . . . . . . . . . . 121Starting and stopping the HTTP server . . . . . . . . . . . . . . . . . . . . . . . . . . 121Starting and stopping the WebSphere Application Server . . . . . . . . . . . . . . . . . . . . 122Starting the WebSphere Administrator’s Console . . . . . . . . . . . . . . . . . . . . . . 122

Appendix E. Connecting to an X display server. . . . . . . . . . . . . . . . . . 123Connecting on the same computer . . . . . . . . . . . . . . . . . . . . . . . . . . . 123Connecting between computers . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126

Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133

Contents v

vi IBM Tivoli License Manager: System Administrator’s Guide

Figures

1. Three-tiered topology of Tivoli License Manager components . . . . . . . . . . . . . . . . . 22. Tivoli License Manager structure with multiple runtime servers . . . . . . . . . . . . . . . . 33. Distribution of agents between divisions and runtime servers . . . . . . . . . . . . . . . . . 44. Monitoring needs of a large company . . . . . . . . . . . . . . . . . . . . . . . . . 55. Tivoli License Manager structure at a large customer . . . . . . . . . . . . . . . . . . . . 66. SSL-enabled virtual host definition for Windows servers . . . . . . . . . . . . . . . . . . 367. SSL-enabled virtual host definition for AIX servers . . . . . . . . . . . . . . . . . . . . 37

© Copyright IBM Corp. 2001, 2003 vii

viii IBM Tivoli License Manager: System Administrator’s Guide

Tables

1. Test environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82. Tivoli License Manager installation prerequisites . . . . . . . . . . . . . . . . . . . . . 123. Accessing the command line on Windows and AIX servers . . . . . . . . . . . . . . . . . 414. Administration and runtime server commands . . . . . . . . . . . . . . . . . . . . . . 425. Agent files on AIX platforms. . . . . . . . . . . . . . . . . . . . . . . . . . . . 516. Agent files on Sun platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . 517. Agent files on Windows platforms . . . . . . . . . . . . . . . . . . . . . . . . . . 528. Agent commands on all agent platforms . . . . . . . . . . . . . . . . . . . . . . . . 529. Agent commands on AIX platforms . . . . . . . . . . . . . . . . . . . . . . . . . 53

10. Agent commands on UNIX platforms . . . . . . . . . . . . . . . . . . . . . . . . . 5311. Agent commands on Windows platforms . . . . . . . . . . . . . . . . . . . . . . . 5312. Subelements of the ProductEntry element in the software usage snapshot . . . . . . . . . . . . . 6013. Subelements of the AgentEntry element in the software usage snapshot . . . . . . . . . . . . . 6114. Subelements of the CapacityEntry element in the software usage snapshot . . . . . . . . . . . . 6115. Subelements of the LicenseEntry element in the software usage snapshot . . . . . . . . . . . . . 6216. Subelements of the SessionEntry element in the software usage snapshot . . . . . . . . . . . . . 6317. Subelements of the EventDataModel element in the trend analysis report . . . . . . . . . . . . . 6418. Subelements of the EventDataModel.stats element in the trend analysis report . . . . . . . . . . . 6419. Subelements of the Product element in the level analysis report . . . . . . . . . . . . . . . . 6620. Subelements of the XmlExport element in the software inventory report . . . . . . . . . . . . . 6821. Subelements of the Product element in the software inventory report . . . . . . . . . . . . . . 6822. Subelements of the Agent element in the software inventory report . . . . . . . . . . . . . . . 6923. Trace levels and log files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7624. WebSphere Application Server configuration scripts . . . . . . . . . . . . . . . . . . . . 8325. Installagent return codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8926. Agent subcomponent error codes . . . . . . . . . . . . . . . . . . . . . . . . . . 9127. Tivoli License Manager message categories . . . . . . . . . . . . . . . . . . . . . . . 9728. Tivoli License Manager messages . . . . . . . . . . . . . . . . . . . . . . . . . . 9829. Configuration files for Tivoli License Manager servers . . . . . . . . . . . . . . . . . . . 10730. Web interface parameters in the system.properties file . . . . . . . . . . . . . . . . . . . 10931. Administration server parameters in the system.properties file . . . . . . . . . . . . . . . . 10932. Runtime server parameters in the system.properties file . . . . . . . . . . . . . . . . . . 11033. Agent parameters in the system.properties file . . . . . . . . . . . . . . . . . . . . . 11134. E-mail configuration parameters in the system.properties file . . . . . . . . . . . . . . . . 11335. Parameters in the db.properties file . . . . . . . . . . . . . . . . . . . . . . . . . 11436. Argument definitions for silent installations . . . . . . . . . . . . . . . . . . . . . . 117

© Copyright IBM Corp. 2001, 2003 ix

x IBM Tivoli License Manager: System Administrator’s Guide

About this guide

This guide contains information about planning, installing, and configuring IBM®

Tivoli® License Manager.

It includes information about using the command line interface and aboutpreventing, identifying, and resolving problems as well as reference material thatdescribes the Tivoli License Manager agents on different platforms.

Who should read this guideThis guide is for system administrators who are responsible for setting up andadministering the license management environment.

What this guide containsThis guide contains the following sections:v Chapter 1, “Planning a Tivoli License Manager implementation”

Provides an overview of the monitoring infrastructure and a list of issues youshould take into account when planning to install Tivoli License Manager.

v Chapter 2, “Installing Tivoli License Manager”Provides instructions for installing and configuring the product.

v Chapter 3, “Enabling secure communications”Provides information on how to use encrypted communications between TivoliLicense Manager servers and between browsers and servers.

v Chapter 4, “The command line interface”Summarizes the commands available on the administration and runtime servers.

v Chapter 5, “The agent”Summarizes agent functionality and provides instructions for manual installationof agents and use of the agent command line.

v Chapter 6, “Event notification”Includes information about the types of event that trigger notifications.

v Chapter 7, “XML interfaces”Provides detailed descriptions of the XML formats used to export reports fromthe Web interface.

v Chapter 8, “Database table cleanup”Provides instructions for setting up a regular task to clear old entries fromcertain database tables.

v Chapter 9, “Problem determination”Provides information to help you validate the installation of Tivoli LicenseManager, to identify and prevent performance problems, and to recognize andresolve commonly occurring problems.

v Appendixes, including a list of the error messages used in Tivoli LicenseManager and information about configuration files.

© Copyright IBM Corp. 2001, 2003 xi

PublicationsThis section lists publications in the Tivoli License Manager library and relateddocuments. It also describes how to access Tivoli publications online and how toorder Tivoli publications.

Tivoli License Manager libraryThe Tivoli License Manager library also includes the following books:v IBM Tivoli License Manager: License Administrator’s Guide, GC23-4833

Provides support for using the Tivoli License Manager Web interfaces.v IBM Tivoli License Manager: Data Dictionary, GC23-4835

Provides descriptions of the database tables and indexes maintained in the TivoliLicense Manager administration server database.

v IBM Tivoli License Manager: Warehouse Enablement Pack Implementation Guide,SC32-1244Provides instructions and other information related to enabling the use of theTivoli Enterprise™ Data Warehouse with Tivoli License Manager.

v IBM Tivoli License Manager: Release Notes, SC23-4848Provides a summary of changes made in a release, documents known errors andworkarounds, and includes information about any product changes that couldnot be included in the main documentation.

Related publicationsThe following documents also provide useful information:v IBM DB2 Universal Database™ Enterprise - Extended Edition for Windows®: Quick

Beginnings, GC09-2963v IBM DB2 Universal Database Enterprise - Extended Edition for UNIX®: Quick

Beginnings, GC09-2964These Quick Beginnings guides provide an introduction to installing andconfiguring DB2® products.

v http://www7b.software.ibm.com/wsdd/WASInfoCenter/infocenter/ providesaccess to WebSphere® Application Server product information.

The Tivoli Software Glossary includes definitions for many of the technical termsrelated to Tivoli software. The Tivoli Software Glossary is available, in English only,at the following Web site:

http://publib.boulder.ibm.com/tividd/glossary/termsmst04.htm

Accessing publications onlineA documentation CD contains the publications that are in the product library, otherthan the IBM Tivoli License Manager: Release Notes, in all supported languages. Theformat of the publications is PDF, HTML, or both. To access the publications usinga Web browser, open the allpubs.htm file. The file is in the root directory on thedocumentation CD. Select the language of your choice, and an Information Centerfor the product in that language is displayed. Select the publication and the formatin which you want to view it.

Note: On Windows platforms, an autorun exec opens the allpubs.htm file in yourdefault browser.

xii IBM Tivoli License Manager: System Administrator’s Guide

http://www7b.software.ibm.com/wsdd/WASInfoCenter/infocenter/

http://publib.boulder.ibm.com/tividd/glossary/termsmst04.htm

IBM posts the IBM Tivoli License Manager: Release Notes, along with publications forthis and all other Tivoli products, as they become available and whenever they areupdated, to the Tivoli Software Information Center Web site. The Tivoli SoftwareInformation Center is located by using the following Web address:

http://www.ibm.com/software/tivoli/library/

Click the Product manuals link to access the Tivoli Software Information Center.

Click the IBM Tivoli License Manager link to access the product library.

Note: If you print PDF documents on other than letter-sized paper, select the Fit topage check box in the Adobe Acrobat Print window. This option is availablewhen you click File > Print. Fit to page ensures that the full dimensions of aletter-sized page print on the paper that you are using.

Ordering publicationsYou can order many Tivoli publications online at the following Web site:

http://www.elink.ibmlink.ibm.com/public/applications/publications/cgibin/pbi.cgi

You can also order by telephone by calling one of these numbers:v In the United States: 800-879-2755v In Canada: 800-426-4968

In other countries, see the following Web site for a list of telephone numbers:

http://www.ibm.com/software/tivoli/order-lit/

AccessibilityAccessibility features help users with a physical disability, such as restrictedmobility or limited vision, to use software products successfully. With this product,you can use assistive technologies to hear and navigate the interface. You can alsouse the keyboard instead of the mouse to operate all features of the graphical userinterface.

This product is operated using a Web browser, which has certain built-inaccessibility features, and has been provided with specific shortcut keys fornavigating the Web interface, starting tasks, and performing toolbar actions.

For additional information, see the Accessibility appendix in the IBM Tivoli LicenseManager: License Administrator’s Guide.

Contacting software supportIf you have a problem with any Tivoli product, refer to the following IBM SoftwareSupport Web site:

http://www.ibm.com/software/sysmgmt/products/support/

About this guide xiii

http://www.ibm.com/software/tivoli/library/

http://publib.boulder.ibm.com/tividd/td/IBMTivoliLicenseManager1.1.html



http://www.ibm.com/software/tivoli/order-lit/

http://www.ibm.com/software/sysmgmt/products/support/

If you want to contact software support, see the IBM Software Support Guide at thefollowing Web site:

http://techsupport.services.ibm.com/guides/handbook.html

The guide provides information about how to contact IBM Software Support,depending on the severity of your problem, and the following information:v Registration and eligibilityv Telephone numbers and e-mail addresses, depending on the country in which

you are locatedv Information you must have before contacting IBM Software Support. You can

use the statusinfo command to assemble log and configuration information. See“Using the statusinfo command to collect error information” on page 77.

Conventions used in this guideThis guide uses several conventions for special terms and actions, and operatingsystem-dependent paths.

Typeface conventionsThis guide uses the following typeface conventions:

Bold

v Lowercase commands and mixed case commands that areotherwise difficult to distinguish from surrounding text

v Interface controls (check boxes, push buttons, radio buttons, spinbuttons, fields, folders, icons, list boxes, items inside list boxes,multicolumn lists, containers, menu choices, menu names, tabs,property sheets), labels (such as Tip:, and Operating systemconsiderations:)

v Column headings in a tablev Keywords and parameters in text

Italic

v Citations (titles of books, diskettes, and CDs)v Words defined in textv Emphasis of words (words as words)v Letters as lettersv New terms in textv Variables and values you must provide

Monospace

v Examples and code examplesv File names, programming keywords, and other elements that are

difficult to distinguish from surrounding textv Message text and prompts addressed to the userv Text that the user must typev Values for arguments or command options

xiv IBM Tivoli License Manager: System Administrator’s Guide

http://techsupport.services.ibm.com/guides/handbook.html

<text> Indicates a variable in a path name. For example, in the path<INSTALL_DIR>\admin\conf, INSTALL_DIR depends on the locationwhere you have installed a Tivoli License Manager component,while \admin\conf is constant.

Operating system-dependent pathsThis guide uses the Windows convention for directory notation.

When using AIX, replace each backslash (\) with a forward slash ( /) in directorypaths.

Note: If you are using the bash shell on a Windows system, you can use the UNIXconventions.

About this guide xv

xvi IBM Tivoli License Manager: System Administrator’s Guide

Chapter 1. Planning a Tivoli License Manager implementation

This chapter provides you with information that will help you to plan theimplementation of Tivoli License Manager. It includes the following sections:v A short overview of the Tivoli License Manager structure. This aims to provide

you with information about the functions of the system components and howthey fit together to form a monitoring infrastructure. See “The licensemanagement infrastructure”.

v A discussion of different implementation scenarios, which provides an exampleof an implementations spread over multiple sites. See “Implementation scenario”on page 5.

v A discussion of the factors you should consider when planning to implementTivoli License Manager in your organization. See “Preparing to implement TivoliLicense Manager” on page 7.

The license management infrastructureThe basis of the license manager infrastructure are the three physical componentsof Tivoli License Manager that can be installed:

Tivoli License Manager agentA license management agent must be deployed on each customer node that isto be monitored by Tivoli License Manager. Each agent performs the followingfunctions:v Performs an inventory of the software installed on the node and forwards

this information to the runtime serverv Identifies the starting or stopping of a software product and communicates

this information to the runtime server so that a license can be assigned orreleased

After an agent is deployed on a node, you can set the agent to automaticallyapply any upgrades that are available on the runtime server.

Tivoli License Manager runtime serverEach Tivoli License Manager installation must have at least one runtime server,and can have several. Each runtime server provides the following facilities:v A repository for information about the software installed on the agents that

the server managesv The capability to assign and release the licenses that are assigned to the

server according to the rules defined for each license poolv The capability to generate and send e-mails to provide notification about

events that have occurred on the server or its agentsv A Web interface that can be used to deploy the agents to nodes that are to

be monitored and to produce real-time reports of usage of software runningon the monitored agents

Tivoli License Manager administration serverEach Tivoli License Manager installation has a single administration server. Itprovides the following facilities:v A central repository of product, license agreement, license usage, inventory,

and customer information

© Copyright IBM Corp. 2001, 2003 1

v A Web interface that can be used to perform license management andadministration tasks and to produce historical reports of license usage andinventory information over time

Tivoli License Manager provides a flexible structure that can be adapted for largeand small installations. Figure 1 shows the three-tiered relationship between thephysical components, which is maintained in all possible implementations, and thefunctions of each component.

Information is passed between the three components at regular intervals, which aredefined in the Tivoli License Manager configuration file. See Appendix B,“Configuration settings”, on page 107.

Information that passes between the administration server and the runtime servercan be encrypted. Information that passes between the runtime server and theagents is not encrypted.

A Tivoli License Manager implementation always has only one administrationserver, where a centralized database of licensing, product, and historical softwareusage and inventory information is maintained. This could be on a customer siteor on an IBM Service Delivery Center (SDC) site.

It is at the runtime server level that an implementation can be expanded to meetthe needs of larger customers. You can install a runtime server component on eachof several computers and allocate monitored nodes to each server. Figure 2 onpage 3 shows an expanded infrastructure with multiple runtime servers.

RuntimeServer

DBMSAdministrationServer

Agents

DBMS

Figure 1. Three-tiered topology of Tivoli License Manager components

License management infrastructure

2 IBM Tivoli License Manager: System Administrator’s Guide

Figure 2 shows that each agent that is deployed on a computer within a customer’senterprise is assigned to a specific runtime server that is registered for thecustomer. Each runtime server receives the license requests from the agents that areassigned to it. However, if a runtime server cannot satisfy a license request from itslicense pools, the agent can contact another runtime server. The range of runtimeservers that an agent can contact is configurable. Possible settings are:v Allow the agent to contact all runtime servers that are registered for the

customer.v Allow the agent to contact runtime servers that have agents in the same

division.v Restrict the agent to its own runtime server.

The default is to allow the agent to contact all servers within the customerenterprise. This structure provides the benefits of improved performance providedby multiple runtime servers without sacrificing license usage efficiency.

Agents are also grouped within divisions. Divisions are administrative units thatgive you the ability to perform operations on a group of agents. For example,inventory scans, which are performed by the agents, are scheduled at divisionlevel; reports can be produced by division; and license pools can be limited toselected divisions.

Figure 3 on page 4 shows an example of the relationship between agents, theirdivisions, and the runtime servers to which they are assigned.

DBMS

Agents

Runtime servers

Administration server

Figure 2. Tivoli License Manager structure with multiple runtime servers


Chapter 1. Planning a Tivoli License Manager implementation 3

The grouping of agents into divisions should reflect the structure of theorganization. For example, there could be a division for each department of acompany. Decisions about how to distribute agents between runtime servers do notneed to reflect the organizational structure. The important factor for these decisionsis performance. Agents should be assigned to a runtime server that is local to themand care should be taken to ensure that the server is not likely to becomeoverloaded because of too many agents attempting to contact it at the same time.For this reason, you should split large divisions between more than one runtimeserver to avoid overloading of the runtime server when an inventory scan of adivision is performed.

The Tivoli License Manager infrastructure includes one other logical component,the customer. The customer is the highest element of the data stored in theadministration server database. All elements of the infrastructure, apart from thecentral administration server, belong to a customer. All runtime servers, divisions,and agents are recorded in the administration server database as the property of acustomer.

Web interfacesTivoli License Manager provides Web interfaces that enable you to access theadministration and runtime servers. You do not need to install client software onthe computers from which you want to access the Web interfaces. All you need is abrowser.

The main Web interface is the password-protected interface on the administrationserver that administrators can use to define the monitoring infrastructure andlicense conditions and to produce historical reports.

The runtime server has a much smaller password-protected interface, whereadministrators can obtain real-time software usage information. The runtime server

Admin

Division

Research

Division

Sales

Division

Figure 3. Distribution of agents between divisions and runtime servers



also hosts a Web page from which end users can deploy the agent software ontheir computers. This page is not password-protected.

Implementation scenarioTo understand the different ways in which Tivoli License Manager can beimplemented to provide a solution to monitoring needs, we can look at anexample of a large company, with several sites in different parts of the world.

Figure 4 shows the structure of a large international company with sites in the US,the UK, and Italy. It illustrates the organization of the workstations that need to bemonitored into a set of meaningful divisions.

Figure 5 on page 6 shows an implementation of Tivoli License Manager designed tomeet the needs of this large company.

ACME Inc.

An international organization with more than

10000 desktops and servers

U.S. Site.

Administration, Research and Development

8000 workstations

Administration Division 80 workstations

Research Division 200 workstations

Development Division 380 workstations

...

–

–

–

Italian Site.

Manufacturing and Sales

1000 workstations

Manufacturing 50 workstations

Sales 40 laptops

...

–

–

U.K. Site.

Help Desk

1000 workstations

Help Desk Division 80 workstations

...

–

Figure 4. Monitoring needs of a large company

Web interfaces


As the largest site and as the site where the administration functions of theorganization are located, the US site has the administration server and associatedDB2 database as well as two runtime servers to which the 8 000 workstations canbe assigned. The administration server database is installed on a separatecomputer, which must have a high-speed connection to the administration servercomputer. A single runtime server is installed at each of the smaller sites, whichhave 1 000 workstations each. Even though it would be possible, in terms ofcapacity, for a single runtime server to cover both of the small sites, each site has alocal runtime server. Runtime servers should be local to the agents they are dealingwith to avoid excessive network traffic, to optimize performance, and for securityreasons.

In this scenario, the three sites are being monitored as a single entity. License poolsthat are applicable to all monitored workstations can be defined, and all softwareusage and inventory information can be included in the same reports.

If the management decide that they would like to separate the licenseadministration and reporting of the sites, each site could be defined as a separatecustomer. This implementation would look exactly the same as the large singlecustomer implementation shown in Figure 5. There is no need to use additionalresources by installing the administration server component on each site. Thecentral administration server would remain on the US site. The difference betweenthe two implementations is in the accessibility of the data stored in theadministration server database. Each customer registered on the administration

RTIT1 RTUK1

Runtime Server1000 workstationsRuntime Server

RTUS2ADMINACMEAdministration

Server

8000 workstations

ACMEDBDB2 Database

Server

1000 workstations

Runtime Server

Runtime ServerRTUS1

U.K. SiteItalian Site

U.S. Site

Figure 5. Tivoli License Manager structure at a large customer

Implementation scenario


server has its own data, including the components that form its monitoringinfrastructure, the software licenses that are defined, and the usage and inventoryinformation that is collected by agents. In the original example, there was onecustomer structure covering the three sites. An administrator logged on to theadministration server Web interface could obtain reports that included data for allthree sites. In the second example, each site is a customer with its own data and nosingle report could include data for more than one of the sites.

Preparing to implement Tivoli License ManagerBefore you start the installation of Tivoli License Manager components, you shouldmake an implementation plan that includes the following tasks:v Identify the workstations that are to be monitored by Tivoli License Manager.v Devise a number of divisions that reflect a meaningful breakdown of the

organization and assign the workstations to the appropriate divisions.

Note: Divisions should not be too large. For performance reasons, it is notadvisable to have a very large number of agents in the same divisionassigned to a single runtime server. A division can be split over more thanone server, but it is not advisable to split it over many.

v Assign a computer for the administration server. Unless there is a runtime serverwith fewer than 1 000 agents assigned, the administration server componentshould be installed on a separate computer.

v Decide whether to install the server DB2 databases on the same computers asthe server components or on different computers. Consider the following:– The probable size of the database

Estimate the database size as 300 MB + a quota for each agent that isdeployed. For the administration server database, estimate the quota as400–500 KB for each agent. For each runtime server database, estimate thequota as 300–400 KB of disk space for each agent that reports to the runtimeserver.

– The speed of accesses to the databasesIf you decide to install a database on a separate computer, ensure that there isa high-speed connection between the server and database computers.

v Decide how many runtime servers are required. You should determine themaximum number of agents that can be assigned to a runtime without reducingperformance to unacceptable levels. See “Determining the number of agents fora runtime server” on page 8.It is advisable for each runtime server to be at the same location as the agentsassigned. This is partly to keep response time when requesting licenses to aminimum and partly for security reasons, as communications between agentsand runtime server are not encrypted. For this reason, if your implementationcovers more than one location, it is advisable to have at least one runtime serverat each location.

v Create a schedule for deploying the agents. For example, create a deploymentcalendar in which each division has a deployment date.When the runtime servers have been installed and the divisions have beencreated, send the schedule to the users, instructing them to deploy the agent atthe stated time, selecting a specified runtime server and division on thedeployment screen.

Implementation scenario


Note: You can check the progress of the scheduled deployments using the Agentoption that is available from the Topology section of the administrationserver Web interface.

v Compile a schedule for performing inventory scans. Scans are performed by theagent and are scheduled by division, so you must plan a date and time for eachdivision.Consider the following when you decide on your schedule:– As far as possible, scans should be scheduled for times when other agent

activity is low.– Scans for divisions that have agents assigned to the same runtime server

should not be scheduled so that they coincide or overlap. See “Estimating theduration of inventory scans” on page 9 for information about how to estimatethe expected duration of an inventory scan. Using the estimated duration, youcan ensure that your schedule avoids the situation where agents in a seconddivision start sending scans to the runtime server before agents in a divisionwith an earlier scheduled time have finished contacting the runtime server.

– Before the information is available for reporting, it must be transferred to theruntime server and then to the administration server.

Note: You create the schedules for inventory scanning on the administrationserver Web interface. This means that some time will elapse between thetime when you record a schedule and the time when the agents can useit. For this reason it is advisable to define the schedule well before thetime at which you want it to start.

Time delays for the transmission of data between Tivoli License Managercomponents are defined in the system.properties configuration file. SeeAppendix B, “Configuration settings”, on page 107.

Determining the number of agents for a runtime serverTests performed have provided a maximum of 5 000 agents for each runtimeserver. The tests were performed in the environment detailed in Table 1. Evaluateyour own maximum by comparing your environment to this one.

Table 1. Test environment

Hardware v Netfinity® 7100

v 2 Intel PIII 700 MHz

v 2 GB RAM

v RAID 5 disks I/O

Software v IBM HTTP Server with the thread pool size = 150

v IBM WebSphere Application Server with a minimum Java™

heap size = 256

Network v LAN subnet 10 MBPS

v Cisco switches 19/24

Tivoli License Managerconfiguration

Default

Usage workload 5 application runs per hour on each agent

Inventory workload 1 500 files per scan

Preparing to implement


In addition to the absolute maximum number of agents for each server, you mustalso take into account the distribution of agents between divisions. The number ofagents within a single division assigned to a single runtime server can be critical tothe performance of the server. This is because the largest load on runtime serveroccurs during the inventory scan, which is scheduled by division. You mustdetermine an acceptable amount of time for an inventory scan of a division to becompleted, for example a working day, and then estimate how many agents in thesame division can be assigned to a single runtime server. See “Estimating theduration of inventory scans”.

Estimating the duration of inventory scansThe agent properties section of the system.properties file for each runtime serverincludes properties that influence the total amount of time required for inventoryscans to be completed by agents and sent to the server. These properties are:

pcInventoryDurationThe amount of time taken to scan a Windows node. The default setting is 120seconds

serverInventoryDurationThe amount of time taken to scan a UNIX node. The default setting is 600seconds

When an inventory scan is scheduled, each agent starts the scan at the specifiedtime. To avoid the situation where all agents attempt to access the runtime serverat the same time, a random delay is applied by each agent before it starts sendingthe scan information. The delay can be anything between 0 seconds and amaximum that is calculated as follows:

(InventoryMaxDelay = pcInventoryDuration * number of Windows agents in thedivision) + (serverInventoryDuration * number of UNIX agents in the division)

InventoryMaxDelay represents the maximum expected duration of the inventoryscan for a division.



Chapter 2. Installing Tivoli License Manager

This chapter provides the information and instructions required to install andconfigure Tivoli License Manager. This information includes:v The platforms on which the components of Tivoli License Manager can be

installed. See “Supported platforms”.v The software and hardware requirements that the computers on which you plan

to install the Tivoli License Manager components should meet. See“Prerequisites”.

v Things that you should do or check before starting the installation. See “Beforeyou start” on page 13.

v Information about upgrading components from version 1.1 to version 1.1.1. See“Upgrading from version 1.1 to version 1.1.1” on page 14.

v Instructions for installing and configuring Tivoli License Manager, including asummary of the steps involved and detailed instructions for performing eachstep. See “Installing and setting up Tivoli License Manager” on page 16.

v Instructions for uninstalling Tivoli License Manager. See “Uninstalling TivoliLicense Manager” on page 31.

Supported platformsTivoli License Manager servers can run on Windows and AIX® platforms. Agentscan be deployed on a range of Windows and UNIX platforms. Catalog managercan run on the same platforms as the servers.

For full details of the supported platforms and of the version and fix pack levelthat is required for a Tivoli License Manager component, see the IBM Tivoli LicenseManager: Release Notes.

PrerequisitesTable 2 on page 12 shows the software, hardware, and space requirements for theinstallation of the Tivoli License Manager components.


Table 2. Tivoli License Manager installation prerequisites

Component Prerequisite Type Prerequisites

Tivoli LicenseManageradministrationand runtimeservers

Database client v IBM DB2 Universal Database, Enterprise Extended Edition 7.2.5runtime client

This is required on the server computer if the DB2 server is installed ona different computer. If the server and database are installed on the samecomputer, the computer must have the prerequisites listed for the DB2databases.

Web server One of the following:

v IBM HTTP Server version 1.3.12.6 (packaged with IBM WebSphereApplication Server 3.5.6)

v IBM HTTP Server version 1.3.19.3 (packaged with IBM WebSphereApplication Server 4.0.4)

v Microsoft® IIS version 5.0 (packaged with Windows 2000 Server)

Web application server One of the following:

v IBM WebSphere Application Server Advanced Edition version 3.5.6

v IBM WebSphere Application Server Advanced Edition version 4.0.4

Internet browser One of the following:

v Microsoft Internet Explorer 5.5 or higher

v Netscape Navigator 6.2 or higher

CPU One of the following:

v Intel Pentium® IV 1.5 GHz or equivalent

v IBM RS/6000® (7044 recommended)

Memory v 1 GB minimum

Space v 100 MB

In addition, on AIX platforms there must be at least 100 MB of free spacein the /tmp directory.

DB2 databasesfor theadministrationand runtimeservers

Database server v IBM DB2 Universal Database, Enterprise Extended Edition 7.2.5

CPU One of the following:

v Intel Pentium IV 1.5 GHz or equivalent

v IBM RS/6000 (7044 recommended)

Memory v 1 GB minimum

Space 300 MB + a quota for each agent supported.

For the administration server database, estimate the quota per agent as400–500 KB. For each runtime server database, estimate the quota peragent as 300–400 KB.

In addition, on AIX platforms there must be at least 100 MB of freespace in the /tmp directory.

Tivoli LicenseManagercatalogmanager

Space v 50 MB

In addition, on AIX platforms there must be at least 100 MB of freespace in the /tmp directory.

Prerequisites


Table 2. Tivoli License Manager installation prerequisites (continued)

Component Prerequisite Type Prerequisites

Tivoli LicenseManager agent

Internet browser One of the following:

v Microsoft Internet Explorer 5.0 or higher

v Netscape Navigator 4.7.x or higher

Notes:

1. For agents running on Sun platforms, you can use only NetscapeNavigator.

2. On AIX, Netscape Navigator 4.79 is recommended.

Space v 10 MB for installation; over time, more space could be required if youuse trace.

Notes:

1. If you plan to install the administration server on an AIX platform, the servercomputer must have access to an X display server. See Appendix E,“Connecting to an X display server”, on page 123 for information aboutchecking for the connection to the X display server and instructions on makingthe connection if it does not exist.

2. If possible, you should use the Java Database Connection (JDBC) driver 2.0, asit provides advanced database capabilities (query optimized execution, datasources) that are not available with the version 1.2 driver. This version is aprerequisite of WebSphere Application Server 4.0, but not of WebSphereApplication Server 3.5.6. If you are using WebSphere Application Server 3.5.6,you should switch to the JDBC driver 2.0. Instructions for this task areprovided in the DB2 documentation.If you cannot switch to the JDBC driver 2.0, you can run Tivoli LicenseManager with the JDBC driver 1.2, though performance and scalability could beaffected. If you want to do this, you must change the setting of thedbPoolerImplementation property in the db.properties file for each installeddatabase to internal. See “The db.properties file” on page 113.

Before you startBefore you start the installation, do the following:v Decide on how you intend to configure your system topology, for example, how

many runtime servers you are installing and on which computers. For moreinformation and examples, see Chapter 1, “Planning a Tivoli License Managerimplementation”, on page 1.

v Check that the computers on which you plan to install the Tivoli LicenseManager components meet the installation prerequisites. See “Prerequisites” onpage 11.

Notes:

1. You should install DB2 before installing WebSphere Application Server.2. If you install the DB2 server on the AIX platform and you are going to install

both the server and database on this computer, make sure that the /home filesystem is at least 10 GB, as the DB2 databases will be hosted in this partition.You can extend the file system size using an AIX configuration tool, forexample, smitty.

3. You can install and configure the IBM HTTP server using the WebSphereApplication Server Quick Installation option. If you want to use thismethod, ensure that no other Web server is running before you start

Prerequisites

Chapter 2. Installing Tivoli License Manager 13

WebSphere Application Server. If you want WebSphere Application Server touse a different Web server, choose the WebSphere Application Server CustomInstallation option and follow the instructions.

4. If you are planning to use secure sockets layer (SSL) for communicationsbetween the administration and runtime servers and between Web browsersand the SSL servers, the IBM HTTP server must be installed with the SSLoption turned on.

v Adjust the time and time zone settings on each computer where you plan toinstall a server component. It is not advisable to change these settings whenTivoli License Manager is in use.

v Start DB2 services on the DB2 servers.v Start WebSphere Application Server on the computers where you plan to install

the Tivoli License Manager servers. For instructions on starting WebSphereApplication Server, see “Starting and stopping the WebSphere ApplicationServer” on page 122.

v Ensure that you have the following information:– The password that is to be assigned to the tlmsrv user for communications

between the Tivoli License Manager server and its DB2 database.– The exact names with which you intend to register the runtime servers you

are installing.– The password that is to be used for communications between each runtime

server and the administration server.– The exact name of the customer for whom runtime servers are being installed.

If you are adding a runtime server for an existing customer, ensure that thisname is exactly the same as the name under which the customer has beenregistered on the administration server Web interface.

– The host name of the computer where the Tivoli License Manageradministration server is installed or will be installed.

v If you are installing a server component in a double-byte character set (DBCS)environment, ensure that the primary language environment settings (culturalconventions, language, and keyboard) are correct. Incorrect settings can result incommunications failures between the administration and runtime servers andbetween runtime servers and agents.

v If the WebSphere Administrator’s Console is set up as password-protected,obtain a valid user name and password. This will be requested during theinstallation process.

Upgrading from version 1.1 to version 1.1.1If you have version 1.1 of the Tivoli License Manager servers, agents, anddatabases installed, note the following:v You do not need to uninstall version 1.1 before installing the new version.v The installation wizard will not ask for a destination directory. It will

automatically install components in the destination directory where thecomponent is currently installed.

v The installation process identifies each existing configuration file that has beenchanged, and asks whether the file is to be retained or overwritten.

v To migrate a database from version 1.1 to version 1.1.1, install and run the newversion of the dbsetup script on the database computer.

Note: Create a backup before migrating any database.

Before you start


v The upgrade process is the same whether or not you have installed patch1.1-TLM-0001 (which upgrades Tivoli License Manager version 1.1 to version1.1.0.10). If you have not installed the patch, there may be a consideration aboutuse of the catalog manager, as explained under “Catalog manager upgradeconsiderations”.

Upgrade stepsTo upgrade Tivoli License Manager version 1.1 servers, agents, and databases toversion 1.1.1, complete the following steps:1. Stop all runtime servers and then stop the administration server.2. Use the installation wizard to install the version 1.1.1 administration server and

database components.For instructions on using the installation wizard, see “Installing Tivoli LicenseManager components” on page 17.

3. Run the dbsetup script on the administration server database computer.For instructions on running the database setup scripts, see “Creating a DB2database for Tivoli License Manager” on page 24.

Note: If you want to perform the upgrade over several days, you can nowrestart the administration and runtime servers. The version 1.1 runtimeservers can communicate with the version 1.1.1 administration server.You must upgrade the administration server first because theadministration server must always be at the same version as the runtimeservers or higher.

4. For each runtime server and database, use the installation wizard to installversion 1.1.1 of the runtime server and database components.

5. Run the dbsetup script on each runtime server database computer.6. Start the administration server.7. To upgrade the agents, follow the instructions in “Automatic upgrade of

agents” on page 50.8. Start the runtime servers.

You can stop and start Tivoli License Manager servers from the WebSphereAdministrator’s Console or by using the srvstop and srvstart commands from theTivoli License Manager command line. See Chapter 4, “The command lineinterface”, on page 41.

Catalog manager upgrade considerationsIf you have exported a copy of the master catalog and you are using catalogmanager version 1.1 to update it, you may not be able to work on the same copywith catalog manager version 1.1.1. This incompatibility will arise only if youexported the catalog before you installed patch 1.1-TLM-0001, or if you did notinstall the patch.

In this case, use the impcat command to update the master catalog with anychanges you have already made. You can do this step before or after the upgradeto version 1.1.1. Then export a new working catalog from the master catalog beforeyou use catalog manager version 1.1.1. To update the master catalog, see theinstructions in IBM Tivoli License Manager: License Administrator’s Guide, GC23-4833.

To check whether patch 1.1-TLM-0001 has been installed, check the level of theproduct in <INSTALL_DIR>/product.xml.

Upgrading to 1.1.1


Upgrading WebSphere Application ServerIf you have WebSphere Application Server 3.5.6 installed on any of your TivoliLicense Manager server computers, you may wish to upgrade to version 4.0.4.

If you decide to upgrade your WebSphere Application Server version as part of theprocess of upgrading to Tivoli License Manager 1.1.1, you must do the upgrade ofTivoli License Manager first to update configurations. However, the Tivoli LicenseManager server must be uninstalled before WebSphere Application Server can beupgraded.

To perform the upgrade of WebSphere Application Server together with theupgrade of a Tivoli License Manager server, complete the following steps.1. Upgrade the Tivoli License Manager server. See “Upgrading from version 1.1 to

version 1.1.1” on page 14.All configuration files that include settings that are not defaults are saved.Configuration files are installed in the following locations:

administration server<INSTALL_DIR>\admin\conf

runtime server<INSTALL_DIR>\runtime\conf

2. Copy the configuration files except for db.properties to a different location.

Note: The db.properties file includes only one setting that can be changed,dbPoolerImplementation. This setting controls the pooler connectionbetween the DB2 database and the Tivoli License Manager server. WhenWebSphere Application Server 4.0.4 is in use, the default setting Externalis correct. For this reason, the configuration file that will be installedwhen you reinstall Tivoli License Manager should be used.

3. Uninstall the Tivoli License Manager server.Do not drop the database that is associated with the server.

4. Upgrade WebSphere Application Server to version 4.0.4.5. Reinstall the Tivoli License Manager server.

Note: If you completed the upgrade process as described, including themigration of the database, do not run the database setup script again.

6. Overwrite the new configuration files with the copies that you saved.

Installing and setting up Tivoli License ManagerTo install Tivoli License Manager and make it ready for use, you must completethe following tasks:1. Install the administration server, runtime server, and catalog manager

components on the computers you have selected. See “Installing Tivoli LicenseManager components” on page 17.

2. Create and populate the DB2 databases for the administration server andruntime servers you have installed. See “Creating a DB2 database for TivoliLicense Manager” on page 24.

3. Set parameters for event notification in the system.properties file of eachTivoli License Manager server. See “Defining notification settings for a server”on page 28.

Upgrading WebSphere Application Server


4. Start the server components that you have installed. See “Starting a TivoliLicense Manager server component” on page 29.

5. Enable SSL on the administration server and configure the runtime server as anSSL client. See Chapter 3, “Enabling secure communications”, on page 35.

Note: This step is optional. When you install a runtime server, you can chooseto use SSL for secure communication. If you choose not to, you can omitthis step.

6. Use the Tivoli License Manager Web interfaces to create the structure requiredfor each customer. See “Setting up Tivoli License Manager” on page 30.

Note: “Validating the installation” on page 73 describes a series of steps you cantake to check that the installation of the server and database components hasbeen successful and that Tivoli License Manager is ready for use.

Installing Tivoli License Manager componentsTivoli License Manager provides a single installation wizard that can be used onall supported platforms. The setup file is:

Windows setupwin32.exe

AIX setupaix.bin

Using the installation wizard, you can do the following:v Install or upgrade the Tivoli License Manager administration and runtime server

components and configure WebSphere Application Server for these servers.When the installation wizard detects a Tivoli License Manager 1.1 componentinstalled on a computer, it automatically runs in upgrade mode. No values arerequested for any of the options that are available when installing for the firsttime, for example, installation location, runtime server name and password. Ifyou want to install an additional component on a computer where an upgrade isrequired, you must run the wizard once to upgrade existing components andthen run the wizard again to add the new component.

v Install or upgrade the Tivoli License Manager catalog manager.v Copy the scripts for creating and populating the DB2 databases for the

administration and runtime servers to the computers where the databases are tobe located.

Using the installation wizard in silent modeWhen the installation wizard runs in silent mode, it takes the parameters itrequires from an InstallShield options file. The options file, recordFile.txt, isprovided with Tivoli License Manager. You must edit this file to provide the valuesfor parameters that the wizard must set.

To launch the installation wizard in silent mode, launch the setup command withthe following arguments:

-options ″.\recordFile.txt″ -silent

You may find this option useful if you are installing a large number of runtimeservers and databases on different computers, as you can use the same options fileon all computers, changing only a small number of parameters, for example, theruntime server name.

Installation and setup


See Appendix C, “Options file for silent installations”, on page 117 for a fulldescription of the recordFile.txt file.

Using the installation wizard in interactive modeTo install a Tivoli License Manager server and configure WebSphere ApplicationServer for the server, complete the following steps:1. Log on to the computer where you want to install Tivoli License Manager

components as a user with administrative rights (Administrator on Windowsplatforms or root on AIX platforms).

2. Launch the setup file for Tivoli License Manager. On Windows platforms, youshould start the wizard using the Add/Remove Program function that isavailable from the control panel. On AIX platforms, the name of the directoryfrom which you launch the setup file, and the names of any directories in thepath to that directory, must not contain blanks.On AIX platforms, if you get the message:Unable to load the launcher file index. Cannot open launcher file.

then you are not logged on as root. Log on as root and try again.

The wizard starts and requests you to select the language version of TivoliLicense Manager that you want to install.

The initial panels include a welcome panel and the license agreement. Youmust select the radio button to accept the license agreement before you canproceed by clicking Next.

The next panel enables you to select the installation location.



3. Accept the default location displayed or click Browse to select a differentlocation. Click Next.

4. Select the type of installation you want for this computer. There are threeoptions:

AdministrationInstalls the administration server, its database, and the catalog manager onthe computer.

RuntimeInstalls the runtime server and its database on the computer.

CustomEnables you to choose the components that are to be installed.

5. Click Next.



If you chose a custom installation, the following panel appears:

6. Clear the check boxes of components that you do not want to install and clickNext.

Note: Unless the runtime server is to support a small number of agents(fewer than 1 000), you should not install a runtime server and theadministration server on the same computer.

If you are installing a database on an AIX platform, the following panelappears:



7. Accept the default location for the DB2 instance owner or click Browse toselect a different location.

8. Click Next to move to the next panel.If you chose to install the administration server, runtime server, or a database,the following panel appears.

9. Enter and confirm the password to be used to access the DB2 database that isassociated with the server component you are installing.The password has a maximum length of 8 characters and can contain only thefollowing characters:A-Z, a-z, 0-9, +, -, =During installation the user tlmsrv is created with a password set to thisvalue.

Note: If you install the administration and runtime server components on thesame computer, this password is valid for both databases.

This is true when you install the components in a single installationand when you install one first and then run the wizard again to installanother. If a component has already been installed on the computer,and the tlmsrv user has already been created, the panel that appearshas a single text box asking you to confirm the password that wasspecified during the first installation.



If you chose to install the runtime server component the following panelappears:

10. Specify information to identify the runtime server, as follows:a. Identify the customer for which the runtime server is being installed.

If the administration server has already been installed and customerrecords have been created using the administration server Web interface,you must be sure that the name you specify exactly matches the customername registered on the interface. Otherwise, you must create a customerwith this name when the administration server Web interface is available.

b. Specify a name for the runtime server that has not already been assignedto a runtime server for the same customer.

c. Specify and confirm the password to be used to authenticate this runtimeserver in communications with the administration server.The password has a maximum length of 8 characters and can contain onlythe following characters:A-Z, a-z, 0-9, +, -, =

Note: These settings are used to authenticate communication between theruntime server and the administration server. You must be careful toenter them correctly, both here and when you later register the runtimeserver on the administration server Web interface. If there is anydiscrepancy between the values entered when installing and registeringthe server, the runtime server cannot be plugged in to theadministration server.



11. Click Next.

12. Specify information to enable the runtime server to communicate with theadministration server. To do this:a. Identify the host computer of the administration server by entering the

host name or the IP address in the Administration server address field.Only US ASCII characters can be used.

b. Specify the number of the port to be used in the Port field. The default forunencrypted communications is 80. For secure (SSL) communications,enter 443.

c. Choose the appropriate radio button to specify whether communicationswith the administration server, initiated by this runtime server, should beencrypted.

d. If you choose Yes, enter the SSL Password and confirm it.The password has a maximum length of 8 characters and can contain onlythe following characters:A-Z, a-z, 0-9, +, -, =Following installation, you must follow the instructions given in Chapter 3,“Enabling secure communications”, on page 35 to enable theadministration server for SSL and complete the configuration of theruntime server as an SSL client.

13. A panel appears confirming the selections you have made and the sizing ofthe installation.

14. Click Next to start the installation.15. When the installation process is complete, a confirmation panel appears. Click

Next to continue.



If you are installing one or more server components, the following panelappears.

16. Make sure that WebSphere Application Server is running.If WebSphere Application Server is not running when you click Next, theWebSphere Application Server configuration will fail and you will need tomanually run the WebSphere Application Server configuration script. SeeTable 24 on page 83 for a list of the WebSphere Application Serverconfiguration scripts for each platform, WebSphere Application Server version,and server type.

17. Click Next.The install wizard configures WebSphere Application Server to recognize theTivoli License Manager server.

18. When the WebSphere Application Server configuration is complete, clickFinish to exit the wizard.

Creating a DB2 database for Tivoli License ManagerFor each Tivoli License Manager server you install, you must create an associateddatabase. You can create the Tivoli License Manager DB2 database on Windowsand AIX platforms. You can create a database on the same computer as theassociated Tivoli License Manager server, or the database and server can be onseparate computers.

Note: The process for creating a database and for migrating from an existingversion 1.1 database to version 1.1.1 is the same. If no database exists, a newdatabase is created. If a version 1.1 database is detected, it is migrated to1.1.1.

Communication is automatically established between the database and the serverwhen both are installed on the same Windows computer. When the database andserver are installed on different computers or when they are installed on the sameAIX computers, additional steps are required to establish communication.



Instructions for creating the databases and for establishing communications in allsupported configurations are provided under the following headings:v “Creating and populating a database on Windows”v “Creating and populating a database on AIX”v “Connecting a database to a Tivoli License Manager server on an AIX computer”

on page 27.v “Connecting a database to a Tivoli License Manager server on a Windows

computer” on page 26.

You should also consult the DB2 Quick Beginnings guides for more informationabout methods of connecting to databases.

Creating and populating a database on WindowsWhen you choose the option to install a database to be associated with a TivoliLicense Manager server, the installation wizard creates the folder:

Administration server<INSTALL_DIR>\admin\db\db2

Runtime servers<INSTALL_DIR>\runtime\db\db2

These folders each contain a script for creating and populating a DB2 database.You must launch this script on the computer where the DB2 server is installed tocreate and populate the DB2 database.

To create and populate the database, complete the following steps:1. Log on to the DB2 server computer as Administrator or as a DB2 administrator

(for example db2admin).2. From the Start menu, open the DB2 command window.3. Change to the DB2 directory:

Administration server<INSTALL_DIR>\admin\db\db2

Runtime servers<INSTALL_DIR>\runtime\db\db2

and enter the command:

dbsetup.bat

If the server and the DB2 database are installed on the same computer or if youare upgrading a database, the database creation is now complete.

If the server is on a different Windows computer, complete the steps described in“Connecting a database to a Tivoli License Manager server on a Windowscomputer” on page 26.

If the server is on an AIX computer, complete the steps described in “Connecting adatabase to a Tivoli License Manager server on an AIX computer” on page 27.

Creating and populating a database on AIXWhen you choose the option to install a database to be associated with a TivoliLicense Manager server, the installation wizard creates the folder:



Administration server<INSTALL_DIR>/admin/db/db2

Runtime servers<INSTALL_DIR>/runtime/db/db2

These directories each contain a script for creating and populating a DB2 database.You must launch this script on the computer where the DB2 server is installed tocreate and populate the DB2 database.

To create and populate the database complete the following steps:1. Log on to the DB2 server computer as root.2. Switch to DB2 instance owner, typically db2inst1. To do this, enter the

command:su - db2inst1

3. Check that the DB2 command line is initialized. To do this, enter the command:db2

You should see the DB2 Command Line Processor. Type quit to exit and returnto the UNIX shell.

4. If the DB2 command line is not initialized, you must load the DB2environment. To do this, change to directory /home/db2inst1/sqllib and enterthe command:. ./db2profile

5. Change to the DB2 directory:

Administration server<INSTALL_DIR>/admin/db/db2

Runtime servers<INSTALL_DIR>/runtime/db/db2

and enter the command:

. ./dbsetup.sh

If you are installing a new database, not upgrading an existing one, you must nowestablish the connection between the database and the Tivoli License Managerserver. The way you do this depends on where the server is installed, as follows:v If the server is installed on the same computer or on another AIX computer,

follow the instructions in “Connecting a database to a Tivoli License Managerserver on an AIX computer” on page 27.

v If the server is installed on a Windows computer, follow the instructions in“Connecting a database to a Tivoli License Manager server on a Windowscomputer”.

Connecting a database to a Tivoli License Manager server on aWindows computerIf the server is installed on a Windows platform and the database is installed on adifferent Windows or AIX computer, complete the following steps:1. Log on to the system where the Tivoli License Manager server is installed.2. Run the DB2 Client Configuration Assistant.3. Click Add and select Search the network.4. Find the DB2 server computer and select the Tivoli License Manager server

database from the list of local databases.



5. In the ODBC folder, clear the check box Register this Database for ODBC.6. Click Finish.

Connecting a database to a Tivoli License Manager server on anAIX computerFollow these instructions for a database on any platform that is associated with aTivoli License Manager server that is installed on an AIX platform.

Note: This includes the situation were the server and database are installed on thesame AIX computer.

1. Log on to the computer where the DB2 server is installed as a user withadministrative rights (Administrator or a DB2 administrator on Windowsplatforms or root on AIX platforms).

2. Using a text editor, open one of the following files:

AIX/etc/services

WindowsC:\winnt\system32\drivers\etc\services

and search for a row with the following information:<service> <port>/tcp # Connection port for DB2

If there is more than one entry like this, find the latest entry.3. On AIX, note the <service> value.

On Windows, note the <port> value.4. Log on as the DB2 instance owner to the system where the Tivoli License

Manager server is installed.5. Load the DB2 environment. To do this, change to the DB2 home directory, for

example, /home/db2inst1/sqllib, and enter the command:. ./db2profile

6. Enter commands as follows:If the database is on the same computer as the server:db2 catalog tcpip node tlmnode remote 127.0.0.1 server <noted value>

db2 catalog database <database name> as <cataloged name> at node tlmnode

If the database and server are on different computers:db2 catalog tcpip node tlmnode remote <host> server <noted value>

db2 catalog database <database name> as <cataloged name> at node tlmnode

where the values of the variables are as follows:

hostThe host name or IP address of the computer where the DB2 server isinstalled.

noted valueThe value you found in the services file. This is a port number if the DB2server is on a Windows computer, and a service name if the DB2 server ison an AIX computer.

database nameThe name of the database: tlma for the administration server database ortlmr for a runtime server database.



cataloged nameThe name used to catalog the database: tlmadb for the administrationserver database or tlmrdb for a runtime server database.

Defining notification settings for a serverTo use event notification you must specify who is to receive notifications anddefine settings that allow the notifications to be automatically sent.

Each Tivoli License Manager server has its own settings that control the sending ofnotifications. You define the parameters to be used to send notifications in thesystem.properties file for each server.

Note: If you start the Tivoli License Manager server before you define notificationsettings or if you change notification settings, you must stop the server andrestart it before the settings take effect.

The following is an example of the Mail Settings section of the system.propertiesfile.#Mail SettingssmtpServer=mailserv120.ibm.commailEngine=InternalmailRecipient=jsmith@[email protected]

To define notification settings for a server, complete the following steps:1. Log on to the computer where the administration or runtime server is installed.2. Open the system.properties file in a text editor.

The location of the system.properties file is as follows:

Administration server<INSTALL_DIR>\admin\conf

Runtime server<INSTALL_DIR>runtime\conf\

Note: If the administration server is installed on the same computer as aruntime server, system.properties files exist in both locations. You mustdefine settings in both files to enable both types of notification.

3. In the#Mail Settings section of the file, define the properties as follows:

smtpServerEnter the host name or IP address of a valid Simple Mail Transfer Protocol(SMTP) server. This server will be used to forward the e-mailcommunications generated by the notification component of the server.

mailRecipientYou can enter the e-mail address to which notifications are to be sent. Thissetting is optional because you can set up Tivoli License Manageradministrators to receive notifications using the Web interfaces.

mailSenderEnter the e-mail address that is to be used by the server as the senderaddress when notifications are generated. This must be a valid e-mailaddress.

4. Save the file and close it.



Note: No e-mails are generated if the settings for the SMTP server and the mailsender are not present or not valid.

Starting a Tivoli License Manager server componentWhen you have installed the administration server or runtime server componenton a computer, you must activate the server using WebSphere Application Server.

To activate a server, complete the following steps:1. Start the WebSphere Administrator’s Console on the computer where the Tivoli

License Manager server is installed.

Note: On AIX, you can open the WebSphere Administrator’s Console byopening a shell window, then changing to directory:

/usr/WebSphere/AppServer/bin

and entering the command:

./adminclient.sh

2. In the navigation pane, navigate to the computer where you installed theserver.

3. Select the IBM Tivoli License Manager Administration Server or IBM TivoliLicense Manager Runtime Server item from the list of application servers, andclick the Play icon on the task bar.

Notes:

a. If the server is not included in the list of application servers, the installationor the WebSphere Application Server configuration has failed. Consult theinstall.log file for details of the failure.If the server has installed successfully but the WebSphere ApplicationServer configuration failed, you must manually run the configuration script.See Table 24 on page 83 for a list of the WebSphere Application Serverconfiguration scripts for each platform, WebSphere Application Serverversion, and server type.

b. The Tivoli License Manager WebSphere Application Server configurationscript configures port 9085 for the administration server and 9086 for aruntime server. If the chosen port is already used by WebSphere ApplicationServer, an exception message appears and you cannot start the server. Theprocedure for resolving this is described in “Common problems” onpage 80. See the items listed under “Servers” on page 80.

c. If you are using WebSphere Application Server 3.5.6 on AIX, you need toclear the working directory on the administration console for both the TivoliLicense Manager servers; otherwise you cannot start them, because of aknown problem with WebSphere Application Server.

4. Check that the name of the computer is included in the list of WebSphereApplication Server host aliases.To add aliases, open the WebSphere Application Server console, select Virtualhosts/default_host, click General, and add any necessary aliases.

Notes:

a. You must include the name as a simple host name, for example, alpha, andas a fully qualified host name, for example, alpha.rome.ibm.com.



b. If you are using IP addresses, rather than host names, to identify the serverhosts, make sure that the IP address is included in the list of aliases, asdescribed above.

c. If the server is not using the default port (80), you must append the portnumber to the server name in all aliases you create, for example,alpha.rome.ibm.com:443.

Setting up Tivoli License ManagerAt this point, you can log on to the Tivoli License Manager Web interfaces and usethe functions available to set up a monitoring structure for the site or sites that youare responsible for.

Notes:

1. “Validating the installation” on page 73 describes a series of steps you can taketo check that the installation of the server and database components has beensuccessful and that Tivoli License Manager is ready for use.

2. You can access the Web interfaces from any computer that can connect to theWeb administration and Web runtime servers using one of the followingbrowsers:v Internet Explorer 5.5 or higherv Netscape Navigator 6.2 or higher

The browsers must be enabled for JavaScript™ and any programs that preventadditional windows from opening automatically must be disabled.

See IBM Tivoli License Manager: License Administrator’s Guide for instructions onusing the Web interfaces.

Before you can start metering software usage, you must perform the followingtasks on the Tivoli License Manager Web interfaces:v Log on to the administration server as user tlmroot and create customer records

and administrators to manage their Tivoli License Manager environment, licenseentitlement, and reporting and to receive license management notifications.

Note: The initial password for user tlmroot is system. You should change this assoon as possible after the initial use, using the Administration Accountsfunction on the administration server Web interface.

v Make any necessary changes to the runtime server configurations. If you areusing proxies for communications between runtime servers and theadministration server or between runtime servers and agents, you must definethe proxies in the runtime server configuration files. See Appendix B,“Configuration settings”, on page 107.

v For each customer, log on to the administration server, using the AdministratorID and password for the customer. Register the runtime servers with theadministration server and create divisions.

v Check that the servers have correctly plugged in. If a server has not plugged in,refer to the event log file (event#n.log) on the administration where the reasonfor failure is reported. The event.log file is located in the<INSTALL_DIR>\admin\log folder.

v Schedule inventory scans for each division you have created.



v Log on to each node that you want to monitor as a user with administrationrights. Deploy the Tivoli License Manager agent from the agent registration pageof a runtime server that is registered for the customer and that has successfullyplugged in.

v Log on to each runtime server as user tlmroot and create accounts foradministrators who will be able to request reports and receive notificationsabout events that occur on the runtime servers.

Uninstalling Tivoli License ManagerThis section includes instructions for uninstalling the following components ofTivoli License Manager:v The Tivoli License Manager servers and catalog manager.v The DB2 databases that are associated with the servers.v The Tivoli License Manager agent.

Uninstalling the Tivoli License Manager servers and catalogmanager

You run the Tivoli License Manager multiplatform uninstall wizard on a computerfrom which you want to remove a Tivoli License Manager server or the catalogmanager.

The wizard enables you to select the components you want to remove and tospecify whether configuration files should be removed. If you choose to remove aserver component, the wizard can also remove the WebSphere Application Serverconfigurations for the server, provided that WebSphere Application Server isrunning when you run the wizard.

It does not remove the following:v The tables and data in the DB2 databases that are associated with the server

components.v Tivoli License Manager log files.

To uninstall Tivoli License Manager server components from a computer, completethe following steps:1. Start the uninstall wizard.

Windows uninstaller.exe

AIX uninstaller.bin

The wizard is located in the folder <INSTALL_DIR>\_uninst.

Note: On AIX platforms, there is a folder called deinst. This folder is not theuninstall folder. It contains files used in the uninstallation.

On Windows, you should start the wizard using the Add/Remove Programsfunction that is available from the control panel.

2. The wizard detects the components that are present on the computer. Deselectany that you do not wish to uninstall.

3. When the uninstall is complete, delete the folder where Tivoli License Managerwas installed, to ensure that all deleted logs and data are removed from the filesystem.



Dropping the Tivoli License Manager databases on WindowsTo drop a Tivoli License Manager database on a Windows platform, complete thefollowing steps:1. Log on to the DB2 server computer as Administrator or as a DB2

administrator, for example db2admin.2. Open a DB2 command window.3. Enter the command:

db2 drop database <database name>

where <database name> is tlma for the administration server database or tlmrfor the runtime server database.

Dropping the Tivoli License Manager databases on AIXTo drop a Tivoli License Manager database on an AIX platform, complete thefollowing steps:1. If the DB2 server is installed on a different computer, log on to that computer

as a DB2 administrator, for example db2inst1, and load the DB2 environmentas described in step 3 under “Disconnecting a database from a Tivoli LicenseManager server on an AIX computer”.

2. On the DB2 server computer, drop the database by entering the command:db2 drop database <database name>

Where <database name> is tlma for the administration server database or tlmrfor the runtime server database.

Disconnecting a database from a Tivoli License Managerserver on a Windows computer

If the server is installed on a Windows platform and the database is installed on adifferent Windows or AIX computer, complete the following steps:1. Log on to the system where the Tivoli License Manager server is installed.2. Run the DB2 Client Configuration Assistant.3. Select the Tivoli License Manager server database (tlmadb or tlmrdb) from the

list of databases.4. Click Delete and then OK.

Disconnecting a database from a Tivoli License Managerserver on an AIX computer

To disconnect a database on any platform from a Tivoli License Manager server onAIX, complete the following steps:1. Log on to the computer where the Tivoli License Manager server was installed

as the DB2 administration user, for example db2inst1.2. Open a shell window.3. If the DB2 command line is not initialized, you must load the DB2

environment. To do this, change to directory /home/db2inst1/sqllib and enterthe command:. ./db2profile

Uninstalling


4. On the computer where the Tivoli License Manager server linked to thisdatabase is located, uncatalog the database, using the command:

Administration serverdb2 uncatalog database tlmadb

Runtime serversdb2 uncatalog database tlmrdb

5. Uncatalog the node, using the command:db2 uncatalog node tlmnode

Uninstalling the agentTo uninstall the Tivoli License Manager agent from a Windows node, complete thefollowing steps:1. On the node where the agent is installed, open a command prompt window.2. Change to the directory:

%windir%\itlm

3. Enter the command:tlmunins.bat

To uninstall the Tivoli License Manager agent from a UNIX node, complete thefollowing steps:1. On the node where the agent is installed, open a shell window.2. Change to the directory:

/var/itlm

3. Enter the command:./tlmunins.sh

Uninstalling


Uninstalling


Chapter 3. Enabling secure communications

SSL secure communications is available for communications between theadministration and runtime servers and for communications between Webbrowsers and the Tivoli License Manager servers.

To enable and use secure communications, you must do the following:v Use the HTTPS protocol instead of the HTTP protocol. See “Using the HTTPS

protocol”v Ensure that the Web server installed on the Tivoli License Manager server

computer you are configuring is enabled for SSL. On IBM HTTP servers, youensure that an SSL-enabled virtual host definition is present in the configurationfile, httpd.conf. See “Enabling SSL for IBM HTTP Server” on page 36.If you use the Microsoft IIS Web server, refer to the IIS documentation forinstructions on configuring a server for SSL communications.

Note: When you configure SSL on the IBM HTTP Server or the Microsoft IISWeb server, set the highest level of security. This ensures thatcommunications are not only validated using the trusted certificate butare also encrypted. For lower levels of security, encryption might not beapplied.

v Update the list of WebSphere Application Server host aliases on theadministration and runtime server computers to include aliases for SSL ports.See “SSL port aliases” on page 38.

v Update key.jks to register your trusted certificate. See “Adding a servercertificate to the trusted store” on page 37.

If you have enabled secure communications but you want to switch to nonsecurecommunications, see “Disabling secure communications” on page 39.

Using the HTTPS protocolFor secure communications, use the secure protocol HTTPS instead of HTTP.

For communications between Web browsers and the Tivoli License Managerservers, this is done by using HTTPS when addressing the logon pages of theserver interfaces as follows:

Administration serverhttps://<server name>:<port>/slmadmin/login

Runtime serverhttps://<server name>:<port>/slmruntime/login

For communications with the administration server, a runtime server uses thevalue held in the adminpath property in the scp.properties file in the followingformat:adminpath = http://<server name>:<port>/slmadmin/service

It is the address and port to be used for communications with the administrationserver. If the server is installed with SSL enabled, this address starts with https andthe port is the secure port 443. If SSL was not enabled at installation and you


decide to enable it later, you must edit the scp.properties file, and change theadminpath property to use HTTPS and port 443. The scp.properties file is storedin the following location on the runtime server computer:

<INSTALL_DIR>\runtime\conf

Secure communications between the runtime and administration servers require apassword to access the key.jks databases held on each runtime server. The SSLpassword is requested by the installation wizard when a runtime server is installedwith the SSL option. If you install the server with SSL turned off and decide toenable it later, you must set the SSL password using the sslpasswd command fromthe Tivoli License Manager command line interface. See “sslpasswd” on page 44.

Enabling SSL for IBM HTTP ServerTo enable SSL for the IBM HTTP server, you must do the following;v Add an SSL virtual host definition to the HTTP configuration file.

You must add a definition to the configuration file on the administration servercomputer. If you also intend to use secure communications between the runtimeserver and browsers, you must also add one to the configuration files onruntime server computers.

v Create or request a server certificate in the key.kdb database that is installed onthe administration server computer and export it so that it can be added to thekey.jks trusted store database on runtime server computers.

Virtual host definition in the HTTP configuration fileFigure 6 shows a sample SSL-enabled virtual host definition for a Windows serverand Figure 7 on page 37 shows an SSL-enabled virtual host definition for an AIXserver.

Open the HTTP configuration file, httpd.conf, and check for an entry like this. Ifyou do not find one, you must add a new definition.

LoadModule ibm_ssl_module modules/IBMModuleSSL128.dllListen 443<VirtualHost yourIPaddress:443>SSLEnableSSLClientAuth noneServerName yourServerNameErrorLog logs/ssl.error_logCustomLog logs/ssl.access_log commonSSLV2Timeout 40SSLV3Timeout 120Keyfile <INSTALL_DIR>/admin/keystore/key.kdb</VirtualHost>SSLDisable

Figure 6. SSL-enabled virtual host definition for Windows servers

Using HTTPS


Note: If you have to add or change an entry in the configuration file, you mustrestart the Web server before the changes take effect.

Creating or requesting a server certificateUsing the IBM Key Management tool (IKEYMAN), which is included with theHTTP server, you can either create a new self-signed certificate or request acertificate from a recognized certificate authority, as follows:1. On the administration server computer, start the IKEYMAN tool and open the

the key.kdb database, which is located in the directory:<INSTALL_DIR>\admin\keystore

The initial password for this database is slmtest.2. Use the IKEYMAN functions to either create a new self-signed certificate or to

request a certificate from one of the recognized authorities.If you have requested a certificate from a certificate authority which is alreadyincluded in the list of authorities held in the key.jks trusted store databases onthe runtime servers, no further action is required to make the certificate usableby the runtime servers. If you have created a self-signed certificate, you mustfollow the procedure described in “Adding a server certificate to the trustedstore”.

Adding a server certificate to the trusted storeThe self-signed certificate delivered with Tivoli License Manager is for testpurposes only. You must update the key.jks trusted store that has been installedon each SSL-enabled runtime server so that it includes the certificate authorityused to sign your own server certificate.

To add a certificate to the trusted store when you are using the IBM HTTP serveras your Web server, complete the following steps:1. On the administration server computer, start the IKEYMAN tool, which is

included with the HTTP server, and open the key.kdb database that is locatedin the directory <INSTALL_DIR>\admin\keystore.The initial password for this database is slmtest.

2. Use IKEYMAN to extract the certificate from the key.kdb database.3. On the runtime server computer, use the IKEYMAN tool provided with

WebSphere Application Server 4.0 or the IKEYMAN tool provided with IBMJava Secure Sockets Extension (IBM JSSE) to import the certificate to thekey.jks trusted store database.

LoadModule ibm_ssl_module libexec/mod_ibm_ssl_128.soAddModule mod_ibm_ssl.cListen 443<VirtualHost yourIPaddress:443>SSLEnableSSLClientAuth noneServerName yourServerNameErrorLog logs/ssl.error_logCustomLog logs/ssl.access_log commonSSLV2Timeout 40SSLV3Timeout 120Keyfile "<INSTALL_DIR>/admin/keystore/key.kdb"</VirtualHost>SSLDisable

Figure 7. SSL-enabled virtual host definition for AIX servers

Enabling SSL

Chapter 3. Enabling secure communications 37

The key.jks database is located in the directory:<INSTALL_DIR>\runtime\keystore. The password requested is the SSL passwordyou specified either when installing the runtime server with the SSL option orwhen you used the sslpasswd command. If you have not yet set an SSLpassword, the initial value is slmtest.

Note: After you have updated the key.jks, you must restart the runtime server.

If you are using Microsoft IIS as your Web server, complete the following steps:1. On the runtime server computer, open the Internet Services Manager console

and select the Web Site Properties and Directory Security tab.2. View the server certificate details, select the Issuer, and click Copy to File.3. When you are asked whether to export the private key, select No.4. Export the certificate information in DER format.5. On the runtime server computer, use the IKEYMAN tool provided with

WebSphere Application Server 4.0 or the IKEYMAN tool provided with IBMJSSE to import the certificate to the key.jks trusted store database.The key.jks database is located in the directory:<INSTALL_DIR>\runtime\keystore. The password requested is the SSL passwordyou specified when either installing the runtime server with the SSL option orwhen you used the sslpasswd command. If you have not yet set an SSLpassword, the initial value is slmtest.

Note: After you have updated the key.jks, you must restart the runtime server.

SSL port aliasesTo update the WebSphere Application Server list of host aliases, repeat thefollowing steps on each computer where a Tivoli License Manager server isinstalled:1. Open the WebSphere Administrator’s Console.2. Select default_host and click Advanced.3. Duplicate all the virtual host entries, specifying the SSL port. For example, if

there are entries for localhost, alpha, alpha.rome.ibm.com, and 127.0.0.1, youshould add localhost:443, alpha:443, alpha.rome.ibm.com:443, and127.0.0.1:443.

Note: If you are using WebSphere Application Server 4.0, you can usewildcards to specify aliases. To specify aliases for securecommunications, add *:443.

4. On the administration server computer only, you can optionally delete thealiases that use the default port (80) or any other port used for nonsecurecommunications. If you do this, only secure communications will be availablebetween the runtime and administration servers.

Note: Do not delete the aliases used for nonsecure communications on runtimeservers, because runtime server to agent communication is not secure.

5. Stop the WebSphere administrative server.6. Restart the WebSphere administrative server and the Tivoli License Manager

asministration server.

Adding a server certificate


Disabling secure communicationsIf you have been using SSL secure communications and you want to switch tononsecure communications, do the following:v Use the HTTP protocol instead of the HTTPS protocol. See “Using the HTTP

protocol”.v Optionally, delete the SSL-enabled virtual host definition from the HTTP

configuration file, httpd.conf. See “Deleting the virtual host definition”.v Ensure that the list of WebSphere Application Server host aliases on the

administration server computer includes aliases for the default ports. See“Restoring default port aliases”.

Using the HTTP protocolFor communications between Web browsers and the Tivoli License Managerservers, to change to the HTTP protocol, use HTTP when addressing the logonpages of the server interfaces as follows:

Administration serverhttp://<server name>/slmadmin/login

Runtime serverhttp://<server name>/slmruntime/login

For communications between the administration server and the runtime server,stop the runtime server. Edit the scp.properties file on the runtime servercomputer, and change the adminpath property to use HTTP and the default port(80). For example, change the adminpath property from:adminpath = https://alpha:443/slmadmin/service

to:adminpath = http://alpha:80/slmadmin/service

The scp.properties file is stored in the following location on the runtime servercomputer:

<INSTALL_DIR>\runtime\conf

After you have edited the scp.properties file, restart the runtime server.

Deleting the virtual host definitionOptionally, you can delete the SSL-enabled virtual host definition from the HTTPconfiguration file, httpd.conf. See “Virtual host definition in the HTTPconfiguration file” on page 36 for the description of the definition that can bedeleted. Stop the HTTP server before you edit the file.

Restoring default port aliasesCheck the WebSphere Application Server list of host aliases on the computer wherethe administration server runs.1. Open the WebSphere Administrator’s Console.2. Select default_host and click Advanced.3. If the aliases that use the default port (80) have been deleted, duplicate all the

virtual host entries, specifying the default port. For example, if there are entriesfor localhost:443, alpha:443, alpha.rome.ibm.com:443, and 127.0.0.1:443, addlocalhost:80, alpha:80, alpha.rome.ibm.com:80, and 127.0.0.1:80.

Disabling secure communications

Chapter 3. Enabling secure communications 39

Note: If you are using WebSphere Application Server 4.0, you can usewildcards to specify aliases. To specify aliases for nonsecurecommunications, add *:80.

4. Optionally, you can delete the aliases that use port 443. If you do this, onlynonsecure communications will be available between the runtime andadministration servers.

5. Stop the WebSphere administration server.6. Restart the HTTP server, the WebSphere administration server, and the Tivoli

License Manager administration server.

Disabling secure communications


Chapter 4. The command line interface

This chapter describes how to use the command line interfaces on theadministration and runtime servers. It includes the following information:v Instructions for accessing the Tivoli License Manager command windows on the

administration and runtime servers. See “Accessing the command line interface”.v Information about use of the Windows command line in Western European

languages. See “Command line output on Windows systems”.v A summary of the commands available on the administration and runtime

servers and instructions for their use. See “Commands on the Tivoli LicenseManager servers” on page 42.

Accessing the command line interfaceTable 3 shows the methods of accessing the command line interface foradministration and runtime servers on Windows and AIX platforms.

Note: The Tivoli License Manager command line can be used only by Windowsusers with administrator rights and user root on AIX.

Table 3. Accessing the command line on Windows and AIX servers

Server Platform Action

Administration Windows Open the Start menu and click TivoliLicense Manager >Admin CLI.

Runtime Windows Open the Start menu and click TivoliLicense Manager >Runtime CLI.

Administration AIX Do the following:

1. Open a shell window and change tothe directory:

<INSTALL_DIR>/admin/cli

2. Enter the command:

. ./tlmcli

Runtime AIX Do the following:

1. Open a shell window and change tothe directory:

<INSTALL_DIR>/runtime/cli

2. Enter the command:

. ./tlmcli

Command line output on Windows systemsIn Western European languages, the translated output of Tivoli commands onWindows operating systems is encoded using the Windows 1252 code page. Toview this text correctly in a DOS command window, perform the following steps:1. Enter the following command:

chcp 1252

2. Set the font for that window to Lucida Console.


Commands on the Tivoli License Manager serversTable 4 shows the commands that are available on the Tivoli License Managerservers. Some are available on both server components and some are onlyapplicable to either the administration or runtime server component.

Table 4. Administration and runtime server commands

Command Server Purpose See Page

dbpasswd Both To change the password for the DB2database that is associated with theadministration or runtime server.

42

expcat Administration To export the master catalog and relatedfiles for update by the catalog manager.

43

help Both To get help on command line usage. 43

impcat Administration To import the updated master catalog andrelated files.

43

info Both To print information about theadministration or runtime serverconfiguration.

43

rtpasswd Runtime To change the password for the runtimeserver.

43

srvstart Both To start the administration or runtimeserver.

44

srvstop Both To stop the administration or runtimeserver.

44

sslpasswd Runtime To change the secure sockets (SSL)password.

44

statusinfo Both To assemble information about a problemto send to IBM Software Support.

44

dbpasswdYou use this command to change the password used to connect to the DB2database.

Note: This command changes the encrypted value of the password held in thepasswd.properties file. This value must match the password defined on theoperating system for the tlmsrv user.

Syntaxdbpassword new_password

For example, to change the password to newdb, type:

dbpassword newdb

The password has a maximum length of 8 characters and can contain only thefollowing characters:

A-Z, a-z, 0-9, +, -, =

Commands


expcatYou use this command as part of the process of updating the master catalog withnew entries. This command exports the catalog and related files so that they can beloaded by the catalog manager, which can modify entries and add entries to thecatalog.

The file, catalog.dat, is written to the following location:

<INSTALL_DIR>\admin\cli\catalog

Syntaxexpcat

helpYou use this command to find out which commands are available on theadministration or runtime server.

Syntaxhelp

The command returns a list of the commands that are available, including a shortdescription of each command.

impcatYou use this command as part of the process of updating the master catalog withnew entries. This command imports the updated catalog files to the administrationserver database.

Syntaximpcat

infoYou use this command to obtain information about the Tivoli License Managerinstallation on the administration or runtime server.

Syntaxinfo

The command returns the following information:v The version of the Tivoli License Manager installedv The installation pathv The name of the DB2 database for the server

rtpasswdYou use this command to change the password for the runtime server. It changesthe value of the password that is held in the password.properties file on theruntime server. A value for runtime server password is also held in theadministration server database, and can be changed on the administration serverThis is required to authenticate communications from the server.

Syntaxrtpasswd new_password

Commands

Chapter 4. The command line interface 43

For example, to change the runtime password to rtnew, type:

rtpasswd rtnew


A-Z, a-z, 0-9, +, -, =

srvstartYou use this command to start the administration or runtime server.

Syntaxsrvstart

srvstopYou use this command to stop the administration or runtime server.

Syntaxsrvstop

sslpasswdYou use this command to change the SSL password for the runtime server. This isrequired to authenticate secure communications from the server.

Syntaxsslpasswd new_password

For example, to change the SSL password to 12secure, type:

sslpasswd 12secure


A-Z, a-z, 0-9, +, -, =

statusinfoYou use this command to gather trace files, configuration files, and database debugtables on the administration or runtime server computer. You can then forward thisinformation to IBM Software Support.

Syntaxstatusinfo

The command creates the directory <INSTALL_DIR>\admin\cli\adminStatus or<INSTALL_DIR>\runtime\cli\runtimeStatus with the following contents:v information.txt: a file that contains general information and the date and time

at which the information was gathered.v configuration: a folder that contains the configuration files for the server. This

is a copy of the server conf folderv traceLogs: a folder that contains the trace files for the server. This is a copy of

the server log folder.v dbData: a folder that contains the .dat files exported from the DB2 database.

Commands


v wasLogs: a folder that contains any WebSphere Application Server logs found inthe <INSTALL_DIR>\admin\was or <INSTALL_DIR>\runtime\was folder.

Commands

Chapter 4. The command line interface 45

Commands


Chapter 5. The agent

This chapter provides the following information about the agent:v An overview of functionality of the agent. See “Summary of agent

functionality”.v Information about deploying and upgrading agents. See “Agent deployment and

upgrade” on page 48.v The directory structures and files that are installed for each of the different

platforms where the agent can be deployed. See “Agent files” on page 50.v The commands that are available to control the agent on different platforms. See

“Agent commands” on page 52.

Summary of agent functionalityThe agent component of Tivoli License Manager runs silently on the nodes whereit is deployed, performing the following tasks:v Collection of details of the node’s hardware and operating system, and of the

software installed on the node, and forwarding this information to the runtimeserver

v Identification of the starting or stopping of a software product andcommunication of this information to the runtime server so that a license can beassigned or released and so that software usage information can be compiled

Each agent is associated with a single runtime server when it is deployed. Theagent makes the following exchanges of information with the runtime server atregular intervals:v It downloads the parameters defined in the agents settings section of the

system.properties configuration file held on the runtime server.Among other things, these settings define how often uploads and downloads ofthe different types of information are performed. See “Agent settings” onpage 111.

v It downloads the runtime server catalog, which identifies the products that theagent can monitor.

v It uploads information to the server about applications it has detected that arenot included in the runtime catalog.

v It downloads the definitions of monitoring system topology that have beendefined most recently.

v It uploads the information that it has collected in inventory scans.v It communicates the starting and stopping of monitored applications and

requests the issue and release of licenses.

While the agent is running, it holds the information that it is working with inmemory. This includes the information that it has downloaded from the server, forexample, the monitoring system topology and runtime server catalog andinformation that it has compiled, for example, unknown file information andinventory scans. If the agent is stopped, the information held in memory is savedto a cache so that it can be retrieved when the agent restarts. The agent also caches


inventory scan information if it fails to send it to the server. It will then try toresend at a later time unless the scan has still not been sent when the next scan isperformed.

Although each agent is assigned to a specific runtime server, it does not need to belimited to this server when requesting licenses. The agent has information aboutother runtime servers in the topology information that it downloads. Dependingon the value of the requestScope property defined in the agent settings section ofthe system.properties file, the agent can contact:v All runtime serversv Runtime servers that have agents in the same divisionv Only the assigned runtime server

The selection of the language for the agent is based on user settings:

WindowsThe language selected is determined by the locale set in the control panelRegional Options settings.

UNIX The language selected is determined by the LANG environment variable.

Agent deployment and upgradeThe agent is typically deployed using the agent registration Web page that isavailable on all runtime servers. This procedure is described in the IBM TivoliLicense Manager: License Administrator’s Guide. You can also deploy the agent byrunning a script from a command line. See “Deploying the agent manually”.

After the agent is installed, you can apply any upgrades automatically. See“Automatic upgrade of agents” on page 50.

You need to uninstall an agent only if you no longer wish to monitor the nodewhere it is installed. If you want to upgrade the agent, you can use the automaticmethod described in “Automatic upgrade of agents” on page 50. If you want toassign the agent to a different runtime server or division, you can simply redeploythe agent with the new parameters.

The deployment of the agent installs a number of files on the monitored node,including an uninstall script, tlmunins.bat on Windows platforms or tlmunins.shon UNIX platforms. See “Uninstalling the agent” on page 33.

Deploying the agent manuallyTo deploy an agent manually, perform the following steps:1. On a runtime server, change to the folder where the agent installation scripts

are stored for all platforms. The folder is:<INSTALL_DIR>\runtime\installedApp.ear\slm_runtime.war\webdoc\agent

It contains a folder for each platform where agents can be deployed and thefiles nls and codeset.

2. Copy the folder contents for the platform you require and the nls and codesetfiles to any directory on the target node.

3. From the directory on the target node, run the installagent command with theappropriate parameters. See “Parameters of the installagent command” onpage 49.

Agent functionality


Note: If you are deploying the agent on a Windows node, ensure that theWindows Service Manager Tool window is closed before running thecommand.

Parameters of the installagent commandThe installagent command has the following parameters. You can code themdirectly in the command line (“Specifying installagent parameters in the commandline” on page 50). If your values for any of the installagent parameters includenon-ASCII characters that need to be in UTF-8 encoding, you can use a UTF-8editor to create a file that contains the parameters and their values (“Specifyinginstallagent parameters in a file” on page 50).

The parameter names are not case-sensitive.

sourcepathThe location to which you copied the agent files from the runtime server.

divisionIDUnique identifier of the division to which the new agent is assigned.

You can extract a list of division IDs from the administration server database,using this query:

SELECT div.id division_id, div.name division_name, cus.namecustomer_name FROM admin.division div, admin.customer cus WHEREdiv.customer_id = cus.id AND cus.name = "xxx"

nodeTagThe computer label of the node.

serverThe host name or IP address of the runtime server that this agent is to use.

portThe runtime server port. This is normally 80.

uriThis must be set to /slmruntime/service.

customerThe name of the customer.

useProxyValid values are: Y (use proxy) and N (do not use proxy).

proxyNameEnter the proxy host name or IP address of the server. You must supply avalue even if useProxy is set to N.

proxyPortEnter the proxy port number of the server. This must be a number that isgreater than 0. You must supply a value even if useProxy is set to N.

traceValid values are: y (enabling the trace file for this command) and n (do nottrace). The name of the trace file is tlmia.trc.

Agent deployment

Chapter 5. The agent 49

Specifying installagent parameters in the command lineTo specify the parameters of the installagent command directly, enter thecommand as follows:

Specifying installagent parameters in a fileIf your values for any of the installagent parameters include non-ASCII charactersthat need to be in UTF-8 encoding, you can use a UTF-8 editor to create a file thatcontains all the parameters and their values. In this case the format of theinstallagent command is:

installagent <sourcepath> -f <filename>

Enter the parameters in the file as in this example:nodeTag = sportue1server = heden.rome.tivoli.comport = 80uri = /slmruntime/servicecustomer = ResearchuseProxy = yproxyName = pastorellinux.rome.tivoli.comproxyPort = 3128trace = n

If the agent does not install successfully, see “Agent deployment” on page 85 for alist of possible causes and solutions.

Automatic upgrade of agentsWhen you receive a patch that contains an upgrade to agent files, first install thepatch on the runtime server. Then you can automatically upgrade all the agentsthat are connected to the runtime server, as follows:1. Edit the agent settings section of the system.properties file on each runtime

server, and change the updateAgentEnabled property to Yes.2. Stop and restart the runtime server so that the changed configurations take

effect.

Following the next download of agent parameters to agents, the agents will start tocheck the runtime server for a changed version of the appropriate agent files. Themaximum interval between checks is defined by the updateAgentPeriod. When anew version of the agent files is found, the agent downloads the files and appliesthe new version.

When all agents have been upgraded, reset the updateAgentEnabled property toNo.

Agent filesThe agent deployment and operation create a number of directories and files. Thelocation of the agent files depends on the platform on which the agent is deployed.

Note: The license status and unknown files log files are not created if the agenttrace level is set to 0. See “Logging and trace setting on the agent” onpage 77.

installagent sourcepath divisionID nodeTag server port uri customer useProxy proxyName proxyPort trace

Agent deployment


AIXOn AIX platforms, the agent files are created as follows:

Table 5. Agent files on AIX platforms

File Description

/usr/sbin/tlmagent The main agent file

/etc/tlmagent.ini The agent configuration file

/var/itlm/tlmunins.sh Uninstall agent script

/var/itlm/tlmkagent.def Device configuration database definitions forthe agent kernel extension.

/usr/lib/drivers/tlmkagent/usr/lib/drivers/tlmkreg/usr/lib/drivers/tlmkstub

The agent kernel extensions

/usr/lib/methods/deftlmkagent/usr/lib/methods/cfgtlmkagent/usr/lib/methods/chgtlmkagent/usr/lib/methods/ucfgtlmkagent/usr/lib/methods/undtlmkagent

Device configuration methods for the agentkernel extensions

/var/itlm/cache/ Folder for agent cache files

/var/itlm/codeset/ Folder containing files for conversions ofcharacters between different code sets

/var/itlm/nls/ Folder containing a subfolder for eachsupported language. The subfolders containthe file where agent messages are defined.

/var/itlm/log/traceagt.log The agent log file

/var/itlm/log/tracelics.log The license status log file

/var/itlm/log/traceuat.log The unknown files log file

SunOn Sun platforms only 64-bit kernels are supported. The agent files are created asfollows:

Table 6. Agent files on Sun platforms

File Description

/usr/sbin/tlmagent The main agent file

/etc/tlmagent.ini The agent configuration file

/usr/kernel/drv/sparcv9/tlmkagent The agent kernel extension

/usr/kernel/drv/tlmkagent.conf The agent kernel extension configuration

/var/itlm/tlmunins.sh Uninstall agent script

/var/itlm/cache/ Folder for agent cache files

/var/itlm/codeset/ Folder containing files for conversions ofcharacters between different code sets

/var/itlm/nls/ Folder containing a subfolder for eachsupported language. The subfolders containthe file where agent messages are defined.

/var/itlm/log/traceagt.log The agent log file

/var/itlm/log/tracelics.log The license status log file

Agent files


Table 6. Agent files on Sun platforms (continued)

File Description

/var/itlm/log/traceuat.log The unknown files log file

/etc/init.d/tlm Auto-startup script

/etc/rc2.d/S01tlm Link to auto-startup script for runlevel 2

/etc/rc1.d/K01tlm Link to auto-startup script for runlevel 1

WindowsOn Windows platforms, the agent files are created in the location:

%windir%\itlm

Table 7. Agent files on Windows platforms

File Description

tlmagent.exe The main agent file

tlmagent.ini The agent configuration file

tlmkagent.sys The agent kernel extension on WindowsNT® and Windows 2000

tlmkagent.dll The agent kernel extension on Windows 98and Windows ME

tlmunins.bat Uninstall agent script

cache\ Folder for agent cache files

codeset\ Folder containing files for conversions ofcharacters between different code sets

nls\ Folder containing a subfolder for eachsupported language. The subfolders containthe file where agent messages are defined.

log\traceagt.log The agent log file

log\tracelics.log The license status log file

log\traceuat.log The unknown files log file

Agent commandsYou can perform some agent tasks from the command line. This section details thecommands that can be used on the different platforms.

All platformsTable 8 lists the commands available on all platforms.

On Windows platforms, commands must be run from the %windir%\itlm folder

Table 8. Agent commands on all agent platforms

Task Command

Return the version of the agent tlmagent -v

Test communication to the server tlmagent -p

Perform an inventory scan tlmagent -s

Plug in and perform a scan tlmagent -sp or tlmagent -ps

Agent files


AIXTable 9 lists the commands available on AIX platforms. On AIX, commands forcontrolling the agent differ from those used on other UNIX platforms because theyuse the AIX System Resource Controller (SRC).

Table 9. Agent commands on AIX platforms

Task Command

Start the agent startsrc -s tlmagent

Stop the agent stopsrc -s tlmagent

Show the status of the agent lssrc -s tlmagent

Other UNIX PlatformsTable 10 lists the commands available on UNIX platforms other than AIX.

Table 10. Agent commands on UNIX platforms

Task Command

Start the agent /etc/init.d/tlm start

Stop the agent /etc/init.d/tlm stop

WindowsTable 11 lists the commands available on Windows platforms.

Commands must be run from the %windir%\itlm folder.

Table 11. Agent commands on Windows platforms

Task Command

Start the agent service tlmagent -g

Stop the agent service tlmagent -e

Register the agent as a service tlmagent -i

Remove the agent from the list ofservices

tlmagent -r

Agent commands


Agent commands


Chapter 6. Event notification

Tivoli License Manager includes a system of notifying administrators of events thathave occurred by automatically generating e-mails and sending them to designatedrecipients. Events are also written to a log.

This chapter provides the following information:v A summary of events that generate notifications on the administration server

and on runtime servers. See “Events that generate notifications”.v Instructions for setting the parameters for sending notifications and for

specifying who is to receive them. See “Defining notification recipients andnotification settings for a server”.

v Information about the event log. See “The event.log file” on page 57.

Events that generate notificationsEvent notifications are generated on the administration server and on each runtimeserver.

The following events generate a notification on the administration server:v The number of licenses in use within a license pool reaches the total number of

license available in the pool.v The percentage of licenses in use within a license pool reaches the threshold

value defined for the pool.v The administration server is stoppedv The administration server is started.

The check that identifies the license usage events is performed at regular intervals,defined by the property hwmScanPeriod in the system.properties file for theadministration server. See “Administration server settings” on page 109.

The following events generate a notification on runtime servers:v The runtime server is stopped.v The runtime server is started.v An inventory scan is sent to the runtime server by an agent.v An agent, associated with the server, is inactive.

An agent is considered inactive if the runtime server has had not communicationfrom it for a period of time defined in the maxAgentInactivity property of thesystem.properties file on the runtime server.

Defining notification recipients and notification settings for a serverTo use event notification you must specify who is to receive notifications anddefine settings that allow the notifications to be automatically sent.

Recipients of notifications are Tivoli License Manager administrators. When youdefine the account details for an administrator, you can specify an e-mail addressand select the option for the administrator to receive e-mails.


You define administrators on the administration server to receive thelicense-related notifications. You define administrators on each runtime server toreceive the notifications relating to runtime server and agent status. See the IBMTivoli License Manager: License Administrator’s Guide for information on creating andupdating administrator accounts.

The administration server and each runtime server has its own settings that controlthe sending of notifications. You define the parameters to be used to sendnotifications in the system.properties file for each server. These parametersinclude the name of the mail server, the mail engine to be used, and the e-mailaddress to which notifications are to be sent. You can also set one mail recipient toreceive notifications in addition to the administrators you have defined. Thisadditional recipient does not need to be an administrator.

The following is an example of the Mail Settings section of the system.propertiesfile.#Mail SettingssmtpServer=mailserv120.ibm.commailEngine=InternalmailRecipient=jsmith@[email protected]

To define notification settings for a server, complete the following steps:1. Log on to the computer where the administration or runtime server is installed.2. Open the system.properties file in a text editor.

The location of the system.properties file is as follows:


Runtime server<INSTALL_DIR>\runtime\conf

Note: If the administration server is installed on the same computer as aruntime server, system.properties files exist in both locations. You mustdefine settings in both files to enable both types of notification.

3. In the #Mail Settings section of the file, define the properties as follows:

smtpServerEnter the host name or IP address of a valid SMTP server. This server willbe used to forward the e-mail communications generated by the server’snotification component.

mailRecipientYou can enter the e-mail address to which notifications are to be sent. Thissetting is optional.

mailSenderEnter the e-mail address that is to be used by the server as the senderaddress when notifications are generated.

Note: No e-mails are generated if the settings for the SMTP server and the mailsender are not present or not valid.

4. Save the file and close it.

Recipients and settings


The event.log fileAll servers maintain an event.log file that includes entries for all the events thatoccur on the server. The location of the file on each server is:

Administration server<INSTALL_DIR>\admin\log

Runtime server<INSTALL_DIR>\runtime\log

In addition to the events that generate notifications, the administration server logsentries in the event.log file when a runtime server fails to plug in to theadministration server. These entries give the reason for failure. This is normally amismatch between information entered at installation of the server and thatentered when registering the runtime server on the administration server.

The following is an example of entries in the event.log file:

February 25, 2002 3:58:46 PM, System, Server Start, The administration server has been startedFebruary 25, 2002 4:29:09 PM, Usage, Threshold Exceeding, The maximum threshold allowed hasbeen reached or exceeded for the following licensesCustomer: Customer1, License: License1, Product: Component1 version 1, Quantity: 10,Threshold: 8, High Water Mark: 9, HWM date: February 25, 2002 4:20:13 PM GMTFebruary 25, 2002 4:29:09 PM, Usage, Enrollment Exceeding, The maximum threshold allowed hasbeen reached or exceeded for the following licenses:Customer: Customer1, License: LicenseUser, Product: Component1 version 1, Quantity: 10, HighWater Mark: 11, HWM date: February 25, 2002 4:20:13 PM GMTFebruary 25, 2002 5:34:10 PM, System, Server Plugin Failure, The runtime server plugin hasbeen refused by the administration server, the attempting server was not found because theruntime server name is unknown.Runtime server name: paoneffFebruary 25, 2002 5:36:41 PM, System, Server Plugin Failure, The runtime server plugin hasbeen refused by the administration server, the attempting server was not found because theruntime server is not owned by the passed customer.Customer name: FabioCustomer3, Runtime server name: paonefFebruary 25, 2002 5:38:59 PM, System, Server Plugin Failure, The runtime server plugin hasbeen refused by the administration server, the attempting server was not found because theruntime server password is wrong.Runtime server name: paonef

February 25, 2002 5:48:19 PM, System, Server Plugin Failure, The runtime server plugin hasbeen refused by the administration server, because of a mismatch between the actual serverID and the expected value.Runtime server name: omega

February 25, 2002 5:59:02 PM, System, Server Stop, The administration server has beenstopped

event.log

Chapter 6. Event notification 57

Chapter 7. XML interfaces

Tivoli License Manager provides document type definitions (DTDs) for the exportof the following reports:v The software usage snapshot. See “XML definition for the software usage

snapshot”.v The software usage trend analysis. See “XML definition for the software usage

trend analysis report” on page 63.v The software usage level analysis. See “XML definition for the software usage

level analysis report” on page 65.v The software inventory report. See “XML formats for the software inventory

report” on page 66.

The DTDs are stored on the administration server computer in the folder:

<INSTALL_DIR>\runtime\installedApp.ear\slm_admin.war\webdoc\xml\export

XML definition for the software usage snapshotThe XML format for the software usage snapshot is defined in the SWUsage.dtd asfollows.<?xml version="1.0" encoding="UTF-8"?><!ELEMENT XMLExport (ProductEntry+)><!ATTLIST XMLExportCustomer CDATA #REQUIRED><!ELEMENT ProductEntry (Category, Description, Name, OSName, Version,Id, VendorId, VendorName, TotalInstall, AgentEntry*, CapacityEntry*)><!ATTLIST ProductEntry Available (true | false) #REQUIRED>

<!ELEMENT CapacityEntry (HWM, InUse, Name, Id, LicenseEntry+,FilteredInUse,LicenseQuantity)>

<!ELEMENT LicenseEntry (Description, ExpirationDate, StartDate,HardStop, Id, MultiInstance, Quantity, TargetType, Threshold, HWM,HWMDate, SessionEntry*, InUse)>

<!ELEMENT SessionEntry (GroupName, HostName, LogonName, Id, EndTime,Capacity, StartTime, ComponentName, QuantityGranted)>

<!ELEMENT AgentEntry (Division, HostName, IpAddress, NodeName, OSName,OsVersion, ServerName)><!ATTLIST AgentEntryAvailable (true | false) #REQUIRED><!ELEMENT Capacity (#PCDATA)><!ELEMENT Category (#PCDATA)><!ELEMENT ComponentName (#PCDATA)><!ELEMENT Description (#PCDATA)><!ELEMENT Division (#PCDATA)><!ELEMENT EndTime (#PCDATA)><!ELEMENT ExpirationDate (#PCDATA)><!ELEMENT FilteredInUse (#PCDATA)><!ELEMENT GroupName (#PCDATA)><!ELEMENT HWM (#PCDATA)><!ELEMENT HWMDate (#PCDATA)><!ELEMENT HardStop (#PCDATA)>


<!ELEMENT HostName (#PCDATA)><!ELEMENT Id (#PCDATA)><!ELEMENT InUse (#PCDATA)><!ELEMENT IpAddress (#PCDATA)><!ELEMENT LicenseQuantity (#PCDATA)><!ELEMENT LogonName (#PCDATA)><!ELEMENT MultiInstance (#PCDATA)><!ELEMENT Name (#PCDATA)><!ELEMENT NodeName (#PCDATA)><!ELEMENT OSName (#PCDATA)><!ELEMENT OsVersion (#PCDATA)><!ELEMENT Quantity (#PCDATA)><!ELEMENT QuantityGranted (#PCDATA)><!ELEMENT ServerName (#PCDATA)><!ELEMENT StartDate (#PCDATA)><!ELEMENT StartTime (#PCDATA)><!ELEMENT TargetType (#PCDATA)><!ELEMENT Threshold (#PCDATA)><!ELEMENT TotalInstall (#PCDATA)><!ELEMENT VendorId (#PCDATA)><!ELEMENT VendorName (#PCDATA)><!ELEMENT Version (#PCDATA)>

The tables included in this section detail the elements that form the XML definitionof the software usage snapshot report.

The format of the report comprises a XmlExport element. This element has therequired attribute Customer, which identifies the customer whose software usageinformation is reported. The XmlExport contains a ProductEntry element for eachproduct included in the report.

Each ProductEntry element has the required attribute Available, which can be setto true or false.

Table 12 lists the subelements contained in a ProductEntry element.

Table 12. Subelements of the ProductEntry element in the software usage snapshot

Element Content

Category The software category of the product, for example,Utilities - Antivirus, or Business - Finance.

Description A description of the software product.

Name The name of the software product.

OSName The operating system on which this product runs.

Version The version of the software product.

Id A unique string that identifies the product.

VendorId A unique string that identifies the product vendor.

VendorName The name of the company that supplies the software product.

TotalInstall The total number of installations of this product on monitorednodes.

AgentEntry Details of an agent that monitors a node on which the productis installed. See Table 13 on page 61.

CapacityEntry Details of the license usage for the product within a specificcapacity type. See Table 14 on page 61.

Software usage snapshot


Table 13 shows the elements that are contained within each AgentEntry element.An AgentEntry element is embedded in the ProductEntry element for each agentthat monitors a node on which the product is installed and has the requiredattribute Available, which can be set to true or false.

Table 13. Subelements of the AgentEntry element in the software usage snapshot

Element Content

Division The name of the division to which the agent is assigned.

HostName The host name of the node on which the agent is deployed.

IpAddress The IP address of the node on which the agent is deployed.

NodeName Name of the node on which the agent is deployed.

OSName The operating system that is running on this node.

OSVersion The operating system version.

ServerName The name of the runtime server with which the agent isregistered.

Table 14 shows the elements that are contained within each CapacityEntry element.A CapacityEntry element is embedded in the ProductEntry element for eachdifferent capacity type for which the product uses licenses.

Table 14. Subelements of the CapacityEntry element in the software usage snapshot

Element Content

HWM The maximum concurrent license usage at any time during thespecified HWM period, for all license pools defined with thiscapacity type. This includes licenses in use on all agents, notonly those selected for reporting.

InUse The total number of licenses, defined with this capacity type,that were in use at the specified time. This includes licenses inuse on all agents, not only those selected for reporting.

Name The name of the capacity type, for example Users, Memory.

Id A unique identifier for the capacity type.

LicenseEntry Details of the licenses of this capacity type that existed for theproduct at the specified reporting time. See Table 15 onpage 62.

FilteredInUse The number of licenses, defined with this capacity type, thatwere in use on the selected agents at the specified time.

LicenseQuantity The volume of licenses for the product available in licensepools with this capacity type.

Table 15 on page 62 shows the elements that are contained within eachLicenseEntry element. A LicenseEntry element is embedded in the CapacityEntryelement for each license pool of the specified capacity that existed for the productat the specified reporting time.


Chapter 7. XML interfaces 61

Table 15. Subelements of the LicenseEntry element in the software usage snapshot

Element Content

Description A description of the license pool.

ExpirationDate The date when the availability of this license pool ends.

StartDate The date when this license pool became available.

HardStop Possible values are:

Yes The quantity of licenses is an absolute maximum.When it is reached, licenses are refused.

No Licenses can still be granted when the maximum hasbeen reached.

Id A unique identifier for the license pool.

MultiInstance Possible values are:

DisabledMultiple sessions for licenses is not allowed.

Same userMultiple sessions are allowed for the same user on thesame agent.

Same groupMultiple sessions are allowed for users in the same groupon the same agent.

Same nodeMultiple sessions are allowed on the same node andagent.

Quantity The volume of licenses available in this pool.

TargetType Indicates the availability of the license pools. Possible valuesare:

EnterpriseAvailable to all nodes.

DivisionRestricted to specified divisions.

NodeRestricted to specified nodes.

AgentRestricted to specified agents.

Threshold The percentage of available licenses at which a notificationshould be generated.

HWM The maximum concurrent use of licenses from this poolduring the HWM period.

HWMDate The date on which the high-water mark was reached.

SessionEntry Details of a session that was using a license from this pool atthe specified reporting time. See Table 16 on page 63.

InUse The number of licenses in use from this pool at the specifiedreporting time.

Table 16 on page 63 shows the elements that are contained within eachSessionEntry element. A SessionEntry element is embedded in the LicenseEntryelement for each session that was using a license from the pool at the specifiedreporting time.



Table 16. Subelements of the SessionEntry element in the software usage snapshot

Element Content

GroupName The name of the user group to which the license was assigned.

HostName The host name of the node on which the session was running.

LogonName The user ID of the user who started the session.

Id A unique identifier for the session.

EndTime The time at which the session ended.

Capacity The capacity type of the license that was granted.

StartTime The time at which the session started.

ComponentName The name of the product component that was in use.

QuantityGranted The volume of licenses granted for the session.

XML definition for the software usage trend analysis reportThe XML format for the software usage trend analysis report is defined in theswu_trend.dtd as follows:<?xml version="1.0" encoding="UTF-8"?>< ELEMENT XMLExport (EventDataModel)>< ELEMENT EventDataModel (EventDataModel.stats, EventDataModel.labels,EventDataModel.events)>< ELEMENT EventDataModel.events (Event+)>< ELEMENT EventDataModel.labels (XLabel, YLabel)>< ELEMENT EventDataModel.stats (Avg. MaxX, MinX, MaxY, MinY, MaxPeak, MinPeak)<!ELEMENT Event EMPTY><!ELEMENT Avg EMPTY><!ELEMENT MaxPeak EMPTY><!ELEMENT MaxX EMPTY><!ELEMENT MaxY EMPTY><!ELEMENT MinPeak EMPTY><!ELEMENT MinX EMPTY><!ELEMENT MinY EMPTY><!ELEMENT XLabel (#PCDATA)><!ELEMENT YLabel (#PCDATA)><!ATTLIST XMLExport Customer CDATA #REQUIRED><!ATTLIST Avg value CDATA #REQUIRED><!ATTLIST Event time CDATA #REQUIRED value CDATA #REQUIRED><!ATTLIST MaxPeak time CDATA #REQUIRED value CDATA #REQUIRED><!ATTLIST MaxX value CDATA #REQUIRED><!ATTLIST MaxY value CDATA #REQUIRED><!ATTLIST MinPeak time CDATA #REQUIRED value CDATA #REQUIRED><!ATTLIST MinX value CDATA #REQUIRED><!ATTLIST MinY value CDATA #REQUIRED>

The tables included in this section detail the elements that form the XML definitionof the software usage trend analysis report. In this report, the high-level element,XmlExport, contains an EventDataModel element which contains the parametersused to plot the trend analysis chart.

Table 17 on page 64 shows the elements that are enclosed in the EventDataModelelement.



Table 17. Subelements of the EventDataModel element in the trend analysis report

Element Content

EventDataModel.stats The statistics that record the time and level of the highest andlowest usage included in the chart as well as the averageusage during the reported period. See Table 18 for informationabout the subelements that occur within this element.

EventDataModel.labels The labels that are attached to the X and Y axes of the chart.This element occurs once and includes the followingsubelements:

XLabelThe label that is assigned to the horizontal axis of thechart.

YLabelThe label that is assigned to the vertical axis of the chart.

EventDataModel.events The events that are plotted on the chart to form the trendanalysis. This element contains multiple Event elements. EachEvent element has attributes that identify the time of the eventand the level of usage.

Table 18 shows the elements that are contained within the EventDataModel.statselement.

Table 18. Subelements of the EventDataModel.stats element in the trend analysis report

Element Content

Avg The average usage of the product during the reporting period.It is the sum of the values of all events included in the chartdivided by the number of events included in the chart.

MaxX The date and time at which the reporting period ends.

MinX The date and time at which the reporting period starts.

MaxY The highest level of usage during the reporting period.

MinY The lowest level of usage during the reporting period.

MaxPeak This element has two attributes:

timeThe date and time at which the highest level of usage wasreached.

valueThe highest level of usage.

MinPeak This element has two attributes:

timeThe date and time at which the lowest level of usage wasrecorded.

valueThe lowest level of usage.

The following is an example XML format for the software usage trend analysisreport.<?xml version="1.0" encoding="UTF-8"?><XMLExport Customer = "IBM">

<EventDataModel><EventDataModel.stats>

<Avg value = "1.672"/>

Software usage trend analysis


<MaxX value = "2/13/03 12:07PM"/><MinX value = "1/13/03 11:07AM"/><MaxY value = "5"/><MinY value = "0"/><MaxPeak time = "2/13/03 11:30AM" value = "5"/><MinPeak time = "1/13/03 11:07AM" value = "0"/>

</EventDataModel.stats><EventDataModel.labels>

<XLabel>Time</XLabel><YLabel>In Use (Number of Users)</XLabel>

</EventDataModel.labels><EventDataModel.events>

<Event time = "1/13/03 11:07AM" value = "0"/><Event time = "2/11/03 4:49PM" value = "1"/><Event time = "2/11/03 4:51PM" value = "0"/><Event time = "2/12/03 1:10PM" value = "1"/><Event time = "2/12/03 4:10PM" value = "0"/><Event time = "2/12/03 4:30PM" value = "1"/><Event time = "2/12/03 4:30PM" value = "2"/><Event time = "2/12/03 4:31PM" value = "3"/><Event time = "2/12/03 5:55PM" value = "2"/><Event time = "2/12/03 6:03PM" value = "3"/><Event time = "2/12/03 6:10PM" value = "2"/><Event time = "2/12/03 6:14PM" value = "3"/><Event time = "2/12/03 7:01PM" value = "2"/><Event time = "2/12/03 7:09PM" value = "1"/><Event time = "2/12/03 7:31PM" value = "0"/><Event time = "2/13/03 7:55AM" value = "1"/><Event time = "2/13/03 9:31AM" value = "2"/><Event time = "2/13/03 9:55AM" value = "3"/><Event time = "2/13/03 19:45AM" value = "4"/><Event time = "2/13/03 11:30AM" value = "5"/><Event time = "2/13/03 12:07PM" value = "4"/>

</EventDataModel.events></EventDataModel>

XML definition for the software usage level analysis reportThe XML format for the software usage level analysis is defined in theSWUsageLevelAnalysisReport.dtd as follows:<?xml version="1.0" encoding="UTF-8"?><!ELEMENT XmlExport (Product+)>

<!ATTLIST XmlExportCustomer (#CDATA) #IMPLIED><!ELEMENT Product (

Name,Version,Vendor,Platform,ThresholdType,UsageData,HWMDate? )>

<!ELEMENT Name (#PCDATA)><!ELEMENT Version (#PCDATA)><!ELEMENT Vendor (#PCDATA)><!ELEMENT Platform (#PCDATA)><!ELEMENT ThresholdType (High Water Mark|Average Usage)><!ELEMENT UsageData (#PCDATA)><!ELEMENT HWMDate (#PCDATA)>

The format of the report comprises an XmlExport element, which contains aProduct element for each product included in the report. The XmlExport elementhas the required attribute Customer, which identifies the customer whose softwareusage information is reported.

Software usage trend analysis


Table 19 shows the elements that are contained within each Product element.

Table 19. Subelements of the Product element in the level analysis report

Element Content



Vendor The company that supplies the software product.

Platform The operating system on which this product runs.

ThresholdType Indicates the value to be used in measuring level of usage.Possible values are High Water Mark and Average Usage.

UsageData The level of usage. Which units that the usage is expressed independs on the capacity type selected when the report wasrequested.

HWMDate The date on which the high-water mark was reached. This ispresent only if ThresholdType is High Water Mark.

XML formats for the software inventory reportTivoli License Manager provides an inventory report that can be produced in thefollowing formats:v Sorted by agent

In this format, the details of each agent are shown followed by a list of allproducts that are installed on the node it is monitoring.

v Sorted by productIn this format, the details of each product are shown followed by a list of all theagents that are monitoring nodes where it is installed.

The XML format for the software inventory report in product order is defined inthe InventoryProductReport.dtd as follows:<?xml version="1.0" encoding="UTF-8"?><!ELEMENT XmlExport (Product+)>

<!ATTLIST XmlExport Customer (#CDATA) #IMPLIED><!ELEMENT Product (

Name,Version,Vendor,Platform,Category,Description,AgentsNumber,IsClone,Agent+ )>

<!ELEMENT Name (#PCDATA)><!ELEMENT Version (#PCDATA)><!ELEMENT Vendor (#PCDATA)><!ELEMENT Platform (#PCDATA)><!ELEMENT Category (#PCDATA)><!ELEMENT Description (#PCDATA)><!ELEMENT AgentsNumber (#PCDATA)><!ELEMENT IsClone (true|false)><!ELEMENT Agent (

IsRemoved,Name,Division,Node,

Software usage level analysis


LastScanDate )><!ELEMENT IsRemoved (true|false)><!ELEMENT Name (#PCDATA)><!ELEMENT Division (#PCDATA)><!ELEMENT Node (#PCDATA)><!ELEMENT LastScanDate (#PCDATA)>

The XML format for the software inventory report in agent order is defined in theInventoryAgentReport.dtd as follows.<?xml version="1.0" encoding="UTF-8"?><!ELEMENT XmlExport (Agent+)>

<!ATTLIST XmlExport Customer (#CDATA) #IMPLIED><!ELEMENT Agent (

Name,Division,Node,LastScanDate,ProductsNumber,IsClone,Product+ )>

<!ELEMENT Name (#PCDATA)><!ELEMENT Division (#PCDATA)><!ELEMENT Node (#PCDATA)><!ELEMENT LastScanDate (#PCDATA)><!ELEMENT ProductsNumber (#PCDATA)><!ELEMENT IsClone (true|false)><!ELEMENT Product (

IsRemoved,Name,Version,Vendor,Platform,Category,Description )>

<!ELEMENT IsRemoved (true|false)><!ELEMENT Name (#PCDATA)><!ELEMENT Version (#PCDATA)><!ELEMENT Vendor (#PCDATA)><!ELEMENT Platform (#PCDATA)><!ELEMENT Category (#PCDATA)><!ELEMENT Description (#PCDATA)>

The tables included in this section detail the elements that form the XML definitionof the inventory reports. The format of both reports comprises an XmlExportelement, within which are enclosed the elements that make up the report.

Table 20 on page 68 shows the second level elements that are enclosed in theXmlExport element. Some of these elements include another level of elements,which are detailed in separate tables.

Inventory reports


Table 20. Subelements of the XmlExport element in the software inventory report

Element Content

Agent The details of an agent. This includes information about thenode on which it is deployed. If the report is produced inproduct order, this element is a subelement of the Productelement.

This element occurs for each agent that is included in thereport. See Table 22 on page 69 for information about thesubelements that occur within this element.

Product The details of a software product that is installed on a nodethat is monitored by Tivoli License Manager. If the report isproduced in agent order, this element is a subelement of theAgent element.

This element occurs for each product that is included in thereport. See Table 21 for information about the subelements thatoccur within this element.

Table 21 shows the elements that are contained within the Product element. If thereport is produced in product order, multiple occurrences of this element areembedded within the XmlExport element, identifying all the inventoried productsthat are included in the report. If the report is produced in agent order, multipleoccurrences of this element are contained within each Agent element, identifying allthe inventoried products on nodes that are monitored by that agent.

Table 21. Subelements of the Product element in the software inventory report

Element Content



Vendor The company that supplies the software product.

Platform The operating system on which this product runs.

Category The software category of the product, for example,Utilities - Antivirus, or Business - Finance.

Description A description of the software product.

AgentsNumber The number of agents that are monitoring nodes on which theproduct is installed.

This element is included only if the report is produced inproduct order.

IsClone This element occurs only when the report is in product order.It indicates whether the reporting entry represented by thisProduct element is a continuation of the list of agents for theproduct from the previous page of the report. Possible valuesare true and false.

IsRemoved Indicates whether the reported product has been removed.Possible values are true and false.

Agent The details of an agent that monitors a node on which thisproduct is installed. See Table 22 on page 69.

This element is embedded in the Product element only if thereport is produced in product order.

Inventory reports


Table 22 shows the elements that are enclosed within the Agent element. If thereport is produced in agent order, multiple occurrences of this element arecontained within the XmlExport element, identifying all the agents that areincluded in the report. If the report is produced in product order, multipleoccurrences of this element are contained within each Product element, identifyingall the agents on nodes where that product is installed.

Table 22. Subelements of the Agent element in the software inventory report

Element Content

Name Specifies the name of the agent.

Division The division of the organization to which the agent isassigned.

Divisions are optional organizational units within an TivoliLicense Manager implementation.

Node The node which the agent is monitoring.

LastScanDate The date and time of the last inventory scan on this agent.

IsClone This element only occurs when the report is in agent order. Itindicates whether the reporting entry represented by thisAgent element is a continuation of the list of products for theagent from the previous page of the report. Possible values aretrue and false.

IsRemoved Indicates whether the reported product has been removed.Possible values are true and false.

ProductsNumber The number of products that are reported as being installed onthe node.

This element is included only if the report is produced inagent order.

Product Details of a software product that is installed on the monitorednode. See Table 21 on page 68.

This element is embedded in the Agent element only if thereport is produced in agent order.

Inventory reports


Inventory reports


Chapter 8. Database table cleanup

The following tables in the administration server database are continually added toby internal processes:

USAGE This table stores the information sent from runtime servers to theadministration server in usage snapshot and usage updatetransactions.

The usage snapshot contains information about the licenses in useat a point in time and is sent at regular intervals.

SERVICE This table maintains a history of requests for services. An entry isadded to the table each time there is an inventory scan by anagent, a update of agent information, or a download of topologyinformation from the administration server to runtime servers.

Tivoli License Manager includes cleanup processes that you can run on a regularbasis to prevent these tables from reaching unmanageable sizes.

Performance and sizing considerationsBecause the internal processes are continually adding new entries to these tables,intervention is needed to stop the tables from growing to proportions that couldaffect performance.

For example, in an environment with a 100 000 agents, it would require only tentransactions per hour over a ten hour working day to add 10 million entries to theUSAGE table in a single day. The USAGE table is the source of data used in thesoftware usage reports, and performance of these reports would be affected if thetable became too large.

Setting parameters for cleanup processesTivoli License Manager provides a cleanup process for the USAGE table andanother for the SERVICE table.

The administration server section of the system.properties file includes propertiesthat control how often the processes are to run and the length of time for whichentries are to be retained. These properties are set to default values, but you candefine them to suit your needs.

Each server has its own system.properties file. The file in which you need to setthese parameters is located on the administration server in the directory:<INSTALL_DIR>\admin\conf

For information about the system.properties file, see Appendix B, “Configurationsettings”, on page 107.

The USAGE table process runs regularly at intervals determined by thecleanUsagePeriod property. The default for this property is one day. You candisable the process by changing the setting of the cleanUsageEnabled property tofalse.


The cleanup process identifies usage transactions that are older than the number ofdays specified in the maxUsageAge property. These transactions are cleared from thetable and the detailed software usage information that they provided is no longeravailable to the software usage reports. However, a less detailed record ismaintained by adding entries to the USAGE_H table. This table includes an entryfor each unique combination of license pool, date, and time. The quantity oflicenses assigned values for all transactions that match on all three parameters areconsidered and the highest value is recorded in the USAGE_H entry. In this way, arecord of the high-water mark is maintained at the license pool, date, and timelevel. This information is accessible using DB2 queries.

The SERVICE table process runs regularly at intervals determined by thecleanServicePeriod property. The default for this property is six hours. You candisable the process by changing the setting of the cleanServiceEnabled property tofalse.

The cleanup process identifies entries that are older the number of days specifiedin the maxServiceAge property and deletes them.

Parameters for cleanup


Chapter 9. Problem determination

This chapter includes the following information:v A procedure for verifying the correct installation of Tivoli License Manager

server and database components. See “Validating the installation”.v An overview of error reporting, logging, and tracing on servers and agents. See

“Log files and tracing” on page 75.v A summary of issues related to performance. See “Performance” on page 78.v A list of common problems and their solutions. See “Common problems” on

page 80.

Validating the installationMany initial problems are caused by mistakes or missed steps during theinstallation process. For information about any problems that occurred duringinstallation, consult the ITLM_install.log file. The file is written in the followinglocation:

Windows%TEMP%\ITLM_install.log

AIX $tmp/ITLM_install.log

Following installation, perform the following checks to ensure that the componentshave been correctly installed:v Check the connection to the Tivoli License Manager administration and runtime

databases, as follows:1. Initialize the DB2 command line on the computer where the Tivoli License

Manager administration or runtime server is installed.2. Enter the following command:

db2 connect to <database name> user tlmsrv

Where <database name> is tlma for the administration server database andtlmr for the runtime server database.

3. Enter the database password when it is requested.

The following information is returned if the connection succeeds:Database Connection Information

Database server = DB2/6000 7.2.5SQL authorization ID = TLMSRVLocal database alias = <database name>

If you do not get this result, there is a problem with the database or with theconnection between the Tivoli License Manager server and the database. See“Databases” on page 84 for details of the possible reasons.

v Check the HTTP server on computers where you have installed a Tivoli LicenseManager server, as follows:1. Open a browser.


2. In the Address box, type the host name of the computer where the TivoliLicense Manager server is installed. The HTTP welcome screen shouldappear.

If this panel does not appear, first check that the host name you typed iscorrect, and if so, check that the HTTP server is running.

v Check the Tivoli License Manager data source on WebSphere Administrator’sConsole, as follows:1. Start the WebSphere Administrator’s Console.2. Open Administrative Domain Tree > Resources > JDBC Providers.3. Find the Tivoli License Manager administration DB2 driver or the Tivoli

License Manager runtime DB2 driver.v Check that the Tivoli License Manager administration or runtime server is

included in the WebSphere Application Server list of application servers for thehost where it is installed and that the application server has been started. To dothis, complete the following steps:1. On the WebSphere Administrator’s Console, open Administrative Domain

Tree > Nodes > <host name> > Application servers.

2. Find the entry for IBM Tivoli License Manager Administration Server or IBMTivoli License Manager Runtime Server.

3. If the server has not been started, start it by selecting it and clicking the Playicon on the task bar.

If the server is not included in the list of application servers, the installation orthe WebSphere Application Server configuration has failed. Consult theITLM_install.log file for details of the failure.

If the server has installed successfully but the WebSphere Application Serverconfiguration failed, you must manually run the configuration script. SeeTable 24 on page 83 for a list of the WebSphere Application Server configurationscripts for each platform, WebSphere Application Server version, and servertype.

Validating installation


If the server fails to start and an exception message informs you that the HTTPtransport port is in use, you need to reconfigure WebSphere Application Serverto use a different port. The procedure for resolving this is described in the“Common problems” on page 80. See “Servers” on page 80.

v Check that the following have been included in the list of the WebSphereApplication Server host aliases and, if not, add them:– The host name of the computer where the Tivoli License Manager server is

installed as both a simple host name, for example alpha, and as a fullyqualified name, for example alpha.ibm.com.

– The IP address of the computer where the Tivoli License Manager server isinstalled if this is being used instead of the host name.

Note: If you are not using the default port (80), the port number must beappended to all the aliases, for example, alpha:443.

To check the aliases on WebSphere Administrator’s Console, complete thefollowing steps:1. On the WebSphere Administrator’s Console, select Virtual

hosts/default_host.2. Click General.

If you have made any changes to WebSphere Application Server configuration,stop and restart WebSphere Application Server.

v Check the Tivoli License Manager command line:1. On the administration server computer, open the Tivoli License Manager

command line.2. Type:

expcat

This command should export the master catalog from the administration serverdatabase to the directory: <INSTALL_DIR>\admin\cli\catalog

If the command fails to extract the catalog, this indicates a failure to access thedatabase, probably caused by a mismatch between the DB2 password enteredduring the server installation and the password defined for the tlmsrv user.

Log files and tracingTivoli License Manager provides information in the form of messages, trace logfiles, event log files, and event notifications. This section includes informationabout the trace files that are available on the administration server, runtimeservers, and agents.

Event notifications are generated in response to licensing events and to TivoliLicense Manager system events, for example, that a server or agent has stopped.Notifications are sent to designated recipients and the events are logged. For moreinformation about the event logging and notification, see Chapter 6, “Eventnotification”, on page 55.

For information about messages, see Appendix A, “Messages”, on page 97.

Validating installation

Chapter 9. Problem determination 75

Logging and trace setting on serversOn the administration and runtime servers, Tivoli License Manager logsinformation in the following files:v error-x.log (where x is a number between 0 and 9).

An entry is logged in this file for all exceptions generated by Tivoli LicenseManager.

v time-x.log (where x is a number between 0 and 9).Time stamped entries in this file are logged for all communication services(start/stop).

v trace-x.log (where x is a number between 0 and 9). This file includes entriesfor trace, debugging and data operation information.

Each file has a maximum size of 1 MB. When the maximum size is reached,logging moves to the next file in sequence. For example, when error-1.log reaches1 MB, error log entries are written to error-2.log and so on. When error-9.logreaches the maximum size, the cycle begins again.

Log files are created in the following directories on the administration server andall runtime servers:

Administration server<INSTALL_DIR>\admin\log

Runtime server<INSTALL_DIR>\runtime\log

The level of information that is included in log files depends on the trace levelsetting for the server as shown in Table 23.

Table 23. Trace levels and log files

Trace level Description Files

0 Error error.log

1 Debug trace.x.log

2 Trace trace.x.log

3 Data trace.x.log

4 Time time.log

-1 Disabled none

You set the trace level in the traceFilter.properties file. There is a copy of thisfile on the administration server and on each runtime server that you install.Therefore, you can set the trace level independently on each server. The location ofthe traceFilter.properties file on the servers is:



There are two methods that you can use to set the trace level in thetraceFilter.properties file:1. By including the statement:

traceLevel = <number>

Log files and tracing


where number is the number of the highest trace level to be written. Forexample, the setting:traceLevel = 2

results in the logging of error (trace level 0), debug (trace level 1), and trace(trace level 2) information.

2. By including statements that set an on/off switch for each trace level. Forexample:error = 0debug = 1trace = 1data = 0time = 0

These statements result in the logging of debug and trace information.

Using this method, you can select higher trace levels without logginginformation at lower levels. This is not possible using the first method.

Note: Disabling tracing using the traceLevel=-1 statement can be overridden byturning the individual trace levels on, for example, the following definitionsresult in disabling of all tracing except error level tracing.traceLevel = -1error = 1

In addition to the statements described here, the traceFilter.properties fileincludes the statement:java.lang.Object = 1

This statement enables tracing within the Java classes. If this line is not present inthe file, no tracing will occur whatever level of trace you set. Ensure that this lineis not removed, and if it is accidentally deleted, edit the file and replace it.

Using the statusinfo command to collect error informationThe statusinfo command provides a way of collecting the trace files, configurationfiles, and database debug tables that can help IBM Software Support to resolveproblems on the Tivoli License Manager servers. You can forward this informationto IBM Software Support.

The command creates the directory <INSTALL_DIR>\admin\cli\adminStatus or<INSTALL_DIR>\runtime\cli\runtimeStatus with the following contents:v information.txt: a file that contains general information and the date and time

at which the information was gathered.v configuration: a folder that contains the configuration files for the server. This

is a copy of the server conf folder.v traceLogs: a folder that contains the trace files for the server. This is a copy of

the server log folder.v dbData: a folder that contains the .dat files exported from the DB2 database.v wasLogs: a folder that contains any WebSphere Application Server logs found in

the <INSTALL_DIR>\admin\was or <INSTALL_DIR>\runtime\was folder.

Logging and trace setting on the agentTrace settings for the agent include settings that enable tracing during deploymentand during operation.



Deployment and installation tracingAgent deployment comprises two phases: the downloading of agent files to thetarget computer and the execution of the installagent program on the targetcomputer.

In the download phase, Tivoli License Manager can send debug information to theJava console. To identify problems in this phase, do the following:1. On the runtime server from which you intend to deploy the agent, open the

agent_install.properties file and set the property parm.debug to true.The agent_install.properties file is located in the directory:<INSTALL_DIR>\runtime\conf

2. Open your Internet browser and enable the Java console.

Note: You may need to restart the browser.3. Deploy the agent on the target computer.4. Check the Java console for any exceptions that have been generated.

The log file for agent installation process that follows the download is tlmia.trc.By default, tracing of the agent deployment is turned off and the file is notproduced. If you are encountering problems, you can turn on the trace. The tracesetting is defined at runtime level in the agent_install.properties file.

The property that turns tracing on or off is called parm.trace. The default value ofparm trace is n. To enable tracing of the deployment you must edit this file andchange the value of parm.trace to y.

Agent operation tracingThe log file that is maintained during the operation of the agent is traceagt.log.

By default, only error conditions are logged to this file. If you are experiencingproblems and you need a more detailed trace to send to IBM Software Support,you must set the trace_level property in the tlmagent.ini file to 2.

The locations of the traceagt.log file and the tlmagent.ini file depend on theagent platform. See “Agent files” on page 50.

PerformanceThe performance of Tivoli License Manager depends on the following factors:v Network trafficv Database sizev Disk spacev System processesv WebSphere Application Server settingsv The HTTP configuration

Network trafficThe control of network traffic and the prevention of periodic surges of activitymust be your objectives when you set up your monitoring infrastructure anddefine configuration settings for your Tivoli License Manager servers.

Chapter 1, “Planning a Tivoli License Manager implementation”, on page 1provides some guidelines for designing your monitoring infrastructure. Default



configuration settings are provided and you do not need to change these. If youwish to make changes, do so with care and ensure that your changes do notunnecessarily increase the load on the network. For example, do not reduceperiods between uploads or downloads of data too much. For information aboutconfiguration settings, see Appendix B, “Configuration settings”, on page 107.

If you have installed a database on a separate computer from its associated TivoliLicense Manager server, database accesses can become a bottleneck. To minimizethis, ensure that there is a high-speed connection between the database and servercomputers.

Database sizeThe performance of the administration server Web interface will be reduced if tablesizes in the administration database become too large. Most of the database tablesare reasonably static as they include information that the administrator defines.However, the USAGE and SERVICE tables are continually updated by internalprocesses. A reduction in performance of the software usage reports is a symptomthat the USAGE table has become too large.

Cleanup processes are provided for these tables. Schedule them to run at intervalsthat are suitable to the size of your Tivoli License Manager implementation. SeeChapter 8, “Database table cleanup”, on page 71.

Disk spaceThe administration and runtime servers each require a minimum of 50 MB ofspace on AIX and 100 MB of space on Windows for storing logs, trace files, andconfiguration information. The associated DB2 databases require considerably morespace. The requirements depend mainly on the number of agents supported. Youshould perform regular checks on the amount of free space on the computerswhere the Tivoli License Manager and DB2 servers are installed.

System processesThe administration and runtime servers run on top of WebSphere ApplicationServer. They all run in different Java virtual machines. You should keep track ofsystem resource usage, in particular memory and I/O, especially on heavily loadedcomputers. To check the use of resources by the Tivoli License Manager servers,you will need their process IDs. You can obtain the process ID for a server byclicking it on the WebSphere Administrator’s Console.

WebSphere Application Server settingsThere are two related values that can be set in the WebSphere Administrator’sConsole for each server: initial and maximum Java heap sizes. The initial Java heapsize sets the amount of memory that is initially reserved for the application, whilethe maximum Java heap size determines the largest amount of memory theapplication will be allowed to consume.

If a runtime server has more than 5 000 agents deployed, you need to increase thedefault value for the initial Java heap size setting to maintain performance.

To change the Java heap size settings for a runtime server, complete the followingsteps:1. On the WebSphere Administrator’s Console, select the runtime server for which

you want to change settings.

Performance


2. Click the JVM settings tab.3. Change Initial Java heap size to 256.

HTTP configurationPerformance of runtime servers responding to multiple concurrent requests will beunsatisfactory if the HTTP configuration setting for the default size of thread poolis too low.

In the httpd.conf file, ensure that the parameter that controls this is set to at least150. The name of the parameter is:

WindowsThreadsperchild

AIXMaxClients

The location of the file is IBM HTTP Server/conf.

Common problemsThis section provides a listing of some common problems, their symptoms, andsolutions.

Server installationSymptom: Setup file cannot be launched.

On an AIX platform, you try to launch the setupaix.bin file and thefollowing message is displayed:

Unable to load the launcher file index. Cannot open launcherfile.

Cause and solution:

You are not logged on as root. Log on as root and try again.

ServersSymptom: The HTTP port is already in use.

An exception occurs on the WebSphere Administrator’s Console when youtry to start a Tivoli License Manager server that you have installed. Theexception reports that the HTTP transport port is already in use.

Cause and solution:

This occurs because the Tivoli License Manager script for configuringWebSphere Application Server specifies a port that is already in use by anapplication server. To resolve this problem you must complete thefollowing steps:1. Find out which port numbers are in use, by using the following

command:

Windowsnetstat -an

AIXnetstat -an |grep LISTEN

Performance


Check the list of ports to see if port 9087 or 9088 is available.2. Open the script file.

See Table 24 on page 83 for information about the correct WebSphereApplication Server configuration script to use.

3. Change the port parameter to a port number that is not in use.4. From the setup directory, run the deleteAdmin or deleteRuntime script.5. From the setup directory, run the appropriate WebSphere Application

Server configuration script.

Symptom: A runtime server does not plug in (connect to the administrationserver).

Following registration of a runtime server, it does not plug in to theadministration server.

Possible causes and solutions:

The reason or reasons for failure are recorded in the event.log file for theadministration server, which is stored at the following location:<INSTALL_DIR>\admin\log.

This problem is typically caused by a misconfiguration, either duringinstallation or during registration of the server on the administrationserver:v There is a mismatch between the values entered at installation and at

registration for customer name, runtime server name, or runtime serverpassword.

v The administration server address that was specified during installationwas incorrect.

If the problem is the customer or runtime server name, check theregistration details of the server, if the values are incorrect, they can bechanged there. If not, you must change the installation values by editingthe scp.properties file for the runtime server.

If the passwords do not match, you must align the passwords. You canchange the password held in the administration server database using theChange server function on the administration server Web interface.Alternatively, you can run the rtpasswd command from the command lineon the runtime server computer to change to the runtime server passwordheld in the password.properties file and align it with the value stored inthe administration server database.

An apparent mismatch between runtime server installation and registrationdetails can also be caused by a misconfiguration of the primary languageenvironment on the runtime server. If an event that is logged in theadministration server event log has values for runtime server name andcustomer that contain incorrect characters, the problem is likely to becaused by a language misconfiguration. Check the cultural conventions,language, and keyboard settings, and ensure that they are set to the correctvalues. If they are not, you must uninstall the Tivoli License Managerserver and WebSphere Application Server, and correct the settings beforereinstalling WebSphere Application Server and Tivoli License Manager.

If the event log shows no record of the runtime server failing to connect tothe administration server, the problem is almost certainly caused by theruntime server configuration having the wrong address for the

Common problems


administration server. Check the value stored in the scp.properties file forthe runtime server which is stored in the following location:<INSTALL_DIR>\runtime\conf.

Symptom: A runtime server is no longer plugged in.A runtime server that has previously plugged in to the administrationserver fails to plug in when the server has been stopped and restarted.


This failure is caused by a mismatch between the server ID passed by theruntime server to the administration server and the ID that theadministration server has stored in its database. This can happen in thefollowing circumstances:v The runtime server administrator has manually transferred the server to

a different customer without dropping the runtime server database.v The runtime server has been deleted from the administration server

database and then reregistered.

In both cases, the runtime server has changed its identity making all thedata stored in its database invalid. You must stop the runtime server, dropthe runtime server database, create a new database and restart the server.See “Creating a DB2 database for Tivoli License Manager” on page 24.

Symptom: Following editing of the scp.properties file on a runtime server,communications between the runtime server and administration server fail.

This is a problem that has been noted when the scp.properties file hasbeen edited in some languages that use a double-byte character set (DBCS).


This problem occurs because the scp.properties file has been saved in thewrong format. To resolve the problem in a Chinese environment, completeone of the following procedures depending on whether the runtime serveris installed on a Windows or an AIX platform.

On Windows platforms with the GB18030 support package installed,complete the following steps:1. Go to the <INSTALL_DIR>\conf folder and rename the scp.properties

file to scp.properties.txt.2. Open scp.properties.txt in Notepad.3. Make any changes that are required and save the file, selecting the

Save as Unicode checkbox in the Save As dialog.4. Start the gbunicnv.exe application.

This application is available in the GB18030Tools folder.5. Complete the dialog as follows:

Source file scp.properties.txt

Target file scp.properties

Option Convert Unicode to GB18030-20006. Click Convert.

On an AIX5L platform with the GB18030 patch installed, complete thefollowing steps:1. Go to the <INSTALL_DIR>/conf folder and rename the scp.properties

file to scp.properties.txt.

Common problems


2. Open scp.properties.txt in a text editor.3. Make any changes that are required and save the file with Unicode

encoding.4. Generate the scp.properties file using the following command:

iconv -f UCS-2 -T GB18030 scp.properties.txt >scp.properties.

Symptom: The srvstart command does not start a server.You run the srvstart command from the command line on an AIXcomputer where a Tivoli License Manager server is installed, but the serverdoes not start.


This failure is probably the result of a known problem with WebSphereApplication Server 3.5.x on AIX. You need to clear the working directoryon the administration console for the Tivoli License Manager server.

WebSphere Application Server configurationSymptom: A Tivoli License Manager server is missing from the WebSphereApplication Server list of application servers.

When you try to start a Tivoli License Manager server from the WebSphereAdministrator’s Console, it is not present in the list of application servers.


The WebSphere Application Server configuration process that is a part ofthe Tivoli License Manager installation wizard has failed. This is probablybecause WebSphere Application Server was not running when the wizardtried to perform the configuration. In some cases, for example on WindowsNT platforms and when the install path used is not the default path, theconfiguration error is not reported. You must manually run the WebSphereApplication Server configuration script that is usually called by theinstallation wizard. Table 24 shows the configuration scripts for eachcombination of platform, WebSphere Application Server version, andserver type.

Table 24. WebSphere Application Server configuration scripts

Platform

WebSphereApplicationServer version Server Script

AIX 3.5.6 administration <INSTALL_DIR>/admin/setup/WASConfig.sh

AIX 3.5.6 runtime <INSTALL_DIR>/runtime/setup/WASConfig.sh

AIX 4.0.4 administration <INSTALL_DIR>/admin/setup/SetupAdmin.sh

AIX 4.0.4 runtime <INSTALL_DIR>/runtime/setup/SetupRuntime.sh

Windows 3.5.6 administration <INSTALL_DIR>\admin\setup\WASConfig.bat

Windows 3.5.6 runtime <INSTALL_DIR>\runtime\setup\WASConfig.bat

Windows 4.0.4 administration <INSTALL_DIR>\admin\setup\SetupAdmin.bat

Windows 4.0.4 runtime <INSTALL_DIR>\runtime\setup\SetupRuntime.bat

Symptom: WebSphere Application Server does not work with DBCS pathname.When Tivoli License Manager is installed in a DBCS environment,WebSphere Application Server is unable to correctly interpret thepathnames for WebSphere Application Server stdout and stderr log filesthat are associated with Tivoli License Manager.

Common problems


Cause and solution:

The only way to resolve this problem is to delete the working directoryand the stdout and stderr entries for Tivoli License Manager from theWebSphere Administrator’s Console. Logs will then be written to thedefault location for WebSphere Application Server logs and not to the pathspecified during installation of Tivoli License Manager.

DatabasesSymptom: Server Web interface cannot connect to the database.

After logging on to the Web interface, an error message indicating adatabase technical error appears.


The possible reasons for this problem are the following:v DB2 services were not running during the installation process or were

started after WebSphere Application Server started. Restarting DB2 andWebSphere Application Server should solve this problem.

v The script has not been run to create and populate the database. Run thescript. See “Creating a DB2 database for Tivoli License Manager” onpage 24.

v The connection between the Tivoli License Manager server and thedatabase was not established. See “Connecting a database to a TivoliLicense Manager server on a Windows computer” on page 26 or“Connecting a database to a Tivoli License Manager server on an AIXcomputer” on page 27.

Note: If the server is on an AIX computer, you must make theconnection between the database and server even if they are onthe same computer.

v The wrong value has been used for the database name in thedb.properties file. See “The db.properties file” on page 113.

v The password held in the passwd.properties file does not match thepassword for the tlmsrv user. You can change the tlmsrv passwordusing the utility for changing user passwords on your operating systemor you can change the password held in the passwd.properties file,using the command dbpasswd. See “dbpasswd” on page 42.

Symptom: Data is missing from historical reports.Updated information is missing from the software usage and inventoryreports on the administration server.


This problem could be caused by a runtime server stopping or by a failureof communication between runtime server databases and theadministration server database.v If the runtime server has stopped, the administrator will have received

an event notification and the event will be logged in the event log. Youcan restart the server either using the WebSphere Administrator’sConsole or by issuing the srvstart command from the Tivoli LicenseManager command line. See Chapter 4, “The command line interface”,on page 41.

v If the runtime server has only recently been installed, the problem maybe caused by mistakes made during the installation and configuration of

Common problems


the runtime server database. This requires the same checks and actionsas described for the previous problem where the administration serverdatabase could not be accessed by the administration server Webinterface.

v If there has previously been successful communication between thedatabases and if the problem affects data from all runtime servers, theproblem is probably caused by a data mismatch following the re-creationor restoration of the administration server database.To resolve this problem, you must drop all runtime server databases andre-create them. See “Creating a DB2 database for Tivoli LicenseManager” on page 24.To avoid this situation, make backups of the administration and runtimeserver databases at the same time and restore all databases if theadministration server database needs to be restored.

Note: You must stop servers before performing the backup or restoreand then restart them when the operation is complete.

Agent deploymentSymptom: The installagent applet is not found.

When you open the deployment Web page, a message appears in thestatus bar indicating that the Installagent applet cannot be found orcannot start.


The applet is corrupt. This can occur if you install the runtime server on acomputer that has WebSphere Application Server 4.0.x without fix pack 4.You must apply the fix pack and reinstall the server.

Symptom: Agent deployment process hangs because of insufficient space. A Javaexception occurs.

The Registration in progress message appears and after a reasonablelength of time there is no message indicating success or failure. When youcheck the Java console, the following exception is reported:

Java.io.exception. No space left on device.


This problem occurs when there is insufficient space for the temporarystorage of agent files. At least 10 MB of free space is required in thedirectory used by the browser for temporary storage of downloaded files.On UNIX platforms, this directory is /tmp. On Windows platforms, thedirectory depends on the Internet browser being used.

You may need to increase the size of the file systems where the browser isinstalled.

Symptom: Agent deployment process hangs because of network traffic. A Javaexception occurs.

The Registration in progress message appears and after a reasonablelength of time there is no message indicating success or failure. When youcheck the Java console, the following exception is reported:

Error loading class: com.ibm.it.rome.slm.applet.SlmInstallAgent.

Common problems



Download of the agent was unsuccessful because of network congestion.Retry the deployment later.

Symptom: Agent deployment process hangs. No Java Virtual Machine isinstalled.

The Registration in progress message appears and after a reasonablelength of time there is no message indicating success or failure. When youcheck the Java console, you find that there is no Java Virtual Machine, andhence no Java console, installed with the browser.


This problem occurs with certain versions of the browsers on certainplatforms, for example, with Internet Explorer, version 6.0 running onWindows NT, version 4.0. In this case, both the browser and the operatingsystem assume that Java Virtual Machine is bundled with the other.

To correct this problem go to the Web site of the browser, and downloadand install the appropriate Java Virtual Machine.

Symptom: Agent files cannot be downloaded.Agent deployment fails with the following message:

An error occurred downloading the file: path/filename. Thedestination directory directory might be full.


This problem occurs when there is insufficient space for the agent files.There must be at least 10 MB of free space in the agent installationdirectory where the files are permanently located. You may need toincrease the size of the file systems where the agent files will be installed.

This problem might also occur when you are not logged onto the node asAdministrator. This is because you do not have the necessary permissionsto write to the directory.

For information about the locations in which agent files are installed ondifferent platforms, see “Agent files” on page 50.

Symptom: Agent files cannot be downloaded.Agent deployment fails with the following message:

Connection was reset by peer.


This is a network connectivity problem that can be caused by an unusuallyhigh amount of traffic or by a server error. Wait for a short time and thenretry the operation. If the problem persists, report the problem to thesystem administrator. You could try deploying the agent from a differentserver.

Symptom: Deployment is denied.Agent deployment fails with the following message:

You are not logged on with administrative/root rights. You arenot allowed to register the IBM Tivoli License Manager agent.

Common problems



Only users with administrator (Windows) or root (UNIX) rights areallowed to deploy the agent on a computer.

Log on as Administrator or root and try again.

Symptom: Deployment fails with a file error.Agent deployment fails with the following message:

An error occurred while verifying the file: filename. The filemight be damaged.


This is probably caused by server or network problems that interrupted thetransmission of the file from the server to the node.

Retry the deployment. If the problem persists, the copy of the agent fileheld on the runtime server might be corrupt.

Try deploying the agent from a different runtime server. If this works, it islikely that the problem is a corrupt file or files on the original runtimeserver. To resolve this problem, copy all of the agent directories andsubdirectories from the runtime server that deployed the agent successfullyto the runtime server where the files are probably corrupt.

Symptom: Deployment fails with internal error.Agent deployment fails with the following message:

An internal error occurred during the registration. Your systemis not registered.


This is probably caused by problems with the browser Java virtualmachine. Check that you are using a level of browser that is compatiblewith deploying the Tivoli License Manager agent. See “Prerequisites” onpage 11.

Netscape on AIX may need to be updated or patched because of knownproblems. Refer to:https://techsupport.services.ibm.com/server/fixes?view=pSeries.

Symptom: Deployment fails because of unsupported operating system.Agent deployment fails with the following message:

Your operating system is not supported.


There is no agent for the platform you are trying to deploy to. Check thelist of supported platforms in the IBM Tivoli License Manager: Release Notes.

Symptom: Deployment fails because the applet certificate was not accepted.Agent deployment fails with the following message:

The registration failed. You may have not accepted the appletcertificate. If you have not accepted the applet certificate, youshould retry the registration, accepting the applet certificate.Otherwise, contact the IBM Tivoli License Manager administrator.

Common problems


https://techsupport.services.ibm.com/server/fixes?view=pSeries


If you did not accept the certificate, retry the deployment and accept thecertificate when the dialog appears.

If you did accept the certificate, this could mean that the applet file iscorrupt. This can occur if you install the runtime server on a computer thathas WebSphere Application Server 4.0.x without fix pack 4. You mustapply the fix pack and reinstall the server.

Symptom: Agent deployment process hangs after you have have responded Noon the Security Warnings and refused the installation of files.

After you have responded No to the request for permission to install fileson your computer, the following message should appear:

The registration failed. You may have not accepted the appletcertificate. If you have not accepted the applet certificate, youshould retry the registration, accepting the applet certificate.Otherwise, contact the IBM Tivoli License Manager administrator.

The message does not appear. Instead, the browser hangs.


This problem occurs on Internet Explorer when it is using its own virtualmachine. To avoid the problem, download and install the Sun Java plug-inand assign it as the default for the Internet Explorer browser.

Symptom: No status is returned to the runtime server.No acknowledgement of success or failure is displayed. The followingmessage appears:

Some problems occurred while sending the Agent Installationstatus back to the runtime server.


Check that the agent has been installed on the node.v On Windows, you can open the services panel from the control panel

and check for Tivoli License Mgr Agent.v On UNIX, enter the following command:

ps -ef | grep tlmagent

If the agent is running a response is returned. If it is not, there is noresponse.

Symptom: Agent install process returns a failure return code.The following message is returned by the agent install process:

An error occurred registering the Tivoli License Manager Agent.Return code: number.


Table 25 on page 89 lists the possible causes and solutions: for each returncode that can be included in the message. If the problem persists, you canget more information by enabling agent deployment tracing. See“Deployment and installation tracing” on page 78.

Common problems


Table 25. Installagent return codes

Return code Possible cause Solution

-1 v Invalid character in the computer labelparameter.

v Invalid character in the customer or servername.

v The agent_install.properties file on theserver is corrupt or incorrectly modified.

v Check your input for computer label.

v Check the customer and server names in thescp.properties file for the server.

v Check the agent_install.properties file.

-2 The Windows environment variable %WINDIR%does not exist.

Check:

My Computer > Properties > Advanced> Environment.

-3 v The agent ID cannot be created because of amisconfiguration of the host name/DNS on thesystem.

v The agent configuration file could not bewritten.

v Check the host name, domain name, and DNSconfiguration.

v Check the disk and file systems where theagent configuration files should be installed.See “Agent files” on page 50.

-4 The main agent file could not be installed. Check the disk and file systems where the agentfile should be installed. See “Agent files” onpage 50.

-5 The agent kernel extension files could not beinstalled.

Check the disk and file systems where the agentkernel files should be installed. See “Agent files”on page 50.

-6 The agent kernel extension could not be installed.(AIX and Sun only).

Check the disk and file systems where the agentconfiguration files should be installed. See“Agent files” on page 50.

-8 The agent failed to start. Check the system and try to start the agent.

-11 The agent kernel extension configuration filecould not be installed (AIX and Sun only).


-12 The agent configuration file could not beinstalled.


-13 The agent uninstall script could not be installed. Check the disk and file systems where the agentuninstall script should be installed. See “Agentfiles” on page 50.

-15 Linux distribution is not supported. Check the supported platforms in the IBM TivoliLicense Manager: Release Notes.

-16 The tables and files for national language supportcould not be installed.

Check the disk and file systems where the tablesand files for national language support should beinstalled. See “Agent files” on page 50.

-17 The check for prerequisite free space on diskfailed.

Free enough space to install the agent. See Table 2on page 12 for agent space requirements.

-18 It was not possible to create the trace file in thedirectory you specified.

Check that the directory exists and that you havethe appropriate permissions to write in it.

Agent operationFor some agent problems, the symptom is detected at the server. For others, thesystem administrator might receive a communication from the application user onwhose system the agent is running, sometimes by way of the license administrator.

Common problems


Some of the solutions require the system administrator to ask the application userto take some action, such as enter a specific command.

Symptom: The agent does not start automatically.After deployment on a Windows platform, the agent does not start.


This problem occurs when the Windows Services panel is open when thedeployment is performed. If the service IBM TLM agent is present but notrunning, you can start it manually by selecting it in the Windows servicepanel and clicking Start or from the command line as follows:

%windir%\itlm\tlmagent -g

If the service is not present, you must use the following commands toregister it and then start it:

%windir%\itlm\tlmagent -i%windir%\itlm\tlmagent -g

Symptom: The agent cannot be stopped.The agent running on a UNIX platform cannot be stopped.


This occurs if you try to stop the agent when the traceagt.log file is open.

Close the file and try again.

Symptom: After deployment, the agent does not appear in the administrationserver agent report.

The agent has been deployed successfully. The agent files are on the targetcomputer and the agent is running but the agent is not included in theagent report or in the lists of agents for the server and division to which itis assigned.


This problem occurs in the unusual situation that a monitored computerchanges from one customer to another. For example, the problem couldoccur if the decision has been made to divide a large enterprise into two ormore customers.

When the agent is deployed from a runtime server assigned to the firstcustomer, an agent record for this customer is created in the administrationserver database. When the agent is redeployed from a runtime serverassigned to the second customer, a new record for the agent under thesecond customer cannot be created while the original record exists. Thismeans that though the agent is in contact with its runtime server and issending information to the server, the runtime server cannot transmit thisinformation to the administration serer because of the database mismatch.

To resolve this problem, uninstall the agent and redeploy it from theruntime server that is assigned to the second customer. The agent now hastwo records in the administration server database, for two differentcustomers and with two different IDs. The original agent record can bedeleted only after it has been recognized by the runtime server that it isinactive and this information has been forwarded to the administrationserver.

Common problems


Symptom: A message containing an error code is displayed at the agent.The error messages that contain error codes also contain the name of theagent subcomponent that is associated with the error. The messages are asfollows:v 3502 Error error code occurred while attempting to install agent

subcomponent.

v 3504 Error error code occurred while attempting to remove agentsubcomponent.

v 3506 Error error code occurred while attempting to start agentsubcomponent.

v 3508 Error error code occurred while attempting to stop agentsubcomponent.

v 3513 Error error code has occurred in the agent subcomponent agentsubcomponent.

v 3520 Error error code occurred during the initialization of theagent.

The error code is one of the following:

Table 26. Agent subcomponent error codes

Error Code Meaning

-1 An attempt has been made to start an agent subcomponent that hadalready been started.

-2 An attempt has been made to stop an agent subcomponent that hasnot been started.

10 An error occurred when attempting to open the agent subcomponentdatabase (Windows platforms only).

21 An error occurred in the creation of the agent subcomponent.

22 An error occurred while accessing the agent subcomponent.

23 An error occurred while starting the agent subcomponent.

24 An error occurred while stopping the agent subcomponent.

25 An error occurred while removing the agent subcomponent.

31 An error occurred while registering the agent driver.

32 An error occurred while accessing the agent driver.

33 An error occurred while starting the agent driver.

34 An error occurred while stopping the agent driver.

35 An error occurred while removing the agent driver.

40 An error occurred while opening the Windows registry (Windowsplatforms only).

41 An error occurred while creating the Tivoli License Manager agent keyin the Windows registry. (Windows platforms only).

42 An error occurred while reading the Tivoli License Manager agent keyin the Windows registry (Windows platforms only).

43 An error occurred while writing the Tivoli License Manager agent keyin the Windows registry (Windows platforms only).

44 An error occurred while deleting the Tivoli License Manager agent keyin the Windows registry (Windows platforms only).

50 An error occurred while reading the Tivoli License Manager agentmain path .

Common problems


Table 26. Agent subcomponent error codes (continued)

Error Code Meaning

51 An error occurred while creating the agent directory.

60 An error occurred while initializing the agent.

61 An error was found in the Tivoli License Manager agent configurationfile.


If one of these problems occurs, contact IBM Software Support and reportthe message. “Contacting software support” on page xiii contains a link tothe IBM Software Support Guide, which explains how to contact IBMSoftware Support and what information to prepare beforehand.

Symptom: A problem is reported with the agent configuration file.The agent fails with the following message:

3519 An error has occurred while loading the configuration fileconfiguration file name.


Contact IBM Software Support and report the message. “Contactingsoftware support” on page xiii contains a link to the IBM Software SupportGuide, which explains how to contact IBM Software Support and whatinformation to prepare beforehand.

Symptom: The agent fails to contact the runtime server.The agent fails with the following message:

3522 The agent failed to contact the runtime server runtimeserver name.


Check that the indicated runtime server is available to other agents. Checkit is available in the network by pinging it. Ask the application users atagents that use the same runtime server if they have experienced the sameerror. If the runtime server is available to other agents, it might have beenunavailable temporarily to the agent where the error occurred. Restart theagent by asking the application user to locally submit the followingcommand:

%windir%\itlm\tlmagent -g

If the problem persists, contact IBM Software Support and report themessage. “Contacting software support” on page xiii contains a link to theIBM Software Support Guide, which explains how to contact IBM SoftwareSupport and what information to prepare beforehand.

Symptom: The agent is not able to create the inventory scan.The agent fails with the following message:

3524 Unable to create the inventory scan.

Common problems



Contact IBM Software Support and report the message. “Contactingsoftware support” on page xiii contains a link to the IBM Software SupportGuide, which explains how to contact IBM Software Support and whatinformation to prepare beforehand.

Symptom: The inventory scan has been successfully completed but could not besent to the license administrator.

The agent fails with the following message:3527 The inventory scan has been successfully completed but couldnot be sent to the License Administrator.


This problem may be a result of network congestion. Retry later. If theproblem persists, contact IBM Software Support and report the message.“Contacting software support” on page xiii contains a link to the IBMSoftware Support Guide, which explains how to contact IBM SoftwareSupport and what information to prepare beforehand.

User interfaceSymptom: The browser indicates that there is a problem with the format of theHTTP header.

When you connect to the server, the browser makes the connection andthen displays a message indicating that the HTTP header is in an incorrectformat.


This problem occurs when the browser setting for the languages in usecontains an entry that is not a valid language for Tivoli License Manager.Check the browser settings for the languages and remove any entries inthe languages list that are not true languages, for example, [pdf].

Symptom: A technical error is produced by the first action after logon.After logging on, when you attempt to perform your first action, forexample, selecting the customer, a technical error is generated.


This problem occurs when the browser is not enabled for JavaScript.Change the browser setting to enable JavaScript and try again.

Symptom: Additional windows do not open automatically.Every time an additional window is required, for example, when you logon or when you click the Help icon, you are prompted to confirm that itshould open.


This occurs if you have software activated to prevent pop-ups fromopening automatically. If you want to avoid the confirmation step eachtime Tivoli License Manager needs to open a supplementary window, youmust disable this software.

Symptom: Problems displaying a chart.The Web interface cannot display the software usage trend analysis chart.

Common problems



This problem can occur when the administration server is installed on anAIX platform and there is no access to an X display server. You mustensure that the administration server has access to an X display server. SeeAppendix E, “Connecting to an X display server”, on page 123.

Symptom: Problems displaying report pages.Software usage and inventory reports do not display correctly the first timethe report page is displayed. The report is often positioned wrongly on thereport or only a part of the expected information is shown.


This is caused by a known problem with Internet Explorer 5.5. which isresolved with Internet Explorer 6.0. Refreshing the page using the Refreshicon on the Web interface toolbar corrects this display problem.

Symptom: Pages do not refresh correctly.When the refresh icon is selected from the toolbar to refresh theinformation on a page of a report, the page is redisplayed with oldinformation stored in the cache during an earlier production of the report.


This problem occurs when the browser setting that controls when the cacheshould be updated with a more recent version of a page is set to neverupdate or only to update once during a session. Change the settingAutomatically or Every visit to the page in Internet Explorer and to Everytime in Netscape.

ReportsSymptom: Products are missing from the software usage reports.

Products that you know have been in use on monitored nodes do notappear in the software usage reports.


There are several possible causes for this:v The product is not in the runtime catalog used by the agent on the

monitored node.

If you have recently installed the runtime server and deployed agents, orif you have recently installed a product that does not have softwareentitlement details set up, this is a likely cause for the problem. Forperformance reasons, the catalog of products to be monitored that isused by the agent does not include all products included in the mastercatalog. It only includes products that have software entitlement settingsand products that have previously been detected by the agents thatreport to the same runtime server. If the agent detects a product that isnot in the runtime catalog, it adds it to a list of unknown files that isperiodically forwarded to the runtime server and used to add entries tothe runtime catalog, which is then downloaded to agents. For thisreason, there is a time delay between the first detection of a product andthe first time the product appears in a report.

v The product is not in the Tivoli License Manager master catalog.

Only products that are included in the master catalog can be included inany Tivoli License Manager reports. Unregistered products will notappear in either the software usage or inventory reports. You can check

Common problems


whether a product is in the master catalog, by looking in the list ofproducts for selection on any of the Tivoli License Manager reports.Unregistered products that are detected by the agents are included in theunknown file lists which is forwarded by runtime servers to theadministration server. This information is stored in the administrationserver database. You can extract it together with the current version ofthe master catalog and use the catalog manager tool to add new entriesto the catalog.

v The product has more than one module and the module detected bythe agent is not included in the master catalog.

If the list of products in the report wizard does include the product thatis missing from reports, a likely reason is that the master catalog hasincomplete information about the modules that are part of the product.Because of this the module will have been included in the list ofunknown files.Check the name of the module, then use the catalog manager to updatethe master catalog. Find the module in the list of unknown files andassociate it with the catalog entry for the product.

v The name of the module is incorrectly interpreted by the agentbecause of inconsistent language settings, and for this reason cannotbe matched with an entry in the catalog.

This problem occurs on multiuser UNIX computers where languageswith different character sets are in use, and the users are not all usingthe default character encoding settings.The agent interprets the information from the file using the defaultcharacter encoding settings. If the user who created the file is not usingthese settings, the character interpretation will not be correct.To avoid this problem, ensure that the character encoding settings for allusers are aligned with the system default settings, as follows:

SystemLC_CTYPE = language.UTF-8

UserLANG = language.UTF-8

LC_ALL = language.UTF-8

where language is a variable that can be different for each user.

Symptom: Software usage reports show a lower number of sessions in use thanexpected.

For some products, the software usage snapshot on the administrationserver interface and the real-time software usage report on runtime serverinterfaces do not report as many sessions as you expected to see.


Some software products do not open multiple sessions even when theproduct is selected multiple times. Instead, the new request is added to theexisting session. Though you may see icons for multiple instances of theproduct, if you check the processes that are running, the list will showonly one process for the product module.

Common problems


Catalog managerSymptom: One or more entries in the unknown file table appear to becorrupted.

The data collected by the agent and added to the unknown files table isnot comprehensible.


This problem occurs on multiuser UNIX computers where languages withdifferent character sets are in use, and the users are not all using thedefault character encoding settings.

The agent interprets the information from the file using the defaultcharacter encoding settings. If the user who created the file is not usingthese settings, the character interpretation will not be correct.

To avoid this problem, ensure that the character encoding settings for allusers are aligned with the system default settings, as follows:

SystemLC_CTYPE = language.UTF-8

UserLANG = language.UTF-8

LC_ALL = language.UTF-8

where language is a variable that can be different for each user.

Event notificationSymptom: e-mail notifications of events are not received.

You have set up event notifications and recipients, but the recipients do notreceive the notifications.


Check the Mail Settings section of the system.properties file on theadministration server and on each runtime server where notifications arenot working to ensure that the mail server and mail sender have been setup properly. If they have, and if you are using WebSphere ApplicationServer version 4.0.4, edit the system.properties file and change themailEngine property from internal to external. If these steps do not solvethe problem, or if you are using WebSphere Application Server version3.5.6, contact IBM Software Support.

Common problems


Appendix A. Messages

Messages appear in the work area of the window. Each message has the followingcomponents:v An external message text, which indicates the nature of the problem.v A message code that can be used as a reference to the error condition.v An internal message text, which provides a more detailed description of the

error and the circumstances that caused it.v A message category, which is one of the following values:

Table 27. Tivoli License Manager message categories

Category Type Description and Response

1 Input error Caused by inconsistent input data in a submitted form orby a failure to find results that match input criteria. Forexample, an input error will be generated if the selectioncriteria you define for a report do not find any matchingproducts to report.

If you get this type of error, check and correct the data yousupplied.

2 Technicalerror

Caused by an internal problem within the Tivoli LicenseManager software.

Contact customer support if this type of error occurs.

3 Business error Associated with database problems, for example, datainsubstantiality, locking errors, or loss of networkconnection.

This type of error is normally caused by a temporarydatabase problem. It may correct itself. Wait and try againlater, or reboot your system.

4 Unexpectederror

The cause of these errors is not predictable.

You should contact software support if this type of erroroccurs.

5 Access error Caused by an attempt by a user to perform anunauthorized operation.

The hideInternalErrorMessage property in the Web interface section of thesystem.properties file controls which of the four message components aredisplayed when an error condition is generated. If hideInternalErrorMessage is setto false, all four components are displayed. If hideInternalErrorMessage is set totrue (the default), the situation is as follows:v For category 1 messages, in response to input errors, only the external message

text is shown.v For all other categories, the error code and the external message text are shown.


Message detailsTable 28 shows the details of the messages that appear on the Web interfaces. Itincludes the standard and long message texts and any parameters used in thetexts, the message number, and the message category of each message. The actionyou should take when a message is displayed depends on the message category.See Table 27 on page 97.

Table 28. Tivoli License Manager messages

Errorcode

External message text andparameters

Internal message text andparameters Category

666 An internal error hasoccurred. Contact your IBMTivoli License Managersystem administrator.

Message: {0}

Parameters0 = native Java error message

2

1099 The profile for user {0} cannotbe found. Ask the IBM TivoliLicense Manager systemadministrator to check youruser profile.

Parameters0 = user ID

The profile file {0} for user {1},logged on at {2} cannot be found.

Parameters0 = file name1 = user ID2 = date and time of logon

5

1100 You have used an incorrectuser ID or password. Retrythe logon.

The logon has failed for user {0}.


5

1101 Your user session has timedout or there has been someother problem with your userprofile. Retry the logon.

A user timeout occurred or there hasbeen some other problem with theprofile for user {0}.

Parameters0 = user reference previouslyassigned to the user

5

1102 An internal error occurredwhen trying to create a usersession for user {0}. Contactyour IBM Tivoli LicenseManager systemadministrator.


Access Manager could not create auser session for user {0}.


2

1103 The user ID that you chosealready exists. Choose adifferent user ID.

The user ID already exists on theXML password file.

1

1105 An internal error occurredwhen performing therequested action for user {0}.


The user session is in an illegal statefor the requested action. Message {0}.


2

Messages


Table 28. Tivoli License Manager messages (continued)

Errorcode



1500 An internal file error hasoccurred. The file {0} was notfound. Contact your IBMTivoli License Managersystem administrator.

Parameters0 = file name

The required file {0} cannot be found.More information might be found inthe log file.


2

1501 An internal I/O error hasoccurred. Contact your IBMTivoli License Managersystem administrator.

More information might be found inthe log file.

2

1502 An internal error has occurredbecause a required variablehas a NULL value. Contactyour IBM Tivoli LicenseManager systemadministrator.

A null pointer error has occurred.More information might be found inthe log file.

2

1503 An internal error has occurredbecause a required class ismissing. Contact your IBMTivoli License Managersystem administrator.

A required class cannot be found.More information might be found inthe log file. The system administratorshould also check the applicationclasspath.

2

1504 An internal error occurredwhile creating or rendering animage. Contact your IBMTivoli License Managersystem administrator.

Message {0}.


2

1505 An internal error occurredwhile creating a chart. Contactyour IBM Tivoli LicenseManager systemadministrator.

An error occurred while creatingchart {0}. Message {1}.

Parameters0 = chart ID1 = native Java error message

2

1600 An internal error has occurredbecause there are no divisionsset up in the runtime serverdatabase. Contact your IBMTivoli License Managersystem administrator.

No further information is available. 2

1601 An internal error has occurredbecause no runtime serversare available. Contact yourIBM Tivoli License Managersystem administrator.

No servers are available from thedatabase of runtime servers on theadministration server.

2

2001 A database error has occurred.Contact your IBM TivoliLicense Manager systemadministrator.

The DB2 core message is: {0} (SQLerror code = {1}).

Parameters0 = message generated by DB21 = SQL error code

2

Messages

Appendix A. Messages 99


Errorcode



2002 An error has occurred with adatabase object. Contact yourIBM Tivoli License Managersystem administrator.

A required database object could notbe found.

2

2003 An error has occurred whensaving a database object.Contact your IBM TivoliLicense Manager systemadministrator.

The object cannot be saved because itwill break unique constraints.

3

2004 An error has occurred becausethe item you are trying tomodify has been modified byanother user since youselected it. Reselect the itemand retry the operation.

An optimistic locking error hasoccurred.

3

2005 An error occurred during adatabase transactionoperation. Contact your IBMTivoli License Managersystem administrator.

An error occurred while executing acommit, rollback, or other transactionoperation.

2

2101 A database error has occurredwith a non-persistent object.Contact your IBM TivoliLicense Manager systemadministrator.

A non-valid operation was requestedfor a non-persistent object.

3

2102 An operation has beenattempted that would affectthe validity of the database.Contact your IBM TivoliLicense Manager systemadministrator.

You are trying to delete the rootadministrator, change its properties,make a wrong profile assignment, orchange an existing licenseentitlement.

3

2801 A database requiredcomponent was not found.Contact your IBM TivoliLicense Manager systemadministrator.

The JDBC driver was not found. 2

2802 A database connection erroroccurred. Contact your IBMTivoli License Managersystem administrator.

The connection pooler failed to get adatabase connection.

2

2803 It is not possible to create aconnection to the database.Contact your IBM TivoliLicense Manager systemadministrator.

No additional information isavailable.

2

2804 The database connection hasbeen lost. Try the operationagain.

A closed database connection wasfound.

2

2805 The attempt to obtain adatabase connection failed.Try the operation again.

The administration databaseconnection pooler did not initializecorrectly.

2

Messages



Errorcode



2806 The IBM Tivoli LicenseManager database versiondoes not match with theversion of the code. Contactyour IBM Tivoli LicenseManager systemadministrator.

No further information available. 2

4000 An error occurred whileinitializing the logger. Contactyour IBM Tivoli LicenseManager systemadministrator.

An error occurred while initializingclass {0}.

Parameters0 = name of the class

2

4001 A logger error occurred.Contact your IBM TivoliLicense Manager systemadministrator.

An error occurred while performinga logger task, for example, theprocessing of an event.

2

5070 An e-mail notification couldnot be sent. Contact your IBMTivoli License Managersystem administrator.

Message {0}

Parameters0 = native Java message

4

9890 An internal class error hasoccurred. Contact your IBMTivoli License Managersystem administrator.

An exception occurred whileinstantiating class (0).

Parameters0 = full name of the Java class

2

9891 An internal method error hasoccurred. Contact your IBMTivoli License Managersystem administrator.

It was not possible to get or invokemethod (0) on class (1).

Parameters0 = name of the Java method1 = full name of the Java class

2

9900 An internal model object errorhas occurred. Contact yourIBM Tivoli License Managersystem administrator.

Incorrect instance of model object. {0}instead of {1}.

Parameters0 = actual class of object1 = expected class of object

2

9902 A field is missing or out ofrange. Check that your entriesare correct and retry theoperation.

Parameter {0} is out of range,missing, required but null, or ofunexpected type.

Parameters0 = parameter name

1

9903 The specified date and time isin the future for the selectedtime zone. Change the valueand retry the operation.

No additional information isavailable.

1

9905 You have entered one or moreincorrect dates. Change thevalue or values and retry theoperation.

User {0} entered one or moreincorrect dates.


1

Messages



Errorcode



9906 You have tried to update datathat could be out of date. Youmay have more than onewindow open to perform thesame operation. Close allwindows relating to theoperation and then open onenew window to retry it.

Missing object model in the report. 1

9910 An internal error occurredwhen trying to get theresource from bundle file {0}.Contact your IBM TivoliLicense Manager systemadministrator.


Bundle file (0) was not found or doesnot contain a required key.


2

9911 An internal error occurredbecause of an unsupportedoutput format. Contact yourIBM Tivoli License Managersystem administrator.

The unsupported output format is{0}.

Parameters0 = HTML format

2

9912 An internal error occurredbecause a class field was notset. Contact your IBM TivoliLicense Manager systemadministrator.

Field {0} was not set by the servlet.

Parameters0 = field name

2

9913 An internal error occurredbecause of a missingargument. Contact your IBMTivoli License Managersystem administrator.

The argument {0} is missing for thereport.

Parameters0 = argument name

2

9914 An internal error occurredbecause of a missing attributein the user session. Contactyour IBM Tivoli LicenseManager systemadministrator.

The attribute {0} is missing in theuser session.

Parameters0 = attribute name

2

9915 An internal error occurredbecause of a missing modelobject. Contact your IBMTivoli License Managersystem administrator.

Model object {0} is missing.

Parameters0 = class name of missing object

2

9916 The GUI task you haveselected is not available.Contact your IBM TivoliLicense Manager systemadministrator.

The flow controller could not findthe requested reply.

2

Messages



Errorcode



9917 The requested data is out ofdate. You may have morethan one window open toperform the same operation.Close all windows relating tothe operation and then openone window to retry it.

Report {0} is no longer in the usersession.

Parameters0 = report name

1

9918 No {0} is available. Youcannot proceed with theoperation unless at least oneof them exists and has beenselected. Contact your IBMTivoli License Managersystem administrator.

Parameters0 = Type of item

No (0) has been returned by thedatabase query.

Parameters0 = The type of object beingqueried.

1

9919 An internal error has occurredbecause there is no storedaction to be refreshed or towhich you can go back. Logoff and log on again.

There is no action in the user sessionto be retrieved.

2

9920 An internal error has occurredbecause the http requestheader has an incorrectformat. Contact your IBMTivoli License Managersystem administrator.

An unexpected {0} header formatwas found in HttpServletRequest.

Parameters0 = header field name

2

9930 An exception error occurredwhile initializing the DOMdocument or its factoryoccurred because it was notpossible to create the DOMdocument. Contact your IBMTivoli License Managersystem administrator.

An exception occurred whileinitializing the DOM document or itsfactory.

2

9931 An internal error has occurredbecause the DOM documentcould not be built. Contactyour IBM Tivoli LicenseManager systemadministrator.

It is not possible to append node (0)in document (1).

Parameters0 = node name1 = document name

2

9932 An internal error has occurredbecause it was not possible toparse the XML file. Contactyour IBM Tivoli LicenseManager systemadministrator.

The parser failed to parse file (0).


2

Messages



Errorcode



9940 An internal error has occurredbecause the XSL transformercould not be initialized.Contact your IBM TivoliLicense Manager systemadministrator.

The XSL transformer initializationfailed. The XSL file (0) contains oneor more serious errors.

Parameters0 = XSL file name

2

9941 An internal error has occurredbecause it was not possible totransform the XML to HTML.Contact your IBM TivoliLicense Manager systemadministrator.

The XSL file (0) does not match theDOM document or contains one ormore errors.


2

9942 An internal error has occurredbecause the HTML serializercould not be initialized.Contact your IBM TivoliLicense Manager systemadministrator.

The HTML serializer initializationfailed. Check the log file.

2

9943 An internal error has occurredbecause the HTML documentcould not be serialized.Contact your IBM TivoliLicense Manager systemadministrator.

It was not possible to serialize theHTML document using a view basedon XSL file {0}.


9945 An internal error has occurredbecause a view object couldnot be instantiated. Contactyour IBM Tivoli LicenseManager systemadministrator.

It was not possible to instantiateview class {0}: exception {1} occurred.

Parameters0 = View class name1 = Java exception type

2

9950 An internal error has occurredbecause the user entitlementcould not be determined.Contact your Tivoli LicenseManager systemadministrator.

An argument {0} needed byentitlement support for user {1} isnull.

Parameters0 = argument name1 = user ID

2

9951 An internal error has occurredbecause the operation contextis not defined. Contact yourIBM Tivoli License Managersystem administrator.

User {0} has an undefined (NULL)operation context.


2

9952 An internal error has occurredbecause the operation was notfound. Contact your IBMTivoli License Managersystem administrator.

Operation {0} cannot be found.Check the operation hierarchy.

Parameters0 = operation name

2

Messages



Errorcode



9953 You are not authorized to runthis task. Log off and checkwith the IBM Tivoli LicenseManager Super Administratorthat you have been given thecorrect role for the tasks youwish to perform.

User {0} is not entitled to executeoperation {1} in context {2}.

Parameters0 = user ID1 = name of operation2 = name of context

1

9954 User {0} is not authorized touse this application. Checkwith the IBM Tivoli LicenseManager Super Administratorthat the user in question hasbeen given the correct role forthe tasks to be performed.


User {0} is not entitled to use theapplication. Logoff required.


1

9955 User {0} is not authorized tooperate in context {1}. Checkwith the IBM Tivoli LicenseManager Super Administratorthat the user in question hasbeen given the correct role forthe tasks to be performed.

Parameters0 = user ID1 = name of context

User {0} is not entitled to operate incontext {1}, type {2}, value {3}.

Parameters0 = user ID1 = name of context2 = context type3 = context value

1

9960 No existing values of {0}match the previous selections.Please make a differentchoice.

Parameters0 = requested information

No {0} has been returned by thedatabase query.

Parameters0 = type of object

1

9961 The report does not containthe entered page number.Retry the operation,specifying a valid pagenumber.

Page {0} is out of range.

Parameters0 = number of the requestedpage

1

Messages


Messages


Appendix B. Configuration settings

This appendix provides information about the configuration files maintained foreach Tivoli License Manager server and how you can use some of them to tuneTivoli License Manager to suit your needs. It includes the following information:v A summary of the configuration files that are installed for each Tivoli License

Manager server. See “Tivoli License Manager configuration files”.v A detailed description of the main server configuration file, the

system.properties file. See “The system.properties file” on page 108.v A detailed description of the configuration file for the DB2 database that is

associated with a Tivoli License Manager server. See “The db.properties file” onpage 113.

v Instructions about configuring proxy settings for communications between aruntime server and the administration server and between a runtime server andits agents. See “Configuring proxies” on page 115.

Tivoli License Manager configuration filesConfiguration files are installed in the following locations:



Table 29 provides a summary of the Tivoli License Manager configuration files thatare installed for each server.

Table 29. Configuration files for Tivoli License Manager servers

File Usage

agent_install.properties Contains the information required to download and install agents from theruntime server. Settings for debugging and tracing deployment are described in“Deployment and installation tracing” on page 78. Settings for proxycommunications between the runtime server and agents are described in“Configuring proxies” on page 115.

You should not change any other properties in this file.

csvPlugins.properties For future use.

db.properties Defines settings that control the communications between a server and itsassociated DB2 database. See “The db.properties file” on page 113.

help.properties Maps each help topic to the associated Web interface dialog. Do not edit thisfile.

locale.properties Defines localization information. Do not edit this file.

password.properties Contains the encrypted values for passwords. You must not edit this file. If youneed to change a password, you should use the appropriate command. SeeChapter 4, “The command line interface”, on page 41.


Table 29. Configuration files for Tivoli License Manager servers (continued)

File Usage

scp.properties Contains the server and customer names specified when the runtime server wasinstalled, and the address at which the runtime server contacts theadministration server. If any of these values are entered incorrectly atinstallation, you can edit the values in this file.

You can define a proxy address for the administration server. See “Configuringproxies” on page 115.

scp.services.properties Defines service handling for client and server tasks. You should not edit thisfile.

slmInitFile.properties Contains the base installation path for the server, the installation path forconfiguration files, and the installation path for log files. You should not editthis file.

stylesheets.properties Maps each Web interface dialog to a stylesheet. You should not edit this file.

system.properties See “The system.properties file”.

traceFilters.properties Defines the level of trace for the server. See “Logging and trace setting onservers” on page 76.

The system.properties fileA system.properties file is installed on the administration server and on eachruntime server. The system.properties file has the following sections:v Web interface settings.

These settings affect the behavior of the Web interfaces on the administrationand runtime servers. Most settings in this section should not be changed. See“Web Interface settings” on page 109 for those that can be changed.

v Administration server settings.The settings in this section are relevant only to the system.properties file thatresides on the administration server. See “Administration server settings” onpage 109.

v Runtime server settings.These settings affect the behavior of the runtime server, for example, the timedelays used between repeats of a task. Each runtime server has its ownsystem.properties file, so settings can be different for each server. See “Runtimeserver settings” on page 110.

v Agent settings.The agent settings that are defined in the system.properties file located on aruntime server are effective for all the agents that are registered with that server.Agent settings are downloaded from the runtime server to the agent at definedintervals. See “Agent settings” on page 111.

v E-mail configuration settings.These settings enable the sending of event notifications that are generated on theserver. See “E-mail configuration settings” on page 113.

Note: The Web interface settings must not be changed. Make changes to the othersections with caution.

Configuration files


Web Interface settingsTable 30 shows properties defined in the Web interface section of thesystem.properties file that you may need to change. You should not change anyother setting in this section of the configuration file.

Table 30. Web interface parameters in the system.properties file

Parameter Default Description

requestOldPassword false Controls whether the Change Password dialog includes afield requesting the current password.

hideInternalErrorMessage true Controls which components of error and informationmessages will be displayed. See Appendix A, “Messages”,on page 97.

maxSelectionListLength 5 000 Defines the maximum number of agents, nodes, or usersthat can be displayed in a list box on the Web interface.Increasing this value can cause decreased performance ofthe Web interface.

Administration server settingsTable 31 shows the properties defined in the administration server settings sectionof the system.properties file.

Table 31. Administration server parameters in the system.properties file


hwmScanPeriod 240 minutes Length of time between checks on the level of licenseusage. Notifications are generated if usage levels reach themaximum or a defined threshold.

cleanUsagePeriod 1 day The number of days between cleanups of the USAGEdatabase table.

cleanUsageEnabled true Possible values are:

true The USAGE table cleanup runs at the intervaldefined by cleanUsagePeriod.

false The USAGE table cleanup does not run.

maxUsageAge 30 days The number of days that software usage data should beretained in the USAGE database table. Once data is olderthan the specified number of days, it is cleared by theregular cleanup process.

adminWakeUpEnabled true Possible values are:

true Checks for changes on the administration serverare made at as defined by adminWakeUpPeriod.

false Checks for changes on the administration serverare not made.

adminWakeUpPeriod 15 minutes Length of time between checks for changes in license pooland entitlement information. If there have been changes,the administration server calls the runtime servers totrigger an update.

cleanServiceEnabled true Possible values are:

true The SERVICE table cleanup runs at the intervaldefined by cleanServicePeriod.

false The SERVICE table cleanup does not run.

system.properties

Appendix B. Configuration settings 109

Table 31. Administration server parameters in the system.properties file (continued)


cleanServicePeriod 6 hours The number of hours between cleanups of the SERVICEdatabase table.

maxServiceAge 7 days The number of days that data should be retained in theSERVICE database table. Once data is older than thespecified number of days, it is cleared by the regularcleanup process.

Runtime server settingsTable 32 shows the properties defined in the runtime server settings section of thesystem.properties file.

Table 32. Runtime server parameters in the system.properties file


defaultCapacityType 0 The capacity type that is used to meter software usage forproducts that do not have user-defined license pools.Possible values are:0 = Users1 = Memory2 = Online processors3 = Configured processors4 = Disks

defaultMultiInstance 0 The setting to be used for the multi-instance rule indefault license pools. Possible values are:0 = No multi-instance licenses1 = Allowed for the same user and agent2 = Allowed for the same user group and agent3 = Allowed for the same node and agent

runtimePluginPeriod 60 minutes Length of time between attempts to plug the runtimeserver to the administration server.

inventoryUpdatePeriod 350 minutes Length of time that the server waits between checks forinventory scans to update. When the scans arrive from theagents, they are stored until the next update time.

cacheUpdatePeriod 355 minutes Length of time between updates of the runtime catalog. Atan interval defined by this property, the runtime serverprocesses the unknown file information that has arrivedfrom the agents since the last update and determineswhich can be added to the runtime catalog.

adminDownloadPeriod 360 minutes Length of time that the server waits between downloadsof updated license, catalog, and topology information fromthe administration server.

adminUploadPeriod 365 minutes Length of time that the server waits between uploads ofsoftware inventory and agent information to theadministration server.

licenseCleanUpPeriod 370 minutes Length of time that the server waits between checks onlicense confirmations sent by agents. If the server does notfind a confirmation that a license is still in use, it releasesit even if no specific release request has been received.

system.properties


Table 32. Runtime server parameters in the system.properties file (continued)


usageSnapshotPeriod 375 minutes Length of time between uploads of software usagesnapshots to the administration server.

Snapshots are sent periodically to enable repair of theusage history if any software usage information is lost.

This property should not be set to less than 120 minutes.

maxAgentInactivity 10 080 minutes The maximum time that an agent can be not respondingbefore it is considered inactive. This period must not belower than the downloadParametersPeriod defined in theagent settings section of this file.

uploadUsageEvents true Possible values are:

true The runtime server continually sends licenseassignment and release information to theadministration server. In addition, snapshots ofcurrent usage are made at intervals defined bythe usageSnapshotPeriod property and sent to theadministration server.

false The usage snapshots are the only usageinformation sent to the administration server.

Setting this property to false will improveperformance by reducing network activity at thecost of a significant reduction in the accuracy anddetail of software usage information.

Agent settingsTable 33 shows the properties defined in the agent settings section of thesystem.properties file.

Table 33. Agent parameters in the system.properties file


pcInventoryDuration 120 seconds The time that it is likely to take for an inventory scan ofa single Windows node to be sent to the runtime server.

serverInventoryDuration 600 seconds The time that it is likely to take for an inventory scan ofa single UNIX node to be sent to the runtime server.

inventoryFilesPerPacket 25 The maximum number of entries per packet in aninventory scan.

The entries in an inventory scan are divided into packetsfor transmission to the runtime server. Once the definedmaximum is reached, the packet is sent and a new packetis started.

system.properties


Table 33. Agent parameters in the system.properties file (continued)


packetDelayThreshold 5 The maximum number of seconds normally required tosend an inventory packet to the server. If no responsefrom the server has been received within this time, theserver is probably busy and a delay in sending furtherpackets is applied to reduce traffic.

The length of the delay is calculated by taking thenumber of seconds by which this threshold is exceededand multiplying it by the packetDelayEscalation value.For example, if the default values are in use, and theresponse is received after 50 seconds, the agent willcalculate (50-30)×1 and so wait 20 seconds before sendingthe next packet.

packetDelayEscalation 30 seconds A factor used in calculating a delay to be applied whensending inventory packets. See the description of thepacketDelayThreshold property.

inventoryResendTimes 1 The maximum number of times that the agent should tryto send an inventory packet. If this number of sends isreached without success, the packet is not sent, and theinventory scan fails.

requestScope 2 Controls the runtime servers that an agent can contact.Possible values are:

0 Only the server with which the agent isregistered

1 Any server that serves agents in the agent’sdivision.

2 All runtime servers registered for the customer.

checkPeriod 10 800 seconds Length of time between checks by the agent on licensesthat have been granted. If a license is no longer in use,the agent releases it. If the license is in use, the agentsends a confirmation to the runtime server.

pingPeriod 3 600 seconds Length of time that the agent waits between checks of theconnection to its runtime server.

downloadParametersPeriod 86 400 seconds Length of time between downloads of the agentparameters from the system.properties file on theruntime server.

downloadCatalogPeriod 86 400 seconds Length of time between downloads of the runtimecatalog from the runtime server.

downloadTopologyPeriod 86 400 seconds Length of time between downloads from the runtimeserver of information about the Tivoli License Managerinfrastructure.

uploadMinTime 10 800 seconds Length of time between uploads of unknown fileinformation from the agent to the runtime server.

updateAgentEnabled No Indicates whether self-updating by agents is enabled.

If this parameter is set to Yes, the agent regularly checksthe runtime server for a new version of the agent and ifit finds one, it automatically triggers deployment usingthe server and division of the current deployment.

updateAgentPeriod 604 800 seconds Length of time between checks for the presence of a newversion of the agent on the runtime server.

system.properties


E-mail configuration settingsTable 34 shows the properties defined in the e-mail configuration settings section ofthe system.properties file. The settings relate to notifications generated on theserver where the system.properties file is located. On the administration server,notifications relate to license events. On the runtime servers, notifications aregenerated in response to changes in server or agent status and to the completion ofinventory scans. For more information about notifications, see Chapter 6, “Eventnotification”, on page 55.

Table 34. E-mail configuration parameters in the system.properties file


smtpServer The host name or IP address of a valid SMTP server.

The text must include only US ASCII characters.

mailEngine internal The mail engine to be used for sending notifications.Possible values are internal (to use the mail engineinternal to Tivoli License Manager) and external (to use anexternal mail engine that is packaged with WebSphereApplication Server). The value external is valid only if youare using WebSphere Application Server version 4.0.4.

mailSender The e-mail address that is to be used by the server as thesender address when notifications are generated.

The text must include only US ASCII characters.

mailRecipient An e-mail address to which notifications should be sent.

This is optional. Tivoli License Manager administrators arethe normal recipients of notifications, and you can specifythis when you create an administrator record using theWeb interfaces.

mailReload 1440 minutes Length of time that the server waits between reloads ofe-mail address information.

The db.properties fileThe properties defined in the db.properties file control the communicationsbetween a server and its associated DB2 database. Several of the properties mustnot be changed if the connection to the database is to function correctly.

Table 35 on page 114 shows the properties defined in the db.properties file.

system.properties


Table 35. Parameters in the db.properties file


dbUser The name of the DB2 user.

dbPoolerImplementation ExternalNote: Change this default only ifyou cannot install the JDBCdriver 2.0.

Indicates the pooler connection to be used byDB2 for the administration and runtimedatabases. Valid values are:

InternalUse the Tivoli License Manager poolerconnection capabilities.

ExternalUse the WebSphere Application Serverpooler connection capabilities. This can beused only if the DB2 JDBC driver 2.0 isinstalled. This driver is standard withWebSphere Application Server 4.0. ForWebSphere Application Server 3.5.6, youmust install the driver on theadministration or runtime server computer,and switch to it as described in the DB2documentation.

dbName For the administration serverdatabase: tlma. For the runtimeserver database: tlmr

The name of the database used for the DB2pooler settings if the dbPoolerImplementationproperty is set to Internal.

The default value should be used if the TivoliLicense Manager server with which thedatabase is associated is installed on aWindows platform. If the associated server ison an AIX platform, the value must be set totlmadb (administration server database) ortlmrdb (runtime server database.

getConnectionTimout 180 seconds The maximum time that a process waits for aconnection to a database before timing out.

maxDbConnections 15 The maximum number of connections to thedatabase if the dbPoolerImplementationproperty is set to Internal.

jdbcDriver ibm.db2.jdbc.app.DB2Driver The path to the DB2 Driver if thedbPoolerImplementation property is set toInternal. Do not change this value.

jdbcDb2UrlPrefix jdbc:db2 The Web address for the database if thedbPoolerImplementation property is set toInternal. Do not change this value.

dbJNDIName For the administration serverdatabase: jdbc/tlma For theruntime server database:jdbc/tlmr

The path to the data source if thedbPoolerImplementation property is set toExternal.

The default value should be used if the TivoliLicense Manager server with which thedatabase is associated is installed on aWindows platform. If the associated server ison an AIX platform, the value must be set tojdbc/tlmadb (administration server database)or jdbc/tlmrdb (runtime server database).

db.properties


Configuring proxiesYou can define proxy settings for communications between runtime servers andthe administration server and between runtime servers and their agents.

To define a proxy for communications between a runtime server and theadministration server, complete the following steps:1. On the runtime server computer, navigate to the <INSTALL_DIR>\runtime\conf

folder.2. Open the scp.properties file in a text editor.3. Under the row that defines the adminpath property, add the following:

proxy = http://<proxy_address>:<proxy_port>/

where <proxy_address> is the full Web address of the proxy server and<proxy_port> is the port number.

4. Save the file and exit.5. Stop and restart the runtime server.

To define a proxy for communications between a runtime server and the agentsthat are assigned to it, complete the following steps before deploying agents:1. On the runtime server computer, navigate to the <INSTALL_DIR>\runtime\conf

folder.2. Open the agent_install.properties file in a text editor.3. Scroll down to find the proxy parameters, and define them as follows:

# Proxy nameparm.proxyname=<proxy_address>

where <proxy_address> is the full path of the proxy.

# Proxy portparm.proxyport=<proxy_port>

where <proxy_port> is the port number

# Proxy is enabledparm.useproxy=y

4. Save the file and exit.

Configuring proxies


Configuring proxies


Appendix C. Options file for silent installations

The recordFile.txt file, which is provided with Tivoli License Manager, is anInstallShield options file for use on Windows platforms. It defines arguments to seteach parameter that must be provided to the Tivoli License Manager installationwizard. Some parameters have default value that you can accept or change, forexample, the installation location. Other parameters do not have default values,and you must provide a value, for example, the name of the customer.

To launch the installation wizard in silent mode, launch the setup command withthe following arguments:

-options ″.\recordFile.txt″ -silent

The command runs using all the arguments that are defined in the options filerecordFile.txt. See Table 36 for descriptions of the arguments and the possiblevalues that you can set.

Table 36. Argument definitions for silent installations

Parameter

Argument Default

Description

State - W license.selection= 1

Determines whether the license agreement is to be accepted. The default value (1) accepts thelicense agreement. If you change this setting to anything else, the installation will be refused.

Install location -P installLocation= ″C:\Program Files\IBM\Tivoli License Manager″

Specifies the installation directory. You can accept the default or specify a different location. Ifthe path name you specify includes spaces, you must enclose it in double quotation marks, asshown for the default location.

Setup type - W setupType= custom

Determines the type of installation to be performed. Possible values are:

adminInstalls the administration server, its database, and the catalog manager.

runtimeInstalls the runtime server and its database.

customEnables you to choose the components that are to be installed.

If you select custom, you must define a ″feature active″ argument for each component you wantto install. If you select admin or runtime, any ″feature active″ arguments contained in the fileare ignored. The components to be installed are defined by the admin or runtime setup type.

Administrationserver featureactive

-P admin.active= true

Specifies whether or not the administration server component should be installed. Possiblevalues are:

true The server will be installed.

false The server will not be installed.


Table 36. Argument definitions for silent installations (continued)

Parameter

Argument Default

Description

Administrationdatabase featureactive

-P adminDB.active= true

Specifies whether or not the administration server database should be installed. Possible valuesare:

true The database will be installed.

false The database will not be installed.

Runtime serverfeature active

-P runtime.active= true

Specifies whether or not the runtime server component should be installed. Possible values are:

true The server will be installed.

false The server will not be installed.

Runtime databasefeature active

-P runtimeDB.active= true

Specifies whether or not the runtime server database component should be installed. Possiblevalues are:

true The database will be installed.

false The database will not be installed.

Catalog managerfeature active

-P catalog_manager.active= true

Specifies whether or not the catalog manager component should be installed. Possible valuesare:

true The catalog manager will be installed.

false The catalog manager will not be installed.

DB2 instanceowner

-W db2Instance.dir= ″/home/db2inst1″

Specifies the location of the DB2 instance owner on AIX platforms. You can accept the default orspecify a different location. If the path name you specify includes spaces, you must enclose it indouble quotation marks.

tlmsrv userpassword

-W DBConfigl= None

Specifies the password to be used to access the DB2 database that is associated with the servercomponent your are installing. During installation the user tlmsrv is created and its password isset to this value.

Customer name -W runtimeConfig.customerName= None

Specifies the name of the customer with which runtime server and database components are tobe associated.

Runtime name -W runtimeConfig.runtimeName= None

Specifies the name of the runtime server you are installing.

Runtimepassword

-W runtimeConfig.runtimePassword= None

Specifies the password to be used to authenticate this runtime server in communications withthe administration server. The password has a maximum length of 8 characters and can containonly the following characters:

A-Z, a-z, 0-9, +, -, =

Administrationhost name

-W runtimeToAdmin.adminHost= None

Specifies the host name of the administration server computer for this runtime server. This valuemust contain only US ASCII characters.

Silent installation


Table 36. Argument definitions for silent installations (continued)

Parameter

Argument Default

Description

Port -W runtimeToAdmin.port= ″80″

Specifies the port to be used for communications between the runtime server and theadministration server.

Use SSL -W runtimeToAdmin.IsSslEnabled= ″-1″

Indicates whether or not secure sockets layer (SSL) communications is to used between theadministration server and runtime server. Possible values are:

0 Use SSL.

-1 Do not use SSL.

Protocol -W runtimeToAdmin.protocol= ″http″

Specifies the protocol to be used for communications between the runtime server and theadministration server. Possible values are:

http For non-secure communications

https For secure communications

SSL password -W runtimeToAdmin.sslPassword= None

Specifies the password to be used to authenticate secure communications between this runtimeserver and the administration server. The password has a maximum length of 8 characters andcan contain only the following characters:

A-Z, a-z, 0-9, +, -, =

Silent installation

Appendix C. Options file for silent installations 119

Silent installation


Appendix D. Common tasks

This appendix provides instructions for performing some common tasks that youwill need to perform when installing and using Tivoli License Manager, but whichare not part of Tivoli License Manager. These include tasks related to WebSphereApplication Server, the HTTP server, and DB2.

Instructions are provided for the following tasks:v Initializing the DB2 command linev Starting and stopping the HTTP serverv Starting and stopping the WebSphere Application Serverv Starting the WebSphere Administrator’s Console

Initializing the DB2 command lineTo initialize the DB2 command line, do the following:

On WindowsClick Start > Programs > IBM DB2 > Command Window.

This opens the DB2 command window.

On AIXType:

. /home/db2inst1/sqllib/db2profile

Starting and stopping the HTTP serverTo start the HTTP server, do the following:

On WindowsClick Start > Programs > IBM HTTP Server > Start HTTP Server.

On AIX

1. Change to the directory: /usr/HTTPServer/bin2. Type:

./apachectl start

To stop the HTTP server, do the following:

On WindowsClick Start > Programs > IBM HTTP Server > Stop HTTP Server.

On AIX

1. Change to the directory: /usr/HTTPServer/bin2. Type:

./apachectl stop


Starting and stopping the WebSphere Application ServerTo start the WebSphere Application Server, do the following:

On WindowsClick Start > Programs > IBM WebSphere > Application Server > StartAdmin Server.

On AIX

1. Change to the directory: /usr/WebSphere/AppServer/bin2. Type:

./startupServer.sh &

You can check that the server has started by viewing the trace log, usingthe command:tail ../logs/tracefile

and looking for the entry:Administration server open for e-business.

To stop the WebSphere Application Server on either Windows or AIX, do thefollowing:1. Start the WebSphere Administrator’s Console.2. In the administrative domain tree, select the node with the name of the

computer.3. Right-click stop, and then confirm the requested action.

Starting the WebSphere Administrator’s ConsoleTo start the WebSphere Administrator’s Console, do the following:

On WindowsClick Start > Programs > IBM WebSphere > Application Server >Administrator’s Console

On AIX

1. Change to the directory: /usr/WebSphere/AppServer/bin2. Enter the command:

./adminclient.sh

WebSphere Application Server


Appendix E. Connecting to an X display server

When the administration server component is installed on an AIX platform,display of graphical components, for example charts, depends on access to an Xdisplay server.

To check whether there is an X display server running on the computer, type:

ps -ef |grep X

If an X display server is running, output similar to the following appears:root 3394 2172 = Mar 20 - 5:09 /usr/lpp/X11/bin/X -x abx-x dbe -x GLX -D /usr/lib/X11/rgb -T -force :0 - auth/var/dt/A:= -lfchMa

Check that the following conditions are true:v The $DISPLAY environment variable, in the environment where you are running

Java, identifies the path to the X display server.v There are no security settings that will prevent the opening of a connection

between the Web administration server computer and the X display servercomputer.

The method of connecting to the X display server depends on where the server isinstalled. The X display server may be installed on the same computer as theadministration server and WebSphere Application Server, or it may be on adifferent computer, where the WebSphere Application Server is running.

Connecting on the same computerIf the X display server is on the same computer as the administration server andWebSphere Application Server, and you start the administration server locally, nofurther action is required.

If you started the administration server from a remote session, complete thefollowing steps:1. If WebSphere Application Server is running, stop it.2. Set the DISPLAY variable for your remote session, as follows:

export DISPLAY=<AdminServerHostName>:0.0

3. Add the host name of the workstation where you launched the remote sessionto the list of computers from which the X display server accepts connections, asfollows:xhost +<RemoteSessionHostName>

4. Start WebSphere Application Server.

Connecting between computersTo establish access to the X display server when it is installed on a different hostfrom the administration server, complete the following steps:1. If WebSphere Application Server is running, stop it.


2. Add the host name of the workstation where the administration server andWebSphere are installed to the list of computers from which the X displayserver accepts connections, as follows:xhost +<AdminServerHostName>

3. Set the DISPLAY variable on the computer where the X display server isinstalled, as follows:export DISPLAY=<XDisplayServerHostName>:0.0

4. Start WebSphere Application Server.

X display server


Notices

This information was developed for products and services offered in the U.S.A.IBM may not offer the products, services, or features discussed in this document inother countries. Consult your local IBM representative for information on theproducts and services currently available in your area. Any reference to an IBMproduct, program, or service is not intended to state or imply that only that IBMproduct, program, or service may be used. Any functionally equivalent product,program, or service that does not infringe any IBM intellectual property right maybe used instead. However, it is the user’s responsibility to evaluate and verify theoperation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matterdescribed in this document. The furnishing of this document does not give youany license to these patents.You can send license inquiries, in writing, to:

IBM Director of LicensingIBM CorporationNorth Castle DriveArmonk, NY 10504-1785 U.S.A.

For license inquiries regarding double-byte (DBCS) information, contact the IBMIntellectual Property Department in your country or send inquiries, in writing, to:

IBM World Trade Asia CorporationLicensing2-31 Roppongi 3-chome, Minato-kuTokyo 106, Japan

The following paragraph does not apply to the United Kingdom or any othercountry where such provisions are inconsistent with local law:

INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THISPUBLICATION ″AS IS″ WITHOUT WARRANTY OF ANY KIND, EITHEREXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIEDWARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESSFOR A PARTICULAR PURPOSE.

Some states do not allow disclaimer of express or implied warranties in certaintransactions, therefore, this statement might not apply to you.

This information could include technical inaccuracies or typographical errors.Changes are periodically made to the information herein; these changes will beincorporated in new editions of the publication. IBM may make improvementsand/or changes in the product(s) and/or the program(s) described in thispublication at any time without notice.

Any references in this information to non-IBM Web sites are provided forconvenience only and do not in any manner serve as an endorsement of those Websites. The materials at those Web sites are not part of the materials for this IBMproduct and use of those Web sites is at your own risk.


IBM may use or distribute any of the information you supply in any way itbelieves appropriate without incurring any obligation to you.

Licensees of this program who wish to have information about it for the purposeof enabling: (i) the exchange of information between independently createdprograms and other programs (including this one) and (ii) the mutual use of theinformation which has been exchanged, should contact:

IBM Corporation2Z4A/10111400 Burnet RoadAustin, TX 78758 U.S.A.

Such information may be available, subject to appropriate terms and conditions,including in some cases, payment of a fee.

The licensed program described in this document and all licensed materialavailable for it are provided by IBM under terms of the IBM Customer Agreement,IBM International Program License Agreement or any equivalent agreementbetween us.

Any performance data contained herein was determined in a controlledenvironment. Therefore, the results obtained in other operating environments mayvary significantly. Some measurements may have been made on development-levelsystems and there is no guarantee that these measurements will be the same ongenerally available systems. Furthermore, some measurement may have beenestimated through extrapolation. Actual results may vary. Users of this documentshould verify the applicable data for their specific environment.

Information concerning non-IBM products was obtained from the suppliers ofthose products, their published announcements or other publicly available sources.IBM has not tested those products and cannot confirm the accuracy ofperformance, compatibility or any other claims related to non-IBM products.Questions on the capabilities of non-IBM products should be addressed to thesuppliers of those products.

This information contains examples of data and reports used in daily businessoperations. To illustrate them as completely as possible, the examples include thenames of individuals, companies, brands, and products. All of these names arefictitious and any similarity to the names and addresses used by an actual businessenterprise is entirely coincidental.

TrademarksThe following terms are trademarks of the IBM Corporation in the United States orother countries or both:

AIXDB2DB2 Universal DatabaseIBMThe IBM logoNetfinityRS/6000


TivoliTivoli EnterpriseWebSphere

UNIX is a registered trademark of The Open Group in the United States and othercountries.

Microsoft, Windows, Windows NT, and the Windows logo are registeredtrademarks, of Microsoft Corporation in the U.S. and other countries.

Pentium is a trademark of Intel Corporation in the US and other countries.

Java and all Java-based trademarks and logos are trademarks or registeredtrademarks of Sun Microsystems, Inc. in the U.S., and other countries.

Other company, product, and service names may be trademarks or service marksof others.

Notices 127

Glossary

Aaccount. See administration account.

administrator. A person who performs the followingtasks for a set of assigned customers.

v Manages the license management environmentincluding registration of runtime servers, divisions,and agents

v Manages license entitlement and license pooldefinitions

v Produces reports

v Receives and reacts to notifications of events

administration server. A component that performs thefollowing tasks:

v Maintains a database of product, license, customer,application user, and infrastructure information

v Provides a Web interface where administrators candefine and update the infrastructure and license rulesfor their customers and produce historical reports

administration server database. A DB2 databaseassociated with the administration server. This databasestores the information about customers, monitoringinfrastructure, and license entitlement that are definedon the administration server as well as the historicinventory and software usage information that is usedin the historical reports available on the administrationserver Web interface.

administration account. The record of anadministrator that is stored in the database.Administration account details include the logoninformation, e-mail address, level of access, and thecustomers that are assigned to the administrator.

agent. A component that is deployed from a runtimeserver to a customer node that is to be monitored. Anagent performs the following functions on themonitored node:

v Performs regular inventory scans and forwards theresults to the runtime server

v Identifies the starting or stopping of monitoredapplications and communicates to the runtime serverso that a license can be assigned or released

application user. A user who can start applications onmonitored nodes. Details of application users aremaintained to allow license pools to be restricted tospecified users.

Ccapacity type. The property of a license pool thatspecifies how to determine the number of requiredlicenses for an application. Depending on the capacitytype selected for the pool, the number of licensesrequired can be based on the number of usersrequesting a license or can depend on the size of thememory, number of processors, or number of harddisks on the node where the application is started.

customer. An organization whose license managementis controlled by Tivoli License Manager. Each customeris the owner of a set of the Tivoli License Managercomponents, including runtime servers, divisions,agents, and application users.

Ddivision. An administrative unit of Tivoli LicenseManager. Divisions are used to group agents so thatthey can be selected as a group, for example whenscheduling inventory scans or specifying targetdistribution rules.

Eevent. An occurrence that causes a notification to begenerated. Events can relate to license management, forexample a usage threshold is reached, or to thefunctioning of Tivoli License Manager, for example, anagent is not responding.

Hhard stop. A property of a license pool that specifieswhether the number of licenses available in the pool isan absolute maximum. If the property is set to Yes, it isan absolute maximum, which means that when alllicenses are in use, no further instances of theapplication can be opened. If the property is set to No,it means that the number of licenses available can beexceeded.

high-water mark. The maximum concurrent licenseusage for a product since the high-water mark was lastreset. Depending on the context, this can refer to usagewithin a specific license pool or to usage for all licensepools of the same capacity type.


Iinventory scan. An operation performed by agents todiscover all the software applications installed onmonitored nodes. Inventory scans can be scheduled torepeat at regular, defined intervals.

Llicense pool. A set of licenses for a specific productthat are administered as a group with a set of rulesgoverning thresholds, hard stops, license allocation tomultiple sessions of the same product, and theavailability of the product to users and nodes.

Mmaster catalog. The central repository of productinformation about all software components and relatedfiles for products that can be monitored.

metering. A process by which software usage ismeasured and recorded.

multi-instance. A property of a license pool thatdetermines whether multiple sessions of an applicationcan be opened using a single license. Multi-instancelicenses can apply to multiple sessions for the sameuser, for users in the same user group, or for sessionson the same node.

Nnode. A workstation in the network that can bemonitored by Tivoli License Manager when an agent isdeployed on it.

notification. An e-mail sent to a designatedadministrator in response to a license management orinternal event.

metering. A process by which software usage ismeasured and recorded. The data recorded (forexample, number of sessions, number of concurrentsessions, duration of sessions, capacity used, node ID,user ID) may be used by licensees to assess licenserequirements, or by software vendors to verifycompliance or to make billing calculations.

Pproduct entitlement settings. A definition thatdetermines whether or not the usage of a productshould be monitored and the level of licenseenforcement that should be applied.

Rruntime catalog. A subset of the master catalogcreated on each runtime server. Entries are added tothe runtime catalog either when user-definedentitlement settings for applications are downloadedfrom the administration server or when applications aredetected on the nodes monitored by agents that belongto the runtime server.

runtime server. A component that performs thefollowing functions:

v Assigns and releases licenses according to the rulesdefined in the license pools when it receives arequest from the agent

v Compiles inventory information about monitorednodes that it receives from its agents and forwardsthe information to the administration server

v Generates and sends notifications in response toevents that occur on the server itself or any of itsagents

v Provides Web interfaces for the deployment of agentsand the production of real-time reports

Ssoftware entitlement. Rules that define how asoftware product is monitored, the conditions underwhich licenses are allocated, and any restrictions placedon the availability of license pools to application usersand monitored nodes.

Ttarget. Any part of a license managementinfrastructure that can have exclusive use of a licensepool. A target can be a division, a node, or an agent,depending on how the target distribution rules for thelicense pool are defined.

target distribution parameters. Rules associated witha license pool that limit the availability of the licensepool to selected targets. The targets can be divisions,nodes, or agents depending on the target type propertyof the license pool.

target type. The property of a license pool thatspecifies where the license pool is available in thecustomer’s environment. The target type for a licensepool is set to one of the following values:v Enterprisev Divisionv Nodev Agent

An enterprise license pool is available throughout thecustomer organization. For division, node, and agentlicense pools, the administrator defines the target

inventory scan • target type


distribution parameters to determine the availability ofthe license pool in those locations.

threshold. A percentage of the licenses available in alicense pool; if more than this percentage of licenses fora product is in use, notifications about the level of useare generated.

topology. The structure in which a customer’s runtimeservers, divisions, and agents are organized.

Uunknown file list. A list, compiled by the agent, thatidentifies any applications detected on the monitorednode that are not included in the copy of the runtimecatalog that has been downloaded to the agent.

unknown file table. A file that is maintained on eachruntime server. It is a compilation of the applications inthe unknown file lists of all agents for that runtimeserver and identifies applications that are not in thecurrent runtime catalog. If the applications in theunknown file table correspond to entries in the mastercatalog, the entries are added to the runtime catalog.

user. See application user.

user distribution parameters. Rules associated with alicense pool that limit the availability of the licensepool to selected application users. The default setting isto allow all users of applications to access the licensepool.

threshold • user distribution parameters

Glossary 131

Index

Special characters/etc/services file 27$DISPLAY environment variable 123$tmp environment variable 73%LANG% environment variable 48%TEMP% environment variable 73%WINDIR% environment variable 89

Aaccessibility xiiiadminDownloadPeriod property 110administration server

commands 42configuration files 107event notifications 55in Tivoli License Manager structure 2installing 17prerequisites 12runtime connection lost 82starting 29, 44, 74stopping 44summary of functionality 1system.properties file settings 109uninstalling 31web interface 7

administration server databasecreating on AIX 25creating on Windows 25dropping on AIX 32dropping on Windows 32prerequisites 12

Administratorrequired for installation on Windows 18

administratorsas notification recipients 28, 55

adminUploadPeriod property 110adminWakeUpEnabled property 109adminWakeUpPeriod property 109agent 47

access to runtime servers 3, 112applet certificate problems 87, 88authorization problems for deployment 86commands 52communication problems 92configuration file problems 92connection problems for deployment 86deployment 48

messages 85troubleshooting 85

deployment process hangs 85, 86disk space for deployment 86does not start 90does not stop 90error codes during operation 91error codes on install 88file errors during deployment 87files 50in Tivoli License Manager structure 2inactive 110, 111

agent (continued)install failure return codes 88installagent applet not found 85internal errors during deployment 87inventory scan problems 92, 93language selection 48not in server agent report 90number to assign to a runtime server 8on Sun 51on Windows 52operation

messages 89troubleshooting 89

patching files 50platforms supported 11prerequisites 13self-update 50, 112status not returned 88summary of functionality 1, 47system.properties file settings 47, 111trace operation 78tracing deployment 78uninstalling on UNIX 33uninstalling on Windows 33unsupported operating system 87

agent_install.properties fileagent deployment debug information 78defining a proxy 115purpose 107

AIXagent commands 53agent files 51agent language selection 48connecting a database to a server 27creating DB2 database 25disconnecting adatabase from a server 32initializing the DB2 command line 121installation 21installation log file 73root user required for installation 18setup file 17starting the HTTP server 121starting the WebSphere Administrator’s Console 122starting WebSphere Application Server 122stopping the HTTP server 121stopping the WebSphere Administrator’s Console 122stopping WebSpherre Application Server 122

aliases, default port 39aliases, SSL port 38allpubs.htm file xii

Bbooks

accessing online xiionline xiiiordering xiii

browserconnection problems 93prerequisites 13problems displaying reports 93, 94


browser (continued)problems with windows 93

CcacheUpdatePeriod property 110capacity type

in default license pools 110catalog

exporting master 43importing master 43upgrading master 15

catalog managerinstalling 17platforms supported 11prerequisites 12troubleshooting 96uninstalling 31unknown file table problems 96upgrade considerations 15

catalog.dat file 43categories of messages 97certificate authority 37checkPeriod property 112clean up SERVICE table 71, 109, 110clean up USAGE table 71, 109cleanServiceEnabled property 72, 109cleanServicePeriod property 72, 110cleanUsageEnabled property 71, 109cleanUsagePeriod property 71, 109CLI (command line interface) 41

checking 75for DB2 121on agents 52starting on AIX 41starting on Windows 41

code pagecommand line output on Windows 41

command line interface (CLI) 41checking 75for DB2 121on agents 52starting on AIX 41starting on Windows 41

commandsdbpasswd 42expcat 43help 43impcat 43info 43installagent 48on agents 52on AIX agents 53on all agent platforms 52on runtime servers 42on Sun agents 53on the administration server 42on Windows agents 53rtpasswd 43, 44srvstart 44srvstop 44statusinfo 44, 77tlmagent 52

configuration 11db.properties file 113files 107proxies 115

configuration (continued)settings 107system.properties file 108WebSphere Application Server 83

connection pooling 13, 114conventions

directory paths xvtypeface xiv

CPU prerequisites 12csvPlugins.properties file 107customer

in Tivoli License Manager Structure 4switching a machine between 90

customer support xiii

Ddatabase

checking the connection 73connecting to a server on AIX 27connecting to a server on Windows 26connections 114creating on AIX 25creating on Windows 25disconnecting from a server on AIX 32disconnecting from a server on Windows 32dropping on AIX 32dropping on Windows 32name 114server 12size, performance impact 79technical error 84timeout 114troubleshooting 84

db.properties file 13, 113DB2

Client Configuration Assistant 26, 32command line 121connection pooling 13, 114connections 114driver 114user 114

DB2 databasechecking the connection 73connecting to a server on AIX 27connecting to a server on Windows 26creating on AIX 25creating on Windows 25disconnecting from a server on AIX 32disconnecting from a server on Windows 32dropping on AIX 32dropping on Windows 32name 43, 114password 21, 42, 118planning 7prerequisites 12

DB2 driverschecking on WebSphere Application Server 74

DBCS pathnamesWebSphere Application Server 83

dbJNDIName property 114dbName property 114dbpasswd command 42dbPoolerImplementation property 13, 114dbsetup.bat script 14, 25dbsetup.sh script 14, 26dbUser property 114


default license pool 110defaultCapacityType property 110defaultMultiInstance property 110deployment

agent 48tracing 78

directory names, notation xvdisconnecting a database

AIX 32Windows 32

disk spaceperformance impact 79

DISPLAY environment variable 123division

in Tivoli License Manager structure 3document type definitions (DTDs)

for exporting reports 59double-byte character set languages 82downloadCatalogPeriod property 112downloadParametersPeriod property 112driver

DB2 114dropping databases 32DTDs (document type definitions)

for exporting reports 59

Ee-mail notifications 55entitlement

defining check period for updates 109environment variable

$DISPLAY 123$tmp 73%LANG% 48%TEMP% 73%WINDIR% 89

error.log file 76event notifications 55

failure 96recipients 28, 55server settings 28, 55system.properties file settings 113

event.log file 57events

inactive agent 55inventory scan 55license usage 55on the administration server 55on the runtime server 55

expcat command 43export

master catalog 43reports 59

Ffile

/etc/services 27agent_install.properties 78, 107, 115allpubs.htm xiicatalog.bat 43csvPlugins.properties 107db.properties 113error.log 76event.log 57

file (continued)help.properties 107httpd.conf 36ITLM_install.log 73locale.properties 107password.properties 107recordFile.txt 117scp.properties 35, 108, 115scp.services.properties 108setupaix.exe 17setupwin32.exe 17slmInit.properties 108stylesheets.properties 108system.properties 28, 56, 97, 108time.log 76tlmia.trc 78trace.log 76traceagt.log 78traceFilters.properties 76, 108

fontcommand line output on Windows 41

GgetConnectionTimeout property 114

Hheap sizes

Java 79help

for the command line interface 43help command 43help.properties file 107high-water mark

scan period 109host name aliases

checking on WebSphere Application Server 75HTTP

changing port 80configuration, performance impact 79, 80port in use 80

HTTP serverchecking availability 73configuring for SSL 36starting 121stopping 121

httpd.conf file 36HTTPS 35hwmScanPeriod property 109

IIBM Software Support xiiiIKEYMAN

with HTTP Server 37with WebSphere Application Server 37

impcat command 43import

master catalog 43inactive agent 110, 111info command 43installagent

applet not found 85command 48return codes 88

Index 135

installation 11agent 48catalog manager 17log 73silent 17, 117Tivoli License Manager servers 17validating 73

installation pathobtaining 43specifying 18

InstallShield options file 117interface

connection problems 93problems displaying reports 93, 94problems with windows 93

Internet Explorer 13inventory reports

exporting 59XML format 66

inventory scanduration 9, 111event 55resending 112

InventoryAgentReport.dtd 67inventoryFilesPerPacket property 111InventoryProductReport.dtd 66inventoryResendTimes property 112inventoryUpdatePeriod property 110ITLM_install.log 73

JJava console 78Java Database Connection (JDBC) drivers 13Java heap sizes 79Java Secure Sockets Extension (JSSE) 37Java virtual machine 87JDBC (Java Database Connection) drivers 13jdbcDb2UrlPrefix property 114jdbcDriver property 114JSSE (Java Secure Sockets Extension) 37

Kkey.jks trusted store 37key.kdb database 37

LLANG environment variable 48language selection

agent 48servers 18

level analysis reportXML format 65

licenserelease 110, 112

license poolsdefault 110defining check period for updates 109maximum reached 55threshold reached 55

license usagedefining check period 109

licenseCleanUpPeriod property 110locale.properties file 107

log files 75installation 73

Lucide Console font 41

Mmail settings

in system.properties file 28, 56mailEngine property 113mailRecipient property 113mailReload property 113mailSender property 113manuals

accessing online xiionline xiiiordering xiii

master catalogexporting 43importing 43upgrading 15

maxAgentInactivity property 111maxDbConnections property 114maxServiceAge property 72, 110maxUsageAge property 71, 109memory prerequisites 12messages

agent deployment 85agent operation 89categories 97descriptions 98on the Web interfaces 97

Microsoft Internet Explorer 13multi-instance

default 110in default license pools 110

Nnational language selection

agent 48servers 18

Netscape Navigator 13network traffic

performance impact 78notation

path names xvtypeface xiv

notificatione-mail 55events 55recipients 28, 55server settings 28, 55system.properties file settings 113

Oonline publications

accessing xiioptions file for silent installation 117ordering publications xiii

PpacketDelayEscalation property 112packetDelayThreshold property 112


parm.trace property 78password

for DB2 database 21, 42, 118for DB2 user 42key.kdb database 37runtime server 22, 43secure sockets layer (SSL) 44SSL 23, 37tlmsrv 21, 118

password.properties file 107patch 1.1-TLM-0001 15patching agent files 50path names, notation xvpath, installation

obtaining 43specifying 18

pcInventoryDuration property 9, 111performance

factors 78pingPeriod property 112planning 1platforms supported 11plug in

runtime server 110plug in failure

runtime server 81, 82port aliases

restoring default 39SSL 38

prerequisitesbrowser 13CPU 12database server 12for administration server 12for agent 13for catalog manager 12for DB2 databases 12memory 12space 12, 13

problem determination 73problems

agent deployment 85agent operation 89catalog manager 96databases 84displaying reports page 94reports 94server installation 80servers 80user interface 93WebSphere Application Server 83WebSphere Application Server servers 83

processor prerequisites 12property

adminDownloadPeriod 110adminUploadPeriod 110adminWakeUpEnabled 109adminWakeUpPeriod 109cacheUpdatePeriod 110checkPeriod 112cleanServiceEnabled 72, 109cleanServicePeriod 72, 110cleanUsageEnabled 71, 109cleanUsagePeriod 71, 109dbJNDIName 114dbName 114dbPoolerImplementation 114

property (continued)dbUser 114defaultCapacityType 110defaultMultiInstance 110downloadCatalogPeriod 112downloadParametersPeriod 112getConnectionTimeout 114hwmScanPeriod 109inventoryFilesPerPacket 111inventoryResendTimes 112inventoryUpdatePeriod 110jdbcDb2UrlPrefix 114jdbcDriver 114licenseCleanUpPeriod 110mailEngine 113mailRecipient 113mailReload 113maxAgentInactivity 111maxDbConnections 114maxServiceAge 72, 110maxUsageAge 71, 109packetDelayEscalation 112packetDelayThreshold 112parm.trace 78pcInventoryDuration 9, 111pingPeriod 112requestScope 3, 112runtimePluginPeriod 110serverInventoryDuration 9, 111smtpServer 113trace_level 78updateAgentEnabled 50, 112updateAgentPeriod 112uploadMinTime 112uploadUsageEvents 111usageSnapshotPeriod 111

proxiesconfiguring 115

publicationsaccessing online xiionline xiiiordering xiii

Rrecipients

of event notifications 28, 55recordFile.txt file 117release license 110, 112reports

exportingsoftware inventory report 66software inventory reports 59software usage reports 59software usage trend analysis reports 63

fewer sessions than expected 95historical data missing 84products missing from 94troubleshooting 94

reports, exportingsoftware inventory 66software usage level analysis 65software usage snapshot 59software usage trend analysis 63

requestScope property 3, 112return codes

agent install process 88

Index 137

return codes (continued)installagent command 88

root userrequired for installation on AIX 18

RS/6000 12rtpasswd command 43, 44runtime catalog

adding unknown files to 110download to agent 112

runtime serverchanging password 43changing SSL password 44commands 42configuration files 107connection to administration server 82event notifications 55in Tivoli License Manager structure 2installing 17no longer plugged in 82number of agents 8plug in 110plug in failure 81prerequisites 12setting password 22starting 29, 44, 74stopping 44summary of functionality 1system.properties file settings 110uninstalling 31

runtime server databasecreating on AIX 25creating on Windows 25dropping on AIX 32dropping on Windows 32prerequisites 12

runtimePluginPeriod property 110

Sscan, inventory

duration 9, 111scp.properties file 108, 115

configuring for secure communications 35scp.services.properties file 108script

dbsetup.bat 14, 25dbsetup.sh 14, 26SetupAdmin.bat 83SetupAdmin.sh 83SetupRuntime.bat 83SetupRuntime.sh 83WASConfig.bat 83WASConfig.sh 83

secure communicationsdisabling 39enabling 35

secure sockets layer (SSL) 35certificate authority 37password

changing 44specifying 23

WebSphere Application Server aliases 38self-signed certificate

creating 37exporting 37requesting 37

self-updating agent 50, 112

server certificatecreating 37exporting 37requesting 37

serverInventoryDuration property 9, 111servers

installation problems 80platforms supported 11starting 29, 44stopping 44troubleshooting 80

SERVICE tablecleanup 71, 109, 110

SetupAdmin.bat script 83SetupAdmin.sh script 83setupaix.bin 80setupaix.exe 17SetupRuntime.bat script 83SetupRuntime.sh script 83setupwin32.exe 17silent installation 17, 117slmInit.properties file 108smtpServer property 113software inventory reports

DTD 66exporting 59

software support xiii, 44software usage information 111software usage level analysis

DTD 65software usage reports

exporting 59software usage snapshot

DTD 59software usage trend analysis

DTD 63problems displaying 93

space prerequisites 12, 13srvstart command 44

failure 83srvstop command 44SSL (secure sockets layer) 35

certificate authority 37password

changing 44specifying 23

WebSphere Application Server aliases 38starting servers 29statusinfo command 44, 77structure of Tivoli License Manager 2stylesheets.properties file 108Sun agent

browser restriction 13commands 53files 51

support, software xiiisupported platforms 11swu_trend.dtd 63SWUsage.dtd 59SWUsageLevelAnalysisReport.dtd 65system processes

performance impact 79system.properties file 108

administration server settings 109agent settings 47, 111e-mail settings 113mail settings 28, 56


system.properties file (continued)runtime server settings 110setting message display property 97Web interface settings 109

TTEMP environment variable 73time.log file 76timeout

database connection 114Tivoli License Manager structure 2Tivoli Software Information Center xiitlmagent command 52tlmia.trc file 49, 78tlmroot user 30tlmsrv password 21, 118tmp environment variable 73trace

agent deployment 78agent operation 78on servers 76

trace level 76setting for servers 76

trace services 75trace_level property 78trace.log file 76traceagt.log file 78traceFilters.properties file 76, 108trend analysis

XML format 63troubleshooting

agent deployment 85agent operation 89catalog manager 96common problems 80databases 84reports 94server installation 80servers 80summary 73user interface 93WebSphere Application Server 83

trusted store, key.jks 37typeface conventions xiv

Uuninstalling

agent on UNIX node 33agent on Windows node 33catalog manager 31Tivoli License Manager servers 31

UNIXagent language selection 48

unknown filesadding to runtime catalog 110sending to runtime server 112

updateAgentEnabled property 50, 112updateAgentPeriod property 112updateUsageEvents property 111upgrading

master catalog 15version 1.1 to version 1.1.1 14WebSphere Application Server to version 4.0.4 16

uploadMinTime property 112

usage information 111USAGE table

cleanup 71, 109usageSnapshotPeriod property 111user

Administrator 18DB2 114root 18tlmroot 30

user interface 4troubleshooting 93

UTF-8 encodinginstallagent parameters 50unknown file table 96UTF-8 encoding 96

Vversion 1.1, upgrading from 14version of Tivoli License Manager

obtaining 43virtual host definition 36

WWASConfig.bat script 83WASConfig.sh script 83Web administration server

event notifications 55in Tivoli License Manager structure 2installing 17prerequisites 12starting 29, 74summary of functionality 1uninstalling 31

Web interface 4administration server 4runtime server 4system.properties file settings 109troubleshooting 93

Web runtime serverevent notifications 55in Tivoli License Manager structure 2installing 17starting 29, 74summary of functionality 1uninstalling 31

WebSphere Administrator’s Consolestarting 122stopping 122

WebSphere Application Serveraliases for SSL 38checking aliases 75checking for DB2 drivers 74configuration scripts 83configuring for Tivoli License Manager 17, 24connection pooling 114DCBS pathnames 83default aliases 39removing configurations for Tivoli License Manager 31starting 122starting a server on 29, 74stopping 122Tivoli License Manager server not listed 83troubleshooting 83upgrading to version 4.0.4 16

Index 139

WINDIR environment variable 89Windows

Administrator required for installation 18agent commands 53agent files 52agent language selection 48connecting a database to a server 26creating DB2 database 25disconnecting a database from a server 32font and code page 41initializing the DB2 command line 121installation log file 73setup file 17starting the HTTP server 121starting the WebSphere Administrator’s Console 122starting WebSphere Application Server 122stopping the HTTP server 121stopping the WebSphere Administrator’s Console 122stopping WebSpherre Application Server 122

XX display server

connecting to 123requirement for 13

XML elementsin inventory report 67in software usage snapshot report 60in the trend analysis report 63

XML formatsoftware inventory report 66software usage level analysis 65software usage snapshot 59software usage trend analysis 63


��

Program Number: 5724-D33

GC23-4834-01

ibm tivoli license managerpublib.boulder.ibm.com/tividd/td/itlm/gc23-4834-01/e… · ·...

Documents