Add documentation for new -ConnectingTimeout parameter for SSH remoting #7464
Description
Summary of the new document or enhancement
A new -ConnectingTimeout parameter has been added to remoting cmdlets SSH transport parameter sets.
- List of articles that need to be updated:
- New articles that need to be created:
- Link(s) to related code PR(s) in the PowerShell/PowerShell repo: Fix SSH remoting connection hang with misconfigured endpoint PowerShell/PowerShell#15175
- Link(s) to related issue(s) in the PowerShell/PowerShell repo:
Description of what changed
-ConnectingTimeout parameter takes an integer value that defines the amount of time, in milliseconds, allowed for the initial SSH connection to complete. If the connection does not complete within this time, an error is thrown. This new parameter applies only to SSH connections and appears only for SSH parameter sets.
Affected cmdlets:
New-PSSession
Enter-PSSession
Invoke-CommandAffected parameter sets:
New-PSSession [-HostName] <string[]> [-Name <string[]>] [-Port <int>] [-UserName <string>] [-KeyFilePath <string>] [-Subsystem <string>] [-ConnectingTimeout <int>] [-SSHTransport] [<CommonParameters>]
New-PSSession -SSHConnection <hashtable[]> [-Name <string[]>] [<CommonParameters>]Enter-PSSession [-HostName] <string> [-Port <int>] [-UserName <string>] [-KeyFilePath <string>] [-Subsystem <string>] [-ConnectingTimeout <int>] [-SSHTransport] [<CommonParameters>]Invoke-Command [-ScriptBlock] <scriptblock> -HostName <string[]> [-Port <int>] [-AsJob] [-HideComputerName] [-JobName <string>] [-UserName <string>] [-KeyFilePath <string>] [-Subsystem <string>] [-ConnectingTimeout <int>] [-SSHTransport] [-RemoteDebug] [-InputObject <psobject>] [-ArgumentList <Object[]>] [<CommonParameters>]
Invoke-Command [-ScriptBlock] <scriptblock> -SSHConnection <hashtable[]> [-AsJob] [-HideComputerName] [-JobName <string>] [-RemoteDebug] [-InputObject <psobject>] [-ArgumentList <Object[]>] [<CommonParameters>]
Invoke-Command -FilePath <string> -HostName <string[]> [-AsJob] [-HideComputerName] [-UserName <string>] [-KeyFilePath <string>] [-Subsystem <string>] [-ConnectingTimeout <int>] [-SSHTransport] [-RemoteDebug] [-InputObject <psobject>] [-ArgumentList <Object[]>] [<CommonParameters>]
Invoke-Command -FilePath <string> -SSHConnection <hashtable[]> [-AsJob] [-HideComputerName] [-RemoteDebug] [-InputObject <psobject>] [-ArgumentList <Object[]>] [<CommonParameters>]Examples:
New-PSSession -HostName localhost -ConnectingTimeout 5000
New-PSSession: [localhost] SSH connection attempt failed after time out: 5 seconds.
$connectionHash = @{ HostName='localhost'; ConnectingTimeout=5000 }
New-PSSession -SSHConnection $connectionHash
New-PSSession: [localhost] SSH connection attempt failed after time out: 5 seconds.Enter-PSSession -HostName localhost -ConnectingTimeout 5000
Enter-PSSession: SSH connection attempt failed after time out: 5 seconds.Invoke-Command -HostName localhost -ScriptBlock { 'Hello' } -ConnectingTimeout 5000
OpenError: [localhost] SSH connection attempt failed after time out: 5 seconds.
$connectionHash = @{ HostName='localhost'; ConnectingTimeout=5000 }
Invoke-Command -SSHConnection $connectionHash -ScriptBlock { 'Hello' }
OpenError: [localhost] SSH connection attempt failed after time out: 5 seconds.