~ubuntu-branches/ubuntu/maverick/openldap/maverick-proposed

« back to all changes in this revision

Viewing changes to doc/guide/admin/overlays.sdf

  • Committer: Bazaar Package Importer
  • Author(s): Mathias Gug, Steve Langasek, Mathias Gug
  • Date: 2009-02-18 18:44:00 UTC
  • mfrom: (1.1.2 upstream) (0.1.2 lenny)
  • Revision ID: james.westby@ubuntu.com-20090218184400-zw4mjse9eywt5566
Tags: 2.4.14-0ubuntu1
[ Steve Langasek ]
* New upstream version
  - Fixes a bug with the pcache overlay not returning cached entries
    (closes: #497697)
  - Update evolution-ntlm patch to apply to current Makefiles.
  - (tentatively) drop gnutls-ciphers, since this bug was reported to be
    fixed upstream in 2.4.8.  The fix applied in 2.4.8 didn't match the
    patch from the bug report, so this should be watched for regressions.
* Build against db4.7 instead of db4.2 at last!  Closes: #421946.
* Build with --disable-ndb, to avoid a misbuild when libmysqlclient is
  installed in the build environment.
* New patch, no-crlcheck-for-gnutls, to fix a build failure when using
  --with-tls=gnutls.

[ Mathias Gug ]
* Merge from debian unstable, remaining changes:
  - debian/apparmor-profile: add AppArmor profile
  - debian/slapd.postinst: Reload AA profile on configuration
  - updated debian/slapd.README.Debian for note on AppArmor
  - debian/control: Recommends apparmor >= 2.1+1075-0ubuntu6
  - debian/control: Conflicts with apparmor-profiles << 2.1+1075-0ubuntu4
    to make sure that if earlier version of apparmour-profiles gets
    installed it won't overwrite our profile.
  - Modify Maintainer value to match the DebianMaintainerField
    speficication.
  - follow ApparmorProfileMigration and force apparmor compalin mode on 
    some upgrades (LP: #203529)
  - debian/slapd.dirs: add etc/apparmor.d/force-complain
  - debian/slapd.preinst: create symlink for force-complain on pre-feisty
    upgrades, upgrades where apparmor-profiles profile is unchanged (ie
    non-enforcing) and upgrades where apparmor profile does not exist.
  - debian/slapd.postrm: remove symlink in force-complain/ on purge
  - debian/patches/fix-ucred-libc due to changes how newer glibc handle
    the ucred struct now.
  - debian/control:
    - Build-depend on libltdl7-dev rather then libltdl3-dev.
  - debian/patches/autogen.sh:
    - Call libtoolize with the --install option to install config.{guess,sub}
      files.
  - Don't use local statement in config script as it fails if /bin/sh
    points to bash (LP: #286063).
  - Disable the testsuite on hppa. Allows building of packages on this
    architecture again, once this package is in the archive.
    LP: #288908.
  - debian/slapd.postinst, debian/slapd.script-common: set correct ownership
    and permissions on /var/lib/ldap, /etc/ldap/slapd.d (group readable) and
    /var/run/slapd (world readable). (LP: #257667).
  - debian/patches/nssov-build, debian/rules: 
    Build and package the nss overlay.
    debian/schema/misc.ldif: add ldif file for the misc schema, which defines
    rfc822MailMember (required by the nss overlay).
  - debian/{control,rules}: enable PIE hardening
  - Use cn=config as the default configuration backend instead of 
    slapd.conf. Migrate slapd.conf  file to /etc/ldap/slapd.d/ on upgrade
    asking the end user to enter a new password to control the access to the
    cn=config tree.
* debian/patches/corrupt-contextCSN: The contextCSN can get corrupted at
  times. (ITS: #5947)

Show diffs side-by-side

added added

removed removed

Lines of Context:
1
 
# $OpenLDAP: pkg/openldap-guide/admin/overlays.sdf,v 1.8.2.20 2008/07/12 05:53:45 quanah Exp $
2
 
# Copyright 2007-2008 The OpenLDAP Foundation, All Rights Reserved.
 
1
# $OpenLDAP: pkg/openldap-guide/admin/overlays.sdf,v 1.8.2.26 2009/01/22 00:00:47 kurt Exp $
 
2
# Copyright 2007-2009 The OpenLDAP Foundation, All Rights Reserved.
3
3
# COPYING RESTRICTIONS APPLY, see COPYRIGHT.
4
4
 
5
5
H1: Overlays
322
322
>        chain-return-error TRUE
323
323
 
324
324
 
 
325
H3: Read-Back of Chained Modifications
 
326
 
 
327
Occasionally, applications want to read back the data that they just wrote.
 
328
If a modification requested to a shadow server was silently chained to its 
 
329
producer, an immediate read could result in receiving data not yet synchronized.  
 
330
In those cases, clients should use the {{B:dontusecopy}} control to ensure 
 
331
they are directed to the authoritative source for that piece of data.
 
332
 
 
333
This control usually causes a referral to the actual source of the data
 
334
to be returned.  However, when the {{slapo-chain(5)}} overlay is used,
 
335
it intercepts the referral being returned in response to the
 
336
{{B:dontusecopy}} control, and tries to fetch the requested data.
 
337
 
 
338
 
325
339
H3: Further Information
326
340
 
327
341
{{:slapo-chain(5)}}
343
357
Configuration via {{slapd.conf}}(5) would look like:
344
358
 
345
359
>        overlay constraint
346
 
>        constraint_attribute mail regex ^[:alnum:]+@mydomain.com$
 
360
>        constraint_attribute mail regex ^[[:alnum:]]+@mydomain.com$
347
361
>        constraint_attribute title uri
348
362
>        ldap:///dc=catalog,dc=example,dc=com?title?sub?(objectClass=titleCatalog)
349
363
 
360
374
>       objectClass: olcOverlayConfig
361
375
>       objectClass: olcConstraintConfig
362
376
>       olcOverlay: constraint
363
 
>       olcConstraintAttribute: mail regex ^[:alnum:]+@mydomain.com$
 
377
>       olcConstraintAttribute: mail regex ^[[:alnum:]]+@mydomain.com$
364
378
>       olcConstraintAttribute: title uri ldap:///dc=catalog,dc=example,dc=com?title?sub?(objectClass=titleCatalog)
365
379
 
366
380
 
1085
1099
 
1086
1100
H3: Overview
1087
1101
 
1088
 
This overlay implements the provider-side support for syncrepl
1089
 
replication, including persistent search functionality
1090
 
 
 
1102
This overlay implements the provider-side support for the LDAP Content Synchronization 
 
1103
({{REF:RFC4533}}) as well as syncrepl replication support, including persistent search functionality.
1091
1104
 
1092
1105
H3: Sync Provider Configuration
1093
1106
 
 
1107
There is very little configuration needed for this overlay, in fact for many situations merely loading 
 
1108
the overlay will suffice.
 
1109
 
 
1110
However, because the overlay creates a contextCSN attribute in the root entry of the database which is
 
1111
updated for every write operation performed against the database and only updated in memory, it is 
 
1112
recommended to configure a checkpoint so that the contextCSN is written into the underlying database to 
 
1113
minimize recovery time after an unclean shutdown:
 
1114
 
 
1115
>       overlay syncprov
 
1116
>       syncprov-checkpoint 100 10
 
1117
 
 
1118
For every 100 operations or 10 minutes, which ever is sooner, the contextCSN will be checkpointed.
 
1119
 
 
1120
The four configuration directives available are {{B:syncprov-checkpoint}}, {{B:syncprov-sessionlog}},
 
1121
{{B:syncprov-nopresent}} and {{B:syncprov-reloadhint}} which are covered in the man page discussing
 
1122
various other scenarios where this overlay can be used. 
1094
1123
 
1095
1124
H3: Further Information
1096
1125
 
1097
 
{{:slapo-syncprov(5)}}
 
1126
The {{:slapo-syncprov(5)}} man page and the {{SECT:Configuring the different replication types}} section
1098
1127
 
1099
1128
 
1100
1129
H2: Translucent Proxy
1102
1131
 
1103
1132
H3: Overview
1104
1133
 
1105
 
This overlay can be used with a backend database such as slapd-bdb (5)
 
1134
This overlay can be used with a backend database such as {{:slapd-bdb}}(5)
1106
1135
to create a "translucent proxy".
1107
1136
 
1108
 
Content of entries retrieved from a remote LDAP server can be partially
1109
 
overridden by the database.
 
1137
Entries retrieved from a remote LDAP server may have some or all attributes 
 
1138
overridden, or new attributes added, by entries in the local database before 
 
1139
being presented to the client.
 
1140
 
 
1141
A search operation is first populated with entries from the remote LDAP server, 
 
1142
the attributes of which are then overridden with any attributes defined in the
 
1143
local database. Local overrides may be populated with the add, modify, and 
 
1144
modrdn operations, the use of which is restricted to the root user of the 
 
1145
translucent local database.
 
1146
 
 
1147
A compare operation will perform a comparison with attributes defined in the
 
1148
local database record (if any) before any comparison is made with data in the 
 
1149
remote database.
1110
1150
 
1111
1151
 
1112
1152
H3: Translucent Proxy Configuration
1113
1153
 
1114
 
 
 
1154
There are various options available with this overlay, but for this example we
 
1155
will demonstrate adding new attributes to a remote entry and also searching 
 
1156
against these newly added local attributes. For more information about overriding remote
 
1157
entries and search configuration, please see {{:slapo-translucent(5)}}
 
1158
 
 
1159
Note: The Translucent Proxy overlay will disable schema checking in the local
 
1160
database, so that an entry consisting of overlay attributes need not adhere
 
1161
 to the complete schema.
 
1162
 
 
1163
First we configure the overlay in the normal manner:
 
1164
 
 
1165
>       include     /usr/local/etc/openldap/schema/core.schema
 
1166
>       include     /usr/local/etc/openldap/schema/cosine.schema
 
1167
>       include     /usr/local/etc/openldap/schema/nis.schema
 
1168
>       include     /usr/local/etc/openldap/schema/inetorgperson.schema
 
1169
>       
 
1170
>       pidfile     ./slapd.pid
 
1171
>       argsfile    ./slapd.args
 
1172
>       
 
1173
>       modulepath  /usr/local/libexec/openldap
 
1174
>       moduleload  back_bdb.la
 
1175
>       moduleload  back_ldap.la
 
1176
>       moduleload  translucent.la
 
1177
>       
 
1178
>       database    bdb
 
1179
>       suffix      "dc=suretecsystems,dc=com"
 
1180
>       rootdn      "cn=trans,dc=suretecsystems,dc=com"
 
1181
>       rootpw      secret
 
1182
>       directory   ./openldap-data
 
1183
>       
 
1184
>       index       objectClass eq
 
1185
>       
 
1186
>       overlay     translucent
 
1187
>       translucent_local carLicense
 
1188
>       
 
1189
>       uri         ldap://192.168.X.X:389
 
1190
>       lastmod     off
 
1191
>       acl-bind    binddn="cn=admin,dc=suretecsystems,dc=com" credentials="blahblah"
 
1192
 
 
1193
You will notice the overlay directive and a directive to say what attribute we 
 
1194
want to be able to search against in the local database. We must also load the 
 
1195
ldap backend which will connect to the remote directory server.
 
1196
 
 
1197
Now we take an example LDAP group:
 
1198
 
 
1199
>       # itsupport, Groups, suretecsystems.com
 
1200
>       dn: cn=itsupport,ou=Groups,dc=suretecsystems,dc=com
 
1201
>       objectClass: posixGroup
 
1202
>       objectClass: sambaGroupMapping
 
1203
>       cn: itsupport
 
1204
>       gidNumber: 1000
 
1205
>       sambaSID: S-1-5-21-XXX
 
1206
>       sambaGroupType: 2
 
1207
>       displayName: itsupport
 
1208
>       memberUid: ghenry
 
1209
>       memberUid: joebloggs
 
1210
 
 
1211
and create an LDIF file we can use to add our data to the local database, using
 
1212
 some pretty strange choices of new attributes for demonstration purposes:
 
1213
 
 
1214
>       [ghenry@suretec test_configs]$ cat test-translucent-add.ldif 
 
1215
>       dn: cn=itsupport,ou=Groups,dc=suretecsystems,dc=com
 
1216
>       businessCategory: frontend-override
 
1217
>       carLicense: LIVID
 
1218
>       employeeType: special
 
1219
>       departmentNumber: 9999999
 
1220
>       roomNumber: 41L-535
 
1221
 
 
1222
Searching against the proxy gives:
 
1223
 
 
1224
>       [ghenry@suretec test_configs]$ ldapsearch -x -H ldap://127.0.0.1:9001 "(cn=itsupport)"
 
1225
>       # itsupport, Groups, OxObjects, suretecsystems.com
 
1226
>       dn: cn=itsupport,ou=Groups,ou=OxObjects,dc=suretecsystems,dc=com
 
1227
>       objectClass: posixGroup
 
1228
>       objectClass: sambaGroupMapping
 
1229
>       cn: itsupport
 
1230
>       gidNumber: 1003
 
1231
>       SAMBASID: S-1-5-21-XXX
 
1232
>       SAMBAGROUPTYPE: 2
 
1233
>       displayName: itsupport
 
1234
>       memberUid: ghenry
 
1235
>       memberUid: joebloggs
 
1236
>       roomNumber: 41L-535
 
1237
>       departmentNumber: 9999999
 
1238
>       employeeType: special
 
1239
>       carLicense: LIVID
 
1240
>       businessCategory: frontend-override
 
1241
 
 
1242
Here we can see that the 5 new attributes are added to the remote entry before 
 
1243
being returned to the our client.
 
1244
 
 
1245
Because we have configured a local attribute to search against:
 
1246
 
 
1247
>       overlay     translucent
 
1248
>       translucent_local carLicense
 
1249
 
 
1250
we can also search for that to return the completely fabricated entry:
 
1251
 
 
1252
>       ldapsearch -x -H ldap://127.0.0.1:9001 (carLicense=LIVID)
 
1253
 
 
1254
This is an extremely feature because you can then extend a remote directory server
 
1255
locally and also search against the local entries.
 
1256
 
 
1257
Note: Because the translucent overlay does not perform any DN rewrites, the local
 
1258
 and remote database instances must have the same suffix. Other configurations 
 
1259
will probably fail with No Such Object and other errors
1115
1260
 
1116
1261
H3: Further Information
1117
1262
 
1123
1268
 
1124
1269
H3: Overview
1125
1270
 
1126
 
This overlay can be used with a backend database such as slapd-bdb (5)
 
1271
This overlay can be used with a backend database such as {{slapd-bdb(5)}}
1127
1272
to enforce the uniqueness of some or all attributes within a subtree.
1128
1273
 
1129
1274
 
1130
1275
H3: Attribute Uniqueness Configuration
1131
1276
 
 
1277
This overlay is only effective on new data from the point the overlay is enabled. To
 
1278
check uniqueness for existing data, you can export and import your data again via the
 
1279
LDAP Add operation, which will not be suitable for large amounts of data, unlike {{B:slapcat}}.
 
1280
 
 
1281
For the following example, if uniqueness were enforced for the {{B:mail}} attribute, 
 
1282
the subtree would be searched for any other records which also have a {{B:mail}} attribute 
 
1283
containing the same value presented with an {{B:add}}, {{B:modify}} or {{B:modrdn}} operation 
 
1284
which are unique within the configured scope. If any are found, the request is rejected.
 
1285
 
 
1286
Note:  If no attributes are specified, for example {{B:ldap:///??sub?}}, then the URI applies to all non-operational attributes. However,
 
1287
the keyword {{B:ignore}} can be specified to exclude certain non-operational attributes. 
 
1288
 
 
1289
To search at the base dn of the current backend database ensuring uniqueness of the {{B:mail}}
 
1290
attribute, we simply add the following configuration:
 
1291
 
 
1292
>       overlay unique
 
1293
>       unique_uri ldap:///?mail?sub?
 
1294
 
 
1295
For an existing entry of:
 
1296
 
 
1297
>       dn: cn=gavin,dc=suretecsystems,dc=com
 
1298
>       objectClass: top
 
1299
>       objectClass: inetorgperson
 
1300
>       cn: gavin
 
1301
>       sn: henry
 
1302
>       mail: ghenry@suretecsystems.com
 
1303
 
 
1304
and we then try to add a new entry of:
 
1305
 
 
1306
>       dn: cn=robert,dc=suretecsystems,dc=com
 
1307
>       objectClass: top
 
1308
>       objectClass: inetorgperson
 
1309
>       cn: robert
 
1310
>       sn: jones
 
1311
>       mail: ghenry@suretecsystems.com
 
1312
 
 
1313
would result in an error like so:
 
1314
 
 
1315
>       adding new entry "cn=robert,dc=example,dc=com"
 
1316
>       ldap_add: Constraint violation (19)
 
1317
>               additional info: some attributes not unique
 
1318
 
 
1319
The overlay can have multiple URIs specified within a domain, allowing complex
 
1320
selections of objects and also have multiple {{B:unique_uri}} statements or 
 
1321
{{B:olcUniqueURI}} attributes which will create independent domains.
 
1322
 
 
1323
For more information and details about the {{B:strict}} and {{B:ignore}} keywords,
 
1324
please see the {{:slapo-unique(5)}} man page.
1132
1325
 
1133
1326
H3: Further Information
1134
1327
 
1140
1333
 
1141
1334
H3: Overview
1142
1335
 
1143
 
This overlay can be used to enforce a specific order for the values
1144
 
of an attribute when it is returned in a search.
1145
 
 
 
1336
The Value Sorting overlay can be used with a backend database to sort the 
 
1337
values of specific multi-valued attributes within a subtree. The sorting occurs 
 
1338
whenever the attributes are returned in a search response.
1146
1339
 
1147
1340
H3: Value Sorting Configuration
1148
1341
 
 
1342
Sorting can be specified in ascending or descending order, using either numeric 
 
1343
or alphanumeric sort methods. Additionally, a "weighted" sort can be specified,
 
1344
 which uses a numeric weight prepended to the attribute values. 
 
1345
 
 
1346
The weighted sort is always performed in ascending order, but may be combined 
 
1347
with the other methods for values that all have equal weights. The weight is 
 
1348
specified by prepending an integer weight {<weight>} in front of each value 
 
1349
of the attribute for which weighted sorting is desired. This weighting factor 
 
1350
is stripped off and never returned in search results.
 
1351
 
 
1352
Here are a few examples:
 
1353
 
 
1354
>       loglevel    sync stats
 
1355
>       
 
1356
>       database    hdb
 
1357
>       suffix      "dc=suretecsystems,dc=com"
 
1358
>       directory   /usr/local/var/openldap-data
 
1359
>       
 
1360
>       ......
 
1361
>       
 
1362
>       overlay valsort
 
1363
>       valsort-attr memberUid ou=Groups,dc=suretecsystems,dc=com alpha-ascend
 
1364
 
 
1365
For example, ascend:
 
1366
 
 
1367
>       # sharedemail, Groups, suretecsystems.com
 
1368
>       dn: cn=sharedemail,ou=Groups,dc=suretecsystems,dc=com
 
1369
>       objectClass: posixGroup
 
1370
>       objectClass: top
 
1371
>       cn: sharedemail
 
1372
>       gidNumber: 517
 
1373
>       memberUid: admin
 
1374
>       memberUid: dovecot
 
1375
>       memberUid: laura
 
1376
>       memberUid: suretec
 
1377
 
 
1378
For weighted, we change our data to:
 
1379
 
 
1380
>       # sharedemail, Groups, suretecsystems.com
 
1381
>       dn: cn=sharedemail,ou=Groups,dc=suretecsystems,dc=com
 
1382
>       objectClass: posixGroup
 
1383
>       objectClass: top
 
1384
>       cn: sharedemail
 
1385
>       gidNumber: 517
 
1386
>       memberUid: {4}admin
 
1387
>       memberUid: {2}dovecot
 
1388
>       memberUid: {1}laura
 
1389
>       memberUid: {3}suretec
 
1390
 
 
1391
and change the config to:
 
1392
 
 
1393
>       overlay valsort
 
1394
>       valsort-attr memberUid ou=Groups,dc=suretecsystems,dc=com weighted
 
1395
 
 
1396
Searching now results in:
 
1397
 
 
1398
>       # sharedemail, Groups, OxObjects, suretecsystems.com
 
1399
>       dn: cn=sharedemail,ou=Groups,ou=OxObjects,dc=suretecsystems,dc=com
 
1400
>       objectClass: posixGroup
 
1401
>       objectClass: top
 
1402
>       cn: sharedemail
 
1403
>       gidNumber: 517
 
1404
>       memberUid: laura
 
1405
>       memberUid: dovecot
 
1406
>       memberUid: suretec
 
1407
>       memberUid: admin
 
1408
 
1149
1409
 
1150
1410
H3: Further Information
1151
1411