add a readme

contrib/slapd-modules/allowed/README

@@ -0,0 +1,83 @@
+This directory contains a slapd overlay, aa.
+
+    --- o --- o --- o ---
+
+It adds to entries returned by search operations the value of attributes
+
+"allowedAttributes"
+	<http://msdn.microsoft.com/en-us/library/ms675217(VS.85).aspx>
+
+"allowedAttributesEffective"
+	<http://msdn.microsoft.com/en-us/library/ms675218(VS.85).aspx>
+
+No other use is made of those attributes: they cannot be compared,
+they cannot be used in search filters, they cannot be used in ACLs, ...
+
+    --- o --- o --- o ---
+
+Other attributes like
+
+"allowedChildClasses"
+	<http://msdn.microsoft.com/en-us/library/ms675219(VS.85).aspx>
+"allowedChildClassesEffective"
+	<http://msdn.microsoft.com/en-us/library/ms675220(VS.85).aspx>
+
+make little sense within OpenLDAP's slapd right now, since any AUXILIARY
+objectClass can be added to an entry, while no STRUCTURAL objectClass can.
+This may change when DIT structure rules are implemented, while ACLs may
+restrict what AUXILIARY objectClasses can be added to an entry.
+
+    --- o --- o --- o ---
+
+Usage: add to slapd.conf(5)
+
+
+moduleload	path/to/allowed.so
+overlay		aa
+
+or add
+
+dn: olcOverlay={0}aa,olcDatabase={1}bdb,cn=config
+objectClass: olcOverlayConfig
+olcOverlay: {0}aa
+
+as a child of the database that's intended to support this feature
+(replace "olcDatabase={1}bdb,cn=config" with the appropriate parent);
+or use
+
+dn: olcOverlay={0}aa,olcDatabase={-1}frontend,cn=config
+objectClass: olcOverlayConfig
+olcOverlay: {0}aa
+
+if it's supposed to be global.
+
+    --- o --- o --- o ---
+
+No Makefile is provided. Use a command line similar to:
+
+gcc -shared -I../../../include -I../../../servers/slapd -Wall -g \
+	-o allop.so allop.c
+
+to compile this overlay, or even better use OpenLDAP's libtool as appropriate.
+
+---
+This work is part of OpenLDAP Software <http://www.openldap.org/>.
+
+Copyright 2006-2009 The OpenLDAP Foundation. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted only as authorized by the OpenLDAP
+Public License.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted only as authorized by the OpenLDAP
+Public License.
+
+A copy of this license is available in the file LICENSE in the
+top-level directory of the distribution or, alternatively, at
+<http://www.OpenLDAP.org/license.html>.
+
+ACKNOWLEDGEMENTS:
+This work was initially developed by Pierangelo Masarati for inclusion in
+OpenLDAP Software.
+