Managing the discovery platform scripts

Discovery scripts and upgrade

Where this topic refers to default scripts, it refers to the discovery scripts that were shipped with the release. For example, in a version 20.08 (12.1) appliance, the default scripts are those that shipped with 20.08 (12.1). If you upgrade the appliance to version 21.05, the default scripts become those that shipped with version 21.05.

When you upgrade from one BMC Discovery version to a later version, the discovery scripts may change to implement the new capabilities of the release or to fix defects in the scripts. The new scripts replace the default scripts from the previous release. However, if you have customized any discovery scripts, those are not replaced. Platforms with modified scripts are shown on the Discovery Platforms page with a change bar. When you click through to the platform page you can see the individual scripts that have been modified. Where a script has been modified you are provided with the following additional controls:

• Show Differences – shows side by side versions of the current file and the modified file with highlighted changes. Use this view to identify your modifications, and the changes made during the upgrade, and decide how to move your changes to the new default script.
• Reset To Default – replaces the modified file with the new default script.

To view the existing scripts

1. From the main menu, click the Administration icon. 
   The Administration page is displayed. 

2. In the Discovery section, click Platforms.
   The Discovery Platforms page lists the categories for which discovery commands are provided. Each category displays headers that link to pages containing details of discovery methods used. Some additional information associated with a header might be displayed as a tooltip. The following table summarizes the available discovery methods in these pages.

   Category	Discovery method
   Windows discovery	The discovery methods used are Scripts, WMI, RemQuery, and SNMP. Scripts refers to the discovery scripts that are used through PowerShell remoting or an AWS Systems Manager session. Windows discovery uses PowerShell, if it is available, as the primary method of discovery.  Windows discovery uses WMI and RemQuery if PowerShell is not available. Even though two different techniques are used as a single method of discovery, it is considered to be a single session. If WMI and RemQuery access fails to establish the initial session, Windows discovery attempts to use SNMP. After an initial session is established, Discovery does not attempt another session. For example, if WMI and RemQuery establishes the initial session but discovery is incomplete, it does not attempt another session by using SNMP. A Path Restrictions tab is also available enabling you to restrict the paths used for running commands on Windows discovery targets. For more information, see Restricting-paths-on-which-you-can-execute-discovery-commands.
   UNIX, Linux & Related Discovery	The discovery methods used are Shell Scripts and SNMP. For VMware ESX and ESXi platforms, vSphere API calls are used. UNIX, Linux, and related discovery uses an interactive login (ssh, telnet, or rlogin) and running shell scripts as the primary method of discovery (for VMware ESX and ESXi platforms, vSphere API calls are used as the primary method of discovery). If the primary method of discovery fails to establish the initial session, BMC Discovery attempts SNMP. After an initial session is established, BMC Discovery does not attempt another session (for example, if interactive login and running shell scripts establish the initial session, even if some scripts fail or commands are not successfully executed, BMC Discovery does not attempt another session with SNMP). A Path Restrictions tab is also available enabling you to restrict the paths used for running commands on UNIX, Linux & Related discovery targets. For more information, see Restricting-paths-on-which-you-can-execute-discovery-commands. Important The rlogin access method that is used to connect to an endpoint is not a secure protocol as communication is not encrypted. Rlogin is not available in the BMC Discovery Outpost UI. If required, you can use rlogin in the appliance UI.
   Mainframe	BMC Discovery uses z/OS Agents (BMC Discovery for z/OS Agent) to obtain information about Mainframes.
   SNMP supported platforms	SNMP discovery is supported for all devices with an accessible SNMP agent. BMC Discovery supports SNMP v1, v2c, and v3.

3. Where the discovery scripts have been changed from the default, a change bar is shown to the left of the platform name.

Amending the existing scripts

You can only edit and enable or disable selected shell and PowerShell scripts from the Discovery Platforms page. You can only view the following methods, they cannot be modified:

• WMI
• RemQuery
• SNMP
• vSphere
• Mainframe

To edit existing scripts

1. On the Discovery Platforms page, click the OS link corresponding to the commands you want to edit. 
2. Click the Shell Scripts tab.
   The commands for the OS are displayed. The following table describes the fields on this page:

      3. Click Apply to save the changes.

Editing PowerShell scripts

PowerShell scripts can be edited just as UNIX or Linux shell scripts. The output of a PowerShell session can contain complex objects, for which, parsing will almost certainly yield unexpected results. Ensure that any script changes you make return text using the Format-List cmdlet.

Additional discovery

In addition to the standard discovery commands described in the previous section, additional discovery methods can be called by patterns. For more information, see manual pattern execution and DiscoveryAccess-page. The following methods are used:

• getFileInfo—Used where a pattern uses the discovery-fileInfo to return a file. The result is stored in a DiscoveredFile node.
• getFileMetadata—Used where a pattern uses the discovery-fileGet to return the metadata on a file. The result is stored in a DiscoveredFile node with no content attribute.
• runCommand—Used where a pattern uses the discovery-runCommand function to run a command on a host during its execution. The result is stored in a DiscoveredCommandResult node.
• getDirectoryListing—Used where a pattern uses the discovery-listDirectory function to return a list of the directory contents. Returns a list of DiscoveredDirectoryEntry nodes.

Returning command exit status data

The commands that BMC Discovery runs on UNIX hosts are all standard UNIX commands that you can view through the UI. When BMC Discovery runs these commands, they return an exit status code. BMC Discovery provides the ability to record exit status codes and output to stderr where commands fail. Success is not recorded.

Bear in mind standard scripting techniques when editing these commands. For example, some BMC Discovery commands use pipelines and might need to be modified so as not to mask the desired exit status code. Exit status codes are OS, OS version, and command dependent. Consult your OS documentation for information about exit status codes and their meanings.

Recording the exit status

To record exit status, you must prefix the discovery commands with tw_capture. The first parameter is a name used to identify the captured information. The second parameter is the command to run, and any further parameters are passed to the command; or example:

You can record an exit status from commands used in a pipeline; for example:

It can also be used in backticks; for example, when running a command and assigning the result to a shell variable:

The following screen shows two example tw_capture commands: one that will succeed, and one that will fail. These commands have been added to the start of the getDeviceInfo method:

To view the exit status

After you have added the tw_capture commands and discovered a host, causing the method to be run, you can see any command failures by viewing the appropriate method link on the Discovery Access page.

1. From the Discovery Recent Runs tab, click the discovery run that you used to scan the host.
2. Click DiscoveryAccess.
   If it is a link to a single DiscoveryAccess, then that DiscoveryAccess page is shown. If there are multiple DiscoveryAccesses, a list page is displayed.
3. Click the method link for the method that you edited to add the return status.
4. Any failures can be seen by clicking the link to related Command Failures.