Net2/usr/src/contrib/isode/QUIPU-READ-ME
Upgrading Quipu-6.0 to Quipu-6.8
Colin Robbins
X-Tel Services Ltd
_A_B_S_T_R_A_C_T
This is a brief note to describe the
differences between Quipu 6.8 and the previous
major release of Quipu -- Quipu-6.0.
To clarify the version numbers, Quipu-6.0 was
distributed with ISODE-6.0. Quipu-6.1 was an
upgrade to Quipu released by UCL a short time
after ISODE-6.0. Quipu-6.8 is part of ISODE-6.8.
When I refer to Quipu-6.0 in the following text,
this includes Quipu-6.1.
You should be able to compile and install the new
code and everything should work as before.
However there is some tailoring you can do to
increase the efficiency of your DSA, and some new
feature you may wish to use.
A WORD OF WARNING: This version of Quipu writes
its EDB files in a slightly different format to
6.0. Once a 6.8 DSA writes an EDB file there is
no easy way to roll back - make sure you have a
back up.
_1. _R_o_b_u_s_t_n_e_s_s
One of the primary reasons for having this beta test is
because we need to be sure then next Major version (i.e
Quipu-7.0) is robust. Any failure in this version of Quipu
should be investigated and reported to Quipu-
support@cs.ucl.ac.uk, if it isn't reported it may not get
fixed !
_2. _P_e_p_s_y
The old pepy based encoders/decoders have been replaced with
table driven encoders/decoders using a tool called pepsy,
written by Andrew Worsley. This means the binaries are a
lot smaller (and compile a lot quicker). This also
March 12, 1991
- 2 -
increases the encoding/decoding speed.
If you have written your own DUA's using the old libdsap and
call the old pepy encode or decode routines directly, you
will need to add
#include <isode/quipu/syntaxes.h>
to the .c files that call the encoder and decoders.
_3. _S_h_a_r_e_d _L_i_b_r_a_r_i_e_s _U_n_d_e_r _S_u_n_O_S_4._1
ISODE and Quipu can be compiled with shared libraries, again
this makes the binaries smaller which seems to help reduce
the DSA paging problems (see config/sunos4.make to see how
to generate shared libraries).
_4. _D_S_A _m_a_n_a_g_e_s _i_t_s _o_w_n _e_n_t_r_y.
A DSA now manages its own entry in the DIT. This is one of
the most important changes to Quipu, and has the potential
for causing the most trouble! Generally the MASTER EDB in
which you DSAs entry resides is not held by your DSA. This
means it is difficult for a DSA to modify its own entry, so
for example it can't keep its version number uptodate. With
Quipu 6.8, a DSA holding the MASTER EDB knows that any DSAs
whose version number is 6.8 or greater wants to manage its
own entry. To allow this to happen, The DSA holding the
MASTER EDB "spot shadows" the remote DSA entry. That is,
from time to time it connects to the DSA in question, reads
its entry, and writes the result back into the MASTER EDB
file. So modify operations on the DSAs entry can now take
place in your local DSA. This has the advantage that attri-
butes such as the version number are kept up to date.
There is a bit of a boot strap problem. You will need to
modify the version number in your DSAs entry in the MASTER
EDB first time to tell it you are running Quipu-6.8. You
will have to do this by connecting straight to the relevant
remote DSA over DAP to do the modify. If you connect
straight to you local DSA it knows it is running 6.8, so
will assume it has control of the version number and won't
let you change it!
There is another problem when modifying the presentation
address of a DSA. You must make sure the DSA with the MASTER
EDB reads the new address, BEFORE you move the DSA. If not
it will always attempt to connect to the wrong address to
shadow the entry (Alternatively you could use a ts_bridge to
make it looks as if the old address still works). This
problem did exist before, but is now made worse!
March 12, 1991
- 3 -
If your DSA does not hold the MASTER EDB file for its own
entry, then there is a fundamental assumption that the DSA
that does hold the MASTER EDB file is also running the new
6.8 code. If it does not operations WILL go wrong. This
means the new Quipu must be inserted into the DIT `top
down'.
To perform this shadowing, the DSA has to read its own entry
across an un-authenticated DSP link, thus it can not read
any attributes that are protected by ACLs. So all important
attributes in the DSAs entry MUST be publically readable
(this includes the unused userPassword attribute). If they
are not readable the shadowing operation will fail.
_5. _S_p_o_t _S_h_a_d_o_w_i_n_g
As an extension to the above, a DSA can `spot shadow' other
entries in the DIT. When searching, often a large part of
the time is involved with chaining off to other DSAs to
search aliases. To enhance performance it is sometimes use-
ful to have a cached copy of the alias locally. To arrange
this, you can add:
shadow_attribute aliasedObjectName
to your quiputailor file. The the DSA will make sure it has
a cached copy of all DNs referenced by aliasedObjectName
attributes. Similarly seeAlso, masterDSA or any DN attri-
bute can be shadowed.
Spot shadowing can also used to interface the Quipu world to
the non-Quipu world. If part of the DIT is not stored in a
Quipu DSA, and the non Quipu DSA wants to master an entry
which is held in a Quipu MASTER EDB, the entry can be spot
shadowed. You should ask quipu-support@cs.ucl.ac.uk for
details of how to do this.
_6. _S_e_a_r_c_h _I_n_d_e_x_e_s
The performance of subtree searching has been greatly
improved, a significant part of this has been obtained by
some code donated by Tim Howes to add AVL trees and indexing
to Quipu. To get the best out of your DSA, a bit of tailor-
ing is needed.
You need to define which attributes should be indexed,
typically commonName and surname, so add the following to
quiputailor:
optimize_attr commonName
March 12, 1991
- 4 -
optimize_attr surname
You can add others (only string attributes), but care should
be taken not to add indexes unnecessarily. There is a bal-
ance to be found between holding the indexs in core, and the
actual benefit. Too many indexes makes the core size large,
and increases paging problems.
The index is only made for subtree searches in certain
parts of the DIT, you need to define which. Typically you
will just do this for the whole organisation by adding
index_subtree c=XX@o=My org
to quipu tailor. However if some OU's are also large, you
may want to index them as well e.g.
index_subtree c=XX@o=My org@ou=Large OU.
The index is only used for equality, approximate and initial
substring matching. General wildcard matches are not
improved by indexing, but should still be quicker than
QUIPU-6.0 due to some scheduling improvements.
(NOTE: The TURBO_LOAD compile option has now been removed,
as the introduction of AVL trees has a similar effect.
TURBO_DISK remains)
_7. _I_n_h_e_r_i_t_e_d _a_t_t_r_i_b_u_t_e_s
Attribute inheritance is a mechanism where an entry can get
default attribute values from its parent entry. This can be
used to make the in core database significantly smaller (and
easier to manage). For example, entries of the object class
`person' for a particular organisation might all have the
same postal address attribute. Using inheritance this
attribute can be placed in the entry one level above, and
inherited down.
For example, if the following was an attribute of the parent
entry
inheritedAttribute = person $ default (
postalAddress= UCL $ Gower Street $ London $ WC1E
6BT
telephoneNumber= +44 71-387-7050
)
Then all entires belonging to the `person' objectclass at
the level below would inherit the postalAddress and
TelephoneNumber attributes IF there is not already a value
there.
March 12, 1991
- 5 -
This is particularly useful for access control lists. Full
details are given in the Manual.
_8. _D_S_A _r_e_l_a_y
If your DSA is not connected to one of the major networks
(Internet, IPSS...), it may from time to time get references
to a DSA that it can not connect to directly, so the opera-
tion can not proceed.
The DSA relay attribute in your DSAs entry supplies the DN
of a DSA(s) that is listening on both your network and the
major networks you are not connected to. There needs to be
an agreement between the managers of the two DSAs because
the relay DSA will be asked to perform operations on your
behalf.
For example, if the DSA `x' has access to IPSS and Internet,
but DSA `y' only has IPSS access, DSA `y' might add a
relayDSA attribute to it own entry, with the DN of DSA `x'
as the value. Then when DSA `y' gets a reference to an
Internet based DSA, it will chain the operation the DSA `x'.
Clearly, if every DSA chooses the same relay DSA, that DSA
will soon become overloaded and reject your association
attempts with a `busy' error. So some care is needed in
choosing the `right' DSA (We recognise that there needs to
be some form of `relay authorisation' for ISODE-7.0 and are
looking at possible solutions).
_9. _N_U_L_L _E_D_B_s.
You can now create NULL EDB files, that is a file that con-
tains only a two line header, and no entries. This should
make writing scripts to build databases a little easier. It
also has the advantage that the last entry from any one
level in the DIT can now be removed, this was previously
greeted with `unwilling to perform' error message.
_1_0. _N_e_w _E_D_B _f_o_r_m_a_t.
To facilitate faster loading of EDB files, the format has
changed slightly (The format DISH presents to the user is,
however the same as before). With multiple attributes
instead of repeating the attribute type, which then has to
be looked up in tables, lines can be split using a `\` con-
tinuation character. For example, previously the following
multivaled attribute was recognised:
March 12, 1991
- 6 -
cn= Colin Robbins & Colin John Robbins
as well as
cn= Colin Robbins
cn= Colin John Robbins
Now, the following is also allowed (and is more widely used
by DSAs)...
cn= Colin Robbins &\
Colin John Robbins
_1_1. _L_i_s_t_e_n _a_d_d_r_e_s_s
Sometimes, particularly in the X.25 world, the address used
to call a DSA is not the same as the address the DSA must
listen on. So a new attribute "listenAddress" attribute has
been introduced. If the address your DSA wants to listen on
is different to the address it need to present to the out-
side world, use the listenAddress to define the address the
DSA should listen on, and the standard PresentationAddress
for the address remote DSAs should call.
_1_2. _M_o_d_i_f_y _f_r_o_m _d_i_s_h.
Instead of always invoking an editor to modify an entry, you
can now do it all from the command line with the following
operations:
modify -add <attribute>
or
modify -remove <attribute>
_1_3. _S_e_c_u_r_e _s_e_a_r_c_h_i_n_g.
In Quipu-6.1 it was only possible to search a part of the
DIT if it was publicly readable, and only public readable
attributes were searched. This restriction is now lifted IF
the DSA performing the search holds the entire subtree being
searched.
_1_4.
_U_s_e_r _F_r_i_e_n_d_l_y _N_a_m_i_n_g
The concept of UFN - User Friendly Naming has been intro-
duced to some of the interfaces, and an example tool
March 12, 1991
- 7 -
(others/quipu/uips/ufn) has been written to demonstrate the
capabilities.
A UFN is a concise representation used to identify a DN.
For example "C Robbins, X-Tel, GB" is sufficient to identify
the long winded "c=GB@o=X-Tel Services Ltd@cn=Colin Rob-
bins". A UFN is also context sensitive, so if I was already
located in the GB part of the DIT "C Robbins, X-Tel" would
be sufficient, or if under the X-Tel part of the DIT "C Rob-
bins" would be enough.
A paper `Using the OSI Directory to achieve User Friendly
Naming' by S.Kille describes the approach in full.
_1_5. _i_s_o_e_n_t_i_t_y & _i_s_o_s_e_r_v_i_c_e _r_e_p_l_a_c_e_m_e_n_t
The directory can now be used as a replacement for isoenti-
ties and isoservices. The isode-gen(8) manual page
describes how to set things up, and describes a _b_o_o_t_s_v_c
script to load the DSA with the relevant data. There are
some scripts in others/quipu/tools/scripts to help manage
such entries once created. You are strongly encouraged to
register your OSI application in the directory then using
UFN, operations such as
ftam "cs, ucl, GB"
vt "x-tel, gb"
imisc "psi, us"
will start to work.
If the DSA fails to find a entity, the old isoentities file
is used as a back up.
_1_6. _I_X_I
IXI has become part of the standard macro definitions. If
you have the line
ts_interim: IXI
in your isotailor file, it should be removed. If you do not
remove the line, you will get a harmless warning about
duplicate prefixes for communities "IXI" and "IXI"
for some processes.
You should make sure you have re-installed ALL applications
that read the isotailor before removing this IXI definition.
March 12, 1991
- 8 -
Once is is removed old applications WILL fail.
_1_7. _A_s_y_n_c_h _D_U_A
There is an (undocumented) asynchronous interface to the
dsap library.
_1_8. _A_l_i_a_s _m_a_n_a_g_e_m_e_n_t
A management version of dish can be found in
others/quipu/uips/manage. This has additional command to
add/delete and check alias entries in to DIT.
_1_9. _D_S_A _s_t_a_t_i_s_t_i_c_s _t_o_o_l_s
There is a script in others/quipu/tools/dsastats which can
process the quipu.log file produced by a DSA and provide
some statistics on the DSA usage.
_2_0. _D_S_C
others/quipu/uips/dsc provides a simple DUA that prompts fom
certain information such as name and organisation, and
return with full name, phone number and email address.
_2_1. _X-_W_i_n_d_o_w_s _D_U_A
The two X-Window DUA's released by Brunel University shortly
after ISODE-6.0 have been integrated into this release,
together with `sd' an enhanced version of the `widget'
interfaces.
_2_2. _T._6_1 _s_t_r_i_n_g_s.
T.61 strings can be represented by mapping them onto an ISO
8859-1 character set (e.g as supported by some X-Window
fonts).
Accented characters are represented by two octets, the first
indicating the accent and the second the base character to
be accented. Note that some combinations of accent and char-
acter do not have an equivalent in ISO 8859-1, and hence
cannot be displayed on an ISO 8859-1 device.
A few example mappings...
T.61 Character EDB file code
March 12, 1991
- 9 -
n tilde \c4n
e circumflex \c3e
a grave \c1a
a acute \c2a
You need to tell the DUA that you have the ability to
display the correct characters, this can be acheived in one
of two ways:
1) In the dsaptailor file, you can add
ch_set ISO8859
or
2) set the environment variable CH_SET to "ISO8859", e.g.,
using `csh'
setenv CH_SET ISO8859
Some EDB files currently have the wrong T.61 codes for some
national characters. These should now be replaced with the
correct T.61 code.
_2_3. _P_h_o_t_o_s
Kevin Jordan has given the old g3fax code a major, and much
needed overhaul. This release provides the framework for
better handling of photo attributes in future releases.
Until ISODE-7.0 if you use the `pbmtofax' tool to encode any
new photographs, you should use the `-old' flag to ensure
that other people can display the pictures using their
6.0/6.1 based code. This options has not been hard wired,
as you may wish to experiment with the new tools.
There is tool to convert the g3fax pictures to postscript.
_2_4. _A_u_t_h_e_n_t_i_c_a_t_i_o_n
Your DSA can now insist on various levels of authentication.
For example, it can be made to reject bind operations that
do not supply a DN. This is set via the `authentication'
quiputailor variable. The value `DN' tells to reject bind's
unless a DN is supplied, and `simple' insists that simple
authentication at the very least is used.
March 12, 1991
- 10 -
_2_5. _A_d_d_r_e_s_s _S_e_l_e_c_t_o_r_s
Quipu now checks that the PSEL, SSEL and TSEL supplied by a
calling entity match the selectors defined in the DSAs
presentationAddress attribute. If they do not, the associa-
tion is rejected with a message of the form:
Session entity not attached to TSAP
_2_6. _l_i_b_d_s_a_p _c_h_a_n_g_e_s
There are a few changes to the dsap library programmers
should be aware of.
a) Calls to the *_decode() routine such as dn_decode() and
as_decode() are no longer needed.
b) The AttributeType structure is now just a pointer into
the OID tables, thus `at_table' struct reference is no
longer needed. So code of the form _a_t-
>_a_t__t_a_b_l_e._o_a__s_y_n_t_a_x should be replaced with _a_t-
>_o_a__s_y_n_t_a_x and _a_t->_a_t__o_i_d replaced with _a_t-
>_o_a__a_t._o_t__o_i_d
c) A few other routines have had their parameters changed
slightly, so you should run your programs through lint
(making sure you bring in the dsap and isode lint
libraries) to check your procedure calls.
_2_7. _M_a_n_u_a_l
The Quipu Manual has been updated to reflect all these new
features.
_2_8. _T_h_a_n_k_s...
The Quipu team would like to thank Tim Howes, George Micha-
elson, Andrew Worsley, Andrew Findlay, Piete Brooks, Kevin
Jordan, Gier Pederson, Juha Heinanen, Petri Jokela, Peter
Yee and many others people for enhancing, bug reporting and
fixing, and testing this and the many other versions of
Quipu since ISODE-6.1 to destruction.
Colin
March 12, 1991