HTTP/1.1 200 OK Date: Tue, 09 Apr 2002 12:05:17 GMT Server: Apache/1.3.20 (Unix) Last-Modified: Sat, 02 Mar 1996 14:17:24 GMT ETag: "3ddd38-635d-31385874" Accept-Ranges: bytes Content-Length: 25437 Connection: close Content-Type: text/plain draft Row creation with SNMPv1 Oct 19, 1993 Row creation with SNMPv1 October 19, 1993 Steven Waldbusser Carnegie Mellon University waldbusser@cmu.edu Status of this Memo This document is an Internet Draft. Internet Drafts are working documents of the Internet Engineering Task Force (IETF), its Areas, and its Working Groups. Note that other groups may also distribute working documents as Internet Drafts. Internet Drafts are valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet Drafts as reference material or to cite them other than as a "work in progress". Expires Apr 19, 1994 [Page 1] draft Row creation with SNMPv1 Oct 19, 1993 1. Introduction This memo describes how the RowStatus textual convention, as defined in RFC 1443 [2], is used with version one of SNMP. The RowStatus textual convention, and the interactions between a manager and agent that use it, have been described in terms of SNMPv2 protocol interactions. If the RowStatus textual convention is used in an SNMPv2 MIB, this memo shows the interactions that an SNMPv1 manager will have with a SNMPv1 only, or bi-lingual SNMPv1/SNMPv2 agent that implements this MIB. Expires Apr 19, 1994 [Page 2] draft Row creation with SNMPv1 Oct 19, 1993 2. The SNMPv2 Network Management Framework The SNMPv2 Network Management Framework consists of four major components. They are: o RFC 1442 which defines the SMI, the mechanisms used for describing and naming objects for the purpose of management. o RFC 1213 defines MIB-II, the core set of managed objects for the Internet suite of protocols. o RFC 1445 which defines the administrative and other architectural aspects of the framework. o RFC 1448 which defines the protocol used for network access to managed objects. The Framework permits new objects to be defined for the purpose of experimentation and evaluation. Expires Apr 19, 1994 [Page 3] draft Row creation with SNMPv1 Oct 19, 1993 3. Overview The RowStatus textual convention is used to manage the creation and deletion of conceptual rows, and is used as the value of the SYNTAX clause for the status column of a conceptual row (as described in Section 7.7.1 of [1].) Before the definition of RowStatus in SNMPv2, the only mechanism commonly used to manage the creation and deletion of conceptual rows with SNMPv1 was the EntryStatus textual convention in the RMON MIB. It is recommended that new MIBs use the RowStatus textual convention because it provides a simple migration path to SNMPv2. This memo describes how to use SNMPv2's RowStatus with SNMPv1. 4. Use of RowStatus with SNMPv1 A RowStatus column has six defined values: - 'active', which indicates that the conceptual row is available for use by the managed device; - 'notInService', which indicates that the conceptual row exists in the agent, but is unavailable for use by the managed device (see NOTE below); - 'notReady', which indicates that the conceptual row exists in the agent, but is missing information necessary in order to be available for use by the managed device; - 'createAndGo', which is supplied by a management station wishing to create a new instance of a conceptual row and to have it available for use by the managed device; - 'createAndWait', which is supplied by a management station wishing to create a new instance of a conceptual row but not to have it available for use by the managed device; and, - 'destroy', which is supplied by a management station wishing to delete all of the instances associated with an existing conceptual row. Whereas five of the six values (all except 'notReady') may be specified in a management protocol set operation, only three values will be returned in response to a management protocol Expires Apr 19, 1994 [Page 4] draft Row creation with SNMPv1 Oct 19, 1993 retrieval operation: 'notReady', 'notInService' or 'active'. That is, when queried, an existing conceptual row has only three states: it is either available for use by the managed device (the status column has value 'active'); it is not available for use by the managed device, though the agent has sufficient information to make it so (the status column has value 'notInService'); or, it is not available for use by the managed device, because the agent lacks sufficient information (the status column has value 'notReady'). NOTE WELL This textual convention may be used for a MIB table, irrespective of whether the values of that table's conceptual rows are able to be modified while it is active, or whether its conceptual rows must be taken out of service in order to be modified. That is, it is the responsibility of the DESCRIPTION clause of the status column to specify whether the status column must be 'notInService' in order for the value of some other column of the same conceptual row to be modified. To summarize the effect of having a conceptual row with a status column having a SYNTAX clause value of RowStatus, consider the following state diagram. This state diagram is the same as that for SNMPv2's RowStatus, except that all 'inconsistentValue' and 'wrongValue' errors have been translated to 'badValue'. STATE +--------------+-----------+-------------+------------- | A | B | C | D | |status col.|status column| |status column | is | is |status column ACTION |does not exist| notReady | notInService| is active --------------+--------------+-----------+-------------+------------- set status |noError ->D|badValue |badValue |badValue column to | or | | | createAndGo |badValue | | | | | | | --------------+--------------+-----------+-------------+------------- set status |noError see 1|badValue |badValue |badValue column to | or | | | createAndWait |badValue | | | --------------+--------------+-----------+-------------+------------- set status |badValue |badValue |noError |noError column to | | | | active | | | | Expires Apr 19, 1994 [Page 5] draft Row creation with SNMPv1 Oct 19, 1993 | | or | | | | | | | |see 2 ->D| ->D| ->D --------------+--------------+-----------+-------------+------------- set status |badValue |badValue |noError |noError ->C column to | | | | notInService | | | | | | or | | or | | | | | |see 3 ->C| ->C|badValue --------------+--------------+-----------+-------------+------------- set status |noError |noError |noError |noError column to | | | | destroy | ->A| ->A| ->A| ->A --------------+--------------+-----------+-------------+------------- set any other |see 4 |noError |noError |noError column to some| | | | value | ->A| see 1| ->C| ->D --------------+--------------+-----------+-------------+------------- (1) goto B or C, depending on information available to the agent. (2) if other variable bindings included in the same PDU, provide values for all columns which are missing but required, then return noError and goto D. (3) if other variable bindings included in the same PDU, provide values for all columns which are missing but required, then return noError and goto C. (4) at the discretion of the agent, either noError or badValue may be returned. NOTE: Other processing of the set request may result in a response other than noError being returned. Expires Apr 19, 1994 [Page 6] draft Row creation with SNMPv1 Oct 19, 1993 4.1. Conceptual Row Creation with SNMPv1 There are four potential interactions when creating a conceptual row: selecting an instance-identifier which is not in use; creating the conceptual row; initializing any objects for which the agent does not supply a default; and, making the conceptual row available for use by the managed device. Interaction 1: Selecting an Instance-Identifier The algorithm used to select an instance- identifier varies for each conceptual row. In some cases, the instance-identifier is semantically significant, e.g., the destination address of a route, and a management station selects the instance-identifier according to the semantics. In other cases, the instance-identifier is used solely to distinguish conceptual rows, and a management station without specific knowledge of the conceptual row might examine the instances present in order to determine an unused instance- identifier. (This approach may be used, but it is often highly sub-optimal; however, it is also a questionable practice for a naive management station to attempt conceptual row creation.) Alternately, the MIB module which defines the conceptual row might provide one or more objects which provide assistance in determining an unused instance-identifier. For example, if the conceptual row is indexed by an integer-value, then an object having an integer- valued SYNTAX clause might be defined for such a purpose, allowing a management station to issue a management protocol retrieval operation. In order to avoid unnecessary collisions between competing management stations, 'adjacent' retrievals of this object should be different. Finally, the management station could select a pseudo-random number to use as the index. In the event that this index was already in use and a badValue was returned in response to the management protocol set operation, the management station should simply select a new pseudo-random number and retry the operation. A MIB designer should choose between the two latter algorithms based on the size of the table (and therefore the efficiency of each algorithm). For tables in which a large number of entries are expected, it is recommended that a MIB object be defined that returns an acceptable index for creation. For tables with small Expires Apr 19, 1994 [Page 7] draft Row creation with SNMPv1 Oct 19, 1993 numbers of entries, it is recommended that the latter pseudo-random index mechanism be used. Note that the above interaction is the same as that for SNMPv2. Interaction 2: Creating the Conceptual Row Once an unused instance-identifier has been selected, the management station determines if it wishes to create and activate the conceptual row in one transaction or in a negotiated set of interactions. Both of these mechanisms are different when using SNMPv1. Interaction 2a: Creating and Activating the Conceptual Row When using SNMPv2, the management station first determines those columns for which it must or must not provide values. SNMPv2 performs this function using the exception mechanism that is not present in SNMPv1. Depending on the complexity of the table and the management station's knowledge of the agent's capabilities, this determination can be made locally by the SNMPv1 management station. It is recommended that the management station make this determination locally, as this will increase the efficiency of the resulting transaction. Once the column requirements have been determined, a management protocol set operation is accordingly issued. This operation also sets the new instance of the status column to 'createAndGo'. When the agent processes the set operation, it verifies that it has sufficient information to make the conceptual row available for use by the managed device. The information available to the agent is provided by two sources: the management protocol set operation which creates the conceptual row, and, implementation-specific defaults supplied by the agent (note that an agent must provide implementation-specific defaults for at least those objects which it implements as read-only). If there is sufficient information available, then the conceptual row is created, a 'noError' response is returned, the status column is set to 'active', and no further interactions are necessary (i.e., interactions 3 and 4 are skipped). If there is insufficient information, then the conceptual row is not created, and the set operation fails with an error of 'badValue'. On this error, the management station determines if the failure was due to the status column or to one of the other columns by inspection of the error-index value in the Expires Apr 19, 1994 [Page 8] draft Row creation with SNMPv1 Oct 19, 1993 response to the set. If the error was due to the status column, a subsequent retrieval of the status object can determine if the selected instance already existed, in which case we return to interaction 1, otherwise we must assume that the original operation failed to specify a required column. If the error was not due to the status column and was a 'noSuchName' error, a column was either not implemented or not accessible. It is recommended that the management station remove the column referenced by the error-index from the list of those columns for which it will provide values and then repeat interaction 2, informing the user of the modified request. Interaction 2b: Negotiating the Creation of the Conceptual Row The management station issues a management protocol set operation which sets the desired instance of the status column to 'createAndWait'. If the agent is unwilling to process a request of this sort, the set operation fails with an error of 'badValue'. (As a consequence, such an agent must be prepared to accept a single management protocol set operation, i.e., interaction 2a above, containing all of the columns indicated by its column requirements.) Of course a 'badValue' might also be returned because the selected instance already existed. Thus, if a 'badValue' response is received by the management station, a subsequent retrieval of the status object can determine if the selected instance already existed, in which case we return to interaction 1, otherwise it must assume that the agent is only willing to accept a single management protocol set operation and must proceed to interaction 2a. Otherwise, the agent creates the conceptual row, a 'noError' response is returned, and the status column is immediately set to either 'notInService' or 'notReady', depending on whether it has sufficient information to make the conceptual row available for use by the managed device. If there is sufficient information available, then the status column is set to 'notInService'; otherwise, if there is insufficient information, then the status column is set to 'notReady'. Regardless, we proceed to interaction 3. Interaction 3: Initializing non-defaulted Objects The management station can now inspect any defaulted values before deciding on the final values it may wish to set for each column. Expires Apr 19, 1994 [Page 9] draft Row creation with SNMPv1 Oct 19, 1993 It then issues a getnext request for the values in all columns (this request will actually contain Object Names that immediately precede the desired Object Name for each column value). In the response, for each column, there are three possible outcomes: - a value for the correct column is returned, indicating that the agent implements the object-type associated with this column and provided a default value. For those columns to which the agent provides read-create access, a value return tells the management station that it may issue additional management protocol set operations, if it desires, in order to change the value associated with this column. - a value for an unexpected column is returned, or - an errorStatus of 'noSuchName' is returned, This indicates that the agent has not set a default value for the column. If the access for this column is read-create, the management station must issue additional management protocol set operations in order to provide a value associated with this column. If any columns have not had values supplied, the management station must supply them at this time. The management station may also update any default values in any read-create columns that it wishes to change. The management station will issue one or more set requests for these columns to supply their initial or updated values. A 'noSuchName' error received in response to any of these set requests is an indication that a column was either not implemented or not accessible. It is recommended that the management station remove the column referenced by the error-index from the list of those column for which it will provide values and repeat the operation, informing the user of the modified request. Interaction 4: Making the Conceptual Row Available Once the management station is satisfied with the values associated with the columns of the conceptual row, it issues a management protocol set operation to set the status column to 'active'. If the agent has sufficient information to make the conceptual row available for use by the managed device, the management protocol set operation succeeds (a 'noError' response is returned). Otherwise, the management protocol set operation fails with an error of 'badValue'. Expires Apr 19, 1994 [Page 10] draft Row creation with SNMPv1 Oct 19, 1993 NOTE WELL A conceptual row having a status column with value 'notInService' or 'notReady' is unavailable to the managed device. As such, it is possible for the managed device to create its own instances during the time between the management protocol set operation which sets the status column to 'createAndWait' and the management protocol set operation which sets the status column to 'active'. In this case, when the management protocol set operation is issued to set the status column to 'active', the values held in the agent supersede those used by the managed device. If the management station is prevented from setting the status column to 'active' (e.g., due to management station or network failure) the conceptual row will be left in the 'notInService' or 'notReady' state, consuming resources indefinitely. The agent must detect conceptual rows that have been in either state for an abnormally long period of time and remove them. This period of time should be long enough to allow for human response time (including 'think time') between the creation of the conceptual row and the setting of the status to 'active'. It is suggested that this period be approximately 5 minutes in length. Conceptual Row Suspension When a conceptual row is 'active', the management station may issue a management protocol set operation which sets the instance of the status column to 'notInService'. If the agent is unwilling to do so, the set operation fails with an error of 'badValue'. Otherwise, the conceptual row is taken out of service, and a 'noError' response is returned. It is the responsibility of the the DESCRIPTION clause of the status column to indicate under what circumstances the status column should be taken out of service (e.g., in order for the value of some other column of the same conceptual row to be modified). Conceptual Row Deletion For deletion of conceptual rows, a management protocol set operation is issued which sets the instance of the status column to 'destroy'. This request may be made regardless of the current value of the status column (e.g., it is possible to delete conceptual rows which are either 'notReady', 'notInService' or 'active'.) If the operation succeeds, then all instances associated with the conceptual row are immediately removed." Expires Apr 19, 1994 [Page 11] draft Row creation with SNMPv1 Oct 19, 1993 5. Acknowledgements The author wishes to thank Keith McCloghrie for his helpful comments on the ideas in this document. Expires Apr 19, 1994 [Page 12] draft Row creation with SNMPv1 Oct 19, 1993 6. References [1] Case, J., McCloghrie, K., Rose, M., and S. Waldbusser, "Structure of Management Information for version 2 of the Simple Network Management Protocol (SNMPv2)", RFC 1442, SNMP Research, Inc., Hughes LAN Systems, Dover Beach Consulting, Inc., Carnegie Mellon University, April, 1993 [2] Case, J., McCloghrie, K., Rose, M., and S. Waldbusser, "Textual Conventions for version 2 of the Simple Network Management Protocol (SNMPv2)", RFC 1443, SNMP Research, Inc., Hughes LAN Systems, Dover Beach Consulting, Inc., Carnegie Mellon University, April, 1993 Expires Apr 19, 1994 [Page 13] draft Row creation with SNMPv1 Oct 19, 1993 7. Security Considerations Security issues are not discussed in this memo. 8. Author's Address Steven Waldbusser Carnegie Mellon University 4910 Forbes Ave Pittsburgh, PA 15213 US Phone: +1 412 268 6628 Email: waldbusser@cmu.edu Expires Apr 19, 1994 [Page 14] draft Row creation with SNMPv1 Oct 19, 1993 Table of Contents 1 Introduction .................................................... 2 2 The SNMPv2 Network Management Framework ......................... 3 3 Overview ........................................................ 4 4 Use of RowStatus with SNMPv1 .................................... 4 4.1 Conceptual Row Creation with SNMPv1 ........................... 7 5 Acknowledgements ................................................ 12 6 References ...................................................... 13 7 Security Considerations ......................................... 14 8 Author's Address ................................................ 14 Expires Apr 19, 1994 [Page 15]