1SLAPO-DDS(5)                  File Formats Manual                 SLAPO-DDS(5)
2
3
4

NAME

6       slapo-dds - Dynamic Directory Services overlay to slapd
7

SYNOPSIS

9       /etc/openldap/slapd.conf
10

DESCRIPTION

12       The dds overlay to slapd(8) implements dynamic objects as per RFC 2589.
13       The name dds stands for Dynamic Directory Services.  It allows  one  to
14       define dynamic objects, characterized by the dynamicObject objectClass.
15
16       Dynamic  objects  have a limited lifetime, determined by a time-to-live
17       (TTL) that can be refreshed by means of  a  specific  refresh  extended
18       operation.   This operation allows one to set the Client Refresh Period
19       (CRP), namely the period between refreshes that is required to preserve
20       the dynamic object from expiration.  The expiration time is computed by
21       adding the requested TTL to the current  time.   When  dynamic  objects
22       reach  the  end of their lifetime without being further refreshed, they
23       are automatically deleted.  There is no guarantee  of  immediate  dele‐
24       tion, so clients should not count on it.
25
26       Dynamic  objects can have subordinates, provided these also are dynamic
27       objects.  RFC 2589 does not specify what  the  behavior  of  a  dynamic
28       directory service should be when a dynamic object with (dynamic) subor‐
29       dinates expires.  In  this  implementation,  the  lifetime  of  dynamic
30       objects  with  subordinates is prolonged until all the dynamic subordi‐
31       nates expire.
32
33
34       This slapd.conf(5) directive adds the dds overlay to the current  data‐
35       base:
36
37
38       overlay dds
39
40
41       The  database  must have a rootdn specified, otherwise, the dds overlay
42       will not be able to delete expired objects. The dds overlay may be used
43       with  any  backend  that implements the add, modify, search, and delete
44       operations.  Since its use may result in many internal  entry  lookups,
45       adds  and  deletes, it should be best used in conjunction with backends
46       that have reasonably good write performances.
47
48
49       The config directives that are specific to the dds overlay are prefixed
50       by  dds-,  to avoid potential conflicts with directives specific to the
51       underlying database or to other stacked overlays.
52
53
54       dds-max-ttl <ttl>
55              Specifies the max TTL value.  This is also the default TTL newly
56              created  dynamic objects receive, unless dds-default-ttl is set.
57              When the client with a refresh extended operation requests a TTL
58              higher  than it, sizeLimitExceeded is returned.  This value must
59              be between 86400 (1 day, the default) and 31557600 (1 year  plus
60              6 hours, as per RFC 2589).
61
62
63       dds-min-ttl <ttl>
64              Specifies  the  min TTL value; clients requesting a lower TTL by
65              means of the refresh extended  operation  actually  obtain  this
66              value as CRP.  If set to 0 (the default), no lower limit is set.
67
68
69       dds-default-ttl <ttl>
70              Specifies  the  default  TTL  value  that  newly created dynamic
71              objects get.  If set to 0  (the  default),  the  dds-max-ttl  is
72              used.
73
74
75       dds-interval <ttl>
76              Specifies  the interval between expiration checks; defaults to 1
77              hour.
78
79
80       dds-tolerance <ttl>
81              Specifies an extra time that is added to the timer that actually
82              wakes  up the thread that will delete an expired dynamic object.
83              So the nominal lifetime of the entry is that  specified  in  the
84              entryTtl attribute, but its lifetime will actually be entryTtl +
85              tolerance.  Note that there is no guarantee that the lifetime of
86              a  dynamic  object  will  be  exactly  the requested TTL; due to
87              implementation details, it may be longer, which  is  allowed  by
88              RFC 2589.  By default, tolerance is 0.
89
90
91       dds-max-dynamicObjects <num>
92              Specifies  the maximum number of dynamic objects that can simul‐
93              taneously exist within a naming context.   This  allows  one  to
94              limit  the  amount  of  resources  (mostly in terms of run-queue
95              size) that are used by dynamic objects.  By default, no limit is
96              set.
97
98
99       dds-state {TRUE|false}
100              Specifies  if  the Dynamic Directory Services feature is enabled
101              or not.  By default it is; however, a proxy  does  not  need  to
102              keep  track  of  dynamic objects itself, it only needs to inform
103              the frontend that support for dynamic objects is available.
104
105

ACCESS CONTROL

107       The dds overlay restricts the refresh  operation  by  requiring  manage
108       access to the entryTtl attribute (see slapd.access(5) for details about
109       the manage access privilege).  Since the entryTtl  is  an  operational,
110       NO-USER-MODIFICATION  attribute, no direct write access to it is possi‐
111       ble.  So the dds overlay  turns  refresh  extended  operation  into  an
112       internal  modification  to the value of the entryTtl attribute with the
113       relax control set.
114
115       RFC 2589 recommends that anonymous clients should  not  be  allowed  to
116       refresh  a  dynamic  object.   This can be implemented by appropriately
117       crafting access control to obtain the desired effect.
118
119       Example: restrict refresh to authenticated clients
120
121              access to attrs=entryTtl
122                   by users manage
123                   by * read
124
125       Example: restrict refresh to the creator of the dynamic object
126
127              access to attrs=entryTtl
128                   by dnattr=creatorsName manage
129                   by * read
130
131       Another suggested usage of dynamic  objects  is  to  implement  dynamic
132       meetings; in this case, all the participants to the meeting are allowed
133       to refresh the meeting object, but only the creator can delete it (oth‐
134       erwise it will be deleted when the TTL expires)
135
136       Example:  assuming  participant  is  a valid DN-valued attribute, allow
137       users to start a meeting and to join it; restrict refresh to  the  par‐
138       ticipants; restrict delete to the creator
139
140              access to dn.base="cn=Meetings"
141                        attrs=children
142                   by users write
143
144              access to dn.onelevel="cn=Meetings"
145                        attrs=entry
146                   by dnattr=creatorsName write
147                   by * read
148
149              access to dn.onelevel="cn=Meetings"
150                        attrs=participant
151                   by dnattr=creatorsName write
152                   by users selfwrite
153                   by * read
154
155              access to dn.onelevel="cn=Meetings"
156                        attrs=entryTtl
157                   by dnattr=participant manage
158                   by * read
159
160
161

REPLICATION

163       This implementation of RFC 2589 provides a restricted interpretation of
164       how dynamic objects replicate.  Only the master takes care of  handling
165       dynamic object expiration, while replicas simply see the dynamic object
166       as a plain object.
167
168       When replicating these objects, one needs  to  explicitly  exclude  the
169       dynamicObject class and the entryTtl attribute.  This implementation of
170       RFC 2589 introduces a new operational attribute,  entryExpireTimestamp,
171       that  contains  the  expiration  timestamp.  This must be excluded from
172       replication as well.
173
174       The quick and dirty solution is to set schemacheck=off in the  syncrepl
175       configuration  and, optionally, exclude the operational attributes from
176       replication, using
177
178              syncrepl ...
179                   exattrs=entryTtl,entryExpireTimestamp
180
181       In any case the overlay must be either statically built in or  run-time
182       loaded by the consumer, so that it is aware of the entryExpireTimestamp
183       operational attribute; however, it must not be configured in the shadow
184       database.   Currently,  there  is  no means to remove the dynamicObject
185       class from the entry; this may be seen as a feature,  since  it  allows
186       one to see the dynamic properties of the object.
187
188

FILES

190       /etc/openldap/slapd.conf
191              default slapd configuration file
192

SEE ALSO

194       slapd.conf(5), slapd-config(5), slapd(8).
195

AUTHOR

197       Implemented by Pierangelo Masarati.
198
199
200
201OpenLDAP 2.4.46                   2018/03/22                      SLAPO-DDS(5)
Impressum