1SLAPO-RWM(5)                  File Formats Manual                 SLAPO-RWM(5)
2
3
4

NAME

6       slapo-rwm - rewrite/remap overlay to slapd
7

SYNOPSIS

9       /etc/openldap/slapd.conf
10

DESCRIPTION

12       The  rwm overlay to slapd(8) performs basic DN/data rewrite and object‐
13       Class/attributeType mapping.  Its usage is mostly intended  to  provide
14       virtual views of existing data either remotely, in conjunction with the
15       proxy backend described in slapd-ldap(5), or  locally,  in  conjunction
16       with the relay backend described in slapd-relay(5).
17
18       This overlay is experimental.
19

MAPPING

21       An  important  feature  of  the  rwm  overlay  is the capability to map
22       objectClasses and attributeTypes from the local set (or a subset of it)
23       to a foreign set, and vice versa.  This is accomplished by means of the
24       rwm-map directive.
25
26       rwm-map {attribute | objectclass} [<local name> | *] {<foreign name>  |
27       *}
28              Map  attributeTypes and objectClasses from the foreign server to
29              different values on the local slapd.  The reason  is  that  some
30              attributes  might  not be part of the local slapd's schema, some
31              attribute names might be different but serve the  same  purpose,
32              etc.   If  local  or foreign name is `*', the name is preserved.
33              If local name is omitted, the foreign name is removed.  Unmapped
34              names  are preserved if both local and foreign name are `*', and
35              removed if local name is omitted and foreign name is `*'.
36
37       The local objectClasses and attributeTypes must be defined in the local
38       schema;  the  foreign  ones do not have to, but users are encouraged to
39       explicitly define the remote attributeTypes and the objectClasses  they
40       intend  to  map.   All in all, when remapping a remote server via back-
41       ldap (slapd-ldap(5)) or back-meta (slapd-meta(5)) their definition  can
42       be  easily  obtained  by  querying  the subschemaSubentry of the remote
43       server; the problem should not exist when remapping a  local  database.
44       Note,  however,  that the decision whether to rewrite or not attribute‐
45       Types with distinguishedName syntax,  requires  the  knowledge  of  the
46       attributeType syntax.  See the REWRITING section for details.
47
48       Note that when mapping DN-valued attributes from local to remote, first
49       the DN is rewritten, and then the attributeType is mapped;  while  map‐
50       ping  from remote to local, first the attributeType is mapped, and then
51       the DN  is  rewritten.   As  such,  it  is  important  that  the  local
52       attributeType  is  appropriately defined as using the distinguishedName
53       syntax.  Also, note that there are DN-related syntaxes  (i.e.  compound
54       types with a portion that is DN-valued), like nameAndOptionalUID, whose
55       values are currently not rewritten.
56
57       If the foreign type of an attribute mapping is not defined on the local
58       server,  it  might be desirable to have the attribute values normalized
59       after the mapping process. Not normalizing the values can lead to wrong
60       results,  when  the  rwm  overlay is used together with e.g. the pcache
61       overlay. This normalization can be enabled by means of the  rwm-normal‐
62       ize-mapped-attrs directive.
63
64       rwm-normalize-mapped-attrs {yes|no}
65              Set  this  to  "yes", if the rwm overlay should try to normalize
66              the values of attributes that are mapped from an attribute  type
67              that  is  unknown to the local server. The default value of this
68              setting is "no".
69
70       rwm-drop-unrequested-attrs {yes|no}
71              Set this to "yes", if the rwm  overlay  should  drop  attributes
72              that  are  not explicitly requested by a search operation.  When
73              this is set to "no", the rwm overlay will leave  all  attributes
74              in  place,  so  that  subsequent  modules can further manipulate
75              them.  In any case, unrequested attributes will be omitted  from
76              search  results  by the frontend, when the search entry response
77              package is encoded.  The default value of this setting is "yes".
78

SUFFIX MASSAGING

80       A basic feature of the rwm overlay is the capability to perform  suffix
81       massaging  between  a virtual and a real naming context by means of the
82       rwm-suffixmassage directive.  This, in conjunction with proxy backends,
83       slapd-ldap(5)   and   slapd-meta(5),   or   with   the  relay  backend,
84       slapd-relay(5), allows one to create virtual  views  of  databases.   A
85       distinguishing  feature  of  this  overlay  is  that, when instantiated
86       before any database, it can modify the DN of requests  before  database
87       selection.   For  this  reason, rules that rewrite the empty DN ("") or
88       the  subschemaSubentry  DN  (usually  "cn=subschema"),  would   prevent
89       clients from reading the root DSE or the DSA's schema.
90
91       rwm-suffixmassage [<virtual naming context>] <real naming context>
92              Shortcut  to  implement  naming  context rewriting; the trailing
93              part of the DN is rewritten from the virtual to the real  naming
94              context  in the bindDN, searchDN, searchFilterAttrDN, compareDN,
95              compareAttrDN, addDN, addAttrDN, modifyDN, modifyAttrDN, modrDN,
96              newSuperiorDN,  deleteDN, exopPasswdDN, and from the real to the
97              virtual naming context in the  searchEntryDN,  searchAttrDN  and
98              matchedDN  rewrite contexts.  By default no rewriting occurs for
99              the searchFilter and for the referralAttrDN and  referralDN  re‐
100              write  contexts.   If  no <virtual naming context> is given, the
101              first suffix of the database is used; this requires the rwm-suf‐
102              fixmassage directive be defined after the database suffix direc‐
103              tive.  The rwm-suffixmassage directive  automatically  sets  the
104              rwm-rewriteEngine to ON.
105
106       See the REWRITING section for details.
107

REWRITING

109       A  string  is  rewritten according to a set of rules, called a `rewrite
110       context'.  The rules are based on POSIX (''extended'') regular  expres‐
111       sions with substring matching; basic variable substitution and map res‐
112       olution of substrings is allowed by specific mechanisms detailed in the
113       following.   The  behavior  of  pattern  matching/substitution  can  be
114       altered by a set of flags.
115
116              <rewrite context> ::= <rewrite rule> [...]
117              <rewrite rule> ::= <pattern> <action> [<flags>]
118
119       The underlying concept is to build a lightweight rewrite module for the
120       slapd server (initially dedicated to the LDAP backend):
121

Passes

123       An incoming string is matched against a set of rewriteRules.  Rules are
124       made of a regex match pattern, a substitution  pattern  and  a  set  of
125       actions,  described  by  a  set  of  optional flags.  In case of match,
126       string rewriting is performed according  to  the  substitution  pattern
127       that  allows one to refer to substrings matched in the incoming string.
128       The actions, if any, are finally  performed.   Each  rule  is  executed
129       recursively,  unless  altered  by  specific  action  flags; see "Action
130       Flags" for details.  A default limit on the recursion level is set, and
131       can  be  altered  by the rwm-rewriteMaxPasses directive, as detailed in
132       the "Additional Configuration Syntax" section.  The  substitution  pat‐
133       tern  allows  map  resolution of substrings.  A map is a generic object
134       that maps a substitution pattern to a value.  The flags are divided  in
135       "Pattern Matching Flags" and "Action Flags"; the former alter the regex
136       match pattern behavior, while the latter alter  the  actions  that  are
137       taken after substitution.
138

Pattern Matching Flags

140       `C'    honors case in matching (default is case insensitive)
141
142       `R'    use    POSIX   ''basic''   regular   expressions   (default   is
143              ''extended'')
144
145       `M{n}' allow no more than n recursive passes for a specific rule;  does
146              not  alter the max total count of passes, so it can only enforce
147              a stricter limit for a specific rule.
148

Action Flags

150       `:'    apply the rule once only (default is recursive)
151
152       `@'    stop applying rules in case of match; the current rule is  still
153              applied  recursively; combine with `:' to apply the current rule
154              only once and then stop.
155
156       `#'    stop current  operation  if  the  rule  matches,  and  issue  an
157              `unwilling to perform' error.
158
159       `G{n}' jump  n  rules  back  and  forth  (watch for loops!).  Note that
160              `G{1}' is implicit in every rule.
161
162       `I'    ignores errors in rule; this  means,  in  case  of  error,  e.g.
163              issued  by  a  map, the error is treated as a missed match.  The
164              `unwilling to perform' is not overridden.
165
166       `U{n}' uses n as return code if the rule matches;  the  flag  does  not
167              alter  the  recursive  behavior of the rule, so, to have it per‐
168              formed only once, it must be used in combination with `:',  e.g.
169              `:U{32}'  returns the value `32' (indicating noSuchObject) after
170              exactly one execution of the rule, if the pattern matches.  As a
171              consequence,  its behavior is equivalent to `@', with the return
172              code set to n; or, in other words, `@' is equivalent to  `U{0}'.
173              Positive  errors  are allowed, indicating the related LDAP error
174              codes as specified in draft-ietf-ldapbis-protocol.
175
176       The ordering of the flags can be significant.   For  instance:  `IG{2}'
177       means  ignore errors and jump two lines ahead both in case of match and
178       in case of error, while `G{2}I' means ignore errors, but jump two lines
179       ahead only in case of match.
180
181       More flags (mainly Action Flags) will be added as needed.
182

Pattern Matching

184       See regex(7) and/or re_format(7).
185

Substitution Pattern Syntax

187       Everything starting with `$' requires substitution;
188
189       the only obvious exception is `$$', which is turned into a single `$';
190
191       the  basic  substitution is `$<d>', where `<d>' is a digit; 0 means the
192       whole string, while 1-9 is a submatch, as discussed in regex(7)  and/or
193       re_format(7).
194
195       a  `$' followed by a `{' invokes an advanced substitution.  The pattern
196       is:
197
198              `$' `{' [ <operator> ] <name> `(' <substitution> `)' `}'
199
200       where <name> must be a legal name for the map, i.e.
201
202              <name> ::= [a-z][a-z0-9]* (case insensitive)
203              <operator> ::= `>' `|' `&' `&&' `*' `**' `$'
204
205       and <substitution> must be a legal substitution pattern, with no limits
206       on the nesting level.
207
208       The operators are:
209
210       >      sub-context  invocation; <name> must be a legal, already defined
211              rewrite context name
212
213       |      external command invocation;  <name>  must  refer  to  a  legal,
214              already defined command name (NOT IMPLEMENTED YET)
215
216       &      variable  assignment;  <name>  defines a variable in the running
217              operation structure which can be dereferenced later; operator  &
218              assigns  a  variable  in  the rewrite context scope; operator &&
219              assigns a variable that scopes  the  entire  session,  e.g.  its
220              value can be dereferenced later by other rewrite contexts
221
222       *      variable  dereferencing; <name> must refer to a variable that is
223              defined and assigned  for  the  running  operation;  operator  *
224              dereferences a variable scoping the rewrite context; operator **
225              dereferences a variable scoping  the  whole  session,  e.g.  the
226              value is passed across rewrite contexts
227
228       $      parameter dereferencing; <name> must refer to an existing param‐
229              eter; the idea is to make some run-time parameters  set  by  the
230              system available to the rewrite engine, as the client host name,
231              the bind DN if any, constant parameters  initialized  at  config
232              time,  and  so  on;  no  parameter  is  currently  set by either
233              back-ldap or back-meta, but constant parameters can  be  defined
234              in the configuration file by using the rewriteParam directive.
235
236       Substitution  escaping  has  been delegated to the `$' symbol, which is
237       used instead of `\' in string  substitution  patterns  because  `\'  is
238       already  escaped  by  slapd's  low  level parsing routines; as a conse‐
239       quence, regex escaping requires two `\'  symbols,  e.g.  `.*\.foo\.bar'
240       must be written as `.*\\.foo\\.bar'.
241

Rewrite Context

243       A rewrite context is a set of rules which are applied in sequence.  The
244       basic idea is to have an application initialize a rewrite engine (think
245       of  Apache's  mod_rewrite  ...)  with  a  set of rewrite contexts; when
246       string rewriting is required, one invokes the appropriate rewrite  con‐
247       text  with  the  input string and obtains the newly rewritten one if no
248       errors occur.
249
250       Each basic server operation is associated to a  rewrite  context;  they
251       are  divided  in two main groups: client -> server and server -> client
252       rewriting.
253
254       client -> server:
255
256              (default)            if defined and no specific context
257                                   is available
258              bindDN               bind
259              searchDN             search
260              searchFilter         search
261              searchFilterAttrDN   search
262              compareDN            compare
263              compareAttrDN        compare AVA
264              addDN                add
265              addAttrDN            add AVA (DN portion of "ref" excluded)
266              modifyDN             modify
267              modifyAttrDN         modify AVA (DN portion of "ref" excluded)
268              referralAttrDN       add/modify DN portion of referrals
269                                   (default to none)
270              renameDN             modrdn (the old DN)
271              newSuperiorDN        modrdn (the new parent DN, if any)
272              newRDN               modrdn (the new relative DN)
273              deleteDN             delete
274              exopPasswdDN         password modify extended operation DN
275
276       server -> client:
277
278              searchEntryDN        search (only if defined; no default;
279                                   acts on DN of search entries)
280              searchAttrDN         search AVA (only if defined; defaults
281                                   to searchEntryDN; acts on DN-syntax
282                                   attributes of search results)
283              matchedDN            all ops (only if applicable; defaults
284                                   to searchEntryDN)
285              referralDN           all ops (only if applicable; defaults
286                                   to none)
287

Basic Configuration Syntax

289       All rewrite/remap directives start with the prefix rwm-; for  backwards
290       compatibility  with  the  historical  slapd-ldap(5)  and  slapd-meta(5)
291       builtin rewrite/remap capabilities, the prefix may be omitted, but this
292       practice is strongly discouraged.
293
294       rwm-rewriteEngine { on | off }
295              If  `on',  the  requested  rewriting  is performed; if `off', no
296              rewriting takes place (an easy way  to  stop  rewriting  without
297              altering too much the configuration file).
298
299       rwm-rewriteContext <context name> [ alias <aliased context name> ]
300              <Context name> is the name that identifies the context, i.e. the
301              name used by the application to refer to the  set  of  rules  it
302              contains.   It  is used also to reference sub contexts in string
303              rewriting.  A context may alias another one.  In this  case  the
304              alias  context  contains  no  rule, and any reference to it will
305              result in accessing the aliased one.
306
307       rwm-rewriteRule <regex match pattern> <substitution pattern> [  <flags>
308       ]
309              Determines  how  a  string  can  be  rewritten  if  a pattern is
310              matched.  Examples are reported below.
311

Additional Configuration Syntax

313       rwm-rewriteMap <map type> <map name> [ <map attrs> ]
314              Allows one to define a map that transforms  substring  rewriting
315              into something else.  The map is referenced inside the substitu‐
316              tion pattern of a rule.
317
318       rwm-rewriteParam <param name> <param value>
319              Sets a value with global scope, that can be dereferenced by  the
320              command `${$paramName}'.
321
322       rwm-rewriteMaxPasses <number of passes> [<number of passes per rule>]
323              Sets  the  maximum  number of total rewriting passes that can be
324              performed in a single rewrite operation  (to  avoid  loops).   A
325              safe  default  is  set  to 100; note that reaching this limit is
326              still treated as a success; recursive  invocation  of  rules  is
327              simply  interrupted.   The count applies to the rewriting opera‐
328              tion as a whole, not to any single rule;  an  optional  per-rule
329              limit  can be set.  This limit is overridden by setting specific
330              per-rule limits with the `M{n}' flag.
331
332

MAPS

334       Currently, few maps are builtin but additional map types may be  regis‐
335       tered at runtime.
336
337       Supported maps are:
338
339       LDAP <URI> [bindwhen=<when>] [version=<version>] [binddn=<DN>] [creden‐
340       tials=<cred>]
341              The LDAP map expands a value by performing a simple LDAP search.
342              Its  configuration is based on a mandatory URI, whose attrs por‐
343              tion must contain exactly one attribute (use  entryDN  to  fetch
344              the  DN of an entry).  If a multi-valued attribute is used, only
345              the first value is considered.
346
347              The parameter bindwhen determines when the connection is  estab‐
348              lished.   It  can  take  the  values  now, later, and everytime,
349              respectively indicating that the connection should be created at
350              startup,  when  required, or any time it is used.  In the former
351              two cases, the connection is cached, while in the latter a fresh
352              new one is used all times.  This is the default.
353
354              The  parameters  binddn and credentials represent the DN and the
355              password that is used to perform an  authenticated  simple  bind
356              before  performing the search operation; if not given, an anony‐
357              mous connection is used.
358
359              The parameter version can be 2 or 3  to  indicate  the  protocol
360              version that must be used.  The default is 3.
361
362
363       slapd <URI>
364              The  slapd  map  expands  a value by performing an internal LDAP
365              search.  Its configuration is based on a  mandatory  URI,  which
366              must  begin  with  ldap:/// (i.e., it must be an LDAP URI and it
367              must not specify a host).  As with the LDAP map, the attrs  por‐
368              tion  must  contain exactly one attribute, and if a multi-valued
369              attribute is used, only the first value is considered.
370
371

REWRITE CONFIGURATION EXAMPLES

373       # set to `off' to disable rewriting
374       rwm-rewriteEngine on
375
376       # the rules the "suffixmassage" directive implies
377       rwm-rewriteEngine on
378       # all dataflow from client to server referring to DNs
379       rwm-rewriteContext default
380       rwm-rewriteRule "(.+,)?<virtualnamingcontext>$" "$1<realnamingcontext>" ":"
381       # empty filter rule
382       rwm-rewriteContext searchFilter
383       # all dataflow from server to client
384       rwm-rewriteContext searchEntryDN
385       rwm-rewriteRule "(.+,)?<realnamingcontext>$" "$1<virtualnamingcontext>" ":"
386       rwm-rewriteContext searchAttrDN alias searchEntryDN
387       rwm-rewriteContext matchedDN alias searchEntryDN
388       # misc empty rules
389       rwm-rewriteContext referralAttrDN
390       rwm-rewriteContext referralDN
391
392       # Everything defined here goes into the `default' context.
393       # This rule changes the naming context of anything sent
394       # to `dc=home,dc=net' to `dc=OpenLDAP, dc=org'
395
396       rwm-rewriteRule "(.+,)?dc=home,[ ]?dc=net$"
397                   "$1dc=OpenLDAP, dc=org"  ":"
398
399       # since a pretty/normalized DN does not include spaces
400       # after rdn separators, e.g. `,', this rule suffices:
401
402       rwm-rewriteRule "(.+,)?dc=home,dc=net$"
403                   "$1dc=OpenLDAP,dc=org"  ":"
404
405       # Start a new context (ends input of the previous one).
406       # This rule adds blanks between DN parts if not present.
407       rwm-rewriteContext  addBlanks
408       rwm-rewriteRule     "(.*),([^ ].*)" "$1, $2"
409
410       # This one eats blanks
411       rwm-rewriteContext  eatBlanks
412       rwm-rewriteRule     "(.*), (.*)" "$1,$2"
413
414       # Here control goes back to the default rewrite
415       # context; rules are appended to the existing ones.
416       # anything that gets here is piped into rule `addBlanks'
417       rwm-rewriteContext  default
418       rwm-rewriteRule     ".*" "${>addBlanks($0)}" ":"
419
420       # Rewrite the search base according to `default' rules.
421       rwm-rewriteContext  searchDN alias default
422
423       # Search results with OpenLDAP DN are rewritten back with
424       # `dc=home,dc=net' naming context, with spaces eaten.
425       rwm-rewriteContext  searchEntryDN
426       rwm-rewriteRule     "(.*[^ ],)?[ ]?dc=OpenLDAP,[ ]?dc=org$"
427                       "${>eatBlanks($1)}dc=home,dc=net"    ":"
428
429       # Bind with email instead of full DN: we first need
430       # an ldap map that turns attributes into a DN (the
431       # argument used when invoking the map is appended to
432       # the URI and acts as the filter portion)
433       rwm-rewriteMap ldap attr2dn "ldap://host/dc=my,dc=org?dn?sub"
434
435       # Then we need to detect DN made up of a single email,
436       # e.g. `mail=someone@example.com'; note that the rule
437       # in case of match stops rewriting; in case of error,
438       # it is ignored.  In case we are mapping virtual
439       # to real naming contexts, we also need to rewrite
440       # regular DNs, because the definition of a bindDN
441       # rewrite context overrides the default definition.
442       rwm-rewriteContext bindDN
443       rwm-rewriteRule "^mail=[^,]+@[^,]+$" "${attr2dn($0)}" ":@I"
444
445       # This is a rather sophisticated example. It massages a
446       # search filter in case who performs the search has
447       # administrative privileges.  First we need to keep
448       # track of the bind DN of the incoming request, which is
449       # stored in a variable called `binddn' with session scope,
450       # and left in place to allow regular binding:
451       rwm-rewriteContext  bindDN
452       rwm-rewriteRule     ".+" "${&&binddn($0)}$0" ":"
453
454       # A search filter containing `uid=' is rewritten only
455       # if an appropriate DN is bound.
456       # To do this, in the first rule the bound DN is
457       # dereferenced, while the filter is decomposed in a
458       # prefix, in the value of the `uid=<arg>' AVA, and
459       # in a suffix. A tag `<>' is appended to the DN.
460       # If the DN refers to an entry in the `ou=admin' subtree,
461       # the filter is rewritten OR-ing the `uid=<arg>' with
462       # `cn=<arg>'; otherwise it is left as is. This could be
463       # useful, for instance, to allow apache's auth_ldap-1.4
464       # module to authenticate users with both `uid' and
465       # `cn', but only if the request comes from a possible
466       # `cn=Web auth,ou=admin,dc=home,dc=net' user.
467       rwm-rewriteContext searchFilter
468       rwm-rewriteRule "(.*\\()uid=([a-z0-9_]+)(\\).*)"
469         "${**binddn}<>${&prefix($1)}${&arg($2)}${&suffix($3)}"
470         ":I"
471       rwm-rewriteRule "^[^,]+,ou=admin,dc=home,dc=net$"
472         "${*prefix}|(uid=${*arg})(cn=${*arg})${*suffix}" ":@I"
473       rwm-rewriteRule ".*<>$" "${*prefix}uid=${*arg}${*suffix}" ":"
474
475       # This example shows how to strip unwanted DN-valued
476       # attribute values from a search result; the first rule
477       # matches DN values below "ou=People,dc=example,dc=com";
478       # in case of match the rewriting exits successfully.
479       # The second rule matches everything else and causes
480       # the value to be rejected.
481       rwm-rewriteContext searchEntryDN
482       rwm-rewriteRule ".+,ou=People,dc=example,dc=com$" "$0" ":@"
483       rwm-rewriteRule ".*" "" "#"
484

MAPPING EXAMPLES

486       The following directives map the object  class  `groupOfNames'  to  the
487       object  class  `groupOfUniqueNames'  and the attribute type `member' to
488       the attribute type `uniqueMember':
489
490              map objectclass groupOfNames groupOfUniqueNames
491              map attribute uniqueMember member
492
493       This presents a limited attribute set from the foreign server:
494
495              map attribute cn *
496              map attribute sn *
497              map attribute manager *
498              map attribute description *
499              map attribute *
500
501       These lines map cn, sn, manager, and description to themselves, and any
502       other attribute gets "removed" from the object before it is sent to the
503       client (or sent up to the LDAP server).  This is obviously a simplistic
504       example, but you get the point.
505

FILES

507       /etc/openldap/slapd.conf
508              default slapd configuration file
509

SEE ALSO

511       slapd.conf(5),     slapd-config(5),    slapd-ldap(5),    slapd-meta(5),
512       slapd-relay(5), slapd(8), regex(7), re_format(7).
513

AUTHOR

515       Pierangelo Masarati;  based  on  back-ldap  rewrite/remap  features  by
516       Howard Chu, Pierangelo Masarati.
517
518
519
520OpenLDAP 2.4.50                   2020/04/28                      SLAPO-RWM(5)
Impressum