From 671dfc17e7fc3348deb02281fe661929c147c38a Mon Sep 17 00:00:00 2001 From: Kurt Zeilenga Date: Thu, 14 Dec 2006 21:56:51 +0000 Subject: [PATCH] Rework chapter --- doc/guide/admin/monitoringslapd.sdf | 407 +++++++++++++++++++--------- 1 file changed, 274 insertions(+), 133 deletions(-) diff --git a/doc/guide/admin/monitoringslapd.sdf b/doc/guide/admin/monitoringslapd.sdf index 56056dcad2..2118cb3683 100644 --- a/doc/guide/admin/monitoringslapd.sdf +++ b/doc/guide/admin/monitoringslapd.sdf @@ -1,133 +1,284 @@ # $OpenLDAP$ # Copyright 1999-2006 The OpenLDAP Foundation, All Rights Reserved. # COPYING RESTRICTIONS APPLY, see COPYRIGHT. -H1: Monitoring Slapd +H1: Monitoring + +{{slapd}}(8) supports an optional {{TERM:LDAP}} monitoring interface +you can use to obtain information regarding the current state of +your {{slapd}} instance. For instance, the interface allows you +to determine how many clients are connected to the server currently. +The monitoring information is provided by a specialized backend, +the {{monitor}} backend. A manual page, {{slapd-monitor}}(5) is +available. + +When the monitoring interface is enabled, LDAP clients may be used +to access information provided by the {{monitor}} backend, subject +to access and other controls. + +When enabled, the {{monitor}} backend dynamically generates and +returns objects in response to search requests in the {{cn=Monitor}} +subtree. Each object contains information about a particular aspect +of the server. The information is held in a combination of user +applications and operational attributes. This information can be +access with {{ldapsearch(1)}}, with any general-purpose LDAP browser, +or with specialized monitoring tools. The {{SECT:Accessing Monitoring +Information}} section provides a brief tutorial on how to use +{{ldapsearch}}(1) to access monitoring information, while the +{{SECT:Monitor information}} section details monitoring information +base and its organization. + +While support for the monitor backend is included in default builds +of slapd(8), this support requires some configuration to become +active. This may be done using either {{EX:cn=config}} or +{{slapd.conf}}(5). The former is discussed in the {{SECT:Monitor +configuration via cn=config}} section of this of this chapter. The +latter is discussed in the {{SECT:Monitor configuration via +slapd.conf(5)}} section of this chapter. These sections assume +monitor backend is built into {{slapd}} (e.g., {{EX:--enable-monitor=yes}}, +the default). If the monitor backend was built as a module (e.g., +{{EX:--enable-monitor=mod}}, this module must loaded. Loading of +modules is discussed in the {{SECT:Configuring slapd}} and {{SECT:The +slapd Configuration File}} chapters. + + +H2: Monitor configuration via cn=config(5) + +{{This section has yet to be written.}} + + +H2: Monitor configuration via slapd.conf(5) + +Configuration of the slapd.conf(5) to support LDAP monitoring +is quite simple. + +First, ensure {{core.schema}} schema configuration file is included +by your {{slapd.conf}}(5) file. The {{monitor}} backend requires +it. + +Second, instanticate the {{monitor backend}} by adding a +{{database monitor}} directive below your existing database +sections. For instance: + +> database monitor + +Lastly, add additional global or database directives as needed. + +Like most other database backends, the monitor backend does honor +slapd(8) access and other adminstrative controls. As some monitor +information may be sensitive, it is generally recommend access to +cn=monitor be restricted to directory administrators and their +monitoring agents. Adding an {{access}} directive immediately below +the {{database monitor}} directive is a clear and effective approach +for controlling access. For instance, the addition of the following +{{access}} directive immediately below the {{database monitor}} +directive restricts access to monitoring information to the specified +directory manager. + +> access to * +> by dn.exact="cn=Manager,dc=example,dc=com +> by * none + +More information on {{slapd}}(8) access controls, see {{The access +Control Directive}} section of the {{SECT:The slapd Configuration +File}} chapter and {{slapd.access}}(5). + +After restarting {{slapd}}(8), you are ready to start exploring the +monitoring information provided in {{EX:cn=config}} as discussed +in the {{SECT:Accessing Monitoring Information}} section of this +chapter. + +One can verify slapd(8) is properly configured to provide monitoring +information by attempting to read the {{EX:cn=monitor}} object. +For instance, if the following {{ldapsearch}}(1) command returns the +cn=monitor object (with, as requested, no attributes), it's working. + +> ldapsearch -x -D 'cn=Manager,dc=example,dc=com' -W \ +> -b 'cn=Monitor' -s base 1.1 + +Note that unlike general purpose database backends, the database +suffix is hardcoded. It's always {{EX:cn=Monitor}}. So no {{suffix}} +directive should be provided. Also note that general purpose +database backends, the monitor backend cannot be instantiated +multiple times. That is, there can only be one (or zero) occurances +of {{EX:database monitor}} in the server's configuration. + + +H2: Accessing Monitoring Information + +As previously discussed, when enabled, the {{monitor}} backend +dynamically generates and returns objects in response to search +requests in the {{cn=Monitor}} subtree. Each object contains +information about a particular aspect of the server. The information +is held in a combination of user applications and operational +attributes. This information can be access with {{ldapsearch(1)}}, +with any general-purpose LDAP browser, or with specialized monitoring +tools. + +This section provides a provides a brief tutorial on how to use +{{ldapsearch}}(1) to access monitoring information. + +To inspect any particular monitor object, one performs search +operation on the object with a baseObject scope and a +{{EX:(objectClass=*)}} filter. As the monitoring information is +contained in a combination of user applications and operational +attributes, the return all user applications attributes (e.g., +{{EX:'*'}}) and all operational attributes (e.g., {{EX:'+'}}) should +be requested. For instance, to read the {{EX:cn=Monitor}} object +itself, the {{ldapsearch}}(1) command (modified to fit your configuration) +can be used: + +> ldapsearch -x -D 'cn=Manager,dc=example,dc=com' -W \ +> -b 'cn=Monitor' -s base '(objectClass=*)' '*' '+' + +When run against your server, this should produce output +similar to: + +> dn: cn=Monitor +> objectClass: monitorServer +> structuralObjectClass: monitorServer +> cn: Monitor +> creatorsName: +> modifiersName: +> createTimestamp: 20061208223558Z +> modifyTimestamp: 20061208223558Z +> description: This subtree contains monitoring/managing objects. +> description: This object contains information about this server. +> description: Most of the information is held in operational attributes, which +> must be explicitly requested. +> monitoredInfo: OpenLDAP: slapd 2.4 (Dec 7 2006 17:30:29) +> entryDN: cn=Monitor +> subschemaSubentry: cn=Subschema +> hasSubordinates: TRUE + +To reduce the number of uninteresting attributes returned, one +can be more selective when requesting which attributes are to be +returned. For instance, one could request the return of all +attributes allowed by the {{monitorServer}} object class (e.g., +{{EX:@objectClass}}) instead of all user and all operational +attributes: + +> ldapsearch -x -D 'cn=Manager,dc=example,dc=com' -W \ +> -b 'cn=Monitor' -s base '(objectClass=*)' '@monitorServer' + +This limits the output as follows: + +> dn: cn=Monitor +> objectClass: monitorServer +> cn: Monitor +> description: This subtree contains monitoring/managing objects. +> description: This object contains information about this server. +> description: Most of the information is held in operational attributes, which +> must be explicitly requested. +> monitoredInfo: OpenLDAP: slapd 2.X (Dec 7 2006 17:30:29) + +To return the names of all the monitoring objects, one performs a +search of {{EX:cn=Monitor}} with subtree scope and {{EX:(objectClass=*)}} +filter and requesting no attributes (e.g., {{EX:1.1}}) be returned. + +> ldapsearch -x -D 'cn=Manager,dc=example,dc=com' -W -b 'cn=Monitor' -s sub 1.1 + +If you run this command you will discover that there are many objects +in the {{cn=Monitor}} subtree. The following section describes +some of the commonly available monitoring objects. + + +H2: Monitor Information + +The {{monitor}} backend provides a wealth of information useful +for monitoring the slapd(8) contained in set of monitor objects. +Each object contains information about a particular aspect of +the server, such as a backends, a connection, or a thread. +Some objects serve as containers for other objects and used +to construct a hierarchy of objects. + +In this hierarchy, the most superior object is {cn=Monitor}. +While this object primarily serves as a container for other +objects, most of which are containers, this object provides +information about this server. In particular, it provides the +slapd(8) version string. Example: + +> dn: cn=Monitor +> monitoredInfo: OpenLDAP: slapd 2.X (Dec 7 2006 17:30:29) + +Note: Examples in this section (and its subsections) have been +trimmed to show only key information. -{{slapd}}(8) supports a monitoring interface you can use to obtain -information regarding the current state of your {{slapd}} instance. -For instance, the interface allows you to determine how many clients -are connected to the server currently. The interface is accessed -used {{TERM:LDAP}} and is provided via the {{monitor}} backend. A -manual page, {{slapd-monitor}}(5) is available. - -The monitor backend to {{slapd}} is not an actual database; if -enabled, it is automatically generated and dynamically maintained -by {{slapd}} with information about the running status of the daemon. - -To inspect all monitor information, one can issue a subtree search -with base {{EX:cn=Monitor}} and filter {{EX:(objectClass=*)}}, -requesting the return of all user (e.g., '*') and operational (e.g., -'+' attributes. Many of the attributes provided by monitor backend -are operational attributes, and hence will not be returned unless -explicitly requested. For example: - -> ldapsearch -x -D 'cn=Manager,dc=example,dc=com' -W -b 'cn=Monitor' '+' '*' - -As there are may be many objects under {{EX:cn=Monitor}}, a search -with a narrower search criteria may be more appropriate. - -Support for the monitor backend is included in slapd(8) in default -builds. The monitor backend may also be built as a loadable module. -The remainder of this section assumes slapd(8) was with with monitor -backend support (e.g., {{EX:--enable-monitor=yes}}, the default), -or build as a module (e.g., {{EX:--enable-monitor=mod}} and loaded -into slapd(8). - - -H2: Configuration - -These {{slapd.conf}}(5) options apply to the monitor backend database. -That is, they must follow a {{EX:database monitor}} line and come -before any subsequent {{backend}} or {{database}} lines. - -As opposed to most databases, the monitor database can be instantiated -only once, i.e. only one occurrence of {{EX:database monitor}} -can occur in the {{slapd.conf}}(5) file. Moreover, the suffix of -the database cannot be explicitly set by means of the suffix -directive. The suffix is automatically set to {{EX:cn=Monitor}} - -The monitor backend honors access control semantics as indicated -in {{slapd.access}}(5), including the disclose access privilege, -on all currently implemented operations. - -For understanding how to do the following with dynamic configuration, -see {{SECT:Configuring slapd}} - -Also ensure that the {{core.schema}} file is loaded. The monitor -backend relies on some standard track {{attributeTypes}} that must -be already defined when the backend is started. - -H3: Activate the monitor database - -Put this in your {{slapd.conf}}(5) or via the {{config}} backend - -> database monitor - -You may also specify a {{rootpw}} below this - -H3: Add ACLs - -Here's an example you might use: - -> access to dn.subtree="cn=Monitor" -> by dn.exact="uid=Admin,dc=my,dc=org" write -> by users read -> by * none - -More information is detailed in {{slapd.access}}(5) - -H2: Available Subsystems - -There are various subsytems you can explicitly query for, with most -information being held in the {{monitoredInfo}} attribute. H3: Backends -The main entry contains the type of backends enabled at compile -time; the child entries, for each backend, contain the type of the -backend. It should also contain the modules that have been loaded -if dynamic backends are enabled. - -For example: - -> dn: cn=Backend 1,cn=Backends,cn=Monitor -> structuralObjectClass: monitoredObject -> monitoredInfo: ldif -> monitorRuntimeConfig: TRUE -> supportedControl: 2.16.840.1.113730.3.4.2 -> entryDN: cn=Backend 1,cn=Backends,cn=Monitor -> subschemaSubentry: cn=Subschema -> hasSubordinates: FALSE -> -> dn: cn=Backend 2,cn=Backends,cn=Monitor -> structuralObjectClass: monitoredObject -> monitoredInfo: hdb -> monitorRuntimeConfig: TRUE -> supportedControl: 1.3.6.1.1.12 -> supportedControl: 2.16.840.1.113730.3.4.2 -> supportedControl: 1.3.6.1.4.1.4203.666.5.2 -> supportedControl: 1.2.840.113556.1.4.319 -> supportedControl: 1.3.6.1.1.13.1 -> supportedControl: 1.3.6.1.1.13.2 -> supportedControl: 1.3.6.1.4.1.4203.1.10.1 -> supportedControl: 1.2.840.113556.1.4.1413 -> entryDN: cn=Backend 2,cn=Backends,cn=Monitor -> subschemaSubentry: cn=Subschema -> hasSubordinates: FALSE -> -> # Backend 3, Backends, Monitor -> dn: cn=Backend 3,cn=Backends,cn=Monitor -> structuralObjectClass: monitoredObject -> monitoredInfo: monitor -> monitorRuntimeConfig: TRUE -> supportedControl: 2.16.840.1.113730.3.4.2 -> entryDN: cn=Backend 3,cn=Backends,cn=Monitor -> subschemaSubentry: cn=Subschema -> hasSubordinates: FALSE - -In this example, the server has three backends: 1) a {{ldif}} backend, -2) a {{hdb}} backend, and 3) a {{monitor}} backend. - +The {{EX:cn=Backends,cn=Monitor}} object, itself, provides a list +of available backends. The list of available backends all builtin +backends, as well as backends loaded by modules. For example: + +> dn: cn=Backends,cn=Monitor +> monitoredInfo: config +> monitoredInfo: ldif +> monitoredInfo: monitor +> monitoredInfo: bdb +> monitoredInfo: hdb + +This indicates the {{config}}, {{ldif}}, {{monitor}}, {{bdb}}, +and {{hdb}} backends are available. + +The {{EX:cn=Backends,cn=Monitor}} object is also a container +for available backend objects. Each available backend object +contains information about a particular backend. For example: + +> dn: cn=Backend 0,cn=Backends,cn=Monitor +> monitoredInfo: config +> monitorRuntimeConfig: TRUE +> supportedControl: 2.16.840.1.113730.3.4.2 +> seeAlso: cn=Database 0,cn=Databases,cn=Monitor +> +> dn: cn=Backend 1,cn=Backends,cn=Monitor +> monitoredInfo: ldif +> monitorRuntimeConfig: TRUE +> supportedControl: 2.16.840.1.113730.3.4.2 +> +> dn: cn=Backend 2,cn=Backends,cn=Monitor +> monitoredInfo: monitor +> monitorRuntimeConfig: TRUE +> supportedControl: 2.16.840.1.113730.3.4.2 +> seeAlso: cn=Database 2,cn=Databases,cn=Monitor +> +> dn: cn=Backend 3,cn=Backends,cn=Monitor +> monitoredInfo: bdb +> monitorRuntimeConfig: TRUE +> supportedControl: 1.3.6.1.1.12 +> supportedControl: 2.16.840.1.113730.3.4.2 +> supportedControl: 1.3.6.1.4.1.4203.666.5.2 +> supportedControl: 1.2.840.113556.1.4.319 +> supportedControl: 1.3.6.1.1.13.1 +> supportedControl: 1.3.6.1.1.13.2 +> supportedControl: 1.3.6.1.4.1.4203.1.10.1 +> supportedControl: 1.2.840.113556.1.4.1413 +> supportedControl: 1.3.6.1.4.1.4203.666.11.7.2 +> seeAlso: cn=Database 1,cn=Databases,cn=Monitor +> +> dn: cn=Backend 4,cn=Backends,cn=Monitor +> monitoredInfo: hdb +> monitorRuntimeConfig: TRUE +> supportedControl: 1.3.6.1.1.12 +> supportedControl: 2.16.840.1.113730.3.4.2 +> supportedControl: 1.3.6.1.4.1.4203.666.5.2 +> supportedControl: 1.2.840.113556.1.4.319 +> supportedControl: 1.3.6.1.1.13.1 +> supportedControl: 1.3.6.1.1.13.2 +> supportedControl: 1.3.6.1.4.1.4203.1.10.1 +> supportedControl: 1.2.840.113556.1.4.1413 +> supportedControl: 1.3.6.1.4.1.4203.666.11.7.2 + +For each of these objects, monitorInfo indicates which backend the +information in the object is about. For instance, the {{EX:cn=Backend +3,cn=Backends,cn=Monitor}} object contains (in the example) information +about the {{bdb}} backend. + +!block table +Attribute|Description +monitoredInfo|Name of backend +supportedControl|supported LDAP control extensions +seeAlso|Database objects of instances of this backend +!endblock H3: Connections @@ -168,7 +319,6 @@ context. For example: -> # Database 2, Databases, Monitor > dn: cn=Database 2,cn=Databases,cn=Monitor > structuralObjectClass: monitoredObject > monitoredInfo: monitor @@ -184,7 +334,6 @@ H3: Listener It contains the description of the devices the server is currently listening on: -> # Listener 0, Listeners, Monitor > dn: cn=Listener 0,cn=Listeners,cn=Monitor > structuralObjectClass: monitoredObject > monitorConnectionLocalAddress: IP=0.0.0.0:389 @@ -349,11 +498,3 @@ Write waiters: > entryDN: cn=Write,cn=Waiters,cn=Monitor > subschemaSubentry: cn=Subschema > hasSubordinates: FALSE - -H2: Monitor search example - -You should be able to use any LDAP client to retrieve this -information. Here's how you might do it using the -{{I: ldapsearch}}(1) client: - -> ldapsearch -x -s base -b cn=monitor 'objectclass=*' + -- 2.39.5