- notes on the map cache layout, and nis-values-format

1 files changed, 36 insertions, 8 deletions

diff --git a/doc/nis-design.txt b/doc/nis-design.txt
index 8725119..7c062a6 100644
--- a/doc/nis-design.txt
+++ b/doc/nis-design.txt
@@ -121,12 +121,16 @@ also ignored, even for connected clients.
 Client access is limited by the local tcp_wrappers configuration on the
 directory server, with a tcp_wrappers service name as dictated by the
 "nis-tcp-wrappers-name" attribute (by default, "nis-plugin") in the
-plugin's configuration.
+plugin's configuration.  If the tcp_wrappers configuration denies access
+for the client, a connected client's connection will be closed, and a
+datagram client's request will be discarded.
 
 Client requests are also limited based on a client's address using
 "securenet"-style settings in the module's configuration entry's
 "nis-securenet" attribute.  If no values are specified, access is
-allowed to all clients.
+allowed to all clients.  If the securenet configuration denies access
+for the client, a connected client's connection will be closed, and a
+datagram client's request will be discarded.
 
 Client requests are further classed as "secure" or not, based on the
 query's originating port.  This information is used elsewhere for
@@ -164,6 +168,26 @@ alternate approach of performing an LDAP query for each NIS query:
   query, we don't have to worry about escaping text to avoid string
   injection attacks.
 
+=== Internal Representation ===
+
+At the topmost level, the map cache is a table.  Each entry in the table
+is the name of a domain and a table of maps.
+
+Each entry in a domain's table of maps contains the map's name, the time
+the map was last modified, a note indicating whether or not the map is a
+"secure" map, a linked list of map entries, and a set of indexes into
+the list.  Each map can also hold a data pointer on behalf of the
+backend.
+
+Each item in the map's list of entries contains an array of NIS keys, an
+array of corresponding values, a unique identifier (which, currently,
+stores the NDN of the directory server entry which was used to create
+this list item) and a data pointer which is kept on behalf of the
+backend.
+
+The map indexes its entry list using an entry's unique identifier, and
+each of its keys.
+
 == Back End ==
 
 The backend interface module sets up, populates, and maintains the map
@@ -187,6 +211,7 @@ plugin's entry, the backend checks for entries with these attributes:
  * nis-key-format
  * nis-keys-format
  * nis-value-format
+ * nis-values-format
 The backend then instructs the map cache to prepare to hold a map in the
 given domain (or domains) with the given map name (or names), and then
 performs a subtree search under the specified base (or bases, if there's
@@ -195,13 +220,16 @@ filter.  Each entry found is then "added" to the map, using the format
 specifiers stored in the "nis-key-format" and "nis-keys-format"
 attributes to construct the keys for the entry in the map, with the
 corresponding value in the map being constructed using the format
-specifier stored in the "nis-value-format" attribute.  The map is marked
-as a "secure" map according to the "nis-secure" attribute, if so set.
+specifiers stored in the "nis-value-format" and "nis-values-format"
+attributes.  The map is also marked as a "secure" map according to the
+"nis-secure" attribute, if so set.
 
 For each "nis-key-format" value, exactly one entry will be created in a
-NIS map.  For each "nis-keys-format" value, any number of entries will
-be created in a NIS map.  The method by which these attributes (and the
-"nis-value-format") are interpreted is described below.
+NIS map.  (If a "nis-key-format" does not yield a single value, the
+directory server entry will not appear in the NIS map.)  For each
+"nis-keys-format" value, any number of entries will be created in a NIS
+map.  The method by which these attributes (and the "nis-value-format"
+and "nis-value-formats") are interpreted is described below.
 
 Should one of the directory server entries which was used to construct
 one or more NIS map entries be modified or removed, the corresponding
@@ -263,7 +291,7 @@ need to escape the double-quote using a '\' character.  Naturally the
 === Implemented Functions ===
   * first(PATTERN[,DEFAULT])
     - Evaluates the pattern, and if one or more values is available,
-      provides that value.  If no values result, then DEFAULT is
+      provides the first value.  If no values result, then DEFAULT is
       evaluated as a pattern and the result is provided.
   * match(ATTRIBUTE,PATTERN[,DEFAULT])
     - Selects the value of ATTRIBUTE which matches the globbing pattern