⟦d8b48fc4e⟧

TextFile

%run this through LaTeX with the appropriate wrapper

\f

\chapter {Installing QUIPU}

\label{quipu:install}

This section describes how to install QUIPU, and make it operate in a basic
fashion.  This is reasonably prescriptive, as it should be possible to
install and operate a QUIPU DUA and/or DSA without too much 
knowledge about how it functions.

QUIPU comes in 4 separate parts of the ISODE tree, none of which are
``made'' as part of the default installation of ISODE.
This section assumes you have installed ISODE.  
You should consult the \file{READ-ME} file in the
top level of the source tree, and \volone/ to \volfour/ of this Manual
if you have not installed ISODE.

There are various options you can set which control
the operation of QUIPU. These are set in the file \file{h/quipu/config.h}, 
however, these are probably best left to their default values.

To generate QUIPU type \verb"make all-quipu" in the top-level ISODE
directory.

A version of \pgm{dish} that runs directly 
from a \unix/ shell, 
\pgm{dishinit}:
a script to create a default \file{.quipurc} file for new users, and 
\pgm{sid}: a set of scripts that utilise the shell version of dish, are all
installed from the \file{others/quipu/uips/dish} directory.
The \pgm{fred}, \pgm{widget} and \pgm{sunint} interfaces
can be installed by looking at 
\file{others/quipu/uips/READ-ME}.

Each of these interfaces knows about the ``photo'' attribute that an entry
in the DIT can have.  In order to display the photographs, the photo
handling code must be compiled, instructions on this can be found in
Section~\ref{dua:photo} of this Manual and the file
\file{others/quipu/photo/READ-ME}.

\section{Files}
Regardless of how you install QUIPU and the ISODE,
the number of files needed to run QUIPU are quite small.

In ISODE's \verb"BINDIR" directory,
typically \file{/usr/local/bin/},
there are a few programs of interest:
\begin{describe}
\item[dish:]	The DIrectory SHell\\
		This is discussed in Chapter~\ref{dish}.

\item[bind:]	Shell interface to \pgm{dish}\\
		There are actually several links (listed below) to a program called
		\pgm{bind}.
		These act to export the \pgm{dish} interface to the \unix/
		shell.
		As such,
		you can issue commands to \pgm{dish} from the shell,
		rather than running \pgm{dish} directly.
\begin{quote}
\begin{tabular}{l}
add\\
compare\\
delete\\
dsacontrol\\
list\\
modify\\
modifyrdn\\
moveto\\
search\\
showentry\\
showname\\
squid
\end{tabular}
\end{quote}

\item[fred:]	A white pages user interface\\
		See Chapter~\ref{DUA:fred}.

\item[editentry:]	Edit a Directory entry\\
		This is a simple shell script that \pgm{dish} invokes when you
		ask \pgm{dish} to edit an entry in the Directory.

\item[unbind:]	Unbind from \pgm{dish}\\
		This command is used to terminate \pgm{dish}.
\end{describe}
In ISODE's \verb"SBINDIR" directory,
typically \file{/usr/etc/},
the DSA resides:
\begin{describe}
\item[ros.quipu:]	The QUIPU DSA\\
			This program will be started once, for each DSA you
			are running, from rc.local.
			A script is provided to invoke this program,
			in case you need to restart it.

%%%\item[dsaconfig:]	a configurator for Level-1 DSAs.
\end{describe}
In ISODE's \verb"ETCDIR" directory,
also typically \file{/usr/etc/},
there are a few programs and files of interest:
\begin{describe}\sloppy
\item[oidtable.at, oidtable.gen, oidtable.oc:]
			These define the attribute types,
			generic object identifiers,
			and object classes known to the system.
			(An object identifier is a method used to unambiguously
			encode, among other things,
			the names of attributes and object classes.)
			These files you never deal with unless they are
			accidently corrupted.
			
\item[dsaptailor:]	This is the run-time tailor file for the DUAs.
			You will configure this file initially and then
			probably leave it alone.


\item[isoaliases, isobjects, isoentities, isomacros, isoservices:]
			These are \\ %%%
			various databases used by the ISODE.
			These files you never deal with unless they are
			accidently corrupted.

\item[isologs:]		This script runs nightly under \man cron(8) to
			trim the ISODE log files, kept in ISODE's \verb"LOGDIR"
			directory,
			typically \file{/usr/tmp/}.
			This file you never deal with unless it is
			accidently corrupted.

\item[isotailor:]	This is the run-time tailor file for the ISODE.
			You will configure this file initially and then
			probably leave it alone.
\end{describe}

\chapter {Configuring a DUA}

It is suggested that you try to get a DUA operational by connecting to
a ``well known'' DSA before you attempt
to operate a local DSA.
Or, if you have a DSA from a previous release of QUIPU - try an connect to
that.

\section {Connecting to a DSA}
\label{dua:connect}

A DUA essentially only needs to know one thing to be able to contact a
DSA, that is the network address of the DSA.
This parameter is defined in the file \file{dsaptailor}, 
together with some other parameters.
The full set of parameters are described in Section \ref{dua:tailor}.

The \verb"dsa_address" parameter defines the name and address of the DSA to 
initially contact. For example,
\begin{quote}\begin{verbatim}
dsa_address  vicuna  Internet=bells.cs.ucl.ac.uk+50987
\end{verbatim}\end{quote}

declares the DSA \verb"vicuna" at the indicated presentation 
address\footnote{The syntax of presentation addresses is discussed in
\volone/ of this manual and \cite{String.Addresses}.}
\index{presentation addresses}
to be the
default DSA for the DUA to contact.
As shown above, the address is preceded by a private key.  This can
be used in some DUAs (including DISH) to specifying the address of the DSA 
to contact.
If there are more than one \verb"dsa_address" entries, the first
entry will be used to supply the default DSA address.

A default dsaptailor file 
(taken from \file{dsap/dsaptailor}) is installed as
\file{dsaptailor} in the ISODE \verb"ETCDIR" directory
(usually \file{/usr/etc/}) when
the dsap library is installed, this supplies the addresses
of various DSAs that you
may be able to access.
 
To try to connect to one of the DSAs listed in dsaptailor, 
invoke \pgm{dish}, with a \verb"-call"
flag, e.g. ``\verb"dish -call giant"'' will try to contact the DSA ``giant''
running at UCL.
If the connection is successful, then the prompt ``\verb"dish ->"'' will be returned.
If the connection fails, the
program will exit with an appropriate error
message.

If this fails
you might want to 
try connecting to some of the other registered DSAs,
for example, try ``\verb"dish -call alpaca"'', ``\verb"dish -call eel"'' 
or ``\verb"dish -call anaconda"''.
A list of registered DSAs is given in Appendix~\ref{dsa:sites}.

If you fail to contact a DSA at this point, there are likely to be lower
level problems. You should turn up the ISODE logging 
(see \voltwo/ of this manual) to see what is happening to the 
network calls.

If you invoke \pgm{dish} without a \verb"-c" flag (using the default \file{dsaptailor}), it will 
try to connect to the DSA defined by the first
\verb"dsa_address" entry.

\pgm{dish} is described in full in Chapter~\ref{dish} 
of this Manual.

\section{Tailoring}
\label{dua:tailor}
\index{dsaptailor}

The program configuration is tailored to
allow you to change logging levels, and other parameters at
run time.  
It is used by the QUIPU DUA procedures, and by the QUIPU User Interfaces.

The file \file{dsaptailor} is used for this purpose and
consists of single value entries (e.g. oidtable), unless otherwise
stated (e.g dsaplog). 
Each entry has a parameter followed by its
value.
The various options are:
\begin{describe}
\item [\verb"oidtable":]
The path for the OID definition tables.
NOTE: It is best to have this appear as the first entry of the tailor file, as
other entries may contain attributes that need to be looked up in these
tables
There are three:
\begin{itemize}
\item \file{file.gen},
which contains generic names for building OIDs;
\item \file{file.at},
which contains the OIDs for attributes; and,
\item \file{file}.oc,
which contains the OIDs for object classes.
\end{itemize}
For example,
\begin{quote}\small\begin{verbatim}
oidtable    /usr/lib/quipu/OIDTable
\end{verbatim}\end{quote}
will direct the DSA to consult:
\begin{quote}\begin{verbatim}
/usr/lib/quipu/OIDTable.gen
/usr/lib/quipu/OIDTable.at
/usr/lib/quipu/OIDTable.oc
\end{verbatim}\end{quote}
By default this is set to \verb"oidtable" which refers to the tables
\file{oidtable.*} in the ISODE \verb"ETCDIR" directory.

\item [\verb"dsa\_address":]
This parameter is described in Section~\ref{dua:connect}.

\item [\verb"dsaplog":]
Tailoring for the normal logging file.
Each entry consists of one or more key/value pairs expressed as:
\begin{quote}\small\begin{verbatim}
key=value
\end{verbatim}\end{quote}
The keys are:
\begin{describe}
\item [\verb"file":]
The name of the logfile.
\item [\verb"size":]
The size in KBytes to which the logfile should be allowed to grow.
When the log has reached this size, if the ``zero'' option
below is set, then the log will be truncated, otherwise, no further
logging will take place.
\item [\verb"level":]
The levels of logging to be written to this log file.
This can be any of the following levels:
\begin{describe}
\item [\verb"fatal":]
fatal errors only
\item [\verb"exceptions":]
serious, but hopefully temporary, errors
\item [\verb"notice":]
general logging information
\item [\verb"trace":]
program tracing
\item [\verb"pdus":]
pdu tracing
\item [\verb"debug":]
full tracing of events
\item [\verb"all":]
log all events
\end{describe}
For example to have all errors written to the file you will need
\begin{quote}\footnotesize\begin{verbatim}
dsaplog level=fatal level=exceptions
\end{verbatim}\end{quote}
\item [\verb"dlevel":]
Do not log the specified log level, this is the opposite of the above
entry.
\item [\verb"dflags"/\verb"sflags":]
The flags associated with the log may be set (with \verb"sflag")
or unset (with \verb"dflag"). The allowable options are:
\begin{describe}
\item [\verb"close":]
close the log after each entry
\item [\verb"create":]
create the log file if it doesn't exist
\item [\verb"zero":]
truncate the file when it gets too big
\item [\verb"tty":]
copy the logging information to the users tty
\end{describe}
\end{describe}
An example might be:
\begin{quote}\footnotesize\begin{verbatim}
dsaplog level=notice size=30 file=quipulog dflags=close
\end{verbatim}\end{quote}
This says log events at ``notice'' level, into the file ``quipulog'', do not
let the file grow larger than 30Kbytes, and do not close the file
after each logging message.

\item [\verb"stats":] Used to control the level of statistical logging
(parameters as for \verb+dsaplog+ above).

\item [\verb"local\_DIT":]
The argument is a distinguished name.  When some User Interfaces start, you
will be automatically moved to this position in the DIT.

\item [\verb"oidformat":]
Defines how object identifiers should be printed.
Use one of:
\begin{quote}\small\begin{verbatim}
oidformat   short
\end{verbatim}
\end{quote}
to print in short local key form, e.g.,
\begin{quote}\small\begin{verbatim}
Country
\end{verbatim}\end{quote}
or,
\begin{quote}\small\begin{verbatim}
oidformat   long
\end{verbatim}
\end{quote}
to print in long object identifier form, e.g.,
\begin{quote}\small\begin{verbatim}
joint.ds.attributeType.country
\end{verbatim}\end{quote}
or,
\begin{quote}\small\begin{verbatim}
oidformat   numeric
\end{verbatim}
\end{quote}
to print in numeric form, e.g.,
\begin{quote}\small\begin{verbatim}
2.5.4.6
\end{verbatim}\end{quote}

\item [\verb"photo":]
The argument is has two parts, a ``terminal type'' such as
``sun'' or ``xterm'', the second is the name of the process that should
handle displaying of photographs, for example
\begin{quote}
photo xterm Xphoto
\end{quote}
tells the DUA to call the process Xphoto to handle photograph attributes if
the user is on a terminal of type ``xterm''.
Handling photographs is described more fully in Section~\ref{dua:photo}.

\item [\verb"quipurc":]
If the argument has the value \verb"on", then a program called 
\pgm{dishinit} will be run every time a user without a ``.quipurc''
file tries to access the directory. \pgm{dishinit} is discussed 
in Section~\ref{dishinit}.

\item [\verb"sizelimit":]
Defines the maximum number of entries a successful list or search should
return.
For example,
\begin{quote}\small\begin{verbatim}
sizelimit 20
\end{verbatim}\end{quote}
sets the DAP default service control ``sizelimit'' to be 20 entries.
\end{describe}

\f

\chapter {Configuring a DSA}

This Chapter discusses how to configure a QUIPU DSA.
We recommend that you get a DUA running before you try to
get a DSA working.

\section{Basic Formats and Structures}

All of the information a DSA requires is
stored on disk and is text structured.  This includes
various files (described later), and the local DIT database itself.
A complete BNF description of the files 
is given in Appendix~\ref{bnf} on page~\pageref{bnf}.

\subsection {Entry Data Block}
\label{edb}
A key component of the Directory database is the Entry Data Block, which is
described fully in \cite{QUIPU.Design}.
Figure \ref{example_edb} shows an example EDB \index{EDB} file containing two ``person''
entries.

\begin{figure}
\smaller
\begin{verbatim}
MASTER
19891025113003Z
CN= Colin Robbins 
CN= Colin John Robbins 
Phone= +44-1-387-7050 ext 3683 
Surname= Robbins 
Room= G10 
Userid= crobbins
userClass= csstaff
rfc822Mailbox= C.Robbins@cs.ucl.ac.uk
Photo= {FILE}crobbins.photo 
objectClass =thornPerson & quipuObject
acl=others # none # attribute # photo 
acl=self # read # attribute # photo 

CN= Steve Kille 
CN= Steve E. Kille & Stephen Kille 
Phone= +44-1-387-7050 ext 7294 
Surname= Kille 
objectClass = thornPerson & quipuObject 
Room= G24 
Userid= steve
userClass= csstaff
rfc822Mailbox= S.Kille@cs.ucl.ac.uk
\end{verbatim}
\caption{Example EDB File}
\label{example_edb}
\end{figure}


An EDB file contains a header, followed by a sequence of entries.

The header consists of two lines of text, the first must contain the string
``\verb"MASTER"'', ``\verb"SLAVE"'' or ``\verb"CACHE"'', 
which indicates whether the data in the EDB
file represents the authoritative \verb"MASTER" data, a \verb"SLAVE"
copy of the data, or \verb"CACHE"d entries.
The next line is a string that describes the version of the EDB. Every
time the EDB is altered, the version\index{version - of an EDB} number
should be changed, so that
\verb"SLAVE" EDBs elsewhere will be automatically updated.
When a DSA alters an EDB file, it writes the current (UTC) time in string
format as the version string.

Following the header are a sequence of blank line separated entries.
An entry consists of a set of attributes.  The first line is
the Relative Distinguished Name
\index{RDN} (RDN) of the entry.

\subsection{Object Class attribute}
Of the attributes an entry may have, the ``objectClass''\index{objectClass attribute}
attribute is one of the most important from the configuration point of view.
It defines the set of mandatory and optional attributes that must and may be
present in the entry.
For example, the object class ``person'' insists that there is a ``surname''
attribute, and there may optionally be a ``telephone number'' attribute.

QUIPU knows about all the standard object classes and attributes, some of
those defined by the THORN\index{thorn} project (see Section~\ref{thorn:na}) and
those defined by QUIPU itself (see Appendix~\ref{naming}).
The full set of object classes and attributes a DSA knows about is
defined by the ``oidtables'' which are explained in Section~\ref{oidtables}.

An entry can belong to more that one object class.
For example, an entry representing an organisation might have the following
object class attribute:-
\begin{quote}\small\begin{verbatim}
objectClass = organization & quipuNonLeafObject
\end{verbatim}\end{quote}
And a person within that organisation might use the following object class
definition:-
\begin{quote}\small\begin{verbatim}
objectClass = organizationalPerson & quipuObject & thornPerson
\end{verbatim}\end{quote}
Every entry in a QUIPU DSA should belong to either the ``\verb"quipuObject"''
or ``\verb"quipuNonLeafObject"'' object classes, as this allows
attributes the DSA needs to be added to an entry.

Further, object classes posses the notion of 
\verb"class inheritance".
This means that an object class can be defined as a ``subclass'' of
a previously defined object class with additional refinements.
As a subclass,
the newly defined object ``inherits'' all the semantics of its
superclass,
in addition to having additional semantics.

For example,
the Directory defines an object class called \verb"person".
This object class defines the attributes which a person in
the real world might have.
It may be useful to refine this somewhat to talk about persons
who have network access.
So, we need a new object class, e.g., \verb"netPerson".
This can be defined in a straight-forward fashion:
\begin{quote}
The object class \verb"netPerson" is a subclass of the object class
\verb"person" which {\em may\/} contain an additional attribute,
\verb"netMailbox".

The syntax of an \verb"netMailbox" is a simple string of printable
characters which is not case sensitive when performing comparisons.
\end{quote}

It is a Quipu requirement that every entry that is not a leaf of the DIT 
should belong to the object class
``\verb"quipuNonLeafObject"''. 

This class has one mandatory attribute:
\begin{describe}
\item[masterDSA:]\index{masterDSA attribute}
			identifies the Directory entity which is responsible
			for maintaining the MASTER EDB for the children of
			this entry.
			The value is a Distinguished Name.
\end{describe}
There is typically a single MASTER for a particular entry in the tree.
Hence, this value is usually single-valued.
When an entry is to be modified,
the Directory must contact the entity responsible for the MASTER EDB for
that entry in order to perform the modification.

This class has two optional attributes:
\begin{describe}
\item[slaveDSA:]\index{slaveDSA attribute}
			identifies any Directory entities which have
			authoritative copies of the EDB for the children
			of this entry.
			The value is one or more Distinguished Names.

\item[treeStructure:]\index{treeStructure attribute}
			identifies the object classes which may exist
			immediately below this entry.
			The value is one or more object classes.
			See Section~\ref{quipu:schema} for full details
			of how to set this attribute.
\end{describe}
Since a fundamental assumption of the Directory is that reads (queries)
occur much more frequently than writes (updates),
it is common to have several entities containing authoritative copies of an
EDB.
By keeping copies locally,
queries can be answered with less latency.

\subsection {Database Structure}

All the information held by the Directory in its in-core database, is loaded
from disk when the Directory starts. 
The data on disk is held in a \unix/ tree of EDB files that map
the DIT.
At every level in the DIT for which the DSA holds data, there is a single
file called \file{EDB}\index{EDB file}.
If an entry defined in an \file{EDB} file has
children, the \file{EDB} file for the children will be found in a
sub-directory whose name is the string encoded Relative
Distinguished Name of the entry.
For example, if an \file{EDB} file has an entry whose RDN is
``ou= Computer Science'', then if the entry ``ou= Computer Science'' has children and is stored locally,
it can be found in the file \file{ou=Computer Science/EDB} relative to the current directory.
NOTE that the case sensitivity of the sub-directory naming is one of the
few areas within QUIPU where string matching is case sensitive.
The case of the attribute type is taken from the definition of the attribute
in the oid tables, whereas the case of the attribute value is the same as
that found in the EDB file.

When an entry is modified, the modified \file{EDB} file is re-written to
disk.  The old \file{EDB} is renamed \file{EDB.bak} to provide
a back-up.

\subsection{Long Distinguished Names}
\label{EDB:mapped}
There is a problem with the above method for naming \unix/ sub directories
with some versions of \unix/ --- particularly System~V.
In these systems directory names are limited in length.

To allow for this, \verb"any" distinguished name can be given a mapping
name, which will be used as the \unix/ sub-directory name.
For example the entry for ``o=University College London'', may be mapped and
stored in the file \file{UCL/EDB}.
The mapped names are specified in a file \file{EDB.map}\index{EDB.map file},
the syntax of which is:
\begin{quote}\begin{verbatim}
<Distinguished Name> `#' <Mapped name>
\end{verbatim}\end{quote}
so for the example used above the file will contain:
\begin{quote}\begin{verbatim}
o=University College London#UCL
\end{verbatim}\end{quote}

If a name is not found in the mapping file, then the long directory name will
be used. 

When a DSA needs to create a sub-directory (e.g after an add operation)
it will use the relative distinguished name for each subdirectory,
unless the name is longer than the maximum number of allowed characters
(usually 15), in which case it will generate a shorter mapped name.

\f

\section {Setting up an Initial DSA}

These instructions are assuming that you are trying to set up a DSA with the
following characteristics:-
\begin{itemize}
\item It is the first DSA in an Organisation
\item It is not the first DSA in the Country
\item It holds a copy of the root EDB
\end{itemize}

This is found in the example:-
\begin{quote}
\file{others/quipu/quipu-db/organisation} 
\end{quote}

There are two other examples which might also be used as illustrations for
national DSAs and organisational DSAs not holding a copy of the root EDB.
These are in :-
\begin{quote}
\file{others/quipu/quipu-db/national}
\end{quote}
and
\begin{quote}
\file{others/quipu/quipu-db/non-root}
\end{quote}

Note that if you are going to be running a DSA in the United States,
then you should skip this section and refer to the document
\cite{NYSER.Admin},
which is provided in the ISODE documentation set
(look in the source tree area for the directory \file{doc/whitepages/admin/}).
This document describes turn-key installation mechanisms for DSAs in the
United States.

To start a DSA with one of these example databases
go into the relevant database directory and type:-
\begin{quote}\begin{verbatim}
$(SBINDIR)ros.quipu -t ./quiputailor
\end{verbatim}\end{quote}

The \tt -t\rm \ flag tells Quipu to use the tailor file \file{./quiputailor}
rather than the default file (\file{quiputailor} in the ISODE \verb"ETCDIR"
directory).

This will cause the DSA to print some logging information onto the screen,
followed by the message
\begin{quote}\begin{verbatim}
DSA c=GB@cn=toucan has started on localHost=17003
\end{verbatim}\end{quote}

\begin{figure}
\smaller
\begin{verbatim}
cn=Toucan
presentationAddress= localHost=17003
edbinfo= #cn=giant tortoise##
description= Demonstration slave-root DSA
description= Bird with large colourful bill.
objectClass= quipuDSA & quipuObject
manager= c=GB@o=University College London@ou=Computer Science@cn=Colin Robbins
acl= self # write # attributes # acl $ userPassword
acl= others # compare # attributes # acl $ userPassword
userPassword = toucan
quipuVersion= 6.0 Distribution
supportedApplicationContext= QuipuDSP & X500DSP & X500DAP
\end{verbatim}
\caption{Example DSA Entry}
\label{DSA:Toucan}
\end{figure}

The default setup assumes you have TCP/IP access and starts a DSA on the IP
address of the local machine (127.0.0.1).  If you do not have TCP/IP, you
will need to change the address the DSA will attempt to listen on.
This is done by editing the file 
\begin{quote}
\file{others/quipu/quipu-db/organisation/c=GB/EDB}
\end{quote}
The first entry in this file is the entry for a DSA called
``c=GB@cn=Toucan'', which is the name of the DSA we are trying to start (as
defined by the ``mydsaname'' entry in quiputailor).
The entry is shown in Figure~\ref{DSA:Toucan}.
The attribute \verb"presentationAddress" defines the address that the DSA is
going to listen to the network on.
If you need to listen on a different address, you should change the value of
the attribute to the address you want to listen on.
For more details of address see \volone/ of this manual and
\cite{String.Addresses}, an example of an X.25 address is given below:
\begin{quote}\begin{verbatim}
presentationAddress= Int-X25(80)=23421920030045
\end{verbatim}\end{quote}

Having started your DSAs you should be able to connect to it by
invoking \pgm{dish}. If you are using the default DSA address, and are
using the default \file{dsaptailor} file, then invoking \pgm{dish}
without arguments is sufficient.
If you are not using the default address or ``dsaptailor'' file, then you
will need to edit \file{dsaptailor} in the ISODE \verb"ETCDIR" directory.
You should add an entry
\begin{quote}\begin{verbatim}
dsa_address  toucan  <presentation address>
\end{verbatim}\end{quote}
Note that \verb+<presentation address>+ should have {\em exactly} the same
value as 
the \verb+presentationAddress+ attribute in the DSAs entry in the EDB file.
Now to contact the DSA use
\begin{quote}\begin{verbatim}
dish -c toucan
\end{verbatim}\end{quote}


Once connected to the DSA, try issuing the
command:-
\begin{quote}\small\begin{verbatim}
list "@c=GB@o=University College London@ou=Computer Science"
\end{verbatim}\end{quote}
You should get a list of four names 
back:-
\begin{quote}\begin{verbatim}
1 commonName=Colin Robbins
2 userid=quipu%commonName=Colin Robbins
3 commonName=Steve Kille
4 commonName=Michael Roe
\end{verbatim}\end{quote}
If this happens you have a working DSA.
(The entry numbered 2, is an example of an RDN with multiple values !)

\subsection{Setting up YOUR DSA}
The examples are tailored to start a DSA called ``toucan'',
and will be sufficient to get an example DSA started,
but this will not be of much use when you want to start adding you own data.
To allow other DSA to connect to you, you will need a new unique
distinguished name for
your own DSA.
Section~\ref{dsa:connect} describes how to choose a name for your DSA and set
up the connections.

A DSA needs to find the entry associated with its own name, it will generally
be able to find this in the local database (the entry ``cn=toucan'' 
in the file \file{quipu-db/organisation/c=GB/EDB} for example).

Having located its own entry, a DSA will know its network 
address by looking at the \verb+presentionAddress+ attribute,
hence it can start listening for operations.

But first it must load the database.
In its own entry it will have a \verb"edbInfo" attribute, this 
describes which EDBs the DSA is expected to hold.
The format of the \verb"edbInfo" \index{edbInfo attribute} attribute is described fully in 
Section~\ref{slave_update}, but essentially the first parameter
supplied says ``load this EDB''. Thus the attribute
\begin{quote}\begin{verbatim}
edbInfo = ##
edbInfo = c=US@o=The Wollongong Group ##
edbInfo = c=GB ##
\end{verbatim}\end{quote}
requests that the EDB files 
\begin{quote}
\file{quipu-db/EDB}
\end{quote}
(signified by no data before the first `\verb+#+' sign),
\begin{quote}
\file{quipu-db/c=US/o=The Wollongong Group/EDB} 
\end{quote}
and 
\begin{quote}
\file{quipu-db/c=GB/EDB}
\end{quote}
are loaded.

There are a few other important attributes your DSAs entry should have, the ``toucan''
entry in Figure~\ref{DSA:Toucan} gives examples of the other attributes.
They are briefly described below.
\begin{describe}
\item[description] A Textual message describing the DSA, and the wildlife!
\item[quipuVersion] This should contain the version number of the
Quipu software you are using.  This can be found by using the dish
command \verb+squid -version+.
\item[manager] The DN of the manager of the DSA, this user will not be blocked by
access control when modifying the local database over DAP.
\item[supportedApplicationContext] This should always have the value
\begin{quote}\begin{verbatim}
QuipuDSP \& X500DSP \& X500DAP
\end{verbatim}\end{quote}
for this version of Quipu.
It is used by remote DSAs to decide which protocols your
 DSA supports, and
thus how best to contact it.
\end{describe}

To connect a DUA to this DSA, 
try typing \verb"dish", the DUA will try to contact the default DSA.

If you have changed the address of the default DSA
(by modifying the ``presentationAddress'' attribute of the DSAs entry)
you will need to modify the 
\verb"dsa_address" variable in the file \file{dsaptailor} to tell the DUAs
your DSAs address.
If you add
\begin{quote}\begin{verbatim}
dsa_address mydsa <the presentation address>
\end{verbatim}\end{quote}
to your \file{dsaptailor} file, then
\begin{quote}\begin{verbatim}
dish -c mydsa
\end{verbatim}\end{quote}
should connect you to your new DSA.

Section~\ref{adding_data} describes how you can add data to you DSA by
extending the supplied textual database to include your 
own data
or by sending data to the Directory via the DUA modify operations.
This may be done independently from connecting to the global directory.

\f

\section {Tailoring}\label{dsa:tailor}

On start up the DSA first consults a run time tailor file \index{quiputailor}
(the default DSA tailor file is called \file{quiputailor} in the ISODE
\verb"ETCDIR" directory, but can be
changed with a \verb"-t" parameter to \pgm{ros.quipu};
consult \man quipu(8c) for details),
which indicates such things as:

\begin{itemize}
\item
name of the DSA
\item
location of the database
\item
location and level of the logs that the DSA will produce.
\item
location of any other DSAs for initial bootstrap
\end{itemize}


The format is identical to the DUA tailor file
described in Section~\ref{dua:tailor}, with the addition of the
following options:
\begin{describe}
\item [\verb"mydsaname":]
The distinguished name of the DSA.
For example,
\begin{quote}\small\begin{verbatim}
mydsaname   CN=axolotl
\end{verbatim}\end{quote}
declares this DSA to have the common name of \verb"axolotl".

\item [\verb"parent":]
This entry consists of a name/address pair of a parent DSA,
and is needed only for DSAs not holding the root EDB.
The DSA referenced needs to hold a Master or Slave copy of an EDB
higher up in the DIT than the highest locally held EDB.
If more than one \verb"parent" tailor entries are found, the DSA
will chose which DSA to contact.  The algorithm for making this
choice has not been fully explored yet
(currently, the first entry is always used, if this fails the second\ldots).
For example,
\begin{quote}\small\begin{verbatim}
parent C=GB@CN=vicuna Internet=vs1.ucl.cs.ac.uk+50987
\end{verbatim}\end{quote}
\index{presentation addresses}
declares the parent DSA to be ``C=GB@CN=vicuna'' at the
indicated address.

\item [\verb"stats":]
The value has the same format as the \verb"dsaplog" entry described in
Section~\ref{dua:tailor}, and is used to control the level of
DSA statistical logging.

\item [\verb"nameserver":]
The value ``off'' prevents Nameserver access to the directory, 
by default this parameter is ``on''.
The nameserver is discussed in Chapter~\ref{quipu:ns}.

\item [\verb"treedir":]
Defines the directory in which the textual database is stored.
For example,
\begin{quote}\small\begin{verbatim}
treedir     /usr/etc/quipu-db/
\end{verbatim}\end{quote}
declares the directory \file{/usr/etc/quipu-db/} to contain the local
part of the Directory Information Tree.

\item [\verb"update":]
The value ``on'' tells the DSA to update SLAVE EDB files when it starts up.
See section \ref{slave_update} for further details, by default 
this parameter is ``off''.

\item [\verb"searchlevel":] Defines the level from which users will be able
to search the DIT --- default 2 (e.g organisations).
If they try to search from higher up, a ``unwilling to perform'' service
error will result.

\item [\verb"lastmodified":] If `\verb"off"', `\verb+lastmodifiedby+'
attributes will not be added by the DSA when an entry is altered.

\item[\verb"readonly":] Bring the DSA up in ``read only'' mode --- that is
prevent user modification.  Slave updates are still allowed.

\item [\verb"dspchaining":]
The value ``on'' tells the DSA to chain DSP requests to other DSAs 
if necessary.
The default mode of operation is to return a DSA referral.
The full set of issues deciding whether to use chaining or referrals
is discussed in the QUIPU design document (\cite{QUIPU.Design}), and 
\cite{QUIPU.Navigate}.

\item [\verb"adminsize":] The administrative size limit for use on search
and list operations.

\item[\verb"admintime":] The maximum time allow to spend on a user query.

\item[\verb"cachetime":] The length of time to keep / use ``cached''
information.

\item[\verb"conntime":] The length of time to hold a unused connection open.

\item[\verb"nsaptime":] The length of time to wait before deciding a
connection can not be established for a given NSAP.

\item[\verb"retrytime":] The length of time before deciding it is worth
attempting to connect to a DSA that could not be contacted earlier.

\item[\verb"slavetime":] The length of time between attempting to update
slave EDB files.

\item[\verb"preferdsa":] When a DSA has creates a reference to other DSAs it
tries to discriminate between and chose the "best" DSA to contact.
This variable gives you a handle on controlling the choice. For example the
lines
\begin{verbatim}
preferDSA c=GB@cn=Vicuna
preferDSA cn=Giant Tortoise
\end{verbatim}
tells the DSA to use either ``c=GB@cn=Vicuna'' or ``cn=Giant Tortoise'' in
preference to any other DSA.  Further, use the DSA ``c=GB@cn=Vicuna'' rather than
``cn=Giant Tortoise'' if possible.

\item[\verb"cainfo":] For authentication.

\item[\verb"secretkey":] For authentication.

\item[\verb"bindwindow":] For authentication.

\item [\verb"isode":]
The argument is an \verb"isodevariable" \verb"isodevalue" pair as would 
be found in \file{isotailor}.  This is used to ``override'' isotailor
settings.
\end{describe}

\subsection {Tailoring a Running DSA}
\label{dsa:mgmt}

The tailoring described above is performed when the DSA is
booted.  It is sometimes useful to alter the tailor settings
after the DSA has started without having to bring
the DSA down and rebooting.  This can be done by via
the  special ``{\bf dsacontrol}'' command in the \man dish(1c) program
as described in Section~\ref{dua:mgmt} on page~\pageref{dua:mgmt}.

The DUA invokes a modify operation, with a
single special attribute ``dSAControl'' defined in \cite{QUIPU.Design}.
The DSA recognises the special attribute, and provided you are
bound as the manager of the DSA, passes the attribute value to the
appropriate routine.

\cite{QUIPU.Design} describes this process in full.

\f

\section {Connection to Other DSAs}
\label{dsa:connect}

All QUIPU DSAs should be connected. This section describes how you should 
configure your DSA to connect to other DSAs in order
to read the data not held locally.
Section \ref{dsa:global} describes how to make sure that other DSAs can access your DSA
(See Appendix~\ref{dsa:sites} on page~\pageref{dsa:sites} for a partial list
of registered QUIPU DSAs.)

A dynamic approach is used to bootstrap a new DSA.
The ``global master'' DSA is administered at UCL,
and other DSAs should be configured in relation to this one.

Every DSA needs to know the distinguished name and
presentation address of one
or more DSA's nearer to, or actually holding, the root EDB.  This parameter
is supplied in the tailor file (see Section~\ref{dsa:tailor})
under the name \verb"parent".
This information is used by the QUIPU DSA when it can not find a DSAs entry
in the local database, or can find no pointers in the local database to the
whereabouts of the data.
If you hold a \verb"SLAVE" copy of the root EDB, then your 
parent should be a DSA that is ``closer'' to the MASTER copy of the root
EDB.

The example databases are set up with default parents (defined in the file
\file{quipu-db/organisation/quiputailor})
To see if your DSA can contact the ``parent'', connect to
the local test (root holding) DSA using \verb"dish", and type

\begin{quote}\begin{verbatim}
list @
\end{verbatim}\end{quote}

This will list the locally held root, now try

\begin{quote}\begin{verbatim}
list @ -dontusecopy
\end{verbatim}\end{quote}

This will try to connect to the parent DSA.
If it is successful, there should be a lot more data returned.

Care should be taken in choosing the parent
DSA. If all DSAs have the same parent
DSA then that DSA will become overloaded.
Typically each site will have several DSAs. One of these should
be the default parent for all the other DSAs, with only one DSA having a 
default parent outside the site.


When ``walking down'' the DIT, QUIPU needs access to information to tell it
on which DSA the next level of the DIT is stored.
To do this each non-leaf entry MUST have a ``masterDSA''\index{masterDSA attribute}
or ``slaveDSA''
attribute.  The value of the attribute is the distinguished name of the DSA
holding the next level of the DIT (it may be your own DSA name, if you hold
the next level as well).  If there is no such attribute, QUIPU assumes the
entry is a leaf.
If the information required is not held in the local DSA then QUIPU
chains the request to the named DSA or returns a referral 
--- depending upon the mode of operation
(The named DSAs entry is read to establish the
address --- this may mean a connection to another DSA 
in-order to read the entry).

Once you have started your DSA, you should try to connect to other DSAs 
using the \verb"DISH" program (this connects to the local DSA, which will
chain requests to other DSAs).  Try listing the children of
organisations other than yourself, to find which organisations are connected,
try listing your countries children.

\subsection {Choosing a Name for Your DSA}
\label{dsa:naming}
Every QUIPU DSA MUST have an entry in the DIT, hence
your DSA will need a unique distinguished name.
The name ``cn=Toucan''
given in the example databases is not unique.
There are two aspects to consider in choosing a name for you DSA.

This entry is used by other DSAs to identify you DSA, and so is needed if 
other DSAs are going to be able to see your DSA.

Firstly, it is a QUIPU convention that DSAs should be named 
after endangered South
American wildlife, and that the entry for the DSA should contain a
description of the animal or plant in question.
Some examples are shown in Table~\ref{wildlife}.
A more comprehensive list can be found in the IUCN's ``Red Book''
\cite{IUCN.Mammal}.

Secondly, the entry for your DSA must be visible to other DSAs who do not know
how to contact your DSA.
So, the MASTER copy of your DSAs own entry must be held at least one level higher up
in the DIT than the part of the DIT it holds as \verb"MASTER" data.
For example the DSA which holds
``c=GB @ o=University College London @ ou=Computer Science'', 
must be held at the
``c=GB @ o=University College London'' level 
(e.g. ``c=GB @ o=University College London @ cn=wombat'') or above.
Such naming also helps prevent loops as described more fully in
\cite{QUIPU.Design}.

In practice DSAs should be named fairly high up the tree.
Each country should have at least two DSAs named at the root level.
Each Organisation should have at least two DSA named at the national level.

\tagtable[tp]{q-1}{Endangered South American Wildlife}{wildlife}

You should use \pgm{dish} to find out if the name you want is already taken.
For example,
if you are creating a DSA for an organization in Great Britain,
you might use:
\begin{quote}\small\begin{verbatim}
% dish -c "Giant Tortoise"
Welcome to Dish (DIrectory SHell)
Dish -> search @c=GB -filter objectClass=dsa
\end{verbatim}\end{quote}
This will print out the list of names already in use.

Having chosen a name, you will need to tell your DSA its name, and 
make sure it can find an EDB file for its own entry.

A DSA finds it own name from the ``mydsaname'' variable defined in the file
\file{quiputailor} (see Section~\ref{dsa:tailor} for details).
An example \verb"quiputailor" entry would be:-
\begin{quote}\small\begin{verbatim}
mydsaname:	"c=GB@cn=a dsa name"
\end{verbatim}\end{quote}
Having read this name from \verb"quiputailor", a DSA will try to find
the corresponding entry.
The process for doing this is complex, and is 
described in full in Section~\ref{dsa:starting}. Essentially the 
DSA needs to find the EDB file holding the entry, and hence you MUST
supply it, if supplied correctly it will be found.

If you hold the EDB that the entry should be in, simply
make sure the entry is in that EDB and then it will be found.
If you do not hold, and do not want to hold the EDB in which your
DSA is named (e.g., your DSA is called \verb"c=GB@cn=toucan" but 
you do not hold the EDB \verb"c=GB"), then you should (normally)
supply a cached copy of the EDB which contains only the 
entry for the DSA, and not all the others entries the full EDB would have.
If you do not supply it, your DSA will have to rely on others DSAs before it
can start.

\f

\subsection {Connection to the Global Directory}\label{dsa:global}


To enable the global directory to connect to you, you must contact the
manager of the DSA immediately above the node you want to added under.
Supply them with the entry for your DSA, and the top level 
entry of the sub-tree
you want to hold.
For example, to add the organisation ``o=foobar'' below ``c=US'',
contact the manager of the DSA holding ``c=US'' as a MASTER, giving them the
entry for ``c=US@o=foobar'' and ``c=US@cn=foobar\_dsa'', assuming
``c=US@cn=foobar\_dsa'' is the name of your DSA (see Section~\ref{dsa:naming}
on naming a DSA).

By convention,
to find out who administers the master EDB for a particular node,
run the \man dish(1c) program and retrieve the \verb"manager" attribute
from the entry for the DSA holding that node.

You can then find a mail address by looking that person up in the directory.

The following example shows you how to get the mail address of the
manager of the c=GB subtree. 

\begin{verbatim}
% dish
Welcome to Dish (DIrectory SHell)
Dish -> showentry @c=GB -type masterDSA
masterDSA 	- cn = Giant Tortoise
Dish -> showentry "@cn=Giant Tortoise" -type manager
manager         - countryName=GB
                  organization=University College London
                  organizationalUnit=Computer Science
                  commonName=Colin Robbins
Dish -> moveto "@c=gb@o=University College London @ 
        ou=Computer Science @ cn=Colin Robbins" 
Dish -> showentry -type rfc822Mailbox 
rfc822Mailbox	- C.Robbins@cs.ucl.ac.uk
Dish -> quit
%
\end{verbatim}

If you want to add data to the root node of the ``global tree''
(e.g., a new country) then you will probably want a copy of the 
ROOT EDB (or you might want a copy for other reasons).
The master can be accessed via the FTAM service at UCL as
file \file{$<$PUB$>$/masterEDB}.
(The address of this service is found in the {\bf Preface\/} of this volume.)
If you are unable to access the FTAM service,
a copy of the master can also be obtained from the {\em quipu-support} 
address given in Section~\ref{quipu:support}.
Having obtained the root EDB, add the new entries, and mail the new
information to the {\em quipu-support} address given in
Section~\ref{quipu:support}.

To keep this EDB upto date you should use the ``getEDB'' 
operation discussed in Section~\ref{slave_update} (this can also be used to
get the EDB in the first place).

When you think you are connected to the ``global DIT'', 
you should test that you are.  To do this use \verb"dish" to connect 
to a DSA higher than you in the DIT (using the \verb"-call" flag as described
in Section~\ref{dua:tailor}, then see if you can navigate to your
own part of the DIT, and look at your data --- if so 
then the DSA is connected.

\section {Adding more Data}
\label{adding_data}

Having got a DSA started, and connected to the global DIT, you should start
to add lots of data.
There are many sources of such data, and with just a relatively small amount
of effort this data can be added to the directory.

There are two ways such data can be added.
First of all you can use one of the DUA programs to bind to the DSA as the
DSA manager, and send data to the directory via the ``add'' and ``modify'' 
operations (see Sections~\ref{dish:add} and \ref{dish:modify}).
This is probably the best way to add relatively small amounts of data,
or make minor changes to the data.

To add a large amount of data (i.e., the initial creation of a 
large database) if is probably easiest to write a shell script using \unix/
tools such as \verb"awk" and \verb"grep" to create the EDB files directly.
In the next version of the software there will be tools to facilitate this.

When adding data for users it is advisable to allocate a ``userPassword''.
\index{user password attribute}
Chapter~\ref{Security} describes how to do this.

\subsection {More on Object Classes}
The only object class discussed so far is the ``quipuDSA'' objectclass.
When you start to add data, you will probably want to add information about
people, sub-divisions of your organisation, and other application entities.
This Section introduces some of the more important object classes, and the
attributes they may contain.
In many cases, only the attribute type is specified, for details of typical
values and the value syntax you should read Chapter~\ref{syntaxes}.

As already discribed, every entry in the DIT must belong to the object
class \verb+top+, which means every entry must have an \verb+objectClass+
attribute.
Also, every entry in the Quipu DIT should belong to either the
\verb+quipuNonLeafObject+ or \verb+quipuObject+.

\subsubsection{Person}
This is a base object class used to represent a person.

There are two mandatory attributes:
\begin{describe}
\item[commonName:]
			which gives a (potentially ambiguous) name for
			the person.
			The value of this attribute is a string usually
			containing the person's first and last names; e.g.,
\begin{quote}\small\begin{verbatim}
Marshall Rose
\end{verbatim}\end{quote}
			This attribute is usually multi-valued, containing
			variations on the first, middle, and last names; e.g.,
\begin{quote}\small\begin{verbatim}
Colin Robbins
Colin John Robbins
Colin J. Robbins
\end{verbatim}\end{quote}
			Generally this attribute will supply the
			distinguished attribute of the entry.
\item[surName:]
			which gives the person's last name.
\end{describe}

The optional attributes are:-
\begin{quote}\small\begin{verbatim}
userPassword
seeAlso
telephoneNumber
description
\end{verbatim}\end{quote}

\subsubsection{OrganizationalPerson}
This is a sub-class of \verb+person+ and introduces the following optional
attributes:-
\begin{quote}\small\begin{verbatim}
preferredDeliveryMethod
destinationIndicator
registeredAddress
internationaliSDNNumber
x121Address
facsimileTelephoneNumber
teletexTerminalIdentifier
telexNumber
physicalDeliveryOfficeName
postOfficeBox
postalCode
postalAddress
title
organizationalUnitName
streetAddress
stateOrProvinceName
locality
\end{verbatim}\end{quote}

\subsubsection{ThornPerson}
like \verb+OrganizationalPerson+, this is also a sub-class of \verb+person+ 
and introduces the following optional
attributes:-
\begin{quote}\small\begin{verbatim}
homePostalAddress
lastModifiedBy
lastModifiedTime
secretary
homePhone
userClass
photo
roomNumber
favouriteDrink
info
rfc822Mailbox
textEncodedORaddress
userid
\end{verbatim}\end{quote}

Two example \verb+ThornPerson+ entries are given in Figure~\ref{example_edb} on
page~\pageref{example_edb}.

\subsubsection{OrganizationalRole}
Entries of this class are used to represent a position or role within an
organization.  

There is one mandatory attribute:
\begin{describe}
\item[commonName:]	which gives the name of the role.
			The value of this attribute is a string; e.g.,
\begin{quote}\small\begin{verbatim}
PostMaster
\end{verbatim}\end{quote}
\end{describe}

There are many optional attributes including:
\begin{describe}
\item[roleOccupant:]    which is the Distinguished Name of the person 
			who fulfills the role e.g.,
\begin{quote}\small\begin{verbatim}
c=US@o=NYSERNet Inc.@ou=Operations@cn=Chris Kolb
\end{verbatim}\end{quote}
\end{describe}

The other optional attributes are:
\begin{quote}\small\begin{verbatim}
seeAlso
preferredDeliveryMethod
destinationIndicator
registeredAddress
internationaliSDNNumber
x121Address
facsimileTelephoneNumber
teletexTerminalIdentifier
telexNumber
telephoneNumber
physicalDeliveryOfficeName
postOfficeBox
postalCode
postalAddress
description
organizationalUnitName
streetAddress
stateOrProvinceName
locality
\end{verbatim}\end{quote}


\subsubsection{Alias}
Objects of this class represent an alias to some other entry in the
DIT.  It is generaly used when an entity belongs in one or more subtrees of
the DIT, and is used to ``point'' one entry at the other.

There are two mandatory attributes:
\begin{describe}
\item[commonName:]	which gives the name of the alias.
			The value of this attribute is a string; e.g.,
\begin{quote}\small\begin{verbatim}
Colin Robbins
\end{verbatim}\end{quote}

\item[aliasedObjectName:] which is a pointer to another object in the Directory;
			e.g.,
\begin{quote}\small\begin{verbatim}
c=GB@o=University College London@ou=Computer Science@cn=Colin Robbins
\end{verbatim}\end{quote}
\end{describe}
There are no optional attributes for this object class.

An example of an Alias entry is given below:-
\begin{quote}\small\begin{verbatim}
cn= Quipu-support
aliasedObjectName= c=GB@o=University College London@ou=Computer
                   Science@cn=Incads
objectClass= quipuObject & alias & top
\end{verbatim}\end{quote}

\subsubsection{OrganizationalUnit}
The \verb+OrganisationalUnit+ object class is used to represent a unit within
your organisation.
There is one mandatory attribute
\begin{describe}
\item[organizationalUnitName:]
			which gives the name of the organizational unit.
			The value of this attribute is a string; e.g.,
\begin{quote}\small\begin{verbatim}
Research and Development
\end{verbatim}\end{quote}
\end{describe}

The optional attributes are:-
\begin{quote}\small\begin{verbatim}
userPassword
seeAlso
preferredDeliveryMethod
destinationIndicator
registeredAddress
internationaliSDNNumber
x121Address
facsimileTelephoneNumber
teletexTerminalIdentifier
telexNumber
telephoneNumber
physicalDeliveryOfficeName
postOfficeBox
postalCode
postalAddress
businessCategory
searchGuide
description
streetAddress
stateOrProvinceName
locality
\end{verbatim}\end{quote}

\subsubsection{Organization}
Objects of this class represent a top-level organizational entity,
such as a corporation, university, government entity, and so on.

There is one mandatory attribute:
\begin{describe}
\item[organizationName:]
			which gives the name of the organization.
			The value of this attribute is a string; e.g.,
\begin{quote}\small\begin{verbatim}
NYSERNet Inc.
\end{verbatim}\end{quote}
\end{describe}

The optional attributes are:-
\begin{quote}\small\begin{verbatim}
userPassword
seeAlso
preferredDeliveryMethod
destinationIndicator
registeredAddress
internationaliSDNNumber
x121Address
facsimileTelephoneNumber
teletexTerminalIdentifier
telexNumber
telephoneNumber
physicalDeliveryOfficeName
postOfficeBox
postalCode
postalAddress
businessCategory
searchGuide
description
streetAddress
stateOrProvinceName
locality
\end{verbatim}\end{quote}

\subsubsection	{domainRelatedObject}
If an object has some relationship to the Internet Domain Name System (DNS),
then this can be represented in the DIT using this objectclass.

This class has one mandatory attribute:
\begin{describe}
\item[associatedDomain:]
			identifies the domain which corresponds to this object.
			The value is a domain string, e.g.,
\begin{quote}\small\begin{verbatim}
nyser.net
cs.ucl.ac.uk
\end{verbatim}\end{quote}
\end{describe}

\subsection {Schemas}
\label{quipu:schema}

Directories should provide a very flexible tool
which enables any information to be stored.  There is a danger that Schemas,
as specified in the OSI Directory, will lead to procrustean directory implementations
which impose unreasonable restrictions.  The QUIPU Directory does not, per
se, place restrictions on what can be placed in a DSA.
It does however give control so that managers may control what is stored in the
directory.

The first aspect of structure is with respect to attributes which may be
present in an entry.  A QUIPU DSA will allow an entry to belong to one or
more object classes which are known to the DSA (stored in a table).  An
entry will typically have a small number of object classes (e.g., TOP
(implicit) + Person + Organisational Person + QUIPU Object).  The DSA will
maintain a table of mandatory and optional attributes for each object class
supported.  This will be follow the guidelines of the standard or
specification identifying the object class in question.  From this
information, the DSA can determine the permitted and mandatory attributes for a
given entry, by calculating the union of all the object classes of that
entry.  Free extension (i.e., the ability to store any attribute) was
rejected, as there does not appear to be a reasonable mechanism to manage
this.  However, it is straightforward for managers to create new object
classes as desired.

\tagrind[htb]{schema}{Schema definition}{schema-py}

It is important 
to allow management control of what is permitted at a given level.
Therefore a ``tree structure''
attribute may be created.  
This attribute is defined in Figure~\ref{schema-py}, with the string syntax
discussed in ~\ref{tree_struct}.
This specifies for the level below,
what types of object are permitted.  
Each attribute value identifies a class of object which can exist at the level
below, and 
defines a set of mandatory and optional object classes.
This can be considered as defining a (private) object class implied by the
combination of these classes.
For each type of object, the attribute types permitted in the RDN are also
listed.  This is not checked in QUIPU-6.0
The directory knows about the tree structure attribute, and will
ensure consistency.  
When creating an entry, the DSA must check that it conforms to the
treeStructure attribute of the parent entry.
When removing information from a treeStructure attribute, the
Directory will  check that all of the children conform to the
modified attribute.

\subsection {Photograph Attributes}
\label{dua:photo}

The data that a DSA can hold does not have to be limited to data that can be
represented by printable strings.
Any attribute a QUIPU DSA does not know a string syntax for, it will hold as
a block of ASN.1.
One such attribute is the ``photo'' attribute.
Photographs of people and objects are stored in the directory as a
g3fax encoded block of ASN.1, and are best stored as ``file'' attributes
described in the next Section.
There is an example of a photograph attribute in the example database.
This can be looked at by connecting to the directory with \verb"dish"
and looking at the entry 
``c= GB @ o= University College London @ ou= Computer Science @ cn= Steve Kille"


Unless you you have compiled and installed the ``photo'' code as 
described in Section~\ref{quipu:install} you will see the message
\begin{quote}\begin{verbatim}
``No display process defined''
\end{verbatim}\end{quote}

Having compiled the ``photo'' code, you will need to add a line such
as
\begin{quote}\small\begin{verbatim}
photo xterm Xphoto
\end{verbatim}\end{quote}
to your dsaptailor file (see Section~\ref{dua:tailor})
This says that if the user in logged on to a terminal
of the type \verb"xterm" then use the process \file{g3fax/Xphoto}
in the ISODE \verb"ETCDIR" directory to display the photograph.

There are display routines provided for the X~window system, SunView,
Tektronix~4014, and ``dumb'' terminals.

\subsection {File Attributes}
\label{file_attr}
Attributes values are generally stored in the EDB file, and loaded 
into memory when the DSA starts.
For some large attributes such a photos, this is not a sensible approach, so the
concept of a ``file'' attribute is introduced.

If an attribute value is prefixed by \verb"FILE", then the value is assumed
to be stored on disk.
For example if the following were found in an EDB file:-
\begin{quote}\small\begin{verbatim}
photo = {FILE} /usr/local/pictures/steve
\end{verbatim}\end{quote}
then the value for the photo attribute would be read from the file
\begin{quote}
\verb"/usr/local/pictures/steve".
\end{quote}

The syntax of the data in the file is expected to be the same as
the string syntax, except in the case of ASN and PHOTO attributes which
are expected to be in raw ASN.1.

If there is not a file name supplied, then a default name is allocated.
The default file name is the RDN of the entry the attribute belongs to
followed by a dot ``.'', followed by the attributeType. This file is expected
to be in the same directory as the EDB file for the entry.
For example the default file for photo attribute, representing the entry
for 
``c= GB @ o= University College London @ 
ou= Computer Science @ cn= Colin Robbins''
 would be:-
\begin{quote}\small\begin{verbatim}
cn=Colin Robbins.photo
\end{verbatim}\end{quote}
in the directory
\begin{quote}\small\begin{verbatim}
quipu-db/c=GB/o=University College London/ou=Computer Science
\end{verbatim}\end{quote}
or equivalent mapped file as described in Section~\ref{EDB:mapped}.

The process defined so far allows for attribute stored in a EDB in file
format to be read by a DSA.
Writing the attributes back to files if modified/added by a DUA requires
a little more.
The DSA needs to know which attributes should be stored on disk.
This information is supplied in the attribute oidtables which are 
defined in Section~\ref{oidtables}.
For example if the following entry was found in the file
\file{oidtable.at} in the ISODE \verb"ETCDIR" directory
then a ``photo'' attributed would always be written
back to disk.
\begin{quote}\small\begin{verbatim}
photo:  thornAttribute.7: photo : file
\end{verbatim}\end{quote}


\section {How a DSA Starts}
\label{dsa:starting}

The Section gives a brief description of how a QUIPU DSA starts.
This is intended to help people who have experienced problems in getting
their DSAs started.

First of all the tailor file \file{quiputailor} in the ISODE \verb"ETCDIR" directory
is read (unless you
specify a different tailor file using the \verb"-t" option to
\pgm{ros.quipu}).
This tells the DSA, amongst other things, its own name, and its parent
DSA(s).

The first thing a DSA need to do if find its own entry, thus it tries to
load the EDB that should contain it.
If it can not find its own entry, then it will try connecting to the
parent DSA to read its own entry. If this fails the DSA will stop.

Having found its own entry, the DSA will check to see if it is a cached
entry read from disk, if so it will attempt to read a new version from the
parent --- if successful a new cache EDB file will be written.

Now the rest of the local DIT can be loaded.  Each EDB specified in the
``edbInfo'' attribute \index{edbInfo attribute} is in turn loaded from disk.

As each EDB is loaded from disk, it is checked to make sure all the
attributes in the entry are allowed, as defined by the ``objectClass''
attribute, \index{objectClass attribute} and that the tree shape conforms to that defined by the
``treeStruture'' attribute. \index{treeStructure attribute}
If any EDB fails these checks then the DSA will not start, and an appropriate
message will be logged.

A check is now made on the \verb"quipuVersion" \index{quipuVersion attribute}
that a DSA entry MUST contain.
If this attribute does not have the same version string as the 
running DSA process, a warning message is printed to the logs.
On seeing this message, you should update the version string
in your DSAs entry.
Future version of the software will maintain the attribute for you.

Having loaded all its data, the DSA will start listening for DAP and DSP
associations (and ``nameserver'' accesses if required --- see
Chapter~\ref{quipu:ns}).

\section {Adding more DSAs}

Many organisations will need to have more than one DSA to meet 
their requirements, the Section suggests how you might arrange your
DSAs to get the most out of the system.

You will almost certainly need at least one DSA that holds a
copy of the root EDB, and your country EDB.
This DSA should also hold the MASTER copy of your organisations own EDB.
Subsequent DSAs that are set up, should have this DSA defined 
as one of their parent DSAs.

For robustness, it is a good idea to have some other DSAs replicating 
these EDBs, so that if one local machine or DSA becomes unavailable, then
there is another copy elsewhere that can be used.
EDBs that contain addresses of other DSAs that you may want to contact
regularly should also be replicated, to prevent extra associations
having to be made just to read DSA addresses.
In short, if you know that data from a certain 
EDB is going to be accessed a lot, replicate it locally.
Replication does not have a high cost.

When setting up multiple DSAs be sure to name them as described in 
Section~\ref{dsa:naming},
ensure the DSA entries are sufficiently high in the DIT, so that other DSAs
can read the entry, without having to contact the DSA concerned.

\section {Receiving EDB Updates}
\label{slave_update}
If your DSA holds a slave copy of one or more EDBs, then it can
automatically update these for you.
The current approach is very simple minded, but will be extended for future
versions.

There are two ways to ask a DSA to update its slave EDBs, either use \pgm {dish}
program and issue a ``dsacontrol --slave'' command --- see 
Section~\ref{dua:mgmt}, or set the \verb"quiputailor" parameter
``update'' to ``on'' (see Section~\ref{dsa:tailor})
--- in which case the DSA will try to update its slaves
when it starts up.

To update the slaves, the DSA uses the ``edbinfo'' attribute that the DSAs
entry in the DIT MUST have.
This attribute specifies which EDBs you hold, and where to get updates of
the from.
NOTE you do not necessarily have to get updates from a \verb"MASTER" EDB,  
a \verb"SLAVE" is acceptable.
In many cases this will be preferable to prevent the 
load on the \verb"MASTER" DSA being too high.
For example a ``national'' EDB is likely to be highly replicated,
it would not be a good idea to have just one DSA
handling updates.  It would be better to have the load spread over several
DSAs.

The syntax of the attribute is \index{edbInfo attribute}
\begin{quote}\begin{verbatim}
edbinfo = EDB concerned # get from # send to
\end{verbatim}\end{quote}
It is a multi-valued attribute. 

A few examples:
\begin{quote}\small\begin{verbatim}
# cn=Giant Tortoise # cn=Fruit Bat
c=US # # cn=Fruit Bat
c=US # # c=US@cn=Spectacled Bear
c=US@l=NY # cn=Fruit Bat #
\end{verbatim}\end{quote}
Note that there is no harm to using multiple \verb"eDBinfo" lines,
even if they refer to the same EDB.
These lines indicate that:
\begin{itemize}
\item	The ROOT EDB is read from the \verb"cn=Giant Tortoise" DSA,
	further the \verb"cn=Fruit Bat" DSA is allowed to read the
	ROOT EDB from this DSA.
	This is an important point --- A DSA has to explicitly say it will
	allow you to update from it, before it will send EDB files.
	Thus if you want to pull EDB files from a remote DSA, you will need
	to ask the manager to add you DSA to their DSAs ``send to'' field.

\item	The \verb"cn=Fruit Bat" DSA and the \verb"c=US@cn=Spectacled Bear" DSA
	are allowed to read the EDB for \verb"c=US". 
	Note that the second and third line could be combined as:
\begin{quote}\small\begin{verbatim}
c=US # # cn=Fruit Bat$c=US@cn=Spectacled Bear
\end{verbatim}\end{quote}
\item	The DSA named \verb"cn=Fruit Bat" supplies the EDB for \verb"c=US@l=NY"
	to this DSA.
\end{itemize}

Whether to update is decided upon by looking at the version string, if the
two EDB files have a different version string, then the EDB will be updated.

\section {Tables}
\label {oidtables}
Throughout QUIPU, all the Object Identifiers that need to be specified, are
specified using a string representation, for example:-

\[\begin{tabular}{|l|l|} \hline
String representation & Object Identifier  \\ \hline 
attributeType & 2.5.4 \\
surname & 2.5.4.4 \\
streetAddress & 2.5.4.9 \\
organizationName & attributeType.10 \\ \hline
\end{tabular}\]

A set of Object Identifier tables in the ISODE \verb"ETCDIR" directory are
used to 
provide this mapping (see also Section~\ref{isobject} in \volone/).
In general the default table will be sufficient, 
this section describes the tables for those who want to extend
the default definitions.

This basic format is used to build up the specification of general object
identifiers.  
This file is by default named \file{oidtable.gen}, and has simple
mappings from string to oid.
These strings can then be used in the definition of further oids (for example
the ``organizationName'' oid in the table above).

This simple table is extended to give table formats for attributes
This file is by default named \file{oidtable.at}.
Each entry in this table is assumed to represent an attribute, so
in addition to mapping strings onto oids, 
it also defines the syntax for that attribute:-

\[\begin{tabular}{|l|l|l|} \hline
String representation & Object Identifier & Syntax\\ \hline
objectClass:&		attributeType.0:	&objectclass \\
aliasedObjectName:&     attributeType.1:	&dn\\
commonName,cn:&		attributeType.3:	&caseignorestring\\
searchGuide:&           attributeType.14:	&asn\\
x121Address:&           attributeType.24:	&numericstring\\
presentationAddress:& 	attributeType.29:	&presentationaddress\\
\hline
\end{tabular}\]

This says that the attribute named ``objectclass'' represents the oid
``attributeType.0'' --- using the expansion of ``attributeType'' (
as defined in the 
file \file{oidtable.gen}) thus gives the oid ``2.5.4.0''.
The syntax taken by the attribute value is ``objectclass''.

Similarly an ``aliasedObjectName'' has ``dn'' (DistinguishedName) syntax.
The recognised syntaxes are defined in the BNF in 
Appendix~\ref{bnf}.

After the ``syntax'' an extra optional parameter is allowed;
if this is the string ``\verb"file"'' the the relevant attribute is 
designated a file attribute --- see Section~\ref{file_attr} for a
description of file attributes.


The file \file{oidtable.oc} defines the object classes\index{object
class} QUIPU knows about.
The file again maps strings onto oids.
Each string is assumed to represent an object class, abd for each it
defines the hierarchy (which object classes it is a subclass of),
the mandatory attributes of the object class, and the optional attributes of
the object class.

For example the entry
\begin{quote}\small\begin{verbatim}
quipuObject:  	quipuObjectClass.2 : top : acl : \
                masterDSA, slaveDSA, treeStructure
\end{verbatim}\end{quote}

defines ``quipuObject'' to be an objectClass represented by the oid
``quipuObjectClass.2''.
It is a SUBCLASS of the object class ``top''.
An entry having this object class MUST have the attribute ``acl'', and MAY
have the attributes ``masterDSA'', ``slaveDSA'' and ``treeStructure''
(NOTE The similarity between this definition and the ASN.1 definition of
a ``quipuObject'' in Appendix \ref{naming}).

To allow for definitions of ``attribute sets'', there is a simple 
MACRO facility provided, for example, using the MACRO
\begin{quote}\small\begin{verbatim}
localeAttributeSet = localityName, streetAddress ...
\end{verbatim}\end{quote}
every occurrence of ``\verb"localeAttributeSet"'' will be replace by the right 
hand side expression.


With the definition of the ``string'' form of the oid it is also possible
to specify ONE abbreviation for the name.
The standard tables use the following abbreviations:-

\[\begin{tabular}{|l|l|}
\hline
c & countryName \\
o & organizationName \\
ou & organizationalUnitName \\
cn & commonName \\
co & friendlyCountryName \\
\hline
\end{tabular}\]

The abbreviated name may be used anywhere the full name would be allowed.


Every entry stored in the QUIPU DSA is checked against these tables to see if
the attributes supplied are allowed in the entry, to make sure the mandatory
attributes are present, and the attributes themselves have the correct syntax.

If you wish to add you own definitions to the tables you should add them to
the files 
\file{isode/dsap/oidtable.at.local},
\file{isode/dsap/oidtable.oc.local} and
\file{isode/dsap/oidtable.gen.local}
in that way, if a new set of tables are issued, you local entries will be
preserved.

\section{More Help Installing Quipu}
Contact ``quipu-support'',
the mail address is given in Section~\ref{quipu:support}.
DataMuseum.dk

DKUUG/EUUG Conference tapes

⟦d8b48fc4e⟧ TextFile

Derivation

TextFile
