Managing the discovery platform scripts

The discovery system runs various scripts through the login session to obtain information from the host systems. From the BMC Helix Discovery user interface, you can:

• View scripts
• Amend scripts (edit script parameters; enable or disable scripts)

However, you cannot add new scripts. 

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.  The discovery of Windows AWS EC2 hosts by using AWS Systems Manager is provided by using a currently undocumented, non-interactive mode. Support for undocumented features is not guaranteed by AWS, so there is a possibility it might change, or be removed. The non-interactive command mode, runs individual scripts, as a single string, in separate sessions. As the script is executed as a single string, powershell.exe discovery_script, you must: use semicolon statement delimiters put comments on separate lines (not use end of line comments).  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 Helix Discovery attempts SNMP. After an initial session is established, BMC Helix 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 Helix 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.
   Mainframe Discovery	BMC Helix Discovery uses z/OS Agents (BMC Discovery for z/OS Agent) to obtain information about Mainframes.
   vCenter Appliance Discovery	The discovery methods used are vCenter, Shell Scripts, and SNMP. The Shell Scripts method uses the Linux platform scripts.
   SNMP supported platforms	SNMP discovery is supported for all devices with an accessible SNMP agent. BMC Helix 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
• vCenter

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 Helix Discovery runs on UNIX hosts are all standard UNIX commands that you can view through the UI. When BMC Helix Discovery runs these commands, they return an exit status code. BMC Helix 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 Helix 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:

tw_capture fileinfo_foo ls -ld /usr/bin/foo

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

tw_capture foo dpkg -l '*' | egrep '^ii '

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

dns_domain=`tw_capture hostname -d | sed -e 's/(none)//'`

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.