summaryrefslogtreecommitdiff
path: root/doc/rfc/rfc3512.txt
diff options
context:
space:
mode:
authorThomas Voss <mail@thomasvoss.com> 2024-11-27 20:54:24 +0100
committerThomas Voss <mail@thomasvoss.com> 2024-11-27 20:54:24 +0100
commit4bfd864f10b68b71482b35c818559068ef8d5797 (patch)
treee3989f47a7994642eb325063d46e8f08ffa681dc /doc/rfc/rfc3512.txt
parentea76e11061bda059ae9f9ad130a9895cc85607db (diff)
doc: Add RFC documents
Diffstat (limited to 'doc/rfc/rfc3512.txt')
-rw-r--r--doc/rfc/rfc3512.txt4651
1 files changed, 4651 insertions, 0 deletions
diff --git a/doc/rfc/rfc3512.txt b/doc/rfc/rfc3512.txt
new file mode 100644
index 0000000..37848f2
--- /dev/null
+++ b/doc/rfc/rfc3512.txt
@@ -0,0 +1,4651 @@
+
+
+
+
+
+
+Network Working Group M. MacFaden
+Request for Comments: 3512 Riverstone Networks, Inc.
+Category: Informational D. Partain
+ Ericsson
+ J. Saperia
+ JDS Consulting, Inc.
+ W. Tackabury
+ Gold Wire Technology, Inc.
+ April 2003
+
+
+ Configuring Networks and Devices with
+ Simple Network Management Protocol (SNMP)
+
+Status of this Memo
+
+ This memo provides information for the Internet community. It does
+ not specify an Internet standard of any kind. Distribution of this
+ memo is unlimited.
+
+Copyright Notice
+
+ Copyright (C) The Internet Society (2003). All Rights Reserved.
+
+Abstract
+
+ This document is written for readers interested in the Internet
+ Standard Management Framework and its protocol, the Simple Network
+ Management Protocol (SNMP). In particular, it offers guidance in the
+ effective use of SNMP for configuration management. This information
+ is relevant to vendors that build network elements, management
+ application developers, and those that acquire and deploy this
+ technology in their networks.
+
+Table of Contents
+
+ 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
+ 1.1. The Internet Standard Management Framework. . . . . . . . 3
+ 1.2. Configuration and the Internet Standard Management
+ Frame-work. . . . . . . . . . . . . . . . . . . . . . . . 4
+ 2. Using SNMP as a Configuration Mechanism. . . . . . . . . . . . 5
+ 2.1. Transactions and SNMP . . . . . . . . . . . . . . . . . . 6
+ 2.2. Practical Requirements for Transactional Control. . . . . 6
+ 2.3. Practices in Configuration--Verification. . . . . . . . . 7
+ 3. Designing a MIB Module . . . . . . . . . . . . . . . . . . . . 9
+ 3.1. MIB Module Design - General Issues. . . . . . . . . . . . 10
+ 3.2. Naming MIB modules and Managed Objects. . . . . . . . . . 11
+ 3.3. Transaction Control And State Tracking. . . . . . . . . . 12
+
+
+
+MacFaden, et al. Informational [Page 1]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+ 3.3.1. Conceptual Table Row Modification Practices. . . . 12
+ 3.3.2. Fate sharing with multiple tables. . . . . . . . . 13
+ 3.3.3. Transaction Control MIB Objects. . . . . . . . . . 14
+ 3.3.4. Creating And Activating New Table Rows . . . . . . 15
+ 3.3.5. Summary Objects and State Tracking . . . . . . . . 15
+ 3.3.6. Optimizing Configuration Data Transfer . . . . . . 18
+ 3.4. More Index Design Issues. . . . . . . . . . . . . . . . . 22
+ 3.4.1. Simple Integer Indexing. . . . . . . . . . . . . . 23
+ 3.4.2. Indexing with Network Addresses. . . . . . . . . . 23
+ 3.5. Conflicting Controls. . . . . . . . . . . . . . . . . . . 24
+ 3.6. Textual Convention Usage. . . . . . . . . . . . . . . . . 25
+ 3.7. Persistent Configuration. . . . . . . . . . . . . . . . . 26
+ 3.8. Configuration Sets and Activation . . . . . . . . . . . . 28
+ 3.8.1. Operational Activation Considerations. . . . . . . 28
+ 3.8.2. RowStatus and Deactivation . . . . . . . . . . . . 30
+ 3.9. SET Operation Latency . . . . . . . . . . . . . . . . . . 31
+ 3.9.1. Subsystem Latency, Persistence Latency,
+ and Activation Latency . . . . . . . . . . . . . . 33
+ 3.10. Notifications and Error Reporting. . . . . . . . . . . . 33
+ 3.10.1. Identifying Source of Configuration Changes . . . 34
+ 3.10.2. Limiting Unnecessary Transmission of
+ Notifications . . . . . . . . . . . . . . . . . . 34
+ 3.10.3. Control of Notification Subsystem . . . . . . . . 36
+ 3.11 Application Error Reporting . . . . . . . . . . . . . . . 36
+ 3.12 Designing MIB Modules for Multiple Managers . . . . . . . 37
+ 3.13 Other MIB Module Design Issues. . . . . . . . . . . . . . 39
+ 3.13.1. Octet String Aggregations . . . . . . . . . . . . 39
+ 3.13.2 Supporting multiple instances of a MIB Module. . . 40
+ 3.13.3 Use of Special Optional Clauses. . . . . . . . . . 41
+ 4. Implementing SNMP Configuration Agents . . . . . . . . . . . . 41
+ 4.1. Operational Consistency . . . . . . . . . . . . . . . . . 41
+ 4.2. Handling Multiple Managers. . . . . . . . . . . . . . . . 43
+ 4.3. Specifying Row Modifiability. . . . . . . . . . . . . . . 44
+ 4.4. Implementing Write-only Access Objects. . . . . . . . . . 44
+ 5. Designing Configuration Management Software. . . . . . . . . . 44
+ 5.1. Configuration Application Interactions
+ with Managed Systems. . . . . . . . . . . . . . . . . . . 45
+ 5.1.1. SET Operations . . . . . . . . . . . . . . . . . . 46
+ 5.1.2. Configuration Transactions . . . . . . . . . . . . 46
+ 5.1.3. Tracking Configuration Changes . . . . . . . . . . 47
+ 5.1.4. Scalability of Data Retrieval. . . . . . . . . . . 48
+ 6. Deployment and Security Issues . . . . . . . . . . . . . . . . 48
+ 6.1. Basic assumptions about Configuration . . . . . . . . . . 48
+ 6.2. Secure Agent Considerations . . . . . . . . . . . . . . . 49
+ 6.3. Authentication Notifications. . . . . . . . . . . . . . . 49
+ 6.4. Sensitive Information Handling. . . . . . . . . . . . . . 50
+ 7. Policy-based Management. . . . . . . . . . . . . . . . . . . . 51
+ 7.1. What Is the Meaning of 'Policy-based' . . . . . . . . . . 51
+
+
+
+MacFaden, et al. Informational [Page 2]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+ 7.2. Organization of Data in an SNMP-Based Policy System . . . 53
+ 7.3. Information Related to Policy-based Configuration . . . . 54
+ 7.4. Schedule and Time Issues. . . . . . . . . . . . . . . . . 56
+ 7.5. Conflict Detection, Resolution and Error Reporting. . . . 56
+ 7.5.1. Changes to Configuration Outside of the
+ Policy System. . . . . . . . . . . . . . . . . . . 57
+ 7.6. More about Notifications in a Policy System . . . . . . . 57
+ 7.7. Using Policy to Move Less Configuration Data. . . . . . . 57
+ 8. Example MIB Module With Template-based Data. . . . . . . . . . 58
+ 8.1. MIB Module Definition. . . . . . . . . . . . . . . . . . 61
+ 8.2. Notes on MIB Module with Template-based Data. . . . . . . 73
+ 8.3. Examples of Usage of the MIB . . . . . . .. . . . . . . . 74
+ 9. Security Considerations . . . . . . . . . . .. . . . . . . . . 77
+ 10. Acknowledgments. . . . . . . . . . . . . . . . . . . . . . . 78
+ 11. Normative References. . . . . . . . . . . . . . . . . . . . . 78
+ 12. Informative References. . . . . . . . . . . . . . . . . . . . 79
+ 13. Intellectual Property . . . . . . . . . . . . . . . . . . . . 81
+ 14. Editors' Addresses. . . . . . . . . . . . . . . . . . . . . . 82
+ 15. Full Copyright Statement. . . . . . . . . . . . . . . . . . . 83
+
+1. Introduction
+
+1.1. The Internet Standard Management Framework
+
+ The Internet Standard Management Framework has many components. The
+ purpose of this document is to describe effective ways of applying
+ those components to the problems of configuration management.
+
+ For reference purposes, the Internet Standard Management Framework
+ presently consists of five major components:
+
+ o An overall architecture, described in RFC 3411 [1].
+
+ 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 STD
+ 16, RFC 1155 [15], STD 16, RFC 1212 [16] and RFC 1215 [17]. The
+ second version, called SMIv2, is described in STD 58, RFC 2578
+ [2], STD 58, RFC 2579 [3] and STD 58, RFC 2580 [4].
+
+ o Message protocols for transferring management information. The
+ first version of the SNMP message protocol is called SNMPv1 and
+ described in STD 15, RFC 1157 [18]. A second version of the SNMP
+ message protocol, which is not an Internet standards track
+ protocol, is called SNMPv2c and described in RFC 1901 [19]. The
+ third version of the message protocol is called SNMPv3 and
+ described in RFC 3417 [5], RFC 3412 [6] and RFC 3414 [7].
+
+
+
+
+MacFaden, et al. Informational [Page 3]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+ o Protocol operations for accessing management information. The
+ first set of protocol operations and associated PDU formats is
+ described in STD 15, RFC 1157 [18]. A second set of protocol
+ operations and associated PDU formats is described in RFC 3416
+ [8].
+
+ o A set of fundamental applications described in RFC 3413 [9] and
+ the view-based access control mechanism described in RFC 3415
+ [10].
+
+ A more detailed introduction to the current SNMP Management Framework
+ can be found in RFC 3410 [12].
+
+ 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.
+
+1.2. Configuration and the Internet Standard Management Framework
+
+ Data networks have grown significantly over the past decade. This
+ growth can be seen in terms of:
+
+ Scale - Networks have more network elements, and the network
+ elements are larger and place more demands on the systems managing
+ them. For example, consider a typical number and speed of
+ interfaces in a modern core network element. A managed
+ metropolitan area network switch can have a port density much
+ greater than the port density built into the expectations of the
+ management systems that predated it. There are also many more
+ interrelationships within and between devices and device
+ functions.
+
+ Functionality - network devices perform more functions.
+ More protocols and network layers are required for the successful
+ deployment of network services which depend on them.
+
+ Rate of Change - the nature of modern network services
+ causes updates, additions, and deletions of device configuration
+ information more often than in the past. No longer can it be
+ assumed that a configuration will be specified once and then be
+ updated rarely. On the contrary, the trend has been towards much
+ more frequent changes of configuration information.
+
+ Correct configuration of network elements that make up data networks
+ is a prerequisite to the successful deployment of the services on
+ them. The growth in size and complexity of modern networks increases
+ the need for a standard configuration mechanism that is tightly
+ integrated with performance and fault management systems.
+
+
+
+MacFaden, et al. Informational [Page 4]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+ The Internet Standard Management Framework has been used successfully
+ to develop configuration management systems for a broad range of
+ devices and networks. A standard configuration mechanism that
+ tightly integrates with performance and fault systems is needed not
+ only to help reduce the complexity of management, but also to enable
+ verification of configuration activities that create revenue-
+ producing services.
+
+ This document describes Current Practices that have been used when
+ designing effective configuration management systems using the
+ Internet Standard Management Framework (colloquially known as SNMP).
+ It covers many basic practices as well as more complex agent and
+ manager design issues that are raised by configuration management.
+ We are not endeavoring to present a comprehensive how-to document for
+ generalized SNMP agent, MIB module, or management application design
+ and development. We will, however, cover points of generalized SNMP
+ software design and implementation practice, where the practice has
+ been seen to benefit configuration management software. So, for
+ example, the requirement for management applications to be aware of
+ agent limitations is discussed in the context of configuration
+ operations, but many issues that a management application developer
+ should consider with regard to manager-agent interactions are left
+ for other documents and resources.
+
+ Significant experience has been gained over the past ten years in
+ configuring public and private data networks with SNMP. During this
+ time, networks have grown significantly as described above. A
+ response to this explosive growth has been the development of
+ policy-based configuration management. Policy-Based Configuration
+ Management is a methodology wherein configuration information is
+ derived from rules and network-wide objectives, and is distributed to
+ potentially many network elements with the goal of achieving
+ consistent network behavior throughout an administrative domain.
+
+ This document presents lessons learned from these experiences and
+ applies them to both conventional and policy-based configuration
+ systems based on SNMP.
+
+2. Using SNMP as a Configuration Mechanism
+
+ Configuration activity causes one or more state changes in an
+ element. While it often takes an arbitrary number of commands and
+ amount of data to make up configuration change, it is critical that
+ the configuration system treat the overall change operation
+ atomically so that the number of states into which an element
+ transitions is minimized. The goal is for a change request either to
+ be completely executed or not at all. This is called transactional
+ integrity. Transactional integrity makes it possible to develop
+
+
+
+MacFaden, et al. Informational [Page 5]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+ reliable configuration systems that can invoke transactions and keep
+ track of an element's overall state and work in the presence of error
+ states.
+
+2.1. Transactions and SNMP
+
+ Transactions can logically take place at very fine-grained levels
+ such as an individual object instance or in very large aggregations
+ that could include many object instances located in many tables on a
+ managed device. For this reason, reliance on transactional integrity
+ only at the SNMP protocol level is insufficient.
+
+2.2. Practical Requirements for Transactional Control
+
+ A well-designed and deployed configuration system should have the
+ following features with regard to transactions and transactional
+ integrity.
+
+ 1) Provide for flexible transaction control at many different levels
+ of granularity. At one extreme, an entire configuration may be
+ delivered and installed on an element, or alternately one small
+ attribute may be changed.
+
+ 2) The transaction control component should work at and understand a
+ notion of the kind of multi-level "defaulting" as described in
+ Section 7.1. The key point here is that it may make most sense to
+ configure systems at an abstract level rather than on an
+ individual instance by instance basis as has been commonly
+ practiced. In some cases it is more effective to send a
+ configuration command to a system that contains a set of
+ 'defaults' to be applied to instances that meet certain criteria.
+
+ 3) An effective configuration management system must allow
+ flexibility in the definition of a successful transaction. This
+ cannot be done at the protocol level alone, but rather must be
+ provided for throughout the application and the information that
+ is being managed. In the case of SNMP, the information would be
+ in properly defined MIB modules.
+
+ 4) A configuration management system should provide time-indexed
+ transaction control. For effective rollback control, the
+ configuration transactions and their successful or unsuccessful
+ completion status must be reported by the managed elements and
+ stored in a repository that supports such time indexing and can
+ record the user that made the change, even if the change was not
+ carried out by the system recording the change.
+
+
+
+
+
+MacFaden, et al. Informational [Page 6]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+ 5) The managed system must support transactional security. This
+ means that depending on who is making the configuration request
+ and where it is being made, it may be accepted or denied based on
+ security policy that is in effect in the managed element.
+
+ Effective transactional control is a responsibility shared between
+ design, implementation, and operational practice. Transaction
+ control techniques for MIB module design are discussed in Section
+ 3.3. Transaction control considerations for the agent implementation
+ are discussed in Section 5.2.2.
+
+2.3. Practices in Configuration--Verification
+
+ Verification of expected behavior subsequent to the commitment of
+ change is an integral part of the configuration process. To reduce
+ the chance of making simple errors in configuration, many
+ organizations employ the following change management procedure:
+
+ pre-test - verify that the system is presently working properly
+
+ change - make configuration changes and wait for convergence
+ (system or network stability)
+
+ re-test - verify once again that the system is working properly
+
+ This procedure is commonly used to verify configuration changes to
+ critical systems such as the domain name system (DNS). DNS software
+ kits provide diagnostic tools that allow automatic test
+ procedures/scripts to be conducted.
+
+ A planned configuration sequence can be aborted if the pre-
+ configuration test result shows the state of the system as unstable.
+ Debugging the unintended effects of two sets of changes in large
+ systems is often more challenging than an analysis of the effects of
+ a single set after test termination.
+
+ Networks and devices under SNMP configuration readily support this
+ change management procedure since the SNMP provides integrated
+ monitoring, configuration and diagnostic capabilities. The key is
+ the sequencing of SNMP protocol operations to effect an integrated
+ change procedure like the one described above. This is usually a
+ well-bounded affair for changes within a single network element or
+ node. However, there are times when configuration of a given element
+ can impact other elements in a network. Configuring network
+ protocols such as IEEE 802.1D Spanning Tree or OSPF is especially
+ challenging since the impact of a configuration change can directly
+ affect stability (convergence) of the network the device is connected
+ to.
+
+
+
+MacFaden, et al. Informational [Page 7]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+ An integrated view of configuration and monitoring provides an ideal
+ platform from which to evaluate such changes. For example, the MIB
+ module governing IEEE 802.1D Spanning Tree (RFC 1493 [24]) provides
+ the following object to monitor stability per logical bridge.
+
+ dot1dStpTopChanges OBJECT-TYPE
+ SYNTAX Counter
+ ACCESS read-only
+ STATUS mandatory
+ DESCRIPTION
+ "The total number of topology changes detected by
+ this bridge since the management entity was last
+ reset or initialized."
+ REFERENCE
+ "IEEE 802.1D-1990: Section 6.8.1.1.3"
+ ::= { dot1dStp 4 }
+
+ Likewise, the OSPF MIB module provides a similar metric for stability
+ per OSPF area.
+
+ ospfSpfRuns OBJECT-TYPE
+ SYNTAX Counter32
+ MAX-ACCESS read-only
+ STATUS current
+ DESCRIPTION
+ "The number of times that the intra-area route
+ table has been calculated using this area's
+ link-state database. This is typically done
+ using Dijkstra's algorithm."
+ ::= { ospfAreaEntry 4 }
+
+ The above object types are good examples of a means of facilitating
+ the principles described in Section 2.3. That is, one needs to
+ understand the behavior of a subsystem before configuration change,
+ then be able to use the same means to retest and verify proper
+ operation subsequent to configuration change.
+
+ The operational effects of a given implementation often differ from
+ one to another for any given standard configuration object. The
+ impact of a change to stability of systems such as OSPF should be
+ documented in an agent-capabilities statement which is consistent
+ with "Requirements for IP Version 4 Routers" [22], Section 1.3.4:
+
+ A vendor needs to provide adequate documentation on all
+ configuration parameters, their limits and effects.
+
+
+
+
+
+
+MacFaden, et al. Informational [Page 8]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+ Adherence to the above model is not fail-safe, especially when
+ configuration errors are masked by long latencies or when
+ configuration errors lead to oscillations in network stability. For
+ example, consider the situation of loading a new software version on
+ a device, which leads to small, slow, cumulative memory leaks brought
+ on by a certain traffic pattern that was not caught during vendor and
+ customer test lab trials.
+
+ In a network-based example, convergence in an autonomous system
+ cannot be guaranteed when configuration changes are made since there
+ are factors beyond the control of the operator, such as the state of
+ other network elements. Problems affecting this convergence may not
+ be detected for a significant period of time after the configuration
+ change. Even for factors within the operator's control, there is
+ often little verification done to prevent mis-configuration (as shown
+ in the following example).
+
+ Consider a change made to ospfIfHelloInterval and
+ ospfIfRtrDeadInterval [24] timers in the OSPF routing protocol such
+ that both are set to the same value. Two routers may form an
+ adjacency but then begin to cycle in and out of adjacency, and thus
+ never reach a stable (converged) state. Had the configuration
+ process described at the beginning of this section been employed,
+ this particular situation would have been discovered without
+ impacting the production network.
+
+ The important point to remember from this discussion is that
+ configuration systems should be designed and implemented with
+ verification tests in mind.
+
+3. Designing a MIB Module
+
+ Carefully considered MIB module designs are crucial to practical
+ configuration with SNMP. As we have just seen, MIB objects designed
+ for configuration can be very effective since they can be associated
+ with integrated diagnostic, monitoring, and fault objects. MIB
+ modules for configuration also scale when they expose their notion of
+ template object types. Template objects can represent information at
+ a higher level of abstraction than instance-level ones. This has the
+ benefit of reducing the amount of instance-level data to move from
+ management application to the agent on the managed element, when that
+ instance-level data is brought about by applying a template object on
+ the agent. Taken together, all of these objects can provide a robust
+ configuration subsystem.
+
+ The remainder of this section provides specific practices used in MIB
+ module design with SMIv2 and SNMPv3.
+
+
+
+
+MacFaden, et al. Informational [Page 9]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+3.1. MIB Module Design - General Issues
+
+ One of the first tasks in defining a MIB module is the creation of a
+ model that reflects the scope and organization of the management
+ information an agent will expose.
+
+ MIB modules can be thought of as logical models providing one or more
+ aspects/views of a subsystem. The objective for all MIB modules
+ should be to serve one or more operational requirements such as
+ accounting information collection, configuration of one or more parts
+ of a system, or fault identification. However, it is important to
+ include only those aspects of a subsystem that are proven to be
+ operationally useful.
+
+ In 1993, one of most widely deployed MIB modules supporting
+ configuration was published, RFC 1493, which contained the BRIDGE-
+ MIB. It defined the criteria used to develop the MIB module as
+ follows:
+
+ To be consistent with IAB directives and good engineering
+ practice, an explicit attempt was made to keep this MIB as simple
+ as possible. This was accomplished by applying the following
+ criteria to objects proposed for inclusion:
+
+ (1) Start with a small set of essential objects and add only as
+ further objects are needed.
+
+ (2) Require objects be essential for either fault or configuration
+ management.
+
+ (3) Consider evidence of current use and/or utility.
+
+ (4) Limit the total (sic) of objects.
+
+ (5) Exclude objects which are simply derivable from others in this
+ or other MIBs.
+
+ (6) Avoid causing critical sections to be heavily instrumented. The
+ guideline that was followed is one counter per critical section
+ per layer.
+
+ Over the past eight years additional experience has shown a need to
+ expand these criteria as follows:
+
+ (7) Before designing a MIB module, identify goals and objectives for
+ the MIB module. How much of the underlying system will be
+ exposed depends on these goals.
+
+
+
+
+MacFaden, et al. Informational [Page 10]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+ (8) Minimizing the total number of objects is not an explicit goal,
+ but usability is. Be sure to consider deployment and usability
+ requirements.
+
+ (9) During configuration, consider supporting explicit error state,
+ capability and capacity objects.
+
+ (10) When evaluating rule (5) above, consider the impact on a
+ management application. If an object can help reduce a
+ management application's complexity, consider defining objects
+ that can be derived.
+
+3.2. Naming MIB modules and Managed Objects
+
+ Naming of MIB modules and objects informally follows a set of best
+ practices. Originally, standards track MIB modules used RFC names.
+ As the MIB modules evolved, the practice changed to using more
+ descriptive names. Presently, Standards Track MIB modules define a
+ given area of technology such as ATM-MIB, and vendors then extend
+ such MIB modules by prefixing the company name to a given MIB module
+ as in ACME-ATM-MIB.
+
+ Object descriptors (the "human readable names" assigned to object
+ identifiers [2]) defined in standard MIB modules should be unique
+ across all MIB modules. Generally, a prefix is added to each managed
+ object that can help reference the MIB module it was defined in. For
+ example, the IF-MIB uses "if" prefix for descriptors of object types
+ such as ifTable, ifStackTable and so forth.
+
+ MIB module object type descriptors can include an abbreviation for
+ the function they perform. For example the objects that control
+ configuration in the example MIB module in Section 8 include "Cfg" as
+ part of the object descriptor, as in bldgHVACCfgDesiredTemp.
+
+ This is more fully realized when the object descriptors that include
+ the fault, configuration, accounting, performance and security [33]
+ abbreviations are combined with an organized OID assignment approach.
+ For example, a vendor could create a configuration branch in their
+ private enterprises area. In some cases this might be best done on a
+ per product basis. Whatever the approach used, "Cfg" might be
+ included in every object descriptor in the configuration branch.
+ This has two operational benefits. First, for those that do look at
+ instances of MIB objects, descriptors as seen through MIB browsers or
+ other command line tools assist in conveying the meaning of the
+ object type. Secondly, management applications can be pointed at
+ specific subtrees for fault or configuration, causing a more
+ efficient retrieval of data and a simpler management application with
+ potentially better performance.
+
+
+
+MacFaden, et al. Informational [Page 11]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+3.3. Transaction Control And State Tracking
+
+ Transactions and keeping track of their state is an important
+ consideration when performing any type of configuration activity
+ regardless of the protocol. Here are a few areas to consider when
+ designing transaction support into an SNMP-based configuration
+ system.
+
+3.3.1. Conceptual Table Row Modification Practices
+
+ Any discussion of transaction control as it pertains to MIB module
+ design often begins with how the creation or modification of object
+ instances in a conceptual row in the MIB module is controlled.
+
+ RowStatus [3] is a standard textual convention for the management of
+ conceptual rows in a table. Specifically, the RowStatus textual
+ convention that is used for the SYNTAX value of a single column in a
+ table controls the creation, deletion, activation, and deactivation
+ of conceptual rows of the table. When a table has been defined with
+ a RowStatus object as one of its columns, changing an instance of the
+ object to 'active' causes the row in which that object instance
+ appears to become 'committed'.
+
+ In a multi-table scenario where the configuration data must be spread
+ over many columnar objects, a RowStatus object in one table can be
+ used to cause the entire set of data to be put in operation or stored
+ based on the definition of the objects.
+
+ In some cases, very large amounts of data may need to be 'committed'
+ all at once. In these cases, another approach is to configure all of
+ the rows in all the tables required and have an "activate" object
+ that has a set method that commits all the modified rows.
+
+ The RowStatus textual convention specifies that, when used in a
+ conceptual row, a description must define what can be modified.
+ While the description of the conceptual row and its columnar object
+ types is the correct place to derive this information on instance
+ modifiability, it is often wrongly assumed in some implementations
+ that:
+
+ 1) objects either must all be presently set or none need be set to
+ make a conceptual RowStatus object transition to active(1)
+
+ 2) objects in a conceptual row cannot be modified once a RowStatus
+ object is active(1). Restricting instance modifiability like
+ this, so that after a RowStatus object is set to active(1) is in
+ fact a reasonable limitation, since such a set of RowStatus may
+ have agent system side-effects which depend on committed columnar
+
+
+
+MacFaden, et al. Informational [Page 12]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+ object instance values. However, where this restriction exists on
+ an object, it should be made clear in a DESCRIPTION clause such as
+ the following:
+
+ protocolDirDescr OBJECT-TYPE
+ SYNTAX DisplayString (SIZE (1..64))
+ MAX-ACCESS read-create
+ STATUS current
+ DESCRIPTION
+ "A textual description of the protocol encapsulation.
+ A probe may choose to describe only a subset of the
+ entire encapsulation (e.g., only the highest layer).
+
+ This object is intended for human consumption only.
+
+ This object may not be modified if the associated
+ protocolDirStatus object is equal to active(1)."
+ ::= { protocolDirEntry 4 }
+
+ Any such restrictions on columnar object instance modification while
+ a row's RowStatus object instance is set to active(1) should appear
+ in the DESCRIPTION clause of the RowStatus columnar OBJECT-TYPE as
+ well.
+
+3.3.2. Fate sharing with multiple tables
+
+ An important principle associated with transaction control is fate
+ sharing of rows in different tables. Consider the case where a
+ relationship has been specified between two conceptual tables of a
+ MIB module (or tables in two different MIB modules). In this
+ context, fate sharing means that when a row of a table is deleted,
+ the corresponding row in the other table is also deleted. Fate
+ sharing in a transaction control context can also be used with the
+ activation of very large configuration changes. If we have two
+ tables that hold a set of configuration information, a row in one
+ table might have to be put in the 'ready' state before the second can
+ be put in the 'ready' state. When that second table can be placed in
+ the 'ready' state, then the entire transaction can be considered to
+ have been 'committed'.
+
+ Fate sharing of SNMP table data should be explicitly defined where
+ possible using the SMI index qualifier AUGMENTS. If the relationship
+ between tables cannot be defined using SMIv2 macros, then the
+ DESCRIPTION clause of the object types which particularly effect the
+ cross-table relationship should define what should happen when rows
+ in related tables are added or deleted.
+
+
+
+
+
+MacFaden, et al. Informational [Page 13]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+ Consider the relationship between the dot1dBasePortTable and the
+ ifTable. These tables have a sparse relationship. If a given
+ ifEntry supports 802.1D bridging then there is a dot1dBasePortEntry
+ that has a pointer to it via dot1dBasePortIfIndex.
+
+ Now, what should happen if an ifEntry that can bridge is deleted?
+ Should the object dot1dBasePortIfIndex simply be set to 0 or should
+ the dot1dBasePortEntry be deleted as well? A number of acceptable
+ design and practice techniques can provide the answer to these
+ questions, so it is important for the MIB module designer to provide
+ the guidance to guarantee consistency and interoperability.
+
+ To this end, when two tables are related in such a way, ambiguities
+ such as this should be avoided by having the DESCRIPTION clauses of
+ the pertinent row object types define the fate sharing of entries in
+ the respective tables.
+
+3.3.3. Transaction Control MIB Objects
+
+ When a MIB module is defined that includes configuration object
+ types, consider providing transaction control objects. These objects
+ can be used to cause a large transaction to be committed. For
+ example, we might have several tables that define the configuration
+ of a portion of a system. In order to avoid churn in the operational
+ state of the system we might create a single scalar object that, when
+ set to a particular value, will cause the activation of the rows in
+ all the necessary tables. Here are some examples of further usage
+ for such object types:
+
+ o Control objects that are the 'write' or 'commit' objects.
+
+ Such objects can cause all pending transactions (change MIB object
+ values as a result of SET operations) to be committed to a
+ permanent repository or operational memory, as defined by the
+ semantics of the MIB objects.
+
+ o Control objects at different levels of configuration granularity.
+
+ One of the decisions for a MIB module designer is what are the
+ levels of granularity that make sense in practice. For example,
+ in the routing area, would changes be allowed on a per protocol
+ basis such as BGP? If allowed at the BGP level, are sub-levels
+ permitted such as per autonomous system? The design of these
+ control objects will be impacted by the underlying software
+ design. RowStatus (see Section 3.3.1) also has important
+ relevance as a general transaction control object.
+
+
+
+
+
+MacFaden, et al. Informational [Page 14]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+3.3.4. Creating And Activating New Table Rows
+
+ When designing read-create objects in a table, a MIB module designer
+ should first consider the default state of each object in the table
+ when a row is created. Should an implementation of a standard MIB
+ module vary in terms of the objects that need to be set in order to
+ create an instance of a given row, an agent capabilities statement
+ should be used to name the additional objects in that table using the
+ CREATION-REQUIRES clause.
+
+ It is useful when configuring new rows to use the notReady status to
+ indicate row activation cannot proceed.
+
+ When creating a row instance of a conceptual table, one should
+ consider the state of instances of required columnar objects in the
+ row. The DESCRIPTION clause of such a required columnar object
+ should specify it as such.
+
+ During the period of time when a management application is attempting
+ to create a row, there may be a period of time when not all of these
+ required (and non-defaultable) columnar object instances have been
+ set. Throughout this time, an agent should return a noSuchInstance
+ error for a GET of any object instance of the row until such time
+ that all of these required instance values are set. The exception is
+ the RowStatus object instance, for which a notReady(3) value should
+ be returned during this period.
+
+ One need only be concerned with the notReady value return for a
+ RowStatus object when the row under creation does not yet have all of
+ the required, non-defaultable instance values for the row. One
+ approach to simplifying in-row configuration transactions when
+ designing MIB modules is to construct table rows that have no more
+ instance data for columnar objects than will fit inside a single SET
+ PDU. In this case, the createAndWait() value for the RowStatus
+ columnar object is not required. It is possible to use createAndGo()
+ in the same SET PDU, thus simplifying transactional management.
+
+3.3.5. Summary Objects and State Tracking
+
+ Before beginning a new set of configuration transactions, a
+ management application might want to checkpoint the state of the
+ managed devices whose configuration it is about to change. There are
+ a number of techniques that a MIB module designer can provide to
+ assist in the (re-)synchronization of the managed systems. These
+ objects can also be used to verify that the management application's
+ notion of the managed system state is the same as that of the managed
+ device.
+
+
+
+
+MacFaden, et al. Informational [Page 15]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+ These techniques include:
+
+ 1. Provide an object that reports the number of rows in a table
+
+ 2. Provide an object that flags when data in the table was last
+ modified.
+
+ 3. Send a notification message (InformRequests are preferable) to
+ deliver configuration change.
+
+ By providing an object containing the number of rows in a table,
+ management applications can decide how best to retrieve a given
+ table's data and may choose different retrieval strategies depending
+ on table size. Note that the availability of and application
+ monitoring of such an object is not sufficient for determining the
+ presence of table data change over a checkpointed duration since an
+ equal number of row creates and deletes over that duration would
+ reflect no change in the object instance value. Additionally, table
+ data change which does not change the number of rows in the table
+ would not be reflected through simple monitoring of such an object
+ instance.
+
+ Instead, the change in the value of any table object instance data
+ can be tracked through an object that monitors table change state as
+ a function of time. An example is found in RFC 2790, Host Resources
+ MIB:
+
+ hrSWInstalledLastUpdateTime OBJECT-TYPE
+ SYNTAX TimeTicks
+ MAX-ACCESS read-only
+ STATUS current
+ DESCRIPTION
+ "The value of sysUpTime when the hrSWInstalledTable
+ was last completely updated. Because caching of this
+ data will be a popular implementation strategy,
+ retrieval of this object allows a management station
+ to obtain a guarantee that no data in this table is
+ older than the indicated time."
+ ::= { hrSWInstalled 2 }
+
+ A similar convention found in many standards track MIB modules is the
+ "LastChange" type object.
+
+ For example, the ENTITY-MIB, RFC 2737 [34], provides the following
+ object:
+
+ entLastChangeTime OBJECT-TYPE
+ SYNTAX TimeStamp
+
+
+
+MacFaden, et al. Informational [Page 16]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+ MAX-ACCESS read-only
+ STATUS current
+ DESCRIPTION
+ "The value of sysUpTime at the time a conceptual row is
+ created, modified, or deleted in any of these tables:
+ - entPhysicalTable
+ - entLogicalTable
+ - entLPMappingTable
+ - entAliasMappingTable
+ - entPhysicalContainsTable"
+ ::= { entityGeneral 1 }
+
+ This convention is not formalized. There tend to be small
+ differences in what a table's LastChanged object reflects. IF-MIB
+ (RFC 2863 [20]) defines the following:
+
+ ifTableLastChange OBJECT-TYPE
+ SYNTAX TimeTicks
+ MAX-ACCESS read-only
+ STATUS current
+ DESCRIPTION
+ "The value of sysUpTime at the time of the last
+ creation or deletion of an entry in the ifTable. If
+ the number of entries has been unchanged since the
+ last re-initialization of the local network management
+ subsystem, then this object contains a zero value."
+ ::= { ifMIBObjects 5 }
+
+ So, if an agent modifies a row with an SNMP SET on ifAdminStatus, the
+ value of ifTableLastChange will not be updated. It is important to
+ be specific about what can cause an object to update so that
+ management applications will be able to detect and more properly act
+ on these changes.
+
+ The final way to keep distributed configuration data consistent is to
+ use an event-driven model, where configuration changes are
+ communicated as they occur. When the frequency of change to
+ configuration is relatively low or polling a cache object is not
+ desired, consider defining a notification that can be used to report
+ all configuration change details.
+
+ When doing so, the option is available to an SNMPv3 (or SNMPv2c)
+ agent to deliver the notification using either a trap or an inform.
+ The decision as to which PDU to deliver to the recipient is generally
+ a matter of local configuration. Vendors should recommend the use of
+ informs over traps for NOTIFICATION-TYPE data since the agent can use
+ the presence or absence of a response to help know whether it needs
+
+
+
+
+MacFaden, et al. Informational [Page 17]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+ to retransmit or not. Overall, it is preferable to use an inform
+ instead of a trap so that changes have a higher likelihood of
+ confirmed end-to-end delivery.
+
+ As a matter of MIB module design, when practical, the NOTIFICATION-
+ TYPE should include in the PDU all of the modified columnar objects
+ in a row of a table. This makes it easier for the management
+ application receiving the notification to keep track of what has
+ changed in the row of a table and perform addition analysis on the
+ state of the managed elements.
+
+ However, the use of notifications to communicate the state of a
+ rapidly changing object may not be ideal either. This leads us back
+ to the MIB module design question of what is the right level of
+ granularity to expose.
+
+ Finally, having to poll many "LastChange" objects does not scale
+ well. Consider providing a global LastChange type object to
+ represent overall configuration in a given agent implementation.
+
+3.3.6. Optimizing Configuration Data Transfer
+
+ Configuration management software should keep track of the current
+ configuration of all devices under its control. It should ensure
+ that the result is a consistent view of the configuration of the
+ network, which can help reduce inadvertent configuration errors.
+
+ In devices that have very large amounts of configuration data, it can
+ be costly to both the agent and the manager to have the manager
+ periodically poll the entire contents of these configuration tables
+ for synchronization purposes. A benefit of good synchronization
+ between the manager and the agent is that the manager can determine
+ the smallest and most effective set of data to send to managed
+ devices when configuration changes are required. Depending on the
+ table organization in the managed device and the agent
+ implementation, this practice can reduce the burden on the managed
+ device for activation of these configuration changes.
+
+ In the previous section, we discussed the "LastChange" style of
+ object. When viewed against the requirements just described, the
+ LastChange object is insufficient for large amounts of data.
+
+ There are three design options that can be used to assist with the
+ synchronization of the configuration data found in the managed device
+ with the manager:
+
+
+
+
+
+
+MacFaden, et al. Informational [Page 18]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+ 1) Design multiple indices to partition the data in a table logically
+ or break a table into a set of tables to partition the data based
+ on what an application will use the table for
+
+ 2) Use a time-based indexing technique
+
+ 3) Define a control MIB module that manages a separate data delivery
+ protocol
+
+3.3.6.1. Index Design
+
+ Index design has a major impact on the amount of data that must be
+ transferred between SNMP entities and can help to mitigate scaling
+ issues with large tables.
+
+ Many tables in standard MIB modules follow one of two indexing
+ models:
+
+ - Indexing based upon increasing Integer32 or Unsigned32 values of
+ the kind one might find in an array.
+
+ - Associative indexing, which refers to the technique of using
+ potentially sparse indices based upon a "key" of the sort one
+ would use for a hash table.
+
+ When tables grow to a very large number of rows, using an associative
+ indexing scheme offers the useful ability to efficiently retrieve
+ only the rows of interest.
+
+ For example, if an SNMP entity exposes a copy of the default-free
+ Internet routing table as defined in the ipCidrRouteTable, it will
+ presently contain around 100,000 rows.
+
+ Associative indexing is used in the ipCidrRouteTable and allows one
+ to retrieve, for example, all routes for a given IPv4 destination
+ 192.0.2/24.
+
+ Yet, if the goal is to extract a copy of the table, the associative
+ indexing reduces the throughput and potentially the performance of
+ retrieval. This is because each of the index objects are appended to
+ the object identifiers for every object instance returned.
+
+ ipCidrRouteEntry OBJECT-TYPE
+ SYNTAX IpCidrRouteEntry
+ MAX-ACCESS not-accessible
+ STATUS current
+ DESCRIPTION
+ "A particular route to a particular destination,
+
+
+
+MacFaden, et al. Informational [Page 19]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+ under a particular policy."
+ INDEX {
+ ipCidrRouteDest,
+ ipCidrRouteMask,
+ ipCidrRouteTos,
+ ipCidrRouteNextHop
+ }
+
+ A simple array-like index works efficiently since it minimizes the
+ index size and complexity while increasing the number of rows that
+ can be sent in a PDU. If the indexing is not sparse, concurrency can
+ be gained by sending multiple asynchronous non-overlapping collection
+ requests as is explained in RFC 2819 [32], Page 41 (in the section
+ pertaining to Host Group indexing).
+
+ Should requirements dictate new methods of access, multiple
+ indices can be defined such that both associative and simple
+ indexing can coexist to access a single logical table.
+
+ Two examples follow.
+
+ First, consider the ifStackTable found in RFC 2863 [20] and the
+ ifInvStackTable RFC 2864 [33]. They are logical equivalents with the
+ order of the auxiliary (index) objects simply reversed.
+
+ ifStackEntry OBJECT-TYPE
+ SYNTAX IfStackEntry
+ MAX-ACCESS not-accessible
+ STATUS current
+ DESCRIPTION
+ "Information on a particular relationship between
+ two sub-layers, specifying that one sub-layer runs
+ on 'top' of the other sub-layer. Each sub-layer
+ corresponds to a conceptual row in the ifTable."
+ INDEX { ifStackHigherLayer, ifStackLowerLayer }
+ ::= { ifStackTable 1 }
+
+ ifInvStackEntry OBJECT-TYPE
+ SYNTAX IfInvStackEntry
+ MAX-ACCESS not-accessible
+ STATUS current
+ DESCRIPTION
+ "Information on a particular relationship between two
+ sub-layers, specifying that one sub-layer runs underneath
+ the other sub-layer. Each sub-layer corresponds to a
+ conceptual row in the ifTable."
+ INDEX { ifStackLowerLayer, ifStackHigherLayer }
+ ::= { ifInvStackTable 1 }
+
+
+
+MacFaden, et al. Informational [Page 20]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+ Second, table designs that can factor data into multiple tables with
+ well-defined relationships can help reduce overall data transfer
+ requirements. The RMON-MIB, RFC 2819 [32], demonstrates a very
+ useful technique of organizing tables into control and data
+ components. Control tables contain those objects that are configured
+ and change infrequently, and the data tables contain information to
+ be collected that can be large and may change quite frequently.
+
+ As an example, the RMON hostControlTable provides a way to specify
+ how to collect MAC addresses learned as a source or destination from
+ a given port that provides transparent bridging of Ethernet packets.
+
+ Configuration is accomplished using the hostControlTable. It is
+ indexed by a simple integer. While this may seem to be array-like,
+ it is common practice for command generators to encode the ifIndex
+ into this simple integer to provide associative lookup capability.
+
+ The RMON hostTable and hostTimeTable represent dependent tables that
+ contain the results indexed by the hostControlTable entry.
+
+ The hostTable is further indexed by the MAC address which provides
+ the ability to reasonably search for a collection, such as the
+ Organizationally Unique Identifier (OUI), the first three octets of
+ the MAC address.
+
+ The hostTimeTable is designed explicitly for fast transfer of bulk
+ RMON data. It demonstrates how to handle collecting large number of
+ rows in the face of deletions and insertions by providing
+ hostControlLastDeleteTime.
+
+ hostControlLastDeleteTime OBJECT-TYPE
+ SYNTAX TimeTicks
+ MAX-ACCESS read-only
+ STATUS current
+ DESCRIPTION
+ "The value of sysUpTime when the last entry
+ was deleted from the portion of the hostTable
+ associated with this hostControlEntry. If no
+ deletions have occurred, this value shall be zero."
+ ::= { hostControlEntry 4 }
+
+3.3.6.2. Time Based Indexing
+
+ The TimeFilter as defined in RFC 2021 [44] and used in RMON2-MIB and
+ Q-BRIDGE-MIB (RFC 2674 [26]) provides a way to obtain only those rows
+ that have changed on or after some specified period of time has
+ passed.
+
+
+
+
+MacFaden, et al. Informational [Page 21]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+ One drawback to TimeFilter index tables is that a given row can
+ appear at many points in time, which artificially inflates the size
+ of the table when performing standard getNext or getBulk data
+ retrieval.
+
+3.3.6.3. Alternate Data Delivery Mechanisms
+
+ If the amount of data to transfer is larger than current SNMP design
+ restrictions permit, as in the case of OCTET STRINGS (64k minus
+ overhead of IP/UDP header plus SNMP header plus varbind list plus
+ varbind encoding), consider delivery of the data via an alternate
+ method, such as FTP and use a MIB module to control that data
+ delivery process. In many cases, this problem can be avoided via
+ effective MIB design. In other words, object types requiring this
+ kind of transfer size should be used judiciously, if at all.
+
+ There are many enterprise MIB modules that provide control of the
+ TFTP or FTP protocol. Often the SNMP part defines what to send where
+ and setting an object initiates the operation (for an example, refer
+ to the CISCO-FTP-CLIENT-MIB, discussed in [38]).
+
+ Various approaches exist for allowing a local agent process running
+ within the managed node to take a template for an object instance
+ (for example for a set of interfaces), and adapt and apply it to all
+ of the actual instances within the node. This is an architecture for
+ one form of policy-based configuration (see [36], for example). Such
+ an architecture, which must be designed into the agent and some
+ portions of the MIB module, affords the efficiency of specifying many
+ copies of instance data only once, along with the execution
+ efficiency of distributing the application of the instance data to
+ the agent.
+
+ Other work is currently underway to improve efficiency for bulk SNMP
+ transfer operations [37]. The objective of these efforts is simply
+ the conveyance of more information with less overhead.
+
+3.4. More Index Design Issues
+
+ Section 3.3.5 described considerations for table row index design as
+ it pertains to the synchronization of changes within sizable table
+ rows. This section simply considers how to specify this syntactically
+ and how to manage indices semantically.
+
+ In many respects, the design issues associated with indices in a MIB
+ module are similar to those in a database. Care must be taken during
+ the design phase to determine how often and what kind of information
+ must be set or retrieved. The next few points provide some guidance.
+
+
+
+
+MacFaden, et al. Informational [Page 22]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+3.4.1. Simple Integer Indexing
+
+ When indexing tables using simple Integer32 or Unsigned32, start with
+ one (1) and specify the maximum range of the value. Since object
+ identifiers are unsigned long values, a question that arises is why
+ not index from zero (0) instead of one(1)?
+
+ RFC 2578 [2], Section 7.7, page 28 states the following: Instances
+ identified by use of integer-valued objects should be numbered
+ starting from one (i.e., not from zero). The use of zero as a value
+ for an integer-valued index object type should be avoided, except in
+ special cases. Consider the provisions afforded by the following
+ textual convention from the Interfaces Group MIB module [33]:
+
+ InterfaceIndexOrZero ::= TEXTUAL-CONVENTION
+ DISPLAY-HINT "d"
+ STATUS current
+ DESCRIPTION
+ "This textual convention is an extension of the
+ InterfaceIndex convention. The latter defines a greater
+ than zero value used to identify an interface or interface
+ sub-layer in the managed system. This extension permits the
+ additional value of zero. the value zero is object-specific
+ and must therefore be defined as part of the description of
+ any object which uses this syntax. Examples of the usage of
+ zero might include situations where interface was unknown,
+ or when none or all interfaces need to be referenced."
+ SYNTAX Integer32 (0..2147483647)
+
+3.4.2. Indexing with Network Addresses
+
+ There are many objects that use IPv4 addresses (SYNTAX IpAddress) as
+ indexes. One such table is the ipAddrTable from RFC 2011 [14] IP-
+ MIB. This limits the usefulness of the MIB module to IPv4. To avoid
+ such limitations, use the addressing textual conventions INET-
+ ADDRESS-MIB [13] (or updates to that MIB module), which provides a
+ generic way to represent addresses for Internet Protocols. In using
+ the InetAddress textual convention in this MIB, however, pay heed to
+ the following advisory found in its description clause:
+
+ When this textual convention is used as the syntax of an index
+ object, there may be issues with the limit of 128 sub-identifiers
+ specified in SMIv2, STD 58. In this case, the OBJECT-TYPE
+ declaration MUST include a 'SIZE' clause to limit the number of
+ potential instance sub-identifiers.
+
+
+
+
+
+
+MacFaden, et al. Informational [Page 23]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+ One should consider the SMI limitation on the 128 sub-identifier
+ specification when using certain kinds of network address index
+ types. The most likely practical liability encountered in practice
+ has been with DNS names, which can in fact be in excess of 128 bytes.
+ The problem can be, of course, compounded when multiple indices of
+ this type are specified for a table.
+
+3.5. Conflicting Controls
+
+ MIB module designers should avoid specifying read-write objects that
+ overlap in function partly or completely.
+
+ Consider the following situation where two read-write objects
+ partially overlap when a dot1dBasePortEntry has a corresponding
+ ifEntry.
+
+ The BRIDGE-MIB defines the following managed object:
+
+ dot1dStpPortEnable OBJECT-TYPE
+ SYNTAX INTEGER {
+ enabled(1),
+ disabled(2) }
+ ACCESS read-write
+ STATUS mandatory
+ DESCRIPTION
+ "The enabled/disabled status of the port."
+ REFERENCE
+ "IEEE 802.1D-1990: Section 4.5.5.2"
+ ::= { dot1dStpPortEntry 4 }
+
+ The IF-MIB defines a similar managed object:
+
+ ifAdminStatus OBJECT-TYPE
+ SYNTAX INTEGER {
+ up(1), -- ready to pass packets
+ down(2),
+ testing(3) -- in some test mode
+ }
+ MAX-ACCESS read-write
+ STATUS current
+ DESCRIPTION
+ "The desired state of the interface. The testing(3)
+ state indicates that no operational packets can be
+ passed. When a managed system initializes, all
+ interfaces start with ifAdminStatus in the down(2) state.
+ As a result of either explicit management action or per
+ configuration information retained by the managed system,
+ ifAdminStatus is then changed to either the up(1) or
+
+
+
+MacFaden, et al. Informational [Page 24]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+ testing(3) states (or remains in the down(2) state)."
+ ::= { ifEntry 7 }
+
+ If ifAdminStatus is set to testing(3), the value to be returned for
+ dot1dStpPortEnable is not defined. Without clarification on how
+ these two objects interact, management implementations will have to
+ monitor both objects if bridging is detected and correlate behavior.
+
+ The dot1dStpPortEnable object type could have been written with more
+ information about the behavior of this object when values of
+ ifAdminStatus which impact it change. For example, text could be
+ added that described proper return values for the dot1dStpPortEnable
+ object instance for each of the possible values of ifAdminStatus.
+
+ In those cases where overlap between objects is unavoidable, then as
+ we have just described, care should be taken in the description of
+ each of the objects to describe their possible interactions. In the
+ case of an object type defined after an incumbent object type, it is
+ necessary to include in the DESCRIPTION of this later object type the
+ details of these interactions.
+
+3.6. Textual Convention Usage
+
+ Textual conventions should be used whenever possible to create a
+ consistent semantic for an oft-recurring datatype.
+
+ MIB modules often define a binary state object such as enable/disable
+ or on/off. Current practice is to use existing Textual Conventions
+ and define the read-write object in terms of a TruthValue from
+ SNMPv2-TC [3]. For example, the Q-BRIDGE-MIB [26] defines:
+
+ dot1dTrafficClassesEnabled OBJECT-TYPE
+ SYNTAX TruthValue
+ MAX-ACCESS read-write
+ STATUS current
+ DESCRIPTION
+ "The value true(1) indicates that Traffic Classes are
+ enabled on this bridge. When false(2), the bridge
+ operates with a single priority level for all traffic."
+ DEFVAL { true }
+ ::= { dot1dExtBase 2 }
+
+ Textual conventions that have a reasonable chance of being reused in
+ other MIB modules ideally should also be defined in a separate MIB
+ module to facilitate sharing of such object types. For example, all
+ ATM MIB modules draw on the ATM-TC-MIB [39] to reference and utilize
+ common definitions for addressing, service class values, and the
+ like.
+
+
+
+MacFaden, et al. Informational [Page 25]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+ To simplify management, it is recommended that existing SNMPv2-TC
+ based definitions be used when possible. For example, consider the
+ following object definition:
+
+ acmePatioLights OBJECT-TYPE
+ SYNTAX INTEGER {
+ on(1),
+ off(2),
+ }
+ MAX-ACCESS read-write
+ STATUS current
+ DESCRIPTION
+ "Current status of outdoor lighting."
+ ::= { acmeOutDoorElectricalEntry 3 }
+
+ This could be defined as follows using existing SNMPv2-TC TruthValue.
+
+ acmePatioLightsOn OBJECT-TYPE
+ SYNTAX TruthValue
+ MAX-ACCESS read-write
+ STATUS current
+ DESCRI2096PTION
+ "Current status of outdoor lighting. When set to true (1),
+ this means that the lights are enabled and turned on.
+ When set to false (2), the lights are turned off."
+ ::= { acmeOutDoorElectricalEntry 3 }
+
+3.7. Persistent Configuration
+
+ Many network devices have two levels of persistence with regard to
+ configuration data. In the first case, the configuration data sent
+ to the device is persistent only until changed with a subsequent
+ configuration operation, or the system is reinitialized. The second
+ level is where the data is made persistent as an inherent part of the
+ acceptance of the configuration information. Some configuration
+ shares both these properties, that is, that on acceptance of new
+ configuration data it is saved permanently and in memory. Neither of
+ these necessarily means that the data is used by the operational
+ code. Sometimes separate objects are required to activate this new
+ configuration data for use by the operational code.
+
+ However, many SNMP agents presently implement simple persistence
+ models, which do not reflect all the relationships of the
+ configuration data to the actual persistence model as described
+ above. Some SNMP set requests against MIB objects with MAX-ACCESS
+ read-write are written automatically to a persistent store. In other
+ cases, they are not. In some of the latter cases, enterprise MIB
+
+
+
+
+MacFaden, et al. Informational [Page 26]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+ objects are required in order to get standard configuration stored,
+ thus making it difficult for a generic application to have a
+ consistent effect.
+
+ There are standard conventions for saving configuration data. The
+ first method uses the Textual Convention known as StorageType [3]
+ which explicitly defines a given row's persistence requirement.
+
+ Examples include the RFC 3231 [25] definition for the schedTable row
+ object schedStorageType of syntax StorageType, as well as similar row
+ objects for virtually all of the tables of the SNMP View-based Access
+ Control Model MIB [10].
+
+ A second method for persistence simply uses the DESCRIPTION clause to
+ define how instance data should persist. RFC 2674 [26] explicitly
+ defines Dot1qVlanStaticEntry data persistence as follows:
+
+ dot1qVlanStaticTable OBJECT-TYPE
+ SYNTAX SEQUENCE OF Dot1qVlanStaticEntry
+ MAX-ACCESS not-accessible
+ STATUS current
+ DESCRIPTION
+ "A table containing static configuration information for
+ each VLAN configured into the device by (local or
+ network) management. All entries are permanent and will
+ be restored after the device is reset."
+ ::= { dot1qVlan 3 }
+
+ The current practice is a dual persistence model where one can make
+ changes to run-time configuration as well as to a non-volatile
+ configuration read at device initialization. The DISMAN-SCHEDULE-MIB
+ module [25] provides an example of this practice. A row entry of its
+ SchedTable specifies the parameters by which an agent MIB variable
+ instance can be set to a specific value at some point in time and
+ governed by other constraints and directives. One of those is:
+
+ schedStorageType OBJECT-TYPE
+ SYNTAX StorageType
+ MAX-ACCESS read-create
+ STATUS current
+ DESCRIPTION
+ "This object defines whether this scheduled action is kept
+ in volatile storage and lost upon reboot or if this row is
+ backed up by non-volatile or permanent storage.
+ Conceptual rows having the value `permanent' must allow
+ write access to the columnar objects schedDescr,
+ schedInterval, schedContextName, schedVariable, schedValue,
+ and schedAdminStatus. If an implementation supports the
+
+
+
+MacFaden, et al. Informational [Page 27]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+ schedCalendarGroup, write access must be also allowed to
+ the columnar objects schedWeekDay, schedMonth, schedDay,
+ schedHour, schedMinute."
+ DEFVAL { volatile }
+ ::= { schedEntry 19 }
+
+ It is important, however, to reiterate that the persistence is
+ ultimately controlled by the capabilities and features (with respect
+ to the storage model of management data) of the underlying system on
+ which the MIB Module agent is being implemented. This falls into
+ very much the same kind of issue set as, for example, the situation
+ where the size of data storage in the system for a Counter object
+ type is not the same as that in the corresponding MIB Object Type.
+ To generalize, the final word on the "when" and "how" of storage of
+ persistent data is dictated by the system and the implementor of the
+ agent on the system.
+
+3.8. Configuration Sets and Activation
+
+ An essential notion for configuration of network elements with SNMP
+ is awareness of the difference between the set of one or more
+ configuration objects from the activation of those configuration
+ changes in the actual subsystem. That is, it often only makes sense
+ to activate a group of objects as a single 'transaction'.
+
+3.8.1. Operational Activation Considerations
+
+ A MIB module design must consider the implications of the preceding
+ in the context of changes that will occur throughout a subsystem when
+ changes are activated. This is particularly true for configuration
+ changes that are complex. This complexity can be in terms of
+ configuration data or the operational ramifications of the activation
+ of the changes in the managed subsystem. A practical technique to
+ accommodate this kind of activation is the partitioning of contained
+ configuration sets, as it pertains to their being activated as
+ changes. Any complex configuration should have a master on/off
+ switch (MIB object type) as well as strategically placed on/off
+ switches that partition the activation of configuration data in the
+ managed subsystem. These controls play a pivotal role during the
+ configuration process as well as during subsequent diagnostics.
+ Generally, a series of set operations should not cause an agent to
+ activate each object, causing operational instability to be
+ introduced with every changed object instance. To avoid this
+ liability, ideally a series of Set PDUs can install the configuration
+ and a final set series of PDUs can activate the changes.
+
+
+
+
+
+
+MacFaden, et al. Informational [Page 28]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+ During diagnostic situations, certain on/off switches can be set to
+ localize the perceived error instead of having to remove the
+ configuration.
+
+ An example of such an object from the OSPF Version 2 MIB [29] is the
+ global ospfAdminStat:
+
+ ospfAdminStat OBJECT-TYPE
+ SYNTAX Status
+ MAX-ACCESS read-write
+ STATUS current
+ DESCRIPTION
+ "The administrative status of OSPF in the
+ router. The value 'enabled' denotes that the
+ OSPF Process is active on at least one interface;
+ 'disabled' disables it on all interfaces."
+ ::= { ospfGeneralGroup 2 }
+
+ Elsewhere in the OSPF MIB, the semantics of setting ospfAdminStat to
+ enabled(2) are clearly spelled out.
+
+ The Scheduling MIB [25] exposes such an object on each entry in the
+ scheduled actions table, along with the corresponding stats object
+ type (with read-only ACCESS) on the scheduled actions row instance.
+
+ This reflects a recurring basic design pattern which brings about
+ semantic clarity in the object type usage. A table can expose one
+ columnar object type which is strictly for administrative control.
+ When read, an instance of this object type will reflect its last set
+ or defaulted value. A companion operational columnar object type,
+ with MAX-ACCESS of read-only, provides the current state of
+ activation or deactivation resulting from the last set of the
+ administrative columnar instance. It is fully expected that these
+ administrative and operational columnar instances may reflect
+ different values over some period of time of activation latency,
+ which is why they are separate. Further sections display some of the
+ problems which can result from attempting to combine the operational
+ and administrative row columns into a single object type.
+
+ Note that all of this is independent of the RowStatus columnar
+ object, and the notion of 'activation' as it pertains to RowStatus.
+ A defined RowStatus object type should be strictly concerned with the
+ management of the table row itself (with 'activation' indicating "the
+ conceptual row is available for use by the managed device" [3], and
+ not to be confused with any operational activation semantics).
+
+
+
+
+
+
+MacFaden, et al. Informational [Page 29]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+ In the following example, schedAdminStatus controls activation of the
+ scheduled action, and schedOperStatus reports on its operational
+ status:
+
+ schedAdminStatus OBJECT-TYPE
+ SYNTAX INTEGER {
+ enabled(1),
+ disabled(2)
+ }
+ MAX-ACCESS read-create
+ STATUS current
+ DESCRIPTION
+ "The desired state of the schedule."
+ DEFVAL { disabled }
+ ::= { schedEntry 14 }
+
+ schedOperStatus OBJECT-TYPE
+ SYNTAX INTEGER {
+ enabled(1),
+ disabled(2),
+ finished(3)
+ }
+ MAX-ACCESS read-only
+ STATUS current
+ DESCRIPTION
+ "The current operational state of this schedule. The state
+ enabled(1) indicates this entry is active and that the
+ scheduler will invoke actions at appropriate times. The
+ disabled(2) state indicates that this entry is currently
+ inactive and ignored by the scheduler. The finished(3)
+ state indicates that the schedule has ended. Schedules
+ in the finished(3) state are ignored by the scheduler.
+ A one-shot schedule enters the finished(3) state when it
+ deactivates itself."
+ ::= { schedEntry 15 }
+
+3.8.2. RowStatus and Deactivation
+
+ RowStatus objects should not be used to control
+ activation/deactivation of a configuration. While RowStatus looks
+ ideally suited for such a purpose since a management application can
+ set a row to active(1), then set it to notInService(2) to disable it
+ then make it active(1) again, there is no guarantee that the agent
+ won't discard the row while it is in the notInService(2) state. RFC
+ 2579 [3], page 15 states:
+
+
+
+
+
+
+MacFaden, et al. Informational [Page 30]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+ The agent must detect conceptual rows that have been in either
+ state for an abnormally long period of time and remove them. It
+ is the responsibility of the DESCRIPTION clause of the status
+ column to indicate what an abnormally long period of time would
+ be.
+
+ The DISMAN-SCHEDULE-MIB's managed object schedAdminStatus
+ demonstrates how to separate row control from row activation.
+ Setting the schedAdminStatus to disabled(2) does not cause the row to
+ be aged out/removed from the table.
+
+ Finally, a reasonable agent implementation must consider how many
+ rows will be allowed to be created in the notReady/notInService state
+ such that resources are not exhausted by an errant application.
+
+3.9. SET Operation Latency
+
+ Many standards track and enterprise MIB modules that contain read-
+ write objects assume that an agent can complete a set operation as
+ quickly as an agent can send back the status of the set operation to
+ the application.
+
+ Consider the subtle operational shortcomings in the following object.
+ It both reports the current state and allows a SET operation to
+ change to a possibly new state.
+
+wheelRotationState OBJECT-TYPE
+ SYNTAX INTEGER { unknown(0),
+ idle(1),
+ spinClockwise(2),
+ spinCounterClockwise(3)
+ }
+ MAX-ACCESS read-write
+ STATUS current
+ DESCRIPTION
+ "The current state of a wheel."
+ ::= { XXX 2 }
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+MacFaden, et al. Informational [Page 31]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+With the object defined, the following example represents one possible
+transaction.
+
+Time Command Generator --------> <--- Command Responder
+----- ----------------- -----------------
+|
+A GetPDU(wheelRotationState.1.1)
+|
+| ResponsePDU(error-index 0,
+| error-code 0)
+|
+B wheelRotationState.1.1 == spinClockwise(2)
+|
+C SetPDU(wheelRotationState.1.1 =
+| spinCounterClockwise(3)
+|
+| ResponsePDU(error-index 0,
+| error-code 0)
+|
+D wheelRotationState.1.1
+ == spinCounterClockwise(3)
+|
+E GetPDU(wheelRotationState.1.1)
+|
+F ResponsePDU(error-index 0,
+| error-code 0)
+|
+V wheelRotationState.1.1 == spinClockwise(2)
+ ....some time, perhaps seconds, later....
+|
+G GetPDU(wheelRotationState.1.1)
+|
+H ResponsePDU(error-index 0,
+| error-code 0)
+| wheelRotationState.1.1
+V == spinCounterClockwise(3)
+
+ The response to the GET request at time E will often confuse
+ management applications that assume the state of the object should be
+ spinCounterClockwise(3). In reality, the wheel is slowing down in
+ order to come to the idle state then begin spinning counter
+ clockwise.
+
+ This possibility of confusing and paradoxical interactions of
+ administrative and operational state is inevitable when a single
+ object type is used to control and report on both types of state.
+ One common practice which we have already seen is to separate out the
+
+
+
+
+MacFaden, et al. Informational [Page 32]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+ desired (settable) state from current state. The objects
+ ifAdminStatus and ifOperStatus from RFC 2863 [20] provide such an
+ example of the separation of objects into desired and current state.
+
+3.9.1. Subsystem Latency, Persistence Latency, and Activation Latency
+
+ A second way latency can be introduced in SET operations is caused by
+ delay in agent implementations that must interact with loosely
+ coupled subsystems. The time it takes the instrumented system to
+ accept the new configuration information from the SNMP agent, process
+ it and 'install' the updated configuration in the system or otherwise
+ process the directives can often be longer than the SNMP response
+ timeout.
+
+ In these cases, it is desirable to provide a "current state" object
+ type which can be polled by the management application to determine
+ the state of control of the loosely coupled subsystem which was
+ affected by its configuration update.
+
+ More generally, some MIB objects may have high latencies associated
+ with changes to their values. This could be either a function of
+ saving the changed value to a persistent storage type, and/or
+ activating a subsystem that inherently has high latency as discussed
+ above. When defining such MIB objects, it might be wise to have the
+ agent process set operations in the managed subsystem as soon as the
+ Set PDU has been processed, and then update appropriate status
+ objects when the save-to- persistent storage and (if applicable)
+ activation has succeeded or is otherwise complete. Another approach
+ would be to cause a notification to be sent that indicates that the
+ operation has been completed.
+
+ When you describe an activation object, the DESCRIPTION clauses for
+ these objects should give a hint about the likely latency for the
+ completion of the operation. Keep in mind that from a management
+ software perspective (as presented in the example of schedAdminStatus
+ in Section 3.8.1), the combined latency of saving-to-persistence and
+ activation are not distinguishable when they are part of a single
+ operation.
+
+3.10. Notifications and Error Reporting
+
+ For the purpose of this section, a 'notification' is as described in
+ the SMIv2, RFC 2578 [2], by the NOTIFICATION-TYPE macro.
+ Notifications can be sent in either SNMPv2c [19] or SNMPv3 TRAP or
+ InformRequest PDUs. Given the sensitivity of configuration
+ information, it is recommended that configuration operations always
+ be performed using SNMPv3 due to its enhanced security capabilities.
+ InformRequest PDUs should be used in preference to TRAP PDUs since
+
+
+
+MacFaden, et al. Informational [Page 33]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+ the recipient of the InformRequest PDUs responds with a Response PDU.
+ This acknowledgment can be used to avoid unnecessary retransmission
+ of NOTIFICATION-TYPE information when retransmissions are in fact
+ required. The use of InformRequest PDUs (as opposed to TRAPs) is not
+ at the control of the MIB module designer or agent implementor. The
+ determination as to whether or not a TRAP or InformRequest PDU is
+ sent from an SNMPv2c or SNMPv3 agent is generally a function of the
+ agent's local configuration (but can be controlled with MIB objects
+ in SNMPv3). To the extent notification timeout and retry values are
+ determined by local configuration parameters, care should be taken to
+ avoid unnecessary retransmission of InformRequest PDUs.
+
+ Configuration change and error information conveyed in InformRequest
+ PDUs can be an important part of an effective SNMP-based management
+ system. They also have the potential to be overused. This section
+ offers some guidance for effective definition of NOTIFICATION-TYPE
+ information about configuration changes that can be carried in
+ InformRequest PDUs. Notifications can also play a key role for all
+ kinds of error reporting from hardware failures to configuration and
+ general policy errors. These types of notifications should be
+ designed as described in Section 3.11 (Application Error Reporting).
+
+3.10.1. Identifying Source of Configuration Changes
+
+ A NOTIFICATION-TYPE designed to report configuration changes should
+ report the identity of the management entity initiating the
+ configuration change. Specifically, if the entity is known to be a
+ SNMP command generator, the transport address and SNMP parameters as
+ found in table snmpTargetParamsTable from RFC 3413 SNMP-TARGET-MIB
+ should be reported where possible. For reporting of configuration
+ changes outside of the SNMP domain, the applicable change mechanism
+ (for example, CLI vs. HTTP-based management client access) should be
+ reported, along with whatever notion of "user ID" of the change
+ initiator is applicable and available.
+
+3.10.2. Limiting Unnecessary Transmission of Notifications
+
+ The design of event-driven synchronization models, essential to
+ configuration management, can use notifications as an important
+ enabling technique. Proper usage of notifications allows the
+ manager's view of the managed element's configuration to be in close
+ synchronization with the actual state of the configuration of the
+ managed element.
+
+ When designing new NOTIFICATION-TYPEs, consider how to limit the
+ number of notifications PDUs that will be sent with the notification
+ information defined in the NOTIFICATION-TYPE in response to a
+ configuration change or error event.
+
+
+
+MacFaden, et al. Informational [Page 34]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+ InformRequest PDUs, when compared to TRAP PDUs, have an inherent
+ advantage when the concern is the reduction of unnecessary messages
+ from the system generating the NOTIFICATION-TYPE data, when in fact
+ retransmission of this data is required. That is, an InformRequest
+ PDU is acknowledged by the receiving entity with a Response PDU. The
+ receipt of this response allows the entity which generated the
+ InformRequest PDU to verify (and record an audit entry, where such
+ facilities exist on the agent system) that the message was received.
+ As a matter of notification protocol, this receipt guarantee is not
+ available when using TRAP PDUs, and if it is required, must be
+ accomplished by the agent using some mechanism out of band to SNMP,
+ and usually requiring the penalty of polling.
+
+ Regardless of the specific PDUs used to convey them, one way to limit
+ the unnecessary generation of notifications is to include in the
+ NOTIFICATION-TYPE definition situations where it need not be sent. A
+ good example is the frDLCIStatusChange defined in FRAME-RELAY-DTE-
+ MIB, RFC 2115 [21].
+
+ frDLCIStatusChange NOTIFICATION-TYPE
+ OBJECTS { frCircuitState }
+ STATUS current
+ DESCRIPTION
+ "This trap indicates that the indicated Virtual Circuit
+ has changed state. It has either been created or
+ invalidated, or has toggled between the active and
+ inactive states. If, however, the reason for the state
+ change is due to the DLCMI going down, per-DLCI traps
+ should not be generated."
+ ::= { frameRelayTraps 1 }
+
+ There are a number of other techniques which can be used to reduce
+ the unwanted generation of NOTIFICATION-TYPE information. When
+ defining notifications, the designer can specify a number of temporal
+ limitations on the generation of specific instances of a
+ NOTIFICATION-TYPE. For example, a definition could specify that
+ messages will not be sent more frequently than once every 60 seconds
+ while the condition which led to the generation of the notification
+ persists. Alternately, a NOTIFICATION-TYPE DESCRIPTION clause could
+ provide a fixed limit on the number of messages sent over the
+ duration of the condition leading to sending the notification.
+
+ If NOTIFICATION-TYPE transmission is "aggregated" in some way -
+ bounded either temporally or by absolute system state change as
+ described above - the optimal design technique is to have the data
+ delivered with the notification reference the actual number of
+ underlying managed element transitions which brought about the
+ notification. No matter which threshold is chosen to govern the
+
+
+
+MacFaden, et al. Informational [Page 35]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+ actual transmission of NOTIFICATION-TYPEs, the idea is to describe an
+ aggregated event or related set of events in as few PDUs as possible.
+
+3.10.3. Control of Notification Subsystem
+
+ There are standards track MIB modules that define objects that either
+ augment or overlap control of notifications. For instance, FRAME-
+ RELAY-DTE-MIB RFC 2115 defines frTrapMaxRate and DOCS-CABLE-DEVICE-
+ MIB defines a set of objects in docsDevEvent that provide for rate
+ limiting and filtering of notifications.
+
+ In the past, agents did not have a standard means to configure a
+ notification generator. With the availability of the SNMP-
+ NOTIFICATION-MIB module in RFC 3413 [9], it is strongly recommended
+ that the filtering functions of this MIB module be used. This MIB
+ facilitates the mapping of given NOTIFICATION-TYPEs and their
+ intended recipients.
+
+ If the mechanisms of the SNMP-NOTIFICATION-MIB are not suitable for
+ this application, a explanation of why they are not suitable should
+ be included in the DESCRIPTION clause of any replacement control
+ objects.
+
+3.11. Application Error Reporting
+
+ MIB module designers should not rely on the SNMP protocol error
+ reporting mechanisms alone to report application layer error state
+ for objects that accept SET operations.
+
+ Most MIB modules that exist today provide very little detail as to
+ why a configuration request has failed. Often the only information
+ provided is via SNMP protocol errors which generally does not provide
+ enough information about why an agent rejected a set request.
+ Typically, there is an incumbent and sizable burden on the
+ configuration application to determine if the configuration request
+ failure is the result of a resource issue, a security issue, or an
+ application error.
+
+ Ideally, when a "badValue" error occurs for a given set request, an
+ application can query the agent for more details on the error. A
+ badValue does not necessarily mean the command generator sent bad
+ data. An agent could be at fault. Additional detailed diagnostic
+ information may aid in diagnosing conditions in the integrated
+ system.
+
+
+
+
+
+
+
+MacFaden, et al. Informational [Page 36]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+ Consider the requirement of conveying error information about a MIB
+ expression 'object' set within the DISMAN-EXPRESSION-MIB [40] that
+ occurs when the expression is evaluated. Clearly, none of the
+ available protocol errors are relevant when reporting an error
+ condition that occurs when an expression is evaluated. Instead, the
+ DISMAN-EXPRESSION-MIB provides objects to report such errors (the
+ expErrorTable). Instead, the expErrorTable maintains information
+ about errors that occur at evaluation time:
+
+ expErrorEntry OBJECT-TYPE
+ SYNTAX ExpErrorEntry
+ MAX-ACCESS not-accessible
+ STATUS current
+ DESCRIPTION
+ "Information about errors in processing an expression.
+ Entries appear in this table only when there is a matching
+ expExpressionEntry and then only when there has been an
+ error for that expression as reflected by the error codes
+ defined for expErrorCode."
+ INDEX { expExpressionOwner, expExpressionName }
+
+ More specifically, a MIB module can provide configuration
+ applications with information about errors on the managed device by
+ creating columnar object types in log tables that contain error
+ information particular to errors that occur on row activation.
+
+ Notifications with detailed failure information objects can also be
+ used to signal configuration failures. If this approach is used, the
+ configuration of destinations for NOTIFICATION-TYPE data generated
+ from configuration failures should be considered independently of the
+ those for other NOTIFICATION-TYPEs which are generated for other
+ operational reasons. In other words, in many management
+ environments, the network operators interested in NOTIFICATION-TYPEs
+ generated from configuration failures may not completely overlap with
+ the community of network operators interested in NOTIFICATION-TYPEs
+ generated from, for example, network interface failures.
+
+3.12. Designing MIB Modules for Multiple Managers
+
+ When designing a MIB module for configuration, there are several
+ pertinent considerations to provide support for multiple managers.
+
+ The first is to avoid any race conditions between two or more
+ authorized management applications issuing SET protocol operations
+ spanning over more than a single PDU.
+
+ The standard textual convention document [3] defines TestAndIncr,
+ often called a spinlock, which is used to avoid race conditions.
+
+
+
+MacFaden, et al. Informational [Page 37]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+ A MIB module designer may explicitly define a synchronization object
+ of syntax TestAndIncr or may choose to rely on snmpSetSerialNo (a
+ global spinlock object) as defined in SNMPv2-MIB.
+
+ snmpSetSerialNo OBJECT-TYPE
+ SYNTAX TestAndIncr
+ MAX-ACCESS read-write
+ STATUS current
+ DESCRIPTION
+ "An advisory lock used to allow several cooperating
+ command generator applications to coordinate their
+ use of the SNMP set operation.
+
+ This object is used for coarse-grain coordination.
+ To achieve fine-grain coordination, one or more similar
+ objects might be defined within each MIB group, as
+ appropriate."
+ ::= { snmpSet 1 }
+
+ Another prominent TestAndIncr example can be found in the SNMP-
+ TARGET- MIB [9], snmpTargetSpinLock.
+
+ Secondly, an agent should be able to report configuration as set by
+ different entities as distinguishable from configuration defined
+ external to the SNMP domain, such as application of a default or
+ through an alternate management interface like a command line
+ interface. Section 3.10.1 describes considerations for this practice
+ when designing NOTIFICATION-TYPEs. The OwnerString textual
+ convention from RMON-MIB RFC 2819 [32] has been used successfully for
+ this purpose. More recently, RFC 3411 [1] introduced the
+ SnmpAdminString which has been designed as a UTF8 string. This is
+ more suitable for representing names in many languages.
+
+ Experience has shown that usage of OwnerString to represent row
+ ownership can be a useful diagnostic tool as well. Specifically, the
+ use of the string "monitor" to identify configuration set by an
+ agent/local management has been prevalent and useful in applications.
+
+ Thirdly, consider whether there is a need for multiple managers to
+ configure the same set of tables. If so, an "OwnerString" may be
+ used as the first component of a table's index to allow VACM to be
+ used to protect access to subsets of rows, at least at the level of
+ securityName or groupName provided. RFC 3231 [25], Section 6
+ presents this technique in detail. This technique does add
+ complexity to the managed device and to the configuration management
+ application since the manager will need to be aware of these
+ additional columnar objects in configuration tables and act
+ appropriately to set them. Additionally, the agent must be
+
+
+
+MacFaden, et al. Informational [Page 38]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+ configured to provide the appropriate instance-level restrictions on
+ the modifiability of the instances.
+
+3.13. Other MIB Module Design Issues
+
+3.13.1. Octet String Aggregations
+
+ The OCTET STRING syntax can be used as an extremely flexible and
+ useful datatype when defining managed objects that allow SET
+ operation. An octet string is capable of modeling many things and is
+ limited in size to 65535 octets by SMIv2[2].
+
+ Since OCTET STRINGS are very flexible, the need to make them useful
+ to applications requires careful definition. Otherwise, applications
+ will at most simply be able to display and set them.
+
+ Consider the following object from RFC 3418 SNMPv2-MIB [11].
+
+ sysLocation OBJECT-TYPE
+ SYNTAX DisplayString (SIZE (0..255))
+ MAX-ACCESS read-write
+ STATUS current
+ DESCRIPTION
+ "The physical location of this node (e.g., `telephone
+ closet, 3rd floor'). If the location is unknown, the value
+ is the zero-length string."
+ ::= { system 6 }
+
+ Such informational object types have come to be colloquially known as
+ "scratch pad objects". While often useful, should an application be
+ required to do more with this information than be able to read and
+ set the value of this object, a more precise definition of the
+ contents of the OCTET STRING is needed, since the actual format of an
+ instance for such an object is unstructured. Hence, alternatively,
+ dividing the object type into several object type definitions can
+ provide the required additional structural detail.
+
+ When using OCTET STRINGS, avoid platform dependent data formats.
+ Also avoid using OCTET STRINGS where a more precise SMI syntax such
+ as SnmpAdminString or BITS would work.
+
+ There are many MIB modules that attempt to optimize the amount of
+ data sent/received in a SET/GET PDU by packing octet strings with
+ aggregate data. For example, the PortList syntax as defined in the
+ Q-BRIDGE-MIB (RFC 2674 [26]) is defined as follows:
+
+
+
+
+
+
+MacFaden, et al. Informational [Page 39]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+ PortList ::= TEXTUAL-CONVENTION
+ STATUS current
+ DESCRIPTION
+ "Each octet within this value specifies a set of eight
+ ports, with the first octet specifying ports 1 through
+ 8, the second octet specifying ports 9 through 16, etc.
+ Within each octet, the most significant bit represents
+ the lowest numbered port, and the least significant bit
+ represents the highest numbered port. Thus, each port
+ of the bridge is represented by a single bit within the
+ value of this object. If that bit has a value of '1'
+ then that port is included in the set of ports; the port
+ is not included if its bit has a value of '0'."
+ SYNTAX OCTET STRING
+
+ This compact representation saves on data transfer but has some
+ limitations. Such complex instance information is difficult to
+ reference outside of the object or use as an index to a table.
+ Additionally, with this approach, if a value within the aggregate
+ requires change, the entire aggregated object instance must be
+ written.
+
+ Providing an SNMP table to represent aggregate data avoids the
+ limitations of encoding data into OCTET STRINGs and is thus the
+ better general practice.
+
+ Finally, as previously mentioned in Section 3.3.6.3, one should
+ consider the practical ramifications of instance transfer for object
+ types of SYNTAX OCTET STRING where they have typical instance data
+ requirements close to the upper boundary of SMIv2 OCTET STRING
+ instance encoding. Where such object types are truly necessary at
+ all, SNMP/UDP may not be a very scalable means of transfer and
+ alternatives should be explored.
+
+3.13.2. Supporting multiple instances of a MIB Module
+
+ When defining new MIB modules, one should consider if there could
+ ever be multiple instances of this MIB module in a single SNMP
+ entity.
+
+ MIB modules exist that assume a one to many relationship, such as
+ MIBs for routing protocols which can accommodate multiple "processes"
+ of the underlying protocol and its administrative framework.
+ However, the majority of MIB modules assume a one-to-one relationship
+ between the objects found in the MIB module and how many instances
+ will exist on a given SNMP agent. The OSPF-MIB, IP-MIB, BRIDGE-MIB
+ are all examples that are defined for a single instance of the
+ technology.
+
+
+
+MacFaden, et al. Informational [Page 40]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+ It is clear that single instancing of these MIB modules limits
+ implementations that might support multiple instances of OSPF, IP
+ stacks or logical bridges.
+
+ In such cases, the ENTITY-MIB [RFC2737] can provide a means for
+ supporting the one-to-many relationship through naming scopes using
+ the entLogicalTable. Keep in mind, however, that there are some
+ drawbacks to this approach.
+
+ 1) One cannot issue a PDU request that spans naming scopes. For
+ example, given two instances of BRIDGE-MIB active in a single
+ agent, one PDU cannot contain a request for dot1dBaseNumPorts from
+ both the first and second instances.
+
+ 2) Reliance on this technique creates a dependency on the Entity MIB
+ for an application to be able to access multiple instances of
+ information.
+
+ Alternately, completely independently of the Entity MIB, multiple MIB
+ module instances can be scoped by different SNMP contexts. This
+ does, however, require the coordination of this technique with the
+ administrative establishment of contexts in the configured agent
+ system.
+
+3.13.3. Use of Special Optional Clauses
+
+ When defining integer-based objects for read-create, read-write and
+ read-only semantics, using the UNITS clause is recommended in
+ addition to specification in the DESCRIPTION clause of any particular
+ details of how UNITs are to be interpreted.
+
+ The REFERENCE clause is also recommended as a way to help an
+ implementer track down related information on a given object. By
+ adding a REFERENCE clause to the specific underlying technology
+ document, multiple separate implementations will be more likely to
+ interoperate.
+
+4. Implementing SNMP Configuration Agents
+
+4.1. Operational Consistency
+
+ Successful deployment of SNMP configuration systems depends on
+ understanding the roles of MIB module design and agent design.
+
+
+
+
+
+
+
+
+MacFaden, et al. Informational [Page 41]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+ Both module and agent design need to be undertaken with an
+ understanding of how UDP/IP-based SNMP behaves. A current practice
+ in MIB design is to consider the idempotency of settable objects.
+ Idempotency basically means being able to invoke the same set
+ operation repeatedly but resulting in only a single activation.
+
+ Here is an example of the idempotency in action:
+
+Manager Agent
+-------- ------
+Set1 (Object A, Value B) ---> receives set OK and responds
+ X<-------- Response PDU(OK) is dropped by
+ network
+Manager times out
+and sends again
+Set2 (Object A, Value B) ---> receives set OK (does nothing),
+ responds
+ <-------- with a Response PDU(OK)
+Manager receives OK
+
+ Had object A been defined in a stateful way, the set operation might
+ have caused the Set2 operation to fail as a result of interaction
+ with Set1. If the agent implementation is not aware of such a
+ possible situation on the second request, the agent may behave poorly
+ by performing the set request again rather than doing nothing.
+
+ The example above shows that all of the software that runs on a
+ managed element and in managed applications should be designed in
+ concert when possible. Particular emphasis should be placed at the
+ logical boundaries of the management system components in order to
+ ensure correct operation.
+
+ 1. The first interface is between SNMP agents in managed devices and
+ the management applications themselves. The MIB document is a
+ contract between these two entities that defines expected behavior
+ - it is a type of API.
+
+ 2. The second interface is between the agent and the instrumented
+ subsystem. In some cases, the instrumented subsystem will require
+ modification to allow for the dynamic nature of SNMP-based
+ configuration, control and monitoring operations. Agent
+ implementors must also be sensitive to the operational code and
+ device in order to minimize the impact of management on the
+ primary subsystems.
+
+ Additionally, while the SNMP protocol-level and MIB module-level
+ modeling of configuration operations may be idempotent and stateless
+ from one set operation to another, it may not be that way in the
+
+
+
+MacFaden, et al. Informational [Page 42]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+ underlying subsystem. It is possible that an agent may need to
+ manage this state in these subsystem architectures explicitly when it
+ has placed the underlying subsystem into an "intermediate" state at a
+ point in processing a series of SET PDUs. Alternatively, depending
+ on the underlying subsystem in question, the agent may be able to
+ buffer all of the configuration set operations prior to activating
+ them in the subsystem all at once (to accommodate the nature of the
+ subsystem).
+
+ As an example, it would be reasonable to define a MIB module to
+ control Virtual Private Network (VPN) forwarding, in which a
+ management station could set a set of ingress/egress IP addresses for
+ the VPN gateway. Perhaps the MIB module presumes that the level of
+ transactionality is the establishment of a single row in a table
+ defining the address of the ingress/egress gateway, along with some
+ prefix information to assist in routing at the VPN layer to that
+ gateway. However, it would be conceivable that in an underlying
+ Layer 2 VPN subsystem instrumentation, the requirement is that all
+ existing gateways for a VPN be deleted before a new one can be
+ defined--that, in other words, in order to add a new gateway, g(n),
+ to a VPN, gateways g(1)..g(n-1) need to be removed, and then all n
+ gateways reestablished with the VPN forwarding service. In this
+ case, one could imagine an agent which has some sort of timer to
+ establish a bounded window for receipt of SETs for new VPN gateways,
+ and to activate them in this removal-then-reestablishment of existing
+ and new gateways at the end of this window.
+
+4.2. Handling Multiple Managers
+
+ Devices are often modified by multiple management entities and with
+ different management techniques. It is sometimes the case that an
+ element is managed by different organizations such as when a device
+ sits between administrative domains.
+
+ There are a variety of approaches that management software can use to
+ ensure synchronization of information between the manager(s) and the
+ managed elements.
+
+ An agent should report configuration changes performed by different
+ entities. It should also distinguish configuration defined locally
+ such as a default or locally specified configuration made through an
+ alternate management interface such as a command line interface.
+ When a change has been made to the system via SNMP, CLI, or other
+ method, a managed element should send an notification to the
+ manager(s) configured as recipients of these applicable
+ notifications. These management applications should update their
+
+
+
+
+
+MacFaden, et al. Informational [Page 43]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+ local configuration repositories and then take whatever additional
+ action is appropriate. This approach can also be an early warning of
+ undesired configuration changes.
+
+ Managers should also develop mechanisms to ensure that they are
+ synchronized with each other.
+
+4.3. Specifying Row Modifiability
+
+ Once a RowStatus value is active(1) for a given row, the management
+ application should be able to determine what the semantics are for
+ making additional changes to a row. The RMON MIB control table
+ objects spell out explicitly what managed objects in a row can and
+ cannot be changed once a given RowStatus goes active.
+
+ As described earlier, some operations take some time to complete.
+ Some systems also require that they remain in a particular state for
+ some period before moving to another. In some cases, a change to one
+ value may require re-initialization of the system. In all of these
+ cases, the DESCRIPTION clause should contain information about
+ requirements of the managed system and special restrictions that
+ managers should observe.
+
+4.4. Implementing Write-only Access Objects
+
+ The second version of the SNMP SMI dropped direct support for a
+ write-only object. It is therefore necessary to return something when
+ reading an object that you may have wished to have write-only
+ semantics. Such objects should have a DESCRIPTION clause that
+ details what the return values should be. However, regardless of the
+ approach, the value returned when reading the object instance should
+ be meaningful in the context of the object's semantics.
+
+5. Designing Configuration Management Software
+
+ In this section, we describe practices that should be used when
+ creating and deploying management software that configures one or
+ more systems using SNMP. Functions all configuration management
+ software should provide, regardless of the method used to convey
+ configuration information to the managed systems are backup, fail-
+ over, and restoration. A management system should have the following
+ features:
+
+ 1. A method for restoring a previous configuration to one or more
+ devices. Ideally this restoration should be time indexed so that
+ a network can be restored to a configured state as of a specific
+ time and date.
+
+
+
+
+MacFaden, et al. Informational [Page 44]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+ 2. A method for saving back up versions of the configuration data in
+ case of hardware or software failure.
+
+ 3. A method of providing fail-over to a secondary (management) system
+ in case of a primary failure. This capability should be deployed
+ in such a way that it does not cause duplicate polling of
+ configuration.
+
+ These three capabilities are of course important for other types of
+ management that are not the focus of this BCP.
+
+5.1. Configuration Application Interactions with Managed Systems
+
+ From the point of view of the design of the management application,
+ there are three basic requirements to evaluate relevant to SNMP
+ protocol operations and configuration:
+
+ o Set and configuration activation operations
+
+ o Notifications from the device
+
+ o Data retrieval and collection
+
+ Depending on the requirements of the specific services being
+ configured, many other requirements may, and probably will, also be
+ present.
+
+ The design of the system should not assume that the objects in a
+ device that represent configuration data will remain unchanged over
+ time.
+
+ As standard MIB modules evolve and vendors add private extensions,
+ the specific configuration parameters for a given operation are
+ likely to change over time. Even in the case of a configuration
+ application that is designed for a single vendor, the management
+ application should allow for variability in the MIB objects that will
+ be used to configure the device for a particular purpose. The best
+ method to accomplish this is by separating, as much as possible, the
+ operational semantics of a configuration operation from the actual
+ data. One way that some applications achieve this is by having the
+ specific configuration objects that are associated with a particular
+ device be table driven rather than hard coded. Ideally, management
+ software should verify the support in the devices it is expected to
+ manage and report any unexpected deviations to the operator. This
+ approach is particularly valuable when developing applications that
+ are intended to support equipment or software from multiple vendors.
+
+
+
+
+
+MacFaden, et al. Informational [Page 45]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+5.1.1. SET Operations
+
+ Management software should be mindful of the environment in which SET
+ operations are being deployed. The intent here is to move
+ configuration information as efficiently as possible to the managed
+ device. There are many ways to achieve efficiency and some are
+ specific to given devices. One general case that all management
+ software should employ is to reduce the number of SET PDU exchanges
+ between the managed device and the management software to the
+ smallest reasonable number. One approach to this is to verify the
+ largest number of variable bindings that can fit into a SET PDU for a
+ managed device. In some cases, the number of variable bindings to be
+ sent in a particular PDU will be influenced by the device, the
+ specific MIB objects and other factors.
+
+ Maximizing the number of variable bindings in a SET PDU also has
+ benefits in the area of management application transaction
+ initiation, as we will discuss in the following section.
+
+ There are, though, agents that may have implementation limitations on
+ the number and order of varbinds they can handle in a single SET PDU.
+ In this case, sending fewer varbinds will be necessary.
+
+ As stated at the outset of this section, the management application
+ software designer must be sensitive to the design of the SNMP
+ software in the managed device. For example, the software in the
+ managed device may require that all that all related configuration
+ information for an operation be conveyed in a single PDU because it
+ has no concept of a transaction beyond a single SNMP PDU. Another
+ example has to do with the RowStatus textual convention. Some SNMP
+ agents implement a subset of the features available and as such the
+ management application must avoid using features that may not be
+ supported in a specific table implementation (such as createAndWait).
+
+5.1.2. Configuration Transactions
+
+ There are several types of configuration transactions that can be
+ supported by SNMP-based configuration applications. They include
+ transactions on a scalar object, transactions in a single table
+ (within and across row instances), transactions across several tables
+ in a managed device and transactions across many devices. The
+ manager's ability to support these different transactions is partly
+ dependent on the design of the MIB objects used in the configuration
+ operation.
+
+ To make use of any kind of transaction semantics effectively, SNMP
+ management software must be aware of the information in the MIB
+ modules that it is to configure so that it can effectively utilize
+
+
+
+MacFaden, et al. Informational [Page 46]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+ RowStatus objects for the control of transactions on one or more
+ tables. Such software must also be aware of control tables that the
+ device supports that are used to control the status of one or more
+ other tables.
+
+ To the greatest extent possible, the management application should
+ provide the facility to support transactions across multiple devices.
+ This means that if a configuration operation is desired across
+ multiple devices, the manager can coordinate these configuration
+ operations such that they become active as close to simultaneously as
+ possible.
+
+ Several practical means are present in the SNMP model that support
+ management application level transactions. One was mentioned in the
+ preceding section, that transactions can be optimized by including
+ the maximum number of SET variable bindings possible in a single PDU
+ sent to the agent.
+
+ There is an important refinement to this. The set of read-create row
+ data objects for tables should be sent in a single PDU, and only
+ placed across multiple PDUs if absolutely necessary. The success of
+ these set operations should be verified through the response(s) to
+ the Set PDU or subsequent polling of the row data objects. The
+ applicable RowStatus object(s), may be set to active only after this
+ verification. This is the only tractable means of affording an
+ opportunity for per-row rollback, particularly when the configuration
+ change is across table row instances on multiple managed devices.
+
+ Finally, where a MIB module exposes the kind of helpful transaction
+ management object types that were discussed in Section 3.3.5, it is
+ clearly beneficial to the integrity of the management application's
+ capacity to handle transactions to make use of them.
+
+5.1.3. Tracking Configuration Changes
+
+ As previously described in Section 3.3.5 (Summary Objects and State
+ Tracking), agents should provide the capability for notifications to
+ be sent to their configured management systems whenever a
+ configuration operation is completed or is detected to have failed.
+ The management application must be prepared to accept these
+ notifications so that it knows the current configured state of the
+ devices under its control. Upon receipt of the notification, the
+ management application should use getBulk or getNext to retrieve the
+ configuration from the agent and store the relevant contents in the
+ management application database. The GetBulkRequest-PDU is useful
+ for this whenever supported by the managed device, since it is more
+ efficient than the GetNextRequest-PDU when retrieving large amounts
+
+
+
+
+MacFaden, et al. Informational [Page 47]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+ of data. For the purposes of backward compatibility, the management
+ station should also support and make use of the GetNextRequest-PDU
+ when the agent does not support the GetBulkRequest-PDU.
+
+ Management systems should also provide configuration options with
+ defaults for users that tend to retrieve the smallest amount of data
+ to achieve the particular goal of the application, to avoid
+ unnecessary load on managed devices for the most common retrieval
+ operations.
+
+5.1.4. Scalability of Data Retrieval
+
+ The techniques for efficient data retrieval described in the
+ preceding sections comprise only one aspect of what application
+ developers should consider in this regard when developing
+ configuration applications. Management applications should provide
+ for distributed processing of the configuration operations. This
+ also extends to management functions that are not the focus of this
+ document. Techniques of distributed processing can also be used to
+ provide resilience in the case of network failures. An SNMP-based
+ configuration management system might be deployed in a distributed
+ fashion where three systems in different locations keep each other
+ synchronized. This synchronization can be accomplished without
+ additional polling of network devices through a variety of
+ techniques. In the case of a failure, a 'backup' system can take
+ over the configuration responsibilities from the failed manager
+ without having to re-synchronize with the managed elements since it
+ will already be up to date.
+
+6. Deployment and Security Issues
+
+ Now that we have considered the design of SNMP MIB data for
+ configuration, agent implementation of its access, and management
+ application issues in configuration using SNMP, we turn to a variety
+ of operational considerations which transcend all three areas.
+
+6.1. Basic assumptions about Configuration
+
+ The following basic assumptions are made about real world
+ configuration models.
+
+ 1) Operations must understand and must be trained in the operation of
+ a given technology. No configuration system can prevent an
+ untrained operator from causing outages due to misconfiguration.
+
+ 2) Systems undergoing configuration changes must be able to cope with
+ unexpected loss of communication at any time.
+
+
+
+
+MacFaden, et al. Informational [Page 48]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+ During configuration operations, network elements must take
+ appropriate measures to leave the configuration in a
+ consistent/recognizable state by either rolling back to a
+ previously valid state or changing to a well-defined or default
+ state.
+
+ 3) Configuration exists on a scale from relatively unchanging to a
+ high volume, high rate of change. The former is often referred to
+ as "set and forget" to indicate that the configuration changes
+ quite infrequently. The latter, "near real-time change control"
+ implies a high frequency of configuration change. Design of
+ configuration management must take into account the rate and
+ volume of change expected in a given configuration subsystem.
+
+6.2. Secure Agent Considerations
+
+ Vendors should not ship a device with a community string 'public' or
+ 'private', and agents should not define default community strings
+ except when needed to bootstrap devices that do not have secondary
+ management interfaces. Defaults lead to security issues that have
+ been recognized and exploited. When using SNMPv1, supporting read-
+ only community strings is a common practice.
+
+ Version 3 of the SNMP represents the current standard for the
+ Internet Management Framework and is recommended for all network
+ management applications. In particular, SNMPv3 provides
+ authorization, authentication, and confidentiality protection and is
+ essential to meeting the security considerations for all management
+ of devices that support SNMP-based configuration.
+
+6.3. Authentication Notifications
+
+ The default state of RFC 1215 [17] Authentication notifications
+ should be off. One does not want to risk accidentally sending out
+ authentication failure information, which by itself could constitute
+ a security liability. Enabling authentication Notifications should
+ be done in the context of a management security scheme which
+ considers the proper recipients of this information.
+
+ There are other liabilities where authentication notifications are
+ generated without proper security infrastructure. When notifications
+ are sent in SNMPv1 trap PDUs, unsolicited packets to a device can
+ causes one or more trap PDUs to be created and sent to management
+ stations. If these traps flow on shared access media and links, the
+ community string from the trap may be gleaned and exploited to gain
+ access to the device. At the very least, this risk should be
+ mitigated by having the authentication trap PDU be conveyed with a
+
+
+
+
+MacFaden, et al. Informational [Page 49]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+ community string which is only used for authentication traps from the
+ agent, and would be useless for access inbound to the agent to get at
+ other management data.
+
+ A further liability of authentication traps can be seen when they are
+ being generated in the face of a Denial Of Service (DOS) attack, in
+ the form of a flood of PDUs with invalid community strings, on the
+ agent system. If it is bad enough that the system is having to
+ respond to and recover from the invalid agent data accesses, but the
+ problem will be compounded if a separate Authentication notification
+ PDU is sent to each recipient on the management network.
+
+6.4. Sensitive Information Handling
+
+ Some MIB modules contain objects that may contain data for keys,
+ passwords and other such sensitive information and hence must be
+ protected from unauthorized access. MIB documents that are created
+ in the IETF must have a 'Security Considerations' section, which
+ details how sensitive information should be protected. Similarly,
+ MIB module designers who create MIB documents for private MIB objects
+ should include similar information so that users of the products
+ containing these objects can take appropriate precautions.
+
+ Even if a device does support DES, it should be noted that
+ configuration of keys for other protocols via SNMP Sets protected by
+ DES should not be allowed if the other keys are longer than the 56
+ bit DES keys protecting the SNMP transmission.
+
+ The DESCRIPTION clause for these object types and their Security
+ Considerations sections in the documents which define them should
+ make it clear how and why these specific objects are sensitive and
+ that a user should only make them accessible for encrypted SNMP
+ access. Vendors should also document sensitive objects in a similar
+ fashion.
+
+ Confidentiality is not a mandatory portion of the SNMPv3 management
+ framework [6].
+
+ Prior to SNMPv3, providing customized views of MIB module data was
+ difficult. This led to objects being defined such as the following
+ from [41].
+
+
+
+
+
+
+
+
+
+
+MacFaden, et al. Informational [Page 50]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+ docsDevNmAccessEntry OBJECT-TYPE
+ SYNTAX DocsDevNmAccessEntry
+ MAX-ACCESS not-accessible
+ STATUS current
+ DESCRIPTION
+ "An entry describing access to SNMP objects by a
+ particular network management station. An entry in
+ this table is not readable unless the management station
+ has read-write permission (either implicit if the table
+ is empty, or explicit through an entry in this table.
+ Entries are ordered by docsDevNmAccessIndex. The first
+ matching entry (e.g., matching IP address and community
+ string) is used to derive access."
+ INDEX { docsDevNmAccessIndex }
+ ::= { docsDevNmAccessTable 1 }
+
+ New MIB modules should capitalize on existing security capabilities
+ of SNMPv3 Framework. One way they can do this is by indicating the
+ level of security appropriate to different object types. For
+ example, objects that change the configuration of the system might be
+ protected by using the authentication mechanisms in SNMPv3.
+ Specifically, it is useful to design MIB module object grouping with
+ considerations for VACM views definition, such that users can define
+ and properly scope what tables are visible to a given user and view.
+
+7. Policy-based Management
+
+ In some designs and implementations, a common practice used to move
+ large amounts of data involves using SNMP as a control channel in
+ combination with other protocols defined for transporting bulk data.
+ This approach is sub-optimal since it raises a number of security and
+ other concerns. Transferring large amounts of configuration data via
+ SNMP can be efficiently performed with several of the techniques
+ described earlier in this document. This policy section shows how
+ even greater efficiency can be achieved using a set of relatively new
+ design mechanisms. This section gives background and defines terms
+ that are relevant to this field and describes some deployment
+ approaches.
+
+7.1. What Is the Meaning of 'Policy-based'?
+
+ In the past few years of output from standards organizations and
+ networking vendor marketing departments, the term 'policy' has been
+ heavily used, touted, and contorted in meaning. The result is that
+ the true meaning of 'policy' is unclear without greater qualification
+ where it is used.
+
+ [42] gives the term 'policy' two explicit definitions:
+
+
+
+MacFaden, et al. Informational [Page 51]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+ - A definite goal, course or method of action to guide and determine
+ present and future decisions. "Policies" are implemented or
+ executed within a particular context (such as policies defined
+ within a business unit).
+
+ - Policies as a set of rules to administer, manage, and control
+ access to network resources.
+
+ Note that these two views are not contradictory since individual
+ rules may be defined in support of business goals.
+
+ As it pertains to our discussion of the term 'policy-based
+ configuration', the meaning is significantly more specific. In this
+ context, we refer to a way of integrating data and the management
+ actions which use it in such a way that:
+
+ - there is the ability to specify "default" configuration data for a
+ number of instances of managed elements, where those instances can
+ be correlated in some data driven or algorithmic way. The engine
+ to do this correlation and activate instances from defaults may
+ reside in the agent or externally. Where the representation of
+ these defaults are in the MIB design itself, the object types
+ supporting this notion are referred to as "template objects".
+
+ - the activation of instance data derived from template object types
+ results from minimal activation directives from the management
+ application, once the instances of the template object types have
+ been established.
+
+ - somewhat independently, the architecture of the overall management
+ agent may accommodate the definition and evaluation of management
+ and configuration policies. The side-effects of the evaluation of
+ these policies typically include the activation of certain
+ configuration directives. Where management data design exposes
+ template object types, the policy-driven activation can (and
+ ideally, should) include the application of template object
+ instances to the analogous managed element instance-level values.
+
+ As it pertains to template object data, the underlying notions
+ implied here have been prevalent for some time in non-SNMP management
+ regimes. A common feature of many command line interfaces for
+ configuring routers is the specification of one or more access
+ control lists. These typically provide a set of IP prefixes, BGP
+ autonomous system numbers, or other such identifying constructs (see,
+ for example, [42]). Once these access control lists are assembled,
+ their application to various interfaces, routing processes, and the
+ like are specified typically in the configuration of what the access
+ control list is applied to. Consistent with the prior properties to
+
+
+
+MacFaden, et al. Informational [Page 52]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+ define our use of policy-based configuration, a) the access list is
+ defined independent from its point of application, and b) its
+ application is independent of the access list definition. For
+ example, changing the application of an access list from one
+ interface to the other does not require a change in the access list
+ itself. The first point just mentioned suggests what is necessary
+ for template-based data organization. The second suggests its
+ application in a policy-based manner.
+
+ Let us now examine the motivation for such a system or subsystem
+ (perhaps bounded at the level of a 'template-enabled' MIB module,
+ given the above definition). Let us explore the importance of
+ policy-based techniques to configuration specifically.
+
+7.2. Organization of Data in an SNMP-Based Policy System
+
+ The number of configurable parameters and 'instances' such as
+ interfaces has increased as equipment has become larger and more
+ complex.
+
+ At the same time, there is a need to configure many of these systems
+ to operate in a coordinated fashion. This enables the delivery of
+ new specialized services that require this coordinated configuration.
+ Examples include delivery of virtual private networks and connections
+ that guarantee specific service levels.
+
+ The growth in size and complexity of configuration information has
+ significant implications for its organization as well as its
+ efficient transfer to the management agent. As an example, an agent
+ that implements the Bridge MIB [24] could be used to represent a
+ large VLAN with some 65,000 port entries. Configuring such a VLAN
+ would require the establishment of dot1dStpPortTable and
+ dot1DStaticTable entries for each such virtual port. Each table
+ entry would contain several parameters. A more efficient approach is
+ to provide default values for the creation of new entries that are
+ appropriate to the VLAN environment in our example. The local
+ management infrastructure should then iterate across the system
+ setting the default values to the selected ports as groups.
+
+ To date, this kind of large-scale configuration has been accomplished
+ with file transfer, by setting individual MIB objects, or with many
+ CLI commands. In each of these approaches the details for each
+ instance are contained in the file, CLI commands or MIB objects.
+ That is, they contain not only the value, and type of object, but
+ also the exact instance of the object to which to apply the value.
+ It is this property that tends to make configuration operations
+ explode as the number of instances (such as interfaces) grows. This
+ per-instance approach can work for a few machines configured by
+
+
+
+MacFaden, et al. Informational [Page 53]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+ experts, but there is a need for a more scalable solution.
+ Template-based data organization and policy-based management
+ abstracts the details above the instance level, which means that
+ fewer SET requests are sent to a managed device.
+
+ Realization of such a policy-driven system requires agents that can
+ take defaults and apply them to instances based on a rule that
+ defines under what conditions the defaults (policy) are to be
+ applied. A policy-driven configuration system which is to be
+ scalable needs to expose a means of layering its application of
+ defaults at discrete ranges of granularity. The spectrum of that
+ granularity might have a starting hierarchy point to apply defaults
+ at the breadth of a network service.
+
+ Ultimately, such a layering ends up with features to support
+ instance-level object instance data within the running agent.
+
+ An example of this kind of layering is implicit in the principle of
+ operations of a SNMPCONF Policy-Based Management MIB [36] (PM-MIB)
+ implementation. However, other entity management systems have been
+ employing these kinds of techniques end-to-end for some time, in some
+ cases using SNMP, in some cases using other encodings and transfer
+ technologies. What the PM-MIB seeks to establish, in an environment
+ ideal for its deployment, is an adaptation between MIB module data
+ which was not designed using template object types, and the ability
+ to allow the PM-MIB agent engine to apply instances of that data as
+ though it were template-based.
+
+7.3. Information Related to Policy-based Configuration
+
+ In order for effective policy management to take place, a range of
+ information about the network elements is needed to avoid making poor
+ policy decisions. Even in those cases where policy-based
+ configuration is not in use, much of the information described in
+ this section can be useful input to the decision-making process about
+ what type of configuration operations to do.
+
+ For this discussion it is important to make distinctions between
+ distribution of policy to a system, activation of a policy in a
+ system, and changes/failures that take place during the time the
+ policy is expected to be active. For example, if an interface is
+ down that is included in a policy that is distributed, there may not
+ be an error since the policy may not be scheduled for activation
+ until a later time.
+
+ On the other hand, if a policy is distributed and applied to an
+ interface that should be operational and it is not, clearly this is a
+ problem, although it is not an error in the configuration policy
+
+
+
+MacFaden, et al. Informational [Page 54]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+ itself. With this as background, here are some areas to consider
+ that are important to making good policy configuration decisions and
+ establishing when a policy has 'failed'.
+
+ o The operational state of network elements that are to be
+ configured.
+
+ Care should be taken to determine if the sub-components to be
+ configured are available for use. In some cases the elements may
+ not be available. The policy configuration software should
+ determine if this is a prerequisite to policy installation or if
+ the condition is even acceptable. This decision is separate from
+ the one to be made about policy activation. Installation is when
+ the policy is sent from the policy manager to the managed device
+ and activation is turning on the policy. In those cases where
+ policy is distributed when the sub-component such as an interface
+ or disk is not available, the managed system should send a
+ notification to the designated management station when the policy
+ is to become active or if the resource is still not available.
+
+ o The capabilities of the devices in the network.
+
+ A capability can be almost any unit of work a network element can
+ perform. These include routing protocols supported, Web server
+ and OS versions, queuing mechanisms supported on each interface
+ that can be used to support different qualities of service, and
+ many others. This information can be obtained from the
+ capabilities table of the Policy MIB module [36].
+
+ Historically, management applications have had to obtain this type
+ of information by issuing get requests for objects they might want
+ to use. This approach is far less efficient since it requires
+ many get requests and is more error prone since some instances
+ will not exist until configured. The new capabilities table is an
+ improvement on the current technique.
+
+ o The capacity of the devices to perform the desired work.
+
+ Capability is an ability to perform the desired work while a
+ capacity is a measure of how much of that capability the system
+ has. The policy configuration application should, wherever
+ possible, evaluate the capacity of the network element to perform
+ the work identified by the policy. In some systems it will not be
+ possible to obtain the capacity of the managed elements to perform
+ the desired work directly, even though it may be possible to
+ monitor the amount of work the element performs. In these cases,
+ the management application may benefit from pre-configured
+
+
+
+
+MacFaden, et al. Informational [Page 55]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+ information about the capacity of different network elements so
+ that evaluations of the resources available can be done before
+ distributing new policies.
+
+ Utilization refers to how much capacity for a particular
+ capability has been consumed. For devices that have been under
+ policy configuration control for any period of time, a certain
+ percentage of the available capacity of the managed elements will
+ be used. Policies should not be distributed to systems that do
+ not have the resources to carry out the policy in a reasonable
+ period of time.
+
+7.4. Schedule and Time Issues
+
+ This section applies equally to systems that are not policy-based as
+ well as policy-based systems, since configuration operations often
+ need to be synchronized across time zones. Wherever possible, the
+ network elements should support time information using the standard
+ DateAndTime TC that includes local time zone information. Policy-
+ based management often requires more complex time expressions than
+ can be conveyed with the DateAndTime TC. See the Policy-Based
+ Management MIB document [36] for more information. Some deployed
+ systems do not store complex notions of local time and thus may not
+ be able to process policy directives properly that contain time zone
+ relevant data. For this reason, policy management applications
+ should have the ability to ascertain the time keeping abilities of
+ the managed system and make adjustments to the policy for those
+ systems that are time-zone challenged.
+
+7.5. Conflict Detection, Resolution and Error Reporting
+
+ Policies sent to a device may contain conflicting instructions.
+ Detection of such commands can occur at the device or management
+ level and may be resolved using any number of mechanisms (examples
+ are, last configuration set wins, or abort change). These unintended
+ conflicts should be reported. Conflicts can occur at different
+ levels in a chain of commands. Each 'layer' in policy management
+ system should be able to check for some errors and report them. This
+ is conceptually identical to programs raising an exception and
+ passing that information on to software that can do something
+ meaningful with it.
+
+ At the instance level, conflict detection has been performed in a
+ limited way for some time in software that realizes MIB objects at
+ this level of resolution. This detection is independent of policy.
+ The types of 'conflicts' usually checked for are resource
+ availability and validity of the set operations. In a policy enabled
+
+
+
+
+MacFaden, et al. Informational [Page 56]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+ system, there are no additional requirements for this software
+ assuming that good error detection and reporting appropriate to this
+ level have already been implemented.
+
+7.5.1. Changes to Configuration Outside of the Policy System
+
+ It is essential to consider changes to configuration that are
+ initiated outside of the policy system. A goal of SNMP-based policy
+ management is to coexist with other kinds of management software that
+ have historically been instance based management. The best example
+ is the command line interface.
+
+ A notification should be sent whenever an out-of-policy control
+ change is made to an element that is under the control of policy.
+ This notification should include the policy that was affected, the
+ instance of the element that was changed and the object and value
+ that it was changed to.
+
+ Even for those systems that have no concept of policy control, the
+ ideas presented above make sense. That is, if SNMP co-exists with
+ other access methods such as a CLI, it is essential that the
+ management station remain synchronized with changes that might have
+ been made to the managed device using other methods. As a result,
+ the approach of sending a notification when another access method
+ makes a change is a good one. Of course this should be configurable
+ by the user.
+
+7.6. More about Notifications in a Policy System
+
+ Notifications can be useful in determining a failure of a policy as a
+ result of an error in the policy or element(s) under policy control.
+ As with all notifications, they should be defined and controlled in
+ such a way that they do not create a problem by sending more than are
+ helpful over a specific period of time. For example, if a policy is
+ controlling 1,000 interfaces and fails, one notification rather than
+ 1,000 may be the better approach. In addition, such notifications
+ should be defined to include as much information as possible to aid
+ in problem resolution.
+
+7.7. Using Policy to Move Less Configuration Data
+
+
+ One of the advantages of policy-based configuration with SNMP is that
+ many configuration operations can be conveyed with a small amount of
+ data. Changing a single configuration parameter for each of 100
+ interfaces on a system might require 100 CLI commands or 100 SNMP
+ variable bindings using conventional techniques.
+
+
+
+
+MacFaden, et al. Informational [Page 57]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+ Using policy-based configuration with SNMP, a single SET PDU can be
+ sent with the policy information necessary to apply a configuration
+ change to 100 similar interfaces. This efficiency gain is the result
+ of eliminating the need to send the value for each instance to be
+ configured. The 'default' for each of the instances included in the
+ policy is sent, and the rule for selection of the instances that the
+ default is to be applied to can also be carried (see the Policy MIB
+ module [36]).
+
+ To extend the example above, assume that there are 10 parameters that
+ need to change. Using conventional techniques, there would now be
+ 1,000 variable bindings, one for each instance of each new value for
+ each interface. Using policy-based configuration with SNMP, it is
+ still likely that all the information can be conveyed in one SET PDU.
+ The only difference in this case is that there are ten parameters
+ sent that will be the 'template' used to create instances on the
+ managed interfaces.
+
+ This efficiency gain not only applies to SET operations, but also to
+ those management operations that require configuration information.
+ Since the policy is also held in the storage for cross-instance
+ defaults (for example, the pmPolicyTable in [36]), an entire data set
+ that potentially controls hundreds of rows of information can be
+ retrieved in a single GET request.
+
+ A policy-friendly data organization such as this is consistent and
+ integrates well with MIB module objects which support "summary"
+ activation and activation reporting, of the kind discussed in Section
+ 3.3.5.
+
+8. Example MIB Module With Template-based Data
+
+ This section defines a MIB module that controls the heating and air
+ conditioning system for a large building. It contains both
+ configuration and counter objects that allow operators to see how
+ much cooling or heating a particular configuration has consumed.
+ Objects that represent the configuration information at a "default"
+ level (as referenced above) are also included.
+
+ These tables, in combination with the application of the tables' row
+ instance data as templated 'defaults', will allow operators to
+ configure and monitor many rooms at once, change the configuration
+ parameters based on time of day, and make a number of other
+ sophisticated decisions based on the 'policy' implied by these
+ defaults and their application. For this reason, these configuration
+ controls have their instances specified from template object types.
+
+
+
+
+
+MacFaden, et al. Informational [Page 58]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+ In our simplified Heating Ventilation and Air Conditioning (HVAC)
+ model we will create three tables based on a simple analysis. More
+ complicated systems will need more tables, but the principles will be
+ the same.
+
+Step 1: As with any other MIB module design, the first step
+ is to determine what objects are necessary for
+ configuration and control operations. The first table
+ to be created is a fairly traditional monitoring
+ table. It includes indices so that we will know what
+ rooms the counters and status objects are for. It
+ includes an object that is a RowPointer to a table
+ that contains configuration information. The objects
+ for the bldgHVACTable, our first table in the HVAC
+ MIB module are:
+
+Index objects that identify what floor and office we are
+managing:
+
+ bldgHVACFloor
+ bldgHVACOffice
+
+A single index reference to a table that 'glues' configuration
+information defaults with descriptive information:
+
+ bldgHVACCfgTemplate
+
+A set of objects that show status and units of
+work (bldgHVACCoolOrHeatMins) and standard per-row
+SnmpAdminString, StorageType, and RowStatus columnar
+objects:
+
+ bldgHVACFanSpeed
+ bldgHVACCurrentTemp
+ bldgHVACCoolOrHeatMins
+ bldgHVACDiscontinuityTime
+ bldgHVACOwner
+ bldgHVACStatus
+
+Step 2: A configuration description table. The purpose of this
+ table is to provide a unique string identifier for
+ templates. These may be driven by policies in a
+ network. If it were necessary to configure devices
+ to deliver a particular quality of service, the
+ index string of this table could be the name and the
+ description part, it could be a brief description of the
+ underlying motivation such as: "provides extra heat to
+ corner offices to counteract excessive exterior wind
+
+
+
+MacFaden, et al. Informational [Page 59]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+ chill". Standard owner and status objects may also
+ be helpful and are included here. The row columnar
+ objects are:
+
+ bldgHVACCfgTemplateInfoIndex
+ bldgHVACCfgTemplateInfoID
+ bldgHVACCfgTemplateInfoDescr
+ bldgHVACCfgTemplateInfoOwner
+ bldgHVACCfgTemplateInfoStatus
+
+Notice that to this point we have provided no
+configuration information. That will be in the next
+table. Some readers may wonder why this table is not
+combined with the configuration template table described
+in the next step. In fact, they can be. The reason for
+having a separate table is that as systems become more
+complex, there may be more than one configuration table
+that points to these descriptions. Another reason for
+two tables is that this in not reproduced for every
+template and instance, which can save some additional
+data movement. Every designer will have to evaluate the
+tradeoffs between number of objects and data movement
+efficiency just as with other MIB modules.
+
+Step 3: The bldgHVACCfgTemplateTable contains the specific
+ configuration parameters that are pointed to by the
+ bldgHVACConfigPtr object. Note that many rows in the
+ bldgHVACTable can point to an entry in this table. It
+ is also possible for entries to be used by 1 or 0 rows
+ of the bldgHVACTable. It is the property of allowing
+ multiple rows (instances) in the bldgHVACTable to
+ point to a row in this table that can produce such
+ efficiency gains from policy-based management with
+ SNMP. Also notice that the configuration data is tied
+ directly to the counter data so that people can see
+ how configurations impact behavior.
+
+The objects in this table are all that are necessary
+for configuration and connection to the other tables as
+well as the usual SnmpAdminString, StorageType, and
+RowStatus objects:
+
+A simple index to the table:
+
+ bldgHVACCfgTemplateIndex
+
+The configuration objects:
+
+
+
+
+MacFaden, et al. Informational [Page 60]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+ bldgHVACCfgTemplateDesiredTemp
+ bldgHVACCfgTemplateCoolOrHeat
+
+
+Administrative objects for SnmpAdminString and
+RowStatus:
+
+ bldgHVACCfgTemplateInfo
+ bldgHVACCfgTemplateOwner
+ bldgHVACCfgTemplateStorage
+ bldgHVACCfgTemplateStatus
+
+8.1. MIB Module Definition
+
+BLDG-HVAC-MIB DEFINITIONS ::= BEGIN
+IMPORTS
+ MODULE-IDENTITY, Counter32,
+ Gauge32, OBJECT-TYPE, Unsigned32, experimental
+ FROM SNMPv2-SMI
+ MODULE-COMPLIANCE, OBJECT-GROUP
+ FROM SNMPv2-CONF
+ TEXTUAL-CONVENTION,
+ TimeStamp, RowStatus, StorageType
+ FROM SNMPv2-TC
+ SnmpAdminString
+ FROM SNMP-FRAMEWORK-MIB;
+
+
+bldgHVACMIB MODULE-IDENTITY
+ LAST-UPDATED "200303270000Z"
+ ORGANIZATION "SNMPCONF working group
+ E-mail: snmpconf@snmp.com"
+ CONTACT-INFO
+ "Jon Saperia
+ Postal: JDS Consulting
+ 174 Chapman Street
+ Watertown, MA 02472
+ U.S.A.
+ Phone: +1 617 744 1079
+ E-mail: saperia@jdscons.com
+
+ Wayne Tackabury
+ Postal: Gold Wire Technology
+ 411 Waverley Oaks Rd.
+ Waltham, MA 02452
+ U.S.A.
+ Phone: +1 781 398 8800
+ E-mail: wayne@goldwiretech.com
+
+
+
+MacFaden, et al. Informational [Page 61]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+ Michael MacFaden
+ Postal: Riverstone Networks
+ 5200 Great America Pkwy.
+ Santa Clara, CA 95054
+ U.S.A.
+ Phone: +1 408 878 6500
+ E-mail: mrm@riverstonenet.com
+
+ David Partain
+ Postal: Ericsson AB
+ P.O. Box 1248
+ SE-581 12 Linkoping
+ Sweden
+ E-mail: David.Partain@ericsson.com"
+ DESCRIPTION
+ "This example MIB module defines a set of management objects
+ for heating ventilation and air conditioning systems. It
+ also includes objects that can be used to create policies
+ that are applied to rooms. This eliminates the need to send
+ per-instance configuration commands to the system.
+
+ Copyright (C) The Internet Society (2003). This version of
+ this MIB module is part of RFC 3512; see the RFC itself for
+ full legal notices."
+
+ REVISION "200303270000Z"
+ DESCRIPTION
+ "Initial version of BLDG-HVAC-MIB as published in RFC 3512."
+ ::= { experimental 122 }
+
+bldgHVACObjects OBJECT IDENTIFIER ::= { bldgHVACMIB 1 }
+bldgConformance OBJECT IDENTIFIER ::= { bldgHVACMIB 2 }
+
+--
+-- Textual Conventions
+--
+
+BldgHvacOperation ::= TEXTUAL-CONVENTION
+ STATUS current
+ DESCRIPTION
+ "Operations supported by a heating and cooling system.
+ A reference to underlying general systems would go here."
+ SYNTAX INTEGER {
+ heat(1),
+ cool(2)
+ }
+--
+-- HVAC Objects Group
+
+
+
+MacFaden, et al. Informational [Page 62]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+--
+
+bldgHVACTable OBJECT-TYPE
+ SYNTAX SEQUENCE OF BldgHVACEntry
+ MAX-ACCESS not-accessible
+ STATUS current
+ DESCRIPTION
+ "This table is the representation and data control
+ for building HVAC by each individual office.
+ The table has rows for, and is indexed by a specific
+ floor and office number. Each such row includes
+ HVAC statistical and current status information for
+ the associated office. The row also contains a
+ bldgHVACCfgTemplate columnar object that relates the
+ bldgHVACTable row to a row in the bldgHVACCfgTemplateTable.
+ If this value is nonzero, then the instance in the row
+ that has a value for how the HVAC has been configured
+ in the associated template (bldgHVACCfgTeplateTable row).
+ Hence, the bldgHVACCfgTeplateTable row contains the
+ specific configuration values for the offices as described
+ in this table."
+ ::= { bldgHVACObjects 1 }
+
+bldgHVACEntry OBJECT-TYPE
+ SYNTAX BldgHVACEntry
+ MAX-ACCESS not-accessible
+ STATUS current
+ DESCRIPTION
+ "A row in the bldgHVACTable. Each row represents a particular
+ office in the building, qualified by its floor and office
+ number. A given row instance can be created or deleted by
+ set operations upon its bldgHVACStatus columnar
+ object instance."
+ INDEX { bldgHVACFloor, bldgHVACOffice }
+ ::= { bldgHVACTable 1 }
+
+BldgHVACEntry ::= SEQUENCE {
+ bldgHVACFloor Unsigned32,
+ bldgHVACOffice Unsigned32,
+ bldgHVACCfgTemplate Unsigned32,
+ bldgHVACFanSpeed Gauge32,
+ bldgHVACCurrentTemp Gauge32,
+ bldgHVACCoolOrHeatMins Counter32,
+ bldgHVACDiscontinuityTime TimeStamp,
+ bldgHVACOwner SnmpAdminString,
+ bldgHVACStorageType StorageType,
+ bldgHVACStatus RowStatus
+ }
+
+
+
+MacFaden, et al. Informational [Page 63]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+bldgHVACFloor OBJECT-TYPE
+ SYNTAX Unsigned32 (1..1000)
+ MAX-ACCESS not-accessible
+ STATUS current
+ DESCRIPTION
+ "This portion of the index indicates the floor of the
+ building. The ground floor is considered the
+ first floor. For the purposes of this example,
+ floors under the ground floor cannot be
+ controlled using this MIB module."
+ ::= { bldgHVACEntry 1 }
+
+bldgHVACOffice OBJECT-TYPE
+ SYNTAX Unsigned32 (1..2147483647)
+ MAX-ACCESS not-accessible
+ STATUS current
+ DESCRIPTION
+ "This second component of the index specifies the
+ office number."
+ ::= { bldgHVACEntry 2 }
+
+bldgHVACCfgTemplate OBJECT-TYPE
+ SYNTAX Unsigned32
+ MAX-ACCESS read-create
+ STATUS current
+ DESCRIPTION
+ "The index (bldgHVACCfgTemplateIndex instance)
+ of an entry in the 'bldgHVACCfgTemplateTable'.
+ The bldgHVACCfgTable row instance referenced
+ is a pre-made configuration 'template'
+ that represents the configuration described
+ by the bldgHVACCfgTemplateInfoDescr object. Note
+ that not all configurations will be under a
+ defined template. As a result, a row in this
+ bldgHVACTable may point to an entry in the
+ bldgHVACCfgTemplateTable that does not in turn
+ have a reference (bldgHVACCfgTemplateInfo) to an
+ entry in the bldgHVACCfgTemplateInfoTable. The
+ benefit of this approach is that all
+ configuration information is available in one
+ table whether all elements in the system are
+ derived from configured templates or not.
+
+ Where the instance value for this colunmar object
+ is zero, this row represents data for an office
+ whose HVAC status can be monitored using the
+ read-only columnar object instances of this
+ row, but is not under the configuration control
+
+
+
+MacFaden, et al. Informational [Page 64]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+ of the agent."
+ ::= { bldgHVACEntry 3 }
+
+bldgHVACFanSpeed OBJECT-TYPE
+ SYNTAX Gauge32
+ UNITS "revolutions per minute"
+ MAX-ACCESS read-only
+ STATUS current
+ DESCRIPTION
+ "Shows the revolutions per minute of the fan. Fan speed
+ will vary based on the difference between
+ bldgHVACCfgTemplateDesiredTemp and bldgHVACCurrentTemp. The
+ speed is measured in revolutions of the fan blade per minute."
+ ::= { bldgHVACEntry 4 }
+
+bldgHVACCurrentTemp OBJECT-TYPE
+ SYNTAX Gauge32
+ UNITS "degrees in celsius"
+ MAX-ACCESS read-only
+ STATUS current
+ DESCRIPTION
+ "The current measured temperature in the office. Should
+ the current temperature be measured at a value of less
+ than zero degrees celsius, a read of the instance
+ for this object will return a value of zero."
+ ::= { bldgHVACEntry 5 }
+
+bldgHVACCoolOrHeatMins OBJECT-TYPE
+ SYNTAX Counter32
+ UNITS "minutes"
+ MAX-ACCESS read-only
+ STATUS current
+ DESCRIPTION
+ "The total number of heating or cooling minutes that have
+ been consumed since the row was activated. Notice that
+ whether the minutes represent heating or cooling is a
+ function of the configuration of this row. If the system
+ is re-initialized from a cooling to heating function or
+ vice versa, then the counter would start over again. This
+ effect is similar to a reconfiguration of some network
+ interface cards. When parameters that impact
+ configuration are changed, the subsystem must be
+ re-initialized. Discontinuities in the value of this counter
+ can occur at re-initialization of the management system,
+ and at other times as indicated by the value of
+ bldgHVACDiscontinuityTime."
+ ::= { bldgHVACEntry 6 }
+
+
+
+
+MacFaden, et al. Informational [Page 65]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+bldgHVACDiscontinuityTime OBJECT-TYPE
+ SYNTAX TimeStamp
+ MAX-ACCESS read-only
+ STATUS current
+ DESCRIPTION
+ "The value of sysUpTime on the most recent occasion at which
+ any heating or cooling operation for the office designated
+ by this row instance experienced a discontinuity. If
+ no such discontinuities have occurred since the last re-
+ initialization of the this row, then this object contains a
+ zero value."
+ ::= { bldgHVACEntry 7 }
+
+bldgHVACOwner OBJECT-TYPE
+ SYNTAX SnmpAdminString
+ MAX-ACCESS read-create
+ STATUS current
+ DESCRIPTION
+ "The identity of the operator/system that
+ last modified this entry. When a new entry
+ is created, a valid SnmpAdminString must
+ be supplied. If, on the other hand, this
+ entry is populated by the agent 'discovering'
+ unconfigured rooms, the empty string is a valid
+ value for this object."
+ ::= { bldgHVACEntry 8 }
+
+bldgHVACStorageType OBJECT-TYPE
+ SYNTAX StorageType
+ MAX-ACCESS read-create
+ STATUS current
+ DESCRIPTION
+ "The persistence of this row of the table in system storage,
+ as it pertains to permanence across system resets. A columnar
+ instance of this object with value 'permanent' need not allow
+ write-access to any of the columnar object instances in the
+ containing row."
+ ::= { bldgHVACEntry 9 }
+
+bldgHVACStatus OBJECT-TYPE
+ SYNTAX RowStatus
+ MAX-ACCESS read-create
+ STATUS current
+ DESCRIPTION
+ "Controls and reflects the creation and activation status of
+ a row in this table.
+
+ No attempt to modify a row columnar object instance value in
+
+
+
+MacFaden, et al. Informational [Page 66]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+ the bldgHVACTable should be issued while the value of
+ bldgHVACStatus is active(1). Should an agent receive a SET
+ PDU attempting such a modification in this state, an
+ inconsistentValue error should be returned as a result of
+ the SET attempt."
+ ::= { bldgHVACEntry 10 }
+--
+-- HVAC Configuration Template Table
+--
+
+bldgHVACCfgTemplateInfoTable OBJECT-TYPE
+ SYNTAX SEQUENCE OF BldgHVACCfgTemplateInfoEntry
+ MAX-ACCESS not-accessible
+ STATUS current
+ DESCRIPTION
+ "This table provides unique string identification for
+ HVAC templates in a network. If it were necessary to
+ configure rooms to deliver a particular quality of climate
+ control with regard to cooling or heating, the index string
+ of a row in this table could be the template name.
+ The bldgHVACCfgCfgTemplateInfoDescription
+ contains a brief description of the template service objective
+ such as: provides summer cooling settings for executive
+ offices. The bldgHVACCfgTemplateInfo in the
+ bldgHVACCfgTemplateTable will contain the pointer to the
+ relevant row in this table if it is intended that items
+ that point to a row in the bldgHVACCfgTemplateInfoTable be
+ identifiable as being under template control though this
+ mechanism."
+
+ ::= { bldgHVACObjects 2 }
+
+bldgHVACCfgTemplateInfoEntry OBJECT-TYPE
+ SYNTAX BldgHVACCfgTemplateInfoEntry
+ MAX-ACCESS not-accessible
+ STATUS current
+ DESCRIPTION
+ "Each row represents a particular template and
+ description. A given row instance can be created or
+ deleted by set operations upon its
+ bldgHVACCfgTemplateInfoStatus columnar object
+ instance."
+ INDEX { bldgHVACCfgTemplateInfoIndex }
+ ::= { bldgHVACCfgTemplateInfoTable 1 }
+
+BldgHVACCfgTemplateInfoEntry ::= SEQUENCE {
+ bldgHVACCfgTemplateInfoIndex Unsigned32,
+ bldgHVACCfgTemplateInfoID SnmpAdminString,
+
+
+
+MacFaden, et al. Informational [Page 67]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+ bldgHVACCfgTemplateInfoDescr SnmpAdminString,
+ bldgHVACCfgTemplateInfoOwner SnmpAdminString,
+ bldgHVACCfgTemplateInfoStatus RowStatus,
+ bldgHVACCfgTemplateInfoStorType StorageType
+ }
+
+bldgHVACCfgTemplateInfoIndex OBJECT-TYPE
+ SYNTAX Unsigned32 (1..2147483647)
+ MAX-ACCESS not-accessible
+ STATUS current
+ DESCRIPTION
+ "The unique index to a row in this table."
+ ::= { bldgHVACCfgTemplateInfoEntry 1 }
+
+bldgHVACCfgTemplateInfoID OBJECT-TYPE
+ SYNTAX SnmpAdminString
+ MAX-ACCESS read-create
+ STATUS current
+ DESCRIPTION
+ "Textual identifier for this table row, and, consequently
+ the template. This should be a unique name within
+ an administrative domain for a particular template so that
+ all systems in a network that are under the same template
+ can have the same 'handle' (e.g., 'Executive Offices',
+ 'Lobby Areas')."
+ ::= { bldgHVACCfgTemplateInfoEntry 2 }
+
+
+bldgHVACCfgTemplateInfoDescr OBJECT-TYPE
+ SYNTAX SnmpAdminString
+ MAX-ACCESS read-create
+ STATUS current
+ DESCRIPTION
+ "A general description of the template. One example might
+ be - Controls the cooling for offices on higher floors
+ during the summer."
+ ::= { bldgHVACCfgTemplateInfoEntry 3 }
+
+bldgHVACCfgTemplateInfoOwner OBJECT-TYPE
+ SYNTAX SnmpAdminString
+ MAX-ACCESS read-create
+ STATUS current
+ DESCRIPTION
+ "The identity of the operator/system that last modified
+ this entry."
+ ::= { bldgHVACCfgTemplateInfoEntry 4 }
+
+bldgHVACCfgTemplateInfoStatus OBJECT-TYPE
+
+
+
+MacFaden, et al. Informational [Page 68]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+ SYNTAX RowStatus
+ MAX-ACCESS read-create
+ STATUS current
+ DESCRIPTION
+ "The activation status of this row.
+
+ No attempt to modify a row columnar object instance value in
+ the bldgHVACCfgTemplateInfo Table should be issued while the
+ value of bldgHVACCfgTemplateInfoStatus is active(1).
+ Should an agent receive a SET PDU attempting such a modification
+ in this state, an inconsistentValue error should be returned as
+ a result of the SET attempt."
+ ::= { bldgHVACCfgTemplateInfoEntry 5 }
+
+bldgHVACCfgTemplateInfoStorType OBJECT-TYPE
+ SYNTAX StorageType
+ MAX-ACCESS read-create
+ STATUS current
+ DESCRIPTION
+ "The persistence of this row of the table in system storage,
+ as it pertains to permanence across system resets. A columnar
+ instance of this object with value 'permanent' need not allow
+ write-access to any of the columnar object instances in the
+ containing row."
+ ::= { bldgHVACCfgTemplateInfoEntry 6 }
+
+--
+-- HVAC Configuration Template Table
+--
+bldgHVACCfgTemplateTable OBJECT-TYPE
+ SYNTAX SEQUENCE OF BldgHVACCfgTemplateEntry
+ MAX-ACCESS not-accessible
+ STATUS current
+ DESCRIPTION
+ "This table contains the templates, which
+ can be used to set defaults that will
+ be applied to specific offices. The application
+ of those values is accomplished by having a row
+ instance of the bldgHVACTable reference a row of
+ this table (by the value of the former's
+ bldgHVACCfgTemplate columnar instance). Identifying
+ information concerning a row instance of this table
+ can be found in the columnar data of the row instance
+ of the bldgHVACCfgTemplateInfoTable entry referenced
+ by the bldgHVACCfgTemplateInfo columnar object of
+ this table."
+ ::= { bldgHVACObjects 3 }
+
+
+
+
+MacFaden, et al. Informational [Page 69]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+bldgHVACCfgTemplateEntry OBJECT-TYPE
+ SYNTAX BldgHVACCfgTemplateEntry
+ MAX-ACCESS not-accessible
+ STATUS current
+ DESCRIPTION
+ "Each row represents a single set of template parameters
+ that can be applied to selected instances - in this case
+ offices. These policies will be turned on and off by the
+ policy module through its scheduling facilities.
+
+ A given row instance can be created or
+ deleted by set operations upon its
+ bldgHVACCfgTemplateStatus columnar object instance."
+ INDEX { bldgHVACCfgTemplateIndex }
+ ::= { bldgHVACCfgTemplateTable 1 }
+
+BldgHVACCfgTemplateEntry ::= SEQUENCE {
+ bldgHVACCfgTemplateIndex Unsigned32,
+ bldgHVACCfgTemplateDesiredTemp Gauge32,
+ bldgHVACCfgTemplateCoolOrHeat BldgHvacOperation,
+ bldgHVACCfgTemplateInfo Unsigned32,
+ bldgHVACCfgTemplateOwner SnmpAdminString,
+ bldgHVACCfgTemplateStorage StorageType,
+ bldgHVACCfgTemplateStatus RowStatus
+}
+
+bldgHVACCfgTemplateIndex OBJECT-TYPE
+ SYNTAX Unsigned32 (1..2147483647)
+ MAX-ACCESS not-accessible
+ STATUS current
+ DESCRIPTION
+ "A unique value for each defined template in this
+ table. This value can be referenced as a row index
+ by any MIB module that needs access to this information.
+ The bldgHVACCfgTemplate will point to entries in this
+ table."
+ ::= { bldgHVACCfgTemplateEntry 1 }
+
+bldgHVACCfgTemplateDesiredTemp OBJECT-TYPE
+ SYNTAX Gauge32
+ UNITS "degrees in celsius"
+ MAX-ACCESS read-create
+ STATUS current
+ DESCRIPTION
+ "This is the desired temperature setting. It might be
+ changed at different times of the day or based on
+ seasonal conditions. It is permitted to change this value
+ by first moving the row to an inactive state, making the
+
+
+
+MacFaden, et al. Informational [Page 70]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+ change and then reactivating the row."
+ ::= { bldgHVACCfgTemplateEntry 2 }
+
+bldgHVACCfgTemplateCoolOrHeat OBJECT-TYPE
+ SYNTAX BldgHvacOperation
+ MAX-ACCESS read-create
+ STATUS current
+ DESCRIPTION
+ "This controls the heating and cooling mechanism and is
+ set-able by building maintenance. It is permitted to
+ change this value by first moving the row to an inactive
+ state, making the change and then reactivating the row."
+ ::= { bldgHVACCfgTemplateEntry 3 }
+
+bldgHVACCfgTemplateInfo OBJECT-TYPE
+ SYNTAX Unsigned32
+ MAX-ACCESS read-create
+ STATUS current
+ DESCRIPTION
+ "This object points to a row in the
+ bldgHVACCfgTemplateInfoTable. This controls the
+ heating and cooling mechanism and is set-able by
+ building maintenance. It is permissible to change
+ this value by first moving the row to an inactive
+ state, making the change and then reactivating
+ the row. A value of zero means that this entry
+ is not associated with a named template found
+ in the bldgHVACCfgTemplateInfoTable."
+ ::= { bldgHVACCfgTemplateEntry 4 }
+
+bldgHVACCfgTemplateOwner OBJECT-TYPE
+ SYNTAX SnmpAdminString
+ MAX-ACCESS read-create
+ STATUS current
+ DESCRIPTION
+ "The identity of the administrative entity
+ that created this row of the table."
+ ::= { bldgHVACCfgTemplateEntry 5 }
+
+bldgHVACCfgTemplateStorage OBJECT-TYPE
+ SYNTAX StorageType
+ MAX-ACCESS read-create
+ STATUS current
+ DESCRIPTION
+ "The persistence of this row of the table across
+ system resets. A columnar instance of this object with
+ value 'permanent' need not allow write-access to any
+ of the columnar object instances in the containing row."
+
+
+
+MacFaden, et al. Informational [Page 71]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+ ::= { bldgHVACCfgTemplateEntry 6 }
+
+bldgHVACCfgTemplateStatus OBJECT-TYPE
+ SYNTAX RowStatus
+ MAX-ACCESS read-create
+ STATUS current
+ DESCRIPTION
+ "The activation status of this row of the table.
+
+ No attempt to modify a row columnar object instance value in
+ the bldgHVACCfgTemplateTable should be issued while the
+ value of bldgHVACCfgTemplateStatus is active(1).
+ Should an agent receive a SET PDU attempting such a modification
+ in this state, an inconsistentValue error should be returned as
+ a result of the SET attempt."
+ ::= { bldgHVACCfgTemplateEntry 7 }
+
+--
+-- Conformance Information
+--
+
+bldgCompliances OBJECT IDENTIFIER ::= { bldgConformance 1 }
+bldgGroups OBJECT IDENTIFIER ::= { bldgConformance 2 }
+
+-- Compliance Statements
+
+bldgCompliance MODULE-COMPLIANCE
+ STATUS current
+ DESCRIPTION
+ "The requirements for conformance to the BLDG-HVAC-MIB. The
+ bldgHVACObjects group must be implemented to conform to the
+ BLDG-HVAC-MIB."
+ MODULE -- this module
+
+ GROUP bldgHVACObjectsGroup
+ DESCRIPTION
+ "The bldgHVACObjects is mandatory for all systems that
+ support HVAC systems."
+ ::= { bldgCompliances 1 }
+
+bldgHVACObjectsGroup OBJECT-GROUP
+ OBJECTS {
+ bldgHVACCfgTemplate,
+ bldgHVACFanSpeed, bldgHVACCurrentTemp,
+ bldgHVACCoolOrHeatMins, bldgHVACDiscontinuityTime,
+ bldgHVACOwner, bldgHVACStatus,
+ bldgHVACStorageType, bldgHVACCfgTemplateInfoID,
+ bldgHVACCfgTemplateInfoDescr, bldgHVACCfgTemplateInfoOwner,
+
+
+
+MacFaden, et al. Informational [Page 72]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+ bldgHVACCfgTemplateInfoStatus,
+ bldgHVACCfgTemplateInfoStorType,
+ bldgHVACCfgTemplateDesiredTemp,
+ bldgHVACCfgTemplateCoolOrHeat,
+ bldgHVACCfgTemplateInfo,
+ bldgHVACCfgTemplateOwner,bldgHVACCfgTemplateStorage,
+ bldgHVACCfgTemplateStatus
+ }
+ STATUS current
+ DESCRIPTION
+ "The bldgHVACObjects Group."
+ ::= { bldgGroups 1 }
+
+END
+
+8.2. Notes on MIB Module with Template-based Data
+
+ The primary purpose of the example "HVAC" MIB module is to show how
+ to construct a single module that includes configuration, template,
+ counter and state information in a single module. If this were a
+ 'real' module we would also have included definitions for
+ notifications for the configuration change operations as previously
+ described. We also would have included notifications for faults and
+ other counter threshold events.
+
+ Implementation and Instance Extensions:
+
+ Just as with networking technologies, vendors may wish to add
+ extensions that can distinguish their products from the competition.
+ If an HVAC vendor also wanted to support humidity control, they could
+ add that facility to their equipment and use AUGMENTS for the
+ bldgHVACTemplateTable with two objects, one that indicates the
+ desired humidity and the other, the actual. The
+ bldgHVACTemplateTable could also be extended using this same approach
+ so that HVAC policies could easily be extended to support this
+ vendor.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+MacFaden, et al. Informational [Page 73]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+8.3. Examples of Usage of the MIB
+
+ The following two examples use two templates to configure the
+ temperature in executive offices and in conference rooms. The
+ "conference rooms" template is applied to all conference rooms (which
+ happen to be office 104 on each floor), and the "executive offices"
+ template is applied to executive offices.
+
+ If offices 24, 25, and 26 on the third floor are executive offices,
+ the values in the bldgHVACTable might be:
+
+ bldgHVACCfgTemplate.3.24 = 2
+ bldgHVACFanSpeed.3.24 = 2989
+ bldgHVACCurrentTemp.3.24 = 24
+ bldgHVACCoolOrHeatMins.3.24 = 123
+ bldgHVACDiscontinuityTime.3.24 = sysUpTime + 12h + 21m
+ bldgHVACOwner.3.24 = "policy engine"
+ bldgHVACStorageType.3.24 = nonVolatile(3)
+ bldgHVACStatus.3.24 = active(1)
+
+ bldgHVACCfgTemplate.3.25 = 2
+ bldgHVACFanSpeed.3.25 = 0
+ bldgHVACCurrentTemp.3.25 = 22
+ bldgHVACCoolOrHeatMins.3.25 = 298
+ bldgHVACDiscontinuityTime.3.25 = sysUpTime + 4h + 2m
+ bldgHVACOwner.3.25 = "policy engine"
+ bldgHVACStorageType.3.25 = nonVolatile(3)
+ bldgHVACStatus.3.25 = active(1)
+
+ bldgHVACCfgTemplate.3.26 = 2
+ bldgHVACFanSpeed.3.26 = 0
+ bldgHVACCurrentTemp.3.26 = 22
+ bldgHVACCoolOrHeatMins.3.26 = 982
+ bldgHVACOwner.3.26 = "policy engine"
+ bldgHVACStorageType.3.26 = nonVolatile(3)
+ bldgHVACStatus.3.26 = active(1)
+
+ The second entry in the bldgHVACCfgTemplateTable, to which all of the
+ above point, might have the following configuration:
+
+ bldgHVACCfgTemplateDesiredTemp.2 = 22
+ bldgHVACCfgTemplateCoolOrHeat.2 = cool(2)
+ bldgHVACCfgTemplateInfo.2 = 2
+ bldgHVACCfgTemplateOwner.2 = "Senior Executive assistant"
+ bldgHVACCfgTemplateStorage.2 = nonVolatile(3)
+ bldgHVACCfgTemplateStatus.2 = active(1)
+
+
+
+
+
+MacFaden, et al. Informational [Page 74]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+ and the associated template information ("executive offices") might
+ be:
+
+ bldgHVACCfgTemplateInfoID.2 = "executive offices"
+ bldgHVACCfgTemplateInfoDescr.2 = "Controls temperature for executive
+ offices"
+ bldgHVACCfgTemplateInfoOwner.2 = "Senior Executive assistant"
+ bldgHVACCfgTemplateInfoStorType.2 = nonVolatile(3)
+ bldgHVACCfgTemplateInfoStatus.2 = active(1)
+
+ The policy engine can now associate instances of executive offices
+ with the template called "executive offices" and apply the values in
+ the second entry of the bldgHVACCfgTemplateTable to each of the
+ instances of the executive offices. This will then attempt to set
+ the temperature in executive offices to 22 degrees celsius.
+
+ It is also possible that there may be an office configured for a
+ particular temperature, but without using a template. For example,
+ office 28 on the third floor might look like this:
+
+ bldgHVACCfgTemplate.3.28 = 3
+ bldgHVACFanSpeed.3.28 = 50
+ bldgHVACCurrentTemp.3.28 = 26
+ bldgHVACCoolOrHeatMins.3.28 = 0
+ bldgHVACDiscontinuityTime.3.28 = 0
+ bldgHVACOwner.3.28 = "Executive with poor circulation"
+ bldgHVACStorageType.3.28 = nonVolatile(3)
+ bldgHVACStatus.3.28 = active(1)
+
+ The entry in the bldgHVACCfgTemplateTable (to which
+ bldgHVACCfgTemplate.3.28 points) might instead look like:
+
+ bldgHVACCfgTemplateDesiredTemp.3 = 28
+ bldgHVACCfgTemplateCoolOrHeat.3 = cool(2)
+ bldgHVACCfgTemplateInfo.3 = 0.0
+ bldgHVACCfgTemplateOwner.3 = "Executive with poor circulation"
+ bldgHVACCfgTemplateStorage.3 = nonVolatile(3)
+ bldgHVACCfgTemplateStatus.3 = active(1)
+
+ Note that this entry does not point to a template.
+
+ If the executive's circulation improves so that the temperature
+ should be aligned with other executive offices, this is accomplished
+ by changing the value of bldgHVACCfgTemplate.3.28 from
+ bldgHVACCfgTemplateInfoID.3 to bldgHVACCfgTemplateInfoID.2 (shown
+ above).
+
+
+
+
+
+MacFaden, et al. Informational [Page 75]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+ Finally, there might be offices for which there is no configured
+ temperature but management applications can read the current
+ temperature, fan speed, and cooling or heating minutes from the
+ bldgHVACTable. In that case, the value of bldgHVACCfgTemplate will
+ be a zero index ("null"), as will the value of bldgHVACOwner.
+
+ bldgHVACCfgTemplate.4.2 = 0
+ bldgHVACFanSpeed.3.28 = 50
+ bldgHVACCurrentTemp.3.28 = 26
+ bldgHVACCoolOrHeatMins.3.28 = 0
+ bldgHVACDiscontinuityTime.3.28 = 0
+ bldgHVACOwner.3.28 = ""
+ bldgHVACStorageType.3.28 = nonVolatile(3)
+ bldgHVACStatus.3.28 = active(1)
+
+ As a second example, the conference rooms on several floors are
+ configured using the "conference rooms" template. When the values in
+ the bldgHVACTable pertaining to conference rooms are read, it might
+ look like:
+
+ bldgHVACCfgTemplate.12.104 = bldgHVACCfgTemplateDesiredTemp.1
+ bldgHVACFanSpeed.12.104 = 1423
+ bldgHVACCurrentTemp.12.104 = 21
+ bldgHVACCoolOrHeatMins.12.104 = 2193
+ bldgHVACDiscontinuityTime.12.104 = sysUpTime + 36h + 15m
+ bldgHVACOwner.12.104 = = "Bob the Conference Guy"
+ bldgHVACStorageType.12.104 = nonVolatile(3)
+ bldgHVACStatus.12.104 = active(1)
+
+ bldgHVACCfgTemplate.14.104 = bldgHVACCfgTemplateDesiredTemp.1
+ bldgHVACFanSpeed.14.104 = 1203
+ bldgHVACCurrentTemp.14.104 = 20
+ bldgHVACCoolOrHeatMins.14.104 = 293
+ bldgHVACDiscontinuityTime.14.104 = sysUpTime + 5h + 54m
+ bldgHVACOwner.14.104 = = "Bob the Conference Guy"
+ bldgHVACStorageType.14.104 = nonVolatile(3)
+ bldgHVACStatus.14.104 = active(1)
+
+ bldgHVACCfgTemplate.15.104 = bldgHVACCfgTemplateDesiredTemp.1
+ bldgHVACFanSpeed.15.104 = 12
+ bldgHVACCurrentTemp.15.104 = 19
+ bldgHVACCoolOrHeatMins.15.104 = 1123
+ bldgHVACDiscontinuityTime.15.103 = sysUpTime + 2d + 2h + 7m
+ bldgHVACOwner.15.104 = = "Bob the Conference Guy"
+ bldgHVACStorageType.15.104 = nonVolatile(3)
+ bldgHVACStatus.15.104 = active(1)
+
+
+
+
+
+MacFaden, et al. Informational [Page 76]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+ The desired temperature and whether to heat or cool is configured in
+ the first entry of the bldgHVACCfgTemplateTable, which tries to set
+ the temperature to 19 degrees celsius in conference rooms:
+
+ bldgHVACCfgTemplateDesiredTemp.1 = 19
+ bldgHVACCfgTemplateCoolOrHeat.1 = cool(2)
+ bldgHVACCfgTemplateInfo.1 = bldgHVACCfgTemplateInfoID.1
+ bldgHVACCfgTemplateOwner.1 = "Bob the Conference Guy"
+ bldgHVACCfgTemplateStorage.1 = nonVolatile(3)
+ bldgHVACCfgTemplateStatus.1 = active(1)
+
+ The associated template information would then have:
+
+ bldgHVACCfgTemplateInfoID.1 = "conference rooms"
+ bldgHVACCfgTemplateInfoDescr.1 = "Controls temperature in conference
+ rooms" bldgHVACCfgTemplateInfoOwner.1 = "Bob the Conference Guy"
+ bldgHVACCfgTemplateInfoStorType.1 = nonVolatile(3)
+ bldgHVACCfgTemplateInfoStatus.1 = active(1)
+
+ The policy system can then apply this template (cool to 19 degrees
+ Celsius) to its notion of all of the conference rooms in the
+ building.
+
+9. Security Considerations
+
+ This document discusses practices and methods for using the SNMP for
+ management and distribution of configuration information for network
+ elements. Any effective use of the SNMP in this application must
+ concern itself with issues of authentication of the management
+ entities initiating configuration change and management, in addition
+ to the integrity of the configuration data itself. Other more subtle
+ considerations also exist.
+
+ To that end, the section of this document entitled "Deployment and
+ Security Issues" covers these security considerations to the extent
+ they affect the current practices described throughout this document.
+ In particular, in the subsection entitled "Secure Agent
+ Considerations", there is a recommendation for the usage of Version 3
+ of the SNMP, and its essential presumption as a foundation for other
+ practices described throughout. With the exception of a small number
+ of cases where a mention is made to the contrary to illustrate
+ techniques for coexistence with application entities dependent upon
+ earlier versions of the SNMP, that recommendation of usage of Version
+ 3 of the SNMP is reiterated here.
+
+
+
+
+
+
+
+MacFaden, et al. Informational [Page 77]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+10. Acknowledgments
+
+ This document was produced by the SNMPCONF Working Group. In
+ particular, the editors wish to thank:
+
+ Christopher Anderson
+ Andy Bierman
+ Greg Bruell
+ Dr Jeffrey Case
+ Chris Elliott
+ Joel Halpern
+ Pablo Halpern
+ Wes Hardaker
+ David Harrington
+ Harrie Hazewinkel
+ Thippanna Hongal
+ Bob Moore
+ David T. Perkins
+ Randy Presuhn
+ Dan Romascanu
+ Shawn Routhier
+ Steve Waldbusser
+ Bert Wijnen
+
+11. Normative References
+
+ [1] Harrington, D., Presuhn, R. and B. Wijnen, "An Architecture for
+ Describing Simple Network Management Protocol (SNMP) Management
+ Frameworks", STD 62, RFC 3411, December 2002.
+
+ [2] McCloghrie, K., Perkins, D. and J. Schoenwaelder, "Structure of
+ Management Information Version 2 (SMIv2)", STD 58, RFC 2578,
+ April 1999.
+
+ [3] McCloghrie, K., Perkins, D. and J. Schoenwaelder, "Textual
+ Conventions for SMIv2", STD 58, RFC 2579, April 1999.
+
+ [4] McCloghrie, K., Perkins, D. and J. Schoenwaelder, "Conformance
+ Statements for SMIv2", STD 58, RFC 2580, April 1999.
+
+ [5] Presuhn, R. (Ed.), "Transport Mappings for the Simple Network
+ Management Protocol (SNMPv2)", STD 62, RFC 3417, December 2002.
+
+ [6] Case, J., Harrington D., Presuhn R. and B. Wijnen, "Message
+ Processing and Dispatching for the Simple Network Management
+ Protocol (SNMP)", STD 62, RFC 3412, December 2002.
+
+
+
+
+
+MacFaden, et al. Informational [Page 78]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+ [7] Blumenthal, U. and B. Wijnen, "User-based Security Model (USM)
+ for version 3 of the Simple Network Management Protocol
+ (SNMPv3)", STD 62, RFC 3414, December 2002.
+
+ [8] Presuhn, R. (Ed.), "Version 2 of the Protocol Operations for the
+ Simple Network Management Protocol (SNMP)", STD 62, RFC 3416,
+ December 2002.
+
+ [9] Levi, D., Meyer, P., and B. Stewart, "Simple Network Management
+ Protocol Applications", STD 62, RFC 3413, December 2002.
+
+ [10] Wijnen, B., Presuhn, R. and K. McCloghrie, "View-based Access
+ Control Model (VACM) for the Simple Network Management Protocol
+ (SNMP)", STD 62, RFC 3415, December 2002.
+
+ [11] Presuhn, R. (Ed.), "Management Information Base for the Simple
+ Network Management Protocol (SNMPv2)", STD 62, RFC 3418,
+ December 2002.
+
+ [12] Case, J., Mundy, R., Partain, D. and B. Stewart, "Introduction
+ and Applicability Statements for Internet-Standard Management
+ Framework", RFC 3410, December 2002.
+
+ [13] Daniele, M., Haberman, B., Routhier, S. and J. Schoenwaelder,
+ "Textual Conventions for Internet Network Addresses", RFC 3291,
+ May 2002.
+
+ [14] McCloghrie, K. (Ed.), "SNMPv2 Management Information Base for
+ the Internet Protocol using SMIv2", RFC 2011, November 1996.
+
+12. Informative References
+
+ [15] Rose, M. and K. McCloghrie, "Structure and Identification of
+ Management Information for TCP/IP-based Internets", STD 16, RFC
+ 1155, May 1990.
+
+ [16] Rose, M. and K. McCloghrie, "Concise MIB Definitions", STD 16,
+ RFC 1212, March 1991.
+
+ [17] Rose, M., "A Convention for Defining Traps for use with the
+ SNMP", RFC 1215, March 1991.
+
+ [18] Case, J., Fedor, M., Schoffstall, M. and J. Davin, "Simple
+ Network Management Protocol", STD 15, RFC 1157, May 1990.
+
+ [19] Case, J., McCloghrie, K., Rose, M., and S. Waldbusser,
+ "Introduction to Community-based SNMPv2", RFC 1901, January
+ 1996.
+
+
+
+MacFaden, et al. Informational [Page 79]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+ [20] McCloghrie, K. and F. Kastenholz, "The Interfaces Group MIB",
+ RFC 2863, June 2000.
+
+ [21] Brown, C. and F. Baker, "Management Information Base for Frame
+ Relay DTEs Using SMIv2", RFC 2115, September 1997.
+
+ [22] Baker, F. (Ed.), "Requirements for IP Version 4 Routers", RFC
+ 1812, June 1995.
+
+ [23] Hawkinson, J. and T. Bates, "Guidelines for Creation, Selection,
+ and Registration of an Autonomous System (AS)", BCP 6, RFC 1930,
+ March 1996.
+
+ [24] Decker, E., Langille, P., Rijsinghani, A. and K. McCloghrie,
+ "Definitions of Managed Objects for Bridges", RFC 1493, July
+ 1993.
+
+ [25] Levi, D. and J. Schoenwaelder "Definitions of Managed Objects
+ for Scheduling Management Operations", RFC 3231, January 2002.
+
+ [26] Bell, E., Smith, A., Langille, P., Rijsinghani, A. and K.
+ McCloghrie, "Definitions of Managed Objects for Bridges with
+ Traffic Classes, Multicast Filtering and Virtual LAN
+ Extensions", RFC 2674, August 1999.
+
+ [27] Baker, F., "IP Forwarding Table MIB", RFC 2096, January 1997.
+
+ [28] St. Johns, M. (Ed.), "Radio Frequency (RF) Interface Management
+ Information Base for MCNS/DOCSIS compliant RF interfaces", RFC
+ 2670, August 1999.
+
+ [29] Baker, F. and R. Coltun, "OSPF Version 2 Management Information
+ Base", RFC 1850, November 1995.
+
+ [30] Blake, S., Black, D., Carlson M., Davies, E., Wang, Z. and W.
+ Weiss, "An Architecture for Differentiated Services ", RFC 2475,
+ December 1998.
+
+ [31] Willis, S., Burruss, J. and J. Chu (Ed.), "Definitions of
+ Managed Objects for the Fourth Version of the Border Gateway
+ Protocol (BGP-4) using SMIv2", RFC 1657, July 1994.
+
+ [32] Waldbusser, S., "Remote Network Monitoring Management
+ Information Base", RFC 2819, May 2000.
+
+ [33] McCloghrie, K. and G. Hanson, "The Inverted Stack Table
+ Extension to the Interfaces Group MIB", RFC 2864, June 2000.
+
+
+
+
+MacFaden, et al. Informational [Page 80]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+ [34] McCloghrie, K. and A. Bierman, "Entity MIB (Version 2)", RFC
+ 2737, December 1999.
+
+ [35] ITU-T,, Recommendation M.3010., PRINCIPLES FOR A
+ TELECOMMUNICATIONS MANAGEMENT NETWORK. February, 2000.
+
+ [36] Waldbusser, S., Saperia, J., and Hongal, T., "Policy Based
+ Management MIB", Work-in-progress.
+
+ [37] Heintz, L., "SNMP Row Operations Extensions", Work-in-progress.
+
+ [38] Zeltserman, D., "A Practical Guide to Snmpv3 and Network
+ Management", Prentice Hall, 1999.
+
+ [39] Noto, M., Spiegel, E. and K. Tesink, "Definitions of Textual
+ Conventions and OBJECT-IDENTITIES for ATM Management", RFC 2514,
+ February 1999.
+
+ [40] Kassaveri, R., Editor, "Distributed Management Expression MIB",
+ RFC 2982, October 2000.
+
+ [41] St. Johns, M., "DOCSIS Cable Device MIB Cable Device Management
+ Information Base for DOCSIS compliant Cable Modems and Cable
+ Modem Termination Systems", RFC 2669, August 1999.
+
+ [42] Westerinen, A., Schnizlein, J., Strassner, J., Scherling, M.,
+ Quinn, B., Herzog, S., Huynh, A., Carlson, M., Perry, J. and S.
+ Waldbusser, "Terminology for Policy-Based Management", RFC 3198,
+ November 2001.
+
+ [43] http://wwww.cisco.com/univercd/cc/td/product/software/ios113ed/
+ 11ed_cr/secur_c/scprt/scacls.pdf.
+
+ [44] Waldbusser, S., "Remote Network Monitoring Management
+ Information Base Version 2 using SMIv2", RFC 2021, January 1997.
+
+13. 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 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
+
+
+
+MacFaden, et al. Informational [Page 81]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+ 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.
+
+14. Editors' Addresses
+
+ Michael R. MacFaden
+ Riverstone Networks, Inc
+ 5200 Great America Parkway
+ Santa Clara, CA 95054
+
+ EMail: mrm@riverstonenet.com
+
+
+ David Partain
+ Ericsson AB
+ P.O. Box 1248
+ SE-581 12 Linkoping
+ Sweden
+
+ EMail: David.Partain@ericsson.com
+
+
+ Jon Saperia
+ JDS Consulting
+ 174 Chapman Street
+ Watertown, MA 02472
+
+ EMail: saperia@jdscons.com
+
+
+ Wayne F. Tackabury
+ Gold Wire Technology
+ 411 Waverley Oaks Rd.
+ Waltham, MA 02452
+
+ EMail: wayne@goldwiretech.com
+
+
+
+
+
+
+
+
+MacFaden, et al. Informational [Page 82]
+
+RFC 3512 Configuring Networks and Devices with SNMP April 2003
+
+
+15. Full Copyright Statement
+
+ Copyright (C) The Internet Society (2003). 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.
+
+Acknowledgement
+
+ Funding for the RFC Editor function is currently provided by the
+ Internet Society.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+MacFaden, et al. Informational [Page 83]
+