Test-Connection

Sends ICMP echo request packets ("pings") to one or more computers using WMI.

Syntax
      Test-Connection [-ComputerName] string[] [[-Source] string[]]
         [-AsJob] [-Authentication AuthenticationLevel]
            [-BufferSize int] [-Count int] [-Credential PSCredential] [-Delay int]
               [-Impersonation ImpersonationLevel] [-Quiet]
                  [-ThrottleLimit int] [-TimeToLive int] [CommonParameters]

Key
   -Authentication AuthenticationLevel
       The authentication level that is used for the WMI connection.
       Valid values:

         Unchanged       The authentication level is the same as the previous command.
         Default         Windows Authentication.
         None            No COM authentication.
         Connect         Connect-level COM authentication.
         Call            Call-level COM authentication.
         Packet          Packet-level COM authentication.
         PacketIntegrity Packet Integrity-level COM authentication.
         PacketPrivacy   Packet Privacy-level COM authentication.

   -BufferSize int
       The size, in bytes, of the buffer sent with this command.
       The default value is 32.

   -ComputerName string[]
       The computers to ping.
       Type the computer names or type IP addresses in IPv4 or IPv6 format.
       Wildcard characters are not permitted. This parameter is required.

       This parameter does not rely on PowerShell remoting.

   -Count int
       The number of echo requests to send.
       The default value is 4.

   -Credential PSCredential
       A user account that has permission to perform this action.
       Type a user name, such as "User64" or "Domain64\User64", or enter
       a PSCredential object, such as one from Get-Credential.

   -Delay int
       The interval between pings, in seconds.

   -Impersonation ImpersonationLevel
       The impersonation level to use when calling WMI.
       Valid values:

         Default      Default impersonation.
         Anonymous    Hides the identity of the caller.
         Identify     Allows objects to query the credentials of the caller.
         Impersonate  Allows objects to use the credentials of the caller.

   -Quiet
       Suppress all errors and return $True if any pings succeeded
       and $False if all failed.

   -Source string[]
       The names of the computers where the ping originates.
       Enter a comma-separated list of computer names.
       The default is the local computer.

   -ThrottleLimit int
       The maximum number of concurrent connections that can be established
       to run this command. If this parameter is NULL or 0, the default
       value of 32, is used.

       The throttle limit applies only to the current command, not to the session or to the computer.

   -TimeToLive int
       The maximum time, in seconds, that each echo request packet
       ("pings") is active. The default value is 80 (seconds).
       The alias of the TimeToLive parameter is TTL.

   CommonParameters:
       -Verbose, -Debug, -ErrorAction, -ErrorVariable, -WarningAction, -WarningVariable,
       -OutBuffer -OutVariable.

Test-Connection sends Internet Control Message Protocol (ICMP) echo request packets ("pings") to one or more remote computers and returns the echo response replies. You can use this cmdlet to determine whether a particular computer can be contacted across an Internet Protocol (IP) network.

Unlike the traditional "ping" command, Test-Connection returns a Win32_PingStatus object, but you can use the -Quiet parameter to force it to return only a Boolean value.

Test-Connection defaults to a static ICMP timeout of 4 seconds.

Examples

Ping from the local computer to the Server64 computer.:

PS C:\> test-connection server64

Use the -quiet parameter to return a True/False value:

PS C:\> If (Test-Connection server64 -count 1 -quiet) {
 Write 'The host responded'
}

Ping two computers using a credential/user account that has permission to ping those machines:

PS C:\> test-connection -computername server64, server65 -credential domain64\Admin01

Send pings from different source computers to a single remote computer, Server64. Use this command format to test the latency of connections from multiple points:

PS C:\> test-connection -source Server14, Server 15, localhost -computername Server64

Use this command format when the ping response is expected to take longer than usual, either because of an extended number of hops or a high-traffic network condition:

PS C:\> test-connection -computername Server64 -count 3 -delay 2 -TTL 256 -buffersize 256 -throttle 32

Run a Test-Connection command as a PowerShell background job:

PS C:\> $job = test-connection -computername (get-content servers.txt) -asjob
PS C:\> if ($job.jobstateinfo.state -ne "Running") {$results = receive-job $job}

Creates a PSSession on Server64 only if at least one of the pings sent to the computer succeeds:

PS C:\> if (test-connection -computername Server64 -quiet) {new-pssession Server64}

“And now I see with eye serene; the very pulse of the machine” ~ William Wordsworth, (She Was a Phantom of Delight)

Related PowerShell Cmdlets:

Test-Path - Return true if the path exists, otherwise return false.
psp - PowerShell Ping function.
Equivalent bash command: ping - Test a network resource.