1 files changed, 257 insertions, 0 deletions
diff --git a/doc/man/man5/slapo-retcode.5 b/doc/man/man5/slapo-retcode.5
new file mode 100644
index 0000000..789c4ca
--- /dev/null
+++ b/doc/man/man5/slapo-retcode.5
@@ -0,0 +1,257 @@
+.TH SLAPO-RETCODE 5 "RELEASEDATE" "OpenLDAP LDVERSION"
+.\" Copyright 1998-2021 The OpenLDAP Foundation, All Rights Reserved.
+.\" Copying restrictions apply.  See the COPYRIGHT file.
+.\" Copyright 2001, Pierangelo Masarati, All rights reserved. <ando@sys-net.it>
+.\" $OpenLDAP$
+.SH NAME
+slapo\-retcode \- return code overlay to slapd
+.SH SYNOPSIS
+ETCDIR/slapd.conf
+.SH DESCRIPTION
+The
+.B retcode
+overlay to
+.BR 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.
+.LP
+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).
+.LP
+Well-known response codes from standard track documents are provided
+in \fBretcode.conf\fP, which can be included after instantiating
+the overlay.
+.LP
+In the second case, objects of classes inherited from 
+the \fBerrAbsObject\fP, like \fBerrObject\fP or \fBerrAuxObject\fP,
+when returned as intermediate responses of a search request, are changed
+into the response dictated by their content.
+.LP
+A third mode causes objects to be looked up from the underlying database 
+to discover if their class inherits from \fBerrABsObject\fP;
+in that case, their content is used to compute the corresponding response.
+.LP
+The behavior is disabled by using the \fBmanageDSAit\fP 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.
+.LP 
+The config directives that are specific to the
+.B retcode
+overlay must be prefixed by
+.BR 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: 
+.TP
+.B retcode\-parent <DN>
+This directive defines the parent DN where dynamically generated
+entries reside.
+If not defined, the suffix of the database is used.
+.HP
+.hy 0
+.B retcode\-item <RDN> <errCode> [op=<oplist>] [text=<message>]
+.B [ref=<referral>] [sleeptime=<sec>] [matched=<DN>]
+.B [unsolicited=<OID>[:<data>]] [flags=[\{pre|post\}\-]disconnect[,...]]
+.RS
+A dynamically generated entry, located below \fBretcode\-parent\fP.
+The \fBerrCode\fP is the number of the response code;
+it can be in any format supported by
+.BR strtol (3).
+The optional \fBoplist\fP is a list of operations that cause
+response code generation; if absent, all operations are affected.
+The \fBmatched\fP field is the matched DN that is returned
+along with the error, while the \fBtext\fP field is an optional
+diagnostics message.
+The \fBref\fP field is only allowed for the \fBreferral\fP 
+response code.
+The \fBsleeptime\fP field causes
+.BR slapd (8)
+to sleep the specified number of seconds before proceeding 
+with the operation.
+The \fBunsolicited\fP field can be used to cause the return
+of an RFC 4511 unsolicited response message; if \fBOID\fP
+is not "0", an extended response is generated, with the optional
+\fBdata\fP appended.
+If \fBflags\fP contains \fBdisconnect\fP, or \fBpre\-disconnect\fP,
+.BR slapd (8)
+disconnects abruptly, without notice; \fBpost\-disconnect\fP
+causes disconnection right after sending response as appropriate.
+.RE
+.TP
+.B retcode\-indir
+Enables exploitation of in-directory stored errAbsObject.
+May result in a lot of unnecessary overhead.
+.TP
+.B 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.
+
+.SH SCHEMA
+The
+.B 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
+.I a work in
+.IR 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.
+
+.LP
+The error code:
+.RS 4
+(  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 )
+.RE
+.LP
+The operations that trigger the response code:
+.RS 4
+( 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 )
+.RE
+.LP
+The text message:
+.RS 4
+( 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 )
+.RE
+.LP
+The sleep time before the response is actually returned to the client:
+.RS 4
+( 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 )
+.RE
+.LP
+The matched DN returned to the client:
+.RS 4
+( 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 )
+.RE
+.LP
+The OID to be returned as extended response OID
+in RFC 4511 unsolicited responses
+("0" generates a regular response with msgid set to 0):
+.RS 4
+( 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 )
+.RE
+.LP
+The octet string to be returned as extended response data
+in RFC 4511 unsolicited response:
+.RS 4
+( 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 )
+.RE
+.LP
+If TRUE,
+.BR slapd (8)
+disconnects abruptly without notice; if FALSE, it disconnects
+after sending response as appropriate:
+.RS 4
+( 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 )
+.RE
+.LP
+The abstract class that triggers the overlay:
+.RS 4
+( 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 ) )
+.RE
+.LP
+The standalone structural objectclass for specifically created data:
+.RS 4
+( 1.3.6.1.4.1.4203.666.11.4.3.1
+    NAME ( 'errObject' )
+    SUP errAbsObject STRUCTURAL )
+.RE
+.LP
+The auxiliary objectclass to alter the behavior of existing objects:
+.RS 4
+( 1.3.6.1.4.1.4203.666.11.4.3.2
+    NAME ( 'errAuxObject' )
+    SUP errAbsObject AUXILIARY )
+.RE
+
+.SH EXAMPLE
+.LP
+.RS
+.nf
+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
+.fi
+.RE
+.LP
+.LP
+
+.SH FILES
+.TP
+ETCDIR/slapd.conf
+default slapd configuration file
+.SH SEE ALSO
+.BR slapd.conf (5),
+.BR slapd\-config (5),
+.BR slapd (8).
+The
+.BR slapo\-retcode (5)
+overlay supports dynamic configuration via
+.BR back-config .
+.SH ACKNOWLEDGEMENTS
+.P
+This module was written in 2005 by Pierangelo Masarati for SysNet s.n.c.