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

   1 # $OpenLDAP$
   2 # Copyright 1999-2017 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 accessed 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 >       monitoredInfo: mdb
 220
 221 This indicates the {{config}}, {{ldif}}, {{monitor}}, {{bdb}},
 222 and {{hdb}} backends are available.
 223
 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:
 227
 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
 233 >
 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
 238 >
 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
 244 >
 245 >       dn: cn=Backend 3,cn=Backends,cn=Monitor
 246 >       monitoredInfo: bdb
 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
 258 >
 259 >       dn: cn=Backend 4,cn=Backends,cn=Monitor
 260 >       monitoredInfo: hdb
 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
 271 >
 272 >       dn: cn=Backend 5,cn=Backends,cn=Monitor
 273 >       monitoredInfo: mdb
 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
 284
 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.
 289
 290 !block table
 291 Attribute|Description
 292 monitoredInfo|Name of backend
 293 supportedControl|supported LDAP control extensions
 294 seeAlso|Database objects of instances of this backend
 295 !endblock
 296
 297 H3: Connections
 298
 299 The main entry is empty; it should contain some statistics on the number
 300 of connections.
 301
 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.
 306
 307 For example:
 308
 309 Total Connections:
 310
 311 >   dn: cn=Total,cn=Connections,cn=Monitor
 312 >   structuralObjectClass: monitorCounterObject
 313 >   monitorCounter: 4
 314 >   entryDN: cn=Total,cn=Connections,cn=Monitor
 315 >   subschemaSubentry: cn=Subschema
 316 >   hasSubordinates: FALSE
 317
 318 Current Connections:
 319
 320 >   dn: cn=Current,cn=Connections,cn=Monitor
 321 >   structuralObjectClass: monitorCounterObject
 322 >   monitorCounter: 2
 323 >   entryDN: cn=Current,cn=Connections,cn=Monitor
 324 >   subschemaSubentry: cn=Subschema
 325 >   hasSubordinates: FALSE
 326
 327
 328 H3: Databases
 329
 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
 332 context.
 333
 334 For example:
 335
 336 >   dn: cn=Database 2,cn=Databases,cn=Monitor
 337 >   structuralObjectClass: monitoredObject
 338 >   monitoredInfo: monitor
 339 >   monitorIsShadow: FALSE
 340 >   monitorContext: cn=Monitor
 341 >   readOnly: FALSE
 342 >   entryDN: cn=Database 2,cn=Databases,cn=Monitor
 343 >   subschemaSubentry: cn=Subschema
 344 >   hasSubordinates: FALSE
 345
 346 H3: Listener
 347
 348 It contains the description of the devices the server is currently
 349 listening on:
 350
 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
 357
 358
 359 H3: Log
 360
 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:
 364
 365 >   Trace
 366 >   Packets
 367 >   Args
 368 >   Conns
 369 >   BER
 370 >   Filter
 371 >   Config
 372 >   ACL
 373 >   Stats
 374 >   Stats2
 375 >   Shell
 376 >   Parse
 377 >   Sync
 378
 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.
 382
 383 H3: Operations
 384
 385 It shows some statistics on the operations performed by the server:
 386
 387 >   Initiated
 388 >   Completed
 389
 390 and for each operation type, i.e.:
 391
 392 >   Bind
 393 >   Unbind
 394 >   Add
 395 >   Delete
 396 >   Modrdn
 397 >   Modify
 398 >   Compare
 399 >   Search
 400 >   Abandon
 401 >   Extended
 402
 403 There are too many types to list example here, so please try for yourself
 404 using {{SECT: Monitor search example}}
 405
 406 H3: Overlays
 407
 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.
 410
 411 It should also contain the modules that have been loaded if dynamic
 412 overlays are enabled:
 413
 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
 423
 424 H3: SASL
 425
 426 Currently empty.
 427
 428 H3: Statistics
 429
 430 It shows some statistics on the data sent by the server:
 431
 432 >   Bytes
 433 >   PDU
 434 >   Entries
 435 >   Referrals
 436
 437 e.g.
 438
 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
 446
 447 H3: Threads
 448
 449 It contains the maximum number of threads enabled at startup and the
 450 current backload.
 451
 452 e.g.
 453
 454 >   # Max, Threads, Monitor
 455 >   dn: cn=Max,cn=Threads,cn=Monitor
 456 >   structuralObjectClass: monitoredObject
 457 >   monitoredInfo: 16
 458 >   entryDN: cn=Max,cn=Threads,cn=Monitor
 459 >   subschemaSubentry: cn=Subschema
 460 >   hasSubordinates: FALSE
 461
 462
 463 H3: Time
 464
 465 It contains two child entries with the start time and the current time
 466 of the server.
 467
 468 e.g.
 469
 470 Start time:
 471
 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
 478
 479 Current time:
 480
 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
 487
 488 H3: TLS
 489
 490 Currently empty.
 491
 492 H3: Waiters
 493
 494 It contains the number of current read waiters.
 495
 496 e.g.
 497
 498 Read waiters:
 499
 500 >   dn: cn=Read,cn=Waiters,cn=Monitor
 501 >   structuralObjectClass: monitorCounterObject
 502 >   monitorCounter: 7
 503 >   entryDN: cn=Read,cn=Waiters,cn=Monitor
 504 >   subschemaSubentry: cn=Subschema
 505 >   hasSubordinates: FALSE
 506
 507 Write waiters:
 508
 509 >   dn: cn=Write,cn=Waiters,cn=Monitor
 510 >   structuralObjectClass: monitorCounterObject
 511 >   monitorCounter: 0
 512 >   entryDN: cn=Write,cn=Waiters,cn=Monitor
 513 >   subschemaSubentry: cn=Subschema
 514 >   hasSubordinates: FALSE
 515
 516 Add new monitored things here and discuss, referencing man pages and present
 517 examples
 518
 519