SLAPO-RETCODE(5)

💖 NAME 💖

okay so bestie, welcome to slapo-retcode — the return code overlay for slapd. that's it, that's the whole name. she's a whole overlay, she's iconic, she makes your server lie (on purpose, for science). 🎀

---

✨ SYNOPSIS ✨

/etc/openldap/slapd.conf

---

🌸 DESCRIPTION 🌸

so like. the retcode overlay for slapd(8) is genuinely the bestie you need when you wanna test how clients behave when the server hits them with weird, wrong, or just plain unhinged responses. we're talking error codes, referrals, response times that take forever, all of it. it's giving "chaos engineering but make it LDAP". 💅

the error responses get generated according to different strategies, and here's the tea:

• strategy one — every operation aimed at a specific configurable subtree makes the object related to the request DN get looked up and checked for return code data. what's in that 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). ✨
• the well-known response codes from standard track documents are handed to you in retcode.conf, which you can include after instantiating the overlay. free real estate.
• strategy two — objects of classes inherited from the errAbsObject, like errObject or errAuxObject, when they get returned as intermediate responses of a search request, get changed into the response dictated by their content. glow-up, basically.
• strategy three — objects get looked up from the underlying database to discover whether their class inherits from errABsObject; and if it does, their content is used to compute the corresponding response.

and here's the important bit 👑: the behavior is disabled by using the manageDSAit control (RFC 3296). in that case, the resulting object — whether it's present in the directory, or dynamically generated by the overlay, or contained in the request — gets handled as usual. no funny business. periodt.

so the config directives that belong to the retcode overlay must be prefixed by retcode-, so they don't start beef with directives specific to the underlying database or to other stacked overlays. here's the full crew of specific directives you can use to configure her:

• retcode-parent <DN> — this one defines the parent DN where the dynamically generated entries live. if you don't define it, the suffix of the database is used. ngl, it's the chill one.
• retcode-item <RDN> <errCode> [op=<oplist>] [text=<message>] [ref=<referral>] [sleeptime=<sec>] [matched=<DN>] [unsolicited=<OID>[:<data>]] [flags=[pre|post-]disconnect[,...]] — a dynamically generated entry, located below retcode-parent. let's break it down fr fr:
  • the errCode is the number of the response code, and it can be in any format supported by strtol(3). versatile queen.
  • the optional oplist is a list of operations that cause response code generation. if it's absent, all operations are affected.
  • the matched field is the matched DN that gets returned along with the error.
  • the text field is an optional diagnostics message.
  • the ref field is only allowed for the referral response code. don't try it anywhere else, bestie.
  • the sleeptime field causes slapd(8) to sleep the specified number of seconds before proceeding with the operation. dramatic pause energy.
  • the unsolicited field can be used to cause the return of an RFC 4511 unsolicited response message; if OID is not "0", an extended response is generated, with the optional data appended.
  • if flags contains disconnect, or pre-disconnect, slapd(8) disconnects abruptly, without notice 😭; post-disconnect causes disconnection right after sending the response as appropriate.
• retcode-indir — enables exploitation of in-directory stored errAbsObject. heads up: may result in a lot of unnecessary overhead. it's giving "expensive hobby". 💀
• retcode-sleep [-]<n> — defines a sleep time in seconds that gets spent before actually handling any operation. if it's negative, a random time between 0 and the absolute value of the argument is used. surprise nap. 🦋

---

🧚 SCHEMA 🧚

the 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. also noted: the schema described here is a work in progress, and hence subject to change without notice. 👀 the schema is loaded automatically by the overlay though, so she handles that bit herself.

the schema includes a number of object classes and associated attribute types, as described below.

🚨 bestie warning: work in progress means it can change without notice. don't build your whole personality on it.

the error code:

(  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 )

the operations that trigger the response code:

( 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 )

the text message:

( 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 )

the sleep time before the response is actually returned to the client:

( 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 )

the matched DN returned to the client:

( 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 )

the OID to be returned as extended response OID in RFC 4511 unsolicited responses ("0" generates a regular response with msgid set to 0):

( 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 )

the octet string to be returned as extended response data in RFC 4511 unsolicited response:

( 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 )

if TRUE, slapd(8) disconnects abruptly without notice; if FALSE, it disconnects after sending response as appropriate:

( 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 )

the abstract class that triggers the overlay:

( 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 ) )

the standalone structural objectclass for specifically created data:

( 1.3.6.1.4.1.4203.666.11.4.3.1
    NAME ( 'errObject' )
    SUP errAbsObject STRUCTURAL )

the auxiliary objectclass to alter the behavior of existing objects:

( 1.3.6.1.4.1.4203.666.11.4.3.2
    NAME ( 'errAuxObject' )
    SUP errAbsObject AUXILIARY )

---

🌈 EXAMPLE 🌈

here's the vibe, copy-paste ready:

overlay         retcode
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
# Wait 10 seconds, then return timelimitExceeded (0x03)
retcode-item    "cn=Timelimit after 10 seconds" 0x03 sleeptime=10

see how we're just out here making people wait 10 whole seconds for their LDAP response. main character behavior honestly. ⭐

---

📁 FILES 📁

• /etc/openldap/slapd.conf — default slapd configuration file

---

👀 SEE ALSO 👀

slapd.conf(5), slapd-config(5), slapd(8). also!! the slapo-retcode(5) overlay supports dynamic configuration via back-config. slay. 🫶

---

💜 ACKNOWLEDGEMENTS 💜

this module was written in 2005 by Pierangelo Masarati for SysNet s.n.c. — an absolute legend, we thank him for his service. 👑

---

and that's the whole page, bestie!! this one's from OpenLDAP 2.7.2, dated 2026/10/21. go forth and return some codes. 💖✨🎀