![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to q-dsa.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 / manual|
Return to q-dsa.tex CVS log | Up to [CSRG BSD Unix] / 43BSDReno / contrib / isode-beta / doc / manual |
1.1 root 1: %run this through LaTeX with the appropriate wrapper
2:
3: \chapter {Installing QUIPU}
4:
5: \label{quipu:install}
6:
7: This section describes how to install QUIPU, and make it operate in a basic
8: fashion. This is reasonably prescriptive, as it should be possible to
9: install and operate a QUIPU DUA and/or DSA without too much
10: knowledge about how it functions.
11:
12: QUIPU comes in 4 separate parts of the ISODE tree, none of which are
13: ``made'' as part of the default installation of ISODE.
14: This section assumes you have installed ISODE.
15: You should consult the \file{READ-ME} file in the
16: top level of the source tree, and \volone/ to \volfour/ of this Manual
17: if you have not installed ISODE.
18:
19: There are various options you can set which control
20: the operation of QUIPU. These are set in the file \file{h/quipu/config.h}
21: but are probably best left to their default values, unless you qualify
22: as a ``large'' site. Larger sites may want to consider enabling
23: the TURBO options described in the next section.
24:
25: To generate QUIPU type \verb"make all-quipu" in the top-level ISODE
26: directory.
27:
28: A version of \pgm{dish} that runs directly
29: from a \unix/ shell,
30: \pgm{dishinit}:
31: a script to create a default \file{.quipurc} file for new users, and
32: \pgm{sid}: a set of scripts that utilise the shell version of dish, are all
33: installed from the \file{others/quipu/uips/dish} directory.
34: The \pgm{fred}, \pgm{widget} and \pgm{sunint} interfaces
35: can be installed by looking at
36: \file{others/quipu/uips/READ-ME}.
37:
38: Each of these interfaces knows about the ``photo'' attribute that an entry
39: in the DIT can have. In order to display the photographs, the photo
40: handling code must be compiled, instructions on this can be found in
41: Section~\ref{dua:photo} of this Manual and the file
42: \file{others/quipu/photo/READ-ME}.
43:
44: \section{TURBO Options for Large Sites}
45: This section describes two options (TURBO\_LOAD and TURBO\_DISK) that
46: can be set in the file \file{h/quipu/config.h}. Both options are
47: most useful for sites with a large amount of data (e.g. hundreds of
48: entries per EDB file). The first option, TURBO\_LOAD, can be used to speed
49: the process of loading data from disk during startup.
50: When QUIPU starts, it must check each entry that it loads
51: against those sibling entries already loaded
52: to ensure that the data in each EDB
53: file contains no duplicate entries. Normally, this is done by
54: searching a linked list of loaded entries. The TURBO\_LOAD option
55: works by building and searching an AVL (height-balanced)
56: tree instead of the linked list. Also, it allocates space for this
57: tree in large chunks to help reduce paging. The AVL tree is only
58: used during the loading process and does not affect operation of the
59: DSA once the database is loaded. There is some extra
60: overhead involved in buildng the AVL tree, and the point at which
61: the TURBO\_LOAD option starts improving things seems to be about
62: 100+ entries per EDB file. If you have EDB files containing
63: significantly more
64: than 100 entries, you may want to consider enabling the TURBO\_LOAD
65: option.
66:
67: To use the TURBO\_LOAD option, add a line like this to the
68: \file{h/quipu/config.h} file:
69: \begin{verbatim}
70: #define TURBO_LOAD /* enable fast loading of big EDB files */
71: \end{verbatim}
72: There are two run time tailor options you should be aware if the
73: TURBO\_LOAD option has been enabled ({\it turbo\_size}
74: and {\it turbo\_namelen}). These options are set in the
75: \file{quiputailor} file and should be left to their default values
76: unless the loading process fails with a message indicating that
77: these parameters should be changed.
78:
79: The second option, TURBO\_DISK, can be used to make modify operations
80: run much faster, especially on large data sets. It requires the use
81: of the \pgm{gdbm} library. \pgm{Gdbm} is a library of simple database routines
82: providing functionality similar to \pgm{dbm} and \pgm{ndbm}, but without the
83: filesystem page size limitations of those systems. \pgm{Gdbm} is GNU
84: software and is available from the Free Software Foundation. It is
85: not a part of the ISODE.
86: Normally, when an
87: entry is modified, QUIPU writes the entire EDB file the entry lives
88: in synchronously out to disk. If the EDB file is very large, this can
89: take some time, especially on a heavily loaded system. The TURBO\_DISK
90: option works by keeping the disk data in \pgm{gdbm} files instead of the
91: regular EDB files. This way, when an update is made, only the
92: affected entry need be written to disk. The performance increase
93: is directly proportional to the size of the EDB file.
94: Whereas a normal update operation takes time proportional to the size
95: of the EDB file, with the TURBO\_DISK option it takes a small constant
96: amount of time. As for TURBO\_LOAD, if you don't have EDB files with
97: at least a hundred or so entries, it's probably not worth enabling
98: the TURBO\_DISK option.
99:
100: To use the TURBO\_DISK option, add a line like this to the
101: \file{h/quipu/config.h} file:
102: \begin{verbatim}
103: #define TURBO_DISK /* enable fast EDB update operations */
104: \end{verbatim}
105: Next, if you have enabled the TURBO\_LOAD option as described above, you
106: will need to edit the file \file{quipu/turbo\_disk.c} and make a small
107: change. The line:
108: \begin{verbatim}
109: #include "/u/up/tim/src/gdbm-1.3/gdbmdefs.h"
110: \end{verbatim}
111: should be changed to reflect the actual location of the \file{gdbmdefs.h}
112: include file on your system. Note that this file is not installed in
113: the normal process of installing \pgm{gdbm}. It is in the \pgm{gdbm} source
114: directory. Disgustingly enough, the {\it turbo\_start} routine needs
115: to be able to {\it stat} the \pgm{gdbm} file, and needs the definitions
116: in \file{gdbmdefs.h} to do so. If you are not using the TURBO\_LOAD
117: option, this step is not necessary.
118:
119: Now make and install QUIPU as usual.
120: Before running QUIPU, you will have to
121: convert your EDB file hierarchy into a gdbm file hierarchy. This step
122: is only necessary once. The \file{quipu/turbo} directory contains some
123: tools to help in this process. The shell script \pgm{tree2dbm} will
124: convert an EDB file hierarchy to a gdbm file hierarchy. To use it,
125: type ``\verb+tree2dbm database-directory+'' where database-directory is the
126: directory where the EDB file hierarchy begins. This script does a
127: find starting in that directory for files named EDB and runs them through the
128: \pgm{edb2dbm} program which creates a file called \file{EDB.gdbm}.
129: The original EDB file is neither removed nor
130: molested, so you'll need roughly twice the disk space. Alternatively, you
131: can run \pgm{edb2dbm} by hand on each EDB file. The reverse operation
132: (converting from a \pgm{gdbm} hierarchy to an EDB hierarchy) is done
133: by the \pgm{synctree} shell script. It is a good idea to run
134: \pgm{synctree} out of \file{crontab} once in a while to update the
135: EDB file hierarchy.
136:
137: Finally, it should be noted that parse errors will be reported
138: somewhat differently in the \file{dsap.log} file with the
139: TURBO\_DISK option enabled. Since line numbers don't make much
140: sense in a \pgm{gdbm} file, errors will be reported based on the
141: Relative Distinguished Name of the offending entry. If you get
142: a parse error (because of a non-printable character, for example),
143: the best approach is to do something like this:
144: \begin{verbatim}
145: edbcat EDB >bob
146: edit the file bob, locate the entry, and fix the problem
147: edb2dbm bob
148: mv bob.gdbm EDB.gdbm
149: \end{verbatim}
150: where this procedure assumes you are in the directory containing
151: the bad EDB.gdbm file. The edbcat program can be found in the
152: \file{quipu/turbo} directory and is used to convert from \pgm{gdbm}
153: back to plain text EDB format.
154:
155: \section{Files}
156: Regardless of how you install QUIPU and the ISODE,
157: the number of files needed to run QUIPU are quite small.
158:
159: In ISODE's \verb"BINDIR" directory,
160: typically \file{/usr/local/bin/},
161: there are a few programs of interest:
162: \begin{describe}
163: \item[dish:] The DIrectory SHell\\
164: This is discussed in Chapter~\ref{dish}.
165:
166: \item[bind:] Shell interface to \pgm{dish}\\
167: There are actually several links (listed below) to a program called
168: \pgm{bind}.
169: These act to export the \pgm{dish} interface to the \unix/
170: shell.
171: As such,
172: you can issue commands to \pgm{dish} from the shell,
173: rather than running \pgm{dish} directly.
174: \begin{quote}
175: \begin{tabular}{l}
176: add\\
177: compare\\
178: delete\\
179: dsacontrol\\
180: list\\
181: modify\\
182: modifyrdn\\
183: moveto\\
184: search\\
185: showentry\\
186: showname\\
187: squid
188: \end{tabular}
189: \end{quote}
190:
191: \item[fred:] A white pages user interface\\
192: See Chapter~\ref{DUA:fred}.
193:
194: \item[editentry:] Edit a Directory entry\\
195: This is a simple shell script that \pgm{dish} invokes when you
196: ask \pgm{dish} to edit an entry in the Directory.
197:
198: \item[unbind:] Unbind from \pgm{dish}\\
199: This command is used to terminate \pgm{dish}.
200: \end{describe}
201: In ISODE's \verb"SBINDIR" directory,
202: typically \file{/usr/etc/},
203: the DSA resides:
204: \begin{describe}
205: \item[ros.quipu:] The QUIPU DSA\\
206: This program will be started once, for each DSA you
207: are running, from rc.local.
208: A script is provided to invoke this program,
209: in case you need to restart it.
210:
211: %%%\item[dsaconfig:] a configurator for Level-1 DSAs.
212: \end{describe}
213: In ISODE's \verb"ETCDIR" directory,
214: also typically \file{/usr/etc/},
215: there are a few programs and files of interest:
216: \begin{describe}\sloppy
217: \item[oidtable.at, oidtable.gen, oidtable.oc:]
218: These define the attribute types,
219: generic object identifiers,
220: and object classes known to the system.
221: (An object identifier is a method used to unambiguously
222: encode, among other things,
223: the names of attributes and object classes.)
224: These files you never deal with unless they are
225: accidently corrupted.
226:
227: \item[dsaptailor:] This is the run-time tailor file for the DUAs.
228: You will configure this file initially and then
229: probably leave it alone.
230:
231:
232: \item[isoaliases, isobjects, isoentities, isomacros, isoservices:]
233: These are \\ %%%
234: various databases used by the ISODE.
235: These files you never deal with unless they are
236: accidently corrupted.
237:
238: \item[isologs:] This script runs nightly under \man cron(8) to
239: trim the ISODE log files, kept in ISODE's \verb"LOGDIR"
240: directory,
241: typically \file{/usr/tmp/}.
242: This file you never deal with unless it is
243: accidently corrupted.
244:
245: \item[isotailor:] This is the run-time tailor file for the ISODE.
246: You will configure this file initially and then
247: probably leave it alone.
248: \end{describe}
249:
250: \chapter {Configuring a DUA}
251:
252: It is suggested that you try to get a DUA operational by connecting to
253: a ``well known'' DSA before you attempt
254: to operate a local DSA.
255: Or, if you have a DSA from a previous release of QUIPU - try an connect to
256: that.
257:
258: \section {Connecting to a DSA}
259: \label{dua:connect}
260:
261: A DUA essentially only needs to know one thing to be able to contact a
262: DSA, that is the network address of the DSA.
263: This parameter is defined in the file \file{dsaptailor},
264: together with some other parameters.
265: The full set of parameters are described in Section \ref{dua:tailor}.
266:
267: The \verb"dsa_address" parameter defines the name and address of the DSA to
268: initially contact. For example,
269: \begin{quote}\begin{verbatim}
270: dsa_address vicuna Internet=bells.cs.ucl.ac.uk+50987
271: \end{verbatim}\end{quote}
272:
273: declares the DSA \verb"vicuna" at the indicated presentation
274: address\footnote{The syntax of presentation addresses is discussed in
275: \volone/ of this manual and \cite{String.Addresses}.}
276: \index{presentation addresses}
277: to be the
278: default DSA for the DUA to contact.
279: As shown above, the address is preceded by a private key. This can
280: be used in some DUAs (including DISH) to specifying the address of the DSA
281: to contact.
282: If there are more than one \verb"dsa_address" entries, the first
283: entry will be used to supply the default DSA address.
284:
285: A default dsaptailor file
286: (taken from \file{dsap/dsaptailor}) is installed as
287: \file{dsaptailor} in the ISODE \verb"ETCDIR" directory
288: (usually \file{/usr/etc/}) when
289: the dsap library is installed, this supplies the addresses
290: of various DSAs that you
291: may be able to access.
292:
293: To try to connect to one of the DSAs listed in dsaptailor,
294: invoke \pgm{dish}, with a \verb"-call"
295: flag, e.g. ``\verb"dish -call giant"'' will try to contact the DSA ``giant''
296: running at UCL.
297: If the connection is successful, then the prompt ``\verb"dish ->"'' will be returned.
298: If the connection fails, the
299: program will exit with an appropriate error
300: message.
301:
302: If this fails
303: you might want to
304: try connecting to some of the other registered DSAs,
305: for example, try ``\verb"dish -call alpaca"'', ``\verb"dish -call eel"''
306: or ``\verb"dish -call anaconda"''.
307: A list of registered DSAs is given in Appendix~\ref{dsa:sites}.
308:
309: If you fail to contact a DSA at this point, there are likely to be lower
310: level problems. You should turn up the ISODE logging
311: (see \voltwo/ of this manual) to see what is happening to the
312: network calls.
313:
314: If you invoke \pgm{dish} without a \verb"-c" flag (using the default \file{dsaptailor}), it will
315: try to connect to the DSA defined by the first
316: \verb"dsa_address" entry.
317:
318: \pgm{dish} is described in full in Chapter~\ref{dish}
319: of this Manual.
320:
321: \section{Tailoring}
322: \label{dua:tailor}
323: \index{dsaptailor}
324:
325: The program configuration is tailored to
326: allow you to change logging levels, and other parameters at
327: run time.
328: It is used by the QUIPU DUA procedures, and by the QUIPU User Interfaces.
329:
330: The file \file{dsaptailor} is used for this purpose and
331: consists of single value entries (e.g. oidtable), unless otherwise
332: stated (e.g dsaplog).
333: Each entry has a parameter followed by its
334: value.
335: The various options are:
336: \begin{describe}
337: \item [\verb"oidtable":]
338: The path for the OID definition tables.
339: NOTE: It is best to have this appear as the first entry of the tailor file, as
340: other entries may contain attributes that need to be looked up in these
341: tables
342: There are three:
343: \begin{itemize}
344: \item \file{file.gen},
345: which contains generic names for building OIDs;
346: \item \file{file.at},
347: which contains the OIDs for attributes; and,
348: \item \file{file}.oc,
349: which contains the OIDs for object classes.
350: \end{itemize}
351: For example,
352: \begin{quote}\small\begin{verbatim}
353: oidtable /usr/lib/quipu/OIDTable
354: \end{verbatim}\end{quote}
355: will direct the DSA to consult:
356: \begin{quote}\begin{verbatim}
357: /usr/lib/quipu/OIDTable.gen
358: /usr/lib/quipu/OIDTable.at
359: /usr/lib/quipu/OIDTable.oc
360: \end{verbatim}\end{quote}
361: By default this is set to \verb"oidtable" which refers to the tables
362: \file{oidtable.*} in the ISODE \verb"ETCDIR" directory.
363:
364: \item [\verb"dsa\_address":]
365: This parameter is described in Section~\ref{dua:connect}.
366:
367: \item [\verb"dsaplog":]
368: Tailoring for the normal logging file.
369: Each entry consists of one or more key/value pairs expressed as:
370: \begin{quote}\small\begin{verbatim}
371: key=value
372: \end{verbatim}\end{quote}
373: The keys are:
374: \begin{describe}
375: \item [\verb"file":]
376: The name of the logfile.
377: \item [\verb"size":]
378: The size in KBytes to which the logfile should be allowed to grow.
379: When the log has reached this size, if the ``zero'' option
380: below is set, then the log will be truncated, otherwise, no further
381: logging will take place.
382: \item [\verb"level":]
383: The levels of logging to be written to this log file.
384: This can be any of the following levels:
385: \begin{describe}
386: \item [\verb"fatal":]
387: fatal errors only
388: \item [\verb"exceptions":]
389: serious, but hopefully temporary, errors
390: \item [\verb"notice":]
391: general logging information
392: \item [\verb"trace":]
393: program tracing
394: \item [\verb"pdus":]
395: pdu tracing
396: \item [\verb"debug":]
397: full tracing of events
398: \item [\verb"all":]
399: log all events
400: \end{describe}
401: For example to have all errors written to the file you will need
402: \begin{quote}\footnotesize\begin{verbatim}
403: dsaplog level=fatal level=exceptions
404: \end{verbatim}\end{quote}
405: \item [\verb"dlevel":]
406: Do not log the specified log level, this is the opposite of the above
407: entry.
408: \item [\verb"dflags"/\verb"sflags":]
409: The flags associated with the log may be set (with \verb"sflag")
410: or unset (with \verb"dflag"). The allowable options are:
411: \begin{describe}
412: \item [\verb"close":]
413: close the log after each entry
414: \item [\verb"create":]
415: create the log file if it doesn't exist
416: \item [\verb"zero":]
417: truncate the file when it gets too big
418: \item [\verb"tty":]
419: copy the logging information to the users tty
420: \end{describe}
421: \end{describe}
422: An example might be:
423: \begin{quote}\footnotesize\begin{verbatim}
424: dsaplog level=notice size=30 file=quipulog dflags=close
425: \end{verbatim}\end{quote}
426: This says log events at ``notice'' level, into the file ``quipulog'', do not
427: let the file grow larger than 30Kbytes, and do not close the file
428: after each logging message.
429:
430: \item [\verb"stats":] Used to control the level of statistical logging
431: (parameters as for \verb+dsaplog+ above).
432:
433: \item [\verb"local\_DIT":]
434: The argument is a distinguished name. When some User Interfaces start, you
435: will be automatically moved to this position in the DIT.
436:
437: \item [\verb"oidformat":]
438: Defines how object identifiers should be printed.
439: Use one of:
440: \begin{quote}\small\begin{verbatim}
441: oidformat short
442: \end{verbatim}
443: \end{quote}
444: to print in short local key form, e.g.,
445: \begin{quote}\small\begin{verbatim}
446: Country
447: \end{verbatim}\end{quote}
448: or,
449: \begin{quote}\small\begin{verbatim}
450: oidformat long
451: \end{verbatim}
452: \end{quote}
453: to print in long object identifier form, e.g.,
454: \begin{quote}\small\begin{verbatim}
455: joint.ds.attributeType.country
456: \end{verbatim}\end{quote}
457: or,
458: \begin{quote}\small\begin{verbatim}
459: oidformat numeric
460: \end{verbatim}
461: \end{quote}
462: to print in numeric form, e.g.,
463: \begin{quote}\small\begin{verbatim}
464: 2.5.4.6
465: \end{verbatim}\end{quote}
466:
467: \item [\verb"photo":]
468: The argument is has two parts, a ``terminal type'' such as
469: ``sun'' or ``xterm'', the second is the name of the process that should
470: handle displaying of photographs, for example
471: \begin{quote}
472: photo xterm Xphoto
473: \end{quote}
474: tells the DUA to call the process Xphoto to handle photograph attributes if
475: the user is on a terminal of type ``xterm''.
476: Handling photographs is described more fully in Section~\ref{dua:photo}.
477:
478: \item [\verb"quipurc":]
479: If the argument has the value \verb"on", then a program called
480: \pgm{dishinit} will be run every time a user without a ``.quipurc''
481: file tries to access the directory. \pgm{dishinit} is discussed
482: in Section~\ref{dishinit}.
483:
484: \item [\verb"sizelimit":]
485: Defines the maximum number of entries a successful list or search should
486: return.
487: For example,
488: \begin{quote}\small\begin{verbatim}
489: sizelimit 20
490: \end{verbatim}\end{quote}
491: sets the DAP default service control ``sizelimit'' to be 20 entries.
492: \end{describe}
493:
494: \chapter {Configuring a DSA}
495:
496: This Chapter discusses how to configure a QUIPU DSA.
497: We recommend that you get a DUA running before you try to
498: get a DSA working.
499:
500: \section{Basic Formats and Structures}
501:
502: All of the information a DSA requires is
503: stored on disk and is text structured. This includes
504: various files (described later), and the local DIT database itself.
505: A complete BNF description of the files
506: is given in Appendix~\ref{bnf} on page~\pageref{bnf}.
507:
508: \subsection {Entry Data Block}
509: \label{edb}
510: A key component of the Directory database is the Entry Data Block, which is
511: described fully in \cite{QUIPU.Design}.
512: Figure \ref{example_edb} shows an example EDB \index{EDB} file containing two ``person''
513: entries.
514:
515: \begin{figure}
516: \smaller
517: \begin{verbatim}
518: MASTER
519: 19891025113003Z
520: CN= Colin Robbins
521: CN= Colin John Robbins
522: Phone= +44-1-387-7050 ext 3683
523: Surname= Robbins
524: Room= G10
525: Userid= crobbins
526: userClass= csstaff
527: rfc822Mailbox= [email protected]
528: Photo= {FILE}crobbins.photo
529: objectClass =thornPerson & quipuObject
530: acl=others # none # attribute # photo
531: acl=self # read # attribute # photo
532:
533: CN= Steve Kille
534: CN= Steve E. Kille & Stephen Kille
535: Phone= +44-1-387-7050 ext 7294
536: Surname= Kille
537: objectClass = thornPerson & quipuObject
538: Room= G24
539: Userid= steve
540: userClass= csstaff
541: rfc822Mailbox= [email protected]
542: \end{verbatim}
543: \caption{Example EDB File}
544: \label{example_edb}
545: \end{figure}
546:
547:
548: An EDB file contains a header, followed by a sequence of entries.
549:
550: The header consists of two lines of text, the first must contain the string
551: ``\verb"MASTER"'', ``\verb"SLAVE"'' or ``\verb"CACHE"'',
552: which indicates whether the data in the EDB
553: file represents the authoritative \verb"MASTER" data, a \verb"SLAVE"
554: copy of the data, or \verb"CACHE"d entries.
555: The next line is a string that describes the version of the EDB. Every
556: time the EDB is altered, the version\index{version - of an EDB} number
557: should be changed, so that
558: \verb"SLAVE" EDBs elsewhere will be automatically updated.
559: When a DSA alters an EDB file, it writes the current (UTC) time in string
560: format as the version string.
561:
562: Following the header are a sequence of blank line separated entries.
563: An entry consists of a set of attributes. The first line is
564: the Relative Distinguished Name
565: \index{RDN} (RDN) of the entry.
566:
567: \subsection{Object Class attribute}
568: Of the attributes an entry may have, the ``objectClass''\index{objectClass attribute}
569: attribute is one of the most important from the configuration point of view.
570: It defines the set of mandatory and optional attributes that must and may be
571: present in the entry.
572: For example, the object class ``person'' insists that there is a ``surname''
573: attribute, and there may optionally be a ``telephone number'' attribute.
574:
575: QUIPU knows about all the standard object classes and attributes, some of
576: those defined by the THORN\index{thorn} project (see Section~\ref{thorn:na}) and
577: those defined by QUIPU itself (see Appendix~\ref{naming}).
578: The full set of object classes and attributes a DSA knows about is
579: defined by the ``oidtables'' which are explained in Section~\ref{oidtables}.
580:
581: An entry can belong to more that one object class.
582: For example, an entry representing an organisation might have the following
583: object class attribute:-
584: \begin{quote}\small\begin{verbatim}
585: objectClass = organization & quipuNonLeafObject
586: \end{verbatim}\end{quote}
587: And a person within that organisation might use the following object class
588: definition:-
589: \begin{quote}\small\begin{verbatim}
590: objectClass = organizationalPerson & quipuObject & thornPerson
591: \end{verbatim}\end{quote}
592: Every entry in a QUIPU DSA should belong to either the ``\verb"quipuObject"''
593: or ``\verb"quipuNonLeafObject"'' object classes, as this allows
594: attributes the DSA needs to be added to an entry.
595:
596: Further, object classes posses the notion of
597: \verb"class inheritance".
598: This means that an object class can be defined as a ``subclass'' of
599: a previously defined object class with additional refinements.
600: As a subclass,
601: the newly defined object ``inherits'' all the semantics of its
602: superclass,
603: in addition to having additional semantics.
604:
605: For example,
606: the Directory defines an object class called \verb"person".
607: This object class defines the attributes which a person in
608: the real world might have.
609: It may be useful to refine this somewhat to talk about persons
610: who have network access.
611: So, we need a new object class, e.g., \verb"netPerson".
612: This can be defined in a straight-forward fashion:
613: \begin{quote}
614: The object class \verb"netPerson" is a subclass of the object class
615: \verb"person" which {\em may\/} contain an additional attribute,
616: \verb"netMailbox".
617:
618: The syntax of an \verb"netMailbox" is a simple string of printable
619: characters which is not case sensitive when performing comparisons.
620: \end{quote}
621:
622: It is a Quipu requirement that every entry that is not a leaf of the DIT
623: should belong to the object class
624: ``\verb"quipuNonLeafObject"''.
625:
626: This class has one mandatory attribute:
627: \begin{describe}
628: \item[masterDSA:]\index{masterDSA attribute}
629: identifies the Directory entity which is responsible
630: for maintaining the MASTER EDB for the children of
631: this entry.
632: The value is a Distinguished Name.
633: \end{describe}
634: There is typically a single MASTER for a particular entry in the tree.
635: Hence, this value is usually single-valued.
636: When an entry is to be modified,
637: the Directory must contact the entity responsible for the MASTER EDB for
638: that entry in order to perform the modification.
639:
640: This class has two optional attributes:
641: \begin{describe}
642: \item[slaveDSA:]\index{slaveDSA attribute}
643: identifies any Directory entities which have
644: authoritative copies of the EDB for the children
645: of this entry.
646: The value is one or more Distinguished Names.
647:
648: \item[treeStructure:]\index{treeStructure attribute}
649: identifies the object classes which may exist
650: immediately below this entry.
651: The value is one or more object classes.
652: See Section~\ref{quipu:schema} for full details
653: of how to set this attribute.
654: \end{describe}
655: Since a fundamental assumption of the Directory is that reads (queries)
656: occur much more frequently than writes (updates),
657: it is common to have several entities containing authoritative copies of an
658: EDB.
659: By keeping copies locally,
660: queries can be answered with less latency.
661:
662: \subsection {Database Structure}
663:
664: All the information held by the Directory in its in-core database, is loaded
665: from disk when the Directory starts.
666: The data on disk is held in a \unix/ tree of EDB files that map
667: the DIT.
668: At every level in the DIT for which the DSA holds data, there is a single
669: file called \file{EDB}\index{EDB file}.
670: If an entry defined in an \file{EDB} file has
671: children, the \file{EDB} file for the children will be found in a
672: sub-directory whose name is the string encoded Relative
673: Distinguished Name of the entry.
674: For example, if an \file{EDB} file has an entry whose RDN is
675: ``ou= Computer Science'', then if the entry ``ou= Computer Science'' has children and is stored locally,
676: it can be found in the file \file{ou=Computer Science/EDB} relative to the current directory.
677: NOTE that the case sensitivity of the sub-directory naming is one of the
678: few areas within QUIPU where string matching is case sensitive.
679: The case of the attribute type is taken from the definition of the attribute
680: in the oid tables, whereas the case of the attribute value is the same as
681: that found in the EDB file.
682:
683: When an entry is modified, the modified \file{EDB} file is re-written to
684: disk. The old \file{EDB} is renamed \file{EDB.bak} to provide
685: a back-up.
686:
687: \subsection{Long Distinguished Names}
688: \label{EDB:mapped}
689: There is a problem with the above method for naming \unix/ sub directories
690: with some versions of \unix/ --- particularly System~V.
691: In these systems directory names are limited in length.
692:
693: To allow for this, \verb"any" distinguished name can be given a mapping
694: name, which will be used as the \unix/ sub-directory name.
695: For example the entry for ``o=University College London'', may be mapped and
696: stored in the file \file{UCL/EDB}.
697: The mapped names are specified in a file \file{EDB.map}\index{EDB.map file},
698: the syntax of which is:
699: \begin{quote}\begin{verbatim}
700: <Distinguished Name> `#' <Mapped name>
701: \end{verbatim}\end{quote}
702: so for the example used above the file will contain:
703: \begin{quote}\begin{verbatim}
704: o=University College London#UCL
705: \end{verbatim}\end{quote}
706:
707: If a name is not found in the mapping file, then the long directory name will
708: be used.
709:
710: When a DSA needs to create a sub-directory (e.g after an add operation)
711: it will use the relative distinguished name for each subdirectory,
712: unless the name is longer than the maximum number of allowed characters
713: (usually 15), in which case it will generate a shorter mapped name.
714:
715: \section {Setting up an Initial DSA}
716:
717: These instructions are assuming that you are trying to set up a DSA with the
718: following characteristics:-
719: \begin{itemize}
720: \item It is the first DSA in an Organisation
721: \item It is not the first DSA in the Country
722: \item It holds a copy of the root EDB
723: \end{itemize}
724:
725: This is found in the example:-
726: \begin{quote}
727: \file{others/quipu/quipu-db/organisation}
728: \end{quote}
729:
730: There are two other examples which might also be used as illustrations for
731: national DSAs and organisational DSAs not holding a copy of the root EDB.
732: These are in :-
733: \begin{quote}
734: \file{others/quipu/quipu-db/national}
735: \end{quote}
736: and
737: \begin{quote}
738: \file{others/quipu/quipu-db/non-root}
739: \end{quote}
740:
741: Note that if you are going to be running a DSA in the United States,
742: then you should skip this section and refer to the document
743: \cite{NYSER.Admin},
744: which is provided in the ISODE documentation set
745: (look in the source tree area for the directory \file{doc/whitepages/admin/}).
746: This document describes turn-key installation mechanisms for DSAs in the
747: United States.
748:
749: To start a DSA with one of these example databases
750: go into the relevant database directory and type:-
751: \begin{quote}\begin{verbatim}
752: $(SBINDIR)ros.quipu -t ./quiputailor
753: \end{verbatim}\end{quote}
754:
755: The \tt -t\rm \ flag tells Quipu to use the tailor file \file{./quiputailor}
756: rather than the default file (\file{quiputailor} in the ISODE \verb"ETCDIR"
757: directory).
758:
759: This will cause the DSA to print some logging information onto the screen,
760: followed by the message
761: \begin{quote}\begin{verbatim}
762: DSA c=GB@cn=toucan has started on localHost=17003
763: \end{verbatim}\end{quote}
764:
765: \begin{figure}
766: \smaller
767: \begin{verbatim}
768: cn=Toucan
769: presentationAddress= localHost=17003
770: edbinfo= #cn=giant tortoise##
771: description= Demonstration slave-root DSA
772: description= Bird with large colourful bill.
773: objectClass= quipuDSA & quipuObject
774: manager= c=GB@o=University College London@ou=Computer Science@cn=Colin Robbins
775: acl= self # write # attributes # acl $ userPassword
776: acl= others # compare # attributes # acl $ userPassword
777: userPassword = toucan
778: quipuVersion= 6.0 Distribution
779: supportedApplicationContext= QuipuDSP & X500DSP & X500DAP
780: \end{verbatim}
781: \caption{Example DSA Entry}
782: \label{DSA:Toucan}
783: \end{figure}
784:
785: The default setup assumes you have TCP/IP access and starts a DSA on the IP
786: address of the local machine (127.0.0.1). If you do not have TCP/IP, you
787: will need to change the address the DSA will attempt to listen on.
788: This is done by editing the file
789: \begin{quote}
790: \file{others/quipu/quipu-db/organisation/c=GB/EDB}
791: \end{quote}
792: The first entry in this file is the entry for a DSA called
793: ``c=GB@cn=Toucan'', which is the name of the DSA we are trying to start (as
794: defined by the ``mydsaname'' entry in quiputailor).
795: The entry is shown in Figure~\ref{DSA:Toucan}.
796: The attribute \verb"presentationAddress" defines the address that the DSA is
797: going to listen to the network on.
798: If you need to listen on a different address, you should change the value of
799: the attribute to the address you want to listen on.
800: For more details of address see \volone/ of this manual and
801: \cite{String.Addresses}, an example of an X.25 address is given below:
802: \begin{quote}\begin{verbatim}
803: presentationAddress= Int-X25(80)=23421920030045
804: \end{verbatim}\end{quote}
805:
806: Having started your DSAs you should be able to connect to it by
807: invoking \pgm{dish}. If you are using the default DSA address, and are
808: using the default \file{dsaptailor} file, then invoking \pgm{dish}
809: without arguments is sufficient.
810: If you are not using the default address or ``dsaptailor'' file, then you
811: will need to edit \file{dsaptailor} in the ISODE \verb"ETCDIR" directory.
812: You should add an entry
813: \begin{quote}\begin{verbatim}
814: dsa_address toucan <presentation address>
815: \end{verbatim}\end{quote}
816: Note that \verb+<presentation address>+ should have {\em exactly} the same
817: value as
818: the \verb+presentationAddress+ attribute in the DSAs entry in the EDB file.
819: Now to contact the DSA use
820: \begin{quote}\begin{verbatim}
821: dish -c toucan
822: \end{verbatim}\end{quote}
823:
824:
825: Once connected to the DSA, try issuing the
826: command:-
827: \begin{quote}\small\begin{verbatim}
828: list "@c=GB@o=University College London@ou=Computer Science"
829: \end{verbatim}\end{quote}
830: You should get a list of four names
831: back:-
832: \begin{quote}\begin{verbatim}
833: 1 commonName=Colin Robbins
834: 2 userid=quipu%commonName=Colin Robbins
835: 3 commonName=Steve Kille
836: 4 commonName=Michael Roe
837: \end{verbatim}\end{quote}
838: If this happens you have a working DSA.
839: (The entry numbered 2, is an example of an RDN with multiple values !)
840:
841: \subsection{Setting up YOUR DSA}
842: The examples are tailored to start a DSA called ``toucan'',
843: and will be sufficient to get an example DSA started,
844: but this will not be of much use when you want to start adding you own data.
845: To allow other DSA to connect to you, you will need a new unique
846: distinguished name for
847: your own DSA.
848: Section~\ref{dsa:connect} describes how to choose a name for your DSA and set
849: up the connections.
850:
851: A DSA needs to find the entry associated with its own name, it will generally
852: be able to find this in the local database (the entry ``cn=toucan''
853: in the file \file{quipu-db/organisation/c=GB/EDB} for example).
854:
855: Having located its own entry, a DSA will know its network
856: address by looking at the \verb+presentionAddress+ attribute,
857: hence it can start listening for operations.
858:
859: But first it must load the database.
860: In its own entry it will have a \verb"edbInfo" attribute, this
861: describes which EDBs the DSA is expected to hold.
862: The format of the \verb"edbInfo" \index{edbInfo attribute} attribute is described fully in
863: Section~\ref{slave_update}, but essentially the first parameter
864: supplied says ``load this EDB''. Thus the attribute
865: \begin{quote}\begin{verbatim}
866: edbInfo = ##
867: edbInfo = c=US@o=The Wollongong Group ##
868: edbInfo = c=GB ##
869: \end{verbatim}\end{quote}
870: requests that the EDB files
871: \begin{quote}
872: \file{quipu-db/EDB}
873: \end{quote}
874: (signified by no data before the first `\verb+#+' sign),
875: \begin{quote}
876: \file{quipu-db/c=US/o=The Wollongong Group/EDB}
877: \end{quote}
878: and
879: \begin{quote}
880: \file{quipu-db/c=GB/EDB}
881: \end{quote}
882: are loaded.
883:
884: There are a few other important attributes your DSAs entry should have, the ``toucan''
885: entry in Figure~\ref{DSA:Toucan} gives examples of the other attributes.
886: They are briefly described below.
887: \begin{describe}
888: \item[description] A Textual message describing the DSA, and the wildlife!
889: \item[quipuVersion] This should contain the version number of the
890: Quipu software you are using. This can be found by using the dish
891: command \verb+squid -version+.
892: \item[manager] The DN of the manager of the DSA, this user will not be blocked by
893: access control when modifying the local database over DAP.
894: \item[supportedApplicationContext] This should always have the value
895: \begin{quote}\begin{verbatim}
896: QuipuDSP \& X500DSP \& X500DAP
897: \end{verbatim}\end{quote}
898: for this version of Quipu.
899: It is used by remote DSAs to decide which protocols your
900: DSA supports, and
901: thus how best to contact it.
902: \end{describe}
903:
904: To connect a DUA to this DSA,
905: try typing \verb"dish", the DUA will try to contact the default DSA.
906:
907: If you have changed the address of the default DSA
908: (by modifying the ``presentationAddress'' attribute of the DSAs entry)
909: you will need to modify the
910: \verb"dsa_address" variable in the file \file{dsaptailor} to tell the DUAs
911: your DSAs address.
912: If you add
913: \begin{quote}\begin{verbatim}
914: dsa_address mydsa <the presentation address>
915: \end{verbatim}\end{quote}
916: to your \file{dsaptailor} file, then
917: \begin{quote}\begin{verbatim}
918: dish -c mydsa
919: \end{verbatim}\end{quote}
920: should connect you to your new DSA.
921:
922: Section~\ref{adding_data} describes how you can add data to you DSA by
923: extending the supplied textual database to include your
924: own data
925: or by sending data to the Directory via the DUA modify operations.
926: This may be done independently from connecting to the global directory.
927:
928: \section {Tailoring}\label{dsa:tailor}
929:
930: On start up the DSA first consults a run time tailor file \index{quiputailor}
931: (the default DSA tailor file is called \file{quiputailor} in the ISODE
932: \verb"ETCDIR" directory, but can be
933: changed with a \verb"-t" parameter to \pgm{ros.quipu};
934: consult \man quipu(8c) for details),
935: which indicates such things as:
936:
937: \begin{itemize}
938: \item
939: name of the DSA
940: \item
941: location of the database
942: \item
943: location and level of the logs that the DSA will produce.
944: \item
945: location of any other DSAs for initial bootstrap
946: \end{itemize}
947:
948:
949: The format is identical to the DUA tailor file
950: described in Section~\ref{dua:tailor}, with the addition of the
951: following options:
952: \begin{describe}
953: \item [\verb"mydsaname":]
954: The distinguished name of the DSA.
955: For example,
956: \begin{quote}\small\begin{verbatim}
957: mydsaname CN=axolotl
958: \end{verbatim}\end{quote}
959: declares this DSA to have the common name of \verb"axolotl".
960:
961: \item [\verb"parent":]
962: This entry consists of a name/address pair of a parent DSA,
963: and is needed only for DSAs not holding the root EDB.
964: The DSA referenced needs to hold a Master or Slave copy of an EDB
965: higher up in the DIT than the highest locally held EDB.
966: If more than one \verb"parent" tailor entries are found, the DSA
967: will chose which DSA to contact. The algorithm for making this
968: choice has not been fully explored yet
969: (currently, the first entry is always used, if this fails the second\ldots).
970: For example,
971: \begin{quote}\small\begin{verbatim}
972: parent C=GB@CN=vicuna Internet=vs1.ucl.cs.ac.uk+50987
973: \end{verbatim}\end{quote}
974: \index{presentation addresses}
975: declares the parent DSA to be ``C=GB@CN=vicuna'' at the
976: indicated address.
977:
978: \item [\verb"stats":]
979: The value has the same format as the \verb"dsaplog" entry described in
980: Section~\ref{dua:tailor}, and is used to control the level of
981: DSA statistical logging.
982:
983: \item [\verb"treedir":]
984: Defines the directory in which the textual database is stored.
985: For example,
986: \begin{quote}\small\begin{verbatim}
987: treedir /usr/etc/quipu-db/
988: \end{verbatim}\end{quote}
989: declares the directory \file{/usr/etc/quipu-db/} to contain the local
990: part of the Directory Information Tree.
991:
992: \item [\verb"update":]
993: The value ``on'' tells the DSA to update SLAVE EDB files when it starts up.
994: See section \ref{slave_update} for further details, by default
995: this parameter is ``off''.
996:
997: \item [\verb"searchlevel":] Defines the level from which users will be able
998: to search the DIT --- default 2 (e.g organisations).
999: If they try to search from higher up, a ``unwilling to perform'' service
1000: error will result.
1001:
1002: \item [\verb"lastmodified":] If `\verb"off"', `\verb+lastmodifiedby+'
1003: attributes will not be added by the DSA when an entry is altered.
1004:
1005: \item[\verb"readonly":] Bring the DSA up in ``read only'' mode --- that is
1006: prevent user modification. Slave updates are still allowed.
1007:
1008: \item [\verb"dspchaining":]
1009: The value ``on'' tells the DSA to chain DSP requests to other DSAs
1010: if necessary.
1011: The default mode of operation is to return a DSA referral.
1012: The full set of issues deciding whether to use chaining or referrals
1013: is discussed in the QUIPU design document (\cite{QUIPU.Design}), and
1014: \cite{QUIPU.Navigate}.
1015:
1016: \item [\verb"adminsize":] The administrative size limit for use on search
1017: and list operations.
1018:
1019: \item[\verb"admintime":] The maximum time allow to spend on a user query.
1020:
1021: \item[\verb"cachetime":] The length of time to keep / use ``cached''
1022: information.
1023:
1024: \item[\verb"conntime":] The length of time to hold a unused connection open.
1025:
1026: \item[\verb"nsaptime":] The length of time to wait before deciding a
1027: connection can not be established for a given NSAP.
1028:
1029: \item[\verb"retrytime":] The length of time before deciding it is worth
1030: attempting to connect to a DSA that could not be contacted earlier.
1031:
1032: \item[\verb"slavetime":] The length of time between attempting to update
1033: slave EDB files.
1034:
1035: \item[\verb"preferdsa":] When a DSA has creates a reference to other DSAs it
1036: tries to discriminate between and chose the "best" DSA to contact.
1037: This variable gives you a handle on controlling the choice. For example the
1038: lines
1039: \begin{verbatim}
1040: preferDSA c=GB@cn=Vicuna
1041: preferDSA cn=Giant Tortoise
1042: \end{verbatim}
1043: tells the DSA to use either ``c=GB@cn=Vicuna'' or ``cn=Giant Tortoise'' in
1044: preference to any other DSA. Further, use the DSA ``c=GB@cn=Vicuna'' rather than
1045: ``cn=Giant Tortoise'' if possible.
1046:
1047: \item[\verb"cainfo":] For authentication.
1048:
1049: \item[\verb"secretkey":] For authentication.
1050:
1051: \item[\verb"bindwindow":] For authentication.
1052:
1053: \item [\verb"isode":]
1054: The argument is an \verb"isodevariable" \verb"isodevalue" pair as would
1055: be found in \file{isotailor}. This is used to ``override'' isotailor
1056: settings.
1057: \end{describe}
1058:
1059: \subsection {Tailoring a Running DSA}
1060: \label{dsa:mgmt}
1061:
1062: The tailoring described above is performed when the DSA is
1063: booted. It is sometimes useful to alter the tailor settings
1064: after the DSA has started without having to bring
1065: the DSA down and rebooting. This can be done by via
1066: the special ``{\bf dsacontrol}'' command in the \man dish(1c) program
1067: as described in Section~\ref{dua:mgmt} on page~\pageref{dua:mgmt}.
1068:
1069: The DUA invokes a modify operation, with a
1070: single special attribute ``dSAControl'' defined in \cite{QUIPU.Design}.
1071: The DSA recognises the special attribute, and provided you are
1072: bound as the manager of the DSA, passes the attribute value to the
1073: appropriate routine.
1074:
1075: \cite{QUIPU.Design} describes this process in full.
1076:
1077: \section {Connection to Other DSAs}
1078: \label{dsa:connect}
1079:
1080: All QUIPU DSAs should be connected. This section describes how you should
1081: configure your DSA to connect to other DSAs in order
1082: to read the data not held locally.
1083: Section \ref{dsa:global} describes how to make sure that other DSAs can access your DSA
1084: (See Appendix~\ref{dsa:sites} on page~\pageref{dsa:sites} for a partial list
1085: of registered QUIPU DSAs.)
1086:
1087: A dynamic approach is used to bootstrap a new DSA.
1088: The ``global master'' DSA is administered at UCL,
1089: and other DSAs should be configured in relation to this one.
1090:
1091: Every DSA needs to know the distinguished name and
1092: presentation address of one
1093: or more DSA's nearer to, or actually holding, the root EDB. This parameter
1094: is supplied in the tailor file (see Section~\ref{dsa:tailor})
1095: under the name \verb"parent".
1096: This information is used by the QUIPU DSA when it can not find a DSAs entry
1097: in the local database, or can find no pointers in the local database to the
1098: whereabouts of the data.
1099: If you hold a \verb"SLAVE" copy of the root EDB, then your
1100: parent should be a DSA that is ``closer'' to the MASTER copy of the root
1101: EDB.
1102:
1103: The example databases are set up with default parents (defined in the file
1104: \file{quipu-db/organisation/quiputailor})
1105: To see if your DSA can contact the ``parent'', connect to
1106: the local test (root holding) DSA using \verb"dish", and type
1107:
1108: \begin{quote}\begin{verbatim}
1109: list @
1110: \end{verbatim}\end{quote}
1111:
1112: This will list the locally held root, now try
1113:
1114: \begin{quote}\begin{verbatim}
1115: list @ -dontusecopy
1116: \end{verbatim}\end{quote}
1117:
1118: This will try to connect to the parent DSA.
1119: If it is successful, there should be a lot more data returned.
1120:
1121: Care should be taken in choosing the parent
1122: DSA. If all DSAs have the same parent
1123: DSA then that DSA will become overloaded.
1124: Typically each site will have several DSAs. One of these should
1125: be the default parent for all the other DSAs, with only one DSA having a
1126: default parent outside the site.
1127:
1128:
1129: When ``walking down'' the DIT, QUIPU needs access to information to tell it
1130: on which DSA the next level of the DIT is stored.
1131: To do this each non-leaf entry MUST have a ``masterDSA''\index{masterDSA attribute}
1132: or ``slaveDSA''
1133: attribute. The value of the attribute is the distinguished name of the DSA
1134: holding the next level of the DIT (it may be your own DSA name, if you hold
1135: the next level as well). If there is no such attribute, QUIPU assumes the
1136: entry is a leaf.
1137: If the information required is not held in the local DSA then QUIPU
1138: chains the request to the named DSA or returns a referral
1139: --- depending upon the mode of operation
1140: (The named DSAs entry is read to establish the
1141: address --- this may mean a connection to another DSA
1142: in-order to read the entry).
1143:
1144: Once you have started your DSA, you should try to connect to other DSAs
1145: using the \verb"DISH" program (this connects to the local DSA, which will
1146: chain requests to other DSAs). Try listing the children of
1147: organisations other than yourself, to find which organisations are connected,
1148: try listing your countries children.
1149:
1150: \subsection {Choosing a Name for Your DSA}
1151: \label{dsa:naming}
1152: Every QUIPU DSA MUST have an entry in the DIT, hence
1153: your DSA will need a unique distinguished name.
1154: The name ``cn=Toucan''
1155: given in the example databases is not unique.
1156: There are two aspects to consider in choosing a name for you DSA.
1157:
1158: This entry is used by other DSAs to identify you DSA, and so is needed if
1159: other DSAs are going to be able to see your DSA.
1160:
1161: Firstly, it is a QUIPU convention that DSAs should be named
1162: after endangered South
1163: American wildlife, and that the entry for the DSA should contain a
1164: description of the animal or plant in question.
1165: Some examples are shown in Table~\ref{wildlife}.
1166: A more comprehensive list can be found in the IUCN's ``Red Book''
1167: \cite{IUCN.Mammal}.
1168:
1169: Secondly, the entry for your DSA must be visible to other DSAs who do not know
1170: how to contact your DSA.
1171: So, the MASTER copy of your DSAs own entry must be held at least one level higher up
1172: in the DIT than the part of the DIT it holds as \verb"MASTER" data.
1173: For example the DSA which holds
1174: ``c=GB @ o=University College London @ ou=Computer Science'',
1175: must be held at the
1176: ``c=GB @ o=University College London'' level
1177: (e.g. ``c=GB @ o=University College London @ cn=wombat'') or above.
1178: Such naming also helps prevent loops as described more fully in
1179: \cite{QUIPU.Design}.
1180:
1181: In practice DSAs should be named fairly high up the tree.
1182: Each country should have at least two DSAs named at the root level.
1183: Each Organisation should have at least two DSA named at the national level.
1184:
1185: \tagtable[tp]{q-1}{Endangered South American Wildlife}{wildlife}
1186:
1187: You should use \pgm{dish} to find out if the name you want is already taken.
1188: For example,
1189: if you are creating a DSA for an organization in Great Britain,
1190: you might use:
1191: \begin{quote}\small\begin{verbatim}
1192: % dish -c "Giant Tortoise"
1193: Welcome to Dish (DIrectory SHell)
1194: Dish -> search @c=GB -filter objectClass=dsa
1195: \end{verbatim}\end{quote}
1196: This will print out the list of names already in use.
1197:
1198: Having chosen a name, you will need to tell your DSA its name, and
1199: make sure it can find an EDB file for its own entry.
1200:
1201: A DSA finds it own name from the ``mydsaname'' variable defined in the file
1202: \file{quiputailor} (see Section~\ref{dsa:tailor} for details).
1203: An example \verb"quiputailor" entry would be:-
1204: \begin{quote}\small\begin{verbatim}
1205: mydsaname: "c=GB@cn=a dsa name"
1206: \end{verbatim}\end{quote}
1207: Having read this name from \verb"quiputailor", a DSA will try to find
1208: the corresponding entry.
1209: The process for doing this is complex, and is
1210: described in full in Section~\ref{dsa:starting}. Essentially the
1211: DSA needs to find the EDB file holding the entry, and hence you MUST
1212: supply it, if supplied correctly it will be found.
1213:
1214: If you hold the EDB that the entry should be in, simply
1215: make sure the entry is in that EDB and then it will be found.
1216: If you do not hold, and do not want to hold the EDB in which your
1217: DSA is named (e.g., your DSA is called \verb"c=GB@cn=toucan" but
1218: you do not hold the EDB \verb"c=GB"), then you should (normally)
1219: supply a cached copy of the EDB which contains only the
1220: entry for the DSA, and not all the others entries the full EDB would have.
1221: If you do not supply it, your DSA will have to rely on others DSAs before it
1222: can start.
1223:
1224: \subsection {Connection to the Global Directory}\label{dsa:global}
1225:
1226:
1227: To enable the global directory to connect to you, you must contact the
1228: manager of the DSA immediately above the node you want to added under.
1229: Supply them with the entry for your DSA, and the top level
1230: entry of the sub-tree
1231: you want to hold.
1232: For example, to add the organisation ``o=foobar'' below ``c=US'',
1233: contact the manager of the DSA holding ``c=US'' as a MASTER, giving them the
1234: entry for ``c=US@o=foobar'' and ``c=US@cn=foobar\_dsa'', assuming
1235: ``c=US@cn=foobar\_dsa'' is the name of your DSA (see Section~\ref{dsa:naming}
1236: on naming a DSA).
1237:
1238: By convention,
1239: to find out who administers the master EDB for a particular node,
1240: run the \man dish(1c) program and retrieve the \verb"manager" attribute
1241: from the entry for the DSA holding that node.
1242:
1243: You can then find a mail address by looking that person up in the directory.
1244:
1245: The following example shows you how to get the mail address of the
1246: manager of the c=GB subtree.
1247:
1248: \begin{verbatim}
1249: % dish
1250: Welcome to Dish (DIrectory SHell)
1251: Dish -> showentry @c=GB -type masterDSA
1252: masterDSA - cn = Giant Tortoise
1253: Dish -> showentry "@cn=Giant Tortoise" -type manager
1254: manager - countryName=GB
1255: organization=University College London
1256: organizationalUnit=Computer Science
1257: commonName=Colin Robbins
1258: Dish -> moveto "@c=gb@o=University College London @
1259: ou=Computer Science @ cn=Colin Robbins"
1260: Dish -> showentry -type rfc822Mailbox
1261: rfc822Mailbox - [email protected]
1262: Dish -> quit
1263: %
1264: \end{verbatim}
1265:
1266: If you want to add data to the root node of the ``global tree''
1267: (e.g., a new country) then you will probably want a copy of the
1268: ROOT EDB (or you might want a copy for other reasons).
1269: The master can be accessed via the FTAM service at UCL as
1270: file \file{$<$PUB$>$/masterEDB}.
1271: (The address of this service is found in the {\bf Preface\/} of this volume.)
1272: If you are unable to access the FTAM service,
1273: a copy of the master can also be obtained from the {\em quipu-support}
1274: address given in Section~\ref{quipu:support}.
1275: Having obtained the root EDB, add the new entries, and mail the new
1276: information to the {\em quipu-support} address given in
1277: Section~\ref{quipu:support}.
1278:
1279: To keep this EDB upto date you should use the ``getEDB''
1280: operation discussed in Section~\ref{slave_update} (this can also be used to
1281: get the EDB in the first place).
1282:
1283: When you think you are connected to the ``global DIT'',
1284: you should test that you are. To do this use \verb"dish" to connect
1285: to a DSA higher than you in the DIT (using the \verb"-call" flag as described
1286: in Section~\ref{dua:tailor}, then see if you can navigate to your
1287: own part of the DIT, and look at your data --- if so
1288: then the DSA is connected.
1289:
1290: \section {Adding more Data}
1291: \label{adding_data}
1292:
1293: Having got a DSA started, and connected to the global DIT, you should start
1294: to add lots of data.
1295: There are many sources of such data, and with just a relatively small amount
1296: of effort this data can be added to the directory.
1297:
1298: There are two ways such data can be added.
1299: First of all you can use one of the DUA programs to bind to the DSA as the
1300: DSA manager, and send data to the directory via the ``add'' and ``modify''
1301: operations (see Sections~\ref{dish:add} and \ref{dish:modify}).
1302: This is probably the best way to add relatively small amounts of data,
1303: or make minor changes to the data.
1304:
1305: To add a large amount of data (i.e., the initial creation of a
1306: large database) if is probably easiest to write a shell script using \unix/
1307: tools such as \verb"awk" and \verb"grep" to create the EDB files directly.
1308: In the next version of the software there will be tools to facilitate this.
1309:
1310: When adding data for users it is advisable to allocate a ``userPassword''.
1311: \index{user password attribute}
1312: Chapter~\ref{Security} describes how to do this.
1313:
1314: \subsection {More on Object Classes}
1315: The only object class discussed so far is the ``quipuDSA'' objectclass.
1316: When you start to add data, you will probably want to add information about
1317: people, sub-divisions of your organisation, and other application entities.
1318: This Section introduces some of the more important object classes, and the
1319: attributes they may contain.
1320: In many cases, only the attribute type is specified, for details of typical
1321: values and the value syntax you should read Chapter~\ref{syntaxes}.
1322:
1323: As already discribed, every entry in the DIT must belong to the object
1324: class \verb+top+, which means every entry must have an \verb+objectClass+
1325: attribute.
1326: Also, every entry in the Quipu DIT should belong to either the
1327: \verb+quipuNonLeafObject+ or \verb+quipuObject+.
1328:
1329: \subsubsection{Person}
1330: This is a base object class used to represent a person.
1331:
1332: There are two mandatory attributes:
1333: \begin{describe}
1334: \item[commonName:]
1335: which gives a (potentially ambiguous) name for
1336: the person.
1337: The value of this attribute is a string usually
1338: containing the person's first and last names; e.g.,
1339: \begin{quote}\small\begin{verbatim}
1340: Marshall Rose
1341: \end{verbatim}\end{quote}
1342: This attribute is usually multi-valued, containing
1343: variations on the first, middle, and last names; e.g.,
1344: \begin{quote}\small\begin{verbatim}
1345: Colin Robbins
1346: Colin John Robbins
1347: Colin J. Robbins
1348: \end{verbatim}\end{quote}
1349: Generally this attribute will supply the
1350: distinguished attribute of the entry.
1351: \item[surName:]
1352: which gives the person's last name.
1353: \end{describe}
1354:
1355: The optional attributes are:-
1356: \begin{quote}\small\begin{verbatim}
1357: userPassword
1358: seeAlso
1359: telephoneNumber
1360: description
1361: \end{verbatim}\end{quote}
1362:
1363: \subsubsection{OrganizationalPerson}
1364: This is a sub-class of \verb+person+ and introduces the following optional
1365: attributes:-
1366: \begin{quote}\small\begin{verbatim}
1367: preferredDeliveryMethod
1368: destinationIndicator
1369: registeredAddress
1370: internationaliSDNNumber
1371: x121Address
1372: facsimileTelephoneNumber
1373: teletexTerminalIdentifier
1374: telexNumber
1375: physicalDeliveryOfficeName
1376: postOfficeBox
1377: postalCode
1378: postalAddress
1379: title
1380: organizationalUnitName
1381: streetAddress
1382: stateOrProvinceName
1383: locality
1384: \end{verbatim}\end{quote}
1385:
1386: \subsubsection{ThornPerson}
1387: like \verb+OrganizationalPerson+, this is also a sub-class of \verb+person+
1388: and introduces the following optional
1389: attributes:-
1390: \begin{quote}\small\begin{verbatim}
1391: homePostalAddress
1392: lastModifiedBy
1393: lastModifiedTime
1394: secretary
1395: homePhone
1396: userClass
1397: photo
1398: roomNumber
1399: favouriteDrink
1400: info
1401: rfc822Mailbox
1402: textEncodedORaddress
1403: userid
1404: \end{verbatim}\end{quote}
1405:
1406: Two example \verb+ThornPerson+ entries are given in Figure~\ref{example_edb} on
1407: page~\pageref{example_edb}.
1408:
1409: \subsubsection{OrganizationalRole}
1410: Entries of this class are used to represent a position or role within an
1411: organization.
1412:
1413: There is one mandatory attribute:
1414: \begin{describe}
1415: \item[commonName:] which gives the name of the role.
1416: The value of this attribute is a string; e.g.,
1417: \begin{quote}\small\begin{verbatim}
1418: PostMaster
1419: \end{verbatim}\end{quote}
1420: \end{describe}
1421:
1422: There are many optional attributes including:
1423: \begin{describe}
1424: \item[roleOccupant:] which is the Distinguished Name of the person
1425: who fulfills the role e.g.,
1426: \begin{quote}\small\begin{verbatim}
1427: c=US@o=NYSERNet Inc.@ou=Operations@cn=Chris Kolb
1428: \end{verbatim}\end{quote}
1429: \end{describe}
1430:
1431: The other optional attributes are:
1432: \begin{quote}\small\begin{verbatim}
1433: seeAlso
1434: preferredDeliveryMethod
1435: destinationIndicator
1436: registeredAddress
1437: internationaliSDNNumber
1438: x121Address
1439: facsimileTelephoneNumber
1440: teletexTerminalIdentifier
1441: telexNumber
1442: telephoneNumber
1443: physicalDeliveryOfficeName
1444: postOfficeBox
1445: postalCode
1446: postalAddress
1447: description
1448: organizationalUnitName
1449: streetAddress
1450: stateOrProvinceName
1451: locality
1452: \end{verbatim}\end{quote}
1453:
1454:
1455: \subsubsection{Alias}
1456: Objects of this class represent an alias to some other entry in the
1457: DIT. It is generaly used when an entity belongs in one or more subtrees of
1458: the DIT, and is used to ``point'' one entry at the other.
1459:
1460: There are two mandatory attributes:
1461: \begin{describe}
1462: \item[commonName:] which gives the name of the alias.
1463: The value of this attribute is a string; e.g.,
1464: \begin{quote}\small\begin{verbatim}
1465: Colin Robbins
1466: \end{verbatim}\end{quote}
1467:
1468: \item[aliasedObjectName:] which is a pointer to another object in the Directory;
1469: e.g.,
1470: \begin{quote}\small\begin{verbatim}
1471: c=GB@o=University College London@ou=Computer Science@cn=Colin Robbins
1472: \end{verbatim}\end{quote}
1473: \end{describe}
1474: There are no optional attributes for this object class.
1475:
1476: An example of an Alias entry is given below:-
1477: \begin{quote}\small\begin{verbatim}
1478: cn= Quipu-support
1479: aliasedObjectName= c=GB@o=University College London@ou=Computer
1480: Science@cn=Incads
1481: objectClass= quipuObject & alias & top
1482: \end{verbatim}\end{quote}
1483:
1484: \subsubsection{OrganizationalUnit}
1485: The \verb+OrganisationalUnit+ object class is used to represent a unit within
1486: your organisation.
1487: There is one mandatory attribute
1488: \begin{describe}
1489: \item[organizationalUnitName:]
1490: which gives the name of the organizational unit.
1491: The value of this attribute is a string; e.g.,
1492: \begin{quote}\small\begin{verbatim}
1493: Research and Development
1494: \end{verbatim}\end{quote}
1495: \end{describe}
1496:
1497: The optional attributes are:-
1498: \begin{quote}\small\begin{verbatim}
1499: userPassword
1500: seeAlso
1501: preferredDeliveryMethod
1502: destinationIndicator
1503: registeredAddress
1504: internationaliSDNNumber
1505: x121Address
1506: facsimileTelephoneNumber
1507: teletexTerminalIdentifier
1508: telexNumber
1509: telephoneNumber
1510: physicalDeliveryOfficeName
1511: postOfficeBox
1512: postalCode
1513: postalAddress
1514: businessCategory
1515: searchGuide
1516: description
1517: streetAddress
1518: stateOrProvinceName
1519: locality
1520: \end{verbatim}\end{quote}
1521:
1522: \subsubsection{Organization}
1523: Objects of this class represent a top-level organizational entity,
1524: such as a corporation, university, government entity, and so on.
1525:
1526: There is one mandatory attribute:
1527: \begin{describe}
1528: \item[organizationName:]
1529: which gives the name of the organization.
1530: The value of this attribute is a string; e.g.,
1531: \begin{quote}\small\begin{verbatim}
1532: NYSERNet Inc.
1533: \end{verbatim}\end{quote}
1534: \end{describe}
1535:
1536: The optional attributes are:-
1537: \begin{quote}\small\begin{verbatim}
1538: userPassword
1539: seeAlso
1540: preferredDeliveryMethod
1541: destinationIndicator
1542: registeredAddress
1543: internationaliSDNNumber
1544: x121Address
1545: facsimileTelephoneNumber
1546: teletexTerminalIdentifier
1547: telexNumber
1548: telephoneNumber
1549: physicalDeliveryOfficeName
1550: postOfficeBox
1551: postalCode
1552: postalAddress
1553: businessCategory
1554: searchGuide
1555: description
1556: streetAddress
1557: stateOrProvinceName
1558: locality
1559: \end{verbatim}\end{quote}
1560:
1561: \subsubsection {domainRelatedObject}
1562: If an object has some relationship to the Internet Domain Name System (DNS),
1563: then this can be represented in the DIT using this objectclass.
1564:
1565: This class has one mandatory attribute:
1566: \begin{describe}
1567: \item[associatedDomain:]
1568: identifies the domain which corresponds to this object.
1569: The value is a domain string, e.g.,
1570: \begin{quote}\small\begin{verbatim}
1571: nyser.net
1572: cs.ucl.ac.uk
1573: \end{verbatim}\end{quote}
1574: \end{describe}
1575:
1576: \subsection {Schemas}
1577: \label{quipu:schema}
1578:
1579: Directories should provide a very flexible tool
1580: which enables any information to be stored. There is a danger that Schemas,
1581: as specified in the OSI Directory, will lead to procrustean directory implementations
1582: which impose unreasonable restrictions. The QUIPU Directory does not, per
1583: se, place restrictions on what can be placed in a DSA.
1584: It does however give control so that managers may control what is stored in the
1585: directory.
1586:
1587: The first aspect of structure is with respect to attributes which may be
1588: present in an entry. A QUIPU DSA will allow an entry to belong to one or
1589: more object classes which are known to the DSA (stored in a table). An
1590: entry will typically have a small number of object classes (e.g., TOP
1591: (implicit) + Person + Organisational Person + QUIPU Object). The DSA will
1592: maintain a table of mandatory and optional attributes for each object class
1593: supported. This will be follow the guidelines of the standard or
1594: specification identifying the object class in question. From this
1595: information, the DSA can determine the permitted and mandatory attributes for a
1596: given entry, by calculating the union of all the object classes of that
1597: entry. Free extension (i.e., the ability to store any attribute) was
1598: rejected, as there does not appear to be a reasonable mechanism to manage
1599: this. However, it is straightforward for managers to create new object
1600: classes as desired.
1601:
1602: \tagrind[htb]{schema}{Schema definition}{schema-py}
1603:
1604: It is important
1605: to allow management control of what is permitted at a given level.
1606: Therefore a ``tree structure''
1607: attribute may be created.
1608: This attribute is defined in Figure~\ref{schema-py}, with the string syntax
1609: discussed in ~\ref{tree_struct}.
1610: This specifies for the level below,
1611: what types of object are permitted.
1612: Each attribute value identifies a class of object which can exist at the level
1613: below, and
1614: defines a set of mandatory and optional object classes.
1615: This can be considered as defining a (private) object class implied by the
1616: combination of these classes.
1617: For each type of object, the attribute types permitted in the RDN are also
1618: listed. This is not checked in QUIPU-6.0
1619: The directory knows about the tree structure attribute, and will
1620: ensure consistency.
1621: When creating an entry, the DSA must check that it conforms to the
1622: treeStructure attribute of the parent entry.
1623: When removing information from a treeStructure attribute, the
1624: Directory will check that all of the children conform to the
1625: modified attribute.
1626:
1627: \subsection {Photograph Attributes}
1628: \label{dua:photo}
1629:
1630: The data that a DSA can hold does not have to be limited to data that can be
1631: represented by printable strings.
1632: Any attribute a QUIPU DSA does not know a string syntax for, it will hold as
1633: a block of ASN.1.
1634: One such attribute is the ``photo'' attribute.
1635: Photographs of people and objects are stored in the directory as a
1636: g3fax encoded block of ASN.1, and are best stored as ``file'' attributes
1637: described in the next Section.
1638: There is an example of a photograph attribute in the example database.
1639: This can be looked at by connecting to the directory with \verb"dish"
1640: and looking at the entry
1641: ``c= GB @ o= University College London @ ou= Computer Science @ cn= Steve Kille"
1642:
1643:
1644: Unless you you have compiled and installed the ``photo'' code as
1645: described in Section~\ref{quipu:install} you will see the message
1646: \begin{quote}\begin{verbatim}
1647: ``No display process defined''
1648: \end{verbatim}\end{quote}
1649:
1650: Having compiled the ``photo'' code, you will need to add a line such
1651: as
1652: \begin{quote}\small\begin{verbatim}
1653: photo xterm Xphoto
1654: \end{verbatim}\end{quote}
1655: to your dsaptailor file (see Section~\ref{dua:tailor})
1656: This says that if the user in logged on to a terminal
1657: of the type \verb"xterm" then use the process \file{g3fax/Xphoto}
1658: in the ISODE \verb"ETCDIR" directory to display the photograph.
1659:
1660: There are display routines provided for the X~window system, SunView,
1661: Tektronix~4014, and ``dumb'' terminals.
1662:
1663: \subsection {File Attributes}
1664: \label{file_attr}
1665: Attributes values are generally stored in the EDB file, and loaded
1666: into memory when the DSA starts.
1667: For some large attributes such a photos, this is not a sensible approach, so the
1668: concept of a ``file'' attribute is introduced.
1669:
1670: If an attribute value is prefixed by \verb"FILE", then the value is assumed
1671: to be stored on disk.
1672: For example if the following were found in an EDB file:-
1673: \begin{quote}\small\begin{verbatim}
1674: photo = {FILE} /usr/local/pictures/steve
1675: \end{verbatim}\end{quote}
1676: then the value for the photo attribute would be read from the file
1677: \begin{quote}
1678: \verb"/usr/local/pictures/steve".
1679: \end{quote}
1680:
1681: The syntax of the data in the file is expected to be the same as
1682: the string syntax, except in the case of ASN and PHOTO attributes which
1683: are expected to be in raw ASN.1.
1684:
1685: If there is not a file name supplied, then a default name is allocated.
1686: The default file name is the RDN of the entry the attribute belongs to
1687: followed by a dot ``.'', followed by the attributeType. This file is expected
1688: to be in the same directory as the EDB file for the entry.
1689: For example the default file for photo attribute, representing the entry
1690: for
1691: ``c= GB @ o= University College London @
1692: ou= Computer Science @ cn= Colin Robbins''
1693: would be:-
1694: \begin{quote}\small\begin{verbatim}
1695: cn=Colin Robbins.photo
1696: \end{verbatim}\end{quote}
1697: in the directory
1698: \begin{quote}\small\begin{verbatim}
1699: quipu-db/c=GB/o=University College London/ou=Computer Science
1700: \end{verbatim}\end{quote}
1701: or equivalent mapped file as described in Section~\ref{EDB:mapped}.
1702:
1703: The process defined so far allows for attribute stored in a EDB in file
1704: format to be read by a DSA.
1705: Writing the attributes back to files if modified/added by a DUA requires
1706: a little more.
1707: The DSA needs to know which attributes should be stored on disk.
1708: This information is supplied in the attribute oidtables which are
1709: defined in Section~\ref{oidtables}.
1710: For example if the following entry was found in the file
1711: \file{oidtable.at} in the ISODE \verb"ETCDIR" directory
1712: then a ``photo'' attributed would always be written
1713: back to disk.
1714: \begin{quote}\small\begin{verbatim}
1715: photo: thornAttribute.7: photo : file
1716: \end{verbatim}\end{quote}
1717:
1718:
1719: \section {How a DSA Starts}
1720: \label{dsa:starting}
1721:
1722: The Section gives a brief description of how a QUIPU DSA starts.
1723: This is intended to help people who have experienced problems in getting
1724: their DSAs started.
1725:
1726: First of all the tailor file \file{quiputailor} in the ISODE \verb"ETCDIR" directory
1727: is read (unless you
1728: specify a different tailor file using the \verb"-t" option to
1729: \pgm{ros.quipu}).
1730: This tells the DSA, amongst other things, its own name, and its parent
1731: DSA(s).
1732:
1733: The first thing a DSA need to do if find its own entry, thus it tries to
1734: load the EDB that should contain it.
1735: If it can not find its own entry, then it will try connecting to the
1736: parent DSA to read its own entry. If this fails the DSA will stop.
1737:
1738: Having found its own entry, the DSA will check to see if it is a cached
1739: entry read from disk, if so it will attempt to read a new version from the
1740: parent --- if successful a new cache EDB file will be written.
1741:
1742: Now the rest of the local DIT can be loaded. Each EDB specified in the
1743: ``edbInfo'' attribute \index{edbInfo attribute} is in turn loaded from disk.
1744:
1745: As each EDB is loaded from disk, it is checked to make sure all the
1746: attributes in the entry are allowed, as defined by the ``objectClass''
1747: attribute, \index{objectClass attribute} and that the tree shape conforms to that defined by the
1748: ``treeStruture'' attribute. \index{treeStructure attribute}
1749: If any EDB fails these checks then the DSA will not start, and an appropriate
1750: message will be logged.
1751:
1752: A check is now made on the \verb"quipuVersion" \index{quipuVersion attribute}
1753: that a DSA entry MUST contain.
1754: If this attribute does not have the same version string as the
1755: running DSA process, a warning message is printed to the logs.
1756: On seeing this message, you should update the version string
1757: in your DSAs entry.
1758: Future version of the software will maintain the attribute for you.
1759:
1760: Having loaded all its data, the DSA will start listening for DAP and DSP
1761: associations.
1762:
1763: \section {Adding more DSAs}
1764:
1765: Many organisations will need to have more than one DSA to meet
1766: their requirements, the Section suggests how you might arrange your
1767: DSAs to get the most out of the system.
1768:
1769: You will almost certainly need at least one DSA that holds a
1770: copy of the root EDB, and your country EDB.
1771: This DSA should also hold the MASTER copy of your organisations own EDB.
1772: Subsequent DSAs that are set up, should have this DSA defined
1773: as one of their parent DSAs.
1774:
1775: For robustness, it is a good idea to have some other DSAs replicating
1776: these EDBs, so that if one local machine or DSA becomes unavailable, then
1777: there is another copy elsewhere that can be used.
1778: EDBs that contain addresses of other DSAs that you may want to contact
1779: regularly should also be replicated, to prevent extra associations
1780: having to be made just to read DSA addresses.
1781: In short, if you know that data from a certain
1782: EDB is going to be accessed a lot, replicate it locally.
1783: Replication does not have a high cost.
1784:
1785: When setting up multiple DSAs be sure to name them as described in
1786: Section~\ref{dsa:naming},
1787: ensure the DSA entries are sufficiently high in the DIT, so that other DSAs
1788: can read the entry, without having to contact the DSA concerned.
1789:
1790: \section {Receiving EDB Updates}
1791: \label{slave_update}
1792: If your DSA holds a slave copy of one or more EDBs, then it can
1793: automatically update these for you.
1794: The current approach is very simple minded, but will be extended for future
1795: versions.
1796:
1797: There are two ways to ask a DSA to update its slave EDBs, either use \pgm {dish}
1798: program and issue a ``dsacontrol --slave'' command --- see
1799: Section~\ref{dua:mgmt}, or set the \verb"quiputailor" parameter
1800: ``update'' to ``on'' (see Section~\ref{dsa:tailor})
1801: --- in which case the DSA will try to update its slaves
1802: when it starts up.
1803:
1804: To update the slaves, the DSA uses the ``edbinfo'' attribute that the DSAs
1805: entry in the DIT MUST have.
1806: This attribute specifies which EDBs you hold, and where to get updates of
1807: the from.
1808: NOTE you do not necessarily have to get updates from a \verb"MASTER" EDB,
1809: a \verb"SLAVE" is acceptable.
1810: In many cases this will be preferable to prevent the
1811: load on the \verb"MASTER" DSA being too high.
1812: For example a ``national'' EDB is likely to be highly replicated,
1813: it would not be a good idea to have just one DSA
1814: handling updates. It would be better to have the load spread over several
1815: DSAs.
1816:
1817: The syntax of the attribute is \index{edbInfo attribute}
1818: \begin{quote}\begin{verbatim}
1819: edbinfo = EDB concerned # get from # send to
1820: \end{verbatim}\end{quote}
1821: It is a multi-valued attribute.
1822:
1823: A few examples:
1824: \begin{quote}\small\begin{verbatim}
1825: # cn=Giant Tortoise # cn=Fruit Bat
1826: c=US # # cn=Fruit Bat
1827: c=US # # c=US@cn=Spectacled Bear
1828: c=US@l=NY # cn=Fruit Bat #
1829: \end{verbatim}\end{quote}
1830: Note that there is no harm to using multiple \verb"eDBinfo" lines,
1831: even if they refer to the same EDB.
1832: These lines indicate that:
1833: \begin{itemize}
1834: \item The ROOT EDB is read from the \verb"cn=Giant Tortoise" DSA,
1835: further the \verb"cn=Fruit Bat" DSA is allowed to read the
1836: ROOT EDB from this DSA.
1837: This is an important point --- A DSA has to explicitly say it will
1838: allow you to update from it, before it will send EDB files.
1839: Thus if you want to pull EDB files from a remote DSA, you will need
1840: to ask the manager to add you DSA to their DSAs ``send to'' field.
1841:
1842: \item The \verb"cn=Fruit Bat" DSA and the \verb"c=US@cn=Spectacled Bear" DSA
1843: are allowed to read the EDB for \verb"c=US".
1844: Note that the second and third line could be combined as:
1845: \begin{quote}\small\begin{verbatim}
1846: c=US # # cn=Fruit Bat$c=US@cn=Spectacled Bear
1847: \end{verbatim}\end{quote}
1848: \item The DSA named \verb"cn=Fruit Bat" supplies the EDB for \verb"c=US@l=NY"
1849: to this DSA.
1850: \end{itemize}
1851:
1852: Some EDB files, such as the ROOT, and country level EDB files are highly
1853: replicated, and having to list all the DSAs that are allowed to pull such EDBs
1854: is too restrictive.
1855: Thus the following syntax can be used as an abbreviation:
1856: \begin{quote}\small\begin{verbatim}
1857: c=US # # c=US
1858: \end{verbatim}\end{quote}
1859: This indicates that the c=US EDB file can be sent to DSA named at the c=US
1860: level of the DIT, for example
1861: \begin{quote}\small\begin{verbatim}
1862: c=US@cn=Wombat
1863: \end{verbatim}\end{quote}
1864: is allowed to pull the EDB, but the following are not:
1865: \begin{quote}\small\begin{verbatim}
1866: cn=Wombat
1867: c=US@o=Foobar Inc.@cn=Wombat
1868: c=GB@cn=Wombat
1869: \end{verbatim}\end{quote}
1870:
1871: Whether to update is decided upon by looking at the version string, if the
1872: two EDB files have a different version string, then the EDB will be updated.
1873:
1874: \section {Tables}
1875: \label {oidtables}
1876: Throughout QUIPU, all the Object Identifiers that need to be specified, are
1877: specified using a string representation, for example:-
1878:
1879: \[\begin{tabular}{|l|l|} \hline
1880: String representation & Object Identifier \\ \hline
1881: attributeType & 2.5.4 \\
1882: surname & 2.5.4.4 \\
1883: streetAddress & 2.5.4.9 \\
1884: organizationName & attributeType.10 \\ \hline
1885: \end{tabular}\]
1886:
1887: A set of Object Identifier tables in the ISODE \verb"ETCDIR" directory are
1888: used to
1889: provide this mapping (see also Section~\ref{isobject} in \volone/).
1890: In general the default table will be sufficient,
1891: this section describes the tables for those who want to extend
1892: the default definitions.
1893:
1894: This basic format is used to build up the specification of general object
1895: identifiers.
1896: This file is by default named \file{oidtable.gen}, and has simple
1897: mappings from string to oid.
1898: These strings can then be used in the definition of further oids (for example
1899: the ``organizationName'' oid in the table above).
1900:
1901: This simple table is extended to give table formats for attributes
1902: This file is by default named \file{oidtable.at}.
1903: Each entry in this table is assumed to represent an attribute, so
1904: in addition to mapping strings onto oids,
1905: it also defines the syntax for that attribute:-
1906:
1907: \[\begin{tabular}{|l|l|l|} \hline
1908: String representation & Object Identifier & Syntax\\ \hline
1909: objectClass:& attributeType.0: &objectclass \\
1910: aliasedObjectName:& attributeType.1: &dn\\
1911: commonName,cn:& attributeType.3: &caseignorestring\\
1912: searchGuide:& attributeType.14: &asn\\
1913: x121Address:& attributeType.24: &numericstring\\
1914: presentationAddress:& attributeType.29: &presentationaddress\\
1915: \hline
1916: \end{tabular}\]
1917:
1918: This says that the attribute named ``objectclass'' represents the oid
1919: ``attributeType.0'' --- using the expansion of ``attributeType'' (
1920: as defined in the
1921: file \file{oidtable.gen}) thus gives the oid ``2.5.4.0''.
1922: The syntax taken by the attribute value is ``objectclass''.
1923:
1924: Similarly an ``aliasedObjectName'' has ``dn'' (DistinguishedName) syntax.
1925: The recognised syntaxes are defined in the BNF in
1926: Appendix~\ref{bnf}.
1927:
1928: After the ``syntax'' an extra optional parameter is allowed;
1929: if this is the string ``\verb"file"'' the the relevant attribute is
1930: designated a file attribute --- see Section~\ref{file_attr} for a
1931: description of file attributes.
1932:
1933:
1934: The file \file{oidtable.oc} defines the object classes\index{object
1935: class} QUIPU knows about.
1936: The file again maps strings onto oids.
1937: Each string is assumed to represent an object class, abd for each it
1938: defines the hierarchy (which object classes it is a subclass of),
1939: the mandatory attributes of the object class, and the optional attributes of
1940: the object class.
1941:
1942: For example the entry
1943: \begin{quote}\small\begin{verbatim}
1944: quipuObject: quipuObjectClass.2 : top : acl : \
1945: masterDSA, slaveDSA, treeStructure
1946: \end{verbatim}\end{quote}
1947:
1948: defines ``quipuObject'' to be an objectClass represented by the oid
1949: ``quipuObjectClass.2''.
1950: It is a SUBCLASS of the object class ``top''.
1951: An entry having this object class MUST have the attribute ``acl'', and MAY
1952: have the attributes ``masterDSA'', ``slaveDSA'' and ``treeStructure''
1953: (NOTE The similarity between this definition and the ASN.1 definition of
1954: a ``quipuObject'' in Appendix \ref{naming}).
1955:
1956: To allow for definitions of ``attribute sets'', there is a simple
1957: MACRO facility provided, for example, using the MACRO
1958: \begin{quote}\small\begin{verbatim}
1959: localeAttributeSet = localityName, streetAddress ...
1960: \end{verbatim}\end{quote}
1961: every occurrence of ``\verb"localeAttributeSet"'' will be replace by the right
1962: hand side expression.
1963:
1964:
1965: With the definition of the ``string'' form of the oid it is also possible
1966: to specify ONE abbreviation for the name.
1967: The standard tables use the following abbreviations:-
1968:
1969: \[\begin{tabular}{|l|l|}
1970: \hline
1971: c & countryName \\
1972: o & organizationName \\
1973: ou & organizationalUnitName \\
1974: cn & commonName \\
1975: co & friendlyCountryName \\
1976: \hline
1977: \end{tabular}\]
1978:
1979: The abbreviated name may be used anywhere the full name would be allowed.
1980:
1981:
1982: Every entry stored in the QUIPU DSA is checked against these tables to see if
1983: the attributes supplied are allowed in the entry, to make sure the mandatory
1984: attributes are present, and the attributes themselves have the correct syntax.
1985:
1986: If you wish to add you own definitions to the tables you should add them to
1987: the files
1988: \file{isode/dsap/oidtable.at.local},
1989: \file{isode/dsap/oidtable.oc.local} and
1990: \file{isode/dsap/oidtable.gen.local}
1991: in that way, if a new set of tables are issued, you local entries will be
1992: preserved.
1993:
1994: \section{More Help Installing Quipu}
1995: Contact ``quipu-support'',
1996: the mail address is given in Section~\ref{quipu:support}.
1997:
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.