WSMan Enhancements in PowerShell 2.0
WSMan Enhancements in PowerShell 2.0
Windows PowerShell 2.0 makes it easy to retrieve WSMan specific Management information in an intuitive, discoverable and script friendly manner.
Variety of tasks such as configuring a machine for remote management to connecting to WinRM service on a machine and managing resources both in-band and out-of-band can be performed.
Available WSMan specific cmdlets can be categorized in two buckets:
· Cmdlets for Performing WSMan Operations:
o Test-WSMan
o Get-WSManInstance
o Set-WSManInstance
o New-WSManInstance
o Remove-WSManInstance
o Invoke-WSManAction
· Cmdlets for Configuring WSMan Session:
o Connect-WSMan
o Disconnect-WSMan
o New-WSManSessionOption
o Set-WSManQuickConfig
o Get-WSManCredSSP
o Enable-WSManCredSSP
o Disable-WSManCredSSP
Running "help *wsman*" in PowerShell 2.0 console provides a list of WSMan PowerShell Cmdlets.
Detail help, documentation and examples can be obtained by running "help <cmdlet name>".
Here is more detail information, including examples:
Test-WSMan
Tests whether the WinRM service is running on a local or remote computer.
The cmdlet submits an identification request that determines whether the WinRM service is running on a local or remote computer. If the tested computer is running the service, the cmdlet displays the WS-Management identity schema, the protocol version, the product vendor, and the product version of the tested service.
C:\PS>test-wsman -computername server01 -authentication default
wsmid : https://schemas.dmtf.org/wbem/wsman/identity/1/wsmanidentity.xsd
ProtocolVersion : https://schemas.dmtf.org/wbem/wsman/1/wsman.xsd
ProductVendor : Microsoft Corporation
ProductVersion : OS: 6.1.7021 SP: 0.0 Stack: 2.0
-----------
This command tests to see if the WinRM service is running on the computer named server01 using the authentication parameter.
Using the authentication parameter allows the Test-WSMan cmdlet to return the operating system version.
Get-WSManInstance
Displays management information for a resource instance specified by a Resource URI.
The cmdlet retrieves an instance of a management resource that is specified by a resource URI.
The information that is retrieved can be a complex XML information set (an object) or a simple value.
This cmdlet is the equivalent to the standard WS-Management Get command.
This cmdlet uses the WSMan connection/transport layer to retrieve information.
C:\PS>Get-WSManInstance -Enumerate wmicimv2/* -filter "select * from win32_service where StartMode = 'Auto' and State = 'Stopped'" -computername server01
xsi : https://www.w3.org/2001/XMLSchema-instance
p : https://schemas.microsoft.com/wbem/wsman/1/wmi/root/cimv2/Win32\_Service
cim : https://schemas.dmtf.org/wbem/wscim/1/common
type : p:Win32_Service_Type
lang : en-US
AcceptPause : false
AcceptStop : false
Caption : Windows Media Center Service Launcher
CheckPoint : 0
CreationClassName : Win32_Service
Description : Starts Windows Media Center Scheduler and Windows Media Center Receiver services at startup if TV is enabled within Windows Media Center.
DesktopInteract : false
DisplayName : Windows Media Center Service Launcher
ErrorControl : Ignore
-----------
This command lists all of the services that meet the following criteria on the remote server01 computer:
- The startup type of the service is "Automatic".
- The service is stopped.
Set-WSManInstance
Modifies the management information that is related to a resource.
C:\PS>set-wsmaninstance -resourceuri winrm/config -valueset @{maxenvelopsizekb=200}
-----------
This command modifies a WS-Management configuration property "maxenvelopsizekb" on a machine.
New-WSManInstance
This cmdlet creates a new instance of a management resource.
It uses a resource URI and a value set or input file to create the new instance of the management resource.
C:\PS>New-WSManInstance winrm/config/Listener -SelectorSet @{Transport=HTTPS} -ValueSet @{Hostname="HOST";CertificateThumbprint="XXXXXXXXXX"}
-----------
This command creates an instance of a WinRM HTTPS listener on all IP addresses.
Remove-WSManInstance
The Remove-WSManInstance deletes an instance of a management resource that is specified in the ResourceURI and SelectorSet parameters.
C:\PS>Remove-WSManInstance winrm/config/Listener -SelectorSet Address=test.Server.com;Transport=http
-----------
Delete the http listener on a remote machine.
Invoke-WSManAction
Invokes an action on the object that is specified by the Resource URI and by the selectors
(parameters specified by key value pairs)
C:\PS>invoke-wsmanaction -action create -resourceuri wmicimv2/win32_process -valueset @{commandline="notepad.exe";currentdirectory="C:\"}
xsi : https://www.w3.org/2001/XMLSchema-instance
p : https://schemas.microsoft.com/wbem/wsman/1/wmi/root/cimv2/Win32\_Process
cim : https://schemas.dmtf.org/wbem/wscim/1/common
lang : en-US
ProcessId : 6356
ReturnValue : 0
-----------
This command calls the Create method of the Win32_Process class. It passes the method two parameter values, Notepad.exe and "C:\". As a result, a new process is created to run Notepad, and the current directory of the new process is set to "C:\".
Connect-WSMan
The Connect-WSMan cmdlet connects to the WinRM service on a remote computer, and it establishes a persistent connection to the remote computer. You can use this cmdlet within the context of the WSMan provider to connect to the WinRM service on a remote computer.
However, you can also use this cmdlet to connect to the WinRM service on a remote computer before you change to the WSMan provider. The remote computer will appear in the root directory of the WSMan provider.
C:\PS>Connect-WSMan -computer server01
PS C:\Users\testuser> cd wsman:
PS WSMan:\>
PS WSMan:\> dir
WSManConfig: Microsoft.WSMan.Management\WSMan::WSMan
ComputerName Type
------------ ----
localhost Container
server01 Container
-----------
This command creates a connection to the remote server01 computer.
The Connect-WSMan cmdlet is generally used within the context of the WSMan provider to connect to a remote computer, inthis case the server01 computer. However, you can use the cmdlet to establish connections to remote computers before you change to the WSMan provider. Those connections will appear in the ComputerName list.
Disconnect-WSMan
The Disconnect-WSMan cmdlet disconnects the client from the WinRM service on a remote computer.
If you saved the WSMan session in a variable, the session object remains in the variable, but the state of the WSMan session is "Closed". You can use this cmdlet within the context of the WSMan provider to disconnect the client from the WinRM service on a remote computer. However, you can also use this cmdlet to disconnect from the WinRM service on remote computers before you change to the WSMan provider.
C:\PS>Disconnect-WSMan -computer server01
C:\PS> cd WSMan:
PS WSMan:\>
PS WSMan:\> dir
WSManConfig: Microsoft.WSMan.Management\WSMan::WSMan
ComputerName Type
------------ ----
localhost Container
-----------
This command deletes the connection to the remote server01 computer.
New-WSManSessionOption
This cmdlet can be used to configure session specifc WSMan settings.
An example would be to provide one set of credentials to a proxy or gateway and another to the endpoint to which a connection is being established
New-WSManSessionOption -ProxyAuthentication Basic -ProxyPassword abc123 -ProxyUserName SomeUser -UseIEProxyconfig
Set-WSManQuickConfig
The Set-WSManQuickConfig cmdlet configures the computer to receive PowerShell remote commands that are sent by using WSMan
The cmdlet performs the following:
1. Checks whether the WinRM service is running. If the WinRM service is not running, the service is started.
2. Sets the WinRM service startup type to automatic.
3. Creates a listener to accept requests on any IP address. By default, the transport is HTTP.
4. Enables a firewall exception for WSMan traffic .
Run the cmdlet in an elevated console for Vista/Windows Server 2008 and later versions of Windows
C:\PS>Set-WSManQuickConfig
-----------
This command sets the required configuration to enable remote management of the local computer.
By default, this command creates a WinRM listener on HTTP.
CredSSP Related Cmdlets:
Get-WSManCredSSP
Enable-WSManCredSSP
Disable-WSManCredSSP
These cmdlets are used to Get/Enable/Disable Credential Security Service Provider-related configuration on the client/Server
This type of authentication is designed for commands that create a remote session from within another remote session.
For example, you use this type of authentication if you want to run a background job on a remote computer.
One point of Caution: CredSSP authentication delegates the user's credentials from the local computer to a remote computer. This practice increases the security risk of the remote operation. If the remote computer is compromised, when credentials are passed to it, the credentials can be used to control the network session.
Examples:
C:\PS>get-wsmancredssp
This command displays CredSSP configuration information for both the client and server.
The output identifies that this computer is or is not configured for CredSSP.
This is the output, if the computer is configured for CredSSP.
The machine is configured to allow delegating fresh credentials to the following target(s): wsman/server02.accounting.company.com
This is the output, if the computer is not configured for CredSSP.
The machine is not configured to allow delgating fresh credentials.
C:\PS>enable-wsmancredssp -role client -delegatecomputer *.accounting.company.com
cfg : https://schemas.microsoft.com/wbem/wsman/1/config/client/auth
lang : en-US
Basic : true
Digest : true
Kerberos : true
Negotiate : true
Certificate : true
CredSSP : true
-----------
This command allows the client credentials to be delegated to all the computers in the accounting.company.com domain.
C:\PS>Disable-WSManCredSSP -Role Server
This command disables CredSSP on the server, which prevents delegation from clients.