![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to introduction.tex CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSDReno / contrib / isode-beta / doc / whitepages / administrator|
Return to introduction.tex CVS log | Up to [CSRG BSD Unix] / 43BSDReno / contrib / isode-beta / doc / whitepages / administrator |
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.