git.sur5r.net Git - openldap/blob - 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