- add some notes on how the schema compatibility plugin is built and configured

4 files changed, 291 insertions, 8 deletions

diff --git a/doc/nis-design.txt b/doc/nis-design.txt
index c44e35a..06bbc16 100644
--- a/doc/nis-design.txt
+++ b/doc/nis-design.txt
@@ -1,6 +1,6 @@
 = Design Overview =
 
-The NIS plugin module's aim is to serve up data from the directory
+The NIS Server plugin's aim is to serve up data from the directory
 server using the NIS protocols.  It does this by doing what any gateway
 would do: it queries the directory server for entries which would
 correspond to the contents of maps, reads the contents of various
@@ -329,9 +329,10 @@ need to escape the double-quote using a '\' character.  Naturally the
       %deref(",","member","uid") -> bob,pete (when a list is acceptable)
   * referred(MAP,THATATTRIBUTE,THATOTHERATTRIBUTE)
     - Creates a separated list of the values of THATOTHERATTRIBUTE for
-      directory entries which have entries in the named MAP and which
-      also have this entry's name as a value for THATATTRIBUTE.  Will
-      fail if used in a context where a single value is required.
+      directory entries which have entries in the current domain in the
+      named MAP and which also have this entry's name as a value for
+      THATATTRIBUTE.  Will fail if used in a context where a single
+      value is required.
     - Example (examining "cn=group"):
         dn: cn=group
         -
diff --git a/doc/sch-configuration.txt b/doc/sch-configuration.txt
new file mode 100644
index 0000000..19b148e
--- /dev/null
+++ b/doc/sch-configuration.txt
@@ -0,0 +1,77 @@
+The plugin's configuration is entirely devoted to sets of entries or
+groups of those sets.  As a result, the entry contains the standard
+attributes for plugins and nothing more.  An example plugin entry might
+look like this:
+
+  dn: cn=Schema Compatibility, cn=plugins, cn=config
+  objectclass: top
+  objectclass: nsSlapdPlugin
+  objectclass: extensibleObject
+  cn: Schema Compatibility
+  nsslapd-pluginpath: /usr/lib/dirsrv/plugins/schemacompat-plugin.so
+  nsslapd-plugininitfunc: schema_compat_plugin_init
+  nsslapd-plugintype: object
+  nsslapd-pluginenabled: on
+  nsslapd-pluginid: schema-compat
+  nsslapd-version: 0.0
+  nsslapd-pluginvendor: redhat.com
+  nsslapd-plugindescription: Schema Compatibility Plugin
+
+Configuration for individual sets should be stored in entries directly
+beneath the plugin's entry.  These attributes are recognized:
+
+ * schema-compat-container-group
+   The top-level container DN under which this container's entry
+   appears.  This level of grouping is useful when using the "referred"
+   function.
+ * schema-compat-container-rdn
+   The RDN of this particular container.
+ * schema-compat-search-base
+   One or more locations in the directory where candidate entries can be
+   found.
+ * schema-compat-search-filter
+   A filter used to select which candidate entries should have new
+   entries created for them in this container.
+ * schema-compat-entry-rdn
+   The RDN to apply to generated entries, which will be stored as
+   children of this container.
+ * schema-compat-entry-attribute
+   Additional attributes to add to each entry in this container.
+
+An pair of example definitions might look like this:
+
+  dn: ou=People,cn=Schema Compatibility, cn=plugins, cn=config
+  objectclass: top
+  objectclass: extensibleObject
+  schema-compat-container-group: cn=compat,cn=Accounts,dc=example,dc=com
+  schema-compat-container-rdn: ou=People
+  schema-compat-search-base: cn=Users,cn=Accounts,dc=example,dc=com
+  schema-compat-search-filter: (objectClass=posixAccount)
+  schema-compat-entry-rdn: uid=%{uid}
+  schema-compat-entry-attribute: objectClass=account
+  schema-compat-entry-attribute: objectClass=posixAccount
+  schema-compat-entry-attribute: objectClass=inetOrgPerson
+  schema-compat-entry-attribute: objectClass=kerberosPrincipalAux
+  schema-compat-entry-attribute: homeDirectory=%{homeDirectory}
+  schema-compat-entry-attribute: uidNumber=%{uidNumber}
+  schema-compat-entry-attribute: gidNumber=%{gidNumber}
+  schema-compat-entry-attribute: loginShell=%{loginShell}
+  schema-compat-entry-attribute: userPassword=*
+  schema-compat-entry-attribute: mail=%{uid}@example.com
+  schema-compat-entry-attribute: krbPrincipalName=%{uid}@EXAMPLE.COM
+
+  dn: ou=Group,cn=Schema Compatibility, cn=plugins, cn=config
+  objectclass: top
+  objectclass: extensibleObject
+  schema-compat-container-group: cn=compat,cn=Accounts,dc=example,dc=com
+  schema-compat-container-rdn: ou=Group
+  schema-compat-search-base: cn=Groups,cn=Accounts,dc=example,dc=com
+  schema-compat-search-filter: (objectClass=posixGroup)
+  schema-compat-entry-rdn: cn=%{cn}
+  schema-compat-entry-attribute: objectClass=posixGroup
+  schema-compat-entry-attribute: gidNumber=%{gidNumber}
+  schema-compat-entry-attribute: userPassword=*
+  schema-compat-entry-attribute: memberUid=%{memberUid}
+  schema-compat-entry-attribute: memberUid=%deref("member","uid")
+  schema-compat-entry-attribute: memberUid=%referred("ou=People","memberOf","uid")
+
diff --git a/doc/sch-design.txt b/doc/sch-design.txt
new file mode 100644
index 0000000..568cec6
--- /dev/null
+++ b/doc/sch-design.txt
@@ -0,0 +1,207 @@
+= Design Overview =
+
+The Schema Compatibility plugin's aim is to synthesize a modified view
+of the contents of one part of the directory and to make that view
+visible in another part of the directory.  It does this by precomputing
+the contents of its entries at startup-time and refreshing its entries
+as needed.
+
+== Map Cache ==
+
+The map cache keeps a dynamically-constructed set of tree locations in
+memory, grouped by the name of their top-level container, and maintains
+each set of entries inside of a specific subcontainer.
+
+== Back End ==
+
+The backend interface module sets up, populates, and maintains the map
+cache.  At startup time, it configures the map cache with the list of
+groups of sets of entries, and populates the sets with initial data.
+Using postoperation plugin hooks, the backend interface also notes when
+entries are added, modified, renamed (modrdn'd), or deleted from the
+directory server.  It uses this information to create or destroy sets in
+the map cache, and to add, remove, or update entries in the map cache's
+sets, thereby ensuring that the synthetic data in the map cache is
+always up to date with respect to the current contents of the directory
+server.
+
+The backend interface reads the configuration it should use for the map
+cache from its configuration area in the directory server.  Beneath the
+plugin's entry, the backend checks for entries with these attributes:
+ * schema-compat-search-base
+ * schema-compat-search-filter
+ * schema-compat-container-group
+ * schema-compat-container-rdn
+ * schema-compat-entry-rdn
+ * schema-compat-entry-attribute
+ * schema-compat-check-access
+
+The backend then instructs the map cache to prepare to hold a set of
+entries in the given container group (or container groups) with the
+given subcontainer RDN name (or names), and then performs a subtree
+search under the specified base (or bases, if there's more than one
+"schema-compat-search-base" value) for entries which match the provided
+filter ("schema-compat-search-filter").
+
+For entry found, a new entry is generated and "added" to the
+subcontainer, using the format specifier stored in the
+"schema-compat-entry-rdn" and "schema-compat-entry-attribute" attributes
+to construct the RDN and attribute values for the entry in the set.
+
+Should one of the directory server entries which was used to construct
+one or more entries be modified or removed, the corresponding entries in
+every applicable container are updated or removed.  Likewise, if an
+entry is added to the directory server which would correspond to an
+entry in a container, entries are created in the corresponding
+container.
+
+== Specifying Entry Contents ==
+
+The "schema-compat-entry-rdn" specifier resembles an RPM format
+specifier, and can include the values of multiple attributes in any part
+of the specifier.  The backend composes the string using the attribute
+values stored in the directory server entry, using the format specifier
+as a guide, and names the resulting entry using the subcontainer's name
+and the generated RDN.  Attributes specified using values of the
+"schema-compat-entry-attribute" attribute are then added.  If the
+resulting entry fails schema checks, it is automatically given the
+"extensibleObject" object class.
+
+An example specification for the "schema-compat-entry-rdn" for a user's
+entry could look something like this:
+  uid=%{uid}
+The syntax borrows from RPM's syntax, which in turn borrows from shell
+syntax, to allow the specification of alternate values to be used when
+the directory server entry doesn't include a "uid" attribute.
+Additional operators include "#", "##", "%", "%%", "/", "//", which
+operate in ways similar to their shell counterparts (with one notable
+exception being that patterns for the "/" operator can not currently be
+anchored to the beginning or end of the string).
+
+After the RDN is determined, attributes can be added.  Most often, this
+will be done either by specifying a specific value (typically for the
+entry's object classes) or an existing attribute, like so:
+  objectclass=posixAccount
+  cn=%{cn}
+
+A format specifier can actually be interpreted in two ways: it can be
+interpreted as a single value, or it can be interpreted as providing a
+list of values.  When the format specifier is being interpreted as a
+single value, any reference to an attribute value which does not also
+specify an alternate value will cause the directory server entry to be
+ignored if the referenced attribute has no value defined for that entry,
+or contains multiple values.  In the above example, the RDN is evaluated
+in such a manner.
+
+For all other attributes, if an attribute is multi-valued, the resulting
+entry will have a corresponding number of values.
+
+A pair of built-in "function"s are available for importing values from
+other entries.
+
+A function-like invocation expects a comma-separated list of
+double-quoted arguments.  Any arguments which contain a double-quote
+need to escape the double-quote using a '\' character.  Naturally the
+'\' this character itself also needs to be escaped whenever it appears.
+
+=== Implemented Functions ===
+  * match(ATTRIBUTE,PATTERN[,DEFAULT])
+    - Selects the value of ATTRIBUTE which matches the globbing pattern
+      PATTERN.  If zero or two or more values match, and a DEFAULT was
+      specified, the DEFAULT is produced, otherwise an error occurs.
+    - Example (examining "cn=group"):
+        dn: cn=group
+	member: bob
+	member: dave
+      %match("member","b*")       -> bob
+      %match("member","d*")       -> dave
+      %match("member","e*")        FAILS
+      %match("member","e*","jim") -> jim
+      %match("member","*","jim")  -> jim (when a single value is required)
+      %match("member","*","jim")  -> bob,dave (when a list is acceptable)
+  * regmatch(ATTRIBUTE,PATTERN[,DEFAULT])
+    - Selects the value of ATTRIBUTE which matches the extended regular
+      expression PATTERN.  If zero or two or more values match, and a
+      DEFAULT was specified, the DEFAULT is produced, otherwise an error
+      occurs.
+    - Example (examining "cn=group"):
+        dn: cn=group
+	member: bob
+	member: dave
+      %regmatch("member","^b.*")       -> bob
+      %regmatch("member","^d.*")       -> dave
+      %regmatch("member","e")          -> dave
+      %regmatch("member","^e")          FAILS
+      %regmatch("member","^e.*","jim") -> jim
+      %regmatch("member",".*","jim")   -> jim (when a single value is required)
+      %regmatch("member",".*","jim")   -> bob,dave (when a list is acceptable)
+  * regsub(ATTRIBUTE,PATTERN,TEMPLATE[,DEFAULT])
+    - Selects the value of ATTRIBUTE which matches the extended regular
+      expression PATTERN and uses TEMPLATE to construct the output.  If
+      zero or two or more values match, and a DEFAULT was specified, the
+      DEFAULT is produced, otherwise an error occurs.  The template is
+      used to construct a result using the n'th substring from the
+      matched value by using the sequence "%n" in the template.
+    - Example (examining "cn=group"):
+        dn: cn=group
+	member: bob
+	member: dave
+      %regsub("member","o","%0")          -> bob
+      %regsub("member","o","%1")          -> 
+      %regsub("member","^o","%0")         FAILS
+      %regsub("member","^d(.).*","%1")    -> a
+      %regsub("member","^(.*)e","t%1y")   -> tdavy
+      %regsub("member","^e","%1")         FAILS
+      %regsub("member","^e.*","%1","jim") -> jim
+  * deref(THISATTRIBUTE,THATATTRIBUTE)
+    - Creates a separated list of the values of THATATTRIBUTE for
+      directory entries named by this entry's THISATTRIBUTE.  Will fail
+      if used to attempt to generate an RDN.
+    - Example (examining "cn=group"):
+        dn: cn=group
+	member: uid=bob
+	member: uid=pete
+        -
+	dn: uid=bob
+	uid: bob
+        -
+	dn: uid=pete
+	uid: pete
+      %deref(",","member","foo") -> FAIL     (when a single value is required)
+      %deref(",","member","foo") ->          (when a list is acceptable)
+      %deref(",","member","uid") -> FAIL     (when a single value is required)
+      %deref(",","member","uid") -> bob,pete (when a list is acceptable)
+  * referred(SET,THATATTRIBUTE,THATOTHERATTRIBUTE)
+    - Creates a separated list of the values of THATOTHERATTRIBUTE for
+      directory entries which have entries in the named SET and which
+      also have this entry's name as a value for THATATTRIBUTE.  Will
+      fail if used to attempt to generate an RDN.
+    - Example (examining "cn=group"):
+        dn: cn=group
+        -
+	dn: uid=bob
+	uid: bob
+	memberOf: cn=group
+        -
+	dn: uid=pete
+	uid: pete
+	memberOf: cn=group
+      %referred(",","memberof","foo") -> FAIL  (when a single value is required)
+      %referred(",","memberof","foo") ->       (when a list is acceptable)
+      %referred(",","memberof","uid") -> FAIL  (when a single value is required)
+      %referred(",","memberof","uid") -> bob,pete (when a list is acceptable)
+  * merge(SEPARATOR,EXPRESSION[,...])
+    - Evaluates and then creates a list using multiple expressions which
+      can evaluate to either single values or lists.
+    - Example (examining "cn=group"):
+        dn: cn=group
+	membername: jim
+	member: uid=bob
+	member: uid=pete
+        -
+	dn: uid=bob
+	uid: bob
+        -
+	dn: uid=pete
+	uid: pete
+      %merge(",","%{membername}","%deref(\"member\",\"uid\")") -> jim,bob,pete
diff --git a/doc/sch-plugin.ldif.in b/doc/sch-plugin.ldif.in
index 133199c..d7d621c 100644
--- a/doc/sch-plugin.ldif.in
+++ b/doc/sch-plugin.ldif.in
@@ -18,7 +18,6 @@ objectClass: extensibleObject
 ou: people
 schema-compat-container-group: cn=compat, @mysuffix@
 schema-compat-container-rdn: ou=people
-schema-compat-check-access: no
 schema-compat-search-base: @people@, @mysuffix@
 schema-compat-search-filter: objectclass=posixAccount
 schema-compat-entry-rdn: uid=%{uid}
@@ -37,13 +36,12 @@ objectClass: extensibleObject
 ou: group
 schema-compat-container-group: cn=compat, @mysuffix@
 schema-compat-container-rdn: ou=group
-schema-compat-check-access: no
 schema-compat-search-base: @groups@, @mysuffix@
 schema-compat-search-filter: objectclass=posixGroup
 schema-compat-entry-rdn: cn=%{cn}
 schema-compat-entry-attribute: objectclass=posixGroup
 schema-compat-entry-attribute: gidNumber=%{gidNumber}
 schema-compat-entry-attribute: memberUid=%{memberUid}
-schema-compat-entry-attribute: memberUid=%deref(",","member","uid")
-schema-compat-entry-attribute: memberUid=%referred(",","ou=people","memberOf","uid")
+schema-compat-entry-attribute: memberUid=%deref("member","uid")
+schema-compat-entry-attribute: memberUid=%referred("ou=people","memberOf","uid")