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

NAME

6       slapo-retcode - return code overlay
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              A dynamically generated  entry,  located  below  retcode-parent.
54              The  <errCode>  is the number of the response code; it can be in
55              any format supported by strtol.  The optional <oplist> is a list
56              of  operations  that  cause response code generation; if absent,
57              all operations are affected.  The matched field is  the  matched
58              DN that is returned along with the error.  The ref field is only
59              allowed for the referral response code.
60
61       retcode-indir
62              Enables exploitation of in-directory stored  errAbsObject.   May
63              result in a lot of unnecessary overhead.
64
65       retcode-sleep [-]<n>
66              Defines  a  sleep  time in seconds that is spent before actually
67              handling any operation.  If negative, a random  time  between  0
68              and the absolute value of the argument is used.
69
70

SCHEMA

72       The retcode overlay utilizes the "return code" schema described herein.
73       This schema is specifically designed for use with this overlay  and  is
74       not  intended  to  be used otherwise.  It is also noted that the schema
75       describe here is a work  in  progress,  and  hence  subject  to  change
76       without notice.  The schema is loaded automatically by the overlay.
77
78       The schema includes a number of object classes and associated attribute
79       types as described below.
80
81
82       The error code:
83           (  1.3.6.1.4.1.4203.666.11.4.1.1
84               NAME ( 'errCode' )
85               DESC 'LDAP error code'
86               EQUALITY integerMatch
87               ORDERING integerOrderingMatch
88               SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
89               SINGLE-VALUE )
90
91       The operations that trigger the response code:
92           ( 1.3.6.1.4.1.4203.666.11.4.1.2
93               NAME ( 'errOp' )
94               DESC 'Operations the errObject applies to'
95               EQUALITY caseIgnoreMatch
96               SUBSTR caseIgnoreSubstringsMatch
97               SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 )
98
99       The text message:
100           ( 1.3.6.1.4.1.4203.666.11.4.1.3
101               NAME ( 'errText' )
102               DESC 'LDAP error textual description'
103               EQUALITY caseIgnoreMatch
104               SUBSTR caseIgnoreSubstringsMatch
105               SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
106               SINGLE-VALUE )
107
108       The sleep time before the response is actually returned to the client:
109           ( 1.3.6.1.4.1.4203.666.11.4.1.4
110               NAME ( 'errSleepTime' )
111               DESC 'Time to wait before returning the error'
112               EQUALITY integerMatch
113               SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
114               SINGLE-VALUE )
115
116       The matched DN returned to the client:
117           ( 1.3.6.1.4.1.4203.666.11.4.1.5
118               NAME ( 'errMatchedDN' )
119               DESC 'Value to be returned as matched DN'
120               EQUALITY distinguishedNameMatch
121               SYNTAX 1.3.6.1.4.1.1466.115.121.1.12
122               SINGLE-VALUE )
123
124       The abstract class that triggers the overlay:
125           ( 1.3.6.1.4.1.4203.666.11.4.3.0
126               NAME ( 'errAbsObject' )
127               SUP top ABSTRACT
128               MUST ( errCode )
129               MAY ( cn $ description $ errOp $ errText $ errSleepTime
130                   $ errMatchedDN ) )
131
132       The standalone structural objectclass for specifically created data:
133           ( 1.3.6.1.4.1.4203.666.11.4.3.1
134               NAME ( 'errObject' )
135               SUP errAbsObject STRUCTURAL )
136
137       The auxiliary objectclass to alter the behavior of existing objects:
138           ( 1.3.6.1.4.1.4203.666.11.4.3.2
139               NAME ( 'errAuxObject' )
140               SUP errAbsObject AUXILIARY )
141
142

EXAMPLE

144              overlay         retcode
145              retcode-parent  "ou=RetCodes,dc=example,dc=com"
146              include         ./retcode.conf
147
148              # Wait 10 seconds, then return success (0x00)
149              retcode-item    "cn=Success after 10 seconds" 0x00 sleeptime=10
150              # Wait 10 seconds, then return timelimitExceeded (0x03)
151              retcode-item    "cn=Timelimit after 10 seconds" 0x03 sleeptime=10
152

FILES

154       /etc/openldap/slapd.conf
155              default slapd configuration file
156

SEE ALSO

158       slapd.conf(5), slapd(8),
159

ACKNOWLEDGEMENTS

161       This module was written in  2005  by  Pierangelo  Masarati  for  SysNet
162       s.n.c.
163
164
165
166OpenLDAP 2.3.34                    2007/2/16                  SLAPO-RETCODE(5)
Impressum