Internet Engineering Task Force F. DaCosta INTERNET-DRAFT January 20, 2000 draft-dacosta-snmp-object-dependency-00.txt Expires July 2000 MIB Object Dependency Expression (MODEX) Status of this Memo This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of 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. Abstract An SNMP MIB models a managed device as if every one of its objects may be atomically read and changed. In reality, many of a device's objects may be interdependent. Typically such dependencies are either undocumented or simply noted in MIB comments or DESCRIPTION clauses. This draft defines a syntax to capture MIB object dependencies and proposes tools for real-world implementation. This document is a product of an individual. Comments are solicited and should be addressed to the author. The concepts described in this document are presented to the open internetworking community for comment and critique. Milgo Solutions, Inc. reserves the right, however, to develop and field implementations of this technology and to market products for profit that derive from these concepts, as may other companies. DaCosta Expires July 2000 [Page 1] Internet Draft draft-dacosta-snmp-object-dependency-00.txt January 20, 2000 1. Introduction MODEX stands for MIB Object Dependency Expression. It is a new way to quantify and describe without ambiguity the dependent interrelationships between MIB objects. It applies to the world of networked devices that are managed by the Simple Network Management Protocol (SNMP), each of whose attributes are expressed in a Management Information Base (MIB) document. MIBs model the attributes of an SNMP device as a series of objects which may be read or written by a management application. MIB objects may either stand alone or be related to others in a table. There are a few other semantic MIB conventions to relate object to object. MIBs cannot, however, comprehensively and syntactically represent all dependencies between the objects. When such dependencies are treated in a MIB, it is only in the form of human-readable comments and DESCRIPTION clauses, and in no standard format. MODEX purports to capture the dependencies between MIB objects in an unambiguous and syntactic form. Using MODEX, the SNMP device agent developer can conceptualize, then publish accurately, the dependent relationships within his agent. Using MODEX, the SNMP management application developer can understand these dependencies and, more importantly, can write code to interpret the dependencies programmatically. 2. Governing Concepts 2.1 What Are Dependencies? Regarding MIB objects, a dependency is a relationship between two or more objects that constrains those objects' behavior. Many objects in a MIB may be independent, meaning that they can be read and changed without reference to the state of other objects. Many other objects may be dependent, meaning that their semantics cannot be wholly known without knowledge of other objects. A common example of an independent object is MIB2 sysContact. The user can set and read this string freely; its characteristics will not change if another object changes. A common example of a dependent object might be a data speed object. The possible speed of a port may depend on the protocol being run, or perhaps on bandwidth sharing options, or on flow-control or framing settings. DaCosta Expires July 2000 [Page 2] Internet Draft draft-dacosta-snmp-object-dependency-00.txt January 20, 2000 2.2 How Do We Find Out About Dependencies? Unfortunately for SNMP engineers, the ASN.1 syntax of MIBs cannot capture or represent object dependency. The operation of SNMP as a raw protocol, with its SETs and GETs, implies that objects are independent and can be accessed atomically at any time. Certain dependencies have been captured in ASN.1 conventions. For instance, * The RowStatus conventions for table row instantiation do a fair job of handling the ambiguities associated with objects that must all be created and defaulted in an atomic operation. * The convention of paired adminStatus and operStatus objects offers a mechanism to deal with the fact that an object may take a long time to change, too long to wait for a confirmation. The first object starts the change; the second object can be polled to verify the change. Still, most MIB clauses assume a static semantic for each object. If an INTEGER specifies a range, there is no way to indicate that the range may suddenly narrow based on a change in protocol or speed or features. If an INTEGER presents an enumerated list of valid values, there is no way to indicate that some choices are only valid some of the time. There are thus only two time-honored ways that an SNMP developer can discover dependencies. One is by reading the DESCRIPTION clauses, which can disclose any object relationships. The other is by external disclosure, either as a separate document, or (all too often) by word of mouth when engineers cope with the actual behavior of the device. DaCosta Expires July 2000 [Page 3] Internet Draft draft-dacosta-snmp-object-dependency-00.txt January 20, 2000 2.3 Can Dependencies Be Classed? Before a better means of handling dependencies can be realized, some attempt must be made to categorize dependent behavior. The following is a list of the most common kinds of dependency. 2.3.1 Access Dependency An object may be modifiable, but only while another object maintains a certain value. 2.3.2 Order Dependency An object may be modifiable, but only after another object is changed. The dependency may even be value-specific; one object may not be able to assume certain values until another object has assumed certain values. 2.3.3 Activation Dependency An object may be modifiable, but its meaning may not actually take effect immediately. It may require time, or a module reset, or another object to assume a certain value. 2.3.4 Range Dependency An object may be modifiable, but the valid range of values may change based on the state of another object. 2.3.5 Choice Dependency An object may be modifiable, but the valid enumerable options may change based on the state of another object. DaCosta Expires July 2000 [Page 4] Internet Draft draft-dacosta-snmp-object-dependency-00.txt January 20, 2000 2.4 Can Dependencies Extend Beyond Objects? Our definition of dependency is partially deficient, in that it focuses on MIB objects that are affected by other MIB objects. However, MIB objects can be subject to conditions that are not modeled in MIB objects and thus not soluble strictly through SNMP calls. For instance, an object may be defined to be modifiable only when another device in the network is online and in communication with the target device. This condition may not be verifiable by an SNMP application. Sometimes MIB objects are supposed to be set to certain values based on the overall application of the device in a network, or else the device will simply not do the job expected of it. This "external knowledge" of the desired behavior of the device cannot be resolved by MIB references. Yet a good configuration tool should constrain the operator's choices based on the use of the product. In defining strategies to resolve dependencies in a configuration tool, this subclass of external dependencies is possibly only soluble by user input. That is, the tool must prompt the operator for additional information, stating an assumption and asking for confirmation to act upon it. 2.5 How Do Devices React To Dependency-Related Failures? Since MIB object dependency is not a formally defined aspect of SNMP, agent developers have been free to react to the situation in haphazard fashion. The result, again, is that the management application developer has no reliable means to determine what problem the agent is wrestling with. Suppose that a management application has just performed an SNMP SET on an object, telling it to assume a valid enumerated selection documented in the MIB. Further suppose that the object cannot assume the new value because of a dependency. The agent has many possible responses, none enlightening: - Simply ignore the request and return no GET-RESPONSE reply - Return some sort of error, usually genError - Return success but do not change the object value - Return success and change the object value, but ignore the new value 3. The Purpose Of MODEX MODEX purports to capture the dependencies between MIB objects in an unambiguous and syntactic form. Using MODEX, the SNMP device agent developer can conceptualize, then publish accurately, the dependent relationships within his agent. Using MODEX, the SNMP management application developer can understand these dependencies and, more importantly, can write code to interpret the dependencies programmatically. DaCosta Expires July 2000 [Page 5] Internet Draft draft-dacosta-snmp-object-dependency-00.txt January 20, 2000 4. The Components Of MODEX 4.1 MODEX Template The primary vehicle for MODEX technology is the MODEX template. The template is the simplest rendition of a collection of MIB object dependencies, expressed in an unambiguous syntax. In practice, the template is generated by the developer of the SNMP agent for a managed device. At the same time that the MIBs are developed, the template is also written. The agent developer can use the format of the template to aid in initial development of the agent, much the same way that MIB syntax helps to limit and guide the implementation of SNMP objects. (Neither the agent nor the MIB predates the other; they tend to be developed together, reflexively. So it is with the MODEX template.) The agent developer publishes the MIBs and the MODEX template together, as a comprehensive description of his agent's behavior. If no other component of MODEX is pursued, this alone is a useful procedure. Other departments, including Technical Writing, Training, Testing, and Management Application Development, can now understand exactly what to expect of the product. 4.2 MODEX Syntax The syntax used to write the MODEX template is designed with two goals. One is human readability. The format must lend itself to understanding by a MIB-knowledgeable reader, using keywords and conventions that convey dependency naturally. The other is compilability. The syntax must be reducible to unambiguous machine-readable form such that a piece of code can interpret it and make decisions regarding MIB object manipulation. The following is a proposed implementation for key portions of the MODEX syntax. DaCosta Expires July 2000 [Page 6] Internet Draft draft-dacosta-snmp-object-dependency-00.txt January 20, 2000 4.2.1 Some Initial Samples Before describing the syntax in detail, here are some fragments of MODEX code, to give the reader an intuitive impression of the syntax. swiProtoType.0 TakesEffect( OnReboot() ); SetAsGroup( nodePriority.0, nodeState.0 ); if( rtrPortState.each Equals( 3,4 ) ) { rtrPortSpeed.each CanEqual( 9600-19200 ); rtrPortProtocol.each CannotEqual( xdsl(), enet() ); rtrPortPeerState.each IsInvalid(); } 4.2.2 MIB Object Nomenclature MIB objects in a template may be expressed either in ASN.1 dot-notation (as in 1.3.6.1.2.1.1.1.0) or by MIB object name (as in sysContact). 4.2.3 Instancing MIB object instancing may be: - Explicit (as in ifSpeed.3) - Inclusive (as in ifOperStatus.any) - Ranged (as in ifAdminStatus.1-3) - Generic (as in ifType.each) - Exclusive (as in ifMtu.none) 4.2.4 Values MIB object values may be: - Explicit (as in 15 or "Text String") - Labeled (as in bps9600() from the INTEGER enumeration label) In cases in which an object and its value are specified together, they are paired with a separating equals sign, as in ifType.1=ppp() or ifSpeed.3=19200. DaCosta Expires July 2000 [Page 7] Internet Draft draft-dacosta-snmp-object-dependency-00.txt January 20, 2000 4.2.5 Simple Dependencies Simple dependencies are those that can be declared in a single clause. 4.2.5.1 TakesEffect This dependency indicates that a given MIB object, once SET, will not actually immediately affect the behavior of the device as intended. The following formations are defined: swiEngineState.any TakesEffect( After( 5000 ) ); swiEngineState.any TakesEffect( OnReboot() ); swiEngineState.any TakesEffect( OnInterfaceReset() ); swiEngineState.any TakesEffect( On( swiEngineResult.each=done() ) ); In the first example, the After() keyword takes as an argument the number of milliseconds which must elapse before the new value of the object actually begins to have the desired effect on the behavior of the managed device. In the second example, OnReboot() means that the desired effect will not occur until the device has been rebooted. In the third example, OnInterfaceReset() means that the desired effect will not occur until the associated interface has been reset. In the fourth example, the On() keyword takes as an argument the exact value that another object will assume to indicate that the first object change has taken effect in the device. A management application can thus SET the first object, then poll the second object to determine when the device behavior has reached the desired state. In all cases, the object does actually assume the desired value successfully when SET, and subsequent GETs of the value will confirm this. The dependency has to do with the behavior of the device, not the object value itself. Note the semantics of the "any" and "each" instancing. "Any" means that this dependency applies to any instance of the object. "Each" means the specific instance that matches the earlier object's instance. Thus, if the above example had read, instead: swiEngineState.any TakesEffect( On( swiEngineResult.any=done() ) ); ... this would mean that the management application, after SETting the first object, could poll any instance of the second object to determine when the behavior had taken full effect. DaCosta Expires July 2000 [Page 8] Internet Draft draft-dacosta-snmp-object-dependency-00.txt January 20, 2000 4.2.5.2 SetAsGroup This dependency indicates that two or more MIB objects must be SET at the same time (that is, in a single PDU) in order for all to safely assume their new values. There are two defined formations: SetAsGroup( hubBandwidth.0, hubFrameType.0 ); SetAsGroup( rtrProtoTable ); In the first example above, SetasGroup takes a list of objects, separated by commas. In the second example, SetAsGroup takes the name of an entire MIB table, indicating that all members of each row of the table must be SET simultaneously for the row to behave properly. DaCosta Expires July 2000 [Page 9] Internet Draft draft-dacosta-snmp-object-dependency-00.txt January 20, 2000 4.2.6 Complex Dependencies Complex dependencies are those that must be declared in multiple clauses. They take the general form: if( condition ) { result; result; . . } Multiple conditions can be combined using standard Boolean operators such as AND, OR, XOR, NOT, or their equivalent C-style forms. Multiple results are listed one after the other within braces. A single result can appear after the condition without braces, as in: if( condition ) result; 4.2.6.1 Conditions Conditions are expressed as a MIB object followed by a statement of that object's value. The following formations are defined: - Equality to a specific value or one of a list of values: Equals( 35 ) Equals( "Idle" ) Equals( bps1200() ) Equals( 14,24,76 ) Equals( 1-3 ) - Non-equality to a specified value or any of a list of values: DoesNotEqual( 52 ) DoesNotEqual( "Busy" ) DoesNotEqual( enabled() ) DoesNotEqual( 1,2,5 ) DoesNotEqual( 5-10 ) DaCosta Expires July 2000 [Page 10] Internet Draft draft-dacosta-snmp-object-dependency-00.txt January 20, 2000 4.2.6.2 Results Results are expressed as a MIB object followed by a statement of that object's value or some other behavior of that object. The following formations are defined: - Assumption of a specific value: WillEqual( 20 ) WillEqual( "Stopped" ) WillEqual( disabled() ) - Limitation to one or more of the object's normally valid SETtable values: CanEqual( 200 ) CanEqual( 5,6,9 ) CannotEqual( hdlc() ) CannotEqual( 56000-128000 ) - IsNotSettable() to indicate that any attempt to SET the object will be rejected with an error - IsNotValid() to indicate that the content of the object cannot be trusted to have its expected meaning under the current condition - IsNotAccessible() to indicate that any attempt to SET the object will be ignored by the device, resulting in no GET-RESPONSE and an accompanying timeout of the management operation 4.2.6.3 Examples Here are a few examples of complex dependencies: if( ifType.each Equals( frame-relay() ) ) { boxPortMsgCount.each IsNotValid(); } if( rtrTrunkUsage.0 DoesNotEqual( loadShare() ) { rtrPacketPrecision.0 CannotEqual( 1,3,6-10 ); } DaCosta Expires July 2000 [Page 11] Internet Draft draft-dacosta-snmp-object-dependency-00.txt January 20, 2000 4.3 MODEX Compiler The template is of great worth as a printed document; its worth is far greater as a machine-readable document. Of course, a program could read and interpret it as-is, but this is inefficient and slow. The better course is to create a MODEX compiler. The resultant file would be encoded for quick traversal by a special search engine. 4.4 MODEX API The application developer who integrates a compiled MODEX file would prefer not to have to know the format of the file or the best algorithm to search it. The developer would rather have an Applications Programming Interface (API) that shields him from these details and exposes the content of the file in convenient ways. In a C++ or Java environment, the most logical implementation of a MODEX API would be a new class object. The program would instantiate the object and call its methods to determine how the managed SNMP device should behave. The object would hide file access and lookup. Consider a new class called yourcompany.util.Modex. A Modex object could be instantiated and passed the name of a compiled MODEX file to open, read, interpret and expose. Alternatively, Modex could be subclassed to produce a project-specific class which already knows the name of its MODEX file and other details. The MODEX API could be made available by the implementor as a dynamic linked library (.DLL) or a remotable component (Java Bean, COM or CORBA object). An application could submit a list of possible object values to the API to determine which ones to grey out because they cannot actually be SET. An application could ask if a given object is subject to a delay in taking effect, so that a loop and message box could provide the user with feedback regarding the operation. DaCosta Expires July 2000 [Page 12] Internet Draft draft-dacosta-snmp-object-dependency-00.txt January 20, 2000 5. Topics For Further Discussion It could be argued that the problem of MIB object dependency expression begs, not for MODEX, but for an improved SNMP MIB syntax. I have chosen to separate dependency handling in this fashion out of practicality. The SNMP community is far more likely to experiment with and field trial implementations of a separate construct like MODEX than to attempt consensus on significant SNMP MIB changes. Even so, implementors may want to define a convention by which MODEX template statements may be integrated into a device's MIB, for convenience. An entire template could be appended to the end of a MIB, protected by comment dashes. Alternatively, individual MODEX statements could be inserted within the MIB object definitions which they limit, again as comments. A special comment convention ( such as "--%" ) could be followed so that MODEX statements could be located and extracted by a MODEX compiler. 6. Author's Address Frank B. DaCosta Milgo Solutions, Inc. 1619 N. Harrison Parkway Sunrise, FL 33323-2802 Phone: +1 954 846 4596 Email: frank_dacosta@milgo.com DaCosta Expires July 2000 [Page 13]