Return to introduction.tex CVS log

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

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

1.1     ! root        1: % run this through LaTeX with the appropriate wrapper
        !             2: 
        !             3: \chapter      {Introduction}
        !             4: This document is {\em The Administrator's Guide\/} for the
        !             5: NYSERNet/PSI White Pages Pilot.
        !             6: The goal of \theguide/ is to provide a site administrator
        !             7: with enough information to be able to participate in the White Pages
        !             8: Pilot.
        !             9: In practical terms,
        !            10: this means that \theguide/ provides information on how
        !            11: to install and maintain an OSI Directory at your site.
        !            12: 
        !            13: The OSI Directory is used to provide the white pages service.
        !            14: \theguide/ is not intended as a tutorial nor a detailed description
        !            15: of the OSI Directory.
        !            16: However, as administrative responsibilities and procedures are
        !            17: outlined,
        !            18: the appropriate Directory concepts will be introduced.%
        !            19: \footnote{Actually this paragraph is a lie:
        !            20: you can't administer the white pages without knowing what you're
        !            21: doing,
        !            22: and you don't know what you're doing unless you understand both
        !            23: the basics of the OSI Directory and how the pilot project software
        !            24: implements the Directory Service.
        !            25: As such,
        !            26: this entire chapter is really a thinly-veiled primer on these
        !            27: two topics.}
        !            28: 
        !            29: Your comments are welcome!
        !            30: The OSI Directory is a new, complex technology.
        !            31: Although \theguide/ attempts to be straight-forward it probably doesn't
        !            32: succeed all the time.
        !            33: If you have comments on this document, send them to the Internet
        !            34: mailbox
        !            35: \begin{quote}\begin{verbatim}
        !            36: [email protected]
        !            37: \end{verbatim}\end{quote}
        !            38: so that \theguide/ can be improved.
        !            39: 
        !            40: \newpage
        !            41: 
        !            42: \section*     {Related Documentation}
        !            43: The white paper
        !            44: {\em An Introduction to a NYSERNet White Pages Pilot Project\/}
        !            45: introduces the goals and phases of the pilot project.
        !            46: Administrators should familiarize themselves with this document
        !            47: before proceeding.
        !            48: 
        !            49: There is also a document which you should provide to the user community at
        !            50: your organization.
        !            51: It is called
        !            52: {\em NYSERNet/PSI White Pages Pilot Project: User's Handbook},
        !            53: or simply \thebook/.
        !            54: 
        !            55: The OSI Directory standard is defined in \cite{ISO.Directory,CCITT.Directory}.
        !            56: 
        !            57: The research note {\em The Design of QUIPU\/} \cite{QUIPU.Design}
        !            58: describes the design of the software used for the pilot project,
        !            59: whilst {\em Volume Five\/} of the ISODE User's Manual \cite{QUIPU.Manual},
        !            60: henceforth termed \volfive/,
        !            61: describes the implementation of the software.
        !            62: \theguide/ is intended to replace these later two documents as the
        !            63: primary reference for administrators of the pilot project.
        !            64: 
        !            65: PostScript versions of these documents are available via anonymous FTP
        !            66: from host \verb"nisc.nyser.net" (\verb"[192.33.4.10]"):
        !            67: \begin{quote}\small\begin{verbatim}
        !            68: % cd /usr/src/local/
        !            69: % ftp nisc.nyser.net
        !            70: Connected to nisc.nyser.net.
        !            71: 220 nisc.nyser.net FTP server ready
        !            72: Name (nisc.nyser.net:user): anonymous
        !            73: Password (nisc.nyser.net:anonymous): guest
        !            74: 331 Guest login ok, send ident as password.
        !            75: 230 Guest login ok, access restrictions apply.
        !            76: ftp> binary
        !            77: 200 Type set to I.
        !            78: ftp> cd pub/isode
        !            79: ftp> get isode-ps.tar.Z
        !            80: ftp> get pilot-ps.tar.Z
        !            81: ftp> quit
        !            82: % uncompress < isode-ps.tar.Z | tar xf -
        !            83: % uncompress < pilot-ps.tar.Z | tar xf -
        !            84: % rm isode-ps.tar.Z pilot-ps.tar.Z
        !            85: \end{verbatim}\end{quote}
        !            86: 
        !            87: \newpage
        !            88: \section      {Informational Model}
        !            89: From a theoretical standpoint,
        !            90: the internals of the white pages service can be viewed from 
        !            91: four different perspectives.
        !            92: We begin with the Informational Model which describes the service in terms of
        !            93: information objects.
        !            94: The Directory's representation of an information object,
        !            95: typically called an {\em entry},
        !            96: contains information about a person, a place, an organization, etc.
        !            97: Each entry consists of one or more attributes.
        !            98: 
        !            99: Each attribute consists of a type,\index{attribute types}
        !           100: indicating what kind of attribute it is,
        !           101: and one or more values
        !           102: (one of which is termed the {\em distinguished value\/}).
        !           103: Attribute values are structured using a data definition language
        !           104: called  Abstract Syntax Notation One (ASN.1).
        !           105: As such,
        !           106: different programs using the Directory will interpret information in the same
        !           107: way.
        !           108: In addition,
        !           109: the Directory will perform type-checking on the values in order
        !           110: to keep things consistent.
        !           111: 
        !           112: \subsection    {Naming}
        !           113: One of the attributes of an entry is particularly special:
        !           114: it is referred to as the {\em Relative Distinguished Name\/} (RDN) of
        !           115: the entry.
        !           116: The RDN is formed by taking the name of the attribute and its
        !           117: distinguished value.
        !           118: For example,
        !           119: if the attribute in question was called \verb"countryName" and it had
        !           120: a distinguished value of \verb"US", then we might say that the RDN
        !           121: for the entry was \verb"countryName=US".
        !           122: Of course,
        !           123: this is strictly a ``user-friendly'' notation:
        !           124: the Directory uses a concise binary format for representing an RDN.
        !           125: Fortunately,
        !           126: the pilot project software allows simple textual strings to be used in their
        !           127: place and converts back and forth accordingly.
        !           128: 
        !           129: In the OSI Directory,
        !           130: information is primarily organized according to a hierarchical tree
        !           131: structure.
        !           132: The top of the tree is termed the {\em root},
        !           133: and has no explicit name.
        !           134: To find the  name of an object,
        !           135: termed its {\em Distinguished Name\/} (DN),
        !           136: one concatenates the RDNs found when traversing the tree by starting
        !           137: at the root and proceeding directly to the object's entry.
        !           138: 
        !           139: For purposes of discussion,
        !           140: we write a Distinguished Name as an ordered series of RDNs separated by
        !           141: an \verb"`@'"-sign with the most significant RDN appearing at the left;
        !           142: e.g.,
        !           143: \begin{quote}\small\begin{verbatim}
        !           144: countryName=US@organizationName=NYSERNet Inc.
        !           145: \end{verbatim}\end{quote}
        !           146: refers to an entry with an RDN of \verb"organizationName=NYSERNet Inc."
        !           147: whose parent has an RDN of \verb"countryName=US".
        !           148: In turn,
        !           149: this parent entry is an immediate child of the root.
        !           150: 
        !           151: To avoid any potential ambiguity when using an interface to the Directory
        !           152: such as \man fred(1c) or \man dish(1c),
        !           153: one prefixes a \verb"`@'"-sign to a string when referring to a fully
        !           154: qualified Distinguished Name;
        !           155: e.g.,
        !           156: \begin{quote}\small\begin{verbatim}
        !           157: @countryName=US@organizationName=NYSERNet Inc.
        !           158: \end{verbatim}\end{quote}
        !           159: always refers to the same entry regardless of context.
        !           160: Note that this is a convention only for interface programs such as these.
        !           161: 
        !           162: As a rule,
        !           163: unless searching,
        !           164: text before the \verb"`='"-sign is not case sensitive,
        !           165: neither is text after the \verb"`='"-sign.
        !           166: 
        !           167: Of course, names like \verb"countryName",
        !           168: while more friendly than binary strings,
        !           169: are still rather long,
        !           170: so there are several abbreviations that the pilot project software permits.
        !           171: Table~\ref{attribute-types} lists the attribute types supported by
        !           172: the pilot project, any abbreviations, and the syntax associated with
        !           173: each attribute's value.
        !           174: Throughout \theguide/,
        !           175: the semantics of these attributes will be introduced.
        !           176: When using this document later on,
        !           177: refer to the Index to quickly find a particular attribute you are interested
        !           178: in.
        !           179: \tagtable[tp]{INT-1}{Supported Attribute Types}{attribute-types}
        !           180: 
        !           181: The entities which access the Directory on behalf of a user
        !           182: are termed {\em Directory User Agents\/} (DUAs).
        !           183: The entities which provide the Directory service are termed
        !           184: {\em Directory System Agents\/} (DSAs).
        !           185: Both kinds of entities are identified by their Distinguished Name.
        !           186: That is,
        !           187: the DSAs and DUAs are not only network processes,
        !           188: they are also objects which have entries in the Directory.
        !           189: 
        !           190: \subsection    {How Entries and Objects are Described}\label{edb:format}
        !           191: It is now time to explain the notation used to describe entries.
        !           192: This notation is termed the ``EDB format'',
        !           193: and is named after the disk-resident data structures used by the
        !           194: pilot project software.
        !           195: 
        !           196: An entry is textually described in an ASCII formatted file.
        !           197: The format of the file is simple:
        !           198: \begin{itemize}
        !           199: \item  Each entry consists of two or more lines followed by a blank line.
        !           200: 
        !           201: \item  Each line consists of an attribute type/value pair using
        !           202:        the familiar
        !           203: \begin{quote}\small\begin{verbatim}
        !           204: name=value
        !           205: \end{verbatim}\end{quote}
        !           206: notation,
        !           207: such as:
        !           208: \begin{quote}\small\begin{verbatim}
        !           209: c=US
        !           210: \end{verbatim}\end{quote}
        !           211: 
        !           212: \item  If multiple values are present for an entry,
        !           213:        then either multiple lines may be used or the values may
        !           214:        be separated by the \verb"`&'"-sign.
        !           215:        The first value occurring is the distinguished value.
        !           216:        Hence,
        !           217: \begin{quote}\small\begin{verbatim}
        !           218: co=US
        !           219: co=United States of America
        !           220: \end{verbatim}\end{quote}
        !           221: and
        !           222: \begin{quote}\small\begin{verbatim}
        !           223: co=US & United States of America
        !           224: \end{verbatim}\end{quote}
        !           225: are identical:
        !           226: both say that the attribute \verb"friendlyCountryName" has two values:
        !           227: the distinguished value is \verb"US" and an alternate value is
        !           228: \verb"United States of America".
        !           229: 
        !           230: \item  Most attributes take textual strings for their value.
        !           231:        However, for a large number of attributes,
        !           232:        the actual characters used are limited to a subset of the
        !           233:        ``printable'' characters: 
        !           234: \begin{quote}\begin{tabular}{l}
        !           235: \verb"A" through \verb"Z"\\
        !           236: \verb"a" through \verb"z"\\
        !           237: \verb"0" through \verb"9"\\
        !           238: \verb"'" (apostrophe)\\
        !           239: \verb"(" (left parenthesis)\\
        !           240: \verb")" (right parenthesis)\\
        !           241: \verb"+" (plus-sign)\\
        !           242: \verb"," (comma)\\
        !           243: \verb"-" (hyphen)\\
        !           244: \verb"." (period)\\
        !           245: \verb"/" (solidus)\\
        !           246: \verb":" (colon)\\
        !           247: \verb"?" (question-mark)\\
        !           248: space
        !           249: \end{tabular}\end{quote}
        !           250:        In particular, note that the characters \verb"`='", \verb"`&'",
        !           251:        \verb"`$'" and \verb"`#'" are not allowed.
        !           252: 
        !           253:        If it makes sense to use a particular character, e.g., \verb"`@'"
        !           254:        in a mail address,
        !           255:        then this usage is usually permitted.
        !           256: 
        !           257:        If it is necessary to characters from the restricted set,
        !           258:        proceed the value with \verb"{T.61}", e.g.,
        !           259: \begin{quote}\small
        !           260: \begin{verbatim}
        !           261: {T.61}whatever$you$want
        !           262: \end{verbatim}\end{quote}
        !           263: 
        !           264:        Always use the appropriate case (upper or lower) when entering
        !           265:        values.
        !           266:        Although the Directory supports imprecise matching for searching,
        !           267:        direct lookup is made on the basis of an exact match.
        !           268: 
        !           269:        When strings are read by the pilot project software,
        !           270:        it strips leading and trailing blanks and also compresses multiple
        !           271:        blanks to a single blank space.
        !           272: 
        !           273: \item  Another common kind of attribute value is a Distinguished
        !           274:        Name, which is specified using the DN notation described earlier.
        !           275:        Note that a DN is always interpreted in absolute form when it is
        !           276:        written in an EDB file.
        !           277:        Hence, the leading \verb"`@'"-sign is never written.
        !           278: 
        !           279: \item  Of course,
        !           280:        there are a few attributes with very special syntaxes,
        !           281:        when these attributes are introduced,
        !           282:        the associated notation will be discussed.
        !           283: \end{itemize}
        !           284: Note that the first line for an entry gives the object's RDN.
        !           285: This line should be repeated later on in the entry,
        !           286: this causes it to be included in the attributes for the object.
        !           287: (The pilot software includes this attribute automatically,
        !           288: but it is a good practice regardless.)
        !           289: 
        !           290: An EDB file contains all of the child objects of a node in the tree.
        !           291: The first line of the file consists of a single keyword, one of:
        !           292: \begin{describe}
        !           293: \item[MASTER:] indicating that this EDB file is the original source of the
        !           294:                information;
        !           295: 
        !           296: \item[SLAVE:]  indicating that this EDB file is a copy of the information
        !           297:                from an authoritative source;
        !           298:                and,
        !           299: 
        !           300: \item[CACHE:]  indicating that this EDB file is a partial, unauthoriative
        !           301:                copy of the information.
        !           302: \end{describe}
        !           303: The second line of the file contains the creation date of the information
        !           304: in the file.
        !           305: This is expressed as a \verb"UniversalTime".
        !           306: Put simply,
        !           307: the format used is:\label{UniversalTime}
        !           308: \begin{quote}\small\begin{verbatim}
        !           309: yymmddhhmmssZ
        !           310: \end{verbatim}\end{quote}
        !           311: as in:
        !           312: \begin{quote}\small\begin{verbatim}
        !           313: 890509213614Z
        !           314: \end{verbatim}\end{quote}
        !           315: which is May 9$^{\underline{\mbox{\scriptsize th}}}$, {\oldstyle 1989},
        !           316: 21:36:14 hours at UT.
        !           317: 
        !           318: Hence,
        !           319: the format of an EDB file is:
        !           320: \begin{quote}\small\begin{verbatim}
        !           321: <keyword>
        !           322: yymmddhhmmssZ
        !           323: <entries>
        !           324: \end{verbatim}\end{quote}
        !           325: (remember that each entry ends with a blank line).
        !           326: Figure~\ref{edb-example} shows an example of a simple EDB file
        !           327: containing two entries.
        !           328: \tagfigure[tp]{INT-1}{An Example of an EDB file}{edb-example}
        !           329: 
        !           330: \subsection    {Object Classes}\index{object classes}\index{attribute types, objectClass}
        !           331: One attribute of an entry,
        !           332: its \verb"objectClass",
        !           333: determines what kind of object this entry corresponds to (e.g., a person).
        !           334: The value of this attribute indicates what types of attributes the
        !           335: entry {\em must\/} and {\em may\/} contain.
        !           336: For example,
        !           337: if the value of \verb"objectClass" indicates that the entry corresponds
        !           338: to a person,
        !           339: then it would make sense for that entry to have a \verb"surName"
        !           340: attribute.
        !           341: On the other hand,
        !           342: if the value of \verb"objectClass" indicates that the entry corresponds
        !           343: to an organization,
        !           344: then a \verb"surName" attribute would be inappropriate.
        !           345: 
        !           346: The OSI Directory is flexible in that it defines several common
        !           347: types of objects,
        !           348: and then allows users to define their own objects.
        !           349: Further,
        !           350: object definition is based on the notion of {\em class inheritance}.
        !           351: This means that an object class can be defined as a ``subclass'' of
        !           352: a previously defined object class with additional refinements.
        !           353: As a subclass,
        !           354: the newly defined object ``inherits'' all the semantics of its
        !           355: superclass,
        !           356: in addition to having additional semantics.
        !           357: 
        !           358: For example,
        !           359: the Directory defines an object class called \verb"person".
        !           360: This object class defines the attributes which a person in
        !           361: the real world might have.
        !           362: It may be useful to refine this somewhat to talk about persons
        !           363: who have Internet access.
        !           364: So, we need a new object class, e.g., \verb"internetPerson".
        !           365: This can be defined in a straight-forward fashion:
        !           366: \begin{quote}
        !           367: The object class \verb"internetPerson" is a subclass of the object class
        !           368: \verb"person" which {\em may\/} contain an additional attribute,
        !           369: \verb"internetMailbox".
        !           370: 
        !           371: The syntax of an \verb"internetMailbox" is a simple string of printable
        !           372: characters which is not case sensitive when performing comparisons.
        !           373: \end{quote}
        !           374: Thus,
        !           375: when entries are defined with an \verb"objectClass" attribute which contains
        !           376: the value \verb"internetPerson":
        !           377: \begin{itemize}
        !           378: \item  they {\em must\/} contain whatever attributes an entry with
        !           379:        \verb"objectClass" \verb"person" {\em must\/} contain;
        !           380: 
        !           381: \item  they {\em may\/} contain whatever attributes an entry with
        !           382:        \verb"objectClass" \verb"person" {\em may\/} contain;
        !           383:        and,
        !           384: 
        !           385: \item  they {\em may\/} contain the \verb"internetMailbox" attribute.
        !           386: \end{itemize}
        !           387: 
        !           388: As was seen in Figure~\ref{edb-example} on page~\pageref{edb-example},
        !           389: the \verb"objectClass" attribute is multi-valued.
        !           390: For our purposes,
        !           391: object class values fall into one of two categories:
        !           392: \begin{itemize}
        !           393: \item  the primary class,
        !           394:        of which each object has one
        !           395:        (this is the class that inherited all the properties from the
        !           396:        superclasses);
        !           397:        and,
        !           398: 
        !           399: \item  one or more superclasses.
        !           400: \end{itemize}
        !           401: In order to limit the focus of the pilot project,
        !           402: only a few primary classes are supported.
        !           403: Further,
        !           404: of those classes,
        !           405: not all optional attributes are supported.%
        !           406: \footnote{This limitation is specific to the pilot project;
        !           407: the pilot project software can support the entire range of object classes
        !           408: and attribute types.}
        !           409: Before discussing the primary classes and their class-specific attributes,
        !           410: there are a few attributes which are required for every object.
        !           411: These are introduced by looking at a few key superclasses.
        !           412: 
        !           413: \subsubsection {The top objectClass}\index{object classes, top}
        !           414: The Directory requires that every object have \verb"top" as a super
        !           415: class.
        !           416: Only one attribute is required for members of this class:
        !           417: \begin{describe}
        !           418: \item[objectClass:]\index{attribute types, objectClass}
        !           419:                        which defines all the classes that this object belongs
        !           420:                        to.
        !           421: \end{describe}
        !           422: 
        !           423: \subsubsection {The quipuObject objectClass}\index{object classes, quipuObject}
        !           424: In addition,
        !           425: the pilot project software requires that every object also have the object
        !           426: class \verb"quipuObject" as a superclass.
        !           427: Only one attribute is required for members of this class:
        !           428: \begin{describe}
        !           429: \item[accessControlList:]\index{attribute types, accessControlList}\index{attribute types, acl (accessControlList)}
        !           430:                        which defines how users of the Directory may
        !           431:                        access the entry.
        !           432: \end{describe}
        !           433: The \verb"accessControlList" attribute uses a special notation to enter
        !           434: its value in the EDB file:
        !           435: \begin{quote}\small\begin{verbatim}
        !           436: <syntax> ::= <who> "#" <action> "#" <what>
        !           437: 
        !           438: <who> ::=       "group" "#" DN
        !           439:             |   "prefix" "#" DN
        !           440:             |   "others"
        !           441:             |   "self"
        !           442: 
        !           443: <action> ::=    "none"
        !           444:             |   "detect"
        !           445:             |   "compare"
        !           446:             |   "read"
        !           447:             |   "add"
        !           448:             |   "write"
        !           449: 
        !           450: <what> ::=      "child"
        !           451:             |   "entry"
        !           452:             |   "default"
        !           453:             |   "attributes" "#" <attribute-list>
        !           454: 
        !           455: <attribute-list> ::=
        !           456:                 attribute-name
        !           457:             |   attribute-name "$" <attribute-list>
        !           458: \end{verbatim}\end{quote}
        !           459: The \verb"<who>" part indicates who the rule applies to.
        !           460: Recall that when a user connects to the Directory,
        !           461: the user {\em binds\/} on behalf of a Distinguished Name.
        !           462: This DN is used to determine which rules apply to the user:
        !           463: \begin{describe}
        !           464: \item[group:]  indicates a DN which has an \verb"objectClass" attribute
        !           465:                of \verb"groupOfNames" or \verb"organizationalRole",
        !           466:                or it indicates a particular DN, which is the most
        !           467:                common case.
        !           468: 
        !           469: \item[prefix:] indicates all DNs which start with the indicated
        !           470:                prefix.  Thus, access may be granted to all users
        !           471:                at or below a particular part of the tree.
        !           472: 
        !           473: \item[self:]   indicates the DN which corresponds to this object.
        !           474: 
        !           475: \item[others:] the default case.
        !           476: \end{describe}
        !           477: The \verb"<what>" part indicates what part of the entry the rule applies
        !           478: to:
        !           479: \begin{describe}
        !           480: \item[child:]  the access control rule applies to children immediately below
        !           481:                the entry.
        !           482: 
        !           483: \item[entry:]  the access control rule applies to the entry itself.
        !           484: 
        !           485: \item[attributes:] the access control rule applies to exactly those
        !           486:                attributes listed.
        !           487:                Multiple attributes pertaining to the same rule are
        !           488:                separated by the \verb"`$'"-sign.
        !           489: 
        !           490: \item[default:]        the default rule for attributes.
        !           491: \end{describe}
        !           492: The \verb"<action>" part indicates the actions which are permitted.
        !           493: The semantics of this part vary, depending on the \verb"<what>" part.
        !           494: However,
        !           495: the \verb"<action>" values are ordered from least- to most-significant;
        !           496: e.g., having ``read'' permission implies both ``compare'' and ``detect''
        !           497: permission.
        !           498: \begin{describe}
        !           499: \item[none:]
        !           500: \begin{tabular}[t]{rp{3.35in}}
        !           501: for entries:&          any knowledge of the entry is hidden\\
        !           502: for attributes:&       any knowledge of the attribute is hidden\\
        !           503: for children:&         downwards progress is blocked
        !           504: \end{tabular}
        !           505: 
        !           506: \item[detect:]
        !           507: \begin{tabular}[t]{rp{3.35in}}
        !           508: for entries:& determination of the entry's existence is permitted\\
        !           509: for attributes:& determination of the attribute's existence is permitted\\
        !           510: for children:& the existence of children is admitted, but downwards progress is still blocked\\
        !           511: \end{tabular}
        !           512: 
        !           513: \item[compare:]
        !           514: \begin{tabular}[t]{rp{3.35in}}
        !           515: for entries:& the RDN may be compared\\
        !           516: for attributes:& the values of the attribute may be compared\\
        !           517: for children:& exactly specified RDNs may be matched\\
        !           518: \end{tabular}
        !           519: 
        !           520: \item[read:]
        !           521: \begin{tabular}[t]{rp{3.35in}}
        !           522: for entries:& the RDN may be read\\
        !           523: for attributes:& the attribute values may be read\\
        !           524: for children:& the child information may be listed, and downward searches are permitted\\
        !           525: \end{tabular}
        !           526: 
        !           527: \item[add:]
        !           528: \begin{tabular}[t]{rp{3.35in}}
        !           529: for entries:& new attributes may be added\\
        !           530: for attributes:& new attribute values may be added\\
        !           531: for children:& new children may be added\\
        !           532: \end{tabular}
        !           533: 
        !           534: \item[write:]
        !           535: \begin{tabular}[t]{rp{3.35in}}
        !           536: for entries:& the RDN may be changed and existing attributes may be added\\
        !           537: for attributes:& values may be modified or removed\\
        !           538: for children:& children may be removed\\
        !           539: \end{tabular}
        !           540: \end{describe}
        !           541: The only exception to these rules is the \verb"accessControlList" attribute
        !           542: itself: access control rules may be added only to the extent access is
        !           543: allowed by the user.
        !           544: 
        !           545: The default access control list is
        !           546: \begin{quote}\small\begin{verbatim}
        !           547: acl=
        !           548: \end{verbatim}\end{quote}
        !           549: which simply means ``read'' access for everything and also
        !           550: \begin{quote}\small\begin{verbatim}
        !           551: self # write # entry
        !           552: self # write # default
        !           553: \end{verbatim}\end{quote}
        !           554: 
        !           555: There are two optional attributes.
        !           556: These are maintained automatically by the Directory:
        !           557: \begin{describe}
        !           558: \item[lastModifiedBy:]\index{attribute types, lastModifiedBy}
        !           559:                        identifies the Directory entity which last modified
        !           560:                        this entry.
        !           561:                        The value is a Distinguished Name.
        !           562: 
        !           563: \item[lastModifiedTime:]\index{attribute types, lastModifiedTime}
        !           564:                        identifies the time at which this entry was last
        !           565:                        modified.
        !           566:                        The value is a \verb"UniversalTime",
        !           567:                        the syntax of which was described earlier on
        !           568:                        page~\pageref{UniversalTime}.
        !           569: \end{describe}
        !           570: 
        !           571: \subsubsection {The quipuNonLeafObject objectClass}\index{object classes, quipuNonLeafObject}
        !           572: If an object is permitted children,
        !           573: the pilot project software requires that that object also have
        !           574: \verb"quipuNonLeafObject" as a superclass.
        !           575: 
        !           576: This class has one mandatory attribute:
        !           577: \begin{describe}
        !           578: \item[masterDSA:]\index{attribute types, masterDSA}
        !           579:                        identifies the Directory entity which is responsible
        !           580:                        for maintaining the MASTER EDB for the children of
        !           581:                        this entry.
        !           582:                        The value is a Distinguished Name.
        !           583: \end{describe}
        !           584: There is typically a single MASTER for a particular entry in the tree.
        !           585: Hence, this value is usually single-valued.
        !           586: When an entry is to be modified,
        !           587: the Directory must contact the entity responsible for the MASTER EDB for
        !           588: that entry in order to perform the modification.
        !           589: 
        !           590: This class has two optional attributes:
        !           591: \begin{describe}
        !           592: \item[slaveDSA:]\index{attribute types, slaveDSA}
        !           593:                        identifies any Directory entities which have
        !           594:                        authoritative copies of the EDB for the children
        !           595:                        of this entry.
        !           596:                        The value is one or more Distinguished Names.
        !           597: 
        !           598: \item[treeStructure:]\index{attribute types, treeStructure}
        !           599:                        identifies the object classes which may exist
        !           600:                        immediately below this entry.
        !           601:                        The value is one or more object classes.
        !           602: \end{describe}
        !           603: Since a fundamental assumption of the Directory is that reads (queries)
        !           604: occur much more frequently than writes (updates),
        !           605: it is common to have several entities containing authoritative copies of an
        !           606: EDB.
        !           607: By keeping copies locally,
        !           608: queries can be answered with less latency.
        !           609: 
        !           610: \subsubsection {The domainRelatedObject objectClass}\index{object classes, domainRelatedObject}
        !           611: If an object has some relationship to the Internet Domain Name System (DNS),
        !           612: the pilot project software requires that that object also have
        !           613: \verb"domainRelatedObject" as a superclass.
        !           614: 
        !           615: This class has one mandatory attribute:
        !           616: \begin{describe}
        !           617: \item[associatedDomain:]\index{attribute types, associatedDomain}
        !           618:                        identifies the domain which corresponds to this object.
        !           619:                        The value is a domain string, e.g.,
        !           620: \begin{quote}\small\begin{verbatim}
        !           621: nyser.net
        !           622: \end{verbatim}\end{quote}
        !           623: \end{describe}
        !           624: There is typically a single MASTER for a particular entry in the tree.
        !           625: Hence, this value is usually single-valued.
        !           626: When an entry is to be modified,
        !           627: the Directory must contact the entity responsible for the MASTER EDB for
        !           628: that entry in order to perform the modification.
        !           629: 
        !           630: Now we look at the primary object classes.
        !           631: Keep in mind that these all have both \verb"top" and \verb"quipuObject" as
        !           632: superclasses.
        !           633: Further,
        !           634: the primary classes which are permitted children all have
        !           635: \verb"quipuNonLeafObject" as a superclass.
        !           636: 
        !           637: \subsubsection {The friendlyCountry objectClass}\index{object classes, friendlyCountry}
        !           638: Objects of this class represent a sovereign nation.
        !           639: For the purposes of the NYSERNet/PSI White Pages Pilot,
        !           640: there is only one of these,
        !           641: although the pilot project is attached to a world-wide Directory service.
        !           642: 
        !           643: Table~\ref{friendlyCountry-attributes} summarizes the attributes types for
        !           644: a \verb"friendlyCountry" object.
        !           645: There are two mandatory attributes:
        !           646: \begin{describe}
        !           647: \item[countryName:]\index{attribute types, countryName}\index{attribute types, c (countryName)}
        !           648:                        which gives the name of the country.
        !           649:                        The value of this attribute is a two-letter ISO~3166
        !           650:                        code; e.g.,
        !           651: \begin{quote}\small\begin{verbatim}
        !           652: US
        !           653: \end{verbatim}\end{quote}
        !           654: 
        !           655: \item[friendlyCountryName:]\index{attribute types, friendlyCountryName}\index{attribute types, co (friendlyCountryName)}
        !           656:                        which gives a user-friendly rendition of the
        !           657:                        country's name (hence the term \verb"friendlyCountry").
        !           658:                        The value of this attribute is a string; e.g.,
        !           659: \begin{quote}\small\begin{verbatim}
        !           660: United States of America
        !           661: \end{verbatim}\end{quote}
        !           662: \end{describe}
        !           663: \tagtable[tp]{INT-2}{Attribute Types for the friendlyCountry Object Class}%
        !           664:        {friendlyCountry-attributes}
        !           665: 
        !           666: In addition,
        !           667: there is one attribute that may be present:
        !           668: \begin{describe}
        !           669: \item[description:]\index{attribute types, description}
        !           670:                        which is a simple textual description;
        !           671:                        e.g.,
        !           672: \begin{quote}\small\begin{verbatim}
        !           673: the land of the free and the home of the brave
        !           674: \end{verbatim}\end{quote}
        !           675: \end{describe}
        !           676: 
        !           677: Putting everything together,
        !           678: one could describe an entry for an object of class \verb"friendlyCountry"
        !           679: thusly:
        !           680: \begin{quote}\small\begin{verbatim}
        !           681: c=US
        !           682: masterDSA= cn=Alpaca#
        !           683: slaveDSA= cn=Fruit Bat#
        !           684: slaveDSA= cn=Giant Tortoise# 
        !           685: acl= others # read # entry
        !           686: acl= group # c=US@cn=Manager # write # entry
        !           687: acl= others # read # default
        !           688: acl= group # c=US@cn=Manager # write # default
        !           689: treeStructure= quipuNonLeafObject & organization & locality
        !           690: treeStructure= quipuDSA & alias & organizationalRole
        !           691: c= US
        !           692: co= USA & US & United States of America
        !           693: objectClass= top & quipuObject & quipuNonLeafObject
        !           694: objectClass= country & friendlyCountry
        !           695: \end{verbatim}\end{quote}
        !           696: These lines indicate that:
        !           697: \begin{itemize}
        !           698: \item  The RDN for this object is \verb"c=US"
        !           699:        (read ``country name is US'').
        !           700: 
        !           701: \item  The user-friendly name for this country takes on one of three values
        !           702: \begin{quote}\small\begin{verbatim}
        !           703: USA
        !           704: US
        !           705: United States of America
        !           706: \end{verbatim}\end{quote}
        !           707: 
        !           708: \item  There are two DSAs which have SLAVE copies of the EDB for this
        !           709:        object, one is called \verb"cn=Giant Tortoise" and the other
        !           710:        is called \verb"cn=Fruit Bat".
        !           711:        (We'll discuss how these colorful names are chosen later on.)
        !           712: 
        !           713: \item  The DSA responsible for maintaining the MASTER copy of the EDB
        !           714:        is called \verb"cn=Alpaca".
        !           715:        Note that all three of these DSAs live directly under the ROOT of
        !           716:        the Directory tree.
        !           717: 
        !           718: \item  Everyone is allowed to read the entry and all of its attributes,
        !           719:        and only \verb"c=US@cn=Manager" is allowed to change anything.
        !           720: 
        !           721: \item  The \verb"treeStructure" attribute says that the children immediately
        !           722:        below this object:
        !           723:     \begin{itemize}
        !           724:      \item     may have children themselves (\verb"quipuNonLeafObject"),
        !           725:                in which case, the objects under \verb"c=US" are either
        !           726:                \verb"organization" or \verb"locality" objects; or,
        !           727: 
        !           728:      \item     needn't have children, being a DSA
        !           729:                (of object class \verb"quipuDSA")
        !           730:                or an \verb"organizationalRole";
        !           731:                or,
        !           732: 
        !           733:     \item      may be an \verb"alias".
        !           734:     \end{itemize}
        !           735: 
        !           736: \item  The official name of this country is \verb"US".
        !           737: 
        !           738: \item  This object belongs to five object classes:
        !           739:     \begin{itemize}
        !           740:     \item      \verb"top" and \verb"quipuObject" because membership is
        !           741:                mandatory;
        !           742: 
        !           743:     \item      \verb"quipuNonLeafObject" so that children may reside
        !           744:                under the entry;
        !           745: 
        !           746:     \item      \verb"friendlyCountry" which is the primary object class; and,
        !           747: 
        !           748:     \item      \verb"country" which is a superclass of \verb"friendlyCountry".
        !           749:     \end{itemize}
        !           750: \end{itemize}
        !           751: 
        !           752: \subsubsection {The organization objectClass}\index{object classes, organization}
        !           753: Objects of this class represent a top-level organizational entity,
        !           754: such as a corporation, university, government entity, and so on.
        !           755: There is an \verb"organization" object for each organization participating in
        !           756: the NYSERNet/PSI White Pages Pilot.
        !           757: 
        !           758: Table~\ref{organization-attributes} summarizes the attributes types for
        !           759: an \verb"organization" object.
        !           760: There is one mandatory attribute:
        !           761: \begin{describe}
        !           762: \item[organizationName:]\index{attribute types, organizationName}\index{attribute types, o (organizationName)}
        !           763:                        which gives the name of the organization.
        !           764:                        The value of this attribute is a string; e.g.,
        !           765: \begin{quote}\small\begin{verbatim}
        !           766: NYSERNet Inc.
        !           767: \end{verbatim}\end{quote}
        !           768: \end{describe}
        !           769: \tagtable[tp]{INT-3}{Attribute Types for the organization Object Class}%
        !           770:        {organization-attributes}
        !           771: 
        !           772: There are several attributes that may be present,
        !           773: which are divided into three groups:
        !           774: physical address, telecommunications address, and miscellaneous information.
        !           775: 
        !           776: The first group describes the physical address of the object:
        !           777: \begin{describe}
        !           778: \item[postalAddress:]\index{attribute types, postalAddress}
        !           779:                        which describes how physical mail is addressed to the
        !           780:                        object.
        !           781:                        The syntax of this attribute's value is special:
        !           782:                        it consists of~1 to~6 fields, seperated by the
        !           783:                        ``\verb"$"''-sign, each field being from~1 to~30
        !           784:                        characters long; e.g.
        !           785: \begin{quote}\small\begin{verbatim}
        !           786: NYSERNet Inc. $ 165 Jordan Road $ Troy, NY 12180
        !           787: \end{verbatim}\end{quote}
        !           788: 
        !           789: \item[registeredAddress:]\index{attribute types, registeredAddress}
        !           790:                        which defines how registered physical mail is
        !           791:                        addressed to the object.
        !           792:                        The syntax is identical to that of the
        !           793:                        \verb"postalAddress" attribute.
        !           794: 
        !           795: \item[streetAddress:]\index{attribute types, streetAddress}
        !           796:                        which is a string describing where the object
        !           797:                        physically resides
        !           798:                        (i.e., the street name, place, avenue, and building
        !           799:                        number); e.g.,
        !           800:                        object
        !           801: \begin{quote}\small\begin{verbatim}
        !           802: 165 Jordan Road
        !           803: \end{verbatim}\end{quote}
        !           804:                        This need have no relationship to the object's
        !           805:                        postal address.
        !           806: 
        !           807: \item[postOfficeBox:]\index{attribute types, postOfficeBox}
        !           808:                        which is a string describing the box at which the
        !           809:                        object will receive physical postal delivery; e.g.,
        !           810: \begin{quote}\small\begin{verbatim}
        !           811: 1010
        !           812: \end{verbatim}\end{quote}
        !           813: 
        !           814: \item[physicalDeliveryOfficeName:]\index{attribute types, physicalDeliveryOfficeName}
        !           815:                        which is a string describing the geographical location
        !           816:                        of the physical delivery office which services the
        !           817:                        postal address of this object; e.g.,
        !           818: \begin{quote}\small\begin{verbatim}
        !           819: Troy
        !           820: \end{verbatim}\end{quote}
        !           821: 
        !           822: \item[stateOrProvinceName:]\index{attribute types, stateOrProvinceName}
        !           823:                        which is a string describing the state in which
        !           824:                        the \verb"locality" is found; e.g.,
        !           825: \begin{quote}\small\begin{verbatim}
        !           826: New York
        !           827: \end{verbatim}\end{quote}
        !           828: 
        !           829: \item[postalCode:]\index{attribute types, postalCode}
        !           830:                        which is a string containing the ZIP code; e.g.,
        !           831: \begin{quote}\small\begin{verbatim}
        !           832: 12180
        !           833: \end{verbatim}\end{quote}
        !           834: or
        !           835: \begin{quote}\small\begin{verbatim}
        !           836: 94043-2112
        !           837: \end{verbatim}\end{quote}
        !           838: 
        !           839: \item[localityName:]\index{attribute types, localityName}\index{attribute types, l (localityName)}
        !           840:                        which is a string describing the geographical
        !           841:                        area containing the \verb"streetAddress"; e.g.,
        !           842: \begin{quote}\small\begin{verbatim}
        !           843: Troy, New York
        !           844: \end{verbatim}\end{quote}
        !           845: \end{describe}
        !           846: The second optional group describes telecommunications addressing information
        !           847: for the object.
        !           848: \begin{describe}
        !           849: \item[telephoneNumber:]\index{attribute types, telephoneNumber}
        !           850:                which is a string describing the phone number of the object
        !           851:                using the international notation; e.g.,
        !           852: \begin{quote}\small\begin{verbatim}
        !           853: +1 518-283-8860
        !           854: \end{verbatim}\end{quote}
        !           855: or
        !           856: \begin{quote}\small\begin{verbatim}
        !           857: +1 518-283-8860 x1234
        !           858: \end{verbatim}\end{quote}
        !           859: In general, the syntax is:
        !           860: \begin{quote}\smaller\begin{verbatim}
        !           861: +<<country code>> <<national number>> [x<<extension>>]
        !           862: \end{verbatim}\end{quote}
        !           863: 
        !           864: \item[facsimileTelephoneNumber:]\index{attribute types, facsimileTelephoneNumber}
        !           865:                which is a string describing the fax number of the object
        !           866:                using the international notation; e.g.,
        !           867: \begin{quote}\small\begin{verbatim}
        !           868: +1 518-283-8904
        !           869: \end{verbatim}\end{quote}
        !           870: 
        !           871: \item[telexNumber:]\index{attribute types, telexNumber}
        !           872:                which is defines the TELEX address of the object in a
        !           873:                three-field format:
        !           874: \begin{quote}\small\begin{verbatim}
        !           875: number $ country $ answerback
        !           876: \end{verbatim}\end{quote}
        !           877:                e.g.,
        !           878: \begin{quote}\small\begin{verbatim}
        !           879: 650 103 7390 $ US $ MCI UW
        !           880: \end{verbatim}\end{quote}
        !           881: \end{describe}
        !           882: The final optional group contains one miscellaneous attribute:
        !           883: \begin{describe}
        !           884: \item[description:]\index{attribute types, description}
        !           885:                        which is a simple textual description;
        !           886:                        e.g.,
        !           887: \begin{quote}\small\begin{verbatim}
        !           888: Not-for-profit organization providing network services
        !           889: \end{verbatim}\end{quote}
        !           890: \end{describe}
        !           891: Figure~\ref{organization-edb} shows an entry for an \verb"organization" object.
        !           892: \tagfigure[tp]{INT-2}{An Example of an Entry for the organization Object Class}%
        !           893:        {organization-edb}
        !           894: 
        !           895: \subsubsection {The organizationalUnit objectClass}\index{object classes, organizationalUnit}
        !           896: Objects of this class represent a unit within an organization,
        !           897: such as a division or department.
        !           898: Each organization participating in the NYSERNet/PSI White Pages Pilot decides
        !           899: how many organizational units it wishes to maintain as subordinates to
        !           900: its organization entry.
        !           901: 
        !           902: Table~\ref{organizationalUnit-attributes} summarizes the attributes types for
        !           903: an \verb"organizationalUnit" object.
        !           904: There is one mandatory attribute:
        !           905: \begin{describe}
        !           906: \item[organizationalUnitName:]\index{attribute types, organizationUnitName}\index{attribute types, ou (organizationUnitName)}
        !           907:                        which gives the name of the organizational unit.
        !           908:                        The value of this attribute is a string; e.g.,
        !           909: \begin{quote}\small\begin{verbatim}
        !           910: Research and Development
        !           911: \end{verbatim}\end{quote}
        !           912: \end{describe}
        !           913: \tagtable[tp]{INT-4}{Attribute Types for the organizationalUnit Object Class}%
        !           914:        {organizationalUnit-attributes}
        !           915: 
        !           916: There are several attributes that may be present.
        !           917: They belong to the physical address, telecommunications address,
        !           918: and miscellaneous information groups described earlier.
        !           919: 
        !           920: Figure~\ref{organizationalUnit-edb} shows an entry for an
        !           921: \verb"organizationalUnit" object.
        !           922: \tagfigure[tp]{INT-3}%
        !           923:        {An Example of an Entry for the organizationalUnit Object Class}%
        !           924:        {organizationalUnit-edb}
        !           925: 
        !           926: \subsubsection {The locality objectClass}\index{object classes, locality}
        !           927: Objects of this class represent a geographical area,
        !           928: such as a state, county, or city.
        !           929: The sponsors of the NYSERNet/PSI White Pages Pilot maintain such an entry for
        !           930: the State of New York.
        !           931: This is used to contain objects corresponding to individuals who are
        !           932: associated with organizations that are not participating in the pilot
        !           933: project.
        !           934: 
        !           935: Table~\ref{locality-attributes} summarizes the attributes types for
        !           936: a \verb"locality" object.
        !           937: There is one mandatory attribute:
        !           938: \begin{describe}
        !           939: \item[localityName:]\index{attribute types, localityName}\index{attribute types, l (localityName)}
        !           940:                        which gives the name of the locality.
        !           941:                        The value of this attribute is a string; e.g.,
        !           942: \begin{quote}\small\begin{verbatim}
        !           943: NY
        !           944: \end{verbatim}\end{quote}
        !           945: or
        !           946: \begin{quote}\small\begin{verbatim}
        !           947: Rensselaer County
        !           948: \end{verbatim}\end{quote}
        !           949: \end{describe}
        !           950: \tagtable[tp]{INT-5}{Attribute Types for the locality Object Class}%
        !           951:        {locality-attributes}
        !           952: 
        !           953: There is only one attribute that may be present,
        !           954: it  belongs to the miscellaneous information group described earlier.
        !           955: 
        !           956: Figure~\ref{sony-edb} shows the entry for the State of New York,
        !           957: whilst Figure~\ref{locality-edb} shows an entry for a subordinate
        !           958: \verb"locality" object.
        !           959: \tagfigure[tp]{INT-4}{The Entry for The State of New York}{sony-edb}
        !           960: \tagfigure[tp]{INT-5}{An Example of an Entry for the locality Object Class}%
        !           961:                {locality-edb}
        !           962: 
        !           963: \subsubsection {The pilotPerson objectClass}\index{object classes, pilotPerson}
        !           964: Objects of this class represent a person participating in the pilot project.
        !           965: 
        !           966: Table~\ref{pilotPerson-attributes} summarizes the attributes types for
        !           967: a \verb"pilotPerson" object.
        !           968: There are two mandatory attributes:
        !           969: \begin{describe}
        !           970: \item[commonName:]\index{attribute types, commonName}\index{attribute types, cn (commonName)}
        !           971:                        which gives a (potentially ambiguous) name for
        !           972:                        the person.
        !           973:                        The value of this attribute is a string usually
        !           974:                        containing the person's first and last names; e.g.,
        !           975: \begin{quote}\small\begin{verbatim}
        !           976: Marshall Rose
        !           977: \end{verbatim}\end{quote}
        !           978:                        This attribute is usually multi-valued, containing
        !           979:                        variations on the first, middle, and last names; e.g.,
        !           980: \begin{quote}\small\begin{verbatim}
        !           981: Colin Robbins
        !           982: Colin John Robbins
        !           983: Colin J. Robbins
        !           984: \end{verbatim}\end{quote}
        !           985:                        For purposes of the pilot project, the distinguished
        !           986:                        value of the attribute usually contains only the
        !           987:                        person's first and last names.
        !           988:                        (See Section~\ref{naming:people} on 
        !           989:                        page~\pageref{naming:people} for a discussion of this.)
        !           990: 
        !           991: \item[surName:]\index{attribute types, surName}
        !           992:                        which gives the person's last name.
        !           993:                        The value of this attribute is a string; e.g.,
        !           994: \begin{quote}\small\begin{verbatim}
        !           995: Rose
        !           996: \end{verbatim}\end{quote}
        !           997: \end{describe}
        !           998: \tagtable[tp]{INT-6}{Attribute Types for the pilotPerson Object Class}%
        !           999:        {pilotPerson-attributes}
        !          1000: 
        !          1001: There are several attributes that may be present,
        !          1002: which are divided into five groups:
        !          1003: physical address, telecommunication information, 
        !          1004: computer environment,
        !          1005: miscellaneous information,
        !          1006: and home information.
        !          1007: The first two groups have been previously described.
        !          1008: 
        !          1009: The third group describes information relating to the person's
        !          1010: computer environment:
        !          1011: \begin{describe}
        !          1012: \item[rfc822Mailbox:]\index{attribute types, rfc822Mailbox}
        !          1013:                        which is the user's computer mail address,
        !          1014:                        e.g., 
        !          1015: \begin{quote}\small\begin{verbatim}
        !          1016: [email protected]
        !          1017: \end{verbatim}\end{quote}
        !          1018: 
        !          1019: \item[otherMailbox:]\index{attribute types, otherMailbox}
        !          1020:                        which is the user's computer mail address
        !          1021:                        in various domains.
        !          1022:                        The syntax of this attribute's value is special:
        !          1023: \begin{quote}\small\begin{verbatim}
        !          1024: <domain> $ <mailbox>
        !          1025: \end{verbatim}\end{quote}
        !          1026:                        e.g., 
        !          1027: \begin{quote}\small\begin{verbatim}
        !          1028: internet $ [email protected]
        !          1029: \end{verbatim}\end{quote}
        !          1030: The current list of mail domains are:
        !          1031: \[\begin{tabular}{l}
        !          1032: applelink\\
        !          1033: bitnet\\
        !          1034: compuserve\\
        !          1035: genie\\
        !          1036: internet\\
        !          1037: mcimail\\
        !          1038: nasamail\\
        !          1039: preferred\\
        !          1040: uucp
        !          1041: \end{tabular}\]
        !          1042: 
        !          1043: \item[userid:]\index{attribute types, userid}
        !          1044:                        which is the user's login name; e.g.,
        !          1045: \begin{quote}\small\begin{verbatim}
        !          1046: mrose
        !          1047: \end{verbatim}\end{quote}
        !          1048: 
        !          1049: \item[userClass:]\index{attribute types, userClass}
        !          1050:                        which describe's the user's classification; e.g.,
        !          1051: \begin{quote}\small\begin{verbatim}
        !          1052: staff
        !          1053: \end{verbatim}\end{quote}
        !          1054: \end{describe}
        !          1055: The next optional group contains a few miscellaneous attributes:
        !          1056: \begin{describe}
        !          1057: \item[description:]\index{attribute types, description}
        !          1058:                        which is a simple textual description;
        !          1059:                        e.g.,
        !          1060: \begin{quote}\small\begin{verbatim}
        !          1061: Principal Implementor of the ISO Development Environment
        !          1062: \end{verbatim}\end{quote}
        !          1063: 
        !          1064: \item[info:]\index{attribute types, info}
        !          1065:                        which is additional information about the object;
        !          1066:                        e.g.,
        !          1067: \begin{quote}\small\begin{verbatim}
        !          1068: It's nearly as good as BIND
        !          1069: \end{verbatim}\end{quote}
        !          1070: 
        !          1071: \item[businessCategory:]\index{attribute types, businessCategory}
        !          1072:                        which describes the person's business,
        !          1073:                        e.g.,
        !          1074: \begin{quote}\small\begin{verbatim}
        !          1075: networking
        !          1076: \end{verbatim}\end{quote}
        !          1077: 
        !          1078: \item[title:]\index{attribute types, title}
        !          1079:                        which is the person's job title,
        !          1080:                        e.g.,
        !          1081: \begin{quote}\small\begin{verbatim}
        !          1082: Senior Scientist
        !          1083: \end{verbatim}\end{quote}
        !          1084: 
        !          1085: \item[roomNumber:]\index{attribute types, roomNumber}
        !          1086:                        which is a string describing where the object resides
        !          1087:                        at the location, e.g.,
        !          1088: \begin{quote}\small\begin{verbatim}
        !          1089: Building T-30
        !          1090: \end{verbatim}\end{quote}
        !          1091: 
        !          1092: \item[userPassword:]\index{attribute types, userPassword}
        !          1093:                        which is a string containing the object's
        !          1094:                        password in the Directory.  This is used,
        !          1095:                        for example, when the user wants to update
        !          1096:                        the entry.
        !          1097:                        The password is kept in the clear
        !          1098:                        (the security ramifications of this are
        !          1099:                        discussed later on); e.g.,
        !          1100: \begin{quote}\small\begin{verbatim}
        !          1101: secret
        !          1102: \end{verbatim}\end{quote}
        !          1103: 
        !          1104: \item[mobileTelephoneNumber:]\index{attribute types, mobileTelephoneNumber}\index{attribute types, mobile (mobileTelephoneNumber)}
        !          1105:                        which is a string describing the user's mobile
        !          1106:                        number (e.g., for a cellular phone).
        !          1107: 
        !          1108: \item[pagerTelephoneNumber:]\index{attribute types, pagerTelephoneNumber}\index{attribute types, pager (pagerTelephoneNumber)}
        !          1109:                        which is a string describing the user's pager number.
        !          1110: 
        !          1111: \item[favouriteDrink:]\index{attribute types, favouriteDrink}\index{attribute types, drink (favouriteDrink)}
        !          1112:                        which is a string describing the user's favorite drink.
        !          1113: 
        !          1114: \item[secretary:]\index{attribute types, secretary}
        !          1115:                        which is the Distinguished Name of the user's
        !          1116:                        secretary.
        !          1117: 
        !          1118: \item[seeAlso:]\index{attribute types, seeAlso}
        !          1119:                        which is a Distinguished Name pointing to another
        !          1120:                        entry related to the user (perhaps in a different
        !          1121:                        role).
        !          1122: 
        !          1123: \item[photo:]\index{attribute types, photo}
        !          1124:                        which is a facsimile bitmap of the user's face.
        !          1125: \end{describe}
        !          1126: The final optional group contains a few attributes about the person at home:
        !          1127: \begin{describe}
        !          1128: \item[homePostalAddress:]\index{attribute types, homePostalAddress}
        !          1129:                        which describes how physical mail is addressed to the
        !          1130:                        person's home.
        !          1131:                        The syntax of this attribute's value is special:
        !          1132:                        it consists of~1 to~6 fields, seperated by the
        !          1133:                        ``\verb"$"''-sign, each field being from~1 to~30
        !          1134:                        characters long; e.g.
        !          1135: \begin{quote}\small\begin{verbatim}
        !          1136: NYSERNet Inc. $ 165 Jordan Road $ Troy, NY 12180
        !          1137: \end{verbatim}\end{quote}
        !          1138: 
        !          1139: \item[homePhone:]\index{attribute types, homePhone}
        !          1140:                which is a string describing the phone number of the object
        !          1141:                using the international notation; e.g.,
        !          1142: \begin{quote}\small\begin{verbatim}
        !          1143: +1 518-283-8860
        !          1144: \end{verbatim}\end{quote}
        !          1145: \end{describe}
        !          1146: Figure~\ref{pilotPerson-edb} shows an entry for a \verb"pilotPerson" object.
        !          1147: \tagfigure[tp]{INT-6}{An Example of an Entry for the pilotPerson Object Class}%
        !          1148:        {pilotPerson-edb}
        !          1149: 
        !          1150: \subsubsection {The alias objectClass}\index{object classes, alias}
        !          1151: Objects of this class represent an alias to some other entry in the
        !          1152: NYSERNet/PSI White Pages Pilot.
        !          1153: Each organization participating in the pilot must define at least two of
        !          1154: these:
        !          1155: \begin{itemize}
        !          1156: \item  a manager responsible for the organization's portion of the Directory
        !          1157:        tree;
        !          1158:        and,
        !          1159: 
        !          1160: \item  a postmaster responsible for the organization's electronic mail.
        !          1161: \end{itemize}
        !          1162: 
        !          1163: Table~\ref{alias-attributes} summarizes the attributes types for
        !          1164: an \verb"alias".
        !          1165: There are two mandatory attributes:
        !          1166: \begin{describe}
        !          1167: \item[commonName:]\index{attribute types, commonName}\index{attribute types, cn (commonName)}
        !          1168:                        which gives the name of the alias.
        !          1169:                        The value of this attribute is a string; e.g.,
        !          1170: \begin{quote}\small\begin{verbatim}
        !          1171: PostMaster
        !          1172: \end{verbatim}\end{quote}
        !          1173: 
        !          1174: \item[aliasedObjectName:]\index{attribute types, aliasedObjectName}
        !          1175:                        which is a pointer to another object in the Directory;
        !          1176:                        e.g.,
        !          1177: \begin{quote}\small\begin{verbatim}
        !          1178: c=US@o=NYSERNet Inc.@ou=Operations@cn=Chris Kolb
        !          1179: \end{verbatim}\end{quote}
        !          1180: \[\fbox{\begin{tabular}{lp{0.4\textwidth}}
        !          1181: \bf NOTE:&     The value of this attribute must not be another alias:
        !          1182:                each alias must point to a non-aliased entry!
        !          1183: \end{tabular}}\]
        !          1184: \end{describe}
        !          1185: There are no optional attributes for this object class.
        !          1186: Figure~\ref{alias-edb} shows an entry for an \verb"alias" object.
        !          1187: \tagtable[tp]{INT-7}{Attribute Types for the alias Object Class}%
        !          1188:        {alias-attributes}
        !          1189: \tagfigure[tp]{INT-7}{An Example of an Entry for the alias Object Class}%
        !          1190:        {alias-edb}
        !          1191: 
        !          1192: \subsubsection {The organizationalRole objectClass}\index{object classes, organizationalRole}
        !          1193: Objects of this class represent a position filled by a person.
        !          1194: 
        !          1195: Table~\ref{organizationalRole-attributes} summarizes the attributes types for
        !          1196: a \verb"organizationalRole".
        !          1197: There is one mandatory attribute:
        !          1198: \begin{describe}
        !          1199: \item[commonName:]\index{attribute types, commonName}\index{attribute types, cn (commonName)}
        !          1200:                        which gives the name of the role.
        !          1201:                        The value of this attribute is a string; e.g.,
        !          1202: \begin{quote}\small\begin{verbatim}
        !          1203: Manager
        !          1204: \end{verbatim}\end{quote}
        !          1205: \end{describe}
        !          1206: There are several attributes that may be present,
        !          1207: which are divided into three groups:
        !          1208: physical address, telecommunication information, 
        !          1209: and miscellaneous information.
        !          1210: The first two groups have been previously described.
        !          1211: The final optional group contains two miscellaneous attributes:
        !          1212: \begin{describe}
        !          1213: \item[description:]\index{attribute types, description}
        !          1214:                        which is a simple textual description;
        !          1215:                        e.g.,
        !          1216: \begin{quote}\small\begin{verbatim}
        !          1217: Manager of the Troy Office
        !          1218: \end{verbatim}\end{quote}
        !          1219: 
        !          1220: \item[roleOccupant:]\index{attribute types, roleOccupant}
        !          1221:                        which is a pointer to another object in the Directory,
        !          1222:                        referring to the person who currently fills the role.
        !          1223:                        e.g.,
        !          1224: \begin{quote}\small\begin{verbatim}
        !          1225: c=US@o=NYSERNet Inc.@ou=Administration@cn=Kimberly Brown
        !          1226: \end{verbatim}\end{quote}
        !          1227: \end{describe}
        !          1228: Figure~\ref{organizationalRole-edb} shows an entry for a \verb"organizationalRole"
        !          1229: object.
        !          1230: \tagtable[tp]{INT-9}{Attribute Types for the organizationalRole Object Class}%
        !          1231:        {organizationalRole-attributes}
        !          1232: \tagfigure[tp]{INT-14}%
        !          1233:        {An Example of an Entry for the organizationalRole Object Class}%
        !          1234:        {organizationalRole-edb}
        !          1235: 
        !          1236: \subsubsection {The quipuDSA objectClass}\index{object classes, quipuDSA}
        !          1237: Objects of this class represent a Directory System Agent (DSA) running 
        !          1238: the pilot project software.
        !          1239: Each organization participating in the NYSERNet/PSI White Pages Pilot typically
        !          1240: runs at least one DSA.
        !          1241: 
        !          1242: Table~\ref{quipuDSA-attributes} summarizes the attributes types for
        !          1243: a \verb"quipuDSA".
        !          1244: There are several mandatory attributes:
        !          1245: \begin{describe}
        !          1246: \item[commonName:]\index{attribute types, commonName}\index{attribute types, cn (commonName)}
        !          1247:                        which gives the name of the DSA,
        !          1248:                        by convention this is the name of an endangered species
        !          1249:                        in South America; e.g.,
        !          1250: \begin{quote}\small\begin{verbatim}
        !          1251: Fruit Bat
        !          1252: \end{verbatim}\end{quote}
        !          1253: 
        !          1254: \item[eDBinfo:]\index{attribute types, eDBinfo}
        !          1255:                        which indicates how the DSA participates when
        !          1256:                        propagating authoritative EDB information
        !          1257:                        (this is the dual
        !          1258:                        of the \verb"masterDSA" and \verb"slaveDSA"
        !          1259:                        attribute types discussed earlier).
        !          1260:                        The syntax of this attribute's value is special:
        !          1261: \begin{quote}\small\begin{verbatim}
        !          1262: <name> # <upstream> # <downstream>
        !          1263: \end{verbatim}\end{quote}
        !          1264: The \verb"<name>" field is a Distinguished Name referring to the object
        !          1265: containing the EDB.
        !          1266: By convention, if absent this refers to the ROOT (unnamed) EDB.
        !          1267: The \verb"<upstream>" field is the Distinguished Name of a DSA which is
        !          1268: considered to be ``closer'' to the MASTER of this EDB.
        !          1269: It may be the name of the actual DSA containing the MASTER EDB,
        !          1270: but it might also be the name of an intermediate DSA (containing a SLAVE copy).
        !          1271: If this field is empty,
        !          1272: then this DSA does not pull the EDB from another DSA
        !          1273: (this needn't mean that it holds the MASTER EDB,
        !          1274: though usually this is the case).
        !          1275: The \verb"<downstream>" field is the Distinguished Name of a DSA which is
        !          1276: allowed to copy the EDB from this DSA.
        !          1277: If this field is empty,
        !          1278: then this DSA does not allow other DSAs to copy the EDB.
        !          1279: If the \verb"<downstream>" field is to contain more than one DSA,
        !          1280: either enter multiple \verb"eDBinfo" lines or separate the Distinguished
        !          1281: Names of the downstream DSAs with the \verb"`$'"-sign.
        !          1282: 
        !          1283: A few examples:
        !          1284: \begin{quote}\small\begin{verbatim}
        !          1285: # cn=Giant Tortoise # cn=Fruit Bat
        !          1286: c=US # # cn=Fruit Bat
        !          1287: c=US # # c=US@cn=Spectacled Bear
        !          1288: c=US@l=NY # cn=Fruit Bat #
        !          1289: \end{verbatim}\end{quote}
        !          1290: Note that there is no harm to using multiple \verb"eDBinfo" lines,
        !          1291: even if they refer to the same EDB.
        !          1292: These lines indicate that:
        !          1293: \begin{itemize}
        !          1294: \item  The ROOT EDB is read from the \verb"cn=Giant Tortoise" DSA,
        !          1295:        further the \verb"cn=Fruit Bat" DSA is allowed to read the
        !          1296:        ROOT EDB from this DSA.
        !          1297: 
        !          1298: \item  The \verb"cn=Fruit Bat" DSA and the \verb"c=US@cn=Spectacled Bear" DSA
        !          1299:        are allowed to read the EDB for \verb"c=US". 
        !          1300:        Note that the second and third line could be combined as:
        !          1301: \begin{quote}\small\begin{verbatim}
        !          1302: c=US # # cn=Fruit Bat$c=US@cn=Spectacled Bear
        !          1303: \end{verbatim}\end{quote}
        !          1304: While more concise,
        !          1305: this format is not recommended as it is probably more difficult to read.
        !          1306: 
        !          1307: \item  The DSA named \verb"cn=Fruit Bat" supplies the EDB for \verb"c=US@l=NY"
        !          1308:        to this DSA.
        !          1309: \end{itemize}
        !          1310: 
        !          1311: \item[presentationAddress:]\index{attribute types, presentationAddress}
        !          1312:                        which is the OSI presentation address that the DSA
        !          1313:                        resides at.
        !          1314:                        The syntax of this attribute's value is special:
        !          1315: \begin{quote}\small\begin{verbatim}
        !          1316: '0101'H/Internet=<quad>+<port>
        !          1317: \end{verbatim}\end{quote}
        !          1318: or
        !          1319: \begin{quote}\small\begin{verbatim}
        !          1320: '0101'H/Internet=<quad-1>+<port>|Internet=<quad-2>+<port>
        !          1321: \end{verbatim}\end{quote}
        !          1322: if the DSA is capable of listing on multiple IP addresses.%
        !          1323: \footnote{Actually, the rules for forming OSI presentation addresses are
        !          1324: {\em much\/} more complicated;
        !          1325: however, for the purposes of the pilot project,
        !          1326: this should suffice.}
        !          1327: The \verb"<quad>" field is a 32-bit IP address expressed in the
        !          1328: usual quad notation (e.g., \verb"130.117.128.2").
        !          1329: The \verb"<port>" field is a decimal TCP port which isn't likely to
        !          1330: be used on your system.
        !          1331: The value \verb"17003" is recommended for the purposes of the pilot project.
        !          1332: 
        !          1333: A simple example:
        !          1334: \begin{quote}\small\begin{verbatim}
        !          1335: '0101'H/Internet=130.117.128.2+17003
        !          1336: \end{verbatim}\end{quote}
        !          1337: Note that multiple values for the \verb"presentationAddress" attribute type
        !          1338: should not be used:
        !          1339: multiple IP addresses (up to~4) can be specified using a single attribute value.
        !          1340: 
        !          1341: \item[manager:]\index{attribute types, manager}
        !          1342:                        which is a pointer to another object in the Directory
        !          1343:                        of the person who manages this DSA;
        !          1344:                        e.g.,
        !          1345: \begin{quote}\small\begin{verbatim}
        !          1346: c=US@o=NYSERNet Inc.@cn=Manager
        !          1347: \end{verbatim}\end{quote}
        !          1348: 
        !          1349: \item[userPassword:]\index{attribute types, userPassword}
        !          1350:                        which is a string containing the DSA's
        !          1351:                        password in the Directory.  This is used
        !          1352:                        when the manager of the DSA wants to
        !          1353:                        change the entry for the DSA itself
        !          1354:                        (as opposed to the entries held by the DSA).
        !          1355:                        The password is kept in the clear
        !          1356:                        (the security ramifications of this are
        !          1357:                        discussed later on); e.g.,
        !          1358: \begin{quote}\small\begin{verbatim}
        !          1359: secret
        !          1360: \end{verbatim}\end{quote}
        !          1361: 
        !          1362: \item[quipuVersion:]\index{attribute types, quipuVersion}
        !          1363:                        which is a simple string relating the version of
        !          1364:                        the pilot project software being run by this DSA;
        !          1365:                        e.g.,
        !          1366: \begin{quote}\small\begin{verbatim}
        !          1367: Version 5.0
        !          1368: \end{verbatim}\end{quote}
        !          1369: \end{describe}
        !          1370: There are two optional attributes:
        !          1371: \begin{describe}
        !          1372: \item[description:]\index{attribute types, description}
        !          1373:                        which, by convention, is multi-valued.
        !          1374:                        The distinguished value is the wildlife description
        !          1375:                        of the \verb"commonName" attribute whilst the other
        !          1376:                        values describe the role that the DSA plays in
        !          1377:                        the pilot project;
        !          1378:                        e.g.,
        !          1379: \begin{quote}\small\begin{verbatim}
        !          1380: The Mischevous Varmint
        !          1381: A MASTER DSA for l=NY under c=US
        !          1382: A SLAVE DSA for ROOT and c=US
        !          1383: \end{verbatim}\end{quote}
        !          1384: 
        !          1385: \item[supportedApplicationContext:]\index{attribute types, supportedApplicationContext}
        !          1386:                        which defines the application ports offerred by this
        !          1387: process.
        !          1388:                        The current values are:
        !          1389: \begin{quote}\small\begin{verbatim}
        !          1390: x500DSP & x500DAP & quipuDSP
        !          1391: \end{verbatim}\end{quote}
        !          1392: \end{describe}
        !          1393: Figure~\ref{quipuDSA-edb} shows an entry for a \verb"quipuDSA" object.
        !          1394: \tagtable[tp]{INT-8}{Attribute Types for the quipuDSA Object Class}%
        !          1395:        {quipuDSA-attributes}
        !          1396: \tagfigure[tp]{INT-8}{An Example of an Entry for the quipuDSA Object Class}%
        !          1397:        {quipuDSA-edb}
        !          1398: 
        !          1399: \section      {Functional Model}
        !          1400: The Functional Model describes the service in terms of entities.
        !          1401: As noted earlier,
        !          1402: two kinds of entities exist:
        !          1403: {\em Directory User Agents\/} (DUAs),
        !          1404: which operate on behalf of a user,
        !          1405: and
        !          1406: {\em Directory System Agents\/} (DSAs),
        !          1407: which provide the service.
        !          1408: 
        !          1409: The key aspect of the functional model is deciding how information
        !          1410: is transferred through the system.
        !          1411: When a DUA requests some action from a DSA
        !          1412: (e.g., to read an entry),
        !          1413: the DSA may not have that information resident.
        !          1414: In this case,
        !          1415: the DSA has a choice:
        !          1416: it may either contact another DSA which is ``closer'' to the information
        !          1417: and propagate the request (this is called {\em chaining\/}),
        !          1418: or it may return information about this ``closer'' DSA to the DUA,
        !          1419: and let the DUA re-issue its request
        !          1420: (this is called {\em referral\/}).
        !          1421: WHen DSAs communicate between themselves,
        !          1422: they may also chain or refer requests.
        !          1423: 
        !          1424: For the purposes of the pilot,
        !          1425: it is important to understand what the term ``resident'' means with respect
        !          1426: to information.
        !          1427: This residency requirement is:
        !          1428: \[\begin{tabular}{|l|l|}
        !          1429: \hline
        !          1430: \multicolumn{1}{|c|}{\bf Operation Requested}&
        !          1431:                \multicolumn{1}{|c|}{\bf EDB Required for Residency}\\
        !          1432: \hline
        !          1433: read, compare& MASTER, SLAVE, or CACHE\\
        !          1434: list, search&  MASTER, or SLAVE\\
        !          1435: update&                MASTER\\
        !          1436: \hline
        !          1437: \end{tabular}\]
        !          1438: Note that after an update occurs,
        !          1439: the DSA actually performing the update (the one holding the MASTER EDB)
        !          1440: will write the in-core EDB structure to disk prior to returning the result
        !          1441: of the operation.
        !          1442: Of course,
        !          1443: once a MASTER DSA updates its copy of the EDB,
        !          1444: there is still the question of how DSAs with SLAVE copies receive this
        !          1445: new information.
        !          1446: The MASTER DSA does not explicitly inform them.
        !          1447: A polling model is used instead.
        !          1448: 
        !          1449: 
        !          1450: At present,
        !          1451: a SLAVE DSA will reload its copy of an EDB when it starts,
        !          1452: or when its \verb"manager" issues a management command directing it to do so.
        !          1453: Later on,
        !          1454: a script will be discussed which performs this task.
        !          1455: The frequency at which the script runs (or how often a DSA reboots)
        !          1456: determines how out of date a SLAVE copy of an EDB can become.
        !          1457: 
        !          1458: Prior to requesting a copy of an EDB,
        !          1459: a DSA checks to see if the timestamp has changed.
        !          1460: If so,
        !          1461: the EDB is updated.
        !          1462: As noted earlier,
        !          1463: the timestamp is the second line of an EDB file.
        !          1464: Whenever a modification is made to an entry in an EDB file,
        !          1465: the MASTER DSA for that EDB will update the timestamp accordingly.
        !          1466: Similarly,
        !          1467: whenever a text editor is used to modify an EDB file,
        !          1468: the user should update the timestamp.
        !          1469: The actual value is unimportant:
        !          1470: when a DSA examines the timestamp,
        !          1471: it looks only for a change;
        !          1472: it does not consider whether the EDB is newer or older.
        !          1473: 
        !          1474: Thus, while replication in the pilot is important to speed queries,
        !          1475: updates still rely on a centralized entity being available.
        !          1476: (This is the best compromise which can be taken without making the system
        !          1477: tremendously more complex.)
        !          1478: 
        !          1479: \section      {Organizational Model}
        !          1480: The Organizational Model describes the service in terms of the policy
        !          1481: defining interactions between entities and the information they hold.
        !          1482: That is,
        !          1483: this model describes how portions of the Directory tree map onto the DSAs.
        !          1484: This includes issues of replication and access control.
        !          1485: A {\em Directory Management Domain\/} (DMD) defines a portion of the
        !          1486: Directory Tree and how it is managed.
        !          1487: 
        !          1488: For the purposes of the pilot project,
        !          1489: DSAs are divided into three categories:
        !          1490: \begin{describe}
        !          1491: \item[Level-0:]        These DSAs are run by the sponsors of the NYSERNet/PSI White
        !          1492:                Pages Pilot.  Their goal is to be highly-available
        !          1493:                authoritative servers.
        !          1494: 
        !          1495: \item[Level-1:]        Each organization participating in the pilot project runs
        !          1496:                a Level-1 DSA.%
        !          1497: \footnote{The pilot project sponsors may run the Level-1 DSA on behalf of an
        !          1498: organization so requested.
        !          1499: This is discouraged, but may be necessary for resource constrained sites.}
        !          1500: The Level-1 DSA for a participating organization holds authoritative
        !          1501: information about that organization object.
        !          1502: 
        !          1503: \item[Level-2:]        As the size of the organization's subtree requires,
        !          1504: an organization runs one or more Level-2 DSA to hold a portion of that subtree.
        !          1505: Typically,
        !          1506: a Level-2 DSA is run for each top-level organizational unit in the
        !          1507: participating organization.
        !          1508: \end{describe}
        !          1509: Figure~\ref{dmd-topology} shows the top-level topology of the pilot project DMD.
        !          1510: Each participating organization is represented by an \verb"organization"
        !          1511: object ($O_1$ through $O_n$) under the \verb"c=US" tree.
        !          1512: Underneath each \verb"c=US@o=O_i" object,
        !          1513: one or more objects of class \verb"organizationalUnit" are placed.
        !          1514: The structure beneath each \verb"c=US@o=O_i@ou=U_j" object
        !          1515: is decided by the participating organization.
        !          1516: The pilot project sponsors suggest that only \verb"pilotPerson" objects
        !          1517: be placed underneath the organizational units.
        !          1518: \tagfigure[tp]{INT-9}{Topology of the Pilot Project Directory Management Domain}%
        !          1519:        {dmd-topology}
        !          1520: 
        !          1521: Now that the general structure is outlined,
        !          1522: how does this portion of the Directory tree map onto DSAs?
        !          1523: 
        !          1524: \subsection    {Level-0 DSAs}
        !          1525: There are two Level-0 DSAs.
        !          1526: Both reside directly under the ROOT.
        !          1527: 
        !          1528: The first Level-0 DSA, \verb"cn=Alpaca",
        !          1529: contains a copy of the ROOT EDB which it obtains directly from the
        !          1530: DSA holding the MASTER copy of the ROOT EDB.
        !          1531: In addition,
        !          1532: \verb"cn=Alpaca" is a MASTER DSA for \verb"c=US".
        !          1533: It propagates this EDB to the second Level-0 DSA,
        !          1534: and to the Level-1 DSAs of all participating organizations
        !          1535: (e.g., each DSA holding the MASTER of the \verb"c=US@o=O_i" EDB).
        !          1536: In addition,
        !          1537: these Level-1 DSAs propagate a copy of their EDB for \verb"c=US@o=O_i"
        !          1538: to this Level-0 DSA.
        !          1539: Finally,
        !          1540: this DSA receives a copy of the EDB for \verb"c=US@l=NY".
        !          1541: 
        !          1542: Figure~\ref{alpaca-edb} shows the entry corresponding to this DSA.
        !          1543: A single participating organization is shown in this entry.
        !          1544: \tagfigure[tp]{INT-10}{The Entry for the Level-0 DSA, cn=Alpaca}{alpaca-edb}
        !          1545: 
        !          1546: The second Level-0 DSA, \verb"cn=Fruit Bat",
        !          1547: contains a copy of the ROOT and \verb"c=US" EDBs which it obtains from
        !          1548: \verb"cn=Alpaca".
        !          1549: It may propagate these EDBs to any Level-1 DSA
        !          1550: (in case \verb"cn=Alpaca" is unavailable for an extended period of time).
        !          1551: In addition,
        !          1552: these Level-1 DSAs
        !          1553: propagate a copy of their MASTER EDB to this Level-0 DSA.
        !          1554: Finally,
        !          1555: \verb"cn=Fruit Bat" is a MASTER DSA for \verb"c=US@l=NY",
        !          1556: which it propagates to \verb"cn=Alpaca".
        !          1557: 
        !          1558: Figure~\ref{fruitbat-edb} shows the entry corresponding to this DSA.
        !          1559: As with the \verb"cn=Alpaca" DSA,
        !          1560: a single participating organization is shown.
        !          1561: \tagfigure[tp]{INT-11}{The Entry for the Level-0 DSA, cn=Fruit Bat}%
        !          1562:        {fruitbat-edb}
        !          1563: 
        !          1564: Level-0 DSAs perform chaining when handling requests from other DSAs.
        !          1565: 
        !          1566: \subsection    {Level-1 DSAs}
        !          1567: Each participating organization runs a DSA which contains the MASTER EDB
        !          1568: for that organization.
        !          1569: This DSA resides directly under \verb"c=US".
        !          1570: 
        !          1571: This DSA receives a copy of the ROOT and \verb"c=US" EDBs from
        !          1572: one of the Level-0 DSAs (usually \verb"cn=Alpaca").
        !          1573: It also propagates its MASTER copy of the \verb"c=US@o=O_i" EDB to
        !          1574: both Level-0 DSAs.
        !          1575: 
        !          1576: In addition,
        !          1577: this DSA propagates its EDB and a copy of the ROOT and \verb"c=US" EDBs
        !          1578: to all Level-2 DSAs run by this organization.
        !          1579: Similarly,
        !          1580: each of these Level-2 DSAs propagate {\em all\/} of the EDBs they
        !          1581: MASTER (e.g., \verb"c=US@o=O_i@ou=U_j") to this Level-1 DSA.
        !          1582: 
        !          1583: Level-1 DSAs perform chaining when handling requests from other DSAs.
        !          1584: 
        !          1585: Figure~\ref{spectacledbear-edb} shows the entry corresponding to a Level-1 DSA,
        !          1586: which might be named \verb"c=US@cn=Spectacled Bear".
        !          1587: A single subordinate Level-2 DSA is shown in this entry.
        !          1588: \tagfigure[tp]{INT-12}{The Entry for a Level-1 DSA}{spectacledbear-edb}
        !          1589: 
        !          1590: \subsection    {Level-2 DSAs}
        !          1591: Each participating organization runs zero or more Level-2 DSAs as the size of
        !          1592: their organizational units require.
        !          1593: These DSAs reside directly under \verb"c=US@o=O_i".
        !          1594: 
        !          1595: \[\fbox{\begin{tabular}{lp{0.8\textwidth}}
        !          1596: \bf NOTE:&     At present, the pilot sponsors discourage the use of Level-2
        !          1597:                DSAs.
        !          1598: 
        !          1599:                Nevertheless,
        !          1600:                it is important to structure an organization so that it 
        !          1601:                contains organizational units.
        !          1602:                In this fashion,
        !          1603:                when a Level-1 DSA is too large to run on an available system,
        !          1604:                a Level-2 DSA can be used to reduce the memory requirements
        !          1605:                on the system running the Level-1 DSA.
        !          1606: \end{tabular}}\]
        !          1607: 
        !          1608: Level-2 DSAs receive a copy of the \verb"c=US@o=O_i" EDB from their
        !          1609: superior Level-1 DSA,
        !          1610: along with SLAVE copies of the ROOT and \verb"c=US" EDBs.
        !          1611: They also propagate all MASTER copies of the EDBs they hold to this Level-1
        !          1612: DSA. 
        !          1613: 
        !          1614: Level-1 DSAs perform referrals when handling requests from other DSAs.
        !          1615: 
        !          1616: Figure~\ref{toucan-edb} shows the entry corresponding to a Level-2 DSA,
        !          1617: which might be named \verb"c=US@o=NYSERNet Inc.@cn=Toucan".
        !          1618: \tagfigure[tp]{INT-13}{The Entry for a Level-2 DSA}{toucan-edb}
        !          1619: 
        !          1620: \subsection    {DUAs}
        !          1621: In terms of the pilot project,
        !          1622: DUAs conceptually exist at the same level as Level-2 DSAs.
        !          1623: When a DUA associates with a DSA to access the Directory service,
        !          1624: chaining is preferred over referrals,
        !          1625: so that the associated DSA may cache the results to any query made by the DUA.
        !          1626: This will slightly enhance the performance for other DUAs which later
        !          1627: associate with this particular DSA.
        !          1628: 
        !          1629: The preference to be used when associating with a DSA is:
        !          1630: \begin{itemize}
        !          1631: \item  ``closest'' Level-2 DSA; followed by
        !          1632: 
        !          1633: \item  Level-1 DSA; followed by
        !          1634: 
        !          1635: \item  \verb"cn=Fruit Bat"; followed by
        !          1636: 
        !          1637: \item  \verb"cn=Alpaca".
        !          1638: \end{itemize}
        !          1639: 
        !          1640: \section      {Security Model}
        !          1641: The Security Model describes the service in terms of authentication
        !          1642: and authorization.
        !          1643: For the purposes of the pilot project,
        !          1644: ``simple'' authentication is performed (i.e., passwords).
        !          1645: The pilot project supports an anonymous DN, termed the NULL DN,
        !          1646: which may be used for public, read-only access.
        !          1647: Otherwise,
        !          1648: users are required to bind to the Distinguished Name which corresponds
        !          1649: to them.
        !          1650: 
        !          1651: Note that an important feature of the DMD topology presented in the
        !          1652: Organizational Model is that information on users
        !          1653: (and hence their passwords and any other sensitive information)
        !          1654: is kept only on Level-1 and Level-2 DSAs.
        !          1655: Since,
        !          1656: in general,
        !          1657: these DSAs are run by each participating organization,
        !          1658: each organization may safeguard the disk-resident EDB files accordingly.
        !          1659: 
        !          1660: Because the ROOT, \verb"c=US", and \verb"c=US@o=O_i" EDBs are widely
        !          1661: replicated,
        !          1662: entries contained therein should not rely on \verb"self" access control
        !          1663: for modification.
        !          1664: That is,
        !          1665: the entries contained in this EDBs should:
        !          1666: \begin{itemize}
        !          1667: \item  if of object class \verb"quipuDSA", have a \verb"manager"
        !          1668:        attribute which resolves to an entry which is not propagated outside
        !          1669:        of the associated organization; e.g.,
        !          1670: \begin{quote}\small\begin{verbatim}
        !          1671: manager= c=US@o=O_i@cn=Manager
        !          1672: \end{verbatim}\end{quote}
        !          1673: which is an object of classe \verb"alias" to
        !          1674: \begin{quote}\small\begin{verbatim}
        !          1675: c=US@o=O_i@ou=Development@cn=FirstName LastName
        !          1676: \end{verbatim}\end{quote}
        !          1677:        and,
        !          1678: 
        !          1679: \item  regardless of the object class,
        !          1680:        always use \verb"group" access to specify an entry which is not
        !          1681:        propagated outside of the associated organization; e.g.,
        !          1682: \begin{quote}\scriptsize\begin{verbatim}
        !          1683: acl= others # read # entry
        !          1684: acl= group # c=US@o=O_i@cn=Manager # write # entry
        !          1685: acl= others # read # default
        !          1686: acl= group # c=US@o=O_i@cn=Manager # write # default
        !          1687: acl= others # compare # attributes # accessControlList$userPassword
        !          1688: acl= group # c=US@o=O_i@cn=Manager # write # attributes # accessControlList$userPassword
        !          1689: \end{verbatim}\end{quote}
        !          1690: \end{itemize}
        !          1691: Note that the object associated with the \verb"manager" attribute of a DSA
        !          1692: is effectively the ``super user'' for all EDBs which that DSA MASTERs.
        !          1693: As such,
        !          1694: the \verb"userPassword" associated with the corresponding object should be 
        !          1695: protected to the greatest extent practical.
        !          1696: 
        !          1697: Since there is no hope of protecting the passwords for a DSA or any object
        !          1698: residing in the ROOT, \verb"c=US", and possibly \verb"c=US@o=O_i" EDBs,
        !          1699: this policy effectively revokes any privileges assocated with the passwords of
        !          1700: the entries contained in these EDBs.
        !          1701: 
        !          1702: \section      {Running your DMD}
        !          1703: The pilot sponsors prefer that you administer your own DMD by running the
        !          1704: pilot software on one of your own systems,
        !          1705: doing maintenance,
        !          1706: and so on.
        !          1707: You should now continue with Chapter~\ref{installation}.
        !          1708: 
        !          1709: However,
        !          1710: if your site is a member of NYSERNet, Inc.,
        !          1711: then the pilot sponsors will administer the DMD for you,
        !          1712: if you lack the facilities to do so.
        !          1713: In this case,
        !          1714: you will be required to provide EDB files to the pilot sponsors.
        !          1715: Contact 
        !          1716: \begin{quote}\small\begin{verbatim}
        !          1717: [email protected]
        !          1718: \end{verbatim}\end{quote}
        !          1719: to find out the full details.
        !          1720: 
        !          1721: For now, 
        !          1722: note that entries are formatted as described above,
        !          1723: but with a few read-only modifications:
        !          1724: \begin{itemize}
        !          1725: \item  The \verb"accessControlList" attribute is simply:
        !          1726: \begin{quote}\small\begin{verbatim}
        !          1727: acl=
        !          1728: \end{verbatim}\end{quote}
        !          1729: 
        !          1730: \item  The \verb"userPassword" attribute is not present.
        !          1731: \end{itemize}
        !          1732: 

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