DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH PRINT BOOK
 

slapo-rwm(5)




SLAPO-RWM(5)              FILE FORMATS               SLAPO-RWM(5)


NAME

     slapo-rwm - rewrite/remap overlay


SYNOPSIS

     /etc/openldap/slapd.conf


DESCRIPTION

     The rwm overlay to 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
     slapd-ldap(5), or locally, in  conjunction  with  the  relay
     backend described in slapd-relay(5).

     This overlay is experimental.


MAPPING

     An important feature of the 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 rwm-map directive.


name> | *}

     rwm-
          map {attribute | objectclass} [<local name>  |  *]  {<foreign
          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 preserved if both local and foreign name are
          `*', and removed if local name is omitted  and  foreign
          name is `*'.

     The local objectClasses and attributeTypes must  be  defined
     in  the  local  schema; the foreign ones do not have to, but
     users are encouraged to explicitly define the remote  attri-
     buteTypes  and the objectClasses they intend to map.  All in
     all, when remapping a remote server  via  back-ldap  (slapd-
     ldap(5))  or  back-meta (slapd-meta(5)) their definition can
     be easily obtained by querying the subschemaSubentry of  the
     remote server; the problem should not exist when remapping a
     local database.  Note, however, that the decision whether to
     rewrite or not attributeTypes with distinguishedName syntax,
     requires the knowledge of the attributeType syntax.  See the
     REWRITING section for details.

     Note that when mapping DN-valued attributes  from  local  to
     remote,  first  the  DN  is rewritten, and then the attribu-
     teType is mapped; while mapping from remote to local,  first

OpenLDAP 2.3.27      Last change: 2006/08/19                    1

SLAPO-RWM(5)              FILE FORMATS               SLAPO-RWM(5)

     the  attributeType  is mapped, and then the DN is rewritten.
     As such, it is important that  the  local  attributeType  is
     appropriately defined as using the distinguishedName syntax.
     Also, note that there are DN-related syntaxes (i.e. compound
     types  with  a  portion  that is DN-valued), like nameAndOp-
     tionalUID, whose values are currently not rewritten.


SUFFIX MASSAGING

     A basic feature of the rwm overlay is the capability to per-
     form  suffix  massaging  between a virtual and a real naming
     context by means of the rwm-suffixmassage directive.


text>

     rwm-
          suffixmassage [<virtual naming context>]  <real  naming  con-
          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,  searchDN,
          searchFilterAttrDN,  compareDN,  compareAttrDN,  addDN,
          addAttrDN,  modifyDN,  modifyAttrDN,   modrDN,   newSu-
          periorDN,  deleteDN, exopPasswdDN, and from the real to
          the virtual naming context in the searchEntryDN,  sear-
          chAttrDN and matchedDN rewrite contexts.  By default no
          rewriting occurs  for  the  searchFilter  and  for  the
          referralAttrDN  and referralDN rewrite contexts.  If no
          <virtual naming context> is given, the first suffix  of
          the   database   is   used;   this  requires  the  rwm-
          suffixmassage directive be defined after  the  database
          suffix   directive.   The  rwm-suffixmassage  directive
          automatically sets the rwm-rewriteEngine to ON.

     See the REWRITING section for details.


REWRITING

     A string is rewritten according to a set of rules, called  a
     `rewrite   context'.    The   rules   are   based  on  POSIX
     (''extended'') regular expressions 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.

          <rewrite context> ::= <rewrite rule> [...]
          <rewrite rule> ::= <pattern> <action> [<flags>]

     The underlying concept is to  build  a  lightweight  rewrite
     module for the slapd server (initially dedicated to the LDAP
     backend):


Passes

     An incoming string is matched against a set of rewriteRules.
     Rules  are  made  of  a  regex match pattern, a substitution

OpenLDAP 2.3.27      Last change: 2006/08/19                    2

SLAPO-RWM(5)              FILE FORMATS               SLAPO-RWM(5)

     pattern and a set of actions, described by a set of 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 recur-
     sively, 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 rwm-rewriteMaxPasses
     directive, as detailed in the "Additional Configuration Syn-
     tax"  section.   The substitution pattern allows map resolu-
     tion 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.


Pattern Matching Flags

     `C'  honors case in matching (default is case insensitive)

     `R'  use POSIX ''basic''  regular  expressions  (default  is
          ''extended'')

     `M{n}'
          allow no more than 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.


Action Flags

     `:'  apply the rule once only (default is recursive)

     `@'  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.

     `#'  stop current operation if the rule matches,  and  issue
          an `unwilling to perform' error.

     `G{n}'
          jump n rules back and forth (watch for  loops!).   Note
          that `G{1}' is implicit in every rule.

     `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.

     `U{n}'
          uses 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 com-
          bination  with  `:',  e.g.   `:U{32}' returns the value
          `32'  (indicating  noSuchObject)  after   exactly   one

OpenLDAP 2.3.27      Last change: 2006/08/19                    3

SLAPO-RWM(5)              FILE FORMATS               SLAPO-RWM(5)

          execution  of  the  rule, if the pattern matches.  As a
          consequence, its behavior is equivalent  to  `@',  with
          the  return  code  set to n; or, in other words, `@' is
          equivalent to `U{0}'.   Positive  errors  are  allowed,
          indicating the related LDAP error codes as specified in
          draft-ietf-ldapbis-protocol.

     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.

     More flags (mainly Action Flags) will be added as needed.


Pattern Matching

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


Substitution Pattern Syntax

     Everything starting with `$' requires substitution;

     the only obvious exception is `$$', which is turned  into  a
     single `$';

     the basic substitution is `$<d>', where `<d>' is a digit;  0
     means  the  whole  string,  while 1-9 is a submatch, as dis-
     cussed in regex(7) and/or re_format(7).

     a `$' followed by a `{' invokes  an  advanced  substitution.
     The pattern is:

          `$' `{' [ <operator> ] <name>  `('  <substitution>  `)'
          `}'

     where <name> must be a legal name for the map, i.e.

          <name> ::= [a-z][a-z0-9]* (case insensitive)
          <operator> ::= `>' `|' `&' `&&' `*' `**' `$'

     and <substitution> must be  a  legal  substitution  pattern,
     with no limits on the nesting level.

     The operators are:

     >    sub-context invocation; <name> must be a legal, already
          defined rewrite context name

     |    external command invocation; <name>  must  refer  to  a
          legal,  already  defined  command name (NOT IMPLEMENTED
          YET)

     &    variable assignment; <name> defines a variable  in  the

OpenLDAP 2.3.27      Last change: 2006/08/19                    4

SLAPO-RWM(5)              FILE FORMATS               SLAPO-RWM(5)

          running  operation  structure which can be dereferenced
          later; operator & assigns a  variable  in  the  rewrite
          context  scope;  operator  &&  assigns  a variable that
          scopes the  entire  session,  e.g.  its  value  can  be
          dereferenced later by other rewrite contexts

     *    variable dereferencing; <name> must refer to a variable
          that is defined and assigned for the running operation;
          operator * dereferences a variable scoping the  rewrite
          context;  operator  **  dereferences a variable scoping
          the whole session, e.g.  the  value  is  passed  across
          rewrite contexts

     $    parameter dereferencing; <name> must refer to an exist-
          ing parameter; the idea is to make some run-time param-
          eters 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 back-ldap
          or back-meta, but constant parameters can be defined in
          the configuration file by using the rewriteParam direc-
          tive.

     Substitution escaping has been delegated to the `$'  symbol,
     which is used instead of `\' in string substitution patterns
     because `\' is already escaped by slapd's low level  parsing
     routines;  as a consequence, regex escaping requires two `\'
     symbols,   e.g.   `.*\.foo\.bar'   must   be   written    as
     `.*\\.foo\\.bar'.


Rewrite Context

     A rewrite context is a set of rules  which  are  applied  in
     sequence.  The basic idea is to have an application initial-
     ize 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.

     Each basic server operation is associated to a rewrite  con-
     text;  they are divided in two main groups: client -> server
     and server -> client rewriting.

     client -> server:

          (default)            if defined and no specific context
                               is available
          bindDN               bind
          searchDN             search
          searchFilter         search
          searchFilterAttrDN   search
          compareDN            compare

OpenLDAP 2.3.27      Last change: 2006/08/19                    5

SLAPO-RWM(5)              FILE FORMATS               SLAPO-RWM(5)

          compareAttrDN        compare AVA
          addDN                add
          addAttrDN            add AVA (DN portion of "ref" excluded)
          modifyDN             modify
          modifyAttrDN         modify AVA (DN portion of "ref" excluded)
          referralAttrDN       add/modify DN portion of referrals
                               (default to none)
          modrDN               modrdn
          newSuperiorDN        modrdn
          deleteDN             delete
          exopPasswdDN         password modify extended operation DN

     server -> client:

          searchEntryDN        search (only if defined; no default;
                               acts on DN of search entries)
          searchAttrDN         search AVA (only if defined; defaults
                               to searchEntryDN; acts on DN-syntax
                               attributes of search results)
          matchedDN            all ops (only if applicable; defaults
                               to searchEntryDN)
          referralDN           all ops (only if applicable; defaults
                               to none)


Basic Configuration Syntax

     All rewrite/remap directives start with the prefix rwm-; for
     backwards  compatibility  with  the historical slapd-ldap(5)
     and slapd-meta(5) builtin  rewrite/remap  capabilities,  the
     prefix  may  be  omitted,  but  this  practice  is  strongly
     discouraged.

     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).


]

     rwm-
          rewriteContext <context name> [ alias <aliased context  name>
          <Context name> 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 alias
          another one.  In this case the alias  context  contains
          no rule, and any reference to it will result in access-
          ing the aliased one.


]

     rwm-
          rewriteRule <regex match pattern>  <substitution  pattern>  [
          Determines how a string can be rewritten if  a  pattern

OpenLDAP 2.3.27      Last change: 2006/08/19                    6

SLAPO-RWM(5)              FILE FORMATS               SLAPO-RWM(5)

          is matched.  Examples are reported below.


Additional Configuration Syntax

     rwm-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.

     rwm-rewriteParam <param name> <param value>
          Sets a value with global scope, that  can  be  derefer-
          enced by the command `${$paramName}'.

     rwm-rewriteMaxPasses <number of passes> [<number of
          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.


REWRITE CONFIGURATION EXAMPLES

     # 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 "(.+,)?<virtualnamingcontext>$" "$1<realnamingcontext>" ":"
     # empty filter rule
     rwm-rewriteContext searchFilter
     # all dataflow from server to client
     rwm-rewriteContext searchEntryDN
     rwm-rewriteRule "(.+,)?<realnamingcontext>$" "$1<virtualnamingcontext>" ":"
     rwm-rewriteContext searchAttrDN alias searchEntryDN
     rwm-rewriteContext matchedDN alias searchEntryDN
     # misc empty rules
     rwm-rewriteContext referralAttrDN
     rwm-rewriteContext referralDN

     # 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:

OpenLDAP 2.3.27      Last change: 2006/08/19                    7

SLAPO-RWM(5)              FILE FORMATS               SLAPO-RWM(5)

     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)}" ":"

     # Rewrite the search base according to `default' rules.
     rwm-rewriteContext  searchDN alias default

     # Search results with OpenLDAP DN are rewritten back with
     # `dc=home,dc=net' naming context, with spaces eaten.
     rwm-rewriteContext  searchEntryDN
     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" ":"

OpenLDAP 2.3.27      Last change: 2006/08/19                    8

SLAPO-RWM(5)              FILE FORMATS               SLAPO-RWM(5)

     # 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=<arg>' 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=<arg>' with
     # `cn=<arg>'; 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 "(.*\\()uid=([a-z0-9_]+)(\\).*)"
       "${**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 searchEntryDN
     rwm-rewriteRule ".+,ou=People,dc=example,dc=com$" "$0" ":@"
     rwm-rewriteRule ".*" "" "#"


MAPPING EXAMPLES

     The following directives map the object class `groupOfNames'
     to  the  object class `groupOfUniqueNames' and the attribute
     type `member' to the attribute type `uniqueMember':

          map objectclass groupOfNames groupOfUniqueNames
          map attribute uniqueMember member

     This presents a  limited  attribute  set  from  the  foreign
     server:

          map attribute cn *
          map attribute sn *
          map attribute manager *
          map attribute description *
          map attribute *

     These lines map cn, sn, manager, and  description  to  them-
     selves,  and  any  other  attribute  gets "removed" from the
     object before it is sent to the client (or sent  up  to  the
     LDAP  server).   This is obviously a simplistic example, but

OpenLDAP 2.3.27      Last change: 2006/08/19                    9

SLAPO-RWM(5)              FILE FORMATS               SLAPO-RWM(5)

     you get the point.


FILES

     /etc/openldap/slapd.conf
          default slapd configuration file


SEE ALSO

     slapd.conf(5), slapd-ldap(5), slapd-meta(5), slapd-relay(5),
     slapd(8), regex(7), re_format(7).


AUTHOR

     Pierangelo  Masarati;  based  on   back-ldap   rewrite/remap
     features by Howard Chu, Pierangelo Masarati.

OpenLDAP 2.3.27      Last change: 2006/08/19                   10


Man(1) output converted with man2html