Foglight 5.9.8 - Administration and Configuration Guide

Agent Adapters

Use the Agent Adapters dashboard to view information about the existing agent adapters that your Foglight agents use to communicate with the Foglight Management Server.

Activating an agent adapter starts the agent adapter process on the Management Server while deactivating an agent adapter stops that process.

If it is requested by Quest Support, you can activate and deactivate agent adapters. The Status column indicates if an adapter is active or not.

TIP: To select multiple agent adapters, press the SHIFT key while selecting the rows containing the adapters that you want to activate.

The Agent Adapters dashboard refreshes, showing the Active icon in the Status column.

TIP: To select multiple agent adapters, press the SHIFT key while selecting the rows containing the adapters that you want to activate.

The Agent Adapters dashboard refreshes, showing the Deactivated icon in the Status column.

Manage Lockboxes

This dashboard is a starting point when creating credentials. Credentials are stored in lockboxes. Ensure that you have the appropriate lockboxes in place before creating credentials. The dashboard displays a list of all lockboxes that are defined on the server, in addition to the System lockbox that is included with the Management Server. This lockbox is not password-protected. Its contents are accessible to all clients in your system. The System lockbox is only intended for use with some agent types, and it is always available for selection in the flow for adding credentials initiated from the Manage Credentials dashboard. For that reason, any purpose-specific wizards included with cartridges whose agents do not support the System lockbox do not provide this lockbox as an option when creating credentials.

Use the Manage Lockboxes dashboard to view a list of lockboxes that exist in your system, to create and delete lockboxes, to change their password, and to release them to credential clients.

By default, the following columns are displayed:

Click to add a password to a lockbox that is not password-protected.

Click to remove a password associated with a password-protected lockbox.

Use the Add button to add a lockbox to the existing collection.

To delete a lockbox, In the left-most column in the list, select the check boxes for one or more lockboxes, then click Delete.

For more information, see Add or delete lockboxes.

A lockbox contains one or more credentials, can be password-protected, and can be released to credential clients. If a lockbox is password-protected, you must know the password in order to release the lockbox to a client.

Typically you need one lockbox per client. In case your business scenario requires different encryption keys for different credentials, or managing user access through password control, it is possible to define multiple lockboxes for an individual client.

Delete lockboxes that are no longer needed. Deleting a lockbox deletes all credentials contained in the lockbox. It causes the clients using these credentials to receive a delete notification and stop using those credentials for authentication.

Lockboxes can be password-protected. Associating passwords with lockboxes enforces access control, allowing only authorized users to release lockboxes to credential clients. Removing a lockbox password enables any user to access the credentials stored in the lockbox.

1	On the Manage Lockboxes dashboard, in the row containing the lockbox that you want to secure with a password, click .

The Add Password To Lockbox dialog box closes and the Manage Lockboxes dashboard refreshes, showing the button in the Add or Remove Password column, indicating that a lockbox password is added and can be removed.

1	On the Manage Lockboxes dashboard, in the row containing the lockbox whose password you want to remove, click .

The Remove Password of Lockbox dialog box closes and the Manage Lockboxes dashboard refreshes, showing the button in the Add or Remove Password column, indicating that a lockbox password no longer exists and can be added.

Lockboxes can be password-protected. Associating passwords with lockboxes enforces access control, allowing only authorized users to release lockboxes to respective credential clients.

1	On the Manage Lockboxes dashboard, in the row containing the lockbox whose password you want to change, click .

A lockbox contains a set of credentials and keys for their encryption and decryption. Credentials are released to credential clients unencrypted. When a lockbox is released to a credential client, the client passes the credential information to its agents. The agents use this information to establish connection with target resources.

CAUTION: Any agents that have access to a credential client with a released lockbox can potentially query and obtain credential information stored within that lockbox.

1	On the Manage Lockboxes dashboard, in the row containing the lockbox that you want to release to a credential client, click .

NOTE: The password box appears only if the selected lockbox is password-protected.

Manage Credentials

This dashboard lists the available lockboxes, the credentials associated with them, and the related information. It allows you to add new and edit existing credentials. Credentials are stored in lockboxes. Lockboxes can be created beforehand, or during the process of creating credentials.

Credential information consists of a name, type, policies, and resource mappings. The credential name uniquely identifies the credential. A range of different types allows you to choose a credential type that suits your organization’s security requirements. A credential type can consist of a user name, password, Windows domain, no input, or the available combinations of these parameters.

A credential can have none, one, or multiple policies. A credential policy defines the number of times a credential can be used, the number of allowed authentication failures, the time range during which the credential is valid, or the length of time the credential data can be cached on the client.

Resource mappings identify secured resources. The mappings typically contain a combination of literal expressions, regular expressions, or an IP address range.

By default, the following columns are displayed:

TIP: You can only query credentials if there are one or more credentials defined in your system, otherwise the Query Credential button appears disabled.

TIP: You can only reorder credentials if there are two or more credentials defined in your system, otherwise the Reorder button appears disabled.

Credentials are stored in lockboxes. Lockboxes can be created beforehand, or during the process of creating credentials.

Credentials are released to credential clients unencrypted. If the agent uses a standard connection mechanism supported by the Foglight Agent Manager such as WinShell, WMI, or SSH, when a lockbox is released to the Agent Manager, the Agent Manager establishes a connection with the monitored resource, and passes the connection to the agent. If the agent uses a different connection mechanism, the client passes the credential information to the agent. The agent uses this information to establish a connection with secured resources.

CAUTION: Any agents that have access to a credential client with a released lockbox can potentially query and obtain credential information stored within that lockbox.

When creating a new credential you have an option to start from a blank credential or copy an existing credential. Credential type, policies, and resource mappings are all preserved and copied over to the new credential. Unlike credential name, policies, and resource mappings, once defined, credential types cannot be changed. Copying an existing credential is useful in situations when you need to quickly create a slightly modified version of the existing credential. For example, if your organization enforces periodic password changes, when this happens, simply copy the credential and change its password.

Credentials that are no longer in use can be deleted.

NOTE: The System lockbox is only intended for use with some agent types, and it is always available for selection in the flow for adding credentials initiated from the Manage Credentials dashboard. For that reason, any purpose-specific wizards included with cartridges whose agents do not support the System lockbox do not provide this lockbox as an option when creating credentials.

NOTE: You can only copy resource mappings from credentials of the same type.

NOTE: There can only be one policy defined for each policy type.

NOTE: You can copy policies from any credentials from any credentials that have policies defined regardless of their credential type.

Credential properties contain authentication data needed to access monitored resources. Each credential type has a unique set of authentication properties.

1	On the Manage Credentials dashboard, in the row containing the credential whose name you want to edit, click .

Credential names are specified during creation. They can be changed at a later time, if required.

1	On the Manage Credentials dashboard, in the row containing the credential whose name you want to edit, click .

A credential can have none, one, or multiple policies. The policy type defines the number of times a credential can be used, the number of allowed authentication failures, the time range during which the credential is valid, or the length of time the credential data can be cached on the client.

Policies can be specified during credential creation or at a later time. You can delete existing policies, add new policies, or edit existing policies. When editing an existing policy, you can only change the settings associated with the policy type, but cannot change the actual type.

1	On the Manage Credentials dashboard, in the row containing the credential to which you want to add a new policy, click .

IMPORTANT: There can only be one policy per policy type.

IMPORTANT: You can copy policies from any credentials that have policies defined regardless of their credential type. This button appears enabled only if there are credentials with policy types that are different than the ones already defined for this credential.

1	On the Manage Credentials dashboard, in the row containing the credential whose policy you want to delete, click .

1	On the Manage Credentials dashboard, in the row containing the credential whose policy you want to delete, click .

3	In the Update Policies of Credential dialog box, in the row containing the policy that you want to edit, click .

Resource mappings identify the parts of the monitored system that can be accessed using the credentials in which they are defined. A credential can have one or more resource mappings that include or exclude specific sets of targets. Resource mappings are combined using the logical OR operator. A resource mapping can have one or more conditions, combined using the logical AND operator. Each resource mapping uses a set of predefined building blocks to identify the monitored targets. For example, you can have a credential with multiple resource mappings (one for each usage, for example, if multiple usages exist in the credential type), and each resource mapping can have one or more resource mapping conditions to select secured resources. You can further refine the mapping, if required.

The type and structure of resource mappings depend on the selected credential type, which in turn depends on the range of installed cartridges. Some cartridges, for example, support the Use Client’s Login At Connection Time and User Name and Password credential types, while others can only accept the Challenge Response or User Name types. A Domain, User Name, and Password (Windows) credential type, for example, that requires a valid domain name, user name, and password to access a monitored system, can have one or more resource mappings for accessing Windows-based systems based on a condition that evaluates the target host name.

TIP: Different cartridges support different types of credentials, and each credential type can have one or more usage definitions. Depending on the type and range of installed cartridges, you can have different or additional usages available. For more information, see the respective cartridge documentation.

TIP: Different cartridge support different types of usages. The usage determines the way the resources are accessed. Depending on the type and range of installed cartridges, you can have different or additional ways for accessing resources. For more information, see the respective cartridge documentation.

TIP: Regular expressions support case insensitive matching when the (?i) flag is used. For example, (?i)host1.example.* returns Host1.example and host1.example.com as matches. Regular expressions run through the JRE Pattern class that supports case insensitivity. For syntax information and usage tips, visit http://rd-www.prod.quest.corp/static/sun_docs/jdk-1_6_0/docs/api/java/util/regex/Pattern.html.

The selections available with each building block in a resource mapping depend on the resource mapping’s Usage type, which in turn depends on the selected credential type and the range of installed cartridges. The selections mentioned above do not reflect the values available with all of the cartridges that support credentials. For information about the available credential types supported by a specific cartridge and the related resource mappings and their building blocks, refer to the cartridge documentation.

When using IPv6 addresses in Credential Mappings it is preferable to use IP Range or CIDR matchers. Since an IPv6 address can have more than one textual representation using String or RegEx matches may lead to confusing server behavior.

1	On the Manage Credentials dashboard, in the row containing the credential where you want to add a new resource mapping, click .

NOTE: Different cartridges support different types of credentials, and each credential type can have one or more usage definitions. Depending on the type and range of installed cartridges, you can have different credential usages available. For more information, see the respective cartridge documentation.

NOTE: Different cartridges support different types of usages. The usage determines which resource component can be evaluated. Depending on the type and range of installed cartridges, you can have different or additional ways for accessing resources. For more information, see the respective cartridge documentation.

NOTE: The range and type of the matching types depend on the resource component selected for evaluation, which in turn depends on the range of installed cartridges. For additional information about the matching types available with a specific cartridge, see the respective cartridge documentation.

g	Click and write a matching expression in the box that appears available for selection.

TIP: Regular expressions support case-insensitive matching when the (?i) flag is used. For example, (?i)host1.example.* returns Host1.example and host1.example.com as matches. Regular expressions run through the JRE Pattern class that supports case insensitivity. For syntax information and usage tips, visit http://rd-www.prod.quest.corp/static/sun_docs/jdk-1_6_0/docs/api/java/util/regex/Pattern.html.

NOTE: You can only copy resource mappings from credentials of the same type.

1	On the Manage Credentials dashboard, in the row containing the credential whose resource mapping you want to edit, click .

3	To add a condition to an existing resource mapping, in the row containing the resource mapping, click and specify the new condition in the New Resource Mapping Condition dialog box that appears.

4	To edit an existing resource mapping condition, in the row containing the resource mapping, click and edit the condition in the Edit Resource Mapping Condition dialog box that appears.

1	On the Manage Credentials dashboard, in the row containing the credential whose resource mapping you want to delete, click .

When a credential client retrieves a set credentials, the credentials are listed in their relative order. For example, a credential with the order of 100 has operator-level privileges, while another one with the order of 200 has administrative privileges that grants access to a far wider range of resources. Given the order values, any queries that return both credentials retrieve the operator-level credentials first. If you need to retrieve the credential with administrative access first, you can do so by simply changing the relative order of both credentials.

TIP: You can only reorder credentials if there are two or more credentials defined in your system, otherwise the Reorder button appears disabled.

•	To move one credential up or down, use the or buttons in the Move Up and Move Down columns, as required.

•	To move multiple credentials, select the rows containing the credentials that you want to move, and use the or buttons in the Move In Front Of and Move Behind columns, as required.

Credential queries help you retrieve credentials using different criteria, such as the target host, a host on which a monitoring agent is running, a credential type, lockboxes to which the credentials belong, and custom properties. You can quickly find out if you can associate existing credentials with monitoring agents rather than create new ones.

TIP: You can only query credentials if there are one or more credentials defined in your system, otherwise the Query Credential button appears disabled.

Monitor Alarms

Credential clients generate alarms when certain pre-defined conditions are met. These errors typically happen when a client attempts to access a resource and encounters a policy-related problem. The Monitor Credential Alarms dashboard lists all alarms generated by the existing credential clients and provides additional information about each event. The list includes any alarms generated by the Catalyst Credential Check rule and Credential events generated by the Foglight Agent Manager.

Credential alarms also appear on the main Alarms dashboard, together with other Foglight alarms, while the Monitor Credential Alarms dashboard only lists the alarm generated due to a credential-related condition. Use it to quickly review and manage credential alarms.

For complete information about alarms in Foglight, see the Foglight User Help.

By default, the Monitor Credential Alarms dashboard displays the following columns:

•	Sev: The alarm severity: Warning , Critical , or Fatal .

TIP: Use the Select All or Unselect All buttons to quickly select all alarms, or to clear your selection, as required:

To filter the list of alarms, click Alarm Filter in the top right and provide the desired settings.

To view the Credential Alarm dialog box, click any column.

Use this dialog box to find out more about the problem that caused the alarm. From here, click the Diagnostic link to access the part of the browser interface that you can use to further investigate the problem.

NOTE: When the Catalyst Credential Check rule generates a credential alarm, the Diagnostics link is disabled. This rule is not associated with any of the query parameters; therefore, they are not applicable.

Credential queries help you retrieve credentials using different criteria, such as the target host, a host on which a monitoring agent is running, a credential type, lockboxes to which the credentials belong, and custom properties. You can quickly find out if you can associate existing credentials with monitoring agents rather than create new ones.

In a federated environment, Federated Child alarms can be viewed on the Federated Child servers using the above approach. While credentials cannot be administered from the Federation Master, it is possible to view Federated Child alarms from the Alarms dashboard on the Federation Master.

The Credential Alarm dialog box that appears shows a smaller subset of information, containing only the alarm message and the name of the Federated Child server. To retrieve complete information about this alarm, log in to the Federated Child server, navigate to the Monitor Credential Alarms dashboard, and drill down on the alarm to display the common version of the Credential Alarm dialog box.

For complete information about alarms in Foglight, see the Foglight User Help.

Foglight Agent Manager generates credential events based on actions that occur during the processing of credential requests. These events result in the creation of credential alarms of the appropriate severity. The following principles apply:

Table 11. A list of the credential events that are generated by the Agent Manager.

Alarm Severity	Description	Event Code	Event Severity
Normal	A connection to the remote host is established.	connection.success	Information
	NOTE: Information events result in the Normal alarm state which does not result in alarm generation.
(Warning)	The Agent Manager attempts to establish a connection, but no credentials were retrieved by the credential query.	connection.nocredentials	Warning
(Warning)	Attempt is made to authenticate a connection through the CleartextCredentialService with a credential that is not granted direct access rights.	direct.access.not.assigned	Warning
(Warning)	A lockbox that is associated with a credential is not granted to the Agent Manager Host.	lockbox.not.granted	Warning
(Fatal)	The credential used to establish a connection fails to authenticate access to the remote resource.	authentication.failure	Error
(Fatal)	A connection to the remote host cannot be established using the retrieved credential.	connection.failure	Error
(Fatal)	The Agent Manager cannot process the retrieved credential.	creation.failed	Error
(Fatal)	The request to delete an assigned lockbox failed.	lockbox.not.deleted	Error
(Fatal)	A credential cannot be used due to a policy violation.	policy.violation	Error

Acknowledging a credential alarm informs other users looking at credential alarms that the alarm is raised due to a known situation. When an alarm is acknowledged, this setting cannot be reverted.

In most cases, Foglight clears alarms when the condition that triggered them changes. You can delete certain types of alarms that do not clear themselves if they are no longer relevant.

If the condition that triggered a credential alarm changes, you can manually clear the alarm. For example, a credential alarm fires when an agent fails to connect to a monitored host due to a wrong password. Creating a new credential with the correct password and releasing the new credential to the appropriate credential client remedies the problem, and you can choose to delete the alarm because it is no longer relevant.

When an alarm is cleared, this setting cannot be reverted. You can see a list of cleared alarms using the alarm filter.