How to Optimize Novell Licensing Services “How To” Article

How to Optimize Novell
Licensing Services
“How To” Article
NOVELL APPNOTES
Boyd Memmott
Engineer
World Wide Support
[email protected]
Bryan Nahrwold
Test Engineer
Core Operating System
[email protected]
Jack Tobiasson
Technical Writer
Product Documentation
[email protected]
The article is for those who must implement and maintain Novell Licensing
Services (NLS) in a NetWare environment.
Contents:
26
•
Novell Licensing Services
•
How NLS Works
•
Installing NLS in a NetWare 5.x Environment
•
Configuring NLS
•
Troubleshooting Tools
•
Troubleshooting Procedures
•
Conclusion
•
Additional References
Topics
installing NLS, configuring NLS, troubleshooting NLS
Products
NetWare, NDS, BorderManager
Audience
network designers, administrators, consultants,
integrators,
Level
Intermediate
Prerequisite Skills
Familiarity with NetWare and Novell Directory Services
Operating System
NetWare
Tools
None
Sample Code
No
www.novell.com/appnotes
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 the 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, Border Manager,
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.
J a n u a r y
2 0 0 1
27
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.
28
www.novell.com/appnotes
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.
J a n u a r y
2 0 0 1
29
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://developer.novell.com/research/appnotes/2001/january/02/a010102.htm.
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://developer.novell.com/research/appnotes/1999/january/04/index.htm.
30
www.novell.com/appnotes
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:”.
License Service Provider. NLS installs a License Service Provider object for
each server running an LSP application. In NetWare 5.x, the LSP object is
identified as NLS_LSP_servername.
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. Border Manager, ZENWorks and other program suites
provide different applications to manage their connections.
J a n u a r y
2 0 0 1
31
7
Novell
Directory
Services
2
Client
Request
6
8
3
9
1
Novell
Licensing
Services
5
POLIMGR.NLM
CONNMGR.NLM
4
10
Figure 1: Flow of a Licensed Client Connection.
1.
2.
32
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.
3.
If the user object is valid, CONNMGR.NLM requests authentication from
POLIMGR.NLM.
4.
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.
5.
POLIMGR.NLM checks NLS to see if a license unit is available for the
requested publisher, product and version.
6.
NLS requests the license unit from either NDS or from the server’s cache.
7.
NDS returns the license unit or a failure code.
www.novell.com/appnotes
8.
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.
9.
POLIMGR.NLM informs CONNMGR.NLM that a license has been granted.
10. CONNMGR.NLM updates its connection table.
11. 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 Environment
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.)
J a n u a r y
2 0 0 1
33
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.
34
www.novell.com/appnotes
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.
J a n u a r y
2 0 0 1
35
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
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.)
36
www.novell.com/appnotes
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://support.novell.com/servlet/filedownload/nsd/nlslsp6.exe.
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://developer.novell.com/research/appnotes/2001/january/02/a010102.htm.
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.
J a n u a r y
2 0 0 1
37
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:
38
•
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)
www.novell.com/appnotes
•
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.
J a n u a r y
2 0 0 1
39
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.
40
www.novell.com/appnotes
Figure 2: 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.
J a n u a r y
2 0 0 1
41
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:
1.
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).
2.
Select “Trustees of this Object” > Add Trustee.
3.
Add the users for whom you are granting access.
4.
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.
42
www.novell.com/appnotes
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:
Figure 3: 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.
J a n u a r y
2 0 0 1
43
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:
1.
Right-click an application object. Click Details > Software Metering. For
detailed information about this property page, click the Help button.
2.
Click Use Novell Licensing and Metering for This Application.
3.
Browse for the License Container object that you created earlier so that its
NDS name appears in the text box.
4.
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.
44
www.novell.com/appnotes
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.
J a n u a r y
2 0 0 1
45
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://developer.novell.com/research/appnotes/2001/january/02/a010102.htm).
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
NextUpdateDN
============================================================================
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 at
http://developer.novell.com/research/appnotes/2001/january/02/a010102.htm.
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.
46
www.novell.com/appnotes
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:...................
publisher:..................
product:....................
version:....................
license ID:.................
installer:..................
installed units:............
used units:.................
available units:............
update period (in minutes):.
installation time:..........
data version:...............
NOVELL
Novell
NetWare 5 Conn SCL
510
SN:350306018
admin.NOVELL
5
4
1
45
Fri Sep 8 14:24:31 2000
50
J a n u a r y
2 0 0 1
47
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:...................
publisher:..................
product:....................
version:....................
license ID:.................
installer:..................
installed units:............
used units:.................
available units:............
update period (in minutes):.
installation time:..........
data version:...............
File Server Assignments:
NLSTEST.NOVELL
User Assignments:
NLSTEST.NOVELL
Users:
48
www.novell.com/appnotes
NOVELL
Novell
NetWare 5 Server
510
SN:350306018
admin.NOVELL
1
1
0
45
Fri Sep 8 14:24:32 2000
50
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
http://developer.novell.com/research/appnotes/2001/january/02/a010102.htm.
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.
J a n u a r y
2 0 0 1
49
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.
50
www.novell.com/appnotes
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 Maintenance
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:
1.
Ensure that the schema is extended.
2.
Ensure that NLS objects are converted to the latest schema.
3.
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.
J a n u a r y
2 0 0 1
51
Q. Has the Schema on the Tree Been Extended to NLS 5.x?
A. 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.
Q. What If NLS Data Becomes Corrupt in the Tree?
A. 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:
1.
Delete all license certificates.
2.
Delete license containers.
3.
Delete the License Service Provider object.
4.
Rebuild the operational schema by running DSRepair > Advanced Options >
Repair Local DS Database.
5.
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:
52
•
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.
www.novell.com/appnotes
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://developer.novell.com/research/appnotes/1999/a9901.htm
“NetWare 5 Overview, Part 2”, January 1999 Developer Note, licensing section.
http://developer.novell.com/research/devnotes/1999/d9901.htm
Novell Licensing Services Version 5.02 On-Line Documentation
http://www.novell.com/documentation/lg/nls502/docui/index.html
Downloads
Novell Technical Support Minimum Patch List.
http://support.novell.com/misc/patlst.htm.
Novell Technical Support Patches and Files.
http://support.novell.com/filefinder.
NLSLSP6.EXE - Latest NLS specific files including NLSDIAG.NLM
http://support.novell.com/servlet/filedownload/nsd/nlslsp6.exe
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 Documents
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
J a n u a r y
2 0 0 1
53
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.
54
www.novell.com/appnotes
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.
J a n u a r y
2 0 0 1
55
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.
56
www.novell.com/appnotes
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).
J a n u a r y
2 0 0 1
57
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:
1.
This is the first login and there are no previously allocated certificate values
(previous connections).
2.
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.
58
www.novell.com/appnotes
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.
J a n u a r y
2 0 0 1
59
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.
60
www.novell.com/appnotes
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 Log File
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.
J a n u a r y
2 0 0 1
61
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:
62
The next five entries in PMTRACE.DBG occur only with license
connections in a hard stop (non-MLA) environment.
www.novell.com/appnotes
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.
J a n u a r y
2 0 0 1
63
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.
64
www.novell.com/appnotes
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.
J a n u a r y
2 0 0 1
65
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.
66
www.novell.com/appnotes
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.
J a n u a r y
2 0 0 1
67
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.
68
www.novell.com/appnotes
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.
J a n u a r y
2 0 0 1
69
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.
70
www.novell.com/appnotes
Soft Stop Unlicensed (Conn):
Unlicensed (CLIB): Unlicensed
(FTAM):
Unlicensed (ANCP):
Unlicensed (Other):
The number of granted connections for which a license has not yet
been requested.
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.
J a n u a r y
2 0 0 1
71
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 Fig 1.
Figure 4: Busiest Threads, Listed in MONITOR.
Threads listed by Number
The following list can help you understand thread usage viewed in MONITOR.
72
www.novell.com/appnotes
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.
Copyright © 2001 by Novell, Inc. All rights reserved.
No part of this document may be reproduced or transmitted
in any form or by any means, electronic or mechanical,
including photocopying and recording, for any purpose
without the express written permission of Novell.
All product names mentioned are trademarks of
their respective companies or distributors.
73
www.novell.com/appnotes