diff options
Diffstat (limited to 'doc/rfc/rfc2579.txt')
| -rw-r--r-- | doc/rfc/rfc2579.txt | 1533 |
1 files changed, 1533 insertions, 0 deletions
diff --git a/doc/rfc/rfc2579.txt b/doc/rfc/rfc2579.txt new file mode 100644 index 0000000..972eb02 --- /dev/null +++ b/doc/rfc/rfc2579.txt @@ -0,0 +1,1533 @@ + + + + + + + +Network Working Group Editors of this version: +Request for Comments: 2579 K. McCloghrie +STD: 58 Cisco Systems +Obsoletes: 1903 D. Perkins +Category: Standards Track SNMPinfo + J. Schoenwaelder + TU Braunschweig + Authors of previous version: + J. Case + SNMP Research + K. McCloghrie + Cisco Systems + M. Rose + First Virtual Holdings + S. Waldbusser + International Network Services + April 1999 + + + Textual Conventions for SMIv2 + + +Status of this Memo + + This document specifies an Internet standards track protocol for the + Internet community, and requests discussion and suggestions for + improvements. Please refer to the current edition of the "Internet + Official Protocol Standards" (STD 1) for the standardization state + and status of this protocol. Distribution of this memo is unlimited. + +Copyright Notice + + Copyright (C) The Internet Society (1999). All Rights Reserved. + + +Table of Contents + + 1 Introduction ..................................................2 + 1.1 A Note on Terminology .......................................2 + 2 Definitions ...................................................2 + 3 Mapping of the TEXTUAL-CONVENTION macro ......................20 + 3.1 Mapping of the DISPLAY-HINT clause .........................21 + 3.2 Mapping of the STATUS clause ...............................22 + 3.3 Mapping of the DESCRIPTION clause ..........................23 + 3.4 Mapping of the REFERENCE clause ............................23 + 3.5 Mapping of the SYNTAX clause ...............................23 + 4 Sub-typing of Textual Conventions ............................23 + 5 Revising a Textual Convention Definition .....................23 + + +McCloghrie, et al. Standards Track [Page 1] + + + + + +RFC 2579 Textual Conventions for SMIv2 April 1999 + + + 6 Security Considerations ......................................24 + 7 Editors' Addresses ...........................................25 + 8 References ...................................................25 + 9 Full Copyright Statement .....................................26 + +1. Introduction + + Management information is viewed as a collection of managed objects, + residing in a virtual information store, termed the Management + Information Base (MIB). Collections of related objects are defined + in MIB modules. These modules are written using an adapted subset of + OSI's Abstract Syntax Notation One, ASN.1 (1988) [1], termed the + Structure of Management Information (SMI) [2]. + + When designing a MIB module, it is often useful to define new types + similar to those defined in the SMI. In comparison to a type defined + in the SMI, each of these new types has a different name, a similar + syntax, but a more precise semantics. These newly defined types are + termed textual conventions, and are used for the convenience of + humans reading the MIB module. It is the purpose of this document to + define the initial set of textual conventions available to all MIB + modules. + + Objects defined using a textual convention are always encoded by + means of the rules that define their primitive type. However, + textual conventions often have special semantics associated with + them. As such, an ASN.1 macro, TEXTUAL-CONVENTION, is used to + concisely convey the syntax and semantics of a textual convention. + +1.1. A Note on Terminology + + For the purpose of exposition, the original Structure of Management + Information, as described in RFCs 1155 (STD 16), 1212 (STD 16), and + RFC 1215, is termed the SMI version 1 (SMIv1). The current version + of the Structure of Management Information is termed SMI version 2 + (SMIv2). + +2. Definitions + +SNMPv2-TC DEFINITIONS ::= BEGIN + +IMPORTS + TimeTicks FROM SNMPv2-SMI; + + +-- definition of textual conventions + +TEXTUAL-CONVENTION MACRO ::= + + +McCloghrie, et al. Standards Track [Page 2] + + + + + +RFC 2579 Textual Conventions for SMIv2 April 1999 + + +BEGIN + TYPE NOTATION ::= + DisplayPart + "STATUS" Status + "DESCRIPTION" Text + ReferPart + "SYNTAX" Syntax + + VALUE NOTATION ::= + value(VALUE Syntax) -- adapted ASN.1 + + DisplayPart ::= + "DISPLAY-HINT" Text + | empty + + Status ::= + "current" + | "deprecated" + | "obsolete" + + ReferPart ::= + "REFERENCE" Text + | empty + + -- a character string as defined in [2] + Text ::= value(IA5String) + + Syntax ::= -- Must be one of the following: + -- a base type (or its refinement), or + -- a BITS pseudo-type + type + | "BITS" "{" NamedBits "}" + + NamedBits ::= NamedBit + | NamedBits "," NamedBit + + NamedBit ::= identifier "(" number ")" -- number is nonnegative + +END + + + + +DisplayString ::= TEXTUAL-CONVENTION + DISPLAY-HINT "255a" + STATUS current + DESCRIPTION + "Represents textual information taken from the NVT ASCII + + +McCloghrie, et al. Standards Track [Page 3] + + + + + +RFC 2579 Textual Conventions for SMIv2 April 1999 + + + character set, as defined in pages 4, 10-11 of RFC 854. + + To summarize RFC 854, the NVT ASCII repertoire specifies: + + - the use of character codes 0-127 (decimal) + + - the graphics characters (32-126) are interpreted as + US ASCII + + - NUL, LF, CR, BEL, BS, HT, VT and FF have the special + meanings specified in RFC 854 + + - the other 25 codes have no standard interpretation + + - the sequence 'CR LF' means newline + + - the sequence 'CR NUL' means carriage-return + + - an 'LF' not preceded by a 'CR' means moving to the + same column on the next line. + + - the sequence 'CR x' for any x other than LF or NUL is + illegal. (Note that this also means that a string may + end with either 'CR LF' or 'CR NUL', but not with CR.) + + Any object defined using this syntax may not exceed 255 + characters in length." + SYNTAX OCTET STRING (SIZE (0..255)) + +PhysAddress ::= TEXTUAL-CONVENTION + DISPLAY-HINT "1x:" + STATUS current + DESCRIPTION + "Represents media- or physical-level addresses." + SYNTAX OCTET STRING + + +MacAddress ::= TEXTUAL-CONVENTION + DISPLAY-HINT "1x:" + STATUS current + DESCRIPTION + "Represents an 802 MAC address represented in the + `canonical' order defined by IEEE 802.1a, i.e., as if it + were transmitted least significant bit first, even though + 802.5 (in contrast to other 802.x protocols) requires MAC + addresses to be transmitted most significant bit first." + SYNTAX OCTET STRING (SIZE (6)) + + + +McCloghrie, et al. Standards Track [Page 4] + + + + + +RFC 2579 Textual Conventions for SMIv2 April 1999 + + +TruthValue ::= TEXTUAL-CONVENTION + STATUS current + DESCRIPTION + "Represents a boolean value." + SYNTAX INTEGER { true(1), false(2) } + +TestAndIncr ::= TEXTUAL-CONVENTION + STATUS current + DESCRIPTION + "Represents integer-valued information used for atomic + operations. When the management protocol is used to specify + that an object instance having this syntax is to be + modified, the new value supplied via the management protocol + must precisely match the value presently held by the + instance. If not, the management protocol set operation + fails with an error of `inconsistentValue'. Otherwise, if + the current value is the maximum value of 2^31-1 (2147483647 + decimal), then the value held by the instance is wrapped to + zero; otherwise, the value held by the instance is + incremented by one. (Note that regardless of whether the + management protocol set operation succeeds, the variable- + binding in the request and response PDUs are identical.) + + The value of the ACCESS clause for objects having this + syntax is either `read-write' or `read-create'. When an + instance of a columnar object having this syntax is created, + any value may be supplied via the management protocol. + + When the network management portion of the system is re- + initialized, the value of every object instance having this + syntax must either be incremented from its value prior to + the re-initialization, or (if the value prior to the re- + initialization is unknown) be set to a pseudo-randomly + generated value." + SYNTAX INTEGER (0..2147483647) + +AutonomousType ::= TEXTUAL-CONVENTION + STATUS current + DESCRIPTION + "Represents an independently extensible type identification + value. It may, for example, indicate a particular sub-tree + with further MIB definitions, or define a particular type of + protocol or hardware." + SYNTAX OBJECT IDENTIFIER + + +InstancePointer ::= TEXTUAL-CONVENTION + STATUS obsolete + + +McCloghrie, et al. Standards Track [Page 5] + + + + + +RFC 2579 Textual Conventions for SMIv2 April 1999 + + + DESCRIPTION + "A pointer to either a specific instance of a MIB object or + a conceptual row of a MIB table in the managed device. In + the latter case, by convention, it is the name of the + particular instance of the first accessible columnar object + in the conceptual row. + + The two uses of this textual convention are replaced by + VariablePointer and RowPointer, respectively." + SYNTAX OBJECT IDENTIFIER + + +VariablePointer ::= TEXTUAL-CONVENTION + STATUS current + DESCRIPTION + "A pointer to a specific object instance. For example, + sysContact.0 or ifInOctets.3." + SYNTAX OBJECT IDENTIFIER + + +RowPointer ::= TEXTUAL-CONVENTION + STATUS current + DESCRIPTION + "Represents a pointer to a conceptual row. The value is the + name of the instance of the first accessible columnar object + in the conceptual row. + + For example, ifIndex.3 would point to the 3rd row in the + ifTable (note that if ifIndex were not-accessible, then + ifDescr.3 would be used instead)." + SYNTAX OBJECT IDENTIFIER + +RowStatus ::= TEXTUAL-CONVENTION + STATUS current + DESCRIPTION + "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 [2].) + + + + + + + + + + + +McCloghrie, et al. Standards Track [Page 6] + + + + + +RFC 2579 Textual Conventions for SMIv2 April 1999 + + + The status 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); 'notInService' has + no implication regarding the internal consistency of + the row, availability of resources, or consistency with + the current state of the managed device; + + - `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 (i.e., one or more required columns in + the conceptual row have not been instanciated); + + - `createAndGo', which is supplied by a management + station wishing to create a new instance of a + conceptual row and to have its status automatically set + to active, making 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 make 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 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 attempt to make it + so (the status column has value `notInService'); or, it is + not available for use by the managed device, and an attempt + to make it so would fail because the agent has insufficient + information (the state column has value `notReady'). + + + + +McCloghrie, et al. Standards Track [Page 7] + + + + + +RFC 2579 Textual Conventions for SMIv2 April 1999 + + + 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 + not be `active' in order for the value of some other + column of the same conceptual row to be modified. If + such a specification is made, affected columns may be + changed by an SNMP set PDU if the RowStatus would not + be equal to `active' either immediately before or after + processing the PDU. In other words, if the PDU also + contained a varbind that would change the RowStatus + value, the column in question may be changed if the + RowStatus was not equal to `active' as the PDU was + received, or if the varbind sets the status to a value + other than 'active'. + + + Also note that whenever any elements of a row exist, the + RowStatus column must also exist. + + + + + + + + + + + + + + + + + + + + + + + + + + +McCloghrie, et al. Standards Track [Page 8] + + + + + +RFC 2579 Textual Conventions for SMIv2 April 1999 + + + 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: + + + 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|inconsist- |inconsistent-|inconsistent- +column to | or | entValue| Value| Value +createAndGo |inconsistent- | | | + | Value| | | +--------------+--------------+-----------+-------------+------------- +set status |noError see 1|inconsist- |inconsistent-|inconsistent- +column to | or | entValue| Value| Value +createAndWait |wrongValue | | | +--------------+--------------+-----------+-------------+------------- +set status |inconsistent- |inconsist- |noError |noError +column to | Value| entValue| | +active | | | | + | | or | | + | | | | + | |see 2 ->D|see 8 ->D| ->D +--------------+--------------+-----------+-------------+------------- +set status |inconsistent- |inconsist- |noError |noError ->C +column to | Value| entValue| | +notInService | | | | + | | or | | or + | | | | + | |see 3 ->C| ->C|see 6 +--------------+--------------+-----------+-------------+------------- +set status |noError |noError |noError |noError ->A +column to | | | | or +destroy | ->A| ->A| ->A|see 7 +--------------+--------------+-----------+-------------+------------- +set any other |see 4 |noError |noError |see 5 +column to some| | | | +value | | 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, + + +McCloghrie, et al. Standards Track [Page 9] + + + + + +RFC 2579 Textual Conventions for SMIv2 April 1999 + + + provide values for all columns which are missing but + required, and all columns have acceptable values, then + return noError and goto D. + + (3) if other variable bindings included in the same PDU, + provide legal values for all columns which are missing but + required, then return noError and goto C. + + (4) at the discretion of the agent, the return value may be + either: + + inconsistentName: because the agent does not choose to + create such an instance when the corresponding + RowStatus instance does not exist, or + + inconsistentValue: if the supplied value is + inconsistent with the state of some other MIB object's + value, or + + noError: because the agent chooses to create the + instance. + + If noError is returned, then the instance of the status + column must also be created, and the new state is B or C, + depending on the information available to the agent. If + inconsistentName or inconsistentValue is returned, the row + remains in state A. + + (5) depending on the MIB definition for the column/table, + either noError or inconsistentValue may be returned. + + (6) the return value can indicate one of the following + errors: + + wrongValue: because the agent does not support + notInService (e.g., an agent which does not support + createAndWait), or + + inconsistentValue: because the agent is unable to take + the row out of service at this time, perhaps because it + is in use and cannot be de-activated. + + (7) the return value can indicate the following error: + + inconsistentValue: because the agent is unable to + remove the row at this time, perhaps because it is in + use and cannot be de-activated. + + + +McCloghrie, et al. Standards Track [Page 10] + + + + + +RFC 2579 Textual Conventions for SMIv2 April 1999 + + + (8) the transition to D can fail, e.g., if the values of the + conceptual row are inconsistent, then the error code would + be inconsistentValue. + + NOTE: Other processing of (this and other varbinds of) the + set request may result in a response other than noError + being returned, e.g., wrongValue, noCreation, etc. + + + Conceptual Row Creation + + 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 + + +McCloghrie, et al. Standards Track [Page 11] + + + + + +RFC 2579 Textual Conventions for SMIv2 April 1999 + + + was already in use and an inconsistentValue 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 numbers of entries, it is + recommended that the latter pseudo-random index mechanism be + used. + + 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. + + Interaction 2a: Creating and Activating the Conceptual Row + + The management station must first determine the column + requirements, i.e., it must determine those columns for + which it must or must not provide values. 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 management station. Alternately, + the management station issues a management protocol get + operation to examine all columns in the conceptual row that + it wishes to create. In response, for each column, there + are three possible outcomes: + + - a value is returned, indicating that some other + management station has already created this conceptual + row. We return to interaction 1. + + - the exception `noSuchInstance' is returned, + indicating that the agent implements the object-type + associated with this column, and that this column in at + least one conceptual row would be accessible in the MIB + view used by the retrieval were it to exist. For those + columns to which the agent provides read-create access, + the `noSuchInstance' exception tells the management + station that it should supply a value for this column + when the conceptual row is to be created. + + + +McCloghrie, et al. Standards Track [Page 12] + + + + + +RFC 2579 Textual Conventions for SMIv2 April 1999 + + + - the exception `noSuchObject' is returned, indicating + that the agent does not implement the object-type + associated with this column or that there is no + conceptual row for which this column would be + accessible in the MIB view used by the retrieval. As + such, the management station can not issue any + management protocol set operations to create an + instance of this column. + + 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 `inconsistentValue'. + On this error, the management station can issue a management + protocol retrieval operation to determine if this was + because it failed to specify a value for a required column, + or, because the selected instance of the status column + already existed. In the latter case, we return to + interaction 1. In the former case, the management station + can re-issue the set operation with the additional + information, or begin interaction 2 again using + `createAndWait' in order to negotiate creation of the + conceptual row. + + + + + + + + + + + +McCloghrie, et al. Standards Track [Page 13] + + + + + +RFC 2579 Textual Conventions for SMIv2 April 1999 + + + NOTE WELL + + Regardless of the method used to determine the column + requirements, it is possible that the management + station might deem a column necessary when, in fact, + the agent will not allow that particular columnar + instance to be created or written. In this case, the + management protocol set operation will fail with an + error such as `noCreation' or `notWritable'. In this + case, the management station decides whether it needs + to be able to set a value for that particular columnar + instance. If not, the management station re-issues the + management protocol set operation, but without setting + a value for that particular columnar instance; + otherwise, the management station aborts the row + creation algorithm. + + 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 `wrongValue'. (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.) Otherwise, + the conceptual row is created, 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 (attempt 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 must now determine the column + requirements. It issues a management protocol get operation + to examine all columns in the created conceptual row. In + the response, for each column, there are three possible + outcomes: + + + + + +McCloghrie, et al. Standards Track [Page 14] + + + + + +RFC 2579 Textual Conventions for SMIv2 April 1999 + + + - a value is returned, indicating that the agent + implements the object-type associated with this column + and had sufficient information to provide a value. For + those columns to which the agent provides read-create + access (and for which the agent allows their values to + be changed after their creation), 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. + + - the exception `noSuchInstance' is returned, + indicating that the agent implements the object-type + associated with this column, and that this column in at + least one conceptual row would be accessible in the MIB + view used by the retrieval were it to exist. However, + the agent does not have sufficient information to + provide a value, and until a value is provided, the + conceptual row may not be made available for use by the + managed device. For those columns to which the agent + provides read-create access, the `noSuchInstance' + exception tells the management station that it must + issue additional management protocol set operations, in + order to provide a value associated with this column. + + - the exception `noSuchObject' is returned, indicating + that the agent does not implement the object-type + associated with this column or that there is no + conceptual row for which this column would be + accessible in the MIB view used by the retrieval. As + such, the management station can not issue any + management protocol set operations to create an + instance of this column. + + If the value associated with the status column is + `notReady', then the management station must first deal with + all `noSuchInstance' columns, if any. Having done so, the + value of the status column becomes `notInService', and we + proceed to interaction 4. + + + + + + + + + + + + +McCloghrie, et al. Standards Track [Page 15] + + + + + +RFC 2579 Textual Conventions for SMIv2 April 1999 + + + 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 + `inconsistentValue'. + + 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. It is the responsibility of the + DESCRIPTION clause of the status column to indicate what an + abnormally long period of time would be. 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'. + In the absence of such information in the DESCRIPTION + clause, it is suggested that this period be approximately 5 + minutes in length. This removal action applies not only to + newly-created rows, but also to previously active rows which + are set to, and left in, the notInService state for a + prolonged period exceeding that which is considered normal + for such a conceptual row. + + + + + +McCloghrie, et al. Standards Track [Page 16] + + + + + +RFC 2579 Textual Conventions for SMIv2 April 1999 + + + 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 `wrongValue' or `inconsistentValue'. Otherwise, + the conceptual row is taken out of service, and a `noError' + response is returned. It is the responsibility of 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." + SYNTAX INTEGER { + -- the following two values are states: + -- these values may be read or written + active(1), + notInService(2), + + -- the following value is a state: + -- this value may be read, but not written + notReady(3), + + -- the following three values are + -- actions: these values may be written, + -- but are never read + createAndGo(4), + createAndWait(5), + destroy(6) + } + +TimeStamp ::= TEXTUAL-CONVENTION + STATUS current + DESCRIPTION + "The value of the sysUpTime object at which a specific + occurrence happened. The specific occurrence must be + + +McCloghrie, et al. Standards Track [Page 17] + + + + + +RFC 2579 Textual Conventions for SMIv2 April 1999 + + + defined in the description of any object defined using this + type. + + If sysUpTime is reset to zero as a result of a re- + initialization of the network management (sub)system, then + the values of all TimeStamp objects are also reset. + However, after approximately 497 days without a re- + initialization, the sysUpTime object will reach 2^^32-1 and + then increment around to zero; in this case, existing values + of TimeStamp objects do not change. This can lead to + ambiguities in the value of TimeStamp objects." + SYNTAX TimeTicks + + +TimeInterval ::= TEXTUAL-CONVENTION + STATUS current + DESCRIPTION + "A period of time, measured in units of 0.01 seconds." + SYNTAX INTEGER (0..2147483647) + +DateAndTime ::= TEXTUAL-CONVENTION + DISPLAY-HINT "2d-1d-1d,1d:1d:1d.1d,1a1d:1d" + STATUS current + DESCRIPTION + "A date-time specification. + + field octets contents range + ----- ------ -------- ----- + 1 1-2 year* 0..65536 + 2 3 month 1..12 + 3 4 day 1..31 + 4 5 hour 0..23 + 5 6 minutes 0..59 + 6 7 seconds 0..60 + (use 60 for leap-second) + 7 8 deci-seconds 0..9 + 8 9 direction from UTC '+' / '-' + 9 10 hours from UTC* 0..13 + 10 11 minutes from UTC 0..59 + + * Notes: + - the value of year is in network-byte order + - daylight saving time in New Zealand is +13 + + For example, Tuesday May 26, 1992 at 1:30:15 PM EDT would be + displayed as: + + 1992-5-26,13:30:15.0,-4:0 + + +McCloghrie, et al. Standards Track [Page 18] + + + + + +RFC 2579 Textual Conventions for SMIv2 April 1999 + + + Note that if only local time is known, then timezone + information (fields 8-10) is not present." + SYNTAX OCTET STRING (SIZE (8 | 11)) + + +StorageType ::= TEXTUAL-CONVENTION + STATUS current + DESCRIPTION + "Describes the memory realization of a conceptual row. A + row which is volatile(2) is lost upon reboot. A row which + is either nonVolatile(3), permanent(4) or readOnly(5), is + backed up by stable storage. A row which is permanent(4) + can be changed but not deleted. A row which is readOnly(5) + cannot be changed nor deleted. + + If the value of an object with this syntax is either + permanent(4) or readOnly(5), it cannot be written. + Conversely, if the value is either other(1), volatile(2) or + nonVolatile(3), it cannot be modified to be permanent(4) or + readOnly(5). (All illegal modifications result in a + 'wrongValue' error.) + + Every usage of this textual convention is required to + specify the columnar objects which a permanent(4) row must + at a minimum allow to be writable." + SYNTAX INTEGER { + other(1), -- eh? + volatile(2), -- e.g., in RAM + nonVolatile(3), -- e.g., in NVRAM + permanent(4), -- e.g., partially in ROM + readOnly(5) -- e.g., completely in ROM + } + + + + + + + + + + + + + + + + + + +McCloghrie, et al. Standards Track [Page 19] + + + + + +RFC 2579 Textual Conventions for SMIv2 April 1999 + + +TDomain ::= TEXTUAL-CONVENTION + STATUS current + DESCRIPTION + "Denotes a kind of transport service. + + Some possible values, such as snmpUDPDomain, are defined in + the SNMPv2-TM MIB module. Other possible values are defined + in other MIB modules." + REFERENCE "The SNMPv2-TM MIB module is defined in RFC 1906." + SYNTAX OBJECT IDENTIFIER + + +TAddress ::= TEXTUAL-CONVENTION + STATUS current + DESCRIPTION + "Denotes a transport service address. + + A TAddress value is always interpreted within the context of a + TDomain value. Thus, each definition of a TDomain value must + be accompanied by a definition of a textual convention for use + with that TDomain. Some possible textual conventions, such as + SnmpUDPAddress for snmpUDPDomain, are defined in the SNMPv2-TM + MIB module. Other possible textual conventions are defined in + other MIB modules." + REFERENCE "The SNMPv2-TM MIB module is defined in RFC 1906." + SYNTAX OCTET STRING (SIZE (1..255)) + + +END + +3. Mapping of the TEXTUAL-CONVENTION macro + + The TEXTUAL-CONVENTION macro is used to convey the syntax and + semantics associated with a textual convention. It should be noted + that the expansion of the TEXTUAL-CONVENTION macro is something which + conceptually happens during implementation and not during run-time. + + The name of a textual convention must consist of one or more letters + or digits, with the initial character being an upper case letter. + The name must not conflict with any of the reserved words listed in + section 3.7 of [2], should not consist of all upper case letters, and + shall not exceed 64 characters in length. (However, names longer + than 32 characters are not recommended.) The hyphen is not allowed + in the name of a textual convention (except for use in information + modules converted from SMIv1 which allowed hyphens in ASN.1 type + assignments). Further, all names used for the textual conventions + defined in all "standard" information modules shall be unique. + + + +McCloghrie, et al. Standards Track [Page 20] + + + + + +RFC 2579 Textual Conventions for SMIv2 April 1999 + + +3.1. Mapping of the DISPLAY-HINT clause + + The DISPLAY-HINT clause, which need not be present, gives a hint as + to how the value of an instance of an object with the syntax defined + using this textual convention might be displayed. The DISPLAY-HINT + clause must not be present if the Textual Convention is defined with + a syntax of: OBJECT IDENTIFIER, IpAddress, Counter32, Counter64, or + any enumerated syntax (BITS or INTEGER). The determination of + whether it makes sense for other syntax types is dependent on the + specific definition of the Textual Convention. + + When the syntax has an underlying primitive type of INTEGER, the hint + consists of an integer-format specification, containing two parts. + The first part is a single character suggesting a display format, + either: `x' for hexadecimal, or `d' for decimal, or `o' for octal, or + `b' for binary. For all types, when rendering the value, leading + zeros are omitted, and for negative values, a minus sign is rendered + immediately before the digits. The second part is always omitted for + `x', `o' and `b', and need not be present for `d'. If present, the + second part starts with a hyphen and is followed by a decimal number, + which defines the implied decimal point when rendering the value. + For example: + + Hundredths ::= TEXTUAL-CONVENTION + DISPLAY-HINT "d-2" + ... + SYNTAX INTEGER (0..10000) + + suggests that a Hundredths value of 1234 be rendered as "12.34" + + + When the syntax has an underlying primitive type of OCTET STRING, the + hint consists of one or more octet-format specifications. Each + specification consists of five parts, with each part using and + removing zero or more of the next octets from the value and producing + the next zero or more characters to be displayed. The octets within + the value are processed in order of significance, most significant + first. + + The five parts of a octet-format specification are: + +(1) the (optional) repeat indicator; if present, this part is a `*', + and indicates that the current octet of the value is to be used as + the repeat count. The repeat count is an unsigned integer (which + may be zero) which specifies how many times the remainder of this + octet-format specification should be successively applied. If the + repeat indicator is not present, the repeat count is one. + + + +McCloghrie, et al. Standards Track [Page 21] + + + + + +RFC 2579 Textual Conventions for SMIv2 April 1999 + + +(2) the octet length: one or more decimal digits specifying the number + of octets of the value to be used and formatted by this octet- + specification. Note that the octet length can be zero. If less + than this number of octets remain in the value, then the lesser + number of octets are used. + +(3) the display format, either: `x' for hexadecimal, `d' for decimal, + `o' for octal, `a' for ascii, or `t' for UTF-8. If the octet + length part is greater than one, and the display format part refers + to a numeric format, then network-byte ordering (big-endian + encoding) is used interpreting the octets in the value. The octets + processed by the `t' display format do not necessarily form an + integral number of UTF-8 characters. Trailing octets which do not + form a valid UTF-8 encoded character are discarded. + +(4) the (optional) display separator character; if present, this part + is a single character which is produced for display after each + application of this octet-specification; however, this character is + not produced for display if it would be immediately followed by the + display of the repeat terminator character for this octet- + specification. This character can be any character other than a + decimal digit and a `*'. + +(5) the (optional) repeat terminator character, which can be present + only if the display separator character is present and this octet- + specification begins with a repeat indicator; if present, this part + is a single character which is produced after all the zero or more + repeated applications (as given by the repeat count) of this + octet-specification. This character can be any character other + than a decimal digit and a `*'. + + Output of a display separator character or a repeat terminator + character is suppressed if it would occur as the last character of + the display. + + If the octets of the value are exhausted before all the octet-format + specification have been used, then the excess specifications are + ignored. If additional octets remain in the value after interpreting + all the octet-format specifications, then the last octet-format + specification is re-interpreted to process the additional octets, + until no octets remain in the value. + +3.2. Mapping of the STATUS clause + + The STATUS clause, which must be present, indicates whether this + definition is current or historic. + + The value "current" means that the definition is current and valid. + + +McCloghrie, et al. Standards Track [Page 22] + + + + + +RFC 2579 Textual Conventions for SMIv2 April 1999 + + + The value "obsolete" means the definition is obsolete and should not + be implemented and/or can be removed if previously implemented. + While the value "deprecated" also indicates an obsolete definition, + it permits new/continued implementation in order to foster + interoperability with older/existing implementations. + +3.3. Mapping of the DESCRIPTION clause + + The DESCRIPTION clause, which must be present, contains a textual + definition of the textual convention, which provides all semantic + definitions necessary for implementation, and should embody any + information which would otherwise be communicated in any ASN.1 + commentary annotations associated with the object. + +3.4. Mapping of the REFERENCE clause + + The REFERENCE clause, which need not be present, contains a textual + cross-reference to some other document, either another information + module which defines a related assignment, or some other document + which provides additional information relevant to this definition. + +3.5. Mapping of the SYNTAX clause + + The SYNTAX clause, which must be present, defines abstract data + structure corresponding to the textual convention. The data + structure must be one of the alternatives defined in the ObjectSyntax + CHOICE or the BITS construct (see section 7.1 in [2]). Note that + this means that the SYNTAX clause of a Textual Convention can not + refer to a previously defined Textual Convention. + + An extended subset of the full capabilities of ASN.1 (1988) sub- + typing is allowed, as appropriate to the underlying ASN.1 type. Any + such restriction on size, range or enumerations specified in this + clause represents the maximal level of support which makes "protocol + sense". Restrictions on sub-typing are specified in detail in + Section 9 and Appendix A of [2]. + +4. Sub-typing of Textual Conventions + + The SYNTAX clause of a TEXTUAL CONVENTION macro may be sub-typed in + the same way as the SYNTAX clause of an OBJECT-TYPE macro (see + section 11 of [2]). + +5. Revising a Textual Convention Definition + + It may be desirable to revise the definition of a textual convention + after experience is gained with it. However, changes are not allowed + if they have any potential to cause interoperability problems "over + + +McCloghrie, et al. Standards Track [Page 23] + + + + + +RFC 2579 Textual Conventions for SMIv2 April 1999 + + + the wire" between an implementation using an original specification + and an implementation using an updated specification(s). Such + changes can only be accommodated by defining a new textual convention + (i.e., a new name). + + The following revisions are allowed: + +(1) A SYNTAX clause containing an enumerated INTEGER may have new + enumerations added or existing labels changed. Similarly, named + bits may be added or existing labels changed for the BITS + construct. + +(2) A STATUS clause value of "current" may be revised as "deprecated" + or "obsolete". Similarly, a STATUS clause value of "deprecated" + may be revised as "obsolete". When making such a change, the + DESCRIPTION clause should be updated to explain the rationale. + +(3) A REFERENCE clause may be added or updated. + +(4) A DISPLAY-HINTS clause may be added or updated. + +(5) Clarifications and additional information may be included in the + DESCRIPTION clause. + +(6) Any editorial change. + + Note that with the introduction of the TEXTUAL-CONVENTION macro, + there is no longer any need to define types in the following manner: + + DisplayString ::= OCTET STRING (SIZE (0..255)) + + When revising an information module containing a definition such as + this, that definition should be replaced by a TEXTUAL-CONVENTION + macro. + +6. Security Considerations + + This document defines the means to define new data types for the + language used to write and read descriptions of management + information. These data types have no security impact on the + Internet. + + + + + + + + + +McCloghrie, et al. Standards Track [Page 24] + + + + + +RFC 2579 Textual Conventions for SMIv2 April 1999 + + +7. Editors' Addresses + + Keith McCloghrie + Cisco Systems, Inc. + 170 West Tasman Drive + San Jose, CA 95134-1706 + USA + Phone: +1 408 526 5260 + EMail: kzm@cisco.com + + David Perkins + SNMPinfo + 3763 Benton Street + Santa Clara, CA 95051 + USA + Phone: +1 408 221-8702 + EMail: dperkins@snmpinfo.com + + Juergen Schoenwaelder + TU Braunschweig + Bueltenweg 74/75 + 38106 Braunschweig + Germany + Phone: +49 531 391-3283 + EMail: schoenw@ibr.cs.tu-bs.de + + +8. References + +[1] Information processing systems - Open Systems Interconnection - + Specification of Abstract Syntax Notation One (ASN.1), + International Organization for Standardization. International + Standard 8824, (December, 1987). + +[2] McCloghrie, K., Perkins, D., Schoenwaelder, J., Case, J., Rose, M. + and S. Waldbusser, "Structure of Management Information Version 2 + (SMIv2)", STD 58, RFC 2578, April 1999. + +[3] The SNMPv2 Working Group, Case, J., McCloghrie, K., Rose, M. and + Waldbusser, S., "Transport Mappings for Version 2 of the" Simple + Network Management Protocol (SNMPv2)", RFC 1906, January 1996. + + + + + + + + + +McCloghrie, et al. Standards Track [Page 25] + + + + + +RFC 2579 Textual Conventions for SMIv2 April 1999 + + +9. Full Copyright Statement + + Copyright (C) The Internet Society (1999). 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." + + + + + + + + + + + + + + + + + + + + + + + +McCloghrie, et al. Standards Track [Page 26] |