2 # Copyright 1999-2014 The OpenLDAP Foundation, All Rights Reserved.
3 # COPYING RESTRICTIONS APPLY, see COPYRIGHT.
6 {{slapd}}(8) supports an optional {{TERM:LDAP}} monitoring interface
7 you can use to obtain information regarding the current state of
8 your {{slapd}} instance. For instance, the interface allows you
9 to determine how many clients are connected to the server currently.
10 The monitoring information is provided by a specialized backend,
11 the {{monitor}} backend. A manual page, {{slapd-monitor}}(5) is
14 When the monitoring interface is enabled, LDAP clients may be used
15 to access information provided by the {{monitor}} backend, subject
16 to access and other controls.
18 When enabled, the {{monitor}} backend dynamically generates and
19 returns objects in response to search requests in the {{cn=Monitor}}
20 subtree. Each object contains information about a particular aspect
21 of the server. The information is held in a combination of user
22 applications and operational attributes. This information can be
23 access with {{ldapsearch(1)}}, with any general-purpose LDAP browser,
24 or with specialized monitoring tools. The {{SECT:Accessing Monitoring
25 Information}} section provides a brief tutorial on how to use
26 {{ldapsearch}}(1) to access monitoring information, while the
27 {{SECT:Monitor information}} section details monitoring information
28 base and its organization.
30 While support for the monitor backend is included in default builds
31 of slapd(8), this support requires some configuration to become
32 active. This may be done using either {{EX:cn=config}} or
33 {{slapd.conf}}(5). The former is discussed in the {{SECT:Monitor
34 configuration via cn=config}} section of this of this chapter. The
35 latter is discussed in the {{SECT:Monitor configuration via
36 slapd.conf(5)}} section of this chapter. These sections assume
37 monitor backend is built into {{slapd}} (e.g., {{EX:--enable-monitor=yes}},
38 the default). If the monitor backend was built as a module (e.g.,
39 {{EX:--enable-monitor=mod}}, this module must loaded. Loading of
40 modules is discussed in the {{SECT:Configuring slapd}} and {{SECT:The
41 slapd Configuration File}} chapters.
44 H2: Monitor configuration via cn=config(5)
46 {{This section has yet to be written.}}
49 H2: Monitor configuration via slapd.conf(5)
51 Configuration of the slapd.conf(5) to support LDAP monitoring
54 First, ensure {{core.schema}} schema configuration file is included
55 by your {{slapd.conf}}(5) file. The {{monitor}} backend requires
58 Second, instantiate the {{monitor backend}} by adding a
59 {{database monitor}} directive below your existing database
60 sections. For instance:
64 Lastly, add additional global or database directives as needed.
66 Like most other database backends, the monitor backend does honor
67 slapd(8) access and other administrative controls. As some monitor
68 information may be sensitive, it is generally recommend access to
69 cn=monitor be restricted to directory administrators and their
70 monitoring agents. Adding an {{access}} directive immediately below
71 the {{database monitor}} directive is a clear and effective approach
72 for controlling access. For instance, the addition of the following
73 {{access}} directive immediately below the {{database monitor}}
74 directive restricts access to monitoring information to the specified
78 > by dn.exact="cn=Manager,dc=example,dc=com
81 More information on {{slapd}}(8) access controls, see {{The access
82 Control Directive}} section of the {{SECT:The slapd Configuration
83 File}} chapter and {{slapd.access}}(5).
85 After restarting {{slapd}}(8), you are ready to start exploring the
86 monitoring information provided in {{EX:cn=config}} as discussed
87 in the {{SECT:Accessing Monitoring Information}} section of this
90 One can verify slapd(8) is properly configured to provide monitoring
91 information by attempting to read the {{EX:cn=monitor}} object.
92 For instance, if the following {{ldapsearch}}(1) command returns the
93 cn=monitor object (with, as requested, no attributes), it's working.
95 > ldapsearch -x -D 'cn=Manager,dc=example,dc=com' -W \
96 > -b 'cn=Monitor' -s base 1.1
98 Note that unlike general purpose database backends, the database
99 suffix is hardcoded. It's always {{EX:cn=Monitor}}. So no {{suffix}}
100 directive should be provided. Also note that general purpose
101 database backends, the monitor backend cannot be instantiated
102 multiple times. That is, there can only be one (or zero) occurrences
103 of {{EX:database monitor}} in the server's configuration.
106 H2: Accessing Monitoring Information
108 As previously discussed, when enabled, the {{monitor}} backend
109 dynamically generates and returns objects in response to search
110 requests in the {{cn=Monitor}} subtree. Each object contains
111 information about a particular aspect of the server. The information
112 is held in a combination of user applications and operational
113 attributes. This information can be access with {{ldapsearch(1)}},
114 with any general-purpose LDAP browser, or with specialized monitoring
117 This section provides a provides a brief tutorial on how to use
118 {{ldapsearch}}(1) to access monitoring information.
120 To inspect any particular monitor object, one performs search
121 operation on the object with a baseObject scope and a
122 {{EX:(objectClass=*)}} filter. As the monitoring information is
123 contained in a combination of user applications and operational
124 attributes, the return all user applications attributes (e.g.,
125 {{EX:'*'}}) and all operational attributes (e.g., {{EX:'+'}}) should
126 be requested. For instance, to read the {{EX:cn=Monitor}} object
127 itself, the {{ldapsearch}}(1) command (modified to fit your configuration)
130 > ldapsearch -x -D 'cn=Manager,dc=example,dc=com' -W \
131 > -b 'cn=Monitor' -s base '(objectClass=*)' '*' '+'
133 When run against your server, this should produce output
137 > objectClass: monitorServer
138 > structuralObjectClass: monitorServer
142 > createTimestamp: 20061208223558Z
143 > modifyTimestamp: 20061208223558Z
144 > description: This subtree contains monitoring/managing objects.
145 > description: This object contains information about this server.
146 > description: Most of the information is held in operational attributes, which
147 > must be explicitly requested.
148 > monitoredInfo: OpenLDAP: slapd 2.4 (Dec 7 2006 17:30:29)
149 > entryDN: cn=Monitor
150 > subschemaSubentry: cn=Subschema
151 > hasSubordinates: TRUE
153 To reduce the number of uninteresting attributes returned, one
154 can be more selective when requesting which attributes are to be
155 returned. For instance, one could request the return of all
156 attributes allowed by the {{monitorServer}} object class (e.g.,
157 {{EX:@objectClass}}) instead of all user and all operational
160 > ldapsearch -x -D 'cn=Manager,dc=example,dc=com' -W \
161 > -b 'cn=Monitor' -s base '(objectClass=*)' '@monitorServer'
163 This limits the output as follows:
166 > objectClass: monitorServer
168 > description: This subtree contains monitoring/managing objects.
169 > description: This object contains information about this server.
170 > description: Most of the information is held in operational attributes, which
171 > must be explicitly requested.
172 > monitoredInfo: OpenLDAP: slapd 2.X (Dec 7 2006 17:30:29)
174 To return the names of all the monitoring objects, one performs a
175 search of {{EX:cn=Monitor}} with subtree scope and {{EX:(objectClass=*)}}
176 filter and requesting no attributes (e.g., {{EX:1.1}}) be returned.
178 > ldapsearch -x -D 'cn=Manager,dc=example,dc=com' -W -b 'cn=Monitor' -s sub 1.1
180 If you run this command you will discover that there are many objects
181 in the {{cn=Monitor}} subtree. The following section describes
182 some of the commonly available monitoring objects.
185 H2: Monitor Information
187 The {{monitor}} backend provides a wealth of information useful
188 for monitoring the slapd(8) contained in set of monitor objects.
189 Each object contains information about a particular aspect of
190 the server, such as a backends, a connection, or a thread.
191 Some objects serve as containers for other objects and used
192 to construct a hierarchy of objects.
194 In this hierarchy, the most superior object is {cn=Monitor}.
195 While this object primarily serves as a container for other
196 objects, most of which are containers, this object provides
197 information about this server. In particular, it provides the
198 slapd(8) version string. Example:
201 > monitoredInfo: OpenLDAP: slapd 2.X (Dec 7 2006 17:30:29)
203 Note: Examples in this section (and its subsections) have been
204 trimmed to show only key information.
209 The {{EX:cn=Backends,cn=Monitor}} object, itself, provides a list
210 of available backends. The list of available backends all builtin
211 backends, as well as backends loaded by modules. For example:
213 > dn: cn=Backends,cn=Monitor
214 > monitoredInfo: config
215 > monitoredInfo: ldif
216 > monitoredInfo: monitor
221 This indicates the {{config}}, {{ldif}}, {{monitor}}, {{bdb}},
222 and {{hdb}} backends are available.
224 The {{EX:cn=Backends,cn=Monitor}} object is also a container
225 for available backend objects. Each available backend object
226 contains information about a particular backend. For example:
228 > dn: cn=Backend 0,cn=Backends,cn=Monitor
229 > monitoredInfo: config
230 > monitorRuntimeConfig: TRUE
231 > supportedControl: 2.16.840.1.113730.3.4.2
232 > seeAlso: cn=Database 0,cn=Databases,cn=Monitor
234 > dn: cn=Backend 1,cn=Backends,cn=Monitor
235 > monitoredInfo: ldif
236 > monitorRuntimeConfig: TRUE
237 > supportedControl: 2.16.840.1.113730.3.4.2
239 > dn: cn=Backend 2,cn=Backends,cn=Monitor
240 > monitoredInfo: monitor
241 > monitorRuntimeConfig: TRUE
242 > supportedControl: 2.16.840.1.113730.3.4.2
243 > seeAlso: cn=Database 2,cn=Databases,cn=Monitor
245 > dn: cn=Backend 3,cn=Backends,cn=Monitor
247 > monitorRuntimeConfig: TRUE
248 > supportedControl: 1.3.6.1.1.12
249 > supportedControl: 2.16.840.1.113730.3.4.2
250 > supportedControl: 1.3.6.1.4.1.4203.666.5.2
251 > supportedControl: 1.2.840.113556.1.4.319
252 > supportedControl: 1.3.6.1.1.13.1
253 > supportedControl: 1.3.6.1.1.13.2
254 > supportedControl: 1.3.6.1.4.1.4203.1.10.1
255 > supportedControl: 1.2.840.113556.1.4.1413
256 > supportedControl: 1.3.6.1.4.1.4203.666.11.7.2
257 > seeAlso: cn=Database 1,cn=Databases,cn=Monitor
259 > dn: cn=Backend 4,cn=Backends,cn=Monitor
261 > monitorRuntimeConfig: TRUE
262 > supportedControl: 1.3.6.1.1.12
263 > supportedControl: 2.16.840.1.113730.3.4.2
264 > supportedControl: 1.3.6.1.4.1.4203.666.5.2
265 > supportedControl: 1.2.840.113556.1.4.319
266 > supportedControl: 1.3.6.1.1.13.1
267 > supportedControl: 1.3.6.1.1.13.2
268 > supportedControl: 1.3.6.1.4.1.4203.1.10.1
269 > supportedControl: 1.2.840.113556.1.4.1413
270 > supportedControl: 1.3.6.1.4.1.4203.666.11.7.2
272 > dn: cn=Backend 5,cn=Backends,cn=Monitor
274 > monitorRuntimeConfig: TRUE
275 > supportedControl: 1.3.6.1.1.12
276 > supportedControl: 2.16.840.1.113730.3.4.2
277 > supportedControl: 1.3.6.1.4.1.4203.666.5.2
278 > supportedControl: 1.2.840.113556.1.4.319
279 > supportedControl: 1.3.6.1.1.13.1
280 > supportedControl: 1.3.6.1.1.13.2
281 > supportedControl: 1.3.6.1.4.1.4203.1.10.1
282 > supportedControl: 1.2.840.113556.1.4.1413
283 > supportedControl: 1.3.6.1.4.1.4203.666.11.7.2
285 For each of these objects, monitorInfo indicates which backend the
286 information in the object is about. For instance, the {{EX:cn=Backend
287 5,cn=Backends,cn=Monitor}} object contains (in the example) information
288 about the {{mdb}} backend.
291 Attribute|Description
292 monitoredInfo|Name of backend
293 supportedControl|supported LDAP control extensions
294 seeAlso|Database objects of instances of this backend
299 The main entry is empty; it should contain some statistics on the number
302 Dynamic child entries are created for each open connection, with stats on
303 the activity on that connection (the format will be detailed later).
304 There are two special child entries that show the number of total and
305 current connections respectively.
311 > dn: cn=Total,cn=Connections,cn=Monitor
312 > structuralObjectClass: monitorCounterObject
314 > entryDN: cn=Total,cn=Connections,cn=Monitor
315 > subschemaSubentry: cn=Subschema
316 > hasSubordinates: FALSE
320 > dn: cn=Current,cn=Connections,cn=Monitor
321 > structuralObjectClass: monitorCounterObject
323 > entryDN: cn=Current,cn=Connections,cn=Monitor
324 > subschemaSubentry: cn=Subschema
325 > hasSubordinates: FALSE
330 The main entry contains the naming context of each configured database;
331 the child entries contain, for each database, the type and the naming
336 > dn: cn=Database 2,cn=Databases,cn=Monitor
337 > structuralObjectClass: monitoredObject
338 > monitoredInfo: monitor
339 > monitorIsShadow: FALSE
340 > monitorContext: cn=Monitor
342 > entryDN: cn=Database 2,cn=Databases,cn=Monitor
343 > subschemaSubentry: cn=Subschema
344 > hasSubordinates: FALSE
348 It contains the description of the devices the server is currently
351 > dn: cn=Listener 0,cn=Listeners,cn=Monitor
352 > structuralObjectClass: monitoredObject
353 > monitorConnectionLocalAddress: IP=0.0.0.0:389
354 > entryDN: cn=Listener 0,cn=Listeners,cn=Monitor
355 > subschemaSubentry: cn=Subschema
356 > hasSubordinates: FALSE
361 It contains the currently active log items. The {{Log}} subsystem allows
362 user modify operations on the {{description}} attribute, whose values {{MUST}}
363 be in the list of admittable log switches:
379 These values can be added, replaced or deleted; they affect what
380 messages are sent to the syslog device.
381 Custom values could be added by custom modules.
385 It shows some statistics on the operations performed by the server:
390 and for each operation type, i.e.:
403 There are too many types to list example here, so please try for yourself
404 using {{SECT: Monitor search example}}
408 The main entry contains the type of overlays available at run-time;
409 the child entries, for each overlay, contain the type of the overlay.
411 It should also contain the modules that have been loaded if dynamic
412 overlays are enabled:
414 > # Overlays, Monitor
415 > dn: cn=Overlays,cn=Monitor
416 > structuralObjectClass: monitorContainer
417 > monitoredInfo: syncprov
418 > monitoredInfo: accesslog
419 > monitoredInfo: glue
420 > entryDN: cn=Overlays,cn=Monitor
421 > subschemaSubentry: cn=Subschema
422 > hasSubordinates: TRUE
430 It shows some statistics on the data sent by the server:
439 > # Entries, Statistics, Monitor
440 > dn: cn=Entries,cn=Statistics,cn=Monitor
441 > structuralObjectClass: monitorCounterObject
442 > monitorCounter: 612248
443 > entryDN: cn=Entries,cn=Statistics,cn=Monitor
444 > subschemaSubentry: cn=Subschema
445 > hasSubordinates: FALSE
449 It contains the maximum number of threads enabled at startup and the
454 > # Max, Threads, Monitor
455 > dn: cn=Max,cn=Threads,cn=Monitor
456 > structuralObjectClass: monitoredObject
458 > entryDN: cn=Max,cn=Threads,cn=Monitor
459 > subschemaSubentry: cn=Subschema
460 > hasSubordinates: FALSE
465 It contains two child entries with the start time and the current time
472 > dn: cn=Start,cn=Time,cn=Monitor
473 > structuralObjectClass: monitoredObject
474 > monitorTimestamp: 20061205124040Z
475 > entryDN: cn=Start,cn=Time,cn=Monitor
476 > subschemaSubentry: cn=Subschema
477 > hasSubordinates: FALSE
481 > dn: cn=Current,cn=Time,cn=Monitor
482 > structuralObjectClass: monitoredObject
483 > monitorTimestamp: 20061207120624Z
484 > entryDN: cn=Current,cn=Time,cn=Monitor
485 > subschemaSubentry: cn=Subschema
486 > hasSubordinates: FALSE
494 It contains the number of current read waiters.
500 > dn: cn=Read,cn=Waiters,cn=Monitor
501 > structuralObjectClass: monitorCounterObject
503 > entryDN: cn=Read,cn=Waiters,cn=Monitor
504 > subschemaSubentry: cn=Subschema
505 > hasSubordinates: FALSE
509 > dn: cn=Write,cn=Waiters,cn=Monitor
510 > structuralObjectClass: monitorCounterObject
512 > entryDN: cn=Write,cn=Waiters,cn=Monitor
513 > subschemaSubentry: cn=Subschema
514 > hasSubordinates: FALSE
516 Add new monitored things here and discuss, referencing man pages and present