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

Monitoring 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

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/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. OpenAM MBeans in a browser You can monitor OpenAM through a web browser.

Monitoring JMX You can configure OpenAM to allow you to listen on port 9999 for JMX 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-rmi-enabled=true You can then use jconsole or other JMX-enabled tools to browse the MBeans. You can also browse the MBeans by connecting to your web application container, and browsing to the OpenAM MBeans. Jconsole browsing OpenAM MBeans You can monitor OpenAM over JMX.

Monitoring SNMP 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

Monitoring Health check 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 up.

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

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. Debug logging Level 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. Debug logging Single file 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.

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.

Debug logging Service selection 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. Login to OpenAM console as administrator, amadmin. Browse to Debug.jsp, for example http://openam.example.com:8080/openam/Debug.jsp. No links to this page are provided in the console. Select the service to debug and also the level required given the hints provided in the Debug.jsp page. The change takes effect immediately. Promptly reproduce the problem you are investigating. 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.

Debug logging Rotation 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.

Sessions OpenAM console lets the administrator view and manage current user sessions under the Sessions tab page. Session management tab page The OpenAM Administrator can view and end user sessions. 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.