Administering PDF - ADDM 10.1

Release Date — November 2014

Navigating the administration interface

Common administration operations

The Administration page is divided into the following sections:

• Discovery— provides links to the configuration and management pages for Discovery. The available links are:
  • Platforms: configure the commands used for each target OS. This is described in Managing the discovery platform scripts.
  • SNMP Devices: view the network devices which can be discovered by BMC Atrium Discovery. This is described in Viewing an SNMP managed device.
  • Storage Devices: view the WBEM queries used to perform direct discovery of storage devices. See Storage device direct discovery.
  • Sensitive Data Filters: mask any sensitive data which might otherwise be seen in the command output. See Masking sensitive data.
  • Discovery Configuration: configure the Discovery process. This is described in Configuring discovery.
  • Discovery Consolidation: configure consolidation of discovery data between appliances. This is described in Consolidation.
  • Ciscoworks Import: import switch data from CiscoWorks. This is described in Importing network device data.
  • Vault Manangement: manage the Credential Vault. This is described in Managing the credential vault.
  • Device Capture: capture an SNMP device using BMC Atrium Discovery to dump the MIB of an SNMP agent, which is then used to request that support be included in BMC Atrium Discovery for that SNMP device. This is described in Capturing SNMP devices.
• Security — provides links for the pages used to configure the security of the appliance and users. For more information, see Managing users and security.
  • Users: add, remove and modify users. This is described in Managing system users.
  • Groups: add, remove and modify groups. This is described in Managing groups.
  • Security Policy: configure the appliance security options. These are described in Managing security policies.
  • HTTPS: configure the HTTPS settings for the appliance. This is described in Configuring HTTPS settings.
  • Appliance Certificates: view and manage the certificates that the appliance uses for authentication.
  • LDAP: view information about integrating BMC Atrium Discovery with LDAP. This is described in Managing LDAP.
  • Single Sign On: Integrate BMC Atrium Discovery with BMC Atrium Single Sign-On (SSO) to simplify the user authentication. BMC Atrium Discovery supports other methods of web authentication using plugins to authenticate user logins, though BMC Atrium SSO is the preferred method.
  • Active Sessions: view all users who are currently logged in. This is described in Viewing active sessions.
  • Audit: configure the appliance audit feature. This is described in Auditing the appliance.
• Appliance— provides links for the configuration pages for the appliance. The pages related to the initial set up of the appliance are described later in this section. These are:
• Model— provides links to the pages used to configure and maintain the model, and import and export data.

Managing users and security

This section explains how to set up and change system users and system groups, including how to create users, change passwords and security settings, and set up groups.

Managing system users

BMC Atrium Discovery can integrate with your corporate LDAP infrastructure. LDAP groups can be mapped to BMC Atrium Discovery groups and hence assigned permissions on the system. For information about setting up LDAP, see Managing LDAP.

As well as being the means of controlling user security, a user is actually set up on the system as a Person data object, and can subsequently be associated with other objects.

All actions on the system are recorded against a user's ID for audit purposes. Users should always use their own ID and keep their security details safe.

Enabling other users

• admin
• appmodel
• discovery

Use the system user only for configuration tasks which require system privileges.

To enable other users

1. Click the Administration tab.
2. In the Security section of the Administration page, click the Users icon.
3. For each user, click the Set Password link.
4. On the Set Password page, enter the new password in each text entry field and click Apply.
5. After you have changed the passwords for each user, log off from the system user account by clicking the logout icon at the top right of the page.

Creating a new user

The BMC Atrium Discovery Administrator can set up new users and assign them to groups. Before creating users, you must ensure that you have set up all the groups that you need. See Managing groups.

To create a new user

1. From the Users page, click Add at the bottom of the page.

2. In the Add User page, enter the following details for the new user:

   Field Name	Details
   Username	Login ID of the user.
   Full Name	Full name of user.
   Password	Enter the password to be allocated to this user. Repeat the password for security reasons.
   Password Rules	A read only display of the rules which are used to validate the password strength.
   Groups	Select one or more groups that this user will be a member of. By default, all new users are members of the public group.

3. To save the changes, click OK.

User names are case sensitive. That is, user names with the same spelling but different case are permitted, for example, Johnson and JOHNSON are not recognized as duplicates.

Amending a user's details

You can change a user's name and the groups that they are a member of. The access defined by the group membership will apply the next time this user logs on.

To amend a user's details

1. From the Users page, click Edit next to the user.
   The page is redisplayed showing editable fields.
2. Amend or overwrite Full Name field.
3. Select one or more Groups that this user is to be a member of.
4. To save the changes, click OK.

Changing a user's password

If users forget their passwords or if a password is not kept secure, you can assign a new password.

To set a new password for a user

1. From the Users page, click Set Password.
   The page is redisplayed, showing blank Password fields. The existing password is not displayed.
   If the password policy requires a password to be changed, the label "MUST be changed" is displayed next to the user.
2. Enter a new password for this user in the Password field. Confirm the password in the Verify Password field.
3. To save the changes, click Apply. The new password will apply the next time the user attempts to log on.
   You can also specify that the user changes their password on their next login. To do this, click Must Change Password.

This section describes the preferred way to set or reset user passwords. However, you can also change users passwords at the command line.

 Click here for details of changing UI user passwords at the command line

To reset the BMC Atrium Discovery user password at the command line

tw_passwd username

[tideway@DE-32 ~]$ tw_passwd fred
New password:
Retype password:
Password set for user 'fred'.
[tideway@DE-32 ~]$

Reactivating a user account

If a user's account is not used for a specified period of time, their account is deactivated. See Managing security policies for information on configuring account deactivation. To reactivate a deactivated user account you must be logged in as a member of the unlocker group and reactivating user accounts must be enabled in the security options page. You can also deactivate a user's account manually.
A deactivated account is never automatically reactivated.

To reactivate a locked user account

• Check that account reactivation is allowed (see Managing security policies)
• From the Users page, click Reactivate next to the user account to be reactivated.

Deleting a user

You can delete any existing user except for yourself or the default system-created users.

To delete an existing user

• From the Users page, click Delete next to the user to be deleted.

User permissions

User permissions in BMC Atrium Discovery are additive. When you grant a user an additional permission (through adding the user to another group), that permission is added to the user's existing permissions. For example, if you grant appmodel permissions to a user with discovery permissions, the user gains no additional permissions because all of the appmodel permissions were already granted in the discovery permission set. Similarly, you cannot add readonly permissions to a system user in the hope of achieving a read only system user.

Managing groups

To log in, a user must be in a group that has permissions security/user/passwd, appserver/login and appserver/module/home. Only four default groups have this permission: readonly, public, system and admin. Every user must be a member of one of these four groups, or a member of a custom group that has at least these permissions.

For example, a user who is only in the discovery group cannot login. You should put a user that requires access to discovery commands into the discovery and public groups.
The BMC Atrium Discovery Administrator is responsible for setting up details of all the user groups in the BMC Atrium Discovery system.

Each group is a collection of permissions. Permissions control granular access to BMC Atrium Discovery modules and are described in Group Permissions.

The default security groups

The default user groups and their security access rights are as follows:

• admin — These users have the highest level of customer access to the system.
• appmodel — These users can write and edit patterns, and create nodes to model business applications. They cannot view credentials but can run discovery (in order to test patterns).
• discovery — These users have access to all of the discovery-related data. They can start and stop discovery, add and remove credentials, and enable or disable audit logging.
• cmdb-export-administrator — These users have access to all of the export-related data.  They can build, modify, delete and run Exporters.
• public — These users have read/write access to all of the system although they cannot access the discovery credentials.
• readonly — These users have read only access to the system. They cannot view the credentials for logging into target hosts.
• system — These users have full access to the system.
• unlocker — These users are able to unlock and unblock user accounts which have been locked or blocked after exceeding the number of permitted authentication failures. See Managing security policies for more information.

Listing all current groups

1. Click Administration.
2. From the Security section, click Groups.
   The Groups page lists all the current groups and allows you to edit details, delete groups or create a new group.

To create a new group

1. From the Groups page, click Add at the bottom of the page.
   The Add Group page is displayed. The page is arranged into functional areas, and then subdivided into columns. The arrangement of the columns from left to right is as follows:
   • Wildcard: contain items which when checked, select a number of permissions. When you mouseover a wildcard permission, it and the permissions it applies are highlighted.
   • Read: read permissions relating to the functional area.
   • Write: write permissions relating to the functional area.
   • Misc: miscellaneous permissions relating to the functional area, such as appliance reboot.
2. In Group name, enter a name for the new group.
3. Select the check boxes that indicate the BMC Atrium Discovery modules that members of this user group are allowed to access. The * wildcard matches anything, so selecting this check box will give unrestricted access to everything in the system.
4. to save the changes, click OK.
   Once the group is set up you can add users. See Managing system users.

To amend group details

You can change a group name and the modules that group members can access. The access defined by the group membership will apply the next time users in this group log in.

1. From the Groups page, click Edit next to the user.
   The page is redisplayed showing editable fields.
2. Amend or overwrite the Name field.
3. Select one or more check boxes corresponding with the BMC Atrium Discovery modules that members of this group can access.
4. To save the changes, click OK.

To delete a group

You can delete any group provided you have created it initially. You cannot delete either the public or the system groups.

1. From the Groups page, click Delete next to the group to be deleted.
   The group is deleted and the system does not display any confirmation.

Group permissions

The following table shows the permissions assigned by default to each group in BMC Atrium Discovery. The individual permissions are described in System Group Permissions by Category.

System group permissions by category

The system group security permissions are shown by category in the following tables.

There are no permissions that restrict access to patterns. All logged in users can view patterns.

Security permissions

The following table shows the current group permissions relating to the security operations.

Credential vault permissions

BMC Atrium Discovery stores all passwords used to access customer devices in a credential vault which can be secured. The contents of the vault can be encrypted and secured using a passphrase.
The following table shows the current group permissions relating to the vault operations.

Discovery permissions

The following table shows the current group permissions relating to the discovery operations.

Consolidation permissions

The following table shows the current group permissions relating to configuring consolidation and scanning appliances.

Datastore permissions

These permissions are a subsystem of the model. The following table shows the current group permissions relating to the datastore operations.

Audit permissions

These permissions are a subsystem of the model. The following table shows the current group permissions relating to the audit operations.

Reasoning permissions

These permissions are a subsystem of the model. The following table shows the current group permissions relating to the reasoning operations.

Search permissions

These permissions relate to listing and cancelling searches using the Search Management Page. To navigate to the Search Management page:

1. Click Administration.
2. From the Model section, click Search Management.

For more information on viewing and cancelling searches, see Using the Search service.

Taxonomy permissions

These permissions are a subsystem of the model. The following table shows the current group permissions relating to the taxonomy operations.

Application server permissions

The following table shows the current group permissions relating to the application server operations.

Specific UI permissions

The following table shows the current group permissions relating to specific user interface operations.

Appliance administration permissions

The following table shows the current group permissions relating to the appliance administration operations.

The 'all' permission (*) allows the user to perform any tasks in BMC Atrium Discovery. Each user has a token which is assigned by the security system and whenever a privilege is requested by a user, the security service checks the database to see if that particular user has permission to carry out that particular task.

However, the first check that BMC Atrium Discovery carries out is to see if the user has the * permission. If the answer is yes, no further privilege checks will be carried out.

Managing security policies

• Accounts and Passwords
  • Password strength and expiry
  • Forced password change
  • Account blocking after authentication failures
  • Deactivation of unused accounts
• Login Page
  • Appearance of the login page
  • Legal banner messages
  • Allow browser autocomplete
• UI Security page
  • Prevent Cross Site Framing

Configuring these settings is described in the following sections.

Accounts and passwords

To configure the security options:

1. Click Administration.

2. From the Security section, click Security Policy.
   The options on the Security Policy page are described below:

   Field Name	Details
   Account Blocking	User accounts can be blocked after a number of unsuccessful login attempts. Select the number of attempts from the drop-down list. Choose from the following 1, 2, 3, 4, or 5 attempts. If you do not want accounts to be blocked, select Never. The default is 3.
   Automatically Unblock	After a user account is blocked, it can be automatically unblocked after a specified period. Select the period from the drop-down list. Choose from the following 1, 2, 3, 4, 5, 10, 15, 20, 30, or 60 minutes. If you do not want accounts to be automatically unblocked, select Never. The default is 10 minutes. If you select Never, there is a chance that you could lock out the system account. See #Blocking of the System Account for more information.
   Account Deactivation	Unused user accounts can be deactivated after a specified period of time. Select the period from the drop-down list. Choose from the following 15, 30, 45, 60, 75, 90, 105, and 120 days. If you do not want accounts to be deactivated, select Never. The default is that disabled accounts cannot be reactivated.
   Disabled Accounts can be reactivated	Select Yes or No to allow user accounts to be reactivated. You will need an administrator to reactivate the account.
   Minimum Password Length	You can specify a minimum length for passwords. Select a minimum length from the drop-down list. Choose a length from 1 to 32 characters. Select None to enforce no minimum length. The default is 8 characters.
   Password History	You can specify a password history length to prevent users from recycling passwords too quickly. Select the password history length from the drop-down list. Choose from 3, 5, 10, or 20. Select None to enforce no restrictions on password reuse. The default is 10.
   Password constraints	Select from the following check boxes to apply constraints to the password contents. In general, the password quality improves with more selected check boxes: • Must contain uppercase characters — for example AIV. The default is true. • Must contain lowercase characters — for example aiv. The default is true. • Must contain numeric characters — for example 174. The default is true. • Must contain special characters — for example ^£). The default is true. • Must not contain sequences — for example AAA, ppp, or 222. The default is true.
   Password Expiry Period	You can specify a maximum length of time for passwords before they are automatically expired. Select an expiry period from the drop-down list. Choose from 30, 45, 60, 75, 90, 105, and 120 days. Select None to enforce no expiry period. The default is 90 days.
   Password Expiry Warning	Users can be warned that their password will expire soon when login into the user interface. The warning icon is displayed in the Navigating the BMC Atrium Discovery UI#Dynamic toolbox. Select a warning period from the drop-down list. Choose from 5, 10, and 15 days. Select Never to give users no warning of an expiring password. The default is 10 days. The expiry warning cannot be set to more than the expiry period.

Blocking of the system account

In the following scenario, the system user account can be locked.

• Account blocking is enabled (the default).
• Automatic account unblocking is disabled (not the default).
• A user repeatedly attempts to log in unsuccessfully to the UI as the system user.
  An administrator is required to log in to the system and unblock the account.

Login page

You can configure the appearance of the login page and add a legal notice to the login page.
To configure the login page:

1. From the Security section of the Administration tab, select Login Page Options.
   The options on the The Security Options: Login page are described below:

   Field Name	Details
   Plain login page	Where security is a concern, you can choose to remove all banners and logos from the login page. Doing so reduces the risk of attack by hiding the nature of system from a would be attacker. Select Yes to do this. This option is not available in the BMC Atrium Discovery Community Edition. The BMC favicon (shown in browser tabs) remains visible when you use the plain login page. If you want to remove the favicon, you should rename the /var/www/html/favico.ico file. For example favico.ico.hidden.
   Legal Notice	Enter an additional legal notice in the Legal Notice text field.
   Allow Browser Autocomplete	You can specify whether to allow data stored in browsers to be used to autocomplete fields in the UI. Select Yes or No.

UI security page

You can prevent cross site framing to defend against possible "clickjacking" attacks.
To configure the UI security page:

1. From the Security section of the Administration tab, select UI Security.

   Field Name	Details
   Prevent Cross Site Framing	You can specify whether to allow the BMC Atrium Discovery UI to be incorporated as part of an umbrella UI. Select Yes or No.

Secure deployment

• Between appliance and Windows proxy
• Between scanning appliance and consolidator
• Between members of a cluster

For information about securing communication between the user's browser and the appliance web user interface, see Configuring HTTPS settings.

When one part of BMC Atrium Discovery connects to another, each end of the connection checks that the other end is approved. The certificate can be thought of as the public key half of a public-private key pair — if the endpoint's private key details match the expected public certificate details, the connection is approved. Note that although the underlying protocols are the same, the trust model in use in BMC Atrium Discovery is different to the trust model involved in HTTPS used on the public web. Technical details are given below.

Certificates are small text files containing an ugly jumble of letters and numbers. To enable visual comparison of certificates, they are reduced to a fingerprint, which is a somewhat shorter sequence of ugly hexadecimal digits, for example '7D:0B:13:54:4B:F1:39:87:A0:AB:4E:FA:3D:A0:A2:0C:2F:0A:A1:BA'. Certificate fingerprints are shown in various parts of BMC Atrium Discovery so that the identities of the endpoints can be confirmed.

Maximum security

The most secure way to deploy the components of BMC Atrium Discovery is for each component to have its own unique key and certificate. This is the default scheme for new deployments. In this scheme, each connection between components must be approved; any connections that have not been approved are denied.

In versions of BMC Atrium Discovery prior to 10.1, a single default certificate was used in all deployments. That default certificate is referred to as the legacy certificate. For added security, the recommendation was to deploy custom keys signed by a private certificate authority. Upon upgrade from an earlier version, the existing keys and certificates are retained, so that existing communication links are not broken. To increase security of existing deployments, we recommend that once all parts of the deployment have been upgraded to version 10.1 or later, unique keys and certificates are generated for each component.

Approving connections

When connecting components of BMC Atrium Discovery, the components' certificates must be exchanged. The actual certificate exchange is performed automatically, but the connection must be confirmed via the user interfaces on both ends of the connection.

• Between scanner and consolidator, the scanner connects to the consolidator and the connection must be approved on the consolidator.
• Between the BMC Atrium Discovery appliance and the Windows Proxy, the link can be established from either end, and must be approved at the other end.
• In a BMC Atrium Discovery cluster, the cluster is considered a single component and all members share the same key and certificate details. When a new member joins the cluster, it automatically receives the key and certificate details.

Once a connection has been established, if either end changes its key and certificate details, the communication link will fail, and must be re-approved.

Upgrade considerations

Upon upgrade from a release prior to 10.1 the existing keys and certificates are retained, so that existing communication links continue to function. To increase the overall security of the system we recommend that once all parts of the system have been upgraded to 10.1 or later, the old keys are replaced by new unique ones for each component. Components can be upgraded one at a time — there is no need to switch all components from legacy keys at the same time.

If the upgraded appliance or Windows proxy was previously using the default legacy keys, then when the switch to unique keys is made, appliances automatically approve the new certificate. If the default keys had been replaced with custom site-specific keys, a switch to new unique keys will disable the existing communication links until they are re-approved. When an appliance key and certificate is changed, the Windows proxy always requires approval of the new certificate.

If it is necessary to add a newly installed appliance or Windows proxy to a system involving older version components, communication will not immediately succeed because the newly installed component will have unique keys that are not known to the old components. In this situation, the newly-installed component should be switched to use the legacy key and certificate via the certificate management interface.

Managing keys and certificates

Within the BMC Atrium Discovery user interface, details of the appliance's own key and certificate, and the certificates of other components that it trusts are visible within the Administration tab, in Security > Appliance Certificates. The page permits the generation of new keys, and the installation of the legacy keys for successful interaction with older-version components.

On the Windows proxy, access information about the proxy's own key and certificate in the Proxy Manager via Edit > Key and Certificate Management. As with the Appliance Certificates page, the dialog permits the generation of a new key and certificate and the installation of the legacy key. Certificate details of the connected appliances are available via Edit > Known Appliances.

Unless switching from the legacy keys to unique ones after an upgrade, generating a new key and certificate will break all existing communication links to other components, until the links are re-established.

Technical details

The TLS (Transport Layer Security) protocols used in BMC Atrium Discovery make use of both public-key and symmetric-key cryptography, and secure hashing. This section explains the effects of these cryptography techniques, how they are used in TLS, and how BMC Atrium Discovery uses the features of TLS to achieve authentication, authorization and end-to-end encryption.

• In symmetric-key cryptography, a message is encrypted with a key, and can only be decrypted with the same key.
• In public-key cryptography, a pair of keys is used. A message that has been encrypted with the private key can only be decrypted with the public key; conversely, a message that has been encrypted with the public key can only be decrypted with the private key.
• Secure hashing takes a message and reduces it to a short hash value. Changing the message changes the hash, and it is computationally infeasible to generate another message with the same hash value.

As a simple example of how these techniques can be used, suppose Alice wishes to communicate with Bob. They each have a public-private key pair, and each knows the other's public key. Public-key encryption algorithms are computationally expensive, so they wish to use a symmetric-key algorithm to exchange messages. The interaction is as follows:

1. Alice invents a new key to use with a symmetric-key algorithm. This is the session key.
2. Alice encrypts the session key first with her private key, and then with Bob's public key. She sends the doubly-encrypted message to Bob.
3. Bob decrypts the message with first his private key and then Alice's public key. Only Bob can do that because only he possesses the correct private key. He is sure that the message really came from Alice because her public key can only decrypt messages encrypted with her private key.
4. Alice and Bob communicate for as long as necessary using the exchanged session key.

TLS negotiates communication in a similar manner, except that it adds an extra layer of indirection that is useful on the public web. Suppose that Alice and Bob do not know each others' public keys, but they do both trust Charlie, and they know his public key. Charlie can act as a certificate authority (or CA). Alice and Bob each ask Charlie to sign their public keys:

1. Alice sends her public key to Charlie.
2. Charlie uses a secure hash algorithm to generate a hash of the public key.
3. Charlie encrypts the hash with his private key. This is the key signature.
4. He sends the combination of public key and encrypted hash back to Alice. Now the public key has been signed, it is called a certificate.

Since Charlie's public key is public, anyone can confirm that Alice's certificate was signed by Charlie, because they can decrypt the encrypted hash using his public key and check that the hash value is correct. Bob can similarly have his public key signed by Charlie or another trusted certificate authority.

Now, Alice and Bob can negotiate a session key to communicate as before, with an additional interaction at the start:

1. Alice sends her certificate to Bob.
2. Bob checks that the certificate was signed by a trusted certificate authority (Charlie).
3. Seeing that it was, he now trusts that the public key does indeed belong to Alice, so he sends Alice his certificate.
4. Alice can also check that Bob's certificate was signed by Charlie, or any other certificate authority she trusts.

Alice and Bob now have each others' public keys, so they can proceed as before. This is, in a somewhat simplified form, how TLS works.

TLS on the public web

On the public web, a number of companies have established themselves as certificate authorities. Browser manufacturers have chosen to accept these certificate authorities, and embed their public keys within the browsers. Web sites that wish to use HTTPS pay a certificate authority to sign their public keys. Now, when Alice wishes to use her web browser to connect to Bob's Bank Inc's web site, her browser can see that the Bob's Bank Inc certificate was signed by Charlie's Certificate Authority Ltd, and it is happy to proceed. End users on the web do not have certificates signed by a certificate authority, so Alice's browser does not have a signed certificate, and the Bob's Bank server does not attempt to verify one — the TLS protocol is configured to only authenticate the server-side certificate, and not require a client certificate. Hopefully Bob's Bank uses another mechanism to verify that Alice really is who she claims to be.

The trust model on the web is only intended to allow browsers to verify that web servers are who they claim to be. It relies on there being a small number of public certificate authorities that are trusted by all browsers.

TLS in BMC Atrium Discovery

The way TLS is used in BMC Atrium Discovery is different to the public web. Both client and server wish to authenticate each other, and all connections are individually approved so there is no need to have a single trusted certificate authority. The TLS protocols require the use of certificate authorities, however, so when each BMC Atrium Discovery component (appliance or Windows proxy) generates a unique public-private key pair for itself, it also generates a unique certificate authority key pair for itself, and signs its own certificate with it. The certificate authority public key is also signed with its own private key, so it is referred to as a self-signed CA Certificate. After generation, the system discards the CA's private key so it can never sign any more certificates with that CA.

Each component in BMC Atrium Discovery therefore has a unique single-use CA with its own CA certificate. It is these CA certificates that are exchanged between components, and must be approved for communication to be permitted.

Configuring HTTPS settings

• Generating server keys and certificate signing requests
• Uploading and signing server certificates
• Upload a CA certificate bundle to the appliance, or download them from the appliance
• Upload a Certificate Revocation List to revoke access to the appliance
• Enable and disable HTTP or HTTPS web access to the appliance

To access the HTTPS Configuration page, select HTTPS from the Security section of the Administration tab. The server key displays the private key for the appliance.

If BMC Atrium Discovery is integrated with a Web Authentication (Single Sign On) solution, you need to replace a default Certificate Authority (CA) bundle  on BMC Atrium Discovery. 

To generate a server key

On the Server Key tab of the HTTPS Configuration page, the existing key details are shown, or if no key exists, empty fields are displayed.

1. To generate a server key, enter relevant information in the editable fields:

   Field Name	Details
   Status	A read-only description of the current server key status. For example, this might contain information on the length and modification date of the key in use.
   Server Name	An editable field automatically populated with the hostname of the standalone appliance. If the appliance is a cluster member, it is the cluster alias, or if an alias has not been set then the cluster name is used.
   Country Code	The two character country code for the country in which the appliance is located, for example GB.
   State or Province	The state or province in which the appliance is located, for example Yorkshire.
   Locality	The locality in which the appliance is located, for example York.
   Company Name	The company name, for example, BMC Software.
   Department	The department using the appliance. This field is optional.
   Email Address	The email contact for users of this appliance. This field is optional.
   RSA key length	The RSA key length. Select one of the following from the drop down list: 1024, 2048, or 4096 bits.

   The values in the Server Key tab must match those used by the certificate authority.

2. When you have entered the required information, click Generate New Server Key.
   The new server key is saved as $TIDEWAY/etc/https/server.key onto the appliance's file system. A certificate signing request is also generated, it is called server.csr and is saved in the same location.
   When you have a key and a signing request, it must be signed before it can be used. You can do this using one of the following methods:
3. To download the certificate signing request, click Download CSR. Use the download dialog to choose the location on your local filesystem in which to save the file.
4. Send the certificate signing request file to your certificate signing authority for signing. When the certificate signing authority has approved the request, they will generate the corresponding certificate and return it as a .crt file.

Uploading a server certificate

1. When your certificate signing authority has approved the request, they will return a certificate. Save this file on your local filesystem.
2. On the HTTPS Configuration page, click the Server Certificate tab.
3. Click Browse next to Certificate File: and select the server certificate you saved in Step 1 of this procedure.
4. Click Upload New Certificate.
   The new certificate is uploaded onto the appliance.

Self signing a server certificate

If you do not use a certificate authority, but still require HTTPS access to the appliance, you can use the self-signing feature.
To self sign a certificate:

1. Ensure that you have created a server key and certificate signing request on the appliance using the procedure described in to generate a server key.
2. In the HTTPS Configuration page, click Server Certificate => Self Sign.
   The server key that you created is signed and saved as a new certificate called server.crt.
3. Enable HTTPS access. See Enabling or disabling HTTP and HTTPS access to the appliance for more information.
   When you access BMC Atrium Discovery using HTTPS, you will be prompted to accept the certificate once per each session.

Uploading or downloading a CA certificate bundle

The CA certificate bundle that is included by default contains a number of certificates from public certificate authorities. These are usually known as Trusted root certificates, or Trusted Intermediate Certificates. You can continue to use these or replace them with a certificate bundle from a certificate authority used by your organization. Your system administrator should tell you whether to use the supplied bundle or will provide you with one supported by your organization.

If you do not have a CA bundle, either the default supplied with the appliance, or one supplied by your organization, you will be unable to use HTTPS.

The default CA bundle is stored on the appliance in the following directory:
/etc/pki/tls/certs/ca-bundle.crt
When the certificate signing authority has approved the request, they will generate the corresponding certificate bundle and return it as a .crt file.
To replace the certificate bundle with one from a certificate authority used by your organization:

1. On the HTTPS Configuration page, click CA Certificates.
2. Click Browse next to CA Certificate Bundle File and select the server certificate you saved in Step 1 of this procedure.
3. Click Upload New CA Certificate Bundle.
   The new certificate bundle is uploaded.

To download the existing CA certificate bundle:

1. Click Download CA Certificate Bundle.
2. Use the download dialog to choose the location on your local filesystem in which to save the file.

Using a Certificate Revocation List to revoke access to the appliance

You can use a Certificate Revocation List (CRL) to ensure that certificates that have been revoked by the CA can no longer be used to access the appliance. A CRL contains a list of certificates which have been revoked by the CA. You can also add compromised certificates to the CRL.

To apply a CRL

1. On the HTTPS Configuration page, click Certificate Revocation List.
2. Click Browse next to Certificate Revocation List and select the CRL to apply.
3. Click Upload CRL.
   The CRL is uploaded and applied.

Enabling or disabling HTTP and HTTPS access to the appliance

Use a two stage approach to enabling redirect to HTTPS. Configure the HTTPS and test that it is configured correctly and permits access to authenticated users. Only then should you enable redirect to HTTPS.

If HTTPS is not configured correctly, and you enable redirect to HTTPS, you could be locked out of the appliance.
By default users can access the BMC Atrium Discovery over HTTP. You can enable HTTPS connections on this page and specify that attempts to connect over HTTP should be redirected to HTTPS.
By default HTTP access is enabled and HTTPS access is disabled.

1. On the HTTPS Configuration page, click HTTPS tab.
   The following screen illustrates an example of HTTPS enabled and HTTP redirected to HTTPS:
   
   
   • To enable HTTPS access, from the HTTPS list, select Enabled.
   • To disable HTTPS access, from the HTTPS list, select Disabled.
   • To enable HTTP access, from the HTTPS list, select Enabled.
   • To redirect HTTP access attempts to HTTPS, from the HTTP list, select Redirect to HTTPS.

Replacing a default Certificate Authority bundle

To replace a default CA:

1. In Administration tab, open HTTPS Configuration.
2. On the CA Bundle tab, choose file with the certificate you would like to use as CA and click Upload New Bundle.
   Note: If you are using Microsoft Certificate Services, you need to use the Download CA certificate chain option with Base 64 encoding. This produces a PKCS #7 encoded file (.p7b) that is converted to the correct format automatically during the upload. 

Managing LDAP

If you are using LDAP authentication there is no need to set up local user accounts for LDAP users on BMC Atrium Discovery.

LDAP Terms

The following terms are used in the sections describing BMC Atrium Discovery LDAP configuration:

• Directory Information Tree (DIT)— The overall tree structure of the data directory queried using the LDAP protocol. The structure is defined by the schema. Each entry in a directory is an object; one of two types:
  • Containers — A container is like a folder: it contains other containers or leaves.
  • Leaves — A leaf is an object at the end of a tree. Leaves cannot contain other objects.
• Domain Component (dc) — Each element of the Internet domain name of the company is given individually.
• Organizational Unit (ou) — Organizations in the company.
• Common Name (cn) — The name of a person.
• Distinguished Name (dn) — The complete name for a person, including the domain components, organisational unit, and common name.

An example Directory Information Tree is shown below.

dc=tideway,dc=com ou=engineering cn=Timothy Taylor telephoneNumber=1234 email= ou=test cn=Sam Smith telephoneNumber=2345 email= ou=product management cn=John Smith telephoneNumber=3456 email=

The login procedure

When a user attempts to log in through the user interface, BMC Atrium Discovery first checks to see whether the username represents a local account. If no local account exists, and LDAP has been configured correctly, BMC Atrium Discovery attempts to authenticate against the directory and then performs an account lookup to return the group memberships of that account. If the group mappings have been enabled, and configured correctly, then authentication takes place and the user is logged in with the local BMC Atrium Discovery rights as defined in the group mapping.

The Global Catalog

The Global Catalog is a distributed data repository that contains a searchable, partial representation of every object in every domain in a multidomain Active Directory Domain Services (AD DS) forest. The global catalog is stored on domain controllers that have been designated as global catalog servers and is distributed through multimaster replication. Searches that are directed to the global catalog are faster because they do not involve referrals to different domain controllers.

Configuring LDAP

To configure the LDAP settings:

1. From the Security section of the Administration tab, select LDAP.
   The LDAP page is displayed showing the LDAP tab.
   
   The options on this page are described below:

   Field Name	Details
   LDAP Support	Select Enabled or Disabled to enable or disable LDAP support for this appliance.
   Connection Status	Displays a message regarding the status of the connection to the LDAP server. For example: • No LDAP operations performed (last update: timestamp) • Invalid credentials (last update: timestamp) • Connection established (last update: timestamp) • Can't contact LDAP server (last update: timestamp)
   Server URI	The address of the LDAP server to connect to. For example: ldap://engineering.bmc.com:3268 or ldaps://engineering.bmc.com The default LDAP port is 389 and the default LDAPS port is 636. For multiple (failover) LDAP servers, enter a space separated list of LDAP server URIs. When using the Microsoft Active Directory group mode for LDAP, you can also use port 3268 to reference the Global Catalog. Check with your LDAP administrator to ensure that you use the correct port.
   LDAPS	Displays a message regarding the CA certificate and provides controls enabling you to upload, remove or replace a certificate. Many large enterprises have their own CAs that will provide a root CA certificate which will allow the appliance to trust the LDAP server's certificate it receives over the network. To upload a certificate, click the Browse button, select the new certificate using the file upload dialog, then click Apply. To replace an existing CA Certificate, select the Remove CA Certificate check box and click Apply. When the page is refreshed, add the new certificate as above. You should contact your organization's LDAP administrator to obtain a CA certificate. Multiple CA certificates can be uploaded by concatenating into a single file prior to upload. You cannot delete a CA certificate when LDAPS is enabled. Likewise, you cannot enable LDAPS without a CA Certificate loaded. In both these cases you will encounter a Cannot use LDAPS without a CA Certificate warning.
   Bind Username	The user name with which to connect to the LDAP server. For example, .
   Bind Password	The password that corresponds to the user name entered in the Bind Username field. Check the box to modify the password.
   Bind Timeout	The length of time that the appliance will wait before the login is assumed to have failed.
   Search Base	The location in the directory from which the LDAP search begins. For example: dc=bmc,dc=com. This restricts the search to the bmc container in the directory information tree. When you are not using group mapping (see #LDAP Group Mapping) any BMC Atrium Discovery group you enter, must be entered in lower case.
   Search Template	Specifies the template to use to search for the user name in the LDAP database. For example: (userPrincipalName=%(username)s) This queries the LDAP database for the userPrincipalName attribute which is equal to %(username)s, which is the user name string entered at the login prompt.
   Search Timeout	If no response is received from the server in this length of time, the query times out. Select a timeout value from the drop-down list.
   Search Scope	Defines how deep to search within the search base. "Base", or zero level, indicates a search of the base object only. "One level" indicates a search of objects immediately subordinate to the base object, but does not include the base object itself. This is typically used to search for objects immediately contained in the search base level. "Sub Tree" indicates a search of the base object and the entire subtree of which the base object distinguished name is the topmost object. Select the required scope from the drop-down list.
   User Cache Timeout	The appliance queries the LDAP server for user information and caches the results to avoid overloading the LDAP server. Select a timeout value from the drop-down list. Values less than 10 minutes are not recommended. You can also clear the cache manually using the Flush Cache button.
   Group Cache Timeout	The appliance queries the LDAP server for group information and caches the results to avoid overloading the LDAP server. Select a timeout value from the drop-down list. Values less than 1 hour are not recommended. You can also clear the user and group cache manually using the Flush Cache button.
   Group Mode	The group mode determines the way that the LDAP server is queried for group information, it should match the LDAP server used by your organization. Select one of the following LDAP server types from the drop-down list: •Microsoft Active Directory •SunONE Directory Server •Other
   Group Attribute on User node	The LDAP attribute name to search for when running a group query. The attribute is on the User node, and provides a list of distinguished names of groups that the user belongs to. For example, the attribute might be called "memberOf" and contain data such as "cn=sales,ou=groups,dc=bmc,dc=com". This field is user editable when the Other Group Mode is selected from the Group Mode drop-down (if the User node does not contain such an attribute, this field should be empty so the Membership Attribute on Group node will be used instead). When any other mode is selected the field is automatically populated.
   Group Query	The LDAP query that is used to find Group objects. It is usual to match the nodes' Object Class, for example: (objectclass=group). This field is user editable when the Other Group Mode is selected from the Group Mode drop-down. When any other mode is selected the field is automatically populated.
   Membership Attribute on Group node	The LDAP attribute name to search for to determine whether an individual is a member of a group. The attribute is on the Group nodes, and provides a list of names of users. For example, the attribute might be called "member". This field is user editable when the Other Group Mode is selected from the Group Mode drop-down. When any other mode is selected the field is automatically populated.

2. To save the LDAP settings, click Apply.

Configuring LDAP for use with BMC Atrium SSO

Depending on how your LDAP servers are configured, user authentication via Atrium SSO may work, but then user authorization in BMC Atrium Discovery fails. This occurs because Atrium SSO sends BMC Atrium Discovery the first part of the user's DN as their userid.

For example, for a DN of the following format:

dn: CN=ADDM QA. TEST,CN=Users,DC=addmsqa,DC=bmc,DC=com

The part that must be matched by the search that BMC Atrium Discovery runs is:

ADDM QA. TEST

To do this, for the example above, set the Search Base to:

cn=users,dc=addmsqa,dc=bmc,dc=com

and the Search Template to:

(cn=%(username)s)

Changing from LDAPS to LDAP

When you reconfigure BMC Atrium Discovery to use LDAP when it was previously configured to use LDAPS, you must remove the CA Certificate, and change the URI in a single step otherwise you will encounter a Cannot use LDAPS without a CA Certificate warning. To do this:

1. Edit the URI to point to the LDAP server's ldap:// URI. Do not click Apply button yet.
2. Select Remove CA Certificate.
3. Click Apply.

Changing from LDAP to LDAPS

When you reconfigure BMC Atrium Discovery to use LDAPS when it was previously configured to use LDAP, you must add a CA certificate before you attempt to enter an ldaps:// URI.

LDAP group mapping

The LDAP group mapping enables you to assign membership of BMC Atrium Discovery groups to LDAP groups. If you do not use group mapping, users will be only be assigned to groups in BMC Atrium Discovery which are exactly the same as the the LDAP groups that they are members of, that is, in LDAP form dc=tideway,dc=com,ou=engineering...

To enable or disable LDAP group mapping

1. From the LDAP page, select the Group Mapping tab.
   
   The LDAP Group Mapping page lists the LDAP groups that are assigned to BMC Atrium Discovery security groups. For each LDAP group, the appliance security groups to which it is assigned are listed. Links for each action that you can perform are provided for each group.
2. Select Enabled or Disabled from the drop-down list to enable or disable LDAP group mapping.

To add or edit LDAP Group Mapping starting from a username

1. From the LDAP page, select the Group Mapping tab.
2. Click Lookup User.
3. In the LDAP User Lookup dialog enter the Username and click the OK button.
4. The system looks up the username in LDAP and displays the results.
   
   LDAP Groups: For each LDAP group of which the user is a member, displays existing group mappings and provides an add link or an edit link.
   Mapped Groups: Displays the final list of mapped groups for this user.
   Details: Displays whether the information was obtained from the local cache and the total number of groups to which this user belongs.
5. Click Add to create a new group mapping or Edit to modify an existing group mapping.
6. Select the appliance security groups to which you want to assign the LDAP group.
7. To save the mapping, click Apply.

To add an LDAP Group Mapping starting from an LDAP group name

1. From the LDAP page, select the Group Mapping tab.
2. Click Add.
3. On the Add LDAP Group Mapping page, enter a search term for the common name into the LDAP Group field and click the Search button. A list of matches is displayed. If more than ten entries match, the first ten are shown and a label is displayed at the bottom of the list showing how many additional matches there are.
4. Select the matching LDAP group from the list. The LDAP groups field is not case sensitive. All LDAP groups returned from the LDAP server are displayed in lower case.
5. Select the appliance security groups to which you want to assign the LDAP group.
6. To save the mapping, click Apply.

To edit an LDAP Group Mapping starting from an LDAP group name

1. From the LDAP page, select the Group Mapping tab.
2. For each LDAP group listed, an edit link and a delete link are provided.
3. Click Edit.
4. Select the appliance security groups to which you want to assign the LDAP group.
5. To save the mapping, click Apply.

To delete an LDAP Group Mapping

1. From the LDAP page, select the Group Mapping tab.
2. For each LDAP group listed, an edit link and a delete link are provided.
3. To remove an LDAP group mapping, click Delete.

Troubleshooting

If you receive a "Can't Contact LDAP Server error" in the Connection Status field, this might be caused by certificate problems rather than simple connectivity (wrong URI, port and so forth). Check that the certificate you are using is the one you received from your LDAP administrator.

If the login fails when attempting LDAP authentication, set the security log /usr/tideway/log/tw_svc_security.log level to debug.

Where the account used to bind to the directory fails to authenticate look for messages similar to the following:

-1285350512: 2010-08-13 10:00:46,843: security.authenticator.ldap: DEBUG: Attempt to auth bind as username "administrator"
-1285350512: 2010-08-13 10:00:47,117: security.authenticator.ldap: DEBUG: LDAP passwd for "CN=Administrator,CN=Users,DC=generic,DC=com" not valid

If you are using group mapping and are experiencing login failures, check that group mappings have been correctly defined for one or more LDAP groups to which the user belongs. See To add or edit LDAP Group Mapping starting from a username.

Integrating with BMC Atrium Single Sign-On

• Integrate various BMC Software products for Single Sign-On user authentication.
• Authenticate with integrated BMC Software products by entering the login credentials only once.
• Log off integrated BMC Software products by logging off from one of those.

BMC Atrium Discovery supports BMC Atrium SSO, version 8.1 and later, for user authentication.

Note

The current version of BMC Atrium Discovery is shipped with the BMC Atrium Single Sign-On (SSO) 8.1 agent. The 8.1 agent is compatible with the recently released SSO 9.0 server. However, this earlier version of the agent does not support some of the latest features and enhancements of BMC Atrium SSO 9.0. Currently, upgrading the agent to 9.0 on BMC Atrium Discovery is not possible.

To configure BMC Atrium SSO user authentication, you must:

1. Have access to the BMC Atrium SSO server in your environment.
2. Register the BMC Atrium SSO Web Agent with the BMC Atrium SSO Server.
3. Activate the registered BMC Atrium SSO Web Agent.
4. Verify that the BMC Atrium SSO Web Agent is registered with the BMC Atrium SSO server.

Accessing the BMC Atrium SSO Server

To configure BMC Atrium SSO user authentication, you must access the BMC Atrium SSO Admin Console. If BMC Atrium SSO is not already installed and configured in your environment, you can download the latest version from the BMC Electronic Product Distribution (EPD) site and install and configure it for user authentication.

The BMC Atrium SSO server URL must always be specified as a Fully Qualified Domain Name (FQDN).

To access to the BMC Atrium SSO Admin Console from the BMC Atrium SSO Server:

1. Click Start > All Programs > BMC Software > BMC Atrium SSO > Administrator.
2. Log in with the BMC Atrium SSO administrator password.

To access to the BMC Atrium SSO Admin Console from a client system:

1. Enter the BMC Atrium SSO URL, this must be an FQDN, including the port number, into the browser and press Return.
   For example,
2. When prompted, enter the BMC Atrium SSO administrator credentials and log in.

Configuring the BMC Atrium SSO Web Agent with the BMC Atrium SSO Server

Before you configure the BMC Atrium SSO Web Agent with the BMC Atrium SSO Server, read the notes on Configuring LDAP for use with BMC Atrium SSO, ensure that the LDAP settings are configured and you are able to login to the BMC Atrium Discovery appliance as an LDAP user with administrative privileges (so that once you have activated the BMC Atrium SSO integration, you will be able to login again and change the configurations, if required).

To configure the BMC Atrium SSO Web Agent, you must perform the following from the BMC Atrium Discovery UI:

1. Register the web agent with the BMC Atrium SSO Server
2. Activate the web agent

To register the web agent

Note

If you plan to enable Federal Information Processing Standard (FIPS) Publication 140-2, you must do it before registering the web agent. The Atrium SSO Server must also be in FIPS 140-2 mode. For more information, see Running in FIPS compliant mode.

1. Log in to the BMC Atrium Discovery appliance UI as a user with administration privileges.
2. From the Security section of the Administration tab, click Single Sign On.
3. From the Registration section of the Atrium SSOtab, complete the following parameters:
   1. Atrium SSO Web Agent: (Read-only field) Displays whether the web agent is registered or not.
   2. Agent FQDN: Enter the FQDN for the web agent. You must use an FQDN, or you may be unable to log in to the BMC Atrium Discovery UI. You cannot specify localhost.localdomain or .local FQDNs.
   3. Atrium SSO Server URL: Enter the URL for the BMC Atrium SSO Server. You must use an FQDN, or you may be unable to log in to the BMC Atrium Discovery UI.
   4. Atrium SSO Realm: Leave the BMC Atrium SSO Realm name as the default value of /BmcRealm.
   5. Admin Username: Leave the BMC Atrium SSO administrator user name as the default value of amadmin.
   6. Admin Password: Enter the BMC Atrium SSO administrator password.
4. To complete the registration, click Register.

The registration might take a few seconds and on completion a message, Atrium SSO Web Agent registered with Atrium SSO Server, is displayed on the UI. For registered web agents, it is not possible to edit the registration parameters. To edit the registration parameters you must deregister the agent. When you deregister a web agent, enter the BMC Atrium SSO administrator password in the Admin Password field and click Deregister.

To activate the web agent

1. From the Activation section of the Atrium SSO page, click Activate.
   Activating the web agent restarts the Apache Web Server in the background and might take a few seconds and on completion a message, Please allow a few seconds for the changes to be applied. You may need to reauthenticate is displayed along with a Refresh link.
2. Click Refresh.
3. If prompted, you must re-authenticate your BMC Atrium SSO session.
   The following fields are displayed:
   1. Status: Displays the activation status of the web agent. For activated web agents it is Activated. Otherwise, the status is Deactivated.
   2. LDAP: Displays whether LDAP support is enabled or not.
      If LDAP support is not configured, click on the corresponding link to complete the configuration.
   3. HTTPS: Displays whether HTTPS support is enabled or not.
      Configuring HTTPS support is highly recommended, and if not configured, click on the corresponding link to complete the configuration.
   4. Restart Web Agent: Enables you to restart the web agent which in turn restarts the Apache Web Server in the background. Typically, if you make any configuration changes in the BMC Atrium SSO Server, you must restart the web agent for the changes to take effect.
   5. Deactivate: Enables you to deactivate the web agent. Deactivating the web agent requires you to re-authenticate your BMC Atrium SSO session and may take a few seconds. Once deactivated, you are presented with the BMC Atrium Discovery appliance’s login UI.

BMC Atrium SSO configurations in a cluster

If you update the BMC Atrium SSO configuration in the coordinator, it are automatically updated in the existing members. However, if you add a new member, the configuration is not automatically updated as the BMC Atrium SSO administrator user ID and password are not stored in the appliance. You must manually apply the configurations on the newly added member.

To manually apply the BMC Atrium SSO configurations on a newly added member, perform the following on the coordinator:

1. Click Administration > Single Sign On.
2. From the Registration section of the Atrium SSO tab, enter the Admin Password.
3. Click Synchronize.
   The synchronization of the configurations on the new member might take a few seconds and a message, Atrium SSO configuration being synchronized, is displayed on the UI of the coordinator.

When the synchronization of the configuration is completed, the Atrium SSO Web Agent for the new member is registered. You must manually activate the web agent from the member's UI.

Verifying registration of the BMC Atrium SSO Web Agent with the BMC Atrium SSO Server

To verify the registration of the BMC Atrium SSO Web Agent with the BMC Atrium SSO Server:

1. From the BMC Atrium SSO Admin Console, click Agent Details.
   The Agent Manager displays the list of the web agents configured for Single Sign-On.
2. Verify if the corresponding web agent is available in the list or not. It may show as Down although it is working.
   If BMC Atrium SSO user authentication is configured, the list displays the corresponding web agent. However, if BMC Atrium SSO user authentication is not configured or the web agent has been deregistered, the list does not display the web agent.

When BMC Atrium SSO user authentication is successfully configured and you attempt to access the login UI for an integrated product, it redirects you to the BMC Atrium SSO login page. Once you get authenticated for the session, you can access all the integrated products without having the need to get authenticated for each of those for as long as the session is valid.

Configuring Web authentication settings

The following web authentication methods are supported:

• SSL Client Certificate Verification: The client's SSL Certificate is verified by the web server. The user name is extracted from the certificate and used for authorization via LDAP. Requires LDAP support.
• SSL Certificate Lookup: The user is authenticated by looking up custom parts of the client's SSL Certificate via LDAP. The certificate is not verified, but it must be valid. Requires LDAP support.
• RSA SecurID Authentication: Authentication is performed by the RSA Authentication Agent. The username is used for authorization via LDAP. Requires HTTPS and LDAP support. This is available in BMC Atrium Discovery 9.0 SP1 and later.
• HTTP Header: BMC Atrium Discovery is integrated with Single Sign-On (SSO) technologies to authenticate users through custom HTTP headers such as CA SiteMinder. Requires LDAP support.
• Standard Atrium Discovery Web Authentication: The user is authenticated by entering a user name and password via the Login page. Supports authentication via LDAP, if LDAP support is enabled.

To configure the web authentication settings:

1. From the Security section of the Administration page, select Single Sign On .
2. Select the Web Authentication tab.

On the Web Authentication page, you can choose the order in which the methods will be attempted, and you can enable, disable, and configure each one. The Standard Atrium Discovery Web Authentication module is a special case (it cannot be disabled and acts as the fail safe login).
For each authentication module (except for the Standard Atrium Discovery Web Authentication module), the following controls are provided:

• Disable — click this link to disable the module. When a module is disabled, the link is replaced with an Enable link.
• Configure — click this link to open a dialog box to configure the module. These dialogs are described in the following sections:
• Ordering controls: click the up or down arrow to move the module up or down. Click the barred up or down arrow to move the module to the top or bottom.
  The page also provide links to the configuration pages for HTTPS and LDAP.

Configuring SSL client certificate verification

This module verifies the client SSL certificate with the web server. If the certificate is valid, the user name is extracted and used for LDAP authorization.

To configure SSL client certificate verification:

1. Click Configure in the SSL Client Certificate Verification row.
2. Enter the extract key in the single editable field.
   The Extract Key which is used to extract the user name. It can be any value in the Distinguished Name (DN) of the supplied X.509 certificate or an X.509 extension value. The default is emailAddress which is used when the email address is the user name.
3. If the user name is not the email address, enter a new extract key to get the user name. This must match the search template used in in the LDAP settings.
4. Click Apply to apply the changes.

In 9.0 SP1 and later you can extract values from X.509 certificate extensions. The extension name subjectAltName is used as the extract key. The extension name is split into parts. The parts that you can extract are determined by the content of the certificate. For example you can refer to:

• subjectAltName — the entire extension name
• subjectAltName.emailAddress — email address (as defined in RFC 822 — for example, "Taylor, Timothy"

Note

A colon is assumed to delimit fields in the subjectAltName value so the string will not be split correctly if a value contains a colon.

SSL certificate lookup

This module extracts information from the client SSL certificate and verifies it against the LDAP server.

1. Click Configure in the SSL Certificate Lookup row.
2. Enter the lookup expression.
   The lookup expression must be a valid LDAP query. It can contain any values from the supplied X.509 certificate or an X.509 extension value. The variables you can use are:
   

   HTTPS	SSL_PROTOCOL	SSL_SESSION_ID
   SSL_CIPHER	SSL_CIPHER_EXPORT	SSL_CIPHER_USEKEYSIZE
   SSL_CIPHER_ALGKEYSIZE	SSL_VERSION_INTERFACE	SSL_VERSION_LIBRARY
   SSL_CLIENT_M_VERSION	SSL_CLIENT_M_SERIAL	SSL_CLIENT_S_DN
   SSL_CLIENT_S_DN_x509	SSL_CLIENT_I_DN	SSL_CLIENT_I_DN_x509
   SSL_CLIENT_V_START	SSL_CLIENT_V_END	SSL_CLIENT_A_SIG
   SSL_CLIENT_A_KEY	SSL_CLIENT_CERT	SSL_CLIENT_CERT_CHAINn
   SSL_CLIENT_VERIFY	SSL_SERVER_M_VERSION	SSL_SERVER_M_SERIAL
   SSL_SERVER_S_DN	SSL_SERVER_S_DN_x509	SSL_SERVER_I_DN
   SSL_SERVER_I_DN_x509	SSL_SERVER_V_START	SSL_SERVER_V_END
   SSL_SERVER_A_SIG	SSL_SERVER_A_KEY	SSL_SERVER_CERT

   
   These are the Apache mod_ssl variables. See the Apache website for more information.
3. Enter the LDAP Attribute against which to check the user name.
4. Click Apply to apply the changes.

To configure RSA SecurID authentication

BMC Atrium Discovery can use an RSA SecurID server to perform authentication. To do this you must first install the RSA Authentication Agent 7.1 for Web for Apache Web Server on the appliance, configure it to access your RSA Authentication Manager, and test to ensure that it is working. See the RSA documentation for instructions on how to do this.

Cannot use system and other standard users

You cannot access the system user and the other standard users unless they have an exactly corresponding RSA/LDAP user. You must create an RSA/LDAP user with permissions exactly corresponding to any default users that you use.

To configure RSA SecurID authentication:

1. Log in to the BMC Atrium Discovery UI using an LDAP account with permissions equivalent to the system user. Ensure you can access the Administration -> Web authentication page while logged in as this user.
2. Click Configure in the RSA SecurID Authentication row.
   There is a single editable field in the configure page, this is the Logout URL which is required to logout via the web authentication framework. The default is /webauthentication?logoff?referrer=/ui.
3. Log out of the BMC Atrium Discovery UI.
4. Install and configure the RSA Authentication Manager according to the instructions in the documentation contained in the download.
   • During the configuration of RSA SecurID, "Use RSA Token for Cross-Site Request Forgery Protection" must be set to disabled otherwise logging out from the BMC Atrium discovery UI will fail.
   • The installation requires that some environment variables are configured. These variables should be appended to /etc/sysconfig/httpd. A typical entry looks like this:
     

     # RSA enablement
     export VAR_ACE=/var/ace
     export LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:/etc/httpd/rsawebagent 

   • If the appliance is a virtual machine and you use VMware snapshots, you should ensure that you update the snapshot after configuring the RSA Authentication Manager. Rolling back to an earlier snapshot removes the shared secret and prevents subsequent log ins. See the RSA Authentication Manager documentation for more information.
5. Navigate to the BMC Atrium Discovery URL. You are presented with the RSA SecurID login page.
6. Log in using the same LDAP account with permissions equivalent to the system user.
   You are now presented with the standard BMC Atrium Discovery login page.
7. Log in to BMC Atrium Discovery with the same LDAP account as you used in the previous step.
8. Navigate to the Administration -> Web authentication page and enable the RSA SecurID integration.
   If you cannot access the Administration -> Web authentication page, you must log out of BMC Atrium Discovery, log back in as the system user, and grant sufficient permissions to the RSA/LDAP user to access that page.

Once RSA SecurID Authentication is enabled in BMC Atrium Discovery, the BMC Atrium Discovery login screen is no longer displayed. To login, enter your username, password, and code from the SecurID token in the RSA SecurID login screens. You are authenticated against the RSA Authentication Manager, and once authenticated you are logged into BMC Atrium Discovery using the same username.

If RSA SecurID Authentication is not enabled, the normal BMC Atrium Discovery login page is displayed, even after successfully logging in using the RSA Authentication Agent. If RSA SecurID Authentication is enabled in ADDM, but the RSA Authentication Agent is not installed or is installed incorrectly, the normal BMC Atrium Discovery login page is also displayed.

This section contains instructions on how to integrate BMC Atrium Discovery with single sign on (SSO) technologies which provide authentication using custom HTTP headers such as CA SiteMinder.

The HTTP header plugin scans each HTTP request for a specific HTTP Header. If the HTTP header is present and contains a valid user ID, the user is authenticated; if not, the user is not authenticated. The header is assumed to contain the username or user ID which is used in an LDAP query to obtain authorization. The LDAP query uses LDAP group mapping.

Warning

HTTP header authentication is a simple authentication mechanism which requires additional protection.

• HTTPS must be enabled with HTTP redirection.
• LDAP support must be enabled
• A reverse proxy must be used, and BMC Atrium Discovery configured only to accept HTTP requests from the IP address or addresses of the proxy.
  Enabling HTTP header authentication without securing the appliance in this manner leaves the appliance vulnerable to attack.

The SSO application inserts a custom header into each HTTP request. For example:

• Big Corp Inc. uses BIGUID: 123456
• Little Corp Inc. uses LITTLEUSER: fbloggs

Before configuring and enabling HTTP header authentication ensure that you understand the potential security implications of this authentication mechanism. To configure HTTP header authentication:

1. On the appliance, click Administration > Single Sign On.
2. Click Web Authentication.
3. In the HTTP Header row, click Configure.
4. Ensure that you understand the potential security implications of this authentication mechanism.
5. In the HTTP Header field, enter the name of the header to use for authentication.
   This is the header that the SSO application must populate with a valid user ID. BMC Atrium Discovery uses the value of this header to do a lookup in the LDAP server for authentication and for authorization via LDAP group mapping.
6. To complete the configuration, click Apply.
7. To enable HTTP header authentication, click Enable.

Standard Atrium Discovery web authentication

No configuration is required for the Standard Atrium Discovery Web Authentication section, it is the fail-safe method of logging in to the system. This authentication method uses local users created on the appliance.

Viewing active sessions

The Active Sessions page contains the following information about each user logged in to the UI:

• User — The user name of the user logged in.
• IP Address — The IP address that the browser is reporting.
• Browser — Browser information, including type, major version, platform, language, version and so forth.
• Login Time — The time that the user logged in to the UI.
• Last URL Accessed — The last URL that the user accessed.
• Last Access Time — The time that the user last performed an action in the UI.

Auditing the appliance

To use the appliance audit feature, you must be logged in as a system user. If you are not a member of this group you are shown the message, You do not have permission to run audit reports.

Reporting on audit events

You can configure the actions that will occur when the appliance status changes. To do this:
From the Security section of the Administration tab, select Audit.

To Search for events, enter search criteria in all or some of the following fields:

• From — the start date and time of the search. The default for this field is 24 hours before the page was loaded.
• To — the end time and date of the search. The default for this is to display the following text in the To fields: Day Month Year hh mm. This means that the logs will be searched up to the current time.
• User ID — a filter to search only for events logged to a particular user, for example, the reporter user.
• Event group — a drop-down filter to search only for events belonging to a particular event group or category. The event group provides a means for viewing related event types. See Event Groups for a list of event groups.
• Events — a drop-down filter to search only for events of a specified type.

When you have entered the search criteria, click Run to start the search. The page is refreshed to show a results table below the search panel.

You can only search the logs through the user interface (UI) using the fields in the Search audit records page. However, if you export the Results List by clicking Export as CSV, you can use a spreadsheet or text editor to perform detailed searches on the data. For example, you can search for events on a specific host.

Click Export as CSV and choose a location to save the file.

Each item in the result row is a hyperlink to the detailed record of the event.

The record data is divided into two sections:

Standard details

The standard details that are recorded for every event are described in the table below:

Additional details

The details shown in the Additional Details section varies from event to event. For example, the following information is provided for a Windows proxy that has been pinged:

• IP Address
• Port
• Windows proxy Name
• Windows proxy Type

When logging in to the user interface over an IPv6 connection, the client might use a temporary IPv6 address. It is this temporary IP address that is reported in the appliance's audit log. Where temporary addresses are shown, tracing the particular computer from which the login came is difficult. To avoid this, you can disable temporary IPv6 addresses on client computers.

Event groups

Audited events are collected into the following groups:

• Appliance Config
• Audit Log
• Consolidation
• DIP
• Datastore Edit
• Discovery Config
• Discovery Ruleset
• ECA Reasoning
• Search
• Security
• Windows proxy
• UI Access
• cmdb-export

The events that belong to these groups are shown on the Audit page in the user interface.

Purging the audit Log

You can purge the audit log of all events that are over one month old. Events less than one month old cannot be deleted. You can purge events using the Audit Purge page. To access the Audit Purge page, from the Audit section of the Administration tab, select Purge.

In the Audit Purge page, the log name, number of events, and the date and time of the oldest record is displayed. A selection drop-down list is displayed which enables you to select the purge until date. The following options are available:

• 1 month ago
• 3 months ago
• 6 months ago
• 12 months ago
• 24 months ago

This ensures that there is a minimum retention period of one month. Click Purge to purge the archive up to the Purge until date selected. When you click Purge, the operation commences immediately. You can navigate away from the page and continue with other tasks.

Purging archive information is also an auditable event. Therefore, after a purge, the newest event is a record of that purge.

There is no automatic purge of the audit information. When the audit information on the appliance becomes very large, you can use the appliance backup feature to create an archive.

A typical number of auditable events is approximately 1000 per day. This equates to approximately 90 000 events in three months.
When deleting events, you can typically remove 500 events per second. Deleting 60 000 or more events will result in the browser timing out, however, the process continues.

Maintaining the appliance

The BMC Atrium Discovery appliance requires little daily maintenance; however, a maintenance mode is provided that only system users can access to perform tasks such as rebooting or shutting down the appliance. In this mode, you can also take appliance backup, and configure the way the system is monitored and audited.

Setting the appliance identification

Changing the appliance hostname

Change the appliance hostname using the General Settings > Change Hostname options in the Tideway Appliance Network Administration Shell. for more information, see topic on the netadmin user account.  

The netadmin user is the preferred way of configuring networking

The preferred way of administering any of the appliance network configuration is to use the netadmin user account. The netadmin user account enables you to change network, hostname and gateway settings without requiring root privileges. You can also use the netadmin user to reboot the appliance.

Viewing the appliance identification

You can view or set details of the appliance identity, support information (displayed in the Help drop-down on each BMC Atrium Discovery page), and read-only information about the appliance software and hardware configuration. This includes information about whether the appliance is correctly specified for its intended use.

Consolidation and Scanning Appliances

You cannot change the name of an appliance if it is configured as a consolidation or scanning appliance. See Consolidation for more information.

To view or edit the appliance identification:

1. Click Administration.
2. From the Appliance section, click Configuration > Identification.
   The Identification page displays details of the appliance identity, support information, software and hardware.

3. Edit the fields that you want to change.
   The following fields can be edited:

   Field name	Description
   Appliance
   Name	The name of the appliance. You cannot change the appliance name if it is part of a cluster.
   Description	A description of the appliance.
   Admin Email	An e-mail address for the person or group responsible for the administration of the appliance.
   Banner color	The color for the top banner in the user interface. Setting a banner color makes it easy for users in the field to identify the appliance they are using for various purposes (for example, development, test, and production environments). The appliance name is displayed on the colored banner. See Configuring the banner color for more information.
   Support
   Support URL	The URL to use in the help drop down.
   Support URL Title	The title for the support URL.
   Support URL Label	The label for the support URL.
   Support URL Description	The descriptive text label for the support URL.

Viewing the appliance specification

To view the appliance specification:

1. Click Administration.
2. In the Appliance section, click Configuration > Identification.
   The Appliance Configuration page displays the following sections:
   • Appliance
   • Support
   • Software
   • Hardware

At the bottom of the Hardware section, the application specification table displays the number of discovered Operating System Instances, and the amount of processor, memory, swap space and filesystem resources detected. Also displayed is the threshold value of these parameters for each class of deployment.

If the appliance does not have sufficient resources for one or more classes of appliance deployment, the following types of messages are displayed:

• Message at the top of the application specification table: Specifies which resources do not meet the minimum resource specification. For example, if sufficient resource is not available for DISK, the warning message Below minimum specification (Disk Capacity) is displayed.
• Warning message at the bottom of the application specification table: Specifies that the appliance has insufficient resources and points to the documentation link for information about hardware specifications.

In the application specification table, the classes of the appliance deployment that do not meet the minimum hardware specification are highlighted in red. The classes of appliance deployment that meet or exceed the respective minimum hardware specification are highlighted in green.

See the Configuring the Virtual Appliance section for more information about classes of appliance deployment and related topics.

In a cluster, the appliance specification table is not shown.

Configuring the banner color

To configure the banner color:

1. On the Administration tab, click Configuration in the Appliance section.
2. In the Banner Colour section, select the option button corresponding to the color you want to display in the banner and click Apply.
   
   
3. In the Name field, type a name that you want to display overlaying the colored banner.
   The selected banner color with the specified name persists so that all pages that you display in the user interface use the same scheme. The banner color also displays on the login page.
   
   

Viewing network interface and routing settings

You can view details of the network interfaces and routing details configured on the appliance.

1. Click Administration.
2. From the Appliance section, click Configuration > Network Interfaces.
   The Network Interfaces page displays details of the configured network interfaces.

Configuring name resolution settings

To configure name resolutions settings:

1. Click Administration.
2. From the Appliance section, click Configuration > Name Resolution.
3. In Search, enter the name of the domain to be searched.
4. In Name Servers, enter the IP address of the name server.
   Multiple IP addresses can also be specified, separated by a space.
5. From the Time Out drop-down, select the required time out for DNS requests. This can be any value between 1 and 10 seconds. The default is 5 seconds. Larger values can affect Discovery performance and are not recommended.
6. From the Retries drop-down, select the required number of retries after DNS look up failure. This can be any value between 1 and 5. The default is 2. Larger values can affect Discovery performance and are not recommended.
7. Click Apply to save the changes.

Configuring mail settings

1. Click Administration.
2. From the Appliance section, click Configuration > Mail Settings.
3. Select Mail Enabled.
4. In From Address, enter the e-mail address used for sending e-mail.
5. In SMTP Server, enter the details of the SMTP server.
6. In SMTP Port, enter the SMTP port number.
7. If the SMTP server requires authentication, select Required in the Authentication section. Then enter the user name and password for the SMTP server.
8. Click Apply to save the changes.

If you configure the appliance mail server settings for an invalid mail server, using mail.send() in a pattern introduces a delay of approximately three minutes while the appliance attempts to contact the SMTP server.

Modifying JVM settings

1. Click Administration.
2. From the Appliance section, click Configuration > JVM Settings.
   The JVM Settings page lists the default and current values for the minimum and maximum memory settings for each JVM.
3. To adjust a setting, select the value from the menu in the Change To column.
4. Click Apply.
5. Restart the appliance.

Configuring usage data collection

Usage data submission

By default, usage data collection is not activated on the appliance. On activation, the appliance submits usage data once every seven days through the customer's web browser. Ten seconds prior to an attempted submission, the Discovery user interface (below the Logout button) displays a message showing the time remaining until the next submission.

To postpone the submission for a day, click not today. Click more info to pause the countdown and show the data to be submitted.

Anonymity

The data sent to BMC Software is totally anonymous. An appliance ID is used, but the appliance cannot be identified from the appliance ID, it is only used to group submissions from the same appliance. The webserver to which the data is sent is configured not to record the source IP address of submitted data.

FAQ

 Click here to show FAQs and their answers.

Why?

BMC Atrium Discovery is a high risk system that has access to some very sensitive data in my data center — why does BMC have functionality to share information from BMC Atrium Discovery across the internet?

The critical point to notice here is that BMC Atrium Discovery is not sharing any sensitive data — there are no details in the data about your environment or IT, and there is nothing in the data that can identify its source. Even the web servers at BMC that receive the submissions of the data are configured to discard (that is, to not log) the originating IP addresses, so that we at BMC would be unable to tie a submission to the customer that submitted it even if we wanted to.

The reason that we have this functionality is so that we can see how our customers use the software, and how to optimally make improvements to it — this will be to your direct benefit, as we can ensure we cater to environments of your size.

What is and what can be sent to BMC?

The data that is communicated back to BMC falls into two categories:

• Statistical usage information: this is information such as the version of BMC Atrium Discovery, the number of discovery runs configured in BMC Atrium Discovery, the number of credentials, which reports are used, the number of different types of items discovered (that is, the server count, switch count, and so on) and how many of those are synchronized to a CMDB.
• SNMP Recognition Rules: you can enable or disable this item as required. When you associate a sysOID with a device vendor and model name using the new SNMP recognition rules functionality, that data is sent to BMC for us to include in our content. In this way, other customers will benefit from your capturing this information, and you will benefit from all of the work that they do.

One of the items we send back is the "applianceID" - this is the consolidation ID that is generated by your appliance, and we use it to tell when we have received multiple submissions from the same BMC Atrium Discovery appliance. We cannot use the ID to identify you, as we never receive that ID from you through any other avenue.

Isn't this a half open backdoor that could be exploited further?

Absolutely not. The data to be sent is hard-coded and displayed in its entirety in the UI. The phone-home logic gathers the data it was written to gather, and then it makes an HTTP POST to the BMC webserver to submit it (using a form submission). It does not receive any result from BMC that it then processes, and there is no facility for BMC to instruct the appliance on what data to send.

How can I ensure that this functionality is not switched on by mistake?

We hope that, having read this FAQ, you'll be happy to switch it on deliberately! If you decide not to participate then you can turn the feature off and it will never ask again to be turned on. Further, only somebody with System permissions can enable this feature which protects you from unauthorized staff switching it on.

Managing usage data collection

You can manage data collection from the Administration > Configuration > Usage Data Collection tab. The following table describes the fields and their corresponding functions on the Usage Data Collection tab:

Activating and deactivating the Usage Data Collection feature

Initial activation

To activate or deactivate usage data collection, you must have permissions to write system settings (system/settings/write). After the initial deployment, when you log on to BMC Atrium Discovery, a Usage Data Collection popup window asks you to activate the feature. Select one of the following options:

• Activate — Activates the feature and allows submission of anonymous usage data.
• Not now — Postpones the decision to activate the feature until later. The popup window prompt will continue to appear until you activate or deactivate the feature.
• here — Displays the Usage Data Collection tab which shows the data that would be submitted on activation.

Subsequent activation and deactivation of the Usage Data Collection

You can choose to deactivate the feature from the Usage Data Collection tab by clicking Deactivate. If you want to active the feature again, click Activate.

Configuring anonymous user feedback

The User Feedback feature enables you to submit anonymous comments on BMC Atrium Discovery to BMC. In doing so you can enable us to better understand how BMC Atrium Discovery meets your needs.

User feedback submission

User feedback submission is enabled as a part of usage data collection. By default, the user feedback button is disabled on the appliance. On activation, the user feedback button appears as a floating label in the bottom right of the UI. Any feedback sent this way is entirely anonymous.

Enabling user feedback submission

To enable user feedback submission:

1. You can enable user feedback submission from the Administration > Configuration > Usage Data Collection tab. 
   
2. Usage Data Collection must be activated to enable user feedback submission. If it is not activated, click the Activate button at the bottom of the page.
3. Enable the User feedback capability by selecting the Activate feedback button on all pages option.

Localizing the appliance

Setting the keyboard layout

The console keyboard layout can be temporarily changed using the loadkeys command to test that a keyboard layout works correctly.

To change the keyboard layout to a US layout, enter the following command:

[tideway@london01 ~]$ loadkeys us
[tideway@london01 ~]$ 

To change the keyboard layout to a UK layout, enter the following command:

[tideway@london01 ~]$ loadkeys uk
[tideway@london01 ~]$ 

After you have determined that the layout works correctly, you should make the change permanent. To do so, change the KEYTABLE, MODEL, and LAYOUT variables in the /etc/sysconfig/keyboard file. For example, to change the keyboard layout to a US layout, use the following:

KEYTABLE="us"
MODEL="PC105+inet"
LAYOUT="us"

The keyboard mapping files can be found in /lib/kbd/keymaps/i386/ but usually you can use the 2-letter
ISO Country Code. See the ISO website to find the code for the country you require. For example, us (United States), uk (United Kingdom), de (Germany), and no (Norway).

Setting the system timezone

The system-wide timezone in Linux is defined by the files /etc/sysconfig/clock and /etc/localtime.

The file /etc/sysconfig/clock is used by the system during upgrades to ensure that /etc/localtime references the latest information. The ZONE value in /etc/sysconfig/clock must reference one of the timezone data files in /usr/share/zoneinfo/. These files contain all the timezone and daylight savings rules for a particular location (for example, /usr/share/zoneinfo/Europe/London contains all the data for London). These files are part of the base packages installed by the system (they are from the tzdata package in RHEL and Fedora).

The file /etc/localtime is either a copy of or a link to one of the timezone data files in /usr/share/zoneinfo/.

To set the timezone, as the root user, update the value of ZONE in /etc/sysconfig/clock and copy or link the relevant file from /usr/share/zoneinfo to /etc/localtime. You must restart the tideway service to bring the timezone change into effect. For example, to set the time to New York time:

[root@london01 ~]# mv /etc/sysconfig/clock /etc/sysconfig/clock.old
[root@london01 ~]# sed -e s/ZONE=\"[^\"]*\"/ZONE=\"US\\/Eastern\"/ /etc/sysconfig/clock.old > /etc/sysconfig/clock
[root@london01 ~]# mv /etc/localtime /etc/localtime.old
[root@london01 ~]# ln -s /usr/share/zoneinfo/US/Eastern /etc/localtime
[root@london01 ~]# exit
[tideway@london01 ~]$ sudo /sbin/service tideway restart

Setting the system time

You can set the time using the date command. For example, to set the current date to ten past twelve on 4 July 2013, enter the following command:

[root@london01 ~]$ date -s "12:10:00 20130704"
Thu Jul 4 12:10:00 BST 2013
[root@london01 ~]$ 

The format for the date string is HH:MM:SS YYYYMMDD.

You can also configure the appliance to synchronize the internal clock to an ntp server. See Configuring the NTP client at the command line for more information.

Do not change the appliance time on to an earlier setting

After BMC Atrium Discovery has been running and has created nodes in the datastore, you must not change the time to an earlier setting. The transaction scheme in the datastore is based on timestamps and setting an earlier time makes data appear out of date causing many transactions to fail.

Configuring dependency visualizations

Configuration file

1. Configuration File Location - The default configuration file can be found in the following location:
   /usr/tideway/data/default/graph-definition.txt
   This default configuration file must not be changed.
2. Configuration File Customisation - To customize a configuration file, create the following:
   /usr/tideway/data/custom/visualizations/graph-definition.txt
   This overlays the default configuration file.

Structure of the file

The file is divided into three sections by rows of equals signs. The first section defines visualization definitions, the second dependency definitions, and the third tooltip definitions. For an explanation of each of these, see the following sections:

Visualization definitions

The visualization definition section contains a number of definitions for visualizations. Each definition takes the form:

visualization_name (tab=tab_name) viewed_node_type type_of_dependency dependency_target_node_type type_of_dependency dependency_target_node_type ... type_of_dependency dependency_target_node_type

• visualization_name — the name of the visualization. This is displayed in the visualizations list when viewing a node of the type defined in viewed_node_type.
• tab_name — the tab under which to display the visualization. Valid values are:
  • Home
  • Application
  • Infrastructure
  • Discovery
  • Reports
  • Setup
  • If no tab is specified, no tab is selected when the visualization is displayed.
• viewed_node_type — the type of node for which this visualization is available.
• type_of_dependency - the type of dependency, for example, depended_upon, or dependant.
• dependency_target_node_type - the node type that is the target for the dependency. For example, in a dependency visualization describing the relationship between a business application running on a host and the host itself, the target is Host.
  For example:

Dependency (tab=Infrastructure) SoftwareInstance depended_upon SoftwareInstance dependant SoftwareInstance running_on Host BusinessApplicationInstance depended_upon BusinessApplicationInstance dependant BusinessApplicationInstance running_on Host

This defines a visualization called Dependency which will be available on the visualizations list when viewing a Software Instance or a Business Application Instance. When displayed, the Infrastructure tab will be selected.

When you pick the Software Instance visualisation, you see the Software Instance node as the starting point of the visualisation, and then all Software Instance and Host nodes related to that Software Instance. Exactly which Software Instance and Host nodes are shown depends on the definition of the depended_upon, dependant, and running_on dependency definitions, which are defined in the dependency definitions part of this file.

The indentation is important and defines the structure of the visualization. An indentation must be composed of spaces, not tabs, and be a multiple of two spaces.

Dependency definitions

The dependency definition (type_of_dependency) defines the route from the viewed_node_type to the dependency_target_node_type.
For example, the following visualization definition, from the first section of the file, shows all Hosts that a Software Instance is running on:

Dependency SoftwareInstance running_on Host

The running_on Host relationship defines the route from the Software Instance to the Host. One of these definitions must exist in the dependency definitions. For example:

SoftwareInstance running_on Host RunningSoftware:HostedSoftware:Host:Host

Here, Software Instance is defined as the source node kind and Host is defined as the destination node kind, and the system will use the traversal RunningSoftware:HostedSoftware:Host:Host to get from any Software Instance nodes currently in the visualization to any related Host nodes.

A dependency definition can have multiple traversals chained one after the other in order to get to a node kind that is distantly related:

Host connected_to Subnet DeviceWithInterface:DeviceInterface:InterfaceOfDevice:NetworkInterface DeviceOnSubnet:DeviceSubnet:Subnet:Subnet 

The visualization will show only Host and Subnet nodes, but in order to get to Subnet nodes from Host nodes, it will traverse through Network Interface nodes.

You can also define a number of alternative paths by listing them on separate lines:

SoftwareInstance communication SoftwareInstance Server:Communication:Client:SoftwareInstance Client:Communication:Server:SoftwareInstance

Each path will be tried in turn, and all resulting nodes connected to the source node will be returned.

Relationships can be wildcarded in the same way as in a generic search using ::

 SoftwareInstance composed_of DiscoveredProcess InferredElement:Inference::DiscoveredProcess

Traversal steps can have an optional '+' after them, for example:

SoftwareContainer:SoftwareContainment:ContainedSoftware:SoftwareInstance+

This causes the step to be followed repeatedly, adding nodes to the set of nodes found so far, until further traversals add no further nodes. The step is always evaluated at least once. A good use of this function is to follow a relationship that forms an arbitrarily deep hierarchy: for example, the Software Instances making up a BAI. Here it is possible to have a first-order Software Instance with a second-order Software Instance as the container, before reaching the BAI. Although not recommended and not often seen, a third-order Software Instance can be inserted between the second order Software Instance and the BAI, and so on. This function will navigate this structure.

Attributes

Attributes can be set on a dependency definition that affect how it is rendered. For example:

SoftwareInstance communication.server SoftwareInstance (color=0f0,left_arrow) Server:Communication:Client:SoftwareInstance communication.client SoftwareInstance (color=0f0,right_arrow) Client:Communication:Server:SoftwareInstance

This displays lines between Software Instance nodes representing client/server communications in green, and draws an arrow pointing at the server.

Attributes appear in brackets after the definition of the dependency type and destination node kind. No spaces are allowed between the brackets, and the attributes are a comma separated list of either flags, or key and value.

Defined attributes are:

 color=rgb left_arrow right_arrow left_box right_box

• color: sets the color of the line in the graph. It takes a three character argument that is the color as an RGB tuple. Each character is the color of that component as a hexadecimal digit (0-f).
• left_arrow: sets arrow heads on the line, pointing to the source node.
• right_arrow: sets arrow heads on the line, pointing to the target node.
  Both attributes can be set, in which case both ends of the line have an arrow, and neither attribute can be set, in which case the line is plain.
• left_box
  • traverse to the destination nodes using the given traversal
  • represent the source node as a box
  • add the destination nodes in the box
• right_box
  • traverse to the destination node using the given traversal
  • represent the destination node as a box
  • add the source node in that box

There must only be a single destination node when using right_box, because it is impossible to turn several destination nodes into separate boxes and put the source node inside each of them. It should be used when it is known there will always be at most one destination node, for example, the Host Container for a Host.

Boxes only appear at the top level; they cannot be nested. If a later definition conflicts with an earlier, for example, attempting to nest boxes or put a node inside two different boxes, the later definition overrides the earlier. The order depends on how the graph is constructed and is not predictable.

The left_box and right_box attributes override the color, left_arrow, and right_arrow attributes.

Special traversals

The :NetworkConnections:: traversal which can be used with Hosts and DiscoveredProcesses, connects nodes based on observed communication information. Observed communication information is directly discovered, rather than specific communication relationships built by patterns.

DiscoveredNetworkConnections and ListeningPorts are used to find this information. These types of traversal are quite slow.

Defining traversals

It is recommended that arrows on edges point towards the depended upon node. For example, the Switch on an edge between Host and Switch, or the Software Instance on an edge between BAI and Software Instance. This will ensure the layout algorithm lays the graph out properly when in hierarchical layout mode.

It makes sense to name traversals as a verb phrase that can be read in the middle of the start and end node kinds (where end is defined as the node with the arrow head and start is the other one). For example, Software Instance running_on Host. This makes it easy to read off what any given edge in the visualization means.

It is also recommended that when defining a pair of traversals for moving between nodes in either direction (for example, from Host to Software Instance and from Software Instance to Host, both using the "RunningSoftware" relationship), that the traversal is named the same thing. In other words, instead of defining the two traverals like this:

 Host has_running_on_it SoftwareInstance (right_arrow) Host:HostedSoftware:RunningSoftware:SoftwareInstance SoftwareInstance is_running_on Host (right_arrow) RunningSoftware:HostedSoftware:Host:Host

define it like this:

 Host running_on SoftwareInstance (left_arrow) Host:HostedSoftware:RunningSoftware:SoftwareInstance SoftwareInstance running_on Host (right_arrow) RunningSoftware:HostedSoftware:Host:Host

The latter form ensures that the edges all point towards the depended upon node (the Host), and also keeps the name the same. If the name, attributes (color and dashed), and source and destination nodes are the same, but the arrow and source and destination nodes are opposites, the two edges will be merged. Without this, the visualization can become ugly as lots of edges will be double edges.

There is one case where a pair of opposite traversals cannot have the same name: when the source and destination nodes are the same node kind. For example:

 SoftwareInstance depended_upon SoftwareInstance (color=00f,right_arrow) Dependant:Dependency:DependedUpon:SoftwareInstance dependant SoftwareInstance (color=00f,right_arrow) DependedUpon:Dependency:Dependant:SoftwareInstance

Ideally the traversals should be called the same thing, as they are opposites of each other. But because the source and destination nodes are the same, there is no way to distinguish them other than to use a different traversal name. In this case, the visualization might end up with two edges between a pair of Software Instances, one pointing one way and labelled "depended_upon" and the other pointing the other way and labelled "dependant".

It is a convention to use the name "xxxxx.box" for "box" traversals, ie. those that put the source or destination nodes in a box by using left_box or right_box. This is because often the non-box case is also required in some visualizations. With this naming scheme, it is clear which form is being used.

Tooltip definitions

By default, the attributes shown as a tooltip when a user hovers over a node are read from the summary list defined in the taxonomy. The tooltip section allows that to be overridden. For example:

Host name os_class

Configuring audit and application options

To set audit and application options

1. From the Appliance section of the Administration tab, select Miscellaneous.

   Field Name	Details
   Allow Audit logs to be fully purged	Users can purge the audit log of all events up to one month before the current date. This ensures that there is a minimum retention period of one month. You can configure the appliance to permit purging up to the current date. You can enable or disable full purging with this option. The default is No.
   History Compression Threshold	The historical comparison pages 'compress' the raw history into changes. Entries are grouped by user and a sliding time threshold. This time threshold is necessary to enable you to view a number of separate changes made by Reasoning as a single change. Select from the following values in the list: • 15 seconds • 30 seconds • 1 minute (default) • 5 minutes • 10 minutes • 30 minutes • 1 hour • 8 hours • 24 hours The History Compression Threshold can be thought of as a sample rate. Select a value providing sufficient granularity to capture the change that you are looking for. For example, if a node is changing state every 20 minutes, a sample rate below this would be required to capture the changes, in this case, choose 10 minutes.
   Max number of visualizations to cache	The maximum number of visualizations to cache. Select from the following values in the list: • 0 (default) • 10 • 100 Changing this setting requires a restart of the tideway service to take effect. Restarting the tideway service clears the visualizations from the cache.
   Time to cache visualizations for	The time to cache visualizations for. This is the length of time from creation of the visualization rather than the last view. Select from the following values in the drop-down list: • 1 hour • 1 day • Forever (default)

Visualization cache

Complex visualizations which need to traverse over many relationships to build the data, such as the Application Dependencies - Software View, can be slow to load. Caching of generated visualizations has been introduced to ensure that this can be minimized.

You should note that cached data is not live, so using this feature will result in visualizations which might not be consistent with the current state of the datastore. This is particularly important when using the forever setting.

Changing either visualization cache settings requires a restart of the tideway service to take effect. Restarting the tideway service clears the visualizations from the cache.

Configuring model maintenance settings

Datastore cache

In previous versions the datastore cache setting required manual configuration. It is now managed automatically.

To configure model maintenance settings:

1. From the Model section of the Administration tab, select Model Maintenance.
   

   The options on the page are described in the following table.

   Directly Discovered Data removal	Specify the age past which Discovery Accesses and all the related DDD nodes are removed (the default is 28 days). • Quarterly (90 days) • Monthly (28 days) • Fortnightly • Weekly If the setting does not match one of these options the value will be shown as "--custom settings--". In a demonstration appliance only, the default setting for aging is Never, meaning that demonstration data never ages out of the system. This setting is not available for any other type of appliance, and demonstration appliances should never be used for anything other than demonstrations. For guidelines, see Modifying DDD, host, and software instance aging limits.
   Time before destroyed nodes are purged	Specify the time elapsed before destroyed nodes are purged from the datastore. The default is one year. To change this, choose one of the following periods from the drop-down list. • Never • 30 days • 90 days • 180 days • One year • Two years
   Time before history entries are purged	Specify the time elapsed before history entries are purged from the datastore. The default is never. To change this, choose one of the following periods from the drop-down list. • Never • 30 days • 90 days • 180 days • One year • Two years
   Scan optimization timeout	When an IP address is designated the preferred IP address for a host, Discovery does not perform scans on other known IP addresses for that host. This is referred to as scan optimization. After a specified Scan optimization timeout period, Discovery will scan other known IP addresses for that host to ensure that they are still non-preferred and on the same host. The default is seven days. Specify one of the following timeout periods from the drop-down list. • 1 - 10 days • 14 days • 21 days
   Host/Network Device/Storage Device/Printer/SNMP Managed Device/Mainframe aging time limit	Specify the host/network device/storage device/printer/SNMP managed device/mainframe aging time limit (the default is 10 days). • 2 - 10 days • 14 days • 21 days • 28 days For guidelines, see Modifying DDD, host, and software instance aging limits.
   Host/Network Device/Storage Device/Printer/SNMP Managed Device/Mainframe aging access failures	Specify the number of host/network device/storage device/printer/SNMP managed device/mainframe access failures. • 1 - 10 failures
   Time to elapse before a software instance/runtime environment/storage can be aged	Specify the time to elapse before a software instance/runtime environment/storage node can be aged. (the default is 10 days). • 1 - 20 days • Steps of 5 to 100 days For guidelines, see Modifying DDD, host, and software instance/runtime environment aging limits
   Minimum number of failed accesses before a software instance/runtime environment/storage is aged	Failed accesses before a software instance/runtime environment/storage node is aged. • 1 - 20 failures • Steps of 5 to 45 failures
   Size Warning	The maximum size of the datastore. When this limit is reached, a warning is displayed in the Appliance Status page. This is a soft limit and does not prevent the datastore growing beyond the specified limit. You can select any value from 10 to 100 GB in steps of 5 GB from the list. The default is 30 GB.
   Checkpoint Interval	The interval between datastore checkpoints. The larger the interval, the more data has to be written to the checkpoint files. The smaller the interval, less data needs to be written to the checkpoint files, though the writing takes place more often. The default is 15 minutes. You must contact Customer Support before you make any changes to this setting.

Modifying DDD, host, and software instance aging limits

In general, the expectation that BMC Atrium Discovery uses for deriving the default model maintenance settings is based on performing one scan of the estate every 24 hours with a DDD depth of one month. This expectation is also used to derive the sizing data. The default setting for data aging for both hosts and software instances is 10 days, because for most deployments this limit provides the best balance of responsiveness without data thrashing. Putting this in a business example, this gives two weekends plus additional time to detect that a host is aging, investigate why it is doing so, and make changes before the host is destroyed. It gives the software teams the same length of time to sort out any failures in the estate.

Best Practice

BMC recommends that you do not attempt to fine-tune model maintenance parameters. Doing so can make BMC Atrium Discovery highly reactive and have negative consequences, such as causing a dramatic increase in the size of the datastore and putting more load on your target estate. If you do alter the model maintenance parameters, BMC recommends that you do not vary more than half or twice the standard settings detailed in the preceding table.

However, there might be occasions when modifying the defaults are necessary, particularly if you scan your estate at different intervals and need to keep close control on disk consumption. The following table show recommended settings based on your scanning frequency.

For more information about aging and how it fits in the node removal process, see How nodes are removed.

Scheduled DDD aging

Viewing existing DDD aging blackout windows

To view existing DDD aging blackout windows:

1. From the Model section of the Administration tab, select Model Maintenance.
2. Select the DDD Removal Blackout Windows tab.
   

When you view the DDD Removal Blackout Windows tab, the active blackout window is highlighted. If multiple blackout windows are active, the one with the longest time remaining before it ends is highlighted. This is not automatically refreshed.

DDD nodes are removed in batches which are not interrupted. Once removal starts, it continues to completion. Therefore, if a batch removal is in progress at the beginning of a DDD removal blackout window, it will continue into the blackout until completion. In normal operation this should take no more than a few minutes.

Adding a new DDD aging blackout window

You can schedule a new DDD aging blackout window to occur daily, weekly, or monthly and can specify a start time and duration. To schedule a new DDD aging blackout window:

1. Click the Add button.
   The Add a New DDD Removal Blackout Window dialog box is displayed.

2. Enter the information for the blackout window in the fields described below.

   Field Name	Details
   Comment	Enter a descriptive comment for the blackout window.
   Frequency	Select a frequency for the window to operate. For example, this can be Daily, Weekly, or Monthly. For a weekly blackout window, you are provided with buttons for each day. Select the day or days that you want the window to operate. For a monthly blackout window, you are provided with buttons for each day in the month. Select the day or days that you want the window to operate. Alternatively, select the No Removal On The radio button and choose one of: • First • Second • Third • Fourth • Last and the day that you want the window to operate. In this way you can select the Second Tuesday of the month and so forth.
   Start Time	Select a time for the window to start.
   Duration	Select a duration in hours. This is the length of time that the blackout window operates and can be from 1 to 24 hours. For a daily blackout window the maximum number of hours you can select is 23. This prevents you from inadvertently scheduling a 24/7 blackout.

3. Click OK.

Scheduling DDD removal blackout windows

Viewing existing DDD aging blackout windows

To view existing DDD aging blackout windows:

1. From the Model section of the Administration tab, select Model Maintenance.
2. Select the DDD Removal Blackout Windows tab.
   

When you view the DDD Removal Blackout Windows tab, the active blackout window is highlighted. If multiple blackout windows are active, the one with the longest time remaining before it ends is highlighted. This is not automatically refreshed.

DDD nodes are removed in batches which are not interrupted. Once removal starts, it continues to completion. Therefore, if a batch removal is in progress at the beginning of a DDD removal blackout window, it will continue into the blackout until completion. In normal operation this should take no more than a few minutes.

Adding a new DDD aging blackout window

You can schedule a new DDD aging blackout window to occur daily, weekly, or monthly and can specify a start time and duration. To schedule a new DDD aging blackout window:

1. Click the Add button.
   The Add a New DDD Removal Blackout Window dialog box is displayed.

2. Enter the information for the blackout window in the fields described below.

   Field Name	Details
   Comment	Enter a descriptive comment for the blackout window.
   Frequency	Select a frequency for the window to operate. For example, this can be Daily, Weekly, or Monthly. For a weekly blackout window, you are provided with buttons for each day. Select the day or days that you want the window to operate. For a monthly blackout window, you are provided with buttons for each day in the month. Select the day or days that you want the window to operate. Alternatively, select the No Removal On The radio button and choose one of: • First • Second • Third • Fourth • Last and the day that you want the window to operate. In this way you can select the Second Tuesday of the month and so forth.
   Start Time	Select a time for the window to start.
   Duration	Select a duration in hours. This is the length of time that the blackout window operates and can be from 1 to 24 hours. For a daily blackout window the maximum number of hours you can select is 23. This prevents you from inadvertently scheduling a 24/7 blackout.

3. Click OK.

Configuring disk space monitor

• Free disk space baseline threshold: The threshold below which the machine baseline raises a critical warning. By default, it is 2048 MB for the partition holding the datastore and 200MB for the partition holding the log files. Baseline threshold is twice of the free disk space threshold. The baseline threshold only raises a warning and does not shut down the machine or prevent it from starting.

• Free disk space shut down threshold: The threshold below which the free disk space monitor gracefully shuts down BMC Atrium Discovery and prevents it from starting until the free disk space baseline threshold is available. By default, it is 1024 MB for the partition holding the datastore and 100Mb for the partition holding the log files.

  If free disk space on respective partitions on a machine in a cluster is below the shut down threshold, the free disk space monitor shuts down all the machines on that cluster and prevents the machines from starting until the free disk space at least match the baseline threshold.

Managing free disk space

You can perform the following operations related to managing and monitoring the disk space on a standalone machine or a cluster member:

Viewing the disk usage of a standalone machine

To view disk usage on a standalone machine:

1. Click Administration.
2. From the Appliance section, click Disk Configuration.
   The Current Usage section of the Manage ADDM Disks page displays the current disk usage. For more information, see Managing disks and swap space.
   

Viewing the disk usage of the cluster member

To view disk usage on a cluster:

1. On the coordinator, click Administration.
2. From the Appliance section, click Cluster Management.
   The Cluster Management page displays the disk usage of each machine on the cluster.
   

Checking the Appliance Disk Space against the baseline

To check the Appliance Disk Space against the predefined baseline on a standalone machine or any cluster member:

1. Click Administration.
2. From the Appliance section, click Baseline Status.
   The Baseline Status page displays the results of the recent checks.

3. Click Check Baseline Now at the bottom of the list to get the latest information and see if the Appliance Disk Space check status is OK.

Freeing up disk space

If the free disk space is below the baseline threshold, a critical baseline warning is raised:

To prevent any shut down, you must free up some disk space on the machine. Possible areas from where you may free up disk space are:

• Application log files: see Contents of the logs for a description and the location of the main application log files. BMC Atrium Discovery is not reliant on these log files and they can be safely deleted. However, the datastore transaction logs must not be deleted, see operational warnings for more information.
• Cores: check that there are no old cores in $TIDEWAY/cores.
• Record data: you can delete any record data that is not required, or using the disk configuration tool you can move record data to an additional disk.
• Workspaces: any areas that you have used as workspaces or staging areas for exports.

If the free disk space is below the shut down threshold, the free space monitor shuts the machine down and the UI displays the machine name which has insufficient free disk space. You must log on to that machine and free up the disk space to the baseline threshold at the minimum. Thereafter, you must restart the services.

Restarting the services to recover from the forced shutdown

When the free disk space goes below the shutdown threshold which is equal to baseline threshold multiplied by two, the BMC Atrium Discovery services are stopped. After you free up the space on the machine that caused the shutdown, you need to restart these services.

To restart services, run the following command on a standalone machine or on any machine in the cluster:

tw_cluster_control --cluster-start-services

Managing disks and swap space

The disk configuration utility enables you to move BMC Atrium Discovery data onto and create swap space on new disks on your appliance. However, the following restrictions apply:

• You can only move data to or create swap space on disks that are not currently used by BMC Atrium Discovery.
• You cannot move more than one component of BMC Atrium Discovery data to a given target disk.
• You cannot move the components back to the system disk after they have been moved to a secondary disk.

Back up your data before changing disk configurations

The disk management utility performs disk operations such as partitioning and moving data. All data on the new disks is deleted. When data is moved from the system disk, it is copied to the new disk and deleted from the system disk. Before using it you should always back up your appliance.

LVM is not supported

If you try to add an LVM disk, the operation fails and the following message is displayed:
Unexpected system configuration: LVM-based configuration detected

The following disk types are defined:

The Disk Configuration page of a standalone appliance displays the following:

• A panel which shows any pending operations
• A panel which shows the current configuration of any disks in the appliance and the suggested configuration of any new disks
• A comprehensive key to the data types and their representation
   

On any new disk, a Change Usage drop down list is displayed which is populated with the data partitions on the system disk. Where there is insufficient space on the new disk to copy the data from a particular partition, that partition's label is disabled. The label is also disabled if the partition has already been selected to have its data moved to another disk.

You can also choose to add a swap partition to the disk by selecting the check box. The check box is only displayed if you have insufficient swap space configured. The disk configuration utility uses the following calculation to determine the best swap size.

• Where the amount of memory is less than 16 GB, swap size is set at double the memory size.
• Where the amount of memory is between 16 and 32 GB, swap size is set at 32 GB.
• Where the amount of memory exceeds 32 GB, swap size is set to equal the memory.

The add swap check box is not displayed if the available new disk does not have enough space to store the additional swap to reach the optimal swap size. For example, if the system has 8GB swap by default, and the optimal swap size is 24GB, then 16GB additional swap is required. If the new disk has only 12GB available, the check box is not displayed.

When you make the changes you have chosen or to accept the changes suggested by the system, the services are shut down and a progress indicator is displayed.

To move data to a new disk

1. Backup your appliance.
2. From the Appliance section of the Administration tab, click Disk Configuration.
   The Disk Configuration page is displayed.
3. If the suggested configuration is what you want, continue this procedure from here.
4. If you do not want to accept the suggested configuration, select Do not move any data here from Change Usage.
5. Select the data to move to the new disk from Change Usage. If the disk is of the type "Non ADDM Disk" then you must unmount all partitions on the disk before proceeding.
6. Select the Add swap check box if you want to add additional swap space.
7. Review the pending changes list.
   If it is what you want, click Start.
8. You are requested for confirmation. The BMC Atrium Discovery Services are stopped and all of the contents of the new disks are deleted before moving data or creating swap partitions. Click OK to proceed.
9. The status page is displayed which shows a progress indicator and details of the individual operations.
   Once the operation has been completed, the services are started and the login page is displayed.

If the only operation you perform is to add swap to a new disk, the services are not stopped and started and you do not need to login.

When data is moved from an additional disk that contains only a data partition, at the end of processing, the disk is identified as a "New Disk" and is displayed with a suggested configuration. The existing data is not deleted, though the partition is not mounted.

When data is moved from an additional disk that contains a data partition and a swap partition, at the end of processing, the disk is identified as an "Non ADDM Disk". The existing data is not deleted, though the partition is not mounted. To reuse this disk, disable the swap partition as shown here.

Managing disks and swap space in a cluster

To minimize cluster downtime, you configure and queue the changes on individual machines and then apply the changes. When you apply the changes, the cluster is shut down automatically and restarted when all of the changes have been applied to the individual machines.

As with a standalone appliance, the following restrictions apply:

• You can only move data or create swap space on disks that are not currently used by BMC Atrium Discovery.
• You cannot move more than one component of BMC Atrium Discovery data to a given target disk.
• You cannot move the components back to the system disk after they have been moved to a secondary disk.

Back up your data before changing disk configurations

The disk management utility performs disk operations such as partitioning and moving data. All data on the new disks is deleted. When data is moved from the system disk, it is copied to the new disk and deleted from the system disk. Before using it you should always backup your cluster.

LVM is not supported

If you try to add an LVM disk, the operation fails and the following message is displayed:
Unexpected system configuration: LVM-based configuration detected

The following disk types are defined:

The Disk Configuration page of a cluster member displays the following:

• A panel which shows the queued changes for all members of the cluster
• A drop down list with links to the UI of each of the other cluster members
• A panel which shows the current configuration of any disks in the appliance and the suggested configuration of any new disks
• A comprehensive key to the data types and their representation

Configuration options for a new disk

Once a physical (or virtual in the case of a VM) disk has been added to the appliance and recognized by the operating system, it is displayed in the Disk Configuration window.

On any new disk, a Change Usage drop down list is displayed which is populated with the data partitions on the system disk. Where there is insufficient space on the new disk to copy the data from a particular partition, that partition's label is disabled. The label is also disabled if the partition has already been selected to have its data moved to another disk.

You can also choose to add a swap partition to the disk by selecting the check box. The check box is only displayed if you have insufficient swap space configured. The disk configuration utility uses the following calculation to determine the best swap size.

• Where the amount of memory is less than 16 GB, swap size is set at double the memory.
• Where the amount of memory is between 16 and 32 GB, swap is set at 32 GB.
• Where the amount of memory exceeds 32 GB, swap is set to equal the memory.

The add swap check box is not displayed if the available new disk does not have enough space to store the additional swap to reach the optimal swap size. For example, if the system has 8GB swap by default, and the optimal swap size is 24GB, then 16GB additional swap is required. If the new disk has only 12GB available, the check box is not displayed.

When you make the changes you have chosen or to accept the changes suggested by the system, the services are shut down and a progress indicator is displayed.

To move data to new disks on cluster members

Once new disks have been added to cluster members and recognized by their individual operating systems, they are displayed in the Disk Configuration window of that machine's UI. To move data to the disk:

1. Backup your cluster.
2. From the Appliance section of the Administration tab, click Disk Configuration.
   The Disk Configuration page is displayed.
3. If the suggested configuration is what you want, continue this procedure from here.
4. If you do not want to accept the suggested configuration, select Do not move any data here from Change Usage.
5. Select the data to move to the new disk from Change Usage. If the disk is of the type "Non ADDM Disk" then you must unmount all partitions on the disk before proceeding.
6. Select the Add swap check box if you want to add additional swap space.
7. Click Queue to add the changes to the Queued Changes for the Cluster list.
8. Repeat from here for each member of the cluster that you need to make changes to. To access the other members of the cluster, select the link for the required member from the Go to another Cluster Member drop down list.
9. Review the Queued Changes for the Cluster list. Click one of the following options to continue:
   • Click Cancel all to remove all queued changes for all machines from the list. You can then start the procedure again.
   • Click Cancel to delete the queued request for the current machine and enable you to reconfigure it.
   • Click Start to proceed.
10. If you clicked Start, you are then requested for confirmation. The BMC Atrium Discovery services are stopped on all members of the cluster and all of the contents of the new disks on all members are deleted before moving data or creating swap partitions.
11. The status page is displayed on each cluster member UI which show a progress indicator and details of the individual operations.
    Once the operation has been completed, the services are started on all members and the login page is displayed on each member's UI.

Note

If the only operation you perform is to add swap to a new disk, the services are not stopped and started and you do not need to login, nor do you need to shut down the cluster.

When data is moved from an additional disk that contains only a data partition, at the end of processing, the disk is identified as a "New Disk" and is displayed with a suggested configuration. The existing data is not deleted, though the partition is not mounted.

When data is moved from an additional disk that contains a data partition and a swap partition, at the end of processing, the disk is identified as an "Non ADDM Disk". The existing data is not deleted, though the partition is not mounted. To reuse this disk, disable the swap partition as shown here.

Backing up and restoring the appliance

Destination system time must not be earlier than source when restoring a backup

You must ensure that the current system time on the destination appliance is no earlier than that of the appliance on which the backup was created. If the modification times on the files contained in the backup are later than the system time when they are restored, the backup will hang. To recover at this point you must kill the backup process, correct the time, run tw_restore --fix-interrupted then repeat the restore using the tw_restore command line utility.

Backing up and CMDB synchronization

The backup contains the CMDB synchronization configuration. When a host has significantly changed so that its key has also changed, problems can be caused if a backup is restored before the changed host is rediscovered. In this case, on the next CMDB synchronization, duplicate hosts will be created in the CMDB representing the changed host, and the CIs representing the original hosts will never be deleted. To ensure that no duplicate hosts are created, you can delete and then recreate the BMC.ADDM dataset.

The backup contains the LDAP configuration. If the destination appliance cannot access the LDAP server, you must ensure that a local (non-LDAP) user belonging to the system and public groups is activated and successfully tested on the source appliance before making a backup.

If you choose to exclude sensitive data when backing up an appliance in which CMDB synchronization has been configured, the CMDB Sync page on the restored appliance displays the "This appliance has not been set up for synchronization with the Atrium CMDB" message. Once the Setup form is complete, filter and blackout window settings are restored.

The appliance backup feature replaces the appliance snapshot that was available in previous releases. On upgraded appliances only, if snapshots are still held in the filesystem, a banner and Remove Snapshots button is provided so you can remove the snapshots and release disk space.

To create a backup of the appliance

1. From the Appliance section of the Administration tab, click Backup & Restore.
   The Appliance Backup page is displayed. This has a panel in which you can configure the backup destination, and details of the size and contents of the backup.
   

2. Enter the details for the backup destination. The fields that can be completed are displayed or hidden depending on the backup type selection. Required fields are indicated with a red asterisk.

   Field Name	Details
   Backup Type	Select the destination type from the drop down list. This can be one of the following: • Local — The backup is written to the $TIDEWAY/var/backup directory. Only one local backup can be stored. • SSH — The backup is written to a remote server over ssh. • Windows Share — The backup is written to a Windows share. You cannot create a backup on a Windows share from a FIPS enabled appliance. The mount operation fails and an error message written to syslog.
   Notes	A free text area in which you can write notes about the backup.
   Directory	The directory into which to write the backup on the remote SSH server. Backups are written into a subdirectory called YYYY-MM-DD_hhmmss_addm_backup inside the specified directory. (SSH only).
   Path	The share name and directory name into which to write the backup on a Windows share. Backups are written into a subdirectory called YYYY-MM-DD_hhmmss_addm_backup inside the specified directory. Path syntax is \\sharename\directoryname, where sharename is the name of the Windows share, and directoryname is the name of the directory into which to write the backup. (Windows share only).
   Host	The hostname or IP address of the remote server onto which to write the backup (SSH).
   Port	The port to which to connect (SSH).
   Username	The username to use to connect to the remote server (SSH and Windows share). To specify the domain for Windows shares, use the following syntax: user@domain
   Password	The corresponding password (SSH and Windows share).
   Verify backup	Select Verify backup to verify (md5) that the files in the backup archive are the same as those on the appliance. Shown only after successfully testing the connection for SSH and Windows share backups.
   Exclude sensitive data	Select Exclude sensitive data to exclude sensitive data from the backup. This will exclude the vault and the appliance key and certificate. Appliance UI users are always backed up and restored, regardless of this setting. So, for example, after a restore the password in effect for the system user will be the one from the source appliance. Shown only after successfully testing the connection for SSH and Windows share backups.
   Email when complete	Select Email when complete and enter an email address if you want an email to be sent automatically when the backup task is completed. Shown only after successfully testing the connection for SSH and Windows share backups.
   Test Connection	Click Test Connection to ensure that the remote host can be contacted and that the credentials are valid. Shown only for SSH and Windows share backups.

3. Click Shutdown & Backup to start the backup operation.
   You are prompted for confirmation.
4. Click No to return to the Appliance Backup page. Click Yes to continue and backup the appliance.
   All services are shut down before the backup occurs and a progress screen is displayed. A Cancel button is also displayed, but is only enabled at the stages of the backup where it is possible to cancel.

To restore a backup to the appliance

FIPS enabled appliance

You should not attempt to restore a backup to a FIPS enabled appliance. Rather, you should restore a backup onto the appliance and then enable FIPS. If you restore to a FIPS enabled appliance, the services cannot restart and the progress screen shows an omniORB.CORBA.INITIALIZE error.

1. Make sure that the time setting on the destination appliance is not earlier than the source appliance. Failing to do so results in a failed restore, and a time consuming process to repair the restore. See this warning for more information.
2. From the Appliance section of the Administration tab, click Backup & Restore.
   The Appliance Backup page is displayed.
3. Click the Restore Backup tab.
   The Restore Backup tab has a panel in which you can choose the source of the backup, and provides details of the size and contents of the existing local backup.
   

4. Enter the details for the backup source. The fields that can be completed are displayed or hidden depending on the backup type selection. Required fields are indicated with a red asterisk.

   Field Name	Details
   Backup Type	Select the destination type from the drop down list. This can be one of the following: • Local — The backup is read from the $TIDEWAY/var/backup directory. • SSH — The backup is read from a remote server over ssh. • Windows Share — The backup is read from a Windows share.
   Directory	The directory from which to read the backup on the remote server (SSH). Backups are written into a subdirectory called YYYY-MM-DD_hhmmss_addm_backup inside the specified directory. Ensure you specify the subdirectory name too. (SSH only).
   Path	The share name and directory name from which to read the backup on the remote server (Windows share). Backups are written into a subdirectory called YYYY-MM-DD_hhmmss_addm_backup inside the specified directory. Path syntax is \\sharename\directoryname, where sharename is the name of the Windows share, and directoryname is the name of the directory containing the backup. (Windows share only).
   Host	The hostname of the remote server from which to read the backup (SSH).
   Port	The port to which to connect (SSH).
   Username	The username to use to connect to the remote server (SSH and Windows share). To specify the domain for Windows shares, use the following syntax: user@domain
   Password	The corresponding password (SSH and Windows share).
   Preserve Identity	Select the check box to preserve the appliance's identity rather than take on the identity from the restored backup. This consists of: • Appliance identity • HTTPS configuration • Consolidation configuration Clear the check box to use the identity from the backup.
   Email when complete	Select the check box and enter an email address if you want an email to be sent automatically when restoring the backup is complete.
   Test Connection	When you enter valid connection information, the Test Connection button is enabled. Click this to test the connection to the remote backup server. When the test is successful, and a backup is present, the Remote Backup Details pane displays information on the remote backup.

5. Click Shutdown & Restore to start the restore operation.
   You are prompted for confirmation.
6. Click No to return to the Appliance Backup page. Click Yes to continue and restore the appliance.
   All services are shut down before the restore occurs and a progress screen is displayed.

Device package error on restore

Network device definitions are automatically installed with a TKU. The source and destination appliance must have the same version network device definitions. If you see the following error when restoring, it is important to update the package as described in the error message.

An error was reported while installing the device package.
Please correct the error and install the device package manually by
running (as root): tw_device_import --force -U --oldpackage <rpm file>

The device package is located in the $TIDEWAY/data/installed/tpl directory.

Backing up and restoring a cluster

If you use appliance backup on a cluster, the entire cluster is backed up. If you choose to backup to local filesystem (the On Member option), each cluster member is backed up onto its local filesystem. When you backup a cluster to a remote destination, the appliance backup feature creates a single backup in which each machine's backup is contained in a subdirectory.

You can cancel an in-progress cluster backup, but only from original session on the UI of the machine from which the backup was started.

VMware snapshots and clusters

You can use the VMware snapshot tools to create a snapshot of all of the machines in a cluster. However, all machines must be shut down before starting the snapshot and must remain shut down until all of the snapshots are complete. This enables any internal cluster communication to be completed before the snapshot is created.

Info

The services on all members of the cluster are shutdown for the backup and restarted when the backup is complete.

The UI lists the items which will be backed up.

Destination system time must not be earlier than source when restoring a backup

You must ensure that the current system time on the destination appliance is no earlier than that of the appliance on which the backup was created. If the modification times on the files contained in the backup are later than the system time when they are restored, the backup will hang. To recover at this point you must kill the backup process, correct the time, run tw_restore --fix-interrupted then repeat the restore using the tw_restore command line utility.

Backing up and CMDB synchronization

The backup contains the CMDB synchronization configuration. When a host has significantly changed so that its key has also changed, problems can be caused if a backup is restored before the changed host is rediscovered. In this case, on the next CMDB synchronization, duplicate hosts will be created in the CMDB representing the changed host, and the CIs representing the original hosts will never be deleted. To ensure that no duplicate hosts are created, you can delete and then recreate the BMC.ADDM dataset.

The backup contains the LDAP configuration. If the destination appliance cannot access the LDAP server, you must ensure that a local (non-LDAP) user belonging to the system and public groups is activated and successfully tested on the source appliance before making a backup.

If you choose to exclude the credential vault when backing up an appliance in which CMDB synchronization has been configured, the CMDB Sync page on the restored appliance displays the "This appliance has not been set up for synchronization with the Atrium CMDB" message. Once the Setup form is complete, filter and blackout window settings are restored.

The appliance backup feature replaces the appliance snapshot that was available in previous releases. On upgraded appliances only, if snapshots are still held in the filesystem, a banner and Remove Snapshots button is provided so you can remove the snapshots and release disk space.

To create a backup of the cluster

1. From the Appliance section of the Administration tab, click Backup & Restore.
   The Appliance Backup page is displayed. This has a panel in which you can configure the backup destination. It also shows details of the cluster size, the size of the backup for this member, and details of the contents of the backup.
   
   
2. Enter the details for the backup destination. The fields that can be completed are displayed or hidden depending on the backup type selection. Required fields are indicated with a red asterisk.
   

   Field Name	Details
   Backup Type	Select the destination type from the drop down list. This can be one of the following: • On Members — The backup for each machine in the cluster is written to the $TIDEWAY/var/backup directory on that machine. Only one local (On Members) backup can be stored. • SSH — The backup is written to a remote server over ssh. • Windows Share — The backup is written to a Windows share. You cannot create a backup on a Windows share from a FIPS enabled appliance. The mount operation fails and an error message written to syslog.
   Notes	A free text area in which you can write notes about the backup.
   Directory	The directory into which to write the backup on the remote SSH server. Backups are written into a subdirectory called YYYY-MM-DD_hhmmss_addm_backup _machine_UUID_ inside the specified directory. (SSH only).
   Path	The share name and directory name into which to write the backup on a Windows share. Backups are written into a subdirectory called YYYY-MM-DD_hhmmss_addm_backup _machine_UUID_ inside the specified directory. Path syntax is \\sharename\directoryname, where sharename is the name of the Windows share, and directoryname is the name of the directory into which to write the backup. (Windows share only).
   Host	The hostname or IP address of the remote server onto which to write the backup (SSH).
   Port	The port to which to connect (SSH).
   Username	The username to use to connect to the remote server (SSH and Windows share).
   Password	The corresponding password (SSH and Windows share).
   Verify backup	Select Verify backup to verify (md5) that the files in the backup archive are the same as those on the appliance. Shown only after successfully testing the connection for SSH and Windows share backups.
   Exclude vault	Select Exclude vault to exclude the credential vault from the backup. Appliance UI users are always backed up and restored, regardless of this setting. So, for example, after a restore the password in effect for the system user will be the one from the source appliance. Shown only after successfully testing the connection for SSH and Windows share backups.
   Email when complete	Select Email when complete and enter an email address if you want an email to be sent automatically when the backup task is completed. Shown only after successfully testing the connection for SSH and Windows share backups.
   Test Connection	Click Test Connection to ensure that the remote host can be contacted and that the credentials are valid. Shown only for SSH and Windows share backups.

3. Click Shutdown & Backup to start the cluster backup operation.
   You are prompted for confirmation.
4. Click No to return to the Appliance Backup page. Click Yes to continue and backup the appliance.
   All services are shut down on all members of the cluster for the backup and restarted when the backup is complete. During the backup, a progress window is displayed. A Cancel button is also displayed, but only on the UI for the machine from which the backup was started. The Cancel button is only enabled at the stages of the backup where it is possible to cancel.

To restore a backup to the cluster

1. From the Appliance section of the Administration tab, click Backup & Restore.
   The Appliance Backup page is displayed.
2. Click the Restore Backup tab.
   The Restore Backup tab has a panel in which you can choose the source of the backup, and provides details of the size and contents of the existing local backup.
   
   
3. Enter the details for the backup source. The fields that can be completed are displayed or hidden depending on the backup type selection. Required fields are indicated with a red asterisk.
   

   Field Name	Details
   Backup Type	Select the destination type from the drop down list. This can be one of the following: • On Members — The backup for each machine is read from that machine's $TIDEWAY/var/backup directory. • SSH — The backup is read from a remote server over ssh. • Windows Share — The backup is read from a Windows share.
   Directory	The directory from which to read the backup on the remote server (SSH). Backups are written into a subdirectory called YYYY-MM-DD_hhmmss_addm_backup _machine_UUID_ inside the specified directory. Ensure you specify the subdirectory name too. (SSH only).
   Path	The share name and directory name from which to read the backup on the remote server (Windows share). Backups are written into a subdirectory called YYYY-MM-DD_hhmmss_addm_backup _machine_UUID_ inside the specified directory. Path syntax is \\sharename\directoryname, where sharename is the name of the Windows share, and directoryname is the name of the directory containing the backup. (Windows share only).
   Host	The hostname of the remote server from which to read the backup (SSH).
   Port	The port to which to connect (SSH).
   Username	The username to use to connect to the remote server (SSH and Windows share).
   Password	The corresponding password (SSH and Windows share).
   Preserve Identity	Select the check box to preserve the identity of the current cluster members rather than take on identities from the restored backup. For each member, this consists of: • Appliance identity • HTTPS configuration • Consolidation configuration Clear the check box to use the identity from the backup.
   Email when complete	Select the check box and enter an email address if you want an email to be sent automatically when restoring the backup is complete.
   Test Connection	When you enter valid connection information, the Test Connection button is enabled. Click this to test the connection to the remote backup server. If the test is successful, and a backup is present, the Remote Backup Details pane displays information on the remote backup.

4. Click Shutdown & Restore to start the restore operation.
   You are prompted for confirmation.
5. Click No to return to the Appliance Backup page. Click Yes to continue and restore the cluster.
   All services are shut down on all members of the cluster for the backup and restarted when the backup is complete.

Device package error on restore

Network device definitions are automatically installed with a TKU. The source and destination appliance must have the same version network device definitions. If you see the following error when restoring, it is important to update the package as described in the error message.

An error was reported while installing the device package.
Please correct the error and install the device package manually by
running (as root): tw_device_import --force -U --oldpackage <rpm file>

The device package is located in the $TIDEWAY/data/installed/tpl directory.

Shutting down restarting and maintenance mode

• Restart services — after making changes to some discovery configuration options
• Shut down — to make hardware changes such as adding disks
• Reboot — after upgrading the BMC Atrium Discovery application software or upgrading the operating system

Maintenance mode is a user mode in which the only users permitted are those who are members of the system group. All users who are not members of this group are logged off the appliance and an explanatory message is displayed.

To restart services

You must be logged in as a user who is a member of the system group to shut down the appliance.

1. From the Appliance section of the Administration tab, select Control.
2. On the Control page, click Restart Appliance Services.
3. Confirm the action.

To reboot the appliance

You must be logged in as a user who is a member of the system group to reboot the appliance.

1. From the Appliance section of the Administration tab, select Control.
2. On the Control page, click Reboot Appliance.
3. Confirm the action.

To shut down the appliance

You must be logged in as a user who is a member of the system group to shut down the appliance.

1. From the Appliance section of the Administration tab, select Control.
2. On the Control page, click Shutdown Appliance.
3. Confirm the action.

To put the appliance into maintenance mode

You must be logged in as a user who is a member of the system group to reboot the appliance.

1. From the Appliance section of the Administration tab, select Control.
2. On the Appliance Control page, click Set Maintenance Mode.
3. Confirm the action.
   All users who are not members of this group are logged off. System group users' screens are refreshed and the Quit Maintenance Mode button is displayed.

Maintenance mode is not a single-user mode. If you are performing any tasks that could affect other users (such as appliance backup) you should ensure that you are the only user logged in.
Use the Administration => Security => Active Sessions window to verify this.

When non-system users are logged out, the login banner is displayed with an "under maintenance" message. When logging into an appliance that is in maintenance mode, you should ensure that your work does not interfere with that of other logged in users.

In maintenance mode, a flashing banner is displayed at the top of all pages. The flashing banner is a link to the Appliance Control page.

To leave maintenance mode

To leave maintenance mode, click Quit Maintenance Mode.

Shutting down restarting and maintenance in clusters

• Restart services — after making changes to some discovery configuration options
• Shut down — to make hardware changes such as adding disks
• Reboot — after upgrading the BMC Atrium Discovery application software or upgrading the operating system

Maintenance mode is a user mode in which the only users permitted are those who are members of the system group. All users who are not members of this group are logged off the cluster and an explanatory message is displayed.

Warning

The operations on the Control page in a cluster apply to every machine in the cluster. Individual machines can be controlled from the cluster management page.

To restart cluster services

You must be logged in as a user who is a member of the system group to restart the services on all machines in the cluster.

1. From the Appliance section of the Administration tab, select Control.
2. On the Control page, click Restart Cluster Services.
3. Confirm the action.

To reboot the cluster

You must be logged in as a user who is a member of the system group to reboot all of the machines in the cluster.

1. From the Appliance section of the Administration tab, select Control.
2. On the Control page, click Reboot Cluster.
3. Confirm the action.

To shut down all machines in the cluster

You must be logged in as a user who is a member of the system group to shut down all machines in the cluster.

1. From the Appliance section of the Administration tab, select Control.
2. On the Control page, click Shutdown Cluster.
3. Confirm the action.

To put the cluster into maintenance mode

You must be logged in as a user who is a member of the system group to place the cluster into maintenance mode.

1. From the Appliance section of the Administration tab, select Control.
2. On the Control page, click Set Maintenance Mode.
3. Confirm the action.
   All users who are not members of this group are logged off. System group users' screens are refreshed and the Quit Maintenance Mode button is displayed.

Maintenance mode is not a single-user mode. If you are performing any tasks that could affect other users (such as appliance backup) you should ensure that you are the only user logged in.
Use the Administration => Security => Active Sessions window to verify this.

When non-system users are logged out, the login banner is displayed with an "under maintenance" message. When logging into an appliance that is in maintenance mode, you should ensure that your work does not interfere with that of other logged in users.

In maintenance mode, a flashing banner is displayed at the top of all pages. The flashing banner is a link to the Control page.

To leave maintenance mode

To leave maintenance mode, click Quit Maintenance Mode.

Performing time synchronization

An accurate clock is important for the operation of BMC Atrium Discovery. For example, you need to ensure that scheduled discovery runs occur at the correct time, or reconcile discovery access timestamps between multiple machines.

When the NTP daemon starts, it performs an initial synchronization. The initial synchronization can be cancelled. Thereafter, the NTP daemon maintains the correct time with regular checks

Viewing the Time Synchronization page

To view the Time Synchronization page, from the Appliance section of the Administration tab, click Time Synchronization.

Fields and links

• Status — Displays the status of the time synchronization. It displays No Time Synchronization when both Network Time Protocol and VMware Time Sync are disabled. When you enable VMware Time Sync, the status changes to Using VMware Time Sync. When you enable Network Time protocol, the status changes to Using Network Time Protocol. An additional message Time Synchronization in progress and an option to Cancel Synchronization is displayed when time is first being synchronized using NTP.
• Network Time Protocol — Displays whether the NTP time synchronization is currently Enabled or Disabled.
• NTP Servers — Displays the list of NTP servers configured for time synchronization.
• VMware Time Sync — Displays whether the VMware time synchronization is currently Enabled or Disabled. When Network Time Protocol is enabled, VMware Time Sync gets disabled and this field becomes non-editable. The warning message is displayed as VMware Time Sync will be disabled when NTP is enabled. When Network Time Protocol is disabled, you can optionally re-enable VMware Time Sync.

  It is recommended that you use NTP instead of VMware Tools time synchronization as NTP provides more precise timekeeping on virtual machines. This is explained in VMware's timekeeping best practices for Linux based Virtual Machines which can be found here under the heading VMware Tools time synchronization configuration.

Actions

• Restart NTPD — Select to restart the NTP daemon. The NTP daemon performs the synchronization of the internal time with NTP servers. This option is not displayed when Network Time Protocol is disabled.
• Apply — Select to update the configuration without closing the current page. The respective messages indicating configuration updates are displayed.
• Cancel — Select to cancel changes that have not been applied and navigate back to the Administration page.

To synchronize the time

To synchronize the time of an appliance with the NTP server or across cluster members, perform the following steps on the Time Synchronization page:

1. If the time is not already synchronized, Status displays No Time Synchronization. To synchronize using VMware time sync, enable VMware Time Sync. To synchronize using NTP, enable Network Time Protocol.
2. Enter the details of the NTP server or servers you want to use. You can toggle the server text view between the plain text view and pill view. In the pill view, as you enter text, the UI formats it as a pill (a discrete editable unit) when you enter a space or a comma. According to the text entered, the pill is formatted to represent one of the previous types or presented as invalid. By default, the list is displayed in the pill view.
   • To edit a pill, click the pill body and edit the text.
   • To delete a pill, click the X icon to the right of the pill, or click to edit and delete all of the text.
   • To view the unformatted source text, click the source toggle switch. The source view is useful for copying to a text editor or spreadsheet. Click the source toggle switch again to see the formatted pill view.
   Underneath the entry field is a filter box. Enter text in the filter box to only show matching pills.
3. Select Apply. An option to Cancel Synchronization is displayed when time is being synchronized using NTP. You can either cancel or continue with the synchronization. When time is synchronized, Status is displayed as Using Network Time Protocol.
4. If you enable Network Time Protocol when VMware Time Sync is enabled, the confirmation message is displayed as Enabling NTP will disable VMware Time Sync on any VMware Virtual Machines in the cluster. Are you sure you want to do this?. Click OK to apply the changes.

Configuring the NTP client at the command line

NTP and VMware Tools

If you are using NTP on a BMC Atrium Discovery Virtual Appliance, you should disable the VMware tools time syncing. This is explained in VMware's timekeeping best practices for Linux based Virtual Machines which can be found here under the heading VMware Tools time synchronization configuration.

To configure the NTP client you must be logged in to the command line as the root user.

1. Edit the /etc/ntp.conf file.
2. Search for the lines beginning server.

   server 0.rhel.pool.ntp.org
   server 1.rhel.pool.ntp.org
   server 2.rhel.pool.ntp.org

3. Replace the server entries with the IP address or hostname of the NTP server or servers with which you want to synchronize. For example:

   server ntp.tideway.com
   server 172.17.1.24

4. Save the file.
5. Configure the NTP client service to start at run level 3 when the appliance boots. Enter:

   [root@localhost] # /sbin/chkconfig --levels 3 ntpd on
   [root@localhost] #

6. Check to ensure that this change has been made correctly. Enter the following command and ensure that the output is the same as that shown:

   [root@localhost] # /sbin/chkconfig --list ntpd
   ntpd 0:off 1:off 2:off 3:on 4:off 5:off 6:off
   [root@localhost] #

7. Start the service. Enter:

   [root@localhost] # /sbin/service ntpd start
   Starting ntpd: [ OK ]
   [root@localhost] #

   The NTP client is now running and needs no further attention.

Rebaseline the appliance after configuring the NTP client

If you use appliance baseline, you must rebaseline the appliance after making this change. To rebaseline the appliance, as the tideway user, enter the following command:

/usr/tideway/bin/tw_tripwire_rebaseline

For more information about tripwire and baselining the appliance, see Baseline configuration.

Message - ntpd is not configured to run at run level 5

The message ntpd is not configured to run at run level 5 which is displayed in the appliance baseline window is erroneous. It is displayed when ntpd is running.

Baseline configuration

Checks performed

 Click here to see a comprehensive list of the checks performed

The checks that are performed for each item in the Appliance Baseline Page are described in the following table:

Viewing the high level appliance status

To view the appliance status, click Appliance Status in the dynamic toolbox.

The appliance status list shows the following information:

• Appliance Name — the name of the appliance.
• Appliance Time — the time read from the appliance's internal clock.
• ECA Engines — the number of ECA engines running. The number of ECA engines affects the maximum number of concurrent discovery requests. For more information, see Configuring discovery.
• Summary link— a link to the detailed baseline status information. It is labeled with one of the following high level status messages that describe the overall status of the appliance:
  • No Problems Detected — The status is green. No problems have been detected.
  • Status Information Available — The status is green, but at least one potential problem has been detected which has an information level message.
  • Minor Problems Detected — At least one minor problem has been detected with your appliance.
  • Major Problems Detected — At least one major problem has been detected with your appliance.
  • Critical Problems Detected — At least one critical problem has been detected with your appliance.

Viewing detailed appliance baseline status

To open detailed appliance baseline check results:

• Click Administration in the top navigation bar.
• In the Appliance section, click Baseline status.
  The list of baseline checks, their recent results and available actions will show.
  

Configuring appliance status options

You can configure the appliance baseline options such as the recipients of automatic emails, and the messages to be included.

Before you begin

You must have setup email on the appliance before using this feature. See Setting Up Appliance Mail Settings for more information.

To configure appliance status options:

1. From the Appliance section of the Administration tab, select Baseline Status.
   The Appliance Baseline page can also be accessed by clicking Appliance Status in the dynamic toolbox, and then clicking the link in the drop-down list.

2. Click Configure Options.
   The Appliance Baseline Options displays the following options:

   Field Name	Details
   Email Recipients	The email address or addresses which will be sent an email. This is entered as a single email address or a comma separated list of addresses.
   Email Subject Template	The template used to create the email subject. By default this is: ADDM Baseline: %(appliance_name)s: %(message)s (%(severity)s) Where: •%(appliance_name) — replaced with the name of the appliance. •%(message) — replaced with the passed message or failed message appropriately. •%(severity) — replaced with the severity of the highest severity check that failed, or OK if the checks all passed.
   Passed Message	The message to include in the email when the test is passed.
   Failed Message	The message to include in the email when the test is failed.
   Services To Allow	Select one or more of the following services to remain open if network access is restricted according to the actions configured. Blocking services such as DHCP or ICMPv6 can prevent the appliance from obtaining an address and it could become unreachable. Also, blocking HTTP, HTTPS, and SSH blocks all remote access to the appliance. In this instance you will need to use the system console to fix the problems. • CLUSTER_MANAGER • DATASTORE • DHCP • DHCPv6 • DNS • HTTP • HTTPS • ICMPv6 • LDAP • REASONING • SMTP • SSH For example, where a critical problem is detected, you might choose to limit network access to and from the appliance to HTTP or HTTPS only. To do this, select HTTP and HTTPS, ensure the other services are deselected. When a failure occurs that you have configured to restrict network access, the firewall is raised. When the problem is fixed, the firewall is not lowered. To do this you must restart the firewall.

If the appliance mail server settings are set to an invalid mail server, configuring baseline to send email introduces a delay of approximately three minutes while the appliance attempts to contact the SMTP server, each time baseline is run. Baseline is run hourly by the cluster manager service, and can be run manually by a user.

Configuring actions on changing appliance status

You can configure the actions that will occur when the appliance status changes to critical, major, or minor. Available actions are:

• Send Email
• Restrict Network Access
• Stop Discovery

To configure actions on changing appliance status:

1. From the Appliance section of the Administration tab, select Baseline Status.
   The Appliance Baseline page can also be accessed by clicking Appliance Status in the dynamic toolbox, and then clicking the link in the drop-down list.
2. Click Configure Actions.

3. The is displayed.
   The Appliance Baseline Actions page displays the following options:

   Field Name	Details
   Actions to take on CRITICAL failure	Select the actions to take when a CRITICAL failure occurs. The following options are available: • Send Email • Restrict Network Access • Stop Discovery
   Actions to take on MAJOR failure	Select the actions to take when a MAJOR failure occurs. The following options are available: • Send Email • Restrict Network Access • Stop Discovery
   Actions to take on MINOR failure	Select the actions to take when a MINOR failure occurs. The following options are available: • Send Email • Restrict Network Access • Stop Discovery
   Actions to take on INFO only	Select the actions to take when a INFO failure occurs. The following options are available: • Send Email • Restrict Network Access • Stop Discovery
   Actions to take on SUCCESS	Select the action to take when there are no failures. The following option is available: • Send Email

Tripwire commissioning and configuration

Tripwire is a third-party software tool that monitors a given set of configuration, system, and source files on an appliance. For further information about Tripwire, see: . Tripwire is installed by the kickstart process but is not commissioned. When Tripwire has been commissioned, it is run hourly. You can also run it manually, see Running Tripwire checks manually for more information.

The Tripwire reports are stored in the following directory: /usr/tideway/var/tripwire/report
You must create this directory if it does not exist. As the tideway user, enter the following command:

mkdir -p /usr/tideway/var/tripwire/report

Adding Tripwire configuration to appliance backup

The tripwire configuration is not included in an appliance backup by default. If you want to include it, add the following to the $TIDEWAY/etc/backup_config.xml file.

 <archive name="addm_tripwire_etc" description="Tripwire configuration" src_dir="$TIDEWAY/tripwire/etc" restore="false" clear="false"> <include>*.txt</include> </archive>

The tripwire directory is archived into the backup directory in a file called addm_tripwire_etc.tgz. The archive is not restored when the backup is restored but can be copied manually onto the restored appliance and recommissioned using the Commissioning Tripwire passkeys procedure.

Commissioning Tripwire passkeys

Commissioning Tripwire passkeys is a one-off procedure. You must be able to log in as the root user to complete Tripwire passkeys commissioning.

1. Log in as the root user.
   The default Tripwire policy file is /usr/tideway/etc/twpol.txt.

2. Edit the file and enter the hostname of the appliance (as returned by the hostname command), replacing localhost.
   An excerpt of the file is shown below:

   @@section GLOBAL
   TWROOT="/usr/tideway/tripwire/sbin";
   TWBIN="/usr/tideway/tripwire/sbin";
   TWPOL="/usr/tideway/tripwire/etc";
   TWDB="/usr/tideway/tripwire/var/lib";
   TWSKEY="/usr/tideway/tripwire/etc";
   TWLKEY="/usr/tideway/tripwire/etc";
   TWREPORT="/usr/tideway/var/tripwire/report";
   ARCH="x86_64";
   HOSTNAME="localhost";

3. If you want to monitor any additional files, add the full path to that file to the policy file.
4. If you want to monitor any additional directories, add the full path to that directory to the policy file.
5. Copy the /usr/tideway/etc/twpol.txt file to /usr/tideway/tripwire/etc/twpol.txt, overwriting the existing file.
6. Run the following command which will set up the initial database and passwords allowing changes to the Tripwire configuration
   /usr/tideway/tripwire/sbin/tripwire-setup-keyfiles
7. You are prompted to create a site and a local password. Record these passwords or you will need to reinstall the Tripwire database.
   The local password is required to remove Tripwire violations.
   The site password is required to update the Tripwire policy file.
8. You are prompted to sign the configuration file twcfg.txt and the policy file twpol.txt.

9. Change the ownership and permissions of the /usr/tideway/tripwire/etc/twpol.txt and the /usr/tideway/tripwire/etc/twcfg.txtfiles to the tideway user. Enter the following commands:

   cd /usr/tideway/tripwire/
   chown tideway:tideway etc
   chmod 750 etc
   cd etc
   chown tideway:tideway twcfg.txt twpol.txt
   chmod 640 twcfg.txt twpol.txt

Initializing the tripwire database

Initializing the Tripwire database is a one-off procedure. This procedure should be performed as the tideway user.

1. The Tripwire database must be initialised with the contents of the Tripwire policy file.

2. Run the following command to initialize the Tripwire database:

   sudo /usr/tideway/tripwire/sbin/tripwire --init

3. Run the following command to rebaseline the Tripwire database:

   /usr/tideway/bin/tw_tripwire_rebaseline

   An error is reported as a database backup file is created.

4. Run the following command again to rebaseline the Tripwire database:

   /usr/tideway/bin/tw_tripwire_rebaseline

   This time, no errors are reported as no files have been added. The tripwire database is now initialised and baselined.

Initial appliance baseline configuration

When you have freshly configured the tripwire database, the appliance baseline must be updated to ensure that the correct status is shown in the user interface.

Warning

This will cause all of the appliance baseline checks to be reset. Make sure that all existing baseline failures are addressed.

1. Run /usr/tideway/bin/tw_baseline or click Check Baseline Now in the user interface to execute all the baseline tests.
2. Verify that only tripwire related tests are failing. Trip wire test names end with "tripwire".

3. Update the tripwire report and then update the appliance baseline as follows:

   sudo /usr/tideway/tripwire/sbin/tripwire --check > /usr/tideway/var/tw_tripwire.txt
   /usr/tideway/bin/tw_baseline --rebaseline

The appliance status is updated, and tripwire commissioning is now complete.

Tripwire maintenance

Updating after a violation

When you use the tw_tripwire_rebaseline utility to rebaseline the Tripwire database, you accept that all files that are being monitored are correct. This procedure should be performed as the tideway user. To update the Tripwire database after an error:

1. Check the items that are reported in the violation report and ensure that the reported changes are what you expected.

2. Run the following command:

   /usr/tideway/bin/tw_tripwire_rebaseline

Updating the tripwire policy file

Sometimes you will need to update the Tripwire policy file. This might be due to:
• An EFix being applied
• A full system upgrade
• Appliance relocation or change of IP Address
• Files changing too frequently and creating false positive alerts
Edit /usr/tideway/tripwire/etc/twpol.txt and make the necessary changes. Save the file using the same name.
Clear all violations before updating the Tripwire policy file by rebaselining the Tripwire database. The system must be in a known good state to update the policy database. This procedure should be performed as the tideway user.

1. Run the following command to rebaseline the Tripwire database:

   /usr/tideway/bin/tw_tripwire_rebaseline

2. Run the following command (on one line) to update the Tripwire policy file:

   cd /usr/tideway/tripwire/etc/
   sudo /usr/tideway/tripwire/sbin/tripwire --update-policy twpol.txt

   You will need both the local and site password for this operation.

3. Check that the update has been performed correctly. Enter:

   sudo /usr/tideway/tripwire/sbin/tripwire --check

4. Run the following command to rebaseline the Tripwire database:

   /usr/tideway/bin/tw_tripwire_rebaseline

For more information about the tw_tripwire_rebaseline utility, see tw_tripwire_rebaseline.

Running Tripwire checks manually

By default, Tripwire is run hourly and the output is written to the tw_tripwire.txt file. If a deviation from the baseline has been detected, the tw_tripwire.txt file is updated with the details. The monitor which sets the appliance status in the user interface checks the tw_tripwire.txt file hourly and sets certain restrictions if configured.
If you have rebaselined the Tripwire database, you should run the following commands to ensure that the correct status is shown in the user interface.

sudo /usr/tideway/tripwire/sbin/tripwire --check > /usr/tideway/var/tw_tripwire.txt
/usr/tideway/bin/tw_baseline --rebaseline

The appliance status is updated.

For more information about the tw_baseline utility, see tw_baseline.

Managing standard data

This section explains how to set up and view standard data on the BMC Atrium Discovery system. You must set up details of the specific data required by your IT organization, such as the locations, product groupings, and status values that you use. Known as standard data categories, they are typically set up at initial deployment, but you can change them later if necessary. Additional standard data that you can view from the Setup menu includes the datastore partitions (discrete areas of data in the datastore) and the system taxonomy, which includes details of all the kinds of data object in the BMC Atrium Discovery system and the relationships between them.

Setting up standard data categories

Viewing the standard categories

To view the standard data categories, click the Custom Categories icon in the Model section of the Administration tab. The Custom Categories page is displayed.

Accessing data in the standard categories

1. The Custom Categories page shows tabs representing the categories of data that you can manage.
2. Click the category tab for the data that you want to view, create or edit. The categories are:
   

Each tab for the standard data shows the data types that are configured on the appliance, along with abbreviations, descriptions, whether that type is active or not, arrow keys to reorder the types, whether the type is standard in BMC Atrium Discovery or user defined, and a Delete button to delete that data type. The page also has a New button which enables you to create a new type, depending on the page you are viewing.

Managing attachment categories

BMC Atrium Discovery users can associate any file - such as a document, a spreadsheet, or a diagram - with an object in the BMC Atrium Discovery datastore in order to provide additional information. You can associate an attachment with a Software Instance, Business Application Instance, or Host. Files can be of any type and are not validated in any way by the BMC Atrium Discovery system. Attached files are uploaded to the BMC Atrium Discovery datastore so that they can be accessed easily for disaster recovery purposes.
When you select the Attachment Category page all existing categories are listed. From this page you can create a new category or display an existing one in detail.

Creating a new attachment category

1. From the Custom Categories page, select the Attachment Category tab. The existing attachment categories are displayed.
2. Click the New Attachment Category button. The Create Attachment Category page is displayed.
3. Complete the details of the attachment category.
   

   Field Name	Details
   Name	Name of attachment category.
   Abbreviation	Abbreviation of category name.
   Description	Free-text description of attachment category.
   Active	Yes if this category is currently active, No if it is not active.
   Attachments	Relationship that defines the actual attachment objects in this category. This information is normally set up when the documents are attached to the objects, but you can search for and select one or more Attachment objects.

4. Click Apply to save the attachment category details.

Viewing details of an attachment category

1. From the Custom Categories page, select the Attachment Category tab. The existing attachment categories are displayed.
2. Click an entry to display the View Object page showing full details of the selected category.
   • To delete the selected category, click Delete.
   • To view audit details of the category, click History.

From the Attachment Category you can also view relevant attachments.

Managing product families

Product Families define the groupings of Business Application Instances that are specific to your organization.
When you select the Product Family page all existing families are listed. From this page you can create a new family or display an existing one in detail.

Creating a new product family

1. From the Custom Categories page, select the Families tab. The existing families are displayed.
2. Click New Family button. The Create Family page is displayed.
3. Complete the Attributes and Relationships of the product family.
   

   Field Name	Details
   Name	Name of product family.
   Abbreviation	Abbreviation of product family name.
   Description	Free-text description of product family.
   Active	Yes if this product family is currently active, No if it is not active. Defaults to Yes.
   Standard	Yes if this product family is standard in your organization; No if it is not active. Defaults to Yes.
   Applications in Family	Relationship that defines the Business Applications that are included in this product family. This information is normally set up when you set up the Business Applications, or can be set by a pattern, or you can search for and select one or more applications from here.
   Family Owner	Relationship that defines the ownership of this product family. Search for and select the appropriate Person.

4. Click Apply to save the product family details.

Viewing details of a product family

1. From the Custom Categories page, select the Families tab. The existing families are displayed.
2. Click an entry to display the View Object page showing full details of the selected family.
   • To delete the selected family, click Delete.
   • To view audit details of the family, click History.

Managing lifecycle status values

A lifecycle status object defines a specific status value that can be applied to the IT components managed in your organization. You can assign a status value to each managed element (for instance, each Software Product, Business Application Instance and Host).

You would normally set up all the lifecycle status values appropriate to your organization when you first set up the system, but you can update them at any time.

From the Lifecycle Status page all lifecycle status values are listed. From this page you can create a new lifecycle status or display an existing one in detail.

Creating a new lifecycle status value

1. From the Custom Categories page, select the Lifecycle Status tab. Existing lifecycle status values are displayed.
2. Click New Lifecycle Status button. The Create Lifecycle Status page is displayed.
3. Complete the Attributes and Relationships of the host type.
   

   Field Name	Details
   Name	Name of this lifecycle status value.
   Abbreviation	Abbreviated life-cycle status name.
   Description	Free-text description of life-cycle status.
   Active	Yes if this lifecycle status is currently active, No if it is not active. Defaults to Yes.
   Withdrawn State?	Yes if this lifecycle status value is Withdrawn, No if it is not. Defaults to No.

4. Complete the Relationships of the lifecycle status.
5. Click Apply to save the lifecycle status details.

Viewing details of a lifecycle status

1. From the Custom Categories page, select the Lifecycle Status tab. Existing lifecycle status values are displayed.
2. Click an entry to display the View Object page showing full details of the selected lifecycle status.
   • To delete the selected lifecycle status, click Delete.
   • To view audit details of the lifecycle status, click History.

Managing locations

A Location object defines a physical location in your organization which can be associated with a managed element or a person. You can create various levels of locations - for example, you can model buildings in sites, or rooms on floors.

You would normally set up all the location values appropriate to your organization when you first set up the system, however, you can update them at any time.
If you need to link locations to other nodes, you can do this by means of patterns. A template pattern is available to do this. For information on template patterns, see Pattern templates. For information on modeling your business applications using patterns, see the Tideway web site and click the Community tab and follow the Documentation Resources link.

From the Location page all locations are listed. From this page you can create a new location or display an existing one in detail.

Creating a new location

1. From the Custom Categories page, select the Locations tab. Existing location values are displayed.
2. Click New Location. The Create Location page is displayed.
3. Complete the Attributes and Relationships of the location.
   

   Field Name	Details
   Name	Name of location.
   Abbreviation	Abbreviated name of location.
   Description	Free-text description of location.
   Active	Yes if this location is currently active, No if it is not active. Defaults to Yes.
   Type	Select type of location (Major or Minor) from drop-down list.
   Address	Address of location.
   Phone	Telephone number of this location.
   Subsidiary Locations	Relationship that defines other locations that are subsidiary to this one. Search for and select one or more locations.
   Parent Location	Relationship that defines the parent location of this one. Search for and select the appropriate location.
   Hosts at this Location	Relationship that defines the host systems that are in this location. Can be set by a pattern, or you can search for and select one or more hosts.
   Subnets at this Location	Relationship that defines the subnets that are in this location. Can be set by a pattern, or you can search for and select one or more subnets.
   Applications at this Location	Defines instances of Business Applications in this physical location. Search for and select one or more applications.

4. Click Apply to save the location details.

Viewing details of a location

1. From the Custom Categories page, select the Locations tab. Existing location values are displayed.
2. Click an entry to display the View Object page showing full details of the selected locations.
   • To delete the selected location, click Delete.
   • To view audit details of the location, click History.

Managing organizational units

An Organizational Unit object defines a logical division of your organization, such as a department or a business unit in your organization. You can create various levels of organizational unit - for example, you can model teams in functional areas. Managed elements in your organization (Software Product, Business Application and Host) can be associated with particular organizational units.
From the Organisational Unit page all organizational units are listed. From this page you can create a new organizational unit or display an existing one in detail.

Creating a new organizational unit

1. From the Custom Categories page, select the Organisational Units tab. Existing organizational units are displayed.
2. Click New OrganisationalUnit. The Create Organisational Unit page is displayed.
3. Complete the Attributes and Relationships of the organizational unit.
   

   Field Name	Details
   Name	Name of organizational unit.
   Abbreviation	Abbreviated form of organizational unit name.
   Description	Free-text description of organizational unit.
   Active	Yes if this organizational unit is currently active, No if it is not active. Defaults to Yes.
   Type	Type of organizational unit.
   Subsidiary Units	Relationship that defines other organizational units that are subsidiary to this one. Search for and select one or more organizational units.
   Parent Unit	Relationship that defines the parent organizational units of this one. Search for and select the appropriate organizational unit.

4. Click Apply to save the organizational unit details.

Viewing details of an organizational unit

1. From the Custom Categories page, select the Organisational Units tab. Existing organizational units are displayed.
2. Click an entry to display the View Object page showing full details of the selected organizational unit.
   • To delete the selected organizational unit, click Delete.
   • To view audit details of the organizational unit, click History.

Searching for Organizational Units

To search for Organizational Units with a Generic Search Query, you must use the following:
    SEARCH OrganisationalUnit
Note the 's' instead of 'z' in OrganisationalUnit.

Managing Recovery Time Values

A Recovery Time object defines a valid recovery time that can be applied to the IT components that can be managed in your organization. You can assign a recovery time to each managed element in your organization (Software Product, Business Application and Host).

You would normally set up all the recovery time values appropriate to your organization when you first set up the system, but you can update them at any time.
From the Recovery Time page all recovery time values are listed. From this page you can create a new recovery time or display an existing one in detail.

Creating a new recovery time

1. From the Custom Categories page, select the Recovery Times tab. Existing recovery times are displayed.
2. Click New Recovery Time. The Create Recovery Time page is displayed.
3. Complete the Attributes and Relationships of the recovery time value.
   

   Field Name	Details
   Name	Name of this recovery time value.
   Abbreviation	Abbreviation of recovery time value.
   Description	Free-text description of recovery time value.
   Active	Yes if this recovery time value is currently active, No if it is not active. Defaults to Yes.

4. Click Apply to save the recovery time details.

Viewing details of a recovery time

1. From the Custom Categories page, select the Recovery Times tab. Existing recovery times are displayed.
2. Click an entry to display the View Object page showing full details of the selected recovery time.
   • To delete the selected recovery time, click Delete.
   • To view audit details of the recovery time, click History.

Purging history and destroyed nodes

History

History information about each node and relationship is recorded in the datastore. This audit trail includes details of the changes made, the date and time of the changes and the user who made the changes. You can view the history of each object in the datastore and you can search for and display details of destroyed objects.

In previous releases a purge history script was provided enabling you to purge the history manually. From BMC Atrium Discovery 9.0 this can be done automatically. By default, history is not purged. For information on how to enable this and specify an age above which history data is purged, see configuring model maintenance settings.

To ensure that the historical information is self-consistent, the creation time record for each node is maintained, and all state changes that occurred between the creation time and the purge time are rolled up into a single state change entry.

Destroyed nodes

When a node is destroyed, it is marked as destroyed but remains in the datastore for a fixed period of time, after which it is automatically purged. For information on how to specify a time after which destroyed nodes are purged, see configuring model maintenance settings.

Viewing the system taxonomy

None of this information can be changed from the BMC Atrium Discovery user interface.

Viewing the system taxonomy

1. Click Administration, and then click View Taxonomy.
   All base taxonomy objects are listed, along with the following information:
   • Object Name — the name of the object kind. The superclass of this object is displayed in brackets as a hyperlink.
   • Description — a description of this object type.
   • Subclasses — subclasses of this object type.
   • Attributes — attributes of this object type.
   • Known relationships — known relationships for this object. The object to which this relationship refers is displayed as a hyperlink at the end of the relationship name.

You can download the base taxonomy in XML format. To do this, right-click the appropriate link and select Save Target As....

The Files tab shows the taxonomy files that are installed on the appliance.

Further details of the data model can be found in the BMC Atrium Discovery taxonomy. To view the taxonomy on the BMC Atrium Discovery UI, from the Administration tab, click View Taxonomy. A link to the current, full-size version of the diagrams below is also available in the online documentation.

Taxonomy limitation

The relationships displayed in the taxonomy are not exhaustive. That is, all possible relationships are not displayed in the taxonomy.
For example, the following containment relationships are valid:

• Group:Container:Containment:ContainedItem:SoftwareInstance
• Group:Container:Containment:ContainedItem:Host

The following diagrams show the BMC Atrium Discovery Default Data Model with its different nodes, attributes and relationships between different parts of BMC Atrium Discovery. It is split across the following diagrams:

• Main Diagram—contains all the core entities used in the modeling and discovery of hosts.
• Network and Printer Diagram—contains entities used in the modeling and discovery of network devices and printers.
• Mainframe Diagram—contains entities used in the modeling and discovery of mainframe computers.
• Storage and Load Balancers—contains entities used in the modeling and discovery of storage entities and load balancers.

It is important to note that the model itself is not in separate sections, the separate diagrams exist in order to more clearly convey information.

Main	Network and Printer
Mainframe	Storage and Load Balancers

Color-Code Key

• Inferred nodes and connection links—Blue.
• DDD nodes and connection links—Green.
• Knowledge (Pattern Management) nodes and connection links—Pink.
• Provenance Relationship connection links—Red.
• Auxiliary nodes and connection links—Brown (used internally by BMC Atrium Discovery).

The PNG images are static and represent the latest taxonomy. They do not reflect any on-site changes that might have been made to the taxonomy on your appliance.

Storage and modification of the taxonomy

Taxonomy definitions are configured using xml files which are held in the following directories:

1. /usr/tideway/data/installed/taxonomy/
2. /usr/tideway/data/custom/taxonomy/

The directories are parsed in the order given (installed before custom), and the files contained in these directories are parsed in alphabetical order, with numbers before letters. This order is important as later definitions for the taxonomy override those loaded earlier.

The standard base taxonomy file is contained in /usr/tideway/data/installed/taxonomy/00taxonomy.xml

To add additional details to a node, we recommend using a detail node rather than extending the taxonomy. For more information, see Detail node.

Managing clusters

Any cluster management and configuration is undertaken from the Cluster Management page of any of the members of a cluster. To access the Cluster Management page:

On the Administration tab, click Cluster Management in the Appliance section.

This example page Cluster Management page is from the coordinator's UI and shows a cluster of three machines where all machines are operating normally. 

The cluster management tasks that you can undertake from this page are described in the following topics:

A cluster is not removed, it stops being a cluster when the last member is removed from the coordinator.

Information displayed on the Cluster Management page

This example Cluster Management page shows multiple pending changes. The machine that is leaving the cluster is displayed in Pending Changes as it is waiting to leave, and it is also displayed in Current Members as it has not yet left the cluster. It will only do so when the changes are committed. When the machine is removed, there will be too few members in the cluster to maintain fault tolerance. Consequently, one of the pending changes is disabling fault tolerance.

You can add multiple changes to the Pending Changes section and commit them all at once. Many cluster changes require a rebalance when committed individually, so committing multiple changes at once avoids the need for multiple rebalances.

The Cluster Management page consists of the following basic sections:

• A cluster control section
  • Shutdown Cluster button — shuts down all machines in the cluster.
  • Reboot Cluster button — reboots all of the machines in the cluster.
  • Restart Cluster Services button — restart the services on all machines in the cluster.
  • Enable Maintenance Mode button — places the cluster into maintenance mode. 
    These buttons duplicate the cluster control functionality available on the Control page.
• An overview information section
  • Name — the name of the cluster you are viewing.
  • Alias — an alias for the cluster, primarily intended for use with load balancers. For example, a cluster has members called member1, member2 and member3. DNS is configured to resolve the name cluster100 to a load balancer. The load balancer is configured to share requests to cluster100 with the following hosts: member1, member2 and member3. In this case, the cluster alias is cluster100.
  • Summary — the status of the cluster, whether the cluster is operating normally, or whether any tasks such as rebalancing are in progress, and a measure of the task's progress.
  • Coordinator — whether the current machine is the coordinator or not; if not, a link is provided to the Cluster Management page on the coordinator UI.
  • Fault Tolerance — whether fault tolerance is enabled or not and a button to enable or disable it depending on the current setting.
• The Current Memberspanel which contains rows with detailed information on the machine or machines currently in the cluster and a mass actions drop down which enables you to remove any selected non-coordinator machine. The mass actions drop down is disabled when the cluster is rebalancing. The information on each cluster member includes:
  • Type — Whether the machine is a coordinator or a member.
  • Volume — The amount of free disk space available in the /usr partition.
  • Health — Whether or not there are any issues with the machine.
  • Activity — Whether or not the machine is operating normally.
  • Last Contact — When the machine last responded to communication from the coordinator.

Each row contains an Actions drop down list enabling you to:

• Change Address — change the IP address or hostname used to communicate the the machine. You can use this if a machine is assigned a new IP address, or you need to communicate using its hostname.
• Ping — Pings the machine to ensure that it can be contacted. On a successful ping, the information is refreshed.
• Remove — Remove the non-coordinator machine from the cluster. On selecting this, an entry row is placed in the Pending Changes panel.
• Make coordinator — Makes this machine the coordinator. See Changing the machine that is the coordinator for more information.
• Restart Services — Restarts the services on this machine. This option is only available when fault tolerance is enabled.
• Reboot — Reboots this machine. This option is only available when fault tolerance is enabled.
• Shutdown — Shuts down this machine. This option is only available when fault tolerance is enabled.

Additional sections are displayed as appropriate. For example, the Previous Members panel is only displayed when a machine has been removed from the cluster:

• A results banner with the result of the most recent operation.
• A There are pending cluster changes list which includes buttons to Commit or Discard changes.
• A Pending Changes panel which contains rows with detailed information on the machine or machines in the pending changes list. Each row contains an Actions drop down list enabling you to remove the row from the panel.
• A Previous Members panel which contains rows with detailed information on the machine or machines that have been members of the list. Each row contains an Actions drop down list enabling you to remove the row from the panel.

Cluster overview

Clusters

A group of coordinated BMC Atrium Discovery machines is called a cluster. A cluster consists of two or more BMC Atrium Discovery machines, one of which is in control of the group and is referred to as the coordinator.

All machines are capable of acting as:

• a standalone BMC Atrium Discovery machine
• a member of a cluster
• a cluster coordinator

A cluster is not removed, it stops being a cluster when the last member is removed from the coordinator.

What is a cluster for?

Clusters are designed for organizations with very large IT infrastructures where the performance required is greater than that of a single BMC Atrium Discovery machine. The problem and the solution are described in Big Discovery.

Cluster recommendations

The individual machines that make up a cluster are intended to be in the same location. The data in the datastore is distributed across all machines so there is significant traffic between cluster members. Putting the cluster machines into different locations increases the communication overhead and slows cluster operations. Clustering is designed with the intention that machines are located on the same fast LAN.

Clusters should be built from machines of similar specifications and performance.The datastore is distributed over multiple machines, with each machine holding a roughly equal share of the stored data. The total capacity of the distributed datastore is therefore limited by the machine with the lowest disk capacity allocated to the datastore. The performance of the cluster is affected by the lowest performing machine, but as the discovery workload is shared, the impact is not a limit, but a reduction in overall performance.

Naming of machines in a cluster

The individual machines in a cluster are named according the the following scheme:

• Coordinator – clustername-01
• First member added – clustername-02
• Next member added – clustername-03
• And so on

Cluster communications

Clustered machines communicate on the following TCP ports:

• 25030 — cluster management
• 25031 — datastore communication
• 25032 — reasoning communication

See Firewall Port Summary for more information.

Clusters and JDBC drivers

In a cluster, JDBC drivers for querying databases using integration points that are uploaded through the Administration > JDBC Drivers page are synchronized across the cluster automatically. Where you create a new driver the driver JAR and properties files must be copied manually. You must restart the tideway services on all machines in the cluster before using the drivers.

When replacing a JDBC driver with a newer version through the Administration > JDBC Drivers page on the coordinator UI, the changes are synchronized across the cluster, but you must also restart the tideway services on all machines in the cluster.

Fault tolerance

To prevent data loss when a machine fails, you can store copies of your data on more than one machine. If every bit of data is stored on two different machines, then any one machine can fail with no resultant loss of data. If every bit of data is stored on three machines, then two machines can fail without data loss. The number of copies of the data governs the number of machines that can fail in the cluster before failures cause data loss. The number of copies, or the replication factor, is configured automatically, as follows:

In the case of the fault tolerant cluster of two, the cluster can experience the failure of a machine without losing data. However, the cluster cannot continue to operate as the coordinator can no longer duplicate data the required number of times (the replication factor), in this case two, as there is only one working machine. To make the cluster operational again, either fix the failed machine, or force remove it from the cluster.

If you enable fault tolerance, the cluster will survive the loss of a machine without losing data, or interruption to discovery, and the UI enables you to control the cluster just as before the failure. If the failure was transient, or the machine was repaired, when it returns it starts to process data again, perform discovery, and catch up with the rest of the cluster. If the failure of the machine is permanent, you can use the cluster manager to remove the machine from the cluster and the cluster will redistribute (rebalance) the data over the remaining members. If you replace the machine then a new copy of the data held on the failed machine is copied to the new one.

Fault tolerance works by storing data on multiple machines. As a consequence of having multiple copies, the total storage capacity of the cluster is reduced. Additionally, the overhead of writing, tracking, and searching through multiple copies reduces the overall performance of the cluster, relative to the same cluster with fault tolerance disabled.

Enabling and disabling fault tolerance

Fault tolerance can be enabled when creating a cluster by selecting the fault tolerance checkbox in the create cluster dialog.

To enable fault tolerance in an existing cluster

From the Fault Tolerance section of the cluster manager, click the Enable Fault Tolerance button.

The summary shows the progress of the rebalancing operation. For a large system containing a large amount of data, this may take some time. However, the system remains fully usable throughout.

To disable fault tolerance in an existing cluster

From the Fault Tolerance section of the cluster manager, click the Disable Fault Tolerance button.

The summary shows the progress of the rebalancing operation. For a large system containing a large amount of data, this may take some time. However, the system remains fully usable throughout.

Creating a cluster

To create a cluster:

1. On the Administration tab, click Cluster Management in the Appliance section.
   
   
2. Click Create Cluster.
   The Create Cluster dialog displays.
   
   
3. Enter the following information:
   

   Field name	Details
   Cluster name	The name of the cluster.
   Cluster alias	The Cluster Alias is an optional name for referring to all the machines in the cluster, such as when the machines are accessed through a load balancer. For example, a cluster has members called member1, member2 and member3. DNS is configured to resolve the name cluster100 to a load balancer. The load balancer is configured to share requests to cluster100 with the following hosts: member1, member2 and member3. In this case, the cluster alias is cluster100.
   Coordinator address	The address of the machine to make the coordinator. If you started the creation process from a machine in a non-default state
   Fault tolerance	Select the checkbox to enable fault tolerance. Fault tolerance enables the cluster to continue to operate even when some machines have failed. It works by ensuring that all data is stored on multiple machines. However, total storage capacity and overall performance are reduced as a consequence.
   Member addresses	Enter the IP address or hostname information for the new members to add to the cluster. It can be in one of the following formats: IPv4 address (for example 192.168.1.100). Labeled v4. IPv6 address (for example 2001:500:100:1187:203:baff:fe44:91a0). Labeled v6. Hostname (for example wilkoapp2.tideway.com). Labeled Hn. The addresses or hostnames used must resolve between all cluster members.

4. Click Create to create the cluster.
   The operation is added to the Pending Changes section.
5. Additionally a banner is displayed stating what the pending cluster changes are.
   
   
6. Click Commit Changes to create the cluster.
   The services on the machines shut down, the cluster changes are made, and the services restarted. The Cluster Management page is refreshed showing the progress of the cluster creation.
   
   
7. When the changes are complete, and the machines have restarted, you need to log in again. The Cluster Management page shows the completed cluster. In this example, the cluster is rebalancing in the background, but is fully usable.
   
   

Adding a machine to an existing cluster

To add a machine to an existing cluster

1. On the Administration tab, click Cluster Management in the Appliance section.
   
   
2. On the Cluster Management page, click Add Members.
   The Add Members dialog displays.
   
   
3. Enter the IP address or hostname information for the new members to add to the cluster in the Member Addresses field. It can be in one of the following formats:
   • IPv4 address (for example 192.168.1.100). Labeled v4.
   • IPv6 address (for example 2001:500:100:1187:203:baff:fe44:91a0). Labeled v6.
   • Hostname (for example wilkoapp3.tideway.com). Labeled Hn.
4. Click Add to add the new member to the cluster. This becomes a pending change which needs to be committed before the member joins the cluster.
   
   
5. Click Commit Changes to add the new member to the cluster.
   The Cluster Management page is refreshed showing the progress of the member addition.
   
   The state of the new member is shown as joining. You may see transient errors during this process, for example, the coordinator may attempt to contact a service that has not yet started. These transient errors will clear and can be ignored. If you attempt to log into a BMC Atrium Discovery machine that is joining, an offline page is shown containing progress messages about the joining process.

To reset the configuration of a machine

1. On the Administration tab, click Cluster Management in the Appliance section. Where the machine is in a non-default configuration, the configuration changes are listed in the Summary pane.
   
   
2. Click Reset Configuration to reset the configuration of the machine to defaults.

   Warning

   Resetting the configuration of the machine destroys all data held in that machine.

   The services are shut down and the machine displays the Reset Configuration screen.
   
   

Changing the machine that is the coordinator

• remove the machine currently acting as the coordinator
• shut down the existing coordinator for maintenance
• troubleshoot problems with the coordinator

You can change the machine that is the coordinator using the Cluster Management page. You can make a member the coordinator by selecting Make coordinator from the Actions menu corresponding to the that machine in the Current Members list. You can also make another cluster member the coordinator by selecting Make coordinator from the Actions menu corresponding to the other machine. You can also perform other cluster management tasks from this page.

Changing the machine that is the coordinator

To change the machine that is the coordinator:

1. On the Administration tab, click Cluster Management in the Appliance section.
2. On the Cluster Management page, select Make coordinator from the Actions list next to the cluster member you want to make the coordinator.
   

3. Confirm that you want to make the selected machine a coordinator

   Note

   As a part of this operation all the services on all machines in the cluster are restarted.

An offline page is shown containing progress messages about the changing coordinator process. If you attempt to log into any machine that is a member of the cluster, the same offline page is shown.
 

Changing the coordinator when the coordinator has failed

This procedure can only be executed in a cluster with fault tolerance enabled.

To make a machine the coordinator when the existing coordinator has failed:

1. Access the UI of the machine you want to make the coordinator.
2. On the Administration tab, click Cluster Management in the Appliance section.
3. On the Cluster Management page select Become Coordinator. If the Become Coordinator button is not visible, reload the page in the browser.
   

4. Confirm that you want to make the selected machine the coordinator. This operation takes place immediately after you click OK.

   Warning

   This will forcibly remove all failed machines, including the current Coordinator, and restart Discovery services on all remaining machines in the cluster.

An offline page is shown containing progress messages about the changing coordinator process. If you attempt to log into any machine that is a member of the cluster, the same offline page is shown.

When the operation has completed, the Cluster Management page is refreshed and shows the previous coordinator in the Previous Members section.

Removing a machine from a cluster

You can also perform other cluster management tasks from this page and from the command line utility.

Before removing a machine that is currently a cluster coordinator, you should make another machine the coordinator.

To remove a machine from a cluster

1. On the Administration tab, click Cluster Management in the Appliance section.
2. On the Cluster Management page, either:
   1. Select the check box on the left hand side of the machine row in the Current Members list and select Remove from the Actions drop down.
   2. From the Actions drop down on the cluster machine row in the Current Members list and select Remove.
      The operation is added to the Pending Changes section and a banner is displayed stating what the pending cluster changes are.

      For normal removal
      If a healthy machine becomes unresponsive while the remove operation is pending, you get an alert about the status change and the remove operation fails when submitted. You can still force remove the machine by clicking Force Removal? option next to the alert.
      

      For force removal
      If an unresponsive machine becomes available while the remove operation is pending, you get an alert about the status change and the force removal fails when submitted. You can still remove the machine normally by clicking Remove Normally? option next to the alert.
      

3. Click Commit Changes to remove the machine from the cluster.
   The summary is updated to show the progress of the datastore rebalancing. When this is complete, the machine row is moved to the Previous Members section.
   

   If you used the removed machine's UI to commit the changes, an offline page is shown containing progress messages about the leaving process. If you attempt to log into a BMC Atrium Discovery machine in this state, an offline page is shown containing progress messages about the leaving process.
   
   

A cluster is not removed, it stops being a cluster when the last member is removed from the coordinator.

Changing the address of a machine

To change the address of a machine:

1. On the Administration tab, click Cluster Management in the Appliance section.
2. From the Actions drop down on the cluster machine row in the Current Members list, select Change Address.
   The Change Member Address dialog is displayed.
3. Enter the new IP address or hostname into the Address field using one of the following formats:
   • IPv4 address (for example 192.168.1.100). Labeled v4.
   • IPv6 address (for example 2001:500:100:1187:203:baff:fe44:91a0). Labeled v6.
   • Hostname (for example wilkoapp3.tideway.com). Labeled Hn.
4. If you are changing the address of the machine whose UI you are using, an additional Show Known Addresses link is shown. Click this to show all of the addresses that refer to this machine.
   1. Click on a displayed address to populate the Address field.
5. Click Ok to change the address. This becomes a pending change which needs to be committed before the address is changed.
6. Click Commit Changes to change the address.
   If the hostname or address entered does not refer to the correct machine then the changes are not applied.

Reverting a cluster member into a standalone machine

Warning

This is a recovery operation. It might break the cluster and you might lose data. All data is removed from the machine that is reverted to a standalone machine. If the cluster does not have fault tolerance enabled, or if multiple machines have failed, you will lose all data in the cluster.

You might need to convert a member of the cluster into a standalone machine in the following circumstances:

• When the machine that was unresponsive and was forcibly removed from the cluster becomes available. If you cannot force remove the machine using the UI, you can do so from the command line. See the user example.
• When you cannot recover the whole cluster as most machines in the cluster are permanently down, but you want to reuse the machines.

Use the tw_cluster_control command line tool with the --revert-to-standalone option on the machine you need to make standalone.

Removing all failed machines from the cluster

You can do this by running tw_cluster_control from any running member of the cluster.

1. Log in to the appliance command line as the tideway user.

2. Use tw_cluster_control to remove all failed machines from the cluster. You need to supply the password of the system user. Enter:

   [tideway@wilkoapp1 ~]$ tw_cluster_control --remove-broken
   Password:
   Found 1 broken member: Harness Cluster-03 (wilkoapp3.tideway.com)
   Are you sure you want to make these changes? (y/n) y
   1 member is being removed
   [tideway@wilkoapp1 ~]$

3. Before you can reuse any machine removed from the cluster, you must revert it to a standalone configuration. All data is lost in this process. On the command line of the machine you want to revert, enter:

   tideway@wilkoapp3 ~]$ tw_cluster_control --revert-to-standalone
   Removing this machine from the current cluster
   WARNING: This will delete all data on this cluster member! Do you wish to proceed? (yes/no) yes
   Stopping Cluster Manager service:
   Stopping Cluster Manager service: [ FAILED ]
   Removing cluster configuration
   Starting Cluster Manager service:
   Starting Cluster Manager service: [ OK ]
   Removing appliance configuration
   Deleting datastore
   Starting Security service: [ OK ]
   ...
   ...
   Starting Reasoning service: [ OK ]
   Importing TKU packages: [ Unknown ]
   Writing TKU-Core-2064-02-1-ADDM-10.0+: [ OK ]
   [ TKU-Extended-DB-Discovery-2064-02-1-ADDM-10.0+: [ Unknown ]
   [ TKU-Extended-Middleware-Discovery-2064-02-1-ADDM-10.0+: [ Unknown ]
   [ TKU-System-2064-02-1-ADDM-10.0+: [ Unknown ]
   Activating patterns: [ OK ]
   Starting Tomcat: [ OK ]
   Starting Reports service: [ OK ]
   Starting Application Server service: [ OK ]
   Updating cron tables: [ OK ]
   Updating baseline: [ OK ]
   Finished removing cluster configuration
   [tideway@wilkoapp3 ~]$ 

Shutting down and restarting machines in a cluster

• Restart services
• Reboot
• Shut down
  For all of these options on individual machines, the cluster must have fault tolerance enabled.

Warning

The control operations on the Cluster Management page apply to every machine in the cluster. Individual machines are controlled from the Actions drop down.

To restart services on a machine in a cluster

You must be logged in as a user who is a member of the system group to restart the services on a machine in a cluster.

1. On the Cluster Management page, select Restart Cluster Services from the Actions drop down.
2. Confirm the action.

To reboot a machine in a cluster

You must be logged in as a user who is a member of the system group to reboot a machine in a cluster.

1. On the Cluster Management page, click Reboot from the Actions drop down.
2. Confirm the action.

To shut down a machine in a cluster

You must be logged in as a user who is a member of the system group to shut down a machine in a cluster.

1. On the Cluster Management page, select Shutdown from the Actions drop down.
2. Confirm the action.

Shutting down and restarting clusters

• Restart services — after making changes to some discovery configuration options
• Shut down — to make hardware changes such as adding disks
• Reboot — after upgrading the BMC Atrium Discovery application software or upgrading the operating system

This functionality is also available in the Appliance Control page.

Maintenance mode is a user mode in which the only users permitted are those who are members of the system group. All users who are not members of this group are logged off the cluster and an explanatory message is displayed.

Note

The control buttons at the top of the Cluster Management page apply to every machine in the cluster. Individual machines can be controlled from the Actions drop down page.

To shut down all machines in the cluster

You must be logged in as a user who is a member of the system group to shut down all machines in the cluster.

1. On the Cluster Management page, click Shutdown Cluster.
2. Confirm the action.

To reboot all machines in the cluster

You must be logged in as a user who is a member of the system group to reboot all of the machines in the cluster.

1. On the Cluster Management page, click Reboot Cluster.
2. Confirm the action.

To restart services on all machines in the cluster

You must be logged in as a user who is a member of the system group to restart the services on all machines in the cluster.

1. On the Cluster Management page, click Restart Cluster Services.
2. Confirm the action.

To put the cluster into maintenance mode

You must be logged in as a user who is a member of the system group to place the cluster into maintenance mode.

1. On the Cluster Management page, click Enable Maintenance Mode.
2. Confirm the action.
   All users who are not members of this group are logged off. System group users' screens are refreshed and the Quit Maintenance Mode button is displayed.

Maintenance mode is not a single-user mode. If you are performing any tasks that could affect other users (such as appliance backup) you should ensure that you are the only user logged in.
Use the Administration => Security => Active Sessions window to verify this.

When non-system users are logged out, the login banner is displayed with an "under maintenance" message. When logging into an appliance that is in maintenance mode, you should ensure that your work does not interfere with that of other logged in users.

In maintenance mode, a flashing banner is displayed at the top of all pages. The flashing banner is a link to the Control page.

To take the cluster out of maintenance mode

To leave maintenance mode, click Quit Maintenance Mode.

Consolidation

IP address ranges

Although consolidation can be used to scan a firewalled environment, it is essential that the IP address ranges scanned by each scanner belong to the same IP address space. That is, if two scanners scan the same address, they must both reach the same device. If the IP address spaces are not consistent across all the scanners, information on the consolidator can be missing or incomplete.

This restriction only applies to the addresses scanned by the scanners – if discovery targets possess other IP addresses, there is no need for them to belong to a consistent IP address space.

Consolidator — The main purpose of the consolidator is to report on data consolidated from a number of other scanners. A consolidator can also be used to perform discovery in its own right.
Scanner — The scanner appliance also operates as a normal appliance. The only difference is that it constantly sends discovery data to the consolidator. After setting up, this process is transparent to the user. A scanner must request and be approved on a consolidator appliance before it can send any data to the consolidator. This is described in Approving or rejecting a scanner request. A scanner can send consolidation data to more than one consolidator.

On the consolidator user interface, the Currently Processing Runs tab shows any local scans and any consolidation runs in progress. The Currently Processing Runs is described in The Discovery Status page. The tab is shown below:

Restrictions

BMC Atrium Discovery version 9.0 introduced major changes in the data model. Consequently there is no support for consolidation to versions 9.0 and later from pre-9.0 appliances.

The consolidator's service pack release must be the same or greater than the scanner. This is checked when you test the scanner-consolidator connection and when the scanner periodically checks that the consolidator is still accessible.

• A 9.0 consolidator can only accept data from a 9.0 scanner
• A 10.0 consolidator can accept data from a 9.0 and 10.0 scanner
• A 10.1 consolidator can accept data from a 9.0, 10.0, and 10.1 scanner

If you try to consolidate to an earlier version, warning messages are shown in the UI.

What is consolidated?

The consolidated data is the BMC Atrium Discovery Directly Discovered Data (DDD) nodes including the data collected by the patterns. The data inferred by the scanners, for example, Software Instance nodes, is not consolidated, but the consolidator will infer it again (based on its pattern configuration).

TKU release, patterns, CSV imports and consolidation

The TKU release package and custom patterns that are loaded on the scanning and consolidators must be the same in order to infer the same data, for example, Software Instance nodes. This is not enforced in any way by the system.
The data imported via CSV in a scanner will not be consolidated. It has to be imported into all other appliances too.

Missing information when patterns run commands on other hosts

When a host is discovered and patterns are triggered which run commands on a second host, the DDD on both hosts is updated. When the original host is consolidated, the DDD on the second host is not available to the patterns that trigger on the consolidator. When the second host is consolidated, the DDD created on it when discovering the first host is not included. Consequently the consolidator will always report that the information from the second host is unavailable. The error "Request for information not part of the consolidated data" will be reported in the consolidated DiscoveryAccess. This can lead to missing nodes (licensing Detail, SoftwareComponents, and so on) and relationships on the consolidator. To work around this behavior, scan the original host from the consolidator.

Configuring consolidation

Configuring consolidation is a two step procedure. Initially the appliance which is to be the consolidator must be set as a consolidator, and then one or more scanners register with the appliance. To configure consolidation you need the permissions detailed in Consolidation Permissions.

Consolidation and clusters

When using standalone scanners to consolidate to a cluster, use the IP address of the coordinator (displayed in the cluster UI) as the consolidation target. If you subsequently change the coordinator of the target cluster, you must update the consolidation configuration on the scanner.

When using a cluster as a scanner, you can configure consolidation using any member UI, but only the coordinator of the cluster sends information to the consolidator. The coordinator of the target cluster must be specified as the consolidation target.

Firewalls and consolidation

Consolidation uses port 25032 to communicate. The scanner must be able to connect to port 25032 on the consolidator. You must configure any firewalls between scanners and consolidators to allow this traffic. For clusters that act as scanners you must open port 25032 on all members. For clusters that act as consolidators you must open port 25032 on the coordinator, but if you change the coordinator you must open port 25032 on the new coordinator.

To set an appliance as a consolidator

1. From the Discovery section of the Administration tab, select Discovery Consolidation.
   The Consolidation page is displayed.
   You cannot use consolidation if the appliance is named Discovery_Appliance. A warning is displayed including a link to where you can change the appliance name.
2. In the Consolidation page, click Set as Consolidation Appliance.
   The appliance is now configured as a consolidator.

To set an appliance as a scanner

1. From the Discovery section of the Administration tab, select Discovery Consolidation.

2. In the Consolidation page, click Set as Scanning Appliance.
   This dialog enables you to specify a Consolidation target. Enter or edit the following information in the dialog:

   Field Name	Details
   Name	The name of the scanner. Names must be unique in the consolidation network and you cannot consolidate a scanner with the default name, Discovery_Appliance. The name is taken from the Administration => Appliance Configuration => Identification page. See Initial configuration. A change link is provided which displays the Identification page. In the identification page you can change the name of the appliance. You can only consolidate appliances which have unique names.
   Consolidation Appliance	The address of the consolidator. This can be specified as one of the following: Hostname or FQDN IPv4 or IPv6 address You can supply credentials for the consolidation appliance in this dialog. If you supply valid credentials here, the scanner is approved automatically.
   Username	The user name for a user on the consolidator. This user must have appropriate permissions to approve the connection of the scanner to the consolidator.
   Password	The password for the user on the consolidator.

If the target consolidator is an earlier version that the scanner, you are warned that the consolidator version is too old.

If you supplied valid credentials for automatic approval on the consolidator, then the scanner is now configured.

To add an additional consolidator

A scanner can send consolidation data to more than one consolidator. To do so:

1. Click the Add new Consolidation Appliance button.
   The Add New Consolidation Appliance dialog is displayed. This is described above.
2. Enter the details of the consolidator and, if required, the username and password for automatic approval.
3. Click submit to apply the changes.

Approving or rejecting a scanner request

After a request (without automatic approval) has been made from a scanner, it requires approval on the consolidator.

To approve or reject a pending scanner request:

1. From the Administration tab on the consolidator, select Discovery Consolidation from the Discovery section.
   In the following example, the "de-32.tideway.com" appliance has requested to become a scanner.
   
   
   • To accept the appliance connection, click Approve.
   • To reject the request, click Reject. When you do this, the connection is deleted from the consolidator and when no connections remain the scanner reverts back to a non-consolidated machine.

When consolidation is running

Once consolidation has been set up, whatever scanning takes place on the scanner is automatically sent to the consolidator as soon as possible after the scan of an endpoint is complete. On the consolidator, runs are displayed that are marked specifically as consolidation runs and can be viewed from the Discovery Status page.

Discovery must be running on the consolidator for consolidation to take place. If Discovery is not running, the consolidator will refuse to accept data from the scanner. The scanner will attempt to resend data later. Also, if Discovery is stopped on the consolidator, it will stop consolidating any data it has already received.

Canceling consolidating discovery runs

You can cancel a consolidating discovery run from the scanner or from the consolidator. Where possible you should always cancel the discovery run on the scanner. This is done by selecting the discovery run on the Discovery Status page of the scanner and clicking Cancel Runs.

Canceling the discovery run at the scanner enables the consolidator to finish receiving data from the scanner. This stops the scan rather than the consolidation so that the two appliances' data remains consistent.

Canceling a consolidation Run on the consolidator stops the consolidation though the scan continues on the scanner. This leads to inconsistencies between the data on the two appliances. Where possible you should always stop the scan on the scanner and allow the consolidation to run to completion.

If you must cancel a consolidation run from the consolidator, you can do so by selecting the discovery run on the Discovery Status page of the consolidator and clicking Cancel Runs. If there are problems canceling the consolidation run, a status message is displayed.

CMDB synchronization

Starting from 2021-02-27_13-08-06_Technology Knowledge Update 2014-Jul-1, the CMDB sync mappings have been enhanced with two new capabilities:

Support for HasImpact population

Relationships in Atrium CMDB can be marked as being “impactful”, by setting the HasImpact attribute to Yes and the ImpactDirection attribute to a suitable value. A new CMDB sync data model means that BMC Atrium Discovery can now set these impact attributes directly, rather than relying on Atrium CMDB’s impact normalization rules. To enable the new data model:

1. In Atrium CMDB, disable Impact Normalization for the ADDM dataset, in the Normalization Console Configuration Editor
2. When adding or editing a connection in BMC Atrium Discovery, ensure the Data Model setting labelled "CMDB 7.6.03 and later (with impact attributes)" is selected (this is the default).

This new data model will become the default in future releases of BMC Atrium Discovery.

Simple static application models

BMC Atrium Discovery allows you define dynamic automatically-updating application models, using Collaborative Application Mapping and related features. That leads to robust comprehensive application models, but it does require time to investigate the application and define a suitable set of patterns. In some circumstances it is useful simply to manually group some hosts or software instances together to create a “static” application model. Such models are of course not automatically updated, but they are extremely quick and easy to define.

To define a static application model, add Hosts or SoftwareInstances to a group in BMC Atrium Discovery, and give the group a name that starts with “StaticApp:”, in exactly that form. Do not use sub-groups. That causes the creation of a BMC_Application CI in Atrium CMDB, named after the group. For example, a group named “StaticApp: Example Application” results in a BMC_Application CI with name “Example Application”.

Data model mapping

The BMC Atrium Discovery data model (Discovery model) is different from the Common Data Model (CDM) used in the CMDB, so the synchronization mechanism is responsible for transforming the required information from one data model to the other. The Discovery model is known as the source model, and the CDM is referred to as the target model.

Both models are graph models, meaning that they represent data as nodes connected to each other with relationships. Synchronization operates on portions of the full graph known as subgraphs. A subgraph contains a root node (such as a host computer), plus all the related nodes that belong to it (such as interface information, software information, and so on), referred to as its components. Some nodes can be shared, meaning that they belong to more than one subgraph. For example, the node representing a subnet is shared by all the host computers on that subnet.

The mapping between the Discovery model and the CDM is defined in syncmapping definitions within TPL files.

The Default CDM Mapping provides a comprehensive mapping from the Discovery model to a best-practices CDM model. If you have added custom nodes to Discovery they are not exported automatically by the default CDM mapping, instead, you will have to create additional mapping definitions within TPL files.

Supported CMDB versions

Deprecated versions of CMDB synchronization

BMC Atrium Discovery version 8.1 introduced the first automatic integration using CMDB synchronization. At that time the previously used method (the Atrium CMDB adapter) was deprecated. In BMC Atrium Discovery 9.0, the Atrium CMDB adapter was removed.

Synchronization stages

Synchronization occurs in the following stages:

1. A root source node is chosen for synchronization. The root node kinds are Host, NetworkDevice, MFPart, Printer and, SNMPManagedDevice corresponding to the main kinds of device that can be discovered. The list of possible root nodes is fixed and cannot be altered in the Syncmappings.
2. The source subgraph is populated by retrieving all the relevant data from the Discovery datastore.
3. The source subgraph is transformed into a target subgraph, centered around a target root node.
4. The target subgraph is compared with the corresponding subgraph stored in the CMDB.
5. The CMDB is updated (by creating, updating and (soft) deleting CIs and relationships) so that the stored subgraph matches the target subgraph.

Note

If any changes are made to the CDM (for example, adding attributes), you cannot synchronize to those attributes until the Tideway service has been restarted. After the tideway service starts, the CDM is read and all customized classes and attributes are available for CMDB synchronization.

Initial configuration

The following steps are required to set up CMDB synchronization:

To perform synchronization

Synchronization can be configured to run in a continuous mode, meaning that as soon as BMC Atrium Discovery completes its scan of a device, the data corresponding to it is queued for synchronization with the CMDB. Alternatively, synchronization can be launched manually for one or more devices from within the browsing interface.

To prevent synchronization at certain times

Typically, synchronization can occur at any time. However, synchronization can place a substantial load on the CMDB, so it might be necessary to prevent synchronization from occurring at times the CMDB will be used heavily. This can be achieved by configuring Configuring CMDB Sync blackout windows.

To filter synchronization data

By default, all details about all devices are synchronized to the CMDB. In some situations, it might be useful to only synchronize a subset of the data. After each of the first three synchronization stages, the data can be filtered to affect the data that finally reaches the CMDB.

1. Filtering the root device node
2. Filtering the synchronized components
3. Filtering the CMDB CI classes

Preparing BMC Atrium CMDB for synchronization

At the time of its release, integration of the current version of BMC Atrium Discovery was supported with the following versions of BMC Atrium CMDB:

• 8.1.02
• 8.1.01
• 8.1.00
• 8.0.00
• 7.6.04

For more information, check the BMC Solution and Product Availability and Compatibility utility (SPAC) (support login required).

Before you begin

Before you can synchronize data to a supported BMC Atrium CMDB version, you must complete the following required tasks in the given order:

Integrating with earlier versions of BMC Atrium CMDB

BMC Atrium CMDB versions earlier than 7.6.04 are no longer supported and are not recommended for use. Synchronizing data to these earlier versions required you to complete some additional tasks. For more information, see the BMC Atrium Discovery 8.3 documentation.

1. Create the BMC.ADDM dataset: The BMC.ADDM dataset must be manually created in the CMDB before a synchronization is attempted.
2. Create the Job to merge the BMC.ADDM dataset with BMC.ASSET: After the BMC.ADDM dataset has been created, you must then create the job to reconcile it with the BMC.ASSET dataset.
3. Check the BMC.ADDM dataset configuration: When using ITSM 7.0 with a backwards compatibility patch, you also need to ensure that the BMC.ADDM dataset is trusted.

After completing the preceding tasks, you can start synchronizing BMC Atrium Discovery data to BMC Atrium CMDB.

Performance considerations

To obtain the maximum synchronization performance when using CMDB synchronization with BMC Atrium Discovery version 8.3.00 and later, you should consider tuning the database which BMC Atrium CMDB (or BMC Remedy AR System) is using. For more information, see the following documentation corresponding to your product version:

To create the Identification, Merge and Purge Job

BMC Atrium Discovery exports its data to a staging dataset in BMC Atrium CMDB. The content of this dataset should then be reconciled into the BMC.ASSET dataset. To accomplish this, a new Job must be added in the BMC Atrium CMDB Reconciliation Console. It is recommended that you create the Identification, Merge and Purge Job on the primary AR System server.

To add the Identification, Merge and Purge Job

1. From the Mid Tier, Open BMC Atrium Core Console > Applications > Reconciliation Application.
2. Select the Create Standard Identification and Merge Job Icon
3. Give the job a meaningful name (for example, "BMC ADDM - Identification, Merge and Purge").
4. Set the Source Dataset to be "BMC.ADDM".
5. After the job is Created, select BMC ADDM - Identification, Merge and Purge Job.
6. Click the Edit Job icon.
7. From the Job Editor window, in the Activities pane, select the New tab.
8. In the New Activity pane, select Type as 'Purge', Sequence as '700' and Name as BMC ADDM - Purge.
9. In the Datasets option, select Datasets as BMC.ADDM.
10. Click Done.
11. Click Save in the Job Editor.

Note

The recommended practice is to create a precedence group that specifies a precedence for the BMC.ADDM dataset. The value depends on your relative preference for data populated by BMC Atrium Discovery and other data providers to the CMDB. For more information about how precedence groups are configured, see the following documentation corresponding to your product version:

To check the BMC.ADDM dataset configuration

When using BMC Remedy ITSM 7.0 with a backward compatibility patch, you also need to ensure that the BMC.ADDM dataset is trusted. To do this:

1. Access the Home page from BMC Remedy User or a browser.
2. Access the Application Administration Console.
3. Go to the Custom Configuration page.
4. From Foundation, select Products / Operational Catalogs.
5. Select Trusted Datasets for Product Catalog and click Open.
6. Select the BMC.ADDM dataset for Dataset Name.
7. Click Save.

To prepare synchronization to another CMDB

There might be occasions where you have already synchronized data to a CMDB, and you want to push data to a different CMDB. For example, if you are migrating from a development to a production environment for your CMDB, you might want to populate your new CMDB with fresh inventory data, independent of previous experiments you might have performed in the development instance. To synchronize the data to the new CMDB, perform the following steps using continuous CMDB synchronization.

1. Stop any discovery runs.
2. Stop continuous synchronization (wait for it to finish processing the queue).
3. Change your configuration to the new CMDB dataset (see the tasks to complete before you begin).
4. From the CMDB Sync > Configuration tab, click Test Connection to the new CMDB dataset.
   Ensure that the connection is successful before proceeding.
5. From the Infrastructure > Hosts page, send one or two hosts to the CMDB, and select Actions > Sync with CMDB.
6. Start continuous synchronization.
7. Restart your discovery runs.

The data is inserted into the new CMDB dataset as your Discovery jobs are executed. BMC Atrium Discovery detects that the data does not exist, and then inserts the data.

To synchronize data from multiple BMC providers to the CMDB

When multiple BMC providers synchronize data to the CMDB (such as BMC Atrium Discovery or BMC BladeLogic), there is the possibility that BMC_OperatingSystem instances might not be merged during reconciliation.

BMC Atrium Discovery is an agentless discovery tool and, as such, it might retrieve slightly different information than an agent-based product (for example, "SunOS" or "Solaris" for the same server). To eliminate this problem, you can add a fallback reconciliation rule based on the ClassId for BMC_OperatingSystem instances.

Synchronizing functional components

Setting up the CMDB synchronization connection

Before you begin

Before you can synchronize BMC Atrium CMDB with BMC Atrium Discovery, you must prepare the CMDB.

CMDB synchronization and clusters

When configuring CMDB synchronization from a cluster, you can use any machine for the initial configuration and subsequent updates. All data synchronized to BMC Atrium CMDB is sent from the coordinator.

To set up CMDB synchronization

1. From the Model section of the Administration page, click CMDB Sync.
   If no CMDB Sync has been configured, a banner displays stating that the appliance has not been set up for CMDB Sync. 
   

   If you want to update the existing CMDB synchronization configuration, it is recommended that you stop discovery, stop continuous CMDB synchronization, and wait until processing of the queue is completed before updating the configuration fields on the CMDB Sync page.

2. Click the Configuration tab to configure a default export to your Atrium server.
   Click Edit to change settings on the Configuration page.
   Type the following information on the CMDB Sync page:

   Atrium CMDB Server	The BMC Atrium CMDB host. This can be specified as one of the following: Hostname or FQDN IPv4 or IPv6 address If BMC Atrium CMDB is installed with an AR System server group, you must enter the following based on the high availability status of the server group: (If high availability is configured) The host name or IP address of the load balancer. (If high availability is not configured) The host name or IP address of the primary AR System Server. To learn about the AR System server groups configuration, see the corresponding documentation for versions 8.1, 8.0, and 7.6.04. To learn about the AR System server high availability configuration and hardware load balancer, see the corresponding documentation for versions 8.1, 8.0, and 7.6.04.
   Specify TCP Port	The communication port. BMC Atrium CMDB typically uses a portmapper service to automatically choose a suitable communication port. If this is not appropriate in your environment, you can configure the CMDB to listen on a specific port, and then specify that port in this field.
   User name	The user name of the BMC Atrium CMDB user that is at least a member of a group having the CMDB Data Change All role. If in doubt, create a dedicated discovery user with the same profile as the standard CMDB Demo user. The CMDB Demo user permissions at least are required for multitenancy to work. A user is not permitted to connect to BMC Atrium CMDB from a second IP address within 4 hours of their last activity at the first IP address. For a failover scenario, you could also create a second discovery user to connect from the failover appliance.
   Set Password	The password of the CMDB user (or blank if the user has no password).
   Dataset ID	The ID of the dataset used for Discovery data. The default is BMC.ADDM.
   Data model	The data model for your CMDB. Different versions of the CMDB have different data models, so the data from BMC Atrium Discovery must be transformed differently according to the CMDB version. The preferred value for Data model is CMDB 7.6.03 and later (with impact attributes).  Choose the correct data model from the menu. If you choose an incorrect value, you might encounter errors during synchronization. Data model value CMDB versions Effect CMDB 7.6.03 and later (with impact attributes) 7.6.03 and later HasImpact and ImpactDirection attributes are set as appropriate. In Atrium CMDB, make sure Impact Normalization is disabled for the ADDM dataset, in the Normalization Console Configuration Editor. CMDB 7.6.03 and later (with impact relationships) 7.6.03 and later Only to be used with legacy BMC Service Impact Management version 7.4. BMC_Impact relationships with Name “ImpactOnly” are created. See warning below CMDB 7.6.03 and later (no impact details) 7.6.03 and later No impact details are set by ADDM. They may be set by Impact Normalization in the CMDB CMDB 7.6 (deprecated) 7.6 before 7.6.03 BMC_Impact relationships with name “IMPACT” are created CMDB 7.5 (deprecated) 7.5 BMC_Impact relationships with name “IMPACT” are created Do not use mixed modes with CMDB 7.6.03 and later (with impact relationships) If you specify the CMDB 7.6.03 and later (with impact relationships) option, CMDB synchronization creates Impact relationships as a relation (IaaR). Normalization in the CMDB using the default setting of auto impact creates Impact relationships as an attribute (IaaA). You must change your CMDB Normalization setting so that it does not use auto impact when the Data model is set to CMDB 7.6.03 and later (with impact relationships) in BMC Atrium Discovery. Do not use a mixed mode of (IaaA) and (IaaR).
   Sync threads	CMDB synchronization can simultaneously process data from multiple control threads (the default is one). Depending on the configuration of your CMDB and the characteristics of the network between BMC Atrium Discovery and the CMDB, the rate at which data is synchronized to the CMDB might be increased by choosing a non-default number of Sync threads. The number of Sync threads in BMC Atrium Discovery must be fewer than the number of Fast Threads defined in the CMDB, and fewer than the value of the Next-Id-Block-Size parameter in the CMDB. Increasing the number of Sync Threads should only be undertaken with the assistance of your AR and CMDB System Architects. Note: each root CI (Host, NetworkDevice, Printer, SNMPManagedDevice, MFPart) is processed by a single thread. If you are processing several root CI's, multiple threads are used. However if you are processing a single root CI, only one thread is used, even if additional threads are configured.
   Multitenancy	Multitenancy support. Selecting this check box enables you to choose a company name from the Default Company menu, which assigns that company name to a discovery run during an initial scan, and assigns that company name to the Company attribute to the CIs created in BMC Atrium CMDB. The CMDB Demo user permissions at least are required for multitenancy to work.

3. Click Apply.
    

4. If necessary, click Edit to change configuration settings.

5. From the CMDB Sync > Configuration tab, click Test Connection to the new CMDB dataset.
   

   Ensure that the connection is successful before proceeding.

6. If you are setting up multitenancy, click Lookup Companies to populate the Companies list.

7. Click Manage Blackout Windows to configure times at which no synchronization should occur with the CMDB.
   This is described in Configuring CMDB Sync blackout windows.

To display status

Comprehensive status information is also available on the CMDB Sync page, which displays a summary of the number of devices that are queued, which devices are currently processing, and those that have recently completed synchronization. If any errors occur during synchronization, error information is shown towards the bottom of the page.

1. To display the status window, click the Status tab.
   The status window automatically refreshes to display up-to-date information.
   Fields in the Most recent synchronized devices section
   

   Time	The time at which the synchronization started.
   Label	The device name.
   Kind	The CMDB device kind.
   Attributes written	The total number of attributes which have been written or updated on all nodes which belong to that particular device. Where the number of attributes written or updated is fewer than the possible total it means that not all attributes have been updated. A scenario in which this might occur is where a node is shared between two root nodes, such as an IPConnectivitySubnet node. The first time it is created, its attributes are set. When another root node that is also linked is created, the shared node's attributes are counted as candidates for writing or updating, but are already set so are not updated.
   Configuration items	The number of configuration items considered, inserted, updated or deleted for this device. Where the number of CIs considered is greater than the number inserted, the number of attributes written (see Attributes written above) is fewer than the possible total.
   Relationships	The number of relationships considered, inserted, updated or deleted for this device. Where the number of relationships considered is greater than the number inserted, the number of attributes written (see Attributes written above) is fewer than the possible total.

2. Click Show all in the Devices that failed last CMDB sync field to show a list view of devices that failed to synchronize.

Multitenancy

The company name is assigned to the cdm_company attribute on the Discovery Run node. This is mapped onto CMDB CIs created as a result of that scan and assigned to the Company attribute.

Important considerations when using multitenancy

Multitenancy obtains company names from BMC Remedy ITSM through BMC Atrium CMDB. Therefore, to obtain company names, you must have a working CMDB Sync and BMC Remedy ITSM must be installed. You do not need to have performed a synchronization, but the connection must be configured and working, with a user with at least CMDB Demo user permissions. Once this is set up, the Lookup Companies button on the CMDB Sync is displayed.

The company list on the appliance is not automatically refreshed from the BMC Atrium CMDB. If you do not see a company that you are expecting to see, refresh the list by clicking Lookup Companies on the CMDB Sync page. Similarly, if you add a new company name to BMC Remedy ITSM, you must refresh the list by clicking Lookup Companies.

If there is no company information available from ITSM, the Default Company does not contain any company names. Instead, it displays No Company.

Multitenancy in Consolidation deployments

In consolidating systems with multiple Scanning appliances feeding a Consolidation appliance, it is the Consolidation appliance that requires the CMDB sync connection. Scanning appliances should not be configured to synchronize with the CMDB, they should send data to the Consolidation appliance. As part of the communication that occurs between associated Consolidation and Scanning appliances, the company list on the Consolidation appliance is automatically populated to the Scanning appliances. However, the list on the consolidating appliance is not automatically refreshed from the BMC Atrium CMDB.

When you are working on a Scanning appliance, and you do not see a company that you are expecting to, you must log onto the Consolidation appliance and refresh the list on the Consolidation appliance by clicking Lookup Companies on the CMDB Sync page.

Filtering the root device node

After configuring a connection to the CMDB, the default view of the CMDB Sync page displays the Device Filter tab.
This tab uses the same three pane selection tool used in the Query Builder. It enables you to construct a filter which pushes just those devices with matching attribute values to the CMDB. The filter can be on simple attribute values, or attributes of a destination node reached by following a relationship, or logical combinations of the same. The filters are shown in map form in the filter builder.

The three pane selection tool enables you to select an attribute to filter on, or follow relationships to other nodes from which you can select attributes to filter on. Relationships are displayed with a following right arrow (►). Scroll down the left hand pane and select the attribute that you require.

 Click here for a more comprehensive guide to using the three pane selector

Search in the left hand pane of the three pane selection tool for the attribute that you wish to select. You can scroll through the list or use the lookup tool beneath each pane. When you enter text into the lookup tool a drop down list of matches is displayed, from which you can select the attribute or relationship to use.

• Clicking an attribute, for example Discovered OS Class, adds a Host: Discovered OS Class entry to the Query Viewer.
• Clicking a relationship, for example Software Instance: Software Instances running on this host, displayed with a following right arrow (►), populates the next pane in the selection tool with the attributes and relationships of the destination node. Click an attribute here to add it to the Query Viewer.
• Clicking a relationship in the second pane populates the third pane in the selection tool with the attributes and relationships of the destination node in the same way as before. Click an attribute here to add it to the Query Constructor.
• Clicking a further relationship populates a fourth pane and scrolls the previous panes to the left, hiding the first pane. You can scroll back by clicking the arrow to the left of the selector panes.

Filter viewer

The filter viewer provides a map of the filter that you are constructing. You can evaluate conditions on an attribute or group of attributes using the following conditions:

• All — True when ALL conditions are true.
• Any — True when any of the conditions are true.
• None — True when none of the conditions are true.

These conditions are selected using a drop down selector in the container which holds the attribute or attributes of interest. For example, in the following screen, two attributes have been selected from the first pane and are grouped with an All condition:

In this example, the filter is still using the Discovered OS Class. A Software Instance filter has been added by scrolling down the list to Software Instance: Software Instances running on this host; when this is clicked, the second pane is populated with the attributes and relationships of Software Instances. The Name attribute has been added to the query viewer by scrolling down the second pane list and clicking Name.

The filter means that only Windows Hosts running IIS are synchronized. All other Hosts are excluded from synchronization.

Example of creating a device filter

The following example shows how to use the filter builder to create a filter which will sync only those hosts in the organization that are web servers. I want to find all Windows hosts running IIS and all UNIX hosts running Apache.

1. From the first pane of the filter builder, select Discovered OS Class from the list of host attributes.
   The Discovered OS Class attribute is added to the Filter Viewer.
2. Enter "Windows" in the text entry field and leave the condition drop-down on contains word.
   We are initially looking for Microsoft Windows hosts running IIS and need to create a nesting level where this first test can be performed.
3. Click the Add Condition icon in the Discovered OS Class row.
   A new container is added which will be used to supply the All, Any, or None condition to be evaluated.
   Before we add a Software Instance filter, we must verify that it is added in the correct place.
4. Set the focus to the container which was just added by clicking in that container's area.
   When selected container is highlighted in yellow.
5. To add the Software Instance filter, scroll down the first pane to Software Instance: Software Instances running on this host. Click this to populate the second pane with the attributes and relationships of Software Instances.
6. From the second pane, select the Name attribute.
7. Enter "IIS" in the text entry field and leave the condition drop-down on contains word.
   
   We now have a filter for Windows hosts which are running IIS.
8. Click Save to save the changes. We now need to find UNIX hosts running Apache.
9. With the root of the Filter Viewer highlighted, select Discovered OS Class from the list of host attributes.
   The Discovered OS Class attribute is added to the Filter Viewer outside the section of the query completed above.
10. Enter "UNIX" in the text entry field and leave the condition drop-down on contains word.
11. Click the *Add Condition8 icon in the Discovered OS Class row.
    A new container is added which will be used to supply the All, Any, or None condition to be evaluated.
12. Click the new container to select it.
    We now need to add the Software Instance filter.
13. Scroll down the first pane to Software Instance: Software Instances running on this host and click this to populate the second pane with the attributes and relationships of Software Instances.
14. From the second pane. select the Name attribute.
15. Enter "Apache" in the text entry field and leave the condition drop-down on contains word.
16. Change the root condition drop-down to Any, instead of All.
    
    
17. Click on Save to save the new filter.

Filtering the synchronized components

To select nodes to filter

1. Click the Component Filter tab of the CMDB Sync page.
   The left pane shows a tree of all the related node kinds in the source subgraph. To exclude all the nodes from a particular branch of the tree, de-select the check box.
2. To filter nodes in the subgraph based on their attribute values, click the relevant entry in the left pane.
   The right pane now shows the attributes defined for the chosen node kind.
3. Click an attribute name to add a filtering condition for that attribute.
   After a filter has been defined for a particular part of the subgraph, only those nodes that match the filter are included in the source subgraph.

Currently the labels in the Component Filter show the node type and a brief description. For generic nodes such as Details, the description is insufficiently detailed to identify which node is selected. You need to check the CMDB after synchronization to ensure that the correct node is selected.

Filtering components from the UI

On the Component Filter tab,

• Not all components displayed on the UI synchronize to the CMDB. However, the UI allows you to filter all the displayed components. If you filter a component which, by default, does not synchronize to the CMDB, that filter will have no effect. For example, you may filter a pattern from the UI. However, by default, patterns are not synchronized to the CMDB. As such, filtering a pattern has no effect. To learn about the components that synchronize to the CMDB by default, see Default CDM Mapping.
• If you apply a filter on a certain component, only that component is filtered from synchronizing to the CMDB. If there are other components associated with it, those are not filtered. For example, if you filter a Software Instance, only that SI is filtered. The host associated with the SI is not filtered.

Example of creating a filter for synchronizing web servers

The following example shows how to use the Filter Builder to create a filter that will synchronize only those software instances representing web servers on those hosts previously identified as web servers.

1. From the left pane of the filter builder, select Software Instance.
   The right pane is populated with Software Instance attributes.
2. Click the Type attribute.
3. Enter "IIS" in the text entry field and leave the condition drop-down on "contains word".
4. Click the Type attribute.
5. Enter "Apache" in the text entry field and leave the condition drop-down on "contains word".
6. Change the Software Instance where... drop-down to "any".
7. Click Save.

With this filter in place, any Software Instances (SIs) that do not match the conditions are removed from the source subgraph. When the source subgraph is transformed into the target subgraph, it is as if the chosen SI nodes were the only ones present in the Discovery datastore.

Filtering the CMDB CI classes

To select classes to synchronize with the CMDB

1. Click the CMDB CI Filter tab.
2. Select the classes of Configuration Item to synchronize by selecting or deselecting the check boxes to the left of the required class.
   You cannot deselect the root (BMC_ComputerSystem) class.

Configuring continuous synchronization

Continuous CMDB synchronization is disabled by default after the initial setup.

To start Continuous CMDB Sync

From the Configuration tab of the CMDB Sync Configuration page, click Start Continuous CMDB Sync.

Continuous CMDB synchronization starts, and the red STOPPED heading banner changes to a green RUNNING banner.

In this mode, as the scan of each device (Host, Network Device or MFPart) is completed, it is automatically queued for synchronization.

If any devices are deleted from the Discovery data store (due to aging), they are also queued for synchronization, so the deletion is synchronized with the CMDB.

To stop a running Continuous CMDB Sync

From the Configuration tab of the CMDB Sync page, click Stop Continuous CMDB Sync.
Continuous CMDB synchronization stops, and the green STARTED heading banner changes to a red STOPPED banner.

No additional devices are automatically queued for synchronization, but those already queued (due either to the continuous synchronization or manual synchronization requests) are still processed.

Batch and individual synchronization can still be performed.

Batch and individual synchronization

To see the progress of the synchronization, you can follow the link in the notification to the status page.

A node is only added to the synchronization queue if it is not already queued.

To synchronize an individual device

From a node view page for a root node kind (Host, Network Device and MFPart), you can choose Sync with CMDB from the Actions menu to synchronize that particular device.

To synchronize deletion of root nodes

When root nodes are deleted in the Discovery datastore, the associated root CIs must be deleted in the CMDB, along with all their related CIs. In continuous synchronization mode, deletions are automatically queued. To synchronize deletions using batch or individual synchronization, view the destroyed node(s), and then choose Sync with CMDB from the Actions menu.

There are many ways to find destroyed nodes. One simple way is to choose Advanced Search, select the Include Destroyed check box, and then choose the node kind (for example, Host) that you want to search for.

Configuring CMDB Sync blackout windows

CMDB synchronization can usually occur at any time. To prevent any CMDB access during sensitive times, you can configure blackout windows to occur daily, weekly, or monthly, and you can specify a start time and duration. During a blackout window, all processing of the CMDB synchronization queue is paused. New nodes can still be scheduled for synchronization, both by continuous synchronization and batch synchronization, but no processing occurs until the blackout window ends.

To configure a CMDB Sync blackout window

1. Set up the CMDB Sync connection as described here.
2. From the Model section of the Administration tab, click CMDB Sync.
3. On the CMDB Sync page, click the Blackout Windows tab.
4. To add a new blackout window, click Add.
   The Add a New Blackout Window dialog is displayed. 

5. Enter the information for the blackout window in the fields described in the following table.

   Field name	Details
   Comment	Enter a comment for the blackout window. Where the blackout window is referred to in the UI, this label is shown.
   Frequency	Select a frequency for the blackout window. For example, this can be: Weekly by days of week Once per week Monthly by day of month Monthly by week of month
   Start	Based on the selected frequency, the following options for starting the blackout window is displayed: Weekly by days of week: You are provided with buttons to select the days and drop down menus to select the start time in hours and minutes for the blackout window. You can select one or more days from the day buttons. The selected buttons appear with a Yellow border. Once per week: You are provided with drop down menus to select the day and start time in hours and minutes for the blackout window. Monthly by day of month: You are provided with drop down menus to select the day of the month and the start time in hours and minutes for the blackout window. Monthly by week of month: You are provided with drop down menus to the select the week, the day of the week, and the start time in hours and minutes for the blackout window.
   End	Based on the selected frequency, the following options for ending the blackout window is displayed: Weekly by days of week: You are provided with drop down menus to select the time in hours and minutes to end the blackout window. Once per week: You are provided with drop down menus to select the day of the week and time to end the blackout window. Monthly by day of month: You are provided with drop down menus to select the day of the month and the time in hours and minutes to end the blackout window. Monthly by week of month: You are provided with drop down menus to the select the number of days and the time in hours and minutes to end the blackout window.

6. Click OK. 
   The Blackout Windows tab displays the configured CMDB Sync blackout windows.
   

To edit an existing blackout window

You can edit an existing CMDB Sync blackout window. If the blackout is currently in progress, it is automatically cancelled when you edit it.

1. From the Blackout Windows tab of the CMDB Sync page, click Edit for the corresponding blackout window.
   The Edit an Existing Blackout Window dialog is displayed.
2. Edit the fields as required.
3. Click OK.

To delete an existing blackout window

You can delete an existing CMDB Sync blackout window.

1. From the Blackout Windows tab of the CMDB Sync page, click Delete for the corresponding blackout window.
2. When prompted, confirm the deletion of the blackout window by clicking OK.

Default CDM Mapping

Root node kind mappings

Each root node kind in the Discovery model is mapped to the Common Data Model (CDM) as follows:

Restart the Tideway service after making changes to CDM

If any changes are made to the CDM in the CMDB, for example, adding attributes, you cannot sync to those attributes until the tideway service has been restarted. On restart of the tideway service, the CDM is read and all customized classes and attributes are available to CMDB sync.

Extending and modifying the standard mappings

If you need to extend or modify the standard mappings, it is best to do so with extension mappings, rather than by editing the standard mappings. Extension mappings are able to create new CIs and relationships, set additional CI attributes, and change the standard values of existing CI attributes. The standard mappings should only be edited as a last resort, if the mapped structure needs to be different. See the Pattern templates for examples.

ADDMIntegrationId

So that Discovery can correctly maintain the CIs it creates in its dataset, it stores a unique key on every CI, in the ADDMIntegrationId attribute. These keys are sometimes directly populated from the key on a corresponding node in the Discovery datastore, but in other situations they are constructed by using rules that are appropriate for the mapping structure. See the syncmapping definitions for details of how keys are populated.

Company attribute

If the CMDB is configured for multitenancy, all CIs can have a Company attribute set appropriately. See Multitenancy for details.

Impact relationships

One of the main features of BMC Atrium CMDB is to indicate the way that one CI impacts another. Versions of BMC Atrium CMDB prior to 7.6.03 represent impact using a specific relationship, BMC_Impact. With those CMDB versions, Discovery is responsible for creating and maintaining the BMC_Impact relationships. In later CMDB versions, the BMC_Impact relationship has been deprecated, and impact is now indicated with the HasImpact attribute on all other relationship classes.

BMC Service Impact Manager (SIM) version 7.4 is incompatible with the new representation of impact as an attribute, so if SIM is used with CMDB version 7.6.03 or later, Discovery must be configured with the "CMDB 7.6.03 and later with Impact relationships" data model. In that case, Discovery will ask the CMDB to create BMC_Impact relationships, but the deprecation mechanism will translate them into BMC_BaseRelationship instances with the Name "ImpactOnly". If you view such a relationship in Atrium Explorer, it will display as a BMC_BaseRelationship with HasImpact set to "Yes". However, the deprecation mechanism means that it is still possible to find the relationships as BMC_Impact by using the CMDB API or by using the BMC.CORE:BMC_Impact form. This complicated situation only applies to BMC Service Impact Manager version 7.4 and earlier, not to the SIM functionality built into later versions of BMC Proactive Performance Manager.

CDM Mapping for Host

Host nodes in the Discovery model are mapped to the Common Data Model (CDM) as shown in this automatically-generated diagram:

The CIs created are described in this topic.

Data models

CMDB version differences

The default mapping works with CMDB versions 7.5, 7.6, and 7.6.03 and later. The data model in each is slightly different.

• BMC_Impact relationships are not normally created with CMDB 7.6.03 and later, since the CMDB automatically maintains them itself. See the information about impact relationships for more details.
• A number of attributes are not present in CMDB 7.5, as noted below.

 Click here for reference information on impact and the data models.

Different versions of the CMDB have subtly different data models. Syncmappings can support multiple data models with datamodel declarations. CMDB data models are assigned simple integer values:

Differences from previous versions of BMC Atrium Discovery

• Except where noted below, the model populated by BMC Atrium Discovery version 9.0 is the same as that populated by earlier versions.
• Starting from version 10.0, in the model populated by BMC Atrium Discovery, the ram attribute is now used for storing the physical memory volume and the new logical_ram attribute is added for the reported logical memory volume.

BMC_ComputerSystem

The root Host node is mapped to a root BMC_ComputerSystem CI with the following attributes:

TokenId rules

TokenId is an attribute that in some circumstances aids reconciliation of CIs populated by multiple data sources. The following describes how discovery sets TokenId for BMC_ComputerSystem.

For most hosts, TokenId is of the form hostname:DNS domain name.

For some virtual hosts, TokenId contains a UUID:

1. For VMware, TokenId is of the form "VI-UUID:ABCD-EF-GH-IJ-KLMNOP". Where each letter represents a hexadecimal digit.
2. For Hyper-V, TokenId is of the form "HYPERV-ID:ABCD-EF-GH-IJ-KLMNOP". With Hyper-V, the UUID is only available on the physical machine, so TokenId is only set for virtual machines that have been successfully linked to their hosting physical machines.
3. For Xen (including Oracle VM), TokenId is of the form "XEN-ID:ABCD-EF-GH-IJ-KLMNOP".
4. For KVM (including RedHat Enterprise Virtualization), TokenId is of the form "KVM-ID:ABCD-EF-GH-IJ-KLMNOP".

BMC_OperatingSystem

The root Host is also mapped to a single BMC_OperatingSystem CI, with the following attributes:

Operating system relationships

BMC_Processor

The root Host is mapped to a number of BMC_Processor CIs.

• For physical machines, the number of CIs corresponds to the number of physical CPU packages present in the machine.
• For virtual machines, the number of CIs corresponds to the number of logical CPUs the OS is scheduling across.

In some circumstances, it is not possible to discover the number of physical CPU packages in a physical machine. In such cases, no BMC_Processor CIs are created for the machine.

All the BMC_Processor CIs for a host are normally identical to each other. New in BMC Atrium Discovery 8.3, they can be different in cases that a physical machine has more than one type of CPU.