Thank you for your feedback.
Form temporarily unavailable. Please try again or contact docfeedback@servicenow.com to submit your comments.

PowerShell for Discovery and Service Mapping

Log in to subscribe to topics and get notified when content changes.

PowerShell for Discovery and Service Mapping

Configure MID Servers to use PowerShell and PowerShell Remoting for accessing configuration items (CIs) during horizontal and top-down discovery.

PowerShell is used to control and automate the administration of Windows servers and applications.

MID Servers can use PowerShell to directly communicate with Windows servers using both WMI and WinRM protocols. For Windows services using the WinRM protocol, the PowerShell process establishes a secure PSSession (PowerShell Remoting session) that stays open until the MID Server finishes querying a Windows server. For Windows servers using the WMI protocol, the PowerShell process sends every PowerShell command with credentials.

As a failover, MID Servers use a WMI (Windows Management Instrumentation) Collector service that helps MID Servers to communicate with Windows servers. Patterns used to discover Windows servers or applications running on them, contain WMI and WinRM queries and commands to run on Windows servers. A WMI Collector service transfers WMI and WinRM queries and commands from the MID Server to Windows-based CIs and brings the results of the queries to the MID Server.

PowerShell is also the preferred method for performing discovery over multiple Windows domains. PowerShell allows a single MID Server to authenticate on servers on different domains using credentials stored on the instance.

If you do not configure MID Servers to use PowerShell and PowerShell Remoting, MID Servers use WMI.

PowerShell requirements

MID Servers using PowerShell must be installed on a supported Windows operating system.

ServiceNow supports these PowerShell versions:
Version Support
2.0 Discovery
3.0
  • Discovery
  • Application Dependency Mapping (ADM)
    Note: PowerShell version 3.0 does not support Windows Server 2003.
4.0
  • Discovery
  • Application Dependency Mapping (ADM)
5.0
  • Discovery
  • Application Dependency Mapping (ADM)
Note: PowerShell version 6.0 is not supported. Many of the cmdlets that discovery relies on have been removed from this version. For example, only cmdlets using WinRM are available for remote operations.

MID Server parameters for PowerShell

The following parameters are optional.
Note: After changing the setting for any parameter, be sure to restart the MID Server service.
Name Description
mid.powershell_api.session_pool.max_size

Specifies the maximum number of sessions allowed in the session pool.

Note: Setting or changing this parameter requires restarting the MID Server.
  • Type: Integer
  • Default value: 25
mid.powershell_api.session_pool.target.max_size

Specifies the maximum number of sessions allowed in the pool per target host.

Note: Setting or changing this parameter requires restarting the MID Server.
  • Type: Integer
  • Default value: 2
mid.powershell_api.winrm.use_ssl Requires the use of SSL certificates for HTTPS connections using WinRM.
  • Type: True | False
  • Default value: false
mid.powershell_api.winrm.additional_pssesion_options Controls advanced options for a PSSession. For more information about advanced PSSession options, refer to https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/new-pssessionoption?view=powershell-6.
mid.powershell_api.winrm.remote_https_port Configures the port for connecting to Windows servers using PowerShell over HTTPS.
  • Type: Integer
  • Default value: 5986
mid.powershell_api.winrm.remote_port Configures the port for connecting to Windows servers using PowerShell over HTTP.
  • Type: Integer
  • Default value: 5985
mid.powershell_api.winrm.skip_ssl_cert_check Skips the SSL certificate check when using WinRM for HTTPS connections.
  • Type: True | False
  • Default value: false
mid.powershell_api.winrm.skip_ssl_cert_check_options Skips specific SSL certificate checks when using WinRM for HTTPS connections. Configure the MID Server to skip checks for certificates from a Certification Authority (CA), from the Common Name (CN) that identifies the host associated with the certificate, and for revoked certificates.
  • Type: String
  • Default value: -SkipCACheck -SkipCNCheck -SkipRevocationCheck
mid.powershell.use_credentials Determines the credentials to use for Discovery with PowerShell. A setting of true directs the MID Server to run probes with the Windows credentials from the credentials table. To run probes with the credentials of the user for the MID Server service, set this parameter to false.
  • Type: true | false
  • Default value: true
mid.use_powershell Enables or disables PowerShell for Discovery. Restart the MID Server after changing the value. If PowerShell is not installed or the version installed is less than version 2.0, Discovery reverts to using WMIRunner.
  • Type: true | false
  • Default value: true, in the Fuji release.
  • Default value: false, in releases prior to Fuji.
mid.powershell.path Enables an administrator to point to a specific PowerShell on a MID Server in cases where more than one PowerShell is installed. Supply the path to the folder containing the PowerShell executable, for example, C:\mypowershell or C:\mypowershell\. ServiceNow automatically appends the string powershell.exe to the path. Configure this parameter when both a 32-bit and 64-bit PowerShells are active on the same MID Server, and it becomes necessary to launch the correct PowerShell for the context. 64-bit Windows employs file system redirection and the MID Server runs as a 32-bit application. If trying to specify a path in %WinDir%\System32, Windows automatically redirects to %WinDir%\SysWOW64. To avoid redirection, specify the path as %WinDir%\Sysnative. For example, instead of C:\WINDOWS\system32\WindowsPowerShell\v1.0\, specify C:\WINDOWS\sysnative\WindowsPowerShell\v1.0\.
Note: On a 64-bit version of Windows XP, a Microsoft hotfix may be required to enable this.

To discover applications running on a 64-bit Windows machine, the MID Server must be running on a 64-bit Windows host machine.

  • Type: string (path)
  • Default value: none
mid.powershell.enforce_utf8 Enable this parameter to force commands on a target Windows system to return UTF-8 encoded output. Disabling it allows the target system to use its default encoding. This parameter is only valid when PowerShell is enabled.

Setting this value to false may result in incorrect values in the CMDB when non-ASCII characters are returned by a probe.

  • Type: true | false
  • Default value: true
mid.powershell.local_mid_service_credential_fallback Enables automatically falling back to MID Server service credentials if all other credentials fail.
  • Type: true | false
  • Default value: true
mid.powershell_api.idle_session_timeout

Specifies the timeout value of idle PowerShell sessions in seconds.

Note: Setting or changing this parameter requires restarting the MID Server.
  • Type: Integer
  • Default value: 60
mid.powershell.command.parameter_passing Enable this parameter to allow passing PowerShell parameters from the command line.
  • Type: True | False
  • Default value: false
mid.powershell.command.script.parameter_passing Enable this parameter to allow passing PowerShell scripts from the command line.
  • Type: True | False
  • Default value: true
mid.windows.management_protocol
Enables administrators to select the Windows management protocol used for device and process classification. Options include:
  • WMI
  • WinRM
  • Type: String
  • Default value: WMI
mid.windows.probe_timeout Sets the timeout interval for all Windows probes on a specific MID Server. This value is overridden by the values configured for individual probes with the wmi_timeout probe parameter.
  • Type: Integer
  • Default value: 300

MID Server Script Includes

The following script includes were added for PowerShell discoveries. These scripts run on the MID Server to generate the scripts that Discovery uses for WMIRunner and PowerShell.
Script Include Description
GenerateWMIScriptJS Generates a Javascript script for the WMIRunner probe.
GenerateWMIScriptPS1 Generates a PowerShell script for PowerShell discovery.

Probe and sensor

When a Windows machine is classified with PowerShell, and an MSSQL instance is detected, a probe called Windows - MSSQL is launched. The probe returns the SQL database catalogs and version to a matching sensor.

Probe parameter

The WMI_ActiveConnections.ps1 probe parameter contains a script that runs netstat.exe on a target server when PowerShell is enabled. This script extracts the information on Windows server connections, such as process IDs, ports, and IP addresses.

Credentials

Discovery uses Windows PowerShell credentials from the Credentials [discovery_credentials] table or the domain administrator credentials of the MID Server service. If Discovery cannot find PowerShell credentials in the Credentials table of the type, Windows), it uses the login credentials of the MID Server service.

Set up MID Servers to use PowerShell

Configure MID Servers in your organization to use PowerShell for horizontal and top-down discovery of Windows servers.

Before you begin

Role required: admin

Procedure

  1. Download PowerShell and install it on each MID Server configured to discover Windows computers.
  2. Enable PowerShell-based discovery by setting the mid.use_powershell MID Server parameter to true on all the MID Servers.
  3. Enable discovery using PowerShell Remoting by setting the mid.sa.prefer_powershell MID Server property to true on all the MID Servers.
  4. Determine which credentials MID Servers use for PowerShell.
    • To discover Windows computers using credentials from the credentials table, set the mid.powershell.use_credentials parameter to true. Using credentials form the credentials table is the default behavior when PowerShell is enabled.
    • To force Discovery and Service Mapping to use the credentials of the MID Server service user, set the mid.powershell.use_credentials parameter to false on the MID Server. The MID Server service must have domain admin credentials to have access to the Windows machines in the domain.
  5. (Optional) If necessary, configure advanced parameters for PowerShell and PowerShell Remoting on each MID Server separately.
Feedback