Chapter 17. Monitoring OpenAM Services
Prev |  | Next

# Chapter 17. Monitoring OpenAM Services

This chapter covers how to monitor OpenAM services to ensure appropriate performance and service availability.

## 17.1. Monitoring Interfaces

OpenAM lets you monitor OpenAM over protocol through web pages, Java Management Extensions (JMX), or Simple Network Management Protocol (SNMP). The services are based on JMX.

To configure monitoring services, login to OpenAM console as OpenAM administrator, and browse to Configuration > System > Monitoring. Alternatively you can use the ssoadm set-attr-defs command.

    $ ssoadm
     set-attr-defs
     --servicename iPlanetAMMonitoringService
     --schematype Global
     --adminid amadmin
     --password-file /tmp/pwd.txt
     --attributevalues iplanet-am-monitoring-enabled=true

Restart OpenAM for the changes to take effect. You must also restart OpenAM if you disable monitoring.

### 17.1.1. Web Based Monitoring

You can configure OpenAM to allow you to access a web based view of OpenAM MBeans on port 8082 where the core server runs, such as `http://openam-ter.example.com:8082/`. Either use the console, or use the ssoadm command.

    $ ssoadm
     set-attr-defs
     --servicename iPlanetAMMonitoringService
     --schematype Global
     --adminid amadmin
     --password-file /tmp/pwd.txt
     --attributevalues iplanet-am-monitoring-http-enabled=true

The default authentication file allows you to authenticate over HTTP as user `demo`, password `changeit`. The user name and password are kept in the file specified, with the password encrypted.

    $ cat openam/openam/openam_mon_auth
    demo AQICMBCKlwx6G3vzK3TYYRbtTpNYAagVIPNP

Or

    $ cat openam/openam/opensso_mon_auth
    demo AQICvSe+tXEg8TUUT8ekzHb8IRzVSvm1Lc2u

You can encrypt a new password using the ampassword command. After changing the authentication file, you must restart OpenAM for the changes to take effect.

[D]

### 17.1.2. JMX Monitoring

You can configure OpenAM to allow you to listen for Java Management eXtension (JMX) clients, by default on port 9999. Either use the OpenAM console page under Configuration > System > Monitoring and make sure both Monitoring Status and Monitoring RMI interface status are both set to Enabled, or use the ssoadm command.

    $ ssoadm
     set-attr-defs
     --servicename iPlanetAMMonitoringService
     --schematype Global
     --adminid amadmin
     --password-file /tmp/pwd.txt
     --attributevalues iplanet-am-monitoring-enabled=true
     iplanet-am-monitoring-rmi-enabled=true

A number of tools support JMX, including jvisualvm and jconsole. When you use jconsole to browse OpenAM MBeans for example, the default URL for the OpenAM running on the local system is `service:jmx:rmi:///jndi/rmi://localhost:9999/server`.

    $ jconsole service:jmx:rmi:///jndi/rmi://localhost:9999/server &

You can also browse the MBeans by connecting to your web application container, and browsing to the OpenAM MBeans. By default, JMX monitoring for your container is likely to be accessible only locally, using the process ID.

[D]

Also see Monitoring and Management Using JMX for instructions on how to connect remotely, how to use SSL, and so forth.

### 17.1.3. SNMP Monitoring

You can configure OpenAM to allow you to listen on port 8085 for SNMP monitoring. Either use the console, or use the ssoadm command.

    $ ssoadm
     set-attr-defs
     --servicename iPlanetAMMonitoringService
     --schematype Global
     --adminid amadmin
     --password-file /tmp/pwd.txt
     --attributevalues iplanet-am-monitoring-snmp-enabled=true

## 17.2. Is OpenAM Running?

You can check over HTTP whether OpenAM is up, using `isAlive.jsp`. Point your application to the file under the OpenAM URL, such as `http://openam.example.com:8080/openam/isAlive.jsp`.

If you get a success code (with `Server is ALIVE:` in the body of the page returned), then OpenAM is in operation.

## 17.3. Log Management

OpenAM implements logging as a service. This means remote clients such as your OpenAM policy agents can log messages to the central logging service.

### 17.3.1. Logging in OpenAM Core Services

By default OpenAM logs to files in the configuration directory for the instance, such as `$HOME/openam/log/` for log files, and `$HOME/openam/debug/` for debug files. You can also configure OpenAM to log through JDBC to a database such as MySQL or Oracle DB.

OpenAM sends messages to different log files, each named after the service logging the message, with two different types log files per service: `.access` and `.error`. Thus the current log files for the authentication service are named `amAuthentication.access` and `amAuthentication.error`.

See the Log Messages reference for details.

OpenAM lets you change the log level on the fly. OpenAM also supports log rotation, secure logging, and log message buffering.

To configure OpenAM logging properties overall, login to the OpenAM console as OpenAM administrator, and browse to Configuration > System > Logging.

To adjust the debug level while OpenAM is running, login to the OpenAM console as OpenAM administrator, and browse to Configuration > Servers and Sites > `Server Name` > General, and then scroll down to Debugging. The default level for debug logging is Error. This level is appropriate for normal production operations, in which case no debug log messages are expected.

Setting debug log level to Warning increases the volume of messages. Setting debug log level to Message dumps detailed trace messages. Unless told to do so by qualified support personnel, do not use Warning and Message levels in production.

During development, you might find it useful to log all debug messages to a single file. In order to do so, set Merge Debug Files to `on`.

After changing this setting, restart OpenAM or the container in which it runs for the change to take effect.

### 17.3.2. Logging in OpenAM Policy Agents

By default, OpenAM Policy Agents log to local files in their configuration directories for debugging. The exact location depends on where you installed the agent.

By default OpenAM policy agents send log messages remotely to OpenAM when you log auditing information about URL access attempts. To configure audit logging for a centrally managed policy agent, login to the OpenAM console as administrator, and browse to Access Control > `Realm Name` > Agents > `Agent Type` > `Agent Name` > Global, and then scroll down to the Audit section.

### 17.3.3. Debug Logging by Service

OpenAM lets you capture debug log messages selectively for a specific service. This can be useful when you must turn on debugging in a production system where you want to avoid excessive logging, but must gather messages when you reproduce a problem.

Perform these steps to capture debug messages for a specific service.

1. Login to OpenAM console as administrator, `amadmin`.

2. Browse to `Debug.jsp`, for example `http://openam.example.com:8080/openam/Debug.jsp`.

   No links to this page are provided in the console.

3. Select the service to debug and also the level required given the hints provided in the `Debug.jsp` page.

   The change takes effect immediately.

4. Promptly reproduce the problem you are investigating.

5. After reproducing the problem, immediately return to the `Debug.jsp` page, and revert to normal log levels to avoid filling up the disk where debug logs are stored.

### 17.3.4. Rotating Debug Logs

By default OpenAM does not rotate debug logs. To rotate debug logs, edit `WEB-INF/classes/debugconfig.properties` where OpenAM is deployed.

The `debugconfig.properties` file includes the following properties.

`org.forgerock.openam.debug.prefix`

  This property specifies the debug log file prefix applied when OpenAM rotates a debug log file. The property has no default. It takes a string as the property value.

`org.forgerock.openam.debug.suffix`

  This property specifies the debug log file suffix applied when OpenAM rotates a debug log file. The property takes a `SimpleDateFormat` string. The default is `-MM.dd.yyyy-kk.mm`.

`org.forgerock.openam.debug.rotation`

  This property specifies an interval in minutes between debug log rotations. Set this to a value greater than zero to enable debug log rotation.

After you edit the `debugconfig.properties` file, you must restart OpenAM or the web container where it runs for the changes to take effect.

## 17.4. Session Management

OpenAM console lets the administrator view and manage current user sessions under the Sessions tab page.

[D]

To end a user session manually, select the user's session, and then click the Invalidate Session button. As a result, the user has to authenticate again.

Prev |  | Next
Chapter 16. Managing Certificates | Home | Chapter 18. Tuning OpenAM