git.sur5r.net Git - openldap/blob - doc/guide/admin/monitoringslapd.sdf

   1 # $OpenLDAP$
   2 # Copyright 1999-2007 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 >   Index
 364
 365 These values can be added, replaced or deleted; they affect what
 366 messages are sent to the syslog device.
 367
 368 H3: Operations
 369
 370 It shows some statistics on the operations performed by the server:
 371
 372 >   Initiated
 373 >   Completed
 374
 375 and for each operation type, i.e.:
 376
 377 >   Bind
 378 >   Unbind
 379 >   Add
 380 >   Delete
 381 >   Modrdn
 382 >   Modify
 383 >   Compare
 384 >   Search
 385 >   Abandon
 386 >   Extended
 387
 388 There are too many types to list example here, so please try for yourself
 389 using {{SECT: Monitor search example}}
 390
 391 H3: Overlays
 392
 393 The main entry contains the type of overlays available at run-time;
 394 the child entries, for each overlay, contain the type of the overlay.
 395
 396 It should also contain the modules that have been loaded if dynamic
 397 overlays are enabled:
 398
 399 >   # Overlays, Monitor
 400 >   dn: cn=Overlays,cn=Monitor
 401 >   structuralObjectClass: monitorContainer
 402 >   monitoredInfo: syncprov
 403 >   monitoredInfo: accesslog
 404 >   monitoredInfo: glue
 405 >   entryDN: cn=Overlays,cn=Monitor
 406 >   subschemaSubentry: cn=Subschema
 407 >   hasSubordinates: TRUE
 408
 409 H3: SASL
 410
 411 Currently empty.
 412
 413 H3: Statistics
 414
 415 It shows some statistics on the data sent by the server:
 416
 417 >   Bytes
 418 >   PDU
 419 >   Entries
 420 >   Referrals
 421
 422 e.g.
 423
 424 >   # Entries, Statistics, Monitor
 425 >   dn: cn=Entries,cn=Statistics,cn=Monitor
 426 >   structuralObjectClass: monitorCounterObject
 427 >   monitorCounter: 612248
 428 >   entryDN: cn=Entries,cn=Statistics,cn=Monitor
 429 >   subschemaSubentry: cn=Subschema
 430 >   hasSubordinates: FALSE
 431
 432 H3: Threads
 433
 434 It contains the maximum number of threads enabled at startup and the
 435 current backload.
 436
 437 e.g.
 438
 439 >   # Max, Threads, Monitor
 440 >   dn: cn=Max,cn=Threads,cn=Monitor
 441 >   structuralObjectClass: monitoredObject
 442 >   monitoredInfo: 16
 443 >   entryDN: cn=Max,cn=Threads,cn=Monitor
 444 >   subschemaSubentry: cn=Subschema
 445 >   hasSubordinates: FALSE
 446
 447
 448 H3: Time
 449
 450 It contains two child entries with the start time and the current time
 451 of the server.
 452
 453 e.g.
 454
 455 Start time:
 456
 457 >   dn: cn=Start,cn=Time,cn=Monitor
 458 >   structuralObjectClass: monitoredObject
 459 >   monitorTimestamp: 20061205124040Z
 460 >   entryDN: cn=Start,cn=Time,cn=Monitor
 461 >   subschemaSubentry: cn=Subschema
 462 >   hasSubordinates: FALSE
 463
 464 Current time:
 465
 466 >   dn: cn=Current,cn=Time,cn=Monitor
 467 >   structuralObjectClass: monitoredObject
 468 >   monitorTimestamp: 20061207120624Z
 469 >   entryDN: cn=Current,cn=Time,cn=Monitor
 470 >   subschemaSubentry: cn=Subschema
 471 >   hasSubordinates: FALSE
 472
 473 H3: TLS
 474
 475 Currently empty.
 476
 477 H3: Waiters
 478
 479 It contains the number of current read waiters.
 480
 481 e.g.
 482
 483 Read waiters:
 484
 485 >   dn: cn=Read,cn=Waiters,cn=Monitor
 486 >   structuralObjectClass: monitorCounterObject
 487 >   monitorCounter: 7
 488 >   entryDN: cn=Read,cn=Waiters,cn=Monitor
 489 >   subschemaSubentry: cn=Subschema
 490 >   hasSubordinates: FALSE
 491
 492 Write waiters:
 493
 494 >   dn: cn=Write,cn=Waiters,cn=Monitor
 495 >   structuralObjectClass: monitorCounterObject
 496 >   monitorCounter: 0
 497 >   entryDN: cn=Write,cn=Waiters,cn=Monitor
 498 >   subschemaSubentry: cn=Subschema
 499 >   hasSubordinates: FALSE
 500
 501 Add new monitored things here and discuss, referencing man pages and present
 502 examples
 503
 504