Edit

WinRM Service Plug-in Configuration

  • Article

A Windows Remote Management (WinRM) plug-in must be registered in the WinRM catalog to enable the infrastructure to dynamically determine the set of available plug-ins and the resource URIs that they support. All resource URIs for WinRM plug-ins should conform to the format that is defined in RFC 3986 (https://www.ietf.org/rfc/rfc3986.txt). Configuration is done through the main WinRM service.

The following command registers a plug-in configuration with the WinRM service:

winrm create http://schemas.microsoft.com/wbem/wsman/1/config/plugin?name=MyPlugIn -file:myplugin.xml

Note

The WinRM service needs to be restarted to expose the newly registered plug-ins.

Plug-in configuration is specified in XML. The following is an example.

<PlugInConfiguration xmlns="http://schemas.microsoft.com/wbem/wsman/1/config/PluginConfiguration" 
                     Name="MyPlugIn"
                     Filename="%systemroot%\system32\myplugin.dll" 
                     SDKVersion="1"
                     XmlRenderingType="text"
                     Architecture="64"
                     Enabled="true">

 <InitializationParameters>
  <Param Name="myParam1" Value="myValue1"/>
  <Param Name="myParam2" Value="myValue2"/>
 </InitializationParameters>

 <Resources>
  <Resource ResourceUri="https://schemas.MyCompany.com/MyUri1" SupportsOptions="true" ExactMatch="false">
   <Capability Type="Get" SupportsFragment="true"/>
   <Capability Type="Put" SupportsFragment="true"/>
   <Capability Type="Create"/>
   <Capability Type="Delete"/>
   <Capability Type="Invoke"/>
   <Capability Type="Enumerate" SupportsFiltering="true"/>
  </Resource>

  <Resource ResourceUri="https://schemas.MyCompany.com/MyUri2" SupportsOptions="false" ExactMatch="true">
   <Security Uri="https://schemas.MyCompany.com/MyUri2" Sddl="O:NSG:BAD:P(A;;GA;;;BA)"/>
   <Security Uri="https://schemas.MyCompany.com/MyUri2/MoreSpecific" Sddl="O:NSG:BAD:P(A;;GR;;;BA)" ExactMatch="true"/>
   <Capability Type="Shell"/>
  </Resource>
 </Resources>
</PlugInConfiguration>

The following list describes the XML elements in more detail and is followed by the configuration schema specified as an XSD.

PlugInConfiguration/OperationsConfiguration

Specifies the file name of the operations plug-in. Any environment variables that are put in this entry will be expanded in the users' context when a request comes in. Each user could have a different version of the same environment variable, so each user could end up with a different plug-in. This entry cannot be blank and must point to a valid plug-in.

PlugInConfiguration/Name

Specifies the display name to use for the plug-in. If an error is returned from the plug-in, this name will be put into the error XML that is returned to the client application. The name is not locale specific.

PlugInConfiguration/Architecture

Specifies whether the operations plug-in is 32-bit or 64-bit. If this element is not specified, the value will default to "32" on x86 systems and to "64" on 64-bit systems. For x86 systems, the only valid value is "32". If the value is "32" on an 64-bit system, wow64 redirection needs to be taken into account when entering the Filename information. The underlying file system will use wow64 redirection to translate system32 to syswow64. For example, if Filename is "%windir%\system32\myplugin.dll" and Architecture is "32", the actual plug-in file is located at "%windir%\syswow64\myplugin.dll".

PlugInConfiguration/XmlRenderingType

Configures the format in which XML is passed to plug-ins through the WSMAN_DATA object. The following types are available:

Text

Incoming XML data is contained in a WSMAN_DATA_TYPE_TEXT structure, which represents the XML as a PCWSTR memory buffer.

XMLReader

Incoming XML data is contained in a WSMAN_DATA_TYPE_WS_XML_READER structure, which represents the XML as an XmlReader object, which is defined in the WebServices.h header file.

PlugInConfiguration/InitializationXml

This node is optional and allows a plug-in to configure extra XML that will be passed in to the WSManPluginStartupmethod. Most plug-ins will not need this extra information, but if a plug-in needs to be used under more than one scenario that requires different run-time semantics, this XML will give the plug-in the flexibility to do this.

PlugInConfiguration/Resources

Specifies a list of resource URIsthat this plug-in supports. At least one ResourceUrientry must be specified; otherwise, the XML will be rejected.

PlugInConfiguration/Resources/Resource

Represents a single resource URIconfiguration.

Note

The SupportsOptionsattribute can be set to false. If SupportsOptionsis set to false, this attribute is not listed when the resource is enumerated.

 

PlugInConfiguration/Resources/Resource/ResourceUri

Specifies a single resource URI either in full or as a partial match string based on the ExactMatch attribute. If ExactMatch is not present, it defaults to False, which means the WinRM SOAP processor will do a partial match to the start of the resource URI and, if there is a match, pass it to the plug-in. The SupportsOptions attribute can be specified if this resource URI is allowed to have any options passed in. By default, no options are supported, and if any are present in the client request, an error will be returned. If options are supported by the plug-in, it is important that the plug-in returns the correct error if an option is present that the plug-in does not understand when the mustUnderstand flag is set to True.

PlugInConfiguration/Resources/Resource/Capability

Specifies a capability that is available on this resource URI. There will be one entry for each type of operation that it supports. The following options are available:

Get

Get operations are supported on the resource URI. The SupportFragment attribute is used if the get operation supports the concept. The SupportFiltering attribute is not valid and should be set to false. This capability is not valid for a resource URI if shell operations are also supported.

Put

Put operations are supported on the resource URI. The SupportFragmentattribute is used if the put operation supports the concept. The SupportFiltering attribute is not valid and should be set to False. This capability is not valid for a resource URI if shell operations are also supported.

Create

Create operations are supported on the resource URI. The SupportFragment attribute is used if the create operation supports the concept. The SupportFiltering attribute is not valid and should be set to False. This capability is not valid for a resource URI if shell operations are also supported.

Delete

Delete operations are supported on the resource URI. The SupportFragment attribute is used if the delete operation supports the concept. The SupportFiltering attribute is not valid and should be set to False. This capability is not valid for a resource URI if shell operations are also supported.

Invoke

Invoke operations are supported on the resource URI. The SupportFragment attribute is not supported for invoke operations and should be set to false. The SupportFiltering attribute is not valid and should be set to False. This capability is not valid for a resource URI if shell operations are also supported.

Enumerate

Enumerate operations are supported on the resource URI. The SupportFragment attribute is not supported for enumerate operations and should be set to False. The SupportFiltering attribute is valid, and if the plug-in supports filtering this attribute should be set to True. This capability is not valid for a resource URI if shell operations are also supported.

Subscribe

Subscribe operations are supported on the resource URI. The SupportFragment attribute is not supported for subscribe operations and should be set to False. The SupportFiltering attribute is not valid and should be set to False. This capability is not valid for a resource URI if shell operations are also supported.

Shell

Shell operations are supported on the resource URI. The SupportFragment attribute is not supported for shell operations and should be set to False. The SupportFiltering attribute is not valid and should be set to False. This capability is not valid for a resource URI if any other operation capability is also supported. If a shell operation capability is configured for a resource URI, then get, put, create, delete, invoke, and enumerate operations are processed internally within the WinRm service to manage shells. As a result, the plug-in cannot deal with the operations itself.

PlugInConfiguration/Resources/Resource/Security

This element defines the security descriptor (via the Sddl attribute) that should be applied to determine access to a particular resource URI (via the Uri attribute). If ExactMatch is not present, the Security element defaults to False, which means that the Sddl applies to all resource URIs that share Uri as a prefix. If ExactMatch is set to true, the Sddl applies only to the exact Uri specified. If there are multiple Security entries that could apply to a particular resource URIs, the longest-prefix match is used to determine the appropriate Sddl. As a result of the longest-prefix match, if an exact-match Uri entry exists, it will always be chosen as the appropriate Security element.

The following is the plug-in configuration schema specified as an XSD.

<?xml version="1.0" encoding="utf-8"?>
<xs:schema attributeFormDefault="unqualified" 
           elementFormDefault="qualified" 
           targetNamespace="http://schemas.microsoft.com/wbem/wsman/1/config/PluginConfiguration" 
           xmlns="http://schemas.microsoft.com/wbem/wsman/1/config/PluginConfiguration" 
           xmlns:xs="https://www.w3.org/2001/XMLSchema">
 <xs:element name="PlugInConfiguration">
  <xs:complexType>
   <xs:sequence>
    <xs:element name="InitializationParameters" minOccurs="0" maxOccurs="1">
     <xs:complexType>
      <xs:sequence>
       <xs:element name="Param">
        <xs:complexType>
         <xs:sequence></xs:sequence>
         <xs:attribute name="Name" type="xs:string"/>
         <xs:attribute name="Value" type="xs:string"/>
        </xs:complexType>
       </xs:element>
      </xs:sequence>
     </xs:complexType>
    </xs:element>
    <xs:element name="Resources">
     <xs:complexType>
      <xs:sequence>
       <xs:element minOccurs="1" maxOccurs="unbounded" name="Resource">
        <xs:complexType>
         <xs:sequence>
          <xs:element name="Capability" minOccurs="1" maxOccurs="unbounded">
           <xs:complexType>
            <xs:simpleContent>
             <xs:extension base="ResourceCapabilityType">
              <xs:attribute name="SupportsFragment" type="xs:boolean" use="optional" default="false"/>
              <xs:attribute name="SupportsFiltering" type="xs:boolean" use="optional" default="false"/>
              <xs:attribute name="Type" type="ResourceCapabilityType"/>
             </xs:extension>
            </xs:simpleContent>
           </xs:complexType>
          </xs:element>
          <xs:element name="Security" minOccurs="0" maxOccurs="unbounded">
           <xs:complexType>
            <xs:sequence></xs:sequence>
            <xs:attribute name="Uri" type="xs:string"/>
            <xs:attribute name="Sddl" type="xs:string"/>
            <xs:attribute name="ExactMatch" type="xs:boolean" use="optional" default="false"/>
           </xs:complexType>
          </xs:element>
         </xs:sequence>
         <xs:attribute name="ResourceUri" type="xs:string"/>
         <xs:attribute name="ExactMatch" type="xs:boolean" use="optional" default="false"/>
         <xs:attribute name="SupportOptions" type="xs:boolean" use="optional" default="false"/>
        </xs:complexType>
       </xs:element>
      </xs:sequence>
     </xs:complexType>
    </xs:element>
   </xs:sequence>
   <xs:attribute name="Filename" type="xs:token"/>
   <xs:attribute name="SDKVersion" type="xs:unsignedInt"/>
   <xs:attribute name="Name" type="xs:string"/>
   <xs:attribute name="XmlRenderingType" type="XmlRenderingTypeType" use="optional" default="text"/>
   <!--Architecture will default to 32 on x86 systems; 64 on 64-bit systems.-->
   <xs:attribute name="Architecture" type="ArchitectureType" use="optional" default="32"/>
  </xs:complexType>
 </xs:element>
 <xs:simpleType name="ResourceCapabilityType">
  <xs:restriction base="xs:token">
   <xs:enumeration value="Get"/>
   <xs:enumeration value="Put"/>
   <xs:enumeration value="Create"/>
   <xs:enumeration value="Delete"/>
   <xs:enumeration value="Invoke"/>
   <xs:enumeration value="Enumerate"/>
   <xs:enumeration value="Subscribe"/>
   <xs:enumeration value="Shell"/>
  </xs:restriction>
 </xs:simpleType>
 <xs:simpleType name="XmlRenderingTypeType">
  <xs:restriction base="xs:token">
   <xs:enumeration value="text"/>
   <xs:enumeration value="XmlReader"/>
  </xs:restriction>
 </xs:simpleType>
 <xs:simpleType name="ArchitectureType">
  <xs:restriction base="xs:token">
   <xs:enumeration value="32"/>
   <xs:enumeration value="64"/>
  </xs:restriction>
 </xs:simpleType>
</xs:schema>