' __________________________________________________ $ | | | ISODE Volume 2 | | | | | | | | Administrator's Guide | | | | | | Installation | | | & __________________________________________________ % Installation _______________________________________________________________________ ISODE is the trademark of ISODE Consortium Limited. All other products and services mentioned in this document are identified by the trademarks or service marks of their respective companies or organisations, and ISODE Consortium Limited disclaims any responsibility for specifying which marks are owned by which companies or organisations. cOThis manual is copyright ISODE Consortium Limited, London, England, 1993-1994. cOThe ISODE software is copyright ISODE Consortium Limited, London, England, 1993-1994. The ISODE Software is a compilation of software of which ISODE Consortium Limited is either the copyright holder or licensee. Permission is granted to any individual or organisation to copy all or part of this documentation, provided that this copyright notice is retained. Acquisition, and use of this software and related materials for any purpose requires a written licence agreement from ISODE Consortium Limited, or a written licence from an organisation licenced by ISODE Consortium Limited to grant such a licence. This documentation and the software are based on contributions from multiple sources. Acknowledgements for contribution are given in ISODE Volume 1: Introduction to ISODE Consortium, Products and Membership. IC R2 Installation _______________________________________________________________________ This manual is associated with Version 2.1 of September 1994, and was last updated in September 1994. IC R2 i Contents 1 Introduction 1 1.1 Synopsis . . . . . . . . . . . 1 1.2 Description . . . . . . . . . . 2 2 Configuration 3 2.1 Makefile . . . . . . . . . . . 3 2.2 Include-File . . . . . . . . . . 4 2.3 PP . . . . . . . . . . . . 5 2.4 DSA . . . . . . . . . . . . 5 2.4.1 GDA . . . . . . . . . . 5 2.5 Configuration Databases . . . . . . . 6 2.5.1 Aliases Database . . . . . . . 6 2.5.2 Services Database . . . . . . . 7 2.5.3 Entities Database . . . . . . . 7 2.5.4 Macros Database . . . . . . . 8 2.5.5 Objects Database . . . . . . . 8 2.6 Options . . . . . . . . . . . 9 3 Build and Installation 10 3.1 Notes and Warnings . . . . . . . . 10 3.1.1 C Language & Compilers . . . . . . 10 3.2 Generation . . . . . . . . . . 12 3.3 Contributed Code . . . . . . . . . 13 3.3.1 FTAM . . . . . . . . . . 13 3.4 Installation . . . . . . . . . . 13 3.5 Testing . . . . . . . . . . . 15 4 Post-Installation Configuration 16 ii IC R2 Installation CONTENTS _______________________________________________________________________ 4.1 Tailoring . . . . . . . . . . 17 4.2 The PP MTA . . . . . . . . . . 17 4.3 Directory Services . . . . . . . . 18 4.3.1 QUIPU Installation . . . . . . . 18 4.3.2 QUIPU Database . . . . . . . . 18 4.3.3 QUIPU Tailoring . . . . . . . 19 4.3.4 QUIPU . . . . . . . . . . 20 4.4 Registering OSI Application Services . . . . 20 4.4.1 Preparation . . . . . . . . 20 4.4.2 Once-only Installation . . . . . . 21 4.4.3 Adding New Services . . . . . . 23 4.5 Network Management . . . . . . . . 24 5 Obtaining Documentation 25 IC R2 iii Preface This guide is published in support of ISODE Consortium Release 2 (IC R2). It is intended for administrators to install ISODE from the source release. It is assumed that readers of this guide are already aware of the contents of ISODE Volume 1: Introduction to ISODE Consortium, Products and Membership. Guides to the modules of IC R2 and their uses are listed under ``Software and Documentation Versions'' later in this Preface. _______________________________________________________________________ What this Guide Covers All aspects of building and installing the ISODE Consortium Release modules are covered here, in order that other volumes may be used in conjunction with binary products based on IC R2. iv IC R2 Installation Preface _______________________________________________________________________ _______________________________________________________________________ Software and Documentation Versions IC R2 is the second major release of ISODE software made by the ISODE Consortium. It is derived, with revisions and additions, from the openly available ISODE 8.0 release. The release is accompanied by a comprehensive documentation set comprising the following volumes: ____________________________________________________________________________________ |Volume||Title______________________________________________________________________| |01 |ISODE Volume 1: Introduction to ISODE Consortium, Products and Membership | |02 |ISODE Volume 2: Administrator's Guide: Installation | |03 |ISODE Volume 3: Administrator's Guide: General Services | |04 |ISODE Volume 4: Administrator's Guide: Message Handling Services | |05 |ISODE Volume 5: Administrator's Guide: Directory Services | |06 |ISODE Volume 6: Administrator's Guide: Message Store | |07 |ISODE Volume 7: User's Guide: Message Handling Services | |08 |ISODE Volume 8: User's Guide: Directory Services | |09 |ISODE Volume 9: Programmer's Guide: General Services | |10 |ISODE Volume 10: Programmer's Guide: ASEs | |11 |IC-1011: Programmer's Guide: Message Store | |12 |ISODE Volume 12: Programmer's Guide: X.500 DUA | |13 |ISODE Volume 13: Programmer's Guide: Layer Interfaces | |14 |ISODE Volume 14: Programmer's Guide: X.400 MTA | |15 |ISODE Volume 15: Programmer's Guide: X.400 UA | |16 |ISODE Volume 16: Programmer's Guide: Transport Services | |17 |ISODE Volume 17: Programmer's Guide: ASN.1 Library | |18_____|ISODE_Volume_18:__Programmer's_Guide:__ASN.1_Tools_________________________| IC R2 is released as a number of separate modules. Each module has its own update number which is incremented independently from other modules whenever an update is made to it. The version numbers of the various components may therefore differ from one another. As of September 1994, the latest versions of the modules and their associated documentation are as follows: IC R2 v Preface Installation _______________________________________________________________________ _____________________________________________________ |_Module_____||Version||Volume||Last_Document_Update_ | | IC Base | R2.1 |__01___|Version_A,_revision_1_| | | |__02___|September_1994________| | | |__03___|May_1994______________| | | |__09___|February_1994_________| | | |__10___|February_1994_________| | | |__13___|February_1994_________| | | |__16___|February_1994_________| | | |__17___|February_1993_________| |_____________|_______|__18___|February_1993_________| |_IC_DSA______|_R2.1__|__05___|May_1994______________| | IC DUA | R2.1 |__08___|February_1993_________| |_____________|_______|__12___|March_1994____________| | IC MTA | R2.1 |__04___|March_1994____________| | | R2.1 |__07___|February_1994_________| | | |__14___|February_1993_________| |_____________|_______|__15___|February_1993_________| | IC MS | R2.1 |__06___|V1.1__________________| |_____________|_______|__11___|V1.0_(draft)__________| |_IC_SNMP_____|_R2.1__|__03___|May_1994______________| |_Contributed_|_R2.1__|___-___|-_____________________| vi IC R2 Installation Preface _______________________________________________________________________ _______________________________________________________________________ The ISODE Consortium The ISODE Consortium is a not-for-profit cooperative enterprise. Its mission is to promote and evolve the ISODE implementation of OSI. This is a major package of OSI applications, including source code and documentation, with a worldwide record of operational success. All individuals and organisations handling ISODE source code are encouraged to join the ISODE Consortium. For more information about the ISODE Consortium, contact: Headquarters Address: ISODE Consortium Phone: +44 81 332 9091 The Dome Fax: +44 81 332 9019 The Square Richmond TW9 1DT UK Email Internet (RFC822):ic-info@isode.com MHS (X.400): S=ic-info; O=ISODE Consortium; P=ISODE; A=MAILNET; C=FI; If this is not possible, you may also reach the ISODE Consortium at: US Office Address: ISODE Consortium Phone: +1 (512) 338 3340 PO Box 200195 Fax: +1 (512) 338 3600 Austin TX 78720 USA IC R2 vii Preface Installation _______________________________________________________________________ _______________________________________________________________________ Availability IC R2 is a source release, and is available in the following ways: 1. To organisational members of the ISODE Consortium as a benefit of membership. 2. To educational and non-commercial research organisations, under zero-cost licence from the ISODE Consortium or under licence from a Research Consortium member of the ISODE Consortium. 3. To any organisation as a 30 day evaluation copy from the ISODE Consortium. Acquisition and use of IC R2 and related materials for any purpose requires a written licence agreement from ISODE Consortium Limited, or a written licence from an organisation licenced by ISODE Consortium Limited to grant such a licence. Binary products based on IC R2 are available on a wide range of platforms from ISODE Consortium members. Information on these products and where to obtain them is available from the ISODE Consortium. _______________________________________________________________________ Bug Reporting Bug reports on software releases made by the ISODE Consortium are welcomed. These may be sent to the Consortium by any means, but electronic mail to one of the bug reporting addresses is preferred. Please send proposed fixes with the reports if possible. For non-members of the ISODE Consortium, any reports will be acknowledged, but no further action is guaranteed. Any changes resulting from bug reports may be included in future releases. The bug reporting addresses in Internet (RFC 822) format are: o bug-isode@isode.com for general ISODE reports. o bug-quipu@isode.com for reports on QUIPU (Directory). o bug-pp@isode.com for reports on PP (MHS). o bug-snmp@isode.com for reports on SNMP. o bug-doc@isode.com for reports on the documentation. viii IC R2 Installation Preface _______________________________________________________________________ The MHS (X.400) equivalents of these addresses are: o S=bug-isode; O=ISODE Consortium; P=ISODE; A=MAILNET; C=FI o S=bug-quipu; O=ISODE Consortium; P=ISODE; A=MAILNET; C=FI o S=bug-pp; O=ISODE Consortium; P=ISODE; A=MAILNET; C=FI o S=bug-snmp; O=ISODE Consortium; P=ISODE; A=MAILNET; C=FI o S=bug-doc; O=ISODE Consortium; P=ISODE; A=MAILNET; C=FI IC R2 ix Preface Installation _______________________________________________________________________ _______________________________________________________________________ Support Basic support of ISODE Consortium releases is available to all consortium members as a benefit of membership. This includes upgrades and access to a database of bug reports and fixes. The ISODE Consortium also offers some additional support to companies building products specifically based on ISODE Consortium releases. A range of ISODE-related support services are offered by ISODE Consortium members. A list of such services will also be available from the ISODE Consortium. x IC R2 Chapter 1 Introduction This document contains a concise description of compiling and installing the ISODE Consortium source distribution, and relates to Version 2.1 of September 1994. All instructions relating to compilation and build issues are described in this manual; so that all other manuals may be distributed with, and be accurate for, binary distributions and products based on Version 2.1 of September 1994. You should read this entire document before typing any commands, as there are optional components, described later, that require additional settings in the configuration file. There are a number of electronic mailing lists associated with the ISODE technology and its applications. These are summarised in ISODE Volume 1: Introduction to ISODE Consortium, Products and Membership. _______________________________________________________________________ 1.1 Synopsis % cd IC % cd isode/src/config % cp samples/system.make Make.defs % vi Make.defs % cp samples/system.h ../h/config.h % chmod u+w ../h/config.h % vi ../h/config.h % vi ../h/pp/ppconfig.h % cp samples/Make.pp Make.pp % vi Make.pp IC R2 1 Chapter 1. Introduction Installation _______________________________________________________________________ % vi ../h/quipu/config.h % cp samples/*.local . % cd .. % ./make all % su # umask 022 # ./make install To build the non-core part of the IC R2 distribution: % cd IC/contrib % ./make all % su # umask 022 # ./make install _______________________________________________________________________ 1.2 Description This is a description of how to bring up IC R2. You must have super-user privileges to (re-)install the software. Super-user privileges are not required to configure or generate this software. The distribution consists of a number of tar files. When unwrapped, these files create a hierarchy starting with the IC directory. If distribution is by tape, each tar file is stored as a separate tape file. To bring the sources on-line, you must move to a directory for local sources and extract the contents of each tape file in turn. Typically, this is achieved by repeated invocations of the tar command upon the ``no-rewind'' version of the tape device file, e.g. % cd /usr/src/local/ % umask 022 % dd if=/dev/nrst1 bs=20b | tar xf - % dd if=/dev/nrst1 bs=20b | tar xf - ... % cd IC If distribution is by transfer over the network, instructions to unwrap the source will be present with the package. 2 IC R2 Chapter 2 Configuration First, go to the isode/src/config directory. % cd isode/src/config From the samples directory, select the Makefile and include-file skeletons which most closely match your system. If appropriate files are not found, use ref.make and ref.h. The makefile skeleton has the extension .make, whereas the include-file skeleton has the extension .h. In the directions that follow, reference is made to directories defined in the config/Make.defs and config/Make.pp files. You should substitute correct values. For example, if the expression is $(SBINDIR)tsapd and if SBINDIR is defined as /usr/etc/ in the config/Make.defs file, then you should type /usr/etc/tsapd instead. _______________________________________________________________________ 2.1 Makefile Copy the makefile skeleton of your choice to Make.defs, make sure that it is writeable, and then edit it. There are many options in this file and you should check them carefully before continuing. Table 2.1 lists the options which you are most likely to change. IC R2 3 Chapter 2. Configuration Installation _______________________________________________________________________ If you are building the software for the first time on a system for which there is a skeleton makefile, you can probably use the default options. However, you should pay particular attention to those options relating to where software is installed on your system, such as PREFIX, XINCLUDE, and LIBX11PATH. variable____default_____________specifies_______________________________________________ APPS everything which applications to build BINDIR /usr/bin/ where to install user programs SBINDIR /usr/sbin/ where to install administrator programs ETCDIR /etc/ where to install administrator files LOGDIR /tmp/ where to write log files INCDIRM /usr/include/isode where to install include files LIBDIR /usr/lib/ where to install object libraries MANDIR /usr/man/ where to install man pages PREFIX a common prefix to all of the above INSROOT a prefix to all the above to be used by ./make install LINTDIR /usr/lib/lint/ where to install lint libraries SYSTEM how to create loader libraries MANOPTS see util/inst-man.sh for details XINCLUDE how to find X11 header files LIBX11PATH how to find X11 libraries OPTIONS other options to cc and lint SHARED should shared libraries be used (recommended) LIBOPTIONS other options to cc when compiling libraries NETLIB network libraries to link in (e.g., -lnsl) LIBSYS system libraries to link in (e.g., -lm) LIBPP PP libraries needed if USE_PP is defined in h/config.h Table 2.1: Main Makefile Configuration Options If you are changing the variables which specify where the software will be installed, you should edit the version with the CONF prefix, for example CONFBINDIR, and you should not modify the plain version, for example BINDIR. Note that all these directories, except INCDIRM, must be absolute path names with a trailing `/' (i.e., start and end with a `/'). If you are building IC R2 to use other software packages, such as SunNet X.25 or RTnet-OSI, that require special include paths to be searched, add these to OPTIONS. Similarly, if you need extra libraries for network services or packages like OSISEC, add them to LIBNET or LIBSYS as appropriate. % cp samples/system.make Make.defs % vi Make.defs _______________________________________________________________________ 2.2 Include-File 4 IC R2 Installation Chapter 2. Configuration _______________________________________________________________________ Copy the include-file skeleton of your choice to ../h/config.h, make sure that it is writeable, and then edit it. This file contains definitions which the software uses to configure itself during generation, and you should check them carefully before continuing. Consult the file samples/OPTIONS for more information. If you are building the software for the first time on a system which has a skeleton include-file, and you only require support for Transport Class 0 over TCP/IP, then you can probably use the default options. % cp samples/system.h ../h/config.h % vi ../h/config.h _______________________________________________________________________ 2.3 PP If you are building PP you need to copy Make.pp from samples and then edit both that file and ../h/pp/ppconfig.h. % vi ../h/pp/ppconfig.h % cp samples/Make.pp Make.pp % vi Make.pp _______________________________________________________________________ 2.4 DSA If you are building the QUIPU DSA you may want to edit the options in ../h/quipu/config.h. % vi ../h/quipu/config.h 2.4.1 GDA The quipu DSA is now augmented with a disk-based version that operates as a sub-process of quipu via the new ``Generic Directory API'' (GDA). IC R2 5 Chapter 2. Configuration Installation _______________________________________________________________________ Pre-requisites The GDA disk database in this release requires the GNU GDBM package to be installed before you can build the software. This package is owned by the Free Software Foundation, and is not supplied or supported by the ISODE Consortium. You can obtain a copy from the Free Software Foundation, either by anonymous FTP to prep.ai.mit.edu, or by contacting them directly: Free Software Foundation 675 Massachusetts Avenue Cambridge, MA 02139 USA +1 617 876 3296 Your attention is drawn to the GNU General Public License which governs the use of GDBM. A copy of it is included with the GDBM distribution. Configuration This is enabled in h/quipu/config.h as follows. #define QB_DISK You must also modify the OPTIONS and LIBGDADB definitions in config/Make.defs to include the GDBM headers and libraries. For example, if you have installed GDBM in /usr/local: OPTIONS = -I$(HDIR) $(PEPYPATH) $(KRBOPT) -I/usr/local/include # GDA DB library, if QB_DISK is defined in h/quipu/config.h LIBGDADB = -L/usr/local/lib -lgdbm _______________________________________________________________________ 2.5 Configuration Databases 2.5.1 Aliases Database Typically, sites run with the default aliases database used by the OSI Directory User Agents. In this case, simply copy the default local configuration file from the samples directory: 6 IC R2 Installation Chapter 2. Configuration _______________________________________________________________________ % cp samples/aliases.local . If you have local modifications to make, either copy in your own file, or edit the file aliases.local, as appropriate. 2.5.2 Services Database Sites which are not running X.400 typically run with the default services database. In this case, simply copy the default local configuration file from the samples directory: % cp samples/services.local . If you have local modifications to make, either copy in your own file, or edit the file services.local, as appropriate. If you are running the PP X.400 protocol channels, you must add lines of the form: "tsap/p1-84" "591" $(CHANDIR)/x400in84 "tsap/p1-88" "592" $(CHANDIR)/x400in88 -n See ISODE Volume 4: Administrator's Guide: Message Handling Services for more details. 2.5.3 Entities Database Sites which are not running PP or SunNet OSI typically run with the default application entity database used by the stub-directory service. In this case, copy the default local configuration file from the samples directory: % cp samples/entities.local . If you have local modifications to make, either copy in your own file, or edit the file entities.local, as appropriate. If you are running PP, you must add a line to entities.local of the form: mta-host "pp qmgr" 1.17.6.2.1 #1001/Internet=mta-host+18000 where ``mta-host'' is the name of the host running the MTA. You may also need to change the isomacro ``Internet'' to something else if you are not connected to the global TCP/IP Internet. IC R2 7 Chapter 2. Configuration Installation _______________________________________________________________________ As an alternative, you may add a suitable entry to the Directory if this is being used as a nameserver. This is described in Section 4.4. If you are using SunNet OSI 7.0, you must put an entry in your entities.local file of the form: myhost default 1.17.4.1.0 #1/NS+mynsap where ``myhost'' is the name of the local machine, and ``mynsap'' is the NSAP of the local machine. For SunNet OSI 7.0, the NSAP is most easily determined by running % /usr/sunlink/osi/etc/osirstat -n | grep '^DA' provided that the SunNet OSI osi.routed program is running. If you run a release of SunLink OSI earlier than 7.0, and you intend to run the standard SunLink OSI listener (osi.netd), you must change the TSEL on which tsapd listens. This is done in two steps: First, in entities.local, change your entry to read as: myhost default 1.17.4.1.0 #2/NS+mynsap Second, in services.local, add a line that reads as: tsap/session #2 tsapd-bootstrap which overrides the default TSEL in the services.db file. 2.5.4 Macros Database Typically, sites run with the default macros database. In this case, simply copy the default local configuration file from the samples directory: % cp samples/macros.local . If you have local modifications to make, either copy in your own file, or edit the file macros.local, as appropriate. 2.5.5 Objects Database Typically, sites run with the default objects database. In this case, simply copy the default local configuration file from the samples directory: 8 IC R2 Installation Chapter 2. Configuration _______________________________________________________________________ % cp samples/objects.local . If you have local modifications to make, either copy in your own file, or edit the file objects.local, as appropriate. _______________________________________________________________________ 2.6 Options Go to the IC/isode/src directory: % cd .. Decide what you want to build. By default, everything will be built, including all the libraries, tools (rosy), support applications (like tsapd), SNMP V2 applications, MTA, DUAs, and DSAs. If you do not want all of these, you must edit some of the default configuration and Makefiles. The Makefiles in directories that have subdirectories have a macro called SUBDIRS which controls which subdirectories are made. If you do not want all the applications under apps, edit the APPS macro in config/Make.defs. However, be careful of the order of the applications that you retain, as some have interdependencies. If you only want the Transport Service interface and compatibility libraries, edit lib/Makefile and modify SUBDIRS (compat and ll) and LIBS (you need only the first 4 libraries) and edit Makefile and reduce SUBDIRS to util config lib. You must also define NO_USE_DSE and NO_STUB_AET in h/config.h. With this configuration, you can build tsapd and tsbridge, but you must disable the building of iaed in apps/tsapd/Makefile. IC R2 9 Chapter 3 Build and Installation _______________________________________________________________________ 3.1 Notes and Warnings Before attempting to generate and install the software, you should read this section carefully to find out if there are any potential problems related to your operating system or intended configuration. 3.1.1 C Language & Compilers An ANSI C-capable C compiler is required to build this release. Older K&R type compilers are not sufficient. One K&R-compatible feature is required: the ability to overwrite string literals. Typically some compiler options are necessary to obtain the required semantics: for example, -Xa with the SunPro SPARCompiler C 2.0.1, or the -fwritable-strings option with GNU C. Other standard compilation tools are also required, including make, yacc and lex. Make program The whole system uses a script, called make, to be found in each directory. There are three separate versions; one for the main part of the tree, one for isode/src/apps/pp and one for contrib. Within each part of the tree, each directory contains exactly the same file (multiple links) which tries to deduce the location of various directories and the real make program. Look over the make program if you have trouble. Some older versions of make (1) do not support inheritance of environment variables as macros. In this case, you should obtain a make program that does, such as the GNU make. Some versions of test (1) do not support the -x flag, in which case you must modify 10 IC R2 Installation Chapter 3. Build and Installation _______________________________________________________________________ the three make scripts referred to above to use some other form of test. If you are using SunOS, do not use the make program supplied with the SunPro package. It is not, contrary to any claims, compatible with the standard make facility. Further, note that if you are running a version of SunOS 4.0 prior to release 4.0.3, then you must use the make program found in /usr/old/, if the default is the SunPro make. In this case, you must put the old, standard make in /usr/bin/, and keep the SunPro make in /bin/. SunOS Linker Errors If you are using SunOS 4.1, you must have Sun patch 100170-10 installed. If you are linking any of the applications against OpenWindows 3.0 on the sun4 architecture, you must have Sun patch 100573-04 installed, and you should add -lm to LIBX in Make.pp. Failure to install these patches may result in unresolved symbol and relocation errors from ld. SunLink OSI & X.25 7.0 header files The header files supplied with SunLink OSI 7.0 and SunLink X.25 7.0 (for SunOS 4) are not compatible with ANSI standard C in their use of macros to construct ioctl(2) arguments. The affected header files should be modified by hand to include appropriate alternate definitions under #ifdef __STDC__. Ultrix, the make script, and other points The built-in test command of the default Ultrix /bin/sh shell does not support the -x operator. Replacing the #!/bin/sh at the start of each of these scripts with #!/bin/sh5 should solve this problem. In isode/src/Makefile there is a test of the form test ! -d $$d but it is reported that this must be collapsed to test !-d$$d for Ultrix. User Process Limits If you are using SVR3, then you may have to type the following command before starting the compilation: % ulimit 32768 IC R2 11 Chapter 3. Build and Installation Installation _______________________________________________________________________ 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 _______________________________________________________________________ 3.2 Generation Now generate the IC R2 software by typing the following command from the isode/src directory: % ./make This will cause a complete generation of the system. If all goes well, proceed with the installation. While compiling, some files may produce a warning: statement not reached or a type ObjectDescriptor: Warning: Can't find file DSE.ph failed 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 make says something like *** Error code 1 or perhaps 12 IC R2 Installation Chapter 3. Build and Installation _______________________________________________________________________ Exit then everything is going just fine! _______________________________________________________________________ 3.3 Contributed Code In addition to the core IC R2 services and applications in the isode/src directory, there are a number of programs and tools in the contrib part of the distributed hierarchy. The contributed code is provided on an unsupported basis, and you should use your own discretion in deciding whether to build and/or use it. If you decide that you do wish to use it, it can be generated and installed in a similar fashion to the core software. You can choose to build some or all of the contributed code by editing SUBDIRS in contrib/Makefile. % cd IC/contrib % vi Makefile % ./make % su # ./make install 3.3.1 FTAM If you are running ISODE on a Berkeley or AT&T System V UNIX system, there is an implementation of the ISO FTAM. FTAM, which stands for File Transfer, Access and Management, is the OSI file service. The implementation provided is fairly complete in the context of the particular file services it offers. It is a minimal implementation in as much as it offers only four core services: transfer of text files, transfer of binary files, directory listings, and file management. _______________________________________________________________________ 3.4 Installation You must be the super-user to install the software. Your (root's) umask should be set to something like 022. Note that installing the software from an NFS-mounted partition requires that you perform the installation as the super-user on the target system after changing to the source directory on the source system. This restriction is relaxed for installation of application defaults files for X11 IC R2 13 Chapter 3. Build and Installation Installation _______________________________________________________________________ programs, which will fail with a soft error. In the directions that follow, reference is made to some of the directories defined in the config/Make.defs and config/Make.pp files. You should substitute the correct value for your system. For example, if the expression is $(SBINDIR)tsapd and if SBINDIR is defined as /usr/etc/ in the config/Make.defs file, then you should type /usr/etc/tsapd instead. If you are running PP, you must create the pp user id. For example, add an entry to the /etc/passwd file of the form: pp:*:21:1:Postmaster:$(PPDIR):/bin/csh The base installation directory and the directories for manual pages must be created before installation. For example: $(INSROOT)$(PREFIX) $(INSROOT)$(CONFINCDIRM) $(INSROOT)$(CONFINCDIRM)/snmp $(INSROOT)$(CONFMANDIR)/man1IC $(INSROOT)$(CONFMANDIR)/man3IC $(INSROOT)$(CONFMANDIR)/man5IC $(INSROOT)$(CONFMANDIR)/man7IC $(INSROOT)$(CONFMANDIR)/man8IC To install the software, type: # ./make install This command tries to build all the directories you have specified, using mkdir. The parent of each directories must exist for the the mkdir to succeed. NOTE: install does not try to build the directories for manual pages. If you are already running ISODE, you must kill and restart the tsapd(8c) daemon when install has finished. If you do not do this, the incoming connections will not be initialised correctly. If this is the first installation of ISODE, start the daemon as soon 14 IC R2 Installation Chapter 3. Build and Installation _______________________________________________________________________ as install completes. From the CShell, the command to do this might be: # $(SBINDIR)tsapd >& /dev/null The daemon will automatically detach. If you do not redirect the daemon's standard-error, it will enter debugging mode, where it will remain attached to the controlling terminal, printing messages about the actions it is taking, and will only accept one connection before exiting. Now, everything is installed and you can clean-up the source tree, by using: % ./make clean _______________________________________________________________________ 3.5 Testing Some directories may have a resident test program. These programs are for internal testing only, and their use is not documented or supported. If you want to test IC R2, you can run isode-test. For isode-test to work, you must have built and installed the isode/src/apps/imisc and contrib/isoc subdirectories, and you must have installed and started tsapd, as described in Section 3.4. The programs in isode/src/apps/imisc implement services such as finger, who, and so forth, which are analogous to those found in the TCP/IP protocol suite. More details can be found in ISODE Volume 3: Administrator's Guide: General Services. The programs in contrib/isoc implement services which perform loopback testing at each layer in the OSI stack. These may be used together to test out the installation of IC R2 on your system: % cd isode/src % isode-test IC R2 15 Chapter 4 Post-Installation Configuration There are some activities that need to be done only once: 1. Verify that the tsapd daemon will be run when the machine goes multi-user. On Berkeley UNIX systems, add these lines to the /etc/rc.local file: if [ -f $(SBINDIR)tsapd ]; then $(SBINDIR)tsapd >/dev/null 2>&1 & (echo -n ' tsap') > /dev/console fi On other systems, a similar procedure is followed. For example, on systems derived from AT&T UNIX, the file /etc/rc2 script might be edited. Once you are familiar with the system, you will likely want to run the OSI Directory and use another program, iaed to invoke local services. Section 4.3 discusses this in greater detail. (However, if this is your first installation of an ISODE Release, don't skip ahead.) 2. Verify that systems with a native /etc/services file contain an entry for the tsap service (if you have configured IC R2 to run over TCP). If no entry exists, add the line: tsap 102/tcp to the /etc/services file. Some systems may have a definition of the form iso-tsap 102/tcp 16 IC R2 Installation Chapter 4. Post-Installation Configuration _______________________________________________________________________ which is also acceptable. If your system does not have such a file, the software automatically compensates for this. 3. On Berkeley UNIX systems, add a line to the /usr/lib/crontab file to invoke a shell-script that will re-cycle the log files. Usually, the line you add looks something like this: 0 4 * * * su daemon < $(SBINDIR)isologs which says that the shell-script $(SBINDIR)isologs should be invoked at 4am each morning. On other systems, a similar procedure is followed. For example, on systems derived from AT&T UNIX, the file /usr/spool/cron/crontabs/root might be edited by the command % crontab -e _______________________________________________________________________ 4.1 Tailoring You can customise the behaviour of the programs which use ISODE when they start, by creating a file called $(ETCDIR)isotailor. Consult ISODE Volume 3: Administrator's Guide: General Services for further information. _______________________________________________________________________ 4.2 The PP MTA The pp user id must have been allocated before you install the software, as described in Section 3.4. A once-only activity is to make sure that PP will run when the machine goes multi-user. On Berkeley UNIX systems, add something along these lines to the /etc/rc.local file: if [ -f $(PPDIR)pp.start ]; then $(PPDIR)pp.start & (echo -n ' pp') > /dev/console fi Sample pp.start files are located in isode/src/apps/pp/config. NOTE: If you wish to use SMTP, it may be appropriate to start the smtp server from /etc/inetd by adding a suitable line to /etc/inetd.conf. See Volume 4 for more details, but the basic format is something like: IC R2 17 Chapter 4. Post-Installation Configuration Installation _______________________________________________________________________ smtp stream tcp nowait pp $(CHANDIR)/smtpd smtpd $(CHANDIR)/smtpsrvr smtp To allow processes to contact the qmgr, you must add a line to your isoentities file, as described in Section 2.5.3. _______________________________________________________________________ 4.3 Directory Services This section describes how to set up and run the OSI Directory. If you're not interested in running a Directory, skip this text and go to Section 4.4. Each host using the OSI Directory implicitly runs a Directory User Agent (DUA). Additionally, you may wish to run a Directory System Agent (DSA) on some hosts. As such, the instructions which follow indicate which activities are necessary in both instances, as appropriate. 4.3.1 QUIPU Installation The QUIPU DSA is a ``static responder''. This means that it accepts new associations and manages old ones on its own. Hence, if you intend to run a local DSA, you must start the ros.quipu 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 $(ETCDIR)quipu-db; $(SBINDIR)ros.quipu >/dev/null 2>&1) & (echo -n ' quipu') > /dev/console fi (This assumes your database is in the directory $(ETCDIR)quipu-db, but it could be somewhere else, in which case substitute the required directory name. On other systems, a similar procedure is followed. 4.3.2 QUIPU Database If you intend to run a local DSA, then you must build a Directory database. (If you are running QUIPU 5.0 or later, you've already done this, so you can skip to Section 4.3.3. The database directory, by default, lives in the ETCDIR area (usually /etc/) under the name of quipu-db/. Three prototype databases can be found in the directory contrib/quipu-db/. These database files should 18 IC R2 Installation Chapter 4. Post-Installation Configuration _______________________________________________________________________ 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 directory. Now customise the chosen prototype database under $(ETCDIR)quipu-db/. The details of this database are explained in ISODE Volume 5: Administrator's Guide: Directory Services. You should be able to derive a minimal database from the non-root prototype by following the example structure defined for University College London in the GB branch of the Directory tree. Once this has been done, delete the example structure for ``O=University College London''. 4.3.3 QUIPU Tailoring If you choose to run a local DSA, you must now configure it. The DSA tailors itself at runtime by reading the file $(ETCDIR)quiputailor. A prototype of this file is 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 section in ISODE Volume 5: Administrator's Guide: Directory Services for a description of the full range of tailoring options in the $(ETCDIR)quiputailor file. When you have done this, you must configure the various DUA programs. These programs tailor themselves at runtime, by reading the file $(ETCDIR)dsaptailor. A prototype of this file is installed during the normal ISODE installation process. 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. Do not confuse the dsa_address in this file with the ns_address in the $(ETCDIR)isotailor file. They relate to separate services and must live at different addresses. See ISODE Volume 5: Administrator's Guide: Directory Services for a description of the full range of tailoring options in the $(ETCDIR)dsaptailor file. IC R2 19 Chapter 4. Post-Installation Configuration Installation _______________________________________________________________________ 4.3.4 QUIPU Having tailored QUIPU, you can start the DSA. However, if you are already running QUIPU, then you must kill and restart the QUIPU DSA. To start the DSA from the CShell, 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, but print messages about the actions it is taking. _______________________________________________________________________ 4.4 Registering OSI Application Services Earlier releases of ISODE relied on static tables to keep track of the OSI application services offered on an end-system. This is a problematic exercise in keeping local and remote tables synchronized. In this release of ISODE, the OSI Directory can be used to manage this information, thereby automating the synchronization process. 4.4.1 Preparation Once you have installed ISODE, you must bring up a DSA. The procedures for doing this vary, depending on your location; consult the section "Setting up an Initial DSA" in the ISODE Volume 5: Administrator's Guide: Directory Services. You should also configure the $(ETCDIR)ufnrc file to reflect your local Directory Tree. Details are given at the head of the stub ufnrc file created during ISODE installation. Once your DSA is running, you must build the DMD (Directory Management Domain) for your organisation. Under the entry for your organisation, you must select an area where your end-system's application entities will reside in the DIT. For example, the OSI application services available at the ISODE Consortium's European headquarters reside under: c=GB @o=ISODE Consortium Note that this area may very well be different to the value of the ``local_DIT'' in your dsaptailor file. In general, all the end-systems at a site will have the same ``local_DIT'' value, but each end-system offering OSI application services will place those services 20 IC R2 Installation Chapter 4. Post-Installation Configuration _______________________________________________________________________ at a different position in the DIT (usually somewhere underneath the ``local_DIT'' value). By convention, all the OSI application services offered by a given end-system are placed in the same location in the DIT, under an applicationProcess entry named with the short name of the end-system, e.g., ``cn=lemming''. So, using the example above, the entry c=GB @o=ISODE Consortium @cn=lemming would contain all the entries of interest. 4.4.2 Once-only Installation The bootsvc script will generate a shell script that will create an applicationProcess entry and then an entry for each of the OSI services provided by ISODE. Before this happens, you must select the RDN for the applicationProcess entry. 1. Run bootsvc to create a script: % config/bootsvc <> > run.sh e.g., % config/bootsvc lemming > run.sh Note that the first line of this script defines the network address where iaed listens for incoming connections. By default, only the address for the Internet community (RFC1006) is set. If the end-system is configured for other OSI communities, then this line should be changed accordingly, for example to: A="Internet=`hostname`|NS+mynsap" 2. Next, start dish in the background, bind as the manager, move to the location in the DIT where the services are to be registered and run the script, e.g., % setenv DISHPROC "127.0.0.1 `expr $$ + 32768`" % bind -u <> % moveto "@c=GB@o=ISODE Consortium" % sh run.sh IC R2 21 Chapter 4. Post-Installation Configuration Installation _______________________________________________________________________ 3. You must arrange for iaed, rather than tsapd, to run when the machine goes multi-user. On Berkeley UNIX systems, replace these lines in the /etc/rc.local file: if [ -f $(SBINDIR)tsapd ]; then $(SBINDIR)tsapd >/dev/null 2>&1 & (echo -n ' tsap') > /dev/console fi with: if [ -f $(SBINDIR)iaed ]; then $(SBINDIR)iaed -D '@c=GB@o=ISODE Consortium@cn=lemming' \ >/dev/null 2>&1 & (echo -n ' iae') > /dev/console fi On other systems, a similar procedure is followed. When iaed starts, it will connect to the Directory, find the services contained therein, and start listening as appropriate. 4. The installed software includes a program called dased. By default, the ISODE initiator programs aren't loaded with the user-friendly name service and the DAP, owing to the code size -- instead, they talk to dased. If you have not already done so, edit the $(ETCDIR)isotailor file to have these two lines: ns_enable: on ns_address: Internet=myhost+17006 You can run dased on a different machine than the one running the local DSA, but it's probably best to have them running on the same machine. Now, you must arrange for dased to be started when the machine goes multi-user. On Berkeley UNIX systems, add these lines to the /etc/rc.local file: if [ -f $(SBINDIR)dased ]; then $(SBINDIR)dased >/dev/null 2>&1 & (echo -n ' dase') > /dev/console fi 5. If you wish to run ISODE initiator applications from systems other than the one running dased, you must edit the $(ETCDIR)isotailor files on those systems too, so that they include these two lines: 22 IC R2 Installation Chapter 4. Post-Installation Configuration _______________________________________________________________________ ns_enable: on ns_address: Internet=dased-host+17006 where ``dased-host'' is the name of the machine which is running dased (the same as ``myhost'' above). 6. To test the system: % isode-test -iaed If all goes well, users should be able to type things such as % imisc "lemming,ISODE Consortium,GB" and ``the right thing'' will happen (that is, local users will be able to access remote services, even if the remote services have not been entered into the entities database). 4.4.3 Adding New Services The installation procedures need be performed only once. If you decide to disable a service, simply remove the corresponding entry from the Directory. To add a new service, see the Section ``Defining New Services' in ISODE Volume 5: Administrator's Guide: Directory Services. IC R2 23 Chapter 4. Post-Installation Configuration Installation _______________________________________________________________________ _______________________________________________________________________ 4.5 Network Management The Release contains an implementation of SNMP V2. Some elements of this implementation are restricted to operation in Berkeley UNIX environments but the core daemon and application-monitoring proxy agents are portable. See ISODE Volume 3, Administrator's Guide, General Services for configuration details. The MD5 implementation is taken from RFC 1321 and is hereby identified as ``derived from the RSA Data Security, Inc. MD5 Message-Digest Algorithm''. 24 IC R2 Chapter 5 Obtaining Documentation The directory isode/doc/ in the distribution contains documentation for this release. The directory isode/doc/manuals/ contains PostScript versions of each volume in the IC R2 documentation set. IC R2 25 Chapter 5. Obtaining Documentation Installation _______________________________________________________________________ 26 IC R2