diff options
Diffstat (limited to '')
| -rw-r--r-- | doc/man/man5/slapo-retcode.5 | 257 |
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..3acd44f --- /dev/null +++ b/doc/man/man5/slapo-retcode.5 @@ -0,0 +1,257 @@ +.TH SLAPO-RETCODE 5 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" Copyright 1998-2018 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. |