Adding upstream version 2.4.57+dfsg.upstream/2.4.57+dfsgupstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 505 insertions, 0 deletions

diff --git a/doc/guide/admin/monitoringslapd.sdf b/doc/guide/admin/monitoringslapd.sdf
new file mode 100644
index 0000000..45d50fe
--- /dev/null
+++ b/doc/guide/admin/monitoringslapd.sdf
@@ -0,0 +1,505 @@
+# $OpenLDAP$
+# Copyright 1999-2021 The OpenLDAP Foundation, All Rights Reserved.
+# COPYING RESTRICTIONS APPLY, see COPYRIGHT.
+H1: Monitoring
+
+{{slapd}}(8) supports an optional {{TERM:LDAP}} 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 monitoring information is provided by a specialized backend,
+the {{monitor}} backend.  A manual page, {{slapd-monitor}}(5) is
+available.
+
+When the monitoring interface is enabled, LDAP clients may be used
+to access information provided by the {{monitor}} backend, subject
+to access and other controls.
+
+When enabled, the {{monitor}} backend dynamically generates and
+returns objects in response to search requests in the {{cn=Monitor}}
+subtree.  Each object contains information about a particular aspect
+of the server.  The information is held in a combination of user
+applications and operational attributes.   This information can be
+access with {{ldapsearch(1)}}, with any general-purpose LDAP browser,
+or with specialized monitoring tools.  The {{SECT:Accessing Monitoring
+Information}} section provides a brief tutorial on how to use
+{{ldapsearch}}(1) to access monitoring information, while the
+{{SECT:Monitor information}} section details monitoring information
+base and its organization.
+
+While support for the monitor backend is included in default builds
+of slapd(8), this support requires some configuration to become
+active.  This may be done using either {{EX:cn=config}} or
+{{slapd.conf}}(5).  The former is discussed in the {{SECT:Monitor
+configuration via cn=config}} section of this of this chapter.  The
+latter is discussed in the {{SECT:Monitor configuration via
+slapd.conf(5)}} section of this chapter.  These sections assume
+monitor backend is built into {{slapd}} (e.g., {{EX:--enable-monitor=yes}},
+the default).  If the monitor backend was built as a module (e.g.,
+{{EX:--enable-monitor=mod}}, this module must loaded.  Loading of
+modules is discussed in the {{SECT:Configuring slapd}} and {{SECT:The
+slapd Configuration File}} chapters.
+
+
+H2: Monitor configuration via cn=config(5)
+
+{{This section has yet to be written.}}
+
+
+H2: Monitor configuration via slapd.conf(5)
+
+Configuration of the slapd.conf(5) to support LDAP monitoring
+is quite simple.
+
+First, ensure {{core.schema}} schema configuration file is included
+by your {{slapd.conf}}(5) file.  The {{monitor}} backend requires
+it.
+
+Second, instantiate the {{monitor backend}} by adding a
+{{database monitor}} directive below your existing database
+sections.  For instance:
+
+>	database monitor
+
+Lastly, add additional global or database directives as needed.
+
+Like most other database backends, the monitor backend does honor
+slapd(8) access and other administrative controls.   As some monitor
+information may be sensitive, it is generally recommend access to
+cn=monitor be restricted to directory administrators and their
+monitoring agents.  Adding an {{access}} directive immediately below
+the {{database monitor}} directive is a clear and effective approach
+for controlling access.  For instance, the addition of the following
+{{access}} directive immediately below the {{database monitor}}
+directive restricts access to monitoring information to the specified
+directory manager.
+
+>	access to *
+>		by dn.exact="cn=Manager,dc=example,dc=com
+>		by * none
+
+More information on {{slapd}}(8) access controls, see {{The access
+Control Directive}} section of the {{SECT:The slapd Configuration
+File}} chapter and {{slapd.access}}(5).
+
+After restarting {{slapd}}(8), you are ready to start exploring the
+monitoring information provided in {{EX:cn=config}} as discussed
+in the {{SECT:Accessing Monitoring Information}} section of this
+chapter.
+
+One can verify slapd(8) is properly configured to provide monitoring
+information by attempting to read the {{EX:cn=monitor}} object.
+For instance, if the following {{ldapsearch}}(1) command returns the
+cn=monitor object (with, as requested, no attributes), it's working.
+
+>	ldapsearch -x -D 'cn=Manager,dc=example,dc=com' -W \
+>		-b 'cn=Monitor' -s base 1.1
+
+Note that unlike general purpose database backends, the database
+suffix is hardcoded.  It's always {{EX:cn=Monitor}}.  So no {{suffix}}
+directive should be provided.  Also note that general purpose
+database backends, the monitor backend cannot be instantiated
+multiple times.  That is, there can only be one (or zero) occurrences
+of {{EX:database monitor}} in the server's configuration.
+
+
+H2: Accessing Monitoring Information
+
+As previously discussed, when enabled, the {{monitor}} backend
+dynamically generates and returns objects in response to search
+requests in the {{cn=Monitor}} subtree.  Each object contains
+information about a particular aspect of the server.  The information
+is held in a combination of user applications and operational
+attributes.  This information can be accessed with {{ldapsearch(1)}},
+with any general-purpose LDAP browser, or with specialized monitoring
+tools.
+
+This section provides a provides a brief tutorial on how to use
+{{ldapsearch}}(1) to access monitoring information.
+
+To inspect any particular monitor object, one performs search
+operation on the object with a baseObject scope and a
+{{EX:(objectClass=*)}} filter.  As the monitoring information is
+contained in a combination of user applications and operational
+attributes, the return all user applications attributes (e.g.,
+{{EX:'*'}}) and all operational attributes (e.g., {{EX:'+'}}) should
+be requested.   For instance, to read the {{EX:cn=Monitor}} object
+itself, the {{ldapsearch}}(1) command (modified to fit your configuration)
+can be used:
+
+>	ldapsearch -x -D 'cn=Manager,dc=example,dc=com' -W \
+>		-b 'cn=Monitor' -s base '(objectClass=*)' '*' '+'
+
+When run against your server, this should produce output
+similar to:
+
+>	dn: cn=Monitor
+>	objectClass: monitorServer
+>	structuralObjectClass: monitorServer
+>	cn: Monitor
+>	creatorsName:
+>	modifiersName:
+>	createTimestamp: 20061208223558Z
+>	modifyTimestamp: 20061208223558Z
+>	description: This subtree contains monitoring/managing objects.
+>	description: This object contains information about this server.
+>	description: Most of the information is held in operational attributes, which 
+>	 must be explicitly requested.
+>	monitoredInfo: OpenLDAP: slapd 2.4 (Dec  7 2006 17:30:29)
+>	entryDN: cn=Monitor
+>	subschemaSubentry: cn=Subschema
+>	hasSubordinates: TRUE
+
+To reduce the number of uninteresting attributes returned, one
+can be more selective when requesting which attributes are to be
+returned.  For instance, one could request the return of all
+attributes allowed by the {{monitorServer}} object class (e.g.,
+{{EX:@objectClass}}) instead of all user and all operational
+attributes:
+
+>	ldapsearch -x -D 'cn=Manager,dc=example,dc=com' -W \
+>		-b 'cn=Monitor' -s base '(objectClass=*)' '@monitorServer'
+
+This limits the output as follows:
+
+>	dn: cn=Monitor
+>	objectClass: monitorServer
+>	cn: Monitor
+>	description: This subtree contains monitoring/managing objects.
+>	description: This object contains information about this server.
+>	description: Most of the information is held in operational attributes, which 
+>	 must be explicitly requested.
+>	monitoredInfo: OpenLDAP: slapd 2.X (Dec  7 2006 17:30:29)
+
+To return the names of all the monitoring objects, one performs a
+search of {{EX:cn=Monitor}} with subtree scope and {{EX:(objectClass=*)}}
+filter and requesting no attributes (e.g., {{EX:1.1}}) be returned.
+
+>	ldapsearch -x -D 'cn=Manager,dc=example,dc=com' -W -b 'cn=Monitor' -s sub 1.1
+
+If you run this command you will discover that there are many objects
+in the {{cn=Monitor}} subtree.  The following section describes
+some of the commonly available monitoring objects.
+
+
+H2: Monitor Information
+
+The {{monitor}} backend provides a wealth of information useful
+for monitoring the slapd(8) contained in set of monitor objects.
+Each object contains information about a particular aspect of
+the server, such as a backends, a connection, or a thread.
+Some objects serve as containers for other objects and used
+to construct a hierarchy of objects.
+
+In this hierarchy, the most superior object is {cn=Monitor}.
+While this object primarily serves as a container for other
+objects, most of which are containers, this object provides
+information about this server.  In particular, it provides the
+slapd(8) version string.  Example:
+
+>	dn: cn=Monitor
+>	monitoredInfo: OpenLDAP: slapd 2.X (Dec  7 2006 17:30:29)
+
+Note: Examples in this section (and its subsections) have been
+trimmed to show only key information.
+
+
+H3: Backends
+
+The {{EX:cn=Backends,cn=Monitor}} object, itself, provides a list
+of available backends.  The list of available backends all builtin
+backends, as well as backends loaded by modules.  For example:
+
+>	dn: cn=Backends,cn=Monitor          
+>	monitoredInfo: config                 
+>	monitoredInfo: ldif     
+>	monitoredInfo: monitor
+>	monitoredInfo: bdb        
+>	monitoredInfo: hdb
+
+This indicates the {{config}}, {{ldif}}, {{monitor}}, {{bdb}},
+and {{hdb}} backends are available.
+
+The {{EX:cn=Backends,cn=Monitor}} object is also a container
+for available backend objects.  Each available backend object
+contains information about a particular backend.  For example:
+
+>	dn: cn=Backend 0,cn=Backends,cn=Monitor 
+>	monitoredInfo: config
+>	monitorRuntimeConfig: TRUE
+>	supportedControl: 2.16.840.1.113730.3.4.2  
+>	seeAlso: cn=Database 0,cn=Databases,cn=Monitor
+>	
+>	dn: cn=Backend 1,cn=Backends,cn=Monitor  
+>	monitoredInfo: ldif          
+>	monitorRuntimeConfig: TRUE     
+>	supportedControl: 2.16.840.1.113730.3.4.2
+>	
+>	dn: cn=Backend 2,cn=Backends,cn=Monitor
+>	monitoredInfo: monitor
+>	monitorRuntimeConfig: TRUE
+>	supportedControl: 2.16.840.1.113730.3.4.2
+>	seeAlso: cn=Database 2,cn=Databases,cn=Monitor
+>	
+>	dn: cn=Backend 3,cn=Backends,cn=Monitor
+>	monitoredInfo: bdb
+>	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
+>	supportedControl: 1.3.6.1.4.1.4203.666.11.7.2
+>	seeAlso: cn=Database 1,cn=Databases,cn=Monitor
+>	
+>	dn: cn=Backend 4,cn=Backends,cn=Monitor
+>	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
+>	supportedControl: 1.3.6.1.4.1.4203.666.11.7.2
+
+For each of these objects, monitorInfo indicates which backend the
+information in the object is about.  For instance, the {{EX:cn=Backend
+3,cn=Backends,cn=Monitor}} object contains (in the example) information
+about the {{bdb}} backend. 
+
+!block table
+Attribute|Description
+monitoredInfo|Name of backend
+supportedControl|supported LDAP control extensions
+seeAlso|Database objects of instances of this backend
+!endblock
+
+H3: Connections
+
+The main entry is empty; it should contain some statistics on the number 
+of connections.
+
+Dynamic child entries are created for each open connection, with stats on
+the activity on that connection (the format will be detailed later).
+There are two special child entries 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 child entries contain, for each database, the type and the naming
+context.
+
+For example:
+
+>   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:
+
+>   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
+>   ACL
+>   Stats
+>   Stats2
+>   Shell
+>   Parse
+>   Sync
+
+These values can be added, replaced or deleted; they affect what 
+messages are sent to the syslog device.
+Custom values could be added by custom modules.
+
+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 child entries, 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 child entries 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
+
+Add new monitored things here and discuss, referencing man pages and present
+examples
+
+