![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to maintenance.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 maintenance.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 {Maintenance}
4: Now that your Level-1 DSA has successfully joined the pilot project DMD,
5: you must maintain your portion of the Directory tree.
6:
7: \section {A file you should know about}
8: The file \file{quiputailor} file in the \file{quipu/wildlife/} directory
9: contains runtime configuration for your Level-1 DSA.
10: It was automatically created earlier.
11:
12: Section~13.3 of \volfive/ discusses the options available for run-time
13: tailoring.
14: Typically,
15: you will not need to edit this file.
16:
17: \section {Nightly Maintenance}
18: One of the last tasks performed when you Level-1 DSA joined the pilot project
19: DMD was to direct your system to run a shell script, \file{nightly.sh}.
20: This script performs two tasks:
21: \begin{itemize}
22: \item it mails your logs to the pilot project sponsors
23: (this is only a temporary measure to aid our understanding of
24: how the software is behaving);
25: and,
26:
27: \item it cycles your logs.
28: \end{itemize}
29: You might wish to modify this script so that you are also informed of the
30: activities of your Level-1 DSA.
31: Actually, the logs record only crude information.
32: During the course of the pilot project,
33: the pilot software might be upgraded to provide more meaningful information.
34: This will be examined as experience is gained.
35:
36: \subsection {Logs}
37: The pilot software does a lot of logging.
38: There are two logs which are generated,
39: the first,
40: \file{dsap.log},
41: contains information on general DSA activity,
42: whilst the second,
43: \file{stats.log},
44: contains statistical information on the DSA.
45:
46: \subsection {Limiting the size of Logs}
47: If your Level-1 DSA is particularly busy,
48: it may generate large logs.
49: As such,
50: you might find it desirable to limit the maximum size that a log may grow to.
51: Since two logs are generated,
52: one for DSA activity and the other for statistics,
53: you will need to make two edits.
54:
55: Look at the \file{quiputailor} file in the \file{quipu/wildlife/} directory.
56: There should be four lines similar to this:
57: \begin{quote}\small\begin{verbatim}
58: # minimal logging
59: dsaplog level=exceptions dflags=tty file=dsap.log
60:
61: # full statistics
62: stats level=all dflags=tty file=stats.log
63: \end{verbatim}\end{quote}
64: Add the string \verb"size=100" at the end of the two lines,
65: e.g.,
66: \begin{quote}\small\begin{verbatim}
67: # minimal logging
68: dsaplog level=exceptions dflags=tty file=dsap.log size=100
69:
70: # full statistics
71: stats level=all dflags=tty file=stats.log size=100
72: \end{verbatim}\end{quote}
73: This will limit the size of each log to 100~Kbytes.
74: If you wish other limits,
75: change the value \verb"100" accordingly.
76:
77: \subsection {Reading Logs}
78: This is currently a black art.
79: When the sponsors of the pilot project have mastered this,
80: \theguide/ will be updated accordingly.
81: In the meantime,
82: if you figure something out,
83: share it with the \verb"wpp-camayocs" list.
84: Have fun.
85:
86: \section {Adding Entries}
87: Now comes the fun part:
88: entering data into the Directory.
89: In general,
90: there are two kinds of activities:
91: small, incremental changes are best made using \man dish(1c).
92: However,
93: for the wholesale entry of massive amounts of data,
94: the easiest way is to run your favorite text editor and create EDB files
95: manually.
96: (In a future release of the pilot project software,
97: more management tools will be available to automate this process somewhat.)
98:
99: Note that if you edit the EDB files directly,
100: you {\bf must\/} tell your DSA to re-read these files after you are done
101: editing.
102: This is accomplished by either killing and restarting the DSA
103: or using the \switch"refresh" option to the \pgm{dish} command
104: \verb"dsacontrol".
105:
106: To aid the process,
107: a number of templates for the objects you might add are found in the directory
108: \file{quipu/templates/}:
109: \begin{quote}\begin{tabular}{rl}
110: \file{alias}& \verb"alias" object\\
111: \file{dsa}& Level-2 DSA\\
112: \file{person}& \verb"pilotPerson" object\\
113: \file{role}& \verb"organizationalRole" object\\
114: \file{unit}& \verb"organizationalUnit" object
115: \end{tabular}\end{quote}
116: Each of these files contains editing instructions.
117:
118: In the \file{quipu/} source directory,
119: there is a program called \pgm{testedb},
120: which can be used to check EDB files for correctness:
121: \begin{quote}\small\begin{verbatim}
122: % cd quipu/
123: % ./make testedb
124: % ./testedb < EDB
125: \end{verbatim}\end{quote}
126: The \pgm{testedb} program will find the vast majority of errors in an EDB file.
127: It can not however,
128: find errors due to schema violation
129: (i.e., not conforming to the \verb"treeStructure" attribute of the EDB's
130: parent).
131: If your DSA fails to boot properly,
132: the log will indicate:
133: \begin{quote}\small\begin{verbatim}
134: DSA Halted
135: \end{verbatim}\end{quote}
136: In this case,
137: invoke the DSA interactively to determine the cause of the problem,
138: e.g.,
139: \begin{quote}\small\begin{verbatim}
140: % $(SBINDIR)ros.quipu -t ./quiputailor
141: Schema error in entry ending line 16...
142: *** Attribute error ***
143: <<DN of entry in error>>
144: Attribute type objectClass - Constrain violation
145: File ...wildlife/c=US/o=O_i/EDB not loaded
146: FATAL ERROR: DSA Halted
147: \end{verbatim}\end{quote}
148:
149: \subsection {Using Dish}
150: If you use the first approach,
151: then your Level-1 DSA will automatically update the database directory.
152: Thus,
153: all you need be able to do is run one of the user interfaces.
154:
155: First, identify yourself to \pgm{dish} as the manager of the DSA holding the
156: entries you want to modify:
157: \begin{quote}\small\begin{verbatim}
158: % dish -c "wildlife name" -user "c=US@o=O_i@cn=Manager"
159: Enter password for "c=US@o=O_i@cn=Manager": secret
160: Dish ->
161: \end{verbatim}\end{quote}
162: You can now use the \verb"add" and \verb"modify" commands as appropriate.
163: For the \verb"add" command,
164: it is suggested you start with one of the supplied templates, e.g.,
165: \begin{quote}\small\begin{verbatim}
166: Dish -> add ou=Corporate -template $(ETCDIR)quipu/templates/unit
167: \end{verbatim}\end{quote}
168: will create a new organizational unit under the current node.
169:
170: The only tricky part is when objects of class \verb"organizationalUnit" or
171: \verb"dsa" are added.
172:
173: \section {Adding organizationalUnits}
174: When an organizational unit is added,
175: you must also modify the entries for the DSAs holding MASTER or SLAVE copies
176: of the subordinates of the organizational unit.
177: \[\fbox{\begin{tabular}{lp{0.8\textwidth}}
178: \bf NOTE:& At the present time, the pilot sponsors strongly recommend
179: against adding Level-2 DSAs.
180:
181: A Level-2 DSA should be added only when a Level-1 DSA is too
182: large to run on an available system. In this case,
183: a Level-2 DSA can be used to reduce the memory requirements
184: on the system running the Level-1 DSA.
185: \end{tabular}}\]
186:
187: If the organizational unit is to be mastered by your Level-1 DSA,
188: then the procedure is straight-forward:
189: First,
190: create a directory in your \file{wildlife/c=US/o=O\_i/} directory with
191: the name of the organizational unit, e.g.,
192: \begin{quote}\smaller\begin{verbatim}
193: wildlife/c=US/o=NYSERNet Inc./ou=Corporate
194: \end{verbatim}\end{quote}
195: Second,
196: create an \file{EDB} file in this \unix/ directory containing information on
197: the entries in that organizational unit.
198: Third,
199: create an entry for that organizational unit in the Directory,
200: e.g., by running \pgm{dish}, moving to your organization's entry,
201: typing:
202: \begin{quote}\small\begin{verbatim}
203: Dish -> add ou=Corporate -template $(ETCDIR)quipu/templates/unit
204: \end{verbatim}\end{quote}
205: and then following the editing instructions in the file.
206:
207: \section {Adding a Level-2 DSA}
208: There are three aspects to adding a Level-2 DSA:
209: first, the entry for your organization and Level-1 DSA must be modified,
210: and an entry for your Level-2 DSA must be created;
211: second,
212: the Level-2 DSA must be configured;
213: and,
214: third,
215: parts of the Directory tree mastered by the Level-1 DSA may be moved over to
216: be mastered by the Level-2 DSA.
217:
218: First, you must choose a name for your new Level-2 DSA.
219: Since there will probably be more Level-2 DSAs then endangered species of
220: South American Wildlife,
221: you do not have to use a wildlife name for a Level-2 DSA.
222: Choose something associated with your organization or state.
223:
224: For the purposes of the pilot project,
225: the name of each Level-2 DSA taks the form:
226: \begin{quote}\small\begin{verbatim}
227: c=US@o=O_i@cn=wildlife name
228: \end{verbatim}\end{quote}
229: As usual,
230: you will have to pick a ``sanitized'' name that will be used for the \unix/
231: directory which will contain the database for your Level-2 DSA.
232:
233: To remain consistent with the discussion on configuring a Level-1 DSA,
234: we'll call the name of the DSA \verb"wildlife name" and the directory will be
235: called \file{wildlife/}.
236:
237: \subsection {Modifying the Level-1 DSA}
238: To the entry for your Level-1 DSA,
239: you will need to add these lines:
240: \begin{quote}\small\begin{verbatim}
241: eDBinfo= # # c=US@o=O_i@cn=wildlife name
242: eDBinfo= c=US # # c=US@o=O_i@cn=wildlife name
243: eDBinfo= c=US@o=O_i # # c=US@o=O_i@cn=wildlife name
244: \end{verbatim}\end{quote}
245: This says that your Level-1 DSA provide copies of the ROOT, \verb"c=US" and
246: your organization's EDBs to your Level-2 DSA.
247:
248: This addition is done using the \verb"modify" command to \pgm{dish}:
249: \begin{quote}\small\begin{verbatim}
250: Dish -> modify "@c=US@cn=wildlife name"
251: \end{verbatim}\end{quote}
252:
253: Note that even though your Level-2 DSA will contain a slave copy of the EDB
254: for your organization,
255: you do not add a \verb"slaveDSA" attribute to your organization's entry to
256: reflect this.
257: In order to contact your Level-2 DSA,
258: it is necessary to find its \verb"presentationAddress" attribute by asking the
259: directory.
260: Since the entry for your Level-2 DSA is kept beneath your organization's
261: entry, anyone asking for information about your Level-2 DSA would already have
262: information on your organization!
263:
264: Finally,
265: you need to add an entry for your Level-2 DSA to the EDB for your organization:
266: \begin{quote}\small\begin{verbatim}
267: Dish -> add "cn=wildlife name" -template $(ETCDIR)quipu/templates/dsa
268: \end{verbatim}\end{quote}
269: The template file contains these editing instructions:
270: \begin{enumerate}
271: \item Change each occurrence of \verb"O_i" to your organization's name; e.g.,
272: \begin{quote}\small\begin{verbatim}
273: NYSERNet Inc.
274: \end{verbatim}\end{quote}
275:
276: \item Change each occurrence of \verb"wildlife name" to the common name of
277: your DSA; e.g.,
278: \begin{quote}\small\begin{verbatim}
279: beeblebrox
280: \end{verbatim}\end{quote}
281:
282: \item For each organizational unit, \verb"U_j", this DSA will master,
283: add a line:
284: \begin{quote}\small\begin{verbatim}
285: eDBinfo = c=US@o=O_i@ou=U_j # # c=US@cn=level-1 DSA
286: \end{verbatim}\end{quote}
287: where \verb"c=US@cn=level-1 DSA" is the name of your Level-1 DSA.
288:
289: \item Change the value of the \verb"presentationAddress" attribute to
290: contain the IP address of the host running the Level-2 DSA,
291: and select an unused TCP port at this IP address
292: (port~17010 is suggested for Level-2 DSAs);
293: e.g.,
294: \begin{quote}\small\begin{verbatim}
295: '0101'H/Internet=130.117.118.3+17010
296: \end{verbatim}\end{quote}
297: If other Level-2 DSAs are to be run on this host,
298: it is suggested that ascending port numbers, starting at 17011, be assigned.
299: However,
300: running multiple Level-2 DSAs on a single host is not recommended.
301:
302: \item Change the value of the \verb"description" attribute for your
303: Level-2 DSA accordingly.
304: The first value should be the wildlife description.
305: Note that you should fully explain the meaning of the Level-2 DSA's
306: common name.
307: Another description value should be added for each organizational
308: unit mastered by this DSA, e.g.,
309: \begin{quote}\small\begin{verbatim}
310: Master DSA for U_j under O_i
311: \end{verbatim}\end{quote}
312: \end{enumerate}
313:
314: \subsection {Configuring a Level-2 DSA}
315: Configuring a Level-2 DSA is currently a pain as \pgm{dsaconfig} is not
316: currently used for this task.
317: Before following the steps below,
318: drop a note to the \verb"wpp-camayocs" list and ask if a new version of
319: \pgm{dsaconfig} is available!
320:
321: Start by copying the database directory for your Level-2 DSA:
322: \begin{quote}\small\begin{verbatim}
323: # cd quipu/
324: # cp -r level-1-dsa wildlife
325: # chmod 700 wildlife
326: # find wildlife -exec chown daemon {} \;
327: # find wildlife -exec chgrp daemon {} \;
328: # su daemon
329: # cd wildlife/
330: \end{verbatim}\end{quote}
331:
332: \subsubsection {Editing the DSA tailoring file}
333: Now edit the \file{quiputailor} file in the \file{quipu/wildlife/} directory.
334: There are three things to do:
335: \begin{enumerate}
336: \item Change the \verb"mydsaname" variable to reflect the Distinguished Name
337: of the DSA.
338: For example:
339: \begin{quote}\small\begin{verbatim}
340: mydsaname "c=US@o=O_icn=wildlife name"
341: \end{verbatim}\end{quote}
342: becomes
343: \begin{quote}\small\begin{verbatim}
344: mydsaname "c=US@o=NYSERNet Inc.@cn=beeblebrox"
345: \end{verbatim}\end{quote}
346:
347: \item Change the \verb"logdir" variable to reflect the \unix/ directory where
348: QUIPU log files are to reside.
349: For example:
350: \begin{quote}\small\begin{verbatim}
351: logdir $(ETCDIR)quipu/wildlife/
352: \end{verbatim}\end{quote}
353: becomes
354: \begin{quote}\small\begin{verbatim}
355: logdir $(ETCDIR)quipu/beeblebrox/
356: \end{verbatim}\end{quote}
357: (Note the trailing slash.)
358:
359: \item Change the \verb"treedir" variable to reflect the \unix/ directory
360: where the DSA's database resides.
361: For example:
362: \begin{quote}\small\begin{verbatim}
363: logdir $(ETCDIR)quipu/wildlife
364: \end{verbatim}\end{quote}
365: becomes
366: \begin{quote}\small\begin{verbatim}
367: logdir $(ETCDIR)quipu/beeblebrox
368: \end{verbatim}\end{quote}
369: (Note the lack of a trailing slash.)
370: \end{enumerate}
371:
372: Section~13.3 of \volfive/ discusses the options available for run-time
373: tailoring.
374: You will have no need of editing this file.
375:
376: \subsubsection {Editing the DSA startup file}
377: Now edit the \file{startup.sh} file in the \file{quipu/wildlife/} directory.
378: There are two things to do:
379: \begin{enumerate}
380: \item Change the \verb"W" variable to reflect the wildlife name of the DSA.
381: For example:
382: \begin{quote}\small\begin{verbatim}
383: W=wildlife
384: \end{verbatim}\end{quote}
385: becomes
386: \begin{quote}\small\begin{verbatim}
387: W="Beeblebrox"
388: \end{verbatim}\end{quote}
389:
390: \item Change the \verb"D" variable to reflect the \unix/ directory where
391: the DSA's database resides.
392: For example:
393: \begin{quote}\small\begin{verbatim}
394: D=$(ETCDIR)quipu/wildlife
395: \end{verbatim}\end{quote}
396: becomes
397: \begin{quote}\small\begin{verbatim}
398: D=$(ETCDIR)quipu/beeblebrox
399: \end{verbatim}\end{quote}
400: \end{enumerate}
401:
402: \subsubsection {Building an Initial Database}
403: The directory database you created with the \pgm{cp} command earlier has done
404: virtually all the work for you.
405: Now all you need do is edit each EDB file to initially mark each as a
406: SLAVE copy.
407: A simple way of doing this is:
408: \begin{quote}\small\begin{verbatim}
409: # find . -name EDB -a -exec vi {} \;
410: \end{verbatim}\end{quote}
411: which will run \pgm{vi} on each EDB file.
412: If the first line of this file says \verb"MASTER",
413: change it to \verb"SLAVE".
414: Otherwise the first line should say \verb"SLAVE"
415: (if the first line of the EDB file says \verb"CACHE",
416: then contact a \camayoc/ for assistance.)
417:
418: \subsubsection {Testing the Level-2 DSA}
419: At this point,
420: your Level-2 DSA should be configured and you should start and test it:
421: \begin{quote}\small\begin{verbatim}
422: # $(SBINDIR)ros.quipu -t ./quiputailor &
423: \end{verbatim}\end{quote}
424: If your DSA is configured properly,
425: it will print out something like:
426: \begin{quote}\small\begin{verbatim}
427: -- '0101'H/Internet=130.117.128.3+17010 --
428: DSA Started
429: \end{verbatim}\end{quote}
430: If your Level-2 DSA does not boot for some reason,
431: consult Section~\ref{dsa:failure} on page~\pageref{dsa:failure}.
432:
433: You should now try connecting to the Level-2 DSA.
434: \begin{quote}\small\begin{verbatim}
435: % dish -c "wildlife name"
436: Welcome to Dish (DIrectory SHell)
437: Dish ->
438: \end{verbatim}\end{quote}
439: indicates that the DUA connected to your Level-1 DSA.
440: Otherwise consult Section~\ref{dua:failure} on
441: page~\pageref{dua:failure} and try to debug the problem.
442:
443: \subsubsection {Editing the DUA tailoring file}
444: Once your Level-2 DSA is operational,
445: you should edit the file \file{dsaptailor} in the ISODE \verb"ETCDIR"
446: directory so that your DUAs
447: will know about this DSA.
448: This is done by adding this line
449: \begin{quote}\smaller\begin{verbatim}
450: dsa_address "wildlife name" '0101'H/Internet=aaa.bbb.ccc.ddd+port
451: \end{verbatim}\end{quote}
452: {\em after\/} the \verb"dsa_address" line for your Level-1 DSA
453: and then making these edits:
454: \begin{enumerate}
455: \item Substitute the common name of your DSA for \verb"wildlife name"; e.g.,
456: \begin{quote}\small\begin{verbatim}
457: Beeblebrox
458: \end{verbatim}\end{quote}
459:
460: \item Change the IP address and TCP port number to correspond to the
461: OSI presentation address you defined earlier in the entry for the
462: DSA;
463: e.g.,
464: \begin{quote}\small\begin{verbatim}
465: '0101'H/Internet=130.117.118.3+17010
466: \end{verbatim}\end{quote}
467: \end{enumerate}
468:
469: Now run the \man dish(1c) program again,
470: telling it to connect to your Level-1 DSA.
471: \begin{quote}\small\begin{verbatim}
472: % dish -c "wildlife name"
473: Welcome to Dish (DIrectory SHell)
474: Dish ->
475: \end{verbatim}\end{quote}
476: indicates that the DUA connected to your Level-1 DSA.
477: Otherwise consult Section~\ref{dua:failure} on
478: page~\pageref{dua:failure} and try to debug the problem.
479:
480: Now look around the Directory tree using \pgm{dish}.
481: Descend to \verb"c=US@o=O_i" to check on your own entries.
482: A good test to run is to try and bind to your own entry,
483: but to do so by dereferencing the alias for the Manager of your DMD:
484: \begin{quote}\small\begin{verbatim}
485: Dish -> bind -user "c=US@o=O_i@cn=Manager"
486: Enter password for "c=US@o=O_i@cn=Manager":
487: Dish ->
488: \end{verbatim}\end{quote}
489: Indicates that you are now bound to the directory as that DN.
490: Instead, if you see:
491: \begin{quote}\small\begin{verbatim}
492: Dish -> bind -user "c=US@o=O_i@cn=Manager"
493: Enter password for "c=US@o=O_i@cn=Manager":
494: Security Error - check name and password
495: \end{verbatim}\end{quote}
496: then either you may have entered the DN or password wrong.
497: Try again.
498: If not,
499: or if you encounter some other problem,
500: contact a \camayoc/ for assistance.
501:
502: \subsection {Moving portions of the Directory Tree}
503: For each organizational unit, \verb"ou=U_j", the Level-2 DSA will master,
504: you now need to do two things:
505: \begin{itemize}
506: \item tell your Level-1 DSA that it no longer masters the EDB;
507: and,
508:
509: \item tell your Level-2 DSA that it now masters the EDB.
510: \end{itemize}
511: The first step is done as follows.
512: Begin by using \pgm{dish} to bind to the Level-1 DSA:
513: \begin{quote}\small\begin{verbatim}
514: % dish -c "Level-1 DSA" -user "c=US@o=O_i@cn=Manager"
515: \end{verbatim}\end{quote}
516: Next:
517: \begin{enumerate}
518: \item Modify the entry for the organizational unit which is held by your
519: Level-1 DSA.
520: Change the \verb"masterDSA" attribute of the entry corresponding to that
521: unit from:
522: \begin{quote}\small\begin{verbatim}
523: masterDSA= c=US@cn=Level-1 DSA
524: \end{verbatim}\end{quote}
525: to:
526: \begin{quote}\small\begin{verbatim}
527: masterDSA= c=US@o=O_i@cn=wildlife name
528: \end{verbatim}\end{quote}
529: You will also need to add a \verb"slaveDSA" attribute to this entry:
530: \begin{quote}\small\begin{verbatim}
531: slaveDSA= c=US@cn=Level-1 DSA
532: \end{verbatim}\end{quote}
533:
534: These additions are done using \pgm{dish}:
535: \begin{quote}\small\begin{verbatim}
536: Dish -> modify "@c=US@o=O_i@ou=U_j"
537: \end{verbatim}\end{quote}
538:
539: \item Modify the entry for your Level-1 DSA.
540: Change the line that says:
541: \begin{quote}\small\begin{verbatim}
542: eDBinfo= c=US@o=O_i@ou=U_j # #
543: \end{verbatim}\end{quote}
544: to:
545: \begin{quote}\small\begin{verbatim}
546: eDBinfo= c=US@o=O_i@ou=U_j # c=US@o=O_i@cn=wildlife name #
547: \end{verbatim}\end{quote}
548: This says that your Level-1 DSA will receive copies of the EDB for each
549: organizational unit held by your Level-2 DSA.
550:
551: This change is done using the \verb"modify" command to \pgm{dish}:
552: \begin{quote}\small\begin{verbatim}
553: Dish -> modify "@c=US@cn=wildlife name"
554: \end{verbatim}\end{quote}
555:
556: \item Lock the Level-1 DSA's copy of the EDB file:
557: \begin{quote}\small\begin{verbatim}
558: Dish -> dsacontrol -lock "c=US@o=O_i@ou=U_j"
559: \end{verbatim}\end{quote}
560:
561: \item Edit the EDB file kept in the {\bf Level-1\/} DSA's directory
562: database by changing the first line from \verb"MASTER" to \verb"SLAVE".
563: (If the first line of this file does not say \verb"MASTER",
564: then you are editing the {\bf wrong\/} directory database.)
565:
566: \item Unlock the Level-1 DSA's copy of the EDB file:
567: \begin{quote}\small\begin{verbatim}
568: Dish -> dsacontrol -refresh "c=US@o=O_i@ou=U_j"
569: Dish -> dsacontrol -unlock "c=US@o=O_i@ou=U_j"
570: \end{verbatim}\end{quote}
571: \end{enumerate}
572:
573: The second step is done as follows.
574: Begin by using \pgm{dish} to bind to the Level-2 DSA:
575: \begin{quote}\small\begin{verbatim}
576: % dish -c "Level-2 DSA" -user "c=US@o=O_i@cn=Manager"
577: \end{verbatim}\end{quote}
578: Next:
579: \begin{enumerate}
580: \item Modify the entry for the for organizational unit which is to be
581: mastered by your Level-2 DSA.
582: Change the \verb"masterDSA" attribute of the entry corresponding to that
583: unit from:
584: \begin{quote}\small\begin{verbatim}
585: masterDSA= c=US@cn=Level-1 DSA
586: \end{verbatim}\end{quote}
587: to:
588: \begin{quote}\small\begin{verbatim}
589: masterDSA= c=US@o=O_i@cn=wildlife name
590: \end{verbatim}\end{quote}
591: You will also need to add a \verb"slaveDSA" attribute to this entry:
592: \begin{quote}\small\begin{verbatim}
593: slaveDSA= c=US@cn=Level-1 DSA
594: \end{verbatim}\end{quote}
595:
596: These additions are done using \pgm{dish}:
597: \begin{quote}\small\begin{verbatim}
598: Dish -> modify "@c=US@o=O_i@ou=U_j"
599: \end{verbatim}\end{quote}
600:
601: \item Modify the entry for your Level-2 DSA.
602: Add this line:
603: \begin{quote}\small\begin{verbatim}
604: eDBinfo= c=US@o=O_i@ou=U_j # # c=US@cn=Level-1 DSA
605: \end{verbatim}\end{quote}
606: This says that your Level-1 DSA will receive copies of the EDB for each
607: organizational unit held by your Level-2 DSA.
608:
609: This change is done using the \verb"modify" command to \pgm{dish}:
610: \begin{quote}\small\begin{verbatim}
611: Dish -> modify "@c=US@o=O_i@cn=wildlife name"
612: \end{verbatim}\end{quote}
613:
614: \item Lock the Level-2 DSA's copy of the EDB file:
615: \begin{quote}\small\begin{verbatim}
616: Dish -> dsacontrol -lock "@c=US@o=O_i@ou=U_j"
617: \end{verbatim}\end{quote}
618:
619: \item Edit the EDB file kept in the {\bf Level-2\/} DSA's directory
620: database by changing the first line from \verb"SLAVE" to \verb"MASTER".
621: (If the first line of this file does not say \verb"SLAVE",
622: then you are editing the {\bf wrong\/} directory database.)
623:
624: \item Unlock the Level-2 DSA's copy of the EDB file:
625: \begin{quote}\small\begin{verbatim}
626: Dish -> dsacontrol -unlock "@c=US@o=O_i@ou=U_j"
627: \end{verbatim}\end{quote}
628: \end{enumerate}
629: You should now reboot your Level-2 DSA and then try to connect to it using
630: \pgm{dish}.
631: Once this is successfully,
632: you should reboot your Level-1 DSA and also use \pgm{dish} to connect to it.
633:
634: When you restart the Level-2 DSA,
635: it will try to update its ROOT,
636: \verb"c=US",
637: and \verb"o=O_i" EDB files from your Level-1 DSA.
638: The first two should be the same as what your Level-2 is running,
639: so no update will take place.
640: The third will be different however,
641: so you should see a file \file{c=US/o=O\_i/EDB.bak} created.
642:
643: When you restart the Level-1 DSA,
644: in addition to trying to reload its ROOT and \verb"c=US" EDB files from the
645: Level-0 DSAs,
646: it will try to reload the EDB file for each organizational unit mastered by
647: the Level-2 DSA.
648: Since these will be the same,
649: initially no update will take place.
650:
651: \subsubsection {Editing the DUA tailoring file}
652: You now edit the \file{dsaptailor} file one more time.
653: Move the \verb"dsa_address" line for your Level-2 DSA above the line for your
654: Level-1 DSA.
655: This will tell your DUAs to contact the Level-2 DSA by default,
656: rather than the Level-1 DSA.
657:
658: \subsubsection {System Administration}
659: Once everything checks out,
660: its time to restart the DSA in the background.
661: Use \pgm{dish} to abort the DSA and then run the \file{startup.sh} script:
662: \begin{quote}\small\begin{verbatim}
663: % $(ETCDIR)quipu/wildlife/startup.sh
664: \end{verbatim}\end{quote}
665: Take a look at the log files it creates and once you're satisfied
666: that it is operational,
667: use \pgm{dish} one last time before considering things up and running.
668:
669: Finally,
670: it's time for the last bit of system administration:
671: \begin{enumerate}
672: \item Add an entry to the file \file{/etc/rc.local}:
673: \begin{quote}\smaller\begin{verbatim}
674: if [ -d $(ETCDIR)quipu/wildlife ]; then
675: $(ETCDIR)quipu/wildlife/startup.sh & \
676: (echo -n ' wildlife') > /dev/console
677: fi
678: \end{verbatim}\end{quote}
679: in the section where the network servers are started.
680: If your \file{rc.local} file starts \man tsapd(8c),
681: then place this entry after the one which starts \pgm{tsapd}.
682:
683: \item Edit the file \file{quipu/wildlife/nightly.sh},
684: by looking for these three lines
685: \begin{quote}\smaller\begin{verbatim}
686: W="dsa name from dsaptailor, e.g., Beeblebrox"
687: D="wildlife directory, e.g., $(ETCDIR)quipu/beeblebrox"
688: \end{verbatim}\end{quote}
689: and editing them appropriately.
690:
691: \item Based on the time that the \verb"c=US" manager gave you for your
692: Level-1 DSA, add one hour and modify the \file{crontab} file according; e.g.,
693: \begin{quote}\small\begin{verbatim}
694: 0 5 * * * $(ETCDIR)quipu/wildlife/nightly.sh
695: \end{verbatim}\end{quote}
696: If the directory database for the Level-2 DSA is owned by a user-ID other
697: than \verb"root" (e.g., \verb"daemon"),
698: then instead the line should look something like this:
699: \begin{quote}\small\begin{verbatim}
700: 0 5 * * * su daemon < $(ETCDIR)quipu/wildlife/nightly.sh
701: \end{verbatim}\end{quote}
702: \end{enumerate}
703:
704: Congratulations!
705: Your Level-2 DSA has now joined the pilot DMD.
706:
707: \section {Miscellaneous Topics}
708: Here is information on a wide range of topics,
709: arranged in no particular order.
710:
711: \subsection {Moving a Level-1 DSA}
712: For various reasons you might need to move your DSA from one host to another.
713: In OSI terminology,
714: you need to change the presentation address of the DSA.
715: The steps to do this are:
716: \begin{enumerate}
717: \item Modify the \verb"presentationAddress" attribute of your DSA using
718: \pgm{dish} to include the second host.
719: Also edit your \file/{dsaptailor} file to include this new address.
720: In both cases, you simply add the string:
721: \begin{quote}\small\begin{verbatim}
722: |Internet=aaa.bbb.ccc.ddd+portno
723: \end{verbatim}\end{quote}
724: to the address.
725: So, if the old address was
726: \begin{quote}\small\begin{verbatim}
727: '0101'H/Internet=192.33.4.20+17003
728: \end{verbatim}\end{quote}
729: the new address might be
730: \begin{quote}\small\begin{verbatim}
731: '0101'H/Internet=192.33.4.20+17003|Internet=130.117.128.2+17003
732: \end{verbatim}\end{quote}
733:
734: \item Edit your DSA's entry in the \file{c=US/EDB} file and remove the line
735: \begin{quote}\small\begin{verbatim}
736: eDBinfo= c=US # cn=Alpaca #
737: \end{verbatim}\end{quote}
738: This will prevent your DSA from seeing this change to it's presentation
739: address,
740: which is necessary since your DSA can't listen on the new address at the
741: moment.
742:
743: \item Now wait a couple of days for this new information to propagate.
744: This is important to avoid a transient service outage.
745:
746: \item Stop the DSA and move its hierarchy over to the new host.
747:
748: \item Edit the \file{c=US/EDB} file and change your
749: DSA's \verb"presentationAddress" attribute to have only the new address, e.g.,
750: \begin{quote}\small\begin{verbatim}
751: presentationAddress= '0101'H/Internet=130.117.128.2+17003
752: \end{verbatim}\end{quote}
753:
754: \item Start the DSA on the new host and verify that it is working okay.
755:
756: \item Modify the \verb"presentationAddress" attribute to remove the first
757: host address for your DSA using \pgm{dish}
758: The presentation address will now match the value in the \file{c=US/EDB} file
759: you have locally.
760: Also edit your \file{dsaptailor} file to have only the new address.
761:
762: \item Edit your DSA's entry in the \file{c=US/EDB} file and add the line
763: \begin{quote}\small\begin{verbatim}
764: eDBinfo= c=US # cn=Alpaca #
765: \end{verbatim}\end{quote}
766: This will resume the automatic downloading of information for your DSA.
767:
768: \item Don't forget to edit \file{/etc/rc.local} and \file{/usr/lib/crontab}
769: on both systems.
770: \end{enumerate}
771:
772: \subsection {Running a SLAVE Level-1 DSA}
773: {\em to be supplied$\ldots$}
774:
775: %%% register at c=US
776: %%% copy edb files
777: %%% change masters to slaves
778: %%% for each master add
779: %%% eDBinfo= dn # master # to slave DSA entry
780: %%% eDBinfo= dn # # slave to master entry
781: %%% slaveDSA= slave to dn entry
782:
783: \subsection {A Final Word on DSAs and Knowledge Information}
784: It is important to appreciate that a DSA may hold knowledge
785: (have local \file{EDB} files)
786: even though the DIT does not indicate this
787: (no corresponding \verb"slaveDSA" attribute for that portion of the tree).
788: This is a feature.
789:
790: For example,
791: if you wish to speed access to certain parts of the tree for your users,
792: then to the entry of the DSA which MASTERs that information,
793: you add this attribute:
794: \begin{quote}\small\begin{verbatim}
795: eDBinfo = interesting_EDB # # slave_DSA_name
796: \end{verbatim}\end{quote}
797: to the entry of the DSA which is to have a copy,
798: you add this attribute:
799: \begin{quote}\small\begin{verbatim}
800: eDBinfo = interesting_EDB # master_DSA_name #
801: \end{verbatim}\end{quote}
802: And you do {\bf not\/} add any \verb"slaveDSA" attribute to the entry
803: corresponding that EDB.
804:
805: This configuration has the effect that any user contacting the slave DSA,
806: will find that information local,
807: but, since this DSA is not listed in the \verb"slaveDSA" attribute,
808: then other DSAs won't bother it asking for information.
809:
810: \subsection {Naming People}\label{naming:people}
811: As noted earlier,
812: entries in the Directory are uniquely named by their
813: Relative Distinguished Name (RDN).
814: In the pilot software,
815: the RDN is represented as the first line of each entry in the \file{EDB} file
816: for its immediate parent.
817: Thus,
818: within an \file{EDB} file,
819: all RDNs must be unique.
820:
821: The simplest way of doing this is to use:
822: \begin{quote}\small\begin{verbatim}
823: cn=FirstName LastName
824: \end{verbatim}\end{quote}
825: as the RDN.
826: However,
827: in organizations with large numbers of people,
828: this may not be sufficient to be unique.
829: So, there are four alternative strategies:
830: \begin{enumerate}
831: \item Use
832: \begin{quote}\small\begin{verbatim}
833: cn=FirstName LastName
834: \end{verbatim}\end{quote}
835: whenever possible.
836: However,
837: whenever ambiguity occurs, use either
838: \begin{quote}\small\begin{verbatim}
839: cn=FirstName MiddleInitial LastName
840: \end{verbatim}\end{quote}
841: or
842: \begin{quote}\small\begin{verbatim}
843: cn=FirstName MiddleName LastName
844: \end{verbatim}\end{quote}
845: Note that,
846: the shorter forms should also be included to aid in searching.
847: Hence,
848: the first three lines of an entry might look like:
849: \begin{quote}\small\begin{verbatim}
850: cn=FirstName MiddleName LastName
851: cn= FirstName MiddleInitial LastName
852: cn= FirstName LastName
853: \end{verbatim}\end{quote}
854: The first value is used for the RDN,
855: and the other two for searching.
856:
857: \item Always use
858: \begin{quote}\small\begin{verbatim}
859: cn=FirstName MiddleName LastName
860: \end{verbatim}\end{quote}
861: as the RDN for all entries,
862: and include the shorter forms whenever possible.
863:
864: \item Always generate a uniquely constructed string
865: \begin{quote}\small\begin{verbatim}
866: cn=FML1
867: \end{verbatim}\end{quote}
868: and include whatever real naming information is available for searching
869: purposes:
870: \begin{quote}\small\begin{verbatim}
871: cn= FirstName MiddleName LastName
872: cn= FirstName MiddleInitial LastName
873: cn= FirstName LastName
874: \end{verbatim}\end{quote}
875: The only caveat with this approach is that each time the EDB file is
876: generated, it is best not to change the RDNs for entries which previously
877: existed.
878:
879: \item Use a multi-valued RDN ({\em deus ex machina\/} formed by a
880: \verb"commonName" attribute and some other distinguishing attribute:
881: \begin{quote}\small\begin{verbatim}
882: cn=FirstName MiddleName LastName%userid=Lastname
883: \end{verbatim}\end{quote}
884: The \verb"`%'"-sign is used to concatenate attributes when forming an RDN.
885: Hence,
886: if the first line of an entry is
887: \begin{quote}\small\begin{verbatim}
888: cn=Marshall Rose%userid=mrose
889: \end{verbatim}\end{quote}
890: then the entry's RDN really has two parts:
891: the most significant part is a \verb"commonName" attribute,
892: and the next significant part is a \verb"userid" attribute.
893: Other good choices besides \verb"userid" are things like \verb"localityName".
894:
895: Of course,
896: the \verb"`%'"-notation can be used only on the first line of an entry,
897: as it is used only for RDNs.
898: \end{enumerate}
899: In all cases,
900: regardless of the actual RDN chosen,
901: it is strongly recommended to include as many alternate forms as possible,
902: in order to aid searching.
903:
904: \subsection {Installing the Software on other hosts}
905: You may wish to install the interfaces to the Directory,
906: on other systems,
907: whilst running a DSA on a single host.
908: If the hardware/software configuration of the new hosts are the same as the
909: initial host,
910: then you can simply install the compiled binaries.
911: Usually this is done by mounting the source hierarchy over the network,
912: logging in to the new host,
913: and using:
914: \begin{quote}\small\begin{verbatim}
915: # ./make inst-all inst-quipu
916: # (cd others/quipu; ./make inst-pilot)
917: \end{verbatim}\end{quote}
918: Then,
919: you must copy over two files from the ISODE \verb"ETCDIR" directory on the
920: original host: \file{dsaptailor} and \file{fredrc}.
921:
922: If, however, you wish to change the software configuration,
923: then after moutning the source hierarchy,
924: you must clean the existing binaries in the source hierarchy,
925: then select the new configuration files and go through the generation and
926: installation process:
927: \begin{quote}\small\begin{verbatim}
928: % ./make distribution
929: % ./make once-only all all-quipu
930: % (cd others/quipu; ./make pilot)
931: # ./make inst-all inst-quipu
932: # (cd others/quipu; ./make inst-pilot)
933: \end{verbatim}\end{quote}
934: Next, you must then copy over the \file{dsaptailor} and \file{fredrc} files
935: from the ISODE \verb"ETCDIR" directory on the original host.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.