This chapter covers how to monitor OpenAM services to ensure appropriate performance and service availability.
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.
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.
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.
Also see Monitoring and Management Using JMX for instructions on how to connect remotely, how to use SSL, and so forth.
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
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.
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.
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.
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.
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 examplehttp://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.jsppage.The change takes effect immediately.
Promptly reproduce the problem you are investigating.
After reproducing the problem, immediately return to the
Debug.jsppage, and revert to normal log levels to avoid filling up the disk where debug logs are stored.
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.prefixThis 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.suffixThis property specifies the debug log file suffix applied when OpenAM rotates a debug log file. The property takes a
SimpleDateFormatstring. The default is-MM.dd.yyyy-kk.mm.org.forgerock.openam.debug.rotationThis 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.
