1SLAPO-RWM(5) File Formats Manual SLAPO-RWM(5)
2
6 slapo-rwm - rewrite/remap overlay
7
9 /etc/openldap/slapd.conf
10
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 This overlay is experimental.
19
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 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 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 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
58 A basic feature of the rwm overlay is the capability to perform suffix
59 massaging between a virtual and a real naming context by means of the
60 rwm-suffixmassage directive.
61 rwm-suffixmassage [<virtual naming context>] <real naming context>
63 Shortcut to implement naming context rewriting; the trailing
64 part of the DN is rewritten from the virtual to the real naming
65 context in the bindDN, searchDN, searchFilterAttrDN, compareDN,
66 compareAttrDN, addDN, addAttrDN, modifyDN, modifyAttrDN, modrDN,
67 newSuperiorDN, deleteDN, exopPasswdDN, and from the real to the
68 virtual naming context in the searchEntryDN, searchAttrDN and
69 matchedDN rewrite contexts. By default no rewriting occurs for
70 the searchFilter and for the referralAttrDN and referralDN re‐
71 write contexts. If no <virtual naming context> is given, the
72 first suffix of the database is used; this requires the rwm-suf‐
73 fixmassage directive be defined after the database suffix direc‐
74 tive. The rwm-suffixmassage directive automatically sets the
75 rwm-rewriteEngine to ON.
76 See the REWRITING section for details.
78
80 A string is rewritten according to a set of rules, called a `rewrite
81 context'. The rules are based on POSIX (''extended'') regular expres‐
82 sions with substring matching; basic variable substitution and map res‐
83 olution of substrings is allowed by specific mechanisms detailed in the
84 following. The behavior of pattern matching/substitution can be
85 altered by a set of flags.
86 <rewrite context> ::= <rewrite rule> [...]
88 <rewrite rule> ::= <pattern> <action> [<flags>]
89 The underlying concept is to build a lightweight rewrite module for the
91 slapd server (initially dedicated to the LDAP backend):
92
94 An incoming string is matched against a set of rewriteRules. Rules are
95 made of a regex match pattern, a substitution pattern and a set of
96 actions, described by a set of optional flags. In case of match,
97 string rewriting is performed according to the substitution pattern
98 that allows to refer to substrings matched in the incoming string. The
99 actions, if any, are finally performed. Each rule is executed recur‐
100 sively, unless altered by specific action flags; see "Action Flags" for
101 details. A default limit on the recursion level is set, and can be
102 altered by the rwm-rewriteMaxPasses directive, as detailed in the
103 "Additional Configuration Syntax" section. The substitution pattern
104 allows map resolution of substrings. A map is a generic object that
105 maps a substitution pattern to a value. The flags are divided in "Pat‐
106 tern Matching Flags" and "Action Flags"; the former alter the regex
107 match pattern behavior, while the latter alter the actions that are
108 taken after substitution.
109
111 `C' honors case in matching (default is case insensitive)
112 `R' use POSIX ''basic'' regular expressions (default is
114 ''extended'')
115 `M{n}' allow no more than n recursive passes for a specific rule; does
117 not alter the max total count of passes, so it can only enforce
118 a stricter limit for a specific rule.
119
121 `:' apply the rule once only (default is recursive)
122 `@' stop applying rules in case of match; the current rule is still
124 applied recursively; combine with `:' to apply the current rule
125 only once and then stop.
126 `#' stop current operation if the rule matches, and issue an
128 `unwilling to perform' error.
129 `G{n}' jump n rules back and forth (watch for loops!). Note that
131 `G{1}' is implicit in every rule.
132 `I' ignores errors in rule; this means, in case of error, e.g.
134 issued by a map, the error is treated as a missed match. The
135 `unwilling to perform' is not overridden.
136 `U{n}' uses n as return code if the rule matches; the flag does not
138 alter the recursive behavior of the rule, so, to have it per‐
139 formed only once, it must be used in combination with `:', e.g.
140 `:U{32}' returns the value `32' (indicating noSuchObject) after
141 exactly one execution of the rule, if the pattern matches. As a
142 consequence, its behavior is equivalent to `@', with the return
143 code set to n; or, in other words, `@' is equivalent to `U{0}'.
144 Positive errors are allowed, indicating the related LDAP error
145 codes as specified in draft-ietf-ldapbis-protocol.
146 The ordering of the flags can be significant. For instance: `IG{2}'
148 means ignore errors and jump two lines ahead both in case of match and
149 in case of error, while `G{2}I' means ignore errors, but jump two lines
150 ahead only in case of match.
151 More flags (mainly Action Flags) will be added as needed.
153
155 See regex(7) and/or re_format(7).
156
158 Everything starting with `$' requires substitution;
159 the only obvious exception is `$$', which is turned into a single `$';
161 the basic substitution is `$<d>', where `<d>' is a digit; 0 means the
163 whole string, while 1-9 is a submatch, as discussed in regex(7) and/or
164 re_format(7).
165 a `$' followed by a `{' invokes an advanced substitution. The pattern
167 is:
168 `$' `{' [ <operator> ] <name> `(' <substitution> `)' `}'
170 where <name> must be a legal name for the map, i.e.
172 <name> ::= [a-z][a-z0-9]* (case insensitive)
174 <operator> ::= `>' `|' `&' `&&' `*' `**' `$'
175 and <substitution> must be a legal substitution pattern, with no limits
177 on the nesting level.
178 The operators are:
180 > sub-context invocation; <name> must be a legal, already defined
182 rewrite context name
183 | external command invocation; <name> must refer to a legal,
185 already defined command name (NOT IMPLEMENTED YET)
186 & variable assignment; <name> defines a variable in the running
188 operation structure which can be dereferenced later; operator &
189 assigns a variable in the rewrite context scope; operator &&
190 assigns a variable that scopes the entire session, e.g. its
191 value can be dereferenced later by other rewrite contexts
192 * variable dereferencing; <name> must refer to a variable that is
194 defined and assigned for the running operation; operator *
195 dereferences a variable scoping the rewrite context; operator **
196 dereferences a variable scoping the whole session, e.g. the
197 value is passed across rewrite contexts
198 $ parameter dereferencing; <name> must refer to an existing param‐
200 eter; the idea is to make some run-time parameters set by the
201 system available to the rewrite engine, as the client host name,
202 the bind DN if any, constant parameters initialized at config
203 time, and so on; no parameter is currently set by either
204 back-ldap or back-meta, but constant parameters can be defined
205 in the configuration file by using the rewriteParam directive.
206 Substitution escaping has been delegated to the `$' symbol, which is
208 used instead of `\' in string substitution patterns because `\' is
209 already escaped by slapd's low level parsing routines; as a conse‐
210 quence, regex escaping requires two `\' symbols, e.g. `.*\.foo\.bar'
211 must be written as `.*\\.foo\\.bar'.
212
214 A rewrite context is a set of rules which are applied in sequence. The
215 basic idea is to have an application initialize a rewrite engine (think
216 of Apache's mod_rewrite ...) with a set of rewrite contexts; when
217 string rewriting is required, one invokes the appropriate rewrite con‐
218 text with the input string and obtains the newly rewritten one if no
219 errors occur.
220 Each basic server operation is associated to a rewrite context; they
222 are divided in two main groups: client -> server and server -> client
223 rewriting.
224 client -> server:
226 (default) if defined and no specific context
228 is available
229 bindDN bind
230 searchDN search
231 searchFilter search
232 searchFilterAttrDN search
233 compareDN compare
234 compareAttrDN compare AVA
235 addDN add
236 addAttrDN add AVA (DN portion of "ref" excluded)
237 modifyDN modify
238 modifyAttrDN modify AVA (DN portion of "ref" excluded)
239 referralAttrDN add/modify DN portion of referrals
240 (default to none)
241 modrDN modrdn
242 newSuperiorDN modrdn
243 deleteDN delete
244 exopPasswdDN password modify extended operation DN
245 server -> client:
247 searchEntryDN search (only if defined; no default;
249 acts on DN of search entries)
250 searchAttrDN search AVA (only if defined; defaults
251 to searchEntryDN; acts on DN-syntax
252 attributes of search results)
253 matchedDN all ops (only if applicable; defaults
254 to searchEntryDN)
255 referralDN all ops (only if applicable; defaults
256 to none)
257
259 All rewrite/remap directives start with the prefix rwm-; for backwards
260 compatibility with the historical slapd-ldap(5) and slapd-meta(5)
261 builtin rewrite/remap capabilities, the prefix may be omitted, but this
262 practice is strongly discouraged.
263 rwm-rewriteEngine { on | off }
265 If `on', the requested rewriting is performed; if `off', no
266 rewriting takes place (an easy way to stop rewriting without
267 altering too much the configuration file).
268 rwm-rewriteContext <context name> [ alias <aliased context name> ]
270 <Context name> is the name that identifies the context, i.e. the
271 name used by the application to refer to the set of rules it
272 contains. It is used also to reference sub contexts in string
273 rewriting. A context may alias another one. In this case the
274 alias context contains no rule, and any reference to it will
275 result in accessing the aliased one.
276 rwm-rewriteRule <regex match pattern> <substitution pattern> [ <flags>
278 ]
279 Determines how a string can be rewritten if a pattern is
280 matched. Examples are reported below.
281
283 rwm-rewriteMap <map type> <map name> [ <map attrs> ]
284 Allows to define a map that transforms substring rewriting into
285 something else. The map is referenced inside the substitution
286 pattern of a rule.
287 rwm-rewriteParam <param name> <param value>
289 Sets a value with global scope, that can be dereferenced by the
290 command `${$paramName}'.
291 rwm-rewriteMaxPasses <number of passes> [<number of passes per rule>]
293 Sets the maximum number of total rewriting passes that can be
294 performed in a single rewrite operation (to avoid loops). A
295 safe default is set to 100; note that reaching this limit is
296 still treated as a success; recursive invocation of rules is
297 simply interrupted. The count applies to the rewriting opera‐
298 tion as a whole, not to any single rule; an optional per-rule
299 limit can be set. This limit is overridden by setting specific
300 per-rule limits with the `M{n}' flag.
301
303 # set to `off' to disable rewriting
304 rwm-rewriteEngine on
305 # the rules the "suffixmassage" directive implies
307 rwm-rewriteEngine on
308 # all dataflow from client to server referring to DNs
309 rwm-rewriteContext default
310 rwm-rewriteRule "(.+,)?<virtualnamingcontext>$" "$1<realnamingcontext>" ":"
311 # empty filter rule
312 rwm-rewriteContext searchFilter
313 # all dataflow from server to client
314 rwm-rewriteContext searchEntryDN
315 rwm-rewriteRule "(.+,)?<realnamingcontext>$" "$1<virtualnamingcontext>" ":"
316 rwm-rewriteContext searchAttrDN alias searchEntryDN
317 rwm-rewriteContext matchedDN alias searchEntryDN
318 # misc empty rules
319 rwm-rewriteContext referralAttrDN
320 rwm-rewriteContext referralDN
321 # Everything defined here goes into the `default' context.
323 # This rule changes the naming context of anything sent
324 # to `dc=home,dc=net' to `dc=OpenLDAP, dc=org'
325 rwm-rewriteRule "(.+,)?dc=home,[ ]?dc=net$"
327 "$1dc=OpenLDAP, dc=org" ":"
328 # since a pretty/normalized DN does not include spaces
330 # after rdn separators, e.g. `,', this rule suffices:
331 rwm-rewriteRule "(.+,)?dc=home,dc=net$"
333 "$1dc=OpenLDAP,dc=org" ":"
334 # Start a new context (ends input of the previous one).
336 # This rule adds blanks between DN parts if not present.
337 rwm-rewriteContext addBlanks
338 rwm-rewriteRule "(.*),([^ ].*)" "$1, $2"
339 # This one eats blanks
341 rwm-rewriteContext eatBlanks
342 rwm-rewriteRule "(.*), (.*)" "$1,$2"
343 # Here control goes back to the default rewrite
345 # context; rules are appended to the existing ones.
346 # anything that gets here is piped into rule `addBlanks'
347 rwm-rewriteContext default
348 rwm-rewriteRule ".*" "${>addBlanks($0)}" ":"
349 # Rewrite the search base according to `default' rules.
351 rwm-rewriteContext searchDN alias default
352 # Search results with OpenLDAP DN are rewritten back with
354 # `dc=home,dc=net' naming context, with spaces eaten.
355 rwm-rewriteContext searchEntryDN
356 rwm-rewriteRule "(.*[^ ],)?[ ]?dc=OpenLDAP,[ ]?dc=org$"
357 "${>eatBlanks($1)}dc=home,dc=net" ":"
358 # Bind with email instead of full DN: we first need
360 # an ldap map that turns attributes into a DN (the
361 # argument used when invoking the map is appended to
362 # the URI and acts as the filter portion)
363 rwm-rewriteMap ldap attr2dn "ldap://host/dc=my,dc=org?dn?sub"
364 # Then we need to detect DN made up of a single email,
366 # e.g. `mail=someone@example.com'; note that the rule
367 # in case of match stops rewriting; in case of error,
368 # it is ignored. In case we are mapping virtual
369 # to real naming contexts, we also need to rewrite
370 # regular DNs, because the definition of a bindDN
371 # rewrite context overrides the default definition.
372 rwm-rewriteContext bindDN
373 rwm-rewriteRule "^mail=[^,]+@[^,]+$" "${attr2dn($0)}" ":@I"
374 # This is a rather sophisticated example. It massages a
376 # search filter in case who performs the search has
377 # administrative privileges. First we need to keep
378 # track of the bind DN of the incoming request, which is
379 # stored in a variable called `binddn' with session scope,
380 # and left in place to allow regular binding:
381 rwm-rewriteContext bindDN
382 rwm-rewriteRule ".+" "${&&binddn($0)}$0" ":"
383 # A search filter containing `uid=' is rewritten only
385 # if an appropriate DN is bound.
386 # To do this, in the first rule the bound DN is
387 # dereferenced, while the filter is decomposed in a
388 # prefix, in the value of the `uid=<arg>' AVA, and
389 # in a suffix. A tag `<>' is appended to the DN.
390 # If the DN refers to an entry in the `ou=admin' subtree,
391 # the filter is rewritten OR-ing the `uid=<arg>' with
392 # `cn=<arg>'; otherwise it is left as is. This could be
393 # useful, for instance, to allow apache's auth_ldap-1.4
394 # module to authenticate users with both `uid' and
395 # `cn', but only if the request comes from a possible
396 # `cn=Web auth,ou=admin,dc=home,dc=net' user.
397 rwm-rewriteContext searchFilter
398 rwm-rewriteRule "(.*\\()uid=([a-z0-9_]+)(\\).*)"
399 "${**binddn}<>${&prefix($1)}${&arg($2)}${&suffix($3)}"
400 ":I"
401 rwm-rewriteRule "^[^,]+,ou=admin,dc=home,dc=net$"
402 "${*prefix}|(uid=${*arg})(cn=${*arg})${*suffix}" ":@I"
403 rwm-rewriteRule ".*<>$" "${*prefix}uid=${*arg}${*suffix}" ":"
404 # This example shows how to strip unwanted DN-valued
406 # attribute values from a search result; the first rule
407 # matches DN values below "ou=People,dc=example,dc=com";
408 # in case of match the rewriting exits successfully.
409 # The second rule matches everything else and causes
410 # the value to be rejected.
411 rwm-rewriteContext searchEntryDN
412 rwm-rewriteRule ".+,ou=People,dc=example,dc=com$" "$0" ":@"
413 rwm-rewriteRule ".*" "" "#"
414
416 The following directives map the object class `groupOfNames' to the
417 object class `groupOfUniqueNames' and the attribute type `member' to
418 the attribute type `uniqueMember':
419 map objectclass groupOfNames groupOfUniqueNames
421 map attribute uniqueMember member
422 This presents a limited attribute set from the foreign server:
424 map attribute cn *
426 map attribute sn *
427 map attribute manager *
428 map attribute description *
429 map attribute *
430 These lines map cn, sn, manager, and description to themselves, and any
432 other attribute gets "removed" from the object before it is sent to the
433 client (or sent up to the LDAP server). This is obviously a simplistic
434 example, but you get the point.
435
437 /etc/openldap/slapd.conf
438 default slapd configuration file
439
441 slapd.conf(5), slapd-ldap(5), slapd-meta(5), slapd-relay(5), slapd(8),
442 regex(7), re_format(7).
443
445 Pierangelo Masarati; based on back-ldap rewrite/remap features by
446 Howard Chu, Pierangelo Masarati.
447OpenLDAP 2.3.34 2007/2/16 SLAPO-RWM(5)