1SLAPD-RELAY(5)                File Formats Manual               SLAPD-RELAY(5)
2
3
4

NAME

6       slapd-relay - relay backend to slapd
7

SYNOPSIS

9       /etc/openldap/slapd.conf
10

DESCRIPTION

12       The primary purpose of this slapd(8) backend is to map a naming context
13       defined in a database running in the same slapd(8) instance into a vir‐
14       tual  naming  context, with attributeType and objectClass manipulation,
15       if required.  It requires the slapo-rwm(5) overlay.
16
17       This backend and the above mentioned overlay are experimental.
18

CONFIGURATION

20       The following slapd.conf directives apply to the  relay  backend  data‐
21       base.   That  is,  they  must  follow  a "database relay" line and come
22       before any subsequent "backend" or "database"  lines.   Other  database
23       options are described in the slapd.conf(5) manual page; only the suffix
24       directive is allowed by the relay backend.
25
26       relay <real naming context>
27              The naming context of the database that  is  presented  under  a
28              virtual  naming context.  The presence of this directive implies
29              that one specific database, i.e. the one serving the real naming
30              context, will be presented under a virtual naming context.
31
32

MASSAGING

34       The relay database does not automatically rewrite the naming context of
35       requests and responses.  For this  purpose,  the  slapo-rwm(5)  overlay
36       must  be  explicitly instantiated, and configured as appropriate.  Usu‐
37       ally, the rwm-suffixmassage directive suffices if only  naming  context
38       rewriting is required.
39
40

ACCESS RULES

42       One important issue is that access rules are based on the identity that
43       issued the operation.  After massaging from the  virtual  to  the  real
44       naming  context,  the  frontend  sees the operation as performed by the
45       identity in  the  real  naming  context.   Moreover,  since  back-relay
46       bypasses  the  real  database  frontend  operations by short-circuiting
47       operations through the internal  backend  API,  the  original  database
48       access  rules do not apply but in selected cases, i.e. when the backend
49       itself applies access control.  As a consequence, the instances of  the
50       relay  database  must provide own access rules that are consistent with
51       those of  the  original  database,  possibly  adding  further  specific
52       restrictions.   So,  access  rules  in the relay database must refer to
53       identities in the real naming context.  Examples are  reported  in  the
54       EXAMPLES section.
55
56

SCENARIOS

58       If  no  relay  directive is given, the relay database does not refer to
59       any specific database, but the most appropriate one is looked-up  after
60       rewriting the request DN for the operation that is being handled.
61
62       This  allows  one  to  write carefully crafted rewrite rules that cause
63       some of the requests to be  directed  to  one  database,  and  some  to
64       another;  e.g.,  authentication  can  be  mapped  to  one database, and
65       searches to another, or different  target  databases  can  be  selected
66       based on the DN of the request, and so.
67
68       Another possibility is to map the same operation to different databases
69       based on details of the virtual naming  context,  e.g.  groups  on  one
70       database and persons on another.
71

EXAMPLES

73       To  implement  a  plain virtual naming context mapping that refers to a
74       single database, use
75
76         database                relay
77         suffix                  "dc=virtual,dc=naming,dc=context"
78         relay                   "dc=real,dc=naming,dc=context"
79         overlay                 rwm
80         rwm-suffixmassage       "dc=real,dc=naming,dc=context"
81
82       To implement a plain virtual naming context mapping that looks  up  the
83       real naming context for each operation, use
84
85         database                relay
86         suffix                  "dc=virtual,dc=naming,dc=context"
87         overlay                 rwm
88         rwm-suffixmassage       "dc=real,dc=naming,dc=context"
89
90       This  is  useful, for instance, to relay different databases that share
91       the terminal portion of the naming context (the one that is rewritten).
92
93       To implement the old-fashioned suffixalias, e.g. mapping the virtual to
94       the  real naming context, but not the results back from the real to the
95       virtual naming context, use
96
97         database                relay
98         suffix                  "dc=virtual,dc=naming,dc=context"
99         relay                   "dc=real,dc=naming,dc=context"
100         overlay                 rwm
101         rwm-rewriteEngine       on
102         rwm-rewriteContext      default
103         rwm-rewriteRule         "dc=virtual,dc=naming,dc=context"
104                                 "dc=real,dc=naming,dc=context" ":@"
105         rwm-rewriteContext      searchFilter
106         rwm-rewriteContext      searchEntryDN
107         rwm-rewriteContext      searchAttrDN
108         rwm-rewriteContext      matchedDN
109
110       Note that the slapo-rwm(5) overlay is  instantiated,  but  the  rewrite
111       rules  are  written  explicitly,  rather than automatically as with the
112       rwm-suffixmassage statement, to map all the virtual to real naming con‐
113       text data flow, but none of the real to virtual.
114
115       Access rules:
116
117         database                bdb
118         suffix                  "dc=example,dc=com"
119         # skip...
120         access to dn.subtree="dc=example,dc=com"
121                 by dn.exact="cn=Supervisor,dc=example,dc=com" write
122                 by * read
123
124         database                relay
125         suffix                  "o=Example,c=US"
126         relay                   "dc=example,dc=com"
127         overlay                 rwm
128         rwm-suffixmassage       "dc=example,dc=com"
129         # skip ...
130         access to dn.subtree="o=Example,c=US"
131                 by dn.exact="cn=Supervisor,dc=example,dc=com" write
132                 by dn.exact="cn=Relay Supervisor,dc=example,dc=com" write
133                 by * read
134
135       Note  that, in both databases, the identities (the <who> clause) are in
136       the real naming context, i.e.  `dc=example,dc=com', while  the  targets
137       (the  <what> clause) are in the real and in the virtual naming context,
138       respectively.
139

ACCESS CONTROL

141       The relay backend does not honor any of the  access  control  semantics
142       described  in  slapd.access(5);  all access control is delegated to the
143       relayed database(s).  Only  read  (=r)  access  to  the  entry  pseudo-
144       attribute  and to the other attribute values of the entries returned by
145       the search operation is honored, which is performed by the frontend.
146

FILES

148       /etc/openldap/slapd.conf
149              default slapd configuration file
150

SEE ALSO

152       slapd.conf(5), slapd-config(5), slapo-rwm(5), slapd(8).
153
154
155
156OpenLDAP 2.4.50                   2020/04/28                    SLAPD-RELAY(5)
Impressum