import retcode overlay

doc/man/man5/slapo-retcode.5

+.TH SLAPO-RETCODE5 "RELEASEDATE" "OpenLDAP LDVERSION"
+.\" Copyright 1998-2004 The OpenLDAP Foundation, All Rights Reserved.
+.\" Copying restrictions apply.  See the COPYRIGHT file.
+.\" Copyright 2001, Pierangelo Masarati, All rights reserved. <ando@sys-net.it>
+.\" $Header$
+.SH NAME
+slapo-retcode \- dynamic listing overlay
+.SH SYNOPSIS
+ETCDIR/slapd.conf
+.SH DESCRIPTION
+The
+.B retcode
+overlay to
+.BR slapd (8)
+is usefult 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, 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 the \fBerrObject\fP class, 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 is \fBerrObject\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>]
+.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 \fBref\fP field is only allowed for the \fBreferral\fP 
+response code.
+.RE
+.TP
+.B retcode\-indir
+Enables exploitation of in-directory stored errObjects.  May result
+in lots of unnecessary overhead.
+
+.SH SCHEMA
+The following schema items are created and used by the overlay:
+.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 objectclass:
+.RS 4
+( 1.3.6.1.4.1.4203.666.11.4.3.1
+    NAME ( 'errObject' )
+    SUP top STRUCTURAL
+    MUST ( errCode )
+    MAY ( cn $ description $ errOp $ errText $ errSleepTime ) )
+.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 AUTHOR
+Pierangelo Masarati

tests/data/retcode.conf

+# slapo-retcode standard track response codes configuration example
+# $Header$
+## This work is part of OpenLDAP Software <http://www.openldap.org/>.
+##
+## Copyright 1998-2005 The OpenLDAP Foundation.
+## All rights reserved.
+##
+## Redistribution and use in source and binary forms, with or without
+## modification, are permitted only as authorized by the OpenLDAP
+## Public License.
+##
+## A copy of this license is available in the file LICENSE in the
+## top-level directory of the distribution or, alternatively, at
+## <http://www.OpenLDAP.org/license.html>.
+#
+# From "ldap.h", revised as per <draft-ietf-ldapbis-protocol>
+
+retcode-item	"cn=success"				0x00
+
+retcode-item	"cn=success w/ delay"			0x00	sleeptime=2
+
+retcode-item	"cn=operationsError"			0x01
+retcode-item	"cn=protocolError"			0x02
+retcode-item	"cn=timeLimitExceeded"			0x03	op=search
+retcode-item	"cn=sizeLimitExceeded"			0x04	op=search
+retcode-item	"cn=compareFalse"			0x05	op=compare
+retcode-item	"cn=compareTrue"			0x06	op=compare
+retcode-item	"cn=authMethodNotSupported"		0x07
+retcode-item	"cn=strongAuthNotSupported"		0x07	text="same as authMethodNotSupported"
+retcode-item	"cn=strongAuthRequired"			0x08
+retcode-item	"cn=strongerAuthRequired"		0x08	text="same as strongAuthRequired"
+#retcode-item	"cn=partialResults"			0x09 "LDAPv2+ (not LDAPv3)"
+
+retcode-item	"cn=referral"				0x0a	text="LDAPv3"
+retcode-item	"cn=adminLimitExceeded"			0x0b	text="LDAPv3"
+retcode-item	"cn=unavailableCriticalExtension"	0x0c	text="LDAPv3"
+retcode-item	"cn=confidentialityRequired"		0x0d	text="LDAPv3"
+retcode-item	"cn=saslBindInProgress"			0x0e	text="LDAPv3"
+
+# LDAP_ATTR_ERROR(n)	LDAP_RANGE((n),0x10,0x15) /* 16-21 */
+
+retcode-item	"cn=noSuchAttribute"			0x10
+retcode-item	"cn=undefinedAttributeType"		0x11
+retcode-item	"cn=inappropriateMatching"		0x12
+retcode-item	"cn=constraintViolation"		0x13
+retcode-item	"cn=attributeOrValueExists"		0x14
+retcode-item	"cn=invalidAttributeSyntax"		0x15
+
+# LDAP_NAME_ERROR(n)	LDAP_RANGE((n),0x20,0x24) /* 32-34,36 */
+
+retcode-item	"cn=noSuchObject"			0x20
+retcode-item	"cn=aliasProblem"			0x21
+retcode-item	"cn=invalidDNSyntax"			0x22
+#retcode-item	"cn=isLeaf"				0x23	text="not LDAPv3"
+retcode-item	"cn=aliasDereferencingProblem"		0x24
+
+# LDAP_SECURITY_ERROR(n)	LDAP_RANGE((n),0x2F,0x32) /* 47-50 */
+
+retcode-item	"cn=proxyAuthzFailure"			0x2F	text="LDAPv3 proxy authorization"
+retcode-item	"cn=inappropriateAuthentication"	0x30
+retcode-item	"cn=invalidCredentials"			0x31
+retcode-item	"cn=insufficientAccessRights"		0x32
+
+# LDAP_SERVICE_ERROR(n)	LDAP_RANGE((n),0x33,0x36) /* 51-54 */
+
+retcode-item	"cn=busy"				0x33
+retcode-item	"cn=unavailable"			0x34
+retcode-item	"cn=unwillingToPerform"			0x35
+retcode-item	"cn=loopDetect"				0x36
+
+# LDAP_UPDATE_ERROR(n)	LDAP_RANGE((n),0x40,0x47) /* 64-69,71 */
+
+retcode-item	"cn=namingViolation"			0x40
+retcode-item	"cn=objectClassViolation"		0x41
+retcode-item	"cn=notAllowedOnNonleaf"		0x42
+retcode-item	"cn=notAllowedOnRDN"			0x43
+retcode-item	"cn=entryAlreadyExists"			0x44
+retcode-item	"cn=objectClassModsProhibited"		0x45
+retcode-item	"cn=resultsTooLarge"			0x46	text="CLDAP"
+retcode-item	"cn=affectsMultipleDSAs"		0x47	text="LDAPv3"
+
+retcode-item	"cn=other"				0x50
+
+# /* LCUP operation codes (113-117) - not implemented */
+retcode-item	"cn=cupResourcesExhausted"		0x71
+retcode-item	"cn=cupSecurityViolation"		0x72
+retcode-item	"cn=cupInvalidData"			0x73
+retcode-item	"cn=cupUnsupportedScheme"		0x74
+retcode-item	"cn=cupReloadRequired"			0x75
+
+# /* Cancel operation codes (118-121) */
+retcode-item	"cn=cancelled"				0x76
+retcode-item	"cn=noSuchOperation"			0x77
+retcode-item	"cn=tooLate"				0x78
+retcode-item	"cn=cannotCancel"			0x79
+
+
+# /* Experimental result codes */
+# LDAP_E_ERROR(n)	LDAP_RANGE((n),0x1000,0x3FFF) /* experimental */
+# LDAP_X_ERROR(n)	LDAP_RANGE((n),0x4000,0xFFFF) /* private use */
+
+# /* for the LDAP Sync operation */
+retcode-item	"cn=syncRefreshRequired"		0x4100
+
+# /* for the LDAP No-Op control */
+retcode-item	"cn=noOperation"			0x410e
+
+# /* for the Assertion control */
+retcode-item	"cn=assertionFailed"			0x410f
+
+# /* for the Chaining Behavior control (consecutive result codes requested;
+#  * see <draft-sermersheim-ldap-chaining> ) */
+retcode-item	"cn=noReferralsFound"			0x4110
+retcode-item	"cn=cannotChain"			0x4111
+

tests/data/slapd-retcode.conf

+# stand-alone slapd config -- for testing (with indexing)
+# $Header$
+## This work is part of OpenLDAP Software <http://www.openldap.org/>.
+##
+## Copyright 1998-2005 The OpenLDAP Foundation.
+## All rights reserved.
+##
+## Redistribution and use in source and binary forms, with or without
+## modification, are permitted only as authorized by the OpenLDAP
+## Public License.
+##
+## A copy of this license is available in the file LICENSE in the
+## top-level directory of the distribution or, alternatively, at
+## <http://www.OpenLDAP.org/license.html>.
+
+include ./schema/core.schema
+include ./schema/cosine.schema
+include ./schema/inetorgperson.schema
+include ./schema/openldap.schema
+include ./schema/nis.schema
+include ./testdata/test.schema
+
+#
+pidfile     ./testrun/slapd.1.pid
+argsfile    ./testrun/slapd.1.args
+
+#mod#modulepath	../servers/slapd/back-@BACKEND@/
+#mod#moduleload	back_@BACKEND@.la
+#monitormod#modulepath ../servers/slapd/back-monitor/
+#monitormod#moduleload back_monitor.la
+#retcodemod#modulepath	../servers/slapd/overlays/
+#retcodemod#moduleload retcode.la
+
+#######################################################################
+# database definitions
+#######################################################################
+
+database	@BACKEND@
+suffix		"dc=example,dc=com"
+directory	./testrun/db.1.a
+rootdn		"cn=Manager,dc=example,dc=com"
+rootpw		secret
+#bdb#index		objectClass	eq
+#bdb#index		cn,sn,uid	pres,eq,sub
+#ldbm#index		objectClass	eq
+#ldbm#index		cn,sn,uid	pres,eq,sub
+
+overlay		retcode
+retcode-parent	"ou=RetCodes,dc=example,dc=com"
+include		testdata/retcode.conf
+
+#monitor#database monitor

tests/scripts/test038-retcode

+#! /bin/sh
+# $Header$
+## This work is part of OpenLDAP Software <http://www.openldap.org/>.
+##
+## Copyright 1998-2005 The OpenLDAP Foundation.
+## All rights reserved.
+##
+## Redistribution and use in source and binary forms, with or without
+## modification, are permitted only as authorized by the OpenLDAP
+## Public License.
+##
+## A copy of this license is available in the file LICENSE in the
+## top-level directory of the distribution or, alternatively, at
+## <http://www.OpenLDAP.org/license.html>.
+
+echo "running defines.sh"
+. $SRCDIR/scripts/defines.sh
+
+if test $RETCODE = retcodeno; then 
+	echo "Retcode overlay not available, test skipped"
+	exit 0
+fi 
+
+mkdir -p $TESTDIR $DBDIR1
+
+echo "Running slapadd to build slapd database..."
+. $CONFFILTER $BACKEND $MONITORDB < $MCONF > $ADDCONF
+$SLAPADD -f $ADDCONF -l $LDIFORDERED
+RC=$?
+if test $RC != 0 ; then
+	echo "slapadd failed ($RC)!"
+	exit $RC
+fi
+
+echo "Running slapindex to index slapd database..."
+. $CONFFILTER $BACKEND $MONITORDB < $RETCODECONF > $CONF1
+$SLAPINDEX -f $CONF1
+RC=$?
+if test $RC != 0 ; then
+	echo "warning: slapindex failed ($RC)"
+	echo "  assuming no indexing support"
+fi
+
+echo "Starting slapd on TCP/IP port $PORT1..."
+$SLAPD -f $CONF1 -h $URI1 -d $LVL $TIMING > $LOG1 2>&1 &
+PID=$!
+if test $WAIT != 0 ; then
+    echo PID $PID
+    read foo
+fi
+KILLPIDS="$PID"
+
+echo "Testing slapd searching..."
+for i in 0 1 2 3 4 5; do
+	$LDAPSEARCH -s base -b "$MONITOR" -h $LOCALHOST -p $PORT1 \
+		'(objectclass=*)' > /dev/null 2>&1
+	RC=$?
+	if test $RC = 0 ; then
+		break
+	fi
+	echo "Waiting 5 seconds for slapd to start..."
+	sleep 5
+done
+
+if test $RC != 0 ; then
+	echo "ldapsearch failed ($RC)!"
+	test $KILLSERVERS != no && kill -HUP $KILLPIDS
+	exit $RC
+fi
+
+echo "Testing searching for timelimitExceeded..."
+$LDAPSEARCH -b "cn=timelimitExceeded,ou=RetCodes,$BASEDN" \
+	-h $LOCALHOST -p $PORT1 '(objectClass=*)' >> $TESTOUT 2>&1
+RC=$?
+if test $RC != 3 ; then
+	echo "ldapsearch failed ($RC)!"
+	test $KILLSERVERS != no && kill -HUP $KILLPIDS
+	exit $RC
+fi
+
+echo "Testing modifying for unwillingToPerform..."
+$LDAPMODIFY -D "$MANAGERDN" -w $PASSWD \
+	-h $LOCALHOST -p $PORT1 >> $TESTOUT 2>&1 << EOMODS
+dn: cn=unwillingToPerform,ou=RetCodes,$BASEDN
+changetype: delete
+EOMODS
+RC=$?
+if test $RC != 53 ; then
+	echo "ldapmodify failed ($RC)!"
+	test $KILLSERVERS != no && kill -HUP $KILLPIDS
+	exit $RC
+fi
+
+test $KILLSERVERS != no && kill -HUP $KILLPIDS
+
+echo ">>>>> Test succeeded"
+exit 0