skip to content

In an SMIv2 MIB module, what does each clause of the OBJECT-TYPE macro declare, and how do textual conventions refine its SYNTAX?

level: middleimportance: should knowfreq 22%

answer

  1. one macro per managed object
  2. SYNTAX, MAX-ACCESS, STATUS, DESCRIPTION
  3. maximum, not minimum, access
  4. a named sub-type of a base type
  5. DisplayString is OCTET STRING underneath

basics

~20 s

OBJECT-TYPE registers an object's OID and declares its SYNTAX, MAX-ACCESS, STATUS and DESCRIPTION, plus optional UNITS, REFERENCE, INDEX or AUGMENTS, and DEFVAL. A textual convention is a named sub-type of a base type that adds meaning and a display hint, never a new wire type.

solid answer

~40 s

The `OBJECT-TYPE` macro (RFC 2578) registers one managed object at an OID. `SYNTAX` gives its data type: a base type, the `BITS` construct or a **textual convention**. `MAX-ACCESS` is the most access that makes protocol sense, ordered `not-accessible`, `accessible-for-notify`, `read-only`, `read-write`, `read-create`; it is independent of any access policy. `STATUS` is `current`, `deprecated` or `obsolete`; `DESCRIPTION` carries the semantics an implementer needs. `UNITS`, `REFERENCE` and `DEFVAL` are optional, and a row object carries `INDEX` or `AUGMENTS`. A textual convention, defined with RFC 2579's `TEXTUAL-CONVENTION` macro, is a sub-typed base type with extra meaning and an optional `DISPLAY-HINT`: `DisplayString` is an `OCTET STRING (SIZE (0..255))` of NVT ASCII, and on the wire it is just that `OCTET STRING`. SMIv1 (RFC 1212) differed: `ACCESS` stated the minimum required, and `STATUS` read `mandatory` or `optional`.

go deeper

for a junior

Name the four clauses every object must have, SYNTAX, MAX-ACCESS, STATUS and DESCRIPTION, and know that DisplayString is text stored as an OCTET STRING.

for a middle

Explain MAX-ACCESS as a protocol ceiling rather than a permission, the difference between deprecated and obsolete, and why a textual convention changes meaning but never the wire encoding.

for a senior

Read a vendor definition and decide from SYNTAX, UNITS and DESCRIPTION how to collect it, rate or gauge, and in which units, before trusting any dashboard built on it.

for a principal

When writing modules, prefer existing textual conventions over new ones, state units and reset behaviour precisely, and remember every clause becomes a permanent public contract.

## The macro and what it registers In a MIB module, every managed object is defined by one invocation of the **`OBJECT-TYPE`** macro. RFC 2578 (SMIv2) stresses that the macro is expanded at implementation time, not at run time: it is the contract an agent implements and a manager reads. The value of the macro is the object's **name**, an OID, and that registration is permanent: once assigned, the OID's semantics cannot change and the OID cannot be reused. Here is a real definition, from SNMPv2-MIB (RFC 3418): ``` sysUpTime OBJECT-TYPE SYNTAX TimeTicks MAX-ACCESS read-only STATUS current DESCRIPTION "The time (in hundredths of a second) since the network management portion of the system was last re-initialized." ::= { system 3 } ``` ## Clause by clause | Clause | Required? | What it declares | |---|---|---| | `SYNTAX` | yes | the data type: a base type, `BITS`, or a textual convention | | `UNITS` | no | a textual statement of the units | | `MAX-ACCESS` | yes | the most access that makes protocol sense | | `STATUS` | yes | `current`, `deprecated` or `obsolete` | | `DESCRIPTION` | yes | all the semantics an implementer needs | | `REFERENCE` | no | a cross-reference to another document | | `INDEX` / `AUGMENTS` | rows only | how a row's instances are identified | | `DEFVAL` | no | a default the agent may use when a row is created | The details that trip people up: - **SYNTAX** may be refined with a range, a size or a subset of enumerations, but a refinement can never change the underlying primitive or application type. - **MAX-ACCESS** values are ordered from least to greatest: `not-accessible`, `accessible-for-notify`, `read-only`, `read-write`, `read-create`. `not-accessible` marks auxiliary objects such as most index columns; `accessible-for-notify` marks an object that appears only inside notifications; `read-create` means a manager can create rows. RFC 2578 states that this maximum is independent of any administrative authorisation policy, so `read-write` does not mean every manager may write. - **STATUS** `deprecated` still allows implementation for interoperability; `obsolete` means do not implement. - **Counters** carry restrictions of their own: `MAX-ACCESS` is only `read-only` or `accessible-for-notify`, and no `DEFVAL` is allowed. ## Textual conventions The base types are few: `INTEGER`/`Integer32`, `OCTET STRING`, `OBJECT IDENTIFIER`, `IpAddress`, `Counter32`, `Gauge32`, `Unsigned32`, `TimeTicks`, `Opaque` and `Counter64`, plus `BITS`. Real data needs more meaning than that, so RFC 2579 defines the **`TEXTUAL-CONVENTION`** macro: a named sub-type of a base type, with a `STATUS`, a `DESCRIPTION` and an optional **`DISPLAY-HINT`** telling a manager how to render it. | Textual convention | Underlying syntax | Meaning | |---|---|---| | `DisplayString` | `OCTET STRING (SIZE (0..255))` | NVT ASCII text, hint `255a` | | `TruthValue` | `INTEGER { true(1), false(2) }` | a boolean | | `TimeStamp` | `TimeTicks` | the value of `sysUpTime` when an event happened | | `MacAddress` | `OCTET STRING (SIZE (6))` | an 802 address, hint `1x:` | | `RowStatus` | enumerated `INTEGER` | the row creation and deletion protocol | Three rules keep the system simple: 1. A textual convention never reaches the wire. The agent sends the base type's encoding; a `DisplayString` arrives as an `OCTET STRING`. 2. A textual convention's `SYNTAX` cannot refer to another textual convention; it must be a base type or `BITS`. 3. A `DISPLAY-HINT` is not allowed for `OBJECT IDENTIFIER`, `IpAddress`, `Counter32`, `Counter64` or enumerated syntaxes. Note that `TimeTicks` is itself a **base type**, hundredths of a second modulo 2^32; `TimeStamp` is the textual convention built on it. ## What changed from SMIv1 SMIv1 (RFC 1155 and RFC 1212) used an `OBJECT-TYPE` macro too, and RFC 3584 lists what converting a module to SMIv2 requires: - `ACCESS`, which stated the **minimum** support required and allowed `write-only`, becomes `MAX-ACCESS`, which states the **maximum**; `write-only` becomes `read-write`. - `STATUS mandatory` or `optional` becomes `current`, `deprecated` or `obsolete`. - `DESCRIPTION`, optional in SMIv1, is required. - `Counter` and `Gauge` become `Counter32` and `Gauge32`; `NetworkAddress` becomes `IpAddress`. - A `MODULE-IDENTITY` must follow the imports, and every object must belong to at least one `OBJECT-GROUP` (RFC 2580). SMIv2 also introduced `Counter64`, `Unsigned32`, `Integer32` and `BITS`, and replaced SMIv1's informal type assignments, such as RFC 1213's `DisplayString ::= OCTET STRING`, with the formal macro. ## Why an operator cares The clauses answer the questions a monitoring design depends on. `SYNTAX` says whether to graph a value or a rate; `UNITS` and `DESCRIPTION` say what a number measures; `MAX-ACCESS` says whether a write could ever succeed; `STATUS` warns that an object is on its way out.

  • If an object's MAX-ACCESS is read-write, why can an SNMP Set to it still be refused?
    RFC 2578 says MAX-ACCESS is the maximal level of access that makes protocol sense and is independent of administrative authorisation. Whether a particular manager may write is decided by the agent's access control, and the agent can also reject a value it cannot apply. MAX-ACCESS sets the ceiling; policy and the implementation decide below it.
  • Why is TimeStamp defined as a textual convention rather than using TimeTicks directly?
    Because a raw TimeTicks needs its two epochs stated each time. RFC 2579's TimeStamp fixes them: the value of sysUpTime when a specific event happened. Every object that records when something occurred, such as a counter discontinuity, can then share one precise meaning while still being encoded as a TimeTicks.
  • Does SMIv2's MAX-ACCESS mean the same thing as SMIv1's ACCESS?
    No. SMIv1's ACCESS stated the minimum level of support an implementation needed and allowed write-only. SMIv2's MAX-ACCESS states the most access that makes protocol sense and adds read-create and accessible-for-notify. RFC 3584 maps write-only to read-write when converting a module.

saying these in an interview costs you the question

  • A textual convention like DisplayString has its own type tag on the wire
  • MAX-ACCESS read-write means any manager is allowed to write it
  • TimeTicks is a textual convention defined on top of Integer32
  • STATUS deprecated means the object must no longer be implemented
  • The DESCRIPTION clause is commentary that an agent may ignore
  • SMIv2's MAX-ACCESS is just SMIv1's ACCESS under a new name