From 1ed71edbd0cb40ac00a4fd8f3664bfc179fc1de1 Mon Sep 17 00:00:00 2001 From: Nalin Dahyabhai Date: Wed, 23 Apr 2008 16:06:06 -0400 Subject: expand some more on the design --- doc/design.txt | 96 +++++++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 71 insertions(+), 25 deletions(-) (limited to 'doc/design.txt') diff --git a/doc/design.txt b/doc/design.txt index 4c1b52e..aa64e04 100644 --- a/doc/design.txt +++ b/doc/design.txt @@ -1,4 +1,4 @@ -=== Overview === +=== Design Overview === The NIS plugin module's aim is to serve up data from the directory server using the NIS protocols. It does this by doing what any gateway @@ -85,33 +85,79 @@ using data from the cache. │ NIS Protocol │──│ Map Cache │──│ Map Back End │──│ Data │ └──────────────┘ └───────────┘ └──────────────┘ └──────┘ -Which takes us to the current state of the work-in-progress. The NIS -protocol handler reads data from the map cache, and the map back end -uses SLAPI to populate the map cache at startup-time, as well as to -watch for changes in the directory's contents which would need to be -reflected in the map cache. +Which takes us to the current design. The NIS protocol handler reads +data from the map cache, and the map back end uses SLAPI to populate the +map cache at startup-time, as well as to watch for changes in the +directory's contents which would need to be reflected in the map cache. === Components === +== Protocol Handler == + This NIS protocol handler module takes the opportunity to set up listening sockets and register with the local portmapper at module -initialization time. It does so at this point because the directory +initialization time. (It does so at this point because the directory server has not yet dropped privileges, and the portmapper will not allow -registrations to unprivileged clients. The plugin then starts a -listening thread to handle NIS clients. Because NIS can be run over -either datagram or connected protocols, the plugin currently services -datagram requests iteratively, but it starts a new thread to handle -requests on behalf of each connected client. - -The map cache tracks maps by domain and can quickly answer whether or -not a domain is being served (by whether or not any maps are defined for -it). The current implementation is purely an in-memory one, and is -currently severely unoptimized. - -The backend interface module currently populates the map cache at -startup based on the in-directory configuration. It does not yet handle -entry additions, modifications, renames, or removal, so changes to the -directory contents are not at all reflected by the map cache until the -server is restarted. Additionally, the backend interface is currently -hard-coded to use the nisMap/nisObject schema, which while useful for -testing purposes, is not expected to be flexible enough for field use. +registrations to unprivileged clients.) The plugin then starts a +listening thread to handle its clients. + +[The plugin listens for datagram queries from clients, processing them + as they come in, as well as answering connections from clients. + Because connected clients may not always transmit an entire request at + once, and because the server may find itself unable to transmit an + entire response at once, it buffers traffic for connected clients, + multiplexing the work it does for all of its clients from inside of the + thread.] The actual protocol datagram parsing is performed by libnsl, + which is provided as a part of the C library. + +== Map Cache == + +The map cache keeps a dynamically-constructed set of maps in memory, +grouped by domain, and for each map maintains information regarding the +last time its contents were modified (to answer client requests for a +map's order). The map cache can quickly answer whether or not a domain +is being served by checking whether or not any maps are defined for it. +The definitions of which maps are served for which domains is +configurable via internal APIs -- the map cache itself has no forehand +knowledge of domain names, map names, or formats, as it merely models +data in the way that a NIS server might. + +== Back End == + +The backend interface module sets up and maintains the map cache. At +startup time, it configures the map cache with the list of domains and +maps, and populates the maps 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 maps in the map cache, and to +add, remove, or update entries in the map cache's maps, thereby ensuring +that the map cache always reflects 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: + * domain + * map + * base + * filter + * key + * value +The backend then instructs the map cache to prepare to hold a map in the +given domain with the given map name, and then performs a subtree search +under the specified base for entries which match the provided filter. +Each found entry is then "added" to the map, using the value of the +attribute named by the "key" as the key for the entry in the map[, with +the corresponding value being constructed using the format specifier +given as the "value"]. + +[The filter, key, and value have sensible defaults for the maps which we + expect to be using -- this is important because it's easy to subtly + construct malformed result strings which could trigger undefined + behavior on clients -- for example by leaving the user's numeric UID + empty in a passwd entry, which may be treated as "0" by inattentive + clients.] + +[The format specifier includes function-like invocations to allow the + backend to be instructed to chase references to other entries, for + example to handle flattening of nested groups or netgroups.] -- cgit