⟦cce1e6102⟧

TextFile

% run this through LaTeX with the appropriate wrapper

\f

\chapter {Overview}

\f

\section {Introduction}

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.

\f

\section {Installing QUIPU}
\label{quipu:install}

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.

To install QUIPU, the library \man libdsap(3n) library needs to be made.
this can be achieved by typing \verb"make inst-all" in the 
\file{dsap} directory.

To make QUIPU itself type
\verb"make inst-all" in the \file{quipu} directory.
This will make both the QUIPU DSA (\pgm{ros.quipu}) and the 
default QUIPU DUA (\pgm{dish}).
If you only want to make \verb"dish" you should enter \verb"make dish".

The \pgm{widget}, \pgm{sunint} interfaces, a 
version of \pgm{dish} that runs directly 
from a \unix/ shell 
and \pgm{dishinit}
a script to create a default \file{.quipurc} file for new users.
can be installed by looking at 
\file{others/quipu/uips/READ-ME} 
To make these interfaces, you will have to installed the header files.
Thus, type \verb"make inst-all" in the directory \file{h/quipu}.
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.

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
\file{others/quipu/photo/READ-ME} and Section~\ref{dua:photo} of this Manual.


\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.

\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{/usr/etc/dsaptailor}, 
together with some other parameters.
The full set of parameters are described in Section \ref{dua:tailor}.

The \verb"dsaAddress" parametr defines the name and address of the DSA to 
initially contact. For example,
\begin{quote}\begin{verbatim}
dsaAddress  vicuna  \"qd\"/Internet=vs1.ucl.cs.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 when specifying the address of the DSA to connect to.
If there are more than one \verb"dsaAddress" entries, the first
entry will be used to supply the default DSA address.

A default dsaptailor file 
(taken from \file{isode/dsap/dua/dsaptailor}) is installed as
\file{/usr/etc/dsaptailor} 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,
hence try ``\verb"dish -call piranah"'', ``\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"dsaAddress" 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 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{/usr/etc/oidtable.*}.

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

\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 default service control ``sizelimit'' to be 20 entries.

\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"local\_dit":]
The argument is a distinguished name.  When a User Interface starts, you
will be automatically moved to this position in the DIT.

\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"dishinit":]
If the argument has the value \verb"on", then a DISH shell script 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"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"dflag"/\verb"sflag":]
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.

\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}

Before configuring a DSA you need to know a little about Directories.
This section is a brief tutorial on the key structures and their textual
representation within QUIPU.

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 {Object Identifiers}
An important part of the OSI Directory system is the Object Identifier (OID).

An OID is a hierarchy of numbers used to uniquely describe various objects
within the OSI world, for example ``1.0.8571.1.1'' describes the FTAM
protocol or ``0.9.2342.19200300.99.1'' 
defines a QUIPU Attribute Type.
The strings of numbers look ``horrible'' and can be difficult to remember.
Throughout QUIPU there is a mapping from OIDs to ``strings'', so that 
easy to remember strings can be used in place of the numeric OIDs, for
example ``iso ftam'' or ``quipuAttributeType''.

The mapping are defined in a set of oidtables which are discussed
in Section~\ref{oidtables}.

\subsection {Attributes}

All information stored in the directory is stored as attributes.

An attribute is represented by an attribute type, and set of attribute values.
An attribute with a single value is represented as follows:-
\begin{quote}	
$<$Attribute Type$>$ ``='' $<$Attribute Value$>$
\end{quote}
The attribute type can either be a string (which must be in the attribute
oidtable --- see Section~\ref{oidtables}) or the OID in a dotted decimal
format.

Each attribute value is represented by a string, the format of the attribute value
depends upon the
syntax defined in the oidtables, but in general will be a string.

So
\begin{quote}\begin{verbatim}	
roomNumber = G24
2.5.4.20   = 453-5674
commonName = Colin Robbins & Colin John Robbins
photo      = 0308207b4001488001fd...
\end{verbatim}\end{quote}
are examples of attributes, the ``commonName'' example shows a multi-valued attribute,
with the two values seperated by the ``\&'' symbol.
Notice how the ``photo'' attribute does not have a specific string format,
so a hexadecimal ``ASN.1'' representation is used.
2.5.4.20 is an Object Identifier represented in numeric form.

\subsection {Names}
\label{quipu_name}
Names are an important part of QUIPU.
A Name is represented by a Distinguished Name (DN).\index{DN}
A DN is made up of a sequence of
Relative Distinguished Names (RDN).\index{RDN}

An RDN is usually represented by a single valued attribute, thus
\begin{quote}	\begin{verbatim}
"commonName = Alan Turland"
"organization = University College London"
\end{verbatim}\end{quote}
are valid RDNs

Distinguished Names - the sequence of RDNs that uniquely define
the node in the DIT are represented as:-
\begin{quote}
RDN ``@'' RDN [``@'' RDN \ldots]
\end {quote}
So
\begin{quote}\small\begin{verbatim}
countryName = GB @ organization = University College London 
\end{verbatim}\end{quote}
is an example valid DN.

In some cases an RDN or DN is evaluated relative to a ``current location''.
To be unambiguous a DN may be rooted using a leading ``@'', for example
\begin{quote}\small\begin{verbatim}
@ countryName = GB @ organization = University College London 
\end{verbatim}\end{quote}


\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}
\begin{center}
\small
\begin{tabbing}
rfc822Mailboxes \= \kill \\
MASTER\\
VERSION example \\
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\\
\# Hide the photograph attribute \\
acl=\>others \# none \# attribute \# photo \\
acl=\>self \# read \# attribute \# photo \\[2ex]
CN=\>Steve Kille \\
CN=\>Steve E. Kille \\
CN=\>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{tabbing}
\caption{Example EDB File}
\label{example_edb}
\end{center}
\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.
Of the other attributes, the ``objectClass''\index{objectClass attribute}
attribute is the most important.
It defines the set of mandatory and optional attributes that must and may be
present in the entry.
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.

Every entry that is not a leaf of the DIT should belong to the object class
``\verb"quipuNonLeafObject"''. This object class has a mandatory
``\verb"masterDSA"''\index{masterDSA attribute} attribute, the value is the name of
the DSA holding the \verb"MASTER" copy of the child EDB.
There is also an optional ``\verb"slaveDSA"'' attribute which defines which
DSAs hold slave copies of the children.

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},
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
``o= Computer Science'', then if the entry ``o= Computer Science'' has children and is stored locally,
it can be found in the file \file{o=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.

\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}

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

Having started your DSAs you should be able to connect to it by
invoking \verb"dish" (with no parameters). Once connected, 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=Alan Turland
2 commonName=Colin Robbins
3 commonName=Steve Kille
4 commonName=Andrew Eliasz
\end{verbatim}\end{quote}
If this happens you have a working 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 name.
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 ``c=GB @ cn=toucan'' 
in the file \file{quipu-db/organisation/EDB} for example).
Having located its own entry a DSA will know its address, 
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'', so 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),
\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.

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"dsaaddress" variable in the file \file{/usr/etc/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{/usr/etc/dsaptailor} file, then
\begin{quote}\begin{verbatim}
dish -c mydsa
\end{verbatim}\end{quote}
should connect you to you 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{/usr/etc/quiputailor}, 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"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"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"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"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}).

\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 \"qd\"/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"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}
list @
\end{quote}

This will list the locally held root, now try

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

This will try to connect to the parent DSA.
If it is sucessful, 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 in 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 that 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}

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{/usr/etc/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 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		- c=GB @ o=University College London @ 
	ou=Computer Science @ cn=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 -> q
%
\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}.

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}
attribute which will give a simple authentication check.
Having allocated a ``userPassword'' you should protect the attribute with an
``accessControlList'' (the abbreviation ``acl'' is also recognised).
The following is an example of an ``acl'' \index{acl attribute}
attribute which protects
itself and the ``userPassword'' by allowing ``others'' to compare the
attribute, but not read it or write to it
(if compare was not allowed, a DSA would not
be able to check the password to let a user bind) and allows the the
user (``entry'') to write (modify) both attributes.
\begin{quote}\small\begin{verbatim}
acl = others # compare # attributes # acl $ userPassword
acl = self   # write   # attributes # acl $ userPassword
\end{verbatim}\end{quote}
The approach to Access Control is described
fully in \cite{QUIPU.Design}.

Another attribute defined in \cite{QUIPU.Design} is the ``treeStructure''
attribute \index{treeStructure attribute}
This is used to control the shape of the tree, for example
\begin{quote}\small\begin{verbatim}
treeStructure = organization & quipuObject
\end{verbatim}\end{quote}
defines that below the current level in the tree only the object classes
organization and quipuObject are allowed (this affects one level only, not
multiple levels).

\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
``\verb"No display process defined"''.

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{/usr/etc/g3fax/Xphoto}
to display the photograph.

There are display routines provided for X~windows, Sunview, 
Tetronix~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/fred
\end{verbatim}\end{quote}
then the value for the photo attribute would be read from the file
\begin{quote}
\verb"/usr/local/pictures/fred".
\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{small}\begin{verbatim}
quipu-db/c=GB/o=University College London/ou=Computer Science
\end{verbatim}\end{small}


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{/usr/etc/oidtable.at} 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{/usr/etc/quiputailor} 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).

Next it tries to load the ROOT EDB, and any children of the ROOT that you
hold.
Having loaded this part of the DIT, the DSA needs to find its own entry in
the DIT, this may have already been loaded, but if not, it will try to load
the relevant EDB file.
If it has still not found 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. 
Thus, if a DSA contained the following attribute
\begin{quote}\begin{verbatim}
edbinfo = # cn=giant tortoise #
edbinfo = c=US # cn=piranah #
edbinfo = c=GB # # c=GB@cn=wombat
\end{verbatim}\end{quote}
Then it would try to contact ``cn=giant tortoise'' for an update of the root
EDB (signified by the `NULL' EDB name), and contact the DSA ``cn=piranah''
for an update of the c=US EDB.
The DSAs ``cn=giant tortoise'' and ``cn=piranah'' will only send the updates 
if the EDBs held are different, and the requesting DSA is listed in the
``send to'' fields of their own entries.
Thus,
our example DSA will not get updates of the c=GB entry as 
no DSA is specified (perhaps it
holds the MASTER itself), but it will allow the DSA 
``c=GB@cn=wombat'' to get updates of ``c=GB'' from itself.

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 are used to
provide this mapping (see also the section on \file{isobjects} in \volone/ of
this manual).
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{/usr/etc/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{/usr/etc/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'' from the 
file \file{/usr/etc/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{/usr/etc/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.


NOTE the name and case of some attributes has changed since ISODE-4.0 in order
to align the attribute type strings with the strings defined in the relevant
standards documents.

\chapter {Configuring the Name Service}
\label{quipu:ns}

A lightweight Nameservice is defined in \cite{QUIPU.Design}. This section
tells you how to start and use the nameserver.

To start the name service, the ``quiputailor''
\verb"nameserver"
variable should be set to \verb"ON" (see Section~\ref{dsa:tailor})
The nameserver will then start listening for association on the address
defined by the ``isotailor'' variable \verb"ns_address" (see \voltwo/ of
this manual for a description of the isotailor file).

If you then set the ``isotailor'' variable \verb"ns_enable" to \verb"ON"
ISODE applications will use the QUIPU name server to look up application
addresses rather than the file \file{/usr/etc/isoentities}.

\section{DAP Access}

By default, ISODE applications that wish to use the directory to look up
PSAP addresses will use the nameserver protocols.
However there are cases when DAP access is needed, for example on
machines without connectionless access.

To get an application using DAP lookup involves a small piece of coding.
The routine
\begin{quote}\small\begin{verbatim}
set_lookup_dap (unbind)
char unbind;
\end{verbatim}\end{quote}
must be called.

If the parameter \verb"unbind" is \verb"TRUE" then the look up routines will
bind and unbind from the directory for every lookup.
If the parameter is not \verb"TRUE", then the connection will remain open until
close by a call to
\begin{quote}\small\begin{verbatim}
ds_unbind()
\end{verbatim}\end{quote}

To compile the program, you will need to include \man libdsap(3n) 
in the link phase.

\section{Dsabuild}

The program \pgm{dsabuild} found in the \file{support} directory of the ISODE
source tree can be used to load an existing \file{isoentites} database
into your local tree.
This will be useful to facilitate bootstrap.

Details are given in \man dsabuild(8c).
DataMuseum.dk

DKUUG/EUUG Conference tapes

⟦cce1e6102⟧ TextFile

Derivation

TextFile
