Ideally a credential that you add for discovery should be one that is valid for a range of machines and has sufficient rights to run system level commands in order to discover richer data.

Adding a credential is the same whether you add it for UNIX systems or Windows systems accessed via the credential slave. You do not need to add credentials for systems accessed via the Workgroup or Active Directory slaves as these use the permissions of the user they were installed as.

To Add a Credential

The discovery system's preferred method of accessing remote hosts is by a remote login. You can set up different login credentials for use on different machines, by individual IP address or a range of addresses.

Available access methods are ssh, telnet, rlogin and windows. You can set up several access methods and define the order in which they are to be attempted. Each access method is attempted until a working credential is found or the list is exhausted.

When you enter a user name and password for use by the External Credential Slave, you must prefix the user name with localhost e.g. localhost\Administrator.

For each host that is successfully logged into, the successful access method is recorded. On subsequent scans the first access method attempted is the one that succeeded for that host on the previous attempt, so long as the appropriate option is selected in the Discovery Configuration page.

If an access login method is disabled, for example telnet, and that method is recorded as the last successful login method, it is tried again on a subsequent scan. If it fails on this scan then that method will not be tried again until it is re-enabled.

An access method is only attempted if it is seen to be available, for instance SSH access will only be attempted if the SSH port is open.

Viewing Login Credentials

To view existing login credentials:

1. From the Secondary Navigation bar on the Discovery tab, click the Credentials button.
2. The Login Credentials page is displayed.
   
   
3. The credentials are checked in sequence, and the first matching entry is used. After a working credential is found, no more are checked. To reorder login credentials, drag the credential to the required position in the list. You can also click the Actions drop down to the right of the credential and select Move up or Move down. You can also move a credential to the top or bottom of the list by selecting Move to top or Move to bottom.
   
   The Credentials are shown in color coded boxes. The colors represent the level of login success achieved with that credential:
   • Green – 100% success rate.
   • Yellow – partial success.
   • Blue – the credential has never been used.
   • Red – 0% success rate.

The following information is shown for each credential:

You can also add new credentials. To do this, click the Add... button. The Add Login Credential page is displayed. See To Set Up Host Login Credentials for information on the fields and settings available from this page.

To Set Up Host Login Credentials

1. From the Login Credentials page, click Add... to add a new credential, or Edit to amend an existing one.
2. The Add/Edit Login Credential page is displayed.
   
   
3. You can then set up the login credentials as follows:
   

   Field Name	Details
   IP Range	Enter an IP address, a range of IP addresses, or a regular expression representing the IP addresses for which this credential is valid. IP address – for example, 10.10.10.3 Range of IP addresses – 10.10.10.* or 10.10.1-5.* or 10.10.10.0/24 Regular expression – .* or 10.10.10.(23|25)
   Username	Username used to log in to hosts identified by the key. If this is a Windows credential that will be used by the External Credential Slave, ensure you prefix the user name with localhost e.g. localhost\Administrator.
   Set Password	When editing a credential, the password is shown as a series of asterisks in this field and it cannot be edited. To enter a new password, select the checkbox. The password entry field is cleared. Enter the password into the password entry field; the password text is not echoed to the screen. To configure a credential to use SSH key exchange, leave the password field blank.
   Description	A free-text description of this login credential.
   Access Methods	Choose the access methods to be attempted for any host identified by the key by selecting them and moving them to the right-hand (enabled) list box using the right arrow button. By default, all access methods are placed in this box, that is, they are all enabled. You can also change the order in which the access methods are attempted by selecting them and moving them up or down with the up or down arrow buttons.
   Options	Choose one or more options that apply to this remote login. To enable an option you must select the checkbox: Session Logging – select this to create a session log. These log all communication between the BMC Atrium Discovery appliance and a host and should only be used for diagnosing discovery problems with that host. There is currently no option for recording a session log for Windows hosts. Prompt – a regular expression to define valid prompt characters expected. SU – select the Switch User checkbox to use the su command to change to the root or any other user. Enter the user to change to, and the corresponding password. The password text is not echoed to the screen. Buffer Size – specify a valid buffer size (any number in bytes). The default is 512 bytes. Timeout – specify a timeout period (in seconds) for a session. This timeout includes the credential handshaking (see also the Session Login Timeout in Configuring Discovery). This timeout is used to control sessions, it is usually not used to limit the time to scan devices. Note: More than one session can be used to scan one device. For this reason, a scan can take more time than this timeout. Typical consequence of this timeout: when the execution of the platform script for getInterfaceList takes more than this timeout, the scan will fail with a script failure (error message “Connection timed out”). Force Subshell – select this to force the session to open a Bourne (/bin/sh) subshell if the default login shell is a C shell (/bin/csh /bin/tcsh). This enables you to cater for machines using non-standard shells. Custom SSH Port – if the host for which this credential is intended is configured to listen for SSH connections on a non-standard port, enter this here. To do this, select the Enable custom ssh port? checkbox and enter the port number in the entry field. If you add a port here, it is automatically added to the [TCP ports to use for initial scan].

4. Click the Apply button to add the credentials, and repeat this for all the credentials you want to add.

Testing Login Credentials

1. When you have added the credentials, you can test them. Click the test link in the Actions column. If the test link is not displayed, click the START ALL SCANS button on the Discovery Status Page. The Test Login Credential dialog is displayed.
2. Enter a single IP in the Target IP address field to test the credentials against. In this example, 172.17.3.100.
   
   
3. Click the Test button. The page is refreshed to show that the test in in progress and when complete, the results are shown.
   
   

You can perform other credential tests from the Credential Tests page.

Privileged Command Execution

The UNIX and Linux discovery scripts in versions of Tideway Foundation before version 7.2 used hard coded commands to run a command as a privileged user. For example, /usr/bin/sudo /usr/sbin/ifconfig args. In version 7.2 and later, these are replaced with user defined commands. That is, the hard coded /usr/bin/sudo is replaced in the script with PRIV_IFCONFIG which is substituted with the user defined command when the script is run. The commands are defined in the init section for each platform.

BMC Atrium Discovery is shipped with no commands using privileged execution. The example below shows adding privileged execution to lsof commands. You will have to do the same for any command that you want to execute as a privileged user.

To configure execution of a command as a privileged user:

1. Click the Platforms icon in the Discovery section of the Administration page.
   The Platforms page is displayed.
   
   
2. Click the operating system link whose commands you want to add the privileged execution to.
3. The commands for the operating system are displayed.
4. Click the Edit link in the Action column of the initialise method row. The edit window is shown containing the script. Click in the edit window to enlarge it. This is shown below.
   
   
5. In the PRIV function (ex: PRIV_LSOF), add the command required (like sudo, pbrun , dzdo, etc. ) to run the commands as a privileged user. For example:

   ...
   PRIV_LSOF() { 
     sudo "$@" 
   }
   ...
   

   Or (if you need to force the path):

   ...
   PRIV_LSOF() { 
   /usr/bin/sudo "$@" } 
   ...
   

If the path is specified, it will affect all discovery commands that use that function and the privileged command might not always be at the same place. If the path is not specified, the privileged command will be found with the path of the user profile and the ADDM variable “path” (at the top of the platform scripts page).

You must add a privileged execution method to whichever commands you require in order to gain the fullest possible discovery. The available commands, their impact on discovery and the platforms they are available on described on the Privileged Commands for each Platform page.