Table Of Contents
Accessing and Using WS-Management
Obtaining and Installing a WS-Management Client
Configuring WinRM
Viewing the Available Commands
Command Structure
Task Examples
Configuring a Battery Sensor Threshold
Configuring a Chassis Locator LED
Viewing and Clearing the System Event Log
Performing a Power Control Operation
Accessing and Using WS-Management
This chapter describes how to access the SMASH Web Services interface (WS-Management) and provides limited information about its use. For detailed information about using the SMASH WS-Management tool, see the DMTF documentation at this URL:
http://www.dmtf.org/standards/smash
This chapter contains the following topics:
•
Obtaining and Installing a WS-Management Client
•
Configuring WinRM
•
Viewing the Available Commands
•
Command Structure
•
Task Examples
Obtaining and Installing a WS-Management Client
To use WS-Management, you must obtain and install a WS-Management client for your operating system. Free clients are available for common operating systems, including Windows, Macintosh OS X, and Linux.
For this guide, we will use Microsoft Windows Remote Management (WinRM) as an example. WinRM is included with current Windows desktop and server versions, and is available as a download from Microsoft for selected earlier versions. Refer to Microsoft's documentation for instructions on obtaining and installing the appropriate version of WinRM for your client computer.
After installation, WinRM can be run from a Windows command prompt in any directory. To test the installation, enter the winrm id command at the Windows command prompt. The command output should appear as in the following example:
ProtocolVersion = http://schemas.dmtf.org/wbem/wsman/1/wsman.xsd
ProductVendor = Microsoft Corporation
ProductVersion = OS: 5.1.2600 SP: 2.0 Stack: 1.1
Configuring WinRM
By default, WinRM has the following restrictions:
•
Requires a secure connection (https)
•
Disallows basic authentication
•
Trusts no host
You must configure the client to allow unencrypted communication and basic authentication, and to trust certain hosts for unencrypted communication. To make these configuration changes, enter the following commands at the Windows command prompt:
winrm set winrm/config/client/auth @{Basic="true"}
winrm set winrm/config/client @{AllowUnencrypted="true"}
winrm set winrm/config/client @{TrustedHosts="*"}
This example shows how to verify the configuration:
C:\> winrm get winrm/config/client
Viewing the Available Commands
To display the WinRM command options, enter the winrm command at the Windows command prompt, as in the following example:
Windows Remote Management Command Line Tool
Windows Remote Management (WinRM) is the Microsoft implementation of
the WS-Management protocol which provides a secure way to communicate
with local and remote computers using web services.
winrm OPERATION RESOURCE_URI [-SWITCH:VALUE [-SWITCH:VALUE] ...]
[@{KEY=VALUE[;KEY=VALUE]...}]
For help on a specific operation:
winrm g[et] -? Retrieving management information.
winrm s[et] -? Modifying management information.
winrm c[reate] -? Creating new instances of management resources.
winrm d[elete] -? Remove an instance of a management resource.
winrm e[numerate] -? List all instances of a management resource.
winrm i[nvoke] -? Executes a method on a management resource.
winrm id[entify] -? Determines if a WS-Management implementation is
running on the remote machine.
winrm quickconfig -? Configures this machine to accept WS-Management
requests from other machines.
winrm configSDDL -? Modify an existing security descriptor for a URI.
winrm helpmsg -? Displays error message for the error code.
For help on related topics:
winrm help uris How to construct resource URIs.
winrm help aliases Abbreviations for URIs.
winrm help config Configuring WinRM client and service settings.
winrm help certmapping Configuring client certificate access.
winrm help customremoteshell Configures a shell executable and
arguments corresponding to a shell URI.
winrm help remoting How to access remote machines.
winrm help auth Providing credentials for remote access.
winrm help input Providing input to create, set, and invoke.
winrm help switches Other switches such as formatting, options, etc.
Tip
The output of the winrm command lists many other help options. Explore these additional options for detailed information about WinRM commands.
Command Structure
The following example shows a typical winrm get command:
C:\> winrm get
cimv2/CCIM_IndicatorLED?SystemCreationClassName=CCIM_ComputerSystem+SystemName=srv:1+Creat
ionClassName=CCIM_IndicatorLED+DeviceID=LED_FPID -r:https://192.0.20.137:443 -a:Basic
-u:admin -p:password -encoding:utf-8 -f:text -skipCAcheck -skipCNcheck
The following table describes the fields of this command:
Field
|
Description
|
|
The main winrm command.
|
|
This command is a GET CIM Object instance WSMAN operation, which retrieves management information.
|
|
The cimv2 path is an alias to the full resource URI that we are trying to retrieve. In this case, it is an alias for a DMTF CIM schema. For more information, enter the winrm help aliases command.
|
|
This is the object whose properties are being queried.
|
SystemCreationClassName=CCIM_ComputerSystem
|
The first of four object identification keys.
|
|
The + operator links multiple instances of key=value pairs.
|
|
The second of four object identification keys.
|
CreationClassName=CCIM_IndicatorLED
|
The third of four object identification keys.
|
|
The last of four object identification keys.
|
-r:https://192.0.20.137:443
|
The resource URI. Specifies an HTTP secure connection to the server at the given IP address at port 443. For more information, enter the winrm help remoting command.
|
|
Basic authentication will be used for the server connection. For more information, enter the winrm help auth command.
|
|
The username for logging in with basic authentication.
|
|
The password for logging in with basic authentication.
|
|
Data exchanged with the server will be in UTF-8 enconding. For more information on this field and the remaining fields, enter the winrm help switches command.
|
|
The format of data exchanged with the server will be formatted as text.
|
|
The SSL certificate authority (CA) of the server need not be a trusted root authority.
|
|
The SSL common name (CN) of the server need not match the hostname of the server.
|
Task Examples
This section contains the following examples:
•
Configuring a Battery Sensor Threshold
•
Configuring a Chassis Locator LED
•
Viewing and Clearing the System Event Log
•
Performing a Power Control Operation
Configuring a Battery Sensor Threshold
This example reads the 3 volt battery sensor status, sets the LowerThresholdCritical property to a new value of 2000, and reads the sensor again to verify the new value (in this example, the value is shown in bold for readability):
C:\> winrm get
cimv2/CCIM_NumericSensor?CreationClassName=CCIM_NumericSensor+DeviceID=0.0.20.1+SystemName
=srv:1+SystemCreationClassName=CCIM_ComputerSystem -r:https://192.0.20.137 -a:Basic
-u:admin -p:password -encoding:utf-8 -f:text -skipCNcheck -skipCAcheck
AdditionalAvailability = null
AvailableRequestedStates = null
CommunicationStatus = null
CreationClassName = CCIM_NumericSensor
ElementName = P3V_BAT_SCALED(0.0.20)
IdentifyingDescriptions = null
LowerThresholdCritical = 21780
LowerThresholdFatal = 19932
LowerThresholdNonCritical = 0
OtherIdentifyingInfo = null
OtherSensorTypeDescription = null
PossibleStates = Normal, Upper Fatal, Upper Critical, Upper Non-Critical, Lower Fatal,
Lower Critical, Lower Non-Critical, Unknown
PowerManagementCapabilities = null
PowerManagementSupported = null
ProgrammaticAccuracy = null
SettableThresholds = 2, 3, 4
StatusDescriptions = null
SupportedThresholds = 2, 3, 4
SystemCreationClassName = CCIM_ComputerSystem
TimeOfLastStateChange = null
TransitioningToState = 12
UpperThresholdCritical = 33000
UpperThresholdNonCritical = 0
C:\> winrm set
cimv2/CCIM_NumericSensor?CreationClassName=CCIM_NumericSensor+DeviceID=0.0.20.1+SystemName
=srv:1+SystemCreationClassName=CCIM_ComputerSystem -r:https://192.0.20.137 -a:Basic
-u:admin -p:password -encoding:utf-8 -f:text -skipCNcheck -skipCAcheck
@{LowerThresholdCritical="2000"}
AdditionalAvailability = null
AvailableRequestedStates = null
CommunicationStatus = null
CreationClassName = CCIM_NumericSensor
ElementName = P3V_BAT_SCALED(0.0.20)
IdentifyingDescriptions = null
LowerThresholdCritical = 2000
LowerThresholdFatal = 19932
LowerThresholdNonCritical = 0
OtherIdentifyingInfo = null
OtherSensorTypeDescription = null
PossibleStates = Normal, Upper Fatal, Upper Critical, Upper Non-Critical, Lower Fatal,
Lower Critical, Lower Non-Critical, Unknown
PowerManagementCapabilities = null
PowerManagementSupported = null
ProgrammaticAccuracy = null
SettableThresholds = 2, 3, 4
StatusDescriptions = null
SupportedThresholds = 2, 3, 4
SystemCreationClassName = CCIM_ComputerSystem
TimeOfLastStateChange = null
TransitioningToState = 12
UpperThresholdCritical = 33000
UpperThresholdNonCritical = 0
C:\> winrm get
cimv2/CCIM_NumericSensor?CreationClassName=CCIM_NumericSensor+DeviceID=0.0.20.1+SystemName
=srv:1+SystemCreationClassName=CCIM_ComputerSystem -r:https://192.0.20.137 -a:Basic
-u:admin -p:password -encoding:utf-8 -f:text -skipCNcheck -skipCAcheck
AdditionalAvailability = null
AvailableRequestedStates = null
CommunicationStatus = null
CreationClassName = CCIM_NumericSensor
ElementName = P3V_BAT_SCALED(0.0.20)
IdentifyingDescriptions = null
LowerThresholdCritical = 1980
LowerThresholdFatal = 19932
LowerThresholdNonCritical = 0
OtherIdentifyingInfo = null
OtherSensorTypeDescription = null
PossibleStates = Normal, Upper Fatal, Upper Critical, Upper Non-Critical, Lower Fatal,
Lower Critical, Lower Non-Critical, Unknown
PowerManagementCapabilities = null
PowerManagementSupported = null
ProgrammaticAccuracy = null
SettableThresholds = 2, 3, 4
StatusDescriptions = null
SupportedThresholds = 2, 3, 4
SystemCreationClassName = CCIM_ComputerSystem
TimeOfLastStateChange = null
TransitioningToState = 12
UpperThresholdCritical = 33000
UpperThresholdNonCritical = 0
Note
Because some properties have limited resolution, the actual resulting value may be slightly different from the value specified in the set command, as in this example.
Configuring a Chassis Locator LED
This example reads the current status of the chassis locator LED, turns the LED on by changing the Activation State from 4 to 3, and verifies the new status:
C:\> winrm get
cimv2/CCIM_IndicatorLED?SystemCreationClassName=CCIM_ComputerSystem+SystemName=srv:1+Creat
ionClassName=CCIM_IndicatorLED+DeviceID=LED_FPID -r:https://192.0.20.137:443 -a:Basic
-u:admin -p:password -encoding:utf-8 -f:text -skipCAcheck -skipCNcheck
AdditionalAvailability = null
AvailableRequestedStates = null
CommunicationStatus = null
CreationClassName = CCIM_IndicatorLED
DefaultActivationState = 4
ElementName = Chassis Identify LED
IdentifyingDescriptions = null
OtherColorDescription = null
OtherIdentifyingInfo = null
OtherIndicatedConditionDescription = null
PowerManagementCapabilities = null
PowerManagementSupported = null
StatusDescriptions = null
SystemCreationClassName = CCIM_ComputerSystem
TimeOfLastStateChange = null
TransitioningToState = 12
C:\> winrm set
cimv2/CCIM_IndicatorLED?SystemCreationClassName=CCIM_ComputerSystem+SystemName=srv:1+Creat
ionClassName=CCIM_IndicatorLED+DeviceID=LED_FPID -r:https://192.0.20.137:443 -a:Basic
-u:admin -p:password -encoding:utf-8 -f:text -skipCAcheck -skipCNcheck
@{ActivationState="3"}
AdditionalAvailability = null
AvailableRequestedStates = null
CommunicationStatus = null
CreationClassName = CCIM_IndicatorLED
DefaultActivationState = 4
ElementName = Chassis Identify LED
IdentifyingDescriptions = null
OtherColorDescription = null
OtherIdentifyingInfo = null
OtherIndicatedConditionDescription = null
PowerManagementCapabilities = null
PowerManagementSupported = null
StatusDescriptions = null
SystemCreationClassName = CCIM_ComputerSystem
TimeOfLastStateChange = null
TransitioningToState = 12
C:\> winrm get
cimv2/CCIM_IndicatorLED?SystemCreationClassName=CCIM_ComputerSystem+SystemName=srv:1+Creat
ionClassName=CCIM_IndicatorLED+DeviceID=LED_FPID -r:https://192.0.20.137:443 -a:Basic
-u:admin -p:password -encoding:utf-8 -f:text -skipCAcheck -skipCNcheck
AdditionalAvailability = null
AvailableRequestedStates = null
CommunicationStatus = null
CreationClassName = CCIM_IndicatorLED
DefaultActivationState = 4
ElementName = Chassis Identify LED
IdentifyingDescriptions = null
OtherColorDescription = null
OtherIdentifyingInfo = null
OtherIndicatedConditionDescription = null
PowerManagementCapabilities = null
PowerManagementSupported = null
StatusDescriptions = null
SystemCreationClassName = CCIM_ComputerSystem
TimeOfLastStateChange = null
TransitioningToState = 12
Viewing and Clearing the System Event Log
This example reads the system event log (SEL) entries, reads the log details, clears the log, and reads the log details again:
C:\> winrm Enumerate cimv2/CCIM_SELLogEntry -r:https://192.0.20.137:443 -a:Basic -u:admin
-p:password -encoding:utf-8 -f:text -skipCAcheck -skipCNcheck
CreationTimeStamp = 20100607145556.000000+000
ElementName = System Event Log Entry
InstanceID = CCIM:SEL:Entry:1
LogInstanceID = CCIM:SEL:1
LogName = System Event Log
RecordData = *1*LED_FPID: Platform sensor, OFF event was asserted
RecordFormat = *string Severity*string Description
CreationTimeStamp = 20100607145600.000000+000
ElementName = System Event Log Entry
InstanceID = CCIM:SEL:Entry:2
LogInstanceID = CCIM:SEL:1
LogName = System Event Log
RecordData = *1*LED_FPID: Platform sensor, FAST BLINK event was asserted
RecordFormat = *string Severity*string Description
C:\> winrm get
"http://schemas.cisco.com/wbem/wscim/1/cim-schema/2/CCIM_SELRecordLog?InstanceID=CCIM:SEL:
1" -r:https://192.0.20.137:443 -a:Basic -u:admin -p:password -encoding:utf-8 -f:text
-skipCAcheck -skipCNcheck
AvailableRequestedStates = null
CommunicationStatus = null
CurrentNumberOfRecords = 2
ElementName = System Event Log
MaxNumberOfRecords = 3008
StatusDescriptions = null
TimeOfLastStateChange = null
TransitioningToState = 12
C:\> winrm invoke ClearLog
"http://schemas.cisco.com/wbem/wscim/1/cim-schema/2/CCIM_SELRecordLog?InstanceID=CCIM:SEL:
1" -r:https://192.0.20.137:443 -a:Basic -u:admin -p:password -encoding:utf-8 -f:text
-skipCAcheck -skipCNcheck
C:\> winrm get
"http://schemas.cisco.com/wbem/wscim/1/cim-schema/2/CCIM_SELRecordLog?InstanceID=CCIM:SEL:
1" -r:https://192.0.20.137:443 -a:Basic -u:admin -p:password -encoding:utf-8 -f:text
-skipCAcheck -skipCNcheck
AvailableRequestedStates = null
CommunicationStatus = null
CurrentNumberOfRecords = 0
ElementName = System Event Log
MaxNumberOfRecords = 3008
StatusDescriptions = null
TimeOfLastStateChange = null
TransitioningToState = 12
Performing a Power Control Operation
This example queries the system power management capabilities with a WinRM enumerate command, displays an XML file containing the desired power control changes, and invokes the changes by applying the XML file with a WinRM invoke command:
C:\> winrm enumerate cimv2/CCIM_CSPowerManagementCapabilities -r:https://192.0.20.137:443
-a:Basic -u:admin -p:password -encoding:utf-8 -f:text -skipCAcheck -skipCNcheck
CCIM_CSPowerManagementCapabilities
ElementName = Power Management Capabilities
InstanceID = CCIM:pwrmgtcap1
OtherPowerCapabilitiesDescriptions = null
OtherPowerChangeCapabilities = null
PowerChangeCapabilities = 3, 4, 7, 8
PowerStatesSupported = 2, 5, 8, 10, 11, 12
C:\> type pwrcntrl_req.xml
<p:RequestPowerStateChange_INPUT
xmlns:p='http://schemas.cisco.com/wbem/wscim/1/cim-schema/2/CCIM_CSPowerManagementService'
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing"
xmlns:wsman="http://schemas.dmtf.org/wbem/wsman/1/wsman.xsd">
<wsa:Address>http://schemas.xmlsoap.org/ws/2004/08/addressing/role/anonymous</wsa:Address>
<wsa:ReferenceParameters>
<wsman:ResourceURI>http://schemas.cisco.com/wbem/wscim/1/cim-schema/2/CCIM_ComputerSystem<
/wsman:ResourceURI>
<wsman:Selector Name="Name">srv:1</wsman:Selector>
<wsman:Selector Name="CreationClassName">CCIM_ComputerSystem</wsman:Selector>
</wsa:ReferenceParameters>
<p:PowerState>5</p:PowerState>
<p:Time>00000000000000.000000:000</p:Time>
<p:TimeoutPeriod>00000000000000.000000:000</p:TimeoutPeriod>
</p:RequestPowerStateChange_INPUT>
C:\> winrm invoke RequestPowerStateChange
"cimv2/CCIM_CSPowerManagementService?CreationClassName=CCIM_CSPowerManagementService+Name=
pwrmgtsvc:1+SystemName=CIMC:1+SystemCreationClassName=CCIM_SPComputerSystem"
-r:https://192.0.20.137:443 -a:Basic -u:admin -p:password -encoding:utf-8 -f:pretty
-skipCAcheck -skipCNcheck -file:pwrcntrl_req.xml
<n1:RequestPowerStateChange_OUTPUT
xmlns:n1="http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/CCIM_CSPowerManagementService"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<n1:Job xsi:nil="true"></n1:Job>
<n1:ReturnValue>2</n1:ReturnValue>
</n1:RequestPowerStateChange_OUTPUT>