Pegasus Enhancement Proposal (PEP)
PEP #: 311
Title: WS-Management Support in CIM Server
Status: Approved
Version History:
Version | Date | Author | Change Description |
---|---|---|---|
1.0 | 25 January 2008 | Roger Kumpf | Initial submittal/placeholder |
1.1 | 7 April 2008 | Roger Kumpf | For general review |
1.2 | 14 April 2008 | Roger Kumpf | Updated based on architecture team review comments and discussion. Added "Future Work" and "Alternative Considered" sections. |
1.3 | 15 April 2008 | Roger Kumpf | Updated based on architecture team review comments and
discussion. Specifically, put "Future Work" items in approximate
priority order, emphasized that WS-Management requests use the same
connection ports and authentication mechanisms as CIM-XML, and
annotated the known limitations. Approved version (Ballot 146). |
1.4 | 30 May 2008 | Roger Kumpf | Updated based on implementation experience. Approved version (Ballot 151). |
2.0 | 8 September 2008 | Dmitry Mikulin, Roger Kumpf | Add support for WS-Enumeration. |
2.1 | 1 October 2008 | Roger Kumpf | Clarifications based on architecture team discussion. Removed
the EnumerateObjectAndEPR enumeration mode limitation. Approved version (Ballot 157). |
2.2 | 1 November 2009 | Mike Brasher | Add support for (1) enumeration filters, (2) identify, (3) and custom actions (see section entitled "Phase 2 Enhancements"). Version 2.2 Approved by Architecture Team in Ballot Nov 2009 for inclusion in Pegasus 2.10. |
Abstract: The CIM Server will be enhanced to support WS-Transfer and WS-Enumeration operations (a subset of WS-Management) using existing CIM providers.
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 behavior of the CIM Server in processing WS-Management requests is guided by these standards:
It is not anticipated that all mandatory requirements in these specifications will be met in this phase of the implementation.
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.
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.
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.
This enhancement requires only minimal changes to existing functionality:
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.
This documentation for the PEGASUS_ENABLE_PROTOCOL_WSMAN build option is proposed for inclusion in PEP 308:
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.
These WS-Management features are not supported:
The implementation also has these properties:
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):
No commitment to complete this future work is made at this time.
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:
Factors that motivate a Pegasus native implementation include:
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.
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.