.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