Pegasus Enhancement Proposal (PEP)



PEP #: 150

Title: Release Notes Pegasus 2.3.2

Version: 1.5

Created: 23 March 2004

Authors: Warren Grunbok
                Karl Schopmeyer

Status:  draft

Version History:

 

 

 

 

 1.0

23 March 2004

 

Initial Submission

1.1

4 April 2004

 K Schopmeyer

Incorporate comments from  review

 1.2/3

 15 April 2004

 K Schopmeyer

 Incorporate comments from Second review

 1.4

 20 April 2004

 K Schopmeyer

 Incorporate review comments from third Review

 1.5

 28 April 2004

 K. Schopmeyer

 Add  Bug 1400 to bug list.

 

Abstract: This document defines the release notes that support release 2.3.2 of the Pegasus platform.  This release notes document incorporates the Pegasus version 2.3.0 and 2.3.1 release notes plus a delta for 2.3.2.  Comments made to these release notes have also been incorporated.

 

Availability of the Release

This release is available as a source release in both ZIP and TAR formats. The release can be downloaded from the OpenPegsaus Web site at www.openpegasus.org.

In addition, this release is available through Pegasus CVS. The CVS tag for the snapshot representing this release is RELEASE_2_3_2-snapshot_1 and the branch tag representing the current state of version 2_3_2 is RELEASE_2_3_2-branch.  This branch defines the current released version of the Pegasus major release 2.3.  RELEASE_2_3_2-root defines the initial release point where Pegasus 2.3 branched from the trunk..  This snapshot release and any subsequent updates to version 2.3.2 will be announced on the web site and the Pegasus mailing list.  Specific additinal snapshots to this release will be marked in the CVS as RELEASE_2_3_2-snapshot_x, where x is the number of the snapshot and these will correspond to equivalent zip and tar files made available on the web site.

The instructions for acquiring the released code are on the WEB site. Installation instructions are part of the README in the root of the source tree.

The OpenPegasus project is currently not providing binary releases.

There may be additional point releases to the Pegasus 2.3 release and these will be announced on the Pegasus web site. 

Functionality of This Release

The overall level of functionality in the Pegasus environment effective with this release is as follows:

CIM Server

CIM Operations over HTTP support

  1. Class Operations (getClass, deleteClass, modifyClass, enumerateClass, enumerateClassNames) - Operational
  2. Qualifier Operations getQualifier, setQualifier, deleteQualifier) - Operational
  3. Instance Operations (getInstance, deleteInstance, modifyInstance, enumerateInstance, enumerateInstanceNames, getProperty, setProperty) -   Operational
  4. Association Operations (references, referencenames, associators, associatornames) - Operational
  5. Methods- Operational
  6. Query operation (Not Operational)


Indications
Process indications are operational in the Server.  This includes support for subscriptions, filters, and indication handlers, the provider API for indications and the CIMXML indication handler. The Pegasus server can be used as an Indication client.  The Client indication  API support is complete, but the interfaces are marked experimental for version 2.3 because this is the first major release version of Pegasus in which these APIs were available.

Query Language

The query language today is based on WQL and is implemented and used for filters.  However, the executeQuery operation has not been implemented pending the availability of a standard DMTF Query language.

Class Repository

XML based file/directory Class repository. All class and qualifier operations access this repository.

Instance Repository

XML based file/directory Instance repository.  The instance repository is used as the default repository unless a flag is set disabling this repository for client operations.

Security

  1. Basic Security (Note that Digest based security is not implemented)
  2. SSL support - SSL is implemented in Pegasus using the OpenSSL libraries. Pegasus does not provide the OpenSSL libraries but SSL can be used on any platform supported by OpenSSL.  Minimum level known to work is  0.9.6c .   This release of Pegasus was tested with 0.9.6k.  See openssl.org for OpenSSL release information

 Platform Management Functions

  1. Configuration through the defined configuration parameters (cimconfig) and server command line options.
  2. Daemon operation on all supported platforms.

SLP Discovery
SLP support is included but is conditionally compiled with the default to not compile it.  This code can be enabled by setting the compile environment variable PEGASUS_ENABLE_SLP. Note that this release differs from 2.3.1 in that the SLP functions have been completed and tested in an interoperable environment.  Also, the provider for the interop classes (CIM_ObjectManager, CIM_Namespace, etc.) is enabled along with the SLP discovery. If the SLP discovery is not enabled, these interop classes are also not available.

CMPI Provider Manager

Pegasus 2.3.2 includes as a compilable option a new set of code that allows multiple provider managers and also a second provider manager for the CMPI C interfaces. This C interface is the result of a project by the IBM SBLIM team (see  http://www-124.ibm.com/sblim/) and also the working draft of the Open Group specification for these interfaces which is in review now within the WBEMSource Initiative (http://www.wbemsource.org). This provides a standardized C level interface for creating providers that can be registered with the Pegasus CIM Server in the same manner as the current C++ providers.

Today, the CMPI provider manager and interfaces are considered experimental and are subject to change in future versions of Pegasus.

The CMPI provider manager, sample providers and the hooks into Pegasus are all conditionally compiled with the environment variables ENABLE_CMPI_PROVIDER_MANAGER and ENABLE_PROVIDERMANAGER_2. See PEP 144 for details.

Providers

There are a number of standard providers available in the Pegasus release. This includes providers in the following categories:

Internal (control) Providers

  • __Namespace provider - Serves the __Namespace class to allow manipulation of namespaces.
  • Subscription Classes Providers - These provide subscription, filter, and indication handler processing.
  • Provider registration Providers - This provide registration of providers using the PG_Provider classes.
  • ConfigProvider - Manages Pegasus configuraton information.
  • UserAuthProvider - Manages password, etc.
  • ShutdownProvider - Provides support for Pegasus shutdown.
  • Interop Provider - Supports many of the DMTF Interop Schema Classes including CIM_Namespace, CIM_ObjectManager, CIM_CommunicationMechanism, etc.. (Note that this provider is part of the SLP work package so is not compiled as part of the default compile. The environment variable PEGASUS_ENABLE_SLP must be set to enable this option.)

Generic Providers

Generic OperatingSystem provider. See the directory src/Providers/generic.

Test/Sample Providers

See the directories src/Providers/TestProviders and src/Providers/Sample for more information about test and sample providers.

Managed System Providers

ComputerSystem, DNSAdmin, DNSService, Operating System, Process, Processor. For more information on these providers see the documentation for each provider in the directory src/Providers/ManagedSystem

CIMOM Statistics Providers

IBMStatisticalData - This is an early version of the work that became CIM_StatisticalData. It is similar to CIM_StatisticalData and provides the same data but the structure of the Classes is slightly different. This will be standardized to the DMTF definition in a future version of Pegasus.

CIM_Schema
The default CIM_Schema loaded with this release is the DMTF CIM 2.7 Final release.  In addition, Pegasus includes a number of local classes defined for Pegasus.  These are visible in the Schemas directory.   CIM 2.8  schema is also available in the CVS but is not the default schema for compile.
The mechanism to switch to the the 2.8 schema is via environment variable: PEGASUS_CIM_SCHEMA = (See Config.mak).

export PEGASUS_CIM_SCHEMA=CIM28

NOTE: the CIM 2.5 schema is maintained in the CVS repository because it remains the basis for parts of the Pegasus test environment.

Pegasus MOF Compiler

Pegasus implements a MOF compiler that can operate either at the client interface to the Pegasus CIM Server (cimmof) or directly interfacing with a CIM repository (cimmofl).

The direct interface compiler is used primarily to provide an initial class/instance repository. WARNING:  the use of cimmofl to manipulate instances in the repository bypasses any provider that is registered to serve these  instances and simply installs the instances in the instance repository; this may result in 1) bad data in the repository if there are registered providers, 2) corruption of the repository if the CIM Server is running or, 3) MOF data that is loaded but not available until the server is stopped and restarted in some cases.  Use of cimmofl in general is discouraged and particularly  to manipulate instances served by a registered providers (ex. Provider registration). Use of cimmof rather that cimmofl wherever possible.

Client Tools

   Pegasus CIM Server Adminstration

  1. cimuser - Manage Pegasus CIM server Users.
  2. cimconfig - Manage the Pegasus CIM Server configuration parameters.
  3. cimauth - Manage the CIM Server authorization characteristics. Today this is authorizing users to namespaces.
  4. cimprovider - Manage information about the providers .

Information client tools

These tools provide information on the objects managed by the server.

  1. tomof - output Classes and/or instance information in MOF or XML format.
  2. dnsinfo - Generate a set of standard information on the Dmain Name System (DNS) configuration from CIM Classes. Note that the information generated is dependent on the information available from providers and differs from system to system.
  3. ipinfo - Generates a set of standard information from the Network Schema.  Information generated varies by system because of the level of provider support.
  4. osinfo - Generate a set of standard information on the Operating System from CIM Classes. Note that the information generated is dependent on the information available from providers and differs from system to system

Test support Tools

  1. Pegasus Unit tests (available through the "tests" option on the Pegasus make files       
  2. The Pegasus Test Suite (see the tests directory and the Pegasus/TestBuildMakeFile)
  3. TestClient - Basic client for overall platform operation testing.
  4. wbemexec - Test tool that sends/receives XML from XML input.
  5. CLI - Command line interface for Client commands.
  6. Benchmark Test - Introduced with Pegasus 2.3, a benchmark test environment is not provided which includes both a client and provider component. See src/clients/benchmarkTest for more information.

Pegasus Interface APIs

Details of the Pegasus public interfaces for release 2.3 are listed in PEP 96 available from the web site(www.openpegasus.org). This document is the authorative source for the list of publicly supported Pegasus APIs.   The Client and Provider API were originally frozen at the Pegasus version 2.1 release. The interfaces in the release of Pegasus 2.1 are forward compatible to release 2.3 Well-behaved clients and providers compiled to the Pegasus 2.1 or 2.2 interfaces should be compatible with Pegasus 2.3 without compilation.  There have been extensions and new interfaces added for release 2.3 and these are shown as experimental.   The Pegasus public interfaces includes the following major functions

  1. Client APIs
  2. Provider APIs
  3. CIM Object and System function APIs
  4. CIM Listener (experimental for Pegasus 2.3.2)
  5. SLP Client (experimental for Pegasus 2.3.2)

 

The APIs are documented in their respective header files and  in HTML documentation based on the information in the header files extracted with the doc++ tool will be available on the OpenPegasus web site.

WMI Mapper

The WBEM to WMI Mapper provides a way to access WMI data from Windows platform systems. It converts incoming XML/CIM requests to Microsoft WMI requests, executes the requests, converts the results to XML/CIM and returns the results to the client. WMI Mapper receives an HTTP message containing the XML/CIM request. It decodes the XML message and extracts from the HTTP message header the user credentials provided on the connection (username and password). The WMI Mapper authenticates these credentials, verifying if the provided credentials have access to the desired WMI data. This is done because the WMI Mapper runs as a service, logged on using an account with administrative rights (which has all access to WMI data). Because of this, the WMI Mapper impersonates the user credentials provided on the HTTP message to ensure that the calling user has rights to browse WMI data. Hence, ALL requests made to the WMI Mapper MUST contain user credentials.

Supported Platforms

Each Pegasus release lists as supported platforms those hardware/software platforms that have recognized ports for the Pegasus code base including a maintainer for the platform that will be willing to regularly assure that the port is maintained as the Pegasus code base is changed.  Pegasus may be operable on other platforms (ex. Windows 98) but without a group to provide the role of test and maintenance, the Pegasus project cannot assure operation. The supported platforms for Pegasus release 2.3.2 are:

Platform and OS

Compilers

AIX 5.2

VisualAge C++ Version 5.0.2.3

HP-UX

HP aC++ B3910B

PowerLinux

gcc

zLinux

gcc

Linux Itanium

gcc

Linux IA-32

gcc (versions 2.9x and 3.xx)

Windows 2000

Microsoft Visual C++ Ver 6 and Microsoft .Net compiler Version.   Works on VC .NET 2003 (aka v7.1)

Windows XP

Microsoft Visual C++ Ver. 6 and Microsoft .Net compiler Version 7.1


Further information regarding Pegasus support on IBM platforms can be found at: http://publib.boulder.ibm.com/eserver/v1r1/en_US/index.html.
Further information regarding Pegasus support on HP platforms can be found at: http://www.hp.com/large/infrastructure/management/wbem/.

 

Conformance with DMTF Specifications

Pegasus tries to conform to the CIM specifications.  It is a major goal of the OpenPegasus project to both drive and utilize the DMTF CIM/WBEM specifications.  However, today there are a number of known differences.  As of Pegasus 2.3.2, some of the differences include the following:

1. Provider Registration - Pegasus supports registration through a set of Provider registration classes and does not support the DMTF defined Provider Qualifier. See the readme for more information on provider registration.

2. Indications. Today Pegasus supports process indications but does not include any specific support for lifecycle indications.

3. Interop Schema implementation differences. Today Pegasus provides alternatives to some of the classes in the Interop Schema including CIM_StatisticalData. Note that the CIM_ObjectManager and other similar classes are only compiled with the SLP option.

4. Today Pegasus does not support the execQuery pending the availability of a standard for the query language.  Pegasus is expected to support execQuery in a future release with the new CQL query language and possibly WQL.

5. Instance qualifiers and class qualifiers on some Operations - The DMTF specifications are unclear regarding the inclusion of qualifiers on CIM instances.  Some CIM Client implementations expect instances returned from the CIM Server to include the qualifiers defined in the class definition (such as KEY qualifiers on properties).  Pegasus is based on the interpretation that class-defined qualifiers are not included in instances, so incompatibilities may exist with clients that rely on these qualifiers.

 

6. HTTP Chunking – Today the Pegasus implementation defines itself as supporting HTTP 1.1 but does NOT support chunking. This is a high priority for a future version.

 

7. CIM MOF compiler functions for instance aliasing - The Pegasus compiler does not today support thi functions.  This function is planned for a future version.

 

8. MultiRequest Oprations - Pegasus does not support the DMTF defined MultiRequest Operation option.

 

9. LocalOnly option on some instance Operations - Because of incompatible changes made between CIM Operation specification versions, the DMTF has determined that there is confusion in the use of the LocalOnly parameter on instance operations and the results it will return.  The definition changed between version 1.0 and version 1.1 of the CIM Operations over HTTP Specification  so that the information provided to the requestor may be different between a CIM Operations version 1.0 specification implementation and a version 1.1 implementation.  Therefore, the Pegasus community discourages the use of this parameter on any operations. NOTE: We recommend that client users always set localOnly to False (remember that the default is true) on instance operations to avoid the confusion of different information from different CIM Server implementations.

NOTE: This problem does not apply to the class operations such as getClass, etc.

Changes in Release 2.3

The development and release of each version of Pegasus is defined and controlled through Pegasus PEP documents.  PEP 57 is the controlling document this release and lists the original set of changes proposed and the status of each of those changes. Note that not all of the originally defined functionality was completed for this release.

In general, the changes implemented for this release were:

  1. Introduction of platform globalization.

  2. Introduction of a listener API.

  3. Introduction of SLP (still experimental and by default not compiled in the 2.3.2 release).

  4. Introduction of a new pluggable Provider Manager (still experimental and by default not compiled in the 2.3.2 release).

  5. Introduction of extensive changes to the HTTP monitor (still experimental and not compiled in the 2.3.2 release).

  6. Inclusion of Pluggable CMPI provider manager.  Note: This makes use of the PPM item described below.  This is an optional compile.


Note that there were a number of objectives that were not completely achieved including:

  1. SLP integration - This code is in place but is compiled only with a conditional compile flag. This code can be enabled by setting the environment variable PEGASUS_SLP_ENABLE and recompiling Pegasus.
  2. Pluggable provider manager - This was a major objective but because the code changes were extensive and released very late in the development cycle of 2.3, both the old and the new provider managers are maintained in the release AND the old provider manager is defined as the default compile.  To compile and run with the new pluggable provider manager functions the user must set a compile flag (TBD).  NOTE: It is the intention of the Pegasus project to move to the new provider manager as soon as possible.
  3. HTTP Monitor enhancements - As with the Pluggable Provider Manager, it was the intention to incorporate a number of enhancements to the HTTP monitor.  Again because the time in the development phase when they were submitted, the project team elected to release 2.3.2 with the existing monitor as the default compile but with the code for both monitors. It is the intention to move to the new monitor as soon as possible and users are free to work with either implementation.  To compile and run with the new monitor use the flag PEGASUS_MONITOR2.
  4. CMPI Pluggable Provider Mgr - The CMPI Provider manager was added as a PEP to release 2.3.2 and uses the same flag as the Pluggable provider manager to control its compilation. Without setting this flag before the build process this provider manager and its sample providers are NOT compiled. 

The set of PEPs defined for release 2.3 is below along with the final implementation status. Note that release 2.3.2 introduced no new PEPs beyond what was in release 2.3.0. All of these PEPS are available on the OpenPegasus web site.

PEP #

PEP Description

Status

56

Unicode Support in Infrastructure

 

58

Unicode Support in Infrastructure


68

Provider Manager Interface - Multiple provider support

Implemented - but requires compile flag to integrate.

84

Provider Manager Interface, Pluggable provider manager configuration

Implemented - see above.

86

Provider Manager Interface, pluggable provider manager.

Implemented - see above.

60

Secure connections between CIM Listener and CIM server

Implemented

62

SNMP Mapper Indication Handler

Implemented

67

Indication Consumer registration

 

76

CIM Listener Client API, Libraries, SDK

Implemented - Experimental

75

Indication Subscription Performance Enhancements

Implemented

30

SLP support

Implemented - Optional compile

52

Interop Schema provider support

Implemented - Optional compile

88

Polling design socket change.

 

64

Java implementation of CIM Client and Listener Interface

Included in Pegasus based SNIA OpenCimom Java Classes.

65

Benchmark test utility

Implemented

74

SSL certificate verification callback enhancement

Implemented

73

Support CIM Schema 2.8 preliminary

 

79

WMI Mapper - local connection enhancements

 

77

Default instance provider

Implemented

85

Configuration Property Table Enhancement

Implemented

90

Add IO trace diagnostics to CIMClient

Implemented

89

SLP Client Integration

Implemented but not compiled by default

99

Restructure of CIMRequest Message

Implemented but not compiled by default

102

 CMPI Pluggable Provider

Implemented but not compiled by default

PEGASUS Bugs

The current bug list for Pegasus is openly available on the OpenPegasus web site.  As of the release of 2.3.2 release date, the following list represents what the Pegasus community feels are a subset of  open bugs with OpenPegasus 2.3.2 that may be of particular interest to users. Please see the bug reports (the number is a link to the report) to determine if there are any workarounds, patches, etc. for particular bugs.

 

ID

Sev

Pri

Plt

Summary

14

nor

P2

All

MOF Compiler does not support aliasing

377

enh

P2

PC

Multireq not supported

424

nor

P2

All

XMLParser removes whitespace

482

maj

P2

PC

Absence of REFERENCECLASSNAME in XML causes error

544

maj

P2

All

MOF compiler does not convert escape characters

786

nor

P2

PC

CIMRepository enumerateinstances deepInheritance, etc. procesing

1054

nor

P2

PC

cimserver stop responding after stress query of repository

1179

nor

P2

All

Sample providers should not be declared in Pegasus namespace

1195

maj

P2

All

ResponseHandler should clone CIM* objects before modifying them

1285

nor

P2

PC

EnumerateInstanceNames generates namespace error CIMException

 

1307

maj

P2

All

Functionality on errors with Enumerate Functions. Should we generate error or send existing data. Today we pass data.

1330

nor

P2

PC

MOF compiler does not handle "/* ... */" comments.
1400 maj P1 All Disabling https prevents indication delivery through http.


 

List of Bugs Corrected in Pegasus 2.3
 

The current bug list for Pegasus is openly available on the OpenPegasus web site bug database.  This site defines the mechanism so that the user can list the bugs that have been fixed between the release of Pegasus 2.2 and the current release.
 

Documentation

The following documentation is available for the this Pegasus release:

  • Pegasus Build and Installation - Readme in the Pegasus Root Directory
  • Pegasus Operation - Readme in the Pegasus Root Directory
  • APIs - See the header files and the HTML  API documentation that is on the web site.
  • Utilities - A combination of help generally available with the -h option for each command and HTML documentation for most of the tools.
  • API usage documentation - The best API usage documentation is the existing utilities and test programs and the examples in the API documentation.  In particular the Common/tests unit tests contain extensive examples of the use of the Common APIs.
  • Building and Debugging Providers - Readme in the Pegasus Root Directory, API documentation, and documentation from the Pegasus Technical Workshop which is available on the Pegasus web site.
  • Building and Debugging Clients - API documentation and the documentation on the Pegasus Technical Workshop which is available on the Pegasus web site.

 

Copyright (c) 2003 BMC Software; Hewlett-Packard Development Company, L.P.; IBM Corp.; 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.