Return to configuration.tex CVS log

Up to [CSRG BSD Unix] / 43BSDReno / contrib / isode-beta / doc / whitepages / administrator

Annotation of 43BSDReno/contrib/isode-beta/doc/whitepages/administrator/configuration.tex, revision 1.1

1.1     ! root        1: % run this through LaTeX with the appropriate wrapper
        !             2: 
        !             3: \chapter      {Installation and Configuration}\label{installation}
        !             4: This chapter describes how to install, configure, and test the pilot project
        !             5: software.
        !             6: Upon completion,
        !             7: your Level-1 DSA will have successfully joined the pilot project DMD!
        !             8: 
        !             9: \section      {Software}
        !            10: The software supporting the pilot project is the QUIPU implementation
        !            11: of the OSI Directory,
        !            12: which is a part of the ISO Development Environment (ISODE).
        !            13: 
        !            14: QUIPU was originally developed as a part of the INCA project
        !            15: (under the auspices of the ESPRIT initiative of the EEC).
        !            16: The Inca of Peru did not have writing.
        !            17: Instead,
        !            18: they stored information on strings,
        !            19: carefully knotted in a specific manner with colored thread,
        !            20: and attached to a larger rope.
        !            21: Such a device was known as a {\em Quipu\/}
        !            22: (pronounced {\em kwip-ooo}).
        !            23: The encoding was obscure,
        !            24: and could only be read by selected trained people:
        !            25: the {\em Quipucamayocs}.
        !            26: The Quipu was a key component of Inca society,
        !            27: as it contained information about property and locations throughout
        !            28: the extensive Inca empire.
        !            29: 
        !            30: The pilot sponsors and the administrators of the participating organizations
        !            31: form the {\em camayocs\/} for the pilot project.
        !            32: There is a special mailing list
        !            33: \begin{quote}\small\begin{verbatim}
        !            34: [email protected]
        !            35: \end{verbatim}\end{quote}
        !            36: which each \camayoc/ belongs to.
        !            37: 
        !            38: \[\fbox{\begin{tabular}{lp{0.8\textwidth}}
        !            39: \bf NOTE:&     This is the official mailing list for administrators of the
        !            40:                pilot project.
        !            41:                If you have a problem, send mail!
        !            42: \end{tabular}}\]
        !            43: 
        !            44: \subsection    {Selecting a Machine}
        !            45: The machine you run the software on should support the Berkeley variant of
        !            46: \unix/.
        !            47: Although the software is known to run on other variants of \unix/, such as
        !            48: those from AT\&T and HP,
        !            49: these configurations are not supported by the pilot sponsors.
        !            50: 
        !            51: You should plan on the DSA consuming 2Kbytes of memory {\em per\/} entry kept
        !            52: in your DMD
        !            53: This is called the QUIPU {\em 2K rule}.
        !            54: Make sure that your machine has available memory for the DSA.
        !            55: A memory-constrained (or worse yet, paging DSA) performs extremely poorly.
        !            56: Find an unloaded system to run your DSA.
        !            57: This investment might seem large,
        !            58: just think of it as a sunk cost.
        !            59: 
        !            60: \subsection    {Files}
        !            61: Regardless of how you install QUIPU and the ISODE,
        !            62: the number of files needed for the pilot project are quite small.
        !            63: 
        !            64: In ISODE's \verb"BINDIR" directory,
        !            65: typically \file{/usr/local/bin/},
        !            66: there are a few programs of interest:
        !            67: \begin{describe}
        !            68: \item[dish:]   The DIrectory SHell\\
        !            69:                This is a interface to the OSI Directory which can be used to
        !            70:                access the full functionality of the Directory service.
        !            71:                This program is not directly run by the ``users'' of the pilot
        !            72:                project, rather various front-ends access \pgm{dish}.
        !            73:                In addition,
        !            74:                the administrators employ this program directly to perform
        !            75:                routine maintenance and diagnostics.
        !            76: 
        !            77: \item[bind:]   Shell interface to \pgm{dish}\\
        !            78:                There are actually several links to a program called
        !            79:                \pgm{bind}.
        !            80:                These act to export the \pgm{dish} interface to the \unix/
        !            81:                shell.
        !            82:                As such,
        !            83:                you can issue commands to \pgm{dish} from the shell,
        !            84:                rather than running \pgm{dish} directly.
        !            85: \begin{quote}
        !            86: \begin{tabular}{l}
        !            87: add\\
        !            88: compare\\
        !            89: delete\\
        !            90: dsacontrol\\
        !            91: list\\
        !            92: modify\\
        !            93: modifyrdn\\
        !            94: moveto\\
        !            95: search\\
        !            96: showentry\\
        !            97: showname\\
        !            98: squid
        !            99: \end{tabular}
        !           100: \end{quote}
        !           101: 
        !           102: \item[fred:]   A white pages user interface\\
        !           103:                This is the interface for the users of the pilot project.
        !           104: 
        !           105: \item[editentry:]      Edit a Directory entry\\
        !           106:                This is a simple shell script that \pgm{dish} invokes when you
        !           107:                ask \pgm{dish} to edit an entry in the Directory.
        !           108: 
        !           109: \item[unbind:] Unbind from \pgm{dish}\\
        !           110:                This command is used to terminate \pgm{dish}.
        !           111: \end{describe}
        !           112: In ISODE's \verb"SBINDIR" directory,
        !           113: typically \file{/usr/etc/},
        !           114: the DSA resides:
        !           115: \begin{describe}
        !           116: \item[ros.quipu:]      The QUIPU DSA\\
        !           117:                        This program will be started once, for each DSA you
        !           118:                        are running, from rc.local.
        !           119:                        A script is provided to invoke this program,
        !           120:                        in case you need to restart it.
        !           121: 
        !           122: \item[dsaconfig:]      a configurator for Level-1 DSAs.
        !           123: \end{describe}
        !           124: In ISODE's \verb"ETCDIR" directory,
        !           125: also typically \file{/usr/etc/},
        !           126: there are a few programs and files of interest:
        !           127: \begin{describe}\sloppy
        !           128: \item[oidtable.at, oidtable.gen, oidtable.oc:]
        !           129:                        These define the attribute types,
        !           130:                        generic object identifiers,
        !           131:                        and object classes known to the system.
        !           132:                        (An object identifier is a method used to unambiguously
        !           133:                        encode, among other things,
        !           134:                        the names of attributes and object classes.)
        !           135:                        These files you never deal with unless they are
        !           136:                        accidently corrupted.
        !           137:                        
        !           138: \item[dsaptailor:]     This is the run-time tailor file for the DUAs.
        !           139:                        You will configure this file initially and then
        !           140:                        probably leave it alone.
        !           141: 
        !           142: 
        !           143: \item[isoaliases, isobjects, isoentities, isomacros, isoservices:]
        !           144:                        These are \\ %%%
        !           145:                        various databases used by the ISODE.
        !           146:                        These files you never deal with unless they are
        !           147:                        accidently corrupted.
        !           148: 
        !           149: \item[isologs:]                This script runs nightly under \man cron(8) to
        !           150:                        trim the ISODE log files, kept in ISODE's \verb"LOGDIR"
        !           151:                        directory,
        !           152:                        typically \file{/usr/tmp/}.
        !           153:                        This file you never deal with unless it is
        !           154:                        accidently corrupted.
        !           155: 
        !           156: \item[isotailor:]      This is the run-time tailor file for the ISODE.
        !           157:                        You will configure this file initially and then
        !           158:                        probably leave it alone.
        !           159: \end{describe}
        !           160: There are a few other things kept in a directory called \file{quipu/}
        !           161: which resides in ISODE's \verb"ETCDIR" directory.
        !           162: The \file{scripts/} directory contains various scripts which may be used for
        !           163: maintenance purposes.
        !           164: The \file{templates/} directory contains templates of entries.
        !           165: 
        !           166: \subsection    {Source Release}
        !           167: You should retrieve a copy of the pilot software.
        !           168: It is available via anonymous FTP from from host
        !           169: \verb"nisc.nyser.net" (\verb"[192.33.4.10]"):
        !           170: \begin{quote}\small\begin{verbatim}
        !           171: % cd /usr/src/local/
        !           172: % ftp nisc.nyser.net
        !           173: Connected to nisc.nyser.net.
        !           174: 220 nisc.nyser.net FTP server ready
        !           175: Name (nisc.nyser.net:user): anonymous
        !           176: Password (nisc.nyser.net:anonymous): guest
        !           177: 331 Guest login ok, send ident as password.
        !           178: 230 Guest login ok, access restrictions apply.
        !           179: ftp> binary
        !           180: 200 Type set to I.
        !           181: ftp> cd pilot/src
        !           182: ftp> get isode-pilot.tar.Z
        !           183: ftp> quit
        !           184: % uncompress < isode-pilot.tar.Z | tar xfp -
        !           185: % rm isode-pilot.tar.Z
        !           186: \end{verbatim}\end{quote}
        !           187: Note that this is a interim release of the ISODE.
        !           188: All of the changes are upwards compatible,
        !           189: but you must run this version rather than the standard ISODE~5.0 release.
        !           190: 
        !           191: Now change to the top-level directory.
        !           192: \begin{quote}\small\begin{verbatim}
        !           193: % cd isode-5.9/
        !           194: \end{verbatim}\end{quote}
        !           195: The file \file{READ-ME} in this directory contains instructions on how to
        !           196: configure, generate, and install the ISODE.
        !           197: 
        !           198: \[\fbox{\begin{tabular}{lp{0.8\textwidth}}
        !           199: \bf NOTE:&     The source installation instructions are intended for
        !           200:                sites which are not already running QUIPU.
        !           201:                If you are,
        !           202:                care should be taken to see that your existing Directory
        !           203:                environment is not compromised.
        !           204:                For example,
        !           205:                the DSAs run under the pilot do not provide the
        !           206:                ``higher performance'' name service,
        !           207:                nor is it intended that they support application entities
        !           208:                other than DSAs.
        !           209: \end{tabular}}\]
        !           210: 
        !           211: \subsubsection {Configuration of the ISODE}
        !           212: As described in the \file{READ-ME} file,
        !           213: configuration is straight-forward.
        !           214: Here's an example of how it's done on a Sun workstation running SunOS~3.5:
        !           215: \begin{quote}\small\begin{verbatim}
        !           216: % cp config/sunos3.h h/config.h
        !           217: % cp config/sunos3.make config/CONFIG.make
        !           218: % cp config/*.local support/
        !           219: \end{verbatim}\end{quote}
        !           220: For other systems,
        !           221: consult the \file{READ-ME} file to see which templates to use.
        !           222: For all systems,
        !           223: take a look at
        !           224: \[\begin{tabular}{l}
        !           225: \file{h/config.h}\\
        !           226: \file{config/CONFIG.make}\\
        !           227: \end{tabular}\]
        !           228: to see if things like \verb"BINDIR",
        !           229: \verb"SBINDIR", \verb"ETCDIR", and \verb"LOGDIR" are set to your liking.
        !           230: 
        !           231: \subsubsection {Generation of the ISODE}
        !           232: Once properly configured,
        !           233: generate both the ISODE and QUIPU using this command from the top-level
        !           234: directory:
        !           235: \begin{quote}\small\begin{verbatim}
        !           236: % ./make once-only all all-quipu
        !           237: \end{verbatim}\end{quote}
        !           238: This takes a while,
        !           239: so its best to redirect the output to a file and then go do something else for
        !           240: a few hours:
        !           241: \begin{quote}\small\begin{verbatim}
        !           242: % ./make once-only all all-quipu >& make.out &
        !           243: \end{verbatim}\end{quote}
        !           244: 
        !           245: If the make command finishes with a non-zero exit status,
        !           246: or if you see a line with:
        !           247: \begin{quote}\small\begin{verbatim}
        !           248: *** Error code 1
        !           249: \end{verbatim}\end{quote}
        !           250: or perhaps
        !           251: \begin{quote}\small\begin{verbatim}
        !           252: Exit
        !           253: \end{verbatim}\end{quote}
        !           254: Then something has gone wrong.
        !           255: Try and determine what the problem is.
        !           256: If you are unable to find the problem,
        !           257: drop a note to the Internet Mailbox
        !           258: \begin{quote}\begin{verbatim}
        !           259: [email protected]
        !           260: \end{verbatim}\end{quote}
        !           261: Your message should contain your two configuration files,
        !           262: the output of the make command,
        !           263: and a description of the hardware/software platform you are using.
        !           264: 
        !           265: Keep in mind that the ISODE runs ``flawlessly'' worldwide on many thousands of
        !           266: machines running numerous variants of \unix/.
        !           267: Failure to complete generation usually indicates a broken configuration file,
        !           268: or a non-standard system
        !           269: (i.e., one with a broken compiler or a different \pgm{make} command).
        !           270: 
        !           271: Now generate the additional commands needed for the pilot project:
        !           272: \begin{quote}\small\begin{verbatim}
        !           273: % (cd others/quipu; ./make pilot)
        !           274: \end{verbatim}\end{quote}
        !           275: 
        !           276: \subsubsection {Installation of the ISODE}\label{isode:install}
        !           277: Once you are satisfied that the generation was successful,
        !           278: become the super-user and install both the ISODE and QUIPU.
        !           279: First make sure that the directories \verb"BINDIR",
        !           280: \verb"SBINDIR",
        !           281: \verb"ETCDIR",
        !           282: \verb"LOGDIR",
        !           283:  as defined in \file{config/CONFIG.make} exist.
        !           284: If not, create them using \pgm{mkdir}.
        !           285: The protection on the \verb"LOGDIR" directory should be 0777.
        !           286: 
        !           287: Next, install the programs, databases, and libraries:
        !           288: \begin{quote}\small\begin{verbatim}
        !           289: # ./make inst-all inst-quipu
        !           290: # (cd others/quipu; ./make inst-pilot)
        !           291: \end{verbatim}\end{quote}
        !           292: 
        !           293: Do {\bf not\/} perform any other installation instructions for QUIPU as
        !           294: given in the \file{READ-ME} file.
        !           295: The remainder of this chapter supercede those instructions.
        !           296: 
        !           297: If you are not planning on doing program development (probably a safe bet),
        !           298: you can remove the various libraries and program development tools by using
        !           299: \begin{quote}\small\begin{verbatim}
        !           300: # ./make zap
        !           301: \end{verbatim}\end{quote}
        !           302: from the \file{isode-5.9/} directory as the super-user.
        !           303: 
        !           304: \section      {Starting the ISODE}
        !           305: In order to aid debugging,
        !           306: you should keep the ISODE system around in an operational state.
        !           307: So,
        !           308: you need to do a few more things:
        !           309: \begin{enumerate}
        !           310: \item  Verify that the file \file{/etc/rc.local} has an entry like this:
        !           311: \begin{quote}\small\begin{verbatim}
        !           312: if [ -f $(SBINDIR)tsapd ]; then
        !           313:    $(SBINDIR)tsapd -t & (echo -n ' tsap') > /dev/console
        !           314: fi
        !           315: \end{verbatim}\end{quote}
        !           316: in the section where the network servers are started
        !           317: (e.g., where \man sendmail(8) is started).
        !           318: 
        !           319: \item  Verify that the file \file{/etc/services} has an entry like this:
        !           320: \begin{quote}\small\begin{verbatim}
        !           321: tsap    102/tcp
        !           322: \end{verbatim}\end{quote}
        !           323: 
        !           324: \item  Verify that the file \file{/usr/lib/crontab} has an entry similar 
        !           325: to this:
        !           326: \begin{quote}\small\begin{verbatim}
        !           327: 0 4 * * * su daemon < $(SBINDIR)isologs
        !           328: \end{verbatim}\end{quote}
        !           329: or this
        !           330: \begin{quote}\small\begin{verbatim}
        !           331: 0 4 * * * su daemon -c "/bin/sh $(SBINDIR)isologs"
        !           332: \end{verbatim}\end{quote}
        !           333: This runs a script to clean-up the logfiles at 4:00am each morning.
        !           334: 
        !           335: \item  Start the \man tsapd(8c) daemon by hand:
        !           336: \begin{quote}\small\begin{verbatim}
        !           337: # $(SBINDIR)tsapd -t >& /dev/null
        !           338: \end{verbatim}\end{quote}
        !           339: The daemon will automatically detach.
        !           340: Instead,
        !           341: if its diagnostic output is associated with a terminal,
        !           342: then the daemon will not detach and will log informative messages to
        !           343: the terminal.
        !           344: 
        !           345: \item  Now verify that the ISODE is installed and tailored correctly.
        !           346: See Sections~\ref{isode:tailoring} and~\ref{isode:testing}.
        !           347: \end{enumerate}
        !           348: 
        !           349: \section      {ISODE Tailoring}\label{isode:tailoring}
        !           350: Before any DSAs or DUAs are installed,
        !           351: the file \file{isotailor} in the ISODE \verb"ETCDIR" directory should be
        !           352: properly configured. 
        !           353: 
        !           354: Typically source installations have ISODE's \verb"ETCDIR" and \verb"LOGDIR"
        !           355: directories hard-wired in during configuration of the ISODE.
        !           356: As such,
        !           357: the source installation procedures do not install a \file{isotailor} file.
        !           358: If a future need arises,
        !           359: the \file{isotailor} file may be modified accordingly.
        !           360: Initially it is recommended that you use a tailoring file which contains
        !           361: no commands;
        !           362: copy it from the \file{quipu/scripts/} area:
        !           363: \begin{quote}\small\begin{verbatim}
        !           364: # cp $(ETCDIR)quipu/scripts/isotailor.empty $(ETCDIR)isotailor
        !           365: \end{verbatim}\end{quote}
        !           366: 
        !           367: \section      {Testing of the ISODE}\label{isode:testing}
        !           368: The easiest way to test the ISODE system is to run
        !           369: the \file{isode-test} script in the directory \file{quipu/scripts/}
        !           370: under ISODE's \verb"ETCDIR" directory.
        !           371: \begin{quote}\small\begin{verbatim}
        !           372: % isode-test
        !           373: \end{verbatim}\end{quote}
        !           374: Prior to termination,
        !           375: the script will indicate the number of errors encountered.
        !           376: If an error occurs,
        !           377: try and determine what the problem is.
        !           378: If you are unable to find the problem,
        !           379: drop a note to the Internet Mailbox \verb"[email protected]".
        !           380: Your message should contain your two configuration files,
        !           381: the output of \file{isode-test},
        !           382: and a description of the hardware/software platform you are using.
        !           383: 
        !           384: \section      {Configuration of DUAs}\label{dua:configure}
        !           385: The first step will be to have the \man dish(1c) program
        !           386: try to connect to one of the Level-0 DSAs in the pilot project:
        !           387: \begin{quote}\small\begin{verbatim}
        !           388: % dish -c "Alpaca"
        !           389: Welcome to Dish (DIrectory SHell)
        !           390: Dish ->
        !           391: \end{verbatim}\end{quote}
        !           392: indicates that you are able to connect.
        !           393: You might now try some simple commands.
        !           394: Figure~\ref{dish-simple} shows a small interaction.
        !           395: Chapter~4 of \volfive/ describes \pgm{dish} in considerable detail.
        !           396: \tagfigure[tp]{CNF-1}{A Small DISH Interaction}{dish-simple}
        !           397: 
        !           398: \subsection    {DUA Failure}\label{dua:failure}
        !           399: There are a few reasons why the DUA might fail.
        !           400: First verify that the ISODE is operating correctly
        !           401: (see Section~\ref{isode:testing} on page~\pageref{isode:testing}.)
        !           402: If the ISODE is working,
        !           403: then here is the most common error encountered:
        !           404: 
        !           405: If instead of the \verb"Dish ->" prompt,
        !           406: you see:
        !           407: \begin{quote}\small\begin{verbatim}
        !           408: *** Service error : Unable to contact DSA ***
        !           409: \end{verbatim}\end{quote}
        !           410: then it is likely that there is some problem with the network,
        !           411: or you have mistyped the name of the DSA.
        !           412: If you see any other diagnostic,
        !           413: contact a \camayoc/ for help.
        !           414: 
        !           415: Otherwise,
        !           416: first check the spelling of the name you are providing.
        !           417: If this is correct,
        !           418: then look at the file \file{dsaptailor} in the ISODE \verb"ETCDIR" directory
        !           419: for the line which starts with:
        !           420: \begin{quote}\small\begin{verbatim}
        !           421: dsa_address "Alpaca"
        !           422: \end{verbatim}\end{quote}
        !           423: You will find an Internet address and TCP port number on the rest of
        !           424: the line.
        !           425: \begin{enumerate}
        !           426: \item  Use the \man ping(8c) utility to see if you can reach the IP address.
        !           427: 
        !           428: \item  If not,
        !           429:        then try contacting one of the other DSAs,
        !           430:        e.g., \verb"Fruit Bat",
        !           431:        listed in the \file{dsaptailor} file.
        !           432:        
        !           433:        Repeat this process until \pgm{dish} successfully contacts a DSA.
        !           434: 
        !           435: \item  If \pgm{ping} can reach the IP address,
        !           436:        then use \pgm{telnet} to try to connect to the TCP port.
        !           437: 
        !           438: \item  If you can connect,
        !           439:        immediately close the connection.
        !           440:        Something is drastically wrong since \pgm{telnet} can reach the TCP
        !           441:        address of the DSA,
        !           442:        but \pgm{dish} can't.
        !           443:        Contact a \camayoc/ for assistance.
        !           444: 
        !           445: \item  If \pgm{telnet} reports an error,
        !           446:        usually
        !           447: \begin{quote}\small\begin{verbatim}
        !           448: Connection refused
        !           449: \end{verbatim}\end{quote}
        !           450:        then this indicates that the DSA isn't listening at that TCP
        !           451:        address.
        !           452:        Either it is temporarily unavailable or it has moved to a new
        !           453:        address.
        !           454:        In either event,
        !           455:        notify a \camayoc/ of the situation.
        !           456:        Then go back to Step~2 above.
        !           457: \end{enumerate}
        !           458: If you exhaust all DSAs listed in the \file{dsaptailor} file,
        !           459: contact a \camayoc/ and give up.
        !           460: 
        !           461: \section      {An Important Note}
        !           462: The configuration instructions contained herein are for sites in the United
        !           463: States.
        !           464: Depending on the policies of the administrators for other national DMDs,
        !           465: these instructions may, or may not, be useful. 
        !           466: If your DSA is joining a DMD other than that of c=US,
        !           467: then you should contact your national administrator to see what turn-key
        !           468: procedures exist for joining your national DMD.
        !           469: 
        !           470: Note that the \man dsaconfig(8) program can be used to configure Level-1 DSAs
        !           471: residing outside of the c=US DMD.
        !           472: At present,
        !           473: the current list of supported countries is:
        !           474: \[\begin{tabular}{l}
        !           475: AU\\ DE\\ ES\\ FI\\ GB\\ IS\\ NO\\ SE
        !           476: \end{tabular}\]
        !           477: In most cases,
        !           478: for the countries listed above,
        !           479: you can simply follow the directions below substituting your country code for
        !           480: any occurrence of \verb"c=US".
        !           481: 
        !           482: In all cases,
        !           483: for DSAs residing outside of the c=US DMD,
        !           484: you should always contact your national administrator before proceeding.
        !           485: 
        !           486: \section      {Configuring your Level-1 DSA}
        !           487: The steps towards configuring a Level-1 DSA are straight-forward.
        !           488: For the text that follows,
        !           489: any example that includes \verb"O_i" means that the name of your organization
        !           490: should be substituted.
        !           491: Similarly,
        !           492: any occurrance of \verb"U_j" refers to the name of your organizational unit.
        !           493: 
        !           494: \subsection    {Choosing a DSA Name}
        !           495: First, you must choose a name for your DSA.
        !           496: It is a QUIPU convention that DSAs should be named after endangered
        !           497: South American wildlife,
        !           498: and that the entry for the DSA should contain a description of the animal
        !           499: or plant in question.
        !           500: Table~\ref{endangered-wildlife},
        !           501: taken from \volfive/ of the ISODE User's Manual,
        !           502: contains a partial list of these species.
        !           503: You might also want to consult IUCN's {\em Red Book\/} \cite{IUCN.Mammal}.
        !           504: \tagtable[tp]{CNF-1}{Endangered South American Wildlife}{endangered-wildlife}
        !           505: 
        !           506: For the purposes of the pilot project,
        !           507: the name of each Level-1 DSA takes the form:
        !           508: \begin{quote}\small\begin{verbatim}
        !           509: c=US@cn=wildlife name
        !           510: \end{verbatim}\end{quote}
        !           511: So, go to Table~\ref{endangered-wildlife} and pick an unused name.
        !           512: Alternately,
        !           513: find a name which sounds plausible enough to fool a \camayoc/.
        !           514: Prepend \verb"c=US@cn=",
        !           515: and this is the Distinguished name of your Level-1 DSA.
        !           516: 
        !           517: To find out what names are already taken,
        !           518: do the following:
        !           519: \begin{quote}\small\begin{verbatim}
        !           520: % dish -c "Alpaca"
        !           521: Welcome to Dish (DIrectory SHell)
        !           522: Dish -> search @c=US -filter objectClass=dsa -nosizelimit
        !           523: \end{verbatim}\end{quote}
        !           524: This will print out the list of names already in use.
        !           525: 
        !           526: Since some of the names in Table~\ref{endangered-wildlife} are long,
        !           527: it is acceptable to use only part of the wildlife name as the common name
        !           528: of your Level-1 DSA.
        !           529: For example,
        !           530: if the wildlife name is something like \verb"Southern Bearded Saki",
        !           531: then it's probably okay to use \verb"Saki" as the name of the DSA,
        !           532: e.g., \verb"c=US@cn=Saki".
        !           533: 
        !           534: Now decide upon a ``sanitized'' name that will be used for the
        !           535: \unix/ directory which will contain the database for your Level-1 DSA.
        !           536: Using all lower case letters and substituting hyphens for spaces is a good
        !           537: rule.
        !           538: So, if the name of your DSA is \verb"c=US@cn=Spectacled Bear",
        !           539: then \file{spectacled-bear/} or just \file{bear/} would be fine.
        !           540: For the purpose of discussion,
        !           541: let's call this directory \file{wildlife/}.
        !           542: 
        !           543: The owner of the directory should be some maintenance account
        !           544: (e.g., \verb"daemon") or \verb"root".
        !           545: When the DSA executes,
        !           546: it will set its user- and group-IDs based on the owner and group of this
        !           547: directory.
        !           548: 
        !           549: \subsection    {Editing the DSA configuration file}
        !           550: Go to the directory \file{quipu/} under ISODE's \verb"ETCDIR" directory:
        !           551: \begin{quote}\small\begin{verbatim}
        !           552: # cd $(ETCDIR)quipu/
        !           553: \end{verbatim}\end{quote}
        !           554: Now copy the configuration tempate file, e.g.,
        !           555: \begin{quote}\small\begin{verbatim}
        !           556: # cp wildlife.dsa spectacled-bear.dsa
        !           557: # chmod 0600 spectacled-bear.dsa
        !           558: \end{verbatim}\end{quote}
        !           559: Now edit the new file to define the initial configuration for your Level-1
        !           560: DSA.
        !           561: Figure~\ref{dsaconfig} shows an example DSA configuration file.
        !           562: \tagfigure[tp]{CNF-2}{Example DSA configuration file}{dsaconfig}
        !           563: 
        !           564: Note that when defining information such as \verb"streetaddress", \verb"telephone",
        !           565: and \verb"description", you should use the values for your organization,
        !           566: not for your own department.
        !           567: If you like,
        !           568: {\em after\/} your DSA is running,
        !           569: you can edit \file{c=US/o=O\_i/EDB} to insert the corresponding
        !           570: information for your own department.
        !           571: 
        !           572: Note that if the name of your ganization is long than 30 characters,
        !           573: then you will have to manually define a postal address in the configuration
        !           574: file for \pgm{dsaconfig}.
        !           575: The format is:
        !           576: \begin{quote}\small\begin{verbatim}
        !           577: postalAddress    "item1 $ item2 $ ... $ itemN"
        !           578: \end{verbatim}\end{quote}
        !           579: where each item is less-than or equal-to 30~characters in length and there are
        !           580: no more than six items.
        !           581: 
        !           582: \subsection    {Running the DSA configuration program}
        !           583: Once the file is edited,
        !           584: run the DSA configuration program, \man dsaconfig(8):
        !           585: \begin{quote}\small\begin{verbatim}
        !           586: # $(SBINDIR)dsaconfig wildlife
        !           587: \end{verbatim}\end{quote}
        !           588: e.g.,
        !           589: \begin{quote}\small\begin{verbatim}
        !           590: # $(SBINDIR)dsaconfig spectacled-bear
        !           591: \end{verbatim}\end{quote}
        !           592: This will create the database directory and all requisite files.
        !           593: Finally,
        !           594: it will set the owner and group of the files appropriately.
        !           595: 
        !           596: It is necessary to explain a little bit about what \pgm{dsaconfig} does.
        !           597: Way back in Section~\ref{edb:format} on page~\pageref{edb:format},
        !           598: the ``EDB format'' of the database was described.
        !           599: All that is now missing is an explanation how different nodes in the Directory
        !           600: tree are structured.
        !           601: This is done using the \unix/ directory hierarchy.
        !           602: 
        !           603: Starting at the ROOT,
        !           604: at every level in the Directory tree for which your Level-1 DSA holds data,
        !           605: there is a single file called \file{EDB}.
        !           606: If an entry defined in an \file{EDB} file has children,
        !           607: the \file{EDB} file for the children will be found in a subdirectory
        !           608: whose name is the string encoded Relative Distinguished Name (RDN) of
        !           609: the entry.
        !           610: 
        !           611: For example,
        !           612: if a \file{EDB} file has an entry whose RDN is \verb"o=Computer Science",
        !           613: and if the entry has children,
        !           614: and if your Level-1 DSA stores this information locally,
        !           615: then the information can be found in the file \file{o=Computer Science/EDB}
        !           616: relative to the current directory.
        !           617: Note that:
        !           618: \begin{itemize}
        !           619: \item  QUIPU is case sensitive when it looks for the subordinate \file{EDB}
        !           620:        file~---~the case of the attribute type
        !           621:        (e.g., \verb"o") is taken from the file \file{oidtable.at} in the
        !           622:        ISODE \verb"ETCDIR" directory, 
        !           623:        whilst the case of the attribute value is taken from the superior
        !           624:        \file{EDB} file;
        !           625:        and,    
        !           626: 
        !           627: \item  blanks are {\em actually\/} present in the sub-directory name.%
        !           628: \footnote{An interesting example of the maxim {\em can implies shall\/}~---~because
        !           629: the Berkeley \unix/ file system {\em can\/} let us have long directory names
        !           630: with embedded spaces, we {\em shall\/} make use of that feature.}
        !           631: \end{itemize}
        !           632: Thus, for a Level-1 DSA, the initial database hierarchy looks like:
        !           633: \begin{quote}\begin{tabular}{l}
        !           634: \file{EDB}\\
        !           635: \file{c=US/EDB}\\
        !           636: \file{c=US/o=O\_i/EDB}\\
        !           637: \file{c=US/o=O\_i/ou=U\_j/EDB}\\
        !           638: \end{tabular}\end{quote}
        !           639: So,
        !           640: \pgm{dsaconfig} built these files for you.
        !           641: 
        !           642: \subsection    {Testing the stand-alone DSA}
        !           643: The first thing to do is to start the DSA interactively so as to see
        !           644: that it can successfully load its local EDB files.
        !           645: So your Level-1 DSA is started thusly:
        !           646: \begin{quote}\small\begin{verbatim}
        !           647: # cd wildlife/
        !           648: # $(SBINDIR)ros.quipu -t ./quiputailor &
        !           649: \end{verbatim}\end{quote}
        !           650: If your DSA is configured properly,
        !           651: it will print out something like:
        !           652: \begin{quote}\smaller\begin{verbatim}
        !           653: DSA wildlife has started on '0101'H/Internet=130.117.128.3+17003
        !           654: \end{verbatim}\end{quote}
        !           655: 
        !           656: \subsection    {DSA Failure}\label{dsa:failure}
        !           657: Instead,
        !           658: if the DSA prints out something like:
        !           659: \begin{quote}\smaller\begin{verbatim}
        !           660: FATAL ERROR: <<reason>>
        !           661: \end{verbatim}\end{quote}
        !           662: then something has gone wrong.
        !           663: 
        !           664: There are a few reasons why the DSA might fail.
        !           665: First verify that the ISODE is operating correctly
        !           666: (see Section~\ref{isode:testing} on page~\pageref{isode:testing}.)
        !           667: Next, verify that the DUA is operating correctly
        !           668: (see Section~\ref{dua:configure} on page~\pageref{dua:configure}.)
        !           669: 
        !           670: There are generally three causes of failure:
        !           671: \begin{itemize}
        !           672: \item  there is an attribute-related schema problem;
        !           673: 
        !           674: \item  there is a structure-related schema problem;
        !           675: or,
        !           676: 
        !           677: \item  something else is running at the OSI presentation address of the DSA.
        !           678: \end{itemize}
        !           679: Since you are using files which have been automatically generated,
        !           680: the first two errors are unlikely.
        !           681: However,
        !           682: they might occur due to spelling errors or catastrophic editing
        !           683: on your part.
        !           684: In order to diagnose the problem,
        !           685: you will need to look at the tail of the file \file{dsap.log} in the
        !           686: \file{wildlife/} directory.
        !           687: 
        !           688: \subsubsection {Attribute Errors}
        !           689: If you misspell the name of an attribute,
        !           690: then the diagnostic will look something like this:
        !           691: \begin{quote}\small\begin{verbatim}
        !           692: line 14: unknown attribute type '<<bad-name>>'
        !           693: File ...wildlife/c=US/o=O_i/EDB not loaded
        !           694: \end{verbatim}\end{quote}
        !           695: Alternately,
        !           696: if you specify an illegal attribute for an object
        !           697: (a violation of the object's schema),
        !           698: then the diagnostic will look something like this:
        !           699: \begin{quote}\small\begin{verbatim}
        !           700: attribute '<<illegal-name>>' not allowed in the specified objectclass
        !           701: Schema error in entry ending line 17...
        !           702: File ...wildlife/c=US/o=O_i/EDB not loaded
        !           703: \end{verbatim}\end{quote}
        !           704: Conversely,
        !           705: if you leave out an attribute which is required by an object:
        !           706: \begin{quote}\small\begin{verbatim}
        !           707: 'Must' attribute missing '<<mandatory-name>>'
        !           708: Schema error in entry ending line 16...
        !           709: File ...wildlife/c=US/o=O_i/EDB not loaded
        !           710: \end{verbatim}\end{quote}
        !           711: 
        !           712: \subsubsection {Structure Errors}
        !           713: If a subordinate object belongs to a class which is not permitted by
        !           714: the schema of its immediate parent
        !           715: (as determined by the parent's \verb"treeStructure" attribute),
        !           716: then the diagnostic looks something like this:
        !           717: \begin{quote}\small\begin{verbatim}
        !           718: Specified object class is not in the tree structure (schema) list
        !           719: Schema error in entry ending line 16...
        !           720: File ...wildlife/c=US/o=O_i/EDB not loaded
        !           721: \end{verbatim}\end{quote}
        !           722: Note that this means you have to look in the file \file{wildlife/c=US/EDB}
        !           723: to find the \verb"treeStructure" attribute of the parent entry
        !           724: and then compare that to the \verb"objectClass" attribute of the entry
        !           725: in error.
        !           726: 
        !           727: \subsubsection {Network Errors}
        !           728: If the local EDB files are consistent,
        !           729: but another process is already listening on the IP address and TCP
        !           730: port for the DSA,
        !           731: then your DSA will print:
        !           732: \begin{quote}\small\begin{verbatim}
        !           733: TNetListen: [Congestion at TSAP] start_tcp_server failed:
        !           734:         Address already in use
        !           735: Address: '0101'H/Internet=130.117.128.3+17003
        !           736: 
        !           737: FATAL ERROR: Couldn't start the DSA!!
        !           738: \end{verbatim}\end{quote}
        !           739: Perhaps another copy of this DSA is already running
        !           740: or the TCP port in the entry for the DSA
        !           741: (found in the file \file{wildlife/c=US/EDB/})
        !           742: is wrong.
        !           743: It is also possible that an early invocation of the DSA was ungracefully
        !           744: terminated and left the TCP port in a \verb"FIN_WAIT_x" state.
        !           745: Use the \pgm{netstat} program to find out.
        !           746: If so,
        !           747: reboot \unix/.
        !           748: 
        !           749: Alternately, you might see:
        !           750: \begin{quote}\small\begin{verbatim}
        !           751: TNetListen: [Congestion at TSAP] start_tcp_server failed:
        !           752:         Can't assign requested address
        !           753: Address: '0101'H/Internet=130.117.128.3+17003
        !           754: 
        !           755: FATAL ERROR: Couldn't start the DSA!!
        !           756: \end{verbatim}\end{quote}
        !           757: This indicates that you mis-identified the IP address of your Level-1 DSA in
        !           758: your \pgm{dsaconfig} configuration file.
        !           759: 
        !           760: \subsection    {Editing the DUA tailoring file}
        !           761: The file \file{dsaptailor} in the ISODE \verb"ETCDIR" directory contains
        !           762: run-time tailoring information for the DUAs provided by the pilot software.
        !           763: You will need to be the super-user to edit this file.
        !           764: 
        !           765: You should now edit the \file{dsaptailor} file so that your DUAs
        !           766: will contact that DSA by default.
        !           767: This is done by looking for these two lines in the \file{dsaptailor} file:
        !           768: \begin{quote}\smaller\begin{verbatim}
        !           769: # the level-1 DSA
        !           770: #dsa_address "wildlife name"      '0101'H/Internet=aaa.bbb.ccc.ddd+port
        !           771: \end{verbatim}\end{quote}
        !           772: and then removing the \verb"`#'"-sign at the beginning of the second line.
        !           773: 
        !           774: Next,
        !           775: you should also have your DUAs start, by default, in your portion of the
        !           776: Directory tree.
        !           777: This is done by looking for these two lines in the \file{dsaptailor} file:
        !           778: \begin{quote}\small\begin{verbatim}
        !           779: local_DIT    "c=US"
        !           780: #local_DIT   "c=US@O_i"
        !           781: \end{verbatim}\end{quote}
        !           782: and then adding a \verb"`#'"-sign at the beginning of the first line,
        !           783: and removing the \verb"`#'"-sign at the beginning of the second line.
        !           784: 
        !           785: Section~12.2 of \volfive/ discusses the options available for run-time
        !           786: tailoring.
        !           787: Typically,
        !           788: you will have no need of further editing this file.
        !           789: 
        !           790: Now run the \man dish(1c) program again,
        !           791: telling it to connect to your Level-1 DSA.
        !           792: \begin{quote}\small\begin{verbatim}
        !           793: % dish -c "wildlife name"
        !           794: Welcome to Dish (DIrectory SHell)
        !           795: Dish ->
        !           796: \end{verbatim}\end{quote}
        !           797: indicates that the DUA connected to your Level-1 DSA.
        !           798: Otherwise consult Section~\ref{dua:failure} on
        !           799: page~\pageref{dua:failure} and try to debug the problem.
        !           800: 
        !           801: Now look around the Directory tree using \pgm{dish}:
        !           802: \begin{quote}\small\begin{verbatim}
        !           803: Dish -> list
        !           804: \end{verbatim}\end{quote}
        !           805: A good test to run is to try and bind to your own entry,
        !           806: but to do so by dereferencing the alias for the Manager of your DMD:
        !           807: \begin{quote}\small\begin{verbatim}
        !           808: Dish -> bind -user "@c=US@o=O_i@cn=Manager"
        !           809: Enter password for "@c=US@o=O_i@cn=Manager": 
        !           810: Dish -> 
        !           811: \end{verbatim}\end{quote}
        !           812: Indicates that you are now bound to the directory as that DN.
        !           813: Instead, if you see:
        !           814: \begin{quote}\small\begin{verbatim}
        !           815: Dish -> bind -user "@c=US@o=O_i@cn=Manager"
        !           816: Enter password for "@c=US@o=O_i@cn=Manager": 
        !           817: Security Error - check name and password
        !           818: \end{verbatim}\end{quote}
        !           819: then either you may have entered the DN or password wrong.
        !           820: Try again.
        !           821: If not,
        !           822: or if you encounter some other problem,
        !           823: contact a \camayoc/ for assistance.
        !           824: 
        !           825: \subsection    {Joining the Pilot DMD}
        !           826: Once your DUA is configured to use your Level-1 DSA and your Level-1 DSA
        !           827: appears to be functioning properly in stand-alone mode,
        !           828: it is time for it to join the Pilot DMD.
        !           829: 
        !           830: First,
        !           831: backup your EDB files:
        !           832: \begin{quote}\small\begin{verbatim}
        !           833: # cp EDB EDB.stand-alone
        !           834: # cp c=US/EDB c=US/EDB.stand-alone
        !           835: \end{verbatim}\end{quote}
        !           836: 
        !           837: \subsubsection {Contact the c=US Manager}
        !           838: Next,
        !           839: contact the Manager of the \verb"c=US" portion of the DMD.
        !           840: Use the \pgm{dish} program to get the necessary contact information, e.g.,
        !           841: \begin{quote}\small\begin{verbatim}
        !           842: % dish -c "Alpaca"
        !           843: Welcome to Dish (DIrectory SHell)
        !           844: Dish -> show @c=US@cn=Manager -fred
        !           845: \end{verbatim}\end{quote}
        !           846: If this fails,
        !           847: contact a \camayoc/ for assistance.
        !           848: Otherwise, e-mail the file \file{c=US/EDB} along with your phone number to the
        !           849: Manager and await a phone call or message in return.
        !           850: Leave your DSA running until you hear from the Manager.
        !           851: 
        !           852: The Manager will enter these into the MASTER \verb"c=US" EDB and then
        !           853: try to connect to your DSA to test it out.
        !           854: The Manager will also give you a ``time slot'' when your \file{nightly.sh}
        !           855: script should run.
        !           856: (This is a feeble attempt to prevent multiple systems from
        !           857: mailing statistical information simultaneously each night.)
        !           858: 
        !           859: If everything looks fine,
        !           860: the Manager will direct you to proceed.
        !           861: 
        !           862: \subsubsection {Connecting In and Checking Out}
        !           863: Restart your DSA and use \pgm{dish} to bind as the manager.
        !           864: Next,
        !           865: direct the DSA to update its slave EDBs:
        !           866: \begin{quote}\small\begin{verbatim}
        !           867: % dish -user "@c=US@o=O_i@cn=Manager"
        !           868: Welcome to Dish (DIrectory SHell)
        !           869: Enter password for "@c=US@o=O_i@cn=Manager": 
        !           870: Dish -> dsacontrol -slave
        !           871: Scheduled
        !           872: Dish -> quit
        !           873: \end{verbatim}\end{quote}
        !           874: The \verb"Scheduled" message means that the EDB updates have been scheduled
        !           875: for execution.
        !           876: The DSA will actually perform these in the background,
        !           877: so it may be a few minutes (or longer, depending on DSA/network availability)
        !           878: before the EDBs are updated.
        !           879: 
        !           880: To verify that your Level-1 DSA is updating its ROOT and \verb"c=US" EDB
        !           881: files,
        !           882: look for the files \file{EDB.bak} and \file{c=US/EDB.bak}
        !           883: in the \file{quipu/wildlife/} directory.
        !           884: If present,
        !           885: these indicate that your Level-1 DSA was able to successfully update the EDBs.
        !           886: If not,
        !           887: look at the \file{dsap.log} log file and contact a \camayoc/ for
        !           888: assistance.
        !           889: 
        !           890: Finally,
        !           891: check that the global Directory tree knows about your DSA
        !           892: (the \verb"c=US" Manager verified this, but you should check anyway).
        !           893: Use the \pgm{dish} but connect to a Level-0 DSA:
        !           894: \begin{quote}\small\begin{verbatim}
        !           895: % dish -c "Alpaca"
        !           896: Welcome to Dish (DIrectory SHell)
        !           897: Dish -> moveto "@c=US@o=O_i"
        !           898: Dish -> list
        !           899:    ...
        !           900: Dish -> list "ou=U_j"
        !           901:    ...
        !           902: \end{verbatim}\end{quote}
        !           903: If this succeeds, the Level-0 DSAs know how to talk to your Level-1 DSA.
        !           904: 
        !           905: The other Level-1 DSAs won't know about your organization and Level-1 DSA
        !           906: for another day or so.
        !           907: (The Manager of the \verb"c=US" may cause a few Level-1 DSAs to immediately
        !           908: reload the \verb"c=US" in order to facilitate things.)
        !           909: 
        !           910: \subsubsection {More System Administration}
        !           911: Once everything checks out,
        !           912: its time to restart the DSA in the background.
        !           913: First, edit the \file{quiputailor} file for your DSA by changing the
        !           914: line
        !           915: \begin{quote}\small\begin{verbatim}
        !           916: update  off
        !           917: \end{verbatim}\end{quote}
        !           918: to
        !           919: \begin{quote}\small\begin{verbatim}
        !           920: update  on
        !           921: \end{verbatim}\end{quote}
        !           922: This tells your DSA to automatically update its SLAVE EDB files on a regular
        !           923: basis.
        !           924: 
        !           925: Next, use \pgm{dish} to abort the DSA:
        !           926: \begin{quote}\small\begin{verbatim}
        !           927: % dish -user "@c=US@o=O_i@cn=Manager"
        !           928: Welcome to Dish (DIrectory SHell)
        !           929: Enter password for "@c=US@o=O_i@cn=Manager": 
        !           930: Dish -> dsacontrol -abort
        !           931: *** Problem with DSA ***
        !           932: Dish -> quit
        !           933: \end{verbatim}\end{quote}
        !           934: Now run the \file{startup.sh} script:
        !           935: \begin{quote}\small\begin{verbatim}
        !           936: % $(ETCDIR)quipu/wildlife/startup.sh
        !           937: \end{verbatim}\end{quote}
        !           938: Take a look at the log files it creates and once you're satisfied
        !           939: that it is operational,
        !           940: use \pgm{dish} one last time before considering things up and running.
        !           941: 
        !           942: Finally,
        !           943: it's time for the last bit of system administration:
        !           944: \begin{enumerate}
        !           945: \item  Add an entry to the file \file{/etc/rc.local}:
        !           946: \begin{quote}\smaller\begin{verbatim}
        !           947: if [ -d $(ETCDIR)quipu/wildlife ]; then
        !           948:    $(ETCDIR)quipu/wildlife/startup.sh & \
        !           949:                                 (echo -n ' wildlife') > /dev/console
        !           950: fi
        !           951: \end{verbatim}\end{quote}
        !           952: in the section where the network servers are started.
        !           953: If your \file{rc.local} file starts \man tsapd(8c),
        !           954: then place this entry after the one which starts \pgm{tsapd}.
        !           955: 
        !           956: The next time your system reboots,
        !           957: check to make sure that your DSA started.
        !           958: On {\em some\/} systems running Sun's ``Yellow Pages'',
        !           959: it has been observed that YP prevents the \pgm{ros.quipu} from starting.
        !           960: No cause or cure is known for this.
        !           961: The problem just seems to ``go away'' after a while.
        !           962: 
        !           963: \item  Based on the time that the \verb"c=US" manager gave you,
        !           964: modify the \file{crontab} file according; e.g.,
        !           965: \begin{quote}\small\begin{verbatim}
        !           966: 0 4 * * * $(ETCDIR)quipu/wildlife/nightly.sh
        !           967: \end{verbatim}\end{quote}
        !           968: If the directory database for the Level-1 DSA is owned by a user-ID other
        !           969: than \verb"root" (e.g., \verb"daemon"),
        !           970: then instead the line should look something like this:
        !           971: \begin{quote}\smaller\begin{verbatim}
        !           972: 0 4 * * * su daemon -c "/bin/sh $(ETCDIR)quipu/wildlife/nightly.sh"
        !           973: \end{verbatim}\end{quote}
        !           974: or perhaps
        !           975: this
        !           976: \begin{quote}\small\begin{verbatim}
        !           977: 0 4 * * * su daemon -c "sh $(ETCDIR)quipu/wildlife/nightly.sh"
        !           978: \end{verbatim}\end{quote}
        !           979: Be sure that the ownership of the \file{nightly.sh} file matches that of the
        !           980: userid that will be running under cron.
        !           981: Verify that the user's shell, paths, and so on, are all correct as well.
        !           982: \end{enumerate}
        !           983: 
        !           984: Congratulations!
        !           985: Your Level-1 DSA has now joined the pilot DMD.
        !           986: Further,
        !           987: the Manager of \verb"c=US" has elevated you to the role of
        !           988: junior \camayoc/ by adding your electronic mail address to the 
        !           989: \verb"wpp-camayocs" mailing list.
        !           990: Each \camayoc/ is expected to share experiences with others so as to
        !           991: expand and advance understanding of running a white pages service using the
        !           992: OSI Directory.
        !           993: 
        !           994: \section      {Configuring the White Pages}
        !           995: The very last step you need do is to configure the white pages service which
        !           996: resides on top of the OSI Directory.
        !           997: 
        !           998: You should now determine if a substantive portion of your user community does
        !           999: not have easy access to a machine running the pilot project software.
        !          1000: If this is the case,
        !          1001: then you will probably want to make the white pages service available via the
        !          1002: network (either via TELNET or by emulating WHOIS) or via electronic mail.
        !          1003: 
        !          1004: \subsection    {White Pages via TELNET}
        !          1005: Choose a machine in your local environment which is running the pilot project
        !          1006: software.
        !          1007: This machine will offer the white pages service via TELNET.
        !          1008: 
        !          1009: On this machine,
        !          1010: add a line to the \file{/etc/passwd} file for a user called \verb"fred"
        !          1011: \begin{quote}\smaller\begin{verbatim}
        !          1012: fred::30:30:Anonyous White Pages User:/:$(SBINDIR)fredsh
        !          1013: \end{verbatim}\end{quote}
        !          1014: where group-id \verb"30" is the \verb"guest".
        !          1015: 
        !          1016: \subsubsection {Fred-only hosts}
        !          1017: After bringing up the software for both the Directory and the White Pages,
        !          1018: you might wish to copy the executables to other machines,
        !          1019: just to make \pgm{fred} available.
        !          1020: To do this, you need the following files:
        !          1021: \begin{itemize}
        !          1022: \item  In the ISODE \verb"BINDIR" directory:
        !          1023: \begin{quote}\begin{tabular}{l}
        !          1024: \pgm{dish}\\
        !          1025: \pgm{editentry}\\
        !          1026: \pgm{fred}
        !          1027: \end{tabular}\end{quote}
        !          1028: 
        !          1029: \item  In the ISODE \verb"SBINDIR" directory:
        !          1030: \begin{quote}\begin{tabular}{l}
        !          1031: \file{fredrc}\\
        !          1032: \file{dsaptailor}\\
        !          1033: \file{oidtable.*}\\
        !          1034: \file{isobjects}\\
        !          1035: \file{isologs}\\
        !          1036: \file{isomacros}\\
        !          1037: \file{isotailor}
        !          1038: \end{tabular}\end{quote}
        !          1039: Note that the \file{isotailor} file need not be present,
        !          1040: depending on the dynamic changes to your system configuration.
        !          1041: 
        !          1042: \item  In the ISODE \verb"SBINDIR" directory:
        !          1043: \begin{quote}\begin{tabular}{l}
        !          1044: \pgm{fredsh}\\
        !          1045: \pgm{in.whitepages}
        !          1046: \end{tabular}\end{quote}
        !          1047: Note that you need \pgm{in.whitepages} only if you plan on using this host to
        !          1048: offer the white pages via WHOIS emulation.
        !          1049: \end{itemize}
        !          1050: 
        !          1051: \subsection    {White Pages via WHOIS}\label{wp:whois}
        !          1052: Choose a machine in your local environment which is running the pilot project
        !          1053: software.
        !          1054: This machine will offer the white pages service via a network port offering an
        !          1055: emulation of the WHOIS service.
        !          1056: 
        !          1057: On this machine,
        !          1058: edit the file \file{/etc/services} so that it has an entry like this:
        !          1059: \begin{quote}\small\begin{verbatim}
        !          1060: whitepages 17005/tcp
        !          1061: \end{verbatim}\end{quote}
        !          1062: 
        !          1063: Next,
        !          1064: edit the file \file{/etc/servers} so that it has an entry like this:
        !          1065: \begin{quote}\small\begin{verbatim}
        !          1066: whitepages tcp  $(SBINDIR)in.whitepages
        !          1067: \end{verbatim}\end{quote}
        !          1068: Because most user interfaces to WHOIS,
        !          1069: e.g., \man whois(1c),
        !          1070: do not allow the user to specify a special port,
        !          1071: you should probably also add this line as well:
        !          1072: \begin{quote}\small\begin{verbatim}
        !          1073: whois   tcp     $(SBINDIR)in.whitepages
        !          1074: \end{verbatim}\end{quote}
        !          1075: If you already have a line for \verb"whois" in the \file{servers} file,
        !          1076: then you are already running a WHOIS service,
        !          1077: and you should {\bf not\/} add a second \verb"whois" line.
        !          1078: This machine is not a good choice for running the white pages via WHOIS
        !          1079: emulation.
        !          1080: 
        !          1081: Note that on newer systems derived from Berkeley \unix/,
        !          1082: \file{/etc/servers} is called \file{/etc/inetd.conf}.
        !          1083: 
        !          1084: \subsubsection {The whitepages Command}
        !          1085: On those systems which are to access the white pages via the network and not
        !          1086: locally
        !          1087: (i.e., those systems which are not running the pilot project software),
        !          1088: you should determine how a user invokes the WHOIS service via the network.
        !          1089: For \unix/ systems,
        !          1090: you should provide a shell script like this:
        !          1091: \begin{quote}\small\begin{verbatim}
        !          1092: : run this script through /bin/sh
        !          1093: 
        !          1094: exec /usr/ucb/whois -h wp.psi.com "$*"
        !          1095: \end{verbatim}\end{quote}
        !          1096: where the name of a host running the pilot project software is substituted for
        !          1097: \verb"whitepages", e.g., \verb"wp.psi.com".
        !          1098: This host must have the files \file{/etc/services} and \file{/etc/servers}
        !          1099: edited as described above.
        !          1100: 
        !          1101: \subsection    {White Pages via mail}\label{wp:mail}
        !          1102: In addition,
        !          1103: you might want to make the whitepages available via electronic mail.
        !          1104: To do this,
        !          1105: choose a machine in your local environment which is running the pilot project
        !          1106: software.
        !          1107: 
        !          1108: On this machine,
        !          1109: edit the file \file{/usr/lib/aliases} so that it has an entry like this:
        !          1110: \begin{quote}\small\begin{verbatim}
        !          1111: whitepages: "|/usr/local/bin/fred -m"
        !          1112: \end{verbatim}\end{quote}
        !          1113: After editing the \file{aliases} file,
        !          1114: you will need to run the \pgm{newaliases} command as the super-user:
        !          1115: \begin{quote}\small\begin{verbatim}
        !          1116: # newaliases
        !          1117: \end{verbatim}\end{quote}
        !          1118: Also make sure that the \file{sendmail.cf} file lists \pgm{sh} and not
        !          1119: \pgm{csh} as the \verb"prog" mailer.
        !          1120: 
        !          1121: Once these changes are in place,
        !          1122: Whenever someone sends to the address \verb"whitepages" on this machine,
        !          1123: the subject line or body of the message will be interrogated for WHOIS-like
        !          1124: commands and the appropriate reply generated.
        !          1125: 
        !          1126: Note that on systems not running \man sendmail(8c),
        !          1127: a similar procedure is followed.
        !          1128: However,
        !          1129: it's up to you to figure out how to define aliases that run commands on
        !          1130: receipt of mail.
        !          1131: 
        !          1132: You should tell the local PostMaster about the white pages service.
        !          1133: In this fashion,
        !          1134: when the PostMaster get queries from other sites,
        !          1135: they can the sender of the message
        !          1136: (and the Postmaster at the sender's site)
        !          1137: about the service.
        !          1138: 
        !          1139: \subsection    {An Undocumented Feature}
        !          1140: In some environments,
        !          1141: in which the IP-address of a host is reasonably trustworthy,
        !          1142: it may be desirable to have an automatic means of mapping an IP-address into a
        !          1143: Distinguished Name.
        !          1144: \pgm{fred} provides such a mechanism under the following conditions:
        !          1145: \begin{enumerate}
        !          1146: \item  Create a file called \file{fredmap} in the ISODE \verb"ETCDIR"
        !          1147:        directory.
        !          1148: 
        !          1149:        The syntax of this file is a series of entries, one to a line.
        !          1150:        Each line contains:
        !          1151:     \begin{itemize}
        !          1152:     \item      a IP-address mask
        !          1153:                (in the familiar ``dot'' notation, e.g., \verb"255.255.255.0");
        !          1154: 
        !          1155:     \item      a IP-network address
        !          1156:                (in the familiar ``dot'' notation, e.g., \verb"192.52.180");
        !          1157: 
        !          1158:     \item      a Distinguished Name
        !          1159:                (e.g., \verb|"c=US@o=DMD@cn=anon"|);
        !          1160:                and,
        !          1161: 
        !          1162:     \item      the password to use when binding to that DN
        !          1163:                (e.g, \verb|"secret"|).
        !          1164:     \end{itemize}
        !          1165: Blanks and/or tab characters are used to separate items.
        !          1166: However, double-quotes may be used to prevent separation for items containing
        !          1167: embedded whitspace.
        !          1168: The sharp character (`\verb"#"') at the beginning of a line indicates a
        !          1169: commentary line.
        !          1170: 
        !          1171: This file should be mode \verb"0640", owned by user \verb"root" and
        !          1172: some previously unused group, e.g., \verb"wp".
        !          1173: 
        !          1174: \item  After installing \pgm{fred} with the
        !          1175: \begin{quote}\small\begin{verbatim}
        !          1176: # (cd others/quipu; ./make inst-pilot)
        !          1177: \end{verbatim}\end{quote}
        !          1178: command
        !          1179: (this was done way back in Section~\ref{isode:install} on
        !          1180: page~\pageref{isode:install}),
        !          1181: make the group of the binary the same as the \file{fredmap} file,
        !          1182: and change the mode to \verb"02755".
        !          1183: 
        !          1184: \item  When a local user invokes \pgm{fred}
        !          1185: \pgm{fred} looks-up the local IP-address,
        !          1186: reads the \file{fredmap} file looking for the first entry satisfying:
        !          1187: $$\mbox{(local IP-address)} \land \mbox{(IP-address mask)}\ \equiv\ 
        !          1188: \mbox{(IP-network address)}$$
        !          1189: Upon finding such an entry,
        !          1190: \pgm{fred} will bind to the Directory using the DN and password for that entry.
        !          1191: 
        !          1192: \item  When \pgm{fred} is accessed via the network
        !          1193: (e.g., with the \verb"in.whitepages" mechanism described in
        !          1194: Section~\ref{wp:whois} on page~\pageref{wp:whois}),
        !          1195: \pgm{fred} will automatically read the \file{fredmap} file,
        !          1196: looking for the first entry satisfying:
        !          1197: $$\mbox{(remote IP-address)} \land \mbox{(IP-address mask)}\ \equiv\ 
        !          1198: \mbox{(IP-network address)}$$
        !          1199: Upon finding such an entry,
        !          1200: \pgm{fred} will bind to the Directory using the DN and password for that entry.
        !          1201: \end{enumerate}
        !          1202: Of course,
        !          1203: the ordering of entries in the \file{fredmap} file is important!
        !          1204: It is suggested that the file begin with host-specific entries
        !          1205: (those with an IP-address mask of \verb"255.255.255.255"),
        !          1206: and then entries follow in decreasing order by the number of bits on in the
        !          1207: IP-address mask.
        !          1208: 
        !          1209: Although use of a ``default'' entry,
        !          1210: one which will match any IP-address,
        !          1211: is strongly discouraged,
        !          1212: it is possible to define such an entry.
        !          1213: This should be the very last entry in the \file{fredmap} file.
        !          1214: The format of this entry is simply:
        !          1215: \begin{quote}\small\begin{verbatim}
        !          1216: 0.0.0.0 0.0.0.0    "some DN"    "some password"
        !          1217: \end{verbatim}\end{quote}
        !          1218: 
        !          1219: It should be noted that this scheme provides a convenient mechanism for
        !          1220: allowing ``local'' users to automatically be authorized as specific entries in
        !          1221: the local DMD.
        !          1222: By doing so,
        !          1223: this eases the administrative burden of assigning passwords to users in an
        !          1224: environment which contains read-only but, nonetheless, sensistive information.
        !          1225: The information is protected via access control,
        !          1226: e.g.,
        !          1227: \begin{quote}\smaller\begin{verbatim}
        !          1228: acl= prefix # c=US@o=DMD # read # attributes # <attribute-list>
        !          1229: acl= self # write # attributes # <attribute-list>
        !          1230: acl= others # none # attributes # <attribute-list>
        !          1231: \end{verbatim}\end{quote}
        !          1232: Note that for a writeable environment,
        !          1233: whilst the access control scheme is still used,
        !          1234: this simplification of locally anonymous DNs usually can not be made.
        !          1235: 
        !          1236: Note that under the current QUIPU access scheme,
        !          1237: the access control list above will prevent any user,
        !          1238: regardless of the DN they are bound as (including local users),
        !          1239: from searching on the values of the attributes named in
        !          1240: \verb"<attribute-list>".
        !          1241: As such, a less restrictive set of rules might be:
        !          1242: \begin{quote}\smaller\begin{verbatim}
        !          1243: acl= prefix # c=US@o=DMD # read # attributes # <attribute-list>
        !          1244: acl= self # write # attributes # <attribute-list>
        !          1245: acl= others # compare # attributes # <attribute-list>
        !          1246: \end{verbatim}\end{quote}
        !          1247: which will enable searching for all users.
        !          1248: However,
        !          1249: it will also allow any user to compare specific values against the attributes
        !          1250: named in \verb"<attribute-list>".
        !          1251: 
        !          1252: Of course,
        !          1253: this simplification is severely limited in that it works only for
        !          1254: IP-addresses, and further assumes that such addresses are trustworthy.
        !          1255: The trustworthiness depends entire upon the network environment in which
        !          1256: \pgm{fred} runs.
        !          1257: For example,
        !          1258: since IP-addresses can be readily forged,
        !          1259: one might rely on routers on the edge of the local environment to simply drop
        !          1260: IP datagrams with local source IP-addresses that originate from the outside
        !          1261: world.
        !          1262: In this case,
        !          1263: entries in the \file{fredmap} file containing local IP-addresses can be
        !          1264: thought to be ``reasonably'' secure against outside attack.
        !          1265: Of course,
        !          1266: nothing prevents a local host from forging a local IP-address.
        !          1267: If the trust policy is simply to distinguish between local and non-local
        !          1268: users,
        !          1269: then the \file{fredmap} mechanism is adequite.
        !          1270: 
        !          1271: Given all of these concerns,
        !          1272: this ``undocumented feature'' is a useful, albeit non-OSI, local mechanism.
        !          1273: 
        !          1274: \section      {Other Services}
        !          1275: There are some additional programs that you might wish to install for your
        !          1276: user community.
        !          1277: 
        !          1278: \subsection    {Faces}
        !          1279: When \pgm{fred} and \pgm{dish} display the entry for someone,
        !          1280: they check to see if there is a photograph associated with the user.
        !          1281: This is stored in facsimile format in the \verb"photo" attribute for the entry.
        !          1282: If a photograph is present,
        !          1283: then the \file{dsaptailor} file is consulted for directives
        !          1284: indicating how the picture should be displayed.
        !          1285: The most common entry is:
        !          1286: \begin{quote}\small\begin{verbatim}
        !          1287: photo    xterm Xphoto
        !          1288: \end{verbatim}\end{quote}
        !          1289: which says that if the user's terminal type is \verb"xterm" then the program
        !          1290: \pgm{Xphoto} should be run.
        !          1291: 
        !          1292: Although there are many different programs that can be used to display a
        !          1293: photograph,
        !          1294: only the \pgm{XPhoto} is supported by the sponsors of the pilot.
        !          1295: 
        !          1296: \subsubsection {XPhoto}
        !          1297: To generate the \pgm{XPhoto} program,
        !          1298: run the following command:
        !          1299: \begin{quote}\small\begin{verbatim}
        !          1300: % (cd others/quipu/photo; ./make all XPhoto)
        !          1301: \end{verbatim}\end{quote}
        !          1302: To install the program,
        !          1303: become the super-user and do:
        !          1304: \begin{quote}\small\begin{verbatim}
        !          1305: # (cd others/quipu/photo; ./make inst-all)
        !          1306: \end{verbatim}\end{quote}
        !          1307: Next,
        !          1308: add this line at the end of the \file{dsaptailor} file:
        !          1309: \begin{quote}\small\begin{verbatim}
        !          1310: photo    xterm Xphoto
        !          1311: \end{verbatim}\end{quote}
        !          1312: 
        !          1313: \subsubsection {xwho and xface}
        !          1314: There are two other programs which consult the Directory for people's faces.
        !          1315: These are \pgm{xwho}, who for X windows;
        !          1316: and,
        !          1317: \pgm{xface}, face agent for X windows.
        !          1318: 
        !          1319: To generate these programs,
        !          1320: first generate \pgm{Xphoto} as described above.
        !          1321: next:
        !          1322: \begin{quote}\small\begin{verbatim}
        !          1323: % (cd others/image; ./make all)
        !          1324: \end{verbatim}\end{quote}
        !          1325: To install the program,
        !          1326: become the super-user and do:
        !          1327: \begin{quote}\small\begin{verbatim}
        !          1328: # (cd others/image; ./make inst-all)
        !          1329: \end{verbatim}\end{quote}
        !          1330: 
        !          1331: The \pgm{xwho} program is free-standing,
        !          1332: but requires that the local system run the \man rwhod(8c) daemon.
        !          1333: 
        !          1334: The \pgm{xface} program runs, for each user, in the background.
        !          1335: When a mail reading program displays a message,
        !          1336: it sends a wake-up call to \pgm{xface} which must then try to find the picture
        !          1337: associated with the sender of the message.
        !          1338: 
        !          1339: At present,
        !          1340: only one mail reading system has been modified to communicate with
        !          1341: \pgm{xface},
        !          1342: the \MH/ system.
        !          1343: The file \file{others/image/mhlsbr.c} is a replacement for the
        !          1344: \file{uip/mhlsbr.c} in the \MH/ distribution.
        !          1345: Once \MH/ has been modified,
        !          1346: the manual entry for \man xface(1c) describes how the user tells \MH/ to
        !          1347: display faces.
        !          1348: 
        !          1349: Finally,
        !          1350: the file \pgm{others/image/READ-ME} describes how images may be collected and
        !          1351: placed in the Directory.
        !          1352: 
        !          1353: \subsection    {Mail Composition}
        !          1354: In addition to using the Directory when messages are being displayed, 
        !          1355: the White Pages may also be consulted when a message is being composed.
        !          1356: 
        !          1357: At present,
        !          1358: only one mail composition system has been modified to use the White Pages,
        !          1359: the \MH/ system.
        !          1360: 
        !          1361: The file \file{others/quipu/uips/fred/MH-patches} contains a patch set to \MH/
        !          1362: to use this facility along with instructions for apply the patch set.
        !          1363: 
        !          1364: Once installed,
        !          1365: users can specify a name by bracketing a White Pages query between
        !          1366: ``\verb"<<"'' and ``\verb">>"'' using the \verb"whois" syntax of the \pgm{fred}
        !          1367: command, e.g.,
        !          1368: \begin{quote}\small\begin{verbatim}
        !          1369: To: << rose -org psi >>
        !          1370: \end{verbatim}\end{quote}
        !          1371: At the \whatnow/ prompt, the user can say \verb"whom" to have the names
        !          1372: expanded into addresses.
        !          1373: Alternately, the \verb"send" option can be used as well.
        !          1374: For each query appearing between ``\verb"<<"'' and ``\verb">>"'',
        !          1375: \pgm{fred} will be asked to perform a White Pages resolution.
        !          1376: All matches are printed and the user is asked to select one.
        !          1377: If one is not selected,
        !          1378: the user remains with \pgm{fred},
        !          1379: to make more queries,
        !          1380: until eventually one is selected
        !          1381: (or the user exits \pgm{fred} to abort the expansion process).
        !          1382: 
        !          1383: Note that expansion can occur only if \verb"whom" or \verb"send" is invoked
        !          1384: interactively. 
        !          1385: If the \verb"push" option is used instead,
        !          1386: then the expansion will fail because \pgm{fred} will be unable to query 
        !          1387: the user to select/confirm the right entry to use for the substitution.
        !          1388: 
        !          1389: \section      {Tell The Users!}
        !          1390: OK, everything is installed and running,
        !          1391: so it's time for you to tell your users about the system!
        !          1392: Print out copies of \thebook/ and the accompanying
        !          1393: {\em White Pages Quick Reference Sheet},
        !          1394: and start distributing them.
        !          1395: Also, encourage your users to subscribe to the 
        !          1396: \begin{quote}\begin{verbatim}
        !          1397: [email protected]
        !          1398: \end{verbatim}\end{quote}
        !          1399: discussion group.
        !          1400: This is done by sending a message to the
        !          1401: \begin{quote}\begin{verbatim}
        !          1402: [email protected]
        !          1403: \end{verbatim}\end{quote}
        !          1404: mailbox and asking to be added.
        !          1405: 
        !          1406: \subsection    {More New and Exciting Stuff}
        !          1407: New and exciting white pages applications are written from time to time.
        !          1408: You should contact \verb"wpp-manager" to see if there's something fun that you
        !          1409: can try out.

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.