Pegasus Enhancement Proposal (PEP)

PEP #: 311

Title: WS-Management Support in CIM Server

Status: Draft

Version History:

Abstract: The CIM Server will be enhanced to support WS-Transfer and WS-Enumeration operations (a subset of WS-Management) using existing CIM providers.

Definition of the Problem

Native support for the WS-Management protocol in the Pegasus CIM Server will become increasingly important to protect the value of CIM providers while promoting interoperable manageability.

A WS-Management server was added to the pegasus_unsupported CVS module with PEP 285. That prototype implementation used a separate front-end process to map a subset of WS-Man requests into WBEM requests according to the WS-Management - CIM Binding specification and the WS-CIM Mapping Specification. Responses are similarly mapped from WBEM back to WS-Man.

The PEP 285 implementation has several shortcomings:

• The implementation uses gSOAP, which has licensing implications
• It is a prototype implementation that is not suitable for deployment in its current state
• Running as a separate process significantly affects performance

Relevant Standards

The behavior of the CIM Server in processing WS-Management requests is guided by these standards:

• DMTF DSP0226: Web Services for Management (WS-Management) Specification
• DMTF DSP0227: WS-Management — CIM Binding
• DMTF DSP0230: WS-CIM Mapping Specification

It is not anticipated that all mandatory requirements in these specifications will be met in this phase of the implementation.

Proposed Solution

WS-Management server support is added as an option directly in the CIM Server. When it is enabled, WS-Management requests are accepted and processed using the same connection ports and authentication mechanisms as for CIM-XML. The implementation supports only WS-Transfer and WS-Enumeration operations. Note that no WS-Management client interface or library is proposed. This implementation does not use gSOAP.

DSP0227 indicates that when a CIM namespace is not specified in a selector set, "the default CIM namespace" is intended. The definition of the default CIM namespace is left to the discretion of the implementation. For this implementation, the default CIM namespace is root/cimv2.

WsmServer library

Code for a new libpegwsmserver library containing the WS-Management implementation is added in the pegasus/src/Pegasus/WsmServer directory. None of the symbolic interfaces in this library are intended for external use.

In the following diagram, the components in green are added in the WsmServer library while the components in blue already exist.

The diagram shows that the HTTP connection and authentication logic remains unchanged. When a request is determined to be a WS-Management request (based on the HTTP request URI), it is routed to the WsmRequestDecoder. The WsmRequestDecoder converts the HTTPMessage to a WsmRequest and forwards it to the WsmProcessor. The WsmProcessor converts the WsmRequest to a CIMOperationRequestMessage and forwards it to the CIMOperationRequestDispatcher, which processes it normally. When the response is received by the WsmProcessor, it converts it to a WsmResponse, and the WsmResponseEncoder converts it into an HTTPMessage which is written back to the HTTPConnection.

Support for WS-Enumeration

Since currently there is no CIM support for pulled enumerations, we need to emulate WS-Enumeration operations in the WsmProcessor. A WS-Man Enumerate request translates into either CIM EnumerateInstances or EnumerateInstanceNames request depending on the EnumerationMode. CIMOperationRequestDispatcher aggregates responses from providers into a complete result before sending it to WsmProcessor. The WsmProcessor maintains a hash table of enumeration contexts indexed by a context identifier. A new context is created for every Enumerate request. Enumeration context structure maintains information necessary to process subsequent Pull and Release requests and to handle enumeration context expiration. Pull and Release requests do not have equivalent CIM operations. Responses to these requests are handled by the WsmProcessor. To handle a Pull operation the WsmProcessor locates the enumeration context, extracts the requested number of items from the context and sends the response to the WsmResponseEncoder. On Release it removes the requested context from the table, frees resources allocated for the context and sends the reply to the encoder.

This design can be adapted to use pulled CIM enumeration requests/responses when their support becomes available.

Changes to existing functionality

This enhancement requires only minimal changes to existing functionality:

• The XmlParser is extended to include support for XML namespaces (including unit tests)
• config.mak is updated to recognize the PEGASUS_ENABLE_PROTOCOL_WSMAN build variable
• The HTTPAuthenticatorDelegator forwards request for /wsman and /wsman-anon URIs to the WsmServer (when enabled)
• The CIMServer is updated to initialize the WsmServer (when enabled)
• A TRC_WSMSERVER trace component is defined in Common/TraceComponents.h
• wbemexec is extended to recognize and issue WS-Management requests (when built with PEGASUS_DEBUG defined, wbemexec replaces response MessageID values with 0's to facilitate automated testing of responses)
• The CIM Server wakes up periodically to unload idle providers. Stale WS-Enumeration contexts will also be cleaned up at this time.

Tests

Unit tests are included for the new WS-Management abstractions as well as the XmlParser extensions. In addition, end-to-end server tests of the WS-Management functionality using the wbemexec extensions are added to the automated test suite.

Informal interoperability testing of the WS-Management functionality will be performed with WinRM and the client tools in the pegasus_unsupported prototype.

Build Option

This documentation for the PEGASUS_ENABLE_PROTOCOL_WSMAN build option is proposed for inclusion in PEP 308:

PEGASUS_ENABLE_PROTOCOL_WSMAN

Description: If true, a version of OpenPegasus is built that accepts and processes WS-Management requests. This feature is initially limited to WS-Transfer and WS-Enumeration operations. If false or not set, WS-Management support is not built or included in any way.
Default Value: false
Recommended Value (Development Build): true
Recommended Value (Release Build): false
Required: No
Considerations:  The WS-Management standards are not mature, and interoperability problems may arise. The WS-Management functionality may change in incompatible ways in subsequent releases. Also note the known limitations specified in PEP 311.

Known Limitations

These WS-Management features are not supported:

• wsman:OperationTimeout (not practical to implement in Pegasus)
• wsman:OptionSet (not applicable)
• UTF-16 XML encoding (may be considered in the future)
• Support for WS-Enumeration does not include filtered enumerations.
• EPR selectors in WS-Enumeration requests other than “__cimnamespace” are not allowed.

The implementation also has these properties:

• Responses may only be sent over the same connection on which the request is received. (wsa:ReplyTo and wsa:FaultTo must specify the anonymous address.)
• The CIM mapping assumes that the ResourceURI for all CIM classes is "http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/class_name" even for classes that are not part of the DMTF standard CIM schema.
• The mapping of a CIMObjectPath hostname to an endpoint reference address assumes the protocol is http, the path is /wsman, and no port is specified. For example, the CIMObjectPath hostname "MyHost" is mapped to the endpoint reference address "http:/MyHost/wsman".
• Faults do not contain any s:Detail data other than a FaultDetail element.
• Null values in an array are not supported. This condition causes a wsman:SchemaValidationError fault.
• Client-defined reference parameters in wsa:ReplyTo headers are not supported (see DSP0226 R5.4.2-5).

Future Work

In Pegasus 2.9, only WS-Transfer and some WS-Enumeration operations are implemented. This restriction limits the initial value of the Pegasus WS-Management support. It is recognized that clients will require more complete WS-Management functionality. WS-Management features to be considered for subsequent releases include (in approximate projected priority order):

• WS-Enumeration filter support and support for association operations
• Custom actions (methods)
• wsmid:Identify operation
• Fragment-Level WS-Transfer
• Eventing

No commitment to complete this future work is made at this time.

Alternative Considered

Openwsman is an existing open source project which is implementing the WS-Management specification. It is possible to leverage that project by integrating a portion of its code with Pegasus. By using only a selected portion of the Openwsman project, Pegasus could use its own HTTP stack for WS-Management operations and defer to Openwsman for other protocol interpretation. The Openwsman daemon would not be used, so its runtime configuration would not be relevant. Benefits of this approach include:

• Decrease development time by reusing existing and future functionality
• Gain from broader testing of leveraged functionality
• Decrease maintenance cost by leveraging defect fixes

Factors that motivate a Pegasus native implementation include:

• Openwsman supports only a subset of the platforms supported by Pegasus
• WS-Management protocol support is a core capability for Pegasus, and a Pegasus native implementation provides more flexibility in optimizing its integration
• A dependency on another project for a core capability introduces complications in deployment, licensing, and non-alignment of release cycles
• A Pegasus native implementation is more likely to meet requirements for deployment in an embedded environment

A Pegasus native implementation of the WS-Management protocol is proposed for the reasons above. For some deployments, however, a solution based on Openwsman may indeed be preferable. The option remains available for an interested party to pursue the Openwsman alternative in parallel.

The WS-Management implementation in the pegasus_unsupported CVS module was also considered. However, this implementation is heavily dependent on gSOAP, which is unacceptable from a license perspective. Replacement of the gSOAP layer was determined to be quite expensive, and it is preferable to reuse the communication layer that already exists in Pegasus. Little opportunity for leverage of this implementation was identified.

Discussion

These discussion points were raised during PEP review:

• Bart Whiteley suggests that pluggable protocol adapters should be introduced before WSMan support.

  While pluggable protocol adapters may well be a valuable enhancement, I see that as somewhat orthogonal to this enhancement. The touch points for the WS-Management support are minimal, so it should be straightforward to conform to a pluggable interface when one exists.

• Norm Paxton suggests looking seriously at using/incorporating openwsman libraries. Benefits: using existing, working, tested code base; further enhancements to openwsman, we would get mostly for free; we get openpegasus community plus openwsman community enhancements; less further fragments of community. We've used this approach with openwbem as a proof of concept. Was not difficult to incorporate, and was much faster to get something real working.

  See "Alternative Considered" above.

• Mike Brasher suggests the first step might be to develop a wsman features matrix, derived from all the wsman specifications. Each feature might reference the corresponding specification and line number. The problem with most implementations today is that there is no way to know which features are implemented. I think the features matrix is a good starting point and will help us track the completeness of the implementation in the future.

  I agree with this suggestion. However, given the preliminary nature of some of the specifications, such a matrix will be difficult to maintain. For now, I intend to track unsupported features as known limitations.

• Mike Brasher says: I think we need a client to perform the end-to-end tests. Ideally, we should add a new pass to the tests where the clients connect via wsman. Without a client, we have no testing. The current implementation implements a client with the CIMClient class interface. This makes it possible to run existing tests against the server using wsman.

  While a WS-Management client that is compatible with the existing CIMClient interface would certainly help in developing a rich suite of server tests, the associated effort is significant and is outside the scope of this proposal.

Copyright (c) 2008 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.