How to Optimize Novell Licensing Services

Articles and Tips: article

Boyd Memmott
Engineer
World Wide Support
bmemmott@novell.com

Bryan Nahrwold
Test Engineer
Core Operating System
bnahrwold@novell.com

Jack Tobiasson
Technical Writer
Product Documentation
jtobiass@novell.com

01 Jan 2001

The article is for those who must implement and maintain Novell Licensing Services (NLS) in a NetWare environment.

Novell Licensing Services
How NLS Works
Troubleshooting Tools
Troubleshooting Procedures
Conclusion
Additional References
Appendix 1: Glossary of Terms
Appendix 2: A Detailed Look at an NLS Trace Log File
Appendix 3: Analysis of a PMTRACE.DBG Log File
Appendix 4: NLS Return Codes
Appendix 5: POLIMGR.NLM Connection States
Appendix 6: A Description of PM STATS
Appendix 7: Usage of Threads in NLS

Novell Licensing Services

This section defines and provides a brief history of Novell Licensing Services (NLS).

What is NLS?

NLS is software that helps you monitor the use of licensed applications on a network. NLS is most widely known for its inclusion in the NetWare 5.x and Novell Small Business Suite operating systems.

Reference sections at the end of this article provide links to documents pertinent to troubleshooting NLS.

History of NLS

This section discusses the roots of NLS, the importance of version control, and baseline updates.

Roots of Product

NLS was first implemented in the 4.x version of NetWare for Small Business. It has since been used in a variety of products including NetWare 5.0, NetWare 5.1, NetWare 5 for Small Business, BorderManager, ZENWorks and NetWare Cluster Services. NetWare 4.x can provide NLS for other applications, but user license consumption in NetWare 4.x does not take advantage of NLS.

Note: Novell does not support NLS on NetWare 4.10 servers.

Importance of Version Control

When customers call Novell Technical Support for assistance with any Novell product, support technicians ask, "Have you loaded the latest support pack?" Support packs are updates that contain fixes and enhancements. As essential performance and reliability enhancements continue to be made throughout the life of the product, many of the product"s enhancements are provided via these updates. Particularly important to NLS, support packs are the basis of Novell"s current "baseline" from which support recommendations are predicated.One of the most prevalent support topics concerning NLS in a NetWare environment is about multiple servers running different versions of NetWare. Problems related to licensing are often viewed as compatibility issues between operating systems, such as NetWare 4.x, NetWare 5.0 and NetWare 5.1. Actually, the concern is with the version of NLS provided with each operating system.

By default, NetWare 5.0 ships with NLS version 4.0. However, NetWare 5.1 ships with NLS version 5.0. It is critical that all servers in the tree be upgraded to run the same version of NLS. At the time of this article, the latest NLS release is version 5.02, dated September 26, 2000. (For links to updated software, see Downloads, under the Additional References section at the end of this article.)

Also, make sure that each NetWare server has the correct NetWare Loadable Module (NLM). NetWare 4.x ships with NLS.NLM. In NetWare 5.x, this module has been replaced with NLSLSP.NLM. NLS.NLM should not be running on any server in a network that includes a NetWare 5.x server.

BaseLine Updates for NLS

As of November 14th, support packs NW5SP6A.EXE and NW51SP2A.EXE contain the baseline code levels assumed for this article. Installing the appropriate support pack on all your servers will resolve both communication and performance issues encountered in the initial implementation of NLS. You can download these support packs from the Novell Support Connection. (For more information, see Downloads under the Additional References section at the end of this article.)

Some improvements for NLS depend upon enhancements to other operating system services. These improvements are available only when the complete operating system support pack is applied.

Also, you must upgrade existing NLS 4.x objects in your tree to version 5.x objects. See the "Installing NLS in a NetWare 5.x Environment" section below for more information on performing this task.

How NLS Works

This section explains how the licensing service responds to network requests and also describes the modules involved with licensing.

High-Level View of the Licensing Process

License consumption involves a client/server process. Although some examples in this article deal with a workstation requesting a license from a NetWare 5.x server, a "client" to NLS is any process that makes requests to the licensing service for license consumption. A server may also perform the client portion of a request. Server-based requests can originate on either the same server or a remote server.

The licensing process begins when a Novell Directory Services (NDS) object initiates a request for a licensed connection that will consume a unit of a license certificate assigned to the desired application. For example, a NetWare client requests a resource such as a drive mapping.

This request differs from non-licensed authentications. For example, when an NDS connection is performing nonserver-based network NDS tree operations, NDS uses a non-licensed connection. An example of this connection is the authentication of objects to the tree. The authentication process does not consume units of a license certificate assigned to an application.

The Connecting Manager (CONNMGR.NLM) first contacts NDS, so that CONNMGR.NLM can verify the authenticity of the object. Once the CONNMGR.NLM determines that the object is valid, CONNMGR.NLM makes a request to the NetWare Policy Manager (POLIMGR.NLM) for a license unit.

Before the release of NLS, each application provided a separate strategy concerning consumption of license units. For NetWare 3.x, licensing for user connections was bound into SERVER.EXE. For NetWare 4.x certificates resided in a hidden directory on the server's SYS volume, and the license policy was determined by SERVER.EXE. This form of licensing is now referred to as legacy licensing.

When NLS was implemented for NetWare, POLIMGR.NLM was modified to take advantage of NLS and act as a license requester. The licensing service itself manages the licensing policies contained in the license certificates. This service, also referred to as the "NLS backend," is contained in NLSLSP.NLM (Novell Licensing Services - License Service Provider).

Note: Prior to the release of the latest support packs mentioned in this article, POLIMGR.NLM was a bound-in NLM. It did not appear in a list of modules.

When POLIMGR.NLM receives a request from CONNMGR.NLM, POLIMGR.NLM contacts the License Service Provider. The License Service Provider then requests license information and properties from NDS. The license information and properties are:

Publisher
Product
Version
Number of units requested (usually one)

Typically, the request for license information is issued to the server holding the master replica of the partition. If the master replica is offline or down, the request is issued to a server with a read/write replica of the partition.

The Licence Service Provider looks for an available license unit. If the License Service Provider finds one, it returns the license unit along with a success code. Otherwise, the License Service Provider returns a failure code.

If the request is successful, POLIMGR.NLM returns this information to CONNMGR.NLM and updates the server's connection table with information about the user connection.

For more information on how this process works, refer to Appendix 2: A Detailed Look at an NLS Trace Log File at http://support.novell.com/techcenter/articles/ana20010102.html.

Modules Used by Licensing

This section briefly describes the licensing NLMs loaded on a NetWare server. For more information about the purpose of these NLMs see http://www.novell.com/documentation/lg/nls502/docui/index.html.

LSAPI.NLM

Handles the base requests for licensed connections and their releases. Novell has enhanced LSP functionality with NLSAPI.NLM.

NLS.NLM

Was the original provider for the NLS service. NSLSP.NLM replaced this NLM.

NLSAPI.NLM

Provides access to NLS management functions. This program is a shared-library NLM.

NLSBTRV.NLM.

Is the NLS Btrieve interface module. NLS uses this NLM when the NLS_LSP_servername object has been configured for Btrieve.

NLSFLAIM.NLM

Tracks certain elements of licensing. This NLM writes persistent cache information to a self-repairing database.

NLSI.NLM

Is used to set up NLS.

NLSLSP.NLM

Handles requests from NLS clients and maintains the license certificates, which are stored within NDS.

NLSTRAP.NLM

Sends alerts to SNMP for notification of NLS events.

NWCONFIG.NLM

Contains options to install and delete certificates, set up licensing, and extend the schema (NDS menu).

POLIMGR.NLM

Acts as the license requester when working with licensing in a Novell server environment. This program is not part of the Novell Licensing Service but is an application which uses NLS.

NLS Objects in NDS

Coverage of NLS objects is provided in the January 1999 issue of AppNotes, "A Closer Look at Novell Licensing Services in NetWare 5" available at http://support.novell.com/techcenter/articles/ana19990104.html.

In brief, NLS uses NDS objects to store information about license certificates and license usage. You can use NetWare Administrator (NWADMN32.EXE) and ConsoleOne to view these objects. Currently, you use NetWare Administrator to manage these objects.

The three most prevalent NLS objects in NDS are License Container objects, License Certificate objects, and License Service Provider objects.

License Container Objects

These objects hold the license certificates. In current versions of NLS as implemented in the NetWare 5.x operating system, License Container objects store (in attributes of the license containers) summary trending information about license usage. For each version of NetWare, these containers are named according to the publisher, product and version, such as:

Novell+NetWare 5 Conn SCL+510
Novell+NetWare 5 Server+510

License Certificate Objects

License certificates are stored as objects in NDS. License Container objects store these objects. In NetWare Administrator, these objects are listed by serial number with the prefix "SN:".

Windows dialogs for the LSP object allow you to change the default licensing configuration. Some configuration is also possible using the SET parameters for NLS. These parameters can be accessed from MONITOR > Server Parameters > Licensing Services.

Detailed Flow of Processing

Figure 1 illustrates the flow of licensing for a NetWare 5.x client login. Other implementations of NLS use the same backend process. However, the application using NLS will differ. POLIMGR.NLM for NLS contains the application for NetWare licensing. BorderManager, ZENWorks and other program suites provide different applications to manage their connections.

Flow of a Licensed Client Connection.

A client requests a license unit.
- An NLS client requests a licensed resource from a license service. In a typical NetWare client scenario, this could be LOGINW32.EXE or the mapping of a drive from Windows Explorer.
- On the client side, an NCP handler packages the request as a NetWare Core Protocol (NCP) packet and submits it to CONNMGR.NLM on the server.
The server receives the license request.
- An NCP handler receives the NCP, unpackages it and presents it to CONNMGR.NLM.
- To determine whether the request is coming from a valid source, CONNMGR.NLM checks the User object in NDS.
If the user object is valid, CONNMGR.NLM requests authentication from POLIMGR.NLM.
POLIMGR.NLM determines the type of request. That is, this is a request for a license, not a request for a printer or a ZENWorks object, and requires consumption of a license unit.
POLIMGR.NLM checks NLS to see if a license unit is available for the requested publisher, product and version.
NLS requests the license unit from either NDS or from the server's cache.
NDS returns the license unit or a failure code.
NLS returns the license unit or a failure code to NLS. At this point, if the request for a license has been met, a license unit has been consumed.
POLIMGR.NLM informs CONNMGR.NLM that a license has been granted.
CONNMGR.NLM updates its connection table.
NLS performs this sequence a second time to obtain a public key from the certificate buffer. This second pass is required to verify that the certificate is authentic and has not been altered.

Installing NLS in a NetWare 5.x Envir

As previously mentioned, NLS is part of the installation of a number of products. This section will touch on the installation process for the NetWare 5.x operating system. For more information, see Additional References at the end of this article.

Prerequisites for NLS during Server Installation

NLS is a service that uses other network services to accomplish its function. NLS is dependent upon NDS, network communication, and operating system libraries for proper licensing operation. This section describes the reasons you should stay current with support pack updates and describes why it is important to maintain a clean network environment.

Support Packs

Support packs have not only provided fixes to known problems, but have also introduced changes that have increased the reliability, reduced the errors, and accelerated the speed of NLS. All servers should run current versions of appropriate support packs. These support packs usually include base module updates for NLS.

When additional NLS files are needed beyond the support pack, SETUPNLS.EXE, described below, can install these files as well as perform other needed functions. (See Preventative Maintenance under Troubleshooting Procedures later in this document.)

Directory Services Issues

NLS will not be able to propagate licensing changes and updates throughout the network unless NDS is properly synchronizing across the network. Detailed support for NDS issues is beyond the scope of this article. However, we recommend some basic checks to verify that NDS is synchronizing and that it is not producing errors. (See Technical Information Documents under Additional References.)

NLS and Object Versions

NLS 4.0 was released as a part of the NetWare 5.0 operating system. The current release of NLS for both NetWare 5.0 and NetWare 5.1 is NLS 5.02. Although NLS 5.02 is backward compatible with NLS 4.0, experience has shown that NLS 4.0 is not reliably forward compatible with NLS 5.02.

This incompatibility applies not only to the actual NLMs running on the server but also to the NLS objects in the tree. It is important to verify that all servers are running NLS 5.02 (dated September 26, 2000) or later and that all NLS objects in NDS have been upgraded to NLS 5.02 objects. (See Preventative Maintenance under Troubleshooting Procedures later in this document.)

Server Installation Procedures

Detailed instructions for installing NetWare can be found in the basic on-line documentation at http://www.novell.com/documentation.

NLS is installed automatically with Novell NetWare for Small Business Suite, NetWare 5.x, and NetWare Cluster Services.

Partitioning Rules

As servers are installed into the tree, they must be able to find the licensing service running on a server with a master or read/write replica of the partition containing the server. In addition, the added servers have some dependencies upon the server with the master replica of the partition holding the licensing object used by servers in question.

Larger networks may have several partitions with multiple license objects. It is important to understand how this works. Consider a three-server tree with servers Master, ReadWrite, and Requester.

In this scenario, the server known as Requester was either recently installed into the tree or has been rebooted and does not contain licensing objects in its cache. To satisfy a request for a license, NLS searches its cache for licensing objects, and failing to find a certificate, interrogates NDS to determine which server is the master of the partition. NLS then makes its requests from this master replica server.

Master responds with a license unit from a certificate. After the first request, Requester caches this object information locally and does not have to obtain this again from Master. If Master is unavailable, then NLS seeks this information from ReadWrite.

NLS searches across both IP and IPX and uses the protocol on which the original request was transmitted. IP has a seven-minute timeout. IPX has a five-minute timeout. If Master is offline or unavailable, Requester checks ReadWrite after the timeout period has expired.

MLA Installation Requirements

MLA licenses may be installed into the same tree multiple times, but must only be installed once into each organization or organizational unit. Thus, when multiple servers are installed into a single organizational unit, only the first server is installed with a license.

Additional servers installed without a license can share previously installed licenses that exist in the tree within the same container or any container in the server's path to the root of the tree.

When NetWare 5.1 servers are installed into a location in the tree where MLA certificates already exist, the installation process prompts for installation without a license. The installation screens request a valid license diskette to install the Novell International Cryptographic Infrastructure (NICI) Foundation Key.

This key is not part of licensing but is normally copied when licensing is installed. Although the NetWare 5.1 installation handles the automatic installation of this key when a license is not installed, NetWare 5.0 does not automatically copy this key. Details on this issue are provided in the TID "Installing MLA License Certificates" available at http://support.novell.com/cgi-bin/search/tidfinder.cgi?10013067.

Prerequisites for NLS Installation Outside of Server Installations

NLS can be installed or reinstalled from applications outside of the default server installation process. Ways to do this are outlined below.

Using NetWare Administrator to Install Certificates

This section discusses using NetWare Administrator to install certificates.

Installation Requirements

NetWare Administrator for NetWare 5.x (and later) requires NWADMN32.EXE and will not work with the NWADMIN.EXE file contained in either SYS:PUBLIC\WIN95 or SYS:PUBLIC\WINNT. If the support packs recommended in this article are used, the version of NWADMN32.EXE listed in Help will be version 5.19f or later.

In addition, NWADMN32.EXE can only be used to install certificates, not the license service itself. Use SETUPNLS.EXE listed below to install NLS.

Installing Certificates

From within NetWare Administrator (NWADMN32.EXE), highlight the container that will receive the licenses. From the Tools Menu option, select Novell Licensing Services > Add Licenses. Follow the prompts to install certificates.

Note: For non-MLA certificates, you will be prompted to make a server assignment for both the server and connection licenses. These certificates will be unavailable until they are assigned to a server running NLS. The opposite is generally true for MLA licenses. MLA licenses are designed to be shared between multiple servers. Assigning specific servers to MLA licenses will restrict access to only the assigned server.

Using NWCONFIG to Install Certificates and NLS

This section discusses using NWCONFIG to install certificates and NLS.

Installing Certificates

From NWCONFIG.NLM, select License Options > Install Licenses. The installation process installs certificates and makes server assignments as needed.

Neither NWADMN32.EXE nor NWCONFIG.NLM will install the NICI foundation key for MLA servers that were installed without a license.

Setting Up the Licensing Service

If Novell Directory Services has been removed and reinstalled, or if problems with licensing indicate reinstallation would be beneficial, reinstall NLS. From NWCONFIG.NLM, select License Options > Create License Service Provider. NWCONFIG.NLM recreates LSP objects in the tree and extends the schema. This procedure is equivalent to executing SETUPNLS.NLM from the console prompt.

Installing NLS with SETUPNLS.EXE

SETUPNLS.EXE is a graphical utility that installs NLS on NetWare 4 and NetWare 5 servers. Designed to facilitate installation of NLS across a network, SETUPNLS.EXE does the following:

Installs or upgrades NLS files
Converts NLS 4.0 objects (if they exist) to NLS 5.02 objects

Note: When installing or upgrading to NetWare 5, the Novell Installation Services program installs NDS and creates the NLS_LSP_servername object. You must use SETUPNLS.EXE to convert the NLS 4.0 objects to NLS 5.02 objects.
Extends the NDS schema
Modifies AUTOEXEC.NCF
Optionally restarts the servers

Using SETUPNLS.EXE, you can easily and quickly install NLS into an entire NDS tree or partition or on selected servers. SETUPNLS.EXE does not install license certificates. (You can use NWCONFIG.NLM and NetWare Administrator to install them.)

Note: This functionality is also provided with Deployment Manager in NetWare 5.1. NetWare 5.1 installation CDs start Deployment Manager by default when the CD is inserted into an autoplay-ready CDROM device.

By default, SELTUPNLS.EXE upgrades all NetWare 4.11, NetWare 4.2, NetWare 5.0, and NetWare 5.1 servers in an NDS tree to the version of NLS contained in NLSLSPX.EXE (see Obtaining SETUPNLS.EXE). Using the Advanced Options tab, you can select a subset of the servers in a tree. SETUPNLS.EXE installs NLS modules, extends the schema, and creates or upgrades the LSP object for each server. Because NLS is a service, it is recommended that all servers in the tree run the most current version of NLS.

Obtaining SETUPNLS.EXE

SETUPNLS.EXE is packaged as NLSLSPx.EXE where X is the current version of the deliverable. As of the publication of this document, the current release is NLSLSP6.EXE. You can download this file from http://download.novell.com/Download?buildid=F5Rd9miV1DU~.

Configuring NLS

NLS is, as previously described, a service. This section provides an overview of configuration programs and options for the use of NLS in a NetWare 5.x server environment. The NLS version included with NetWare 5.x provides tools which:

Affect how the license service searches for certificates
Determine if a transaction database will be activated
Allow assignment of licenses to servers
Provide tools for examining the allocation of certificate units

A full examination of the features is contained in the appendix of this document at http://support.novell.com/techcenter/articles/ana20010102.html.

Console SET Parameters

This section discusses the License Service Provider object.

NLS SEARCH TYPE

The License Service Provider object, which appears in the tree as NLS_LSP_servername, allows you to configure how licenses are searched up the tree as well as initialize a transaction tracking database.

The default is to search upward to the root of the tree. The other option is to search only to the root of the partition. To alter the search method, use the SET parameter NLS SEARCH TYPE.

0 stops the search at the root of the tree.

1 stops the search at the partition root.

To reduce WAN traffic, customers with local LSP services across WAN links may wish to set the search for LSPs to stop at the root of the partition.

Store NetWare 5 Conn SCL MLA Usage in NDS

To reduce synchronization traffic in MLA environments, this parameter is (by default) set to off in NW5SP5.EXE and NW51SP1.EXE. With this parameter set to off, no usage information (for analysis) is stored in certificate containers. Right-clicking on certificate containers will show zero units consumed, no matter how many users have consumed license units.

Nevertheless, we recommend this parameter be set off to prevent utilization problems in large environments. For background information on this issue, see TID 2945295 at http://support.novell.com/cgi-bin/search/tidfinder.cgi?2945295.

Managing the NLS_LSP_ServerName Object

The NLS_LSP_servername object should exist in the same container as the server object. The NLS_LSP_servername object is created when the server is installed or recreated when one of the following options is executed:

SETUPNLS.NLM
SETUPNLS.EXE
NWCONFIG > License Options > Create License Service Provider

You can manage this object by using NetWare Administrator (NWADMN32.EXE). To enter configuration options, right-click the NLS_LSP_servername object, select Details, and then use the General, Configuration, and Notify tabs.

General

The General tab provides summary information on how this object is configured. It includes:

The name of the server hosting the LSP service
Notification enabled state (Yes or No) The Yes option enables an e-mail notification list.
Transactions Enabled (Yes or No) The Yes option sends data to a log file.
Transaction Log. (Name or N/A)
Record Manager (Btrieve, FLAIM or N/A)
Search To: (Root of the tree or root of the partition)
Date installed

Configuration

The Configuration tab enables you to configure the license search method, notifications, transaction database, and the database record manager. The available options are listed above in the General Tab description.

Changes to the NLS Search Type made in this object are not reflected in the SET parameter NLS Search Type. When both exist, the NLS_LSP_servername object takes preference.

Notify

The Notify tab enables you to configure event notification. Three levels of notification are provided:

Notify by Network Broadcast
Notify by E-Mail Message
Notify by Mail Server Addresses

Managing License Container Objects

NetWare 5.x provides License Container objects to record summary information. These containers hold certificates and have some configuration properties of their own. Each organization or organization unit holding certificates will have two license containers designated by the publisher, product and version. For NetWare 5.1, these two containers are:

You can manage these objects by using NetWare Administrator. Right-click the License Container object, select Details, and then use the General, Units in Use, and Notify tabs.

In addition to the reference material provided, NetWare Administrator provides help on every dialog screen. Step by step procedures and descriptions of objects are provided.

General.

This tab provides product and license summary information.

Note: Summary information will be unavailable when Store NetWare 5 Conn SCL MLA Usage in NDS is set to off.

When summary information is enabled, this tab shows you how many units are installed, how many are available, the type of licenses installed, and the "high water mark" of usage.

The following example illustrates information that the Product Information fields provide:

Publisher	Novell
Product	NetWare 5 Conn SCL
Version	510

The following example illustrates information that the License Information fields provide:

Units Installed	5
Units in Use	2
Units Available	3
Highest Units Used	2
As of	10/14/2000 03:55:00 pm
Notification Enabled	Yes
Data Version	50

Units in Use

The Units in Use tab can be extremely helpful when trying to track down a denial for license unit consumption in an environment when users are limited to a single connection. In the In Use By window, click the user in question.

License Container.

As Figure 2 illustrates, the Usage For tab displays information about that user:

All the connections this UserID is consuming
How many units are consumed
What station (IP address or MAC address) has consumed the displayed units

Notify

The Notify tab allows you to specify which users receive notifications by network broadcast and by e-mail messages.

Managing License Certificate Objects

When licenses are installed for NetWare 5.x, license certificates are installed both for connection and server licenses. As needed, additional connection certificate licenses can be installed to increase the user count.

You can manage License Container objects by using NetWare Administrator. In an expanded License Container object, right-click the object and select Details. Then use the General, Units in Use, Installer, Assignments, and Policy tabs.

Information for the General and Units in Use tabs is similar to the information for the same tabs for License Container objects.

Installer

The Installer tab identifies the UserID used to install the license certificate. To perform actions like deleting certificates, this UserID must exist in the Installer field.

Assignments

The Assignments tab is used to assign a server to a license certificate. Server assignments are required for licenses purchased through Retailers and for customers purchasing licenses through the Volume License Agreement (VLA) program and for Corporate License Agreement (CLA) customer who do not purchase MLA unlimited licenses. (This form of licensing is also referred to as RedBox, non-MLA, and hard stop licensing).

Non-MLA licenses cannot be consumed until a server assignment is made. This assignment is automatic when licenses are installed during a NetWare installation or with NWCONFIG.NLM. However, NetWare Administrator prompts you to make server assignments during license installation.

In an Master License Agreement (MLA) and many Corporate License Agreement (CLA) environments, this assignment prevents all but the assigned server from consuming units from the specified certificate. Because this situation is generally not the desired outcome for MLA licensing, MLA/CLA customers with MLA unlimited license certificates are advised to leave the Server Assignment field blank.

Policy

The Policy tab lists details of the certificate policy. In addition to information about the publisher, product, version and installed units, specific information is provided about the nature of the certificate usage (for example, how many units are consumed at a time and whether an expiration date exists).

Use ACL to Restrict License Consumption.

The General tab on each certificate has a Use ACL to Restrict License Consumption check box. (ACL stands for Access Control List.) This check box enables you to limit which NDS objects can consume units of certificates within a particular license container. When checked, the ACL check box excludes users from using the certificate until you perform the following procedure for each user that should consume licenses from the certificate:

From within NetWare Administrator, right-click the license container, typically Novell+NetWare 5 Conn SCL+510 for NetWare 5.1 or (+500 for NetWare 5).
Select "Trustees of this Object" " Add Trustee.
Add the users for whom you are granting access.
Select either All Properties > Write or Selected Properties > NLS:List of Handles for each of the users added.

Reporting License Usage

You can generate a report and a graph that show consumption of certificate units. In NetWare Administrator, highlight the Organizational Unit or Organization containing license objects and select Tools > Novell Licensing Services > Generate License Reports.

To generate a report concerning the current location or context, click OK. To generate a report concerning the entire NDS tree, click Start at Root. You can use this report to quickly check how close you are to using all the license units. You might need to install additional units.

To convert this information to a graph, click Actions > Create License Usage Report > Finish. The graph displays installed units in blue and unit consumption in green.

Creating Metered Certificates

NetWare provides the ability to create metered certificates for use with applications that control access, such as ZENworks. Creation of a metered certificate without an application like ZENworks to consume the certificate will provide no new functionality.

Creating a Metered Certificate

From NetWare Administrator, select Tools > Novell Licensing Services > Add Licenses > License Metering. You will be presented with the following dialog:

Create a Metered Certificate.

When you create a metering certificate, you must use the exact Publisher Name, Product Name, and Version strings listed by the application you want to meter. Also, the application must include the ability to communicate with licensing services based on the standard LSAPI specification.

Create the Metered Certificate object in the desired context. Enter the number of license units you have purchased. Selecting "Multiple Launches at a Workstation Use Just 1 License" determines whether a workstation will consume one or more than one license when the metered application is launched multiple times from a single workstation.

Tying to a ZENworks object

Full details of this process are beyond the scope of this article. For complete information, see the ZENworks documentation at http://www.novell.com/documentation/lg/zen2/docui/index.html.

After ZENworks has been installed with an application that can use software metering, perform the following steps:

Right-click an application object. Click Details > Software Metering. For detailed information about this property page, click the Help button.
Click Use Novell Licensing and Metering for This Application.
Browse for the License Container object that you created earlier so that its NDS name appears in the text box.
Click Do Not Run Application If NLS Is Not Available.

Troubleshooting Tools

This section lists the log files and tools available to assist with troubleshooting NLS.

LOG FILES

Several log files are available to assist with the troubleshooting of licensing issues. This section explains where to find these logs and what information they provide. The appendix provides details on these logs.

NLSTRACE

At the server console prompt, enter SET NLSTRACE=X, where X is 0, 1 or 2.

0 - Shuts off the running trace file, closes SYS:SYSTEM\NLSTRACE.DBG, and converts the output file to SYS:SYSTEM\NLSTRACE.OLD.

1 - Turns on NLSTRACE and displays output to an NLS screen on the console.

2 - Turns on NLSTRACE, creates NLSTRACE.DBG, and displays output to an NLS screen on the console. If a previous NSTRACE.OLD file exists, it will remain until NLSTRACE is set to 0, at which time it will be overwritten with the current trace session.

NLSTRACE.DBG only exists while the trace file is open.

To see trace output from the console, press Ctrl+Esc and select Novell Licensing Service from the Current Screens menu.

NLSTRACE provides a log of NLS activity on the current server.

PMTRACE

POLIMGR.NLM is an application that uses NLS API calls. Reviewing POLIMGR.NLM traces can help identify where problems originate. However, it is important to reiterate that POLIMGR.NLM is not part of the NLS API.

To review a POLIMGR.NLM trace file, at the server console prompt enter PM TRACE xxxx where xxx represents several actions. To view the available options, enter PM HELP at the console prompt. The screen displays the following listing:

PM Help - displays the listing PM INFO - displays PM NLM info to the console PM TRACEON - turns trace screen ON PM TRACEOFF- turns trace screen OFF PM TRACEFILEON - turns trace file ON PM TRACEFILEOFF - turns trace file OFF PM OUTPUT TO SYSTEM CONSOLE ON - turns PM messages to the console ON PM OUTPUT TO SYSTEM CONSOLE OFF - turns PM messages to the console OFF PM ALLOW OLD APIs - turns support for applications using outdated, unsupported APIs ON (default) PM DISALLOW OLD APIs - turns support for applications using outdated, unsupported APIs OFF

PMTRACE.DBG is created when the trace file is turned on. If a previous PMTRACE.DBG file exists, it is copied to PMTRACE.OLD. PMTRACE logs activity performed by POLIMGR.NLM. POLIMGR.NLM acts as the License Requester.

When the PMTRACE file is written, the contents of PM DISPLAY and PM STATS are appended to this file.

POLIMGR.NLM Diagnostics

POLIMGR.NLM provides two other information screens: PM Stats and PM Display. Again, these tools provide diagnostics for POLIMGR.NLM, not Novell Licensing Services. When looking at POLIMGR.NLM diagnostic information, you are determining what problems are exhibited when POLIMGR.NLM communicates with the licensing library.

PM Display

PM DISPLAY lists the current connection table on the server. The table contains seven columns of information:

Conn:	The number identifying each connection.
State:	The type of connection made. For more information, see POLIMGR.NLM Connection States in the appendix (http://support.novell.com/techcenter/articles/ana20010102.html).
F:	The flag field provides information on the type of licensing this object has been able to obtain during the life of this connection. Most connections display a "1" indicating that this connection has or had obtained a real license. A zero occurs if POLIMGR.NLM is unloaded and PM DISPLAY is executed before POLIMGR.NLM refreshes its connection table. A zero can also occur if a certificate is removed and POLIMGR.NLM refreshes its connection table and cannot find a valid certificate. However, this connection should persist until logout.
NLSHandle:	The hexadecimal handle assigned to this connection.
Started:	The date and time the connection was established.
NextUpdate:	The time this connection is scheduled for.
DN:	The distinguished name of the object connected.

Sample PM Display:

PM Connection Table (entries=50)

Conn     State   F   NLSHandle   Started     NextUpdate  DN

============================================================================

11   00000001    1   0xF4204711  10-23-00 8:52 am    00:31:50    .admin.NOVELL

13   00000001    1   0xF420F4BB  10-23-00 8:53 am    00:33:12    .test1.NOVELL

15   00000001    1   0xF420F37F  10-23-00 8:53 am    00:31:12    .test2.NOVELL

17   00000001    1   0xF451FCEC  10-23-00 8:58 am    00:35:2     .test3.NOVELL

Total State

     4 Licensed (NLS) (1)

PM Stats

PM STATS provides version and date information on POLIMGR.NLM as well as summary statistics on POLIMGR.NLM activity since the last time it was loaded. For information on some of the more critical elements of this log file, see Appendix 5.

SYS$LOG.ERR

As of NW5SP5.EXE and NW51SP1.EXE, many of the informational messages that were displayed to the console are now only found in the system error log. The change happened because the majority of the messages in question are purely informational. If problems do crop up, these messages might help you isolate the problem. Therefore, it is a good idea to check the system error log: SYS:SYSTEM\SYS$LOG.ERR.

CONSOLE UTILITIES

The following utilities (except NLSDIAG.NLM) are available from the NetWare Server console after the server is installed. NLSDIAG.NLM is available as a downloadable utility. For details, see the Additional References section.

NLSDIAG

NLSDIAG.NLM provides a snapshot of the licensing service set up on a single server. Run NLSDIAG from the console. The application loads, creates SYS:SYSTEM\NLSTRACE.TXT, and then automatically unloads.

This snapshot can be compared between servers to verify that all servers are running the same version of NLS. The report also provides information on the licenses that are installed and how they have been consumed up to the point of the report generation.

Note: In the current version, licenses are listed multiple times in the actual NLSTRACE.TXT file produced. In the interest of space, the following sample lists each user once.

Novell Licensing Service Trace File

Created Mon Oct 23 09:04:25 2000

File Server: NLSTEST



NLSAPI.NLM

NLSAPI Library

Copyright 1996-1999 Novell, Inc. All Rights Reserved.

Version: 5.02 8-15-2000



NLSLSP.NLM

NLS License Service Provider

Copyright 1996-2000 Novell, Inc. All Rights Reserved.

Version: 5.02 9-26-2000



Server DN: CN=NLSTEST.O=NOVELL

NDS Tree: NLSTESTTREE

Partition Root Context: [Root]



Replica Ring:

CN=NLSTEST.O=NOVELL - Replica type= MASTER



Read Certificate(s), begin at: O=NOVELL



Certificate:

location:................... NOVELL

publisher:.................. Novell

product:.................... NetWare 5 Conn SCL

version:.................... 510

license ID:................. SN:350306018

installer:.................. admin.NOVELL

installed units:............ 5

used units:................. 4

available units:............ 1

update period (in minutes):. 45

installation time:.......... Fri Sep 8 14:24:31 2000

data version:............... 50



File Server Assignments:

NLSTEST.NOVELL





User Assignments:

NLSTEST.NOVELL





Users:

name:.......... admin.NOVELL

Handle number:. 0xF4204711

Units in use:.. 1

Update time:... Mon Oct 23 08:53:23 2000

Net address type is IPX, address: 151 155 173 254 0 128 41 160 85 66 



name:.......... test2.NOVELL

Handle number:. 0xF420F37F

Units in use:.. 1

Update time:... Mon Oct 23 08:53:23 2000

Net address type is IPX, address: 151 155 173 254 0 128 41 99 132 222 



name:.......... test1.NOVELL

Handle number:. 0xF420F4BB

Units in use:.. 1

Update time:... Mon Oct 23 08:53:23 2000

Net address type is IPX, address: 151 155 173 254 0 128 41 160 84 166 



name:.......... test3.NOVELL

Handle number:. 0xF451FCEC

Units in use:.. 1

Update time:... Mon Oct 23 08:58:30 2000

Net address type is TCP/IP, address: 137 65 171 10 





Certificate:

location:................... NOVELL

publisher:.................. Novell

product:.................... NetWare 5 Server

version:.................... 510

license ID:................. SN:350306018

installer:.................. admin.NOVELL

installed units:............ 1

used units:................. 1

available units:............ 0

update period (in minutes):. 45

installation time:.......... Fri Sep 8 14:24:32 2000

data version:............... 50



File Server Assignments:

NLSTEST.NOVELL





User Assignments:

NLSTEST.NOVELL





Users:

name:.......... NLSTEST.NOVELL

Handle number:. 0xB94B1A75

Units in use:.. 1

Update time:... Mon Oct 23 08:52:23 2000

Net address type is IPX, address: 254 173 2 3 0 0 0 0 0 1

MONITOR.NLM

MONITOR.NLM provides information on utilization and statistics regarding processes running on the server. Run MONITOR.NLM from the console. NLS-specific information can be found in the General Information, Loaded Modules, and Kernel sections.

General Information

When MONITOR.NLM first loads, it displays the General Information screen, which provides utilization and statistical information, including the Current Connections statistic. When determining how a server is reporting license consumption, check this statistic.

Loaded Modules

The Loaded Modules menu item provides statistics on file dates and memory allocation for modules loaded on the system. NLS-related modules typically maintain a stable amount of memory (which varies depending on the environment).

NLS consumes memory as license units are consumed. Therefore, NLS usage of memory increases until the system selftunes or optimizes. The modules you can monitor are NLSLSP.NLM, NLSFLAIM.NLM, LSAPI.NLM, NLSAPI.NLM and NLSTRAP.NLM.

Kernel

The Kernel menu item provides access to thread performance. From the Available Options screen, select Kernel > Threads.

A similar screen can be found in MONITOR by selecting Kernel > Applications > NetWare Applications > F4 (View Busiest Threads). For more information, see Figure 4 in Appendix 7: Usage of Threads in NLS.

NLS should not be a high priority task. NLSLSP Thread 9 will appear occasionally to indicate that the cache is being flushed. However, NLS threads should be low on this list.

NWCONFIG.NLM

Both the License Options and Directory Options in NWCONFIG.NLM may provide useful troubleshooting information.

License Options

License Options lets you install licenses, remove licenses, and create a License Service Provider. Install Licenses and Remove Licenses are the most frequently used options.

Directory Options

Directory Options enables you to extend the schema for NLS in the tree. Log in as Admin or as a user with Admin equivalent rights at the root of the tree. The first server extended should have a master or read/write replica of [Root]. You will be prompted for a location from which to extend the schema.

The schema file for NLS is NLS.SCH. A copy is located in SYS:SYSTEM\SCHEMA. However, make sure you are using a recent schema. Preferably, copy this file from the most current support pack to SYS:SYSTEM\SCHEMA\NLS.SCH. Before attempting to extend the schema, verify that the file copied is a newer file.

DSRepair

The Advanced Options > Global Schema Operation in DSRepair has a number of schema options. Because these features can create problems when improperly used, consult Novell Technical Support Services before invoking these features.

Graphical Utilities

This section will focus on NetWare Administrator, NLS Manager, and Console One.

NetWare Administrator

NetWare Administrator (NWADMN32.EXE) still has the most NLS administration features provided in Novell utilities.In the future, other tools like ConsoleOne will supplant NetWare Administrator for NLS administration. To access NLS features in NetWare Administrator, you need NLSMGR32.DLL, an NLS snap-in found at SYS:PUBLIC\WIN32\SNAPINS\NLSMGR32.DLL.

This .DLL file should be automatically updated by support pack and should be dated at least 8/2/2000. If this file is missing or outdated, replace it with the most current file found in the shipping support pack.

Note: This .DLL file must not be in use when you replace it.

With the snap-in in place, you can access NLS administration dialog boxes. Right-click NLS certificate containers, NLS certificates, or LSP objects.

In addition, Tools > Novell Licensing Services from the NetWare Administrator menu provides access to adding licenses, moving licenses, and generating license reports.

NLS Manager

This tool is obsolete and is no longer supported.

ConsoleOne

ConsoleOne does not yet have all the features of NLS administration that NetWare Administrator has, but it does have one extremely valuable enhancement critical to larger environments. ConsoleOne can view containers with thousands of objects much more quickly.

Nevertheless, to facilitate maintenance we recommend that customers with large numbers of users keep the users in a container separate from the server objects and license containers.

Troubleshooting Procedures

The troubleshooting section of this application note is intended to provide information on how to generally troubleshoot NLS. For specific issues, see the Technical Information Documents (TIDs) and Solution Documents, which can be found on the Web at the locations listed in the Additional References section.

Preventative Maint

To avoid problems in the future and because of the complexity of today's networks, we recommend preventative maintenance.

Apply the most current module: NLSLSP6.EXE (or later) or the most current support pack. To provide functionality and fault tolerance, install NLS as a service on all NetWare 4.x and later servers in the tree.

SETUPNLS.EXE and support packs provide the functionality to accomplish the following tasks:

Ensure that the schema is extended.
Ensure that NLS objects are converted to the latest schema.
Recreate the license provider object for each server in the tree.

Troubleshooting Dependencies

Because of dependencies on other modules and products, it is important to understand that Novell Licensing Services will only be as stable as the components underneath it. The main component dependencies are the LAN infrastructure, the protocol stacks, and Novell Directory Services.

Therefore, when you troubleshoot licensing, it is best to enable the trace screens for both NLS as well as for POLIMGR.NLM. (See Troubleshooting Tools for details.) The trace files will provide details of NLS and POLIMGR.NLM operation.

NLSDIAG.NLM may also provide insight as to how NLS and NDS are configured. Once the trace files have been obtained, open them with an ASCII text editor. Appendices to this article contain the NLS and POLIMGR.NLM return codes as well as sample trace files. Look for return codes that are non-zero. A zero return code represents success.

Has the Schema on the Tree Been Extended to NLS 5.x?

To ensure that the schema has been consistently updated throughout the tree, it is necessary to execute schema operations from the root of the tree. To extend the schema, use NWCONFIG. Select Directory Options > Extend Schema. If in doubt, extend the schema again.

What If NLS Data Becomes Corrupt in the Tree?

If current support packs have been installed on all servers in the network, all servers are running with the same baseline code. Also, the schema has been extended. However, there may be occasions where NDS may have a problem, resulting in corruption of data. In this case, it may be necessary to delete NLS information in the tree and then create the necessary containers and objects again by following these steps:

Delete all license certificates.
Delete license containers.
Delete the License Service Provider object.
Rebuild the operational schema by running DSRepair > Advanced Options > Repair Local DS Database.
Reinstall license certificates.

If problems persist, you might have to contact Novell Customer Support.

Conclusion

The most critical concept concerning Novell License Services is to understand that NLS is a service and not a part of a particular NetWare operating system. For best performance, verify the following for every server in the tree:

All NetWare servers are running a current version of NLS.
The schema for NLS has been extended from the top of the tree downward.
All NLS objects in NDS have been converted to the current version of NLS.
Certificates are available in the search path to the root or the partition or the root of the tree for each server. (This preference is configured in the NLS_LSP_servername object.)
NDS is functioning properly, and network communication allows all NLS services to communicate.

Additional References

Additional information can be obtained from the following sources.

Articles

Novell Application Notes and Developer Notes are available on the Internet at: http://developer.novell.com. These specific documents provide additional information on the Novell Licensing Service.

"A Closer Look at Novell Licensing Services in NetWare 5", January 1999 AppNote. http://support.novell.com/techcenter/articles/ana19990104.html

"NetWare 5 Overview, Part 2", January 1999 Developer Note, licensing section. http://support.novell.com/techcenter/articles/dnd19990102.html

Novell Licensing Services Version 5.02 On-Line Documentation http://www.novell.com/documentation/lg/nls502/docui/index.html

Dow

Novell Technical Support Minimum Patch List. http://support.novell.com/misc/patlst.htm.

Novell Technical Support Patches and Files. http://download.novell.com/.

NLSLSP6.EXE - Latest NLS specific files including NLSDIAG.NLM http://download.novell.com/Download?buildid=F5Rd9miV1DU~

NW51SP2A.EXE - NetWare 5.1 128bit Support Pack http://support.novell.com/cgi-bin/search/tidfinder.cgi?2958182

NW50SP6A.EXE - NetWare 5.0 Support Pack http://support.novell.com/cgi-bin/search/tidfinder.cgi?2958185

Technical Information Doc

Technical Information Documents (TIDs) provide the latest information of a technical nature on Novell products.

The Novell Support KnowledgeBase http://support.novell.com/search/kb_index.htm

Understanding NetWare 5 Licensing http://support.novell.com/cgi-bin/search/tidfinder.cgi?10013723

Installing MLA License Certificates http://support.novell.com/cgi-bin/search/tidfinder.cgi?10013067

NDS Health Check Procedures http://support.novell.com/cgi-bin/search/tidfinder.cgi?10012858

Unable to write license info to NDS http://support.novell.com/cgi-bin/search/tidfinder.cgi?2945295

Appendix 1: Glossary of Terms

This appendix contains a list of some of the terms used in this article.

Activation Key

Activation keys are required for upgrade licenses and are provided with the purchase of upgrade licenses. Certificates requiring activation may be processed on-line at http://www.novell.com/products/activation.

Cache

A cache is a dedicated storage area holding information that will be used again by subsequent requests for the same information. A cache can be implemented in memory or on disk. The purpose of a cache is to speed to retrieval of repeated requests for the same information.

Certificate

Licenses are purchased in increments of 5, 10, 25 Licenses are installed into the tree as License Certificate objects and can be viewed from NWADM32.EXE and ConsoleOne within licensing containers.

Grace Connection

To permit administration of servers, two grace connections are provided in addition to the licensed number of units purchased. These units convert to "real" licenses when other in-use units are freed.

Handle

When a connection is granted, a number is assigned to identify the memory allocated.

Legacy

NetWare 4.x and previous versions of licensing.

License Container

A License Container object. Holds license certificates.

LSP

License Service Provider. This is the NLS backend program (NLSLSP.NLM).

MLA

Master License Agreement. MLA licenses are considered soft stop licenses because NLS does not stop connections at a pre-defined limit. MLA licensing allows multiple servers to run the same certificate and generally provides unlimited connections. Actual licensing is handled by contract and auditing.

NCP

NetWare Core Protocol. Novell's definition for client requests for service from servers. NCPs are transmitted both ways between clients and NetWare operating systems.

Redbox

Redbox licenses are those purchased for off-the-shelf software. They are considered "hard stop" licenses because requests for additional units are rejected once connections have exceeded the number of licensed units.

Schema

The NDS schema defines the classes of NDS objects (such as User, Printer, and Group) that can be created in your NDS tree. Every type of object in an NDS tree has a class defined for it in the tree's schema.

Staleout

NLS requires periodic communication to verify that a license connection is still required. NLS uses timestamps to determine if each connection is still available and, if not, performs a "staleout" on the connection. Redbox licenses (those designed with specific user count limitation) staleout after 45 minutes. MLA certificates staleout after 24 hours.

Stop

A policy in a License Certificate object.

A hard stop informs users that they are out of compliance with the terms and conditions of the license agreement. A hard stop prevents users from accessing a license unit. The hard stop could result from all available license units already being in use.

A soft stop informs users that they are out of compliance but allows them to continue using license units under certain conditions.

A no stop ignores situations in which no license units are available. NLS keeps track of the overage by logging the non-compliance but does not inform or warn the user.

Timestamp

NDS records the time attributes of objects to allow for synchronization between servers and services.

Appendix 2: A Detailed Look at an NLS Trace Log File

This appendix contains an analysis of an NLSTRACE.OLD file captured during a successful license consumption associated with a standard Client32 login. The server in question was running NetWare 5.1 with a Redbox Server+5 license. Each entry in the trace file is followed by the corresponding explanation of that trace entry.

We provide this sample analysis to help you generally understand how to interpret a trace file. Different fonts are used for the trace and commentary sections, as shown below.

NLSTRACE captured information

Commentary on captured information

NLSTRACE.OLD analysis:

Beginning logging session: Thu Sep 28 15:29:15 2000

NLSLSP.NLM NLS License Service Provider Version 5.02 9-26-2000

The beginning of each trace starts with a date and time stamp and the version of NLSLSP.NLM.

87:UpdateCertificates returned 0

The XX: number at the beginning of each entry is the thread of execution for that process. This entry was generated by thread eight, which checks the current cache every minute.

As a rule of thumb, you can use this information to determine how long different processes are taking, even when events are not time stamped. In this case, this entry was coincidental with the start of the login process.

Note: This is a different thread of execution from the rest of the log file.

225:GetVersion()

To determine what version of NLS is running, POLIMGR.NLM issues GetVersion() to the backend licensing process, NLSLSP. GetVersion() first checks for NLS 5.x. If NLS 5.x is not running, GetVersion() then checks for NLS 4.x. If NLS 4.x is not running the process fails.

79:NLS Thread Pool Thread 0 is now running Thu Sep 28 15:30:29 2000

This statement in the trace file indicates that this thread, which was dormant in a "waiting on a semaphore" state, is now running and ready to service the request. Any form of LSRequest will activate Thread Pool Thread 0. Appendix 7 shows how NLS uses threads. Threads 2 through 5 are used to service client requests. NLS Thread Pool Threads 2 and 3 service remote requests originating on other servers. Threads 4 and 5 are used by local requests emanating from the same server.

Note: Different utilities report these threads differently.

NLSTRACE	MONITOR/Debugger
Remote NLS Pool Thread 0	NLS LSP Thread 2
Remote NLS Pool Thread 1	NLS LSP Thread 3
NLS Thread Pool Thread 0	NLS LSP Thread 4
NLS Thread Pool Thread 1	NLS LSP Thread 5

79:Received request from connection 0 (0BBF678A/000000000001)

79:Conn request from 16 (979BADFE/008029A05434)

These two entries are related. They indicate where the connection request originated. The first statement indicates that the request was received from the server (connection 0). The second statement indicates that the server is handling the request in behalf of client connection 16. If the call originated from the server, such as a ZENworks wrapped application, the request would be one line:

79:Received request from connection 16 (address )

Only NLMs running directly on the same server can use connection 0. This connection provides NLMs operating on the local operating system access the local file system. Because the first request was using connection 0, we know that it came from the server.

Note: There are two kinds of requests: LSRequest (a typical client request) and LSRequestConn (an LSRequest proxy made by the server in behalf of a client connection). The Conn Request listed above is actually a LSRequestConn call.

79:LSRequest(, Novell, NetWare 5 Conn SCL, 510, -1, NetWare 5 License Policy Manager)

Now that POLIMGR.NLM has detected the request for a license, it sends an LSRequest() to the client library (LSAPI.NLM and NLSAPI.NLM), which routes this request to the licensing service (NLSLSP.NLM).

The trace statement shows what type of license POLIMGR.NLM is requesting, namely a Publisher (Novell), Product (NetWare 5 Conn SCL), Version (5.10), and Units (1).

79:Retrieved cached certificate NLS:License

ID=SN:350306018.NLS:Publisher=Novell+NLS:Product=NetWare 5 Conn

SCL+NLS:Version=510.ORG0.NLS.US

NLSLSP found the certificate in cached memory and is reporting the ID of the certificate, the matching publisher, product and version, and the location of the certificate.

In this case, the certificate was found in cache. In the Server Connection Licensing (SCL) model, the license service uses the following procedure to find certificates.

NLSLSP first checks cache. If the license certificate is not found in cache, then an actual search of NDS is performed.
In both the case of a cached search or in a search of the actual directory, the search will begin at the server's context and move upward through the tree.
If NDS is configured to search only to the root of the partition, the search will stop at the current partition root. Otherwise the search will continue upward to the root of the tree or until a certificate is found.

In this case, the certificate was found in the current server's container in cache, so no search process was entered into the log file.

Note: The log file only records searches in actual NDS, not in cache.

79:Certificate has 0 present values, 0 not present values

This entry is provided primarily for the NLS programming staff and is generally not pertinent when analyzing the trace. In this case, the trace facility indicates that the server has no previous usage statistics for one of two reasons:

This is the first login and there are no previously allocated certificate values (previous connections).
The server is not tracking usage information because connection tracking was disabled in NDS. The following SET parameter disabled connection tracking:

Set Store NetWare 5 Conn SCL MLA usage in NDS = OFF

This reduces synchronization traffic in MLA environments. Beginning with NW5SP5.EXE and with NW51SP1.EXE this SET statement is set to Off.

Background information on this issue is available in TID 2945295. (For details, see the reference section.)

79:Certificate has 5 available units, 0 reusable units, 0 grace units

NLSLSP has determined the number and type of licenses available. This server had a server+5 license with no users logged in prior to this login session. The license type is Redbox on NetWare 5.1. Thus the certificate found 5 available units. It found 0 reusable units. Reusable units are only found in the Small Business licensing model, which uses nodal user licensing.

In this model, a user logs into one server in the tree and consumes a license. However, when this same user, at this same workstation, logs into another server in the tree, the license is reused. A single user at a single workstation uses a single license in the tree, no matter how many servers the user connects to. This same UserID will consume a second license if login is completed at a second workstation.

For administrative purposes, every server has two grace connections in addition to the specified user count. When these logins are performed, they create entries in error logs but not at workstations or at the console. When another user logs out, the grace connections converted to the available license unit.

79:Certificate is added to list of certificates to possibly consume units from.

79:SearchSpecifiedUnits found 1 certificates on upward search.

These two entries in the log file document the certificates found.

Certificates are placed in a candidate list as prospects for consumption. In reality, once a single certificate is found, NLSLSP usually searches no further for licenses. At this point, the license is not yet consumed, just identified. When the list contains sufficient units, NLS consumes a unit.

79:Unable to recycle-allocating new handle d3b87593

This log entry is a declaration, not an error message. NLS is indicating that it made an attempt to use a recycled handle first, but no handles were available. As mentioned above, to reduce NDS synchronization traffic, NLS 5.x attempts to reuse unallocated handles. Thus, before NLS attempts to create and use a new handle, it attempts to reuse a released handled.

In this case, this login session was the first one attempted since the server was last rebooted. There were no existing handles to recycle.

79:User admin.ORG0.NLS.US has consumed 1 units. Handle is D3B87593

This entry in the log file confirms that the user admin.org0.nls.us consumed a license unit for the connection whose handle is D3B87593. Handle information can also be viewed in PMTRACE.DBG.

79:AddUnitsToUser returned 0

In NLSTRACE log files, return values of 0 indicate success.

79:LSRequest challenge succeeded

When an LSRequest is initiated, POLIMGR.NLM, using secrets, creates a challenge. NLSLSP.NLM pulls shared secrets out of the certificate and creates its own challenge. These two challenges are compared. For a successful unit allocation, these challenges must match.

This process allows POLIMGR.NLM and the NLS backend (NLSLSP) to verify that information is transmitted between each other unaltered and that the requests originated from valid sources.

79:LSRequest returned 0. Handle is d3b87593

This log entry indicates that POLIMGR.NLM received the success code of 0.

79:Success req 3 failure req 0 success rel 1 failure rel 0 staleouts 0 DDC adds 2 DDC deletes 1 DDC overwrites 17 Cacheonlys 0 normal handle adds 3 static handle adds 0 handle deletes 1 recycled 1 non recycled 2

This log entry was actually intended for internal troubleshooting. Some of the accumulated statistics and states apply only to interim processes that do not correlate to manageable elements of NLS. This entry can be ignored.

79:NLS Thread Pool Thread 0 is waiting

This entry brings the process almost full circle. The NLS thread pool is again waiting for a semaphore. NLS has processed the LSRequest and the user is fully logged in.

However, the process is not done yet. POLIMGR.NLM now wants to look at the certificate buffer again to make sure that the certificate has not been tampered with. Although the user is logged in at this point, POLIMGR.NLM again follows the same process to actually obtain the public key in the certificate buffer. This step makes sure that the certificate has not been tampered with.

224:GetVersion()

79:NLS Thread Pool Thread 0 is now running Thu Sep 28 15:30:29 2000

79:Received request from connection 0 (0BBF678A/000000000001)

79:NLSNDSGetCertificate(Novell, NetWare 5 Conn SCL, 510, , -742885997)

This request is coming from NLSAPI.NLM. All API calls of the format NLSNDS are contained in NLSAPI.NLM. Usually, this API call comes from a NetWare 5 server or NetWare 5 Conn SCL; however, double-clicking in NetWare Administrator also calls NLSNDSGetCertificate, so that NetWare Administrator can display the information.

These remaining trace file statements list the completion of the second certificate search used to verify authenticity.

79:Retrieved cached certificate NLS:License

ID=SN:350306018.NLS:Publisher=Novell+NLS:Product=NetWare 5 Conn

SCL+NLS:Version=510.ORG0.NLS.US

79:Certificate has 0 present values, 0 not present values

79:Retrieved cached certificate NLS:License

ID=SN:350306018.NLS:Publisher=Novell+NLS:Product=NetWare 5 Conn

SCL+NLS:Version=510.ORG0.NLS.US

79:Certificate has 0 present values, 0 not present values

79:IterationOperation found 2 certificates on upward search

79:InternalNLSNDSGetCertInfo 0

79:NLS Thread Pool Thread 0 is waiting

16:"NLSTRACE" callback called

Appendix 3: Analysis of a PMTRACE.DBG Lo

This trace file was generated at the same time as the NLSTRACE.OLD file listed above. The two trace files were the result of a Windows NT client running LOGINW32.EXE to perform a standard login as user Admin to context OU=org0.O=nls.C=us.tree.

To complete such a login, both the client and server have NCP Handler engines that communicate requests. NCP, or the NetWare Core Protocol, is a remote procedure call (RPC) based protocol. It is used to create packets of data that allow communication requests for service between NetWare clients and servers.

The client sends a License Connection NCP to the server. The NCP Handler at the server processes the packet. The login request is eventually handed to CONNMGR.NLM.

CONNMGR.NLM must first verify that the request is coming from a valid client and check with a Name Service, in this case, NDS. CONNMGR.NLM then verifies that the credentials of the user are valid.

Once this step is complete, CONNMGR.NLM requests a license from POLIMGR.NLM. POLIMGR.NLM then follows the process examined below. Note that POLIMGR.NLM makes requests of NLSLSP.NLM, which then responds to POLIMGR.NLM. This interaction can be seen in both the NLSTRACE and PMTRACE log files.

POLIMGR.NLM Trace File Started 9-28-2000 3:29:24 pm

(Old trace file existed and was renamed)

Policy Manager trace started: 9-28-2000 3:30:29 pm

POLIMGR.NLM V5.42.0 7-26-2000 for NetWare 510 Server: NLSBS2

These four entries in the log file provide the header for PMTRACE.DBG. The trace file is initiated by entering PM TRACE FILE ON at the NetWare console prompt. To clear the file and capture only a single login in this example, PM TRACE FILE OFF was entered just prior to entering PM TRACE FILE ON.

If PM TRACE FILE ON was in force when the server was restarted, PMTRACE.DBG would also capture the process that POLIMGR.NLM follows when obtaining the server based license.

15:30:29: PMGetConnInfo: NCP conn 16, objectName ADMIN, object class User, free

POLIMGR.NLM is reporting a request for a license, a request that was received from CONNMGR.NLM. POLIMGR.NLM is trying to determine if the request is for a free connection or a licensed connection. Free connections are those coming from other services rather than user requests. For example, NLM logins are usually free connections.

Also, ZENworks objects must login but do not consume licenses. These connections are considered free connections.

15:30:29: AddEntry (licensed) conn 16 objID 8040 state 6

POLIMGR.NLM is adding an entry to its internal connection table, which is loosely related to the server's connection table. They are two actual tables. Entries in this table can be viewed by typing PM Display at the console.

15:30:29: Immediate request: conn 16

"Immediate request" indicates that the policy for the connection licenses is a hard stop. (See the terminology section). A soft stop (the policy of MLA connection licenses) grants connections immediately and then requests licenses later. The hard stop policy means that a connection won"t be granted unless a request for a license succeeds.

15:30:29: ReleaseConnLicense: Conn 16, handle 0, state 6

15:30:29: ReleaseNLSConnLicense: Conn 16, handle 0, state 6

15:30:29: RequestConnLicense: Conn = 16, objectID = 8040

These three entries provide information pertinent to the programmer in tracing low level POLIMGR.NLM routines. These log entries are not pertinent to user-level troubleshooting of NLS.

Note: The next five entries in PMTRACE.DBG occur only with license connections in a hard stop (non-MLA) environment.

15:30:29: LSRequestConn (LS_ANY, Novell, NetWare 5 Conn SCL, 510, ...): conn 16 (0x0)

This is a call to the licensing backend (NLSAPI.NLM) to obtain the connection. The (0x0) is the successful return code from NLSAPI.

15:30:29: RequestNLSConnLicense: conn 16, handle = D3B87593

This POLIMGR.NLM entry displays connection handle information to assist with debugging connection problems using PMTRACE.DBG.

15:30:29: NLSNDSQuery (NULL, NULL, 102, NULL, Novell, NetWare 5 Conn SCL, 510, D3B87593 ...): conn 16 (0x0)

This is a POLIMGR.NLM query to NLSAPI to get the actual certificate and validate its digital signature.

15:30:29: NLS license GRANTED to conn #16

POLIMGR.NLM prints information to the trace file and/or trace screen, indicating that the license was granted.

15:30:29: Immediate request succeeded: conn 16

POLIMGR.NLM prints information to the trace file and/or trace screen, indicating that the request for a hard stop license (Immediate Request) was successful.

15:30:38: WriteConnLicHandleList: handles = 1, dataSize = 12

In case the server goes down, POLIMGR.NLM maintains a list of persistent handles. The next time POLIMGR.NLM is initialized, it checks the file containing these persistent handles (kept in SYS:_NETWARE). After finding an LSP service, POLIMGR.NLM calls NLS to release these handles and, therefore, the associated licenses.

15:30:44: Console Command: PM tracefileoff

15:30:44: Trace file turned OFF

15:30:44: SavePersistentControlInfo

15:30:44: CloseTraceFile

These remaining four entries in PMTRACE.DBG list activities to close the trace file after PM TRACE FILE OFF is entered.

Appendix 4: NLS Return Codes

NLS generates return codes at the console, in the system error log (SYS:SYSTEM\SYS$LOG.ERR), and in NLSTRACE.OLD. The following abbreviated list explains these codes.

It is important to note that some of the return values are primarily intended for the programmers to troubleshoot the program code. Those return codes that are of no real value to administrators contain an asterisk. Most of these programmer-specific codes indicate some form of corruption and will require that the NLSTRACE.OLD file be submitted to Technical Support. A few of these programmer-specific return codes may require a coredump as well.

NLS Return Codes

The following are NLS return codes.

0x0

A zero return code value indicates success; the function completed successfully. No action is necessary.

0xC0001001

LS_BAD_HANDLE. The handle passed within licensing did not point to a valid connection handle. The most likely cause of this error is a valid response to a "staleout" of a certificate. It is also possible that NLS experienced an internal problem when an application requested a license unit. For third party applications, contact the software vendor of the application. Describe the problem and report the return code displayed in this message.

0xC0001002

LS_INSUFFICIENT_UNITS. A license is not available, or no license has been installed at or above the server's NDS context. Depending on the type of license certificate, install a certificate in the server's context or in the requesting user's context. If you have a Server Connection License model, install the certificate in the server's context. If you have a User Access License model, install the certificate in the user's context.

0xC0001003

LS_SYSTEM_UNAVAILABLE. NLSLSP.NLM is not running, NDS is not running, or licensing has not been setup. Make sure that the NDS database is open and that the replicas are synchronizing.

If NLS is installed, load NLSLSP.NLM. If NLS is not installed, run SETUPNLS.EXE to install a licensing service provider (NLSLSP.NLM). You can also use License Options > Create License Service Provider in NWCONFIG.NLM.

0xC0001004

LS_LICENSE_TERMINATED. The licensing system has determined that a resource used to satisfy a previous request (handle, connection no, etc) is no longer granted (has terminated or expired) to the calling software, or the license system has released the license units because of a delayed update.

0xC0001005

LS_AUTHORIZATION_UNAVAILABLE. The license is assigned to different server. If user assignments have been made, then the user is not assigned to the license. A second cause could be that no license certificates are installed for the requested product. Verify that you have installed licenses for the correct product and version.

0xC0001006

LS_LICENSE_UNAVAILABLE. All available, installed license units are in use.

0xC0001007

LS_RESOURCES_UNAVAILABLE. There are insufficient resources (such as memory) available to complete the request.

0xC0001008

LS_NETWORK_UNAVAILABLE. This is a network problem. NLS cannot communicate with a target service. A network problem or an NDS problem might be preventing access to the NDS database.

0xC0001009*

LS_TEXT_UNAVAILABLE.This is an internal check of data passed through licensing. A warning occurred while looking up an error message string for the LSGetMessage() function.

0xC000100A*

LS_UNKNOWN_STATUS. An unknown status code was passed into the LSGetMessage() function.

0xC000100B*

LS_BAD_INDEX. An invalid index was specified in the LSEnumProvider() or LSQuery() function.

0xC000100C

LS_LICENSE_EXPIRED. The license associated with the current context has expired. This may be due to a time-restriction on the license. To determine the expiration date, check the policy tab for the certificate details. If the license is installed, install new license certificates.

0xC000100D*

LS_BUFFER_TOO_SMALL. The buffer passed in LSGetMessage() is too small to accommodate the text string to be returned. Or, the challenge data structure is too small to accommodate the challenge response.

0xC000100E*

LS_BAD_ARG. One or more arguments to LSRequest() were missing or incorrect. This error is also generated when a consistency check of secrets passed during a challenge has failed.

0x80004001*

NLS_TOO_MANY_UNITS. The number of units in the license certificate, when added to the number of units already installed, would have exceeded the maximum number of units allowed. Check the number of license units already installed in the network. (Use the License Usage Reporting feature.) Install a license certificate that brings the total license units available to within the maximum allowable total units for the network.

0xC0004002

NLS_ALREADY_INSTALLED. NLS_ALREADY_EXISTS. The license certificate already exists in the NDS tree. The attempt to install a license certificate failed.

0xC0004003

NLS_OLD_SCHEMA_DETECTED. NLS has detected the presence of outdated object class and attribute names used for legacy licensing services in your NDS schema. This may be the result of an incorrect or failed extension of the schema. The schema might improperly extend if NDS synchronization problems are present.

0xC0004004*

NLS_NULL_SERVER_CONTEXT. A client request must have a valid server DN (for example, CN=PRV-MOBIUS.O=NOVELL). A request from the server might contain a NULL server context.

0xC0004005*

NLS_NO_DATA_RETURNED. One of a number of functions failed to return data.

0xC0004007*

NLS_WRONG_SUMMARY_VERSION. NLS expected a different version in a license container, or the License Container object has become corrupted. Delete the License Certificate objects and the License Container object. Then reinstall the license certificates.

0xC0004008

NLS_CORRUPT_SUMMARY_DATA. An internal consistency check found discrepancies in the summary data contained in the License Container object. This warning indicates that some summary data for a License Container object may be corrupted or lost. This will not impact licensing functionality. You do not need to delete and reinstall any certificates or containers.

0xC0004009

NLS_REMOTE_NCP_FAILURE. The license service provider that the NLS client is communicating with failed to communicate with another server. A NetWare Core Protocol packet error occurred during this process. Make sure that the NDS database is open, that the replicas are synchronizing and that network communication is available.

0xC000400A

NLS_INVALID_DATA_VERSION. The License Service Provider taking care of the current request encountered another NLS object of an incompatible revision (usually older). A version of NLSLSP.NLM running on one server might differ from a version running on another server. If the older object is from NLS 3.0 or 3.4, run SETUPNLS.NLM. If the object is from NLS 5.0, run SETUPNLS.EXE.

0xC000400B

NLS_UNSUPPORTED_FUNCTION. The License Service Provider that the NLS client is communicating with does not support this function. A call is being issued to an older LSP. The LSP is unable to handle the request. Update NLSLSP.NLM by running SETUPNLS.EXE.

0xC000400C

NLS_NO_DATABASE_NLM. No database NLM is currently loaded on the server specified. The NLM that is required for transaction logging does not exist. The Enable Transaction Database parameter is not set for the LSP object. Using NetWare Administrator, view information about the LSP object. At the Configuration page, check the Enable Transaction Database check box and specify a database record manager.

0xC000400D

NLS_CORRUPT_CERT. The data in the license certificate does not exist or is corrupted. Delete and reinstall the license certificate.

0xC000400E

NLS_REMOTE_SERVER_UNAVAILABLE. An LSP running on one server has attempted to fulfill a request by communicating with an LSP running on another server. The requested LSP is not available. Make sure that each partition containing a license certificate has NLSLSP.NLM running on at least one server that has a read/write replica. Also make sure that the two LSP servers can communicate.

0xC000400F

NLS_DOES_NOT_EXIST. This message primarily indicates that NLS could not find an NLS object, allowing NLS to follow different code paths. In rare instances, this situation might indicate that the specified object (License Container, License Certificate, or LSP) does not exist or is unknown to NLS. The object is not installed. In that case, you can reinstall the object by running SETUPNLS.EXE or by installing a license certificate.

0xC0004010

NLS_INVALID_ACTIVATION_KEY. An activation key was not provided or was entered incorrectly. Enter the activation key correctly. If the problem persists, check with your vendor.

0xC0004012*

NLS_DOES_NOT_EQUAL. This message is internal to the program and is not displayed on the customer's screen.

0xC0004013

NLS_INVALID_CONNECTION. The NCP connection for which an NLS request was attempted is invalid. An earlier POLIMGR.NLM exists. The earlier POLIMGR.NLM passed an invalid connection. Install the latest POLIMGR.NLM by applying the most current support pack.

0xC0004014

NLS_REMOTE_AUTHENTICATION_FAILED. The license request or update challenge made by one LSP to another on behalf of an NLS client failed. Someone is trying to gain unauthorized access. A software component trying to function like an LSP communicated with other NLSLSP.NLMs running on other servers. Because the LSPs authenticate to make sure that the communications are valid, this communication failed.

0xC0004015

NLS_CHALLENGE_FAILED. Some functions (for example, NLSNDSRequest and NLSNDSUpdate) require a challenge. During authentication between POLIMGR.NLM and the licensing service, the challenge failed. Make sure that you have a valid license certificate. Contact your vendor.

0xC0004016*

NLS_INVALID_TAG. The license certificate has an invalid tag. Contact the software vendor. Describe the problem and report the return code displayed in this message.

0xC0004017

NLS_INVALID_CERTIFICATE. The specified license certificate is not a valid NLS license certificate. Delete and reinstall the license certificate. If the problem persists, contact your vendor.

0xC0004018*

NLS_TAG_NOT_FOUND. The data specified does not exist in the license certificate. NLS experienced an internal problem when an application requested a license unit. Contact the software vendor. Describe the problem and report the return code displayed in this message.

0xC0004019*

NLS_INVALID_CERT_HANDLE. NLS could not verify a specified license unit. NLS experienced an internal problem when an application requested a license unit. Contact the software vendor. Describe the problem and report the return code displayed in this message.

0xC000401A

NLS_INVALID_RADIX.

0xC000401B

NLS_INVALID_TAG_LENGTH.

0xC000401C

NLS_INVALID_TAG_DATA.

0xC000401D

NLS_STRING_TOO_LONG.

0xC0004020

NLS_CERTIFICATE_INCOMPLETE.

These five return codes all deal with a certificate that does not conform to NLS standards. Either a required component of the certificate is missing or a component has an invalid data value. Contact the software vendor. Describe the problem and report the return code displayed in this message.

0xC000401E

NLS_UNKNOWN_TAG. NLS does not recognize a tag. An older version of an application is unable to recognize newer tags on license certificates. Upgrade the application or tool that deals with licenses.

0xC000401F*

NLS_INVALID_KEY_LENGTH. Either the length of the activation key is 0 or it exceeds 255 characters. Contact the software vendor. Describe the problem and report the return code displayed in this message.

0xC0004021*

NLS_NO_CHECKSUM_TAG. The license certificate buffer does not contain the NLS_LIC_CHECK_SUM tag, which is required. Contact the software vendor. Describe the problem and report the return code displayed in this message.

0xC0004022

NLS_INVALID_CHECKSUM.The specified activation key and checksum do not match. Contact the software vendor. Describe the problem and report the return code displayed in this message.

0xC0004023

NLS_HAS_SUBORDINATES. NLS has determined that a License Container object has one or more license certificates.

0xC0004024

NLS_PRIMARY_HAS_SECONDARIES. NLS has determined that a user currently consuming a primary usage instance is also consuming one or more secondary usage instances. This user still has secondary usage instances of this license.

You cannot remove a user's primary usage instance of a license until all of the user's secondary usage instances have been removed. This user may have other secondary usage instances of this license that are not visible in this view. For example, the user may be consuming units of this product from a license certificate located in a different directory context.

To remove the primary usage instance of this license for the selected user, remove all of the user's secondary usage instances and then try the operation again.

0xC0004025

NLS_LSP_VERSION_LESS_THAN_REQUIRED. This error is saved as NLS attempts to find an LSP service at lower versions. NLS displays this error if the subsequent attempt at accessing the LSP through the legacy LSP object also fails.

0xC0004026

NLS_CERT_IN_USE. This error is primarily used to indicate that you are trying to delete a certificate that is currently in use.

0xC0004027

NLS_UNABLE_TO_CONNECT. This return code is used internally as part of in-memory caching during periods of network unavailability. If communication errors persist, the console or clients may also display -625, -622 and x8910 errors. In these cases, this return code may cause NLS to branch to 0xC000400E NLS_REMOTE_SERVER_UNAVAILABLE or 0xC0001008 LS_NETWORK_UNAVAILABLE. These are external network problems that must be cleared up for NLS to function properly.

Appendix 5: POLIMGR.NLM Connection States

POLIMGR.NLM provides several diagnostic screens and a log file which yield valuable information about POLIMGR.NLM interactions with NLS. Each connection achieves a state indicating whether or not the connection is licensed. These states can be seen when executing PM DISPLAY and when viewing PMTRACE.DBG.

State	Description
0	A connection is not in use.
1	A connection is using an NLS license. This is the standard unit connection and will be displayed as real connections in trace statistics.
2	A connection is using a grace connection. Each license provides two grace connections beyond the total purchased connections. When the unit count drops below the total license count, these connections are converted to real licensed connections.
3	A connection is in use but has no license. Causes:MLA or soft stop licensing. POLIMGR.NLM grants the license first and then looks for an available unit. The MLA license gets to this state if an available license cannot be found. Hard Stop licensing. If a hard stop license suffers a loss of license, due to a power outage or other failure, the license changes to this state while POLIMGR.NLM tries to re-acquire a license.
4	An NLM is using a connection. NLM connections do not consume license units.
5	A connection is a legacy connection. This number will only appear on NetWare 4.x legacy licensing connections.
6	A connection is using an unlicensed soft stop. Connections are in this state until the first attempt to get a real license is complete. (This situation is true only when a policy is soft stop.)
7	The connection is a CLIB connection. This is an unlikely state, indicating a connection from CLIB.
8-10	Reserved for future use.
10000000	A connection is queued for release. If a connection is queued for release, a mask of 1000000 in hex will be 'OR'd with the actual state. (A '1' will appear in the left most column of the state.) Licenses in this state are released asynchronously on a thread separate from the logout request coming to POLIMGR.NLM from the CONNMGR.NLM.

Appendix 6: A Description of PM STATS

PM STATS provides a great deal of summary state information.

Licensed (NLS):	The number of connections currently licensed with an NLS license.
Licensed (Grace):	The number of connections currently using a grace connection.
Unlicensed (Conn):	The number of connections that are currently in use but do not have a license.
Unlicensed (NLM):	The number of connections in use by NLMs (These are never licensed).
Unlicensed (Legacy):	The number of connections currently licensed with a 4.x license.
Soft Stop Unlicensed (Conn):	The number of granted connections for which a license has not yet been requested.
Unlicensed (CLIB): Unlicensed (FTAM): Unlicensed (ANCP): Unlicensed (Other):	CLIB, FTAM, ANCP, and Other are all unlicensed (free) connections of various types.
AttemptsToFindNLS:	The number of times POLIMGR.NLM has tried to communicate with and find NLS.
LocatedNLSSuccessful:	The number of times POLIMGR.NLM has found NLS.
TimesLostCommWithNLS:	The number of times POLIMGR.NLM has lost communication with NLS.
Peak Unlicensed:	The peak number of unlicensed connections.
Current Unlicensed:	The current number of unlicensed connections.
Total unlicensed connections converted to Real licenses:	The number of connections which were, at some point, running without a license and which eventually were able to get a license.
Conn Requests - Total:	The total number of login connection requests.
New:	The number of these Conn Requests that were new. (No connection already existed for this connection number.)
Unlicensed:	The number of these Conn Requests that were already in use but unlicensed.
Unlicensed SS:	The number of these Conn Requests that were already in use but were unlicensed soft stop.
Licensed:	The number of these Conn Requests that were already in use and licensed (either NLS, legacy or grace).
Conn Release Requests:	These statistics record successful, licensed, unlicensed, and other Conn Release Requests.
Successful:	The number of successful logout requests from connections.
Licensed:	The number of Conn Release Requests that were licensed at the time they logged out.
Unlicensed:	The number of Conn Release Requests that were unlicensed at the time they logged out.
Other:	The number of Conn Release Requests that were in some other state at the time they logged out.

For detailed information on the following codes, refer to Appendix 4: NLS Return Codes.

Conn Request Failures:	These statistics record the number of failures for each of the most prevalent types of NLS return codes. All PM STATS summary statistics are reset when POLIMGR.NLM is reloaded.
0xC0001002:	NLS_ALREADY_INSTALLED NLS_ALREADY_EXISTS
0xC0001003:	NLS_OLD_SCHEMA_DETECTED
0xC0001005:	NLS_NO_DATA_RETURNED
0xC0001006:	LS_LICENSE_UNAVAILABLE
0xC0001008:	NLS_CORRUPT_SUMMARY_DATA
0xC000100e:	LS_BAD_ARG

Appendix 7: Usage of Threads in NLS

NLSTRACE files often list Thread Pool Thread 0. Thread Pool Threads 0 and 1 listed in NLSTRACE files map to threads 4 and 5 as shown in MONITOR. To see thread usage, enter MONITOR at the console prompt. From the menu, select Kernel > Threads. The most prevalent listing for NLS threads will be NLS LSP Thread 8.

A similar screen can be found in MONITOR at Available Options > Kernel > Applications > NetWare Applications > F4 (View Busiest Threads). See Figure 4.

Busiest Threads, Listed in MONITOR.

Threads listed by Number

The following list can help you understand thread usage viewed in MONITOR.

Thread	Function	Explanation
1	Main NLS thread	Main worker thread for NLS processing
2	Remote	LSAPI or NLSAPI requests from other NLSLSP services on the network
3	Remote	LSAPI or NLSAPI requests from other NLSLSP services on the network
4	Client	LSPAPI or NLSAPI requests for client requests processed by this server
5	Client	LSPAPI or NLSAPI requests for client requests processed by this server
6	Dupcheck	Thread checking for duplicate licenses on the network
7	Dredge	The dredge thread searches the entire tree for duplicate license certificates
8	Cache commit	Commit changes from the certificate cache to Novell Directory Services once per minute. Commit changes from Novell Directory Services to cache every 30 minutes
9	Janitor (UAL)	The janitor process is primarily for the User Access Model, as found, for example, in Small Business Suite. This thread is uncommon

* Originally published in Novell AppNotes

Disclaimer

The origin of this information may be internal or external to Novell. While Novell makes all reasonable efforts to verify this information, Novell does not make explicit or implied claims to its validity.