Share via

Windows Remote Management Command-Line Tool (Winrm.cmd)

  • Article

Applies To: Windows Server 2003 R2

Windows Remote Management (WinRM) uses a new command-line tool, Winrm.cmd, to perform its operations. These operations include Get, Put, Invoke, and Enumerate. The command-line tool also has several switches to allow for remote operations, credentials, and hash tables. Winrm.cmd runs a script, Winrm.vbs, which is written in Visual Basic Scripting Edition.

Authentication mechanisms

The following authentication mechanisms are supported:

  • Basic

  • Digest [Client Only]

  • Negotiate

The Negotiate authentication mechanism allows authentication using Kerberos when using domain account, or NTLM when using local accounts.

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.

Negotiate is the default authentication mechanism if no authentication is specified in the command-line tool.

Specifying a Remote Machine

A remote machine can be specified using the –machine switch. When specifying the remote machine, the following are valid:

  • Localhost

  • NetBIOS name

  • Fully Qualified Domain Name (FQDN)

  • IP address

Using self-signed certificates

When using self-signed certificates on the server, the client should specify

–skipCAcheck in order to skip authentication of the Certificate Authority (CA) that issued the certificate. Note that this should be used only in lab environments due to the security risks.

When using certificates on the server that are issued to an entity other than the server hostname (for example, to the IP address), the client should specify –skipCNcheck to skip authentication of the Common Name (CN). Note that this should be used only in lab environments due to the security risks.

Note

Two switches can be used when communicating with a remote host: -skipCAcheck Specifies that the certificate issuer need not be a trusted root authority. Used only in remote operations. Note that this option should be used only for trusted machines. -skipCNcheck Specifies that certificate CN of the server need not match the hostname of the server. Used only in remote operations. Note that this option should be used only for trusted machines.

Another optional switch that can be used on the command line in conjunction with the –machine switch is the –port switch. The –port switch allows you to specify on which port the remote WinRM Listener service is listening for requests.

Note

When using the –machine switch, the name used needs to match the CN used in the Server Certificate on the remote system.

This example uses an FQDN to specify the remote machine:

winrm action uri -machine:server.acme.dom -port:443

Handling Hash Tables

As you’ll see in the following sections, both Put and Invoke operations require input to be supplied for the operation to succeed. There are a couple of different ways to supply this input. The first is by generating the input XML file and letting the command-line tool read the file using the –file switch. The second is by using a hash table.

A hash table is a method of supplying property names and their values. The Winrm command-line tool will then generate the input XML automatically.

Note

More than one key/value pair can be specified by placing a semicolon (;) between each pair (with no space). The quotation marks around the value are required.

When performing an Invoke operation that requires no input, an empty hash table is needed:

@{}

Note

The hash table must be the last item on the command line and must be preceded by a space. This is also true with using any other command-line switches, such as –machine. If a hash table is used, the switches must come before the hash table.

Output Format

The Winrm command–line tool allows the administrator to choose the type of output that is returned. There are three options:

-format:#xml
-format:#pretty
-format:#text

The default is text output. An example of each output format option is shown below for an enumeration of Win32_LogicalDisk.

Note

When redirecting the output to a file, Cmd.exe always saves the text as ANSI. When there are Unicode characters in the XML output, they cause the XML to be malformed. To prevent this, open the file in Notepad and save as Unicode. You can also write the output with a script using the XML Document Object Model, which saves the file as Unicode.

Raw XML

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

<wsman:Results>
<p:Win32_LogicalDisk xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance" xmlns:p="https://schemas.microsoft.org/root/cimv2/2004/07" __uri="wsman:microsoft.operatingsystem.wmi/root/cimv2/Win32_LogicalDisk?DeviceID=C:"><p:Access xsi:nil="true"/><p:Availability xsi:nil="true"/><p:BlockSize xsi:nil="true"/><p:Caption>C:</p:Caption><p:Compressed>false</p:Compressed><p:ConfigManagerErrorCode xsi:nil="true"/><p:ConfigManagerUserConfig xsi:nil="true"/><p:CreationClassName>Win32_LogicalDisk</p:CreationClassName><p:Description>Local Fixed Disk</p:Description><p:DeviceID>C:</p:DeviceID><p:DriveType>3</p:DriveType><p:ErrorCleared xsi:nil="true"/><p:ErrorDescription xsi:nil="true"/><p:ErrorMethodology xsi:nil="true"/><p:FileSystem>NTFS</p:FileSystem><p:FreeSpace>22935719936</p:FreeSpace><p:InstallDate xsi:nil="true"/><p:LastErrorCode xsi:nil="true"/><p:MaximumComponentLength>255</p:MaximumComponentLength><p:MediaType>12</p:MediaType><p:Name>C:</p:Name><p:NumberOfBlocks xsi:nil="true"/><p:PNPDeviceID xsi:nil="true"/><p:PowerManagementCapabilities xsi:nil="true"/><p:PowerManagementSupported xsi:nil="true"/><p:ProviderName xsi:nil="true"/><p:Purpose xsi:nil="true"/><p:QuotasDisabled>true</p:QuotasDisabled><p:QuotasIncomplete>true</p:QuotasIncomplete><p:QuotasRebuilding>false</p:QuotasRebuilding><p:Size>36880187392</p:Size><p:Status xsi:nil="true"/><p:StatusInfo xsi:nil="true"/><p:SupportsDiskQuotas>true</p:SupportsDiskQuotas><p:SupportsFileBasedCompression>true</p:SupportsFileBasedCompression><p:SystemCreationClassName>Win32_ComputerSystem</p:SystemCreationClassName><p:SystemName>MyMachine</p:SystemName><p:VolumeDirty>false</p:VolumeDirty><p:VolumeName>IBM_PRELOAD</p:VolumeName><p:VolumeSerialNumber>6440000C</p:VolumeSerialNumber></p:Win32_LogicalDisk>
<p:Win32_LogicalDisk xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance" xmlns:p="https://schemas.microsoft.org/root/cimv2/2004/07" __uri="wsman:microsoft.operatingsystem.wmi/root/cimv2/Win32_LogicalDisk?DeviceID=D:"><p:Access xsi:nil="true"/><p:Availability xsi:nil="true"/><p:BlockSize xsi:nil="true"/><p:Caption>D:</p:Caption><p:Compressed xsi:nil="true"/><p:ConfigManagerErrorCode xsi:nil="true"/><p:ConfigManagerUserConfig xsi:nil="true"/><p:CreationClassName>Win32_LogicalDisk</p:CreationClassName><p:Description>CD-ROM Disc</p:Description><p:DeviceID>D:</p:DeviceID><p:DriveType>5</p:DriveType><p:ErrorCleared xsi:nil="true"/><p:ErrorDescription xsi:nil="true"/><p:ErrorMethodology xsi:nil="true"/><p:FileSystem xsi:nil="true"/><p:FreeSpace xsi:nil="true"/><p:InstallDate xsi:nil="true"/><p:LastErrorCode xsi:nil="true"/><p:MaximumComponentLength xsi:nil="true"/><p:MediaType>11</p:MediaType><p:Name>D:</p:Name><p:NumberOfBlocks xsi:nil="true"/><p:PNPDeviceID xsi:nil="true"/><p:PowerManagementCapabilities xsi:nil="true"/><p:PowerManagementSupported xsi:nil="true"/><p:ProviderName xsi:nil="true"/><p:Purpose xsi:nil="true"/><p:QuotasDisabled xsi:nil="true"/><p:QuotasIncomplete xsi:nil="true"/><p:QuotasRebuilding xsi:nil="true"/><p:Size xsi:nil="true"/><p:Status xsi:nil="true"/><p:StatusInfo xsi:nil="true"/><p:SupportsDiskQuotas xsi:nil="true"/><p:SupportsFileBasedCompression xsi:nil="true"/><p:SystemCreationClassName>Win32_ComputerSystem</p:SystemCreationClassName><p:SystemName> MyMachine </p:SystemName><p:VolumeDirty xsi:nil="true"/><p:VolumeName xsi:nil="true"/><p:VolumeSerialNumber xsi:nil="true"/></p:Win32_LogicalDisk>
</wsman:Results>

Pretty Formatting

This option displays XML in indented format. A four-character indentation is used for displaying nested XML elements. Internet Explorer can also be used to display in this format from raw XML output.

<cfg:Config xmlns:cfg="wsman:microsoft.com/wsman/2005/02/config.xsd">
    <cfg:MaxEnvelopeSizekb>50</cfg:MaxEnvelopeSizekb>
    <cfg:MaxTimeoutms>60000</cfg:MaxTimeoutms>
    <cfg:MaxBatchItems>5</cfg:MaxBatchItems>
    <cfg:SoapTraceEnabled>true</cfg:SoapTraceEnabled>
    <cfg:MaxProviderRequests>25</cfg:MaxProviderRequests>
    <cfg:Client>
        <cfg:NetworkDelayms>5000</cfg:NetworkDelayms>
        <cfg:HTTPS>
            <cfg:Port>443</cfg:Port>
            <cfg:URLPrefix>wsman</cfg:URLPrefix>
        </cfg:HTTPS>
    </cfg:Client>
    <cfg:Service>
        <cfg:RootSDDL>O:NSG:BAD:P(A;;GA;;;BA)S:P(AU;SAFA;GWGX;;;WD)
        </cfg:RootSDDL>
        <cfg:MaxConcurrentOperations>100</cfg:MaxConcurrentOperations>
        <cfg:EnumerationTimeoutms>60000</cfg:EnumerationTimeoutms>
        <cfg:MaxClientCertInfoSize>16384</cfg:MaxClientCertInfoSize>
        <cfg:HTTPS>
            <cfg:MaxConnections>50</cfg:MaxConnections>
        </cfg:HTTPS>
    </cfg:Service>
</cfg:Config>

Text Formatting

The command-line tool supports basic text formatting of output XML. A four-character indentation is used for displaying nested elements.

Win32Logical_Disk
    DeviceID = C:
    Access = NULL
    Availability = NULL
    BlockSize = NULL
    Caption = C:
    Compressed = false

Win32Logical_Disk
    DeviceID = D:
    Access = NULL
    Availability = NULL
    BlockSize = NULL
    Caption = D:
    Compressed = false

URI Aliases

URI aliases can simplify the Winrm command line. The following URI aliases are supported:

wmi = https://schemas.microsoft.com/wsman/2005/06/wmi
wsman = wsman:microsoft.com/wsman/2005/06/
cimv2.9 = https://schemas.dmtf.org/wsman/2005/06/cimv2.9
cimv2 = https://schemas.microsoft.com/wsman/2005/06/wmi/root/cimv2

For example, the following command:

winrm get https://schemas.microsoft.com/wsman/2005/06/wmi/root/cimv2/Win32_Service?Name=WSMan

Gets replaced with:

winrm get wmi/root/cimv2/Win32_Service?Name=WinRM

Performing a Get Operation

The WS-Management Get operation returns the value of a specific WMI object. In this example, WS-Management retrieves the properties of the Alerter service:

winrm get https://schemas.microsoft.com/wsman/2005/06/wmi/root/cimv2/win32_service?name=Alerter

If this operation completes successfully, an XML result similar to the following is returned:

<p:win32_service xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance" xmlns:p="https://schemas.microsoft.com/wsman/2005/06/wmi/root/cimv2">
  <p:AcceptPause>false</p:AcceptPause>
  <p:AcceptStop>false</p:AcceptStop>
  <p:Caption>Alerter</p:Caption>
  <p:CheckPoint>0</p:CheckPoint>
  <p:CreationClassName>Win32_Service</p:CreationClassName>
  <p:Description>Notifies selected users and computers of administrative alerts. If the service is stopped, programs that use administrative alerts will not receive them. If this service is disabled, any services that explicitly depend on it will fail to start.</p:Description>
  <p:DesktopInteract>false</p:DesktopInteract>
  <p:DisplayName>Alerter</p:DisplayName>
  <p:ErrorControl>Normal</p:ErrorControl>
  <p:ExitCode>1077</p:ExitCode>
  <p:InstallDate xsi:nil="true"/>
  <p:Name>Alerter</p:Name>
  <p:PathName>C:\WINDOWS\System32\svchost.exe -k LocalService</p:PathName>
  <p:ProcessId>0</p:ProcessId>
  <p:ServiceSpecificExitCode>0</p:ServiceSpecificExitCode>
  <p:ServiceType>Share Process</p:ServiceType>
  <p:Started>false</p:Started>
  <p:StartMode>Disabled</p:StartMode>
  <p:StartName>NT AUTHORITY\LocalService</p:StartName>
  <p:State>Stopped</p:State>
  <p:Status>OK</p:Status>
  <p:SystemCreationClassName>Win32_ComputerSystem</p:SystemCreationClassName>
  <p:SystemName>Host</p:SystemName>
  <p:TagId>0</p:TagId>
  <p:WaitHint>0</p:WaitHint>
  <cim:Location xmlns:cim="https://schemas.dmtf.org/wsman/2005/02/base">
    <wsa:EndpointReference xmlns:wsa="https://schemas.xmlsoap.org/ws/2004/08/addressing" xmlns:wsman="https://schemas.xmlsoap.org/ws/2005/02/management">    <wsa:Address>https://schemas.xmlsoap.org/ws/2004/08/addressing/role/anonymous?ResourceURI=(https://schemas.microsoft.com/wsman/2005/02/wmi/root/cimv2/Win32_Service)</wsa:Address>
      <wsa:ReferenceParameters>
        <wsman:SelectorSet>
          <wsman:Selector Name="Name">Alerter</wsman:Selector>
        </wsman:SelectorSet>
      </wsa:ReferenceParameters>
    </wsa:EndpointReference>
  </cim:Location>
</p:win32_service>

Performing a Put Operation

The WS-Management Put operation allows the values of keys to be set. In this example, the value of the MaxEnvelopeSizekb key is configured:

winrm put wsman:microsoft.com/wsman/2005/06/Config @{MaxEnvelopeSizekb="100"}

If the key is modified successfully, the configuration with the new value(s) will be returned in the result XML:

<cfg:Config xmlns:cfg="wsman:microsoft.com/wsman/2005/06/config.xsd">
  <cfg:MaxEnvelopeSizekb>100</cfg:MaxEnvelopeSizekb>
  <cfg:MaxTimeoutms>60000</cfg:MaxTimeoutms>
  <cfg:MaxBatchItems>20</cfg:MaxBatchItems>
  <cfg:SoapTraceEnabled>false</cfg:SoapTraceEnabled>
  <cfg:MaxProviderRequests>25</cfg:MaxProviderRequests>
  <cfg:Client>
    <cfg:NetworkDelayms>5000</cfg:NetworkDelayms>
    <cfg:HTTPS>
      <cfg:Port>443</cfg:Port>
      <cfg:URLPrefix>wsman</cfg:URLPrefix>
    </cfg:HTTPS>
  </cfg:Client>
  <cfg:Service>
    <cfg:RootSDDL>O:NSG:BAD:P(A;;GA;;;BA)S:P(AU;SAFA;GWGX;;;WD)</cfg:RootSDDL>
    <cfg:MaxConcurrentOperations>100</cfg:MaxConcurrentOperations>
    <cfg:EnumerationTimeoutms>60000</cfg:EnumerationTimeoutms>
    <cfg:MaxClientCertInfoSize>16384</cfg:MaxClientCertInfoSize>
    <cfg:HTTPS>
      <cfg:MaxConnections>50</cfg:MaxConnections>
    </cfg:HTTPS>
  </cfg:Service>
</cfg:Config>

If the key cannot be modified, Fault XML similar to the XML below is returned:

<f:WSManFault xmlns:f="https://schemas.microsoft.com/ws/2005/06/wsmanfault" Code="32833" Machine="AMD64-R3-10">
  <f:Message>
    <f:ProviderFault providerId="A855B0EE-65C2-4282-830B-7FA181E73BFF">
      <f:WSManFault xmlns:f="https://schemas.microsoft.com/ws/2005/02/wsmanfault" Code="32833" Machine="">
        <f:Message>Input xml contained an unrecognized xml element "MaxEnvelopeSizeKb".  Double check the spelling and case of the element name.</f:Message>
      </f:WSManFault>
    </f:ProviderFault>
  </f:Message>
</f:WSManFault>

Error number: -2146992063 0x80078041
The supplied SOAP violates the corresponding XML schema definition.

Performing an Enumerate Operation

The WS-Management Enumerate operation returns a collection of objects. In this example, the command returns all the services that exist on the computer, using the Win32_Service WMI class:

winrm enumerate https://schemas.microsoft.com/wsman/2005/02/wmi/root/cimv2/Win32_Service

This returns XML data for each service within the enumeration. The result is similar to the Get example, except that the information for all the services is returned, rather than a single service. For example, output XML is returned for each service instance in the enumeration. Below is an example of one such instance:

<wsman:Results xmlns:wsman="https://schemas.microsoft.com/ws/2005/03/wsman/results">
  <p:win32_service xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance" xmlns:p="https://schemas.microsoft.com/wsman/2005/06/wmi/root/cimv2">
    <p:AcceptPause>false</p:AcceptPause>
    <p:AcceptStop>false</p:AcceptStop>
    <p:Caption>Alerter</p:Caption>
    <p:CheckPoint>0</p:CheckPoint>
    <p:CreationClassName>Win32_Service</p:CreationClassName>
    <p:Description>Notifies selected users and computers of administrative alerts. If the service is stopped, programs that use administrative alerts will not receive them. If this service is disabled, any services that explicitly depend on it will fail to start.</p:Description>
    <p:DesktopInteract>false</p:DesktopInteract>
    <p:DisplayName>Alerter</p:DisplayName>
    <p:ErrorControl>Normal</p:ErrorControl>
    <p:ExitCode>1077</p:ExitCode>
    <p:InstallDate xsi:nil="true"/>
    <p:Name>Alerter</p:Name>
    <p:PathName>C:\WINDOWS\System32\svchost.exe -k LocalService</p:PathName>
    <p:ProcessId>0</p:ProcessId>
    <p:ServiceSpecificExitCode>0</p:ServiceSpecificExitCode>
    <p:ServiceType>Share Process</p:ServiceType>
    <p:Started>false</p:Started>
    <p:StartMode>Disabled</p:StartMode>
    <p:StartName>NT AUTHORITY\LocalService</p:StartName>
    <p:State>Stopped</p:State>
    <p:Status>OK</p:Status>
    <p:SystemCreationClassName>Win32_ComputerSystem</p:SystemCreationClassName>
    <p:SystemName>Host</p:SystemName>
    <p:TagId>0</p:TagId>
    <p:WaitHint>0</p:WaitHint>
    <cim:Location xmlns:cim="https://schemas.dmtf.org/wsman/2005/02/base">
      <wsa:EndpointReference xmlns:wsa="https://schemas.xmlsoap.org/ws/2004/08/addressing" xmlns:wsman="https://schemas.xmlsoap.org/ws/2005/02/management">
        <wsa:Address>https://schemas.xmlsoap.org/ws/2004/08/addressing/role/anonymous?ResourceURI=(https://schemas.microsoft.com/wsman/2005/02/wmi/root/cimv2/Win32_Service)</wsa:Address>
        <wsa:ReferenceParameters>
          <wsman:SelectorSet>
            <wsman:Selector Name="Name">Alerter</wsman:Selector>
          </wsman:SelectorSet>
        </wsa:ReferenceParameters>
      </wsa:EndpointReference>
    </cim:Location>
  </p:win32_service>
</wsman:Results>

Performing an Invoke Operation

The WS-Management Invoke operation executes methods on the target objects. In this example, Winrm starts the Alerter service using the StartService WMI method:

winrm invoke StartService https://schemas.microsoft.com/wsman/2005/06/wmi/root/cimv2/Win32_Service?Name=Alerter @{}

Once this operation has executed, the return value is returned in the XML result:

<p:StartService_OUTPUT xmlns:p="https://schemas.microsoft.com/wsman/2005/06/wmi/root/cimv2">
  <p:_ReturnValue>0</p:_ReturnValue>
</p:StartService_OUTPUT>>