Table of Contents

Introduction to the Sun GlassFish Web Stack Enterprise Manager

Sun GlassFish Web Stack Enterprise Manager (Enterprise Manager) is a browser-based software application to monitor the health and availability of the Sun GlassFish Web Stack (Web Stack) components.

The Enterprise Manager provides availability, response time, and performance monitoring metrics by retrieving the information from the Web Stack components like the Apache Web Server and the MySQL Server at regular intervals.

The Enterprise Manager gathers statistics about the running servers and depicts the statistics through graphs. These statistics can then be used to find current performance bottlenecks and predict future system loads.

The Enterprise Manager is not yet available for OpenSolaris 2009.06.

Note The Enterprise Manager can only monitor servers co-existing in the same installation.

Enterprise Manager Features

Sun GlassFish Web Stack Enterprise Manager includes the following monitoring and management features:

• Server System Monitoring - Enterprise Manager provides dashboard widgets that monitors server RAM and CPU usage.
• Life Cycle Support - Enterprise Manager provides the Life Cycle Support (Starting/Stopping/Restarting) for the Sun GlassFish Web Stack server components.
• Web Stack Server Component Monitoring - Enterprise Manager provides various graphs, which gathers the status of the installed servers, overall resource utilization gauges and basic vital statistics.

The Enterprise Manager supports monitoring of the following Web Stack components:

• Apache Web Server
• MySQL Server
• lighttpd Server
• Squid Proxy Server
• memcached Server
• Tomcat Web Server

Installing the Enterprise Manager

Follow the standard installation procedure provided in the Sun GlassFish Web Stack Installation and Configuration Guide.

Install the Enterprise Manager packages by invoking the following command (as a root user):

# ./install admin

The Enterprise Manager will be installed in the following location:

• Application Directory - OPT_ROOT/admin
• Configuration Directory - ETC_ROOT/admin
• Data Directory - VAR_ROOT/admin
• Log Directory - VAR_ROOT/admin/logs

The OPT_ROOT, ETC_ROOT, and VAR_ROOT are defined in the Sun GlassFish Web Stack Installation and Configuration Guide.

Starting the Enterprise Manager

The following table shows how you can start/stop the Enterprise Manager in different supported platforms:

Warning In the Red Hat Enterprise Linux Unbundled IPS/pkg(5) distribution, you need to add the OPT_ROOT/bin in the PATH variable before starting the Enterprise Manager service. Failing to do so will make the Enterprise Manager inaccessible.

Using the Enterprise Manager

The Enterprise Manager Dashboard is the central location where you can monitor and configure the Sun GlassFish Web Stack components. To access the Dashboard, access the following location from your web browser:

https://<Server Host Name/IP Address>:8484

In the login screen enter the user name and password as described here:

• Enterprise Manager running as root user. If you have started the Enterprise Manager as a root user, enter the root user name and password in the login screen. However, if you need to allow other users of the system to use the Enterprise Manager, read the Allowing Users to Access the Enterprise Manager section.
• Enterprise Manager running as non-root user. For instance, Unbundled IPS/pkg(5) distribution. If you have started the Enterprise Manager as a non-root user, enter the user name and password provided during the first login to the Enterprise Manager.

Note While accessing the Dashboard you may be presented with the "Invalid security certificate error" or similar error. This is a normal behavior and happens because of the self-signed certificate.

The Enterprise Manager Dashboard

The Enterprise Manager Dashboard is divided into the following sections:

• Sidebar - Sidebar contains the system usage dials and the server controls.
• Toolbar - Toolbar contains the various tools to work with the Dashboard. This includes the Navigation and the "Add Graphs" drop down list.
• Graph Area - This is the place where all the monitoring graphs will be added.
• Recent Alerts - Recent Alerts shows the Sun GlassFish Web Stack Enterprise Manager's alerts and activities.

The Sidebar

The server configuration controls and the usage dials are available in the Sidebar section of the Dashboard.

You can start/stop the servers from this sidebar.

The sidebar lists only the servers that are installed through the Web Stack. If you have installed the Web Stack through the ./install amp option, you will see only the Apache, MySQL 5.1, and lighttpd entries under the Server sub-section. For monitoring other Web Stack components like memcached and Apache Tomcat Server, install the respective components.

From the sidebar, you can perform the following actions:

• View the memory and CPU usage.
• Start/stop the servers.
• Restart the servers.
• Enable/Disable monitoring for the servers.
• View if the servers are in the maintenance mode (Solaris 10 OS only).

The Toolbar

The Toolbar provides various control options to work with the Dashboard. This includes the Dashboard navigation and the "Add Graphs" drop down list. If you are using a time restricted evaluation copy of the Enterprise Manager, number of days remaining for the evaluation license to expire is shown in the Toolbar area.

There are buttons in the Toolbar, which will let you perform the following actions:

• Switch between the Dashboard and the Analytics view.
• Logout from the Enterprise Manager.
• Read the Online Help.

The Graph Area

The Graph area is the place where you can add the graphs when you are in the Dashboard view or the Analytics view.

To add a graph, click the Add Graphs drop down list from the Toolbar. A list of graphs available for the server for that particular view will appear in the drop down list. Click the graph name to make it appear on the Graph Area.

Click the graph or click the magnification glass icon button on the graph to switch to the Analytics view.

Note The graph list might change depending on the selected view. For instance, the Apache Web Server's Scoreboard graph provides various server statistics and is only available in the Analytics view.

You can add a graph only when:

• The servers are running.
• Monitoring has been enabled for the servers.
• There is server data available to generate the graph.

The X axis unit of the graph is the time of day and the Y axis of the graph changes based on the type of graph added to the Graph Area.

Note that the graphs uses the SI notation to scale the values on Y-axis to the appropriate units. The units are as follows:

• kilo - k
• mega - M
• giga - G
• tera - T
• milli - m

Sometimes the graph may show a red alert icon on the top right corner signifying that the server is offline or not available due to other reasons.

You are advised to start the respective server for the graph to show the correct statistics.

The Recent Alerts

When the user starts/stops the server or perform any other action from the Dashboard, the status message is displayed in this area.

The recent alerts area also displays detailed server startup messages and errors.

Different Graph Views

The are two supported views for graphs in the Dashboard:

1. Dashboard View - The default view. You can use this view to add graphs for monitoring the various Web Stack components.
2. Analytics View - The advanced view. You can use this view to add detailed graphs providing more component level metrics.

Dashboard View

The Dashboard view is the default view for viewing the graphs.

The following figure shows the graphs in the Dashboard view:

Analytics View

The Enterprise Manager provides a more detailed view of the graphs in the Analytics view.

The Analytics view can be invoked by any one of the following methods:

• Using the Analytics Button - In Dashboard view, click the Analytics button available on the top right corner of the page to switch to the Analytics view.
• From the Dashboard Graph - In Dashboard view, clicking any graph will switch the graph to the Analytics view.

The following figure shows a graph in the Analytics view:

You can use the following options in the Analytics view:

• Timed Data - You can use the or icons to traverse the time line.
• Synchronized Graphs - There is a synchronize button available on the graphs, which when clicked will cause all the graphs on the page to synchronize with the current graph (anchor graph). This will cause all the graphs to show the same time period as the anchor graph. Moving back or forward on any graph will cause all other graphs to move back and forward synchronously.

Enabling/Disabling Monitoring

For graphs to be added for a particular server, monitoring needs to be enabled. You can enable/disable monitoring from the sidebar by clicking the settings icon after the server name.

The following figure shows how you can turn on monitoring for the Apache Web Server:

Whenever you turn on monitoring, you need to restart the server for adding the graphs. The Enterprise Manager shows a dialog box from where you can restart the server.

For enabling MySQL Server monitoring, you need to additionally provide the DB root user name and password:

Logging

The Enterprise Manager log files provides information about the requests that have been served and the errors that might have occured while accessing the Enterprise Manager.

The log files are available at VAR_ROOT/admin/logs. See this document for more information on the directory layout for your platform.

There are three log files and their descriptions are given below:

1. access.log - Logs all the requests that have been served with URI and response status.
2. error.log - Contains all the Enterprise Manager's server process error messages.
3. admin.log - Enterprise Manager's error log (The log level can be specified as shown in the later section).

Changing the Log Level

The log level can be configured to control the extent of logging by the Enterprise Manager. To change the logging level edit the ETC_ROOT/admin/admin.conf file. In the [globals] section, modify the log-level value.

...
[globals]
# debug,info,warning,error (default: info)
log-level=info
...

There are multiple log levels that control the amount of data to be logged. The debug level should be used to gather debugging data, which is useful for troubleshooting the Enterprise Manager.

Configuring the Enterprise Manager

The configuration files for the Enterprise Manager are located in the ETC_ROOT/admin directory. The configuration files can be modified to change the log level, authentication mechanism, user authorization, session timeout, and Enterprise Manager's SSL and listen port.

You can modify the following configuration files:

• ETC_ROOT/admin/admin.conf - Controls log level, authentication mechanism, user authorization and session timeout.
• ETC_ROOT/admin/server.conf - The configuration file of the Enterprise Manager server process. Controls the SSL and the listen port of the Enterprise Manager.
• ETC_ROOT/admin/collectd/collectd.conf - This file should only be edited to change the network plugin's listen port.

Changing the Default Ports

For multiple installations of the Enterprise Manager to work on the same machine, you must change the server port (8484) and the collectd port (25826). To change the default listen ports, perform the following tasks:

1. Edit the ETC_ROOT/admin/collectd/collectd.conf file. Change the default value (25826) to any other value.

   ...
   LoadPlugin network
   <Plugin network>
       Listen "localhost" "25826"
   </Plugin>
   ...
   

2. Edit the ETC_ROOT/admin/server.conf file. Change the default value (8484) to any other value.

   ...
   server.port = 8484
   ...
   

Note that you should be a privileged user to start the Enterprise Manager on certain ports (For instance, ports < 1024).

The collectd port corresponds to the port in the jcd.dest property that needs to be set for enabling monitoring for the Apache Tomcat Server. Whenever you change the default collectd port, make sure that you change the value of the jcd.dest property too.

Configuring the Session Timeout

By default, the login session will timeout after 1 hour of inactivity. However, the session duration can be modified by setting the timeout property (in seconds) under the session section of the ETC_ROOT/admin/admin.conf file.

...
[session]
# in seconds (default: 3600)
#timeout=3600
...

Authentication

The Enterprise Manager supports the following authentication mechanisms:

• none - No authentication (login not required).
• pam - Use any system username and it's corressponding password. Default for root user.
• file - Users are defined in the ETC_ROOT/admin/passwd file. Users can be added to this file by executing the OPT_ROOT/admin/bin/wsuseradd command. Default for non-root user.

Note In Unbundled IPS/pkg(5) distribution, when the Enterprise Manager is started for the first time as a non-root user, the user is prompted to add a login username and password.

Adding a User for the Enterprise Manager

To add a user to the ETC_ROOT/admin/passwd file, you need to execute the following command:

# OPT_ROOT/admin/bin/wsuseradd
Please specify a username and password required to access Web Stack Enterprise Managaer
Enter user name: User1
Password:
Confirm Password:

Authorization

For any authentication mechanism, login rights might be restricted to a specified list of users. By default, only the username that the Enterprise Manager is running as is allowed to login. A comma separated list of user names might be mentioned for restricting login to only these user names. The * character might be used to allow all the valid users.

Allowing Users to Access the Enterprise Manager

The user authorization works per-authentication mechanism. So add/edit a section with the authentication mechanism name ([pam] or [file]). Authentication mechanism 'none' doesn't have a section. In the ETC_ROOT/admin/admin.conf file, under the relevant authentication section, define the property allow-users as shown below:

	[globals]
	...
	# auth=pam OR auth=file
        auth=pam

	[pam]
	allow-users=user1,user2,...

	[file]
	allow-users=*

Try the Evaluation Copy of the Enterprise Manager

The evaluation copy of the Enterprise Manager expires in 30 days. If you want to continue using the Enterprise Manager, you need to purchase the Sun GlassFish Portfolio Subsciption.

After purchasing the Sun GlassFish Portfolio Subscription, you will be provided with the download link to the package called sun-wsadmin-license. This package will enable the restriction-free mode of the Enterprise Manager. Execute the following command to install the license package:

./install sun-wsadmin-license

After installing the license package, you need to restart the Enterprise Manager Service to apply the changes.

When you are evaluating the Enterprise Manager, the Toolbar shows the number of days left before which you need to purchase a license.

Help

For detailed information on Sun GlassFish Web Stack components please see the Documentation.