SLAPD-RELAY(5)

📦
version 2.7.2 · 24 versions
, in arch rolling

💖 SLAPD-RELAY(5) 💖

okay bestie, gather round, because we're talking about slapd-relay — the relay backend to slapd — straight out of the File Formats Manual. it's giving niche, it's giving powerful, it's giving "please read the whole thing before you touch it." 🫶

This is the page that lives in section 5 of the manual, the file formats one, and it's all about /etc/openldap/slapd.conf. yes, that file. the one you're scared of. let's go. ✨

🌸 NAME 🌸

slapd-relay — the relay backend for slapd. no cap, that's the whole name.

🎀 SYNOPSIS 🎀

/etc/openldap/slapd.conf

yep, that's it. that's the whole synopsis. the config file is the moment. 💅

🦋 DESCRIPTION 🦋

okay so first things first, what does this backend even do. The main job of this slapd(8) backend is to take a naming context that's defined in a database running inside the same slapd(8) instance, and map it into a virtual naming context — with attributeType and objectClass manipulation if you need it. that's the glow-up. ✨

Heads up though: it needs the slapo-rwm(5) overlay to function. no overlay, no vibes.

and um, important disclaimer: this backend AND the overlay mentioned above are both experimental. 🧪 so like, iconic, but proceed with the energy of someone who reads warnings. literally.

💜 CONFIGURATION 💜

The following slapd.conf directives apply to the relay backend database. and when I say "apply to the relay backend database," I mean they have to follow a "database relay" line and come before any subsequent "backend" or "database" lines. order matters bestie, the parser does not play. 🫠

Other database options are described over in the slapd.conf(5) manual page — but heads up, only the suffix directive is allowed by the relay backend. that's the whole allowlist. one (1) directive. iconic restraint honestly.

  • relay <real naming context> — this is the naming context of the database that gets presented under a virtual naming context. The presence of this directive implies that one specific database — like, the one serving the real naming context — will be presented under a virtual naming context. so it's a commitment. you're picking your database. 💍

✨ MASSAGING ✨

okay so this is the part where I have to say "massaging" with a straight face, and I do. 🧖

The relay database does not automatically rewrite the naming context of requests and responses. nope. not a thing it does on its own. For that, the slapo-rwm(5) overlay must be explicitly instantiated, and configured as appropriate.

Usually, the rwm-suffixmassage directive is enough if the only thing you need is naming context rewriting. easy, breezy. 💅

🔥 ACCESS RULES 🔥

here's the one important issue, and it's a big one. Access rules are based on the identity that issued the operation. After massaging from the virtual to the real naming context, the frontend sees the operation as performed by the identity in the real naming context.

and it gets spicier: since back-relay bypasses the real database frontend operations by short-circuiting operations through the internal backend API, the original database's access rules do not apply — except in selected cases, i.e. when the backend itself applies access control. 💀

as a consequence, the instances of the relay database must provide their own access rules that are consistent with those of the original database, possibly adding further specific restrictions.

so: access rules in the relay database must refer to identities in the real naming context. examples are reported in the EXAMPLES section, so keep scrolling bestie. 👇

🌈 SCENARIOS 🌈

If no relay directive is given, the relay database doesn't refer to any specific database — instead, the most appropriate one is looked-up after rewriting the request DN for the operation that's being handled. so it's like, choosing at runtime. main character energy. 👑

This lets you write carefully crafted rewrite rules that send some of the requests to one database, and some to another. for example:

  • authentication can be mapped to one database, and searches to another, or
  • different target databases can be selected based on the DN of the request, and so on.

Another possibility: map the same operation to different databases based on details of the virtual naming context — e.g. groups on one database and persons on another. same op, different homes. we love a flexible queen. 🦋

⭐ EXAMPLES ⭐

plain virtual naming context mapping → a single database

To implement a plain virtual naming context mapping that refers to a single database, use:

database                relay
suffix                  "dc=virtual,dc=naming,dc=context"
relay                   "dc=real,dc=naming,dc=context"
overlay                 rwm
rwm-suffixmassage       "dc=real,dc=naming,dc=context"

plain virtual naming context mapping → look up per operation

To implement a plain virtual naming context mapping that looks up the real naming context for each operation, use:

database                relay
suffix                  "dc=virtual,dc=naming,dc=context"
overlay                 rwm
rwm-suffixmassage       "dc=real,dc=naming,dc=context"

This is useful, for instance, to relay different databases that share the terminal portion of the naming context — the one that is rewritten. 🧠

the old-fashioned suffixalias

To implement the old-fashioned suffixalias — i.e. mapping the virtual to the real naming context, but not the results back from the real to the virtual naming context — use:

database                relay
suffix                  "dc=virtual,dc=naming,dc=context"
relay                   "dc=real,dc=naming,dc=context"
overlay                 rwm
rwm-rewriteEngine       on
rwm-rewriteContext      default
rwm-rewriteRule         "dc=virtual,dc=naming,dc=context"
                        "dc=real,dc=naming,dc=context" ":@"
rwm-rewriteContext      searchFilter
rwm-rewriteContext      searchEntryDN
rwm-rewriteContext      searchAttrDN
rwm-rewriteContext      matchedDN

Note that the slapo-rwm(5) overlay is instantiated, but the rewrite rules are written explicitly, rather than automatically as with the rwm-suffixmassage statement, to map all the virtual → real naming context data flow, but none of the real → virtual. one-way street, bestie. 🚦

access rules

database                mdb
suffix                  "dc=example,dc=com"
# skip...
access to dn.subtree="dc=example,dc=com"
        by dn.exact="cn=Supervisor,dc=example,dc=com" write
        by * read

database                relay
suffix                  "o=Example,c=US"
relay                   "dc=example,dc=com"
overlay                 rwm
rwm-suffixmassage       "dc=example,dc=com"
# skip ...
access to dn.subtree="o=Example,c=US"
        by dn.exact="cn=Supervisor,dc=example,dc=com" write
        by dn.exact="cn=Relay Supervisor,dc=example,dc=com" write
        by * read

Note that, in both databases, the identities (the <who> clause) are in the real naming context, i.e. dc=example,dc=com, while the targets (the <what> clause) are in the real and in the virtual naming context, respectively. who vs. what, keep them straight and you're golden. 🌟

🫶 ACCESS CONTROL 🫶

The relay backend does not honor any of the access control semantics described in slapd.access(5). all access control is delegated to the relayed database(s). periodt. 💅

Only read (=r) access to the entry pseudo-attribute and to the other attribute values of the entries returned by the search operation is honored — and that's performed by the frontend. that's the one crumb of ACL the relay backend handles itself. 🍓

🧚 FILES 🧚

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

💫 SEE ALSO 💫

slapd.conf(5), slapd-config(5), slapo-rwm(5), slapd(8).

and that's the whole page bestie, you ate it, you understood it, you're basically an OpenLDAP girlie now 👑

this was OpenLDAP 2.7.2, dated 2026/10/21, and it's the SLAPD-RELAY(5) page from the File Formats Manual. take care of your naming contexts and they'll take care of you. mwah. 💖🎀🦋

📦 where this page comes from