1# $OpenLDAP$ 2# Copyright 1999-2021 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 46The {{monitor backend}} is statically built into slapd and can be 47instantiated via ldapadd. 48 49> dn: olcDatabase=monitor,cn=config 50> objectClass: olcDatabaseConfig 51> olcDatabase: monitor 52 53H2: Monitor configuration via slapd.conf(5) 54 55Configuration of the slapd.conf(5) to support LDAP monitoring 56is quite simple. 57 58First, ensure {{core.schema}} schema configuration file is included 59by your {{slapd.conf}}(5) file. The {{monitor}} backend requires 60it. 61 62Second, instantiate the {{monitor backend}} by adding a 63{{database monitor}} directive below your existing database 64sections. For instance: 65 66> database monitor 67 68Lastly, add additional global or database directives as needed. 69 70Like most other database backends, the monitor backend does honor 71slapd(8) access and other administrative controls. As some monitor 72information may be sensitive, it is generally recommend access to 73cn=monitor be restricted to directory administrators and their 74monitoring agents. Adding an {{access}} directive immediately below 75the {{database monitor}} directive is a clear and effective approach 76for controlling access. For instance, the addition of the following 77{{access}} directive immediately below the {{database monitor}} 78directive restricts access to monitoring information to the specified 79directory manager. 80 81> access to * 82> by dn.exact="cn=Manager,dc=example,dc=com 83> by * none 84 85More information on {{slapd}}(8) access controls, see {{The access 86Control Directive}} section of the {{SECT:The slapd Configuration 87File}} chapter and {{slapd.access}}(5). 88 89After restarting {{slapd}}(8), you are ready to start exploring the 90monitoring information provided in {{EX:cn=config}} as discussed 91in the {{SECT:Accessing Monitoring Information}} section of this 92chapter. 93 94One can verify slapd(8) is properly configured to provide monitoring 95information by attempting to read the {{EX:cn=monitor}} object. 96For instance, if the following {{ldapsearch}}(1) command returns the 97cn=monitor object (with, as requested, no attributes), it's working. 98 99> ldapsearch -x -D 'cn=Manager,dc=example,dc=com' -W \ 100> -b 'cn=Monitor' -s base 1.1 101 102Note that unlike general purpose database backends, the database 103suffix is hardcoded. It's always {{EX:cn=Monitor}}. So no {{suffix}} 104directive should be provided. Also note that general purpose 105database backends, the monitor backend cannot be instantiated 106multiple times. That is, there can only be one (or zero) occurrences 107of {{EX:database monitor}} in the server's configuration. 108 109 110H2: Accessing Monitoring Information 111 112As previously discussed, when enabled, the {{monitor}} backend 113dynamically generates and returns objects in response to search 114requests in the {{cn=Monitor}} subtree. Each object contains 115information about a particular aspect of the server. The information 116is held in a combination of user applications and operational 117attributes. This information can be accessed with {{ldapsearch(1)}}, 118with any general-purpose LDAP browser, or with specialized monitoring 119tools. 120 121This section provides a provides a brief tutorial on how to use 122{{ldapsearch}}(1) to access monitoring information. 123 124To inspect any particular monitor object, one performs search 125operation on the object with a baseObject scope and a 126{{EX:(objectClass=*)}} filter. As the monitoring information is 127contained in a combination of user applications and operational 128attributes, the return all user applications attributes (e.g., 129{{EX:'*'}}) and all operational attributes (e.g., {{EX:'+'}}) should 130be requested. For instance, to read the {{EX:cn=Monitor}} object 131itself, the {{ldapsearch}}(1) command (modified to fit your configuration) 132can be used: 133 134> ldapsearch -x -D 'cn=Manager,dc=example,dc=com' -W \ 135> -b 'cn=Monitor' -s base '(objectClass=*)' '*' '+' 136 137When run against your server, this should produce output 138similar to: 139 140> dn: cn=Monitor 141> objectClass: monitorServer 142> structuralObjectClass: monitorServer 143> cn: Monitor 144> creatorsName: 145> modifiersName: 146> createTimestamp: 20061208223558Z 147> modifyTimestamp: 20061208223558Z 148> description: This subtree contains monitoring/managing objects. 149> description: This object contains information about this server. 150> description: Most of the information is held in operational attributes, which 151> must be explicitly requested. 152> monitoredInfo: OpenLDAP: slapd 2.5 (Dec 7 2006 17:30:29) 153> entryDN: cn=Monitor 154> subschemaSubentry: cn=Subschema 155> hasSubordinates: TRUE 156 157To reduce the number of uninteresting attributes returned, one 158can be more selective when requesting which attributes are to be 159returned. For instance, one could request the return of all 160attributes allowed by the {{monitorServer}} object class (e.g., 161{{EX:@objectClass}}) instead of all user and all operational 162attributes: 163 164> ldapsearch -x -D 'cn=Manager,dc=example,dc=com' -W \ 165> -b 'cn=Monitor' -s base '(objectClass=*)' '@monitorServer' 166 167This limits the output as follows: 168 169> dn: cn=Monitor 170> objectClass: monitorServer 171> cn: Monitor 172> description: This subtree contains monitoring/managing objects. 173> description: This object contains information about this server. 174> description: Most of the information is held in operational attributes, which 175> must be explicitly requested. 176> monitoredInfo: OpenLDAP: slapd 2.X (Dec 7 2006 17:30:29) 177 178To return the names of all the monitoring objects, one performs a 179search of {{EX:cn=Monitor}} with subtree scope and {{EX:(objectClass=*)}} 180filter and requesting no attributes (e.g., {{EX:1.1}}) be returned. 181 182> ldapsearch -x -D 'cn=Manager,dc=example,dc=com' -W -b 'cn=Monitor' -s sub 1.1 183 184If you run this command you will discover that there are many objects 185in the {{cn=Monitor}} subtree. The following section describes 186some of the commonly available monitoring objects. 187 188 189H2: Monitor Information 190 191The {{monitor}} backend provides a wealth of information useful 192for monitoring the slapd(8) contained in set of monitor objects. 193Each object contains information about a particular aspect of 194the server, such as a backends, a connection, or a thread. 195Some objects serve as containers for other objects and used 196to construct a hierarchy of objects. 197 198In this hierarchy, the most superior object is {cn=Monitor}. 199While this object primarily serves as a container for other 200objects, most of which are containers, this object provides 201information about this server. In particular, it provides the 202slapd(8) version string. Example: 203 204> dn: cn=Monitor 205> monitoredInfo: OpenLDAP: slapd 2.X (Dec 7 2006 17:30:29) 206 207Note: Examples in this section (and its subsections) have been 208trimmed to show only key information. 209 210 211H3: Backends 212 213The {{EX:cn=Backends,cn=Monitor}} object, itself, provides a list 214of available backends. The list of available backends all builtin 215backends, as well as backends loaded by modules. For example: 216 217> dn: cn=Backends,cn=Monitor 218> monitoredInfo: config 219> monitoredInfo: ldif 220> monitoredInfo: monitor 221> monitoredInfo: mdb 222 223This indicates the {{config}}, {{ldif}}, {{monitor}}, 224and {{mdb}} backends are available. 225 226The {{EX:cn=Backends,cn=Monitor}} object is also a container 227for available backend objects. Each available backend object 228contains information about a particular backend. For example: 229 230> dn: cn=Backend 0,cn=Backends,cn=Monitor 231> monitoredInfo: config 232> monitorRuntimeConfig: TRUE 233> supportedControl: 2.16.840.1.113730.3.4.2 234> seeAlso: cn=Database 0,cn=Databases,cn=Monitor 235> 236> dn: cn=Backend 1,cn=Backends,cn=Monitor 237> monitoredInfo: ldif 238> monitorRuntimeConfig: TRUE 239> supportedControl: 2.16.840.1.113730.3.4.2 240> 241> dn: cn=Backend 2,cn=Backends,cn=Monitor 242> monitoredInfo: monitor 243> monitorRuntimeConfig: TRUE 244> supportedControl: 2.16.840.1.113730.3.4.2 245> seeAlso: cn=Database 2,cn=Databases,cn=Monitor 246> 247> dn: cn=Backend 3,cn=Backends,cn=Monitor 248> monitoredInfo: mdb 249> monitorRuntimeConfig: TRUE 250> supportedControl: 1.3.6.1.1.12 251> supportedControl: 2.16.840.1.113730.3.4.2 252> supportedControl: 1.3.6.1.4.1.4203.666.5.2 253> supportedControl: 1.2.840.113556.1.4.319 254> supportedControl: 1.3.6.1.1.13.1 255> supportedControl: 1.3.6.1.1.13.2 256> supportedControl: 1.3.6.1.4.1.4203.1.10.1 257> supportedControl: 1.2.840.113556.1.4.1413 258> supportedControl: 1.3.6.1.4.1.4203.666.11.7.2 259 260For each of these objects, monitorInfo indicates which backend the 261information in the object is about. For instance, the {{EX:cn=Backend 2625,cn=Backends,cn=Monitor}} object contains (in the example) information 263about the {{mdb}} backend. 264 265!block table 266Attribute|Description 267monitoredInfo|Name of backend 268supportedControl|supported LDAP control extensions 269seeAlso|Database objects of instances of this backend 270!endblock 271 272H3: Connections 273 274The main entry is empty; it should contain some statistics on the number 275of connections. 276 277Dynamic child entries are created for each open connection, with stats on 278the activity on that connection (the format will be detailed later). 279There are two special child entries that show the number of total and 280current connections respectively. 281 282For example: 283 284Total Connections: 285 286> dn: cn=Total,cn=Connections,cn=Monitor 287> structuralObjectClass: monitorCounterObject 288> monitorCounter: 4 289> entryDN: cn=Total,cn=Connections,cn=Monitor 290> subschemaSubentry: cn=Subschema 291> hasSubordinates: FALSE 292 293Current Connections: 294 295> dn: cn=Current,cn=Connections,cn=Monitor 296> structuralObjectClass: monitorCounterObject 297> monitorCounter: 2 298> entryDN: cn=Current,cn=Connections,cn=Monitor 299> subschemaSubentry: cn=Subschema 300> hasSubordinates: FALSE 301 302 303H3: Databases 304 305The main entry contains the naming context of each configured database; 306the child entries contain, for each database, the type and the naming 307context. 308 309For example: 310 311> dn: cn=Database 2,cn=Databases,cn=Monitor 312> structuralObjectClass: monitoredObject 313> monitoredInfo: monitor 314> monitorIsShadow: FALSE 315> monitorContext: cn=Monitor 316> readOnly: FALSE 317> entryDN: cn=Database 2,cn=Databases,cn=Monitor 318> subschemaSubentry: cn=Subschema 319> hasSubordinates: FALSE 320 321H3: Listener 322 323It contains the description of the devices the server is currently 324listening on: 325 326> dn: cn=Listener 0,cn=Listeners,cn=Monitor 327> structuralObjectClass: monitoredObject 328> monitorConnectionLocalAddress: IP=0.0.0.0:389 329> entryDN: cn=Listener 0,cn=Listeners,cn=Monitor 330> subschemaSubentry: cn=Subschema 331> hasSubordinates: FALSE 332 333 334H3: Log 335 336It contains the currently active log items. The {{Log}} subsystem allows 337user modify operations on the {{description}} attribute, whose values {{MUST}} 338be in the list of admittable log switches: 339 340> Trace 341> Packets 342> Args 343> Conns 344> BER 345> Filter 346> Config 347> ACL 348> Stats 349> Stats2 350> Shell 351> Parse 352> Sync 353 354These values can be added, replaced or deleted; they affect what 355messages are sent to the syslog device. 356Custom values could be added by custom modules. 357 358H3: Operations 359 360It shows some statistics on the operations performed by the server: 361 362> Initiated 363> Completed 364 365and for each operation type, i.e.: 366 367> Bind 368> Unbind 369> Add 370> Delete 371> Modrdn 372> Modify 373> Compare 374> Search 375> Abandon 376> Extended 377 378There are too many types to list example here, so please try for yourself 379using {{SECT: Monitor search example}} 380 381H3: Overlays 382 383The main entry contains the type of overlays available at run-time; 384the child entries, for each overlay, contain the type of the overlay. 385 386It should also contain the modules that have been loaded if dynamic 387overlays are enabled: 388 389> # Overlays, Monitor 390> dn: cn=Overlays,cn=Monitor 391> structuralObjectClass: monitorContainer 392> monitoredInfo: syncprov 393> monitoredInfo: accesslog 394> monitoredInfo: glue 395> entryDN: cn=Overlays,cn=Monitor 396> subschemaSubentry: cn=Subschema 397> hasSubordinates: TRUE 398 399H3: SASL 400 401Currently empty. 402 403H3: Statistics 404 405It shows some statistics on the data sent by the server: 406 407> Bytes 408> PDU 409> Entries 410> Referrals 411 412e.g. 413 414> # Entries, Statistics, Monitor 415> dn: cn=Entries,cn=Statistics,cn=Monitor 416> structuralObjectClass: monitorCounterObject 417> monitorCounter: 612248 418> entryDN: cn=Entries,cn=Statistics,cn=Monitor 419> subschemaSubentry: cn=Subschema 420> hasSubordinates: FALSE 421 422H3: Threads 423 424It contains the maximum number of threads enabled at startup and the 425current backload. 426 427e.g. 428 429> # Max, Threads, Monitor 430> dn: cn=Max,cn=Threads,cn=Monitor 431> structuralObjectClass: monitoredObject 432> monitoredInfo: 16 433> entryDN: cn=Max,cn=Threads,cn=Monitor 434> subschemaSubentry: cn=Subschema 435> hasSubordinates: FALSE 436 437 438H3: Time 439 440It contains two child entries with the start time and the current time 441of the server. 442 443e.g. 444 445Start time: 446 447> dn: cn=Start,cn=Time,cn=Monitor 448> structuralObjectClass: monitoredObject 449> monitorTimestamp: 20061205124040Z 450> entryDN: cn=Start,cn=Time,cn=Monitor 451> subschemaSubentry: cn=Subschema 452> hasSubordinates: FALSE 453 454Current time: 455 456> dn: cn=Current,cn=Time,cn=Monitor 457> structuralObjectClass: monitoredObject 458> monitorTimestamp: 20061207120624Z 459> entryDN: cn=Current,cn=Time,cn=Monitor 460> subschemaSubentry: cn=Subschema 461> hasSubordinates: FALSE 462 463H3: TLS 464 465Currently empty. 466 467H3: Waiters 468 469It contains the number of current read waiters. 470 471e.g. 472 473Read waiters: 474 475> dn: cn=Read,cn=Waiters,cn=Monitor 476> structuralObjectClass: monitorCounterObject 477> monitorCounter: 7 478> entryDN: cn=Read,cn=Waiters,cn=Monitor 479> subschemaSubentry: cn=Subschema 480> hasSubordinates: FALSE 481 482Write waiters: 483 484> dn: cn=Write,cn=Waiters,cn=Monitor 485> structuralObjectClass: monitorCounterObject 486> monitorCounter: 0 487> entryDN: cn=Write,cn=Waiters,cn=Monitor 488> subschemaSubentry: cn=Subschema 489> hasSubordinates: FALSE 490 491Add new monitored things here and discuss, referencing man pages and present 492examples 493 494 495