Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update remoting information #10240

Merged
merged 4 commits into from
Jul 5, 2023
Merged

Update remoting information #10240

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
4d96ffd
Update remoting information
sdwheeler Jul 5, 2023
6cb19bd
fix broken xrefs
sdwheeler Jul 5, 2023
a1fcf24
fix typos
sdwheeler Jul 5, 2023
59451f3
Apply suggestions from review
michaeltlombardi Jul 5, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
188 changes: 91 additions & 97 deletions reference/5.1/Microsoft.PowerShell.Core/About/about_Remote.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
description: Describes how to run remote commands in PowerShell.
Locale: en-US
ms.date: 01/03/2018
ms.date: 07/03/2023
online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_remote?view=powershell-5.1&WT.mc_id=ps-gethelp
schema: 2.0.0
title: about Remote
Expand All @@ -13,37 +13,31 @@ Describes how to run remote commands in 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.
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.

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 PowerShell remoting, you must configure the local and remote computers
> for remoting. For more information, see [about_Remote_Requirements][06].

Note: To use PowerShell remoting, the local and remote computers must
be configured for remoting. For more information, see
[about_Remote_Requirements](about_Remote_Requirements.md).

## HOW TO START AN INTERACTIVE SESSION (ENTER-PSSESSION)
## 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, just as though you typed them directly on the remote computer. You
can connect to only one computer in each interactive session.
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:
To start an interactive session, use the `Enter-PSSession` cmdlet. The
following command starts an interactive session with the Server01 computer:

```powershell
Enter-PSSession Server01
```

The command prompt changes to indicate that you are connected to the Server01
PowerShell changes the command prompt to include the name of the remote
computer.

```
Expand All @@ -58,18 +52,18 @@ To end the interactive session, type:
Exit-PSSession
```

For more information, see Enter-PSSession.
For more information, see [Enter-PSSession][09].

## HOW TO USE CMDLETS THAT HAVE A COMPUTERNAME PARAMETER TO GET REMOTE DATA
## How to use cmdlets that have a computername parameter
michaeltlombardi marked this conversation as resolved.
Show resolved Hide resolved

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

Because these cmdlets do not use WS-Management-based PowerShell
remoting, you can use the ComputerName parameter of these cmdlets on any
computer that is running PowerShell. The computers do not have to be
configured for PowerShell remoting, and the computers do not have to
meet the system requirements for remoting.
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:

Expand All @@ -84,15 +78,15 @@ Get-WinEvent Test-Connection
Get-WmiObject Write-EventLog
```

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

```powershell
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
**ComputerName** parameter and don't have a **Session** parameter. To find
these cmdlets in your session, type:

```powershell
Expand All @@ -102,69 +96,65 @@ Get-Command | Where-Object {
}
```

## HOW TO RUN A REMOTE COMMAND
## How to run a remote command

To run other commands on remote computers, use the Invoke-Command cmdlet.
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.
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
For example, the following command runs a `Get-Culture` command on the Server01
computer.

```powershell
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)
## How to create a persistent connection

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.
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
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.
and Server02 computers and then saves the PSSessions in the `$s` variable.

```powershell
$s = New-PSSession -ComputerName Server01, Server02
```

## HOW TO RUN COMMANDS IN A PSSESSION
## 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.
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.
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.

```powershell
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.
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`.

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

## HOW TO RUN A REMOTE COMMAND ON MULTIPLE COMPUTERS
## 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
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
For example, the following command runs a `Get-Culture` command on three
computers:

```powershell
Expand All @@ -173,70 +163,74 @@ 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.
run a `Get-Culture` command in each of the PSSessions.

```powershell
$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".
To include the local computer list of computers, type the name of the local
computer, type a dot (`.`), or type `localhost`.

```powershell
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.
## How to run a script on remote computers

For example, the following command runs the Sample.ps1 script on the S1 and S2
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:

```powershell
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.
PowerShell returns the results of the script to the local computer.

## HOW TO STOP A REMOTE COMMAND
## 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.
To interrupt a command, press <kbd>Ctrl</kbd>+<kbd>c</kbd>. PowerShell passes
the interrupt request to the remote computer where it terminates the remote
command.

## FOR MORE INFORMATION
## For more information

- For information about the system requirements for remoting, see
[about_Remote_Requirements](about_Remote_Requirements.md).
[about_Remote_Requirements][06].

- For help in formatting remote output, see [about_Remote_Output](about_Remote_Output.md).
- For help in formatting remote output, see [about_Remote_Output][05].

- For information about how remoting works, how to manage remote data, special
configurations, security issues, and other frequently asked questions, see
[PowerShell Remoting FAQ](/powershell/scripting/learn/remoting/powershell-remoting-faq).
[PowerShell Remoting FAQ][01].

- For help in resolving remoting errors, see [about_Remote_Troubleshooting](about_Remote_Troubleshooting.md).
- For help with resolving remoting errors, see
[about_Remote_Troubleshooting][07].

- For information about PSSessions and persistent connections, see
[about_PSSessions](about_PSSessions.md).

- For information about PowerShell background jobs, see [about_Jobs](about_Jobs.md).

## KEYWORDS
[about_PSSessions][03].

about_Remoting
- For information about PowerShell background jobs, see [about_Jobs][02].

## See also

- [about_PSSessions](about_PSSessions.md)
- [about_Remote_Disconnected_Sessions](about_Remote_Disconnected_Sessions.md)
- [about_Remote_Requirements](about_Remote_Requirements.md)
- [about_Remote_TroubleShooting](about_Remote_TroubleShooting.md)
- [about_Remote_Variables](about_Remote_Variables.md)
- [Invoke-Command](xref:Microsoft.PowerShell.Core.Invoke-Command)
- [Enter-PSSession](xref:Microsoft.PowerShell.Core.Enter-PSSession)
- [New-PSSession](xref:Microsoft.PowerShell.Core.New-PSSession)
- [PowerShell Remoting FAQ](/powershell/scripting/learn/remoting/powershell-remoting-faq)
- [about_Remote_Disconnected_Sessions][04]
- [about_Remote_Variables][08]
- [Invoke-Command][10]
- [Enter-PSSession][09]
- [New-PSSession][11]

<!-- link references -->
[01]: /powershell/scripting/learn/remoting/powershell-remoting-faq
[02]: about_Jobs.md
[03]: about_PSSessions.md
[04]: about_Remote_Disconnected_Sessions.md
[05]: about_Remote_Output.md
[06]: about_Remote_Requirements.md
[07]: about_Remote_Troubleshooting.md
[08]: about_Remote_Variables.md
[09]: xref:Microsoft.PowerShell.Core.Enter-PSSession
[10]: xref:Microsoft.PowerShell.Core.Invoke-Command
[11]: xref:Microsoft.PowerShell.Core.New-PSSession
Loading