Textual Conventions for SMIv2
obsoletes
- rfc-1903 — Textual Conventions for Version 2 of the Simple Network Management Protocol (SNMPv2)
also
- std-58
Extracted elements (25)
Changes to a textual convention that could cause interoperability problems between old and new implementations are not allowed; such changes require defining a new textual convention with a new name. Allowed revisions include adding enumerations, adding/updating DISPLAY-HINT and REFERENCE, deprecating status, and editorial clarifications.
For large tables, a MIB-defined helper object returning an acceptable index is recommended for row creation; for small tables, pseudo-random index selection with retry on inconsistentValue is preferred. This distinction is made because scanning all existing rows to find a free index is highly sub-optimal at scale.
The RowStatus DESCRIPTION clause (not the convention itself) is responsible for specifying whether the status must be non-active in order to modify other columns. This keeps the textual convention general and allows table-specific policies to be expressed in the MIB object description.
MacAddress is always stored in canonical (LSB-first) order regardless of the underlying 802 technology. This contrasts with 802.5 (Token Ring), which transmits MAC addresses MSB-first; implementors must convert when reading from 802.5 hardware.
TimeStamp values are reset to zero when sysUpTime is reset. However, after approximately 497 days sysUpTime wraps back to zero without a re-initialization; in this case TimeStamp values do not change, creating potential ambiguity between old and new timestamps.
The agent must detect conceptual rows that have been in notInService or notReady state for an abnormally long period and remove them. In the absence of a DESCRIPTION-specified timeout, approximately 5 minutes is suggested.
The DISPLAY-HINT clause must not be present when the Textual Convention syntax is OBJECT IDENTIFIER, IpAddress, Counter32, Counter64, or any enumerated syntax (BITS or INTEGER).
The name of a textual convention must begin with an upper-case letter, must not conflict with SMIv2 reserved words, shall not exceed 64 characters in length, and must not contain hyphens (except for SMIv1 conversions). All names in standard information modules shall be unique.
The SYNTAX clause of a TEXTUAL-CONVENTION macro must refer to a base SMIv2 type or the BITS construct; it cannot reference a previously defined Textual Convention.
When a createAndGo set succeeds, the agent must immediately set the status column to active and return noError; if the agent lacks sufficient information, it must not create the row and must return inconsistentValue.
When the network management subsystem is re-initialized, every TestAndIncr object instance must either be incremented from its prior value or, if the prior value is unknown, set to a pseudo-randomly generated value.
Whenever any column instances of a conceptual row exist, the RowStatus column must also exist.
DisplayString represents NVT ASCII text as defined in RFC 854, using character codes 0–127. Objects using this syntax may not exceed 255 characters in length. SYNTAX is OCTET STRING (SIZE (0..255)) with DISPLAY-HINT '255a'.
MacAddress represents an 802 MAC address as a 6-octet OCTET STRING in the canonical order defined by IEEE 802.1a (least significant bit first), even though 802.5 transmits most significant bit first. DISPLAY-HINT is '1x:'.
RowPointer identifies a conceptual row by the OID of the first accessible columnar object instance in that row (e.g., ifIndex.3). VariablePointer identifies a specific scalar or columnar object instance (e.g., sysContact.0). Both replaced the obsolete InstancePointer.
StorageType describes the persistence of a conceptual row: other(1), volatile(2, lost on reboot), nonVolatile(3, backed by stable storage), permanent(4, can be changed but not deleted), readOnly(5, can be neither changed nor deleted). A permanent(4) or readOnly(5) value cannot be written; the value cannot be modified to permanent(4) or readOnly(5) from the other three types.
TDomain (OBJECT IDENTIFIER) and TAddress (OCTET STRING SIZE 1..255) form a pair identifying a transport service type and address. Every TDomain definition must be accompanied by a corresponding textual convention for TAddress interpretation.
TestAndIncr provides an atomic test-and-increment mechanism for coordinating concurrent SNMP set operations. A set succeeds only if the supplied value exactly matches the current instance value; on success the value increments by one (wrapping from 2^31-1 to zero).
The TEXTUAL-CONVENTION macro is used to define new data types for SMIv2 MIB modules. Each definition includes a DISPLAY-HINT, STATUS, DESCRIPTION, optional REFERENCE, and SYNTAX clause. Objects using a textual convention are always encoded using the rules of their primitive type.
TruthValue represents a boolean as INTEGER { true(1), false(2) }. The value 1 means true and 2 means false; there is no zero.
RFC 2579 defines mechanisms for creating new SMIv2 data types (textual conventions) for describing management information. These data type definitions have no direct security impact on the Internet.
RowStatus defines six values for managing conceptual row lifecycle: active, notInService, notReady (readable states) and createAndGo, createAndWait, destroy (write-only actions). Only three values—active, notInService, notReady—are returned on retrieval. Transitions among states A (row absent), B (notReady), C (notInService), and D (active) are governed by a formal state table.
DateAndTime is an 8- or 11-octet OCTET STRING encoding year (2 octets, network byte order), month, day, hour, minutes, seconds (0–60 to allow leap seconds), deci-seconds, and optionally UTC direction ('+'/'-'), hours-from-UTC, and minutes-from-UTC. DISPLAY-HINT is '2d-1d-1d,1d:1d:1d.1d,1a1d:1d'.
The DISPLAY-HINT for INTEGER-syntax objects consists of a format character ('x', 'd', 'o', 'b') and an optional decimal-point offset specified as '-N' (e.g., 'd-2' renders 1234 as '12.34'). Leading zeros are omitted; negative values prefix a minus sign.
The DISPLAY-HINT for OCTET STRING objects is one or more octet-format specifications, each with five optional parts: repeat indicator ('*'), octet length, display format ('x','d','o','a','t' for UTF-8), separator character, and repeat terminator. Trailing separator and terminator characters are suppressed; excess specifications are ignored; if octets remain after all specifications, the last specification is reapplied.