]> git.sur5r.net Git - openldap/blob - doc/guide/admin/monitoringslapd.sdf
Merge remote-tracking branch 'origin/mdb.master'
[openldap] / doc / guide / admin / monitoringslapd.sdf
1 # $OpenLDAP$
2 # Copyright 1999-2012 The OpenLDAP Foundation, All Rights Reserved.
3 # COPYING RESTRICTIONS APPLY, see COPYRIGHT.
4 H1: Monitoring
5
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
12 available.
13
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.
17
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.
29
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.
42
43
44 H2: Monitor configuration via cn=config(5)
45
46 {{This section has yet to be written.}}
47
48
49 H2: Monitor configuration via slapd.conf(5)
50
51 Configuration of the slapd.conf(5) to support LDAP monitoring
52 is quite simple.
53
54 First, ensure {{core.schema}} schema configuration file is included
55 by your {{slapd.conf}}(5) file.  The {{monitor}} backend requires
56 it.
57
58 Second, instantiate the {{monitor backend}} by adding a
59 {{database monitor}} directive below your existing database
60 sections.  For instance:
61
62 >       database monitor
63
64 Lastly, add additional global or database directives as needed.
65
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
75 directory manager.
76
77 >       access to *
78 >               by dn.exact="cn=Manager,dc=example,dc=com
79 >               by * none
80
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).
84
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
88 chapter.
89
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.
94
95 >       ldapsearch -x -D 'cn=Manager,dc=example,dc=com' -W \
96 >               -b 'cn=Monitor' -s base 1.1
97
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.
104
105
106 H2: Accessing Monitoring Information
107
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
115 tools.
116
117 This section provides a provides a brief tutorial on how to use
118 {{ldapsearch}}(1) to access monitoring information.
119
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)
128 can be used:
129
130 >       ldapsearch -x -D 'cn=Manager,dc=example,dc=com' -W \
131 >               -b 'cn=Monitor' -s base '(objectClass=*)' '*' '+'
132
133 When run against your server, this should produce output
134 similar to:
135
136 >       dn: cn=Monitor
137 >       objectClass: monitorServer
138 >       structuralObjectClass: monitorServer
139 >       cn: Monitor
140 >       creatorsName:
141 >       modifiersName:
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
152
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
158 attributes:
159
160 >       ldapsearch -x -D 'cn=Manager,dc=example,dc=com' -W \
161 >               -b 'cn=Monitor' -s base '(objectClass=*)' '@monitorServer'
162
163 This limits the output as follows:
164
165 >       dn: cn=Monitor
166 >       objectClass: monitorServer
167 >       cn: Monitor
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)
173
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.
177
178 >       ldapsearch -x -D 'cn=Manager,dc=example,dc=com' -W -b 'cn=Monitor' -s sub 1.1
179
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.
183
184
185 H2: Monitor Information
186
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.
193
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:
199
200 >       dn: cn=Monitor
201 >       monitoredInfo: OpenLDAP: slapd 2.X (Dec  7 2006 17:30:29)
202
203 Note: Examples in this section (and its subsections) have been
204 trimmed to show only key information.
205
206
207 H3: Backends
208
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:
212
213 >       dn: cn=Backends,cn=Monitor          
214 >       monitoredInfo: config                 
215 >       monitoredInfo: ldif     
216 >       monitoredInfo: monitor
217 >       monitoredInfo: bdb        
218 >       monitoredInfo: hdb
219
220 This indicates the {{config}}, {{ldif}}, {{monitor}}, {{bdb}},
221 and {{hdb}} backends are available.
222
223 The {{EX:cn=Backends,cn=Monitor}} object is also a container
224 for available backend objects.  Each available backend object
225 contains information about a particular backend.  For example:
226
227 >       dn: cn=Backend 0,cn=Backends,cn=Monitor 
228 >       monitoredInfo: config
229 >       monitorRuntimeConfig: TRUE
230 >       supportedControl: 2.16.840.1.113730.3.4.2  
231 >       seeAlso: cn=Database 0,cn=Databases,cn=Monitor
232 >       
233 >       dn: cn=Backend 1,cn=Backends,cn=Monitor  
234 >       monitoredInfo: ldif          
235 >       monitorRuntimeConfig: TRUE     
236 >       supportedControl: 2.16.840.1.113730.3.4.2
237 >       
238 >       dn: cn=Backend 2,cn=Backends,cn=Monitor
239 >       monitoredInfo: monitor
240 >       monitorRuntimeConfig: TRUE
241 >       supportedControl: 2.16.840.1.113730.3.4.2
242 >       seeAlso: cn=Database 2,cn=Databases,cn=Monitor
243 >       
244 >       dn: cn=Backend 3,cn=Backends,cn=Monitor
245 >       monitoredInfo: bdb
246 >       monitorRuntimeConfig: TRUE
247 >       supportedControl: 1.3.6.1.1.12
248 >       supportedControl: 2.16.840.1.113730.3.4.2
249 >       supportedControl: 1.3.6.1.4.1.4203.666.5.2
250 >       supportedControl: 1.2.840.113556.1.4.319
251 >       supportedControl: 1.3.6.1.1.13.1
252 >       supportedControl: 1.3.6.1.1.13.2
253 >       supportedControl: 1.3.6.1.4.1.4203.1.10.1
254 >       supportedControl: 1.2.840.113556.1.4.1413
255 >       supportedControl: 1.3.6.1.4.1.4203.666.11.7.2
256 >       seeAlso: cn=Database 1,cn=Databases,cn=Monitor
257 >       
258 >       dn: cn=Backend 4,cn=Backends,cn=Monitor
259 >       monitoredInfo: hdb
260 >       monitorRuntimeConfig: TRUE
261 >       supportedControl: 1.3.6.1.1.12
262 >       supportedControl: 2.16.840.1.113730.3.4.2
263 >       supportedControl: 1.3.6.1.4.1.4203.666.5.2
264 >       supportedControl: 1.2.840.113556.1.4.319
265 >       supportedControl: 1.3.6.1.1.13.1
266 >       supportedControl: 1.3.6.1.1.13.2
267 >       supportedControl: 1.3.6.1.4.1.4203.1.10.1
268 >       supportedControl: 1.2.840.113556.1.4.1413
269 >       supportedControl: 1.3.6.1.4.1.4203.666.11.7.2
270
271 For each of these objects, monitorInfo indicates which backend the
272 information in the object is about.  For instance, the {{EX:cn=Backend
273 3,cn=Backends,cn=Monitor}} object contains (in the example) information
274 about the {{bdb}} backend. 
275
276 !block table
277 Attribute|Description
278 monitoredInfo|Name of backend
279 supportedControl|supported LDAP control extensions
280 seeAlso|Database objects of instances of this backend
281 !endblock
282
283 H3: Connections
284
285 The main entry is empty; it should contain some statistics on the number 
286 of connections.
287
288 Dynamic child entries are created for each open connection, with stats on
289 the activity on that connection (the format will be detailed later).
290 There are two special child entries that show the number of total and
291 current connections respectively.
292
293 For example:
294
295 Total Connections:
296
297 >   dn: cn=Total,cn=Connections,cn=Monitor
298 >   structuralObjectClass: monitorCounterObject
299 >   monitorCounter: 4
300 >   entryDN: cn=Total,cn=Connections,cn=Monitor
301 >   subschemaSubentry: cn=Subschema
302 >   hasSubordinates: FALSE
303
304 Current Connections:
305
306 >   dn: cn=Current,cn=Connections,cn=Monitor
307 >   structuralObjectClass: monitorCounterObject
308 >   monitorCounter: 2
309 >   entryDN: cn=Current,cn=Connections,cn=Monitor
310 >   subschemaSubentry: cn=Subschema
311 >   hasSubordinates: FALSE
312
313
314 H3: Databases
315
316 The main entry contains the naming context of each configured database; 
317 the child entries contain, for each database, the type and the naming
318 context.
319
320 For example:
321
322 >   dn: cn=Database 2,cn=Databases,cn=Monitor
323 >   structuralObjectClass: monitoredObject
324 >   monitoredInfo: monitor
325 >   monitorIsShadow: FALSE
326 >   monitorContext: cn=Monitor
327 >   readOnly: FALSE
328 >   entryDN: cn=Database 2,cn=Databases,cn=Monitor
329 >   subschemaSubentry: cn=Subschema
330 >   hasSubordinates: FALSE
331
332 H3: Listener
333
334 It contains the description of the devices the server is currently 
335 listening on:
336
337 >   dn: cn=Listener 0,cn=Listeners,cn=Monitor
338 >   structuralObjectClass: monitoredObject
339 >   monitorConnectionLocalAddress: IP=0.0.0.0:389
340 >   entryDN: cn=Listener 0,cn=Listeners,cn=Monitor
341 >   subschemaSubentry: cn=Subschema
342 >   hasSubordinates: FALSE
343
344
345 H3: Log
346
347 It contains the currently active log items.  The {{Log}} subsystem allows 
348 user modify operations on the {{description}} attribute, whose values {{MUST}} 
349 be in the list of admittable log switches:
350
351 >   Trace
352 >   Packets
353 >   Args
354 >   Conns
355 >   BER
356 >   Filter
357 >   Config
358 >   ACL
359 >   Stats
360 >   Stats2
361 >   Shell
362 >   Parse
363 >   Sync
364
365 These values can be added, replaced or deleted; they affect what 
366 messages are sent to the syslog device.
367 Custom values could be added by custom modules.
368
369 H3: Operations
370
371 It shows some statistics on the operations performed by the server:
372
373 >   Initiated
374 >   Completed
375
376 and for each operation type, i.e.:
377
378 >   Bind
379 >   Unbind
380 >   Add
381 >   Delete
382 >   Modrdn
383 >   Modify
384 >   Compare
385 >   Search
386 >   Abandon
387 >   Extended
388
389 There are too many types to list example here, so please try for yourself 
390 using {{SECT: Monitor search example}}
391
392 H3: Overlays
393
394 The main entry contains the type of overlays available at run-time;
395 the child entries, for each overlay, contain the type of the overlay.
396
397 It should also contain the modules that have been loaded if dynamic 
398 overlays are enabled:
399
400 >   # Overlays, Monitor
401 >   dn: cn=Overlays,cn=Monitor
402 >   structuralObjectClass: monitorContainer
403 >   monitoredInfo: syncprov
404 >   monitoredInfo: accesslog
405 >   monitoredInfo: glue
406 >   entryDN: cn=Overlays,cn=Monitor
407 >   subschemaSubentry: cn=Subschema
408 >   hasSubordinates: TRUE
409
410 H3: SASL
411
412 Currently empty.
413
414 H3: Statistics
415
416 It shows some statistics on the data sent by the server:
417
418 >   Bytes
419 >   PDU
420 >   Entries
421 >   Referrals
422
423 e.g.
424
425 >   # Entries, Statistics, Monitor
426 >   dn: cn=Entries,cn=Statistics,cn=Monitor
427 >   structuralObjectClass: monitorCounterObject
428 >   monitorCounter: 612248
429 >   entryDN: cn=Entries,cn=Statistics,cn=Monitor
430 >   subschemaSubentry: cn=Subschema
431 >   hasSubordinates: FALSE
432
433 H3: Threads
434
435 It contains the maximum number of threads enabled at startup and the 
436 current backload.
437
438 e.g.
439
440 >   # Max, Threads, Monitor
441 >   dn: cn=Max,cn=Threads,cn=Monitor
442 >   structuralObjectClass: monitoredObject
443 >   monitoredInfo: 16
444 >   entryDN: cn=Max,cn=Threads,cn=Monitor
445 >   subschemaSubentry: cn=Subschema
446 >   hasSubordinates: FALSE
447
448
449 H3: Time
450
451 It contains two child entries with the start time and the current time 
452 of the server.
453
454 e.g.
455
456 Start time:
457
458 >   dn: cn=Start,cn=Time,cn=Monitor
459 >   structuralObjectClass: monitoredObject
460 >   monitorTimestamp: 20061205124040Z
461 >   entryDN: cn=Start,cn=Time,cn=Monitor
462 >   subschemaSubentry: cn=Subschema
463 >   hasSubordinates: FALSE
464
465 Current time:
466
467 >   dn: cn=Current,cn=Time,cn=Monitor
468 >   structuralObjectClass: monitoredObject
469 >   monitorTimestamp: 20061207120624Z
470 >   entryDN: cn=Current,cn=Time,cn=Monitor
471 >   subschemaSubentry: cn=Subschema
472 >   hasSubordinates: FALSE
473
474 H3: TLS
475
476 Currently empty.
477
478 H3: Waiters
479
480 It contains the number of current read waiters.
481
482 e.g.
483
484 Read waiters:
485
486 >   dn: cn=Read,cn=Waiters,cn=Monitor
487 >   structuralObjectClass: monitorCounterObject
488 >   monitorCounter: 7
489 >   entryDN: cn=Read,cn=Waiters,cn=Monitor
490 >   subschemaSubentry: cn=Subschema
491 >   hasSubordinates: FALSE
492
493 Write waiters:
494
495 >   dn: cn=Write,cn=Waiters,cn=Monitor
496 >   structuralObjectClass: monitorCounterObject
497 >   monitorCounter: 0
498 >   entryDN: cn=Write,cn=Waiters,cn=Monitor
499 >   subschemaSubentry: cn=Subschema
500 >   hasSubordinates: FALSE
501
502 Add new monitored things here and discuss, referencing man pages and present
503 examples
504
505