From: Pierangelo Masarati Date: Sun, 18 Jul 2004 21:45:20 +0000 (+0000) Subject: document rwm overlay X-Git-Tag: OPENDLAP_REL_ENG_2_2_MP~48 X-Git-Url: https://git.sur5r.net/?a=commitdiff_plain;h=fa694f0c3c339b53cd124384b6d904232917e945;p=openldap document rwm overlay --- diff --git a/doc/man/man5/slapo-rwm.5 b/doc/man/man5/slapo-rwm.5 new file mode 100644 index 0000000000..64a0ff533a --- /dev/null +++ b/doc/man/man5/slapo-rwm.5 @@ -0,0 +1,499 @@ +.TH SLAPO-RWM 5 "RELEASEDATE" "OpenLDAP LDVERSION" +.\" Copyright 1998-2004 The OpenLDAP Foundation, All Rights Reserved. +.\" Copying restrictions apply. See the COPYRIGHT file. +.\" Copyright 2004, Pierangelo Masarati, All rights reserved. +.\" $OpenLDAP$ +.\" +.\" Portions of this document should probably be moved to slapd-ldap(5) +.\" and maybe manual pages for librewrite. +.\" +.SH NAME +slapo-rwm \- rewrite/remap overlay +.SH SYNOPSIS +ETCDIR/slapd.conf +.SH DESCRIPTION +The +.B rwm +overlay to +.BR slapd (8) +performs basic DN/data rewrite and objectClass/attributeType mapping. +Its usage is mostly intended to provide virtual views of existing data +either remotely, in conjunction with the proxy backend described in +.BR slapd-ldap (5), +or locally, in conjunction with the relay backend described in +.BR slapd-relay (5). +.SH MAPPING +An important feature of the +.B rwm +overlay is the capability to map objectClasses and attributeTypes +from the local set (or a subset of it) to a foreign set, and vice versa. +This is accomplished by means of the +.B rwm-map +directive. +.TP +.B rwm-map "{attribute | objectclass} [ | *] { | *}" +Map attributeTypes and objectClasses from the foreign server to +different values on the local slapd. +The reason is that some attributes might not be part of the local +slapd's schema, some attribute names might be different but serve the +same purpose, etc. +If local or foreign name is `*', the name is preserved. +If local name is omitted, the foreign name is removed. +Unmapped names are preseved if both local and foreign name are `*', +and removed if local name is omitted and foreign name is `*'. +.LP +The local +.I objectClasses +and +.I attributeTypes +must be defined in the local schema; the foreign ones do not have to. +Note, however, that the decision whether to rewrite or not attributeTypes +with +.IR "distinguishedName syntax" , +requires the knowledge of the attributeType syntax. +See the REWRITING section for details. +.SH SUFFIX MASSAGING +A basic feature of the +.B rwm +overlay is the capability to perform suffix massaging between a virtual +and a real naming context by means of the +.B rwm-suffixmassage +directive. +.TP +.B rwm-suffixmassage "" "" +Shortcut to implement naming context rewriting; the trailing part +of the DN is rewritten from the virtual to the real naming context +in the bindDN, searchBase, searchFilterAttrDN, compareDN, compareAttrDN, +addDN, addAttrDN, modifyDN, modifyAttrDN, modrDN, newSuperiorDN, +deleteDN, exopPasswdDN, and from the real to the virtual naming context +in the searchResult, searchAttrDN and matchedDN rewrite contexts. +By default no rewriting occurs for the searchFilter rewrite context. +This directive implies setting the +.B rwm-rewriteEngine +to +.BR ON . +.LP +See the REWRITING section for details. +.SH REWRITING +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; 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 +.RS +.nf + ::= [...] + ::= [] +.fi +.RE +.LP +The underlying concept is to build a lightweight rewrite module +for the slapd server (initially dedicated to the LDAP backend): +.LP +.SH Passes +An incoming string is matched agains a set of +.IR rewriteRules . +Rules are made of a +.IR "regex match pattern" , +a +.I "substitution pattern" +and a set of actions, described by a set of +.IR "optional flags" . +In case of match, 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. +Each rule is executed recursively, unless altered by specific action +flags; see "Action Flags" for details. +A default limit on the recursion level is set, and can be altered +by the +.B rwm-rewriteMaxPasses +directive, as detailed in the "Additional Configuration Syntax" section. +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 behavior, while the latter +alter the actions that are taken after substitution. +.SH "Pattern Matching Flags" +.TP +.B `C' +honors case in matching (default is case insensitive) +.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 `:' +apply the rule once only (default is recursive) +.TP +.B `@' +stop applying rules in case of match; the current rule is still applied +recursively; combine with `:' to apply the current rule only once +and then stop. +.TP +.B `#' +stop current operation if the rule matches, and issue an `unwilling to +perform' error. +.TP +.B `G{n}' +jump +.B n +rules back and forth (watch for loops!). +Note that `G{1}' is implicit in every rule. +.TP +.B `I' +ignores errors in rule; this means, in case of error, e.g. issued by a +map, the error is treated as a missed match. +The `unwilling to perform' is not overridden. +.TP +.B `U{n}' +uses +.B +n +as return code if the rule matches; the flag does not alter the recursive +behavior of the rule, so, to have it performed only once, it must be used +in combination with `:', e.g. +.B `:U{16}' +returns the value `16' after exactly one execution of the rule, if the +pattern matches. +As a consequence, its behavior is equivalent to `@', with the return +code set to +.BR n ; +or, in other words, `@' is equivalent to `U{0}'. +By convention, the freely available codes are above 16 included; +the others are reserved. +.LP +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 +More flags (mainly Action Flags) will be added as needed. +.SH "Pattern Matching" +See +.BR regex (7). +.SH "Substitution Pattern Syntax" +Everything starting with `$' requires substitution; +.LP +the only obvious exception is `$$', which is left as is; +.LP +the basic substitution is `$', where `' is a digit; +0 means the whole string, while 1-9 is a submatch, as discussed in +.BR regex (7); +.LP +a `$' followed by a `{' invokes an advanced substitution. +The pattern is: +.LP +.RS +`$' `{' [ ] `(' `)' `}' +.RE +.LP +where must be a legal name for the map, i.e. +.LP +.RS +.nf + ::= [a-z][a-z0-9]* (case insensitive) + ::= `>' `|' `&' `&&' `*' `**' `$' +.fi +.RE +.LP +and must be a legal substitution +pattern, with no limits on the nesting level. +.LP +The operators are: +.TP +.B > +sub-context invocation; must be a legal, already defined +rewrite context name +.TP +.B | +external command invocation; must refer to a legal, already +defined command name (NOT IMPLEMENTED YET) +.TP +.B & +variable assignment; defines a variable in the running +operation structure which can be dereferenced later; operator +.B & +assigns a variable in the rewrite context scope; operator +.B && +assigns a variable that scopes the entire session, e.g. its value +can be derefenced later by other rewrite contexts +.TP +.B * +variable dereferencing; must refer to a variable that is +defined and assigned for the running operation; operator +.B * +dereferences a variable scoping the rewrite context; operator +.B ** +dereferences a variable scoping the whole session, e.g. the value +is passed across rewrite contexts +.TP +.B $ +parameter dereferencing; must refer to an existing parameter; +the idea is to make some run-time parameters set by the system +available to the rewrite engine, as the client host name, the bind DN +if any, constant parameters initialized at config time, and so on; +no parameter is currently set by either +.B back\-ldap +or +.BR back\-meta , +but constant parameters can be defined in the configuration file +by using the +.B rewriteParam +directive. +.LP +Substitution escaping has been delegated to the `$' symbol, +which is used instead of `\e' in string substitution patterns +because `\e' is already escaped by slapd's low level parsing routines; +as a consequence, +.BR regex (7) +escaping requires two `\e' symbols, e.g. `\fB.*\e.foo\e.bar\fP' must +be written as `\fB.*\e\e.foo\e\e.bar\fP'. +.\" +.\" The symbol can be altered at will by redefining the related macro in +.\" "rewrite-int.h". +.\" +.SH "Rewrite Context" +A rewrite context is a set of rules which are applied in sequence. +The basic idea is to have an application initialize a rewrite +engine (think of Apache's mod_rewrite ...) with a set of rewrite +contexts; when string rewriting is required, one invokes the +appropriate rewrite context with the input string and obtains the +newly rewritten one if no errors occur. +.LP +Each basic server operation is associated to a rewrite context; +they are divided in two main groups: client \-> server and +server \-> client rewriting. +.LP +client -> server: +.LP +.RS +.nf +(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 +server -> client: +.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) +.fi +.RE +.LP +.SH "Basic Configuration Syntax" +All rewrite/remap directives start with the prefix +.BR rwm- ; +for backwards compatibility with the historical +.BR slapd-ldap (5) +and +.BR slapd-meta (5) +builtin rewrite/remap capabilities, the prefix may be omitted, +but this practice is strongly discouraged. +.TP +.B rwm-rewriteEngine { on | off } +If `on', the requested rewriting is performed; if `off', no +rewriting takes place (an easy way to stop rewriting without +altering too much the configuration file). +.TP +.B rwm-rewriteContext "[ alias ]" + is the name that identifies the context, i.e. the name +used by the application to refer to the set of rules it contains. +It is used also to reference sub contexts in string rewriting. +A context may aliase another one. +In this case the alias context contains no rule, and any reference to +it will result in accessing the aliased one. +.TP +.B rwm-rewriteRule "" "" "[ ]" +Determines how a string can be rewritten if a pattern is matched. +Examples are reported below. +.SH "Additional Configuration Syntax" +.TP +.B rwm-rewriteMap "" "" "[ ]" +Allows to define a map that transforms substring rewriting into +something else. +The map is referenced inside the substitution pattern of a rule. +.TP +.B rwm-rewriteParam +Sets a value with global scope, that can be dereferenced by the +command `${$paramName}'. +.TP +.B rwm-rewriteMaxPasses [] +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 +rwm-rewriteEngine on + +# the rules the "suffixmassage" directive implies +rwm-rewriteEngine on +# all dataflow from client to server referring to DNs +rwm-rewriteContext default +rwm-rewriteRule "(.*)$" "$1" ":" +# empty filter rule +rwm-rewriteContext searchFilter +# all dataflow from server to client +rwm-rewriteContext searchResult +rwm-rewriteRule "(.*)$" "$1" ":" +rwm-rewriteContext searchAttrDN alias searchResult +rwm-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' + +rwm-rewriteRule "(.*)dc=home,[ ]?dc=net$" + "$1dc=OpenLDAP, dc=org" ":" + +# since a pretty/normalized DN does not include spaces +# after rdn separators, e.g. `,', this rule suffices: + +rwm-rewriteRule "(.*)dc=home,dc=net$" + "$1dc=OpenLDAP,dc=org" ":" + +# Start a new context (ends input of the previous one). +# This rule adds blanks between DN parts if not present. +rwm-rewriteContext addBlanks +rwm-rewriteRule "(.*),([^ ].*)" "$1, $2" + +# This one eats blanks +rwm-rewriteContext eatBlanks +rwm-rewriteRule "(.*),[ ](.*)" "$1,$2" + +# Here control goes back to the default rewrite +# context; rules are appended to the existing ones. +# anything that gets here is piped into rule `addBlanks' +rwm-rewriteContext default +rwm-rewriteRule ".*" "${>addBlanks($0)}" ":" + +.\" # Anything with `uid=username' is looked up in +.\" # /etc/passwd for gecos (I know it's nearly useless, +.\" # but it is there just as a guideline to implementing +.\" # custom maps). +.\" # Note the `I' flag that leaves `uid=username' in place +.\" # if `username' does not have a valid account, and the +.\" # `:' that forces the rule to be processed exactly once. +.\" rwm-rewriteContext uid2Gecos +.\" rwm-rewriteRule "(.*)uid=([a-z0-9]+),(.+)" +.\" "$1cn=$2{xpasswd},$3" "I:" +.\" +.\" # Finally, in a bind, if one uses a `uid=username' DN, +.\" # it is rewritten in `cn=name surname' if possible. +.\" rwm-rewriteContext bindDN +.\" rwm-rewriteRule ".*" "${>addBlanks(${>uid2Gecos($0)})}" ":" +.\" +# Rewrite the search base according to `default' rules. +rwm-rewriteContext searchBase alias default + +# Search results with OpenLDAP DN are rewritten back with +# `dc=home,dc=net' naming context, with spaces eaten. +rwm-rewriteContext searchResult +rwm-rewriteRule "(.*[^ ],)?[ ]?dc=OpenLDAP,[ ]?dc=org$" + "${>eatBlanks($1)}dc=home,dc=net" ":" + +# Bind with email instead of full DN: we first need +# an ldap map that turns attributes into a DN (the +# argument used when invoking the map is appended to +# the URI and acts as the filter portion) +rwm-rewriteMap ldap attr2dn "ldap://host/dc=my,dc=org?dn?sub" + +# Then we need to detect DN made up of a single email, +# e.g. `mail=someone@example.com'; note that the rule +# in case of match stops rewriting; in case of error, +# it is ignored. In case we are mapping virtual +# to real naming contexts, we also need to rewrite +# regular DNs, because the definition of a bindDn +# rewrite context overrides the default definition. +rwm-rewriteContext bindDN +rwm-rewriteRule "^mail=[^,]+@[^,]+$" "${attr2dn($0)}" ":@I" + +# This is a rather sophisticated example. It massages a +# search filter in case who performs the search has +# administrative privileges. First we need to keep +# 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: +rwm-rewriteContext bindDN +rwm-rewriteRule ".+" "${&&binddn($0)}$0" ":" + +# A search filter containing `uid=' is rewritten only +# if an appropriate DN is bound. +# To do this, in the first rule the bound DN is +# dereferenced, while the filter is decomposed in a +# prefix, in the value of the `uid=' AVA, and +# in a suffix. A tag `<>' is appended to the DN. +# If the DN refers to an entry in the `ou=admin' subtree, +# the filter is rewritten OR-ing the `uid=' with +# `cn='; otherwise it is left as is. This could be +# useful, for instance, to allow apache's auth_ldap-1.4 +# module to authenticate users with both `uid' and +# `cn', but only if the request comes from a possible +# `cn=Web auth,ou=admin,dc=home,dc=net' user. +rwm-rewriteContext searchFilter +rwm-rewriteRule "(.*\e\e()uid=([a-z0-9_]+)(\e\e).*)" + "${**binddn}<>${&prefix($1)}${&arg($2)}${&suffix($3)}" + ":I" +rwm-rewriteRule "^[^,]+,ou=admin,dc=home,dc=net$" + "${*prefix}|(uid=${*arg})(cn=${*arg})${*suffix}" ":@I" +rwm-rewriteRule ".*<>$" "${*prefix}uid=${*arg}${*suffix}" ":" + +# This example shows how to strip unwanted DN-valued +# attribute values from a search result; the first rule +# matches DN values below "ou=People,dc=example,dc=com"; +# in case of match the rewriting exits successfully. +# The second rule matches everything else and causes +# the value to be rejected. +rwm-rewriteContext searchResult +rwm-rewriteRule ".*,ou=People,dc=example,dc=com$" "$0" ":@" +rwm-rewriteRule ".*" "" "#" +.fi +.SH FILES +.TP +ETCDIR/slapd.conf +default slapd configuration file +.SH SEE ALSO +.BR slapd.conf (5), +.BR slapd\-ldap (5), +.BR slapd\-meta (5), +.BR slapd\-relay (5), +.BR slapd (8), +.BR regex (7). +.SH AUTHOR +Pierangelo Masarati; based on back-ldap rewrite/remap features +by Howard Chu, Pierangelo Masarati.