

		Internet QA (OSI<->SnmpV1) Beta Release 1
		==========================================

1) Introduction
===============

	This document outlines the information needed to configure
and execute the OSIMIS Cmip to SnmpV1 generic gateway as developed
by the UCL and DNAC RACE ICM partners. The gateway is generic in 
the sense that the description of the MIBs that are to be proxied 
for are read in at start up.

	This implementation has borrowed heavily from the Network Management
Forum's Internet Management Coexistence work [IIMCIMIBTRANS,IIMCPROXY,
IIMCSEC]. The developers would like to take this opportunity to thank 
the NMF for their stirling efforts in this regard.

	The IQA executible itself is but one component in the OSIMIS
Q-Adaptor package, that has been developed under the auspices
of the RACE ICM project. Jim Reilly of VTT Finland has very successfully 
implemented the NMF's Internet SMI to GDMO translation specifications 
[IIMCIMIBTRANS] to produce his "imibtool". James Cowan provided the innovative 
platform independent GDMO compiler [GDMO] which is used to convert GDMO into
a corresponding SNMP Simple Input Format (SIF) MIB descriptions for input 
into the IQA.

		V Internet MIB (Systems Management Information)
		V
	     imibtool (with some post-processing)
		V
		V GDMO
		V
	      gdmo (the GDMO compiler, used with the iimcgdmo.gen script)
		V
		V SNMP Simple Input Format file 
		V
	       iqa

1.1) Beta release 1 notes
=========================

	The following aspects are NOT fulfilled by this beta release
since they can not be currently achieved under OSIMIS :-

	a) the "retransmissionPackage" [IIMCPROXY] is not represented as
	   a conditional package, instead the constituent attributes are
	   appended to the "cmipsnmpProxyAgent" and "cmipsnmpProxy" managed
	   object classes.

	b) currently OSIMIS only permits associations with the whole
	   proxy MIB tree. It is hoped that associations that permit
	   views of just the sub-tree specific to a remote agent
	   will be possible.

	c) "noSuchAttribute" GetList errors can not be returned (see 
	   section 3.1.)

	d) new enterprise specific traps must be listed in Pma.h and
	   oidtable.at.

	e) the "SnmpGenericRDN" syntax (see section 3.2) does not 
	   individually tag each SEQUENCE component, as required by
	   IIMC recommendations (which is unnecessary anyway !) 


	This release has an etc directory specific to the IQA.
The environment variable "OSIMISETCPATH" should point to this directory
when using the proxy.

	The full directory layout is as follows :-

				   osimis
				     |
			           proxy
				     |
			 	    iqa [this file]
				     |
    +------------------+-------------+-----------+----------------+
    |		       |	     |		 |		  |
imibtool	      snmp	   proxy	pma		 etc
[VTT's SMI to	  [modified	 [snmp agent,  [main]	      [oidtables]
 GDMO translator   Snmp library]  image MO,			  |
 tree]	                   	  class info,		   +------+-------+
 	 			  syntaxes]		   |		  |
 							gdmodir         iqadir
						     [iimcgdmo.gen]   [IQA config files,
						      		       sample RFC1213
								       input file]

	Real-world SNMPv1 agent implementations tend to have personalities
of their own - which is a polite way of saying that they are non-conformant !
Certain allowances have been built into IQA for this - but no doubt others
will need to be incorporated as it is tried with other SNMP agent implementations.


2) IQA Configuration
====================

2.1) "$OSIMISETCPATH/iqadir/iqastartupagents.icm"
=================================================

|"athena",   {snmpUDPDomain:0x80:10:08:0b:00:a1}, snmpV1, {IIMCrfc1213}, 3, 2000, "public", 0
|
|"glenlivet",{snmpUDPDomain:0x80:10:08:1b:00:a1}, snmpV1, {IIMCrfc1213}, 3, 2000, "public", 0
|
|"poteen",   {snmpUDPDomain:0x80:10:08:4e:00:a1}, snmpV1, {IIMCrfc1213}, 3, 2000, "public", 0

	The eight mandatory configuration parameters that are required to enable
the IQA to proxy for a remote SNMP agent are as follows :-

	i)   the remote agent's systemId - a character string.
	ii)  one or more transport domain/transport address pairs.
	iii) the remote management protocol - this must be snmpV1.
	iv)  one of more MIB OIDs for MIBs that are remotely supported.
	     Multiple MIB OIDs must be seperated by whitespace.
	v)   the maximum number of retransmissions upon a timeout of
	     a remote request.
	vi)  the retransmission timeout in milliseconds (though with
	     a granularity in seconds.)
	vii) the required community string for the remote agent.
	viii)a "magic number" - currently a value of "1" permits the IQA
	     to attempt to recover from failed communications with 
	     agents that do not return "TooBig" SNMP request responses.

	Optional trap ",<port>, <trap community string>" pair(s) may also be
appended:-
	
|"synapse",	{snmpUDPDomain:0x80:10:08:aa:00:a1}, snmpV1, {IIMCrfc1213}, 3, 2000, "public", \
0, 3163, "traps", 3163, "trapx"
	
	Please ensure that you have the necessary UNIX permissions before specifying
reserved ports for your incoming traps.

	The '\' line continuation character can be used to break overly long lines.

	The precise file name that the IQA reads in, "iqastartupagents.icm"
in this case, is determined by the "IQA_START_UP_AGENTS_FILE" symbol within
"osimis/proxy/iqa/proxy/cmipsnmpProxy.inc.hcl".


2.2) "$OSIMISETCPATH/iqadir/iqamibconfig.icm"
=============================================

|UseGenericRDNs	:	FALSE
|
|# File name	:	MIB name as defined in oidtable.gen
|
|rfc1213.sif	:	iimcRFC1213
|rfc1354.sif	:	iimcRFC1354

	The "UseGenericRDNs" switch indicates whether the proxied
image managed objects shall utilise the "SnmpGenericRDN" (when set to TRUE) 
or the "GraphicString" ("dot format") RDN syntaxes. During its start up
sequence the IQA will check that the setting of this switch is correct
with respect to the naming attribute syntaxes as listed in the MIB simple 
input file(s) and the "oidtable.at" file.

	A list of file name and OID pairs for each of the MIBs that the IQA 
is to proxy for must be provided. For example "rfc1213.sif" is a file containing
the simple input format representation for the RFC1213 objects. The MIB
requires an OID, "iimcRFC1213", which must be listed in "oidtable.gen".

	The precise file name that the IQA reads in, "iqamibconfig.icm"
in this case, is determined by the "IQA_INPUT_FILE" symbol within 
"osimis/proxy/iqa/pma/Pma.h".


2.3) The simple input files e.g. "rfc1213.sif"
==============================================

	If you have not done so already compile the "imibtool" 
with the "-DGENERIC_QAF_OUTPUT=1" flag.
	
	Next use "imibtool" to convert the required MIB's SMI into an 
equivalent GDMO specification. Some post-processing of this GDMO is
required, such as insertion of the delete attribute and value PARSE statements
together with insertion of the "CREATE" and "DELETE" name binding requirements,
(which is normally achieved via a "sed" script.) This release also requires the
removal of the reference to the "internetAlarm" notification, since this is
automatically supported by the IQA.

	It is important to remember that being generic the proxy requires
that only the SNMP syntaxes listed in section 3.1 appear in the GDMO.
In addition an "internetSystem" System class must be listed, though if 
a given remote agent proxies for two or more MIBs then the class needs
to be listed in only one of the MIBs.

	The post-processed GDMO can then be translated by the
IIMC GDMO Compiler script, for example :-

	gdmo -x iimcgdmo.gen vtt.mibii.gdmo

	Finally rename the "gdmo.log" SIF output e.g. to rfc1213.sif.



	Consider the following section from an RFC1213 MIB :-

internetSystem
ATTRS=8
internetSystemId	SnmpGenericRDN	0	1
sysDescr	SnmpDisplayString	0	1
sysObjectID	SnmpOID	0	1
sysUpTime	SnmpTimeTicks	0	1
sysContact	SnmpDisplayString	0	3
sysName	SnmpDisplayString	0	3
sysLocation	SnmpDisplayString	0	3
sysServices	SnmpInteger	0	1
NB=1
internetSystem-remoteSystemNB	remoteSystem	internetSystemId	0	0

ip
ATTRS=21
ipId	SnmpGenericRDN	0	1
ipForwarding	SnmpInteger	0	3
ipDefaultTTL	SnmpInteger	0	3
ipInReceives	SnmpCounter	0	1
ipInHdrErrors	SnmpCounter	0	1
ipInAddrErrors	SnmpCounter	0	1
ipForwDatagrams	SnmpCounter	0	1
ipInUnknownProtos	SnmpCounter	0	1
ipInDiscards	SnmpCounter	0	1
ipInDelivers	SnmpCounter	0	1
ipOutRequests	SnmpCounter	0	1
ipOutDiscards	SnmpCounter	0	1
ipOutNoRoutes	SnmpCounter	0	1
ipReasmTimeout	SnmpInteger	0	1
ipReasmReqds	SnmpCounter	0	1
ipReasmOKs	SnmpCounter	0	1
ipReasmFails	SnmpCounter	0	1
ipFragOKs	SnmpCounter	0	1
ipFragFails	SnmpCounter	0	1
ipFragCreates	SnmpCounter	0	1
ipRoutingDiscards	SnmpCounter	0	1
NB=1
ip-remoteSystemNB	remoteSystem	ipId	0	0

ipRouteEntry
ATTRS=14
ipRouteEntryId	SnmpGenericRDN	0	1
ipRouteDest	SnmpIpAddress	0	1
ipRouteIfIndex	SnmpInteger	0	3
ipRouteMetric1	SnmpInteger	0	3
ipRouteMetric2	SnmpInteger	0	3
ipRouteMetric3	SnmpInteger	0	3
ipRouteMetric4	SnmpInteger	0	3
ipRouteNextHop	SnmpIpAddress	0	3
ipRouteType	SnmpInteger	0	3
ipRouteProto	SnmpInteger	0	1
ipRouteAge	SnmpInteger	0	3
ipRouteMask	SnmpIpAddress	0	3
ipRouteMetric5	SnmpInteger	0	3
ipRouteInfo	SnmpOID	0	1
NB=1
ipRouteEntry-ipNB	ip	ipRouteEntryId	6	4
INDEX=1
ipRouteDest
ipRouteType
 2 

	The aspects that will are not immediately clear from the
above are as follows:-

	a) The two digits appearing on the end of each attribute line
	   indicate the "MatchesFor" and "GetReplace" bit details.
	   It should be noted that the IQA ignores the "MatchesFor"
	   values as the respective syntaxes define the matching rules.

	   Get=1, Replace=2, GetReplace=3
	   
	b) The two digits on the end of each name binding indicate
	   the "Create" and "Delete" bit specifications.

	   Create = 1, CreateWithReference = 2, CreateWithAutoInstanceNaming = 4
	   Delete = 1, DeleteIfNoContained = 2, DeleteContainedObjects = 4

	c) For those table entries with a delete attribute and value
	   specification the data appears immediately after the
	   specification for the "INDEX" attributes. For example
	   the "ipRouteEntry" class has a delete attribute "ipRouteType"
	   and a delete value of "2".



3)	IQA Syntaxes
====================

3.1) IQA SNMPv1 syntaxes
========================

	The IQA can be used to proxy for SNMP objects with the following
syntaxes, which are aliases for the respective RFC1155 "SimpleSyntax"
and "ApplicationSyntax" syntaxes :-

	SnmpInteger, SnmpOID, SnmpOctetString, SnmpDisplayString,
	SnmpPhysAddress, SnmpNULL, SnmpIpAddress, SnmpCounter, SnmpGauge and
	SnmpTimeTicks.

	If the remote SNMP agent does not support a given object instance 
then the following default values will be returned...

	SnmpInteger				: -1
	SnmpOID					: 0.0
	SnmpOctetString, SnmpDisplayString	: ""
	SnmpPhysAddress				: ""
	SnmpCounter, SnmpGauge, SnmpTimeTicks	: 0
	SnmpIpAddress				: 0.0.0.0
	

3.2) RDN Syntaxes
=================

	The IQA supports two forms of RDNs, the "dot format" "GraphicString"
and the "SnmpGenericRDN". When utilising generic RDNs the "SnmpGenericRDN" 
syntax supports INTEGER, Octet String, OBJECT IDENTIFIER and IPADDRESS indices. 
File "osimis/proxy/iqa/proxy/PrxSV1Sntx.py" contains the ASN.1 specifications.

	Let us consider an example, should a manager require an RDN to
have the syntax "IpNetToMediaEntryIdValue" then the proxy agent would
handle this as an instance of the "SnmpGenericRDN" by utilising the
INDEX information within the simple input files, so that the correct
response BER can be produced for :-

	IpNetToMediaEntryIdValue ::= SEQUENCE {
					ipNetToMediaIfIndex    SnmpInteger,
					ipNetToMediaNetAddress SnmpIpAddress
					}

Note: the "SnmpGenericRDN" syntax does not currently insert the additional
tags that are specified within [IIMCIMIBTRANS], e,g "ipNetToMediaIfIndex [1] Integer".

	Should a manager application e.g. the "cmisbrowser" utilise the
SnmpGenericRDN syntaxes itself then an example of the print output would be:-

	SnmpInteger=1 <TAB> SnmpIpAddress=1.2.3.4

You may find that the browser's Interviews gui may not handle the tab seperator
properly, but this will not affect processing.

	When inputing SnmpGenericRDN instances e.g. to mibdump, please
enclose the instance DN in single quotes if multiple indices are present,
as they must be seperated by whitespace e.g.

-i 'systemId=synapse@systemId=kinou@ipId=NULL@
		IpNetToMediaEntryId=SnmpInteger=1 SnmpIpAddress=128.16.1.2'
	

3.3) Access Control Syntax
==========================

	The SNMPv1 community string may be transferred over the CMIS interface
within the "AccessControlCertficate" as specified within [IIMCSEC] during
"cmipsnmpProxyAgent" (see section 4) [IIMCPROXY] creation.

Note: 1) the "iqa/proxy/libiqasyntaxes.a" routine "External* buildAccessControl(char*)",
     	 may be used to generate the required Cmis Create parameter.
	 This call has been added to the "mcreate" manager and is accessed
	 via the "-C <commstring>" option.

Note: 2) When a "cmipsnmpProxyAgent" object is created over the Cmis interface
         the remote SNMP agent's community string is read from the Cmis Create's 
         access control field. If it is not present then the "snmpSecurityParameter"
	 object is accessed, else a default "public" is used.


4)	IQA Containment hierarchy and start up operation
========================================================

		       			  system
			proxySystem			remoteSystem xN

		       cmipsnmpProxy			SnmpImageMO representations
							of remote MIBs
	snmpSecurityParameter  cmipsnmpProxyAgent xN


	Upon start up the "system", "proxySystem", "snmpSecurityParameter"
and "cmipsnmpProxy" objects are instantiated. The creation of the "cmipsnmpProxy"
object causes the file pointed to by the "IQA_START_UP_AGENTS_FILE" to be parsed
in order that it may determine the specifications for the remote agents to be 
proxied for. For each remote agent an instance of the "cmipsnmpProxyAgent"
object is created, which in turn creates a "remoteSystem" object. Now the
"remoteSystem" polls the "internetSystem" class at the SNMPv1 agent. If the poll
fails then the related "remoteSystem" and "cmipsnmpProxyAgent" objects
are removed. However if the poll succeeds an "internetSystem" "SnmpImageMO" 
instance is created below the "remoteSystem" object.

	During normal execution further "SnmpImageMO" instances are created
as per the containment hierarchy of the respectice SNMP MIBs that are being proxied
for, when they appear in the scope of a CMIS request.

	In code terms the initialisation phase comes down to:-

i)   The "cmipsnmpProxy" object calls cmipsnmpProxyAgent::cmipsnmpStartUpProxyAgent(...)
     for each SNMPv1 remote agent.

ii)  These in turn call cmipsnmpProxyAgent::cmipsnmpStartUpRemoteAgent(...)
     which create an "SnmpRMIBAgent" object that acts as the SNMPv1 protocol
     interface with the remote agent. In addition a "remoteSystem" object
     is instantiated.

iii) The "remoteSystem" objects contructor calls remoteSystem::refreshSubordinate(...),
     which in turn calls SnmpImageAccess::refreshImageSubordinate() in order
     to poll the remote SNMPv1 agent, so as to determine its reachibility.

iv)  A successful poll causes the constructor for "SnmpImageMO" to be called
     in order to create an "internetSystem" instance immediately below the
     "remoteSystem" object.
  

5)	IQA execution
=====================

	iqa<return>

	The executible will then read in the $OSIMISETCPATH oidtables,
the "$OSIMISETCPATH/iqadir/iqastartupagents.icm" MIB configuration files and 
will prepare to proxy for the specified "$OSIMISETCPATH/iqadir/iqamibconfig.icm"
remote SnmpV1 agents.


6) 	Sample usage
====================

	Unfortunately due to the lack of access rights
we have not been able to test those commands that utilise 
SNMP Sets beyond checking that they emit the correct OID/PE
pairs.

6.1)	Causing the IQA to proxy for additional SNMPv1 agents
-------------------------------------------------------------

mcreate IQA kinou -c cmipsnmpProxyAgent 
	-i 'systemId=kinou@systemId=NULL@cmipsnmpProxyId=NULL@
					cmipsnmpProxyAgentId=glenlivet' 
	-a 'transportAddresses={snmpUDPDomain:0x80:10:08:1b:00:a1}' 
	-a managementProtocol=snmpV1 
	-a 'supportedMIBs={IIMCrfc1213 IIMCrfc1354}' 
	-a accessControlMechanism=agent 
	-a administrativeState=unlocked 
	-a snmpMsgRetryLimit=4 
	-a snmpMsgTimeout=5000 
	-C public

6.2) 	Table entry creation 
----------------------------

mcreate IQA kinou -c tcpConnEntry 
	-i 'systemId=kinou@systemId=synapse@tcpId=NULL@tcpConnEntryId=SnmpIpAddress=127.2.3.4 SnmpInteger=500 SnmpIpAddress=128.2.3.6 SnmpInteger=600'
	-a 'tcpConnLocalAddress=127.2.3.4' 
	-a tcpConnLocalPort=500 
	-a 'tcpConnRemAddress=128.2.3.6' 
	-a tcpConnRemPort=600 
	-a tcpConnState=1


6. )	Setting an SNMPv1 object
--------------------------------

mset IQA kinou -c internetSystem 
	-i 'systemId=kinou@systemId=synapse@internetSystemId=NULL' 
	-w 'sysContact=John Smith'


6. ) 	Deleting a table entry using a Generic RDN
--------------------------------------------------

mdelete IQA kinou -c ipRouteEntry 
	-i 'systemId=kinou@systemId=synapse@ipId=NULL@
			ipRouteEntryId=SnmpIpAddress=224.0.0.0'


7) 	References
==================
IIMCIMIBTRANS	Translation of Internet MIBs to ISO/CCITT GDMO MIBs, NMF026
IIMCSEC		ISO/CCITT to internet Management Security, NMF027
IIMCPROXY	ISO/CCITT to Internet Management Proxy, NMF028
GDMO		OSIMIS GDMO Compiler User Manual, UCL, August 5th 1993
