Foglight 5.9.4 - Administration and Configuration Guide

Logging in

The browser interface supports most web browsers, such as Internet Explorer and Mozilla Firefox. Before you log in, ensure that your Management Server and any Foglight agent instances are up and running and adjust your browser settings.

NOTE: Foglight displays dynamic data that is regularly updated. Therefore, using your browser’s Back and Forward buttons may cause cached views to appear or result in an error message.

NOTE: The preceding URL uses the default HTTP port number, 8080. For more information about default port assignments, see Default port assignments.

From here, after a successful login, you can explore the Administration dashboards in the browser interface.

The Management Server supports integration with external LDAP directories. In a Kerberos-based environment, such as Microsoft® Active Directory®, most web browsers can authenticate users against the web server using their current credentials.

When this feature is configured, if you log in to a machine running a Windows® OS and then log in to the browser interface, the Management Server uses your Windows account credentials to authenticate you as a Management Server user.

You can also import all of the related groups from Active Directory and map the groups to Management Server roles, to control user permissions in the browser interface.

Complete the following configuration steps to enable the Windows single sign-on (SSO) feature:

If you were using the VSJ SSO that was provided in earlier versions of Foglight, you must also migrate your settings to the Windows OS-based SSO. For more information, see Migrate to Windows SSO from VSJ SSO.

Microsoft® Active Directory® provides a directory service supporting the Lightweight Directory Access Protocol (LDAP), and a Kerberos KDC (key distribution center) to authenticate users. It allows organizations to share and manage information about users and network resources. When properly configured, Active Directory® provides an SSO environment that can be integrated with the standard Windows® OS desktop login.

TIP: When setting up the Kerberos Service Principal Name (SPN), use the following instructions to create mappings between the user account and SPNs, and to create a keytab file to configure in krb5‑auth.config. For example: ktpass -princ HTTP/<fmshost.example.com>@REALM -mapuser "<domain>\<user>" -pass <password> -out <keytabFilePath> And: Use setspn to set up the mapping for just the host name. For example: setspn -A HTTP/<fmshost> <user>

NOTE: Duplicate SPNs cause Kerberos authentication to return an NTLM token and fallback to Form authentication. To search for duplicate SPNs: setspn -X -F If you locate duplicate SPNs for “HTTP/<fmshost>”, you can remove them with the following command: setspn -d HTTP/<fmshost> <user>

Foglight provides SSO for the Management Server using Active Directory® as its identity store. It includes an enterprise-wide method of identification and authorization that can be administered in a consistent and transparent manner. This method allows users to access only those Management Server components for which they are authorized.

Enabling the Windows® SSO feature in Foglight requires the configuration of the following components:

Table 2. Properties requiring configuration for SSO in Foglight.

Property Name	Comment
Krb5ConfigFilePath	Location of the Kerberos configuration file.
Principal	The Active Directory® service principal.
QualifyUserPrincipal	Include the Active Directory® Domain name in the user principal name.
Keytab	The keytab file of the service principal specified above.
LDAPURLOverrides	If there is a connection issue with the default LDAP URL, use the LDAPURLOverrides property to override the default setting. This property specifies the LDAP URL to be used by the server for retrieving group membership information for SSO users. By default, the server gets the LDAP URL from krb5.config (see the Krb5ConfigFilePath property). This property can be used to override that value. The domain name must be set as lowercase ASCII. For example: LDAPURLOverrides = { "domain1" : "ldap://ldap1.example.com", /regex.*/ : "ldap://ldap2.example.com", /.*/ : "ldap://ldap3.example.com", };
QualifyGroupName	Specifies whether the server should append the domain to the group name when importing SSO user-associated groups. The default value is true.
AdditionalContextParameters	Specifies additional context parameters when the Management Server initializes the LDAP context and connects to the LDAP server for retrieving group membership information for SSO users. For example: AdditionalContextParameters = { "java.naming.referral" : "follow", }; NOTE: This property is commented out by default.
UserQueryFilter	Specifies the LDAP filter used to search for LDAP User objects. The filter argument is the SSO user name. For example: UserQueryFilter = "(&(objectClass=user)(sAMAccountName={0}))"; NOTE: If this property is not set, the default setting is: UserQueryFilter ="(&(objectClass=user)(sAMAccountName={0}))"
GroupQueryFilter	Specifies the LDAP filter used to search for LDAP User groups. The filter argument is the LDAP User DN. For example, to import direct groups: GroupQueryFilter = "(&(objectclass=group)(member={0}))"; For example, to import all nested groups: GroupQueryFilter = "(&(objectclass=group)(member:1.2.840.113556.1.4.1941:={0}))"; If this property is not set, then the default value is GroupQueryFilter = "(&(objectclass=group)(member={0}))"

NOTE: The first KDC in krb5.conf will be used as the LDAP server for the related domain by default. If that is not appropriate you should configure LDAP URLs for each of their domains relevant to Foglight SSO in the LDAPURLOverides element in krb5-auth.config.

Most web browsers include extensions that allow Foglight users to participate in a Kerberos-based single sign-on (SSO) environment. This environment relies on the SPNEGO (Simple and Protected GSS-API Negotiation Mechanism) authentication mechanism. To enable this feature, configure your web browser to support SPNEGO authentication.

IMPORTANT: Only Microsoft® Internet Explorer®, Google Chrome™, and Mozilla® Firefox® browsers can be configured to support SPNEGO authentication currently.

If you were using the VSJ SSO implementation in earlier versions of Foglight, you must migrate to the new Windows OS-based SSO.

Table 3. VSJ properties and the corresponding krb5-auth.config properties

vsj.properties	krb5-auth.config
idm.princ	Principal
idm.keytab	Keytab
idm.ad.qualifyUserPrincipal	QualifyUserPrincipal

After you configure Windows® SSO, log in to your Active Directory® domain, start your web browser, and navigate to the Foglight browser interface. You are no longer required to provide your user name and password on the login page. The Management Server now uses your Kerberos credentials to log you in to the Foglight browser interface and grant you permissions associated with your Active Directory® account. This configuration allows you to bypass the common login page.

If you want to log in to the browser interface using an internal Foglight user account instead of your Windows account (for example, foglight/foglight), you have two options.

Manage Licenses

Installing a license enables you to access any features that are defined in the license file for a specific length of time.

When the Management Server reads the license file, it stores it in the database and no longer requires the actual file.

The top part of the Manage Licenses dashboard provides an overview of the licensed capabilities currently enabled on the server. Installing a Foglight license enables the capabilities that are defined in the license file.

Deleting a license disables the features defined in the license.

Email Configuration

A proper configuration of email parameters enables Foglight to send email messages to selected recipients when certain thresholds are reached. Use the Email Configuration dashboard to view, configure and test email configuration parameters in Foglight.

The dashboard contains two views, each listing a set of configuration parameters: Email Server Configuration and Email Routing. Each parameter contains a registry value that Foglight uses to perform email actions. The following table describes the email parameters and identifies the registry variables they are associated with.

Table 4. Foglight email parameters and associated registry variables.

Parameter	Registry Variable	Required?	Description
Email Server Configuration view
Mail Server (Name or IP)	mail.host	Yes	Name or IP address of the mail server.
Email Sender Address	mail.from	Yes	Email address of the user that Foglight uses to send email messages.
Username to Login to Server	mail.user	No	User name of the account that Foglight uses to send email messages.
User Password	mail.password	No	Password of the user account that Foglight uses to send email messages
NOTE: If your mail server requires user authentication, supply the user name and password. For more information, contact you mail server administrator.
Mail Server Port	mail.port	No	Port number that Foglight uses to communicate with the mail server. The default value is 25. If you want to use a different port number, set this parameter to the desired value.
Mail Protocol	mail.transport.protocol	No	Protocol used for sending email messages. The default protocol is SMTP. The only other protocol type supported, aside from SMTP, is SMTPS.
Enable Debug Mode?	mail.debug	No	Indicates whether email-related debugging information is stored in the log.
Enable STARTTLS?	mail.smtp.starttls.enable	No	Indicates whether you want to enable the STARTTLS protocol and use encryption when sending email messages from Foglight.
Enable SSL?	mail.use.ssl	No	Indicates whether you want to enable the SSL protocol and use encryption when sending email messages from Foglight.
Mail Greeting	alarm.notification.template.body.greeting	No	Body message of the customized alarm email. Only string type is supported.
Mail Signature	alarm.notification.template.body.signature	No	Signature of the customized alarm email. Only string type is supported.
Mail Subject	alarm.notification.template.subject	No	Subject of the customized alarm email. Only string type is supported.
Email Routing view
Database Notifications	DBADMIN	No	Email address of the database administrator.
JavaEE Notifications	J2EEADMIN	No	Email address of the Java EE technologies administrator.
Operating System Notifications	SYSADMIN	No	Email address of the system administrator.
Global Notifications	mail.recipient	No	Email address of the default recipient.

Use the Edit button on the Email Configuration dashboard to edit email settings.

IMPORTANT: At minimum, specify the Mail Server (Name or IP) and Email Sender Address parameters.

NOTE: The appearance of the dialog box depends on the data type of the parameter that you are specifying. For example, configuring a text string shows a text box, while the control for editing a Boolean value (such as Is Run in Debug Mode) appears as a check box.

Test your email configuration to ensure that the potential recipients can receive email messages when pre-defined thresholds are reached.

For testing purposes, use an email address that you can easily access, such as your own email address. If you successfully configured email actions, the test email arrives at the specified destination address immediately after initiating the email test action.

TIP: The Mail Server (Name or IP) and Email Sender Address parameters are mandatory for a successful email configuration. Your mail server setup may require you to set additional parameters, such as the user name and password of the default sender, among others.

Users and Security

A Foglight user has a user name and a password and can belong to one or more groups. A user account has access to all the roles associated with the groups the user belongs to, and any additional roles associated with that account. Logging in to Foglight as a specific user authorizes you to perform a certain set of actions, based on the roles that are associated with that user account. Foglight can store user passwords on the Management Server, or in an external directory.

The Users tab lists all Foglight users, including:

For every user, the list shows the following:

The Users tab includes controls for managing user settings, creating new users, deleting users, forcing password changes, unlocking a user accounts, and a search tool. Clicking a user’s role or group entry allows you to quickly edit user permissions.

To access this tab, on the navigation panel, click Dashboards > Administration > Users & Security. From there, to start managing user access, click Manage Users, Groups, Roles and ensure that the Users tab is open in the display area.

The Users and Security dashboard allows you to look for user account, given a part of their user name.

The Users tab includes a wizard that allows you to create new users and grant them access permissions. The wizard is invoked using the New User button on the Users tab. Using this flow you can create one or more users with the same set of permissions.

Alternatively, use the fglcmd security:createuser command to create a user. For more information, see the Command-Line Reference Guide.

TIP: By default, the maximum length of Name is 15 characters; the maximum length of Email is 80 characters

TIP: The default value is Last 1 Hour.

Use the Remove Users button on the Users tab to remove user accounts from Foglight. You can only delete those users that are added after the installation, or users imported into Foglight from an external directory. Their types appear as Internal and External, respectively, on the Users tab. The type of the default user account included with Foglight appears as Built-In. The Built-In account, or the account used to log in to Foglight, cannot be removed.

Deleting an external user from Foglight does not remove that account from the external directory.

Alternatively, you can delete internal or external users using the security:deleteuser command that comes with the fglcmd interface. For more information, see the Command-Line Reference Guide.

Copying a user account is useful in situations when you need to quickly create a modified version of an existing user. Instead of re-creating all of the account’s settings, such as adding groups or roles, simply copy an existing account and edit the required parameters. Copying external accounts creates a copy of that account in Foglight, with no effects on the external directory in which the account is defined. A copy of an external account appears as an internal account in Foglight and shows no association with external groups that the original account belongs to.

TIP: By default, the maximum length of Name is 15 characters; the maximum length of Email is 80 characters.

TIP: The default value is Last 4 Hours.

Adding a user account to a group grants that user account access to all the roles associated with that group. Adding a role to a user account grants that user account access to any actions associated with that role, in addition to the roles previously given to the groups that user is a member of. Individual roles that are associated with a group a user belongs to cannot be removed from the user account, without removing the user from that group.

Groups and roles can be associated with a user account in many different flows, for example, when creating new accounts or editing user details. This topic describes the process of editing users’ groups and roles directly on the Users tab.

On the Users tab, the Groups column shows the names of groups that are associated with each account, or the number of groups, if that number is higher than five. The Roles column contains the names of the roles that are granted to each group, or the number of roles, if a group takes on six or more roles.

Hovering over these columns shows a list of the groups and roles assigned to the user entry.

When hovering over an entry that contains an external user account, the list also displays the groups from the external directory that the user belongs to, and that are selected for visibility on the Groups tab.

IMPORTANT: Individual roles that are granted to the user though group membership cannot be removed from the user account, and appear disabled for selection. Removing such a role requires removing the user from all groups to which that role is granted. This will, however, disable access to all roles that are associated with the groups from which the user is removed. You can add them to the user account later, as described in this procedure.

Foglight password settings dictate the restrictions for password creation for internal and built-in users. Passwords for external users are defined and managed in the external LDAP directory.

The restrictions include the number of unsuccessful attempts after which an account is locked, or the number of days after which a password expires. The Locked column on the Users tab indicates if an account is locked, while Password Expired shows which user accounts have an expired password. Force Password Change identifies the user accounts that, upon a successful login, are asked to change their passwords. Additionally, Token Available indicates if the Auth Token is available for an account. This setting is recommended during the user creation process, to protect user credentials.

For example, the configured number of unsuccessful login attempts dictates the number of bad logins after which a user account is locked.

It is also possible to set individual user passwords to never expire or to set a specific expiry date.

For more information about password settings, see Configuring Password settings.

TIP: To set a specific expiry date, run the command: fglcmd.bat -cmd security:passwordexpiry -set <date> -u <user_name>

The Details of User View shows current user profile. It also allows you to edit individual settings, such as password changes, groups and roles associated with the user, and the user audit trail. Drill down to this view by clicking the Name column on the Users tab, and choosing View from the shortcut menu that appears.

You can also edit user information using a wizard flow. This flow is limited to internal and built-in users only. It is similar to the one for creating new users. Start this flow by clicking the Name column on the Users tab, and choosing Edit from the shortcut menu.

TIP: The default home page is the Welcome page.

TIP: The default value is Last 4 Hours.

In Foglight, groups contain users. Roles are assigned to groups. A role that assigned to a group is also assigned to each member of that group.

The Groups tab lists all Foglight users. This includes the default groups included with Foglight and any groups that you create after the installation. For every group, the list shows its name, the roles and users associated with that group, and the group type. There are three types of groups in Foglight:

IMPORTANT: Built-in groups can not be deleted.

This tab includes controls for creating new groups, deleting existing groups, editing roles and users, and a search tool. Clicking a user’s role or group entry allows you to quickly edit group details.

To access this tab, on the navigation panel, choose Dashboards > Administration > Users & Security. From there, to start managing user access, click Manage Users, Groups, Roles and open the Groups tab.

The Groups tab includes a wizard that allows you to create new groups and associate them with roles and users. The wizard is invoked using the New Group button on the Groups tab. Using this flow you can create one or more groups.

Alternatively, you can create groups using the security:createuser fglcmd. For more information, see the Command-Line Reference Guide.

LDAP groups are any user groups that are mapped from an LDAP-compatible directory service supported by Foglight, when external directory services are configured. By default, external groups do not appear on the Groups tab of the Users & Security Management dashboard. You can enable them for visibility, when required. Any groups that appear on this tab also appear in other flows.

You need to turn group visibility on and then configure LDAP group access permissions for the visible groups. Importing LDAP groups into Foglight and granting them access permissions enables their users to access the browser interface. Failure to do so prevents them from using the browser interface.

Groups with a certain set of permissions likely require similar permission levels in Foglight. For example, consider granting the Foglight Administrator role to those LDAP groups that already have administrative privileges in the external directory. In any case, follow you organization’s standards when configuring access permissions.

When you integrate Foglight with an external directory service, any user that is granted the Security Administration role (regardless of whether their account type is internal, built-in, or external), can import LDAP groups. To import one or more LDAP groups into Foglight, you must log in with an internal Foglight account (for example, foglight/foglight) to import and configure LDAP groups.

IMPORTANT: If the external ldap group name is the same as the internal foglight group name we are not able to import it since group name is unique in foglight. By default there are six internal Foglight user groups: • SvcAccts: hidden from UI • Foglight Users: hidden from UI • Cartridge Developers • Foglight Administrators • Foglight Operators • Foglight Security Administrators

For more information about configuring Foglight to use an external directory service, see Configuring directory services.

From here, you can grant appropriate Foglight roles to the imported groups. For more information, see Associate roles with groups.

In a default Foglight installation, the Welcome page is the default page that appears in the display area after a successful login. In large distributed environments, some users may require access to other, role-specific dashboards immediately after logging in. A Foglight administrator, for example, may want to have the Administration home page as the landing page, instead of being taken to the Welcome page and having to navigate to the Administration page from there. Similarly, an operator may need to go directly to the Alarms dashboards, to review potential bottlenecks.

Foglight Security administrators have the ability to assign different home pages to different users or groups, when required. This can be done by configuring user preferences. In addition to changing the home page, configuring user preferences allows you to set the time range for the home page along with the refresh interval for the data appearing on that page. This is particularly useful when the home page displays important performance metrics that affect the behavior of your monitored system, and your organization as a whole.

You can configure user preferences for a user or a group. Changing a group’s home page affects all users that belong to that group, even if some of them already have a different home page assigned. For example, if a user belongs to the Foglight Administrators group, and you want that user to have a different home page, you can change that user’s preferences. However, changing the Foglight Administrators group preferences at a later time overwrites the user’s preferences causing that user to have the same home page as other members of the Foglight Administrators group.

When assigning home pages, it is important to take into consideration the allowed roles that are associated with individual dashboards. Although it is possible to view and select the dashboards for which a selected user or group does not generally have access permissions, doing so does not grant access to those dashboards. For example, setting the Administration dashboard as an operator’s home page results in the following message after the operator logs in to Foglight:

TIP: If you change the user preferences for all members of the selected group, then the home page changes for those users that already have a home page defined.

TIP: The default home page is the Welcome page.

TIP: The default value is Last 4 Hours.

Use the Remove Groups button on the Groups tab to remove groups from Foglight. You can only delete those groups that are added after the installation, or groups from en external directory that are selected for visibility on the Groups tab. Their types appear as Internal and External, respectively, on the Groups tab. The type of the default groups included with Foglight appears as Built-In. Built-In groups cannot be removed. Removing an external group has no effect on the external directory in which it is defined.

Alternatively, you can delete internal or external groups using the security:deleteuser fglcmd command. For more information, see the Command-Line Reference Guide.

Adding a user account to a group grants that user account access to all the roles associated with that group. You can only edit users for built-in and internal groups, but not for external groups. Adding a role to a group grants the members of that group access to any actions associated with that role.

Roles and users can be associated with a group in many different flows, for example, when creating new groups or editing existing groups. This describes the process of editing groups’ users and roles directly on the Groups tab.

On the Groups tab, the Role Names column shows the roles granted to each group, or the number of roles, if that number is higher than five. The User Names column contains the names of the users that belong to each group, or the number of users, if a group contains six or more users.

Hovering over these columns shows a list of the groups and roles associated with the group entry.

You can edit group details using a wizard. This workflow is very similar to the one used creating new groups. Start it by clicking the Name column on the Groups tab.

TIP: If access requirements associated with this user account change at a later time, you can change their users by editing the group details. For more information, see Associate groups with roles and users.

In Foglight, roles are granted to groups and individual users. A role that is assigned to a group is also assigned to each member of that group.

There are two types of roles in Foglight:

IMPORTANT: The Built-In roles cannot be deleted.

NOTE: Having the Administrator role in addition to the Core Reports role allows you access deprecated reports.

NOTE: The General Access role is not assigned to users, and cannot be used to log in.

This tab includes controls for creating new roles, deleting existing roles, editing groups, and a search tool. Clicking a group column entry allows you to quickly edit the groups that are associated with a role.

To access this tab, on the navigation panel, choose Dashboards > Administration > Users & Security. From there, to start managing user access, click Manage Users, Groups, Roles and open the Roles tab.

The Roles tab includes a wizard that allows you to create new roles and associate them with groups. The wizard is invoked using the New Role button on the Roles tab. Using this flow you can create one or more roles.

Use the Remove Roles button on the Roles tab to remove roles from Foglight. You can only delete internal roles that are added after the installation.

Granting a role to a group grants the role access to all users that are the members of that group.

Roles and groups can be associated with a group in many different flows, for example, when creating new roles or editing existing roles. This describes the process of editing roles’ groups directly on the Roles tab.

On the Roles tab, the Groups column shows the roles granted to each group, or the number of roles, if that number is higher than five.

Hovering over this column shows a list of the groups associated with the role entry.

You can edit role details using a wizard flow. This flow is very similar to the one used creating new roles. Start this flow by clicking the Name column on the Roles tab.

Foglight administrators can configure the browser interface for to control end user access to dashboards. This is done by implementing role-based permissions.

Foglight includes a set of built-in roles, such as Operator and Dashboard User, but it also allows for the creation of additional roles. New roles can be assigned to users and used to control access to dashboards. For more information about built-in roles, see Explore the Roles tab.

Every view in Foglight has Allowed and Relevant Roles. Allowed Roles act as a security mechanism. When Allowed Roles are set for a dashboard, only the users granted these roles can access that dashboard. Relevant Roles are different in that they act as a filter, indicating the roles for which the dashboard is useful.

For example, if one of your roles matches one of the Allowed Roles assigned to a dashboard, the dashboard appears listed on the navigation panel. Clicking that node displays the dashboard in the display area. If a dashboard has Allowed and Relevant Roles set, but the Relevant Roles do not match your user roles, that dashboard remains hidden (that is, it does not appear on the navigation panel). It does not appear on the navigation panel. If the Allowed Roles match your user role, you can navigate to this dashboard from another dashboard, assuming such a link exists. Similarly, if embedded or drilldown views also have Allowed and Relevant roles set, and they do not match your roles, an error message appears on the dashboard indicating that you do not have access to those views.

Portal and query access is enabled for the following user roles: Dashboard User, Operator, Advanced Operator, Dashboard Designer, and Cartridge Developer. Users with any these roles have access to the Data dashboard, accessible by choosing Configuration > Data from the navigation panel. This dashboard allows access to Foglight objects through root queries. Root queries return objects that match the query parameters. The returned objects are presented in a view best suited to the objects’ types. Thus, to restrict access to portals and root queries that populate the Data dashboard, you must ensure that the restricted user does not have any of the roles that permit access to this dashboard. Similarly, to grant access to these components, ensure that the user is granted these roles.

Granting access to selected portals and root queries involves the same process as the one for enabling access to views. Besides having the above roles granted, the assigned roles must match one of the portal’s or query’s roles. In general, this requires creating at least one new role and adding it to the portal or query, and granting that role to the user.

The following procedure gives a basic example of how to create a user account that has access to selected dashboard. The Hosts and Alarms dashboards are used in the example. First, you create a new user role, Host Access. Then, create a new user account, Host User, and grant that account the Host Access role. Next, add the Host Access role to the Hosts and Alarms dashboards and their embedded views. Follow the same process to grant access to other dashboards, as required, by adding the Host Access role to these dashboards and the embedded views. Finally, test this configuration by logging in to the browser interface as the Host User and observe the result: the Hosts page appears in the browser interface and this is the only dashboard that you can access, as required.

TIP: There is no need to select groups in this step. In this example we grant roles directly to the selected user, instead of assigning the role to a group and adding the user to the group.

TIP: In this example we grant roles directly to the selected user, instead of assigning the role to a group and adding the user to the group. That is why there is no need to select groups in this step.

TIP: If a user does not have a home page defined, a warning page appears after logging in.

TIP: The Console User role grants access to the browser interface. You need this role in addition to the Host Access role to access the Hosts page.

TIP: To navigate to the Hosts dashboard, under Homes, click Hosts.To navigate to the Alarms dashboard, under Homes, click Alarms.

TIP: When Allowed Roles are set and do not match the Relevant Roles, access to this dashboard is disabled to those users that have those Relevant Roles.