Translation of SMI to IDL

Introduction

SNMP/CORBA Interoperability Scenarios describes possible scenarios using CORBA-based SNMP managers and agents. The specification of the SNMP Gateway is addressed in the associated JIDM Interaction Translation specification.

The SNMP MIB definition language is built on ASN.1 and this section re-uses the translation given in Translation of ASN.1 to IDL.

This chapter describes CORBA/TMN interworking for SNMP, gives an outline description of the basic scheme for translating SMIv2 to CORBA-IDL, and defines the mapping of SNMP information modules into CORBA-IDL. Mapping of SMIv2 Macros to IDL describes the mapping of SNMP SMI macros to CORBA-IDL.

The previous version of this specification (JIDM Specification Translation, Preliminary Specification P509) addressed the issues related to the mapping of ASN.1 types and SMI macros to IDL types and interfaces. The mapping rules of specification translation are based on the SMI specifications in SNMP and applicable to MIB information modules specified for SNMPv1, SNMPv2 (all the versions) and SNMPv3. This mapping has been completely revised, and so the definitions given in this document supersede those defined in the previous (P509) publication.

CORBA/TMN interworking for SNMP

• JIDM specification translation

• JIDM interaction translation

The specification translation (this JIDM_ST document) addresses the issues related to the mapping of ASN.1 types and SMI macros to IDL types and interfaces. The ST mapping rules are based on the SMI specifications in SNMP and applicable to MIB information modules specified for SNMPv1, SNMPv2 (all the versions) and SNMPv3.

The interaction translation (associated JIDM_IT document) address the mapping of names, messages and events in the SNMP domain to names, operation invocation, and events, in th CORBA domain and vice-versa.

The JIDM interaction translation specification consists of two parts:

• JIDM facilities, that describe a generic manager-agent framework

• SNMP management faclities that describe the SNMP-specific extension CORBA object services to support the goals of the interaction translation.

SNMP MIB to IDL in CORBA Domain describes the usage of the SNMP SMI based MIB specification and the IDL files (obtained from MIB using ST) in the CORBA domain, in contrast to the usage of MIB in the non-CORBA domain. In CORBA domains, SMI based MIB information modules are converted to IDL based on the ST mapping. The generated IDL interfaces are used to implement server-side MIB objects (table entries/groups) at the network devices, as part of agent-side instrumentation. The same IDL interfaces are also used to generate language specific stubs to write manager-side applications that would interact with the server side MIB implementation.

The main difference between implementing SNMP MIBs or writing management applications in a CORBA domain with a non-CORBA domain is in how the language-dependent APIs are generated from the MIB information modules. In a non-CORBA domain, the MIB specification is mapped directly to specific languages using either proprietary or standard methods. In the JIDM_ST approach (as described in this document), the MIB is first mapped to CORBA-IDL and then the language specific APIs (stubs/skeletons) are obtained using IDL->[C/C++/Java/SmallTalk] mapping rules defined in the CORBA 2.1 specification (see referencved documents). The specification translation approach supports both static and dynamic binding in a CORBA compliant way. Since the specification translation maps MIB to IDL, one can take advantage of the Dynamic Invocation Interface (DII) on the client side to write applications, and the Dynamic Skeleton Interface (DSI) on the server side to implement a SNMP MIB or an extension of the MIB.

Programming with DII and DSI does not need stubs/skeletons generated from the IDL and thus reduces the code size significantly. JIDM_ST supports both strongly typed programming using stubs/skeletons as well as untyped programming using DII/DSI interfaces. In addition, the JIDM_ST approach maps the MIB to IDL in such a way that generated interfaces are compatible with requirements of CORBA object services (LifeCycle, Event/Notification, and Naming, Interface Repository etc.).

In summary, the SMI to IDL translation approach described in this document is defined to be an "all CORBA solution" for implementing SNMP MIBs in the CORBA domain, for management of CORBA/non-CORBA objects as well as writing of management applications in the CORBA domain for managed objects in CORBA and SNMP domains.

Outline of Translation Algorithm

1. Map an SMIv2 Information module (SMI document) into an IDL module:

   • all interfaces, types and constant generated from a SNMP information module will be within the scope of the corresponding IDL module

   • declare the imported types in the information module as typedef of imported IDL type

   • declare an IDL interface, called SmiEntryFactory (F in Mapping of SNMP Information Module to IDL), if there is at least one group with non-tabular variable or table

   • declare two IDL interfaces, called Notifications and PullNotifications (N & PullN in Mapping of SNMP Information Module to IDL), if there is at least one NOTIFICATION-TYPE macro in the MIB module. Notifications and PullNotifications interfaces will be used for typed-push and typed-pull event communication respectively.

   • declare a pseudo IDL interface, called DefaultValues (D in Mapping of SNMP Information Module to IDL), if there is at least one OBJECT-TYPE macro with DEFVAL clause. Pseudo IDL interfaces generate library code similar to specification of CORBA::TypeCode interface.

   • declare a pseudo IDL interface, called TextualConventions (TC in Mapping of SNMP Information Module to IDL), if there is at least one TEXTUAL-CONVENTION macro with DISPLAY-HINT clause

2. Map each of the ASN.1 type into IDL type using the translation scheme defined in this specification. A complex ASN.1 data type (used to describe PDUs for SNMP) may generate more than one IDL data type.

3. Map the value-specification of SYNTAX clause of TEXTUAL-CONVENTION macro, such as DisplayString, into an IDL type.

   If DISPLAY-HINT clause is present then, define two operations within the scope of TextualConventions interface for converting the typed value to string and string to typed value.

4. Map the value of the invocation of the MODULE-IDENTITY macros into a constant IDL literal of type string.

5. Map the value of the invocation of the OBJECT-IDENTITY macros into a constant IDL literal of type string.

6. Each group is mapped as follows. One IDL interface is generated for the group (G in Mapping of SNMP Information Module to IDL) and one IDL interface (T in Mapping of SNMP Information Module to IDL) for entry of each table in the group.

   • Make forward declaration of all IDL interface types generated for the table entries in the group.

   • Declare one attribute for the table within the scope of the IDL interface for the group. The type of the attribute is sequence of the type of the interface for the entries of the table.

   • Non-tabular variables of a group are mapped as IDL attribute within the scope of the IDL interface for the group. Column variables of the tables are mapped as attributes within the scope of the IDL interface for the entries of the table:

     • Use the descriptor of the OBJECT-TYPE macro of the corresponding variable as the identifier of attribute.

     • Acquire the IDL type of the attribute from the SYNTAX clause of the OBJECT-TYPE macro of the corresponding variable.

     • acquire the mode of the attribute from the MAX-ACCESS clause of the OBJECT-TYPE macro of the corresponding variable.

   • If DEFVAL clause is present then, define an operations that returns the default value in typed form and the operations is defined within the scope of the DefaultValues interface.

   • Define an operation (create_<interface_id>) within the scope of the SmiEntryFactory interface, where <interface_id> is the name of the IDL interface for the group/table-entry.

7. Map the value of the invocation of the NOTIFICATION-TYPE/TRAP-TYPE macros into a constant IDL literal of type ASN1_ObjectIdentifier:

   • Map the value-specification of OBJECTS/VARIABLES clause to an IDL struct which has one item for each variable in the OBJECTS/VARIABLES clause. The type of the items of the struct are defined as name-index-value triplet, and the type of the value is derived from the variable being mapped.

   • Define an operation within the scope of the Notifications interface of this module for typed-push event communication. The in parameters of the operation are the event source name in the form of CosNaming::Name (it will inlcude host ip-address, the community name, enterprise-oid for SNMPv1 and SNMPv2c and host ip-address, context-name, context-engine-id), a time-stamp for the event, and the IDL struct defined for the value-specification of the OBJECTS/VARIABLES clause. Use the descriptor of the macro as the identifier for the operation.

   • Define two operations (try_<op> and pull_<op>) within the scope of PullNotifications interface of this module, where <op> is the identifier of the corresponding operation in the Notifications interface. The parameters of the operations are same as push-event model but they are defined as out parameters.

8. The compiler will generate a file, with name <module-name>.oid, where each line the file contains four elements in given order: IDL Scoped name, OID, SMI type of the variable, and the MAX-ACCESS.

9. Ignore the macros related to module compliance rules.

Note:

Since the SNMPv3 specification only enhances the security administration part of the SNMPv2 specification and does not specify any changes to the SMI part, the mapping scheme defined in this document is also applicable to the MIB module specified for SNMPv3.

Changes from Preliminary Specification

• CosLifeCycle::LifeCycleObject and CosPropertyService::PropertySet interfaces are defined as the base interfaces for SNMPMgmt::SmiEntry.

• The DESCRIPTION clause of macros is mapped as a block comment in the IDL. The block comments start with \/* and end with \*/.

• OBJECT-TYPE macro for Table is mapped as IDL operation that returns an iterator (of type SNMPMgmt::SmiTableIterator) within the scope of the IDL interface of the enclosing group (instead of mapping the macro as IDL string constant).

• INDEX clause in OBJECT-TYPE macro for table entry is now mapped as IDL constant of type string within the scope of the IDL interface for the Table entry.

• The value-specification of AUGMENT clause in OBJECT-TYPE macro for a table entry is now used as base type instead of SNMPMgmt::SmiEntry.

• Definitions have been introduced for a generic factory interface in the SNMPMgmt module and for a mapping scheme for generating factory interfaces for MIB specific groups/table-entries.

• The GenericNotifications and PullGenericNotifications interfaces in the SNMPMgmt module are renamed as Notifications and PullNotifications, respectively.

• The MIB specific Notifications and PullNotifications interfaces now have SNMPMgmt::Notifications and SNMPMgmt::PullNotifications as their base interfaces, respectively.

• Generation of #pragma IDs for IDL identifiers is deprecated. Instead, the compiler generates the mapping between scoped names for IDL interface/attributes and corresponding OIDs in a separate ASCII text file. This file is only necessary at the gateway between the CORBA and SNMP domains.

Issues Related SMIv1 and SMIv2 MIB Modules

Since the TRAP-TYPE macro in SMIv1 is not present in SMIv2, this specification includes explicit mapping of the TRAP-TYPE macro to IDL, based on the SMIv1 to SMIv2 mapping specification in the referenced SMIv1 to SMIv2 document.

Lexical Translation of ASN.1 Identifiers/Macros Descriptors

The Type suffix is added to all types generated from the ASN.1 types and the SYNTAX clause of the OBJECT-TYPE and TEXTUAL-CONVENTION macros defined in a SNMPv2 Information module. Consideration was given to dropping the Type suffix rule for ASN.1 types, but this would have required implementing two different ASN.1->IDL compilers, one for GDMO/ASN.1 and one for SNMP/ASN.1. The Type suffix rule also helps to generate identifiers for subtyping of values of SYNTAX clause in OBJECT-TYPE macro. It was therefore decided to keep the Type suffix rule for ASN.1 types.

The ASN.1 hyphen ("-") maps to IDL underscore ("_").

Compiler Options

-A

Output IDL files for every imported module

-I<path>

Specifies directory where imported MIB files reside

-D<path>

Specifies the directory where IDL file is put.

Standard IDL Files Used

ASN1Types.idl

Contains the base definitions for translating ASN.1 types

SNMPMgmt.idl

Contains the definition for base IDL interface for SNMP groups or Tables; it also contains the specification of generic factory interface.

It also contains the IDL types for untyped event communication and base interfaces for generic typed event communication for Traps/Notifications.

RFC1155_SMI.idl

Contains SNMPv1 specific SMI defined ASN.1 types in IDL.

SNMPv2_SMI.idl

Contains SNMPv2 specific SMI defined ASN.1 types in IDL.

The IDL interfaces and types in these files are described later in this Part of the document.

Contents of SNMPMgmt.idl file

This file also defines generic factory interface, called GenericFactory, for SNMP specific LifeCycle service.

The SNMPMgmt module comprises a collection of interfaces that together define a basic set of services for developing Systems Management Applications based on CORBA. This module contains the following interfaces and the interfaces are describe in the referenced Interaction Translation document:

• The ProxyAgent interface

• The SmiEntry interface

• The GenericFactory interfaces

• The NamingContext interface

• The SmiTableIterator and GetNextEntryIterator interfaces

• The Notifications and PullNotifications interfaces

Mapping of Module Definition

 

<module-identifier> DEFINITIONS ::= BEGIN
	<macro-instances>
END

The DEFINITIONS statement is mapped to IDL as follows:

 

module <module-identifier> {
	<idl-mapped-macro-invocations>
};

where <module-identifier> is mapped as an ASN.1 identifier as defined in the referenced Common Management Facilities document. The END statement at the end of the information module is mapped to the closing brace for the IDL module.

The SNMP->IDL compiler generated IDL file follows the following rules:

• For each SNMPv2 information module in a SNMP file, the compiler generates an IDL file. The IDL file is named based on the <module-identifier> defined in the corresponding information module.

• The information in an IDL file must be enclosed using #ifndef/#endif in the following way:

  
   
  
  #ifndef _<module-identifier>_idl_
  #define _<module-identifier>_idl_
  module <module-identifier> {
  
  	<idl-mapped-macro-invocations>
  
  };
  #endif /* !_<module-identifier>_idl_ */
  
  
  
  

Naming of the Generated IDL Files

Naming of the Generated OID Files

Mapping of IMPORT/FROM Clause

 

IMPORTS <descriptor1> [, <descriptor2 ... [, descriptorn] ] FROM <module-name>

Descriptors, which are not macro reference or macro descriptor, in the IMPORTS statement are declared within the scope of the IDL module by way of typedef in the following format:

 

typedef <module-name>::<descriptor1>Type <descriptor1>Type;
typedef <module-name>::<descriptor2>Type <descriptor2>Type;
typedef <module-name>::<descriptor1>Type <descriptor1>Type;

Note that we have added the "Type" suffix to all types that are defined in another module. Since base ASN.1 types are assumed globally defined and they are not explicitly imported, the rule is always consistent.

If there is no "IMPORTS ... FROM" statement in the SMI module, then the following include directives will be added at the beginning of the file:

 

#include <ASN1Types.idl >
#include <SNMPMgmt.idl >

in order to include the global ASN.1 types and base IDL interface.

Each FROM <module-name> clause will map to a #include statement at the beginning of the file (even if the imported elements from the <module-name> are ignored), as follows:

 

#include <<module-name>.idl>

Example

Mapping of DESCRIPTION Clause as Block Comments

If the REFERENCE clause is present in a macro then the value-specification for this clause
is to the block comment of the DESCRIPTION clause of the corresponding macro.

 





/*


<DESCRIPTION-value-specification>





<REFERENCE-value-specification>


*/

Mapping of ASN.1 OBJECT IDENTIFIER

The value of the OBJECT IDENTIFIER assignment and the IDL scoped name of the mapped descriptor are declared in the .oid file for the MIB module in the following format:

 

<IDL-SCOPED-NAME> <OID> ASN1_ObjectIdentifier not-accessible

Please note that each of the elements of the above declarations are separated by one or more spaces and the declaration is terminated by a new line character.

Mapping between OID and ScopedName in Separate File

Each line of the .oid file represents one entry in MIB module and contains exactly four elements in the given order:

• The IDL scoped name of the mib variable/group/table/table-entry/module-identity/OID. The IDL scoped name represents the unique name in the Interface Repository of the corresponding SNMP MIB element.

• The SMI Object Identifier (in dotted number form) of the IDL scoped name of the first element

• The name of the base SMI type in IDL for the variable. If the identifier is not a variable then Group/Table/TableEntry/OID/Notification is used. The base SMI types are built-in ASN.1 types in ASN.1 idl file and the types defined in RFC1155_SMI.idl for SMIv1 specific MIBS and SNMPv2_SMI.idl for SMIv2 specific MIBs. This information is needed because most existing SNMP protocol stack implementation require the knowledge of base ASN.1 type or the SMI type of a variable. In CORBA 2.0 compliant system this information can derived from the TypeCode of the IDL types of the Attributes for the variables by way of AliasDef information in the Interface Repository.

• The value specification from the MAX-ACCESS clause for OBJECT-TYPE macro. If the entry is not for OBJECT-TYPE macro then this item is labeled as not-accessible always. This item is needed to find out which variables support read-write and which variables support read-create. You cannot obtain this information directly from the mapped IDL.

Use of RFC1213_MIB.oid for Mapping IDL ScopedName describes a subset of entries in RFC1213_MIB.oid file obtained from the RFC1213-MIB mib information module.