.TH SLAPO-RETCODE 5 "RELEASEDATE" "OpenLDAP LDVERSION"
-.\" Copyright 1998-2007 The OpenLDAP Foundation, All Rights Reserved.
+.\" Copyright 1998-2013 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
+slapo\-retcode \- return code overlay to slapd
.SH SYNOPSIS
ETCDIR/slapd.conf
.SH DESCRIPTION
.hy 0
.B retcode\-item <RDN> <errCode> [op=<oplist>] [text=<message>]
.B [ref=<referral>] [sleeptime=<sec>] [matched=<DN>]
+.B [unsolicited=<OID>[:<data>]] [flags=[{pre|post}\-]disconnect[,...]]
.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
+The \fBerrCode\fP is the number of the response code;
+it can be in any format supported by
+.BR strtol (3).
+The optional \fBoplist\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.
+along with the error, while the \fBtext\fP field is an optional
+diagnostics message.
The \fBref\fP field is only allowed for the \fBreferral\fP
response code.
+The \fBsleeptime\fP field causes
+.BR slapd (8)
+to sleep the specified number of seconds before proceeding
+with the operation.
+The \fBunsolicited\fP field can be used to cause the return
+of an RFC 4511 unsolicited response message; if \fBOID\fP
+is not "0", an extended response is generated, with the optional
+\fBdata\fP appended.
+If \fBflags\fP contains \fBdisconnect\fP, or \fBpre\-disconnect\fP,
+.BR slapd (8)
+disconnects abruptly, without notice; \fBpost\-disconnect\fP
+causes disconnection right after sending response as appropriate.
.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>
+.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
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
+It is also noted that the schema described here is
.I a work in
.IR progress ,
and hence subject to change without notice.
EQUALITY integerMatch
ORDERING integerOrderingMatch
SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
- SINGLE-VALUE )
+ SINGLE\-VALUE )
.RE
.LP
The operations that trigger the response code:
EQUALITY caseIgnoreMatch
SUBSTR caseIgnoreSubstringsMatch
SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
- SINGLE-VALUE )
+ SINGLE\-VALUE )
.RE
.LP
The sleep time before the response is actually returned to the client:
DESC 'Time to wait before returning the error'
EQUALITY integerMatch
SYNTAX 1.3.6.1.4.1.1466.115.121.1.27
- SINGLE-VALUE )
+ SINGLE\-VALUE )
.RE
.LP
The matched DN returned to the client:
DESC 'Value to be returned as matched DN'
EQUALITY distinguishedNameMatch
SYNTAX 1.3.6.1.4.1.1466.115.121.1.12
- SINGLE-VALUE )
+ SINGLE\-VALUE )
+.RE
+.LP
+The OID to be returned as extended response OID
+in RFC 4511 unsolicited responses
+("0" generates a regular response with msgid set to 0):
+.RS 4
+( 1.3.6.1.4.1.4203.666.11.4.1.6
+ NAME ( 'errUnsolicitedOID' )
+ DESC 'OID to be returned within unsolicited response'
+ EQUALITY objectIdentifierMatch
+ SYNTAX 1.3.6.1.4.1.1466.115.121.1.38
+ SINGLE\-VALUE )
+.RE
+.LP
+The octet string to be returned as extended response data
+in RFC 4511 unsolicited response:
+.RS 4
+( 1.3.6.1.4.1.4203.666.11.4.1.7
+ NAME ( 'errUnsolicitedData' )
+ DESC 'Data to be returned within unsolicited response'
+ SYNTAX 1.3.6.1.4.1.1466.115.121.1.40
+ SINGLE\-VALUE )
+.RE
+.LP
+If TRUE,
+.BR slapd (8)
+disconnects abruptly without notice; if FALSE, it disconnects
+after sending response as appropriate:
+.RS 4
+( 1.3.6.1.4.1.4203.666.11.4.1.8
+ NAME ( 'errDisconnect' )
+ DESC 'Disconnect without notice'
+ SYNTAX 1.3.6.1.4.1.1466.115.121.1.7
+ SINGLE\-VALUE )
.RE
.LP
The abstract class that triggers the overlay:
.RS
.nf
overlay retcode
-retcode-parent "ou=RetCodes,dc=example,dc=com"
+retcode\-parent "ou=RetCodes,dc=example,dc=com"
+
+# retcode.conf is found in tests/data/ of the source tree
include ./retcode.conf
# Wait 10 seconds, then return success (0x00)
-retcode-item "cn=Success after 10 seconds" 0x00 sleeptime=10
+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
+retcode\-item "cn=Timelimit after 10 seconds" 0x03 sleeptime=10
.fi
.RE
.LP
default slapd configuration file
.SH SEE ALSO
.BR slapd.conf (5),
-.BR slapd (8),
+.BR slapd\-config (5),
+.BR slapd (8).
+The
+.BR slapo\-retcode (5)
+overlay supports dynamic configuration via
+.BR back-config .
.SH ACKNOWLEDGEMENTS
.P
This module was written in 2005 by Pierangelo Masarati for SysNet s.n.c.
projects / openldap / blobdiff