3.1.4.5.2 Remote Shells

  • Article

To create a new Shell, a wst:Create message MUST be sent where the wsman:ResourceURI element of the EPR specifies the type of Shell to be created. There are two types of remote shells:

  1. Text-based Command Shell scenario

  2. Custom Remote Shell scenario

To create a Text-based Command Shell on the remote system, the URI element MUST have the value http://schemas.microsoft.com/wbem/wsman/1/windows/shell/cmd; any other URI implies a Custom Remote Shell.

In essence, this EPR (with its wsman:ResourceURI) is a "factory" for instances of the Shell. The s:Body of the message contains the startup parameters defined by the Shell data type, as specified in section 2.2.4.37. This is illustrated as follows.

 <s:Envelope ...>
   <s:Header ...>
     <wsa:Action>
       http://schemas.xmlsoap.org/ws/2004/09/transfer/Create
     </wsa:Action>
     ...other WS-Addressing & WS-Management headers...
     <wsman:ResourceURI>
       http://schemas.microsoft.com/wbem/wsman/1/windows/shell/cmd
     </wsman:ResourceURI>
     <wsman:OptionSet xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
       <wsman:Option Name="xs:string"/>...value...</wsman:Option>+
     </wsman:OptionSet>   
   </s:Header>
   <s:Body ...>
     <rsp:Shell>
         ...Value defined by the Shell data type...
     </rsp:Shell>
   </s:Body>
 </s:Envelope>

The following named options MAY be used when creating the Remote Shell.<110>

Option

Description

WINRS_NOPROFILE

If set to TRUE, this option specifies that the user profile does not exist on the remote system and that the default profile SHOULD be used. By default, the value is TRUE.

WINRS_CODEPAGE

The value of the options specifies the client's console output code page. The value is returned by GetConsoleOutputCP API; on the server side, this value is set as input and output code page to display the number of the active character set (code page) or to change the active character set.

Upon successful processing of an wst:Create message, the Web Services Management Protocol Extensions for Windows Vista service MUST create a Shell instance and return a reference to it as a wsa:EndpointReference, as specified in [WSAddressing] and [DMTF-DSP0226] section 7.6 rule R7.6-5.

Otherwise, the body of the CreateResponse message SHOULD also include information about the created shell instance described by the rsp:Shell element. The following elements MUST be present in the rsp:Shell element:

  • ShellID

  • InputStreams

  • OutputStreams

The following elements SHOULD be present in the rsp:Shell element:

  • ResourceUri

  • Owner

  • ClientIP

  • IdleTimeout

  • ShellRunTime

  • ShellInactivity

The following additional fields SHOULD be returned by shell instances of plug-ins that support the Disconnected Shell capability:

  • Name

  • ProcessId

  • MaxIdleTimeout

  • Locale

  • DataLocale

  • CompressionMode

  • ProfileLoaded

  • Encoding

  • BufferMode

  • State

This is illustrated as follows.

 <s:Envelope ...>
   <s:Header ...>
     <wsa:Action>
       http://schemas.xmlsoap.org/ws/2004/09/transfer/CreateResponse
     </wsa:Action>
     ...other WS-Addressing & WS-Management headers...
   </s:Header>
   <s:Body>
     <wst:ResourceCreated>
       <wsa:Address>
              Transport level
          address of shell processor
       </wsa:Address>
       <wsa:ReferenceParameters>
         <wsman:ResourceURI>
           http://schemas.microsoft.com/wbem/wsman/1/windows/shell/cmd
         </wsman:ResourceURI>
         <wsman:SelectorSet>
           <wsman:Selector Name="ShellID">
                            ...shell GUID...
           </wsman:Selector>
         </wsman:SelectorSet>
       </wsa:ReferenceParameters>
     </wst:ResourceCreated>
     <rsp:Shell>
        ...Value defined by the Shell data type...
     </rsp:Shell>
   </s:Body>
 </s:Envelope>
 

The wsa:EndpointReference encapsulated within the wst:ResourceCreated contains a reference to the newly created Shell instance. This address is used in all subsequent messages to the Shell instance, that is, wst:Delete, Command, Signal, Send, and Receive.

The following describes the additional normative constraints on the Shell EPR:

  • ReferenceParameters: This required element identifies the created Shell instance.

  • ResourceURI: The value of Resource URI will be different for Text-based Command Shell and Custom Remote Shell

  • In case of Text-based Command Shell, the value of Resource URI MUST be as follows. http://schemas.microsoft.com/wbem/wsman/1/windows/shell/cmd

  • An example of Resource URI for Custom Remote Shell scenario is as follows. http://schemas.microsoft.com/wbem/wsman/1/windows/shell/CustomShell

  • SelectorSet: This value of the Name attribute of Selector element MUST contain the GUID identifying the new Shell.

The client extracts this new EPR and uses it in all subsequent messages, as it refers to the Shell instance that was just created.

The client MUST use the same wsman:Locale (section 3.2.4.1.4), wsmv:DataLocale (section 3.2.4.1.5) and encoding (as described in [DMTF-DSP0226] section 13.1) in all subsequent messages of the Remote Shell protocol, as those values refer to the Shell instance that was just created. The server behavior is undefined if any of these properties change.