about_Remote

	Copy Code
TOPIC about_Remote SHORT DESCRIPTION Describes how to run remote commands in Windows PowerShell. LONG DESCRIPTION You can run remote commands on a single computer or on multiple computers by using a temporary or persistent connection. You can also start an interactive session with a single remote computer. This topic provides a series of examples to show you how to run different types of remote command. After you try these basic commands, read the Help topics that describe each cmdlet that is used in these commands. The topics provide the details and explain how you can modify the commands to meet your needs. Note: To use Windows PowerShell remoting, the local and remote computers must be configured for remoting. For more information, see about_Remote_Requirements. HOW TO START AN INTERACTIVE SESSION (ENTER-PSSESSION) 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, just 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 The command prompt changes to indicate that you are connected to the Server01 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 TO GET REMOTE DATA Several cmdlets have a ComputerName parameter that lets you get objects from remote computers. Because these cmdlets do not use WS-Management-based Windows PowerShell remoting, you can use the ComputerName parameter of these cmdlets on any computer that is running Windows PowerShell. The computers do not have to be configured for Windows PowerShell remoting, and the computers do not 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 do not have a Session parameter. To find these cmdlets in your session, type: get-command \| where { $_.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} The ComputerName parameter is designed for situation in which you run a single command or several unrelated commands on one or many computers. To establish a persistent connection to a remote computer, use the Session parameter. HOW TO CREATE A PERSISTENT CONNECTION (PSSESSION) When you use the ComputerName parameter of the Invoke-Command cmdlet, Windows PowerShell establishes a connection just for the command. Then, it closes the connection when the command is complete. Any variables or functions that are defined in the command 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 of 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. 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 The results of the script are returned to the local computer. You do not need to copy any files. HOW TO STOP A REMOTE COMMAND To interrupt a command, press CTRL+C. The interrupt request is passed 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 about_Remote_FAQ. -- For help in resolving remoting errors, see about_Remote_Troubleshooting. -- For information about PSSessions and persistent connections, see about_PSSessions. -- For information about Windows PowerShell background jobs, see about_Jobs. KEYWORDS about_Remoting SEE ALSO about_PSSessions about_Remote_Requirements about_Remote_FAQ about_Remote_TroubleShooting Enter-PSSession Invoke-Command New-PSSession

Copy Code

TOPIC
about_Remote

SHORT DESCRIPTION
Describes how to run remote commands in Windows PowerShell.

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

This topic provides a series of examples to show you how to
run different types of remote command. After you try these basic
commands, read the Help topics that describe each cmdlet that is
used in these commands. The topics provide the details and explain
how you can modify the commands to meet your needs.

Note: To use Windows PowerShell remoting, the local and remote computers
must be configured for remoting. For more information, see
about_Remote_Requirements.

HOW TO START AN INTERACTIVE SESSION (ENTER-PSSESSION)

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, just 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

The command prompt changes to indicate that you are connected
to the Server01 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 TO GET REMOTE DATA

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

Because these cmdlets do not use WS-Management-based Windows PowerShell
remoting, you can use the ComputerName parameter of these cmdlets on any
computer that is running Windows PowerShell. The computers do not have to
be configured for Windows PowerShell remoting, and the computers do not
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 do not have a Session parameter. To
find these cmdlets in your session, type:

get-command | where { $_.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}

The ComputerName parameter is designed for situation in which you run
a single command or several unrelated commands on one or many computers.
To establish a persistent connection to a remote computer, use
the Session parameter.

HOW TO CREATE A PERSISTENT CONNECTION (PSSESSION)

When you use the ComputerName parameter of the Invoke-Command
cmdlet, Windows PowerShell establishes a connection just for the
command. Then, it closes the connection when the command is complete. Any
variables or functions that are defined in the command 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 of
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.

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

The results of the script are returned to the local computer. You
do not need to copy any files.

HOW TO STOP A REMOTE COMMAND

To interrupt a command, press CTRL+C. The interrupt request is
passed 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 about_Remote_FAQ.

-- For help in resolving remoting errors, see about_Remote_Troubleshooting.

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

-- For information about Windows PowerShell background jobs, see
about_Jobs.

KEYWORDS
about_Remoting

SEE ALSO
about_PSSessions
about_Remote_Requirements
about_Remote_FAQ
about_Remote_TroubleShooting
Enter-PSSession
Invoke-Command
New-PSSession