< Back

Find-DbaInstance

Mon Jan 13, 2020 10:09 am

NAME Find-DbaInstance



SYNOPSIS

Search for SQL Server Instances.





SYNTAX

Find-DbaInstance [-Credential <Pscredential>] [-SqlCredential <Pscredential>] [-ScanType

<Sqlcollaborative.Dbatools.Discovery.DbaInstanceScanType[]>] [-DomainController <String>] [-TCPPort

<System.Int32[]>] [-MinimumConfidence <Sqlcollaborative.Dbatools.Discovery.DbaInstanceConfidenceLevel>]

[-EnableException <Switch>] [<CommonParameters>]



Find-DbaInstance -ComputerName <Sqlcollaborative.Dbatools.Parameter.DbaInstanceParameter[]> [-Credential

<Pscredential>] [-SqlCredential <Pscredential>] [-ScanType

<Sqlcollaborative.Dbatools.Discovery.DbaInstanceScanType[]>] [-DomainController <String>] [-TCPPort

<System.Int32[]>] [-MinimumConfidence <Sqlcollaborative.Dbatools.Discovery.DbaInstanceConfidenceLevel>]

[-EnableException <Switch>] [<CommonParameters>]



Find-DbaInstance -DiscoveryType <Sqlcollaborative.Dbatools.Discovery.DbaInstanceDiscoveryType> [-Credential

<Pscredential>] [-SqlCredential <Pscredential>] [-ScanType

<Sqlcollaborative.Dbatools.Discovery.DbaInstanceScanType[]>] [-IpAddress <System.String[]>] [-DomainController

<String>] [-TCPPort <System.Int32[]>] [-MinimumConfidence

<Sqlcollaborative.Dbatools.Discovery.DbaInstanceConfidenceLevel>] [-EnableException <Switch>] [<CommonParameters>]





DESCRIPTION

This function searches for SQL Server Instances.



It supports a variety of scans for this purpose which can be separated in two categories:



- Discovery



- Scan



Discovery:



This is where it compiles a list of computers / addresses to check.



It supports several methods of generating such lists (including Active Directory lookup or IP Ranges), but also

supports specifying a list of computers to check.



- For details on discovery, see the documentation on the '-DiscoveryType' parameter



- For details on explicitly providing a list, see the documentation on the '-ComputerName' parameter



Scan:



Once a list of computers has been provided, this command will execute a variety of actions to determine any

instances present for each of them.



This is described in more detail in the documentation on the '-ScanType' parameter.



Additional parameters allow more granular control over individual scans (e.g. Credentials to use).



Note on logging and auditing:



The Discovery phase is un-problematic since it is non-intrusive, however during the scan phase, all targeted

computers may be accessed repeatedly.



This may cause issues with security teams, due to many logon events and possibly failed authentication.



This action constitutes a network scan, which may be illegal depending on the nation you are in and whether you

own the network you scan.



If you are unsure whether you may use this command in your environment, check the detailed description on the

'-ScanType' parameter and contact your IT security team for advice.





PARAMETERS

-ComputerName [<Sqlcollaborative.Dbatools.Parameter.DbaInstanceParameter[]>]

The computer to scan. Can be a variety of input types, including text or the output of Get-ADComputer.

Any extra instance information (such as connection strings or live sql server connections) beyond the

computername will be discarded.



Required? false

Position? named

Default value

Accept pipeline input? False

Accept wildcard characters? false



-Credential [<Pscredential>]

The credentials to use on windows network connection.

These credentials are used for:

- Contact to domain controllers for SPN lookups (only if explicit Domain Controller is specified)

- CIM/WMI contact to the scanned computers during the scan phase (see the '-ScanType' parameter documentation

on affected scans).



Required? false

Position? named

Default value

Accept pipeline input? False

Accept wildcard characters? false



-DiscoveryType [<Sqlcollaborative.Dbatools.Discovery.DbaInstanceDiscoveryType>]

The mechanisms to be used to discover instances.

Supports any combination of:

- Service Principal Name lookup ('DomainSPN'; from Active Directory)

- SQL Instance Enumeration ('DataSourceEnumeration'; same as SSMS uses)

- IP Address range ('IPRange'; all IP Addresses will be scanned)

- Domain Server lookup ('DomainServer'; from Active Directory)



SPN Lookup:

The function tries to connect active directory to look up all computers with registered SQL Instances.

Not all instances need to be registered properly, making this not 100% reliable.

By default, your nearest Domain Controller is contacted for this scan.

However it is possible to explicitly state the DC to contact using its DistinguishedName and the

'-DomainController' parameter.

If credentials were specified using the '-Credential' parameter, those same credentials are used to perform

this lookup, allowing the scan of other domains.



SQL Instance Enumeration:

This uses the default UDP Broadcast based instance enumeration used by SSMS to detect instances.

Note that the result from this is not used in the actual scan, but only to compile a list of computers to scan.

To enable the same results for the scan, ensure that the 'Browser' scan is enabled.



IP Address range:

This 'Discovery' uses a range of IPAddresses and simply passes them on to be tested.

See the 'Description' part of help on security issues of network scanning.

By default, it will enumerate all ethernet network adapters on the local computer and scan the entire subnet

they are on.

By using the '-IpAddress' parameter, custom network ranges can be specified.



Domain Server:

This will discover every single computer in Active Directory that is a Windows Server and enabled.

By default, your nearest Domain Controller is contacted for this scan.

However it is possible to explicitly state the DC to contact using its DistinguishedName and the

'-DomainController' parameter.

If credentials were specified using the '-Credential' parameter, those same credentials are used to perform

this lookup, allowing the scan of other domains.



Required? false

Position? named

Default value

Accept pipeline input? False

Accept wildcard characters? false



-DomainController [<String>]

The domain controller to contact for SPN lookups / searches.

Uses the credentials from the '-Credential' parameter if specified.



Required? false

Position? named

Default value

Accept pipeline input? False

Accept wildcard characters? false



-EnableException [<Switch>]

By default, when something goes wrong we try to catch it, interpret it and give you a friendly warning message.

This avoids overwhelming you with "sea of red" exceptions, but is inconvenient because it basically disables

advanced scripting.

Using this switch turns this "nice by default" feature off and enables you to catch exceptions with your own

try/catch.



Required? false

Position? named

Default value

Accept pipeline input? False

Accept wildcard characters? false



-IpAddress [<System.String[]>]

This parameter can be used to override the defaults for the IPRange discovery.

This parameter accepts a list of strings supporting any combination of:

- Plain IP Addresses (e.g.: "10.1.1.1")

- IP Address Ranges (e.g.: "10.1.1.1-10.1.1.5")

- IP Address & Subnet Mask (e.g.: "10.1.1.1/255.255.255.0")

- IP Address & Subnet Length: (e.g.: "10.1.1.1/24)

Overlapping addresses will not result in duplicate scans.



Required? false

Position? named

Default value

Accept pipeline input? False

Accept wildcard characters? false



-MinimumConfidence [<Sqlcollaborative.Dbatools.Discovery.DbaInstanceConfidenceLevel>]

This command tries to discover instances, which isn't always a sure thing.

Depending on the number and type of scans completed, we have different levels of confidence in our results.

By default, we will return anything that we have at least a low confidence of being an instance.

These are the confidence levels we support and how they are determined:

- High: Established SQL Connection (including rejection for bad credentials) or service scan.

- Medium: Browser reply or a combination of TCPConnect _and_ SPN test.

- Low: Either TCPConnect _or_ SPN

- None: Computer existence could be verified, but no sign of an SQL Instance



Required? false

Position? named

Default value

Accept pipeline input? False

Accept wildcard characters? false



-ScanType [<Sqlcollaborative.Dbatools.Discovery.DbaInstanceScanType[]>]

The scans are the individual methods used to retrieve information about the scanned computer and any

potentially installed instances.

This parameter is optional, by default all scans except for establishing an actual SQL connection are

performed.

Scans can be specified in any arbitrary combination, however at least one instance detecting scan needs to be

specified in order for data to be returned.



Scans:

Browser

- Tries discovering all instances via the browser service

- This scan detects instances.



SQLService

- Tries listing all SQL Services using CIM/WMI

- This scan uses credentials specified in the '-Credential' parameter if any.

- This scan detects instances.

- Success in this scan guarantees high confidence (See parameter '-MinimumConfidence' for details).



SPN

- Tries looking up the Service Principal Names for each instance

- Will use the nearest Domain Controller by default

- Target a specific domain controller using the '-DomainController' parameter

- If using the '-DomainController' parameter, use the '-Credential' parameter to specify the credentials used

to connect



TCPPort

- Tries connecting to the TCP Ports.

- By default, port 1433 is connected to.

- The parameter '-TCPPort' can be used to provide a list of port numbers to scan.

- This scan detects possible instances. Since other services might bind to a given port, this is not the most

reliable test.

- This scan is also used to validate found SPNs if both scans are used in combination



DNSResolve

- Tries resolving the computername in DNS



Ping

- Tries pinging the computer. Failure will NOT terminate scans.



SqlConnect

- Tries to establish a SQL connection to the server

- Uses windows credentials by default

- Specify custom credentials using the '-SqlCredential' parameter

- This scan is not used by default

- Success in this scan guarantees high confidence (See parameter '-MinimumConfidence' for details).



All

- All of the above



Required? false

Position? named

Default value

Accept pipeline input? False

Accept wildcard characters? false



-SqlCredential [<Pscredential>]

The credentials used to connect to SqlInstances to during the scan phase.

See the '-ScanType' parameter documentation on affected scans.



Required? false

Position? named

Default value

Accept pipeline input? False

Accept wildcard characters? false



-TCPPort [<System.Int32[]>]

The ports to scan in the TCP Port Scan method.

Defaults to 1433.



Required? false

Position? named

Default value

Accept pipeline input? False

Accept wildcard characters? false



<CommonParameters>

This cmdlet supports the common parameters: Verbose, Debug,

ErrorAction, ErrorVariable, WarningAction, WarningVariable,

OutBuffer, PipelineVariable, and OutVariable. For more information, see

about_CommonParameters (https:/go.microsoft.com/fwlink/?LinkID=113216).



INPUTS



OUTPUTS



NOTES





Tags: Instance, Connect, SqlServer

Author: Scott Sutherland, 2018 NetSPI | Friedrich Weinmann (@FredWeinmann)



Website: https://dbatools.io

Copyright: (c) 2018 by dbatools, licensed under MIT

License: MIT https://opensource.org/licenses/MIT



Outside resources used and modified:

https://gallery.technet.microsoft.com/s ... a-60c5bb6b



-------------------------- EXAMPLE 1 --------------------------



PS C:\\>Find-DbaInstance -DiscoveryType Domain, DataSourceEnumeration



Performs a network search for SQL Instances by:

- Looking up the Service Principal Names of computers in Active Directory

- Using the UDP broadcast based auto-discovery of SSMS

After that it will extensively scan all hosts thus discovered for instances.

-------------------------- EXAMPLE 2 --------------------------



PS C:\\>Find-DbaInstance -DiscoveryType All



Performs a network search for SQL Instances, using all discovery protocols:

- Active directory search for Service Principal Names

- SQL Instance Enumeration (same as SSMS does)

- All IPAddresses in the current computer's subnets of all connected network interfaces

Note: This scan will take a long time, due to including the IP Scan

-------------------------- EXAMPLE 3 --------------------------



PS C:\\>Get-ADComputer -Filter "*" | Find-DbaInstance



Scans all computers in the domain for SQL Instances, using a deep probe:

- Tries resolving the name in DNS

- Tries pinging the computer

- Tries listing all SQL Services using CIM/WMI

- Tries discovering all instances via the browser service

- Tries connecting to the default TCP Port (1433)

- Tries connecting to the TCP port of each discovered instance

- Tries to establish a SQL connection to the server using default windows credentials

- Tries looking up the Service Principal Names for each instance

-------------------------- EXAMPLE 4 --------------------------



PS C:\\>Get-Content .\\servers.txt | Find-DbaInstance -SqlCredential $cred -ScanType Browser, SqlConnect



Reads all servers from the servers.txt file (one server per line),

then scans each of them for instances using the browser service

and finally attempts to connect to each instance found using the specified credentials.

then scans each of them for instances using the browser service and SqlService

-------------------------- EXAMPLE 5 --------------------------



PS C:\\>Find-DbaInstance -ComputerName localhost | Get-DbaDatabase | Format-Table -Wrap



Scans localhost for instances using the browser service, traverses all instances for all databases and displays

all information in a formatted table.

-------------------------- EXAMPLE 6 --------------------------



PS C:\\>Find-DbaInstance -ComputerName localhost | Get-DbaDatabase | Select-Object SqlInstance, Name, Status,

RecoveryModel, SizeMB, Compatibility, Owner, LastFullBackup, LastDiffBackup, LastLogBackup | Format-Table -Wrap



Scans localhost for instances using the browser service, traverses all instances for all databases and displays a

subset of the important information in a formatted table.



Using this method regularly is not recommended. Use Get-DbaService or Get-DbaRegServer instead.



RELATED LINKS

https://dbatools.io/Find-DbaInstance