\begindata{text,539047692}
\textdsversion{12}
\template{default}
\define{global
}


\chapter{Overview of the White Pages}


\section{What is the White Pages?}  


The White Pages (WP) is a database of information about people.  It has been 
designed to support the needs of sites with thousands of users, replacing the 
standard UNIX single-file \typewriter{passwd} mechanism with a faster B-tree 
that is divided into many medium-sized files.  Note that a site WP does not 
completely replace the \typewriter{passwd(5)} mechanism; much of the 
information in the site WP B-tree is extracted from the site 
\typewriter{passwd} file. 


The site WP provides a superset of the information in the usual /etc/passwd 
file, including nicknames, special mail delivery addresses, forwarding 
addresses, alternate names, etc.  It can be extended to include additional 
information; instructions for extending a WP database can be found in the 
White Pages Programmer's reference in /usr/andew/doc/ams/WP.pgr.


\section{What Uses the White Pages?}  


There are, in general, two ways to use the WP software; either as the 
\bold{site} WP, or as a \bold{non-site} WP.  The site WP database resides in a 
specific directory, the name of which is consistent in every Andrew File 
System (AFS) cell: /afs/CELLNAME/service/wp/.  The consistent location of the 
site WP allows WP client programs to find the local site's, or any other 
site's, WP database from any cell. 


The site WP is intended to provide necessary information about all the people 
at that site to certain Andrew applications, such as the Andrew Message 
Delivery System (AMDS), the Andrew File System (AFS), and the \typewriter{ls} 
program.  These applications must be built with \italic{WHITEPAGES_ENV} 
defined before they will use a site WP.  The site WP can also be used by any 
other program via the WP interface routines described in the White Pages 
Programmer's Guide. 


Many Andrew installations will choose to use the WP software to provide for 
the Andrew applications mentioned above, but the software is also suited for 
other tasks that require a name-oriented, fast database.  A given application 
can choose to use the site WP database, another Andrew site's WP (if running 
AFS), or some other \bold{non-site} WP that has been built in another 
directory to contain different information.  Note that there is at most one 
site WP per Andrew installation, which always resides in a certain directory, 
but programmers can create and use other \bold{non-site} WP databases as they 
wish as long as they tell their application programs where to find them. 


\section{Installing and Maintaining the White Pages} 


The WP installation procedure is detailed in the document \bold{Installing the 
White Pages}, in /usr/andew/doc/ams/WP.ins.  The procedures for installing a 
site versus a non-site WP are slightly different, but the same tools are used 
to maintain either kind of WP. 


The WP database is completely built from human-readable database sources. WP 
maintenance involves modifying the sources and running the updating script 
wpbuild.  The document \bold{Maintaining the White Pages}, in 
/usr/andew/doc/ams/WP.adm, describes the format of the database source files, 
and provides instructions for making changes to them. 


\begindata{bp,537558784}
\enddata{bp,537558784}
\view{bpv,537558784,1697,0,0}
Copyright 1992 Carnegie Mellon University and IBM.  All rights reserved.

\smaller{\smaller{$Disclaimer: 

Permission to use, copy, modify, and distribute this software and its 

documentation for any purpose is hereby granted without fee, 

provided that the above copyright notice appear in all copies and that 

both that copyright notice, this permission notice, and the following 

disclaimer appear in supporting documentation, and that the names of 

IBM, Carnegie Mellon University, and other copyright holders, not be 

used in advertising or publicity pertaining to distribution of the software 

without specific, written prior permission.



IBM, CARNEGIE MELLON UNIVERSITY, AND THE OTHER COPYRIGHT HOLDERS 

DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING 

ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS.  IN NO EVENT 

SHALL IBM, CARNEGIE MELLON UNIVERSITY, OR ANY OTHER COPYRIGHT HOLDER 

BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY 

DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, 

WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS 

ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE 

OF THIS SOFTWARE.

 $

}}\enddata{text,539047692}