---

Introduction

Discover how WS-Management promotes interoperability between management applications and managed resources such as notebooks and desktops.  Understand the basic concepts behind WS-Management, and how to implement the concepts using existing tools.

WS-Management is an industry standard SOAP-based protocol for managing systems such as desktops, notebooks, servers, and other IT related infrastructure.  The intent of WS-Management is to reduce the cost and complexity of IT management by providing a common way for systems to access and exchange management information across the enterprise.

---

WS-Management and Industry standards

There are existing industry standards which applications can use to exchange management information such as Alert Standard Format (ASF) and Intelligent Platform Management Interface (IPMI).  The ASF standard was developed primarily to support remote management of client systems in OS-absent environments, while IPMI was developed to instrument server hardware.  Both ASF and IPMI are based on Remote Management Control Protocol (RMCP) which is a UDP based networking protocol.   In contrast, WS-Management is based on standard internet based protocols such as SOAP/XML and Web-Services.   Furthermore, WS-Management was developmed as a management protocol suitable for all IT infrastructures, and is not limited to just desktop management or server instrumentation.

---

WS-Management Concepts

In order to understand WS-Management the following terms are taken from the specification.

Managed Resource

A Managed Resource is an entity that can be of interest to an administrator. It may be a physical object such as a laptop computer or a printer, or an abstract entity such as a service.

Resource Class

A Resource Class is an abstract representation (type) of a managed resource. It defines the representation of management-related operations and properties. An example of a resource class is the description of operations and properties for a set of laptop computers.

Resource Instance

A Resource Instance is an instantiation of a resource class. An example is the set of management related operations and property values for a specific laptop (such as the one being used to create this document).

Selector

A Selector is a resource-relative name and value pair which acts as an instance-level discriminate. This is essentially a filter or "key" which identifies the desired instance of the resource.

A Comparison Using Device Manager

Taking a look at Device Manager on a typical computer can help in understanding the concepts of classes, instances, and selectors.  While Device Manger itself has really nothing to do with WS-Management, it can be used to describe the concepts.

[missing image]

Running Device Manager on a typical PC reveals a list of device types such as disk drives, keyboards, and processors. These device types can be thought of as "resource classes," since they define a type of device found on the system.  Furthermore, Device Manager can be used to view specific instances of devices that are present on the computer.  For example, expanding the processor type reveals 2 instances of a processor.  Each processor listed can be thought of as a "resource instance."

Now, let’s say you want to perform an action on one of the processors listed.  Since there are two processors, you must first select one before performing any action.  Similarly, in WS-Management, “selectors” are used to select or choose the instance of a resource you want actions performed.

Once you select a specific resource in Device Manager, you can use the Action Menu to perform specific operations on the resource.  In this case we can perform actions like Update Driver or view Properties. Likewise, WS-Management defines a core set of actions that can be performed on any resource.

---

WS-Management Features

WS-Management exposes a common set of operations that are central to all systems.

These core operations include:

• 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

 

Core operations are organized into the following web services:

• WS-Transfer: Provides simple operations on a single resource such as GET, PUT, CREATE, and DELETE
• WS-Enumeration: Provides access to multiple resources such as containers, collections, and large tables
• WS-Eventing: Provides a mechanism for applications to subscribe for events emitted by resource

 

In addition, WS-Addressing provides a common framework for defining references to resources, as well as, the basic mechanics for sending and receiving messages.

---

WS-Transfer

Taking a closer look at WS-Transfer we see the following actions defined:

AnyXMLMessage resourceRef.Get() // reads information about a resource

OptionalXMLMessage resourceRef.Put(AnyXMLMessage) // writes to a resource

resourceRef.Delete() // deletes a resource

CreateResponseMessage Create(AnyXMLMessage) // creates a resource

It should be noted that WS-Transfer simply provides a means to exchange information regarding a resource instance, or create a new resource.  The inputs and outputs can be any XML data a resource chooses to expose.  WS-Management itself does not define the structure or format of a resource (other than that XML will be used).  However, later on, we will discuss CIM bindings, which can used to formally define the structure of a resource.

Another thing to note, is that in order to send a message to a resource, we first need a reference to it, with the exception of create message, which is used to construct a new resource.  WS-Addressing provides the standard structure to define references to resources so that messages can be sent to them.  WS-Addressing uses endpoint references (also known as EPRs) as the addressing model for individual resource instances.  The following is a full example of a hypothetical GET message:

xmlns:s="http://www.w3.org/2003/05/soap-envelope"
xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing"
xmlns:wsman="http://schemas.dmtf.org/wbem/wsman/1/wsman.xsd">

http://1.2.3.4/wsman/

http://samples.org/2005/02/physicalDisk



http://schemas.xmlsoap.org/ws/2004/08/addressing/role/anonymous



http://schemas.xmlsoap.org/ws/2004/09/transfer/Get


uuid:d9726315-bc91-430b-9ed8-ce5ffb858a87


2

PT30S

Now let us consider each element in the above GET message.

s:Envelope, s:Header, and s:Body

Defines the basic structure of a SOAP message

wsa:To

The transport address of the service.  In this case the hypothetical address: http://1.2.3.4/wsman

wsman:ResourceURI

The URI of the resource class representation or instance representation.  In this case the hypothetical “physicalDisk” class.  The ResourceURI is any valid URI according to RFC 3986. While there is no default scheme, http: and urn: are common defaults. If http: is us ed, users may expect to find web-based documentation regarding the resource at that address.  Both this URI and the wsa:To URI forms the full address of the resource class or instance.

wsa:ReplyTo

Present in all request messages when a reply is expected.

wsa:Action

Identifies which operation is to be carried out against the resource, in this case, a "Get".

wsa:MessageID

Identifies messages uniquely for tracking and correlation purposes.

wsa:SelectorSet

Identifies or selects the resource instance to be accessed when more than one instance of the resource exists. In this case, the Selector is "LUN" (logical unit number), and the selected device is unit number "2".

The response to our hypothetical GET message would look like the following:

<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.dmtf.org/wbem/wsman/1/wsman.xsd">
<s:Header>
<wsa:To>
http://schemas.xmlsoap.org/ws/2004/08/addressing/role/anonymous
</wsa:To>
<wsa:Action s:mustUnderstand="true">
http://schemas.xmlsoap.org/ws/2004/09/transfer/GetResponse
</wsa:Action>
<wsa:MessageID s:mustUnderstand="true">
uuid:d9726315-bc91-430b-9ed8-ce5ffb858a88
</wsa:MessageID>
<wsa:RelatesTo>
uuid:d9726315-bc91-430b-9ed8-ce5ffb858a87
</wsa:RelatesTo>
</s:Header>
<s:Body>
<PhysicalDisk xmlns="http://schemas.acme.com/2005/02/samples/physDisk">
<Manufacturer> Acme, Inc. </Manufacturer>
<Model> 123-SCSI 42 GB Drive </Model>
<LUN> 2 </LUN>
<Cylinders> 16384 </Cylinders>
<Heads> 80 </Heads>
<Sectors> 63 </Sectors>
<OctetsPerSector> 512 </OctetsPerSector>
<BootPartition> 0 </BootPartition>
</PhysicalDisk>
</s:Body>
</s:Envelope>

 

The elements in the response are essentially the same as those present in the request.  Note the SOAP body contains the actual data returned by the resource.  Remember the resource data in the response is not defined by WS-Management, but is in whatever format the resource decides to return.

---

WS-Enumeration

Now let’s take a closer look at WS-Enumeration.  WS-Management does not define any messages or techniques for batched operations, such as batched Get or Delete. All such operations must be sent as a series of single messages.  On the other hand, WS-Enumeration can be used to retrieve lists or collections of resources.

It should be noted that WS-Transfer simply provides a means to exchange information regarding a resource instance, or create a new resource.  The inputs and outputs can be any XML data a resource chooses to expose.  WS-Management itself does not define the structure or format of a resource (other than that XML will be used).  However, later on, we will discuss CIM bindings, which can used to formally define the structure of a resource.

Another thing to note, is that in order to send a message to a resource, we first need a reference to it, with the exception of create message, which is used to construct a new resource.  WS-Addressing provides the standard structure to define references to resources so that messages can be sent to them.  WS-Addressing uses endpoint references (also known as EPRs) as the addressing model for individual resource instances.  The following is a full example of a hypothetical GET message:

<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.dmtf.org/wbem/wsman/1/wsman.xsd">
<s:Header>
<wsa:To>http://1.2.3.4/wsman/</wsa:To>
<wsman:ResourceURI>
http://samples.org/2005/02/physicalDisk
</wsman:ResourceURI>
<wsa:ReplyTo>
<wsa:Address>
http://schemas.xmlsoap.org/ws/2004/08/addressing/role/anonymous
</wsa:Address>
</wsa:ReplyTo>
<wsa:Action>
http://schemas.xmlsoap.org/ws/2004/09/transfer/Get
</wsa:Action>
<wsa:MessageID>
uuid:d9726315-bc91-430b-9ed8-ce5ffb858a87
</wsa:MessageID>
<wsman:SelectorSet>
<wsman:Selector Name="LUN"> 2 </wsman:Selector>
</wsman:SelectorSet>
<wsman:OperationTimeout> PT30S </wsman:OperationTimeout>
</s:Header>
<s:Body/>
</s:Envelope>

 

Now let us consider each element in the above GET message.

s:Envelope, s:Header, and s:Body

Defines the basic structure of a SOAP message

wsa:To

The transport address of the service.  In this case the hypothetical address: http://1.2.3.4/wsman

wsman:ResourceURI

The URI of the resource class representation or instance representation.  In this case the hypothetical “physicalDisk” class.  The ResourceURI is any valid URI according to RFC 3986. While there is no default scheme, http: and urn: are common defaults. If http: is us ed, users may expect to find web-based documentation regarding the resource at that address.  Both this URI and the wsa:To URI forms the full address of the resource class or instance.

wsa:ReplyTo

Present in all request messages when a reply is expected.

wsa:Action

Identifies which operation is to be carried out against the resource, in this case, a "Get".

wsa:MessageID

Identifies messages uniquely for tracking and correlation purposes.

wsa:SelectorSet

Identifies or selects the resource instance to be accessed when more than one instance of the resource exists. In this case, the Selector is "LUN" (logical unit number), and the selected device is unit number "2".

The response to our hypothetical GET message would look like the following:

<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.dmtf.org/wbem/wsman/1/wsman.xsd">
<s:Header>
<wsa:To>
http://schemas.xmlsoap.org/ws/2004/08/addressing/role/anonymous
</wsa:To>
<wsa:Action s:mustUnderstand="true">
http://schemas.xmlsoap.org/ws/2004/09/transfer/GetResponse
</wsa:Action>
<wsa:MessageID s:mustUnderstand="true">
uuid:d9726315-bc91-430b-9ed8-ce5ffb858a88
</wsa:MessageID>
<wsa:RelatesTo>
uuid:d9726315-bc91-430b-9ed8-ce5ffb858a87
</wsa:RelatesTo>
</s:Header>
<s:Body>
<PhysicalDisk xmlns="http://schemas.acme.com/2005/02/samples/physDisk">
<Manufacturer> Acme, Inc. </Manufacturer>
<Model> 123-SCSI 42 GB Drive </Model>
<LUN> 2 </LUN>
<Cylinders> 16384 </Cylinders>
<Heads> 80 </Heads>
<Sectors> 63 </Sectors>
<OctetsPerSector> 512 </OctetsPerSector>
<BootPartition> 0 </BootPartition>
</PhysicalDisk>
</s:Body>
</s:Envelope>

 

The elements in the response are essentially the same as those present in the request.  Note the SOAP body contains the actual data returned by the resource.  Remember the resource data in the response is not defined by WS-Management, but is in whatever format the resource decides to return.

---

WS-Enumeration

Now let’s take a closer look at WS-Enumeration.  WS-Management does not define any messages or techniques for batched operations, such as batched Get or Delete. All such operations must be sent as a series of single messages.  On the other hand, WS-Enumeration can be used to retrieve lists or collections of resources.

Items[] enumerate() // Begins an enumeration

Items[] Pull() // Retrieves the next batch of items

Release() // Releases an active enumerator

A typical response to an enumerate message would be as follows:

<s:Body>
<wsen:EnumerateResponse>
<wsen:EnumerationContext/>
<wsman:Items>

<PhysicalDisk
xmlns="http://schemas.acme.com/2005/02/samples/physDisk">
<Manufacturer> Acme, Inc. </Manufacturer>
<Model> 123-SCSI 42 GB Drive </Model>
<LUN> 2 </LUN>
<Cylinders> 16384 </Cylinders>
<Heads> 80 </Heads>
<Sectors> 63 </Sectors>
<OctetsPerSector> 512 </OctetsPerSector>
<BootPartition> 0 </BootPartition>
</PhysicalDisk>

...

</wsman:Items>
<wsman:EndOfSequence/>
</wsen:EnumerateResponse>
</s:Body>

 

---

The Common Information Model

 

While the WS-Management specification defines basic operations that can be performed on resources, it does not define what an actual resource looks like.  This is the role of Common Information Model (CIM).  CIM is an object oriented modeling language that can be used to define the actual structure of resources, including their properties and methods.  In this case, the model or definition of a specific resource is known as a CIM class.  In addition, CIM profiles are collections of classes needed to implement a specific management feature.  For example, resources that support power state management could be expected to support the Power State Management Profile.  This profile would define all the individual CIM classes necessary to conduct power management operations.

CIM classes can be described visually using UML Diagrams or described textually using the Managed Object Format (MOF) syntax or even XML.  It is beyond the scope of this document to describe all of the aspects of CIM and the various ways to define and model CIM classes.  The description of the CIM schema that Intel® AMT is based on can be found at the following DTMF website:

http://dmtf.org/standards/cim/cim_schema_v211

 

---

Windows Remote Management

The Windows Remote Management (WinRM) is the Microsoft implementation of the WS-Management Protocol.  Using WinRM scripting objects or the command-line tool you can obtain management data from devices that support the WS-Management protocol (Including Intel® AMT 3.0 devices).  WinRM ships with the Vista operating system (all flavors), and will be included in Longhorn Server.  Moreover, WinRM v1.1 will be available on XP and Win2003 shortly (currently in beta).

The WinRM exposes the following methods:

Method	Description
Create	Creates a new instance of a resource and returns the URI of the new object.
Delete	Deletes the resource specified in the resource URI.
Enumerate	Enumerates a collection, table, or message log resource.
Get	Retrieves a resource from the service and returns an XML representation of the current instance of the resour ce.
Identify	Queries a remote computer to determine if it supports the WS-Management protocol.
Invoke	Invokes a method that returns the results of the method call.
Put	Updates a resource.

 

As you can see, the methods exposed by WinRM correspond to the actions defined by the WS-Management protocol.  Below is an example of how to use VBScript to send commands to an Intel® AMT device.

'Create a WSMan object.

Dim objWsman Set objWsman = CreateObject( "WSMAN.Automation" )

‘Setup digests user name and password

iFlags = WSMan.SessionFlagUseDigest Or WSMan.SessionFlagCredUsernamePassword
Set Options = Wsman.CreateConnectionOptions

Options.Username = “admin"
Options.Password = "P@ssw0rd"

'Create Session object.
Dim objSession Set objSession = objWsman.CreateSession(“ http://amthost:16992/wsman ”,iFlags,options);

‘Define the resourceUri (including selectors) of a resource Instance
‘Selectors are passed as query arguments in the URI

strResourceUri = “http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/AMT_SetupAndConfigurationService” &
“?Name=Intel® AMT Setup and Configuration Service” &
“+CreationClassName=AMT_SetupAndConfigurationService” & “
+SystemCreationClassName=CIM_ComputerSystem” & ”+SystemName=Intel® AMT"

‘Get the information for the resource
xmlResource = objSession.get( strResourceUri )


‘Enumerate all instances of CIM_ManagedElement

strResourceUri = “http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/CIM_ManagedElement”

xmlResource = objSession.Enumerate(strResourceUri)

 

You can also use the WinRM command-line tool to send commands to Intel® AMT.  Open a command prompt and type “WinRM” to get instructions on how to use the tool.  The following is an example of how to enumerate elements on an Intel® AMT device using the command-line.

>winrm e http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/CIM_ManagedElement -a:Digest
-r:http://amthost:166992/wsman&rdq uo; -encoding:utf-8 -u:”admin” -p:”adminstrongpassword”

 

As you can see WinRM is useful tool for sending commands to Intel® AMT.  WinRM also demonstrates the interoperability that can be achieved through WS-Management.  WinRM was written without any specific knowledge of Intel® AMT hardware.  Yet because both WinRM and Intel® AMT understand the WS-Management protocol they both can interact with each other.  That’s Interoperability!

---

Learn More about WS-Management

For further information regarding WS-Management, the following resources provide a good starting point:

• Web Services for Management contains the actual specification for WS-Management protocol.
• WS-Managment - CIM Binding contains the actual CIM-Binding specification for the WS-Management protocol
• MSDN: Search for “WinRM” to get information regarding Windows Remote Management

 

The Intel AMT SDK 3.0 release contains the following resources regarding WS-Management.

• Intel® Active Management Technology WS-Management Flows
• WS-Management_classesindexl.html