Introduction to WinRM PowerShell
WinRm stands for Windows Remote Management protocol. This protocol is used for establishing a connection between computers so that remote operations can be performed. To enable PowerShell remoting first the Enable-PSRemoting cmdlet must be run on both the source and the destination computers. This will start the WinRM service and creates a firewall rule so that requests can be sent and received on computers to perform remote operations. Once the service is started listeners must be created.
Syntax:
The WinRM service is started by running the following cmdlet
Enable-PSRemoting
It is available in the namespace Microsoft.WsMan.Management and the corresponding assembly is System.Management.Automation. There are many cmdlets available related to WInRM management.
Various Classes of WinRm in PowerShell
This article will cover detail about the WinRM in Powershell along with the various classes that are implemented by PowerShell.
1. Connect-WSMan
This cmdlet establishes a connection to the WinRM service in the remote computer. If the client and server are present in different domain credentials must be provided explicitly. This establishes a persistent connection. This is generally used when a WSMan provider is used for establishing a connection to a remote computer.
Syntax:
Connect-WSMan [[-ComputerName] <string>] [-ApplicationName <string>] [-OptionSet <hashtable>] [-Port <int>] [-SessionOption <SessionOption>] [-UseSSL]
[-Credential <pscredential>] [-Authentication {None | Default | Digest | Negotiate | Basic | Kerberos | ClientCertificate | Credssp}] [-CertificateThumbprint
<string>] [<CommonParameters>]
Connect-WSMan [-ConnectionURI <uri>] [-OptionSet <hashtable>] [-Port <int>] [-SessionOption <SessionOption>] [-Credential <pscredential>] [-Authentication
{None | Default | Digest | Negotiate | Basic | Kerberos | ClientCertificate | Credssp}] [-CertificateThumbprint <string>] [<CommonParameters>]
Example:
Connect-WSMan -ComputerName "testserver01"
2. Disconnect-WSMan
This cmdlet is used to disconnect the WinRm service on the remote system. If the session is stored in a variable, only the state of the WS-Management session is closed.
Syntax:
Disconnect-WSMan [[-ComputerName] <String> [<CommonParameters>]
Example:
Disconnect-WSMan -computer testserver01
3. Enable-WSManCredSSP
This cmdlet is used to enable the Credssp authentication mechanism on the desired system. This is used when the cmdlets run creates a remote session from another session. When this mechanism is used, the user credentials are used for authentication. Whenever a background job needs to be run, this cmdlet can be used.
Syntax:
Enable-WSManCredSSP [-Role] <String> [[-DelegateComputer] <String[]>] [-Force] [<CommonParameters>]
Example:
Enable-WSManCredSSP -Role "Client" -DelegateComputer "testServer02.test.com"
4. Disable-WSManCredSSP
This cmdlet is used to disable the Credssp authentication mechanism on the desired system. When this mechanism is used, the user credentials are used for authentication. Whenever a background job needs to be run, this cmdlet can be used. To disable on the client, specify role as a client to disable on server specify role as a server.
Syntax:
Disable-WSManCredSSP [-Role] <String>[<CommonParameters>]
Example:
Disable-WSManCredSSP -Role Client
The above cmdlet disables the credssp on the client machine
Disable-WSManCredSSP -Role Client
The above cmdlet disables the credssp on the server machine.
5. Get-WSManCredSSP
This cmdlet is used to get the credential security support provider that is present in the client computer or the server. The output denotes whether the authentication is enabled or disabled. This also displays information about allow fresh credentials.
Syntax:
Get-WSManCredSSP []
Example:
Get-WSManCredSSP
If the credssp is not enabled, a message saying the machine is not configured will be displayed.
6. Get-WSManInstance
This cmdlet is used to find out the management resource that is defined by a uniform resource identifier. The output is either in the form of a complex xml or an object. It uses a connection or transport layer of WS- Management connection to retrieve the information.
Syntax:
Get-WSManInstanc[-ApplicationName <String>][-BasePropertiesOnly] [-ComputerName <String>] [-ConnectionURI <Uri>] [-Dialect <Uri>] [-Enumerate] [-Filter <String>] [-OptionSet <Hashtable>] [-Port <Int32>] [-Associations] [-ResourceURI] <Uri> [-ReturnType <String>] [-SessionOption <SessionOption>] [-Shallow] [-UseSSL] [-Credential <PSCredential>] [-Authentication <AuthenticationMechanism> [-CertificateThumbprint <String> [<CommonParameters>]
Example:
Get-WSManInstance -ResourceURI wmicimv2/win32_service -SelectorSet @{name="winrm"} -ComputerName "testServer01"
7. Invoke-WSManAction
This provokes an action on an object that is denoted by uri. The parameters are supplied as key value pairs. It uses the transport layer to perform the action.
Syntax:
Invoke-WSManAction[-Action] <String>[-ConnectionURI <Uri>][-FilePath <String>] [-OptionSet <Hashtable>] [[-SelectorSet] <Hashtable>] [-SessionOption <SessionOption>] [-ValueSet <Hashtable>] [-ResourceURI] <Uri> [-Credential <PSCredential>] [-Authentication <AuthenticationMechanism> [-CertificateThumbprint <String>] [<CommonParameters>]
Example:
Invoke-WSManAction -Action startservice -ResourceURI wmicimv2/win32_service -SelectorSet @{name="spooler"} -Authentication default
8. New-WSManInstance
This cmdlet creates a new management resource’s instance. It uses a resource uri along with input file to create a new resource.
Syntax:
New-WSManInstance [-ConnectionURI <Uri>] [-FilePath <String>] [-OptionSet <Hashtable>] [-ResourceURI] <Uri> [-SelectorSet] <Hashtable> [-SessionOption <SessionOption>] [-ValueSet <Hashtable>] [-Credential <PSCredential>] [-Authentication <AuthenticationMechanism>] [-CertificateThumbprint <String>][<CommonParameters>]
9. Ws-Management Enumerations
The following are the enumerations that are implemented in PowerShell. These are present in the software development kit.
10. New-WSManSessionOption
This creates a new hash table session option to be used as input for WS-Management cmdlets. These can be passed to as input to the following cmdlets.
- Get-WSManInstance
- Set-WSManInstance
- Invoke-WSManAction
- Connect-WSMan
Syntax:
New-WSManSessionOption [-ProxyAccessType <ProxyAccessType>] [-ProxyAuthentication <ProxyAuthentication>] [-ProxyCredential <PSCredential>] [-SkipCACheck] [-SkipCNCheck] [-SkipRevocationCheck] [-SPNPort <Int32>] [-OperationTimeout <Int32>] [-NoEncryption] [-UseUTF16][<CommonParameters>]
The proxy access type specifies the mechanism that is used to locate the server. Some of its values are ProxyIEConfig, ProxywinHttpConfig, ProxyAutoDetect and ProxyNoProxyServer. ProxyIeConfig is the default value.
The Proxy authentication parameter denotes the authentication mechanism that is used. The values to this parameter are Basic, Digest, and Negotiate. Negotiate is the default value.
Example:
$sess = New-WSManSessionOption -OperationTimeout 10000
Connect-WSMan -ComputerName "server01" -SessionOption $sess
Input:
Write-Host "Welcome to the WinRM demo"
Enable-PSRemoting
Write-Host "The winrm service is started" -ForegroundColor Green
Write-Host "Verify the listeners"
Get-WSManInstance -ResourceURI winrm/config/listener -SelectorSet @{Address="*";Transport="http"}
write-host "True"
Write-Host "Connecting to wim service in remote"
Connect-WSMan -ComputerName "testserver1"
Write-Host "Connected to the remote server"
Write-Host "Passing credentials to be used in remote server"
Enable-WSManCredSSP -Role "Client" -DelegateComputer "test.test.com"
Write-Host "disconnecting the session"
Disconnect-WSMan -computer testserver1
Write-Host "Session disconnected"
Output:
Conclusion
Thus, the article covered and explained in detail about the WinRM in PowerShell. It explained the various cmdlets that are available in the WinRM class and explained each of them with their appropriate syntax and examples. The article also showed on how to use various cmdlets to connect to the remote computer using the WinRM mechanism. To learn more in details it is advisable to write and practice sample programs.
Recommended Articles
This is a guide to WinRM PowerShell. Here we also discuss the introduction and various classes of WinRM in PowerShell along with different examples and its code implementation. You may also have a look at the following articles to learn more –
