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 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 or modify -remove _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