UCL's OSI MANAGEMENT INFORMATION SERVICE


INTRODUCTION

This is UCL's OSI management system, known as the OSI Management
Information Service (OSIMIS). OSIMIS does not intend to provide a
comprehensive set of OSI management facilities but rather to show how
the rich OSI Management functionality can be exploited and to serve
as a generic OSI management platform. In particular, extended support
through an object-oriented (in C++) Application Program Interface (API)
is provided to implementors of management applications
in agent and manager roles, which hides the details of management
information access through the OSI Common Management Information
Service/Protocol (CMIS/P).

The system has been developed using the ISO Development Environment
(ISODE) and has generic and specific parts. The generic parts are
object-oriented infrastructure for the development of OSI agents
and managers and a set of generic manager applications i.e. independent
of specific management information bases. The specific parts are
agents supporting specific MIBs and associated managing applications.
It should be added that the emphasis is on generic infrastructure
rather than specific applications, the latter have been developed
in order to exercise the generic infrastructure and verify the concepts.

There is only a small team involved in the OSIMIS work at UCL and the system
has been a side product of our involvement in European research projects
(see below). Although we will try to answer questions about the system
and rectify bugs as they are reported, we cannot give guarantees about
any level of support. A primary motivation for us in putting OSIMIS in
the public domain has been to provide other developers with a platform
on which they can build their implementations. We hope, for example, that
others will be encouraged to develop additional MIB support and managing
applications (particularly nice graphical ones) and that these will be
placed in the public domain on the same basis as OSIMIS. We would be glad
to hear of any such developments and interworking experiences as well
as bug reports (and fixes!) via the OSIMIS list <osimis@cs.ucl.ac.uk>.


OSIMIS has been developed as part of UCL's participation
in the following European research projects:

ESPRIT I INCA - Integrated Network Communications Architecture

This had as target the design and development of OSI infrastructure and
applications. Parts of ISODE, the QUIPU Directory Service and the very
first version of OSIMIS that comprised an embryonic version of CMIS/P
and agent/managers specific to the management of the ISO Transport Protocol
were developed then.

ESPRIT II PROOF - Primary Rate ISDN OSI Office Facilities

This had as target the research, design and development of IP / X.25 to
Primary Rate ISDN gateways and related OSI management tools. The first
version of the OSIMIS Generic Managed System (GMS) was developed while log
control and the OSI Internet MIB were later added. Special agents and
managers for managing those gateways were also developed.

RACE I NEMESYS - Network Management using Expert Systems

This had as target the research into Traffic and Quality of Service Management
for Integrated Broadband Communications and the evaluation of Advanced
Information Processing (AIP) techniques. The GMS was developed much further,
manager support such as shadow MIB concepts were investigated and a layered
QoS management prototype was produced based on the Telecommunications
Management Network (TMN) principles, with hybrid units (agents/managers)
organised in a hierarchical fashion.

RACE II ICM - Integrated Communications Management

This is the continuation of NEMESYS with more functions and real IBCN (ATM)
infrastructure as opposed to the latter where the IBC network and services
were simulated. Work is in progress.

ESPRIT III MIDAS - Management In a Distributed Application/Service environment

This has as target to show that the OSI management model is equally suitable
to the management of distributed applications by producing management systems
for the OSI Directory (X.500) and Mail (X.400) services. Work is in progress.



SUPPORTED MIBs

In the current version there are the following implemented MIBs:

a. a MIB for the ISO/CCITT Transport Protocol management which is used
   to manage (monitor) the ISODE implementation of the latter. This is
   non-standard though the relevant managed objects are similar
   to the ones specified in the (draft) ISO/IEC 10737 "Transport Layer
   Management".

   Incarnations of the transport protocol run as user space processes
   (code linked with OSI applications) and information in them is reported
   to the agent through UDP datagrams as the local interprocess communication
   mechanism ("loosely-coupled real resources with asynchronous reporting").

b. a trivial example UNIX MIB with one managed object showing the number
   of users in a UNIX system with an associated threshold and tide-mark,
   whose purpose is to serve as an example of the interface to the generic
   parts of the system.

   Information on the number of users is obtained by executing the UNIX
   "users" command and reading its output through a pipe to it, either
   upon external CMIS request or periodically to support notifications
   ("loosely-coupled resource with a fetch-on-request/polling access")

c. an implementation of the OSI Internet MIB (OIM - OSI view of the
   TCP/IP SNMP MIB-II) as in the RFC1214 without the EGP and SNMP groups.

   This is a non-proxy implementation in the sense that real resource
   information is retrieved by accessing the UNIX kernel either upon
   external CMIS request or periodically to support notifications
   ("tightly-coupled resources with a fetch-on-request/polling access").

It should be added that though not in this release, we also have at UCL
a proxy implementation of the OSI Internet MIB which talks at the back-end
to the ISODE SNMP agent ("loosely-coupled resources with a fetch-on-request
access and asynchronous reports i.e. SNMP traps"). This will find its
way to OSIMIS in a future release.



MANAGING APPLICATIONS

The following managing applications are provided:

a. a set of programs that allow any operation to be performed to a management
   agent with any CMIS parameter apart from access control information.
   These work from the command line and are namely mibdump, mset, maction,
   mcreate and mdelete.

b. two programs that allow event reports to be requested and received or
   logged. These work from the command line and are namely evsink and evlog.

c. a X-Windows based MIB browser which enables one to browse through a remote
   management information tree, set management attributes and also "monitor"
   managed objects at regular intervals.

d. a program specific to the OSI Internet MIB which allows one to manipulate
   IP routing tables. This works from the command line and is called iproute.



GENERIC INFRASTRUCTURE

The basic common infrastructure comprises a CMIS/P implementation
together with infrastructure for writing applications using an
event-driven approach by exercising centralised control / providing
polling support and also infrastructure for hiding ASN.1 manipulation.

Then there is extensive infrastructure for developing management agents.
Development support for these is provided through the Generic Managed
System (GMS) which hides completely CMIS access details such as managed object
addressing, scoping, filtering and error handling and allows MIB implementors
to concentrate on issues related to real resource access. A GDMO compiler
is planned for the near future which will minimise even further the code
that needs to be written. The GMS also provides support for the systems
management functions, event reporting and logging being supported at present.
Object management, access control and others are planned for the future.

As far as generic manager infrastructure is concerned, there exists at
the moment an (non-complete) implementation of a "Remote MIB (RMIB)" which
offers an object-oriented abstraction of a management association, assembles
linked replies, hides the manipulation of ASN.1 and in general offers
a higher level CMIS interface - this will be completed in the near future.
As a longer term project, there are plans of providing a higher level
abstraction of a "Shadow MIB (SMIB)", which will enable to access managed
objects in remote MIBs as if they existed in the local address space.



CMIP AND STACK PROFILES

The OSIMIS CMIP implementation conforms fully to the IS version 2
(the one also adopted by the NM Forum) and uses the ISODE upper layer
OSI stack. The latter allows the following stack profiles (transport
and network protocol combinations to provide the OSI Transport Service):

  -- OSI TS ---       ---------------        --------        --------
  | Transport |       | TP0/RFC1006 |        | TP0  |        | TP4  |
  -------------       ---------------        --------        --------
  | Network   |       | TCP/IP      |        | X.25 |        | CLNP |
  -------------       ---------------        --------        --------

OSI TS  OSI Transport Service
TPx     Transport Protocol Class x
CLNP    ConnectionLess Network Protocol
TCP/IP  Transmission Control Protocol / Internet Protocol

Applications on any of these stacks can interoperate through transport
service bridging. ISODE also provides an implementation of the Lightweight
Presentation Protocol (LPP) which enables CMIP to run directly on top
of TCP which offers the connection-oriented Internet Transport Service.
This approach known as CMOT (CMIP over TCP/IP - RFC 1189).

The complete upper layer stacks for CMIP and CMOT are:

                Full CMIP stack          CMOT stack

            CMIS -------------          ------------- CMIS
                 | CMIP      |          | CMIP      |
                 -------------          -------------
                 | ACSE/ROSE |          | ACSE/ROSE |
                 -------------          -------------
                 | OSI PP    |          | LPP       |
                 -------------          ------------- Internet TS
                 | OSI SP    |
          OSI TS -------------

ACSE:  Association Control Service Element
ROSE:  Remote Operations Service Element
(L)PP: (Lightweight) Presentation Protocol
SP:    Session Protocol

The OSI Transport Service can be provided by any of the stacks shown above.
Applications over the lightweight CMOT stack can NOT interoperate with
applications over the full CMIP stack but applications are portable across
the two stacks (in fact, all that is involved is linking the applications
with a different stack library as the CMIS interface remains the same).


(*) As background to the previous discussion, we mention here the OSI
    notion of protocol and service: the protocol provides the service,
    the latter being independent of the protocol's internal operation.
    There may be more than one approaches to producing APIs for an abstract
    service e.g. sockets and streams for TCP/IP, OSIMIS CMIS and the X/Open
    XMP etc. The concept is shown below using CMIS and CMIP as an example:

               --- service ---          ---- CMIS ----
               |             |          |            |
               |   protocol  |          |    CMIP    |
               |             |          |            |
               ---------------          --------------


INTEROPERABILITY

Although we have never done any conformance or interoperability testing
ourselves, third parties have tested the OSIMIS CMIP (over ISODE)
against the Retix and IBM NetView CMIP successfully. No interoperability
testing was done at the GMS (agent) level regarding linked replies, error
handling etc. Such interoperability tests will be conducted in the future.



USE OF ISODE

OSIMIS uses the following ISODE interfaces/support:

The ASN.1 pepsy(*) compiler - it offers an API broadly
equivalent to the X/Open XOM one (also adopted by the OSF DME)(**).

The Association Control / Remote Operation Service API which are used
to implement CMIP - CMIS is broadly equivalent to the X/Open XMP interface
(also adopted by the OSF DME)(**).

It may use the X.500 OSI Directory Service implementation coming with ISODE
(QUIPU) for application addressing i.e. mapping Application Entity Information
to OSI Presentation Addresses. In the default case, it uses local tables.

It also uses parts of the QUIPU code that manipulate ASN.1 syntaxes through
the use of object identifier / syntax tables. This is used as the basis
of the higher level ASN.1 abstractions offered by OSIMIS.


(*)  In OSI management, plain ASN.1 is used to describe the CMIP Protocol
     Data Units (PDUs) and also the syntax of attribute, action and
     notification values of managed objects.

(**) Please note the term "broadly equivalent" regarding the resemblance
     of the ISODE ASN.1 and OSIMIS CMIS APIs to the X/Open XOM/XMP ones.
     As somebody put it "we should be ashamed of any resemblance
     that does exist" as the latter are simply horrific.



IMPLEMENTATION INFORMATION

The system can be used with the ISODE versions 7.0 or 8.0 or the
ISODE Consortium Release 1.0 .

The management protocol layer (CMIP) has been developed using
the C programming language in order to be easily integrated from
different programming environments.

The generic management infrastructure and applications have been developed
in C++ to exploit the object oriented nature of the OSI Management model.

The C++ compilers used for the development were the GNU C++ version 2.2.2
and the ATT (Sun) C++ compiler version 2.1 . The last GNU version (2.5.8)
will also work apart from  the browser because of InterViews-2.6 (see below).
ATT versions 3.x have never been tried and will probably not work.

The browser has been implemented using the InterViews library version
2.6 (with both GNU and ATT C++). This InterViews version is now superseeded
but UCL still provides it since it is needed for the MIB browser.
The reason we have not switched to versions 3.0 or later is that these
are very different to 2.6 in both concepts and APIs. We intend to abandon
InterViews in favour of Motif in the near future and of TCL/TK later.

If you have GNU 2.5.x and need the browser, you may use the pre-compiled
version in $(TOP)/bin for Sun SPARC/SunOS 4.1.3 if you have the same
environment. You may then comment out the browser in the first part
of CONFIG.make and build the rest of the system without it (see later).

No other object libraries have been used in order to minimise tool
dependencies. Note that GNU C++ versions do not work with shared libraries.
If you use GNU, make sure that ISODE libraries have NOT been configured
as shared.



PORTABILITY

OSIMIS is (potentially) portable on every platform ISODE is and the later
runs on many, mainly UNIX, platforms (Sun, IBM, DEC, HP etc.) The only
portability problems could be related to the C++ compiler / system header
files and should be easily resolved. This version is known to work for the
Sun SunOS, IBM AIX, HP HP-UX and PC 386BSD versions of UNIX, we would welcome
extensions that will provide portability to other systems.

If you intend to build OSIMIS for HP-UX/AIX, you will have to modify slightly
Makefiles in compilers/mocompiler/flex, compilers/mocompiler/gdmo,
util/sntx and xmp/test as HPUX/AIX Makefiles do not support the += construct.
You will have to put all additional paths in OPTIONS/CCFLAGS in
$(TOP)/CONFIG.make.




DIRECTORY STRUCTURE

A snapshot of the directory structure and short comments on their contents
is given below. There are README files in most directories, some offering
comprehensive information.

osimis/
    |
    |-- doc/
    |
    |-- lib$(CMPL)$(ARCH)
    |
    |-- bin$(ARCH)
    |
    |-- man
    |
    |-- etc/
    |
    |-- include/
    |       |
    |       |-- isode/
    |
    |-- h/
    |
    |-- misode/
    |
    |-- util/
    |       |
    |       util/
    |       |
    |       sntx/
    |       |
    |       sys_info/
    |       |
    |       progs/
    |       |
    |       security/
    |
    |-- compilers/
    |       |
    |       |-- mocompiler/
    |               |
    |               |-- flex/
    |               |
    |               |-- byacc/
    |               |
    |               |-- gdmo/
    |               |
    |               |-- attrcompiler/
    |               |
    |               |-- osimis-pepsy/
    |
    |-- lt/
    |
    |-- kernel/
    |       |
    |       |-- example/
    |
    |-- msap/
    |
    |-- agent/
    |       |
    |       |-- smi/
    |       |
    |       |-- gms/
    |       |
    |       |-- monmet_mib/
    |       |
    |       |-- isode_mib/
    |       |
    |       |-- ux_mib/
    |       |
    |       |-- oim_mib/
    |       |
    |       |-- sma/
    |       |
    |       |-- oim_sma/
    |  
    |-- manager/
    |       |
    |       |-- rmib/
    |       |
    |       |-- general/
    |       |
    |       |-- general2/
    |       |
    |       |-- browser/
    |
    |-- mibutil
    |
    |-- examples/
    |       |
    |       |-- odp/
    |
    |-- simtime
    |       |
    |       |-- library/
    |       |
    |       |-- example/
    |
    |-- proxy
    |       |
    |       |-- iqa
    |             |
    |             |-- etc
    |             |
    |             |-- imibtool
    |             |
    |             |-- snmp
    |             |
    |             |-- proxy
    |             |
    |             |-- pma
    |
    |--   xmp
    |       |
    |       |-- provide/
    |       |
    |       |-- use/
    |       |
    |       |-- test/
                  
                  


`doc' - documentation


`lib$(CMPL)$(ARCH)' - the default library directory, possibly more than one
                      for different C++ compiler / machine architecture
                      combinations (see tailoring below)

`bin$(ARCH)' - the default binary directory, possibly more than one
               for different machine architectures (see tailoring below)

`man' - the default manual directory

`etc' - the default OSIMIS ETCDIR

`include' - the default OSIMIS INCLUDE directory which contains modified
            versions of system header files that should be in /usr/include,
            /usr/local/include etc. The `include/isode' subtree contains
            the modified with C++ function prototypes ISODE header files


`h' - the default OSIMIS header file directory


`misode' - a version of the ISODE library with the transport management hooks
           compiled in which allows to manage (monitor) OSI applications
           linked with it (ISODE is built without them in the default case)



`util/util' - a utility library: generic classes and gdbm(3), the GNU
              version of the UNIX database management system (dbm) which
              is used for managed object persistency


`util/sntx' - a copy of the ISODE QUIPU oidtable and syntax manipulation
              software which is also found in the ISODE dsap library.
              The reason for being replicated is OSIMIS is to overcome
              a limitation on the size of handled tables and to provide
              performance and other enhancements in the future.

`util/sys_info' - utility routines for kernel access, used by the OIM MIB

`util/progs' - a utility program for looking at dbm files

`util/security' - the peer authentication and integrity check security
                  extenstions library

`compilers' - the GDMO compiler in compilers/mocompiler
              the attribute compiler in compilers/attrcompiler
              the OSIMIS version of pepsy required for use with the attribute
              compiler in compilers/osimis-pepsy

`lt' - the location transparency facility based on the X.500 directory service


`kernel' - the kernel infrastructure common to agents/managers
           providing process coordination and high-level ASN.1 support


`kernel/example' - a trivial example of using this infrastructure


`msap' - full CMIP version 2 implementation


`agent/smi' - the Structure/Definition of Management Information syntaxes


`agent/gms' - the Generic Managed System library (agent infrastructure)


`agent/monmet_mib' - the monitor metric SMF MIB


`agent/isode_mib' - the TP MIB to manage the ISODE TP implementation


`agent/ux_mib' - the example UNIX MIB


`agent/oim_mib' - the OSI Internet MIB


`agent/sma' - the agent for the TP and UNIX MIB


`agent/oim_sma' - the agent for the OSI Internet MIB


`manager/rmib' - the "Remote MIB" manager infrastructure


`manager/general' - the mibdump, mset, maction, mcreate, mdelete, evsink and
                    evlog programs

`manager/general2' - an implementation of the mibdump and evsink as examples
                     using the RMIB infrastructure (as opposed to plain
                     CMIS in manager/general)

`manager/browser' - the cmisbrowser program


`mibutil' - utilities to look up files of persistent MOs / logs


`examples/odp' - an ODP-like simple statistics calculator through OSI mgmt;
		 the directory maybe used for location transparency


`simtime' - a facility that enables real management applications to
            operate in simulated time over a network/service simulator
            without any code change

`proxy/iqa' - the Internet Q-Adaptor i.e. CMIS->SNMP generic proxy


`xmp' - the prototype XMP (without XOM) implementation



HOW TO SET UP THE SYSTEM

First of all, you need to configure OSIMIS for the version of ISODE
you are using. The default configuration is for version 8.0. If you
are using version 7.0 or IC-R1.0, you should go in the directory
osimis/include/ and change the ISODE header file tree:

rm isode; ln -s isode-7 isode  or
rm isode; ln -s isode-icr1 isode

You should also go in the directory osimis/misode and change the
managed ISODE tsap directory:

rm tsap; ln -s tsap-7 tsap  or
rm tsap; ln -s tsap-icr1 tsap


CONDITIONALLY COMPILED OPTIONS

Many of the extensions to OSIMIS are now available as conditionally compiled
options. These include:

    BROWSER  - the MIB browser
    RMIB     - the Remote MIB object-oriented manager access API
    SIMTIME  - the simulated time support service
    LT       - the X.500-based location transparency feature
    MONMET   - the monitor metric objects
    OIM      - the native implementation of the OSI Internet MIB
    IQA      - the Internet Q-Adaptor (CMIS->SNMPv1 proxy)
    XMP      - the prototype XMP implementation
    SECURITY - uuthenticated associations and integrity checks
    ATTRCOMP - attribute compiler
    OSIMISPEPSY - a modified version of pepsy (needed by the attr compiler)

These options are selected (deselected) by editing the top part of
osimis/CONFIG.make and removing (adding) the comment mark '#' to the beginning
of certain lines. For instance, to include the proxy, make sure the following
variables are un-commented:

#CCONFIG         += -DIQA
#IQA             = iqa
#IQA_SNTX_LIB    = $(TOP)/proxy/iqa/proxy/libiqasyntaxes.a

Each options is accompanied by a 'CCONFIG =+' directive which is used in
OPTIONS to direct conditionally compiled options.

Some of the commented out options do not exist in the tar image and this
is indicated by a comment in CONFIG.make and your licence. Obviously,
you should NOT uncomment these while you may uncomment any of the other
(optional features).


LOCAL PATH TAILORING

Before building OSIMIS, you will need to tailor osimis/CONFIG.make
to reflect the local configuration. The following paths should be edited:

LSOCKET	=	the same as in the CONFIG.make you used to build ISODE
		(usually empty); you may also use it to add specific
		system libraries e.g. -liberty for AIX

CC	=	the C compiler (gcc for GNU, cc if you use ATT CC for C++)

CCPLUS	=	the C++ compiler (g++ for GNU, CC for Sun ATT C++)

PEPSY	=	the ISODE pepsy ASN.1 compiler. It should be just 'pepsy' or
		the full pathname if not in the standard directories searched

ISODE	=	the ISODE library directory

IVIEWS	=	the InterViews library directory

X11	=	the X Windows library directory
		should be empty for plain X and -L/usr/openwin/lib
		for Sun OpenWindows

		Note: you need to add -I/usr/openwin/include to
                the definition of OPTIONS variable in CONFIG.make
                if you use Sun OpenWindows.

IVIEWSINC=	the local system directory that contains
		the InterViews header files. These are needed only
		for the MIB browser application.

X11INC	=	the local system directory that contains the X11 header files.
		If this happens to be the same with the previous one,
		you should just leave it empty

		PLEASE NOTE:

		None of the two previous paths should be /usr/include
		as compilers look in that directory in any case. If you specify
		it explicitly through IVIEWSINC/X11INC, you will
        	confuse the compiler and get a lot of compilation errors.

		Also if any of the previous labels is left empty,
		you will have to remove the related -I<label> directive from
		the INC label further down.


LPP	=	a directive to use the lightweight presentation layer
		directly on top of TCP (CMOT stack) -
		in this case this should be "-lpp", else undefined (empty)

		PLEASE NOTE:

		If you set the LPP label to -lpp to use the CMOT stack,
		you should add the -DLPP directive to the CCONFIG list.
		Otherwise make sure the -DLPP directive is not present.

CMPL	=	you may use this if you wish to build OSIMIS for more
		than one compiler e.g. GNU and ATT C++ as we do at UCL.
		This directive is used to create unique names for the
		library directory, else should be undefined (empty)

ARCH	=	you may use this if you wish to build OSIMIS for more
		than one machine architecture e.g. Sun4 and Sun3, Sun4
		and RS6000 etc. This directive is used to create unique names
		for the binary directory, else should be undefined (empty)

OSISEC  =       If using the security extensions, this should point to your
                OSISEC installation. You should not need to change the
                variables OSISEC-INC and OSISEC-OPT apart from selecting them
                by un-commenting if necessary.

The following six directory paths (LIB, BIN, OSIMIS-INC, H, ETC, MAN)
should be left to point within the OSIMIS tree during the build process.
They should be edited after the latter has been successfully completed and
if the final installation directories are outside the OSIMIS tree.

LIB	=	this is the directory where the OSIMIS libraries should
		be installed. Its default position is within the OSIMIS
		tree but you may choose to install the libraries in another
		place such as /usr/local/lib/osimis

BIN	=	this is the directory where the OSIMIS programs should
		be installed. Its default position is within the OSIMIS
		tree but you may choose to install the libraries in another
		place such as /usr/local/bin

OSIMIS-INC =	this is the directory where the OSIMIS replacements/additions
		to system header files are installed. Its default position
		is within the OSIMIS tree but you may choose to install
		the header files in another place such as
		/usr/local/include/osimis

H	=	this is the directory where the OSIMIS header files are
		installed. Its default position is within the OSIMIS
		tree but you may choose to install the header files in another
		place such as /usr/local/include/osimis

ETC	=	this is the OSIMIS ETC directory. Its default position
		is within the OSIMIS tree but you may choose to put it
		in another place such as /usr/local/etc/osimis

MAN	=	this is the directory where the OSIMIS manual pages are
		installed. Its default position is within the osimis
		tree but you may choose to install the header files in another
		place such as /usr/local/man


Also if you use OSIMIS with the IC-R1.0, you should add the -DICR1
directive in the CCONFIG list to force the necessary conditional compilation.



BUILDING MISODE

In order to manage the ISODE implementation of the ISO Transport Protocol,
management instrumentation has been added to the ISODE transport layer.
This instrumentation is not usually compiled in when building ISODE, so
the misode/ directory contains a version of the ISODE library with that
instrumentation compiled in. It also contains a version of the standard
ISODE test client/server programs imisc/imiscd linked with that library
as simple managed applications, hence the renaming to mimisc/mimiscd.
Any other OSI applications using ISODE can be managed by simply being linked
with that library.

Before building the system, you should decide if you want to install
and operate the ISO Transport Protocol MIB which enables you to manage
(monitor) the transport activity of OSI applications that use ISODE
(apart from the management ones as this would be incestuous!).
As a warning, though all the necessary steps are described here,
it would help if you understood how ISODE can be configured (static and
dynamic servers, transport daemon etc.) as we found that in the past people
had problems in setting this MIB up.

If you decide to do so, you should build the software in the directory
misode/, if not you can ignore this step.  First you should make sure that
the osimis/include/isode/config.h file is the same as the config.h you
used to build ISODE, apart from the following line added to the former:

#define MGMT			/* transport management hooks */

Then go into the directory misode/ and type "make".
You will receive innocuous warnings, you may consult the
make-log/make-misode.log file which contains the log in our local system.



BUILDING OSIMIS

Before you start the building procedure, you will need to set the
environment variable GDMODIR to point to the directory ../osimis/etc/gdmodir
which contains the scripts and databases the GDMO compiler needs.
For example, if you use the csh you should type
setenv GDMODIR /<dir>/<dir>/../osimis/etc/gdmodir

Building the whole system

Go in the top osimis/ directory and type "make install-h; make".

Building the generic parts only

In many sites OSIMIS is used as a development environment and as such
only its generic parts are of interest.
It is mentioned, though obvious, that the misode/ directory
is not needed in this case.

Go in the top osimis/ directory and type "make install-h; make generic".


Building the CMIS/P-SNMP Proxy

When you make OSIMIS, this is not automatically made. In order to build it,
go in the directory osimis/proxy/iqa and type "make".



INSTALLING OSIMIS

When building OSIMIS, libraries and programs remain in their directories
within the source tree. The installation procedure moves them to the target
directories specified in osimis/CONFIG.make as explained above. You may
choose to leave those directories in their default places which are within
the source tree but you may as well choose to use directories in
/usr/local or anywhere else. In the latter case, change the paths
LIB, BIN, OSIMIS-INC, H, ETC, MAN in osimis/CONFIG.make before proceeding.


Installing the whole system

Having successfully built and tailored OSIMIS, you may install it by typing
"make install" in the top osimis/ and misode/ directories - the latter
if you are interested in the managed ISODE library and the mimisc/mimiscd
programs. You may then clean the source tree by typing "make clean" in
the same directories.

The installation procedure may also take place in the following steps:

make install-lib
make install-prog
make install-man

for the misode/ directory and

make install-etc
make install-inc
make install-h
make install-lib
make install-prog
make install-man

for osimis/.


Installing the generic parts only

If you have built the generic parts only, you may install them by typing
"make install-g" in the top osimis/ directory (the misode/ directory is then
irrelevant). You may then clean the source tree by typing "make clean" in
the same directory.

The installation procedure may also take place in steps, note that
you should specify only the generic header files, libraries and programs:

make install-etc
make install-inc
make install-gh
make install-glib
make install-gprog


Installing the CMIS/P-SNMP Proxy

If you have made and want to install this, go in the directory
osimis/proxy/iqa and type "make install".



INSTALLING THE ALREADY-BUILT OSIMIS

OSIMIS is already pre-built for Sun SPARC/SunOS 4.1.3 architecture /
operating system using GNU 2.5.8 (apart from the browser which
is built using 2.2.2). If you have a different architecture this
is useless, so you may clean the $(TOP)/lib and $(TOP)/bin directories
(e.g. rm -r lib). If not and you do not want to take the trouble
to build OSIMIS, you may install the pre-built binaries.

Edit CONFIG.make to set the ETC, OSIMIS-INC, H, LIB, BIN and MAN paths
to the places you want things installed (see also above about these) and type:

make-install-built




TAILORING THE OSIMIS/ISODE DATABASE

Having successfully built OSIMIS, you will need to tailor the OSIMIS/ISODE
database to reflect the local configuration. ISODE uses a database that
holds information on various things e.g. communities for transport bridging,
transport service stacks, application addresses (when the actual Directory
Service is not used), tables with object identifiers and possibly associated
ASN.1 syntax etc. This directory is known as ETCDIR as is hard-wired in
the library when it is built.

OSIMIS needs to use a directory with exactly the same functionality as
the ISODE ETCDIR but the two directories can NOT be merged because of name
collisions between the Directory and Management name space, so OSIMIS uses
its own. In OSIMIS, we have chosen not to  hard-wire this in the library
when it is built in order to increase flexibility but to use instead
an environment variable to point to it (see later).


1. Tailoring the OSIMIS isoentities file

First of all you should update those parts of the database related
to application addressing and which are used by default when the Directory
Service (QUIPU) is not in use. Go into the directory osimis/etc
and edit the file `isoentities' to contain the presentation addresses
of the management agents on the hosts on which they will run. Note that
there should be entries for the application titles SMA (Systems Management
Agent for the TP/UNIX MIB) and OIM-SMA (OSI Internet MIB Systems Management
Agent).

You will need to add entries for any hosts on your network on which
you wish to run the OSIMIS agents and delete those that are of no use.
Use as a template any of the existing entries and change the host name
and network address (TCP address if you use ISODE over TCP/IP with
the RFC 1006 method, X.121 address if you use it over X.25). The format
of two entries for TCP/IP / X.25 and the description of subcomponents is:

athena     SMA             1.17.5.12.0  \
                        #603/Internet=128.16.8.11+11010

petand     SMA             1.17.5.12.0  \
                        #603/Int-X25(80)=26245050261702

athena / petand         the host names
SMA                     the management application "qualifier" (logical name)
1.17.5.12.0             the application qualifier object identifier
#603                    the transport selector
Internet / Int-X25(80)  the network address community
128.16.8.11             the IP address of system `athena'
11010			the TCP port of application SMA
262450502617		the X.121 address of system `petand'
02                      the X.25 channel number of application SMA

Note that the only reason for having entries with X.25 addresses is for
remote systems i.e. systems not on the local network (it is assumed
that TCP/IP is run locally). The above address at UCL identifies a system
at IBM ENC Heidelberg which can be accessed either directly, for UCL hosts
with direct international X.25 access, or through transport service bridging
for hosts on the local Ethernet (see tailoring the OSIMIS tailor file below).

Please note that the TCP port should be a unique local number in each end
system in order to avoid collisions - check the file /etc/services for
possible TCP ports with the same number and if so, change the OSIMIS ones to
be unique.


2. Tailoring the ISODE isoservices file

The following step is only needed if you plan to operate the ISO TP MIB,
if not you can skip it. Edit the isoentities file in the standard ISODE
ETCDIR (again, the ISODE not the OSIMIS one) with the entries

default	"management"		1.17.4.1.1.15	\"598"/
default	"misode miscellany"	1.17.5.14.0	\"605"/

and the isoservices file in the same directory with the entry

"tsap/misode miscellany"	"605"	/<dir>/.../osimis/bin/mimiscd
or
"tsap/misode miscellany"	"605"	/usr/local/bin/mimiscd

which tells the transport daemon where to find the mimiscd program
to execute when a connection is requested by mimisc (dynamic server).
The reason these entries need to be in the standard ISODE and not the
OSIMIS ETCDIR is because the ISODE transport daemon (tsapd) does not
know of OSIMIS.


3. Tailoring the OSIMIS tailor file

There is a special file in the OSIMIS ETCDIRs called osimistailor
which is equivalent in functionality to the ISODE ETCDIR isotailor.
The only variables necessary to be set in there are related to logging
and are the gmsLogDir and gmsLogRecordAccess. The gmsLogDir specifies
where agents should store logs or other persistent managed objects.
The format should be (an example):

gmsLogDir:	/cs/research/midas/poteen/common/osimis/logs

Make sure this directory is not /tmp as in some Unix systems there is a bug
related to the fcntl(2) system call which is used for file locking.
Also make sure the directory exists.

The gmsLogRecordAccess flag can have the values "on" or "off".
The format should be (an example):

gmsLogRecordAccess:        on

This allows the scoping operation for log records to be switched on or
off and it is an ad-hoc access control mechanism to disallow access
to log records through CMIS scoping. The main reason for this
is related to potential resource limitations: GMS scoped objects must be
in-core which means possible memory exhaustion for logs with thousands
of records (depending on available memory and swap space).
If you use OSIMIS to monitor resources that generate a lot of
notifications which may be logged, it is advised to have this switch off.

Many other variables could be set if you intend to use OSIMIS/ISODE
in a sophisticated fashion i.e. use message tracing, use the QUIPU directory
service for address resolution or use dual stacks and transport service
bridging. The current settings have default values and should be adequate
(as far you are using TCP/IP locally...) If you intend to change these,
you should read very carefully the ISODE User's Manual Volume 2 Chapter 6
"The ISODE Tailoring File" and Chapter 8 "The Transport Switch".


4. Updating the local /etc/services file

This step is also needed only if you plan to operate the ISO TP MIB,
if not you can skip it. Update the /etc/services file on the hosts
where you will run management agents with the entry

manager		<port_no>/udp		# SMA

Make sure that the <port_no> is a unique UDP port in your local system.
This is needed because the ISODE stack is code linked with OSI applications
and runs as part of the application process, so "invocations" of the
transport protocol use UDP datagrams to report asynchronously management
information to the SMA that listens to the above port ("asynchronous
reporting from real resources to managed objects").


5. Pointing to the OSIMIS ETC directory

As already mentioned, the OSIMIS ETCDIR path is not hard-wired in the code,
an environment variable should be used instead. This should be called
OSIMISETCPATH and should point to the OSIMIS ETC directory.
You may put this in your shell start-up file (~/.login for csh etc.)
or set it explicitly in shell scripts that start the programs.

Setting an environment variable in UNIX shells is done as follows:

csh, tch:       setenv OSIMISETCPATH /<dir>/.../etc
sh:             OSIMISETCPATH=/<dir>/.../etc ; export OSIMISETCPATH
bash:           export OSIMISETCPATH=/<dir>/.../etc


6. Tailoring the OSI Internet MIB SMA

Before starting the OIM-SMA you must ensure that the binary (oimsma) has
permission to read /dev/kmem. This is so that it can extract the relevant
information from the UNIX kernel. [Please see $(TOP)/agent/oim_mib/README for
instructions on setting up the OIM-SMA with the correct permissions.]

If you intend to run the OIM-SMA on every UNIX workstation to manage TCP/IP
by putting an entry in the /etc/rc.local file, there are the following
options (see also the manual page for oimsma.8c):

a. Running it with root permissions, in which case intrusive management
   for the IP routing table is possible through the iproute and mset programs
   but without any authorisation or access control - can be dangerous!

b. Running it as a specific regular user, in which case set operations
   will not succeed - you are advised to do this.

Before starting the OIM-SMA you must update two configuration files for your
site. The two files are in the ETC directory:

- if.config, which is a table that is used to map the name of an interface
  to its type and speed. The file has entries of the form :

  ifDescr  ifType  [ifSpeed]

  The ifSpeed value is optional, and if omitted a default is assumed.

- sys.config, which is a table which is used to initialise the attribute
  values for sysLocation, sysServices and sysContact attributes. This file
  has the format:

  # first line is the default value for sysContact
  sysContact
  # subsequent lines have the form
  hostname: sysLocation: sysServices [: sysContact]

  The first line in the file is the default sysContact. Subsequent lines have
  the general form as shown, but if a value for sysContact is specified
  then it over-rides the default value.

Comment lines can be included in the files by inserting a "#" as the very
first character.

7. Tailoring for location transparency

If the directory is to be used to store agent addresses instead of the
./etc/isoentities file then the reader should first read ./doc/lt.ps.

Particular attention must be paid to the symbols dsa_address, lt_manager, 
lt_passwd and lt_local_DIT within the ./etc/dsaptailor file ; also the dir_user
and dir_passwd symbols within ./etc/isotailor must be defined.

WARNING: the lt_passwd and dir_passwd symbols necessitate security
provisions for the ./etc/dsaptailor and ./etc/isotailor files.

Also ensure that the ./CONFIG.make CCONFIG symbol contains "-DUSE_X500".



HOW TO TEST AND RUN THE SYSTEM

As has already been explained, there are two OSIMIS agents, one
supporting the OSI Internet MIB with application title OIM-SMA and another
supporting the ISO TP and UNIX MIB with application title SMA.
You may start the OIM-SMA automatically when a UNIX system is
booted by putting an entry in the /etc/rc.local file while you may start
the other manually to experiment with OSI management. Of course, you
may choose to start both manually.

You may then use the cmisbrowser, mibdump, mset, mcreate, mdelete, evsink
end evlog programs to connect to these agents. The cmisbrowser allows you to
retrieve, alter (set) and monitor managed objects, the mibdump program allows
to retrieve managed objects, the mset program allows to set management
attributes, the evsink program allows to request and receive event reports
through an event forwarding discriminator and the evlog program allows
to request the logging of notifications at the remote managed system which
may be subsequently retrieved/deleted using the other programs.
Also the mcreate and mdelete programs allow to create and delete managed
objects. Finally, the iproute program is a specific manager
for the OIM-SMA and enables the manipulation routing table entries if the agent
runs with root permissions (note AGAIN the danger of doing this!).
There are comprehensive manual pages for all these programs. You are also
advised to look at the GDMO description of the the MIBs in the doc/ directory.

One of the most important aspects of OSI management model is its support
for event-directed management, in contrast to the Internet (SNMP) model which
is based on polling. The OIM MIB, being a direct translation of the
equivalent SNMP one, does support only very few event reports (cold/warmStart,
linkUp/Down) which, though supported in OSIMIS, are unlikely to be experienced.

The UNIX MIB supports events related to a threshold and tide-mark associated
to the number of users attribute. You may manipulate the threshold and
tide-mark values using the cmisbrowser or the mset program and use the
evsink and/or evlog programs to receive and/or log the event reports.
You may experiment by logging in and out of a specific UNIX system where
the SMA runs in order to alter the number of users and generate these reports.

If you operate the Transport Protocol MIB, you may generate transport
activity using the managed mimisc client from or towards a system
where the SMA is running. You are reminded that the ISODE transport daemon
should be running at the target system in order to fork the mimiscd
server. This will generate one or two transport connection endpoint
managed objects in the SMA, depending on if the association from mimisc
to mimiscd is on different or the same end-system. You may then generate
traffic by using the `chargen' or other mimisc commands (see manual page)
in order to see counter thresholds being exceeded and event reports being
generated. Actually, the ISODE isode-test program exists in the misode/
directory renamed as misode-test. This can be used as `misode-test <hostname>'
and will invoke mimisc several times, performing various operations.
You may check this activity with the cmisbrowser, mibdump and
evsink/svlog programs.

If you want to manage (or should better say monitor) other ISODE OSI
applications, you should just link them with the libmisode.a library.

(*) For reading manual pages you may use "man -M <path> <progname>";
    the path for the directory containing the manual pages is needed
    by the man program as it will not be the standard /usr/man e.g.
    "man -M /<dir>/.../osimis/man mibdump" or
    "man -M /usr/local/man cmisbrowser"




COMMENTS, PROBLEMS AND BUG REPORTS

Any problems, comments and bug reports should be sent to <osimis@cs.ucl.ac.uk>.

Specific problems/comments should be targeted to the following persons:

CMIP, GMS, TP MIB    - George Pavlou,    <g.pavlou@cs.ucl.ac.uk>
OIM-SMA, Log Control - Saleem N. Bhatti, <s.bhatti@cs.ucl.ac.uk>
CMIS Browser, RMIB   - James Cowan,      <j.cowan@cs.ucl.ac.uk>
UNIX MIB             - Graham Knight,    <g.knight@cs.ucl.ac.uk>


For general information or other:

- George Pavlou, <g.pavlou@cs.ucl.ac.uk>
- Graham Knight, <g.knight@cs.ucl.ac.uk>




GLOSSARY

Though the full terms for most acronyms have been introduced in the text,
a short glossary is given below.

OSI		Open Systems Interconnection
OSIMIS		OSI Management Information Service
ISODE		ISO Development Environment
CMIS		Common Management Information Service
CMIP		Common Management Information Protocol
SNMP		Simple Network Management Protocol
GMS		Generic Managed System
MO		Managed Object
GDMO		Guidelines for the Defintion of Managed Objects
MIB		Management Information Base
RMIB		Remote MIB
SMIB		Shadow MIB
OIM		OSI Internet MIB
SMA		System Management Agent
pepsy 		Presentation Element Parser and Structure-generator Yacc-based
QUIPU		it is not an acronym, Quipus were encoding devices used
		by the Incas of Peru - remember that the QUIPU implementation
		of X.500 was developed as a part of the INCA project
OSF DME		Open Software Foundation Distributed Management Environment
XOM		X/Open OSI-Abstract-Data Manipulation
XMP		X/Open Management Protocols
