]> git.sur5r.net Git - openldap/blob - doc/man/man5/slapd-relay.5
Sync with HEAD
[openldap] / 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).