# $OpenLDAP$
# Copyright 1999-2006 The OpenLDAP Foundation, All Rights Reserved.
# COPYING RESTRICTIONS APPLY, see COPYRIGHT.
H1: Monitoring Slapd

{{slapd}}(8) supports a monitoring interface you can use to obtain
information regarding the current state of your {{slapd}} instance.
For instance, the interface allows you to determine how many clients
are connected to the server currently.  The interface is accessed
used {{TERM:LDAP}} and is provided via the {{monitor}} backend.  A
manual page, {{slapd-monitor}}(5) is available.

The monitor backend to {{slapd}} is not an actual database; if
enabled, it is automatically generated and dynamically maintained
by {{slapd}} with information about the running status of the daemon.

To inspect all monitor information, one can issue a subtree search
with base {{EX:cn=Monitor}} and filter {{EX:(objectClass=*)}},
requesting the return of all user (e.g., '*') and operational (e.g.,
'+' attributes.   Many of the attributes provided by monitor backend
are operational attributes, and hence will not be returned unless
explicitly requested.  For example:

> ldapsearch -x -D 'cn=Manager,dc=example,dc=com' -W -b 'cn=Monitor' '+' '*'

As there are may be many objects under {{EX:cn=Monitor}}, a search
with a narrower search criteria may be more appropriate.

Support for the monitor backend is included in slapd(8) in default
builds.  The monitor backend may also be built as a loadable module.
The remainder of this section assumes slapd(8) was with with monitor
backend support (e.g., {{EX:--enable-monitor=yes}}, the default),
or build as a module (e.g., {{EX:--enable-monitor=mod}} and loaded
into slapd(8).


H2: Configuration

These {{slapd.conf}}(5) options apply to the monitor backend database.
That is, they must follow a {{EX:database monitor}} line and come
before any subsequent {{backend}} or {{database}} lines.

As opposed to most databases, the monitor database can be instantiated
only once, i.e. only  one  occurrence  of {{EX:database monitor}}
can occur in the {{slapd.conf}}(5) file. Moreover, the suffix of
the database cannot be explicitly set by means of the suffix
directive.  The suffix is automatically set to {{EX:cn=Monitor}}

The monitor backend honors access control semantics as indicated
in {{slapd.access}}(5), including the disclose access privilege,
on all currently implemented operations.

For understanding how to do the following with dynamic configuration, 
see {{SECT:Configuring slapd}}

Also ensure that the {{core.schema}} file is loaded. The monitor
backend relies on some standard track {{attributeTypes}} that must
be already defined when the backend is started.

H3: Activate the monitor database

Put this in your {{slapd.conf}}(5) or via the {{config}} backend

>   database monitor

You may also specify a {{rootpw}} below this

H3: Add ACLs

Here's an example you might use:

>   access to dn.subtree="cn=Monitor"
>       by dn.exact="uid=Admin,dc=my,dc=org" write
>       by users read
>       by * none

More information is detailed in {{slapd.access}}(5)

H2: Available Subsystems

There are various subsytems you can explicitly query for, with most
information being held in the {{monitoredInfo}} attribute.

H3: Backends

The main entry contains the type of backends enabled at compile
time; the subentries, for each backend, contain the type of the
backend.  It should also contain the modules that have been loaded
if dynamic backends are enabled.

For example:

>   dn: cn=Backend 1,cn=Backends,cn=Monitor
>   structuralObjectClass: monitoredObject
>   monitoredInfo: ldif
>   monitorRuntimeConfig: TRUE
>   supportedControl: 2.16.840.1.113730.3.4.2
>   entryDN: cn=Backend 1,cn=Backends,cn=Monitor
>   subschemaSubentry: cn=Subschema
>   hasSubordinates: FALSE
>
>   dn: cn=Backend 2,cn=Backends,cn=Monitor
>   structuralObjectClass: monitoredObject
>   monitoredInfo: hdb
>   monitorRuntimeConfig: TRUE
>   supportedControl: 1.3.6.1.1.12
>   supportedControl: 2.16.840.1.113730.3.4.2
>   supportedControl: 1.3.6.1.4.1.4203.666.5.2
>   supportedControl: 1.2.840.113556.1.4.319
>   supportedControl: 1.3.6.1.1.13.1
>   supportedControl: 1.3.6.1.1.13.2
>   supportedControl: 1.3.6.1.4.1.4203.1.10.1
>   supportedControl: 1.2.840.113556.1.4.1413
>   entryDN: cn=Backend 2,cn=Backends,cn=Monitor
>   subschemaSubentry: cn=Subschema
>   hasSubordinates: FALSE
>
>   # Backend 3, Backends, Monitor
>   dn: cn=Backend 3,cn=Backends,cn=Monitor
>   structuralObjectClass: monitoredObject
>   monitoredInfo: monitor
>   monitorRuntimeConfig: TRUE
>   supportedControl: 2.16.840.1.113730.3.4.2
>   entryDN: cn=Backend 3,cn=Backends,cn=Monitor
>   subschemaSubentry: cn=Subschema
>   hasSubordinates: FALSE

In this example, the server has three backends: 1) a {{ldif}} backend,
2) a {{hdb}} backend, and 3) a {{monitor}} backend.


H3: Connections

The main entry is empty; it should contain some statistics on the number 
of connections.

Dynamic subentries are created for each open connection, with stats on
the activity on that connection (the format will be detailed later).
There are two special subentries that show the number of total and
current connections respectively.

For example:

Total Connections:

>   dn: cn=Total,cn=Connections,cn=Monitor
>   structuralObjectClass: monitorCounterObject
>   monitorCounter: 4
>   entryDN: cn=Total,cn=Connections,cn=Monitor
>   subschemaSubentry: cn=Subschema
>   hasSubordinates: FALSE

Current Connections:

>   dn: cn=Current,cn=Connections,cn=Monitor
>   structuralObjectClass: monitorCounterObject
>   monitorCounter: 2
>   entryDN: cn=Current,cn=Connections,cn=Monitor
>   subschemaSubentry: cn=Subschema
>   hasSubordinates: FALSE


H3: Databases

The main entry contains the naming context of each configured database; 
the subentries contain, for each database, the type and the naming
context.

For example:

>   # Database 2, Databases, Monitor
>   dn: cn=Database 2,cn=Databases,cn=Monitor
>   structuralObjectClass: monitoredObject
>   monitoredInfo: monitor
>   monitorIsShadow: FALSE
>   monitorContext: cn=Monitor
>   readOnly: FALSE
>   entryDN: cn=Database 2,cn=Databases,cn=Monitor
>   subschemaSubentry: cn=Subschema
>   hasSubordinates: FALSE

H3: Listener

It contains the description of the devices the server is currently 
listening on:

>   # Listener 0, Listeners, Monitor
>   dn: cn=Listener 0,cn=Listeners,cn=Monitor
>   structuralObjectClass: monitoredObject
>   monitorConnectionLocalAddress: IP=0.0.0.0:389
>   entryDN: cn=Listener 0,cn=Listeners,cn=Monitor
>   subschemaSubentry: cn=Subschema
>   hasSubordinates: FALSE


H3: Log

It contains the currently active log items.  The {{Log}} subsystem allows 
user modify operations on the {{description}} attribute, whose values {{MUST}} 
be in the list of admittable log switches:

>   Trace
>   Packets
>   Args
>   Conns
>   BER
>   Filter
>   Config		(useless)
>   ACL
>   Stats
>   Stats2
>   Shell
>   Parse
>   Cache		(deprecated)
>   Index

These values can be added, replaced or deleted; they affect what 
messages are sent to the syslog device.

H3: Operations

It shows some statistics on the operations performed by the server:

>   Initiated
>   Completed

and for each operation type, i.e.:

>   Bind
>   Unbind
>   Add
>   Delete
>   Modrdn
>   Modify
>   Compare
>   Search
>   Abandon
>   Extended

There are too many types to list example here, so please try for yourself 
using {{SECT: Monitor search example}}

H3: Overlays

The main entry contains the type of overlays available at run-time;
the subentries, for each overlay, contain the type of the overlay.

It should also contain the modules that have been loaded if dynamic 
overlays are enabled:

>   # Overlays, Monitor
>   dn: cn=Overlays,cn=Monitor
>   structuralObjectClass: monitorContainer
>   monitoredInfo: syncprov
>   monitoredInfo: accesslog
>   monitoredInfo: glue
>   entryDN: cn=Overlays,cn=Monitor
>   subschemaSubentry: cn=Subschema
>   hasSubordinates: TRUE

H3: SASL

Currently empty.

H3: Statistics

It shows some statistics on the data sent by the server:

>   Bytes
>   PDU
>   Entries
>   Referrals

e.g.

>   # Entries, Statistics, Monitor
>   dn: cn=Entries,cn=Statistics,cn=Monitor
>   structuralObjectClass: monitorCounterObject
>   monitorCounter: 612248
>   entryDN: cn=Entries,cn=Statistics,cn=Monitor
>   subschemaSubentry: cn=Subschema
>   hasSubordinates: FALSE

H3: Threads

It contains the maximum number of threads enabled at startup and the 
current backload.

e.g.

>   # Max, Threads, Monitor
>   dn: cn=Max,cn=Threads,cn=Monitor
>   structuralObjectClass: monitoredObject
>   monitoredInfo: 16
>   entryDN: cn=Max,cn=Threads,cn=Monitor
>   subschemaSubentry: cn=Subschema
>   hasSubordinates: FALSE


H3: Time

It contains two subentries with the start time and the current time 
of the server.

e.g.

Start time:

>   dn: cn=Start,cn=Time,cn=Monitor
>   structuralObjectClass: monitoredObject
>   monitorTimestamp: 20061205124040Z
>   entryDN: cn=Start,cn=Time,cn=Monitor
>   subschemaSubentry: cn=Subschema
>   hasSubordinates: FALSE

Current time:

>   dn: cn=Current,cn=Time,cn=Monitor
>   structuralObjectClass: monitoredObject
>   monitorTimestamp: 20061207120624Z
>   entryDN: cn=Current,cn=Time,cn=Monitor
>   subschemaSubentry: cn=Subschema
>   hasSubordinates: FALSE

H3: TLS

Currently empty.

H3: Waiters

It contains the number of current read waiters.

e.g.

Read waiters:

>   dn: cn=Read,cn=Waiters,cn=Monitor
>   structuralObjectClass: monitorCounterObject
>   monitorCounter: 7
>   entryDN: cn=Read,cn=Waiters,cn=Monitor
>   subschemaSubentry: cn=Subschema
>   hasSubordinates: FALSE

Write waiters:

>   dn: cn=Write,cn=Waiters,cn=Monitor
>   structuralObjectClass: monitorCounterObject
>   monitorCounter: 0
>   entryDN: cn=Write,cn=Waiters,cn=Monitor
>   subschemaSubentry: cn=Subschema
>   hasSubordinates: FALSE

H2: Monitor search example

You should be able to use any LDAP client to retrieve this
information. Here's how you might do it using the
{{I: ldapsearch}}(1) client:

>   ldapsearch -x -s base -b cn=monitor 'objectclass=*' +