git.sur5r.net Git - openldap/blob - doc/man/man5/slapo-dds.5

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