Web Services for Management (WS-Management) October 2004 Authors Akhil Arora, Sun Alan Geller, Microsoft (editor) Jackson He, Intel Chris Kaler, Microsoft Ray McCollum, Microsoft Milan Milenkovic, Intel Paul Montgomery, AMD Junaid Saiyed, Sun Enoch Suen, Dell Copyright Notice (c) 2004 Advanced Micro Devices, Inc., Dell, Inc., Intel Corporation, Microsoft Corporation, and Sun Microsystems, Inc. All rights reserved. Permission to copy and display WS-Management, which includes its associated WSDL and Schema files and any other associated metadata (the "Specification"), in any medium without fee or royalty is hereby granted, provided that you include the following on ALL copies of the Specification that you make: 1. A link or URL to the Specification at one of the Co-Developers’ websites. 2. The copyright notice as shown in the Specification. Microsoft, Intel, AMD, Dell, and Sun (collectively, the "Co-Developers") each agree upon request to grant you a license, provided you agree to be bound by such license, under royalty-free and otherwise reasonable, non-discriminatory terms and conditions to their respective patent claims that would necessarily be infringed by an implementation of the Specification and solely to the extent necessary to comply with the Specification. THE SPECIFICATION IS PROVIDED "AS IS," AND THE CO-DEVELOPERS MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, OR TITLE; THAT THE CONTENTS OF THE SPECIFICATION ARE SUITABLE FOR ANY PURPOSE; NOR THAT THE IMPLEMENTATION OF SUCH CONTENTS WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS. THE CO-DEVELOPERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF OR RELATING TO ANY USE OR DISTRIBUTION OF THE SPECIFICATIONS. The name and trademarks of the Co-Developers may NOT be used in any manner, including advertising or publicity pertaining to the Specifications or their contents without specific, written prior permission. Title to copyright in the Specifications will at all times remain with the Co-Developers. No other rights are granted by implication, estoppel or otherwise. Abstract This specification describes a general SOAP-based protocol for managing systems such as PCs, servers, devices, Web services and other applications, and other manageable entities. Status Published specification. Table of Contents 1. Introduction 1.1 Requirements 2. Notations and Terminology 2.1 Notational Conventions 2.2 XML Namespaces 2.3 Terminology 2.4 Compliance 3. Addressing 4. General Messaging 4.1 Operation time out 4.2 Locale 4.3 Data freshness 5. Resource Access 5.1 WS-Transfer 5.2 WS-Enumeration 6. Eventing 6.1 General 6.1.1 Subscription managers and identifiers 6.1.2 Expiration 6.1.3 Event message format 6.2 Batched delivery mode 6.3 Pull delivery mode 6.4 Trap delivery mode 6.5 Resumable subscriptions 7. Security Considerations 7.1 Message security 7.1.1 Confidentiality 7.1.2 Integrity 7.1.3 Authentication 7.1.4 Authorization 7.2 Event Delivery Security 8. Acknowledgements 9. References Appendix I. Profile Appendix I.1 URI Appendix I.2 UDP Appendix I.3 HTTP/HTTPS Appendix I.4 XML Encoding Appendix I.5 SOAP Envelope Appendix I.6 Attachments Appendix I.7 WS-Addressing Appendix II: Faults Appendix III: XSD 1. Introduction The Web services architecture is based on a suite of specifications that define rich functions and that may be composed to meet varied service requirements. A crucial application for these services is in the area of systems management. To promote interoperability between management applications and managed resources, this specification identifies a core set of Web service specifications and usage requirements to expose a common set of operations that are central to all systems management. This comprises the abilities to • DISCOVER the presence of management resources and navigate between them. • GET, PUT, CREATE, and DELETE individual management resources, such as settings and dynamic values. • ENUMERATE the contents of containers and collections, such as large tables and logs. • SUBSCRIBE to events emitted by managed resources. • EXECUTE specific management methods with strongly typed input and output parameters. In each of these areas of scope, this specification defines minimal implementation requirements for compliant Web service implementations. An implementation is free to extend beyond this set of operations, and may also choose not to support one or more areas of functionality listed above if that functionality is not appropriate to the target device or system. 1.1 Requirements This specification intends to meet the following requirements: • Constrain Web services protocols and formats so Web services can be implemented in management agents with a small footprint, in both hardware and software. • Define minimum requirements for compliance without constraining richer implementations. • Ensure composability with other Web services specifications, such as WS- ReliableMessaging and WS-AtomicTransactions. • Minimize additional mechanism beyond the current Web service architecture. 2. Notations and Terminology This section specifies the notations, namespaces, and terminology used in this specification. 2.1 Notational Conventions The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [RFC 2119]. This specification uses the following syntax to define normative outlines for messages: • The syntax appears as an XML instance, but values in italics indicate data types instead of values. • Characters are appended to elements and attributes to indicate cardinality: • "?" (0 or 1) • "*" (0 or more) • "+" (1 or more) • The character "|" is used to indicate a choice between alternatives. • The characters "[" and "]" are used to indicate that contained items are to be treated as a group with respect to cardinality or choice. • An ellipsis (i.e. "...") indicates a point of extensibility that allows other child or attribute content. Additional children and/or attributes MAY be added at the indicated extension points but MUST NOT contradict the semantics of the parent and/or owner, respectively. If a receiver does not recognize an extension, the receiver SHOULD NOT process the message and MAY fault. • XML namespace prefixes (see Table 1) are used to indicate the namespace of the element being defined. 2.2 XML Namespaces The XML namespace URI that MUST be used by implementations of this specification is: http://schemas.xmlsoap.org/ws/2004/10/management Table 1 lists XML namespaces that are used in this specification. The choice of any namespace prefix is arbitrary and not semantically significant. Table 1: Prefixes and XML namespaces used in this specification. Prefix XML Namespace Specification(s) wsman http://schemas.xmlsoap.org/ws/2004/10/management This specification s http://www.w3.org/2003/05/soap-envelope SOAP 1.2 [SOAP 1.2] xs http://www.w3.org/2001/XMLSchema XML Schema [Part 1, 2] wsdl http://schemas.xmlsoap.org/wsdl WSDL/1.1 [WSDL 1.1] mex http://schemas.xmlsoap.org/ws/2004/09/mex WS-MetadataExchange [WS-MetadataExchange] wsa http://schemas.xmlsoap.org/ws/2004/08/addressing WS-Addressing [WS- Addressing] wse http://schemas.xmlsoap.org/ws/2004/08/eventing WS-Eventing [WS- Eventing] wsen http://schemas.xmlsoap.org/ws/2004/09/enumeration WS-Enumeration [WS- Enumeration] wxf http://schemas.xmlsoap.org/ws/2004/09/transfer WS-Transfer [WS- Transfer] 2.3 Terminology Agent An application that provides management services for a System by exposing a set of Resource Services. The Agent provides management operations within its local scope. Manager A Web service that is used to manage one or more Systems by sending messages to and/or receiving messages from an Agent for that System. Resource Instance A single manageable item, such as a disk drive or a running process. Also called a Resource or an Instance. Resource Service A Web service that provides access to a single category of manageable items, such as disk drives or running processes, that share the same operations and representation schema. System A top-level managed entity composed of one or more Resource Instances. For instance, a PC is a System that contains Resources such as disk drives and running processes. 2.4 Compliance An implementation is not compliant with this specification if it fails to satisfy one or more of the MUST or REQUIRED level requirements defined herein. A SOAP Node MUST NOT use the XML namespace identifier for this specification (listed in Section 2.2) within SOAP Envelopes unless it is compliant with this specification. 3. Addressing WS-Management Resources are identified by the following information: • The transport address (URL) of the Agent that provides the Resource Services. • The unique identifier (URI) of the System that the Resource is part of. If the System is uniquely identified by the Agent address, this component may be omitted. • The unique identifier (URI) of the Resource Service that provides access to the Resource. • Zero or more keys (string name/value pairs) that identify the Resource These components are represented in a WS-Addressing Endpoint Reference as follows: • The Agent’s transport address is mapped to the [address] property. • The System identifier is mapped to a [reference property] named wsman:System. • The Resource Service identifier is mapped to a [reference property] named wsman:ResourceURI. • Each key is mapped to a [reference parameter] named wsman:Key with an element attribute named Name that contains the key name; the contents of the element is the key value. When serialized into a SOAP message, these components are represented as SOAP headers, as follows: <s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing" xmlns:wsman="http://schemas.xmlsoap.org/ws/2004/10/management"> <s:Header> ... <wsa:To>Agent transport address</wsa:To> <wsman:System>System identifier</wsman:System> ? <wsman:ResourceURI>Resource Type identifier</wsman:ResourceURI> <wsman:Key Name="key name">key value</wsman:Key> * ... </s:Header> ... </s:Envelope> There may be different representations of the identifying information of a Resource Instance used for other purposes, such as command line entry. 4. General Messaging 4.1 Operation time out Most management operations are time-critical due to quality of service constraints and obligations. If they cannot be completed in a specified time, usually an alternate approach is required to resolve an issue. The Agent should be aware of any such constraints a Manager may have. <wsman:OperationTimeout> xs:duration </wsman:OperationTimeout> All request messages MAY contain a wsman:OperationTimeout header element that indicates the maximum amount of time the Manager is willing to wait for the Agent to issue a response. The Agent SHOULD issue a wsman:OperationTimeout fault as follows if this time is exceeded and the operation is not yet complete: [Code] s12:Recipient [Subcode] wsman:OperationTimeout [Reason] "the operation could not be completed in the time requested" If the Agent faults a request for an operation time out, it SHOULD undo any effects of the operation that were accomplished before the time out. A correctly formatted 30-second timeout appears as follows in the SOAP header: <wsman:OperationTimeout>PT30S</wsman:OperationTimeout> 4.2 Locale Management operations often span locales, and many items in responses can require translation. <wsman:Locale lang="xs:language" s:mustUnderstand="false" /> All request messages MAY contain a wsman:Locale header element whose "lang" attribute indicates the locale of the client using an RFC 1766 (ISO 639) language code. The Agent SHOULD utilize this value when composing the response message and adjust any localizable values accordingly. The following example indicates the manager prefers a response localized to U.S. English: <wsman:Locale lang="en-us"/> 4.3 Data freshness Many implementations cache expensive values, but managers need a way to signal that recomputed, up-to-date values are required. <wsman:NoCache s:mustUnderstand="false" /> All request messages MAY contain a wsman:NoCache header element that indicates that the Agent SHOULD NOT used cached values for the content of the response. 5. Resource Access If a Resource provides a machine-readable representation of its state, and exposes read, update, create, and delete operations that operate on that state, it MUST do so by implementing WS-Transfer. Similarly, if a Resource exposes enumerable items such as tables, logs, or containers, the Resource MUST implement WS-Enumeration to support that enumeration. 5.1 WS-Transfer WS-Management defines the following header flags (empty elements) that MAY be used with the indicated WS-Transfer operations: <wsman:SummaryPermitted s:mustUnderstand="false" /> This header MAY be included on Get requests. It indicates that the Agent SHOULD return an abbreviated representation, if available. <wsman:ReturnResource s:mustUnderstand="true" /> This header MAY be included on Put and Create requests. It indicates that the Agent MUST return the new representation of the updated or created resource. Note that while Agents SHOULD support these headers, they MAY ignore wsman:SummaryPermitted. All WS-Management Agents MUST support the wsman:ReturnResource header; for this reason, it is appropriate to attach the SOAP mustUnderstand attribute to this header with a true value. The following header MAY be included by a resource instance with its response to the indicated WS-Transfer operations: <wsman:NewKeys s:mustUnderstand="true"> <wsman:Key Name="key name">key value</wsman:Key> + </wsman:NewKeys> If the Put operation caused one or more instance keys for the resource to change, this header will contain the complete set of wsman:Key elements that identify the updated resource instance. A Manager MUST recognize and appropriately process the contents of a wsman:NewKeys header. 5.2 WS-Enumeration <wsman:SummaryPermitted s:mustUnderstand="false" /> The wsman:SummaryPermitted header flag defined above in section 5.1 may also be used with Pull requests. 6. Eventing If a Resource can emit events and allows Managers to subscribe to and receive event messages, it MUST do so by implementing WS-Eventing. 6.1 General 6.1.1 Subscription managers and identifiers WS-Eventing introduces the concept of a subscription manager, which is a Web service that an event source delegates the management of a subscription to. While WS-Eventing places no restrictions on the EPR for the subscription manager, WS-Management constrains this EPR in order to define a consistent mechanism and to allow the subscription manager EPR to be known in cases where the subscription occurs as a result of configuration. All Resources that are event sources MUST create subscription manager EPRs by extending the Resource's EPR with a reference parameter named wse:Identifier. This reference parameter element MUST have no attributes and simple content, of type xs:anyURI. Subscribers MAY include a wsman:ProposedID header in a Subscribe message. If present, the contents of this header is a URI whose value is a proposed subscription ID, as follows: <wsman:ProposedID> xs:anyURI </wsman:ProposedID> The Resource that received the Subscribe message MUST use this ID to form the subscription manager EPR by setting wse:Identifier to the value of the wsman:ProposedID header element. If the Resource cannot do this, it MUST raise a wsman:InvalidProposedID fault: [Code] s12:Sender [Subcode] wsman:InvalidProposedID [Reason] "the proposed subscription ID could not be used" 6.1.2 Expiration If a Subscribe or Renew request contains a requested Expiration of type xs:dateTime, the Resource MAY include an Expiration of type xs:duration in the response message. Systems are required to have an internal clock, but there is no requirement that the clock be synchronized with other Systems, or indeed that the internal clock provide absolute time at all (as opposed to relative time). Therefore, Systems are not required to express subscription expiration as an absolute time. 6.1.3 Event message format All event messages sent using Push, Batched, or Trap mode MUST include a wse:Identifier header that contains the URI that identifies the related subscription. 6.2 Batched delivery mode Batching of events is an effective way of minimizing event traffic from a high-volume event source without sacrificing event timeliness. WS-Management defines a custom event delivery mode, Batched, that allows an event source to bundle multiple outgoing event messages into a single SOAP envelope. For this delivery mode, the wse:Delivery element has the following format: <wse:Delivery Mode="http://schemas.xmlsoap.org/ws/2004/10/management/Batched"> <wse:NotifyTo> wsa:EndpointReferenceType </wse:NotifyTo> <wsman:MaxItems> xs:positiveInteger </wsman:MaxItems> ? <wsman:MaxTime> xs:duration </wsman:MaxTime> ? <wsman:MaxCharacters> xs:positiveInteger </wsman:MaxCharacters> ? </wse:Delivery> The following describes additional, normative constraints on the outline listed above: wse:Delivery/@Mode MUST be "http://schemas.xmlsoap.org/ws/2004/10/management/Batched". wse:Delivery/wse:NotifyTo This required element MUST contain the endpoint reference to which event messages should be sent for this subscription. wse:Delivery/wsman:MaxItems This optional element MAY contain a positiveInteger that indicates the maximum number of event bodies to batch into a single SOAP envelope. The Resource MUST NOT deliver more than this number of items in a single delivery, although it MAY deliver fewer. wse:Delivery/wsman:MaxCharacters This optional element MAY contain a positiveInteger that indicates the maximum number of characters in the SOAP body for the event batch. The Resource MUST NOT deliver a batch of event items whose total character count exceeds this value. Because of the variable size of SOAP Body declarations and the unpredictable size of the SOAP Header, this does not refer to the entire maximum message size. wse:Delivery/wsman:MaxTime This optional element MAY contain a duration that indicates the maximum amount of time the SERVICE should allow to elapse while batching EVENT bodies. That is, this time may not be exceeded between the encoding of the first event in the batch and the dispatching of the batch for delivery. If Batched mode is requested in a Subscribe message, and none of MaxItems, MaxCharacters, and MaxTime are present, the Resource MUST issue a wsman:InvalidBatchParameter fault. [Code] s12:Sender [Subcode] wsman:InvalidBatchParameter [Reason] "at least one batching parameter must appear" If a subscription has been created using Batched mode, all event messages MUST have the following format: <s:Envelope ...> <s:Header> ... <wsa:Action> http://schemas.xmlsoap.org/ws/2004/10/management/Events </wsa:Action> ... </s:Header> <s:Body> <wsman:Events> <wsman:Event Action="event action URI"> ... </wsman:Event> + </wsman:Events> </s:Body> </s:Envelope> s:Envelope/s:Header/wsa:Action MUST be http://schemas.xmlsoap.org/ws/2004/10/management/Events. s:Envelope/s:Body/wsman:Events/wsman:Event Each of these required elements MUST contain the body of the corresponding event message, as if wsman:Event were the s:Body element. s:Envelope/s:Body/wsman:Events/wsman:Event/@Action This required attribute MUST contain the Action URI that would have been used for the contained event message. The following example shows batching parameters supplied to a wse:Subscribe operation. The service is instructed to send no more than 10 items per batch, to wait no more than 20 seconds between the time the first event is encoded until the entire batch is dispatched, and to include no more than 8192 characters in the SOAP body: <wse:Delivery Mode="http://schemas.xmlsoap.org/ws/2004/10/management/Batched"> <wse:NotifyTo> <wsa:Address>http://2.3.4.5/client</wsa:Address> </wse:NotifyTo> <wsman:MaxItems>10</wsman:MaxItems> <wsman:MaxTime>PT20S</wsman:MaxTime> <wsman:MaxCharacters>8192</wsman:MaxCharacters> </wse:Delivery> The following example shows an example of batched delivery that conforms to this specification. The salient features are the present of a wse:Identifier header as described above in section 6.1.3, the ws:Action specific to batched delivery, and the actual wsman:Event items juxtaposed in the env:Body acting as wrappers for the real events: <s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing xmlns:wse="http://schemas.xmlsoap.org/ws/2004/08/eventing"> <s:Header> <wsa:To env:mustUnderstand="true">http://2.3.4.5/client</wsa:To> <wse:Identifier> uuid:d795621f-a01d-4542-85f9-bdf50c00cb2e </wse:Identifier> <wsa:Action> http://schemas.xmlsoap.org/ws/2004/10/management/Events </wsa:Action> </s:Header> <s:Body> <wsman:Events> <wsman:Event Action="http://schemas.xmlsoap.org/2004/10/diskspacechange"> <DiskChange xmlns="http://schemas.xmlsoap.org/2004/10/diskspacechange"> <Drive> C: </Drive> <FreeSpace> 802012911 </FreeSpace> </DiskChange> </wsman:Event> <wsman:Event Action="http://schemas.xmlsoap.org/2004/10/diskspacechange"> <DiskChange xmlns="http://schemas.xmlsoap.org/2004/10/diskspacechange"> <Drive> D: </Drive> <FreeSpace> 1402012913 </FreeSpace> </DiskChange> </wsman:Event> </wsman:Events> </s:Body> </s:Envelope>