Novell is now a part of Micro Focus

Kayak: Node-Based Licensing Using NetWare Licensing System (NLS) Services

Articles and Tips: article

BRENT REED
Developer Support Engineer
Developer Support

01 Jan 1997


Presents the steps for developing to NLS. Also discusses how Kayak uses NLS to license connections and how this affects legacy APIs.

Introduction

Kayak is the code name for the small business offering of IntranetWare, due to be released in January 1997. Kayak is the first Novell OS to use NetWare Licensing System (NLS) Services to license the server and connections.

With Kayak, a user license is based on the node. When a user logs into Novell Directory Services (NDS) a license will be consumed. Any additional connections to a server in the tree by a node will not consume any additional licenses.

NetWare APIs which in the past returned server based license connection information will now return the available NLS connection licenses in the NDS tree. This affects applications which base their licensing/pricing scheme on the legacy form of NetWare server-based licensing where connection licenses reside at the server and are coupled to the server; each licensed connection to the server consumes a license.

This article will discuss legacy NetWare licensing with corresponding CLIB APIs used to get the number of licensed connections on a server. Also discussed is how Kayak uses NLS to license connections and how this affects legacy APIs. In addition, we present the logical steps for developing to NLS.

NetWare Licensing System (NLS) Services are currently available on IntranetWare and NetWare 4.11. However, Kayak is the first NetWare OS which will benefit from the use of NLS.

NLS provides to Kayak license certificates which aren't tied to the application but are instead stored in the NDS tree. An application's licensing behavior is determined by the license itself as the application queries the license service provider (LSP) which then reads the license certificate tags and returns the appropriate behavior for the application. With a variety of policy attributes to choose from, flexible license policy stratifications can be created for the same executable.

The capability of NetWare to utilize NLS is another positive step in the history of NetWare toward making licensing easier to manage and administer.

NetWare Legacy Licensing Architecture

Server Connection Model

NetWare (excluding Kayak) has been and is currently priced and sold based on a server connection model. A server is available in different stratifications: 5-user, 10-user, 25-user, and up to 1000-user version. NetWare 3.x has the license stratification as part of SERVER.EXE with an additional 100 local connections available for NLMs.

NetWare 4.x added some extra twists to licensing. Instead of embedding a user stratification in the executable, a license diskette containing a SERVER.MLS file was used. Additive licensing was introduced which would allow the combining of stratifications on the server. Also, SFT III and SMP licenses enable their respective products.

Non-Licensed Connection

NDS created the need for the nonlicensed connection. When a directory services connection is performing network NDS Tree operations which are not considered to be server-based, it uses a nonlicensed connection. This connection does not count against the user stratification.

Connection Table

To accommodate this functionality, NetWare 4.x contains a dynamic connection table which grows as the need arises, unlike the fixed size connection table in 3.x.

Legacy APIs Used To Determine Server Stratifications

For certain applications, developers have found it advantageous to tie their licensing model to the number of supported users on a NetWare or IntranetWare file server. When using CLIB APIs, developers had to migrate from GetServerInformation()in 3.x to SSGetOSVersionInfo() when determining the number of licensed connections supported on a 4.x server. It's not that GetServerInformation() would not return information on a 4.x server. The meaning just changed when using the API on a NetWare 4.x server.

GetServerInformation()returns theFILE_SERV_INFO structure which has a maxConnectionsSupported field. When calling a remote 3.x server, this structure gives you the size of the static connection table. Making this call on a local 3.x server gives you the size of the connection table plus a static fixed size of 100 which is for local NLM connections. When you make this call to a 4.x server, the meaning changes because the connection table grows dynamically in response to the need for nonlicensed connection support. To accommodate this need for developers to discover the number of licensed connections supported on a server, SSGetOSVersionInfo() returns a GetOSVersionInfoStructurewith a maxNumOfUsersfield.

Server-Based Model

Despite the above difference, the licensing of the NetWare OS (excluding Kayak) is server centric based. When a connection (bindery or NDS) needs to access resources which belong to a server, such as file or print resources, it will use a licensed connection belonging to that server. If a single user needs to access server resources residing on n different servers, n licensed connections will be consumed.

NLS Architecture

NetWare Licensing System (NLS) Services is a distributed, enterprise network service to license applications on the network. NLS is tightly integrated with Novell Directory Services (NDS) and is based on an "enterprise service" architecture. This architecture, demonstrated in Figure 1, consists of NLS client access which is supported on different platforms and system components that reside on NetWare servers. System components include one or more License Service Providers (LSPs) and a transaction database.

Figure 1: NLS Architecture.

The client components of NLS enable applications to access license services. These services can be grouped into two different categories: access to license certificates and administrative/management functions. This article's emphasis is on client access to license certificates. Access to license certificates (NDS objects) conforms to the industry standard common licensing API (LSAPI) described in the LSAPI Specification 1.1.

NLS Components

Figure 2 displays NLS objects as seen in the Kayak Novell Easy Administration Tool (NEAT). Kayak is also shipped with NWADMIN. Each LSP is registered as an NDS object. This reduces NLS associated network traffic and increases manageability. License certificates are also stored in NDS as objects. They are placed in product containers which identify the publisher, product and version of contained licenses.

Figure 2: NLS Objects in the Novell Easy Administration Tool (NEAT).

Access to License Certificates

As the application makes LSAPI requests, the underlying NLS Client Provider communicates requests directly to the LSP. In NLS, the LSP resides on the NetWare server as NLS.NLM. The LSP searches the NDS context for license objects.

In more detail, NLS uses the following steps to process a license resource request:

  1. NLS clients request services from the license service.

  2. A client specific component packages the request and submits it to the LSP.

  3. The LSP examines the request and checks NDS to determine whether it can fulfill the request. It does this by checking the current user context for license certificates.

  4. The LSP fulfills the request, if possible, allocating the requested resources.

  5. If the LSP cannot fulfill the request, it can check each next higher context in NDS to find the necessary license units.

  6. Requests are stored in a transaction database for further analysis using NLS management APIs.

Kayak Licensing Architecture

In a later discussion of NLS license certificates, this article explains how these certificates can be extremely flexible in defining the license behavior of an application. With this flexibility, NLS has given Novell the ability to separate out usage licenses from SERVER.EXE. Two types of licenses exist for Kayak: the server base license and the connection license.

Server Licensing

The server Policy Manager is the entity which enforces licensing. Policy Manager uses a locally stored server base license to validate the use of the Kayak OS. Policy Manager is also the NLS client that requests license information (including units) when users use the connections. The detailed steps describing how an NLS client requests a license are found in the Application Access to License Certificates section above.

Node-Based Connection Model

With Kayak, Novell has taken connection licensing a step further. Instead of using a server centric model, where each time a client creates a connection to the NetWare server, it consumes a license (not considering nonlicensed connections), the licensing of connections is node based; the consuming of a license is based on the node connecting once to the network. This means that when a user logs into the Novell Directory Services (NDS) based network and consumes an NLS connection license in NDS, any additional connections to a server in the tree by a node will not consume any additional licenses.

Kayak and Legacy APIs

Legacy APIs for gathering licensing information from Kayak will still return information. However, like the above example where a situation when moving from a static license table in 3.x to a dynamic table in 4.x caused developers to use different APIs to get license information, so is the case with gathering license information from Kayak. The number of licensed connections available to a server will be those connection licenses which are visible to the LSP.

Following is an example of using legacy APIs on a Kayak server. After installing the first Kayak server with a base license, two connection licenses were installed: a 5-user license, and an 8-user license. The selected results of GetServerInformation()and SSGetOSVersionInfo() ran on the first server are as follows:

GetServerInformation()

     Max Connections Supported = 9 (size of the connection table in 4.x)

          

SSGetOSVersionInfo()

     Max Num Of Users = 13 (number of available connection licenses in Kayak)

After installing a second Kayak server in the same tree with a base license but without installing any additional connection licenses, GetServerInformation()and SSGetOSVersionInfo() are as follows:

GetServerInformation()

     Max Connections Supported = 13 (size of the connection table in 4.x)



SSGetOSVersionInfo()

         Max Num Of Users = 13 (number of available connection licenses in Kayak)

Developing to NetWare Licensing System (NLS) Services

NetWare Licensing System Services is part of the DeveloperNet NetWare SDK. Books in the NetWare SDK documentation referencing NLS are the Cross Platform Developers Guide and Cross Platform Function Reference.

APIs which belong to the LSAPI standard are prefixed with LS. Administrative APIs are prefixed with NLS.

Benefits of Using NLS

NLS enables a more flexible approach to licensing on the IntranetWare network operating system. A foundation is provided for software vendors to sell their software using electronic licenses instead of paper ones. Since policy information is contained in the license, only one executable image is necessary. By using NLS, an application can benefit by adopting different licensing models and easy implement and deploy application stratifications which aren't tied to the executable.

Additional benefits of using NLS are the same benefits obtained when using NDS. Some of these benefits are fault tolerance, scalability, reduced SAP traffic, and manageability of license objects.

NLS also helps administrators monitor and control the use of licensed applications on a network. Since all NLS requests are stored in a transaction database, management tools can monitor the usage of applications on the network.

NLS is based on the LSAPI specification. If an application is embedded with these calls, any LSP can service the application.

Migrating to NLS

NLS can be grouped in three main categories; application enabling using LSAPI calls, license certificate generation, and management functionality using NLS management calls. The first logical step is to enable your application. Next is to generate license certificates. Both are discussed below. Next in the logical sequence is to use management APIs. At a minimum you can do management with NWADMIN and NDS. Management APIs are not covered in this article.

Application Enabling

License enabling an application is a simple process of using the LSAPI specification APIs. Sample code which demonstrates the enabling of an application using these APIs can be found in the LSAPI Demo on the DeveloperNet SDK. Remember, these are industry standard APIs which any License Service Provider conforming to the standard could service.

A licensed application can take two forms: a metered application and a secure application. A metered application does not require the challenge mechanism which is described in the LSAPI specification. A secure license requires the challenge mechanism. To discourage tampering, just copy the challenge code somewhere directly into your application instead of linking in a separate .OBJ file.

A brief explanation of these APIs and the sequence to use them follows. The optional LSGetMessage() for generating message strings for error handling has been omitted for simplicity.

Startup LSRequest() Request a license from the LSP. Creates a license handle. Also gathers licensing resources such as the default update period.

During each update period (set a timer) LSUpdate() Informs the LSP that this client is still using resources

Termination of the Application LSRelease() Informs the LSP that this client has finished with the resources LSFreeHandle() Cleans up all resources associated with the license handle

Even if your current product strategy is not mature enough for NLS licenses, your application can use these APIs now. When your application passively makes these calls, even when a license is not available, NLS management tools accessing the transaction database could monitor the activity of your application. NLS does not make the decision as to whether the application can run or not. NLS lets the application know if license units are available or not available.

NetWare License Certificates

The next logical step in developing to NLS is creating a license certificate. The license certificate format is found in Appendix A of the Cross Platform Developers Guide in the NetWare SDK. At the minimum you can create a meter license using NWADMIN which license is composed of a Publisher, Product Version, and Number of Units. When you are ready to adventure into more complex license stratifications, you will combine a set of license tags to produce the desired outcome.

As illustrated in Figure 3, a license certificate is composed of a group of license tags (also referred to as fields, attributes, and descriptors). These license tags give the developer the flexibility to create a myriad of different policies. License tags are nested/appended together in order to form a certificate. In addition to default certificate tags, a NetWare License Certificate defines optional NLS policy attributes which can be placed in the license system specific area of the certificate. These policy attributes include consumption, security, unit related, and error handling attributes.

Figure 3: License Certificate.

The following example demonstrates the flexibility of execution which can be obtained when defining a license certificate:

Application X is license enabled using LSAPI specification APIs. This one application is shipped with different kinds of beta licenses for different groups of beta testers. One license certificate stratification is 5 units and expires July 1, 1997. The second license certificate stratification is also 5 units and expires July 1, 1997. The difference is the second license also contains an exception policy to allow 30 more days of use for a preferred set of testers. If the licenses are used during the exception period, this fact will be recorded in the transaction database for further analysis.

Following is a sample of policy descriptors which can be used to create flexible license policies (from Appendix A of the Cross Platform Developers Guide in the NetWare SDK):

Assignment Required Field. This field specifies whether or not an assignment (specific user or group) is required to use this license certificate. If this field is TRUE, then the certificate should not grant units until an assignment has been made to the certificate. If it is FALSE, the certificate should be immediately available but may accept assignments.

Consumptive Descriptor. The presence of this descriptor indicates that when license units are requested from this certificate, the count of units should be decremented, and those units should never be available again. This descriptor requires no arguments. Note that both Consumptive and Shareable can't be present at the same time, or an error occurs

Minimum Units to Consume. This descriptor indicates the minimum number of units to consume, no matter what value is specified by the application. If the value specified by the application is greater than this value, this descriptor has no effect. It has one parameter, an LS_ULONG, which indicates the minimum number of units.

Success on LS_LICENSE_TERMINATED. This descriptor tells the licensing system to return success on an LSUpdate even if the license has been reclaimed for some reason. For example, if an application fails to check back in with the licensing system, the licensing system may assume that the power has been shut off to the PC. It reclaims the license units and grants them to someone else. After this has occurred, suppose the application checks back in. This descriptor would enable the licensing system to return success.

Grant on LS_LICENSE_EXPIRED. If this descriptor is present, the licensing system returns LS_SUCCESS if any applications requesting units encounter an LS_LICENSE_EXPIRED error. This only occurs when an installed license that would normally cause the request to be successful has expired.

Publisher Product Version Unique Identifier. This descriptor has one parameter, an LS_ULONG. This parameter indicates the maximum number of days for this grace period. If the value of this parameter is zero, there is no limit to the grace period.

Grant on LS_LICENSE_UNAVAILABLE. If this descriptor is present, the licensing system returns LS_SUCCESS on an LSRequest or an LSUpdate if either of these calls would have generated the error code LS_LICENSE_UNAVAILABLE. Any available units are consumed/utilized.

This descriptor has one parameter, an LS_ULONG. This parameter describes the maximum number of additional units to grant. The licensing system no longer returns LS_SUCCESS if the number of consumed licenses exceeds the number of installed licenses by the specified value. If a value of the parameter is zero, no limitation occurs.

Conclusion

Since NLS logs transactions in a database for further analysis, NLS-enabled administration tools can track events such as Grant on LS_LICENSE_EXPIREDand Grant on LS_LICENSE_UNAVAILABLE. For the developer, creating NLS administration tools using the NLS management functions would be the next logical step to consider when developing to NLS.

* Originally published in Novell AppNotes

Disclaimer

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

© Copyright Micro Focus or one of its affiliates