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