]> git.sur5r.net Git - openldap/blob - doc/man/man5/slapo-dds.5
ITS#7928 fix syncprov abandon cleanup
[openldap] / doc / man / man5 / slapo-dds.5
1 .TH SLAPO-DDS 5 "RELEASEDATE" "OpenLDAP LDVERSION"
2 .\" Copyright 2005-2014 The OpenLDAP Foundation, All Rights Reserved.
3 .\" Copying restrictions apply.  See the COPYRIGHT file.
4 .\" $OpenLDAP$
5 .SH NAME
6 slapo\-dds \- Dynamic Directory Services overlay to slapd
7 .SH SYNOPSIS
8 ETCDIR/slapd.conf
9 .SH DESCRIPTION
10 The
11 .B dds
12 overlay to
13 .BR slapd (8)
14 implements dynamic objects as per RFC 2589.
15 The name 
16 .B dds
17 stands for
18 Dynamic Directory Services.
19 It allows to define dynamic objects, characterized by the
20 .B dynamicObject
21 objectClass.
22
23 Dynamic objects have a limited lifetime, determined by a time-to-live
24 (TTL) that can be refreshed by means of a specific
25 .B refresh
26 extended operation.
27 This operation allows to set the Client Refresh Period (CRP),
28 namely the period between refreshes that is required to preserve the
29 dynamic object from expiration.
30 The expiration time is computed by adding the requested TTL to the 
31 current time.
32 When dynamic objects reach the end of their lifetime without being
33 further refreshed, they are automatically deleted.
34 There is no guarantee of immediate deletion, so clients should not count
35 on it.
36
37 Dynamic objects can have subordinates, provided these also are dynamic
38 objects.
39 RFC 2589 does not specify what the behavior of a dynamic directory
40 service should be when a dynamic object with (dynamic) subordinates
41 expires.
42 In this implementation, the lifetime of dynamic objects with subordinates
43 is prolonged until all the dynamic subordinates expire.
44
45
46 This 
47 .BR slapd.conf (5)
48 directive adds the 
49 .B dds
50 overlay to the current database:
51
52 .TP
53 .B overlay dds
54
55 .LP
56 The database must have a
57 .B rootdn
58 specified, otherwise, the
59 .B dds
60 overlay will not be able to delete expired objects. The 
61 .B dds
62 overlay may be used with any backend that implements the 
63 .BR add ,
64 .BR modify ,
65 .BR search ,
66 and
67 .BR delete
68 operations.
69 Since its use may result in many internal entry lookups, adds
70 and deletes, it should be best used in conjunction with backends
71 that have reasonably good write performances.
72
73 .LP 
74 The config directives that are specific to the
75 .B dds
76 overlay are prefixed by
77 .BR dds\- ,
78 to avoid potential conflicts with directives specific to the underlying 
79 database or to other stacked overlays.
80
81 .TP
82 .B dds\-max\-ttl <ttl>
83 Specifies the max TTL value.
84 This is also the default TTL newly created
85 dynamic objects receive, unless
86 .B dds\-default\-ttl
87 is set.
88 When the client with a refresh extended operation requests a TTL higher
89 than it, sizeLimitExceeded is returned.
90 This value must be between 86400 (1 day, the default) and 31557600
91 (1 year plus 6 hours, as per RFC 2589).
92
93 .TP
94 .B dds\-min\-ttl <ttl>
95 Specifies the min TTL value; clients requesting a lower TTL by means
96 of the refresh extended operation actually obtain this value as CRP.
97 If set to 0 (the default), no lower limit is set.
98
99 .TP
100 .B dds\-default\-ttl <ttl>
101 Specifies the default TTL value that newly created dynamic objects get.
102 If set to 0 (the default), the
103 .B dds\-max\-ttl
104 is used.
105
106 .TP
107 .B dds\-interval <ttl>
108 Specifies the interval between expiration checks; defaults to 1 hour.
109
110 .TP
111 .B dds\-tolerance <ttl>
112 Specifies an extra time that is added to the timer that actually wakes up
113 the thread that will delete an expired dynamic object.
114 So the nominal lifetime of the entry is that specified in the
115 .B entryTtl
116 attribute, but its lifetime will actually be
117 .BR "entryTtl + tolerance" .
118 Note that there is no guarantee that the lifetime of a dynamic object
119 will be
120 .I exactly
121 the requested TTL; due to implementation details, it may be longer, which 
122 is allowed by RFC 2589.
123 By default, tolerance is 0.
124
125 .TP
126 .B dds\-max\-dynamicObjects <num>
127 Specifies the maximum number of dynamic objects that can simultaneously exist
128 within a naming context.
129 This allows to limit the amount of resources (mostly in terms of
130 run-queue size) that are used by dynamic objects.
131 By default, no limit is set.
132
133 .TP
134 .B dds\-state {TRUE|false}
135 Specifies if the Dynamic Directory Services feature is enabled or not.
136 By default it is; however, a proxy does not need to keep track of dynamic
137 objects itself, it only needs to inform the frontend that support for
138 dynamic objects is available.
139
140 .SH ACCESS CONTROL
141 The
142 .B dds
143 overlay restricts the refresh operation by requiring 
144 .B manage
145 access to the 
146 .B entryTtl
147 attribute (see
148 .BR slapd.access (5)
149 for details about the 
150 .B manage
151 access privilege).
152 Since the
153 .B entryTtl
154 is an operational, NO-USER-MODIFICATION attribute, no direct write access
155 to it is possible.
156 So the 
157 .B dds
158 overlay turns refresh extended operation into an internal modification to
159 the value of the
160 .B entryTtl
161 attribute with the
162 .B relax
163 control set.
164
165 RFC 2589 recommends that anonymous clients should not be allowed to refresh
166 a dynamic object.
167 This can be implemented by appropriately crafting access control to obtain 
168 the desired effect.
169
170 Example: restrict refresh to authenticated clients
171
172 .RS
173 .nf
174 access to attrs=entryTtl
175         by users manage
176         by * read
177
178 .fi
179 .RE
180 Example: restrict refresh to the creator of the dynamic object
181
182 .RS
183 .nf
184 access to attrs=entryTtl
185         by dnattr=creatorsName manage
186         by * read
187
188 .fi
189 .RE
190 Another suggested usage of dynamic objects is to implement dynamic meetings;
191 in this case, all the participants to the meeting are allowed to refresh 
192 the meeting object, but only the creator can delete it (otherwise it will
193 be deleted when the TTL expires)
194
195 Example: assuming \fIparticipant\fP is a valid DN-valued attribute, 
196 allow users to start a meeting and to join it; restrict refresh 
197 to the participants; restrict delete to the creator
198
199 .RS
200 .nf
201 access to dn.base="cn=Meetings"
202                 attrs=children
203         by users write
204
205 access to dn.onelevel="cn=Meetings"
206                 attrs=entry
207         by dnattr=creatorsName write
208         by * read
209
210 access to dn.onelevel="cn=Meetings"
211                 attrs=participant
212         by dnattr=creatorsName write
213         by users selfwrite
214         by * read
215
216 access to dn.onelevel="cn=Meetings"
217                 attrs=entryTtl
218         by dnattr=participant manage
219         by * read
220
221 .fi
222 .RE
223
224 .SH REPLICATION
225 This implementation of RFC 2589 provides a restricted interpretation of how
226 dynamic objects replicate.  Only the master takes care of handling dynamic
227 object expiration, while replicas simply see the dynamic object as a plain
228 object.
229
230 When replicating these objects, one needs to explicitly exclude the 
231 .B dynamicObject
232 class and the
233 .B entryTtl
234 attribute.
235 This implementation of RFC 2589 introduces a new operational attribute,
236 .BR entryExpireTimestamp ,
237 that contains the expiration timestamp.  This must be excluded from 
238 replication as well.
239
240 The quick and dirty solution is to set 
241 .B schemacheck=off
242 in the syncrepl configuration
243 and, optionally, exclude the operational attributes from replication, using
244
245 .RS
246 .nf
247 syncrepl ...
248         exattrs=entryTtl,entryExpireTimestamp
249 .fi
250 .RE
251
252 In any case the overlay must be either statically built in or run-time loaded 
253 by the consumer, so that it is aware of the 
254 .B entryExpireTimestamp
255 operational attribute; however, it must not be configured in the shadow 
256 database.
257 Currently, there is no means to remove the 
258 .B dynamicObject
259 class from the entry; this may be seen as a feature, since it allows to see
260 the dynamic properties of the object.
261
262 .SH FILES
263 .TP
264 ETCDIR/slapd.conf
265 default slapd configuration file
266 .SH SEE ALSO
267 .BR slapd.conf (5),
268 .BR slapd\-config (5),
269 .BR slapd (8).
270 .SH AUTHOR
271 Implemented by Pierangelo Masarati.