ABOUT_REMOTE


Short description

Describes how to run remote commands in PowerShell.


Long description

You can run remote commands on a single or multiple remote computers using
a temporary or persistent connection. You can also start an interactive
session with a single remote computer.

  [!NOTE] To use PowerShell remoting, you must configure the local and
  remote computers for remoting. For more information, see
  about_Remote_Requirements.


How to start an interactive session

The easiest way to run remote commands is to start an interactive session
with a remote computer.

When the session starts, the commands that you type run on the remote
computer, as though you typed them directly on the remote computer. You can
connect to only one computer in each interactive session.

To start an interactive session, use the Enter-PSSession cmdlet. The
following command starts an interactive session with the Server01 computer:

    Enter-PSSession Server01

PowerShell changes the command prompt to include the name of the remote
computer.

    Server01\PS>

Now, you can type commands on the Server01 computer.

To end the interactive session, type:

    Exit-PSSession

For more information, see Enter-PSSession.


How to use cmdlets that have a ComputerName parameter

Several cmdlets have a COMPUTERNAME parameter that lets you get objects
from remote computers.

Because these cmdlets don't use WS-Management-based PowerShell remoting,
you can use the COMPUTERNAME parameter of these cmdlets on any computer
that's running PowerShell. The computers don't have to be configured for
PowerShell remoting, and the computers don't have to meet the system
requirements for remoting.

The following cmdlets have a ComputerName parameter:

    Clear-EventLog    Limit-EventLog
    Get-Counter       New-EventLog
    Get-EventLog      Remove-EventLog
    Get-HotFix        Restart-Computer
    Get-Process       Show-EventLog
    Get-Service       Stop-Computer
    Get-WinEvent      Test-Connection
    Get-WmiObject     Write-EventLog

For example, the following command gets the services on the Server01 remote
computer:

    Get-Service -ComputerName Server01

Typically, cmdlets that support remoting without special configuration have
a COMPUTERNAME parameter and don't have a SESSION parameter. To find these
cmdlets in your session, type:

    Get-Command | Where-Object {
      $_.Parameters.Keys -contains 'ComputerName' -and
      $_.Parameters.Keys -notcontains 'Session'
    }


How to run a remote command

To run other commands on remote computers, use the Invoke-Command cmdlet.

To run a single command or a few unrelated commands, use the COMPUTERNAME
parameter of Invoke-Command to specify the remote computers. Use the
SCRIPTBLOCK parameter to specify the command.

For example, the following command runs a Get-Culture command on the
Server01 computer.

    Invoke-Command -ComputerName Server01 -ScriptBlock {Get-Culture}


How to create a persistent connection

When you use the COMPUTERNAME parameter of the Invoke-Command cmdlet,
PowerShell establishes a temporary connection to the remote computer. It
closes the connection when the command is complete. Any variables or
functions defined in this temporary session are lost.

To create a persistent connection to a remote computer, use the
New-PSSession cmdlet. For example, the following command creates PSSessions
on the Server01 and Server02 computers and then saves the PSSessions in the
$s variable.

    $s = New-PSSession -ComputerName Server01, Server02


How to run commands in a PSSession

With a PSSession, you can run a series of remote commands that share data,
like functions, aliases, and the values of variables. To run commands in a
PSSession, use the SESSION parameter of the Invoke-Command cmdlet.

For example, the following command uses the Invoke-Command cmdlet to run a
Get-Process command in the PSSessions on the Server01 and Server02
computers. The command saves the processes in a $p variable in each
PSSession.

    Invoke-Command -Session $s -ScriptBlock {$p = Get-Process}

Because the PSSession uses a persistent connection, you can run another
command in the same PSSession that uses the $p variable. The following
command counts the number of processes saved in $p.

    Invoke-Command -Session $s -ScriptBlock {$p.count}


How to run a remote command on multiple computers

To run a remote command on multiple computers, type all the computer names
in the value of the COMPUTERNAME parameter of Invoke-Command. Separate the
names with commas.

For example, the following command runs a Get-Culture command on three
computers:

    Invoke-Command -ComputerName S1, S2, S3 -ScriptBlock {Get-Culture}

You can also run a command in multiple PSSessions. The following commands
create PSSessions on the Server01, Server02, and Server03 computers and
then run a Get-Culture command in each of the PSSessions.

    $s = New-PSSession -ComputerName S1, S2, S3
    Invoke-Command -Session $s -ScriptBlock {Get-Culture}

To include the local computer list of computers, type the name of the local
computer, type a dot (.), or type localhost.

    Invoke-Command -ComputerName S1, S2, S3, localhost -ScriptBlock {Get-Culture}


How to run a script on remote computers

To run a local script on remote computers, use the FILEPATH parameter of
Invoke-Command. You don't need to copy any files. For example, the
following command runs the Sample.ps1 script on the S1 and S2 computers:

    Invoke-Command -ComputerName S1, S2 -FilePath C:\Test\Sample.ps1

PowerShell returns the results of the script to the local computer.


How to stop a remote command

To interrupt a command, press Ctrl+c. PowerShell passes the interrupt
request to the remote computer where it terminates the remote command.


For more information

-   For information about the system requirements for remoting, see
    about_Remote_Requirements.

-   For help in formatting remote output, see about_Remote_Output.

-   For information about how remoting works, how to manage remote data,
    special configurations, security issues, and other frequently asked
    questions, see PowerShell Remoting FAQ.

-   For help with resolving remoting errors, see
    about_Remote_Troubleshooting.

-   For information about PSSessions and persistent connections, see
    about_PSSessions.

-   For information about PowerShell background jobs, see about_Jobs.


See also

-   about_Remote_Disconnected_Sessions
-   about_Remote_Variables
-   Invoke-Command
-   Enter-PSSession
-   New-PSSession