Internet Draft Andy Bierman Cisco Systems, Inc. 5 November 2001 Structure of Management Information: Data Structures Status of this Memo This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026 [RFC2026]. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet- Drafts as reference material or to cite them other than as "work in progress". The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. Distribution of this document is unlimited. Please send comments to the RMONMIB WG mailing list . 1. Copyright Notice Copyright (C) The Internet Society (2001). All Rights Reserved. Internet Draft SMI Data Structures November 5, 2001 2. Abstract This memo defines a portion of the Structure of Management Information (SMI) for use with network management protocols in the Internet community. In particular, it describes a new structure and naming scheme for network management information, allowing the specification of arbitrarily complex hierarchical data structures. 3. Table of Contents 1 Copyright Notice ................................................ 1 2 Abstract ........................................................ 2 3 Table of Contents ............................................... 2 4 The SNMP Network Management Framework ........................... 2 5 Overview ........................................................ 3 5.1 Terms ......................................................... 4 5.2 Design Objectives ............................................. 5 5.3 Module Declarations ........................................... 6 5.4 Data Structure Constructs ..................................... 6 5.5 Hierarchical Instance Naming .................................. 7 5.5.1 Data Structure Naming Algorithm ............................. 8 5.6 SMI-DS Data Object Usage Examples ............................. 10 5.6.1 InetAddress Example ......................................... 11 5.6.2 Generic High Capacity Counter Example ....................... 13 5.7 AUGMENTS for Data Structures .................................. 15 5.7.1 STRUCT AUGMENTS Example ..................................... 16 5.7.2 UNION AUGMENTS Example ...................................... 18 5.7.3 ARRAY AUGMENTS Example ...................................... 20 5.8 Complete MODULE Example ....................................... 25 6 Definitions ..................................................... 35 6.1 Namespaces .................................................... 35 6.2 Syntax ........................................................ 35 7 Intellectual Property ........................................... 41 8 Acknowledgements ................................................ 42 9 References ...................................................... 42 10 Security Considerations ........................................ 45 11 Author's Address ............................................... 45 12 Full Copyright Statement ....................................... 46 4. The SNMP Network Management Framework The SNMP Management Framework presently consists of five major components: Expires May 5, 2002 [Page 2] Internet Draft SMI Data Structures November 5, 2001 o An overall architecture, described in RFC 2571 [RFC2571]. o Mechanisms for describing and naming objects and events for the purpose of management. The first version of this Structure of Management Information (SMI) is called SMIv1 and described in RFC 1155 [RFC1155], RFC 1212 [RFC1212] and RFC 1215 [RFC1215]. The second version, called SMIv2, is described in RFC 2578 [RFC2578], RFC 2579 [RFC2579] and RFC 2580 [RFC2580]. o Message protocols for transferring management information. The first version of the SNMP message protocol is called SNMPv1 and described in RFC 1157 [RFC1157]. A second version of the SNMP message protocol, which is not an Internet standards track protocol, is called SNMPv2c and described in RFC 1901 [RFC1901] and RFC 1906 [RFC1906]. The third version of the message protocol is called SNMPv3 and described in RFC 1906 [RFC1906], RFC 2572 [RFC2572] and RFC 2574 [RFC2574]. o Protocol operations for accessing management information. The first set of protocol operations and associated PDU formats is described in RFC 1157 [RFC1157]. A second set of protocol operations and associated PDU formats is described in RFC 1905 [RFC1905]. o A set of fundamental applications described in RFC 2573 [RFC2573] and the view-based access control mechanism described in RFC 2575 [RFC2575]. A more detailed introduction to the current SNMP Management Framework can be found in RFC 2570 [RFC2570]. Managed objects are accessed via a virtual information store, termed the Management Information Base or MIB. Objects in the MIB are defined using the mechanisms defined in the SMI. This memo does not specify a MIB module. 5. Overview There is a need for a standardized way of defining complex data structures for the representation of management information, which can be utilized with existing versions of SNMP. The current SMIv2 design model is based on groups of rectangular tables, which are related because they share one or more index components. This model provides a single containment layer (per table), because all the objects in a Expires May 5, 2002 [Page 3] Internet Draft SMI Data Structures November 5, 2001 conceptual row must be simple types (e.g., Integer32, SnmpAdminString, Counter64). The practice of spreading a multi-layer data structure across several rectangular tables causes MIB modules to be much too verbose, and hard to understand. The containment relationships between tables are usually described in INDEX clauses and various DESCRIPTION clauses. This practice also has a negative impact on agent implementations, which are harder to implement and test, due to row creation and row activation ordering issues. These issues add complexity to management application development as well. Software development and human readability would benefit from a data definition language and associated naming scheme which more closely represents the basic data structures that exist in almost all programming languages. [ed. - this initial version is meant to introduce the new SMI Data Structure concepts and is not yet defined in sufficient detail to be suitable as a formal specification.] 5.1. Terms The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119. [RFC2119] This document uses some terms that need introduction: Complex Data Object This term refers to any data object which provides some sort of containment for other data objects, which is any variable construct other than SCALAR (e.g. ARRAY, UNION, or STRUCT). Data Object This term refers to any (new) SMI Data Structure variable declaration, at any level of containment. MIB Object This term generically refers to a SMIv2 OBJECT-TYPE macro definition. It does not refer to an SMI Data Structure definition. Scalar This term refers to a non-tabular SMIv2 MIB object. Expires May 5, 2002 [Page 4] Internet Draft SMI Data Structures November 5, 2001 SCALAR This term refers to any accessible data object with a syntax that resolves to a SMI base type. To avoid confusion, the term appears in capital letters when referring to a data object definition. SMI Data Structure (SMI-DS) This term refers to the concepts and definitions defined in this document. 5.2. Design Objectives The working group objectives for this work are detailed in the SMIng Objectives document [SMING-OBJ]. [ed. - TBD: identify how this document addresses each of the objectives in that document.] The primary high-level design goals of this work are: - Significantly enhance the usefulness of the SMI as a network management data definition language. - Significantly enhance SMI object instance naming to support complex hierarchical data structures, and optimize OBJECT IDENTIFIER component order for Set, GetNext, and GetBulk SNMP PDUs efficiency. - Preserve as much of SMIv2 mechanisms and 'installed knowledge-base' as possible (if it ain't broke, then we don't fix it). - Get rid of as much textual cruft as possible (if it don't help, then we don't need it). - Make sure accessible data objects (i.e. SCALARs) can be used with existing versions of SNMP. There are two significant WG design objectives that are not addressed: - This document does not attempt to decouple object and instance naming from the object definitions, to allow for multiple naming schemes. The creation and maintenance of separate modules for definitions and protocol-specific name mappings will add unwarranted complexity to the documents and dramatically increase the opportunity to introduce bugs into these documents. The differences between SMI and SPPI row instance naming do not even apply to a data structure oriented design model. Expires May 5, 2002 [Page 5] Internet Draft SMI Data Structures November 5, 2001 - This document does not attempt to introduce any object-oriented methodologies into the management framework. Instead, some basic data structure constructs (e.g., arrays, unions, and structures available in the C Programming Language) are introduced. Direct inheritance is achieved by including the 'base type' in a new STRUCT TYPEDEF definition, and add new data objects to the STRUCT as desired. An AUGMENTS mechanism is also available to extend data object definitions over time, similar the the SMIv2 AUGMENTS for tables. 5.3. Module Declarations The type of declarations that can be made in an SMI-DS module do not really change at all. Textual conventions become typedefs, and MIB object definitions become data object declarations. Notifications are not changed at all. Most of the constructs (macros and their clauses) in SMI-DS are identical in semantic content as their SMIv2 counterparts. The syntax for some macros are slightly different, in that multi-part macros now have opening and closing curly braces ('{' and '}'), to help manage the increased containment complexity. Many constructs do not change at all, such as the MODULE-IDENTITY, NOTIFICATION-TYPE, MODULE-COMPLIANCE, OBJECT-GROUP, and NOTIFICATION-GROUP macros. 5.4. Data Structure Constructs There are four basic constructs available in the SMI-DS language for the definition of data objects. SCALAR This construct is conceptually equivalent to an OBJECT-TYPE macro definition for an accessible MIB object in SMIv2, except a SCALAR can be defined at any level of containment. A SCALAR type definition or variable declaration resolves to any SMIng base type. In SMI-DS, all other constructs must eventually resolve to some number of these objects, and only SCALAR data objects are actually accessible via a management protocol. ARRAY This construct provides a multi-dimensional array structure, similar to the SEQUENCE construct in SMIv2. However, instead of one flat 'row' consisting of only accessible base-type MIB objects, an ARRAY can consist of an arbitrary mix of any of the four types of data object constructs. Conceptually, the INDEX structure for Expires May 5, 2002 [Page 6] Internet Draft SMI Data Structures November 5, 2001 an ARRAY is the same as for a SEQUENCE, except the SMI-DS naming scheme is different. Only base type data objects can be used in an ARRAY INDEX clause (the same ones as in SMIv2), and the rules for encoding INDEX clause base types in OBJECT IDENTIFIERs are the same as for SMIv2. An ARRAY can be defined without containing any objects, for placeholder purposes only. UNION This construct provides a mechanism to conceptually allow a single object definition to contain one of potentially several different construct definitions. Only one of these constructs is actually instantiated at any time by the agent. Unlike a union in the C language, the unused union members cannot be accessed at all (no 'cast' operator in SMI). A UNION can be defined without containing any objects, for placeholder purposes only. STRUCT This construct provides a mechanism to group an arbitrary number of data constructs (of any type), allowing a theoretically unlimited number of data containment layers. It is similar to the ARRAY construct, except there is no INDEX clause. A STRUCT can be defined without containing any objects, for placeholder purposes only. 5.5. Hierarchical Instance Naming In order to fully utilize the capabilities of arbitrary containment, a new way of naming object instances is needed, which is designed for hierarchical data structures instead of tables. It is also desirable to preserve naming containment, even for augmented data structures. With SMIv2, it is possible that related object instances exist in multiple sub-trees, due the AUGMENTS clause and the use of "associated" cascading tables. A new naming scheme is proposed which allows naming containment to be preserved for AUGMENTS. SMIv2 naming in non-optimal for GetNext and GetBulk retrievals, even from the same table, because the instance identifier components (the fields interesting for sorting or subsetted retrieval) are all at the end, after all the base (static) object identifier components. Natural SMIv2 lexinext ordering is well-suited for retrieving all the instances for a single MIB object, but poorly suited for retrieving the same related instance of all related MIB objects. Expires May 5, 2002 [Page 7] Internet Draft SMI Data Structures November 5, 2001 The GetBulk PDU is designed to minimize this deficiency by allowing multiple 'GetNext start points' to be requested, but this adds complexity for both the agent and the application (especially when these multiple 'GetNext threads' get out of sync). A new naming scheme is proposed which is optimized for retrieving related objects for a single instance, no matter how complicated the object structure. Since it's possible for accessible (SCALAR) objects to exist in the same containment structure as non-accessible (e.g., ARRAY, UNION, or STRUCT) objects, it is not possible to name SMI-DS objects with a 'flat' model. SMIv2 assumes all accessible objects in the same containment structure (SEQUENCE) have the same number of object identifier components, and the exact same format (INDEX structure) for all instance identifier components. This assumption cannot be made for SMI-DS object naming. In the SMIv2 framework, it makes sense to group all object components on the left, and group all instance components on the right. Although SNMP does not make this distinction, conceptually a MIB object which contains an OBJECT IDENTIFIER, either refers to an object definition (object pointer), or some subset of instances (instance pointer), depending on how many OBJECT IDENTIFIER components are present. Instead of grouping all the instance identifiers and appending them to a fixed-length object identifier, instance identifiers and object node identifiers are combined in layers, depending on the data object definition. Note that this new naming scheme can also help reduce implementation complexity for agent and application developers for SNMP Set operations. Currently, associated attributes can be spread across multiple tables, (possibly sharing major indices) each with their own RowStatus and set of 'SNMP callback' functions. This design approach can get relatively complicated, especially if 'createAndWait' and 'notInService' RowStatus values are supported. By allowing complex containment instead of unfolding data structures into tables, and insuring that all associated objects for a given set of instances are located in the 'same place' in the MIB sub-tree (even for AUGMENTS), implementation of high-level Set operations can be simplified for both agent and application developers. 5.5.1. Data Structure Naming Algorithm The basic format of an OBJECT IDENTIFIER for an SMI-DS data object is as follows: Expires May 5, 2002 [Page 8] Internet Draft SMI Data Structures November 5, 2001 Basic Data Object Name Format: . [. ...] where: is a well-formed OBJECT IDENTIFIER base fragment is the first data object node identifier, which must be an INTEGER between 1 and 4294967295 is different, based on the data construct of the current () parent node. For SCALAR: there are no child nodes For ARRAY: .. where: contains the INDEX encoding of each INDEX object (in order), encoded exactly the same as for an SMIv2 INDEX. contains a zero if the childNode is defined in the original TYPEDEF, otherwise it contains the numeric augmentation node identifier of the AUGMENTS macro for this data type, which must be an INTEGER between 1 and 4294967295. contains the node identifier for the child node, which must be an INTEGER between 1 and 4294967295. It is only unique within the scope of a particular value. For UNION and STRUCT: . where: is defined the same as for an ARRAY. is defined the same as for an ARRAY. The expansion algorithm for is repeated if the current represents a complex data object. The current replaces the current in the algorithm, before is expanded again. The algorithm terminates when either a SCALAR data object or no accessible object is encountered. The following example demonstrates hierarchical naming, using a simple array of first and last name pairs. Expires May 5, 2002 [Page 9] Internet Draft SMI Data Structures November 5, 2001 C Language Representation: typedef struct Name_ { char first_name[MAX_STRING_LEN]; char last_name[MAX_STRING_LEN]; } Name; Name nameList[MAX_NAMES]; Hierarchical Naming Representation: nameList ::= { someRoot 1 } nameList[N] ::= { nameList N } nameList[N].first_name ::= { nameList N 0 1 } nameList[N].last_name ::= { nameList N 0 2 } Note 1) In order to support arbitrary containment, it is not possible or desirable to group all the instance components together on the right. It is important to correctly represent all layers of containment, to allow for certain conceptual references (e.g., 'nameList[N]' in the example above). Note 2) An OID component of zero is inserted before the component for the 'first_name' or 'last_name' fields. This node is used for potential augmentations to this data type, in order to identify their namespace. The data objects defined within a TYPEDEF are always assigned the namespace value zero. Note 3) The instance naming algorithm for SCALAR data types is similar to SMIv2, except there is never an extra component with a value of zero added for non-tabular objects. SCALAR data types cannot be augmented or extended, so there is no need for an augmentation node either. 5.6. SMI-DS Data Object Usage Examples The following sections introduce some examples of simple data structures that are currently achieved with relatively verbose text in TEXTUAL- CONVENTION and OBJECT-TYPE DESCRIPTION clauses using SMIv2. Expires May 5, 2002 [Page 10] Internet Draft SMI Data Structures November 5, 2001 5.6.1. InetAddress Example The Internet Address textual conventions defined in the "Textual Conventions for Internet Network Addresses" MIB module [RFC2851] defines several variants of an Internet address (InetAddress), and a control object (InetAddressType) to distinguish which variant is actually present in an InetAddress object instance. This construct may be more concisely and properly represented in SMI-DS by a structure containing the control object and a union of all the address variants. -- a union of all the InetAddress types TYPEDEF UNION InetAddressUnion { DESCRIPTION "Internet address in 4 different representations." SCALAR ipUnknown { SYNTAX OCTET STRING (SIZE (0..65535)) MAX-ACCESS read-only STATUS current DESCRIPTION "Represents an Internet address using an externally defined format. The associated InetAddressType object value is 'unknown(0)'." } ::= 1 SCALAR ipv4Addr { SYNTAX InetAddressIPv4 MAX-ACCESS read-only STATUS current DESCRIPTION "Represents an IPv4 Internet address. The associated InetAddressType object value is 'ipv4(1)'." } ::= 2 SCALAR ipv6Addr { SYNTAX InetAddressIPv6 MAX-ACCESS read-only STATUS current DESCRIPTION "Represents an IPv6 Internet address. The associated InetAddressType object value is 'ipv6(2)'." } ::= 3 Expires May 5, 2002 [Page 11] Internet Draft SMI Data Structures November 5, 2001 SCALAR ipDnsAddr { SYNTAX InetAddressDNS MAX-ACCESS read-only STATUS current DESCRIPTION "Represents an DNS domain name. The associated InetAddressType object value is 'dns(16)'." } ::= 4 } TYPEDEF STRUCT HostInetAddress { DESCRIPTION "Internet address for an end-station host, adhering to the SMIv2 'associated objects' design approach." SCALAR addrType { SYNTAX InetAddressType MAX-ACCESS read-only STATUS current DESCRIPTION "The type of Internet address." } ::= 1 UNION addr { SYNTAX InetAddressUnion STATUS current DESCRIPTION "The Internet address." } ::= 2 } STRUCT myAddress { SYNTAX HostInetAddress STATUS current DESCRIPTION "Internet address of this host." } ::= { someBase 1 } UNION newAddress { SYNTAX InetAddressUnion STATUS current DESCRIPTION "Example of the new way to represent a union variable, without the use of an associated InetAddressType object." } ::= { someBase 2 } Expires May 5, 2002 [Page 12] Internet Draft SMI Data Structures November 5, 2001 Note 1) The accessible object instances defined within this structure (addrType, ipUnknown, ipv4Addr, ipv6Addr, etc.) have different lengths: myAddress ::= { someBase 1 } myAddress.addrType ::= { myAddress 0 1 } myAddress.addr ::= { myAddress 0 2 } myAddress.addr.ipUnknown ::= { myAddress 0 2 0 1 } myAddress.addr.ipv4Addr ::= { myAddress 0 2 0 2 } myAddress.addr.ipv6Addr ::= { myAddress 0 2 0 3 } myAddress.addr.dnsAddr ::= { myAddress 0 2 0 4 } newAddress ::= { someBase 2 } newAddress.ipUnknown ::= { newAddress 0 1 } newAddress.ipv4Addr ::= { newAddress 0 2 } newAddress.ipv6Addr ::= { newAddress 0 3 } newAddress.dnsAddr ::= { newAddress 0 4 } Note 2) The addrType field is not actually needed for simple variable declarations, because UNION constructs are instantiated with at most one accessible member. In the example above, a GetNext Request for 'myAddress.addr' or 'newAddress' will return only one type of InetAddress string from the InetAddressUnion. The associated InetAddressType variable is needed only when used together with the InetAddress (generic string form) as INDEX components in an ARRAY. Note 3) Just like a TEXTUAL-CONVENTION in SMIv2, a TYPEDEF has no instances associated with it and therefore no MIB root assigned. However, accessible data objects (SCALARs) can be defined within a TYPEDEF, which are numbered hierarchically relative to the start of the TYPEDEF. It is only when a a variable of a particular type is declared (and therefore assigned a MIB root) that the full OBJECT IDENTIFIER for a data object is known. 5.6.2. Generic High Capacity Counter Example There are many MIBs that contain up to the three OBJECT-TYPE macro definitions for every high capacity counter, in order to accommodate SNMPv1 implementations without support for Counter64 and 32-bit implementations without any high capacity support at all. A type definition (GenericCounter) for a union that contains an object for each of the three scenarios would better represent the intended semantics of this design, and use less text within data structure definitions than an SMIv2 version. Note that a discriminator object is Expires May 5, 2002 [Page 13] Internet Draft SMI Data Structures November 5, 2001 not needed for a union, because the agent (or management application) will instantiate at most one of the variants. TYPEDEF UNION GenericCounter { DESCRIPTION "Generic HC counter for all versions of SNMP." SCALAR c32 { SYNTAX Counter32 MAX-ACCESS read-only STATUS current DESCRIPTION "The Counter32 representation of the counter." } ::= 1 SCALAR c64 { SYNTAX Counter64 MAX-ACCESS read-only STATUS current DESCRIPTION "The Counter64 representation of the counter." } ::= 2 STRUCT c32pair { DESCRIPTION "Pair of Counter32 objects to represent a 64-bit counter." SCALAR c32low { SYNTAX Counter32 MAX-ACCESS read-only STATUS deprecated DESCRIPTION "The lower 32 bits of a 64 bit counter." } ::= 1 SCALAR c32hi { SYNTAX Counter32 MAX-ACCESS read-only STATUS deprecated DESCRIPTION "The upper 32 bits of a 64 bit counter." } ::= 2 } ::= 3 } Expires May 5, 2002 [Page 14] Internet Draft SMI Data Structures November 5, 2001 UNION myCounter { SYNTAX GenericCounter STATUS current DESCRIPTION "An example generic counter variable." } ::= { someBase 1 } Note 1) Inline vs. external type definition: The 'c32pair' STRUCT could have been defined as a separate type and a STRUCT declared with a SYNTAX clause that referenced that type (e.g. form of the STRUCT declaration). The instance numbering works out the same either way, even though only complex data objects defined with a separate TYPEDEF can be augmented. This simplifies SNMP engine implementations, which may not know which variant of the complex data object TYPEDEF was used in the MIB definition. In other words. an augmentation identifier OBJECT IDENTIFIER component is encoded for all complex data objects, just before the child node identifier. The following OBJECT IDENTIFIERs would be possible for the 'myCounter' variable declaration: myCounter ::= { someBase 1 } myCounter.c32 ::= { myCounter 0 1 } myCounter.c64 ::= { myCounter 0 2 } myCounter.c32pair ::= { myCounter 0 3 } myCounter.c32pair.c32low ::= { myCounter 0 3 0 1 } myCounter.c32pair.c32hi ::= { myCounter 0 3 0 2 } Note 2) Even though only one node of a UNION can be instantiated at any given time, a GetNext Request for a UNION which contains other complex data objects can cause multiple instances to be returned from that sub- tree, as with the 'c32low' and 'c32hi' SCALARs in the example above. Note 3) Only the STATUS clauses for SCALAR data object definitions are relevant for compliance section usage. However, the above example raises issues regarding a complex data object which contains a mixture of current, deprecated, and obsolete SCALARs. (Is the STATUS of the GenericCounter UNION itself current or deprecated?) 5.7. AUGMENTS for Data Structures SMIv2 allows for MIB tables (SEQUENCEs) to be conceptually extended over time, without touching the original MIB table definition. This is usually done to avoid editing a 'stable' RFC, and it causes related objects of the same conceptual row to be spread across different MIB Expires May 5, 2002 [Page 15] Internet Draft SMI Data Structures November 5, 2001 sub-trees. In SMI-DS, the concept of AUGMENTS is preserved and adapted for use with complex data objects, instead of SEQUENCE definitions. The following examples demonstrate how each of the complex data object types can be augmented over time in a manner that is consistent with the semantics of SMIv2, except that the naming containment is preserved for the augmenting objects. An AUGMENTS can be defined without containing any objects, for placeholder purposes only. Just as with SMIv2, SCALAR objects cannot be augmented. 5.7.1. STRUCT AUGMENTS Example The AUGMENTS clause is applied to a STRUCT TYPEDEF in order to add additional fields to a base STRUCT type, instead of redefining the STRUCT type. The following trivial example shows how a 2 dimensional point might be augmented to represent a 3 dimensional point. TYPEDEF STRUCT Point { DESCRIPTION "A 2 dimensional point." SCALAR x { SYNTAX Unsigned32 MAX-ACCESS read-only STATUS current DESCRIPTION "The X-axis coordinate value for the point." } ::= 1 SCALAR y { SYNTAX Unsigned32 MAX-ACCESS read-only STATUS current DESCRIPTION "The Y-axis coordinate value for the point." } ::= 2 } AUGMENTS STRUCT Point { DESCRIPTION "Adds 1 more coordinate for a 3 dimensional point." Expires May 5, 2002 [Page 16] Internet Draft SMI Data Structures November 5, 2001 SCALAR z { SYNTAX Unsigned32 MAX-ACCESS read-only STATUS current DESCRIPTION "The Z-axis coordinate value for the point." } ::= 1 } ::= 1 STRUCT myPoint { SYNTAX Point STATUS current DESCRIPTION "An example variable instance of a point." } ::= { someBase 1 } Note 1) The OBJECT IDENTIFIER values for each of the fields in the 'myPoint' variable are listed below. For an agent which supports only the base type, without the augmentation, the following OBJECT IDENTIFIERs would be defined: myPoint ::= { someBase 1 } myPoint.x ::= { myPoint 0 1 } myPoint.y ::= { myPoint 0 2 } For an agent which supports the base type with this augmentation, the following OBJECT IDENTIFIER would also be defined: myPoint.z ::= { myPoint 1 1 } Note 2) Augmentations have to be assigned a relative root within the parent data structure, and also that augmentations cannot be defined for other augmentations. Only one level of AUGMENTS is supported, but up to 4 billion (minus 1) different augmentations for the same data type can be defined. Since AUGMENTS are used relatively rarely, and usually in a controlled way, it is not unreasonable to coordinate the augmentation node identifiers for each augmented TYPEDEF. Although the OID namespace allows for 4 billion augmentations, in actual usage the total number of AUGMENTS clauses for a given data type will be much closer to 4. Note 3) A GetNext or GetBulk sweep of 'myPoint' object would return all the fields in the same sub-tree, allowing the agent support for the augmentation to be easily discovered by an application. Expires May 5, 2002 [Page 17] Internet Draft SMI Data Structures November 5, 2001 Note 4) Only TYPEDEFs can be augmented, not variable declarations. This eliminates the implementation complexity of managing different namespace definitions for each complex data object definition. It is recommended that data object definitions be made using a TYPEDEF, rather than with an 'inline' complex object declaration, in order to allow for future augmentations to the data object. 5.7.2. UNION AUGMENTS Example The AUGMENTS clause is applied to the UNION data object in a similar manner as a STRUCT, in order to define additional UNION choices without redefining the data type. Only one node defined in a UNION (regardless of the number of augmentations) is allowed to be instantiated at any given time. The following trivial example shows how the InetAddressUnion type (defined above) might be augmented to add new InetAddress types defined in the RFC 2851 update draft [INET_TC]. Note that just as with SMIv2, it is up to the MIB designer(s) to decide whether to edit a base data type or augment it instead. This example is not meant to suggest that AUGMENTS should have been used in the case of the InetAddress, even if that were possible with SMIv2. -- see the Usage Examples section for the TYPEDEF for -- the InetAddressUnion type AUGMENTS UNION InetAddressUnion { DESCRIPTION "Adding two InetAddress types to match new InetAddressType enumerations." SCALAR ipv4zAddr { SYNTAX InetAddressIPv4z MAX-ACCESS read-only STATUS current DESCRIPTION "Represents an IPv4 Internet address and its zone index. The associated InetAddressType object value is 'ipv4z(3)'." } ::= 1 SCALAR ipv6zAddr { SYNTAX InetAddressIPv6z MAX-ACCESS read-only STATUS current Expires May 5, 2002 [Page 18] Internet Draft SMI Data Structures November 5, 2001 DESCRIPTION "Represents an IPv6 Internet address and its zone index. The associated InetAddressType object value is 'ipv6z(4)'." } ::= 2 } ::= 1 -- variable declarations from previous example STRUCT myAddress { SYNTAX HostInetAddress STATUS current DESCRIPTION "Internet address of this host." } ::= { someBase 1 } UNION newAddress { SYNTAX InetAddressUnion STATUS current DESCRIPTION "Example of the new way to represent a union variable, without the use of an associated InetAddressType object." } ::= { someBase 2 } Note 1) The following table lists the OBJECT IDENTIFIER component values for each of the fields in the 'myAddress' and 'newAddress' variables in the example above. For an agent which supports only the base type, without the augmentation, the following OBJECT IDENTIFIERs would be defined: myAddress ::= { someBase 1 } myAddress.addrType ::= { myAddress 0 1 } myAddress.addr ::= { myAddress 0 2 } myAddress.addr.ipUnknown ::= { myAddress 0 2 0 1 } myAddress.addr.ipv4Addr ::= { myAddress 0 2 0 2 } myAddress.addr.ipv6Addr ::= { myAddress 0 2 0 3 } myAddress.addr.dnsAddr ::= { myAddress 0 2 0 4 } newAddress ::= { someBase 2 } newAddress.ipUnknown ::= { newAddress 0 1 } newAddress.ipv4Addr ::= { newAddress 0 2 } newAddress.ipv6Addr ::= { newAddress 0 3 } newAddress.dnsAddr ::= { newAddress 0 4 } Expires May 5, 2002 [Page 19] Internet Draft SMI Data Structures November 5, 2001 For an agent which supports the base type with the augmentation, the following additional OBJECT IDENTIFIERs would be defined: myAddress.addr.ipv4zAddr ::= { myAddress 0 2 1 1 } myAddress.addr.ipv6zAddr ::= { myAddress 0 2 1 2 } newAddress.ipv4zAddr ::= { newAddress 1 1 } newAddress.ipv6zAddr ::= { newAddress 1 2 } 5.7.3. ARRAY AUGMENTS Example The AUGMENTS clause is applied to an ARRAY TYPEDEF in order to add additional fields to a base ARRAY type, instead of redefining the ARRAY TYPEDEF. It is similar to a traditional SMIv2 SEQUENCE AUGMENTS, except naming containment is preserved and the augmentations are not limited to base type objects. The INDEX clause of an ARRAY macro cannot be augmented, to reduce implementation complexity. Instead, a new TYPEDEF has to be defined or the existing TYPEDEF has to be edited (just like SMIv2). The following trivial example shows how some high-capacity counters and time-related attributes might be added to an existing array of packet statistics. TYPEDEF ARRAY InetHostStats { DESCRIPTION "Example of a IP host stats table." INDEX { SYNTAX InterfaceIndex -- range of the INDEX SIZE (0..2147483647) -- range of the instances DESCRIPTION "The interface source for these statistics." } INDEX { SYNTAX InetAddressType SIZE (0..65535) DESCRIPTION "The IP address type for the array entry. The InetAddressType values 'unknown(1)' and 'dns(16)' are not allowed." } Expires May 5, 2002 [Page 20] Internet Draft SMI Data Structures November 5, 2001 INDEX { SYNTAX InetAddress SIZE (0..65535) DESCRIPTION "The IP address for the array entry." } SCALAR inPkts { SYNTAX Counter32 MAX-ACCESS read-only STATUS current DESCRIPTION "The number of packets received by the specified host on the specified interface." } ::= 1 SCALAR outPkts { SYNTAX Counter32 MAX-ACCESS read-only STATUS current DESCRIPTION "The number of packets transmitted by the specified host on the specified interface." } ::= 2 SCALAR inOctets { SYNTAX Counter32 MAX-ACCESS read-only STATUS current DESCRIPTION "The number of octets received by the specified host on the specified interface." } ::= 3 SCALAR outOctets { SYNTAX Counter32 MAX-ACCESS read-only STATUS current DESCRIPTION "The number of octets transmitted by the specified host on the specified interface." } ::= 4 } -- a struct containing additional information for each Expires May 5, 2002 [Page 21] Internet Draft SMI Data Structures November 5, 2001 -- set of counters TYPEDEF STRUCT HostStatsTimeData { DESCRIPTION "Add some times related objects associated with each set of counters." SCALAR createTime { SYNTAX TimeStamp MAX-ACCESS read-only STATUS current DESCRIPTION "The value of sysUpTime at the time this set of counters was created." } ::= 1 SCALAR updateInterval { SYNTAX Unsigned32 UNITS "milliseconds" MAX-ACCESS read-only STATUS current DESCRIPTION "The average amount of time that elapses between internal polling intervals for this counter set. A value of zero indicates that the counter set values are not polled internally." } ::= 2 } -- Augment the InetHostStats TYPEDEF with 4 counters and -- a HostStatsTimeData STRUCT AUGMENTS ARRAY InetHostStats { DESCRIPTION "Adds HC counters and additional information to the statistics entry." SCALAR inHCPkts { SYNTAX Counter64 MAX-ACCESS read-only STATUS current DESCRIPTION "The number of packets received by the specified host on the specified interface." } ::= 1 Expires May 5, 2002 [Page 22] Internet Draft SMI Data Structures November 5, 2001 SCALAR outHCPkts { SYNTAX Counter64 MAX-ACCESS read-only STATUS current DESCRIPTION "The number of packets transmitted by the specified host on the specified interface." } ::= 2 SCALAR inHCOctets { SYNTAX Counter64 MAX-ACCESS read-only STATUS current DESCRIPTION "The number of octets received by the specified host on the specified interface." } ::= 3 SCALAR outHCOctets { SYNTAX Counter64 MAX-ACCESS read-only STATUS current DESCRIPTION "The number of octets transmitted by the specified host on the specified interface." } ::= 4 STRUCT timeData { SYNTAX HostStatsTimeData STATUS current DESCRIPTION "Additional time-related information." } ::= 5 } ::= 1 -- variable declaration for a InetHostStats data collection ARRAY ipStats { SYNTAX InetHostStats MAX-ACCESS read-only STATUS current DESCRIPTION "The IP host statistics for this network device." } ::= { someBase 1 } Expires May 5, 2002 [Page 23] Internet Draft SMI Data Structures November 5, 2001 Note 1) The following example lists the OBJECT IDENTIFIER values for each of the fields in the 'myStats' variable in the example above. For an agent which supports only the base type, without the augmentation, the following OBJECT IDENTIFIERs would be defined. In this example only the instances for interface 17, InetAddressType 'ipv4(1)', and InetAddress '192.168.0.1' are shown. ipStats ::= { someBase 1 } ipStats[17] ::= { ipStats 17 } ipStats[17][1] ::= { ipStats 17 1 } ipStats[17][1][192.168.0.1] ::= { ipStats 17 1 4 192 168 0 1 } ipStats[17][1][192.168.0.1].inPkts ::= { ipStats 17 1 4 192 168 0 1 0 1 } ipStats[17][1][192.168.0.1].outPkts ::= { ipStats 17 1 4 192 168 0 1 0 2 } ipStats[17][1][192.168.0.1].inOctets ::= { ipStats 17 1 4 192 168 0 1 0 3 } ipStats[17][1][192.168.0.1].outOctets ::= { ipStats 17 1 4 192 168 0 1 0 4 } For an agent which supports the base type with the augmentation, the following additional OBJECT IDENTIFIERs would be defined: ipStats[17][1][192.168.0.1].inHCPkts ::= { ipStats 17 1 4 192 168 0 1 1 1 } ipStats[17][1][192.168.0.1].outHCPkts ::= { ipStats 17 1 4 192 168 0 1 1 2 } ipStats[17][1][192.168.0.1].inHCOctets ::= { ipStats 17 1 4 192 168 0 1 1 3 } ipStats[17][1][192.168.0.1].outHCOctets ::= { ipStats 17 1 4 192 168 0 1 1 4 } ipStats[17][1][192.168.0.1].timeData ::= { ipStats 17 1 4 192 168 0 1 1 5 } Expires May 5, 2002 [Page 24] Internet Draft SMI Data Structures November 5, 2001 ipStats[17][1][192.168.0.1].timeData.createTime ::= { ipStats 17 1 4 192 168 0 1 1 5 0 1 } ipStats[17][1][192.168.0.1].timeData.updateInterval ::= { ipStats 17 1 4 192 168 0 1 1 5 0 2 } Note 1) Although arbitrary levels of nested containment are theoretically possible, SNMP varbind size limitations set practical limits on the complexity of data object definitions, especially ARRAYs. Note 2) The SPPI provides an EXTENDS mechanism, which allows new SCALAR objects to be defined in a table which conceptually adds INDEX components to an existing table. This mechanism is accomplished by defining an additional ARRAY (with the new INDEX components and objects) in an AUGMENTS for an ARRAY TYPEDEF. 5.8. Complete MODULE Example The following example shows a complete MIB module, converted from the Remote Monitoring Extensions for Differentiated Services document [DSMON-MIB]. Refer to that document to compare the SMIv2 and SMI-DS definitions for the same objects. -- the MODULE starts out differently than SMIv2 so MIB -- compilers can tell immediately the type of module MODULE DSMON-MIB { -- partial IMPORTS; only for the aggregation control objects IMPORTS { MODULE-IDENTITY, Integer32, Counter32 FROM SNMPv2-SMI MODULE-COMPLIANCE, OBJECT-GROUP FROM SNMPv2-CONF RowStatus, TimeStamp, TruthValue FROM SNMPv2-TC OwnerString, rmon FROM RMON-MIB SnmpAdminString FROM SNMP-FRAMEWORK-MIB Dscp FROM DIFFSERV-DSCP-TC } Expires May 5, 2002 [Page 25] Internet Draft SMI Data Structures November 5, 2001 -- the MODULE-IDENTITY macro is not changed at all dsmonMIB MODULE-IDENTITY LAST-UPDATED "200111050000Z" ORGANIZATION "IETF RMONMIB Working Group" CONTACT-INFO " Andy Bierman Cisco Systems, Inc. RMONMIB WG Chair and DSMON MIB Editor Postal: 170 West Tasman Drive San Jose, CA USA 95134 Tel: +1 408 527-3711 E-mail: abierman@cisco.com Send comments to Mailing list subscription info: http://www.ietf.org/mailman/listinfo/rmonmib " DESCRIPTION "This module defines Remote Monitoring MIB extensions for Differentiated Services enabled networks. RMON DIFFSERV DSCP statistics * Per Aggregation Group * Per Protocol Per Aggregation Group * Per Aggregation Group Per Host * Per Aggregation Group Per Host-Pair In order to maintain the RMON 'look-and-feel' and semantic consistency, some of the text from the RMON-2 and HC-RMON MIBs by Steve Waldbusser has been adapted for use in this MIB." REVISION "200111050000Z" DESCRIPTION "Initial version of the DSMON MIB module. This version published as RFC xxxx (to be assigned by the RFC Editor)." ::= { rmon 26 } -- a NODES clause is added to formalize and more easily find -- the OBJECT IDENTIFIER MIB root nodes defined in a MIB MODULE -- this list is allowed to be empty NODES { dsmonObjects OBJECT IDENTIFIER ::= { dsmonMIB 1 } Expires May 5, 2002 [Page 26] Internet Draft SMI Data Structures November 5, 2001 dsmonNotifications OBJECT IDENTIFIER ::= { dsmonMIB 2 } dsmonConformance OBJECT IDENTIFIER ::= { dsmonMIB 3 } dsmonAggObjects OBJECT IDENTIFIER ::= { dsmonObjects 1 } -- the following objects removed from the example dsmonStatsObjects OBJECT IDENTIFIER ::= { dsmonObjects 2 } dsmonPdistObjects OBJECT IDENTIFIER ::= { dsmonObjects 3 } dsmonHostObjects OBJECT IDENTIFIER ::= { dsmonObjects 4 } dsmonCapsObjects OBJECT IDENTIFIER ::= { dsmonObjects 5 } dsmonMatrixObjects OBJECT IDENTIFIER ::= { dsmonObjects 6 } } -- converted DsmonAggGroupIndex TC to a TYPEDEF TYPEDEF SCALAR DsmonAggGroupIndex { SYNTAX Integer32 (0..2147483647) STATUS current DESCRIPTION "This TC describes a data type which identifies a DSMON aggregation group, which is an arbitrary grouping of DSCP values, for monitoring purposes only. The range for this data type begins with zero (instead of one), to allow for a direct mapping between DSCP and aggregation group values." } -- converted DsmonAggProfileIndex TC to a TYPEDEF TYPEDEF SCALAR DsmonAggProfileIndex { SYNTAX Integer32 (1..2147483647) STATUS current DESCRIPTION "This TC describes a data type which identifies a DSMON aggregation profile, which is a set of aggregation group assignments for each of the 64 DSCP values, for a particular statistical collection." } -- -- this object could have been defined as an ARRAY, -- or wrappered (as it is) inside STRUCT definition, -- which can be extended over time. -- -- converted dsmonAggProfileTable Expires May 5, 2002 [Page 27] Internet Draft SMI Data Structures November 5, 2001 TYPEDEF STRUCT DsmonAggProfile { DESCRIPTION "Controls the setup of a single aggregation profile, for which every DSCP value MUST be configured into exactly one aggregation group. This object MUST NOT be modified if the dsmonAggControlLocked object is equal to 'true'. If the agent supports non-volatile configuration of this object, then upon system initialization, this object SHOULD be initialized with the saved values." ARRAY aggGroupMapping { DESCRIPTION "A set of 64 DSCP to Aggregation Group Index mappings." INDEX { SYNTAX Dscp SIZE (64) -- fixed array of 64 entries DESCRIPTION "The specific DSCP value which is configured in an aggregation group by this entry." } -- more INDEX clauses may be present, for multi-dimensional arrays SCALAR dsmonAggGroupIndex { SYNTAX DsmonAggGroupIndex MAX-ACCESS read-write STATUS current DESCRIPTION "The aggregation group which contains this DSCP value. Upon creation of a new sub-tree (set of 64 entries with the same dsmonAggControlIndex value) in this object, the agent SHOULD initialize all related instances of this object to the value zero. This object MUST NOT be modified if the dsmonAggControlLocked object is equal to 'true'." DEFVAL { 0 } } ::= 1 } ::= 1 } -- following is done as an inline array instead of a Expires May 5, 2002 [Page 28] Internet Draft SMI Data Structures November 5, 2001 -- separate struct definition (like DsmonAggProfile) for -- demonstration purposes -- converted dsmonAggGroupTable TYPEDEF ARRAY DsmonAggGroup { DESCRIPTION "Controls the setup of a single aggregation profile, for which every DSCP value MUST be configured into exactly one aggregation group. This object MUST NOT be modified if the dsmonAggControlLocked object is equal to 'true'. If the agent supports non-volatile configuration of this object, then upon system initialization, this object SHOULD be initialized with the saved values." INDEX { SYNTAX DsmonAggGroupIndex -- range of the INDEX SIZE (0..2147483647) -- range of the instances DESCRIPTION "The specific Aggregation Group which is represented group by each entry." } SCALAR dsmonAggGroupDescr { SYNTAX SnmpAdminString (SIZE(0..64)) MAX-ACCESS read-create STATUS current DESCRIPTION "An administratively assigned description of the aggregation group identified by this entry. Upon first creation of an instance of this object, the agent SHOULD set this object to the empty string. This object MUST NOT be modified if the associated dsmonAggGroupStatus object is equal to 'active', or the dsmonAggControlLocked object is equal to 'true'." } ::= 1 } -- converted dsmonAggControlTable Expires May 5, 2002 [Page 29] Internet Draft SMI Data Structures November 5, 2001 TYPEDEF STRUCT DsmonAggControl { DESCRIPTION "Provides an overall description and control point for a single aggregation control configuration. This object MUST NOT be modified if the dsmonAggControlLocked object is equal to 'true'." SCALAR dsmonAggControlDescr { SYNTAX SnmpAdminString (SIZE(0..64)) MAX-ACCESS read-create STATUS current DESCRIPTION "An administratively assigned description of the aggregation profile identified by this entry. Upon first creation of an instance of this object, the agent SHOULD set this object to the empty string. If the agent supports non-volatile storage, then this object SHOULD be re-initialized with its stored value after a system reboot. This object MUST NOT be modified if the associated dsmonAggControlStatus object is equal to 'active', or the dsmonAggControlLocked object is equal to 'true'." } ::= 1 STRUCT aggProfile { SYNTAX DsmonAggProfile STATUS current DESCRIPTION "A set of DSCP to Aggregation Group mappings." } ::= 2 ARRAY aggGroup { SYNTAX DsmonAggGroup STATUS current DESCRIPTION "An array of Aggregation Group descriptions." } ::= 3 SCALAR dsmonAggControlOwner { SYNTAX OwnerString MAX-ACCESS read-create STATUS current DESCRIPTION Expires May 5, 2002 [Page 30] Internet Draft SMI Data Structures November 5, 2001 "The entity that configured this object and is therefore using the resources assigned to it." } ::= 4 SCALAR dsmonAggControlStatus { SYNTAX RowStatus MAX-ACCESS read-create STATUS current DESCRIPTION "The status of this entire aggregation control object. An entry MUST NOT exist in the active state unless all objects in the entry have an appropriate value. This object MUST NOT be modified if the dsmonAggControlLocked object is equal to 'true'." } ::= 5 } -- -- variable declarations for the 4 scalars in this group -- SCALAR dsmonMaxAggGroups { SYNTAX Integer32 (2..64) MAX-ACCESS read-only STATUS current DESCRIPTION "The maximum number of aggregation groups that this agent can support. (Rest of text removed to keep the example shorter.)" } ::= { dsmonAggObjects 1 } SCALAR dsmonAggControlLocked { SYNTAX TruthValue MAX-ACCESS read-write STATUS current DESCRIPTION "Controls the setup of aggregation groups for this agent. (Rest of text removed to keep the example shorter.)" } ::= { dsmonAggObjects 2 } SCALAR dsmonAggControlChanges { SYNTAX Counter32 MAX-ACCESS read-only Expires May 5, 2002 [Page 31] Internet Draft SMI Data Structures November 5, 2001 STATUS current DESCRIPTION "This object counts the number of times the value of the dsmonAggControlLocked object has changed. (Rest of text removed to keep the example shorter.)" } ::= { dsmonAggObjects 3 } SCALAR dsmonAggControlLastChangeTime { SYNTAX TimeStamp MAX-ACCESS read-only STATUS current DESCRIPTION "This object identifies the value of sysUpTime at the moment the dsmonAggControlLocked object was last modified. (Rest of text removed to keep the example shorter.)" } ::= { dsmonAggObjects 4 } -- finishing the dsmonAggControlTable by allowing multiple -- instances of an aggregation control block ARRAY dsmonAggProfiles { STATUS current DESCRIPTION "A collection of DSMON aggregation control profiles. This object MUST NOT be modified if the dsmonAggControlLocked object is equal to 'true'. If the agent supports non-volatile configuration of this object, then upon system initialization, this object SHOULD be initialized with the saved values." INDEX { SYNTAX DsmonAggProfileIndex SIZE (1..2147483647) -- variable sized array DESCRIPTION "The specific Aggregation Profile which is represented group by each entry." } STRUCT aggControl { SYNTAX DsmonAggControl STATUS current DESCRIPTION "The DSMON Aggregation Control entry for each profile." } ::= 1 Expires May 5, 2002 [Page 32] Internet Draft SMI Data Structures November 5, 2001 } ::= { dsmonAggObjects 5 } -- No NOTIFICATION-TYPE macros defined in this module -- Compliance section (unchanged from SMIv2) dsmonAggControlCompliance MODULE-COMPLIANCE STATUS current DESCRIPTION "Example compliance for the aggregation control portion of the DSMON-MIB module." MODULE -- this module MANDATORY-GROUPS { dsmonAggControlGroup } ::= { dsmonCompliances 1 } dsmonAggControlGroup OBJECT-GROUP OBJECTS { dsmonMaxAggGroups, dsmonAggControlLocked, dsmonAggControlChanges, dsmonAggControlLastChangeTime, dsmonAggControlDescr, dsmonAggControlOwner, dsmonAggControlStatus, dsmonAggGroupIndex, dsmonAggGroupDescr } STATUS current DESCRIPTION "A collection of objects used to configure and manage aggregation groups for DSMON collection purposes." ::= { dsmonGroups 1 } } -- END DSMON-MIB MODULE Note 1) The following example shows the difference between SMIv2 naming and SMI-DS naming, for the OBJECT IDENTIFIERS in the DSMON-MIB module example above. Object Instance Examples ------------------------------ O=Old (SMIv2), N=New (SMI-DS) dsmonAggGroup scalars: Expires May 5, 2002 [Page 33] Internet Draft SMI Data Structures November 5, 2001 dsmonMaxAggGroups O: dsmonAggObjects.1.0 N: dsmonAggObjects.1 dsmonAggControlLocked O: dsmonAggObjects.2.0 N: dsmonAggObjects.2 dsmonAggControlChanges O: dsmonAggObjects.3.0 N: dsmonAggObjects.3 dsmonAggControlLastChangeTime O: dsmonAggObjects.4.0 N: dsmonAggObjects.4 dsmonAggControlTable example for row 77: dsmonAggControlDescr O: dsmonAggObjects.5.1.2.77 N: dsmonAggObjects.5.77.0.1.0.1 dsmonAggControlOwner O: dsmonAggObjects.5.1.3.77 N: dsmonAggObjects.5.77.0.1.0.4 dsmonAggControlStatus O: dsmonAggObjects.5.1.3.77 N: dsmonAggObjects.5.77.0.1.0.5 dsmonAggProfileTable example for row 77.22: dsmonAggGroupIndex O: dsmonAggObjects.6.1.2.77.22 N: dsmonAggObjects.5.77.0.1.0.2.0.1.22.0.1 dsmonAggGroupTable example for row 77.44: dsmonAggGroupDescr O: dsmonAggObjects.7.1.1.77.44 N: dsmonAggObjects.5.77.0.1.0.3.44.0.1 dsmonAggGroupStatus O: dsmonAggObjects.7.1.2.77.44 N: not needed because dsmonAggControlStatus controls the entire object Expires May 5, 2002 [Page 34] Internet Draft SMI Data Structures November 5, 2001 6. Definitions The follow sections specify the SMI Data Structures syntax and semantics. [ed. -- this section is intentionally incomplete, because the first draft is meant to introduce the SMI Data Structures concepts, syntax, and examples. Complete specification to the level of SMIv2 is TBD.] 6.1. Namespaces The type names and variable names used in SMI Data Structures are contained is the same namespace, similar to the SMIv2 namespace for OBJECT-TYPE descriptors, but not shared with SMIv2. Ideally, every data object containment level would define its own namespace, in a truly hierarchical fashion. However, this would not be compatible with existing SMIv2 practices, and would require changes to the IMPORTS, MODULE-COMPLIANCE and OBJECT-GROUP macros to support. [ed. - further definition of namespaces TBD] 6.2. Syntax [ed. - the following ad-hoc syntax definition is a first-pass attempt, and obviously needs re-writing and a detailed mappings and rules section for each construct.] ::= MODULE "{" [] [ ...] "}" ::= IMPORTS "{" [ ...] "}" Expires May 5, 2002 [Page 35] Internet Draft SMI Data Structures November 5, 2001 ::= (same as SMIv2, except last one does not end with a semi-colon) ::= (same as SMIv2) ::= NODES "{" [ ...] "}" ::= (same as SMIv2 OBJECT IDENTIFIER declaration) ::= ( | | ) ::= ( | | | | ) ::= ( | | | ) ::= TYPEDEF ::= SCALAR "{" [] Expires May 5, 2002 [Page 36] Internet Draft SMI Data Structures November 5, 2001 [] [] "}" ::= (same rules as for SMIv2 TEXTUAL-CONVENTION descriptors) ::= (same as SMIv2) ::= (same as SMIv2) ::= (same as SMIv2) ::= (same as SMIv2) ::= (same as SMIv2) ::= (same as SMIv2) ::= (same as SMIv2) ::= SCALAR "{" [] [] Expires May 5, 2002 [Page 37] Internet Draft SMI Data Structures November 5, 2001 [] "}" ::= ::= (same rules as for SMIv2 OBJECT-TYPE descriptors) ::= an INTEGER in the range (1..4294967295) ::= SCALAR "{" [] [] [] "}" ::= ::= (same as SMIv2) ::= TYPEDEF ::= ARRAY "{" [] [ ...] [ ...] "}" ::= INDEX [] "{" [] Expires May 5, 2002 [Page 38] Internet Draft SMI Data Structures November 5, 2001 [] "}" -- size clause is the number of allowed instances, not just max ::= "(" ( | ) ")" ::= INTEGER between (1 .. 2147483647) ::= ".." (where the second must be larger than the first ) ::= INTEGER between (0 .. 2147483647) ::= ( | | | | | | | ) ::= ARRAY "{" [] "}" ::= ::= ARRAY "{" Expires May 5, 2002 [Page 39] Internet Draft SMI Data Structures November 5, 2001 [] "}" ::= ::= TYPEDEF ::= UNION "{" [] [ ...] "}" ::= UNION "{" [] "}" ::= ::= UNION "{" [] "}" ::= ::= TYPEDEF ::= STRUCT "{" [] Expires May 5, 2002 [Page 40] Internet Draft SMI Data Structures November 5, 2001 [ ...] "}" ::= STRUCT "{" [] "}" ::= ::= STRUCT "{" [] "}" ::= ::= AUGMENTS "{" [ ...] "}" ::= ::= ( ARRAY | UNION | STRUCT ) ::= (same as SMIv2) ::= (same as SMIv2) 7. Intellectual Property The IETF takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain Expires May 5, 2002 [Page 41] Internet Draft SMI Data Structures November 5, 2001 to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on the IETF's procedures with respect to rights in standards-track and standards- related documentation can be found in BCP-11. Copies of claims of rights made available for publication and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementors or users of this specification can be obtained from the IETF Secretariat. The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights which may cover technology that may be required to practice this standard. Please address the information to the IETF Executive Director. 8. Acknowledgements Portions of the existing SMI RFCs, SMIng drafts, and the ANSI C Programming Language inspired many of the concepts discussed in this memo. 9. References [DSMON-MIB] Bierman, A., "Remote Monitoring MIB Extensions for Differentiated Services", Work in progress (draft-ietf-rmonmib-dsmon-mib-08.txt), Cisco Systems, Inc., October 2001. [INET_TC] Daniele, M., Haberman, B., Routhier, S., and J. Schoenwaelder, "Textual Conventions for Internet Network Addresses", Work in progress (draft-ietf-ops-rfc2851-update-05.txt), Consultant, Nortel Networks, Wind River Systems, Inc., TU Braunschweig, October 2001. [RFC1155] Rose, M., and K. McCloghrie, "Structure and Identification of Management Information for TCP/IP-based Internets", RFC 1155, Performance Systems International, Hughes LAN Systems, May 1990. [RFC1157] Case, J., Fedor, M., Schoffstall, M., and J. Davin, "Simple Network Management Protocol", RFC 1157, SNMP Research, Performance Systems Expires May 5, 2002 [Page 42] Internet Draft SMI Data Structures November 5, 2001 International, Performance Systems International, MIT Laboratory for Computer Science, May 1990. [RFC1212] Rose, M., and K. McCloghrie, "Concise MIB Definitions", RFC 1212, Performance Systems International, Hughes LAN Systems, March 1991. [RFC1215] M. Rose, "A Convention for Defining Traps for use with the SNMP", RFC 1215, Performance Systems International, March 1991. [RFC1901] SNMPv2 Working Group, Case, J., McCloghrie, K., Rose, M., and S. Waldbusser, "Introduction to Community-based SNMPv2", RFC 1901, SNMP Research, Inc., Cisco Systems, Inc., Dover Beach Consulting, Inc., International Network Services, January 1996. [RFC1905] SNMPv2 Working Group, Case, J., McCloghrie, K., Rose, M., and S. Waldbusser, "Protocol Operations for Version 2 of the Simple Network Management Protocol (SNMPv2)", RFC 1905, SNMP Research, Inc., Cisco Systems, Inc., Dover Beach Consulting, Inc., International Network Services, January 1996. [RFC1906] SNMPv2 Working Group, Case, J., McCloghrie, K., Rose, M., and S. Waldbusser, "Transport Mappings for Version 2 of the Simple Network Management Protocol (SNMPv2)", RFC 1906, SNMP Research, Inc., Cisco Systems, Inc., Dover Beach Consulting, Inc., International Network Services, January 1996. [RFC2026] Bradner, S., "The Internet Standards Process -- Revision 3", RFC 2026, Harvard University, October, 1996. [RFC2119] S. Bradner, "Key words for use in RFCs to Indicate Requirement Levels" RFC 2119, Harvard University, March 1997. [RFC2570] Case, J., Mundy, R., Partain, D., and B. Stewart, "Introduction to Version 3 of the Internet-standard Network Management Framework", RFC 2570, SNMP Research, Inc., TIS Labs at Network Associates, Inc., Ericsson, Cisco Systems, April 1999. Expires May 5, 2002 [Page 43] Internet Draft SMI Data Structures November 5, 2001 [RFC2571] Harrington, D., Presuhn, R., and B. Wijnen, "An Architecture for Describing SNMP Management Frameworks", RFC 2571, Cabletron Systems, Inc., BMC Software, Inc., IBM T. J. Watson Research, April 1999. [RFC2572] Case, J., Harrington D., Presuhn R., and B. Wijnen, "Message Processing and Dispatching for the Simple Network Management Protocol (SNMP)", RFC 2572, SNMP Research, Inc., Cabletron Systems, Inc., BMC Software, Inc., IBM T. J. Watson Research, April 1999. [RFC2573] Levi, D., Meyer, P., and B. Stewart, "SNMPv3 Applications", RFC 2573, SNMP Research, Inc., Secure Computing Corporation, Cisco Systems, April 1999. [RFC2574] Blumenthal, U., and B. Wijnen, "User-based Security Model (USM) for version 3 of the Simple Network Management Protocol (SNMPv3)", RFC 2574, IBM T. J. Watson Research, April 1999. [RFC2575] Wijnen, B., Presuhn, R., and K. McCloghrie, "View-based Access Control Model (VACM) for the Simple Network Management Protocol (SNMP)", RFC 2575, IBM T. J. Watson Research, BMC Software, Inc., Cisco Systems, Inc., April 1999. [RFC2578] McCloghrie, K., Perkins, D., Schoenwaelder, J., Case, J., Rose, M., and S. Waldbusser, "Structure of Management Information Version 2 (SMIv2)", RFC 2578, STD 58, Cisco Systems, SNMPinfo, TU Braunschweig, SNMP Research, First Virtual Holdings, International Network Services, April 1999. [RFC2579] McCloghrie, K., Perkins, D., Schoenwaelder, J., Case, J., Rose, M., and S. Waldbusser, "Textual Conventions for SMIv2", RFC 2579, STD 58, Cisco Systems, SNMPinfo, TU Braunschweig, SNMP Research, First Virtual Holdings, International Network Services, April 1999. [RFC2580] McCloghrie, K., Perkins, D., Schoenwaelder, J., Case, J., Rose, M., and S. Waldbusser, "Conformance Statements for SMIv2", RFC 2580, STD 58, Cisco Systems, SNMPinfo, TU Braunschweig, SNMP Research, Expires May 5, 2002 [Page 44] Internet Draft SMI Data Structures November 5, 2001 First Virtual Holdings, International Network Services, April 1999. [RFC2851] Daniele, M., Haberman, B., Routhier, S., and J. Schoenwaelder, "Textual Conventions for Internet Network Addresses", RFC 2851, Compaq Computer Corporation, Nortel Networks, Wind River Systems, Inc., TU Braunschweig, June 2000. [SMING-OBJ] Elliot, C., Harrington, D., Jason, J., Schoenwaelder, J., Strauss, F., and W. Weiss, "SMIng Objectives", Work in progress (draft-ietf- sming-reqs-06.txt), Cisco Systems, Enterasys Networks, Intel Corporation, TU Braunschweig, Ellacoya Networks, October 2001. 10. Security Considerations This document defines a structure for management data and therefore does not expose any management information from a particular device. However, accessible data objects defined with the mechanisms defined in this document should be given the same security consideration as objects specified with SMIv2, when being transferred with SNMP. SNMPv1 by itself is not a secure environment. Even if the network itself is secure (for example by using IPSec), even then, there is no control as to who on the secure network is allowed to access and GET/SET (read/change/create/delete) the objects in this MIB. It is recommended that the implementors consider the security features as provided by the SNMPv3 framework. Specifically, the use of the User- based Security Model RFC 2574 [RFC2574] and the View-based Access Control Model RFC 2575 [RFC2575] is recommended. It is then a customer/user responsibility to ensure that the SNMP entity giving access to an instance of this MIB, is properly configured to give access to the objects only to those principals (users) that have legitimate rights to indeed GET or SET (change/create/delete) them. 11. Author's Address Andy Bierman Cisco Systems, Inc. 170 West Tasman Drive San Jose, CA USA 95134 Phone: +1 408-527-3711 Email: abierman@cisco.com Expires May 5, 2002 [Page 45] Internet Draft SMI Data Structures November 5, 2001 12. Full Copyright Statement Copyright (C) The Internet Society (2001). All Rights Reserved. This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to the Internet Society or other Internet organizations, except as needed for the purpose of developing Internet standards in which case the procedures for copyrights defined in the Internet Standards process must be followed, or as required to translate it into languages other than English. The limited permissions granted above are perpetual and will not be revoked by the Internet Society or its successors or assigns. This document and the information contained herein is provided on an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Expires May 5, 2002 [Page 46]