1SLAPO-RETCODE(5)              File Formats Manual             SLAPO-RETCODE(5)
2
3
4

NAME

6       slapo-retcode - return code overlay to slapd
7

SYNOPSIS

9       /etc/openldap/slapd.conf
10

DESCRIPTION

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
16       The error responses are generated according to different strategies.
17
18       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
24       Well-known response codes from standard track documents are provided in
25       retcode.conf, which can be included after instantiating the overlay.
26
27       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
32       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
36       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
41       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
46       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
51       retcode-item    <RDN>    <errCode>    [op=<oplist>]    [text=<message>]
52              [ref=<referral>]        [sleeptime=<sec>]         [matched=<DN>]
53              [unsolicited=<OID>[:<data>]]
54              [flags=[{pre|post}-]disconnect[,...]]
55              A dynamically generated  entry,  located  below  retcode-parent.
56              The errCode is the number of the response code; it can be in any
57              format supported by strtol(3).  The optional oplist is a list of
58              operations  that  cause response code generation; if absent, all
59              operations are affected.  The matched field is  the  matched  DN
60              that  is  returned along with the error, while the text field is
61              an optional diagnostics message.  The ref field is only  allowed
62              for  the  referral  response  code.   The sleeptime field causes
63              slapd(8)  to  sleep  the  specified  number  of  seconds  before
64              proceeding  with  the  operation.   The unsolicited field can be
65              used to cause the return of an  RFC  4511  unsolicited  response
66              message;  if  OID is not "0", an extended response is generated,
67              with the optional data appended.  If flags contains  disconnect,
68              or   pre-disconnect,   slapd(8)  disconnects  abruptly,  without
69              notice; post-disconnect causes disconnection right after sending
70              response as appropriate.
71
72       retcode-indir
73              Enables  exploitation  of in-directory stored errAbsObject.  May
74              result in a lot of unnecessary overhead.
75
76       retcode-sleep [-]<n>
77              Defines a sleep time in seconds that is  spent  before  actually
78              handling  any  operation.   If negative, a random time between 0
79              and the absolute value of the argument is used.
80
81

SCHEMA

83       The retcode overlay utilizes the "return code" schema described herein.
84       This  schema  is specifically designed for use with this overlay and is
85       not intended to be used otherwise.  It is also noted  that  the  schema
86       described  here  is  a  work  in  progress, and hence subject to change
87       without notice.  The schema is loaded automatically by the overlay.
88
89       The schema includes a number of object classes and associated attribute
90       types as described below.
91
92
93       The error code:
94           (  1.3.6.1.4.1.4203.666.11.4.1.1
95               NAME ( 'errCode' )
96               DESC 'LDAP error code'
97               EQUALITY integerMatch
98               ORDERING integerOrderingMatch
99               SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
100               SINGLE-VALUE )
101
102       The operations that trigger the response code:
103           ( 1.3.6.1.4.1.4203.666.11.4.1.2
104               NAME ( 'errOp' )
105               DESC 'Operations the errObject applies to'
106               EQUALITY caseIgnoreMatch
107               SUBSTR caseIgnoreSubstringsMatch
108               SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 )
109
110       The text message:
111           ( 1.3.6.1.4.1.4203.666.11.4.1.3
112               NAME ( 'errText' )
113               DESC 'LDAP error textual description'
114               EQUALITY caseIgnoreMatch
115               SUBSTR caseIgnoreSubstringsMatch
116               SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
117               SINGLE-VALUE )
118
119       The sleep time before the response is actually returned to the client:
120           ( 1.3.6.1.4.1.4203.666.11.4.1.4
121               NAME ( 'errSleepTime' )
122               DESC 'Time to wait before returning the error'
123               EQUALITY integerMatch
124               SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
125               SINGLE-VALUE )
126
127       The matched DN returned to the client:
128           ( 1.3.6.1.4.1.4203.666.11.4.1.5
129               NAME ( 'errMatchedDN' )
130               DESC 'Value to be returned as matched DN'
131               EQUALITY distinguishedNameMatch
132               SYNTAX 1.3.6.1.4.1.1466.115.121.1.12
133               SINGLE-VALUE )
134
135       The OID to be returned as extended response OID in RFC 4511 unsolicited
136       responses ("0" generates a regular response with msgid set to 0):
137           ( 1.3.6.1.4.1.4203.666.11.4.1.6
138               NAME ( 'errUnsolicitedOID' )
139               DESC 'OID to be returned within unsolicited response'
140               EQUALITY objectIdentifierMatch
141               SYNTAX 1.3.6.1.4.1.1466.115.121.1.38
142               SINGLE-VALUE )
143
144       The octet string to be returned as extended response data in  RFC  4511
145       unsolicited response:
146           ( 1.3.6.1.4.1.4203.666.11.4.1.7
147               NAME ( 'errUnsolicitedData' )
148               DESC 'Data to be returned within unsolicited response'
149               SYNTAX 1.3.6.1.4.1.1466.115.121.1.40
150               SINGLE-VALUE )
151
152       If  TRUE,  slapd(8)  disconnects  abruptly without notice; if FALSE, it
153       disconnects after sending response as appropriate:
154           ( 1.3.6.1.4.1.4203.666.11.4.1.8
155               NAME ( 'errDisconnect' )
156               DESC 'Disconnect without notice'
157               SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
158               SINGLE-VALUE )
159
160       The abstract class that triggers the overlay:
161           ( 1.3.6.1.4.1.4203.666.11.4.3.0
162               NAME ( 'errAbsObject' )
163               SUP top ABSTRACT
164               MUST ( errCode )
165               MAY ( cn $ description $ errOp $ errText $ errSleepTime
166                   $ errMatchedDN ) )
167
168       The standalone structural objectclass for specifically created data:
169           ( 1.3.6.1.4.1.4203.666.11.4.3.1
170               NAME ( 'errObject' )
171               SUP errAbsObject STRUCTURAL )
172
173       The auxiliary objectclass to alter the behavior of existing objects:
174           ( 1.3.6.1.4.1.4203.666.11.4.3.2
175               NAME ( 'errAuxObject' )
176               SUP errAbsObject AUXILIARY )
177
178

EXAMPLE

180              overlay         retcode
181              retcode-parent  "ou=RetCodes,dc=example,dc=com"
182
183              # retcode.conf is found in tests/data/ of the source tree
184              include         ./retcode.conf
185
186              # Wait 10 seconds, then return success (0x00)
187              retcode-item    "cn=Success after 10 seconds" 0x00 sleeptime=10
188              # Wait 10 seconds, then return timelimitExceeded (0x03)
189              retcode-item    "cn=Timelimit after 10 seconds" 0x03 sleeptime=10
190

FILES

192       /etc/openldap/slapd.conf
193              default slapd configuration file
194

SEE ALSO

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

ACKNOWLEDGEMENTS

200       This  module  was  written  in  2005  by Pierangelo Masarati for SysNet
201       s.n.c.
202
203
204
205OpenLDAP 2.4.40                   2014/09/20                  SLAPO-RETCODE(5)
Impressum