Return to q-dsa.tex CVS log

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

Annotation of 43BSDReno/contrib/isode-beta/doc/manual/q-dsa.tex, revision 1.1

1.1     ! root        1: %run this through LaTeX with the appropriate wrapper
        !             2: 
        !             3: \chapter {Installing QUIPU}
        !             4: 
        !             5: \label{quipu:install}
        !             6: 
        !             7: This section describes how to install QUIPU, and make it operate in a basic
        !             8: fashion.  This is reasonably prescriptive, as it should be possible to
        !             9: install and operate a QUIPU DUA and/or DSA without too much 
        !            10: knowledge about how it functions.
        !            11: 
        !            12: QUIPU comes in 4 separate parts of the ISODE tree, none of which are
        !            13: ``made'' as part of the default installation of ISODE.
        !            14: This section assumes you have installed ISODE.  
        !            15: You should consult the \file{READ-ME} file in the
        !            16: top level of the source tree, and \volone/ to \volfour/ of this Manual
        !            17: if you have not installed ISODE.
        !            18: 
        !            19: There are various options you can set which control
        !            20: the operation of QUIPU. These are set in the file \file{h/quipu/config.h}
        !            21: but are probably best left to their default values, unless you qualify
        !            22: as a ``large'' site.  Larger sites may want to consider enabling
        !            23: the TURBO options described in the next section.
        !            24: 
        !            25: To generate QUIPU type \verb"make all-quipu" in the top-level ISODE
        !            26: directory.
        !            27: 
        !            28: A version of \pgm{dish} that runs directly 
        !            29: from a \unix/ shell, 
        !            30: \pgm{dishinit}:
        !            31: a script to create a default \file{.quipurc} file for new users, and 
        !            32: \pgm{sid}: a set of scripts that utilise the shell version of dish, are all
        !            33: installed from the \file{others/quipu/uips/dish} directory.
        !            34: The \pgm{fred}, \pgm{widget} and \pgm{sunint} interfaces
        !            35: can be installed by looking at 
        !            36: \file{others/quipu/uips/READ-ME}.
        !            37: 
        !            38: Each of these interfaces knows about the ``photo'' attribute that an entry
        !            39: in the DIT can have.  In order to display the photographs, the photo
        !            40: handling code must be compiled, instructions on this can be found in
        !            41: Section~\ref{dua:photo} of this Manual and the file
        !            42: \file{others/quipu/photo/READ-ME}.
        !            43: 
        !            44: \section{TURBO Options for Large Sites}
        !            45: This section describes two options (TURBO\_LOAD and TURBO\_DISK) that
        !            46: can be set in the file \file{h/quipu/config.h}.  Both options are
        !            47: most useful for sites with a large amount of data (e.g. hundreds of
        !            48: entries per EDB file).  The first option, TURBO\_LOAD, can be used to speed
        !            49: the process of loading data from disk during startup.
        !            50: When QUIPU starts, it must check each entry that it loads
        !            51: against those sibling entries already loaded 
        !            52: to ensure that the data in each EDB
        !            53: file contains no duplicate entries.  Normally, this is done by 
        !            54: searching a linked list of loaded entries.  The TURBO\_LOAD option
        !            55: works by building and searching an AVL (height-balanced)
        !            56: tree instead of the linked list.  Also, it allocates space for this
        !            57: tree in large chunks to help reduce paging.  The AVL tree is only
        !            58: used during the loading process and does not affect operation of the
        !            59: DSA once the database is loaded.  There is some extra
        !            60: overhead involved in buildng the AVL tree, and the point at which
        !            61: the TURBO\_LOAD option starts improving things seems to be about
        !            62: 100+ entries per EDB file.  If you have EDB files containing 
        !            63: significantly more 
        !            64: than 100 entries, you may want to consider enabling the TURBO\_LOAD
        !            65: option.
        !            66: 
        !            67: To use the TURBO\_LOAD option, add a line like this to the
        !            68: \file{h/quipu/config.h} file:
        !            69: \begin{verbatim}
        !            70: #define TURBO_LOAD     /* enable fast loading of big EDB files */
        !            71: \end{verbatim}
        !            72: There are two run time tailor options you should be aware if the
        !            73: TURBO\_LOAD option has been enabled ({\it turbo\_size} 
        !            74: and {\it turbo\_namelen}).  These options are set in the 
        !            75: \file{quiputailor} file and should be left to their default values
        !            76: unless the loading process fails with a message indicating that
        !            77: these parameters should be changed.
        !            78: 
        !            79: The second option, TURBO\_DISK, can be used to make modify operations
        !            80: run much faster, especially on large data sets.  It requires the use
        !            81: of the \pgm{gdbm} library.  \pgm{Gdbm} is a library of simple database routines
        !            82: providing functionality similar to \pgm{dbm} and \pgm{ndbm}, but without the
        !            83: filesystem page size limitations of those systems.  \pgm{Gdbm} is GNU
        !            84: software and is available from the Free Software Foundation.  It is
        !            85: not a part of the ISODE.
        !            86: Normally, when an
        !            87: entry is modified, QUIPU writes the entire EDB file the entry lives
        !            88: in synchronously out to disk.  If the EDB file is very large, this can
        !            89: take some time, especially on a heavily loaded system.  The TURBO\_DISK
        !            90: option works by keeping the disk data in \pgm{gdbm} files instead of the
        !            91: regular EDB files.  This way, when an update is made, only the 
        !            92: affected entry need be written to disk.  The performance increase 
        !            93: is directly proportional to the size of the EDB file.
        !            94: Whereas a normal update operation takes time proportional to the size
        !            95: of the EDB file, with the TURBO\_DISK option it takes a small constant
        !            96: amount of time.  As for TURBO\_LOAD, if you don't have EDB files with
        !            97: at least a hundred or so entries, it's probably not worth enabling
        !            98: the TURBO\_DISK option.
        !            99: 
        !           100: To use the TURBO\_DISK option, add a line like this to the
        !           101: \file{h/quipu/config.h} file:
        !           102: \begin{verbatim}
        !           103: #define TURBO_DISK     /* enable fast EDB update operations */
        !           104: \end{verbatim}
        !           105: Next, if you have enabled the TURBO\_LOAD option as described above, you
        !           106: will need to edit the file \file{quipu/turbo\_disk.c} and make a small
        !           107: change.  The line:
        !           108: \begin{verbatim}
        !           109: #include "/u/up/tim/src/gdbm-1.3/gdbmdefs.h"
        !           110: \end{verbatim}
        !           111: should be changed to reflect the actual location of the \file{gdbmdefs.h}
        !           112: include file on your system.  Note that this file is not installed in
        !           113: the normal process of installing \pgm{gdbm}.  It is in the \pgm{gdbm} source
        !           114: directory.  Disgustingly enough, the {\it turbo\_start} routine needs
        !           115: to be able to {\it stat} the \pgm{gdbm} file, and needs the definitions
        !           116: in \file{gdbmdefs.h} to do so.  If you are not using the TURBO\_LOAD
        !           117: option, this step is not necessary.
        !           118: 
        !           119: Now make and install QUIPU as usual.  
        !           120: Before running QUIPU, you will have to
        !           121: convert your EDB file hierarchy into a gdbm file hierarchy.  This step
        !           122: is only necessary once.  The \file{quipu/turbo} directory contains some
        !           123: tools to help in this process.  The shell script \pgm{tree2dbm} will
        !           124: convert an EDB file hierarchy to a gdbm file hierarchy.  To use it,
        !           125: type ``\verb+tree2dbm database-directory+'' where database-directory is the
        !           126: directory where the EDB file hierarchy begins.  This script does a
        !           127: find starting in that directory for files named EDB and runs them through the
        !           128: \pgm{edb2dbm} program which creates a file called \file{EDB.gdbm}.
        !           129: The original EDB file is neither removed nor
        !           130: molested, so you'll need roughly twice the disk space.  Alternatively, you
        !           131: can run \pgm{edb2dbm} by hand on each EDB file.  The reverse operation
        !           132: (converting from a \pgm{gdbm} hierarchy to an EDB hierarchy) is done
        !           133: by the \pgm{synctree} shell script.  It is a good idea to run 
        !           134: \pgm{synctree} out of \file{crontab} once in a while to update the
        !           135: EDB file hierarchy.
        !           136: 
        !           137: Finally, it should be noted that parse errors will be reported
        !           138: somewhat differently in the \file{dsap.log} file with the
        !           139: TURBO\_DISK option enabled.  Since line numbers don't make much
        !           140: sense in a \pgm{gdbm} file, errors will be reported based on the
        !           141: Relative Distinguished Name of the offending entry.  If you get
        !           142: a parse error (because of a non-printable character, for example),
        !           143: the best approach is to do something like this:
        !           144: \begin{verbatim}
        !           145:        edbcat EDB >bob
        !           146:        edit the file bob, locate the entry, and fix the problem
        !           147:        edb2dbm bob
        !           148:        mv bob.gdbm EDB.gdbm
        !           149: \end{verbatim}
        !           150: where this procedure assumes you are in the directory containing
        !           151: the bad EDB.gdbm file.  The edbcat program can be found in the
        !           152: \file{quipu/turbo} directory and is used to convert from \pgm{gdbm}
        !           153: back to plain text EDB format.
        !           154: 
        !           155: \section{Files}
        !           156: Regardless of how you install QUIPU and the ISODE,
        !           157: the number of files needed to run QUIPU are quite small.
        !           158: 
        !           159: In ISODE's \verb"BINDIR" directory,
        !           160: typically \file{/usr/local/bin/},
        !           161: there are a few programs of interest:
        !           162: \begin{describe}
        !           163: \item[dish:]   The DIrectory SHell\\
        !           164:                This is discussed in Chapter~\ref{dish}.
        !           165: 
        !           166: \item[bind:]   Shell interface to \pgm{dish}\\
        !           167:                There are actually several links (listed below) to a program called
        !           168:                \pgm{bind}.
        !           169:                These act to export the \pgm{dish} interface to the \unix/
        !           170:                shell.
        !           171:                As such,
        !           172:                you can issue commands to \pgm{dish} from the shell,
        !           173:                rather than running \pgm{dish} directly.
        !           174: \begin{quote}
        !           175: \begin{tabular}{l}
        !           176: add\\
        !           177: compare\\
        !           178: delete\\
        !           179: dsacontrol\\
        !           180: list\\
        !           181: modify\\
        !           182: modifyrdn\\
        !           183: moveto\\
        !           184: search\\
        !           185: showentry\\
        !           186: showname\\
        !           187: squid
        !           188: \end{tabular}
        !           189: \end{quote}
        !           190: 
        !           191: \item[fred:]   A white pages user interface\\
        !           192:                See Chapter~\ref{DUA:fred}.
        !           193: 
        !           194: \item[editentry:]      Edit a Directory entry\\
        !           195:                This is a simple shell script that \pgm{dish} invokes when you
        !           196:                ask \pgm{dish} to edit an entry in the Directory.
        !           197: 
        !           198: \item[unbind:] Unbind from \pgm{dish}\\
        !           199:                This command is used to terminate \pgm{dish}.
        !           200: \end{describe}
        !           201: In ISODE's \verb"SBINDIR" directory,
        !           202: typically \file{/usr/etc/},
        !           203: the DSA resides:
        !           204: \begin{describe}
        !           205: \item[ros.quipu:]      The QUIPU DSA\\
        !           206:                        This program will be started once, for each DSA you
        !           207:                        are running, from rc.local.
        !           208:                        A script is provided to invoke this program,
        !           209:                        in case you need to restart it.
        !           210: 
        !           211: %%%\item[dsaconfig:]   a configurator for Level-1 DSAs.
        !           212: \end{describe}
        !           213: In ISODE's \verb"ETCDIR" directory,
        !           214: also typically \file{/usr/etc/},
        !           215: there are a few programs and files of interest:
        !           216: \begin{describe}\sloppy
        !           217: \item[oidtable.at, oidtable.gen, oidtable.oc:]
        !           218:                        These define the attribute types,
        !           219:                        generic object identifiers,
        !           220:                        and object classes known to the system.
        !           221:                        (An object identifier is a method used to unambiguously
        !           222:                        encode, among other things,
        !           223:                        the names of attributes and object classes.)
        !           224:                        These files you never deal with unless they are
        !           225:                        accidently corrupted.
        !           226:                        
        !           227: \item[dsaptailor:]     This is the run-time tailor file for the DUAs.
        !           228:                        You will configure this file initially and then
        !           229:                        probably leave it alone.
        !           230: 
        !           231: 
        !           232: \item[isoaliases, isobjects, isoentities, isomacros, isoservices:]
        !           233:                        These are \\ %%%
        !           234:                        various databases used by the ISODE.
        !           235:                        These files you never deal with unless they are
        !           236:                        accidently corrupted.
        !           237: 
        !           238: \item[isologs:]                This script runs nightly under \man cron(8) to
        !           239:                        trim the ISODE log files, kept in ISODE's \verb"LOGDIR"
        !           240:                        directory,
        !           241:                        typically \file{/usr/tmp/}.
        !           242:                        This file you never deal with unless it is
        !           243:                        accidently corrupted.
        !           244: 
        !           245: \item[isotailor:]      This is the run-time tailor file for the ISODE.
        !           246:                        You will configure this file initially and then
        !           247:                        probably leave it alone.
        !           248: \end{describe}
        !           249: 
        !           250: \chapter {Configuring a DUA}
        !           251: 
        !           252: It is suggested that you try to get a DUA operational by connecting to
        !           253: a ``well known'' DSA before you attempt
        !           254: to operate a local DSA.
        !           255: Or, if you have a DSA from a previous release of QUIPU - try an connect to
        !           256: that.
        !           257: 
        !           258: \section {Connecting to a DSA}
        !           259: \label{dua:connect}
        !           260: 
        !           261: A DUA essentially only needs to know one thing to be able to contact a
        !           262: DSA, that is the network address of the DSA.
        !           263: This parameter is defined in the file \file{dsaptailor}, 
        !           264: together with some other parameters.
        !           265: The full set of parameters are described in Section \ref{dua:tailor}.
        !           266: 
        !           267: The \verb"dsa_address" parameter defines the name and address of the DSA to 
        !           268: initially contact. For example,
        !           269: \begin{quote}\begin{verbatim}
        !           270: dsa_address  vicuna  Internet=bells.cs.ucl.ac.uk+50987
        !           271: \end{verbatim}\end{quote}
        !           272: 
        !           273: declares the DSA \verb"vicuna" at the indicated presentation 
        !           274: address\footnote{The syntax of presentation addresses is discussed in
        !           275: \volone/ of this manual and \cite{String.Addresses}.}
        !           276: \index{presentation addresses}
        !           277: to be the
        !           278: default DSA for the DUA to contact.
        !           279: As shown above, the address is preceded by a private key.  This can
        !           280: be used in some DUAs (including DISH) to specifying the address of the DSA 
        !           281: to contact.
        !           282: If there are more than one \verb"dsa_address" entries, the first
        !           283: entry will be used to supply the default DSA address.
        !           284: 
        !           285: A default dsaptailor file 
        !           286: (taken from \file{dsap/dsaptailor}) is installed as
        !           287: \file{dsaptailor} in the ISODE \verb"ETCDIR" directory
        !           288: (usually \file{/usr/etc/}) when
        !           289: the dsap library is installed, this supplies the addresses
        !           290: of various DSAs that you
        !           291: may be able to access.
        !           292:  
        !           293: To try to connect to one of the DSAs listed in dsaptailor, 
        !           294: invoke \pgm{dish}, with a \verb"-call"
        !           295: flag, e.g. ``\verb"dish -call giant"'' will try to contact the DSA ``giant''
        !           296: running at UCL.
        !           297: If the connection is successful, then the prompt ``\verb"dish ->"'' will be returned.
        !           298: If the connection fails, the
        !           299: program will exit with an appropriate error
        !           300: message.
        !           301: 
        !           302: If this fails
        !           303: you might want to 
        !           304: try connecting to some of the other registered DSAs,
        !           305: for example, try ``\verb"dish -call alpaca"'', ``\verb"dish -call eel"'' 
        !           306: or ``\verb"dish -call anaconda"''.
        !           307: A list of registered DSAs is given in Appendix~\ref{dsa:sites}.
        !           308: 
        !           309: If you fail to contact a DSA at this point, there are likely to be lower
        !           310: level problems. You should turn up the ISODE logging 
        !           311: (see \voltwo/ of this manual) to see what is happening to the 
        !           312: network calls.
        !           313: 
        !           314: If you invoke \pgm{dish} without a \verb"-c" flag (using the default \file{dsaptailor}), it will 
        !           315: try to connect to the DSA defined by the first
        !           316: \verb"dsa_address" entry.
        !           317: 
        !           318: \pgm{dish} is described in full in Chapter~\ref{dish} 
        !           319: of this Manual.
        !           320: 
        !           321: \section{Tailoring}
        !           322: \label{dua:tailor}
        !           323: \index{dsaptailor}
        !           324: 
        !           325: The program configuration is tailored to
        !           326: allow you to change logging levels, and other parameters at
        !           327: run time.  
        !           328: It is used by the QUIPU DUA procedures, and by the QUIPU User Interfaces.
        !           329: 
        !           330: The file \file{dsaptailor} is used for this purpose and
        !           331: consists of single value entries (e.g. oidtable), unless otherwise
        !           332: stated (e.g dsaplog). 
        !           333: Each entry has a parameter followed by its
        !           334: value.
        !           335: The various options are:
        !           336: \begin{describe}
        !           337: \item [\verb"oidtable":]
        !           338: The path for the OID definition tables.
        !           339: NOTE: It is best to have this appear as the first entry of the tailor file, as
        !           340: other entries may contain attributes that need to be looked up in these
        !           341: tables
        !           342: There are three:
        !           343: \begin{itemize}
        !           344: \item \file{file.gen},
        !           345: which contains generic names for building OIDs;
        !           346: \item \file{file.at},
        !           347: which contains the OIDs for attributes; and,
        !           348: \item \file{file}.oc,
        !           349: which contains the OIDs for object classes.
        !           350: \end{itemize}
        !           351: For example,
        !           352: \begin{quote}\small\begin{verbatim}
        !           353: oidtable    /usr/lib/quipu/OIDTable
        !           354: \end{verbatim}\end{quote}
        !           355: will direct the DSA to consult:
        !           356: \begin{quote}\begin{verbatim}
        !           357: /usr/lib/quipu/OIDTable.gen
        !           358: /usr/lib/quipu/OIDTable.at
        !           359: /usr/lib/quipu/OIDTable.oc
        !           360: \end{verbatim}\end{quote}
        !           361: By default this is set to \verb"oidtable" which refers to the tables
        !           362: \file{oidtable.*} in the ISODE \verb"ETCDIR" directory.
        !           363: 
        !           364: \item [\verb"dsa\_address":]
        !           365: This parameter is described in Section~\ref{dua:connect}.
        !           366: 
        !           367: \item [\verb"dsaplog":]
        !           368: Tailoring for the normal logging file.
        !           369: Each entry consists of one or more key/value pairs expressed as:
        !           370: \begin{quote}\small\begin{verbatim}
        !           371: key=value
        !           372: \end{verbatim}\end{quote}
        !           373: The keys are:
        !           374: \begin{describe}
        !           375: \item [\verb"file":]
        !           376: The name of the logfile.
        !           377: \item [\verb"size":]
        !           378: The size in KBytes to which the logfile should be allowed to grow.
        !           379: When the log has reached this size, if the ``zero'' option
        !           380: below is set, then the log will be truncated, otherwise, no further
        !           381: logging will take place.
        !           382: \item [\verb"level":]
        !           383: The levels of logging to be written to this log file.
        !           384: This can be any of the following levels:
        !           385: \begin{describe}
        !           386: \item [\verb"fatal":]
        !           387: fatal errors only
        !           388: \item [\verb"exceptions":]
        !           389: serious, but hopefully temporary, errors
        !           390: \item [\verb"notice":]
        !           391: general logging information
        !           392: \item [\verb"trace":]
        !           393: program tracing
        !           394: \item [\verb"pdus":]
        !           395: pdu tracing
        !           396: \item [\verb"debug":]
        !           397: full tracing of events
        !           398: \item [\verb"all":]
        !           399: log all events
        !           400: \end{describe}
        !           401: For example to have all errors written to the file you will need
        !           402: \begin{quote}\footnotesize\begin{verbatim}
        !           403: dsaplog level=fatal level=exceptions
        !           404: \end{verbatim}\end{quote}
        !           405: \item [\verb"dlevel":]
        !           406: Do not log the specified log level, this is the opposite of the above
        !           407: entry.
        !           408: \item [\verb"dflags"/\verb"sflags":]
        !           409: The flags associated with the log may be set (with \verb"sflag")
        !           410: or unset (with \verb"dflag"). The allowable options are:
        !           411: \begin{describe}
        !           412: \item [\verb"close":]
        !           413: close the log after each entry
        !           414: \item [\verb"create":]
        !           415: create the log file if it doesn't exist
        !           416: \item [\verb"zero":]
        !           417: truncate the file when it gets too big
        !           418: \item [\verb"tty":]
        !           419: copy the logging information to the users tty
        !           420: \end{describe}
        !           421: \end{describe}
        !           422: An example might be:
        !           423: \begin{quote}\footnotesize\begin{verbatim}
        !           424: dsaplog level=notice size=30 file=quipulog dflags=close
        !           425: \end{verbatim}\end{quote}
        !           426: This says log events at ``notice'' level, into the file ``quipulog'', do not
        !           427: let the file grow larger than 30Kbytes, and do not close the file
        !           428: after each logging message.
        !           429: 
        !           430: \item [\verb"stats":] Used to control the level of statistical logging
        !           431: (parameters as for \verb+dsaplog+ above).
        !           432: 
        !           433: \item [\verb"local\_DIT":]
        !           434: The argument is a distinguished name.  When some User Interfaces start, you
        !           435: will be automatically moved to this position in the DIT.
        !           436: 
        !           437: \item [\verb"oidformat":]
        !           438: Defines how object identifiers should be printed.
        !           439: Use one of:
        !           440: \begin{quote}\small\begin{verbatim}
        !           441: oidformat   short
        !           442: \end{verbatim}
        !           443: \end{quote}
        !           444: to print in short local key form, e.g.,
        !           445: \begin{quote}\small\begin{verbatim}
        !           446: Country
        !           447: \end{verbatim}\end{quote}
        !           448: or,
        !           449: \begin{quote}\small\begin{verbatim}
        !           450: oidformat   long
        !           451: \end{verbatim}
        !           452: \end{quote}
        !           453: to print in long object identifier form, e.g.,
        !           454: \begin{quote}\small\begin{verbatim}
        !           455: joint.ds.attributeType.country
        !           456: \end{verbatim}\end{quote}
        !           457: or,
        !           458: \begin{quote}\small\begin{verbatim}
        !           459: oidformat   numeric
        !           460: \end{verbatim}
        !           461: \end{quote}
        !           462: to print in numeric form, e.g.,
        !           463: \begin{quote}\small\begin{verbatim}
        !           464: 2.5.4.6
        !           465: \end{verbatim}\end{quote}
        !           466: 
        !           467: \item [\verb"photo":]
        !           468: The argument is has two parts, a ``terminal type'' such as
        !           469: ``sun'' or ``xterm'', the second is the name of the process that should
        !           470: handle displaying of photographs, for example
        !           471: \begin{quote}
        !           472: photo xterm Xphoto
        !           473: \end{quote}
        !           474: tells the DUA to call the process Xphoto to handle photograph attributes if
        !           475: the user is on a terminal of type ``xterm''.
        !           476: Handling photographs is described more fully in Section~\ref{dua:photo}.
        !           477: 
        !           478: \item [\verb"quipurc":]
        !           479: If the argument has the value \verb"on", then a program called 
        !           480: \pgm{dishinit} will be run every time a user without a ``.quipurc''
        !           481: file tries to access the directory. \pgm{dishinit} is discussed 
        !           482: in Section~\ref{dishinit}.
        !           483: 
        !           484: \item [\verb"sizelimit":]
        !           485: Defines the maximum number of entries a successful list or search should
        !           486: return.
        !           487: For example,
        !           488: \begin{quote}\small\begin{verbatim}
        !           489: sizelimit 20
        !           490: \end{verbatim}\end{quote}
        !           491: sets the DAP default service control ``sizelimit'' to be 20 entries.
        !           492: \end{describe}
        !           493: 
        !           494: \chapter {Configuring a DSA}
        !           495: 
        !           496: This Chapter discusses how to configure a QUIPU DSA.
        !           497: We recommend that you get a DUA running before you try to
        !           498: get a DSA working.
        !           499: 
        !           500: \section{Basic Formats and Structures}
        !           501: 
        !           502: All of the information a DSA requires is
        !           503: stored on disk and is text structured.  This includes
        !           504: various files (described later), and the local DIT database itself.
        !           505: A complete BNF description of the files 
        !           506: is given in Appendix~\ref{bnf} on page~\pageref{bnf}.
        !           507: 
        !           508: \subsection {Entry Data Block}
        !           509: \label{edb}
        !           510: A key component of the Directory database is the Entry Data Block, which is
        !           511: described fully in \cite{QUIPU.Design}.
        !           512: Figure \ref{example_edb} shows an example EDB \index{EDB} file containing two ``person''
        !           513: entries.
        !           514: 
        !           515: \begin{figure}
        !           516: \smaller
        !           517: \begin{verbatim}
        !           518: MASTER
        !           519: 19891025113003Z
        !           520: CN= Colin Robbins 
        !           521: CN= Colin John Robbins 
        !           522: Phone= +44-1-387-7050 ext 3683 
        !           523: Surname= Robbins 
        !           524: Room= G10 
        !           525: Userid= crobbins
        !           526: userClass= csstaff
        !           527: rfc822Mailbox= [email protected]
        !           528: Photo= {FILE}crobbins.photo 
        !           529: objectClass =thornPerson & quipuObject
        !           530: acl=others # none # attribute # photo 
        !           531: acl=self # read # attribute # photo 
        !           532: 
        !           533: CN= Steve Kille 
        !           534: CN= Steve E. Kille & Stephen Kille 
        !           535: Phone= +44-1-387-7050 ext 7294 
        !           536: Surname= Kille 
        !           537: objectClass = thornPerson & quipuObject 
        !           538: Room= G24 
        !           539: Userid= steve
        !           540: userClass= csstaff
        !           541: rfc822Mailbox= [email protected]
        !           542: \end{verbatim}
        !           543: \caption{Example EDB File}
        !           544: \label{example_edb}
        !           545: \end{figure}
        !           546: 
        !           547: 
        !           548: An EDB file contains a header, followed by a sequence of entries.
        !           549: 
        !           550: The header consists of two lines of text, the first must contain the string
        !           551: ``\verb"MASTER"'', ``\verb"SLAVE"'' or ``\verb"CACHE"'', 
        !           552: which indicates whether the data in the EDB
        !           553: file represents the authoritative \verb"MASTER" data, a \verb"SLAVE"
        !           554: copy of the data, or \verb"CACHE"d entries.
        !           555: The next line is a string that describes the version of the EDB. Every
        !           556: time the EDB is altered, the version\index{version - of an EDB} number
        !           557: should be changed, so that
        !           558: \verb"SLAVE" EDBs elsewhere will be automatically updated.
        !           559: When a DSA alters an EDB file, it writes the current (UTC) time in string
        !           560: format as the version string.
        !           561: 
        !           562: Following the header are a sequence of blank line separated entries.
        !           563: An entry consists of a set of attributes.  The first line is
        !           564: the Relative Distinguished Name
        !           565: \index{RDN} (RDN) of the entry.
        !           566: 
        !           567: \subsection{Object Class attribute}
        !           568: Of the attributes an entry may have, the ``objectClass''\index{objectClass attribute}
        !           569: attribute is one of the most important from the configuration point of view.
        !           570: It defines the set of mandatory and optional attributes that must and may be
        !           571: present in the entry.
        !           572: For example, the object class ``person'' insists that there is a ``surname''
        !           573: attribute, and there may optionally be a ``telephone number'' attribute.
        !           574: 
        !           575: QUIPU knows about all the standard object classes and attributes, some of
        !           576: those defined by the THORN\index{thorn} project (see Section~\ref{thorn:na}) and
        !           577: those defined by QUIPU itself (see Appendix~\ref{naming}).
        !           578: The full set of object classes and attributes a DSA knows about is
        !           579: defined by the ``oidtables'' which are explained in Section~\ref{oidtables}.
        !           580: 
        !           581: An entry can belong to more that one object class.
        !           582: For example, an entry representing an organisation might have the following
        !           583: object class attribute:-
        !           584: \begin{quote}\small\begin{verbatim}
        !           585: objectClass = organization & quipuNonLeafObject
        !           586: \end{verbatim}\end{quote}
        !           587: And a person within that organisation might use the following object class
        !           588: definition:-
        !           589: \begin{quote}\small\begin{verbatim}
        !           590: objectClass = organizationalPerson & quipuObject & thornPerson
        !           591: \end{verbatim}\end{quote}
        !           592: Every entry in a QUIPU DSA should belong to either the ``\verb"quipuObject"''
        !           593: or ``\verb"quipuNonLeafObject"'' object classes, as this allows
        !           594: attributes the DSA needs to be added to an entry.
        !           595: 
        !           596: Further, object classes posses the notion of 
        !           597: \verb"class inheritance".
        !           598: This means that an object class can be defined as a ``subclass'' of
        !           599: a previously defined object class with additional refinements.
        !           600: As a subclass,
        !           601: the newly defined object ``inherits'' all the semantics of its
        !           602: superclass,
        !           603: in addition to having additional semantics.
        !           604: 
        !           605: For example,
        !           606: the Directory defines an object class called \verb"person".
        !           607: This object class defines the attributes which a person in
        !           608: the real world might have.
        !           609: It may be useful to refine this somewhat to talk about persons
        !           610: who have network access.
        !           611: So, we need a new object class, e.g., \verb"netPerson".
        !           612: This can be defined in a straight-forward fashion:
        !           613: \begin{quote}
        !           614: The object class \verb"netPerson" is a subclass of the object class
        !           615: \verb"person" which {\em may\/} contain an additional attribute,
        !           616: \verb"netMailbox".
        !           617: 
        !           618: The syntax of an \verb"netMailbox" is a simple string of printable
        !           619: characters which is not case sensitive when performing comparisons.
        !           620: \end{quote}
        !           621: 
        !           622: It is a Quipu requirement that every entry that is not a leaf of the DIT 
        !           623: should belong to the object class
        !           624: ``\verb"quipuNonLeafObject"''. 
        !           625: 
        !           626: This class has one mandatory attribute:
        !           627: \begin{describe}
        !           628: \item[masterDSA:]\index{masterDSA attribute}
        !           629:                        identifies the Directory entity which is responsible
        !           630:                        for maintaining the MASTER EDB for the children of
        !           631:                        this entry.
        !           632:                        The value is a Distinguished Name.
        !           633: \end{describe}
        !           634: There is typically a single MASTER for a particular entry in the tree.
        !           635: Hence, this value is usually single-valued.
        !           636: When an entry is to be modified,
        !           637: the Directory must contact the entity responsible for the MASTER EDB for
        !           638: that entry in order to perform the modification.
        !           639: 
        !           640: This class has two optional attributes:
        !           641: \begin{describe}
        !           642: \item[slaveDSA:]\index{slaveDSA attribute}
        !           643:                        identifies any Directory entities which have
        !           644:                        authoritative copies of the EDB for the children
        !           645:                        of this entry.
        !           646:                        The value is one or more Distinguished Names.
        !           647: 
        !           648: \item[treeStructure:]\index{treeStructure attribute}
        !           649:                        identifies the object classes which may exist
        !           650:                        immediately below this entry.
        !           651:                        The value is one or more object classes.
        !           652:                        See Section~\ref{quipu:schema} for full details
        !           653:                        of how to set this attribute.
        !           654: \end{describe}
        !           655: Since a fundamental assumption of the Directory is that reads (queries)
        !           656: occur much more frequently than writes (updates),
        !           657: it is common to have several entities containing authoritative copies of an
        !           658: EDB.
        !           659: By keeping copies locally,
        !           660: queries can be answered with less latency.
        !           661: 
        !           662: \subsection {Database Structure}
        !           663: 
        !           664: All the information held by the Directory in its in-core database, is loaded
        !           665: from disk when the Directory starts. 
        !           666: The data on disk is held in a \unix/ tree of EDB files that map
        !           667: the DIT.
        !           668: At every level in the DIT for which the DSA holds data, there is a single
        !           669: file called \file{EDB}\index{EDB file}.
        !           670: If an entry defined in an \file{EDB} file has
        !           671: children, the \file{EDB} file for the children will be found in a
        !           672: sub-directory whose name is the string encoded Relative
        !           673: Distinguished Name of the entry.
        !           674: For example, if an \file{EDB} file has an entry whose RDN is
        !           675: ``ou= Computer Science'', then if the entry ``ou= Computer Science'' has children and is stored locally,
        !           676: it can be found in the file \file{ou=Computer Science/EDB} relative to the current directory.
        !           677: NOTE that the case sensitivity of the sub-directory naming is one of the
        !           678: few areas within QUIPU where string matching is case sensitive.
        !           679: The case of the attribute type is taken from the definition of the attribute
        !           680: in the oid tables, whereas the case of the attribute value is the same as
        !           681: that found in the EDB file.
        !           682: 
        !           683: When an entry is modified, the modified \file{EDB} file is re-written to
        !           684: disk.  The old \file{EDB} is renamed \file{EDB.bak} to provide
        !           685: a back-up.
        !           686: 
        !           687: \subsection{Long Distinguished Names}
        !           688: \label{EDB:mapped}
        !           689: There is a problem with the above method for naming \unix/ sub directories
        !           690: with some versions of \unix/ --- particularly System~V.
        !           691: In these systems directory names are limited in length.
        !           692: 
        !           693: To allow for this, \verb"any" distinguished name can be given a mapping
        !           694: name, which will be used as the \unix/ sub-directory name.
        !           695: For example the entry for ``o=University College London'', may be mapped and
        !           696: stored in the file \file{UCL/EDB}.
        !           697: The mapped names are specified in a file \file{EDB.map}\index{EDB.map file},
        !           698: the syntax of which is:
        !           699: \begin{quote}\begin{verbatim}
        !           700: <Distinguished Name> `#' <Mapped name>
        !           701: \end{verbatim}\end{quote}
        !           702: so for the example used above the file will contain:
        !           703: \begin{quote}\begin{verbatim}
        !           704: o=University College London#UCL
        !           705: \end{verbatim}\end{quote}
        !           706: 
        !           707: If a name is not found in the mapping file, then the long directory name will
        !           708: be used. 
        !           709: 
        !           710: When a DSA needs to create a sub-directory (e.g after an add operation)
        !           711: it will use the relative distinguished name for each subdirectory,
        !           712: unless the name is longer than the maximum number of allowed characters
        !           713: (usually 15), in which case it will generate a shorter mapped name.
        !           714: 
        !           715: \section {Setting up an Initial DSA}
        !           716: 
        !           717: These instructions are assuming that you are trying to set up a DSA with the
        !           718: following characteristics:-
        !           719: \begin{itemize}
        !           720: \item It is the first DSA in an Organisation
        !           721: \item It is not the first DSA in the Country
        !           722: \item It holds a copy of the root EDB
        !           723: \end{itemize}
        !           724: 
        !           725: This is found in the example:-
        !           726: \begin{quote}
        !           727: \file{others/quipu/quipu-db/organisation} 
        !           728: \end{quote}
        !           729: 
        !           730: There are two other examples which might also be used as illustrations for
        !           731: national DSAs and organisational DSAs not holding a copy of the root EDB.
        !           732: These are in :-
        !           733: \begin{quote}
        !           734: \file{others/quipu/quipu-db/national}
        !           735: \end{quote}
        !           736: and
        !           737: \begin{quote}
        !           738: \file{others/quipu/quipu-db/non-root}
        !           739: \end{quote}
        !           740: 
        !           741: Note that if you are going to be running a DSA in the United States,
        !           742: then you should skip this section and refer to the document
        !           743: \cite{NYSER.Admin},
        !           744: which is provided in the ISODE documentation set
        !           745: (look in the source tree area for the directory \file{doc/whitepages/admin/}).
        !           746: This document describes turn-key installation mechanisms for DSAs in the
        !           747: United States.
        !           748: 
        !           749: To start a DSA with one of these example databases
        !           750: go into the relevant database directory and type:-
        !           751: \begin{quote}\begin{verbatim}
        !           752: $(SBINDIR)ros.quipu -t ./quiputailor
        !           753: \end{verbatim}\end{quote}
        !           754: 
        !           755: The \tt -t\rm \ flag tells Quipu to use the tailor file \file{./quiputailor}
        !           756: rather than the default file (\file{quiputailor} in the ISODE \verb"ETCDIR"
        !           757: directory).
        !           758: 
        !           759: This will cause the DSA to print some logging information onto the screen,
        !           760: followed by the message
        !           761: \begin{quote}\begin{verbatim}
        !           762: DSA c=GB@cn=toucan has started on localHost=17003
        !           763: \end{verbatim}\end{quote}
        !           764: 
        !           765: \begin{figure}
        !           766: \smaller
        !           767: \begin{verbatim}
        !           768: cn=Toucan
        !           769: presentationAddress= localHost=17003
        !           770: edbinfo= #cn=giant tortoise##
        !           771: description= Demonstration slave-root DSA
        !           772: description= Bird with large colourful bill.
        !           773: objectClass= quipuDSA & quipuObject
        !           774: manager= c=GB@o=University College London@ou=Computer Science@cn=Colin Robbins
        !           775: acl= self # write # attributes # acl $ userPassword
        !           776: acl= others # compare # attributes # acl $ userPassword
        !           777: userPassword = toucan
        !           778: quipuVersion= 6.0 Distribution
        !           779: supportedApplicationContext= QuipuDSP & X500DSP & X500DAP
        !           780: \end{verbatim}
        !           781: \caption{Example DSA Entry}
        !           782: \label{DSA:Toucan}
        !           783: \end{figure}
        !           784: 
        !           785: The default setup assumes you have TCP/IP access and starts a DSA on the IP
        !           786: address of the local machine (127.0.0.1).  If you do not have TCP/IP, you
        !           787: will need to change the address the DSA will attempt to listen on.
        !           788: This is done by editing the file 
        !           789: \begin{quote}
        !           790: \file{others/quipu/quipu-db/organisation/c=GB/EDB}
        !           791: \end{quote}
        !           792: The first entry in this file is the entry for a DSA called
        !           793: ``c=GB@cn=Toucan'', which is the name of the DSA we are trying to start (as
        !           794: defined by the ``mydsaname'' entry in quiputailor).
        !           795: The entry is shown in Figure~\ref{DSA:Toucan}.
        !           796: The attribute \verb"presentationAddress" defines the address that the DSA is
        !           797: going to listen to the network on.
        !           798: If you need to listen on a different address, you should change the value of
        !           799: the attribute to the address you want to listen on.
        !           800: For more details of address see \volone/ of this manual and
        !           801: \cite{String.Addresses}, an example of an X.25 address is given below:
        !           802: \begin{quote}\begin{verbatim}
        !           803: presentationAddress= Int-X25(80)=23421920030045
        !           804: \end{verbatim}\end{quote}
        !           805: 
        !           806: Having started your DSAs you should be able to connect to it by
        !           807: invoking \pgm{dish}. If you are using the default DSA address, and are
        !           808: using the default \file{dsaptailor} file, then invoking \pgm{dish}
        !           809: without arguments is sufficient.
        !           810: If you are not using the default address or ``dsaptailor'' file, then you
        !           811: will need to edit \file{dsaptailor} in the ISODE \verb"ETCDIR" directory.
        !           812: You should add an entry
        !           813: \begin{quote}\begin{verbatim}
        !           814: dsa_address  toucan  <presentation address>
        !           815: \end{verbatim}\end{quote}
        !           816: Note that \verb+<presentation address>+ should have {\em exactly} the same
        !           817: value as 
        !           818: the \verb+presentationAddress+ attribute in the DSAs entry in the EDB file.
        !           819: Now to contact the DSA use
        !           820: \begin{quote}\begin{verbatim}
        !           821: dish -c toucan
        !           822: \end{verbatim}\end{quote}
        !           823: 
        !           824: 
        !           825: Once connected to the DSA, try issuing the
        !           826: command:-
        !           827: \begin{quote}\small\begin{verbatim}
        !           828: list "@c=GB@o=University College London@ou=Computer Science"
        !           829: \end{verbatim}\end{quote}
        !           830: You should get a list of four names 
        !           831: back:-
        !           832: \begin{quote}\begin{verbatim}
        !           833: 1 commonName=Colin Robbins
        !           834: 2 userid=quipu%commonName=Colin Robbins
        !           835: 3 commonName=Steve Kille
        !           836: 4 commonName=Michael Roe
        !           837: \end{verbatim}\end{quote}
        !           838: If this happens you have a working DSA.
        !           839: (The entry numbered 2, is an example of an RDN with multiple values !)
        !           840: 
        !           841: \subsection{Setting up YOUR DSA}
        !           842: The examples are tailored to start a DSA called ``toucan'',
        !           843: and will be sufficient to get an example DSA started,
        !           844: but this will not be of much use when you want to start adding you own data.
        !           845: To allow other DSA to connect to you, you will need a new unique
        !           846: distinguished name for
        !           847: your own DSA.
        !           848: Section~\ref{dsa:connect} describes how to choose a name for your DSA and set
        !           849: up the connections.
        !           850: 
        !           851: A DSA needs to find the entry associated with its own name, it will generally
        !           852: be able to find this in the local database (the entry ``cn=toucan'' 
        !           853: in the file \file{quipu-db/organisation/c=GB/EDB} for example).
        !           854: 
        !           855: Having located its own entry, a DSA will know its network 
        !           856: address by looking at the \verb+presentionAddress+ attribute,
        !           857: hence it can start listening for operations.
        !           858: 
        !           859: But first it must load the database.
        !           860: In its own entry it will have a \verb"edbInfo" attribute, this 
        !           861: describes which EDBs the DSA is expected to hold.
        !           862: The format of the \verb"edbInfo" \index{edbInfo attribute} attribute is described fully in 
        !           863: Section~\ref{slave_update}, but essentially the first parameter
        !           864: supplied says ``load this EDB''. Thus the attribute
        !           865: \begin{quote}\begin{verbatim}
        !           866: edbInfo = ##
        !           867: edbInfo = c=US@o=The Wollongong Group ##
        !           868: edbInfo = c=GB ##
        !           869: \end{verbatim}\end{quote}
        !           870: requests that the EDB files 
        !           871: \begin{quote}
        !           872: \file{quipu-db/EDB}
        !           873: \end{quote}
        !           874: (signified by no data before the first `\verb+#+' sign),
        !           875: \begin{quote}
        !           876: \file{quipu-db/c=US/o=The Wollongong Group/EDB} 
        !           877: \end{quote}
        !           878: and 
        !           879: \begin{quote}
        !           880: \file{quipu-db/c=GB/EDB}
        !           881: \end{quote}
        !           882: are loaded.
        !           883: 
        !           884: There are a few other important attributes your DSAs entry should have, the ``toucan''
        !           885: entry in Figure~\ref{DSA:Toucan} gives examples of the other attributes.
        !           886: They are briefly described below.
        !           887: \begin{describe}
        !           888: \item[description] A Textual message describing the DSA, and the wildlife!
        !           889: \item[quipuVersion] This should contain the version number of the
        !           890: Quipu software you are using.  This can be found by using the dish
        !           891: command \verb+squid -version+.
        !           892: \item[manager] The DN of the manager of the DSA, this user will not be blocked by
        !           893: access control when modifying the local database over DAP.
        !           894: \item[supportedApplicationContext] This should always have the value
        !           895: \begin{quote}\begin{verbatim}
        !           896: QuipuDSP \& X500DSP \& X500DAP
        !           897: \end{verbatim}\end{quote}
        !           898: for this version of Quipu.
        !           899: It is used by remote DSAs to decide which protocols your
        !           900:  DSA supports, and
        !           901: thus how best to contact it.
        !           902: \end{describe}
        !           903: 
        !           904: To connect a DUA to this DSA, 
        !           905: try typing \verb"dish", the DUA will try to contact the default DSA.
        !           906: 
        !           907: If you have changed the address of the default DSA
        !           908: (by modifying the ``presentationAddress'' attribute of the DSAs entry)
        !           909: you will need to modify the 
        !           910: \verb"dsa_address" variable in the file \file{dsaptailor} to tell the DUAs
        !           911: your DSAs address.
        !           912: If you add
        !           913: \begin{quote}\begin{verbatim}
        !           914: dsa_address mydsa <the presentation address>
        !           915: \end{verbatim}\end{quote}
        !           916: to your \file{dsaptailor} file, then
        !           917: \begin{quote}\begin{verbatim}
        !           918: dish -c mydsa
        !           919: \end{verbatim}\end{quote}
        !           920: should connect you to your new DSA.
        !           921: 
        !           922: Section~\ref{adding_data} describes how you can add data to you DSA by
        !           923: extending the supplied textual database to include your 
        !           924: own data
        !           925: or by sending data to the Directory via the DUA modify operations.
        !           926: This may be done independently from connecting to the global directory.
        !           927: 
        !           928: \section {Tailoring}\label{dsa:tailor}
        !           929: 
        !           930: On start up the DSA first consults a run time tailor file \index{quiputailor}
        !           931: (the default DSA tailor file is called \file{quiputailor} in the ISODE
        !           932: \verb"ETCDIR" directory, but can be
        !           933: changed with a \verb"-t" parameter to \pgm{ros.quipu};
        !           934: consult \man quipu(8c) for details),
        !           935: which indicates such things as:
        !           936: 
        !           937: \begin{itemize}
        !           938: \item
        !           939: name of the DSA
        !           940: \item
        !           941: location of the database
        !           942: \item
        !           943: location and level of the logs that the DSA will produce.
        !           944: \item
        !           945: location of any other DSAs for initial bootstrap
        !           946: \end{itemize}
        !           947: 
        !           948: 
        !           949: The format is identical to the DUA tailor file
        !           950: described in Section~\ref{dua:tailor}, with the addition of the
        !           951: following options:
        !           952: \begin{describe}
        !           953: \item [\verb"mydsaname":]
        !           954: The distinguished name of the DSA.
        !           955: For example,
        !           956: \begin{quote}\small\begin{verbatim}
        !           957: mydsaname   CN=axolotl
        !           958: \end{verbatim}\end{quote}
        !           959: declares this DSA to have the common name of \verb"axolotl".
        !           960: 
        !           961: \item [\verb"parent":]
        !           962: This entry consists of a name/address pair of a parent DSA,
        !           963: and is needed only for DSAs not holding the root EDB.
        !           964: The DSA referenced needs to hold a Master or Slave copy of an EDB
        !           965: higher up in the DIT than the highest locally held EDB.
        !           966: If more than one \verb"parent" tailor entries are found, the DSA
        !           967: will chose which DSA to contact.  The algorithm for making this
        !           968: choice has not been fully explored yet
        !           969: (currently, the first entry is always used, if this fails the second\ldots).
        !           970: For example,
        !           971: \begin{quote}\small\begin{verbatim}
        !           972: parent C=GB@CN=vicuna Internet=vs1.ucl.cs.ac.uk+50987
        !           973: \end{verbatim}\end{quote}
        !           974: \index{presentation addresses}
        !           975: declares the parent DSA to be ``C=GB@CN=vicuna'' at the
        !           976: indicated address.
        !           977: 
        !           978: \item [\verb"stats":]
        !           979: The value has the same format as the \verb"dsaplog" entry described in
        !           980: Section~\ref{dua:tailor}, and is used to control the level of
        !           981: DSA statistical logging.
        !           982: 
        !           983: \item [\verb"treedir":]
        !           984: Defines the directory in which the textual database is stored.
        !           985: For example,
        !           986: \begin{quote}\small\begin{verbatim}
        !           987: treedir     /usr/etc/quipu-db/
        !           988: \end{verbatim}\end{quote}
        !           989: declares the directory \file{/usr/etc/quipu-db/} to contain the local
        !           990: part of the Directory Information Tree.
        !           991: 
        !           992: \item [\verb"update":]
        !           993: The value ``on'' tells the DSA to update SLAVE EDB files when it starts up.
        !           994: See section \ref{slave_update} for further details, by default 
        !           995: this parameter is ``off''.
        !           996: 
        !           997: \item [\verb"searchlevel":] Defines the level from which users will be able
        !           998: to search the DIT --- default 2 (e.g organisations).
        !           999: If they try to search from higher up, a ``unwilling to perform'' service
        !          1000: error will result.
        !          1001: 
        !          1002: \item [\verb"lastmodified":] If `\verb"off"', `\verb+lastmodifiedby+'
        !          1003: attributes will not be added by the DSA when an entry is altered.
        !          1004: 
        !          1005: \item[\verb"readonly":] Bring the DSA up in ``read only'' mode --- that is
        !          1006: prevent user modification.  Slave updates are still allowed.
        !          1007: 
        !          1008: \item [\verb"dspchaining":]
        !          1009: The value ``on'' tells the DSA to chain DSP requests to other DSAs 
        !          1010: if necessary.
        !          1011: The default mode of operation is to return a DSA referral.
        !          1012: The full set of issues deciding whether to use chaining or referrals
        !          1013: is discussed in the QUIPU design document (\cite{QUIPU.Design}), and 
        !          1014: \cite{QUIPU.Navigate}.
        !          1015: 
        !          1016: \item [\verb"adminsize":] The administrative size limit for use on search
        !          1017: and list operations.
        !          1018: 
        !          1019: \item[\verb"admintime":] The maximum time allow to spend on a user query.
        !          1020: 
        !          1021: \item[\verb"cachetime":] The length of time to keep / use ``cached''
        !          1022: information.
        !          1023: 
        !          1024: \item[\verb"conntime":] The length of time to hold a unused connection open.
        !          1025: 
        !          1026: \item[\verb"nsaptime":] The length of time to wait before deciding a
        !          1027: connection can not be established for a given NSAP.
        !          1028: 
        !          1029: \item[\verb"retrytime":] The length of time before deciding it is worth
        !          1030: attempting to connect to a DSA that could not be contacted earlier.
        !          1031: 
        !          1032: \item[\verb"slavetime":] The length of time between attempting to update
        !          1033: slave EDB files.
        !          1034: 
        !          1035: \item[\verb"preferdsa":] When a DSA has creates a reference to other DSAs it
        !          1036: tries to discriminate between and chose the "best" DSA to contact.
        !          1037: This variable gives you a handle on controlling the choice. For example the
        !          1038: lines
        !          1039: \begin{verbatim}
        !          1040: preferDSA c=GB@cn=Vicuna
        !          1041: preferDSA cn=Giant Tortoise
        !          1042: \end{verbatim}
        !          1043: tells the DSA to use either ``c=GB@cn=Vicuna'' or ``cn=Giant Tortoise'' in
        !          1044: preference to any other DSA.  Further, use the DSA ``c=GB@cn=Vicuna'' rather than
        !          1045: ``cn=Giant Tortoise'' if possible.
        !          1046: 
        !          1047: \item[\verb"cainfo":] For authentication.
        !          1048: 
        !          1049: \item[\verb"secretkey":] For authentication.
        !          1050: 
        !          1051: \item[\verb"bindwindow":] For authentication.
        !          1052: 
        !          1053: \item [\verb"isode":]
        !          1054: The argument is an \verb"isodevariable" \verb"isodevalue" pair as would 
        !          1055: be found in \file{isotailor}.  This is used to ``override'' isotailor
        !          1056: settings.
        !          1057: \end{describe}
        !          1058: 
        !          1059: \subsection {Tailoring a Running DSA}
        !          1060: \label{dsa:mgmt}
        !          1061: 
        !          1062: The tailoring described above is performed when the DSA is
        !          1063: booted.  It is sometimes useful to alter the tailor settings
        !          1064: after the DSA has started without having to bring
        !          1065: the DSA down and rebooting.  This can be done by via
        !          1066: the  special ``{\bf dsacontrol}'' command in the \man dish(1c) program
        !          1067: as described in Section~\ref{dua:mgmt} on page~\pageref{dua:mgmt}.
        !          1068: 
        !          1069: The DUA invokes a modify operation, with a
        !          1070: single special attribute ``dSAControl'' defined in \cite{QUIPU.Design}.
        !          1071: The DSA recognises the special attribute, and provided you are
        !          1072: bound as the manager of the DSA, passes the attribute value to the
        !          1073: appropriate routine.
        !          1074: 
        !          1075: \cite{QUIPU.Design} describes this process in full.
        !          1076: 
        !          1077: \section {Connection to Other DSAs}
        !          1078: \label{dsa:connect}
        !          1079: 
        !          1080: All QUIPU DSAs should be connected. This section describes how you should 
        !          1081: configure your DSA to connect to other DSAs in order
        !          1082: to read the data not held locally.
        !          1083: Section \ref{dsa:global} describes how to make sure that other DSAs can access your DSA
        !          1084: (See Appendix~\ref{dsa:sites} on page~\pageref{dsa:sites} for a partial list
        !          1085: of registered QUIPU DSAs.)
        !          1086: 
        !          1087: A dynamic approach is used to bootstrap a new DSA.
        !          1088: The ``global master'' DSA is administered at UCL,
        !          1089: and other DSAs should be configured in relation to this one.
        !          1090: 
        !          1091: Every DSA needs to know the distinguished name and
        !          1092: presentation address of one
        !          1093: or more DSA's nearer to, or actually holding, the root EDB.  This parameter
        !          1094: is supplied in the tailor file (see Section~\ref{dsa:tailor})
        !          1095: under the name \verb"parent".
        !          1096: This information is used by the QUIPU DSA when it can not find a DSAs entry
        !          1097: in the local database, or can find no pointers in the local database to the
        !          1098: whereabouts of the data.
        !          1099: If you hold a \verb"SLAVE" copy of the root EDB, then your 
        !          1100: parent should be a DSA that is ``closer'' to the MASTER copy of the root
        !          1101: EDB.
        !          1102: 
        !          1103: The example databases are set up with default parents (defined in the file
        !          1104: \file{quipu-db/organisation/quiputailor})
        !          1105: To see if your DSA can contact the ``parent'', connect to
        !          1106: the local test (root holding) DSA using \verb"dish", and type
        !          1107: 
        !          1108: \begin{quote}\begin{verbatim}
        !          1109: list @
        !          1110: \end{verbatim}\end{quote}
        !          1111: 
        !          1112: This will list the locally held root, now try
        !          1113: 
        !          1114: \begin{quote}\begin{verbatim}
        !          1115: list @ -dontusecopy
        !          1116: \end{verbatim}\end{quote}
        !          1117: 
        !          1118: This will try to connect to the parent DSA.
        !          1119: If it is successful, there should be a lot more data returned.
        !          1120: 
        !          1121: Care should be taken in choosing the parent
        !          1122: DSA. If all DSAs have the same parent
        !          1123: DSA then that DSA will become overloaded.
        !          1124: Typically each site will have several DSAs. One of these should
        !          1125: be the default parent for all the other DSAs, with only one DSA having a 
        !          1126: default parent outside the site.
        !          1127: 
        !          1128: 
        !          1129: When ``walking down'' the DIT, QUIPU needs access to information to tell it
        !          1130: on which DSA the next level of the DIT is stored.
        !          1131: To do this each non-leaf entry MUST have a ``masterDSA''\index{masterDSA attribute}
        !          1132: or ``slaveDSA''
        !          1133: attribute.  The value of the attribute is the distinguished name of the DSA
        !          1134: holding the next level of the DIT (it may be your own DSA name, if you hold
        !          1135: the next level as well).  If there is no such attribute, QUIPU assumes the
        !          1136: entry is a leaf.
        !          1137: If the information required is not held in the local DSA then QUIPU
        !          1138: chains the request to the named DSA or returns a referral 
        !          1139: --- depending upon the mode of operation
        !          1140: (The named DSAs entry is read to establish the
        !          1141: address --- this may mean a connection to another DSA 
        !          1142: in-order to read the entry).
        !          1143: 
        !          1144: Once you have started your DSA, you should try to connect to other DSAs 
        !          1145: using the \verb"DISH" program (this connects to the local DSA, which will
        !          1146: chain requests to other DSAs).  Try listing the children of
        !          1147: organisations other than yourself, to find which organisations are connected,
        !          1148: try listing your countries children.
        !          1149: 
        !          1150: \subsection {Choosing a Name for Your DSA}
        !          1151: \label{dsa:naming}
        !          1152: Every QUIPU DSA MUST have an entry in the DIT, hence
        !          1153: your DSA will need a unique distinguished name.
        !          1154: The name ``cn=Toucan''
        !          1155: given in the example databases is not unique.
        !          1156: There are two aspects to consider in choosing a name for you DSA.
        !          1157: 
        !          1158: This entry is used by other DSAs to identify you DSA, and so is needed if 
        !          1159: other DSAs are going to be able to see your DSA.
        !          1160: 
        !          1161: Firstly, it is a QUIPU convention that DSAs should be named 
        !          1162: after endangered South
        !          1163: American wildlife, and that the entry for the DSA should contain a
        !          1164: description of the animal or plant in question.
        !          1165: Some examples are shown in Table~\ref{wildlife}.
        !          1166: A more comprehensive list can be found in the IUCN's ``Red Book''
        !          1167: \cite{IUCN.Mammal}.
        !          1168: 
        !          1169: Secondly, the entry for your DSA must be visible to other DSAs who do not know
        !          1170: how to contact your DSA.
        !          1171: So, the MASTER copy of your DSAs own entry must be held at least one level higher up
        !          1172: in the DIT than the part of the DIT it holds as \verb"MASTER" data.
        !          1173: For example the DSA which holds
        !          1174: ``c=GB @ o=University College London @ ou=Computer Science'', 
        !          1175: must be held at the
        !          1176: ``c=GB @ o=University College London'' level 
        !          1177: (e.g. ``c=GB @ o=University College London @ cn=wombat'') or above.
        !          1178: Such naming also helps prevent loops as described more fully in
        !          1179: \cite{QUIPU.Design}.
        !          1180: 
        !          1181: In practice DSAs should be named fairly high up the tree.
        !          1182: Each country should have at least two DSAs named at the root level.
        !          1183: Each Organisation should have at least two DSA named at the national level.
        !          1184: 
        !          1185: \tagtable[tp]{q-1}{Endangered South American Wildlife}{wildlife}
        !          1186: 
        !          1187: You should use \pgm{dish} to find out if the name you want is already taken.
        !          1188: For example,
        !          1189: if you are creating a DSA for an organization in Great Britain,
        !          1190: you might use:
        !          1191: \begin{quote}\small\begin{verbatim}
        !          1192: % dish -c "Giant Tortoise"
        !          1193: Welcome to Dish (DIrectory SHell)
        !          1194: Dish -> search @c=GB -filter objectClass=dsa
        !          1195: \end{verbatim}\end{quote}
        !          1196: This will print out the list of names already in use.
        !          1197: 
        !          1198: Having chosen a name, you will need to tell your DSA its name, and 
        !          1199: make sure it can find an EDB file for its own entry.
        !          1200: 
        !          1201: A DSA finds it own name from the ``mydsaname'' variable defined in the file
        !          1202: \file{quiputailor} (see Section~\ref{dsa:tailor} for details).
        !          1203: An example \verb"quiputailor" entry would be:-
        !          1204: \begin{quote}\small\begin{verbatim}
        !          1205: mydsaname:     "c=GB@cn=a dsa name"
        !          1206: \end{verbatim}\end{quote}
        !          1207: Having read this name from \verb"quiputailor", a DSA will try to find
        !          1208: the corresponding entry.
        !          1209: The process for doing this is complex, and is 
        !          1210: described in full in Section~\ref{dsa:starting}. Essentially the 
        !          1211: DSA needs to find the EDB file holding the entry, and hence you MUST
        !          1212: supply it, if supplied correctly it will be found.
        !          1213: 
        !          1214: If you hold the EDB that the entry should be in, simply
        !          1215: make sure the entry is in that EDB and then it will be found.
        !          1216: If you do not hold, and do not want to hold the EDB in which your
        !          1217: DSA is named (e.g., your DSA is called \verb"c=GB@cn=toucan" but 
        !          1218: you do not hold the EDB \verb"c=GB"), then you should (normally)
        !          1219: supply a cached copy of the EDB which contains only the 
        !          1220: entry for the DSA, and not all the others entries the full EDB would have.
        !          1221: If you do not supply it, your DSA will have to rely on others DSAs before it
        !          1222: can start.
        !          1223: 
        !          1224: \subsection {Connection to the Global Directory}\label{dsa:global}
        !          1225: 
        !          1226: 
        !          1227: To enable the global directory to connect to you, you must contact the
        !          1228: manager of the DSA immediately above the node you want to added under.
        !          1229: Supply them with the entry for your DSA, and the top level 
        !          1230: entry of the sub-tree
        !          1231: you want to hold.
        !          1232: For example, to add the organisation ``o=foobar'' below ``c=US'',
        !          1233: contact the manager of the DSA holding ``c=US'' as a MASTER, giving them the
        !          1234: entry for ``c=US@o=foobar'' and ``c=US@cn=foobar\_dsa'', assuming
        !          1235: ``c=US@cn=foobar\_dsa'' is the name of your DSA (see Section~\ref{dsa:naming}
        !          1236: on naming a DSA).
        !          1237: 
        !          1238: By convention,
        !          1239: to find out who administers the master EDB for a particular node,
        !          1240: run the \man dish(1c) program and retrieve the \verb"manager" attribute
        !          1241: from the entry for the DSA holding that node.
        !          1242: 
        !          1243: You can then find a mail address by looking that person up in the directory.
        !          1244: 
        !          1245: The following example shows you how to get the mail address of the
        !          1246: manager of the c=GB subtree. 
        !          1247: 
        !          1248: \begin{verbatim}
        !          1249: % dish
        !          1250: Welcome to Dish (DIrectory SHell)
        !          1251: Dish -> showentry @c=GB -type masterDSA
        !          1252: masterDSA      - cn = Giant Tortoise
        !          1253: Dish -> showentry "@cn=Giant Tortoise" -type manager
        !          1254: manager         - countryName=GB
        !          1255:                   organization=University College London
        !          1256:                   organizationalUnit=Computer Science
        !          1257:                   commonName=Colin Robbins
        !          1258: Dish -> moveto "@c=gb@o=University College London @ 
        !          1259:         ou=Computer Science @ cn=Colin Robbins" 
        !          1260: Dish -> showentry -type rfc822Mailbox 
        !          1261: rfc822Mailbox  - [email protected]
        !          1262: Dish -> quit
        !          1263: %
        !          1264: \end{verbatim}
        !          1265: 
        !          1266: If you want to add data to the root node of the ``global tree''
        !          1267: (e.g., a new country) then you will probably want a copy of the 
        !          1268: ROOT EDB (or you might want a copy for other reasons).
        !          1269: The master can be accessed via the FTAM service at UCL as
        !          1270: file \file{$<$PUB$>$/masterEDB}.
        !          1271: (The address of this service is found in the {\bf Preface\/} of this volume.)
        !          1272: If you are unable to access the FTAM service,
        !          1273: a copy of the master can also be obtained from the {\em quipu-support} 
        !          1274: address given in Section~\ref{quipu:support}.
        !          1275: Having obtained the root EDB, add the new entries, and mail the new
        !          1276: information to the {\em quipu-support} address given in
        !          1277: Section~\ref{quipu:support}.
        !          1278: 
        !          1279: To keep this EDB upto date you should use the ``getEDB'' 
        !          1280: operation discussed in Section~\ref{slave_update} (this can also be used to
        !          1281: get the EDB in the first place).
        !          1282: 
        !          1283: When you think you are connected to the ``global DIT'', 
        !          1284: you should test that you are.  To do this use \verb"dish" to connect 
        !          1285: to a DSA higher than you in the DIT (using the \verb"-call" flag as described
        !          1286: in Section~\ref{dua:tailor}, then see if you can navigate to your
        !          1287: own part of the DIT, and look at your data --- if so 
        !          1288: then the DSA is connected.
        !          1289: 
        !          1290: \section {Adding more Data}
        !          1291: \label{adding_data}
        !          1292: 
        !          1293: Having got a DSA started, and connected to the global DIT, you should start
        !          1294: to add lots of data.
        !          1295: There are many sources of such data, and with just a relatively small amount
        !          1296: of effort this data can be added to the directory.
        !          1297: 
        !          1298: There are two ways such data can be added.
        !          1299: First of all you can use one of the DUA programs to bind to the DSA as the
        !          1300: DSA manager, and send data to the directory via the ``add'' and ``modify'' 
        !          1301: operations (see Sections~\ref{dish:add} and \ref{dish:modify}).
        !          1302: This is probably the best way to add relatively small amounts of data,
        !          1303: or make minor changes to the data.
        !          1304: 
        !          1305: To add a large amount of data (i.e., the initial creation of a 
        !          1306: large database) if is probably easiest to write a shell script using \unix/
        !          1307: tools such as \verb"awk" and \verb"grep" to create the EDB files directly.
        !          1308: In the next version of the software there will be tools to facilitate this.
        !          1309: 
        !          1310: When adding data for users it is advisable to allocate a ``userPassword''.
        !          1311: \index{user password attribute}
        !          1312: Chapter~\ref{Security} describes how to do this.
        !          1313: 
        !          1314: \subsection {More on Object Classes}
        !          1315: The only object class discussed so far is the ``quipuDSA'' objectclass.
        !          1316: When you start to add data, you will probably want to add information about
        !          1317: people, sub-divisions of your organisation, and other application entities.
        !          1318: This Section introduces some of the more important object classes, and the
        !          1319: attributes they may contain.
        !          1320: In many cases, only the attribute type is specified, for details of typical
        !          1321: values and the value syntax you should read Chapter~\ref{syntaxes}.
        !          1322: 
        !          1323: As already discribed, every entry in the DIT must belong to the object
        !          1324: class \verb+top+, which means every entry must have an \verb+objectClass+
        !          1325: attribute.
        !          1326: Also, every entry in the Quipu DIT should belong to either the
        !          1327: \verb+quipuNonLeafObject+ or \verb+quipuObject+.
        !          1328: 
        !          1329: \subsubsection{Person}
        !          1330: This is a base object class used to represent a person.
        !          1331: 
        !          1332: There are two mandatory attributes:
        !          1333: \begin{describe}
        !          1334: \item[commonName:]
        !          1335:                        which gives a (potentially ambiguous) name for
        !          1336:                        the person.
        !          1337:                        The value of this attribute is a string usually
        !          1338:                        containing the person's first and last names; e.g.,
        !          1339: \begin{quote}\small\begin{verbatim}
        !          1340: Marshall Rose
        !          1341: \end{verbatim}\end{quote}
        !          1342:                        This attribute is usually multi-valued, containing
        !          1343:                        variations on the first, middle, and last names; e.g.,
        !          1344: \begin{quote}\small\begin{verbatim}
        !          1345: Colin Robbins
        !          1346: Colin John Robbins
        !          1347: Colin J. Robbins
        !          1348: \end{verbatim}\end{quote}
        !          1349:                        Generally this attribute will supply the
        !          1350:                        distinguished attribute of the entry.
        !          1351: \item[surName:]
        !          1352:                        which gives the person's last name.
        !          1353: \end{describe}
        !          1354: 
        !          1355: The optional attributes are:-
        !          1356: \begin{quote}\small\begin{verbatim}
        !          1357: userPassword
        !          1358: seeAlso
        !          1359: telephoneNumber
        !          1360: description
        !          1361: \end{verbatim}\end{quote}
        !          1362: 
        !          1363: \subsubsection{OrganizationalPerson}
        !          1364: This is a sub-class of \verb+person+ and introduces the following optional
        !          1365: attributes:-
        !          1366: \begin{quote}\small\begin{verbatim}
        !          1367: preferredDeliveryMethod
        !          1368: destinationIndicator
        !          1369: registeredAddress
        !          1370: internationaliSDNNumber
        !          1371: x121Address
        !          1372: facsimileTelephoneNumber
        !          1373: teletexTerminalIdentifier
        !          1374: telexNumber
        !          1375: physicalDeliveryOfficeName
        !          1376: postOfficeBox
        !          1377: postalCode
        !          1378: postalAddress
        !          1379: title
        !          1380: organizationalUnitName
        !          1381: streetAddress
        !          1382: stateOrProvinceName
        !          1383: locality
        !          1384: \end{verbatim}\end{quote}
        !          1385: 
        !          1386: \subsubsection{ThornPerson}
        !          1387: like \verb+OrganizationalPerson+, this is also a sub-class of \verb+person+ 
        !          1388: and introduces the following optional
        !          1389: attributes:-
        !          1390: \begin{quote}\small\begin{verbatim}
        !          1391: homePostalAddress
        !          1392: lastModifiedBy
        !          1393: lastModifiedTime
        !          1394: secretary
        !          1395: homePhone
        !          1396: userClass
        !          1397: photo
        !          1398: roomNumber
        !          1399: favouriteDrink
        !          1400: info
        !          1401: rfc822Mailbox
        !          1402: textEncodedORaddress
        !          1403: userid
        !          1404: \end{verbatim}\end{quote}
        !          1405: 
        !          1406: Two example \verb+ThornPerson+ entries are given in Figure~\ref{example_edb} on
        !          1407: page~\pageref{example_edb}.
        !          1408: 
        !          1409: \subsubsection{OrganizationalRole}
        !          1410: Entries of this class are used to represent a position or role within an
        !          1411: organization.  
        !          1412: 
        !          1413: There is one mandatory attribute:
        !          1414: \begin{describe}
        !          1415: \item[commonName:]     which gives the name of the role.
        !          1416:                        The value of this attribute is a string; e.g.,
        !          1417: \begin{quote}\small\begin{verbatim}
        !          1418: PostMaster
        !          1419: \end{verbatim}\end{quote}
        !          1420: \end{describe}
        !          1421: 
        !          1422: There are many optional attributes including:
        !          1423: \begin{describe}
        !          1424: \item[roleOccupant:]    which is the Distinguished Name of the person 
        !          1425:                        who fulfills the role e.g.,
        !          1426: \begin{quote}\small\begin{verbatim}
        !          1427: c=US@o=NYSERNet Inc.@ou=Operations@cn=Chris Kolb
        !          1428: \end{verbatim}\end{quote}
        !          1429: \end{describe}
        !          1430: 
        !          1431: The other optional attributes are:
        !          1432: \begin{quote}\small\begin{verbatim}
        !          1433: seeAlso
        !          1434: preferredDeliveryMethod
        !          1435: destinationIndicator
        !          1436: registeredAddress
        !          1437: internationaliSDNNumber
        !          1438: x121Address
        !          1439: facsimileTelephoneNumber
        !          1440: teletexTerminalIdentifier
        !          1441: telexNumber
        !          1442: telephoneNumber
        !          1443: physicalDeliveryOfficeName
        !          1444: postOfficeBox
        !          1445: postalCode
        !          1446: postalAddress
        !          1447: description
        !          1448: organizationalUnitName
        !          1449: streetAddress
        !          1450: stateOrProvinceName
        !          1451: locality
        !          1452: \end{verbatim}\end{quote}
        !          1453: 
        !          1454: 
        !          1455: \subsubsection{Alias}
        !          1456: Objects of this class represent an alias to some other entry in the
        !          1457: DIT.  It is generaly used when an entity belongs in one or more subtrees of
        !          1458: the DIT, and is used to ``point'' one entry at the other.
        !          1459: 
        !          1460: There are two mandatory attributes:
        !          1461: \begin{describe}
        !          1462: \item[commonName:]     which gives the name of the alias.
        !          1463:                        The value of this attribute is a string; e.g.,
        !          1464: \begin{quote}\small\begin{verbatim}
        !          1465: Colin Robbins
        !          1466: \end{verbatim}\end{quote}
        !          1467: 
        !          1468: \item[aliasedObjectName:] which is a pointer to another object in the Directory;
        !          1469:                        e.g.,
        !          1470: \begin{quote}\small\begin{verbatim}
        !          1471: c=GB@o=University College London@ou=Computer Science@cn=Colin Robbins
        !          1472: \end{verbatim}\end{quote}
        !          1473: \end{describe}
        !          1474: There are no optional attributes for this object class.
        !          1475: 
        !          1476: An example of an Alias entry is given below:-
        !          1477: \begin{quote}\small\begin{verbatim}
        !          1478: cn= Quipu-support
        !          1479: aliasedObjectName= c=GB@o=University College London@ou=Computer
        !          1480:                    Science@cn=Incads
        !          1481: objectClass= quipuObject & alias & top
        !          1482: \end{verbatim}\end{quote}
        !          1483: 
        !          1484: \subsubsection{OrganizationalUnit}
        !          1485: The \verb+OrganisationalUnit+ object class is used to represent a unit within
        !          1486: your organisation.
        !          1487: There is one mandatory attribute
        !          1488: \begin{describe}
        !          1489: \item[organizationalUnitName:]
        !          1490:                        which gives the name of the organizational unit.
        !          1491:                        The value of this attribute is a string; e.g.,
        !          1492: \begin{quote}\small\begin{verbatim}
        !          1493: Research and Development
        !          1494: \end{verbatim}\end{quote}
        !          1495: \end{describe}
        !          1496: 
        !          1497: The optional attributes are:-
        !          1498: \begin{quote}\small\begin{verbatim}
        !          1499: userPassword
        !          1500: seeAlso
        !          1501: preferredDeliveryMethod
        !          1502: destinationIndicator
        !          1503: registeredAddress
        !          1504: internationaliSDNNumber
        !          1505: x121Address
        !          1506: facsimileTelephoneNumber
        !          1507: teletexTerminalIdentifier
        !          1508: telexNumber
        !          1509: telephoneNumber
        !          1510: physicalDeliveryOfficeName
        !          1511: postOfficeBox
        !          1512: postalCode
        !          1513: postalAddress
        !          1514: businessCategory
        !          1515: searchGuide
        !          1516: description
        !          1517: streetAddress
        !          1518: stateOrProvinceName
        !          1519: locality
        !          1520: \end{verbatim}\end{quote}
        !          1521: 
        !          1522: \subsubsection{Organization}
        !          1523: Objects of this class represent a top-level organizational entity,
        !          1524: such as a corporation, university, government entity, and so on.
        !          1525: 
        !          1526: There is one mandatory attribute:
        !          1527: \begin{describe}
        !          1528: \item[organizationName:]
        !          1529:                        which gives the name of the organization.
        !          1530:                        The value of this attribute is a string; e.g.,
        !          1531: \begin{quote}\small\begin{verbatim}
        !          1532: NYSERNet Inc.
        !          1533: \end{verbatim}\end{quote}
        !          1534: \end{describe}
        !          1535: 
        !          1536: The optional attributes are:-
        !          1537: \begin{quote}\small\begin{verbatim}
        !          1538: userPassword
        !          1539: seeAlso
        !          1540: preferredDeliveryMethod
        !          1541: destinationIndicator
        !          1542: registeredAddress
        !          1543: internationaliSDNNumber
        !          1544: x121Address
        !          1545: facsimileTelephoneNumber
        !          1546: teletexTerminalIdentifier
        !          1547: telexNumber
        !          1548: telephoneNumber
        !          1549: physicalDeliveryOfficeName
        !          1550: postOfficeBox
        !          1551: postalCode
        !          1552: postalAddress
        !          1553: businessCategory
        !          1554: searchGuide
        !          1555: description
        !          1556: streetAddress
        !          1557: stateOrProvinceName
        !          1558: locality
        !          1559: \end{verbatim}\end{quote}
        !          1560: 
        !          1561: \subsubsection {domainRelatedObject}
        !          1562: If an object has some relationship to the Internet Domain Name System (DNS),
        !          1563: then this can be represented in the DIT using this objectclass.
        !          1564: 
        !          1565: This class has one mandatory attribute:
        !          1566: \begin{describe}
        !          1567: \item[associatedDomain:]
        !          1568:                        identifies the domain which corresponds to this object.
        !          1569:                        The value is a domain string, e.g.,
        !          1570: \begin{quote}\small\begin{verbatim}
        !          1571: nyser.net
        !          1572: cs.ucl.ac.uk
        !          1573: \end{verbatim}\end{quote}
        !          1574: \end{describe}
        !          1575: 
        !          1576: \subsection {Schemas}
        !          1577: \label{quipu:schema}
        !          1578: 
        !          1579: Directories should provide a very flexible tool
        !          1580: which enables any information to be stored.  There is a danger that Schemas,
        !          1581: as specified in the OSI Directory, will lead to procrustean directory implementations
        !          1582: which impose unreasonable restrictions.  The QUIPU Directory does not, per
        !          1583: se, place restrictions on what can be placed in a DSA.
        !          1584: It does however give control so that managers may control what is stored in the
        !          1585: directory.
        !          1586: 
        !          1587: The first aspect of structure is with respect to attributes which may be
        !          1588: present in an entry.  A QUIPU DSA will allow an entry to belong to one or
        !          1589: more object classes which are known to the DSA (stored in a table).  An
        !          1590: entry will typically have a small number of object classes (e.g., TOP
        !          1591: (implicit) + Person + Organisational Person + QUIPU Object).  The DSA will
        !          1592: maintain a table of mandatory and optional attributes for each object class
        !          1593: supported.  This will be follow the guidelines of the standard or
        !          1594: specification identifying the object class in question.  From this
        !          1595: information, the DSA can determine the permitted and mandatory attributes for a
        !          1596: given entry, by calculating the union of all the object classes of that
        !          1597: entry.  Free extension (i.e., the ability to store any attribute) was
        !          1598: rejected, as there does not appear to be a reasonable mechanism to manage
        !          1599: this.  However, it is straightforward for managers to create new object
        !          1600: classes as desired.
        !          1601: 
        !          1602: \tagrind[htb]{schema}{Schema definition}{schema-py}
        !          1603: 
        !          1604: It is important 
        !          1605: to allow management control of what is permitted at a given level.
        !          1606: Therefore a ``tree structure''
        !          1607: attribute may be created.  
        !          1608: This attribute is defined in Figure~\ref{schema-py}, with the string syntax
        !          1609: discussed in ~\ref{tree_struct}.
        !          1610: This specifies for the level below,
        !          1611: what types of object are permitted.  
        !          1612: Each attribute value identifies a class of object which can exist at the level
        !          1613: below, and 
        !          1614: defines a set of mandatory and optional object classes.
        !          1615: This can be considered as defining a (private) object class implied by the
        !          1616: combination of these classes.
        !          1617: For each type of object, the attribute types permitted in the RDN are also
        !          1618: listed.  This is not checked in QUIPU-6.0
        !          1619: The directory knows about the tree structure attribute, and will
        !          1620: ensure consistency.  
        !          1621: When creating an entry, the DSA must check that it conforms to the
        !          1622: treeStructure attribute of the parent entry.
        !          1623: When removing information from a treeStructure attribute, the
        !          1624: Directory will  check that all of the children conform to the
        !          1625: modified attribute.
        !          1626: 
        !          1627: \subsection {Photograph Attributes}
        !          1628: \label{dua:photo}
        !          1629: 
        !          1630: The data that a DSA can hold does not have to be limited to data that can be
        !          1631: represented by printable strings.
        !          1632: Any attribute a QUIPU DSA does not know a string syntax for, it will hold as
        !          1633: a block of ASN.1.
        !          1634: One such attribute is the ``photo'' attribute.
        !          1635: Photographs of people and objects are stored in the directory as a
        !          1636: g3fax encoded block of ASN.1, and are best stored as ``file'' attributes
        !          1637: described in the next Section.
        !          1638: There is an example of a photograph attribute in the example database.
        !          1639: This can be looked at by connecting to the directory with \verb"dish"
        !          1640: and looking at the entry 
        !          1641: ``c= GB @ o= University College London @ ou= Computer Science @ cn= Steve Kille"
        !          1642: 
        !          1643: 
        !          1644: Unless you you have compiled and installed the ``photo'' code as 
        !          1645: described in Section~\ref{quipu:install} you will see the message
        !          1646: \begin{quote}\begin{verbatim}
        !          1647: ``No display process defined''
        !          1648: \end{verbatim}\end{quote}
        !          1649: 
        !          1650: Having compiled the ``photo'' code, you will need to add a line such
        !          1651: as
        !          1652: \begin{quote}\small\begin{verbatim}
        !          1653: photo xterm Xphoto
        !          1654: \end{verbatim}\end{quote}
        !          1655: to your dsaptailor file (see Section~\ref{dua:tailor})
        !          1656: This says that if the user in logged on to a terminal
        !          1657: of the type \verb"xterm" then use the process \file{g3fax/Xphoto}
        !          1658: in the ISODE \verb"ETCDIR" directory to display the photograph.
        !          1659: 
        !          1660: There are display routines provided for the X~window system, SunView,
        !          1661: Tektronix~4014, and ``dumb'' terminals.
        !          1662: 
        !          1663: \subsection {File Attributes}
        !          1664: \label{file_attr}
        !          1665: Attributes values are generally stored in the EDB file, and loaded 
        !          1666: into memory when the DSA starts.
        !          1667: For some large attributes such a photos, this is not a sensible approach, so the
        !          1668: concept of a ``file'' attribute is introduced.
        !          1669: 
        !          1670: If an attribute value is prefixed by \verb"FILE", then the value is assumed
        !          1671: to be stored on disk.
        !          1672: For example if the following were found in an EDB file:-
        !          1673: \begin{quote}\small\begin{verbatim}
        !          1674: photo = {FILE} /usr/local/pictures/steve
        !          1675: \end{verbatim}\end{quote}
        !          1676: then the value for the photo attribute would be read from the file
        !          1677: \begin{quote}
        !          1678: \verb"/usr/local/pictures/steve".
        !          1679: \end{quote}
        !          1680: 
        !          1681: The syntax of the data in the file is expected to be the same as
        !          1682: the string syntax, except in the case of ASN and PHOTO attributes which
        !          1683: are expected to be in raw ASN.1.
        !          1684: 
        !          1685: If there is not a file name supplied, then a default name is allocated.
        !          1686: The default file name is the RDN of the entry the attribute belongs to
        !          1687: followed by a dot ``.'', followed by the attributeType. This file is expected
        !          1688: to be in the same directory as the EDB file for the entry.
        !          1689: For example the default file for photo attribute, representing the entry
        !          1690: for 
        !          1691: ``c= GB @ o= University College London @ 
        !          1692: ou= Computer Science @ cn= Colin Robbins''
        !          1693:  would be:-
        !          1694: \begin{quote}\small\begin{verbatim}
        !          1695: cn=Colin Robbins.photo
        !          1696: \end{verbatim}\end{quote}
        !          1697: in the directory
        !          1698: \begin{quote}\small\begin{verbatim}
        !          1699: quipu-db/c=GB/o=University College London/ou=Computer Science
        !          1700: \end{verbatim}\end{quote}
        !          1701: or equivalent mapped file as described in Section~\ref{EDB:mapped}.
        !          1702: 
        !          1703: The process defined so far allows for attribute stored in a EDB in file
        !          1704: format to be read by a DSA.
        !          1705: Writing the attributes back to files if modified/added by a DUA requires
        !          1706: a little more.
        !          1707: The DSA needs to know which attributes should be stored on disk.
        !          1708: This information is supplied in the attribute oidtables which are 
        !          1709: defined in Section~\ref{oidtables}.
        !          1710: For example if the following entry was found in the file
        !          1711: \file{oidtable.at} in the ISODE \verb"ETCDIR" directory
        !          1712: then a ``photo'' attributed would always be written
        !          1713: back to disk.
        !          1714: \begin{quote}\small\begin{verbatim}
        !          1715: photo:  thornAttribute.7: photo : file
        !          1716: \end{verbatim}\end{quote}
        !          1717: 
        !          1718: 
        !          1719: \section {How a DSA Starts}
        !          1720: \label{dsa:starting}
        !          1721: 
        !          1722: The Section gives a brief description of how a QUIPU DSA starts.
        !          1723: This is intended to help people who have experienced problems in getting
        !          1724: their DSAs started.
        !          1725: 
        !          1726: First of all the tailor file \file{quiputailor} in the ISODE \verb"ETCDIR" directory
        !          1727: is read (unless you
        !          1728: specify a different tailor file using the \verb"-t" option to
        !          1729: \pgm{ros.quipu}).
        !          1730: This tells the DSA, amongst other things, its own name, and its parent
        !          1731: DSA(s).
        !          1732: 
        !          1733: The first thing a DSA need to do if find its own entry, thus it tries to
        !          1734: load the EDB that should contain it.
        !          1735: If it can not find its own entry, then it will try connecting to the
        !          1736: parent DSA to read its own entry. If this fails the DSA will stop.
        !          1737: 
        !          1738: Having found its own entry, the DSA will check to see if it is a cached
        !          1739: entry read from disk, if so it will attempt to read a new version from the
        !          1740: parent --- if successful a new cache EDB file will be written.
        !          1741: 
        !          1742: Now the rest of the local DIT can be loaded.  Each EDB specified in the
        !          1743: ``edbInfo'' attribute \index{edbInfo attribute} is in turn loaded from disk.
        !          1744: 
        !          1745: As each EDB is loaded from disk, it is checked to make sure all the
        !          1746: attributes in the entry are allowed, as defined by the ``objectClass''
        !          1747: attribute, \index{objectClass attribute} and that the tree shape conforms to that defined by the
        !          1748: ``treeStruture'' attribute. \index{treeStructure attribute}
        !          1749: If any EDB fails these checks then the DSA will not start, and an appropriate
        !          1750: message will be logged.
        !          1751: 
        !          1752: A check is now made on the \verb"quipuVersion" \index{quipuVersion attribute}
        !          1753: that a DSA entry MUST contain.
        !          1754: If this attribute does not have the same version string as the 
        !          1755: running DSA process, a warning message is printed to the logs.
        !          1756: On seeing this message, you should update the version string
        !          1757: in your DSAs entry.
        !          1758: Future version of the software will maintain the attribute for you.
        !          1759: 
        !          1760: Having loaded all its data, the DSA will start listening for DAP and DSP
        !          1761: associations.
        !          1762: 
        !          1763: \section {Adding more DSAs}
        !          1764: 
        !          1765: Many organisations will need to have more than one DSA to meet 
        !          1766: their requirements, the Section suggests how you might arrange your
        !          1767: DSAs to get the most out of the system.
        !          1768: 
        !          1769: You will almost certainly need at least one DSA that holds a
        !          1770: copy of the root EDB, and your country EDB.
        !          1771: This DSA should also hold the MASTER copy of your organisations own EDB.
        !          1772: Subsequent DSAs that are set up, should have this DSA defined 
        !          1773: as one of their parent DSAs.
        !          1774: 
        !          1775: For robustness, it is a good idea to have some other DSAs replicating 
        !          1776: these EDBs, so that if one local machine or DSA becomes unavailable, then
        !          1777: there is another copy elsewhere that can be used.
        !          1778: EDBs that contain addresses of other DSAs that you may want to contact
        !          1779: regularly should also be replicated, to prevent extra associations
        !          1780: having to be made just to read DSA addresses.
        !          1781: In short, if you know that data from a certain 
        !          1782: EDB is going to be accessed a lot, replicate it locally.
        !          1783: Replication does not have a high cost.
        !          1784: 
        !          1785: When setting up multiple DSAs be sure to name them as described in 
        !          1786: Section~\ref{dsa:naming},
        !          1787: ensure the DSA entries are sufficiently high in the DIT, so that other DSAs
        !          1788: can read the entry, without having to contact the DSA concerned.
        !          1789: 
        !          1790: \section {Receiving EDB Updates}
        !          1791: \label{slave_update}
        !          1792: If your DSA holds a slave copy of one or more EDBs, then it can
        !          1793: automatically update these for you.
        !          1794: The current approach is very simple minded, but will be extended for future
        !          1795: versions.
        !          1796: 
        !          1797: There are two ways to ask a DSA to update its slave EDBs, either use \pgm {dish}
        !          1798: program and issue a ``dsacontrol --slave'' command --- see 
        !          1799: Section~\ref{dua:mgmt}, or set the \verb"quiputailor" parameter
        !          1800: ``update'' to ``on'' (see Section~\ref{dsa:tailor})
        !          1801: --- in which case the DSA will try to update its slaves
        !          1802: when it starts up.
        !          1803: 
        !          1804: To update the slaves, the DSA uses the ``edbinfo'' attribute that the DSAs
        !          1805: entry in the DIT MUST have.
        !          1806: This attribute specifies which EDBs you hold, and where to get updates of
        !          1807: the from.
        !          1808: NOTE you do not necessarily have to get updates from a \verb"MASTER" EDB,  
        !          1809: a \verb"SLAVE" is acceptable.
        !          1810: In many cases this will be preferable to prevent the 
        !          1811: load on the \verb"MASTER" DSA being too high.
        !          1812: For example a ``national'' EDB is likely to be highly replicated,
        !          1813: it would not be a good idea to have just one DSA
        !          1814: handling updates.  It would be better to have the load spread over several
        !          1815: DSAs.
        !          1816: 
        !          1817: The syntax of the attribute is \index{edbInfo attribute}
        !          1818: \begin{quote}\begin{verbatim}
        !          1819: edbinfo = EDB concerned # get from # send to
        !          1820: \end{verbatim}\end{quote}
        !          1821: It is a multi-valued attribute. 
        !          1822: 
        !          1823: A few examples:
        !          1824: \begin{quote}\small\begin{verbatim}
        !          1825: # cn=Giant Tortoise # cn=Fruit Bat
        !          1826: c=US # # cn=Fruit Bat
        !          1827: c=US # # c=US@cn=Spectacled Bear
        !          1828: c=US@l=NY # cn=Fruit Bat #
        !          1829: \end{verbatim}\end{quote}
        !          1830: Note that there is no harm to using multiple \verb"eDBinfo" lines,
        !          1831: even if they refer to the same EDB.
        !          1832: These lines indicate that:
        !          1833: \begin{itemize}
        !          1834: \item  The ROOT EDB is read from the \verb"cn=Giant Tortoise" DSA,
        !          1835:        further the \verb"cn=Fruit Bat" DSA is allowed to read the
        !          1836:        ROOT EDB from this DSA.
        !          1837:        This is an important point --- A DSA has to explicitly say it will
        !          1838:        allow you to update from it, before it will send EDB files.
        !          1839:        Thus if you want to pull EDB files from a remote DSA, you will need
        !          1840:        to ask the manager to add you DSA to their DSAs ``send to'' field.
        !          1841: 
        !          1842: \item  The \verb"cn=Fruit Bat" DSA and the \verb"c=US@cn=Spectacled Bear" DSA
        !          1843:        are allowed to read the EDB for \verb"c=US". 
        !          1844:        Note that the second and third line could be combined as:
        !          1845: \begin{quote}\small\begin{verbatim}
        !          1846: c=US # # cn=Fruit Bat$c=US@cn=Spectacled Bear
        !          1847: \end{verbatim}\end{quote}
        !          1848: \item  The DSA named \verb"cn=Fruit Bat" supplies the EDB for \verb"c=US@l=NY"
        !          1849:        to this DSA.
        !          1850: \end{itemize}
        !          1851: 
        !          1852: Some EDB files, such as the ROOT, and country level EDB files are highly
        !          1853: replicated, and having to list all the DSAs that are allowed to pull such EDBs
        !          1854: is too restrictive.
        !          1855: Thus the following syntax can be used as an abbreviation:
        !          1856: \begin{quote}\small\begin{verbatim}
        !          1857: c=US # # c=US
        !          1858: \end{verbatim}\end{quote}
        !          1859: This indicates that the c=US EDB file can be sent to DSA named at the c=US
        !          1860: level of the DIT, for example 
        !          1861: \begin{quote}\small\begin{verbatim}
        !          1862: c=US@cn=Wombat
        !          1863: \end{verbatim}\end{quote}
        !          1864: is allowed to pull the EDB, but the following are not:
        !          1865: \begin{quote}\small\begin{verbatim}
        !          1866: cn=Wombat
        !          1867: c=US@o=Foobar Inc.@cn=Wombat
        !          1868: c=GB@cn=Wombat
        !          1869: \end{verbatim}\end{quote}
        !          1870: 
        !          1871: Whether to update is decided upon by looking at the version string, if the
        !          1872: two EDB files have a different version string, then the EDB will be updated.
        !          1873: 
        !          1874: \section {Tables}
        !          1875: \label {oidtables}
        !          1876: Throughout QUIPU, all the Object Identifiers that need to be specified, are
        !          1877: specified using a string representation, for example:-
        !          1878: 
        !          1879: \[\begin{tabular}{|l|l|} \hline
        !          1880: String representation & Object Identifier  \\ \hline 
        !          1881: attributeType & 2.5.4 \\
        !          1882: surname & 2.5.4.4 \\
        !          1883: streetAddress & 2.5.4.9 \\
        !          1884: organizationName & attributeType.10 \\ \hline
        !          1885: \end{tabular}\]
        !          1886: 
        !          1887: A set of Object Identifier tables in the ISODE \verb"ETCDIR" directory are
        !          1888: used to 
        !          1889: provide this mapping (see also Section~\ref{isobject} in \volone/).
        !          1890: In general the default table will be sufficient, 
        !          1891: this section describes the tables for those who want to extend
        !          1892: the default definitions.
        !          1893: 
        !          1894: This basic format is used to build up the specification of general object
        !          1895: identifiers.  
        !          1896: This file is by default named \file{oidtable.gen}, and has simple
        !          1897: mappings from string to oid.
        !          1898: These strings can then be used in the definition of further oids (for example
        !          1899: the ``organizationName'' oid in the table above).
        !          1900: 
        !          1901: This simple table is extended to give table formats for attributes
        !          1902: This file is by default named \file{oidtable.at}.
        !          1903: Each entry in this table is assumed to represent an attribute, so
        !          1904: in addition to mapping strings onto oids, 
        !          1905: it also defines the syntax for that attribute:-
        !          1906: 
        !          1907: \[\begin{tabular}{|l|l|l|} \hline
        !          1908: String representation & Object Identifier & Syntax\\ \hline
        !          1909: objectClass:&          attributeType.0:        &objectclass \\
        !          1910: aliasedObjectName:&     attributeType.1:       &dn\\
        !          1911: commonName,cn:&                attributeType.3:        &caseignorestring\\
        !          1912: searchGuide:&           attributeType.14:      &asn\\
        !          1913: x121Address:&           attributeType.24:      &numericstring\\
        !          1914: presentationAddress:&  attributeType.29:       &presentationaddress\\
        !          1915: \hline
        !          1916: \end{tabular}\]
        !          1917: 
        !          1918: This says that the attribute named ``objectclass'' represents the oid
        !          1919: ``attributeType.0'' --- using the expansion of ``attributeType'' (
        !          1920: as defined in the 
        !          1921: file \file{oidtable.gen}) thus gives the oid ``2.5.4.0''.
        !          1922: The syntax taken by the attribute value is ``objectclass''.
        !          1923: 
        !          1924: Similarly an ``aliasedObjectName'' has ``dn'' (DistinguishedName) syntax.
        !          1925: The recognised syntaxes are defined in the BNF in 
        !          1926: Appendix~\ref{bnf}.
        !          1927: 
        !          1928: After the ``syntax'' an extra optional parameter is allowed;
        !          1929: if this is the string ``\verb"file"'' the the relevant attribute is 
        !          1930: designated a file attribute --- see Section~\ref{file_attr} for a
        !          1931: description of file attributes.
        !          1932: 
        !          1933: 
        !          1934: The file \file{oidtable.oc} defines the object classes\index{object
        !          1935: class} QUIPU knows about.
        !          1936: The file again maps strings onto oids.
        !          1937: Each string is assumed to represent an object class, abd for each it
        !          1938: defines the hierarchy (which object classes it is a subclass of),
        !          1939: the mandatory attributes of the object class, and the optional attributes of
        !          1940: the object class.
        !          1941: 
        !          1942: For example the entry
        !          1943: \begin{quote}\small\begin{verbatim}
        !          1944: quipuObject:   quipuObjectClass.2 : top : acl : \
        !          1945:                 masterDSA, slaveDSA, treeStructure
        !          1946: \end{verbatim}\end{quote}
        !          1947: 
        !          1948: defines ``quipuObject'' to be an objectClass represented by the oid
        !          1949: ``quipuObjectClass.2''.
        !          1950: It is a SUBCLASS of the object class ``top''.
        !          1951: An entry having this object class MUST have the attribute ``acl'', and MAY
        !          1952: have the attributes ``masterDSA'', ``slaveDSA'' and ``treeStructure''
        !          1953: (NOTE The similarity between this definition and the ASN.1 definition of
        !          1954: a ``quipuObject'' in Appendix \ref{naming}).
        !          1955: 
        !          1956: To allow for definitions of ``attribute sets'', there is a simple 
        !          1957: MACRO facility provided, for example, using the MACRO
        !          1958: \begin{quote}\small\begin{verbatim}
        !          1959: localeAttributeSet = localityName, streetAddress ...
        !          1960: \end{verbatim}\end{quote}
        !          1961: every occurrence of ``\verb"localeAttributeSet"'' will be replace by the right 
        !          1962: hand side expression.
        !          1963: 
        !          1964: 
        !          1965: With the definition of the ``string'' form of the oid it is also possible
        !          1966: to specify ONE abbreviation for the name.
        !          1967: The standard tables use the following abbreviations:-
        !          1968: 
        !          1969: \[\begin{tabular}{|l|l|}
        !          1970: \hline
        !          1971: c & countryName \\
        !          1972: o & organizationName \\
        !          1973: ou & organizationalUnitName \\
        !          1974: cn & commonName \\
        !          1975: co & friendlyCountryName \\
        !          1976: \hline
        !          1977: \end{tabular}\]
        !          1978: 
        !          1979: The abbreviated name may be used anywhere the full name would be allowed.
        !          1980: 
        !          1981: 
        !          1982: Every entry stored in the QUIPU DSA is checked against these tables to see if
        !          1983: the attributes supplied are allowed in the entry, to make sure the mandatory
        !          1984: attributes are present, and the attributes themselves have the correct syntax.
        !          1985: 
        !          1986: If you wish to add you own definitions to the tables you should add them to
        !          1987: the files 
        !          1988: \file{isode/dsap/oidtable.at.local},
        !          1989: \file{isode/dsap/oidtable.oc.local} and
        !          1990: \file{isode/dsap/oidtable.gen.local}
        !          1991: in that way, if a new set of tables are issued, you local entries will be
        !          1992: preserved.
        !          1993: 
        !          1994: \section{More Help Installing Quipu}
        !          1995: Contact ``quipu-support'',
        !          1996: the mail address is given in Section~\ref{quipu:support}.
        !          1997: 

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