Directory Server, Version 6.1

 

Appendix F. Simple Network Management Protocol agent

The Simple Network Management Protocol (SNMP) agent services requests for monitoring the state of the directory server and issues traps to the Network Management Station. Using the IBM® Tivoli® Directory Integrator (TDI) assembly line with the SNMP agent, the performance and wellness information of the directory server can be reported and monitored. The TDI assembly line will collect and report performance and wellness information like monitor search, root DSE search, and system information of the directory server it is monitoring. Directory server performance information will be logged periodically and made available in Extensible Markup Language (XML) format defined for Common Base Event (CBE).

Note:

You must have IBM Tivoli Directory Integrator 6.1 installed to use the SNMP agent. If you acquire IBM Tivoli Directory Server through Passport Advantage®, it includes a copy of IBM Tivoli Directory Integrator 6.1 for limited use with IBM Tivoli Directory Server 6.1. (Installation instructions are included with the package.)

You also need to add a user to the directory and place ACLs on the suffixes of the directory, denying the user any permission to access the Data Information Tree (DIT) data. This user is created for performing monitor searches only and must exist across all monitored instances.

To monitor the IBM Tivoli Directory server, modify the properties and configuration files for the Simple Network Management Protocol (SNMP) agent.

The idssnmp.properties file is encrypted by default once the idssnmp agent is started. This file is located in the <install_directory>\idstools\snmp directory. The idssnmp.properties file contains the following: 

snmpuserdn: <user_DN>
snmpuserpwd: <user_pwd>
systemuser: <user_ID>
systemuserpwd: <user_pwd>
filterCacheActive: True/False 
filterCacheThreshold: <Threshold Value in percentage>  
pendingRequestsActive: True/False 
pendingRequestsThreshold: <Threshold Value>
pendingRequestsSinceLastIntervalActive: True/False 
pendingRequestsSinceLastIntervalThreshold: <Threshold Value>
activeConnectionActive: True/False
activeConnectionThreshold: <Threshold Value>
memoryUtilizationActive: True/False
memoryUtilizationThreshold: <Threshold Value in kilobytes>
cpuUtilizatinActive: True/False
cpuUtilizationThreshold: <Threshold Value in percentage>
diskSpaceUtilizationActive: True/False
diskSpaceUtilizationThreshold: <Threshold Value in kilobytes>
replicationPendingChangeCountActive: True/False
replicationPendingChangeCountThreshold: <Threshold Value>
replicationStatusActive: True/False

where:

snmpuserdn

Represents the user DN used to access the DIT.

snmpuserpwd

Represents the user password.

systemuser

Represents the system user id.

systemuserpwd

Represents the system user password.

filterCacheActive

If set to true, then a trap alert is generated when the percentage of search filter cache used exceeds the threshold limit.

filterCacheThreshold

Specifies the threshold value in percentage.

pendingRequestsActive

If set to true, then a trap alert is generated when the difference between number of operations requested and the number of operations completed (pending requests) exceeds the threshold limit.

pendingRequestsThreshold

Specifies the threshold value.

pendingRequestsSinceLastIntervalActive

If set to true, then a trap alert is generated when the number of pending requests since the last interval exceeds the threshold limit.

pendingRequestsSinceLastIntervalThreshold

Specifies the threshold value.

activeConnectionActive

If set to true, then a trap alert is generated when the number of active connections exceed the threshold limit.

activeConnectionThreshold

Specifies the threshold value.

memoryUtilizationActive

If set to true, then a trap alert is generated when the maximum system memory utilization exceeds the threshold limit.

memoryUtilizationThreshold

Specifies the threshold value in kilobytes.

cpuUtilizatinActive

If set to true, then a trap alert is generated when the Maximum CPU utilization exceeds the threshold limit. This is applicable only for non-windows operating systems.

cpuUtilizationThreshold

Specifies the threshold value in percentage.

diskSpaceUtilizationActive

If set to true, then a trap alert is generated when the disk space utilization by the directory where DB2® database is stored exceeds the threshold limit.

diskSpaceUtilizationThreshold

Specifies the threshold value in kilobytes.

replicationPendingChangeCountActive

If set to true, then a trap alert is generated when the replication queue reaches a predefined threshold, for instance if the queue grows larger than 10000 entries.

replicationPendingChangeCountThreshold

Specifies the threshold value.

replicationStatusActive

If set to true, then a trap alert is generated if the current state of replication is incompatible, server is down, authentication has failed, or down level server is not supported.

The configuration file, idssnmp.conf, is in the standard SNMP format, that is, space separated with certain keywords. This configuration file contains the port number on which the SNMP agent runs, at least one IP address or host name, the IP address of the network management system (NMS) to where the connector sends its traps, and the communities that this SNMP Agent responds to. This file is located in the <install_directory>\idstools\snmp directory.

  1. Edit the port number in the configuration file for the IBM Tivoli Directory Server SNMP agent. The SNMP Agent monitors the IBM Tivoli Directory Server. If you want to monitor something other than the directory server, the SNMP agent for the IBM Tivoli Directory Server must be run on a nonstandard port. The nonstandard port is necessary to avoid a port conflict with the agent for the other application. 
    Port 		161
    The example shows that the SNMP agent runs on port 161. If more than one port is specified, only the first line of type Port is read, others are ignored

  2. Add lines with "Server" and "SecureServer" as tags and the IP address and the port number on which the monitored LDAP servers are running. The keyword Server specifies a non-encrypted connection. It is followed by the IP Address of the LDAP instance and then the port number of the LDAP instance. The IP Address should be IPV4. The keyword SecureServer indicates that the communication between the LDAP instance and the SNMP Agent is SSL encrypted. 
    Server         13.14.15.16 	389  
SecureServer   9.10.11.12 	636
    In this example, two servers are configured, one on a regular port, and one on a secure port. The first server is using unencrypted authentication. The second server is using SSL authentication. If a server is configured for both (simple and SSL) then it is the prerogative of the directory administrator to decide which port (secured or unsecured) of the LDAP server is accessed.

  3. To properly receive any traps, edit the line in the SNMP configuration file that has the keyword Trap by adding the IP address of the NMS receiving the traps (by default the value is 127.0.0.1), its port number and the community string it expects to receive from the agent. We can repeat the line to specify multiple machines that are receiving the traps. For example: 
    Trap		5.4.3.2 162 public
    This example shows that any traps that are generated are sent to a machine with the IP address 5.4.3.2 on port 162 using the community string "public".

  4. Specify a polling interval in seconds. After the specified number of seconds the agent polls the servers to discover their status. 
    Poll		600
    In this example the agent checks the servers every 600 seconds, that is, every 10 minutes.

  5. If you want to restrict access to the agent, we can specify an optional community string. If you specify community, provide the string. For example: 
    Community 	dirServer
    Any machine supplying the community string, dirServer, has access to the data. If the community string is not specified, authorization is not restricted. To further restrict access, you can provide other tokens such as the IP address in the community string line that the machine originating the request must have: 
    Community 	dirServer	1.2.3.4
    If no IP Address is specified, then any machine supplying the community string has access to the data. If additional access restrictions are needed, we can also specify the supported access right, readOnly, to the elements of the community and lastly the view of the subtree. Please note that the data is implicitly read only and that readOnly is used to maintain the SNMP configuration file standards. If you specify community, the string is required. The IP address, access right and view are optional, however these restrictions are sequential in nature. We can optionally specify IP address or IP address and access right, but you could not optionally specify the access right and view without IP address.

    This example is the most restrictive and illustrates the correct sequence of the tokens. 

    Community 	dirServer	1.2.3.4		readOnly 	1.5.4.3.2.1

    In this example, the requesting NMSs must supply "dirServer" as a community string. The requests must originate from a machine with IP address 1.2.3.4 and all elements in this community are read only and the view is 1.5.4.3.2.1.

    Note:

    With restricted authorization, if more than one machine is running an NMS authorized to perform get operation on the Directory SNMP Agent, the community line will need to be duplicated.

  6. If we need to divide the SNMP OID tree, we can specify a view of the subtree. 
    View 		1.5.4.3.2.1
    This example indicates that the agent deals with all the subtrees under the OID 1.5.4.3.2.1.
Notes:

  1. When Server and SecureServer are specified in the idssnmp.conf file, their order in the file is inconsequential to the way the SNMP agent returns the next value for a get_next operation.

    For example, if the idssnmp.conf file contains the following: 

    Port 161 
Community public 9.182.182.134 
Trap 9.182.190.159 162 public 
SecureServer 9.53.190.143 1636 
Server 9.53.190.176 389 
SecureServer 9.53.190.143 636

    Then the following occurs:

    • The get-next for 1.3.6.1.4.1.2.6.199.2.1.63.1.4.9.53.190.143.636 returns SNMPv2-SMI::enterprises.2.6.199.2.1.63.1.4.9.53.190.143.1636

    • The get-next for 1.3.6.1.4.1.2.6.199.2.1.63.1.4.9.182.190.143.1636 returns SNMPv2-SMI::enterprises.2.6.199.2.1.63.1.4.9.53.190.176.389

    • The get-next for 1.3.6.1.4.1.2.6.199.2.1.63.1.4.9.53.190.176.389 returns an error message that indicates there are no more results in the Management information base (MIB) tree.

    The order of the servers is determined by the value of the server's IP and port. The servers with lower values are at the beginning of the MIB tree. We can see from the preceeding example that the server IPs are identical until the 143 and 176 are reached. Since 143 is lower than 176, the servers with 9.53.190.143 are placed ahead of the 9.53.190.176 server. In the case where the 9.53.190.143 servers are matching until the port is reached, the port numbers are compared. Because 636 is lower than 1636, the 9.53.190.143 636 is placed ahead of the 9.53.190.143 1636 in the MIB tree.

  2. Load the following MIBS to your NMS: 
    <install_directory>/idstools/snmp/IBM-DIRECTORYSERVER-MIB 
<install_directory>/idstools/snmp/INET-ADDRESS-MIB

The SNMP agent can be started by running the idssnmp script located in the <install_directory>\sbin directory.

See the IBM Tivoli Directory Integrator documentation for information on how to install IBM Tivoli Directory Integrator and how to setup SSL (IBM Tivoli Directory Integrator Users Guide).

 

Logging

By default, the idssnmp application logs its data to the file /var/idsldap/V6.1/idssnmp.log on the UNIX® platform and <ldap install dir>\var\idssnmp.log on the Windows® platform.

In addition to the tool's main log file, idssnmp.log, there are two additional log files that ITDI produces:

  • ibmdi.log

  • idssnmpinit.log

These files are produced because the ITDI application writes logs to a static location. After the idssnmp tool is initialized, most of the log statements are written to idssnmp.log. The ibmdi.log file and idssnmpinit.log file are written to the following directories:

  • /var/idsldap/V6.1 (UNIX)

  • <install_directory>\var (Windows)

If these directories are not created, then the logs are placed in the current working directory. The ibmdi.log and idssnmpinit.log are overwritten each time the idssnmp tool is run so the filesize can remain small.

The following command line option: 

–D DEBUG

can be specified to debug idssnmp. The log can then have more detailed information of the agent's execution.

Note:

The TDI assembly line will periodically log directory server performance information in XML format defined for Common Base Event (CBE).

 

Using the command line – idssnmp

idssnmp has the following command line options:

-q

This will not display the log messages to the screen. This is an optional parameter.

-v

Displays the version number of the idssnmp tool. This is an optional parameter.

-?

Displays the usage. This is an optional parameter.

When IBM Tivoli Directory Integrator ends, it returns one of the following exit codes:

0

User started IBM Tivoli Directory Integrator with -v parameter (show info and exit).

1

  • Cannot open logfile (-l parameter)

  • Cannot open configuration file

  • Stopped by admin request

2

Exit after auto-run. When you start IBM Tivoli Directory Integrator specifying the -w option, IBM Tivoli Directory Integrator runs the AssemblyLines specified by the -r parameter and then exits.

9

License expired or invalid.




[ Top of Page | Previous Page | Next Page | Contents | Index ]