Access Management 7.3.2

SNMP monitoring

The interface stability of this legacy feature is deprecated.

SNMP depends on labels known as Object Identifiers (OIDs). These are uniquely defined labels, organized in tree format. For AM, they are configured in a .mib file named FORGEROCK-OPENAM-CTS.mib, found inside the /path/to/tomcat/webapps/openam/WEB-INF/lib/openam-mib-schema-<version>.jar file of the AM deployment.

For detailed information on configured OIDs, refer to SNMP CTS object identifiers.

With the OIDs in hand, you can set up an SNMP server to collect the data. You would also need SNMP utility commands with associated OIDs to measure the current state of a component.

Enable SNMP monitoring

  1. Stop the AM instance or the container where it runs.

  2. Download the AM ZIP file from the ForgeRock BackStage download site.

  3. Extract the contents of the ZIP file.

  4. Go to the /snmp folder, and run the opendmk.jar installer file. For example:

    $ java -jar opendmk.jar

  5. Accept the License Agreement.

  6. Select the directory you want to install to.

    For example: /tmp/opendmk.

  7. Copy the jdmkrt.jar file from the /lib folder of the extracted archive to the AM /WEB-INF/lib folder.

    For example:

    $ cp /tmp/opendmk/OpenDMK-bin/lib/jdmkrt.jar /path/to/openam.war/WEB-INF/lib

  8. Restart the AM instance or the container in which it runs.

  9. Go to Configure > Global Services > Monitoring.

  10. Set Monitoring Status to enabled.

  11. Set Monitoring SNMP interface status to enabled.

    By default, AM listens on port 8085 for SNMP monitoring.

  12. Save your work.

  13. Restart the AM instance for the change to take effect.

Once enabled, SNMP monitoring works over UDP by default. You may want to install one of many available network monitoring tools. For the purpose of this section, basic SNMP service and monitoring tools have been installed on a Unix-like system.

First, to verify the operation of SNMP on a GNU/Linux system, run the following command over port 8085 using SNMP version 2c:

# snmpstatus -c public -v 2c localhost

The output should specify communications over UDP. If you get a timeout message, the SNMP service may not be running.

You can get the value for a specific OID. For example, the following command retrieves the cumulative count for CTS create operations, over port 8085:

# snmpget -c public -v 2c :8085 enterprises.36733.1.2.3.3.1.1.1

If your version of the tool does not support the enterprises OID string, use 1.3.6.1.4.1 instead, as in 1.3.6.1.4.1.36733.1.2.3.3.1.1.1.

For one view of the tree of OIDs, you can use the snmpwalk command. For example, the following command lists all OIDs related to CTS:

# snmpwalk -c public -v 2c :8085 enterprises.36733.1.2.3

A number of CTS OIDs are listed with a Counter64 value. As defined in RFC 2578, an OID so configured has a maximum value of 264 - 1.

SNMP monitoring for sessions

You can monitor server-side session statistics over SNMP. AM records statistics for up to a configurable number of recent sessions. (You can configure the number in the AM admin UI under Configuration > System > Monitoring. For details, refer to the system configuration reference section, Monitoring.)

SNMP monitoring is not available for client-side sessions.

SNMP uses OIDs defined in a .mib file that specifies the statistics AM keeps for policy evaluation operations, the FORGEROCK-OPENAM-SESSION.mib file. This file is found inside the /path/to/tomcat/webapps/openam/WEB-INF/lib/openam-mib-schema-<version>.jar file of the AM deployment.

When monitoring is active, AM records statistics about both the numbers of internal, remote, and CTS sessions, and also the times taken to process sessions.

The statistics are all read-only. The base OID for session statistics is enterprises.36733.1.2.1. Times are expressed in nanoseconds rather than milliseconds, as many operations take less than one millisecond. The following table describes the values that you can read:

OIDs used in SNMP session monitoring
OID Description Syntax

enterprises.36733.1.2.1.1.1

Total number of current internal sessions

Counter64

enterprises.36733.1.2.1.1.2

Average time it takes to refresh an internal session

Counter64

enterprises.36733.1.2.1.1.3

Average time it takes to logout an internal session

Counter64

enterprises.36733.1.2.1.1.4

Average time it takes to destroy an internal session

Counter64

enterprises.36733.1.2.1.1.5

Average time it takes to set a property on an internal session

Counter64

enterprises.36733.1.2.1.2.1

Total number of current remote sessions

Counter64

enterprises.36733.1.2.1.2.2

Average time it takes to refresh a remote session

Counter64

enterprises.36733.1.2.1.2.3

Average time it takes to logout a remote session

Counter64

enterprises.36733.1.2.1.2.4

Average time it takes to destroy a remote session

Counter64

enterprises.36733.1.2.1.2.5

Average time it takes to set a property on a remote session

Counter64

enterprises.36733.1.2.1.3.1

Total number of sessions currently in the Core Token Service (CTS)

Counter64

enterprises.36733.1.2.1.3.2

Average time it takes to refresh a CTS session

Counter64

enterprises.36733.1.2.1.3.3

Average time it takes to logout a CTS session

Counter64

enterprises.36733.1.2.1.3.4

Average time it takes to destroy a CTS session

Counter64

enterprises.36733.1.2.1.3.5

Average time it takes to set a property on a CTS session

Counter64

SNMP monitoring for policy evaluation

You can monitor policy evaluation performance over SNMP. AM records statistics for up to a number of recent policy evaluation requests. (You can configure the number in the AM admin UI under Configuration > System > Monitoring.) For details, refer to Monitoring.

SNMP uses OIDs defined in the .mib file, FORGEROCK-OPENAM-POLICY.mib, found inside the /path/to/tomcat/webapps/openam/WEB-INF/lib/openam-mib-schema-<version>.jar file of the AM deployment. This file specifies the statistics AM keeps for policy evaluation operations.

When monitoring is active, AM records statistics about the numbers and rates of policy evaluations performed, and the time taken to process policy evaluations.

The statistics are all read-only. The base OID for policy evaluation statistics is enterprises.36733.1.2.2.1. The following table describes the values that you can read:

OIDs used in SNMP monitoring for policy evaluation
OID Description Syntax

enterprises.36733.1.2.2.1.1.1

Cumulative number of policy evaluations for specific resources (self)

Counter64

enterprises.36733.1.2.2.1.1.2

Average rate of policy evaluations for specific resources (self)

Counter64

enterprises.36733.1.2.2.1.1.3

Minimum rate of policy evaluations for specific resources (self)

Counter64

enterprises.36733.1.2.2.1.1.4

Maximum rate of policy evaluations for specific resources (self)

Counter64

enterprises.36733.1.2.2.1.2.1

Cumulative number of policy evaluations for a tree of resources (subtree)

Counter64

enterprises.36733.1.2.2.1.2.2

Average rate of policy evaluations for a tree of resources (subtree)

Counter64

enterprises.36733.1.2.2.1.2.3

Minimum rate of policy evaluations for a tree of resources (subtree)

Counter64

enterprises.36733.1.2.2.1.2.4

Maximum rate of policy evaluations for a tree of resources (subtree)

Counter64

enterprises.36733.1.2.2.1.1.2

Average length of time to evaluate a policy for a specific resource (self)

Counter64

enterprises.36733.1.2.2.2.1.2

Slowest evaluation time for a specific resource (self)

SnmpAdminString

enterprises.36733.1.2.2.1.2.2.1

Average length of time to evaluate a policy for a tree of resources (subtree)

Counter64

enterprises.36733.1.2.2.1.2.2.2

Slowest evaluation time for a tree of resources (subtree)

SnmpAdminString

enterprises.36733.1.2.2.1.3.1

Slowest individual policy evaluation time overall

SnmpAdminString