COSINE

PARADISE-GEN(8)       MAINTENANCE COMMANDS        PARADISE-GEN(8)



NAME
     paradise-gen - generating the _P_A_R_A_D_I_S_E DSA and DUA.

PARADISE
     _P_A_R_A_D_I_S_E is a European project under the  _C_O_S_I_N_E  initiative
     aimed  at  providing Directory services across Europe.  This
     version of the _P_A_R_A_D_I_S_E software is  the  first  release  of
     both the DSA and DUA packages for the project.

     This documentation describes how to configure, generate, and
     install  the  _P_A_R_A_D_I_S_E  DSA  and  DUA  versions  of  the ISO
     Development Environment.

     You will probably want to read  over  this  entire  document
     first,  before typing any commands; e.g., there are optional
     components described later on that require  additional  set-
     tings in the configuration file.

     This document describes how to compile and install the QUIPU
     DSA  and DUA for the _P_A_R_A_D_I_S_E DSA and DUA services only, for
     full details on how to install the ISODE you should  consult
     isode-gen(8).

     Comments concerning this _P_A_R_A_D_I_S_E release should be directed
     to the mailbox "helpdesk@paradise.ulcc.ac.uk".

SYNOPSIS
          % cd isode-8.0/
          % cp config/_s_y_s_t_e_m.h h/config.h
          % cp config/_s_y_s_t_e_m.make config/CONFIG.make
          % cp config/*.local support/
          % ./make paradise
          # ./make inst-paradise


DESCRIPTION
     This is a description of how one can bring up  the  _P_A_R_A_D_I_S_E
     DSA  It  is  assumed  that you have super-user privileges in
     order to install the software.   Super-user  privileges  are
     not required to configure or generate this software.

     The  distribution  tape  contains  the  hierarchy  for   the
     isode-8.0/ directory.  Bring the sources on-line by changing
     to a directory for local sources and running tar, e.g.,

          % cd /usr/src/local/
          % tar x
          % cd isode-8.0/


CONFIGURATION
     First, go to the config/ directory.



Sun Release 4.1     Last change: 19 June 1992                   1






PARADISE-GEN(8)       MAINTENANCE COMMANDS        PARADISE-GEN(8)



          % cd config


     Select the Makefile and include-file  skeletons  which  most
     closely match your system.  The current choices are:

          _f_i_l_e        _c_o_n_f_i_g_u_r_a_t_i_o_n
          aix         AIX 3.2
          apollo      Apollo
          aux         A/UX release 2.0.1
          bsd42       generic 4.2BSD UNIX
          bsd43       generic 4.3BSD UNIX
          bsd43-rt    RT/PC with 4.3BSD
          bsd44       4.4BSD UNIX with OSI
          ccur        Concurrent RTU 6.0
          hpux        HP-UX
          mips        MIPS RISC/OS
          osx         Olivetti LSX 30xx
          ros         Ridge Operating System
          solbourne Solbourne
          sunlink3    SunOS release 3 with SunLink OSI/X.25 release 5.2
          sunlink4    SunOS release 4 with SunLink OSI/X.25 release 6.0
          sunnet7     SunOS release 4 with SunNet OSI release 7.0
          sunnet7x    SunOS release 4 with SunNet X.25 release 7.0
          sunos3      SunOS release 3
          sunos4      SunOS release 4
          sunos4-1    SunOS release 4.1
          sys52-exos  SVR2 UNIX with EXOS
          sys52-rt    RT/PC with AIX
          sys52-sun   SVR2 UNIX emulation on SunOS release 3
          sys52-win   SVR2 UNIX with WIN/TCP
          sys53       generic SVR3
          sys54       generic SVR4
          ultrix      Ultrix 3.1

     The makefile skeleton has the extension .make,  whereas  the
     include-file skeleton has the extension .h.

  MAKEFILE
     Copy the makefile skeleton of your  choice  to  pickle.make,
     where  "pickle"  is  the name of your system.  Now edit this
     file to set the following _m_a_k_e variables:

          _v_a_r_i_a_b_l_e _d_e_f_a_u_l_t              _s_p_e_c_i_f_i_e_s
          OPTIONS                       options to _c_c and _l_i_n_t (e.g., -I../h)
          LSOCKET                       libraries to link in (e.g., -lcci)
          BINDIR   /usr/local/bin/      where to install user programs
          SBINDIR  /usr/etc/            where to install administrator
                                        programs
          ETCDIR   /usr/etc/            where to install administrator files
          LOGDIR   /usr/tmp/            where to install log files
          INCDIR   /usr/include/isode/  where to install include files



Sun Release 4.1     Last change: 19 June 1992                   2






PARADISE-GEN(8)       MAINTENANCE COMMANDS        PARADISE-GEN(8)



          LIBDIR   /usr/lib/            where to install object libraries
          LINTDIR  /usr/lib/lint/       where to install lint libraries
          SYSTEM                        directs how to create loader libraries
          MANDIR   /usr/man/            where to install man pages
          MANOPTS                       see compat/inst-man.sh for details

     NOTE THAT ALL THESE DIRECTORIES MUST BE ABSOLUTE PATH  NAMES
     (i.e., start and end with a `/').

     Finally,

          ln pickle.make CONFIG.make

     (yes, that's "CONFIG" in uppercase and "make" in lowercase).
     Both  of these files are in the isode-8.0/config/ directory.
     This latter file is the one which the software uses to  con-
     figure itself during generation.

  INCLUDE-FILE
     Copy the include-file skeleton of your choice  to  pickle.h,
     where  "pickle"  is  the  name  of your system.  Now add any
     additional definitions you like (usually none).  Consult the
     file config/OPTIONS for a list.

     Now:

          ln pickle.h ../h/config.h

     This latter file is the one which the software uses to  con-
     figure itself during generation.

  MACROS and OBJECTS DATABASE
     Typically, sites run with the  default  macros  and  objects
     databases.  In this case, simply copy the default local con-
     figuration files to the support/ directory:

          % cp macros.local ../support/
          % cp objects.local ../support/

     If you have local modifications you  wish  to  make,  either
     copy in your own file or edit the files support/macros.local
     and support/objects.local as appropriate.

  OTHER DATABASES
     There are other databases used by the ISODE, but  these  are
     not  needed  by  the  _P_A_R_A_D_I_S_E  DSA.  If you want to install
     these consult isode-gen(8).

GENERATION
     Go to the isode-8.0/ directory

          % cd ..



Sun Release 4.1     Last change: 19 June 1992                   3






PARADISE-GEN(8)       MAINTENANCE COMMANDS        PARADISE-GEN(8)



     Now reset the dates of the configuration files for the  sys-
     tem.  This is done only once per source-tree:

          % ./make once-only

     Then to make both the DUA and DSA use:

          % ./make paradise

     To make the DSA only use:

          % ./make paradise-dsa

     To make the DUA only use:

          % ./make paradise-dua

     If you are using SunOS, do not use the _m_a_k_e program supplied
     with the SunPro package.  It is not, contrary to any claims,
     compatible with the standard _m_a_k_e facility.   Further,  note
     that  if  you  are  running  a version of SunOS 4.0 prior to
     release 4.0.3, then you may need to  use  the  _m_a_k_e  program
     found  in  /usr/old/, if the standard _m_a_k_e your are using is
     the SunPro _m_a_k_e.  In this case, you will  need  to  put  the
     old, standard _m_a_k_e in /usr/bin/, and you can keep the SunPro
     _m_a_k_e in /bin/.

     If you are using SVR3, then you will probably have  to  type
     this command before starting the compilation:

          % ulimit 32768

     Similarly, you may need to increase the stacksize limitation
     on other systems.  For example, some users of the RT, report
     needing to use

          % limit stacksize 16m

     in order to get FTAM to fully compile.

     The _m_a_k_e command from the top-level directory will  cause  a
     complete  generation  of  the  system.   If  all  goes well,
     proceed with the installation.  If not, complain,  as  there
     "should be no problems" at this step.  Some files while com-
     piling may produce a

          warning: statement not reached

     or a

          type ObjectDescriptor: Warning: Can't find file DSE.ph failed




Sun Release 4.1     Last change: 19 June 1992                   4






PARADISE-GEN(8)       MAINTENANCE COMMANDS        PARADISE-GEN(8)



     message.  This is normal.  Sometimes when building a  loader
     library, you might see several

          ranlib: warning: ../libisode.a(aetdbm.o): no symbol table

     messages.  This is also normal.  You might also  see  a  few
     messages like:

          *** Error code 1 (ignored)

     This is also normal.  As a rule, unless _m_a_k_e says  something
     like

          *** Error code 1

     or perhaps

          Exit

     then everything is going just fine!

INSTALLATION
     You will need to be the super-user to install the  software.
     Note that installing the software from an NFS-mounted parti-
     tion requires that  you  perform  the  installation  as  the
     super-user on the _t_a_r_g_e_t system after changing to the source
     directory on the _s_o_u_r_c_e system.

     In the directions that follow, reference is made to some  of
     the directories defined in the CONFIG.make file.  You should
     substitute in the correct value, for example, if the expres-
     sion

          $(SBINDIR)ros.quipu

     and if SBINDIR is defined as /usr/etc/  in  the  CONFIG.make
     file, then you should type

          /usr/etc/ros.quipu

     instead.

     To install the software use:

          # ./make inst-paradise

     which does the installation of both the  DUA  and  DSA.   To
     install the DSA only use:

          # ./make inst-paradise-DSA





Sun Release 4.1     Last change: 19 June 1992                   5






PARADISE-GEN(8)       MAINTENANCE COMMANDS        PARADISE-GEN(8)



     To install the DUA only use:

          # ./make inst-paradise-DUA


     That's about it.  This will install everything.  To clean-up
     the source tree as well, use:

          % ./make clean

     at this point.

Running a DSA
     The QUIPU DSA is a "static responder".  This means  that  it
     accepts new associations and managing old ones as necessary.
     Hence, it is necessary to start the  _r_o_s._q_u_i_p_u  daemon  when
     the  machine goes multi-user.  On Berkeley UNIX systems, add
     these lines to the /etc/rc.local file:

          if [ -f $(SBINDIR)ros.quipu ]; then
              cd $(ETDDIR)quipu-db; $(SBINDIR)ros.quipu 2>&1 >/dev/null
              (echo -n ' quipu') > /dev/console
          fi

     (This  assumes   your   database   is   in   the   directory
     $(ETCDIR)quipu-db  -  it  need  not  be) On other systems, a
     similar procedure is followed.

  QUIPU DATABASE
     If you intend to run a local DSA,  then  you  will  need  to
     build  a  Directory  database.   The  database directory, by
     default, lives in the ETCDIR area (usually /usr/etc/)  under
     the  name  of  quipu-db/.   Three prototype databases can be
     found in the directory others/quipu/quipu-db/.  These  data-
     base  files  should  be  protected as they contain Directory
     passwords and other sensitive information.  The DSA needs to
     be  able  to read this information, and so performs a setuid
     on execution to the UID of the owner of the database  direc-
     tory.

     Now  customize   the   chosen   prototype   database   under
     /usr/etc/quipu-db/.    The  details  of  this  database  are
     explained in Volume 5 of  the  users  manual.   However  you
     should be able to derive a minimal database by following the
     example structures defined for University College London and
     X-Tel  Services  Ltd in the GB branch of the Directory tree.
     Then delete the example structures for O=University  College
     London and X-Tel Services Ltd.

  QUIPU TAILORING
     If you choose to run a local DSA, you will now need to  con-
     figure it.  The DSA tailors itself at runtime by reading the



Sun Release 4.1     Last change: 19 June 1992                   6






PARADISE-GEN(8)       MAINTENANCE COMMANDS        PARADISE-GEN(8)



     file $(ETCDIR)quiputailor.  A prototype of this file will be
     installed  during  the  normal  ISODE  installation process.
     Only one entry in the file usually needs to be changed:

          mydsaname          CN=toucan

     Substitute the name of the DSA as it occurs in the Directory
     for  "CN=toucan".  See the QUIPU manual for a description of
     the   full   range   of    tailoring    options    in    the
     $(ETCDIR)quiputailor file.

  QUIPU ONCE-ONLY
     Having tailored QUIPU, you can now start the DSA.   However,
     if you are already running QUIPU, then you will need to kill
     and restart the QUIPU DSA.

     Start the DSA now.  From the _C_S_h_e_l_l, the command might be:

          # $(SBINDIR)ros.quipu >& /dev/null

     The  daemon  will  automatically  detach.   If  you  do  not
     redirect  the  daemon's  standard-error,  then  it  will not
     detach, instead printing messages as to what actions  it  is
     taking.

Running the DUA
     To run a DUA you will need to configure the various DUA pro-
     grams.   Most of these tailor themselves at runtime by read-
     ing the file $(ETCDIR)dsaptailor.  A prototype of this  file
     will  be installed during the normal ISODE installation pro-
     cess.  Only one entry  in  the  file  usually  needs  to  be
     changed:

          dsa_address     toucan  localHost=17003

     Substitute the name of your "primary" DSA for  "toucan"  and
     its    corresponding    presentation    address    for   the
     "localHost=17003" string.  This information can be found  in
     the Directory on the host which is running the DSA.

     Do not confuse the _d_s_a__a_d_d_r_e_s_s used in this  file  with  the
     _n_s__a_d_d_r_e_s_s  used  in the $(ETCDIR)isotailor file.  These are
     separate services and must live at different addresses.  See
     _q_u_i_p_u_t_a_i_l_o_r (5)  for  a  description  of  the  full range of
     tailoring options in the $(ETCDIR)dsaptailor file.

     The _P_A_R_A_D_I_S_E DUA is called _d_e. On startup it reads the  file
     $(ETCDIR)de/detailor.   Most  of the parameters in this file
     do not need changing, but some do.

     The line




Sun Release 4.1     Last change: 19 June 1992                   7






PARADISE-GEN(8)       MAINTENANCE COMMANDS        PARADISE-GEN(8)



          dsa_address: Internet=...

     WILL need  changing.   You  should  substitute  the  "Inter-
     net=..." string with the presentation address of the DSA you
     wish to contact.

     You are VERY STRONGLY encouraged to set the username.   This
     is the name with which the interface binds to the directory.
     Don't  forget  to  create  an  entry  in  the  directory  as
     appropriate:

          username:@c=GB@o=University College London@cn=Public Access Dua

     You'll probably want  to  configure  these  for  your  local
     organisation:

          default_country: GB
          default_org: University College London


     The interface is started using the

          de

     command, online help can be obtained by invoking de and typ-
     ing "?" at the prompt.

GENERATING DOCUMENTATION
     The directory doc/ contains the documentation set  for  this
     release.   Consult the file doc/READ-ME for a description of
     each document.  Usually it is easier to print the  files  in
     this  directory than generate the documentation from scratch
     as the sources to these documents are in either  LaTeX  (for
     papers) or SLiTeX (for presentations).

FILES
     Too numerous to mention.  Honest.

SEE ALSO
     _T_h_e _I_S_O _D_e_v_e_l_o_p_m_e_n_t _E_n_v_i_r_o_n_m_e_n_t: _U_s_e_r'_s _M_a_n_u_a_l
     isode-gen(8)

AUTHOR
     Colin Robbins with help from a template by Marshall T. Rose.











Sun Release 4.1     Last change: 19 June 1992                   8