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 Atrium Discovery user interface, you can:
- View the scripts
- Amend scripts (edit script parameters, or enable or disable scripts)
However, the BMC Atrium Discovery user interface does not enable you to add new scripts.
Where this page refers to "default scripts", it refers to the discovery scripts that were shipped with the release. For example, in a version 8.2.03 appliance, the default scripts are those that shipped with 8.2.03. If you upgrade the appliance to version 8.3, the default scripts are those that shipped with version 8.3.
If you have just upgraded your installation and have not updated the discovery scripts, you can use the Discovery Platforms page to view the script differences and choose to upgrade to the current version by clicking Reset to Default. This enables you, post-upgrade, to view the script differences and choose to upgrade to the current version by clicking Reset to Default.
Viewing the existing scripts
To view existing scripts, perform the following:
- From the Discovery section of the Administration tab, select Platforms.
The Discovery Platforms page is displayed.
- The Discovery Platforms page lists the categories for which discovery commands are provided.
The available categories are:
- Windows Discovery
- UNIX, Linux and Related Discovery
- Mainframe Discovery
- SNMP Supported Platforms
Each category displays headers which link to pages containing details of discovery methods used.
Some additional information associated with a header might be displayed as a tool tip.
The following table summarizes the available discovery methods in these pages:
The discovery methods used are WMI, RemQuery, Shell Scripts, 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 an interactive login (ssh or telnet) and running shell scripts and SNMP in the given order and uses the first one with which the initial session is established.
Once an initial session is established, Discovery does not attempt another session (for example, if WMI and RemQuery establishes the initial session and even if some scripts fail or commands are not successfully executed, Discovery does not attempt another session with interactive login and shell scripts).
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 the primary method of discovery (in case of VMware ESX and ESXi platforms, vSphere API calls are used as the the primary method of discovery).
If the primary method of discovery fails to establish the initial session, Discovery attempts SNMP.
Once an initial session is established, Discovery does not attempt another session (for example, if interactive login and running shell scripts establish the initial session and even if some scripts fail or commands are not successfully executed, Discovery does not attempt another session with SNMP).
Discovery uses the MainView Host Server to obtain mainframe information.
SNMP supported platforms
SNMP discovery is supported for all the devices with an accessible SNMP agent. Discovery supports SNMP v1, v2c and v3.
- Where the discovery scripts have been changed from the default, a red change bar is shown to the left of the platform name.
- To manage the changed scripts in the UNIX, Linux and Related Discovery section, you can use the following controls:
- Reset All: click this to reset all scripts to the default.
- View Script Differences: this link opens a page showing a list of changed discovery methods, sorted by platform.
Click the discovery method header to reveal the detailed view of the differences between the default method and the current method:
- Reset All: click this to reset all scripts to the default.
- Click the operating system link whose commands you want to edit. You cannot edit the SNMP methods, you can only view them.
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, perform the following:
- On the Discovery Platforms page, click the operating system link whose commands you want to edit.
Click on the Shell Scripts tab.
The commands for the operating system are displayed. The following table describes the fields in this page:
Download host script
To download the entire script, click this link.
To edit the command path which 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 the scripts, click this link.
Displays the discovery method used.
* 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 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.
Enabled or Disabled
Displays if the script is selected to be enabled or not.
In the Actions column, the following options are available:
- Edit: To edit the script, click this link. You can edit the discovery script, 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 the 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 this occurring.
- Click Apply to save the changes.
Methods such as the following are used:
getFileInfo– used where a pattern uses the
discovery.fileGetto return a file. The result is stored in a
getFileMetadata– used where a pattern uses the
discovery.fileInfoto return the metadata on a file. The result is stored in a
DiscoveredFilenode 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
getDirectoryListing– used where a pattern uses the
discovery.listDirectoryfunction to return a list of the directory contents. Returns a list of
Returning command exit status data
The commands that Discovery runs on UNIX hosts are all standard UNIX commands, and can be viewed through the UI. When Discovery runs these commands they return an exit status code. Discovery provides the ability to record exit status codes and output to stderr where commands fail. Success is not recorded.
You should bear in mind standard scripting techniques when editing these commands. For example, some Discovery commands use pipelines, and may need to be modified so as not to mask the desired exit status code.
Exit status codes are operating system, operating system version, and command dependent. Consult your operating system documentation for information on exit status codes and their meanings.
Recording the exit status
To record the exit status you need to 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. For example:
In order to be able to capture output using
/tmp on the target host needs to 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 which will succeed, and one which will fail. These have been added to the start of the
Viewing the exit status
Once you have added the
tw_capture commands, and discovered a host causing the method to be run, you can see any script failures by viewing the appropriate method link on the Discovery Access page.
To view the exit status:
- From the Discovery Recent Runs tab, click the discovery run which 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, then a list page is displayed.
- Click the method link for the method which you edited to add the return status.