21.10. Monitoring Directory Server Using SNMP

The server and database activity monitoring log setup described in Chapter 21, Monitoring Server and Database Activity is specific to Directory Server. You can also monitor your Directory Server using Simple Network Management Protocol (SNMP), which is a management protocol used for monitoring network activity which can be used to monitor a wide range of devices in real time.
Directory Server can be monitored with SNMP through an AgentX subagent. SNMP monitoring collects useful information about the Directory Server, such as bind information, operations performed on the server, and cache information. The Directory Server SNMP subagent supports SNMP traps to send notifications about changes in the running state of your server instances.

21.10.1. About SNMP

SNMP has become interoperable on account of its widespread popularity. It is this interoperability, combined with the fact that SNMP can take on numerous jobs specific to a whole range of different device classes, that make SNMP the ideal standard mechanism for global network control and monitoring. SNMP allows network administrators to unify all network monitoring activities, with Directory Server monitoring part of the broader picture.
SNMP is used to exchange data about network activity. With SNMP, data travels between a managed device and a network management application (NMS) where users remotely manage the network. A managed device is anything that runs SNMP, such as hosts, routers, and your Directory Server. An NMS is usually a powerful workstation with one or more network management applications installed. A network management application graphically shows information about managed devices, which device is up or down, which and how many error messages were received, and so on.
Information is transferred between the NMS and the managed device through the use of two types of agents: the subagent and the master agent. The subagent gathers information about the managed device and passes the information to the master agent. Directory Server has a subagent. The master agent exchanges information between the various subagents and the NMS. The master agent usually runs on the same host machine as the subagents it talks to, although it can run on a remote machine.
Values for SNMP attributes, otherwise known as variables, that can be queried are kept on the managed device and reported to the NMS as necessary. Each variable is known as a managed object, which is anything the agent can access and send to the NMS. All managed objects are defined in a management information base (MIB), which is a database with a tree-like hierarchy. The top level of the hierarchy contains the most general information about the network. Each branch underneath is more specific and deals with separate network areas.
SNMP exchanges network information in the form of protocol data units (PDUs). PDUs contain information about variables stored on the managed device. These variables, also known as managed objects, have values and titles that are reported to the NMS as necessary. Communication between an NMS and a managed device takes place either by the NMS sending updates or requesting information or by the managed object sending a notice or warning, called a trap, when a server shuts down or starts up.

21.10.2. Enabling and Disabling SNMP Support

By default, the SNMP protocol is enabled in Directory Server and, after configuring the subagent, you can use it.
To enable or disable SNMP in an instance, set the nsSNMPEnabled parameter to on or off. For example, to disable SNMP in a Directory Server instance: 
# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x

dn: cn=SNMP,cn=config
changetype: modify
replace: nsSNMPEnabled
nsSNMPEnabled: on

21.10.3. Setting Parameters to Identify an Instance Using SNMP

Directory Server provides the following attributes which help identifying instances using SNMP:
  • nsSNMPOrganization
  • nsSNMPLocation
  • nsSNMPContact
  • nsSNMPDescription
For details about the parameters, see their descriptions in the cn=SNMP section in the Red Hat Directory Server Configuration, Command, and File Reference.
For example, to the set the nsSNMPLocation parameter to Munich, Germany: 
# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x

dn: cn=SNMP,cn=config
changetype: modify
replace: nsSNMPLocation
nsSNMPLocation: Munich, Germany

21.10.4. Setting up an SNMP Agent for Directory Server

To query information from Directory Server using the SNMP protocol, set up an SNMP agent:
  1. Install the 389-ds-base-snmp and net-snmp packages: 
    # dnf install 389-ds-base-snmp net-snmp
  2. To configure the SNMP master agent, edit the /etc/snmp/snmpd.conf file, adding the following entry to enable the agent extensibility (AgentX) protocol: 
    master agentx
    For further details about the AgentX protocol, see RFC 2741.
  3. To configure the SNMP subagent, edit the /etc/dirsrv/config/ldap-agent.conf file, adding a server parameter for each Directory Server instance you want to monitor. For example: 
    server slapd-instance_name
  4. Optionally, create an SNMP user account:
    1. Stop the snmpd service: 
      # systemctl stop snmpd
    2. Create the SNMP user account. For example: 
      # net-snmp-create-v3-user -A authentication_password -a SHA \
     -X private_password -x AES user_name
      For details about the parameters used in the command, see the net-snmp-create-v3-user(1) man page.
    3. Start the snmpd service: 
      # systemctl start snmpd
  5. Optionally, set the Directory Server descriptive properties. For details, see Section 21.10.3, “Setting Parameters to Identify an Instance Using SNMP”.
  6. Start the dirsrv-snmp service: 
    # systemctl start dirsrv-snmp
  7. Optionally, to verify the configuration:
    1. Install the net-snmp-utils package: 
      # dnf install net-snmp-utils
    2. Query the Directory Server Object Identifiers (OID). For example: 
      # snmpwalk -v3 -u user_name -M /usr/share/snmp/mibs:/usr/share/dirsrv/mibs/ \
     -l AuthPriv -m +RHDS-MIB -A authentication_password -a SHA
     -X private_password -x AES server.example.com .1.3.6.1.4.1.2312.6.1.1
For further details about SNMP, see the Monitoring Performance with Net-SNMP section in the Red Hat System Administrator's Guide.

21.10.5. Configuring SNMP Traps

An SNMP trap is essentially a threshold which triggers a notification if it is encountered by the monitored server. To use traps, the master agent must be configured to accept traps and do something with them. For example, a trap can trigger an email notification for an administrator of the Directory Server instance stops.
The subagent is only responsible for sending the traps to the master agent. The master agent and a trap handler must be configured according to the documentation for the SNMP master agent you are using.
Traps are accompanied by information from the Entity Table, which contains information specific to the Directory Server instance, such as its name and version number. The Entity Table is described in Section 21.10.6.3, “Entity Table”. This means that the action the master agent takes when it receives a trap is flexible, such as sending an email to an email address defined in the dsEntityContact variable for one instance while sending a notification to a pager number in the dsEntityContact variable for another instance.
There are two traps supported by the subagent:
  • DirectoryServerDown. This trap is generated whenever the subagent detects the Directory Server is potentially not running. This trap will be sent with the Directory Server instance description, version, physical location, and contact information, which are detailed in the dsEntityDescr, dsEntityVers, dsEntityLocation, and dsEntityContact variables.
  • DirectoryServerStart. This trap is generated whenever the subagent detects that the Directory Server has started or restarted. This trap will be sent with the Directory Server instance description, version, physical location, and contact information, which are detailed in the dsEntityDescr, dsEntityVers, dsEntityLocation, and dsEntityContact variables.

21.10.6. Using the Management Information Base

The Directory Server's MIB is a file called redhat-directory.mib stored in the /usr/share/dirsrv/mibs directory. This MIB contains definitions for variables pertaining to network management for the directory. These variables are known as managed objects. Using the directory MIB and Net-SNMP, you can monitor your directory like all other managed devices on your network. For more information on using the MIB, see Section 21.10.4, “Setting up an SNMP Agent for Directory Server”.
The client tools need to load the Directory Server MIB to use the variable names listed in the following sections.
Using the directory MIB enables administrators to use SNMP to see administrative information about the directory and monitor the server in real-time. The directory MIB is broken into four distinct tables of managed objects:

Note

All of the Directory Server attributes monitored by SNMP use 64-bit integers for the counters, even on 32-bit systems.

21.10.6.1. Operations Table

The Operations Table provides statistical information about Directory Server access, operations, and errors. Table 21.1, “Operations Table: Managed Objects and Descriptions” describes the managed objects stored in the Operations Table of the redhat-directory.mib file.

Table 21.1. Operations Table: Managed Objects and Descriptions

Managed Object Description
dsAnonymousBinds The number of anonymous binds to the directory since server startup.
dsUnauthBinds The number of unauthenticated binds to the directory since server startup.
dsSimpleAuthBinds The number of binds to the directory that were established using a simple authentication method (such as password protection) since server startup.
dsStrongAuthBinds The number of binds to the directory that were established using a strong authentication method (such as TLS or a SASL mechanism like Kerberos) since server startup.
dsBindSecurityErrors The number of bind requests that have been rejected by the directory due to authentication failures or invalid credentials since server startup.
dsInOps The number of operations forwarded to this directory from another directory since server startup.
dsReadOps The number of read operations serviced by this directory since application start. The value of this object will always be 0 because LDAP implements read operations indirectly using the search operation.
dsCompareOps The number of compare operations serviced by this directory since server startup.
dsAddEntryOps The number of add operations serviced by this directory since server startup.
dsRemoveEntryOps The number of delete operations serviced by this directory since server startup.
dsModifyEntryOps The number of modify operations serviced by this directory since server startup.
dsModifyRDNOps The number of modify RDN operations serviced by this directory since server startup.
dsListOps The number of list operations serviced by this directory since server startup. The value of this object will always be 0 because LDAP implements list operations indirectly using the search operation.
dsSearchOps The total number of search operations serviced by this directory since server startup.
dsOneLevelSearchOps The number of one-level search operations serviced by this directory since server startup.
dsWholeSubtreeSearchOps The number of whole subtree search operations serviced by this directory since server startup.
dsReferrals The number of referrals returned by this directory in response to client requests since server startup.
dsSecurityErrors The number of operations forwarded to this directory that did not meet security requirements.
dsErrors The number of requests that could not be serviced due to errors (other than security or referral errors). Errors include name errors, update errors, attribute errors, and service errors. Partially serviced requests will not be counted as an error.

21.10.6.2. Entries Table

The Entries Table provides information about the contents of the directory entries. Table 21.2, “Entries Table: Managed Objects and Descriptions” describes the managed objects stored in the Entries Table in the redhat-directory.mib file.

Table 21.2. Entries Table: Managed Objects and Descriptions

Managed Object Description
dsMasterEntries The number of directory entries for which this directory contains the master entry. The value of this object will always be 0 (as no updates are currently performed).
dsCopyEntries The number of directory entries for which this directory contains a copy.The value of this object will always be 0 (as no updates are currently performed).
dsCacheEntries The number of entries cached in the directory.
dsCacheHits The number of operations serviced from the locally held cache since application startup.
dsSlaveHits The number of operations that were serviced from locally held replications (shadow entries). The value of this object will always be 0.

21.10.6.3. Entity Table

The Entity Table contains identifying information about the Directory Server instance. The values for the Entity Table are set in cn=SNMP,cn=config entry as described in Section 21.10.3, “Setting Parameters to Identify an Instance Using SNMP”.
Table 21.3, “Entity Table: Managed Objects and Descriptions” describes the managed objects stored in the Entity Table of the redhat-directory.mib file.

Table 21.3. Entity Table: Managed Objects and Descriptions

Managed Object Description
dsEntityDescr The description set for the Directory Server instance.
dsEntityVers The Directory Server version number of the Directory Server instance.
dsEntityOrg The organization responsible for the Directory Server instance.
dsEntityLocation The physical location of the Directory Server instance.
dsEntityContact The name and contact information for the person responsible for the Directory Server instance.
dsEntityName The name of the Directory Server instance.

21.10.6.4. Interaction Table

Note

The Interaction Table is not supported by the subagent. The subagent can query the table, but it will not ever be updated with valid data.
Table 21.4, “Interaction Table: Managed Objects and Descriptions” describes the managed objects stored in the Interaction Table of the redhat-directory.mib file.

Table 21.4. Interaction Table: Managed Objects and Descriptions

Managed Object Description
dsIntTable Details, in each row of the table, related to the history of the interaction of the monitored Directory Servers with their respective peer Directory Servers.
dsIntEntry The entry containing interaction details of a Directory Server with a peer Directory Server.
dsIntIndex Part of the unique key, together with applIndex, to identify the conceptual row which contains useful information on the (attempted) interaction between the Directory Server (referred to by applIndex) and a peer Directory Server.
dsName The distinguished name (DN) of the peer Directory Server to which this entry belongs.
dsTimeOfCreation The value of sysUpTime when this row was created. If the entry was created before the network management subsystem was initialized, this object will contain a value of zero.
dsTimeOfLastAttempt The value of sysUpTime when the last attempt was made to contact this Directory Server. If the last attempt was made before the network management subsystem was initialized, this object will contain a value of zero.
dsTimeOfLastSuccess The value of sysUpTime when the last attempt made to contact this Directory Server was successful. This entry will have a value of zero if there have been no successful attempts or if the last successful attempt was made before the network management subsystem was initialized.
dsFailuresSinceLastSuccess The number of failures since the last time an attempt to contact this Directory Server was successful. If there has been no successful attempts, this counter will contain the number of failures since this entry was created.
dsFailures Cumulative failures since the creation of this entry.
dsSuccesses Cumulative successes since the creation of this entry.
dsURL The URL of the Directory Server application.