Provided by: slapd_2.5.13+dfsg-1ubuntu1_amd64 bug

NAME

       slapo-retcode - return code overlay to slapd

SYNOPSIS

       /etc/ldap/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, excessive
       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 underlying 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  overlay  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.

       retcode-item   <RDN>    <errCode>    [op=<oplist>]    [text=<message>]    [ref=<referral>]
              [sleeptime=<sec>]            [matched=<DN>]            [unsolicited=<OID>[:<data>]]
              [flags=[pre|post-]disconnect[,...]]
              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(3).  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, while the text  field  is  an  optional  diagnostics
              message.   The  ref  field  is  only  allowed  for the referral response code.  The
              sleeptime field causes slapd(8) to sleep the specified  number  of  seconds  before
              proceeding  with  the  operation.   The  unsolicited field can be used to cause the
              return of an RFC 4511 unsolicited response message; if OID is not "0", an  extended
              response  is  generated,  with  the  optional  data  appended.   If  flags contains
              disconnect, or  pre-disconnect,  slapd(8)  disconnects  abruptly,  without  notice;
              post-disconnect causes disconnection right after sending response as appropriate.

       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 described 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 )

       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 OID to be returned as extended response OID in RFC  4511  unsolicited  responses  ("0"
       generates a regular response with msgid set to 0):
           ( 1.3.6.1.4.1.4203.666.11.4.1.6
               NAME ( 'errUnsolicitedOID' )
               DESC 'OID to be returned within unsolicited response'
               EQUALITY objectIdentifierMatch
               SYNTAX 1.3.6.1.4.1.1466.115.121.1.38
               SINGLE-VALUE )

       The  octet  string  to  be  returned  as  extended  response  data in RFC 4511 unsolicited
       response:
           ( 1.3.6.1.4.1.4203.666.11.4.1.7
               NAME ( 'errUnsolicitedData' )
               DESC 'Data to be returned within unsolicited response'
               SYNTAX 1.3.6.1.4.1.1466.115.121.1.40
               SINGLE-VALUE )

       If TRUE, slapd(8) disconnects abruptly without notice;  if  FALSE,  it  disconnects  after
       sending response as appropriate:
           ( 1.3.6.1.4.1.4203.666.11.4.1.8
               NAME ( 'errDisconnect' )
               DESC 'Disconnect without notice'
               SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
               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"

              # retcode.conf is found in tests/data/ of the source tree
              include         ./retcode.conf

              # 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/ldap/slapd.conf
              default slapd configuration file

SEE ALSO

       slapd.conf(5),  slapd-config(5),  slapd(8).  The slapo-retcode(5) overlay supports dynamic
       configuration via back-config.

ACKNOWLEDGEMENTS

       This module was written in 2005 by Pierangelo Masarati for SysNet s.n.c.