git.sur5r.net Git - openldap/blob - 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.