1.lf 1 stdin 2.TH SLAPO-RETCODE 5 "2020/04/28" "OpenLDAP 2.4.50" 3.\" Copyright 1998-2020 The OpenLDAP Foundation, All Rights Reserved. 4.\" Copying restrictions apply. See the COPYRIGHT file. 5.\" Copyright 2001, Pierangelo Masarati, All rights reserved. <ando@sys-net.it> 6.\" $OpenLDAP$ 7.SH NAME 8slapo\-retcode \- return code overlay to slapd 9.SH SYNOPSIS 10/etc/openldap/slapd.conf 11.SH DESCRIPTION 12The 13.B retcode 14overlay to 15.BR slapd (8) 16is useful to test the behavior of clients when server-generated erroneous 17and/or unusual responses occur, e.g. error codes, referrals, 18excessive response times and so on. 19 20The error responses are generated according to different strategies. 21.LP 22In the first case, all operations targeted at a specific configurable 23subtree cause the object related to the request DN to be looked up 24and checked for return code data: a response code, plus an optional 25textual message, an optional configurable delay, an optional matched DN 26field, and, when the response code is "referral", a (list of) referral(s). 27.LP 28Well-known response codes from standard track documents are provided 29in \fBretcode.conf\fP, which can be included after instantiating 30the overlay. 31.LP 32In the second case, objects of classes inherited from 33the \fBerrAbsObject\fP, like \fBerrObject\fP or \fBerrAuxObject\fP, 34when returned as intermediate responses of a search request, are changed 35into the response dictated by their content. 36.LP 37A third mode causes objects to be looked up from the underlying database 38to discover if their class inherits from \fBerrABsObject\fP; 39in that case, their content is used to compute the corresponding response. 40.LP 41The behavior is disabled by using the \fBmanageDSAit\fP control (RFC 3296); 42in that case, the resulting object, either present in the directory 43or dynamically generated by the overlay, or contained in the request, 44is handled as usual. 45.LP 46The config directives that are specific to the 47.B retcode 48overlay must be prefixed by 49.BR retcode\- , 50to avoid conflicts with directives specific to the underlying database 51or to other stacked overlays. The following specific directives 52can be used to configure the retcode overlay: 53.TP 54.B retcode\-parent <DN> 55This directive defines the parent DN where dynamically generated 56entries reside. 57If not defined, the suffix of the database is used. 58.HP 59.hy 0 60.B retcode\-item <RDN> <errCode> [op=<oplist>] [text=<message>] 61.B [ref=<referral>] [sleeptime=<sec>] [matched=<DN>] 62.B [unsolicited=<OID>[:<data>]] [flags=[\{pre|post\}\-]disconnect[,...]] 63.RS 64A dynamically generated entry, located below \fBretcode\-parent\fP. 65The \fBerrCode\fP is the number of the response code; 66it can be in any format supported by 67.BR strtol (3). 68The optional \fBoplist\fP is a list of operations that cause 69response code generation; if absent, all operations are affected. 70The \fBmatched\fP field is the matched DN that is returned 71along with the error, while the \fBtext\fP field is an optional 72diagnostics message. 73The \fBref\fP field is only allowed for the \fBreferral\fP 74response code. 75The \fBsleeptime\fP field causes 76.BR slapd (8) 77to sleep the specified number of seconds before proceeding 78with the operation. 79The \fBunsolicited\fP field can be used to cause the return 80of an RFC 4511 unsolicited response message; if \fBOID\fP 81is not "0", an extended response is generated, with the optional 82\fBdata\fP appended. 83If \fBflags\fP contains \fBdisconnect\fP, or \fBpre\-disconnect\fP, 84.BR slapd (8) 85disconnects abruptly, without notice; \fBpost\-disconnect\fP 86causes disconnection right after sending response as appropriate. 87.RE 88.TP 89.B retcode\-indir 90Enables exploitation of in-directory stored errAbsObject. 91May result in a lot of unnecessary overhead. 92.TP 93.B retcode\-sleep [\-]<n> 94Defines a sleep time in seconds that is spent before actually handling 95any operation. 96If negative, a random time between 0 and the absolute value of the argument 97is used. 98 99.SH SCHEMA 100The 101.B retcode 102overlay utilizes the "return code" schema described herein. 103This schema is specifically designed for use with this 104overlay and is not intended to be used otherwise. 105It is also noted that the schema described here is 106.I a work in 107.IR progress , 108and hence subject to change without notice. 109The schema is loaded automatically by the overlay. 110 111The schema includes a number of object classes and associated 112attribute types as described below. 113 114.LP 115The error code: 116.RS 4 117( 1.3.6.1.4.1.4203.666.11.4.1.1 118 NAME ( 'errCode' ) 119 DESC 'LDAP error code' 120 EQUALITY integerMatch 121 ORDERING integerOrderingMatch 122 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 123 SINGLE\-VALUE ) 124.RE 125.LP 126The operations that trigger the response code: 127.RS 4 128( 1.3.6.1.4.1.4203.666.11.4.1.2 129 NAME ( 'errOp' ) 130 DESC 'Operations the errObject applies to' 131 EQUALITY caseIgnoreMatch 132 SUBSTR caseIgnoreSubstringsMatch 133 SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 ) 134.RE 135.LP 136The text message: 137.RS 4 138( 1.3.6.1.4.1.4203.666.11.4.1.3 139 NAME ( 'errText' ) 140 DESC 'LDAP error textual description' 141 EQUALITY caseIgnoreMatch 142 SUBSTR caseIgnoreSubstringsMatch 143 SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 144 SINGLE\-VALUE ) 145.RE 146.LP 147The sleep time before the response is actually returned to the client: 148.RS 4 149( 1.3.6.1.4.1.4203.666.11.4.1.4 150 NAME ( 'errSleepTime' ) 151 DESC 'Time to wait before returning the error' 152 EQUALITY integerMatch 153 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 154 SINGLE\-VALUE ) 155.RE 156.LP 157The matched DN returned to the client: 158.RS 4 159( 1.3.6.1.4.1.4203.666.11.4.1.5 160 NAME ( 'errMatchedDN' ) 161 DESC 'Value to be returned as matched DN' 162 EQUALITY distinguishedNameMatch 163 SYNTAX 1.3.6.1.4.1.1466.115.121.1.12 164 SINGLE\-VALUE ) 165.RE 166.LP 167The OID to be returned as extended response OID 168in RFC 4511 unsolicited responses 169("0" generates a regular response with msgid set to 0): 170.RS 4 171( 1.3.6.1.4.1.4203.666.11.4.1.6 172 NAME ( 'errUnsolicitedOID' ) 173 DESC 'OID to be returned within unsolicited response' 174 EQUALITY objectIdentifierMatch 175 SYNTAX 1.3.6.1.4.1.1466.115.121.1.38 176 SINGLE\-VALUE ) 177.RE 178.LP 179The octet string to be returned as extended response data 180in RFC 4511 unsolicited response: 181.RS 4 182( 1.3.6.1.4.1.4203.666.11.4.1.7 183 NAME ( 'errUnsolicitedData' ) 184 DESC 'Data to be returned within unsolicited response' 185 SYNTAX 1.3.6.1.4.1.1466.115.121.1.40 186 SINGLE\-VALUE ) 187.RE 188.LP 189If TRUE, 190.BR slapd (8) 191disconnects abruptly without notice; if FALSE, it disconnects 192after sending response as appropriate: 193.RS 4 194( 1.3.6.1.4.1.4203.666.11.4.1.8 195 NAME ( 'errDisconnect' ) 196 DESC 'Disconnect without notice' 197 SYNTAX 1.3.6.1.4.1.1466.115.121.1.7 198 SINGLE\-VALUE ) 199.RE 200.LP 201The abstract class that triggers the overlay: 202.RS 4 203( 1.3.6.1.4.1.4203.666.11.4.3.0 204 NAME ( 'errAbsObject' ) 205 SUP top ABSTRACT 206 MUST ( errCode ) 207 MAY ( cn $ description $ errOp $ errText $ errSleepTime 208 $ errMatchedDN ) ) 209.RE 210.LP 211The standalone structural objectclass for specifically created data: 212.RS 4 213( 1.3.6.1.4.1.4203.666.11.4.3.1 214 NAME ( 'errObject' ) 215 SUP errAbsObject STRUCTURAL ) 216.RE 217.LP 218The auxiliary objectclass to alter the behavior of existing objects: 219.RS 4 220( 1.3.6.1.4.1.4203.666.11.4.3.2 221 NAME ( 'errAuxObject' ) 222 SUP errAbsObject AUXILIARY ) 223.RE 224 225.SH EXAMPLE 226.LP 227.RS 228.nf 229overlay retcode 230retcode\-parent "ou=RetCodes,dc=example,dc=com" 231 232# retcode.conf is found in tests/data/ of the source tree 233include ./retcode.conf 234 235# Wait 10 seconds, then return success (0x00) 236retcode\-item "cn=Success after 10 seconds" 0x00 sleeptime=10 237# Wait 10 seconds, then return timelimitExceeded (0x03) 238retcode\-item "cn=Timelimit after 10 seconds" 0x03 sleeptime=10 239.fi 240.RE 241.LP 242.LP 243 244.SH FILES 245.TP 246/etc/openldap/slapd.conf 247default slapd configuration file 248.SH SEE ALSO 249.BR slapd.conf (5), 250.BR slapd\-config (5), 251.BR slapd (8). 252The 253.BR slapo\-retcode (5) 254overlay supports dynamic configuration via 255.BR back-config . 256.SH ACKNOWLEDGEMENTS 257.P 258This module was written in 2005 by Pierangelo Masarati for SysNet s.n.c. 259