PEP

Document title: PEP#267 - external SLP SA support for Pegasus 2.6 Document details Comments Help with document reviews

Pegasus Enhancement Proposal (PEP)

PEP #: 267

PEP Type: Functional

Title: External SLP SA support for Pegasus.

Version: 1.5

Created: 22 May 2006

Authors: Muni S Reddy

Status: Approved

Version History:

Version	Date	Author	Change Description
1.0	22 May 2006	Muni S Reddy	Initial Submission
1.1	15 Sept 2006	Muni S Reddy	Added a section Configuration Properties and Added list of file/modules added and modified.
1.2	28 Sept 2006	Muni S Reddy	1. Removed configuration variable pegasus_use_ibmslpsa and references to IBM SLP SA. 2. Added a compile time switch PEGASUS_SLP_REG_TIMEOUT to Configuration Properties section. 3. Added a new problem ( Problem # 2) for re-registration with external SLP SA under abstract. 4. Added skeletal code which starts a new thread to advertisement and for reregistration. 5. Removed Makefile and ConfigManager.cpp files for the 'source files to be changed' section. 6. Removed pegcommon and pegconfig form the 'modules changed' section. 7. Changed the ibmslpsa_testcase to externalslpsa_testcases under 'New Modules added' section.
1.3	03 Oct 2006	Muni S Reddy	1. Added a table to describe the slp Compile time switches. 2. Changed the solution for problem 1 and 2 to Pseudo code. 3. Added to headings, for How to build and verify built-in SA and External SA.
1.4	05 Oct 2006	Muni S Reddy	1. Changed section name 'Configuration Properties' to "New Environment Variable to build OpenPegasus" 2. Moved New Case 3 & New Case 4 to proposed solution.
1.5	13 Oct 2006	Muni S Reddy	1. Added a check to see if slpd is already running in case 2 and New case 4. 2. Changed reregistration time from second to minutes. 3. Added definition of reregistration under proposed solution section. 4. Changed new case 4 from a error case to a valid case. 5. Modified the table explaining the relation between different environment variables.

Abstract: The Pegasus CIM Server has a built in SLP SA implementation. This SA has the limitation of not being able to register when there is already an external SLP SA agent running on the system. The purpose of this PEP is address:

Problem #1. To enable Pegasus registration with External SLP SA instead of using its own built-in SA.
Problem #2. Re-register Pegasus with external SLP SA based on a PEGASUS_SLP_REG_TIMEOUT compile time switch.
Problem #3. Add testcases to test the SLP functionality external SLP SA and the functions added through SLP implementation.

What is SLP?

SLP (Service Location Protocol) is an Internet Engineering Task Force (IETF) standard used for simplifying discovery and use of network resources. Traditionally, in order to locate services on the network, users of network applications have been required to supply the hostname or network address of the machine that provides the desired service. With SLP the user only needs to know the description of the service he is interested in. Based on this description, SLP can return information on the service. There are three agents in SLP that together perform the discovery tasks. In SLP an agent is a software entity that processes SLP protocol messages. The three types of SLP agents are: User Agent (UA), Directory Agent (DA) and Service Agent (SA).

UA: Is the application that queries for services registered with a SA on behalf of client and also accepts responses.

SA: The SLP Service Agent is a software entity that advertises the location of one or more services.

DA : The SLP Directory Agent is a software entity that acts as a centralized repository for service location information received from SAs and other possible sources.

Definition of the Problem

Pegasus is unable to re-register (i.e. update an existing registration with a new 'lifetime") with an external SLP SA running in the system. The objective of this document is to propose design changes in the Pegasus CIM Server to advertise itself with an external SLP SA agent running in the system when it is started, and then re-register the CIM Server with the external SLP SA after PEGASUS_SLP_REG_TIMEOUT minutes (i.e. new compile time switch introduced). This PEP also proposes adding new testcases for register, re-register (or update), and unregister with external SLP SA.

Current Implementation

Pegasus has support for both system installed Open SLP SA and built-in SLP SA. Pegasus can register with built-in SLP SA only when Pegasus is built with PEGASUS_ENABLE_SLP. The built-in SA is supported as a Provider in Pegasus. This provider gets registered when the cimserver is started. startSLPProvider is used to register the provider. SLP provider is available as a part of cimserver.

Pegasus can register with Open SLP SA , when built with PEGASUS_ENABLE_SLP and PEGASUS_USE_OPENSLP compile time switches. Open SLP SA registration also use startSLPProvider and some SLP APIs (SLPOpen, SLPClose, ..) for registration.

How to build and verify registration with existing SLP SA :

Build steps for built-in SLP SA and OPEN SLP SA are also explained in src/config.mak file.

Case 1: Built-in SLP SA: Follow the below steps to register CIM Server with Pegasus Built-in SLP SA.

            1. Build Pegasus with PEGASUS_ENABLE_SLP set to 'true', PEGASUS_USE_OPENSLP set to 'false' and PEGASUS_SLP_REG_TIMEOUT is not defined.
            2. Start cimserver.
            3. To check the registration 'slp_query --type=service:wbem'. ( slp_query is a program available in Pegasus when built with PEGASUS_ENABLE_SLP)
            4. Step 3 should display all the registrations made with built-in SLP SA. If no results are returned, that mean registration failed.

Case 2: Open SLP SA:

            1. Build Pegasus with PEGASUS_ENABLE_SLP , PEGASUS_USE_OPENSLP set to 'true' and PEGASUS_SLP_REG_TIMEOUT is not defined.
            2. Start slpd if slpd is not already running. This starts Open SLP SA. Assuming that Open SLP SA is already installed.
            3. Start cimserver.
            4. To check the registrations 'slptool findsrvs service:wbem'
            5. Step 4 should display all the registrations made with Open SLP SA. If no results are returned, that mean registration failed.

Proposed Solution:

Typically applications that provide services, need to register information regarding the services they provide with SLP Directory Agents. The CIM Server will need to register for discovery with the SA regarding its services, which can be queried by a UA.
When CIM Server is started, external SLP SA registration advertisement is started in its own thread. This thread advertises Pegasus to a listening external SLP DA.

Re-registration:

There is no direct way of reregistration either in Open SLP SA or External SLP SA ( i.e. IBM SLP SA). Reregistration means, a fresh registration with the same attributes used for the first time registration (i.e. the same code gets executed for both reregistration and first time registration).

New Environment Variable for building OpenPegasus:

PEGASUS_SLP_REG_TIMEOUT: Reregistration time in minutes.

Description: Every SLP mandates re-registration after some amount of time. This is specified with the new compile time switch PEGASUS_SLP_REG_TIMEOUT. Table given below explains the new compile time switch's behavior with existing SLP environment variables (PEGASUS_ENABLE_SLP, PEGASUS_USE_OPENSLP)

PEGASUS_SLP_REG_TIMEOUT option can be either undefined or assigned with a non-zero positive integer. This positive integer specifies the reregistration time in minutes.

1. PEGASUS_SLP_REG_TIMEOUT is undefined: In this case no re-registration is needed, meaning either built-in SLP SA is used or Open SLP SA is used.
2. PEGASUS_SLP_REG_TIMEOUT is set to a positive integer 'n': In this case CIM Server should start a reregistration thread after 'n' minutes.

Default Value: undefined
Recommended Default Value (Development Build): undefined
Recommended Default Value (Release Build): undefined
Example: export PEGASUS_SLP_REG_TIME=10

PEGASUS_ENABLE_SLP	PEGASUS_USE_OPENSLP	PEGASUS_SLP_REG_TIMEOUT	Remark
false	false	false/not defined	SLP is disabled. No SLP code gets compiled.
false	false	true/'n' positive integer	SLP is disabled. No SLP code gets compiled.
false	true	false/not defined	SLP is disabled. No SLP code gets compiled.
false	true	true/'n' positive integer	SLP is disabled. No SLP code gets compiled.
true	false	false/not defined	SLP is enabled, built-in SA is used as in case 1
true	false	true/'n' positive integer	SLP is enabled, External SLP SA is used as in case 3.
true	true	false/not defined	SLP is enabled, Open SLP SA is used as in case 2.
true	true	true/'n' positive integer	SLP is enabled, Open SLP is used with reregistration time as PEGASUS_SLP_REG_TIMEOUT minutes.

The existing "slp" configuration variable continues to work as is for all SLP variations (i.e. built-in SA, Open SLP SA and external SLP SA) in Pegasus. That is, when "slp" is set to true, OpenPegasus activates or registers with an SLP SA, based on the environment variables defined above. When "slp" is set to false, no activation or registration occurs.

How to build and verify registration with external SLP SA:

Explained below are the two ways we can build Pegasus with the new compile time switch PEGASUS_SLP_REG_TIMEOUT defined.

New Case 3: external SLP SA: This is the new feature to be added in this PEP.
            1. Build Pegasus with PEGASUS_ENABLE_SLP set to 'true', PEGASUS_USE_OPENSLP set 'false' and PEGASUS_SLP_REG_TIMEOUT defined.
            2. Start cimserver.
            3. To check the registration 'slp_query --type=service:wbem'
            4. Step 3 should display all the registrations made with built-in SLP SA. If no results are returned, that means registration failed.

New Case 4: Open SLP with Reregistration : This is a new case introduced in this PEP. The additional thing in this case compared to case 2 is , we have reregistration option here.
            1. Build Pegasus with PEGASUS_ENABLE_SLP and PEGASUS_USE_OPENSLP set to 'true' and PEGASUS_SLP_REG_TIMEOUT defined.
            2. Start slpd if slpd is not already running. This starts Open SLP SA. Assuming that Open SLP SA is already installed.
            3. Start cimserver.
            4. To check the registrations 'slptool findsrvs service:wbem'
            5. Step 4 should display all the registrations made with Open SLP SA. If no results are returned, that mean registration failed.

Solution to Problem #1. A new thread will be started from startSLPProvider(), which is responsible for:

1. invoking built-in SLP provider to advertise CIM Server with either built-in SLP SA or Open SLP SA.
2. Advertise CIM Server with external SLP SA.

Pseudo code

void CIMServer::startSLPProvider()
{

// This routine gets executed only when PEGASUS_ENABLE_SLP is defined.
....................................................

1. if PEGASUS_SLP_REG_TIMEOUT is defined and PEGASUS_USE_OPENSLP is not defined, then use External SLP

2. if PEGASUS_SLP_REG_TIMEOUT is defined and PEGASUS_USE_OPENSLP is defined the use Open SLP SA.

3. if PEGASUS_SLP_REG_TIMEOUT is not defined , then start the thread which invokes built-in SLP provider. Also this thread registers CIM Server with either
built in SLP SA or Open SLP SA. In this case PEGASUS_USE_OPENSLP is not checked because CIM Server advertise to built-in SA or Open SLP SA with same code, expect for few APIs are different. There will not be any reregistration in this case.

}

Solution to Problem #2:

Re-Registration with External SLP SA: In the CIMServer::runForever() PEGASUS_SLP_REG_TIMEOUT is tested for a non-Zero value. This test is to make sure that we are performing re-registration only when it is required. The interval of this reregistration invocation is defined with this compile time switch. The registration is performed with a new thread. This thread registers the CIM Server with new time and terminates.
This logic is same as that of calling unloadIdleProviders() from runForever(). unloadIdleProviders() gets called after a fixed interval, but re-Register with external SLA SA would be called based on the value set to PEGASUS_SLP_REG_TIMEOUT.

void CIMServer::runForever()
{
.........................................................................

if PEGASUS_ENABLE_SLP is defined and PEGASUS_SLP_REG_TIMEOUT is greater than ZERO then

check if the time lapsed between last registration and now is greater than PEGASUS_SLP_REG_TIMEOUT or nor.

if yes, then start a thread, which registers CIM Server with external SLP SA.

------------Rest of the routine with the existing code -----------------------
}

Solution to Problem #3.

Testcases to test the functions of SLP ( register/unregister/modify registration) and also testcase for the function implemented in src/slp_client/src/cmd-utils/slp_client/slp_client.cpp.

Testcase1 :

To check the existing registrations external SLP SA. To implement this testcase:

1. Create a slp client.

2. Fabricate data for query

3. Query the external SLP SA using get_response().

                                     4. Check the response for non NULL string.

                                     5. destroy the client.

Testcase2 :

To check if we can unregister an existing registration with external SLP SA. To implement this testcase:

1. Create a slp client.

2. Fabricate data for query

3. Query the external SLP SA using get_response().

4. Fabricate registration data based on the response int eh step 3.

5. unregister with external SLP SA using srv_reg_local() with lifetime as ZERO. This call would return zero if the unregistration is unsuccessful.

6. destroy the client.

Testcase3:

To Check for NO registrations:

1. Create a slp client

2. Query the external SLP SA using get_response().

3. Unregister all the registered service returned in step 2 using srv_reg_local() with lifetime as ZERO. Check for the success of srv_reg_local() for each unregister.

4. Query the external SLP SA using get_response(). Test for no responses.

5. destroy the client.

Testcase4:

To Check if the registration is correct or not.

                                     1.Create an slp client.

                                     2. Fabricate data for service registration.

3. Register the service using srv-reg_local()

4. Query the external SLP SA using get_response().

                                     5. Compare the response returned by above call with the data used for registration.

                                     6. Destroy the client.

Testcase5:
To Check more than one registration is correct or not

1. Step 1, 2 and 3 are same as Testcase 4

                                     2. Repeat step 2 and 3 of testcase 4 with a different data.

                                     3. Query the external SLP SA using get_response().

4. Compare the response for both the number of registrations returned and the contents of the responses returned.

5. Destroy the client.

Testcase6:

To Check if the Unregister is proper.

1. Unregister a non existing registration using srv_reg_local() with lifetime ZERO.

2. Check for the failure of unregister call in step 1.

3. Destroy the client

Testcase7:

To Check if the duplicate registration is accepted.

1. Create a slp client.

2. Fabricate the data for slp registration.

3. Register with external SLP SA using srv_reg_local().

4. Repeat step 3 with same data.

                                      5. check the response of the step 4.

                                    6. Destroy the client.

Testcase8:

To display the attributes of a registration .

1. Create a slp client

2. Query for attributes using attr_req()

3. Check for the all the attributes returned and print them.

4. Destroy the client

Testcase9:
To Check for the modify registrations.

1. Create a slp client.

2. Fabricate data for query

3. Query the external SLP SA using get_response().

4. Modify the data returned from step 3.

5. Register the modified data using srv_reg_local()

6. repeat step 3 and check if the response is correct.

7. Destroy the client.

source files to be changed:
                                     1. src/Pegasus/Server/CIMServer.cpp
                                     2. src/Pegasus/Server/Makefile           // SLPAttrib.cpp will be added to the source files list

Modules Changed:

1. cimserver

New files to be added:

                                     1. src/Pegasus/Server/SLPAtrrib.h
                                     2. src/Pegasus/Server/SLPAtrrib.cpp           // SLPAttrib class is used to frame data for cimserver advertisement.
                                     3. src/slp/slp_client/src/cmd-utils/tests/slpTestcases.cpp
                                     4. src/slp/slp_client/src/cmd-utils/tests/Makefile

New Modules added:

1. externalslpsa_testcase

Rationale

To be able to register with the external SLP SA. To cover all the code that is implemented as part of SLP.

Schedule

Action	Planned	Actual	Comment
PEP Submitted	09/15/2006	09/15/2006
PEP Reviewed	09/19/2006	09/22/2006
PEP Approved	09/22/2006	10/18/2006
Code Committed	09/29/2006	11/29/2006	Post-FC Exception by Steering Committee

Discussion

Copyright (c) 2006 Hewlett-Packard Development Company, L.P.; IBM Corp.;
EMC Corporation; Symantec Corporation; The Open Group.

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to
deal in the Software without restriction, including without limitation the
rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
sell copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

THE ABOVE COPYRIGHT NOTICE AND THIS PERMISSION NOTICE SHALL BE INCLUDED IN
ALL COPIES OR SUBSTANTIAL PORTIONS OF THE SOFTWARE. THE SOFTWARE IS PROVIDED
"AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Template last modified: March 26th 2006 by Martin Kirk
Template version: 1.11