PSARC/2008/035 nss versioning API draft

nss versioning API -- PSARC/2008/035

Note, this was approved as PSARC/2008/035 -- Jan 23, 2008

See finder APIs
for the additional Duckwater nss2 and finder API enhancements.

Overview

This document defines the new nsswitch versioning interfaces
and extensions to the finder APIs to detect extended characteristics
of a nsswitch backend, including new switch API interface.

The intent of the versioning and finder APIs is to provide
efficient, upward compatible and extensible APIs that allow for
the addition of new XbyYs [get/put/ent etc.], configuration
interfaces (duckwater) and other extendable nscd APIs.

Backend Versioning

Currently the name service switch has two classes of backends.

The first class of backends are pre PSARC/2005/133 backends.
These are any backend that has not been updated to behave with
the new name service switch engine in nscd, and subsequent
versionable changes.  These backends are considered 'foreign'
to the new name service switch engine.  The new name service
switch engine returns requests that need to use a foreign
backend to the original (obsolete) libc name service switch
using the TRYLOCAL protocol for local processing on the client.

Databases using an old style backend are generally not cached.

The second class of backends are backends that have been updated
to support the new interfaces.  Nscd has a built-in "knowledge" of
a core set of these backends that are delivered in unison with nscd
in the ON consolidation.  These backends are required to always
adhere to all the current latest [post PSARC/2005/133] nsswitch
specifications.  These are the backends that are used to test and
qualify the name service switch in ON at each build/delivery.

The current well known/built-in backends are those located in the
ON consolidation tree:  usr/src/lib/nsswitch.  They currently include
  compat, dns, files, ldap, mdns, nis, nisplus user

All other backends fall into one of the other categories.

Versioned backends

Additionally, nscd will, through the use of new finder APIs,
check for updated backends that support versioning.

Versioned backends have at a minimum an externally defined version
global symbol [dlsym retrievable] of the form:

    \//nss\//[backend-name]~_version

where backend-name corresponds to the backend name used in nsswitch.conf
as in:

    ~_nss~_nis~_version, ~_nss~_files~_version etc.

Existence of the symbol implies compliance with the specifications of
PSARC/2005/133.

The contents of the variable is treated as a castable (void *) pointer
in the native pointer size for the compiled library.

If the pointer is NULL, then the library meets the minimal specifications
from PSARC/2005/133 only.  If the pointer is non NULL, then the contents of
the variable is considered to be a pointer to a nss_version structure
defined below.  This structure will be searched for using new finder APIs
and then used [when set] provide additional post PSARC/2005/133
version information.