.TH SLAPD-META 5 "RELEASEDATE" "OpenLDAP LDVERSION"
-.\" Copyright 1998-2003 The OpenLDAP Foundation, All Rights Reserved.
+.\" 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>
.\" $OpenLDAP$
However, both for backward compatibility and for ease of configuration
when simple suffix massage is required, it has been preserved.
It wraps the basic rewriting instructions that perform suffix
-massaging.
+massaging. See the "REWRITING" section for a detailed list
+of the rewrite rules it implies.
.LP
Note: this also fixes a flaw in suffix massaging, which operated
on (case insensitive) DNs instead of normalized DNs,
A string is rewritten according to a set of rules, called a `rewrite
context'.
The rules are based on Regular Expressions (POSIX regex) with
-substring matching; extensions are planned to allow basic variable
-substitution and map resolution of substrings.
+substring matching; basic variable substitution and map resolution
+of substrings is allowed by specific mechanisms detailed in the following.
The behavior of pattern matching/substitution can be altered by a set
of flags.
.LP
for the slapd server (initially dedicated to the LDAP backend).
.SH Passes
An incoming string is matched agains a set of rules.
-Rules are made of a match pattern, a substitution pattern and a set of
-actions.
+Rules are made of a regex match pattern, a substitution pattern
+and a set of actions, described by a set of flags.
In case of match a string rewriting is performed according to the
substitution pattern that allows to refer to substrings matched in the
incoming string.
The actions, if any, are finally performed.
The substitution pattern allows map resolution of substrings.
A map is a generic object that maps a substitution pattern to a value.
+The flags are divided in "Pattern matching Flags" and "Action Flags";
+the former alter the regex match pattern behaviorm while the latter
+alter the action that is taken after substitution.
.SH "Pattern Matching Flags"
.TP
.B `C'
.TP
.B `R'
use POSIX Basic Regular Expressions (default is Extended)
+.TP
+.B `M{n}'
+allow no more than
+.B n
+recursive passes for a specific rule; does not alter the max total count
+of passes, so it can only enforce a stricter limit for a specific rule.
.SH "Action Flags"
.TP
.B `:'
By convention, the freely available codes are above 16 included;
the others are reserved.
.LP
-The ordering of the flags is significant.
+The ordering of the flags can be significant.
For instance: `IG{2}' means ignore errors and jump two lines ahead
both in case of match and in case of error, while `G{2}I' means ignore
errors, but jump two lines ahead only in case of match.
.LP
.RS
.nf
-(default) if defined and no specific context
- is available
-bindDN bind
-searchBase search
-searchFilter search
-compareDN compare
-compareAttrDN compare AVA
-addDN add
-addAttrDN add AVA
-modifyDN modify
-modifyAttrDN modify AVA
-modrDN modrdn
-newSuperiorDN modrdn
-deleteDN delete
+(default) if defined and no specific context
+ is available
+bindDN bind
+searchBase search
+searchFilter search
+searchFilterAttrDN search
+compareDN compare
+compareAttrDN compare AVA
+addDN add
+addAttrDN add AVA
+modifyDN modify
+modifyAttrDN modify AVA
+modrDN modrdn
+newSuperiorDN modrdn
+deleteDN delete
+exopPasswdDN passwd exop DN if proxy
.fi
.RE
.LP
.LP
.RS
.nf
-searchResult search (only if defined; no default;
- acts on DN and DN-syntax attributes
- of search results)
-searchAttrDN search AVA
-matchedDN all ops (only if applicable)
+searchResult search (only if defined; no default;
+ acts on DN and DN-syntax attributes
+ of search results)
+searchAttrDN search AVA
+matchedDN all ops (only if applicable)
.fi
.RE
.LP
In this case the alias context contains no rule, and any reference to
it will result in accessing the aliased one.
.TP
-.B rewriteRule "<regex pattern>" "<substitution pattern>" "[ <flags> ]"
-Determines how a tring can be rewritten if a pattern is matched.
+.B rewriteRule "<regex match pattern>" "<substitution pattern>" "[ <flags> ]"
+Determines how a string can be rewritten if a pattern is matched.
Examples are reported below.
.SH "Additional configuration syntax:"
.TP
-.B rewriteMap "<map name>" "<map type>" "[ <map attrs> ]"
+.B rewriteMap "<map type>" "<map name>" "[ <map attrs> ]"
Allows to define a map that transforms substring rewriting into
something else.
The map is referenced inside the substitution pattern of a rule.
Sets a value with global scope, that can be dereferenced by the
command `%{$paramName}'.
.TP
-.B rewriteMaxPasses <number of passes>
+.B rewriteMaxPasses <number of passes> [<number of passes per rule>]
Sets the maximum number of total rewriting passes that can be
performed in a single rewrite operation (to avoid loops).
+A safe default is set to 100; note that reaching this limit is still
+treated as a success; recursive invocation of rules is simply
+interrupted.
+The count applies to the rewriting operation as a whole, not
+to any single rule; an optional per-rule limit can be set.
+This limit is overridden by setting specific per-rule limits
+with the `M{n}' flag.
.SH "Configuration examples:"
.nf
# set to `off' to disable rewriting
rewriteEngine on
+# the rules the "suffixmassage" directive implies
+rewriteEngine on
+# all dataflow from client to server referring to DNs
+rewriteContext default
+rewriteRule "(.*)<virtualnamingcontext>$" "%1<realnamingcontext>" ":"
+# empty filter rule
+rewriteContext searchFilter
+# all dataflow from server to client
+rewriteContext searchResult
+rewriteRule "(.*)<realnamingcontext>$" "%1<virtualnamingcontext>" ":"
+rewriteContext searchAttrDN alias searchResult
+rewriteContext matchedDN alias searchResult
+
# Everything defined here goes into the `default' context.
# This rule changes the naming context of anything sent
# to `dc=home,dc=net' to `dc=OpenLDAP, dc=org'
.\"
.\" # Finally, in a bind, if one uses a `uid=username' DN,
.\" # it is rewritten in `cn=name surname' if possible.
-.\" rewriteContext bindDn
+.\" rewriteContext bindDN
.\" rewriteRule ".*" "%{>addBlanks(%{>uid2Gecos(%0)})}" ":"
.\"
-# Rewrite the search base according to `default' rules.
+# Rewrite the search base according to `default' rules.
rewriteContext searchBase alias default
# Search results with OpenLDAP DN are rewritten back with
# to real naming contexts, we also need to rewrite
# regular DNs, because the definition of a bindDn
# rewrite context overrides the default definition.
-rewriteContext bindDn
+rewriteContext bindDN
rewriteRule "^mail=[^,]+@[^,]+$" "%{attr2dn(%0)}" ":@I"
# This is a rather sophisticated example. It massages a
# track of the bind DN of the incoming request, which is
# stored in a variable called `binddn' with session scope,
# and left in place to allow regular binding:
-rewriteContext bindDn
+rewriteContext bindDN
rewriteRule ".+" "%{&&binddn(%0)}%0" ":"
# A search filter containing `uid=' is rewritten only
projects / openldap / blobdiff