Demystifying the WinRM command

Revision 3 posted to Systems Management - Wiki by sushmab on 10/28/2014 4:31:01 PM

The following article was written by Sushma B from the PG Validation Group.

Introduction:

On first glance the WinRM commands may be quite intimidating. However in absence of a full-fledged console program, we have to rely on the usage of such command line tools for retrieving data from the WSMAN stack.

Let us look at the following examples of commands:

Command 1:

winrm e http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/root/dcim/DCIM_NICview -u:[iDRAC username] -p:[iDRAC password] -r:https://[iDRAC ip]/wsman -a:basic -encoding:utf-8 -skipCACheck -skipCNCheck -skipRevocationCheck -dialect:http://schemas.microsoft.com/wbem/wsman/1/WQL -filter:"select * from DCIM_NicView where FQDD="NIC.Slot.5-2-1"" -options:{ShowExtensions="true"}

Command 2:

winrm e http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/root/dcim/* -u:[iDRAC username] -p:[iDRAC password] -r:https://[iDRAC ip]/wsman -a:basic -encoding:utf-8 -skipCACheck -skipCNCheck -dialect:association -filter:{object=DCIM_MetricServiceCapabilities?InstanceID=DCIM:MetricServiceCapabilities:1;associationclassname=DCIM_BMelementCapabilities;resultclassname=DCIM_MetricService;resultrole=ManagedElement;role=Capabilities}

All the above commands are valid and serve specific purpose in handling the data served by the CIMOM layer. (Feel free to try them out on any PowerEdge 12G server).

Parts of the command:

If we look closely we can format the commands with following grammar

<winrm command>:= “winrm” <method> <resource-uri> <user-credentials> [<host>] [options]

The first part of any winrm command is to tell the client what it needs to do. The available commands are enumerate, get, set, invoke, create, delete, etc. For more information on WinRM commands please type winrm –help.

To access data from the CIM layer, one needs to provide the Class Name or an instance of the class name. This is defined by the resource uri. In general the resource uri’s are of the format http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/[iDRAC username]/dcim/DCIM_NICview.This specifies the class name “DCIM_NICView”. The prefixed “schemas.dmtf.org” contains the schema definitions referenced by a number of specifications, including registries, protocols, wrapper specifications and the CIM Schema itself.

However WinRM provides a way to bypass the lengthy url’s with the use of aliases. The list of aliases supported by WinRM can be found by winrm –help aliases.

To access a remote WSMAN service, one needs to provide the authentication parameters. The username and the password need to be provided to access the WSMAN service as described by the hostname.

Authentication options:

The following options are supported by the winrm service.

a) Basic: The user name and password sent in the authentication exchange. Basic authentication can be configured to use either HTTP or HTTPS transport in a domain or workgroup. This method is the least secure method of authentication transport in a domain or workgroup. This method should be used when the underlying transport layer will provide the data security.

b) Digest: An exchange wherein the server receives a request from a client and sends data about the client to an authenticating server, typically a domain controller. If the client is authenticated, then the server receives a Digest session key used to authenticate subsequent requests from the client.

c) Negotiate: A negotiated, single sign on type of authentication that is the Windows implementation of Simple and Protected GSSAPI Negotiation Mechanism (SPNEGO). SPNEGO negotiation determines whether authentication is handled by Kerberos or NTLM. Kerberos is the preferred mechanism.

d) Kerberos: There are two ways to use this mechanism: If no credentials are specified, then the logged-on credentials are used to authenticate against the remote machine. This allows for a single sign-on experience. If explicit credentials are specified by designating the username and password, then Kerberos is used when credentials for a domain account are specified, and NTLM is used when credentials for a local account on the remote machine are specified.

e) Certificate: Client authentication certificates may also be used for the authentication to the WSMAN service. For more information please refer to winrm –help certmapping

f) CredSSP: CredSSP is a new Security Support Provider (SSP) by using the Security Support Provider Interface (SSPI). CredSSP enables a program to use client-side SSP to delegate user credentials from the client computer to the target server.

The preferred mode of authentication is basic as the underlying transport layer provides data security over HTTPS.

Certificate related options:

For a self-signed certificate to work, WinRM provides the following options

-skipCAcheck-- skip authenticating the Certificate Authority

-skipCNcheck-- skip authentication of common name

-skipRevocationcheck -- Do not check the revocation status of the server certificate.

Formatting options:

The following options for output are possible:

format:#xml

In this type, the raw XML is shown without any changes.

winrm e http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/root/dcim/DCIM_FanView -u:[iDRAC username] -p:[iDRAC password] -r:https://10.94.193.25/wsman -SkipCNcheck -SkipCAcheck -encoding:utf-8 -a:basic -format:xml

<wsman:Results xmlns:wsman="http://schemas.dmtf.org/wbem/wsman/1/wsman/results">

<n1:DCIM_FanView xmlns:n1="http://schemas.dell.com/wbem/wscim/1/cim-schema/2/DCIM_FanView" xml:lang=""><n1:ActiveCooling>true</n1:ActiveCooling><n1:BaseUnits>19</n1:BaseUnits><n1:CurrentReading>2040</n1:CurrentReading><n1:DeviceDescription>Fan 1</n1:DeviceDescription><n1:FQDD>Fan

.Embedded.1</n1:FQDD><n1:InstanceID>Fan.Embedded.1</n1:InstanceID><n1:LastSystemInventoryTime>20130621101455.000000+000</n1:LastSystemInventoryTime><n1:LastUpdateTime>20130623021234.000000+000</n1:LastUpdateTime><n1:PrimaryStatus>1</n1:PrimaryStatus><n1:RateUnits>0</n1:RateUnits>

<n1:RedundancyStatus>0</n1:RedundancyStatus><n1:UnitModifier>0</n1:UnitModifier><n1:VariableSpeed>true</n1:VariableSpeed></n1:DCIM_FanView>

</wsman:Results>

format:#pretty

This option displays XML in indented format. A four-character indentation is used for displaying nested XML elements.

<wsman:Results xmlns:wsman="http://schemas.dmtf.org/wbem/wsman/1/wsman/results">

<n1:DCIM_FanView xml:lang="" xmlns:n1="http://schemas.dell.com/wbem/wscim/1/cim-schema/2/DCIM_FanView">

<n1:ActiveCooling>true</n1:ActiveCooling>

<n1:BaseUnits>19</n1:BaseUnits>

<n1:CurrentReading>2040</n1:CurrentReading>

<n1:DeviceDescription>Fan 1</n1:DeviceDescription>

….

<n1:RateUnits>0</n1:RateUnits>

<n1:RedundancyStatus>0</n1:RedundancyStatus>

<n1:UnitModifier>0</n1:UnitModifier>

<n1:VariableSpeed>true</n1:VariableSpeed>

</n1:DCIM_FanView>

</wsman:Results>

format:#text

The default is text output.

DCIM_FanView

ActiveCooling = true

BaseUnits = 19

RedundancyStatus = 0

UnitModifier = 0

VariableSpeed = true

Dialects:

Use of dialects helps filtering out instances specific to a query from a large set of instances.

Dialect of the filter expression for enumeration or fragment.

                    Example: Use a WQL query

                      -dialect:http://schemas.microsoft.com/wbem/wsman/1/WQL

                    Example: Use XPATH for filtering with enumeration or fragment get/set.

                      -dialect:http://www.w3.org/TR/1999/REC-xpath-19991116

The implementation supports multiple dialects namely

a) WQL: Use WMI query language

b) CQL: Use CIM query language

c) Selectors: Use a filter without a query

d) Associations: To traverse association through filters

Conclusion:

Though WinRM commands are complex, it follows a standard structure and most of the commands can be formulated based on this. The above blog tries to demystify the different parts of the command which controls how the WinRM command will behave.