  libuser 0.52.2
  Nalin Dahyabhai <nalin@redhat.com>
  28 September 2004

  This is the libuser administrator and programmer's guide. It first
  describes the motivation for the existence of this library, and then
  delves into the library interface used by both libuser modules and
  applications.

  11..  IInnttrroodduuccttiioonn

  This section describes libuser: why it was written, and how it works.
  How the library is to be used will be described later.

  11..11..  MMoottiivvaattiioonn

  When proper nsswitch functionality was introduced into glibc 2.0, it
  became possible to supply third-party facilities which would allow the
  standard C library (and by extension, all of a system's binaries) to
  pull information about users, protocols, and services from a variety
  of sources the glibc authors might not have anticipated.

  The most common use for a new nsswitch module is supplementing the
  user and group databases, extending the data sources accessed over a
  network to a centrally-managed information store. This, along with the
  ability to authenticate users using networked servers (functionality
  provided by the increasingly-ubiquitous Linux-PAM library) and an
  enterprise-class networked filesystem, allows a properly-configured
  Linux workstation to participate as a full-fledged client in a large-
  scale network.

  The facilities provided by PAM allow a user to log in and change her
  authentication tokens. The nsswitch interface allows any user (even
  unprivileged users like nnoobbooddyy) to look up information needed to run
  applications.

  However, there are certain functions supplied by traditional isolated
  systems which such a networked workstation can't provide. Users have
  no method for modifying their non-essential information (cchhffnn is
  broken), and the system administrator who previously had total power
  over the user and group databases must now perform all administration
  at the server using tools which are designed for general modification
  of the information store (hand-editing zone files for hesiod
  databases, llddaappmmooddiiffyy, kkaaddmmiinn) instead of the traditionally-used
  tools.

  11..22..  AAlltteerrnnaattiivvee SSoolluuttiioonnss

  The software which comes closest to meeting these needs is ppwwddbb.
  However, the pwdb library has a few design limitations which make it
  unsuitable for this purpose. Like the standard files-based mechanisms,
  pwdb assumes that the superuser wields full power over the databases
  it interfaces with. The current version of pwdb provides no facilities
  for managing groups(?). The current version of pwdb can not be
  extended easily by third parties due to its reliance on static
  linking.

  11..33..  TThhee lliibbuusseerr LLiibbrraarryy

  The libuser library implements a fully-modular system for reading,
  modifying, creating, and removing user and group accounts and account
  information. Modules which provide access to information stores can
  request information from the accessing user in order to authenticate
  to the information store.

  22..  SSyysstteemm AAddmmiinniissttrraattiioonn

  This section describes libuser's configuration file and bundled
  applications which may be of use to system administrators.

  22..11..  CCoonnffiigguurraattiioonn

  The libuser configuration file is named lliibbuusseerr..ccoonnff and usually lives
  in //eettcc. Its format is the common format used by numerous other
  programs. Sections are marked by the section name enclosed in square
  brackets ([[sseeccttiioonn]]), and configuration directives within these
  sections are of the form kkeeyy == vvaalluuee.

  The ddeeffaauullttss, uusseerrddeeffaauullttss, and ggrroouuppddeeffaauullttss sections are used by the
  library itself. The ddeeffaauullttss section specifies the directory where
  modules can be found (mmoodduulleeddiirr) and lists the modules to be consulted
  when looking up user information.

  There are two lists of modules because lliibbuusseerr separates an account's
  authentication information from other information. This is done to
  allow different information stores to be used for these functions, and
  because some information stores can only hold authentication data (for
  example, shadow).

  For the iinnffoo__mmoodduulleess and aauutthh__mmoodduulleess lists, order is only important
  for account creation -- the library will attempt to create a data
  entry for the user in each of the modules until one of them succeeds
  (so if you prefer new accounts to be created in your LDAP directory,
  then you'd make sure "ldap" was listed _b_e_f_o_r_e "files"). For looking up
  account information, the order determines precedence because the
  library stops searching after a module returns success (so again,
  you'd want "ldap" listed before "files").  Account modifications and
  deletions go straight to the information store which is known to hold
  the user's information.

  22..22..  MMoodduulleess

  Specific modules implement access to specific information stores. The
  modules included in the source distribution are the ffiilleess and sshhaaddooww
  modules. Modules can supply and manipulate either (or both) of two
  distinct types of data about a user: generic user information (the
  UID, home directory, etc.), and authentication-related information.

  22..22..11..  ffiilleess

  The files module implements both information and authentication data
  stores using the standard ppaasssswwdd and ggrroouupp files.

  This module uses the ffiilleess section of the configuration file to store
  configuration data. It presently recognizes these flags:


  +o  directory - the directory the ppaasssswwdd and ggrroouupp files are to be
     stored in

  22..22..22..  sshhaaddooww

  The shadow module implements only an authentication data store using
  the sshhaaddooww and the ggsshhaaddooww files. While the format of these files (and
  even the existence of the ggsshhaaddooww file) varies between OSs, this
  module supports the same file formats used by the shadow password
  suite.

  This module uses the sshhaaddooww section of the configuration file to store
  configuration data. It presently recognizes these flags:


  +o  directory - the directory the sshhaaddooww and ggsshhaaddooww files are to be
     stored in.

  22..22..33..  llddaapp

  The ldap module implements both information and authentication data
  stores using an LDAP directory and a schema which (should) conform to
  RFC2307. The module expects the client and server to support access
  using LDAPv3 with TLS; TLS is not required if the server is specified
  by URI.

  This module uses the llddaapp section of the configuration file to store
  configuration data. It presently recognizes these flags:


  +o  server - the hostname or URI of the LDAP server

  +o  basedn - the distinguished name which is the root of your tree

  +o  user - the user name with which to perform SASL binds

  +o  authuser - the authorization user name with which to perform SASL
     binds

  +o  binddn - the distinguished name to connect as for administrative
     access

  +o  userBranch - the distinguished name (relative to the basedn) under
     which user account data is kept

  +o  groupBranch - the distinguished name (relative to the basedn) under
     which group account data is kept

  22..33..  AApppplliiccaattiioonnss

  Sample testbed applications which mimic the behavior of certain parts
  of the shadow password suite are included in the libuser distribution.
  To allow them to be used alongside existing utilities, their names
  have been prefixed with the letter 'l'.

  As of this writing (version 0.7), this list of tools includes
  workalikes for uusseerraadddd, uusseerrmmoodd, uusseerrddeell, ggrroouuppaadddd, ggrroouuppmmoodd,
  ggrroouuppddeell, and cchhaaggee.  It should be noted that none of these tools
  provide a means for modifying the defaults they use, and no functions
  for creating, populating, moving, or deleting user home directories
  are implemented.



