Solstice Enterprise Manager 4.1 Management Information Server (MIS) Guide | ![]() ![]() ![]() ![]() |
Management Information Tree (MIT)
This appendix describes the following topics:
- Section B.1 Management Information Tree Objects
- Section B.2 Compilers
- Section B.3 Command Line Syntax for em_gdmo
- Section B.4 The Concise MIB Compiler
- Section B.5 The Schema Compiler
- Section B.6 Invoking the Compilers
Note It is assumed that you installed Solstice EM in the default directory
/opt/SUNWconn/em. If you installed the product in a different directory, replace all /opt/SUNWconn/em instances in this chapter with the appropriate directory path.
Compilers provide a way for you to add new managed object definitions to the MIS. If your application refers only to object classes already known to the Solstice Enterprise Manager (Solstice EM) MIS, you will not need to use these compilers. However, if you plan to add new managed objects to MIS, read this chapter for instructions.
B.1 Management Information Tree Objects
Every object known to MIS is represented in the MIT. The objects in the MIT include network devices such as routers and hosts, virtual objects such as queues, filters, and events, and objects that MIS itself or applications create. A single global MIT provides a single naming scheme for all data. The MIT is constructed according to a standard provided by OMNIPoint 1.
B.1.1 Object Descriptions
A description of every object known to MIS is stored in the MDR. The data in the descriptions encompasses everything from the syntax required to refer to an attribute, to the composition of an object package. The MIS then makes this data available to its clients.
For every managed object known to MIS, there also must be the following information:
- The class to which the object belongs.
- The specifics of the instance of that class, such as a list of attributes, the syntax of each attribute, and the name bindings, which give the object's position within the MIT.
The definitions for managed objects are contained in ASN.1 and GDMO documents. These are found in the following default directories, respectively:
- /opt/SUNWconn/bin/etc/asn1
- /opt/SUNWconn/bin/etc/gdmo
These documents are normally compiled and installed into the MDR when you install Solstice EM, or when you run the command em_services -reload
For more information about the em_services command, see Chapter 2.
Note There is one GDMO document associated with a particular managed object. The document names are usually composed of the name of the managed object class followed by the suffix .asn1 or .gdmo
B.1.2 Adding a New Managed Object to the MDR
If you want to add a new definition for a managed object to the MDR, you must create the appropriate ASN.1 and GDMO documents. You can use existing ASN.1 and GDMO documents as templates for your new documents, or you can write your own from scratch. Once you have created these documents, you must compile the definitions and add them to the MDR.
B.1.3 Compiling Definitions for the MDR
The following summarizes the processes handled by each compiler:
- The ASN.1 Compiler (em_asn1)
- This compiler processes a description of a managed object transfer syntax written in ASN.1 type format. Such a description may be produced as output from the Concise MIB compiler, from the Schema compiler, or can be supplied directly from an ASN.1 document. See The ASN.1 Compiler, for details on using this compiler.
- The GDMO Compiler (em_gdmo)
- This compiler processes a managed object description written in GDMO format. Such a description may be produced as output from the Concise MIB compiler, from the Schema compiler, or can be supplied directly from a GDMO document. See The GDMO Compiler, for details on using this compiler.
- The Concise MIB Compiler (em_cmib2gdmo)
- This compiler translates an SNMP MIB into both GDMO and ASN.1 formats, thus serving as a preprocessor for both the GDMO and ASN.1 compilers. See The Concise MIB Compiler, for details.
- The Schema Compiler (em_snm2gdmo)
- You can use this compiler to translate SunNet Manager 2.2 or later schema files to GDMO and ASN.1 format. This compiler serves as a preprocessor to the GDMO compiler. Refer to SectionB.5 The Schema Compiler for detailed information on the Schema compiler.
B.2 Compilers
The following are descriptions of each compiler.
B.2.1 The ASN.1 Compiler
Use the ASN.1 compiler to compile ASN.1 descriptions of managed objects contained in ASN.1 documents, into the MDR.
ASN.1 documents contain ASN.1 definitions written in ASN.1 format. A message that uses ASN.1 encoding must include not only the encoded data, but also information about the type of encoded information. A process that represents a value with an ASN.1 encoding, or that extracts a value from an ASN.1 encoding, must be able to access the definition of the particular encoding employed. The GDMO descriptions of new objects also make reference to ASN.1 descriptions for the syntax of attributes defined within.
To provide effective access to the needed ASN.1 definitions, the Solstice EM MDR keeps a set of files containing type definitions and encoding rules. When the definitions of new objects make reference to new ASN.1 types, files containing the new ASN.1 definitions must be included in the MIS ASN1 directory. At start-up and periodically thereafter, the Solstice EM MIS loads these ASN.1 type files into the MDR.
Solstice EM provides ASN.1 documents for a variety of managed objects. These documents are located in the directory /opt/SUNWconn/bin/etc/asn1.
B.2.1.1 Compiling ASN.1 Documents
The ASN.1 compiler compiles the contents of ASN.1 documents into a format used internally by MIS. Upon successful compilation, it places the output files into the directory in which the compiler was invoked. You must then move or copy the output file into the /var/opt/SUNWconn/em/usr/data/ASN1 MDR user directory. Alternatively, you can use the -o parameter and specify this directory when invoking the ASN.1 compiler from the command line.
![]()
To Invoke the ANS.1 Compiler
- Type:
- em_asn1 [-debug][-verbose][-output <output_dir>] file <file> [file] ...
The optional parameters for the em_asn1 command are described in the following table.
For detailed information on using ASN.1 and the format of ASN.1 definitions, refer to the following reference materials:
- ISO 8824 Specification of Abstract Syntax Notation One (ASN.1)
- ISO 8825 Specification of Basic Encoding Rules for Abstract Syntax Notation One (ASN.1)
B.2.2 The GDMO Compiler
You can use the GDMO compiler (em_gdmo) to compile new GDMO managed object descriptions. To add them to the MDR, you must either restart MIS, or use the
-host hostname parameter. This enables MIS to recognize new classes of GDMO-defined objects not previously known to it. For examples of this procedure, see Chapter 8.B.2.2.1 GDMO Updates
The GDMO compiler has been enhanced to be compliant with the 1995 amendments to the ITU GDMO specification. (For information on the 1995 amendments to the ITU GDMO specification, see the CCITT Recommendation X.722 and Amendments 1, 2, and 3.) This enhancement includes:
- Support for the alias directive feature
- Solstice EM's GDMO compiler now supports both exporting and importing alias directive entries in its GDMO files. The syntax of GDMO Alias directive is as specified in Amendment 2 of X.722.
- The addition of a Global Documents Aliases Names Database
- To support the alias feature, Solstice EM now has Global Documents Aliases Names Database (GDANDB). This database is contained in a flat file found at
/var/opt/SUNWComm/em/date/MDR/EM_ALIAS_REF.- During a compilation, the GDMO compiler adds entries to this database upon detecting an "exporting" Alias directive. Entries to this database are checked for uniqueness to avoid duplication. To avoid possible corruption to the database entries due to multiple concurrent compiler users, only one user is allowed to update the database at a time. Another user will be blocked from updating until the lock is removed.
- Integration of the SUNWgdmod v2.0 packages into Solstice EM and the Sun TMN product set.
- SUNWgdmod v2.0 is integrated into Solstice EM so that both Solstice EM and the Sun TMN product set support the same set of ITU/CCITT standard GDMO MIB files.
- The OID for X.227 document has been changed to:
- ACSE-1 {joint-iso-itu-t association-control (2) modules (0) apdus (0) version1 (1) }
- Support for the following new properties and directives:
- SET-BY-CREATE property (as specified in Amendment 1 of X.722)
- NO-MODIFY property (as specified in Amendment 2 of X.722)
- GDMO.Document and GDMO-End-Document directives (as specified by Amendment 2 OF x.722)
- GDMO.Version directive (as specified in Amendment 2 of X.722)
- Support for Document Override feature
A new directive extension by Sun GDMO Override is added to enable overriding the document label. If an Override directive is stated for a particular document, the document label, if and when completed, will be replaced with the overriding label. The syntax of Override directive is <GDMO.Override "<old label>" "<new label>". The typical path name of the override directives is
opt/SUNWcomm/em/etc/gdmo/em_alias_ref.gdmo
B.2.2.2 GDMO Compiler Input
The GDMO compiler takes as its input one or more object class descriptions written in the standard GDMO format. The input must be provided in ASCII text files. A single file may contain several descriptions; the required format for a description clearly delimits the beginning and end of each. You may write a single description so that it spans several files, but this is not recommended.
The format of a GDMO description is described in the ISO/IEC 10165-4 specification Information Technology - Structure of Management Information - Part 4: Guidelines for the Definition of Managed Objects. This refernce resource publication includes templates; that is, sample descriptions of various types of managed objects. These templates may serve as models for the description of specific objects of the same general type but with differing particulars.
The GDMO compiler follows the required format very closely and is unforgiving of deviations.
The Solstice EM product provides GDMO documents in the $EM_HOME/etc/gdmo directory. You can use these managed object descriptions as is, or you can create your own. If you are creating new managed object definitions, note that GDMO documents are generally given mnemonic names followed by a .gdmo extension. When the GDMO compiler is used on these files, it produces one or more output files depending on the content of the documents.
Solstice EM provides the user MDR directory /var/opt/SUNWconn/em/usr/data/MDR in which you can store your private compiled GDMO documents. When MIS is started, it looks for compiled documents in both this directory and the directory /var/opt/SUNWconn/em/data/MDR, and loads any appropriate documents that it finds. For the documents to be loaded into the MDR, they must be in one of these two directories. You can compile the documents in any directory and then manually copy or move then over, or you can specify a directory using the
-output <output_dir> parameter (see Command Line Syntax for em_gdmo).B.2.2.3 Managing Related GDMO Documents
For parsing purposes, all GDMO definitions and documents used by a GDMO document should be in the same file. This ensures proper validation across document boundaries. Parsing GDMO documents as separate files is permissible, but does not provide cross-validation between files.
Consider an example where Document A calls out an attribute operationalState and states it is defined in Document B. The actual syntax of operationalState cannot be validated unless Document B is in the same file.
If Document B is a different file, during parsing of Document A, the parser assumes that Document B will be found and will contain what is needed. If in Document B the attribute name is misspelled (for example, OperationalState rather than operationalState), the parser cannot validate Document B and therefore notes a warning. A warning is not fatal; it would be reported even if Document B were perfect. Parsing then continues.
You may still receive a "parsing complete" message when the information is loaded into the MDR. You would see no errors for Document B. Later, the fault will manifest as a "no-such-attribute" error when an attempt is made to instantiate an object whose definition contains the incorrect syntax.
This may also occur when an attempt is made to display information retrieved from a remote object that uses the invalidated syntax.
B.2.2.4 GDMO Compiler Output
When the GDMO compiler runs in compile (non-parsing) mode, it reads the source files, compiles them, and passes the compiled description--via the PMI--to a running Solstice EM MIS. The portions of the description dealing with object classes, packages, attributes, and name bindings are compiled and stored in the MDR.
The output files are written to the directory in which the compiler was invoked. You must then copy or move the output files to the directory /var/opt/SUNWconn/em/usr/data/MDR. Alternatively, you can specify this directory in conjunction with the -output <output_dir> parameter when you invoke the GDMO compiler.
Note If you invoke the GDMO compiler without the -host hostname parameter, MIS must be restarted in order for the GDMO data to be loaded into the MDR.
Each output file is assigned a name derived from the source document, except a space character is mapped to an underscore character, and a slash (/) character is mapped to a percent character.
Each output file must start with a header line. If you invoke the GDMO compiler with the -header <header_string> parameter, the specified string is used as the first line of the output file. If you omit this parameter, the following default header is used:
@(#) Created by <user> at <date>B.3 Command Line Syntax for em_gdmo
![]()
To Invoke the GDMO Compiler
- Type:
- em_gdmo [options] -file <file> [file] ...
The -file <file> parameter is used to specify the input file(s). The optional parameters for the em_gdmo command are described in the following table.
The GDMO compiler functions in two modes of operation:
- Parse-only
- Parse-and-compile
B.3.1 Parse-only Operation
Invoke the GDMO compiler as follows so that it uses a grammar parser to verify conformance to syntactic rules:
An error detected by the GDMO compiler during parsing generates a message stating the name of the file being parsed, and the line number where the error was encountered.
B.3.2 Parse-and-Compile Operation
Once the input files can be parsed without error, you can run the compiler in the parse-and-compile mode to store the parsed and compiled definitions in the MDR directory, then restart MIS to load the definitions.
![]()
To Run the Compiler in Parse-and-Compile Mode
1. Invoke em_gdmo as follows:
- em_gdmo -output /var/opt/SUNWconn/em/usr/data/MDR -file <file>
2. You then must run em_services to load the definitions into the MDR. Alternatively, you can load the definitions into the MDR directly:
- em_gdmo -host <hostname> -file <file>
Caution If the MIS does not have access to the required ASN.1 definitions, the GDMO compiler will not receive an error. Consequently, the problem will not become evident until later. When a process attempts to instantiate an object based on the class description you supplied, or to display information retrieved from a remote object that used your syntax, it is likely to receive a "no-such-attribute" error, or some other related error.
To process the parsed and compiled input, MIS must refer to the ASN.1 documents located in the $EM_HOME/etc/asn1 directory. You must be root to write to this directory. The GDMO descriptions assume that these definitions are present. See Compiling ASN.1 Documents, for more information about the preparation, storage, and availability of ASN.1 files. ASN1 documents can be found in the /var/opt/SUNWconn/em/usr/ASN1 directory.
B.4 The Concise MIB Compiler
You can extend the Solstice EM MIS Management Information Tree (MIT) to recognize new types of managed objects. When a new object description is specified in a GDMO document, the description can be processed directly by the GDMO compiler (described in SectionB.2.2 The GDMO Compiler. However, when the object description is written in the Internet Concise MIB format, the description must first be processed by the Concise MIB compiler.
The Concise MIB compiler (em_cmib2gdmo) takes MIBs and generates two files in the appropriate formats for the GDMO and ASN.1 compilers. When the resulting GDMO descriptions are parsed and compiled, they make use of ASN.1 descriptions of their data types. The Concise MIB compiler generates a <type>.asn1 file as well as a <type>.gdmo file, as illustrated in FIGURE B-1.
If the target files exist, they are overwritten. You would normally use the Concise MIB compiler (em_cmib2gdmo) in conjunction with the GDMO compiler (em_gdmo) and the ASN.1 compiler (em_asn1) to take a vendor- specific Concise MIB, convert it to GDMO and ASN.1 components, and incorporate further compiled versions of these into the Solstice EM MIS. The Concise MIB compiler checks the source files to ensure they conform to RFC 1212, and reports any errors that are discovered. The GDMO and ASN.1 output files are produced even if incorrect or incomplete.
By default, em_cmib2gdmo imports the following OIDs from RFC 1155:
- ISO
- ORG
- DOD
- Internet
- directory
- MGMT
- experimental
- private
- enterprises
This importation can be suppressed by using the -1155 option (refer to TABLE B-2). Also, by default, the following types are built in (normally defined in RFC 1155):
- NetworkAddress
- IpAddress
- Counter
- Gauge
- TimeTicks
- Opaque
The following are also built in (normally defined in RFC 1213):
- OBJECT-TYPE
- DisplayString
- PhysAddress
![]()
FIGURE B-1 The Concise MIB Compiler
B.4.1 Names of Input and Output Files
An input file for the GDMO compiler can have any name, but by convention, the name should end with the extension .mib. The Concise MIB compiler generates two output files for each input file. The output files have the same names as the input file with the extension (if any) replaced by .gdmo and .asn1, respectively.
![]()
To Process Files Produced by the Concise MIB Compiler
1. Use the ASN.1 compiler to process the type.asn1 file.
- See The ASN.1 Compiler, for more information about the ASN.1 compiler.
2. Use the GDMO compiler to process the <filename>.gdmo file.
- Refer to The GDMO Compiler, for more information about the GDMO compiler and how to further process the <filename>.gdmo file for inclusion in MIS.
B.4.2 Command Line Syntax for em_cmib2gdmo
Following is the format of the Concise MIB compiler's command line syntax.
hostname% em_cmib2gdmo [-b -d -1155 -h -l -m -p -r -t -v1 -v2 -w - autosuffix] <file>...The optional parameters for the em_cmib2gdmo command are described in the following table.
- The -l option further instructs the compiler to generate only a GDMO output file and an ASN.1 type file for the last specified Concise MIB file. This is useful if a MIB imports information from another MIB, but you wish to translate only the MIB with the dependency. For example, if the (RMON) MIB rfc1271 imports OIDs from rfc1213 (MIB-II), but you have no desire to translate rfc1213, you can use the following command:
em_cmib2gdmo -l rfc1213.mib rfc1271.mib
- Only the rfc1271.gdmo and rfc1271TYPE.asn1 output files are generated.
For detailed information about Concise MIBs and the format of Concise MIB definitions, refer to the following reference materials:
- RFC 1212, Concise MIB Definitions
- RFC 1215, A Convention for Defining Traps for use with the SNMP
- LaBarre, Lee (Ed), ISO/CCITT and Internet Management Coexistence (IIMC): Translation of Internet MIBs to ISO/CCITT GDMO MIBs, March 26, 1993
- LaBarre, Lee (Ed), ISO/CCITT and Internet Management Coexistence (IIMC): Translation of Internet MIB-II (RFC1213) to ISO/CCITT GDMO MIB
- ISO/CCITT SMI Guidelines for Definition of Managed Objects [ISO10165-4]
B.4.3 Diagnostics
The compiler is structured to recover from syntax errors. The type checker does not affect the translation process, but simply produces messages if it finds type errors. The GDMO output phase prints warnings for those OIDs that are not resolved. It also prints the characters "???" in place of the unresolved OID in the GDMO output file.
B.5 The Schema Compiler
The SunNet Manager (SNM) 2.x products use schema files to represent the managed object classes available to the SNM database. You must use the Schema compiler (em_snm2gdmo) as the first step in converting the SNM 2.2 or later schema files into GDMO descriptions used in Solstice EM.
To translate an SNM 2.2 or later schema file, run the Schema compiler with the file to be translated as an argument (<filename>). The output of the translation produces two files:
- A GDMO document with a name of the form <filename>.gdmo for non-agent schemas, or <agent/proxy_name>.gdmo for SNM agent schemas.
- An ASN.1 document with a name of the form <filename>.asn1 for non-agent schemas, or <agent/proxy_name>.asn1 for SNM agent schemas.
These output files are created in the directory from which you invoke the Schema compiler. Once you have created the output files, you must then pass them through the GDMO compiler.
B.5.1 Command Line Syntax for em_snm2gdmo
![]()
To Invoke the Schema Compiler
1. Type:
em_snm2gdmo <filename> <OID_branch>
- You must specify the filename of the schema file you want to translate, and any unused <OID_branch> number for that file. This number is used to assign a unique OID to every record type defined within the specified schema file. To determine which OID branch numbers have not already been used, go to the directory where the ASN.1 documents are stored (the default directory is $EM_HOME/etc/asn1), then type the following command:
grep "em_snm2gdmo" *.asn1- All files that are generated by the schema compiler will contain the line:
-- This file was generated by em_snm2gdmo.- The OID branch numbers "0" and "1" are reserved:
- "0" is reserved for SNM agent/proxy schemas, which can be found in $SNM_HOME/agents.
- "1" is reserved specifically for the schema file elements.schema.
- To find out what other OID branch numbers have already been used, edit the files listed as a result of the grep command shown above. The following code example lists is the contents of the file cooptoolsschema.asn1
- The OID branch number is the last integer before the } character in the lines beginning with "Cooptoolsschema". The number 3 has been assigned to the schema file cooptools.schema.
Refer to the Solstice Site/SunNet/Domain Manager Application and Agent Development Guide for a description of the schema file format.
Diagnostics
The Schema compiler stops at the first occurrence of an error in the schema file. In many cases it displays messages that aid in debugging, but does not do so in all cases.
B.6 Invoking the Compilers
The following command line options may also be used for invoking the compilers.
![]()
The em_asn1 Command
The em_asn1 command invokes the ASN.1 compiler, which is used to compile the contents of ASN.1 documents into a format used internally by MIS.
B.6.1 To Invoke the ANS.1 Compiler
The optional parameters for the em_asn1 command are described in TABLE B-1.
![]()
The em_compose_all Command
The em_compose_all command takes a GDMO file as input, and:
- Reads all the object classes and name bindings in the GDMO definition file.
- Composes and loads the name bindings accordingly in MIS.
Prior to running this command, the GDMO file should have been loaded into the MDR using the GDMO compiler em_gdmo.
Invoke the em_compose_all command from the command line as follows:
em_compose_all <filename>You must specify the name of a GDMO document.
![]()
The em_compose_oc Command
The em_compose_oc command is used to instantiate a new object class with volatile data storage. Volatile data storage means that if MIS is restarted (with the em_services command but without the -i option), any object of the object class which was composed with the em_compose_oc command will not be in MIS after it is restarted.
Before running this command, the Managed Object Class should have been loaded into the MDR using the GDMO compiler em_gdmo and the ASN.1 compiler em_asn1.
B.6.2 To Invoke the em_compose_oc Command
The arguments for the em_compose_oc command are one or more object classes from the GDMO file.
![]()
The em_compose_poc Command
The em_compose_poc command is used to instantiate a new object class with persistent data storage. Persistent data storage means that if MIS is restarted (with the em_services command, but without the -i option), any object of the object class which was composed with the em_compose_oc command will remain in MIS after it is restarted.
Note If MIS is restarted using em_services -i, then all persistent storage is lost.
Before running this command, the Managed Object Class should have been loaded into the MDR using the GDMO compiler em_gdmo and the ASN.1 compiler em_asn1.
![]()
To Invoke the em_compose_poc Command
The arguments for the em_compose_poc command are one or more object classes from the GDMO file.
B.6.3 The em_cmib2gdmo Command
The em_cmib2gdmo command invokes the Concise MIB compiler, which is used to translate a managed object description written in the Concise MIB format into both GDMO and ASN.1 formats, thus serving as a preprocessor for both the GDMO and ASN.1 compilers.
![]()
To Invoke the Concise MIB Compiler
The optional parameters for the em_cmib2gdmo command are described in TABLE B-3.
B.6.4 The em_gdmo Command
The em_gdmo command invokes the GDMO compiler, which is used to extend the capabilities of the Solstice EM MIS to deal with new classes of objects not previously known to it. It does this by compiling GDMO descriptions of managed objects, which are provided in GDMO documents.
![]()
To Invoke the GDMO Compiler
- Type:
em_gdmo [options] -file <file>...
- The -file <file> parameter is used to specify the input file(s). The optional parameters for the em_gdmo command are described in TABLE B-2.
- The GDMO compiler functions in two modes of operation:
- Parse-only
- Parse-and-compile
B.6.5 The em_load_name_bindings Command
The em_load_name_bindings command loads the name bindings, which tell MIS where the object is in the MIT. Prior to running this command:
- The GDMO definitions should be loaded into the MDR using the GDMO compiler em_gdmo.
- The ASN.1 definitions should be loaded into MDR using the ASN.1 compiler em_asn1.
- The object classes used in the name binding should have been composed using em_compose_oc or em_compose_poc.
![]()
To Invoke em_load_name_bindings
The command line arguments for the em_load_name_bindings command are one or more name bindings from the GDMO file.
B.6.6 The em_snm2gdmo Command
The em_snm2gdmo command invokes the Schema compiler, which is used to translate SNM 2.2 or later schema files into GDMO descriptions used in Solstice EM.
![]()
To Invoke the Schema Compiler
The OID_branch parameter is any unused OID branch number for the specified schema file.
This number is used to assign a unique OID to every record type defined within the specified schema file. "0" and "1" are the only OID branch numbers that are already reserved:
- "0" is reserved for SNM agent/proxy schemas, which can be found in $SNM_HOME/agents.
- "1" is reserved specifically for the schema file elements.schema.
B.6.7 The em_topo_args Command
The command em_topo_args is used to pass arguments to applications that are launched from the Object Menu of a device. For example:
$EM_HOME/bin/em_topo_args EM_UNIQUE_ID "/bin/echo %serviceProvider > /tmp/test2"In this example, serviceProvider is an attribute added to the topoNodeUserData of a device type and so em_topo_args can be used to extract its value.
The em_topo_args command was written for backwards compatibility, although it can be used for non bc applications. The % is from SNM. % in SNM is used to pass an element type (glyph) schema attribute to the command line.
There are also some limitations on what you can pass on to an application. If the topoNodeUserData type is a SET OF xxx, it will not work since topoargs does not have a way to pull out individual members of a SET. It does work for SEQ.
Sun Microsystems, Inc. Copyright information. All rights reserved. |
Doc Set | Contents | Previous | Index |