1Relay backend sets up a relay virtual database that allows
2to access other databases in the same instance of slapd
3through different naming contexts and remapping attribute
4values.
5
6The DN rewrite, filter rewrite and attributeType/objectClass
7mapping is done by means of the rewrite-remap overlay.
8
9The database containing the real naming context can be
10explicitly selected by means of the "relay" directive,
11which must contain the naming context of the target
12database.  This also causes the rewrite-remap overlay
13to be automatically instantiated.  If the optional keyword
14"massage" is present, the rewrite-remap overlay is
15automatically configured to map the virtual to the real
16naming context and vice-versa.
17
18Otherwise, the rewrite-remap overlay must be explicitly
19instantiated, by using the "overlay" directive, as
20illustrated below.  This allows much more freedom in target
21database selection and DN rewriting.
22
23If the "relay" directive is not present, the backend is
24not bound to a single target database; on the contrary,
25the target database is selected on a per-operation basis.
26
27This allows, for instance, to relay one database for
28authentication and anotheir for search/modify, or allows
29to use one target for persons and another for groups
30and so on.
31
32To summarize: the "relay" directive:
33- explicitly bounds the database to a single database
34  holding the real naming context;
35- automatically instantiates the rewrite-remap overlay;
36- automatically configures the naming context massaging
37  if the optional "massage" keyword is added
38
39If the "relay" directive is not used, the rewrite-remap
40overlay must be explicitly instantiated and the massaging
41must be configured, either by using the "suffixmassage"
42directive, or by issuing more sophisticate rewrite
43instructions.
44
45AttributeType/objectClass mapping must be explicitly
46required.
47
48Note that the rewrite-remap overlay is not complete nor
49production- ready yet.
50Examples are given of all the suggested usages.
51
52# automatically massage from virtual to real naming context
53database	relay
54suffix		"dc=virtual,dc=naming,dc=context"
55relay		"dc=real,dc=naming,dc=context" massage
56
57# explicitly massage (same as above)
58database	relay
59suffix		"dc=virtual,dc=naming,dc=context"
60relay		"dc=real,dc=naming,dc=context"
61suffixmassage	"dc=virtual,dc=naming,dc=context" \
62			"dc=real,dc=naming,dc=context"
63
64# explicitly massage (same as above, but dynamic backend resolution)
65database	relay
66suffix		"dc=virtual,dc=naming,dc=context"
67overlay		rewrite-remap
68suffixmassage	"dc=virtual,dc=naming,dc=context" \
69			"dc=real,dc=naming,dc=context"
70
71# old fashioned suffixalias, applied also to DN-valued attributes
72# from virtual to real naming context, but not the reverse...
73database	relay
74suffix		"dc=virtual,dc=naming,dc=context"
75relay		"dc=real,dc=naming,dc=context"
76rewriteContext	default
77rewriteRule	"(.*)dc=virtual,dc=naming,dc=context$" \
78			"$1dc=real,dc=naming,dc=context"
79rewriteContext	searchFilter
80rewriteContext	searchResult
81rewriteContext	searchResultAttrDN
82rewriteContext	matchedDN
83
84