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 Discovery user interface, you can:
- View scripts
- Amend scripts (edit script parameters; enable or disable scripts)
However, you cannot add new 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 10.1 appliance, the default scripts are those that shipped with 10.1. If you upgrade the appliance to version 11.2, the default scripts are those that shipped with version 11.2.
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
From the main menu, click the Administration icon.
The Administration page displays.
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 WMI, RemQuery, and SNMP.
Windows discovery uses WMI and RemQuery as the primary method of discovery. Even though two different techniques are used as the primary 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 using SNMP).
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).
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.
- 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 scripts from the Discovery Platforms page. You can only view and not amend the following methods:
To amend 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.
To edit the command path that is set when a shell is opened on the target, click the corresponding Edit link.
Just the command path displayed is set; it is not added to any existing path in the user environment.
Show All Scripts
To display a view-only version of all scripts, click this link.
Displays the discovery method used.
An asterisk (*) indicates methods that will successfully create a host.
To display a view-only version of a script, click this link for the corresponding script.
Some scripts might be marked as Privileges. This designation means that a normal login does not have sufficient access rights to get all of the information required. In this case, the root, or another user with higher access rights, is used.
Indicates whether the script is enabled.
In the Actions column, the following options are available:
- Edit—To edit the script, click this link. You can edit the discovery script and notes, and enable or disable the script.
- Disable or Enable—To change the enable and disable status of a script, click this link.
- Download—To download a copy of a script, click this link. You can then edit it in a text editor and save it locally.
- Upload—To upload a script to replace the existing one, click this link.
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.
Maximum Line Length
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.
- Click Apply to save the changes.
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.fileGetto return a file. The result is stored in a DiscoveredFile node.
getFileMetadata—Used where a pattern uses the
discovery.fileInfoto 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.runCommandfunction 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.listDirectoryfunction 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:
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.