1# OpenLDAP: pkg/openldap-guide/admin/monitoringslapd.sdf,v 1.9.2.6 2009/01/22 00:00:47 kurt Exp 2# Copyright 1999-2009 The OpenLDAP Foundation, All Rights Reserved. 3# COPYING RESTRICTIONS APPLY, see COPYRIGHT. 4H1: Monitoring 5 6{{slapd}}(8) supports an optional {{TERM:LDAP}} monitoring interface 7you can use to obtain information regarding the current state of 8your {{slapd}} instance. For instance, the interface allows you 9to determine how many clients are connected to the server currently. 10The monitoring information is provided by a specialized backend, 11the {{monitor}} backend. A manual page, {{slapd-monitor}}(5) is 12available. 13 14When the monitoring interface is enabled, LDAP clients may be used 15to access information provided by the {{monitor}} backend, subject 16to access and other controls. 17 18When enabled, the {{monitor}} backend dynamically generates and 19returns objects in response to search requests in the {{cn=Monitor}} 20subtree. Each object contains information about a particular aspect 21of the server. The information is held in a combination of user 22applications and operational attributes. This information can be 23access with {{ldapsearch(1)}}, with any general-purpose LDAP browser, 24or with specialized monitoring tools. The {{SECT:Accessing Monitoring 25Information}} 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 28base and its organization. 29 30While support for the monitor backend is included in default builds 31of slapd(8), this support requires some configuration to become 32active. This may be done using either {{EX:cn=config}} or 33{{slapd.conf}}(5). The former is discussed in the {{SECT:Monitor 34configuration via cn=config}} section of this of this chapter. The 35latter is discussed in the {{SECT:Monitor configuration via 36slapd.conf(5)}} section of this chapter. These sections assume 37monitor backend is built into {{slapd}} (e.g., {{EX:--enable-monitor=yes}}, 38the default). If the monitor backend was built as a module (e.g., 39{{EX:--enable-monitor=mod}}, this module must loaded. Loading of 40modules is discussed in the {{SECT:Configuring slapd}} and {{SECT:The 41slapd Configuration File}} chapters. 42 43 44H2: Monitor configuration via cn=config(5) 45 46{{This section has yet to be written.}} 47 48 49H2: Monitor configuration via slapd.conf(5) 50 51Configuration of the slapd.conf(5) to support LDAP monitoring 52is quite simple. 53 54First, ensure {{core.schema}} schema configuration file is included 55by your {{slapd.conf}}(5) file. The {{monitor}} backend requires 56it. 57 58Second, instantiate the {{monitor backend}} by adding a 59{{database monitor}} directive below your existing database 60sections. For instance: 61 62> database monitor 63 64Lastly, add additional global or database directives as needed. 65 66Like most other database backends, the monitor backend does honor 67slapd(8) access and other administrative controls. As some monitor 68information may be sensitive, it is generally recommend access to 69cn=monitor be restricted to directory administrators and their 70monitoring agents. Adding an {{access}} directive immediately below 71the {{database monitor}} directive is a clear and effective approach 72for controlling access. For instance, the addition of the following 73{{access}} directive immediately below the {{database monitor}} 74directive restricts access to monitoring information to the specified 75directory manager. 76 77> access to * 78> by dn.exact="cn=Manager,dc=example,dc=com 79> by * none 80 81More information on {{slapd}}(8) access controls, see {{The access 82Control Directive}} section of the {{SECT:The slapd Configuration 83File}} chapter and {{slapd.access}}(5). 84 85After restarting {{slapd}}(8), you are ready to start exploring the 86monitoring information provided in {{EX:cn=config}} as discussed 87in the {{SECT:Accessing Monitoring Information}} section of this 88chapter. 89 90One can verify slapd(8) is properly configured to provide monitoring 91information by attempting to read the {{EX:cn=monitor}} object. 92For instance, if the following {{ldapsearch}}(1) command returns the 93cn=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 98Note that unlike general purpose database backends, the database 99suffix is hardcoded. It's always {{EX:cn=Monitor}}. So no {{suffix}} 100directive should be provided. Also note that general purpose 101database backends, the monitor backend cannot be instantiated 102multiple times. That is, there can only be one (or zero) occurrences 103of {{EX:database monitor}} in the server's configuration. 104 105 106H2: Accessing Monitoring Information 107 108As previously discussed, when enabled, the {{monitor}} backend 109dynamically generates and returns objects in response to search 110requests in the {{cn=Monitor}} subtree. Each object contains 111information about a particular aspect of the server. The information 112is held in a combination of user applications and operational 113attributes. This information can be access with {{ldapsearch(1)}}, 114with any general-purpose LDAP browser, or with specialized monitoring 115tools. 116 117This section provides a provides a brief tutorial on how to use 118{{ldapsearch}}(1) to access monitoring information. 119 120To inspect any particular monitor object, one performs search 121operation on the object with a baseObject scope and a 122{{EX:(objectClass=*)}} filter. As the monitoring information is 123contained in a combination of user applications and operational 124attributes, the return all user applications attributes (e.g., 125{{EX:'*'}}) and all operational attributes (e.g., {{EX:'+'}}) should 126be requested. For instance, to read the {{EX:cn=Monitor}} object 127itself, the {{ldapsearch}}(1) command (modified to fit your configuration) 128can be used: 129 130> ldapsearch -x -D 'cn=Manager,dc=example,dc=com' -W \ 131> -b 'cn=Monitor' -s base '(objectClass=*)' '*' '+' 132 133When run against your server, this should produce output 134similar 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 153To reduce the number of uninteresting attributes returned, one 154can be more selective when requesting which attributes are to be 155returned. For instance, one could request the return of all 156attributes allowed by the {{monitorServer}} object class (e.g., 157{{EX:@objectClass}}) instead of all user and all operational 158attributes: 159 160> ldapsearch -x -D 'cn=Manager,dc=example,dc=com' -W \ 161> -b 'cn=Monitor' -s base '(objectClass=*)' '@monitorServer' 162 163This 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 174To return the names of all the monitoring objects, one performs a 175search of {{EX:cn=Monitor}} with subtree scope and {{EX:(objectClass=*)}} 176filter 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 180If you run this command you will discover that there are many objects 181in the {{cn=Monitor}} subtree. The following section describes 182some of the commonly available monitoring objects. 183 184 185H2: Monitor Information 186 187The {{monitor}} backend provides a wealth of information useful 188for monitoring the slapd(8) contained in set of monitor objects. 189Each object contains information about a particular aspect of 190the server, such as a backends, a connection, or a thread. 191Some objects serve as containers for other objects and used 192to construct a hierarchy of objects. 193 194In this hierarchy, the most superior object is {cn=Monitor}. 195While this object primarily serves as a container for other 196objects, most of which are containers, this object provides 197information about this server. In particular, it provides the 198slapd(8) version string. Example: 199 200> dn: cn=Monitor 201> monitoredInfo: OpenLDAP: slapd 2.X (Dec 7 2006 17:30:29) 202 203Note: Examples in this section (and its subsections) have been 204trimmed to show only key information. 205 206 207H3: Backends 208 209The {{EX:cn=Backends,cn=Monitor}} object, itself, provides a list 210of available backends. The list of available backends all builtin 211backends, 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 220This indicates the {{config}}, {{ldif}}, {{monitor}}, {{bdb}}, 221and {{hdb}} backends are available. 222 223The {{EX:cn=Backends,cn=Monitor}} object is also a container 224for available backend objects. Each available backend object 225contains 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 271For each of these objects, monitorInfo indicates which backend the 272information in the object is about. For instance, the {{EX:cn=Backend 2733,cn=Backends,cn=Monitor}} object contains (in the example) information 274about the {{bdb}} backend. 275 276!block table 277Attribute|Description 278monitoredInfo|Name of backend 279supportedControl|supported LDAP control extensions 280seeAlso|Database objects of instances of this backend 281!endblock 282 283H3: Connections 284 285The main entry is empty; it should contain some statistics on the number 286of connections. 287 288Dynamic child entries are created for each open connection, with stats on 289the activity on that connection (the format will be detailed later). 290There are two special child entries that show the number of total and 291current connections respectively. 292 293For example: 294 295Total 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 304Current 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 314H3: Databases 315 316The main entry contains the naming context of each configured database; 317the child entries contain, for each database, the type and the naming 318context. 319 320For 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 332H3: Listener 333 334It contains the description of the devices the server is currently 335listening 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 345H3: Log 346 347It contains the currently active log items. The {{Log}} subsystem allows 348user modify operations on the {{description}} attribute, whose values {{MUST}} 349be 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 365These values can be added, replaced or deleted; they affect what 366messages are sent to the syslog device. 367Custom values could be added by custom modules. 368 369H3: Operations 370 371It shows some statistics on the operations performed by the server: 372 373> Initiated 374> Completed 375 376and 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 389There are too many types to list example here, so please try for yourself 390using {{SECT: Monitor search example}} 391 392H3: Overlays 393 394The main entry contains the type of overlays available at run-time; 395the child entries, for each overlay, contain the type of the overlay. 396 397It should also contain the modules that have been loaded if dynamic 398overlays 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 410H3: SASL 411 412Currently empty. 413 414H3: Statistics 415 416It shows some statistics on the data sent by the server: 417 418> Bytes 419> PDU 420> Entries 421> Referrals 422 423e.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 433H3: Threads 434 435It contains the maximum number of threads enabled at startup and the 436current backload. 437 438e.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 449H3: Time 450 451It contains two child entries with the start time and the current time 452of the server. 453 454e.g. 455 456Start 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 465Current 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 474H3: TLS 475 476Currently empty. 477 478H3: Waiters 479 480It contains the number of current read waiters. 481 482e.g. 483 484Read 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 493Write 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 502Add new monitored things here and discuss, referencing man pages and present 503examples 504 505 506