slapo-retcode(5)
SLAPO-RETCODE5(2006/08/19MISC. REFERENCE MANUAL PAGESLAPO-RETCODE5(2006/08/19)
NAME
slapo-retcode - return code overlay
SYNOPSIS
/etc/openldap/slapd.conf
DESCRIPTION
The retcode overlay to slapd(8) is useful to test the
behavior of clients when server-generated erroneous and/or
unusual responses occur, e.g. error codes, referrals, exces-
sive response times and so on.
The error responses are generated according to different
strategies.
In the first case, all operations targeted at a specific
configurable subtree cause the object related to the request
DN to be looked up and checked for return code data: a
response code, plus an optional textual message, an optional
configurable delay, an optional matched DN field, and, when
the response code is "referral", a (list of) referral(s).
Well-known response codes from standard track documents are
provided in retcode.conf, which can be included after
instantiating the overlay.
In the second case, objects of classes inherited from the
errAbsObject, like errObject or errAuxObject, when returned
as intermediate responses of a search request, are changed
into the response dictated by their content.
A third mode causes objects to be looked up from the under-
lying database to discover if their class inherits from
errABsObject; in that case, their content is used to compute
the corresponding response.
The behavior is disabled by using the manageDSAit control
(RFC 3296); in that case, the resulting object, either
present in the directory or dynamically generated by the
overlay, or contained in the request, is handled as usual.
The config directives that are specific to the retcode over-
lay must be prefixed by retcode-, to avoid conflicts with
directives specific to the underlying database or to other
stacked overlays. The following specific directives can be
used to configure the retcode overlay:
retcode-parent <DN>
This directive defines the parent DN where dynamically
generated entries reside. If not defined, the suffix
of the database is used.
Last change: OpenLDAP 2.3.27 1
SLAPO-RETCODE5(2006/08/19MISC. REFERENCE MANUAL PAGESLAPO-RETCODE5(2006/08/19)
retcode-item <RDN> <errCode> [op=<oplist>] [text=<message>]
[ref=<referral>] [sleeptime=<sec>] [matched=<DN>]
A dynamically generated entry, located below
retcode-parent. The <errCode> is the number of the
response code; it can be in any format supported by
strtol. The optional <oplist> is a list of operations
that cause response code generation; if absent, all
operations are affected. The matched field is the
matched DN that is returned along with the error. The
ref field is only allowed for the referral response
code.
retcode-indir
Enables exploitation of in-directory stored
errAbsObject. May result in a lot of unnecessary
overhead.
retcode-sleep [-]<n>
Defines a sleep time in seconds that is spent before
actually handling any operation. If negative, a random
time between 0 and the absolute value of the argument
is used.
SCHEMA
The retcode overlay utilizes the "return code" schema
described herein. This schema is specifically designed for
use with this overlay and is not intended to be used
otherwise. It is also noted that the schema describe here
is a work in progress, and hence subject to change without
notice. The schema is loaded automatically by the overlay.
The schema includes a number of object classes and
associated attribute types as described below.
The error code:
( 1.3.6.1.4.1.4203.666.11.4.1.1
NAME ( 'errCode' )
DESC 'LDAP error code'
EQUALITY integerMatch
ORDERING integerOrderingMatch
SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
SINGLE-VALUE )
The operations that trigger the response code:
( 1.3.6.1.4.1.4203.666.11.4.1.2
NAME ( 'errOp' )
DESC 'Operations the errObject applies to'
EQUALITY caseIgnoreMatch
SUBSTR caseIgnoreSubstringsMatch
SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 )
Last change: OpenLDAP 2.3.27 2
SLAPO-RETCODE5(2006/08/19MISC. REFERENCE MANUAL PAGESLAPO-RETCODE5(2006/08/19)
The text message:
( 1.3.6.1.4.1.4203.666.11.4.1.3
NAME ( 'errText' )
DESC 'LDAP error textual description'
EQUALITY caseIgnoreMatch
SUBSTR caseIgnoreSubstringsMatch
SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
SINGLE-VALUE )
The sleep time before the response is actually returned to
the client:
( 1.3.6.1.4.1.4203.666.11.4.1.4
NAME ( 'errSleepTime' )
DESC 'Time to wait before returning the error'
EQUALITY integerMatch
SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
SINGLE-VALUE )
The matched DN returned to the client:
( 1.3.6.1.4.1.4203.666.11.4.1.5
NAME ( 'errMatchedDN' )
DESC 'Value to be returned as matched DN'
EQUALITY distinguishedNameMatch
SYNTAX 1.3.6.1.4.1.1466.115.121.1.12
SINGLE-VALUE )
The abstract class that triggers the overlay:
( 1.3.6.1.4.1.4203.666.11.4.3.0
NAME ( 'errAbsObject' )
SUP top ABSTRACT
MUST ( errCode )
MAY ( cn $ description $ errOp $ errText $
errSleepTime
$ errMatchedDN ) )
The standalone structural objectclass for specifically
created data:
( 1.3.6.1.4.1.4203.666.11.4.3.1
NAME ( 'errObject' )
SUP errAbsObject STRUCTURAL )
The auxiliary objectclass to alter the behavior of existing
objects:
( 1.3.6.1.4.1.4203.666.11.4.3.2
NAME ( 'errAuxObject' )
SUP errAbsObject AUXILIARY )
EXAMPLE
overlay retcode
retcode-parent "ou=RetCodes,dc=example,dc=com"
include ./retcode.conf
Last change: OpenLDAP 2.3.27 3
SLAPO-RETCODE5(2006/08/19MISC. REFERENCE MANUAL PAGESLAPO-RETCODE5(2006/08/19)
# Wait 10 seconds, then return success (0x00)
retcode-item "cn=Success after 10 seconds" 0x00 sleeptime=10
# Wait 10 seconds, then return timelimitExceeded (0x03)
retcode-item "cn=Timelimit after 10 seconds" 0x03 sleeptime=10
FILES
/etc/openldap/slapd.conf
default slapd configuration file
SEE ALSO
slapd.conf(5), slapd(8),
ACKNOWLEDGEMENTS
This module was written in 2005 by Pierangelo Masarati for
SysNet s.n.c.
Last change: OpenLDAP 2.3.27 4
Man(1) output converted with
man2html