Test Subnet with PowerShell

A few years ago I published a PowerShell function to test IP addresses on a given subnet. I had an email the other day about it and I decided to refresh it. My new version adds a few bells and whistles that I think you might like. For example, you can now run it from a remote computer. In other words, you can ping IP addresses from another computer which might be helpful.

I've also added an option to resolve the IP address to a hostname using DNS. Because I don't want to require anything on a remote computer, I am using the .NET DNS class to resolve the name. In addition, I have included a fallback resolution using NETBIOS. If you ask for resolution, and DNS doesn't return a name, you can opt to use the NBTSTAT command to resolve the hostname. I use a regular expression pattern to pull the computername.

Here's version 2.0 of Test-Subnet.

#requires -version 3.0

Function Test-Subnet {

<#
.SYNOPSIS
Ping addresses in an IP subnet
.DESCRIPTION
This command is a wrapper for Test-Connection. It will ping an IP subnet range
and return a custom object for each address indicating if the address responded
to a ping.

IPAddress      : 172.16.10.1
Hostname       : 
Pinged         : True
TTL            : 80
Buffersize     : 32
Delay          : 1
TestDate       : 4/25/2014 9:53:08 AM
PSComputerName : JH-WIN81-ENT
RunspaceId     : ac86e6eb-676f-4e80-b231-4b554e2e5039

By default the command pings all hosts from 1 to 254 on the specfied subnet. 
Enter the subnet value like this: 172.16.10.0.

You can optionally choose to resolve the IP address to a hostname using DNS
with a last resort, if that fails, to use NETBIOS.

.PARAMETER Subnet
The IP subnet such as 192.168.10.0. A regular expression pattern will validate
the subnet value.
.PARAMETER Range
The range of host IP addresses. The default is 1..254.
.PARAMETER Count
The number of pings to send. The default is 1. The most
you can send with this command is 10.
.PARAMETER Delay
The delay between pings in seconds. The default is 1. The maximum value is 60.
.PARAMETER Buffer
Specifies the size, in bytes, of the buffer sent with this command.
The buffer default is 32.
.PARAMETER TTL
Specifies the maximum time, in seconds, that each echo request packet 
("pings") is active. The default value is 80 (seconds). 
.PARAMETER AsJob
Run the command as a background job.
.PARAMETER Resolve
Resolve the DNS host name if the computer can be pinged.
.PARAMETER UseNBT
If the host name cannot be resolved using DNS, attempt to resolve using NETBIOS
and the NBTSTAT command.
.PARAMETER Computername
Test the subnet from a remote computer. The default is the local host.
The remote computer should be running PowerShell v3 or later but it is not
required as long as remoting is enabled.
.EXAMPLE
PS C:\> Test-Subnet 192.168.10.0
Ping all computers in the 192.168.10 subnet.
.EXAMPLE
PS C:\> Test-Subnet 192.168.10.0 (100..200) -asjob
Ping computers 192.168.10.100 through 192.168.10.200 and run the command as a 
background job.
.NOTES
NAME        :  Test-Subnet
VERSION     :  2.0   
LAST UPDATED:  4/25/2014
AUTHOR      :  Jeffery Hicks

Learn more:
 PowerShell in Depth: An Administrator's Guide (http://www.manning.com/jones2/)
 PowerShell Deep Dives (http://manning.com/hicks/)
 Learn PowerShell 3 in a Month of Lunches (http://manning.com/jones3/)
 Learn PowerShell Toolmaking in a Month of Lunches (http://manning.com/jones4/)

  ****************************************************************
  * DO NOT USE IN A PRODUCTION ENVIRONMENT UNTIL YOU HAVE TESTED *
  * THOROUGHLY IN A LAB ENVIRONMENT. USE AT YOUR OWN RISK.  IF   *
  * YOU DO NOT UNDERSTAND WHAT THIS SCRIPT DOES OR HOW IT WORKS, *
  * DO NOT USE IT OUTSIDE OF A SECURE, TEST SETTING.             *
  ****************************************************************

Originally published https://jdhitsolutions.com/blog/2011/11/ping-ip-range/

.LINK
https://jdhitsolutions.com/blog/2014/04/test-subnet-with-powershell/
.LINK
Test-Connection 
.INPUTS
None
.OUTPUTS
Custom object
#>

[cmdletbinding(DefaultParameterSetName="NoResolve")]

Param (
[Parameter(Position=0)]
[ValidatePattern("\d{1,3}\.\d{1,3}\.\d{1,3}\.0")]
[string]$Subnet="172.16.10.0",
[Parameter(Position=1)]
[ValidateRange(1,254)]
[int[]]$Range=1..254,
[ValidateRange(1,10)]
[int]$Count=1,
[ValidateRange(1,60)]
[int]$Delay=1,
[ValidateScript({$_ -ge 1})]
[int]$Buffer=32,
[ValidateScript({$_ -ge 1})]
[int]$TTL=80,
[Switch]$AsJob,
[Parameter(ParameterSetName="Resolve")]
[Switch]$Resolve,
[Parameter(ParameterSetName="Resolve")]
[Switch]$UseNBT,
[ValidateNotNullorEmpty()]
[string[]]$Computername=$env:COMPUTERNAME
)

Write-Verbose "Testing $subnet"
#define a scriptblock so we can run as a job if necessary
$sb={

#define some variables for Write-Progress
$progHash=@{
Activity = "Test Subnet from $($env:computername)"
Status = "Pinging"
CurrentOperation = $Null
PercentComplete = 0
}

Write-Progress @progHash

$i=0
$total = ($using:Range).count

Foreach($node in ($using:range)) {

    $i++
    
    $progHash.PercentComplete = ($i/$total) * 100

    #replace the 0 with the range number
    $target= ([regex]"0$").replace($using:subnet,$node)

    $progHash.CurrentOperation = $target
    Write-Progress @progHash
    
    #define a hashtable of paramters to splat to Test-Connection
    $pingHash = @{
      ComputerName = $target
      count = $using:count
      Delay = $using:delay
      BufferSize = $using:Buffer
      TimeToLive = $using:ttl
      Quiet = $True
    }

    $ping = Test-Connection @pingHash 
    
    if ($ping -AND $using:resolve) {
        $progHash.status =  "Resolving host name"
        Write-Progress @progHash
        <#
        using .NET because there's no guarantee remote computers
        will have the necessary cmdlets, and this should also be
        faster.
        #>
        $Hostname = [system.net.dns]::Resolve("$target").hostname

        if ($UseNBT -AND ($hostname -eq $target)) {
            Write-verbose "Resolving with NBTSTAT"
            [regex]$rx="(?<Name>\S+)\s+<00>\s+UNIQUE"                                                              
            $nbt = nbtstat -A $target | out-string
            $Hostname = $rx.Match($nbt).groups["Name"].value    

        }
    }
    else {
        $Hostname = $Null
    }

    #use an ordered hashtable if running v3 or later
    if ($PSVersionTable.PSVersion.Major -ge 3) {
        $resultHash = [ordered]@{
            IPAddress = $Target
            Hostname = $Hostname
            Pinged = $ping
            TTL = $using:TTL
            Buffersize = $using:buffer
            Delay = $Using:Delay
            TestDate = Get-Date
        }
    }
    else {
       $resultHash = @{
            IPAddress = $Target
            Hostname = $Hostname
            Pinged = $ping
            TTL = $using:TTL
            Buffersize = $using:buffer
            Delay = $Using:Delay
            TestDate = Get-Date
        }
    }

    #create the property
    New-Object -TypeName PSObject -Property $resultHash
}
} #close scriptblock


#hashtable of parameters for Invoke-Command
$icmHash = @{
  Scriptblock = $sb
  Computername = $Computername
}
if ($AsJob) {
    Write-Verbose "Creating a background job"
    #Start-Job -ScriptBlock $sb -Name "Ping $subnet" 
    $icmHash.Add("AsJob",$True)
    $icmHash.Add("JobName","Ping $subnet") 
}
 Write-Verbose "Running the command"
 Invoke-Command @icmHash 
 
} #end function

And to be clear, "subnet" may be a bit of a misnomer as I'm not calculating any addresses with a subnet mask. Instead you enter the base IPAddress, like 10.10.1.0 and then a range of host numbers between 1 and 254, which is the default by the way. The command will then test 10.10.1.1 through 10.10.1.254, or whatever you entered.

My script employs some other techniques you might find help such as splatting, parameter sets, Write-Progress and parameter validation. Here's a screenshot of results that I've sent to Out-Gridview and then customized.

But since the command writes objects to the pipeline you could do whatever you wanted. I trust you'll let me know what you think. Enjoy!!

---

---