doc: Add RFC documents

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]