git.sur5r.net Git - openldap/blob - doc/man/man5/slapd-relay.5

   1 .TH SLAPD-RELAY 5 "RELEASEDATE" "OpenLDAP LDVERSION"
   2 .SH NAME
   3 slapd-relay \- relay backend to slapd
   4 .SH SYNOPSIS
   5 ETCDIR/slapd.conf
   6 .SH DESCRIPTION
   7 The primary purpose of this
   8 .BR slapd (8)
   9 backend is to map a naming context defined in a database
  10 running in the same
  11 .BR slapd (8)
  12 instance into a virtual naming context, with attributeType
  13 and objectClass manipulation, if required.
  14 It requires the
  15 .B rwm
  16 .BR overlay .
  17 .LP
  18 This backend and the above mentioned overlay are experimental.
  19 .SH CONFIGURATION
  20 The following
  21 .B slapd.conf
  22 directives apply to the relay backend database.
  23 That is, they must follow a "database relay" line and come before any
  24 subsequent "backend" or "database" lines.
  25 Other database options are described in the
  26 .BR slapd.conf (5)
  27 manual page; only the
  28 .B suffix
  29 directive is required by the
  30 .I relay
  31 backend.
  32 .TP
  33 .B relay <real naming context> [massage]
  34 The naming context of the database that is presented
  35 under a virtual naming context.
  36 The presence of this directive implies that one specific database,
  37 i.e. the one serving the
  38 .BR "real naming context" ,
  39 will be presented under a virtual naming context.
  40 This directive automatically instantiates the
  41 .IR "rwm overlay" .
  42 If the optional
  43 .B massage
  44 keyword is present, the suffix massaging is automatically
  45 configured as well; otherwise, specific massaging instructions
  46 are required by means of the
  47 .I rewrite
  48 directives described in
  49 .BR slapo-rwm (5).
  50
  51 .SH ACCESS RULES
  52 One important issue is that access rules are based on the identity
  53 that issued the operation.
  54 After massaging from the virtual to the real naming context, the
  55 frontend sees the operation as performed by the identity in the
  56 real naming context.
  57 Moreover, since
  58 .B back-relay
  59 bypasses the real database frontend operations by short-circuiting
  60 operations thru the internal backend API, the original database
  61 access rules do not apply but in selected cases, i.e. when the
  62 backend itself applies access control.
  63 As a consequence, the instances of the relay database must provide
  64 own access rules that are consistent with those of the original
  65 database, possibly adding further specific restrictions.
  66 So, access rules in the
  67 .B relay
  68 database must refer to identities in the real naming context.
  69 Examples are reported in the EXAMPLES section.
  70
  71 .SH SCENARIOS
  72 .LP
  73 If no
  74 .B relay
  75 directive is given, the
  76 .I relay
  77 database does not refer to any specific database, but the most
  78 appropriate one is looked-up after rewriting the request DN
  79 for the operation that is being handled.
  80 .LP
  81 This allows to write carefully crafted rewrite rules that
  82 cause some of the requests to be directed to one database, and
  83 some to another; e.g., authentication can be mapped to one
  84 database, and searches to another, or different target databases
  85 can be selected based on the DN of the request, and so.
  86 .LP
  87 Another possibility is to map the same operation to different
  88 databases based on details of the virtual naming context,
  89 e.g. groups on one database and persons on another.
  90 .LP
  91 .SH Caveats
  92 The
  93 .B rwm overlay
  94 is experimental.
  95 .LP
  96 .SH EXAMPLES
  97 To implement a plain virtual naming context mapping
  98 that refers to a single database, use
  99 .LP
 100 .nf
 101   database        relay
 102   suffix          "dc=virtual,dc=naming,dc=context"
 103   relay           "dc=real,dc=naming,dc=context" massage
 104 .fi
 105 .LP
 106 To implement a plain virtual naming context mapping
 107 that looks up the real naming context for each operation, use
 108 .LP
 109 .nf
 110   database        relay
 111   suffix          "dc=virtual,dc=naming,dc=context"
 112   overlay         rwm
 113   suffixmassage   "dc=real,dc=naming,dc=context"
 114 .fi
 115 .LP
 116 This is useful, for instance, to relay different databases that
 117 share the terminal portion of the naming context (the one that
 118 is rewritten).
 119 .LP
 120 To implement the old-fashioned suffixalias, e.g. mapping
 121 the virtual to the real naming context, but not the results
 122 back from the real to the virtual naming context, use
 123 .LP
 124 .nf
 125   database        relay
 126   suffix          "dc=virtual,dc=naming,dc=context"
 127   relay           "dc=real,dc=naming,dc=context"
 128   rewriteEngine   on
 129   rewriteContext  default
 130   rewriteRule     "dc=virtual,dc=naming,dc=context"
 131           "dc=real,dc=naming,dc=context" ":@"
 132   rewriteContext  searchFilter
 133   rewriteContext  searchEntryDN
 134   rewriteContext  searchAttrDN
 135   rewriteContext  matchedDN
 136 .fi
 137 .LP
 138 Note that the virtual database is bound to a single real database,
 139 so the
 140 .B rwm overlay
 141 is automatically instantiated, but the rewrite rules
 142 are written explicitly to map all the virtual to real
 143 naming context data flow, but none of the real to virtual.
 144 .LP
 145 Access rules:
 146 .LP
 147 .nf
 148   database        bdb
 149   suffix          "dc=example,dc=com"
 150   # skip...
 151   access to dn.subtree="dc=example,dc=com"
 152           by dn.exact="cn=Supervisor,dc=example,dc=com" write
 153           by * read
 154
 155   database        relay
 156   suffix          "o=Example,c=US"
 157   relay           "dc=example,dc=com" massage
 158   # skip ...
 159   access to dn.subtree="o=Example,c=US"
 160           by dn.exact="cn=Supervisor,dc=example,dc=com" write
 161           by dn.exact="cn=Relay Supervisor,dc=example,dc=com" write
 162           by * read
 163 .fi
 164 .LP
 165 Note that, in both databases, the identities (the
 166 .B <who>
 167 clause) are in the
 168 .BR "real naming context" ,
 169 i.e.
 170 .BR "`dc=example,dc=com'" ,
 171 while the targets (the
 172 .B <what>
 173 clause) are in the
 174 .B real
 175 and in the
 176 .BR "virtual naming context" ,
 177 respectively.
 178 .SH ACCESS CONTROL
 179 The
 180 .B relay
 181 backend does not honor any of the access control semantics described in
 182 .BR slapd.access (5);
 183 all access control is delegated to the relayed database(s).
 184 Only
 185 .B read (=r)
 186 access to the
 187 .B entry
 188 pseudo-attribute and to the other attribute values of the entries
 189 returned by the
 190 .B search
 191 operation is honored, which is performed by the frontend.
 192 .SH FILES
 193 .TP
 194 ETCDIR/slapd.conf
 195 default slapd configuration file
 196 .SH SEE ALSO
 197 .BR slapd.conf (5),
 198 .BR slapo-rwm (5),
 199 .BR slapd (8).