PowerShell - Remoting

The Windows PowerShell remoting features are supported by the WS-Management protocol and the Windows Remote Management (WinRM) service that implements WS-Management in Windows. Computers running Windows 7 and later include WinRM 2.0 or later. On computers running earlier versions of Windows, you need to install WinRM 2.0 or later as appropriate and if supported. Currently, remoting is supported on Windows Vista with Service Pack 1 or later, Windows 7, Windows Server 2008, and Windows Server 2008 Release 2.

Enable Remoting

You can verify the availability of WinRM and configure a PowerShell for remoting by following these steps:

1. Start Windows PowerShell as an administrator by right-clicking the Windows PowerShell shortcut and selecting Run As Administrator.

2. The WinRM service is configured for manual startup by default. You must change the startup type to Automatic and start the service on each computer you want to work with. At the PowerShell prompt, you can verify that the WinRM service is running using the following command:

   get-service winrm

   The value of the Status property in the output should be Running. 3. To configure Windows PowerShell for remoting, type the following command:

   Enable-PSRemoting -force

In many cases, you will be able to work with remote computers in other domains. However, if the remote computer is not in a trusted domain, the remote computer might not be able to authenticate your credentials. To enable authentication, you need to add the remote computer to the list of trusted hosts for the local computer in WinRM. To do so, type:

winrm s winrm/config/client '@{TrustedHosts="RemoteComputer"}'

When you are working with computers in workgroups or homegroups, you must either use HTTPS as the transport or add the remote machine to the TrustedHosts configuration settings. If you cannot connect to a remote host, verify that the service on the remote host is running and is accepting requests by running the following command on the remote host:

winrm quickconfig

This command analyses and configures the WinRM service.

To use Windows PowerShell remoting features, you must start Windows PowerShell as an administrator by right-clicking the Windows PowerShell shortcut and selecting Run As Administrator. When starting PowerShell from another program, such as the command prompt (cmd.exe), you must start that program as administrator.

One way of getting the advantage of Group Policy is to deploy a logon script. The script is a single line, saved in a .ps1 file:

Enable-PSRemoting -Force

Remoting Commands

You can work with remote computers using the following remoting cmdlets:

• Invoke-Command Runs commands on a local computer or one or more remote computers, and returns all output from the commands, including errors. To run a single command on a remote computer, use the -ComputerName parameter. To run a series of related commands that share data, create a PowerShell session (PSSession) on a remote computer, and then use the -Session parameter of Invoke-Command to run the command in the PSSession.
• New-PSSession Creates a PowerShell session (PSSession) on a local or remote computer. When you create a PSSession, Windows PowerShell establishes a persistent connection to the remote computer, and you can use the PSSession to interact directly with the computer.

• Get-PSSession Gets the PowerShell sessions (PSSessions) that were created in the current session. Without parameters, this cmdlet returns all of the PSSessions created in the current session. You can use the parameters of Get-PSSession to get the sessions that are connected to particular computers or identify sessions by their names, IDs, or instance IDs. For computers, type the NetBIOS name, IP address, or fully qualified domain name. To specify the local computer, type the computer name, localhost, or a dot (.). For IDs, type an integer value that uniquely identifies the PSSession in the current session. PSSessions can be assigned friendly names with the -Name parameter. You can specify the friendly names using wildcards. To find the names and IDs of PSSessions, use Get-PSSessionwithout parameters. An instance ID is a GUID that uniquely identifies a PSSession, even when you have multiple sessions running in PowerShell. The instance ID is stored in the RemoteRunspaceID property of the RemoteRunspaceInfo object that represents a PSSession. To find the InstanceID of the PSSessions in the current session, type:

  get-pssession | Format-Table Name, ComputerName, RemoteRunspaceId

• Enter-PSSession Starts an interactive session with a single remote computer. During the session, you can run commands just as if you were typing directly on the remote computer. You can have only one interactive session at a time. Typically, you use the -ComputerName parameter to specify the name of the remote computer. However, you can also use a session that you created previously by using New-PSSession for the interactive session.

• Exit-PSSession Ends an interactive session and disconnects from the remote computer. You can also type exit to end an interactive session. The effect is the same as using Exit-PSSession.
• Import-PSSession Imports cmdlets, aliases, functions, and other command types from an open session on a local or remote computer into the current session. You can import any command that Get-Command can find in the other session. To import commands, first use New-PSSession to connect to the session from which you will import. Then use Import-PSSession to import commands. By default, Import-PSSession imports all commands except for commands that exist in the current session. To overwrite a command, specify the command in the -CommandName parameter. PowerShell adds the imported commands to a temporary module that exists only in your session, and it returns an object that represents the module. Although you can use imported commands just as you would use any command in the session, the imported part of the command actually runs in the session from which it was imported. Because imported commands might take longer to run than local commands, Import-PSSession adds an -AsJob parameter to every imported command. This parameter allows you to run the command as a PowerShell background job.
• Export-PSSession Gets cmdlets, functions, aliases, and other command types from an open session on a local or remote computer, and saves them in a Windows PowerShell script module file (.psm1). When you want to use the commands from the script module, use the Add-Module cmdlet to add the commands to the local session so that they can be used. To export commands, first use New-PSSession to connect to the session that has the commands that you want to export. Then use Export-PSSession to export the commands. By default, Export-PSSession exports all commands except for commands that already exist in the session. However, you can still use the -PSSnapin, -CommandName, and -CommandType parameters to specify the commands to export.

Invoking Remote Commands

One way to run commands on remote computers is to use the Invoke-Command cmdlet. With this cmdlet, you can do the following:

• Use the -ComputerName parameter to specify the remote computers to work with by DNS name, NetBIOS name, or IP address.
• When working with multiple remote computers, separate each computer name or IP address with a comma.
• Enclose your command or commands to execute in curly braces, which denotes a script block, and use the -ScriptBlock parameter to specify the command or commands to run.

After completing any of the preceding actions, you can type the following command as a single line to run a Get-Process command remotely:

invoke-command -computername Server4, Server2, Server8 -scriptblock \`
{get-process}

By default, Invoke-Command runs under your user name and credentials. Use the -Credential parameter to specify alternate credentials, such as UserName or Domain\UserName. You will be prompted for a password.

Invoking Sessions

You can establish a local or remote session to create a persistent connection using the New-PSSession cmdlet. Unless you use the -ComputerName parameter and use it to specify the name of one or more remote computers, PowerShell assumes you are creating a session for the local computer. With New-PSSession, you must use the -Session parameter with Invoke-Command to run the command in the named session.

For example, you can establish a session by typing the following command:

$s = new-PSSession -computername Server24

Here, $s is a variable that sets the name of the session. Because you've used the -ComputerName parameter, PowerShell knows you are creating a remote session rather than a local session. PowerShell creates a persistent connection with the specified computer. You can then use Invoke-Command with the -Session parameter to run the command in the named session as shown in this example:

invoke-command -session $s -scriptblock {get-process}

You can just as easily establish a session with multiple computers. Simply establish the session and name all the computers. Generally, you might also need to specify your credentials using the -Credential parameter.

Sometimes, you'll want to execute an application or external utility on remote computers as shown in the following example:

$comp = get-content c:\\computers.txt
$s = new-pssession -computername $comp
invoke-command -session $s { powercfg.exe -energy }

Here, C:\Computers.txt is the path to the file containing the list of remote computers to check. On each computer, you run PowerCfg with the -Energy parameter. This generates an Energy-Report.html file in the default directory for the user account used to access the computer.

Working Remotely Without WinRM

Some cmdlets have a -ComputerName parameter that lets you work with a remote computer without using Windows PowerShell remoting. This means you can use the cmdlet on any computer that is running Windows PowerShell, even if the computer is not configured for Windows PowerShell remoting. These cmdlets include the following:

Add-Computer                    Clear-EventLog          Get-Counter
Get-EventLog                    Get-HotFix              Get-Process
Get-Service                     Get-WinEvent            Get-WmiObject
Limit-EventLog                  New-EventLog            Remove-Computer
Remove-EventLog                 Rename-Computer         Restart-Computer
Reset-ComputerMachinePassword   Set-Service             Show-EventLog
Stop-Computer                   Write-EventLog

Because these cmdlets don't use remoting, you can run any of these cmdlets on a remote computer in a domain simply by specifying the name of one or more remote computers in the -ComputerName parameter. However, Windows policies and configuration settings must allow remote connections, and you must still have the appropriate credentials.