external/bsd/openldap/man/slapo-dds.5

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