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
From the main menu, click the Administration icon.
The Administration page is displayed.
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.
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.
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.
- 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:
To edit existing scripts
- On the Discovery Platforms page, click the OS link corresponding to the commands you want to edit.
- Click the Shell Scripts tab.
The commands for the OS are displayed. The following table describes the fields on this page:
Download host script
To download the entire script, click this link.
The PowerShell discovery script is not digitally signed and you might need to make changes to your PowerShell Execution Policy before you can run it. See for more information.
To edit the command path that is set when a shell is opened on the target, click the corresponding Edit link.
Show All Scripts
To display a view-only version of all scripts, click this link.
Displays the discovery method used.
To display a view-only version of a script, click this link for the corresponding script.
Indicates whether the script is enabled.
In the Actions column, the following options are available:
Where you edit or replace an existing script, a red change bar shows that the script has been changed and an additional Reset To Default link is displayed. Click this link to reset the script to the default.
The maximum line length of an interactive script is OS and shell dependent, and exceeding such a limit will cause the commands to fail. Ensuring that all lines in discovery scripts contain fewer than 128 characters will prevent such a failure from occurring.
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.
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:
To enable capture of output using
/tmp on the target host must be writable by the discovering account.
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
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.
- From the Discovery Recent Runs tab, click the discovery run that you used to scan the host.
- 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.
- Click the method link for the method that you edited to add the return status.
- Any failures can be seen by clicking the link to related Command Failures.