1SLAPO-RETCODE(5) File Formats Manual SLAPO-RETCODE(5)
2
6 slapo-retcode - return code overlay to slapd
7
9 /etc/openldap/slapd.conf
10
12 The retcode overlay to slapd(8) is useful to test the behavior of
13 clients when server-generated erroneous and/or unusual responses occur,
14 e.g. error codes, referrals, excessive response times and so on.
15 The error responses are generated according to different strategies.
17 In the first case, all operations targeted at a specific configurable
19 subtree cause the object related to the request DN to be looked up and
20 checked for return code data: a response code, plus an optional textual
21 message, an optional configurable delay, an optional matched DN field,
22 and, when the response code is "referral", a (list of) referral(s).
23 Well-known response codes from standard track documents are provided in
25 retcode.conf, which can be included after instantiating the overlay.
26 In the second case, objects of classes inherited from the errAbsObject,
28 like errObject or errAuxObject, when returned as intermediate responses
29 of a search request, are changed into the response dictated by their
30 content.
31 A third mode causes objects to be looked up from the underlying data‐
33 base to discover if their class inherits from errABsObject; in that
34 case, their content is used to compute the corresponding response.
35 The behavior is disabled by using the manageDSAit control (RFC 3296);
37 in that case, the resulting object, either present in the directory or
38 dynamically generated by the overlay, or contained in the request, is
39 handled as usual.
40 The config directives that are specific to the retcode overlay must be
42 prefixed by retcode-, to avoid conflicts with directives specific to
43 the underlying database or to other stacked overlays. The following
44 specific directives can be used to configure the retcode overlay:
45 retcode-parent <DN>
47 This directive defines the parent DN where dynamically generated
48 entries reside. If not defined, the suffix of the database is
49 used.
50 retcode-item <RDN> <errCode> [op=<oplist>] [text=<message>]
52 [ref=<referral>] [sleeptime=<sec>] [matched=<DN>]
53 [unsolicited=<OID>[:<data>]] [flags=[pre|post-]disconnect[,...]]
54 A dynamically generated entry, located below retcode-parent.
55 The errCode is the number of the response code; it can be in any
56 format supported by strtol(3). The optional oplist is a list of
57 operations that cause response code generation; if absent, all
58 operations are affected. The matched field is the matched DN
59 that is returned along with the error, while the text field is
60 an optional diagnostics message. The ref field is only allowed
61 for the referral response code. The sleeptime field causes
62 slapd(8) to sleep the specified number of seconds before
63 proceeding with the operation. The unsolicited field can be
64 used to cause the return of an RFC 4511 unsolicited response
65 message; if OID is not "0", an extended response is generated,
66 with the optional data appended. If flags contains disconnect,
67 or pre-disconnect, slapd(8) disconnects abruptly, without
68 notice; post-disconnect causes disconnection right after sending
69 response as appropriate.
70 retcode-indir
72 Enables exploitation of in-directory stored errAbsObject. May
73 result in a lot of unnecessary overhead.
74 retcode-sleep [-]<n>
76 Defines a sleep time in seconds that is spent before actually
77 handling any operation. If negative, a random time between 0
78 and the absolute value of the argument is used.
79
82 The retcode overlay utilizes the "return code" schema described herein.
83 This schema is specifically designed for use with this overlay and is
84 not intended to be used otherwise. It is also noted that the schema
85 described here is a work in progress, and hence subject to change
86 without notice. The schema is loaded automatically by the overlay.
87 The schema includes a number of object classes and associated attribute
89 types as described below.
90 The error code:
93 ( 1.3.6.1.4.1.4203.666.11.4.1.1
94 NAME ( 'errCode' )
95 DESC 'LDAP error code'
96 EQUALITY integerMatch
97 ORDERING integerOrderingMatch
98 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
99 SINGLE-VALUE )
100 The operations that trigger the response code:
102 ( 1.3.6.1.4.1.4203.666.11.4.1.2
103 NAME ( 'errOp' )
104 DESC 'Operations the errObject applies to'
105 EQUALITY caseIgnoreMatch
106 SUBSTR caseIgnoreSubstringsMatch
107 SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 )
108 The text message:
110 ( 1.3.6.1.4.1.4203.666.11.4.1.3
111 NAME ( 'errText' )
112 DESC 'LDAP error textual description'
113 EQUALITY caseIgnoreMatch
114 SUBSTR caseIgnoreSubstringsMatch
115 SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
116 SINGLE-VALUE )
117 The sleep time before the response is actually returned to the client:
119 ( 1.3.6.1.4.1.4203.666.11.4.1.4
120 NAME ( 'errSleepTime' )
121 DESC 'Time to wait before returning the error'
122 EQUALITY integerMatch
123 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
124 SINGLE-VALUE )
125 The matched DN returned to the client:
127 ( 1.3.6.1.4.1.4203.666.11.4.1.5
128 NAME ( 'errMatchedDN' )
129 DESC 'Value to be returned as matched DN'
130 EQUALITY distinguishedNameMatch
131 SYNTAX 1.3.6.1.4.1.1466.115.121.1.12
132 SINGLE-VALUE )
133 The OID to be returned as extended response OID in RFC 4511 unsolicited
135 responses ("0" generates a regular response with msgid set to 0):
136 ( 1.3.6.1.4.1.4203.666.11.4.1.6
137 NAME ( 'errUnsolicitedOID' )
138 DESC 'OID to be returned within unsolicited response'
139 EQUALITY objectIdentifierMatch
140 SYNTAX 1.3.6.1.4.1.1466.115.121.1.38
141 SINGLE-VALUE )
142 The octet string to be returned as extended response data in RFC 4511
144 unsolicited response:
145 ( 1.3.6.1.4.1.4203.666.11.4.1.7
146 NAME ( 'errUnsolicitedData' )
147 DESC 'Data to be returned within unsolicited response'
148 SYNTAX 1.3.6.1.4.1.1466.115.121.1.40
149 SINGLE-VALUE )
150 If TRUE, slapd(8) disconnects abruptly without notice; if FALSE, it
152 disconnects after sending response as appropriate:
153 ( 1.3.6.1.4.1.4203.666.11.4.1.8
154 NAME ( 'errDisconnect' )
155 DESC 'Disconnect without notice'
156 SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
157 SINGLE-VALUE )
158 The abstract class that triggers the overlay:
160 ( 1.3.6.1.4.1.4203.666.11.4.3.0
161 NAME ( 'errAbsObject' )
162 SUP top ABSTRACT
163 MUST ( errCode )
164 MAY ( cn $ description $ errOp $ errText $ errSleepTime
165 $ errMatchedDN ) )
166 The standalone structural objectclass for specifically created data:
168 ( 1.3.6.1.4.1.4203.666.11.4.3.1
169 NAME ( 'errObject' )
170 SUP errAbsObject STRUCTURAL )
171 The auxiliary objectclass to alter the behavior of existing objects:
173 ( 1.3.6.1.4.1.4203.666.11.4.3.2
174 NAME ( 'errAuxObject' )
175 SUP errAbsObject AUXILIARY )
176
179 overlay retcode
180 retcode-parent "ou=RetCodes,dc=example,dc=com"
181 # retcode.conf is found in tests/data/ of the source tree
183 include ./retcode.conf
184 # Wait 10 seconds, then return success (0x00)
186 retcode-item "cn=Success after 10 seconds" 0x00 sleeptime=10
187 # Wait 10 seconds, then return timelimitExceeded (0x03)
188 retcode-item "cn=Timelimit after 10 seconds" 0x03 sleeptime=10
189
191 /etc/openldap/slapd.conf
192 default slapd configuration file
193
195 slapd.conf(5), slapd-config(5), slapd(8). The slapo-retcode(5) overlay
196 supports dynamic configuration via back-config.
197
199 This module was written in 2005 by Pierangelo Masarati for SysNet
200 s.n.c.
201OpenLDAP 2.6.6 2023/07/31 SLAPO-RETCODE(5)