386BSD 0.1 development

[unix-history] / usr / othersrc / contrib / isode / quipu-new.8

.TL
Upgrading Quipu-6.0 to Quipu-6.8
.AU 
Colin Robbins
.AI
X-Tel Services Ltd
.AB
.nh
This is a brief note to describe the differences between Quipu 6.8 and
the previous major release of Quipu -- Quipu-6.0.
.LP
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.
.LP 
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.
.LP
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.
.AE

.NH
Robustness 
.LP
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 !

.NH 
Pepsy 
.LP
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 increases the encoding/decoding speed.
.LP
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
.IP
	#include <isode/quipu/syntaxes.h>
.LP
to the .c files that call the encoder and decoders.

.NH
Shared Libraries Under SunOS4.1
.LP
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).


.NH
DSA manages its own entry.  
.LP
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 attributes such as the version number are
kept up to date.
.LP
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!
.LP
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!
.LP
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'.
.LP
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.
.NH
Spot Shadowing
.LP
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 useful to have a cached copy of the alias locally.  To
arrange this, you can add:
.IP   
shadow_attribute aliasedObjectName 
.LP
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
attribute can be shadowed.
.LP
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.



.NH
Search Indexes 
.LP
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 tailoring is needed.  

.PP
You need to define which attributes should be indexed, typically
commonName and surname, so add the following to quiputailor:
.IP
   optimize_attr commonName
.sp 0
   optimize_attr surname 
.LP
You can add others (only string attributes), but care should be taken
not to add indexes unnecessarily.  There is a balance 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.  

.PP
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
.IP
   index_subtree c=XX@o=My org
.LP
to quipu tailor.  However if some OU's are also large, you may want
to index them as well e.g.
.IP
   index_subtree c=XX@o=My org@ou=Large OU.
.LP
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.
.LP
(NOTE: The TURBO_LOAD compile option has now been removed, as the introduction
of AVL trees has a similar effect.  TURBO_DISK remains)


.NH
Inherited attributes
.LP
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.
.LP
For example, if the following was an attribute of the parent entry
.PS
    	inheritedAttribute = person $ default (
.sp 0 
    	postalAddress= UCL $ Gower Street $ London $ WC1E 6BT
.sp 0 
	telephoneNumber= +44 71-387-7050
.sp 0 
	)
.PE
.LP
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.
.LP
This is particularly useful for access control lists.
Full details are given in the Manual.


.NH
DSA relay
.LP
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
operation can not proceed.
.LP
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.
.LP
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'.
.LP
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).


.NH
NULL EDBs.
.LP
You can now create NULL EDB files, that is a file that
contains 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.

.NH
New EDB format.
.LP
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 `\\` continuation character.  For example,
previously the following multivaled attribute was recognised:
.IP
	  cn= Colin Robbins & Colin John Robbins 
.LP
as well as
.IP
	  cn= Colin Robbins
.sp 0
	  cn= Colin John Robbins 
.LP
Now, the following is also allowed (and is more widely used by DSAs)...
.IP
	  cn= Colin Robbins &\\
.sp 0
	      Colin John Robbins

.NH
Listen address
.LP
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 outside world, use the listenAddress to
define the address the DSA should listen on, and the standard
PresentationAddress for the address remote DSAs should call.

.NH
Modify from dish.
.LP
Instead of always invoking an editor to modify an
entry, you can now do it all from the command line with the following
operations:
.IP
   modify -add <attribute> 
.LP
or
.IP
   modify -remove <attribute>

.NH
Secure searching.
.LP
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.


.NH
 User Friendly Naming
.LP
The concept of UFN - User Friendly Naming has been introduced to some
of the interfaces, and an example tool (others/quipu/uips/ufn) has
been written to demonstrate the capabilities.

.LP
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 Robbins".
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 Robbins" would be enough.
.LP
A paper `Using the OSI Directory to achieve User Friendly Naming' by
S.Kille describes the approach in full.

.NH 
isoentity & isoservice replacement
.LP	  
The directory can now be used as a replacement for isoentities and
isoservices.  The isode-gen(8) manual page describes how to set things
up, and describes a 
.B
bootsvc 
.R
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
.IP
	ftam "cs, ucl, GB"
.sp 0
	vt "x-tel, gb"
.sp 0
	imisc "psi, us"
.LP
will start to work.

.LP
If the DSA fails to find a entity, the old isoentities file is used as a back up.

.NH
IXI
.LP
IXI has become part of the standard macro definitions.  If you have
the line
.IP
    ts_interim: IXI
.LP
in your isotailor file, it should be removed.  If you do not
remove the line, you will get a harmless warning about
.IP
    duplicate prefixes for communities "IXI" and "IXI"
.LP
for some processes.
.LP
You should make sure you 
have re-installed ALL applications that read the isotailor
before removing this IXI definition.  Once is is removed old applications
WILL fail.

.NH
Asynch DUA
.LP
There is an (undocumented) asynchronous interface to the dsap library.

.NH
Alias management
.LP
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.

.NH
DSA statistics tools
.LP
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.

.NH
DSC
.LP
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.

.NH
X-Windows DUA
.LP
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.

.NH
T.61 strings.
.LP
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).
.LP
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 character do not have an equivalent in ISO 8859-1,
and hence cannot be displayed on an ISO 8859-1 device.
.LP
A few example mappings...
.LP
.PS
     T.61 Character		EDB file code
.sp 1
     n tilde 			\\c4n
.sp 0 
     e circumflex		\\c3e
.sp 0 
     a grave			\\c1a
.sp 0 
     a acute			\\c2a
.PE

.LP
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:
.IP 1)
In the dsaptailor file, you can add
     ch_set ISO8859
.LP
or

.IP 2) 
set the environment variable CH_SET to "ISO8859", e.g., using `csh'
     setenv CH_SET ISO8859

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


.NH
Photos
.LP

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.

.LP
There is tool to convert the g3fax pictures to postscript.

.NH
Authentication
.LP
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.

.NH
Address Selectors
.LP
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 association is rejected with a message
of the form:
.IP
Session entity not attached to TSAP

.NH
libdsap changes
.LP
There are a few changes to the dsap library programmers should be
aware of.
.IP a)
Calls to the *_decode() routine such as dn_decode() and as_decode()
are no longer needed.
.IP 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
.B
at->at_table.oa_syntax  
.R
should be replaced with
.B
at->oa_syntax
.R
and
.B
at->at_oid
.R
replaced with
.B
at->oa_at.ot_oid
.R
\.

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


.NH
Manual
.LP
The Quipu Manual has been updated to reflect all these new features.

.NH
Thanks...
.LP
The Quipu team would like to thank Tim Howes, George Michaelson,
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