Enter-PSSession

启动与远程计算机的交互式会话。

语法

Enter-PSSession
     [-ComputerName] <String>
     [-EnableNetworkAccess]
     [[-Credential] <PSCredential>]
     [-ConfigurationName <String>]
     [-Port <Int32>]
     [-UseSSL]
     [-ApplicationName <String>]
     [-SessionOption <PSSessionOption>]
     [-Authentication <AuthenticationMechanism>]
     [-CertificateThumbprint <String>]
     [<CommonParameters>]
Enter-PSSession
     [-HostName] <String>
     [-Port <Int32>]
     [-UserName <String>]
     [-KeyFilePath <String>]
     [-SSHTransport]
     [<CommonParameters>]
Enter-PSSession
     [[-Session] <PSSession>]
     [<CommonParameters>]
Enter-PSSession
     [[-ConnectionUri] <Uri>]
     [-EnableNetworkAccess]
     [[-Credential] <PSCredential>]
     [-ConfigurationName <String>]
     [-AllowRedirection]
     [-SessionOption <PSSessionOption>]
     [-Authentication <AuthenticationMechanism>]
     [-CertificateThumbprint <String>]
     [<CommonParameters>]
Enter-PSSession
     [-InstanceId <Guid>]
     [<CommonParameters>]
Enter-PSSession
     [[-Id] <Int32>]
     [<CommonParameters>]
Enter-PSSession
     [-Name <String>]
     [<CommonParameters>]
Enter-PSSession
     [-VMId] <Guid>
     [-Credential] <PSCredential>
     [-ConfigurationName <String>]
     [<CommonParameters>]
Enter-PSSession
     [-VMName] <String>
     [-Credential] <PSCredential>
     [-ConfigurationName <String>]
     [<CommonParameters>]
Enter-PSSession
     [-ContainerId] <String>
     [-ConfigurationName <String>]
     [-RunAsAdministrator]
     [<CommonParameters>]

说明

Enter-PSSession cmdlet 启动与单个远程计算机的交互式会话。 在会话期间,键入的命令在远程计算机上运行,就像直接在远程计算机上键入一样。 一次只可以进行一个交互式会话。

通常,你可以使用 ComputerName 参数来指定远程计算机的名称。 但是,也可以使用通过使用交互式会话的 New-PSSession cmdlet 创建的会话。 但是,不能使用 Disconnect-PSSessionConnect-PSSessionReceive-PSSession cmdlet 与交互式会话断开连接或重新连接到该会话。

从 PowerShell 6.0 开始,如果本地计算机上提供 SSH,并且远程计算机配置了 PowerShell SSH 终结点,则可以使用安全外壳 (SSH) 与远程计算机建立连接。 基于 SSH 的 PowerShell 远程会话的优点是它可以跨多个平台工作, (Windows、Linux、macOS) 。 对于基于 SSH 的远程处理,请使用 HostName 参数集来指定远程计算机和相关连接信息。 有关如何设置 PowerShell SSH 远程处理的详细信息,请参阅 通过 SSH 进行 PowerShell 远程处理

若要结束交互式会话并从远程计算机断开连接,请使用 Exit-PSSession cmdlet 或键入 exit

示例

示例 1:启动交互式会话

PS> Enter-PSSession
[localhost]: PS>

此命令将在本地计算机上启动交互式会话。 命令提示符将发生更改,以指示你现在正在不同的会话中运行命令。

你输入的命令将在该新会话中运行,而结果将以文本形式返回到默认会话中。

示例 2:使用交互式会话

第一个命令使用 Enter-PSSession cmdlet 启动与远程计算机 Server01 的交互式会话。 会话启动时,命令提示符将更改为包含该计算机名称。

第二个命令获取 PowerShell 进程,并将输出重定向到 Process.txt 文件。 该命令将提交到远程计算机,并且该文件将保存在远程计算机上。

第三个命令使用 Exit 关键字 (keyword) 结束交互式会话并关闭连接。 第四个命令确认 Process.txt 文件是否位于远程计算机上。 Get-ChildItem 本地计算机上的 (“dir”) 命令找不到该文件。

PS C:\> Enter-PSSession -ComputerName Server01
[Server01]: PS>
[Server01]: PS C:\> Get-Process PowerShell > C:\ps-test\Process.txt
[Server01]: PS C:\> exit
PS C:\>
PS C:\> dir C:\ps-test\process.txt
Get-ChildItem : Cannot find path 'C:\ps-test\process.txt' because it does not exist.
At line:1 char:4
+ dir <<<<  c:\ps-test\process.txt

此命令显示了如何在与远程计算机的交互式会话中进行工作。

示例 3:使用 Session 参数

PS> $s = New-PSSession -ComputerName Server01
PS> Enter-PSSession -Session $s
[Server01]: PS>

这些命令使用 的 Enter-PSSessionSession 参数在现有 PowerShell 会话中运行交互式会话, (PSSession) 。

示例 4:启动交互式会话并指定 Port 和 Credential 参数

PS> Enter-PSSession -ComputerName Server01 -Port 90 -Credential Domain01\User01
[Server01]: PS>

此命令启动与 Server01 计算机的交互式会话。 它使用 Port 参数指定端口,使用 Credential 参数指定有权连接到远程计算机的用户的帐户。

示例 5:停止交互式会话

PS> Enter-PSSession -ComputerName Server01
[Server01]: PS> Exit-PSSession
PS>

此示例显示了如何启动和停止交互式会话。 第一个命令使用 Enter-PSSession cmdlet 启动与 Server01 计算机的交互式会话。

第二个命令使用 Exit-PSSession cmdlet 结束会话。 还可以使用退出关键字 (keyword) 结束交互式会话。 Exit-PSSessionExit 具有相同的效果。

示例 6:使用 SSH 启动交互式会话

PS> Enter-PSSession -HostName UserA@LinuxServer01

此示例演示如何使用安全外壳 (SSH) 启动交互式会话。 如果在远程计算机上将 SSH 配置为提示输入密码,则会收到密码提示。 否则,必须使用基于 SSH 密钥的用户身份验证。

示例 7:使用 SSH 启动交互式会话并指定端口和用户身份验证密钥

PS> Enter-PSSession -HostName UserA@LinuxServer02:22 -KeyFilePath c:\<path>\userAKey_rsa

此示例演示如何使用 SSH 启动交互式会话。 它使用 Port 参数指定要使用的端口,使用 KeyFilePath 参数指定用于对远程计算机上的用户进行身份验证的 RSA 密钥。

参数

-AllowRedirection

允许将此连接重定向到备用统一资源标识符 (URI)。 默认情况下,不允许重定向。

使用 ConnectionURI 参数时,远程目标将返回一个指令,以重定向到不同的 URI。 默认情况下,PowerShell 不会重定向连接,但你可以使用此参数允许它重定向连接。

你也可以通过更改 MaximumConnectionRedirectionCount 会话选项值,限制重定向连接的次数。 使用 cmdlet 的 New-PSSessionOptionMaximumRedirection 参数或设置首选项变量的 $PSSessionOptionMaximumConnectionRedirectionCount 属性。 默认值为 5。

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ApplicationName

指定连接 URI 的应用程序名称段。 当命令中未使用 ConnectionURI 参数时,请使用此参数指定应用程序名称。

默认值是 $PSSessionApplicationName 本地计算机上首选项变量的值。 如果未定义此首选项变量,则默认值为 WSMAN。 该值适用于大多数使用情况。 有关详细信息,请参阅 about_Preference_Variables

WinRM 服务使用应用程序名称来选择一个侦听器来为连接请求提供服务。 此参数的值应与远程计算机上的侦听器的 URLPrefix 属性值匹配。

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:True
Accept wildcard characters:False

-Authentication

指定用于对用户的凭据进行身份验证的机制。 此参数的可接受值为:

  • Default
  • 基本
  • Credssp
  • 摘要
  • Kerberos
  • Negotiate
  • NegotiateWithImplicitCredential

默认值为 Default。

CredSSP 身份验证仅在 Windows Vista、Windows Server 2008 和更高版本的 Windows 操作系统中可用。

有关此参数的值的详细信息,请参阅 AuthenticationMechanism 枚举

警告:凭据安全支持提供程序 (CredSSP) 身份验证(其中用户凭据传递到远程计算机进行身份验证)适用于需要在多个资源上进行身份验证的命令,例如访问远程网络共享。 此机制增加了远程操作的安全风险。 如果远程计算机的安全受到威胁,则传递给该计算机的凭据可用于控制网络会话。

Type:AuthenticationMechanism
Accepted values:Default, Basic, Negotiate, NegotiateWithImplicitCredential, Credssp, Digest, Kerberos
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-CertificateThumbprint

指定有权执行此操作的用户帐户的数字公钥证书 (X509)。 输入证书的证书指纹。

在基于客户端证书的身份验证中使用证书。 证书只能映射到本地用户帐户,而不适用于域帐户。

若要获取证书,请使用 Get-Item PowerShell 证书: 驱动器中的 或 Get-ChildItem 命令。

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ComputerName

指定计算机名称。 此 cmdlet 与指定的远程计算机启动交互式会话。 仅输入一个计算机名称。 默认为本地计算机。

键入计算机的 NetBIOS 名称、IP 地址或完全限定的域名。 还可以通过管道将计算机名称传递给 Enter-PSSession

若要在 ComputerName 参数的值中使用 IP 地址,该命令必须包含 Credential 参数。 此外,必须为计算机配置 HTTPS 传输,或者必须在本地计算机上的 WinRM TrustedHosts 列表中包含远程计算机的 IP 地址。 有关将计算机名称添加到 TrustedHosts 列表的说明,请参阅 about_Remote_Troubleshooting 中的“如何将计算机添加到受信任的主机列表”。

注意:在 Windows Vista 和更高版本的 Windows 操作系统中,若要在 ComputerName 参数的值中包含本地计算机,必须使用“以管理员身份运行”选项启动 PowerShell。

Type:String
Aliases:Cn
Position:0
Default value:None
Required:True
Accept pipeline input:True
Accept wildcard characters:False

-ConfigurationName

指定用于交互式会话的会话配置。

输入会话配置的配置名称或完全限定的资源 URI。 如果仅指定配置名称,则会在前面添加以下架构 URI: https://schemas.microsoft.com/powershell

与 SSH 一起使用时,这将指定在目标上使用的子系统,如 sshd_config 中定义。 SSH 的默认值为 powershell 子系统。

会话的会话配置位于远程计算机上。 如果远程计算机上不存在指定的会话配置,则该命令会失败。

默认值是本地计算机上的首选项变量的值 $PSSessionConfigurationName 。 如果未设置此首选项变量,则默认值为 Microsoft.PowerShell。 有关详细信息,请参阅 about_Preference_Variables

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:True
Accept wildcard characters:False

-ConnectionUri

指定定义会话的连接终结点的 URI。 URI 必须完全限定。 此字符串的格式如下:

<Transport>://<ComputerName>:<Port>/<ApplicationName>

默认值如下:

https://localhost:5985/WSMAN

如果未指定 ConnectionURI,则可以使用 UseSSLComputerNamePortApplicationName 参数来指定 ConnectionURI 值。

URI 的 Transport 段的有效值为 HTTP 和 HTTPS。 如果使用传输段指定连接 URI,但未指定端口,则使用标准端口创建会话:80 用于 HTTP,443 用于 HTTPS。 若要使用默认端口进行 PowerShell 远程处理,请为 HTTP 指定端口 5985,为 HTTPS 指定端口 5986。

如果目标计算机将连接重定向到其他 URI,则 PowerShell 会阻止重定向,除非你在 命令中使用 AllowRedirection 参数。

Type:Uri
Aliases:URI, CU
Position:1
Default value:None
Required:False
Accept pipeline input:True
Accept wildcard characters:False

-ContainerId

指定容器的 ID。

Type:String
Position:0
Default value:None
Required:True
Accept pipeline input:True
Accept wildcard characters:False

-Credential

指定有权执行此操作的用户帐户。 默认为当前用户。

键入用户名,例如 User01Domain01\User01,或输入 cmdlet Get-Credential 生成的 PSCredential 对象。 如果键入用户名,系统会提示输入密码。

凭据存储在 PSCredential 对象中,密码存储为 SecureString

注意

有关 SecureString 数据保护的详细信息,请参阅 SecureString 的安全性如何?

Type:PSCredential
Position:1
Default value:Current user
Required:False
Accept pipeline input:True
Accept wildcard characters:False

-EnableNetworkAccess

指示此 cmdlet 将交互式安全令牌添加到环回会话。 通过交互式令牌,你可以在环回会话中运行用于获取其他计算机中的数据的命令。 例如,你可以在该会话中运行用于将 XML 文件从远程计算机复制到本地计算机的命令。

环回会话是在同一计算机上开始并终止的 PSSession。 若要创建环回会话,请省略 ComputerName 参数或将其值设置为 。 (点) 、localhost 或本地计算机的名称。

默认情况下,环回会话是使用网络令牌创建的,该令牌可能无法提供足够的权限来对远程计算机进行身份验证。

EnableNetworkAccess 参数仅在环回会话中有效。 如果在远程计算机上创建会话时使用 EnableNetworkAccess ,则命令会成功,但参数将被忽略。

通过用于将会话凭据委派给其他计算机的 CredSSP 参数的 Authentication 值,你还可以在环回会话中进行远程访问。

已在 Windows PowerShell 3.0 中引入了此参数。

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-HostName

指定安全外壳 (基于 SSH) 连接的计算机名称。 这类似于 ComputerName 参数,只是使用 SSH 而不是 Windows WinRM 连接到远程计算机。 此参数支持使用 格式 user@hostname:port指定用户名和/或端口作为主机名参数值的一部分。 指定为主机名一部分的用户名和/或端口优先于 -UserName-Port 参数(如果指定)。 这允许将多个计算机名称传递给此参数,其中一些具有特定用户名和/或端口,而另一些则使用 和 -Port 参数中的-UserName用户名和/或端口。

此参数是在 PowerShell 6.0 中引入的。

Type:String
Position:0
Default value:None
Required:True
Accept pipeline input:True
Accept wildcard characters:False

-Id

指定现有会话的 ID。 Enter-PSSession 使用交互式会话的指定会话。

若要查找会话的 ID,请使用 Get-PSSession cmdlet。

Type:Int32
Position:0
Default value:None
Required:False
Accept pipeline input:True
Accept wildcard characters:False

-InstanceId

指定现有会话的实例 ID。 Enter-PSSession 使用交互式会话的指定会话。

实例 ID 是一个 GUID。 若要查找会话的实例 ID,请使用 Get-PSSession cmdlet。 还可以使用 会话名称ID 参数来指定现有会话。 或者,可以使用 ComputerName 参数启动临时会话。

Type:Guid
Position:Named
Default value:None
Required:False
Accept pipeline input:True
Accept wildcard characters:False

-KeyFilePath

指定安全外壳 (SSH) 用于对远程计算机上的用户进行身份验证的密钥文件路径。

SSH 允许通过私钥/公钥执行用户身份验证,作为基本密码身份验证的替代方法。 如果为远程计算机配置了密钥身份验证,则此参数可用于提供用于标识用户的密钥。

此参数是在 PowerShell 6.0 中引入的。

Type:String
Aliases:IdentityFilePath
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Name

指定现有会话的友好名称。 Enter-PSSession 使用交互式会话的指定会话。

如果你指定的名称与多个会话相匹配,则该命令会失败。 还可以使用 SessionInstanceIDID 参数指定现有会话。 或者,可以使用 ComputerName 参数启动临时会话。

若要为会话建立友好名称,请使用 cmdlet 的 New-PSSessionName 参数。

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:True
Accept wildcard characters:False

-Port

指定远程计算机上用于此命令的网络端口。

在 PowerShell 6.0 中,此参数包含在支持安全外壳 (SSH) 连接的 HostName 参数集中。

WinRM (ComputerName 参数集)

若要连接到一台远程计算机,则必须在该连接所用的端口上侦听远程计算机。 默认端口为 5985(HTTP 的 WinRM 端口)和 5986(HTTPS 的 WinRM 端口)。

使用备用端口之前,你必须在远程计算机上配置 WinRM 侦听器,才能在该端口上进行侦听。 使用以下命令配置侦听器:

  1. winrm delete winrm/config/listener?Address=*+Transport=HTTP
  2. winrm create winrm/config/listener?Address=*+Transport=HTTP @{Port="\<port-number\>"}

除非必要,否则不要使用 Port 参数。 命令中的端口设置适用于运行该命令的所有计算机或会话。 备用端口设置可能会阻止在所有计算机上运行该命令。

SSH (HostName 参数集)

若要连接到远程计算机,必须为远程计算机配置 SSH 服务 (SSHD) ,并且必须侦听连接使用的端口。 SSH 的默认端口为 22。

Type:Int32
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-RunAsAdministrator

指示 PSSession 以管理员身份运行。

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Session

指定要用于交互式会话的 PowerShell 会话 (PSSession) 。 此参数获取一个会话对象。 还可以使用 NameInstanceIDID 参数来指定 PSSession

输入包含会话对象的变量,或者创建或获取会话对象的命令,如 New-PSSessionGet-PSSession 命令。 还可以通过管道将会话对象传递给 Enter-PSSession。 使用此参数只能提交一个 PSSession 。 如果输入包含多个 PSSession 的变量,则命令将失败。

使用 Exit-PSSessionEXIT 关键字 (keyword) 时,交互式会话结束,但创建的 PSSession 将保持打开状态并可供使用。

Type:PSSession
Position:0
Default value:None
Required:False
Accept pipeline input:True
Accept wildcard characters:False

-SessionOption

为该会话设置高级选项。 输入 SessionOption 对象,例如使用 New-PSSessionOption cmdlet 创建的会话选项对象,或其中键为会话选项名称且值为会话选项值的哈希表。

选项的默认值由首选项变量的值 $PSSessionOption (如果已设置)确定。 否则,通过在会话配置中设置的选项创建默认值。

对于在首选项变量和会话配置中 $PSSessionOption 设置的会话,会话选项值优先于默认值。 但是,它们不优先于在会话配置中设置的最大值、配额或限制。

有关会话选项的说明(包括默认值),请参阅 New-PSSessionOption。 有关首选项变量的信息 $PSSessionOption ,请参阅 about_Preference_Variables。 有关会话配置的详细信息,请参阅 about_Session_Configurations

Type:PSSessionOption
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-SSHTransport

指示使用安全外壳 (SSH) 建立远程连接。

默认情况下,PowerShell 使用 Windows WinRM 连接到远程计算机。 此开关强制 PowerShell 使用 HostName 参数集来建立基于 SSH 的远程连接。

此参数是在 PowerShell 6.0 中引入的。

Type:SwitchParameter
Accepted values:true
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Subsystem

指定用于新 PSSession 的 SSH 子系统。

这将指定在目标上使用的子系统,如 sshd_config 中定义。 子系统使用预定义的参数启动特定版本的 PowerShell。 如果远程计算机上不存在指定的子系统,则命令将失败。

如果未使用此参数,则默认为“powershell”子系统。

Type:String
Position:Named
Default value:powershell
Required:False
Accept pipeline input:True
Accept wildcard characters:False

-UserName

指定用于在远程计算机上创建会话的帐户的用户名。 用户身份验证方法将取决于在远程计算机上配置安全外壳 (SSH) 的方式。

如果为基本密码身份验证配置了 SSH,则系统会提示输入用户密码。

如果为基于密钥的用户身份验证配置了 SSH,则可以通过 KeyFilePath 参数提供密钥文件路径,并且不会发生密码提示。 请注意,如果客户端用户密钥文件位于 SSH 已知位置,则基于密钥的身份验证不需要 KeyFilePath 参数,并且用户身份验证将根据用户名自动进行。 有关详细信息,请参阅有关基于密钥的用户身份验证的 SSH 文档。

这不是必需的参数。 如果未指定 UserName 参数,则将当前登录用户名用于连接。

此参数是在 PowerShell 6.0 中引入的。

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-UseSSL

指示此 cmdlet 使用安全套接字层 (SSL) 协议来建立与远程计算机的连接。 默认情况下,不使用 SSL。

WS-Management 加密通过网络传输的所有 PowerShell 内容。 UseSSL 参数是一种额外的保护,它通过 HTTPS 连接而不是 HTTP 连接发送数据。

如果使用此参数,但 SSL 在用于命令的端口上不可用,则命令将失败。

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-VMId

指定虚拟机的 ID。

Type:Guid
Aliases:VMGuid
Position:0
Default value:None
Required:True
Accept pipeline input:True
Accept wildcard characters:False

-VMName

指定虚拟机的名称。

Type:String
Position:0
Default value:None
Required:True
Accept pipeline input:True
Accept wildcard characters:False

输入

System.String, System.Management.Automation.Runspaces.PSSession

可以通过管道将计算机名称作为字符串或会话对象传递给此 cmdlet。

输出

None

该 cmdlet 不返回任何输出。

备注

若要连接到远程计算机,你必须是该远程计算机上 Administrators 组的成员。 若要在本地计算机上启动交互式会话,必须使用“ 以管理员身份运行” 选项启动 PowerShell。

使用 Enter-PSSession时,远程计算机上的用户配置文件将用于交互式会话。 远程用户配置文件中的命令(包括用于添加 PowerShell 模块和更改命令提示符的命令)在显示远程提示之前运行。

Enter-PSSession 使用本地计算机上的 UI 区域性设置进行交互式会话。 若要查找本地 UI 区域性,请使用 $UICulture 自动变量。

Enter-PSSession 需要 Get-CommandOut-DefaultExit-PSSession cmdlet。 如果远程计算机上的会话配置中不包含这些 cmdlet,则 Enter-PSSession 命令将失败。

与 (在将命令发送到远程计算机之前分析和解释命令)不同 Invoke-CommandEnter-PSSession 将命令直接发送到远程计算机,而无需解释。

如果要进入的会话正忙于处理命令,则 PowerShell 在响应 Enter-PSSession 命令之前可能存在延迟。 会话可用后,即已连接。 若要取消该 Enter-PSSession 命令,请按 Ctrl+C

从 PowerShell 6.0 开始,包含 HostName 参数集。 添加它以基于安全外壳 (SSH) 提供 PowerShell 远程处理。 SSH 和 PowerShell 在多个平台上都受支持, (Windows、Linux、macOS) 和 PowerShell 远程处理将在安装和配置 PowerShell 和 SSH 的这些平台上工作。 这与之前的仅 Windows 远程处理(基于 WinRM)不同,并且许多 WinRM 特定功能和限制不适用。 例如,目前不支持基于 WinRM 的配额、会话选项、自定义终结点配置和断开连接/重新连接功能。 有关如何设置 PowerShell SSH 远程处理的详细信息,请参阅 通过 SSH 进行 PowerShell 远程处理

在 PowerShell 7.1 之前,通过 SSH 进行远程处理不支持第二个跃点的远程会话。 此功能仅限于使用 WinRM 的会话。 PowerShell 7.1 允许 Enter-PSSessionEnter-PSHostProcess 在任何交互式远程会话中工作。