mirror of
https://git.openldap.org/openldap/openldap.git
synced 2024-12-21 03:10:25 +08:00
202 lines
6.0 KiB
Groff
202 lines
6.0 KiB
Groff
.TH SLAPO-RETCODE5 "RELEASEDATE" "OpenLDAP LDVERSION"
|
|
.\" Copyright 1998-2006 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
|
|
.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>]
|
|
.RS
|
|
A dynamically generated entry, located below \fBretcode\-parent\fP.
|
|
The \fB<errCode>\fP is the number of the response code;
|
|
it can be in any format supported by strtol.
|
|
The optional \fB<oplist>\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.
|
|
The \fBref\fP field is only allowed for the \fBreferral\fP
|
|
response code.
|
|
.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 describe 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 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"
|
|
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 (8),
|
|
.SH ACKNOWLEDGEMENTS
|
|
.P
|
|
This module was written in 2005 by Pierangelo Masarati for SysNet s.n.c.
|