Return to maintenance.tex CVS log

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

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

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.