Discovery CLI - Support and Troubleshooting

Discovery CLI Discovery CLI

This feature augments your ServiceNow CLI experience by introducing a suite of commands exclusively dedicated to discovery processes.

With the Discovery CLI, you have the power to streamline your Discovery operations in a few simple steps:

- Host Configuration: The Discovery CLI allows you to specify the host of your ServiceNow instance. Whether you use the full URL or just the hostname, this CLI caters to your specific needs.

- Login Method Selection: Choose your preferred login method. The interface supports various methods, with a special note that the ui-component extension exclusively supports the Basic authentication method.

- User Credentials: Provide your username and password for authentication. Your credentials are handled securely, ensuring a safe and reliable connection to your ServiceNow instance.

- Output Format Customization: Tailor your command results with ease. The Discovery CLI lets you customize output formats according to your preference - be it JSON, YAML, plain text, or a structured table format.

This powerful suite of commands not only simplifies your discovery processes but also enhances the efficiency of your IT workflows. By integrating these commands into your daily operations, you can ensure that your discovery tasks are executed swiftly and accurately.

Prerequisites:

To utilize the discovery command group in the ServiceNow instance, the following plugins need to be installed:

Discovery Plugin CLI Metadata Plugin Pattern Designer Enhancement Plugin Make sure these plugins are installed and activated in your ServiceNow instance before using the discovery cli commands.

Command Group

Name: discovery

Description: The discovery command group empowers administrators with essential tools to orchestrate and optimize discovery processes in the ServiceNow instance. These commands facilitate a wide array of tasks, from gaining deep insights into discovery configurations to executing specific commands on remote devices. With the ability to fetch credentials, retrieve pattern details, and test configurations, this command group ensures seamless discovery operations within the ServiceNow ecosystem.

Synopsis: snc discovery [arguments]

Available Commands:

Discovery Insights:

Command: snc discovery discovery-insights Description: Gain comprehensive insights into discovery configurations, custom pattern details, and plugin information. Understand the nuances of your instance's discovery setup. Roles Required: discovery_admin

Note: To enable the successful execution of this command and retrieve data from CMDB, it's essential to grant read access to the following tables:

Disco Log ( discovery_log ) Update Version ( sys_update_version ) Example snc discovery discovery-insights Output : The command returns a JSON(default) object containing the following information: Customized Patterns: patternName: Name of the customized pattern. source: Source from which contains the customized changes (e.g., Default). Instance Details: buildDate: Date of the instance build (format: MM-DD-YYYY_HHMM). buildName: Name of the instance build. Plugin Details: Pattern Designer Enhancements: Version of the Pattern Designer Enhancements plugin. Visibility Content: Version of the Visibility Content plugin. & plugins related to discovery configurations Return value { "customisedPattern": [ { "patternName": "A10", "source": "Default" }, { "patternName": ".NET Application", "source": "Default" } ], "instanceDetails": { "buildDate": "09-16-2023_2010", "buildName": "utah-p0" }, "pluginDetails": { "CMDB CI Class Models": "1.48", "Discovery and Service Mapping Patterns": "1.8.0", "Pattern Designer Enhancements": "3.1.0", "Visibility Content": "6.13.0" } } Get Discovery Credentials:

Command: snc discovery get-discovery-credentials [--testableonly= ] Description: Retrieve a list of available discovery credentials. Optionally, filter and include only credentials that can be tested for immediate validation. Roles Required: discovery_admin

Examples: List discovery credentials $ snc discovery get-discovery-credentials List testable discovery credentials only $ snc discovery get-discovery-credentials --testableonly="true" Output: snc discovery get-discovery-credentials ✔ Get only testable credentials [ssh, snmpv3, snmp, ssh_private_key, windows, vmware, jdbc, jms]: false ✔ Discovery credentials details retrieved { "credentials": [ { "active": true, "name": "WindowsCred", "type": "windows", "updated": "2023-10-10 12:18:17" } { "active": true, "name": "shCred", "type": "ssh", "updated": "2023-10-12 08:00:32" }, { "active": true, "name": "public", "type": "snmp", "updated": "2023-09-28 07:40:35" }, { "active": true, "name": "Windows MID Server Service Account", "type": "windows", "updated": "2023-09-28 07:40:35" } ] } Get MID Servers:

Command: snc discovery get-midservers [--include-issues= ] Description: Fetch detailed information about MID Servers, including status, validation details, and any associated issues. Optionally, include mid-server issues in the output. Roles Required: discovery_admin

Examples: Retrieve Mid Servers Command: $ snc discovery get-midservers The command, get-midservers, fetches essential details about mid servers, allowing users to obtain critical insights into their operational status and attributes. Retrieve Mid-servers with issue logs Command: $ snc discovery get-midservers --include-issues=true The command, get-midservers --include-issues, goes a step further by fetching mid-server information and presenting any issue logs associated with each mid-server. Output: ✔ Mid-server details were fetched successfully. { "mid_servers": [ { "home_directory": "C:\\Users\\admin\\Desktop\\midInstallationFolder\\agent", "host_name": "LocalLab", "host_os_version": "10.0.xxxx", "ip_address": "192.168.0.1", "issues": [], "last_refreshed": "2023-10-01 00:00:00", "name": "WindowsMidServer", "started": "2023-10-01 00:01:01", "status": "Up", "sys_id": "cb8d1625c3fdb110c72691477d01312e", "unresolved_issues": "0", "validated": "true", "validated_at": "2023-10-01 00:01:01" } ] } Get Patterns:

Command: snc discovery get-patterns Description: Retrieve a comprehensive list of available discovery patterns within the instance. Understand the variety of patterns available for discovery operations. Roles Required: discovery_admin

Examples Usage: snc discovery get-patterns Retrieve a comprehensive list of available discovery patterns.

Output: ✔ Details of Discovery Patterns successfully retrieved. [ { "active": true, "ci_type": "cmdb_ci_appl_dot_net", "name": ".NET Application", "pattern_type": "1 - Application" }, { "active": true, "ci_type": "cmdb_ci_lb_service", "name": "A10", "pattern_type": "1 - Application" }, { "active": true, "ci_type": "cmdb_ci_lb_a10", "name": "A10 Load Balancer", "pattern_type": "3 - Infrastructure" }, { "active": true, "ci_type": "cmdb_ci_lb_a10", "name": "A10 Load Balancer SSH", "pattern_type": "3 - Infrastructure" }, { "active": true, "ci_type": "cmdb_ci_appl_generic", "name": "A10 SSH Hosting Formatting", "pattern_type": "2 - Shared library" }, ...... ] Get Pattern Commands:

Command: snc discovery get-pattern-commands --pattern=" " Description: Retrieve a detailed list of commands associated with a specific discovery pattern identified by name or sysId. Understand the commands executed during discovery. Roles Required: discovery_admin

Examples: snc discovery get-pattern-commands --pattern="Windows OS - Servers" snc discovery get-pattern-commands --pattern="670e55a4db702200c06776231f961942" By executing this command, you gain insight into the commands associated with a particular discovery pattern. This information is vital for understanding the actions performed during the discovery process and for customizing pattern behaviors to suit your environment. Output: ✔ Commands fetched successfully. [ { "Command": "\"\\root\\CIMV2\" \"SELECT Caption,IPAddress,MACAddress,DHCPEnabled,Index,InterfaceIndex,IPEnabled FROM Win32_NetworkAdapterConfiguration\"", "Command Type": "wmi", "sys_id": "2e677c4ec3adb1106618b10ad0013185" }, { "Command": "\"\\root\\CIMV2\" \"SELECT Index,InterfaceIndex,Name,Manufacturer,NetConnectionID FROM Win32_NetworkAdapter\"", "Command Type": "wmi", "sys_id": "6a677c4ec3adb1106618b10ad0013185" }, { "Command": "powershell -command \\Get-NetRoute -AddressFamily IPv6\\", "Command Type": "shell", "sys_id": "a6677c4ec3adb1106618b10ad0013185" }, { "Command": "\"\\root\\CIMV2\" \"SELECT Destination,Mask,NextHop, InterfaceIndex FROM Win32_IP4RouteTable\"", "Command Type": "wmi", "sys_id": "e2677c4ec3adb1106618b10ad0013185" }, { "Command": "\"\\root\\CIMV2\" \"SELECT DefaultIPGateway FROM Win32_NetworkAdapterConfiguration\"", "Command Type": "wmi", "sys_id": "e6677c4ec3adb1106618b10ad00131ab" }, ........ ] Run Command:

Command: snc discovery run-command --command=" " --command-type=" " --credential=" " --midserver=" " --os-server=" " --target=" " Description: Execute specific commands on remote devices using designated credentials, targets, and MID Servers. Enable seamless interaction with remote systems. Roles Required: discovery_admin

Examples: snc discovery run-command --command="\"\\root\\CIMV2\" \"SELECT UUID,IdentifyingNumber FROM Win32_ComputerSystemProduct\"" --command-type="wmi" --credential="WinCred" --midserver="WinMidServer" --os-server="cmdb_ci_win_server" --target="192.168.1.1"

Execute this command to run a specified command on a target device using a particular credential and mid-server. This enables the execution of tasks on remote devices while leveraging the capabilities of a designated mid-server, facilitating efficient data collection and management. Output: ✔ The command is sent for execution. { "eccQueueOutputSysId": "9a3c55a3c33db910c72691477d0131cd" } ✔ Command Executed Successfully... { "result": { "IdentifyingNumber": "VMware-00 00 00 00 00 00 00 00-00 00 00 00 00 00 00 00", "Name": "VMware Virtual Platform", "Object Reference": null, "UUID": "61410042-XXXX-XXXX-XXXX-XXXXXXXXXXXX", "Version": "None", "__CLASS": "Win32_ComputerSystemProduct", "internal_classname": "Win32_ComputerSystemProduct", "internal_namespace": "root/cimv2" } } Test Discovery Credential:

Command: snc discovery test-discovery-credential --name=" " --target=" " --midserver=" " Description: Validate the correctness of a discovery credential against a specified target system using a designated MID Server. Ensure the readiness of credentials for network discovery tasks. Roles Required: discovery_admin

Limitation (Known Issue): Users may encounter an "Access Denied" error referencing the cryptographic module 'global.com_snc_core_automation_connection_credential_glideencrypter' while trying to run the command. This error occurs when accessing the module for decryption purposes. This issue is recognized and being tracked under PRB1705566.

Resolution: To resolve this, it is necessary to import the attached XML file into the Module Access Policy list. This action will enable proper access and address the decryption-related issue associated with the 'global.com_snc_core_automation_connection_credential_glideencrypter' module. Output : If the credential is valid, the connection to the target system is successful, and the specified MID Server is operational, the command will return a success message. If the credential is invalid, the connection fails, or the specified MID Server is unavailable, an error message detailing the issue will be displayed. Note: This command does not modify or affect the configuration of the discovery credential or the target system. It is purely for testing purposes. Ensure that the specified target system is reachable, and the specified MID Server is operational and accessible from the host where this command is executed.

Arguments --dbname string Name of the database on which to test these credentials --dbtype string Type of database on which to test these credentials, MSSQL, MySQL, or Oracle --icf string Name of the JNDI class that is used to create the InitialContext. For example, to connect to ActiveMQ: org.apache.activemq.jndi.ActiveMQInitialContextFactory --midserver string MID Server to use for this test. You must use a Windows MID Server to test "Windows" credentials --name string Credential name --port string Port on the target to use for this test. The system pre-populates this field with the default port for the selected credential type --target string Target host on which these credentials are run. This value must be an IP address for all credential types except VMware, which can be the host URL. Examples snc discovery test-discovery-credential [arguments] snc discovery test-discovery-credential --name="WinCred" --target="192.168.1.1" --midserver="WinMidServer" Quick Discovery:

Command: snc discovery quick-discovery -type ip -target 192.168.1.100 Description: Execute quick discovery against a specific CI or IP address. Roles Required: discovery_admin

Arguments --error-logs-only Return error logs only? (default false) --target string Target host --type string Quick discovery type: CI or IP Execute a quick discovery against a target entity using specified criteria. Examples: snc discovery quick-discovery -type ip -target 192.168.1.100 snc discovery quick-discovery -type ci -target d0e8761137201000deeabfc8bcbe5da7 snc discovery quick-discovery -type ci -target ecommerce001 snc discovery quick-discovery -type ci -target L3BB911 Note: When callback retries exceed the max limit, you may receive a similar message indicating discovery progress. To track progress, check "snc discovery get-discovery-logs" or the instance for updates on Discovery Status. ✗ Discovery Failed. { "CurrentActivity": "", "DiscoveryStatus": {}, "State": "Active" } Execute this command to perform quick discovery against a target entity, with options to specify the type and target. Examples include IP addresses and configuration items (CIs). Be aware of possible callback limitations and use the provided tools for tracking progress and logs. Output: snc discovery quick-discovery --type ip --target ✔ Discovery job submitted Status Number: DIS0010054 ✔ Discovery is complete { "DiscoveryLogs": [ { "CI": "v-w2k12-clus1@Hyper-V Server", "Created": "2023-10-17 08:16:28", "Device": " ", "ECCQueueInput": "MultiProbe", "Level": "1", "Message": "Failed to access target system. Please check credentials and firewall settings on the target system to ensure accessibility: Access is denied. (Exception from HRESULT: 0x80070005 (E_ACCESSDENIED))", "Source": "Discovery", "Status": "DIS0010054" }, { "CI": "v-w2k12-clus1@Hyper-V Server", "Created": "2023-10-17 08:16:28", "Device": " ", "ECCQueueInput": "MultiProbe", "Level": "1", "Message": "Failure(s) with available Windows credentials from the instance.", "Source": "Discovery", "Status": "DIS0010054" }, { "CI": "v-w2k12-clus1@Hyper-V Server", "Created": "2023-10-17 08:16:28", "Device": " ", "ECCQueueInput": "MultiProbe", "Level": "1", "Message": "Authentication failure with the local MID server service credential.", "Source": "Discovery", "Status": "DIS0010054" } ], "DiscoveryStatus": [ { "Completed": "6", "Created": "2023-10-17 08:13:43", "Description": "Discover CI", "Discover": "CIs", "Duration": "1970-01-01 00:03:58", "Number": "DIS0010054", "Schedule": "", "Started": "6", "State": "Completed", "Updated": "2023-10-17 08:17:47" } ], "State": "Completed" } Get Discovery Logs:

Command: snc discovery get-discovery-logs --status-id="DIS0010013" --ecc-queue-logs="true" --devices="true" --pattern-logs="true" Description: Retrieve discovery logs with flexible options including status filtering, device inclusion, ECC queue logs, pattern logs, and output format choices using the snc discovery get-discovery-logs command. Roles Required: discovery_admin

Example: Usage: snc discovery get-discovery-logs [options] Retrieve discovery status, associated discovery logs, and related logs based on specified options. Options: --status-id= Filter logs by the provided discovery status number. --devices= Include device-specific logs. Possible values: "true" or "false". --ecc-queue-logs= Include associated ECC queue logs. Possible values: "true" or "false". --pattern-logs= Include pattern execution logs. Possible values: "true" or "false". --pattern-log-level= Filter pattern logs by severity level. DEBUG: Include only DEBUG log messages. ERROR: Include ERROR and DEBUG messages only. WARN: Include WARN, ERROR, and DEBUG messages only. INFO: Include all messages (default). --output-format= Specify the output format for logs. Supported formats: "table", "json (default)" Examples: snc discovery get-discovery-logs Discovery status number: DIS0010013 Include Devices: true Include ECC Queue logs: true Include pattern execution logs: true Pattern max log level (INFO, WARN, ERROR, DEBUG): DEBUG Maximum number of log records to return: 100 Output format [supported: json(default), table]: json OR snc discovery get-discovery-logs --status-id="DIS0010013" --ecc-queue-logs="true" --devices="true" --pattern-logs="true" --output-format="table" Execute this command to retrieve discovery status, associated logs, and optional extended logs using specified options. Customize the log retrieval by filtering based on status ID, including devices, ECC queue logs, and adjusting output format. Mid Server Action:

Command: snc discovery midserver-action --mid-server="WinMidServer" --action="restart" Description: Execute various actions on mid servers within the ServiceNow Discovery framework using the snc discovery midserver-action command. Roles Required: discovery_admin

Arguments -a, --action string name of the action that you wish to run on the selected mid server -m, --mid-server string Name or SysId of the mid-server Examples Usage: snc discovery midserver-action [options] Perform various actions on mid servers. Options : --mid-server [-m]= Specify the name or identifier of the mid server. --action [-a]= Specify the action to perform on the mid server. Available actions include: - invalidate - resume - stop - pause - autoUpgrade - upgrade - restart - file_discovery_refresh - grab_logs - validate For detailed help information on a specific command, run: snc discovery --help The discovery command group is a robust toolkit for discovery administrators, streamlining various discovery-related activities and ensuring the ServiceNow instance operates at peak efficiency.

Release Information

Release: November 2023 Store

Application version: 3.3.0

Previous version: 3.1.0

Note: This is the fifth release of this scoped application.