

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 may 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 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
   (software 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. a generic SNMPv1 proxy agent ("Internet Q-Adaptor") based on the NMF
   026, 027, 028 documents; this is pre-configured to proxy for the Internet
   MIB-II as in the RFC 1213 by providing an OSI view of the same resources
   as in the NMF 029 document ("loosely-coupled resources with
   fetch-on-request access method and asynchronous reports i.e. SNMP traps").



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.



GENERIC INFRASTRUCTURE

The basic common infrastructure comprises a CMIS/P implementation
together with infrastructure for writing applications using a fully
event-driven approach and hiding ASN.1 manipulation.
The latter is supported by an object-oriented ASN.1 compiler that
produces C++ objects corresponding to arbitrary ASN.1 syntaxes.

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 used to produce C++ stub managed objects, leaving only behavioural
aspects to be hand-coded.  The GMS also provides support for the systems
management functions: event reporting and logging, object/state management,
metric monitoring and enhanced monitoring support (non-standard research
extensions) are provided at present.

Regarding generic manager infrastructure, an object-oriented view
of remote systems (agents) is offered through the "Remote MIB (RMIB)".
This assembles linked replies, hides ASN.1 manipulation. provides a
high level interface to event reporting and in general offers
high level CMIS services in a much much friendlier way than XOM/XMP.
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).
Despite the presence of LPP support, we do NOT encourage its use as
the resulting savings are not great while at the same time interoperability
with full OSI environments is lost.


(*) 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, OpenView and IBM NetView CMIP successfully. At the GMS
level, OSIMIS has interoperated with HP OpenView, IBM NetView,
Ericsson TMOS and Bull ISM. We cannot provide any details on the
interoperability tests but we would be very interested to know of any
problems with those or other platforms.



USE OF ISODE

OSIMIS uses the following ISODE interfaces/support:

The ASN.1 base pepsy compiler. This is encapsulated by the OSIMIS
object-oriented ASN.1 compiler and generic support infrastructure
to offer services broadly equivalent to those of the X/Open XOM interface (*).

The Association Control / Remote Operation Service API which are used
to implement CMIP. The OSIMIS CMIS API is known as MSAP and is broadly
equivalent to the X/Open XMP interface (*).

OSIMIS applications may also use the X.500 OSI Directory Service
implementation coming with ISODE (QUIPU) for application addressing
and location transparency services. In the default case, local tables
are used to provide the Application Process (SMAP) to presentation
address mapping, using the name of the machine where the SMAP runs
as the service qualifier e.g. SMA-athena (designator-qualifier pair).

(*)  Please note the term "broadly equivalent" regarding the resemblance
     of the OSIMIS ASN.1 and 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 version 8.0.

Some parts of the system such as the CMIP library and the logic
associated with ASN.1 syntaxes are written in (non-ANSI) C with the rest of
the system written in C++, mainly to exploit the object oriented nature
of the OSI Management model.

The C++ compilers supported are GNU 2.7.2 on SunOS, GNU 2.6.3 on Linux,
GNU 2.7.2 / Sun C++ 4.1 on Solaris and GNU 2.5.4 on HP-UX.
Later GNU versions may work on HP-UX but we have not tried any.
Backwards compatibility to GNU 2.5.8 on Solaris/SunOS is guaranteed
but previous versions may not work.

The Tcl/Tk versions supported are Tcl 7.4 and Tk 4.0.

The object-oriented ASN.1 compiler requires GNU gawk. This component
is essential, so you will need to get it.
The MIB browser uses InterViews-2.6 which is an old version and will
not compile with GNU 2.5.8 or later versions. In fact, we provide 
a ready-built browser for Sun SPARC architecture with SunOS 4.1.3.
A future version of OSIMIS will contain a TCL/TK-based browser instead
of the InterViews-based one.

No other object libraries have been used in order to minimise tool
dependencies. Note that GNU compilers 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, HP, IBM, DEC, Intel 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 on
the following platforms:

Solaris 2.x
SunOS 4.1.3
Linux 1.2.x
HP-UX 9.x.

It may also work with some changes on AIX - previous versions have worked
on AIX but we do not use AIX locally so we cannot test compatibility.

If you intend to build OSIMIS for HP-UX/AIX, you will have to modify
CONFIG.make as HP-UX/AIX Makefiles do not support the += construct.
You will need one only CCONFIG line with all the chosen options.

We have also found that the HP-UX gcc/g++ v. 2.5.4 linker does not
accept the -s (strip) flag, you may leave LDFLAGS in CONFIG.make empty.




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/
    |       |
    |       progs/
    |
    |-- compilers/
    |       |
    |       |-- asncompiler/
    |       |
    |       |-- mocompiler/
    |               |
    |               |-- flex/
    |               |
    |               |-- byacc/
    |               |
    |               |-- gdmo/
    |
    |-- lt/
    |
    |-- kernel/
    |       |
    |       |-- example/
    |
    |-- msap/
    |
    |-- msap-xmp/
    |
    |-- agent/
    |       |
    |       |-- smi/
    |       |
    |       |-- gms/
    |       |
    |       |-- monmet_mib/
    |       |
    |       |-- monsup_mib/
    |       |
    |       |-- isode_mib/
    |       |
    |       |-- ux_mib/
    |       |
    |       |-- sma/
    |  
    |-- manager/
    |       |
    |       |-- rmib/
    |       |
    |       |-- tcl-cmis/
    |       |
    |       |-- general/
    |       |
    |       |-- general2/
    |       |
    |       |-- browser/
    |
    |-- mibutil
    |
    |-- examples/
    |       |
    |       |-- odp/
    |
    |-- simtime
    |       |
    |       |-- library/
    |       |
    |       |-- example/
    |
    |-- proxy
    |       |
    |       |-- iqa
    |             |
    |             |-- etc
    |             |
    |             |-- imibtool
    |             |
    |             |-- snmp
    |             |
    |             |-- proxy
    |             |
    |             |-- pma
                  
                  


`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/progs' - a utility program for looking at dbm files

`compilers' - the object-oriented ASN.1 compiler in compilers/asncompiler
	      the GDMO compiler in compilers/mocompiler

`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 offering
         the OSIMIS CMIS API known as MSAP


`msap-xmp' - full CMIP version 2 implementation offering
             the X/Open XOM/XMP API; this will work at present only
             over the Sun XOM/XMP stack version 8.1


`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/monsup_mib' - the monitoring support research SMF MIB


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


`agent/ux_mib' - the example UNIX MIB


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


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


`manager/tcl-cmis' - the TCL-based manager-role CMIS API


`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



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 the IC-R1.0 release , you should go in the directory
osimis/include/ and change the ISODE header file tree:

rm isode; ln -s isode-icr1 isode

Now go into the isode directory (cd isode), remove the file config.h
and make a symbolic link to the same file with the extension that
denotes the operating system in use e.g.

ln -s config.h.sunos config.h

If you have an operating system that is not mentioned there, you should
copy the config.h file you used to build ISODE and add to it the line:

#define MGMT


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

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
    SIMTIME  - the simulated time support service
    LT       - the X.500-based location transparency service
    MONMET   - the monitor metric objects
    MONSUP   - the monitoring support objects
    IQA      - the Internet Q-Adaptor (CMIS/P->SNMPv1 proxy)
    XMP      - the XOM/XMP CMIS/P stack
    TCLRMIB  - the TCL-based generic manager support service
    TPMIB    - the Transport Protocol MIB for ISODE
    ODPOBJ   - the example ODP objects


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.


We do not encourage the use of the following options:

BROWSER		You need InterViews-2.6 and GNU C++ 2.2.x (ancient);
		UCL supplies a SunOS binary while a new version based
		on TCL/TK will appear in the future
LT		You need to know how ro set up the ISODE QUIPU X.500
		implementation in order to use it; not encouraged
		unless you know what you are doing
XMP		You need Sun XOM/XMP stack version 8.1 instead of ISODE

Bear also in mind that TCLRMIB is very useful as it allows to write
interpreted managers with GUIs in TCL/TK. You will need though TCL/TK
in order to build it. At present, no OSIMIS applications in this release
use it, the next version of the BROWSER will be based on it.



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:

HOME	=	the absolute path of the $(TOP) directory which contains the 
		CONFIG.make file
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.
		-lsocket -lnsl -lelf /usr/ucblib/libucb.a
		for Solaris without using POSIX signals or
		-lsocket -lnsl -lelf
		for Solaris using POSIX signals (this is advised, see later)

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++);
		note that -DSUNCC4 in the CCONFIG list for Sun ATT C++ v 4.x
		is no more necessary

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; you will not need this
		unless you try to build the browser

X11	=	the X Windows library directory
		should be empty for plain X and -L/usr/openwin/lib
		for Sun OpenWindows; you will not need this either
		unless you try to build the browser

TCLTK	=	the TCL/TK library directory; note you will need to set this
		only if you have chosen the TCLRMIB option

IVIEWSINC=	the local system directory that contains
		the InterViews header files; you will not need this
		unless you try to build the browser
                
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; you will not need this
		unless you intend to compile the kernel/XCoord.cc file
		in order to build Motif-based GUIs

TCLINC	=	the local system directory that contains the TCL header files

TKINC	=	the local system directory that contains the TK header files;
		you will need the last two only if you have selected TCLRMIB

		PLEASE NOTE:

		None of the four 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)

LDFLAGS	=	make sure this is set to -s to get small size stripped programs;
		it does not work though on HP-UX, so leave it empty

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


* NOTE ALSO that the gawk program should be in your path when compiling
* OSIMIS as there is no way at present to configure this through CONFIG.make .


If you use OSIMIS with the IC-R1.0, you should add the -DICR1
directive to the CCONFIG list to force the necessary conditional compilation.
If you have the IC-R1.1 release, you should also add the -DICR1_1
directive to the CCONFIG list i.e. you will need both.

If you use OSIMIS on Solaris, HP-UX or AIX, you will need also to add
-DSOLARIS, -D__HPUX__ or -DAIXV3 respectively (no special symbol is needed
for SunOS and Linux). On Solaris 2.4 you will *also* need -DSOLARIS24
(no special symbol is necessary for Solaris 2.5 and later).

Also, if you are using OSIMIS on a Linux stand-alone PC (i.e. non-networked),
you should add -DLOCALHOST to the CCONFIG list to be able to work over
the local loopback interface.


Special note on POSIX signals on Solaris
----------------------------------------

You are advised to use POSIX signals on Solaris and avoid the UCB
compatibility library (/usr/ucblib/libucb.a) in LSOCKET.
In order to do this, you should add the -DPOSIX_SIGNALS symbol in CCONFIG.

Note also that in order to use POSIX signals, you should build ISODE
*without* the UCB extensions. This means you should make sure the
symbol SVR4_UCB is *not* defined in h/config.h.



BUILDING MISODE

In general, you will NOT want to build this. If so, skip to the next section.

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.
Go into the directory misode/ and type "make all".
You will receive innocuous warnings, you may consult the
make-log/make-misode.log file which contains the log in our local system.


BUILDING THE OPTIONAL TCL-MCMIS AND XOM/XMP

These are recent additions and their compilation is not yet controlled
from the top-level Makefile. The Tcl-MCMIS manager infarstructure is
in manager/tcl-cmis directory and XOM/XMP in msap-xmp. Before you build
the former you will need to set the TCL-related variables in CONFIG.make.
For XOM/XMP, read carefully the README file and update CONFIG.make.
Bear in mind that the XOM/XMP addition is only experimental at present.

In order to build and install these, you will have to go in the two
directories and build/install them in the same manner as the rest of OSIMIS.


BUILDING OSIMIS

Before you start the building procedure, you will need to set the
environment variable OSIMISETCPATH to point to the directory $(TOP)/etc.
For example, if you use the csh you should type
setenv OSIMISETCPATH /<dir>/<dir>/.../osimis/etc

Building the whole system

Go in the top osimis/ directory and type "make all".

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 generic".


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 ALREADY-BUILT OSIMIS

When OSIMIS is already pre-built, you may only install the
binaries, header files, configuration information (etc) and manual pages.

Edit CONFIG.make to set the ETC, OSIMIS-INC, H, LIB, BIN and MAN paths
to the places you want things installed. Also set the PEPSY path. Then type:

make install-bin




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 ODPTEST.

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 osimistailor 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.

gmsGlobalNameDomain:	c=GB@o=UCL@ou=CS

This is the global name domain that will be used as a prefix for
managed object names in applications in your domain. It is the
X.500 Directory portion of the global name that applies to your
environment. The actual global name is formed by concatenating to
this the following relative names:

cn=XYZ		where XYZ is the application process e.g. SMA, ODPTEST, etc.
systemId=<host>	where <host> is the host name where the application runs

An example of a global name for a managed object is:

c=GB@o=UCL@ou=CS@cn=SMA@systemId=athena@uxObjId=test

Note that c is a shorthand for country, o for organization, ou for
organisational unit and cn for common name. Note also that not all
applications in agent roles should have as top MIT object one of class
system; the latter applies only to element and system management.
Currently OSIMIS supports only this as the top MIT object. The reason is
that there are no name bindings for generic SMF classes
(discriminator, log, scanner etc.) to classes like network, service,
application etc. The obvious trick is to cheat and use those under
system. This is not strictly correct, but there are no standard models
for anything but element management at present.


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 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

You may start the SMA agent either automatically or through
the /etc/rc.local file when the host boots.
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. There are comprehensive manual pages for all these programs.

One of the most important aspects of OSI management model is its support
for event-directed management.
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 comments and bug reports should be sent to <osimis@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
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
XOM		X/Open OSI-Abstract-Data Manipulation
XMP		X/Open Management Protocols
