MIB Smithy

Leaf Objects/OBJECT-TYPEs

Where other definitions in a MIB Module are used to define the OID structure, groupings, and conformance levels of the module, OBJECT-TYPEs are used to define the identification, type and semantics of the actual objects or variables containing management information that can be queried in an SNMP device. These include scalar objects, which have at most one instance in a device, and columnar objects, which may have multiple unique instances within an a device that are related to other columnar objects within a conceptual table.

The OBJECT-TYPE macro is used to define not only the scalar and columnar objects, but also conceptual tables rows by following specific OID assignment rules and assigning the 'SEQUENCE' and 'SEQUENCE OF' types that define the table structure. A conceptual table is defined with a primary type of SEQUENCE OF RowType, and a row is defined with a primary type of RowType, where RowType is a Type Assignment of type SEQUENCE that lists the descriptors and types, in exact order, of the columnar objects. The row OBJECT-TYPE is assigned an OID with subidentifier 1 that is immediately subordinate to the table, and each of the columns are assigned unique subidentifiers that are immediately subordiante to the row.

Creating an OBJECT-TYPE

To create an OBJECT-TYPE in MIB Smithy, you must first have created one or more MIB Modules within the project. Use the Project Tree to select the module in which to create the record. Then, you can either: use Insert → Object Definition in the main menu; click on the Add Object button in the Toolbar; or right-click on the module within the Project Tree, and use its New → Object menu. MIB Smithy will then create the record record with a unique, automatically assigned name, and open a page in the Workspace Panel where you can edit its name and other properties.

General Properties

The Attribute Name, Status, Units, Access Level and OID Value properties are all available to be edited from the General Page of the OBJECT-TYPE Workspace, which is pictured below.

Attribute Name

Each OBJECT-TYPE must be assigned a name. MIB Smithy will automatically assign a name that is unique within the project; however, a user should assign a more suitable name that roughly describes the nature of the object, such as its purpose, the function it provides when set, or the type of management information provided. The name should be chosen so-as to minimize to the possibility of other OIDs being given the same name for compatibility with tools that do not provide mechanisms for working around name collision.

Common practice is for conceptual table and row OBJECT-TYPEs to be assigned 'Table' and 'Entry' suffixes, and for them to share a common prefix with the columns of the table, along with the SEQUENCE Type Assignment defining the table structure to have the same name as the 'Entry' OBJECT-TYPE but with a capitalized first letter. This is a good way to minimize the possibility of collision while at the same time allowing a user to see, at a glance, an implied relationship between the definitions by way of their related naming convention.

A valid object name begins with a lowercase letter and may contain zero or more additional letters or numbers. Hyphens are allowed in SMIv1 provided the name does not end in a hyphen and no two hyphens are adjacent. Hyphens are not allowed in SMIv2 except by way of conversion from SMIv1.

This property is unconditionally required.

Status

This property indicates the status of the object with regards to its historic nature. It may take one of several values depending on the SMI version. For SMIv2 and COPS-PR-SPPI, it may take the values 'current', 'deprecated' or 'obsolete', indicating that the object is current and valid and may continue to be used, that it may still be used but may soon become obsolete in the future, or that the object is now obsolete and should not be implemented or expected to be supported in any recent implementation, respectively.

In SMIv1, it may take the values 'mandatory' or 'optional', indicating that an implementation MUST implement the object if it is to claim conformance to the MIB specification, or that the object is optional and need not be implemented to claim conformance, repectively. It may also take the values 'deprecated' and 'obsolete' in SMIv1, with the same meanings as in SMIv2.

This property is unconditionally required.

Units

This field, which may only be specified for SMIv2 OBJECT-TYPEs, allows the MIB author to specify a suggested (but not required) textual representation of the units associated with a value of the object that may be used for display purposes. For example, an object representing a length of time might choose "seconds" or "minutes", or "ms", while an object representing a running total of the number of packets sent might choose "pkts", and an object representing a throughput rate might choose "kbps".

This property is optional and is not permitted by SMIv1.

Maximum Access Level

The purpose and semantics of the (Maximum) Access Level property are a little different depending on the type and version of the module in question, but in general its purpose is to specify the operations that are allowed for an instance of the object.

In SMIv2, the MAX-ACCESS value specifies the maximum access level that any implementation is permitted to provide. For example, a MAX-ACCESS of read-only means that it is not permitted for an SNMP agent to implement the object such that it is writeable under any circumstances. It can, however, implement the object with a lower access level (e.g. read-only), provided it meets any other constraints imposed by, for example, a MODULE-COMPLIANCE statement.

In contrast, SMIv1's, ACCESS value generally specifies the exact access level that all implementations are required to provide. Of course, an SMIv1 module could have been converted from SMIv2, so one can't always rely on this being the case.

The PIB-ACCESS clause of COPS-PR-SPPI objects is quite different from both SMIv1 and SMIv2. Where both SMIv1 and SMIv2 are required to have their respective ACCESS fields on all OBJECT-TYPE definitions, only those OBJECT-TYPEs defining a Provisioning Class (PRC), and more specifically the top-level OBJECT-TYPE in the PRC (analgous to a MIB module's Table object) allows and requires PIB-ACCESS to be present. PRCs are somewhat the opposite of MIB tables, in that PRC rows (Provisioning Instances or PRIs) are whole units, whereas only individual columns instances are the largest accessible unit in SNMP MIB modules. The PIB-ACCESS level thus indicates the type of operations typically supported by or allowed for a PRC; for other OBJECT-TYPEs, the value should be left as undefined.

This property is required for SMIv1, SMIv2 and COPS-PR-SPPI PRC Tables. It is not permitted for other COPS-PR-SPPI objects.

OID Value

This property registers a unique OBJECT IDENTIFIER value to the OBJECT-TYPE that may be used to identify the definition associated with an instance of a managed object. Instances of managed objects within an SNMP entity are identified by one or more subidentifiers added to the OBJECT-TYPE's OID Value. When assigning an OID to an object, keep the following rules in mind:

1. If the object corresponds to a conceptual column, then only a single assignment, that for a conceptual row, is present immediately above that object. The administratively assigned name for the column is derived by appending a unique, positive sub-identifier to the administratively assigned name for the conceptual row above.
2. If the object corresponds to a conceptual row, only a single assignment, that for a conceptual table is present immediately above that object. The administratively assigned name for the conceptual row object is derived by appending a sub-identifier of "1" to the administratively assigned name for the conceptual table immediately above the row.
3. Otherwise, no other OBJECT IDENTIFIERs which are subordinate to any other OBJECT-TYPE may be assigned to the object.

This property is unconditionally required.

See Also

Object Identifier Values

Syntax Property

The OBJECT-TYPE's Syntax property, which must be present, is used to specify the data type associated with values that the object allows, and may either be one of the base types defined by the SMI, an ASN.1 type allowed by SNMP, or a type derived from either such as a TEXTUAL-CONVENTION. The user interface for this property is functionally the same as for TEXTUAL-CONVENTIONs and Variations, and provides the user with ability either enter the type manually or use a number of filters to quickly locate the desired type.

The OBJECT-TYPE's Syntax property is also used as the primary basis by which a conceptual table or conceptual row is defined. In the case of a conceptual table, the 'Primary Type' field is specified as 'SEQUENCE OF' with a 'Subtype Class' field corresponding to an ASN.1 Type Assignment of type 'SEQUENCE'. For a conceptual row, the 'Primary Type' field is specified as the same type as the 'Subtype Class' for the corresponding conceptual table. For either case, additional restrictions apply on the allowed OID values and the structure defined by the SEQUENCE type.

This property is unconditionally required.

See Also

Syntax Properties

Default Value Property

Starting with RFC 1212 and later versions, the OBJECT-TYPE macro allows specification (via the DEFVAL clause) of a default value that an instance of the object will take during initialization or row creation. As well, Variations defined in an AGENT-CAPABILITIES statement allow specification of such defaults on a per-implementation basis where the OBJECT-TYPE doesn't specify a default, or where the implementation uses a different default. MIB Smithy allow specification of default values from the Defval page of the appropriate workspace.

This property is optional.

See Also

Default Object Values

Description Property

The OBJECT-TYPE's Description property, which must be present when OBJECT-TYPE is imported from SMI versions defined by RFC 1212 or later, is used to provide the reader or implementor a description of the technical purpose and semantics of the managed object, along with any instructions for implementors to follow that cannot be represented syntactically. This should include, for example, the meaning behind a particular value of the object, any additional restrictions on the values that may only be read or written, and any object-specific actions that an implementation should perform when the object is written with specific values.

This property is required for RFC 1212 or later versions.

See Also

Formatting Text Fields

Index Properties

The various indexing properties are used in the definition of conceptual row OBJECT-TYPEs to identify those columnar objects, whether in the same table or other tables, that are to be used in uniquely identifying and sorting a row in the table. Several different forms of indexing are available depending on the module version and how the table or PRC relates to others, if at all. All of these are are configured through the Index tab of the OBJECT-TYPE's workspace, which is pictured below.

For most normal tables in SMIv1 and SMIv2 (MIB) modules, the Index property is used. In this case, each of the column objects - whether in the same table or in other tables - are listed in the table's row object definition. The union of the values of these objects uniquely identifies a row in the table, and the order that index objects are listed determines the order that rows will be sorted in the table. This is somewhat in contrast to the use of Augments or Extends, where the indexing is defined in a separate table and essentially inherited by the augmentation.

Checking the Implied option indicates that the IMPLIED keyword should precede the final index object. It may only be used if the last index is of a variable length, such as an OBJECT IDENTIFIER type or an OCTET STRING without a fixed size restriction.

Normally such indexes are encoded with an extra subidentifier indicating how many of the following subidentifiers are part of the column's value, which causes the sorting on that column to be first by length and then by value. The IMPLIED keyword disables the additional subidentifier so that they are sorted purely by value. The usual reason one wants to do this is to get "alphabetical" sorting; however, because different languages have different sorting rules that aren't necessarily the same as sorting by binary value, this can cause more problems than it's worth. The IMPLIED keyword has therefore been deprecated by the SMI language and its use is discouraged.

In COPS-PR-SPPI objects, the normal Index property of MIB modules does not actually get used to index the PIB table. Rather, PIB tables use the PIB Index, Augments or Extends properties, but allow a normal Index to be present to aid in converting a PIB module to a MIB module.

This property is must only be used with OBJECT-TYPEs defining conceptual rows, and cannot be used in conjunction with the Augments property.

PIB Index Property

The PIB Index property is the principal way by which Provisioning Classes are indexed. The value of this property is a reference to an object, usually but not necessarily within the same table that is of type InstanceId (a TEXTUAL-CONVENTION defined in the COPS-PR-SPPI module). The value of the InstanceId object uniquely identifies a row in the table. The InstanceId object of another table can be used to instead through the 'Augments' or 'Extends' property.

This property is may only be specified in COPS-PR-SPPI row OBJECT-TYPEs defining rows (type SEQUENCE). Each such row must contain one PIB Index, Augments or Extends reference.

PIB Tag Property

The PIB Tag property is used with COPS-PR-SPPI attribute objects when the type is TagReferenceId. This property and type together indicate that the attribute references a "tag list" of instances of another Provisioning Class (table). The value of this property points to an attribute in the other table having type TagId. The "tag list" is formed by all instances of the that table having the same TagId value for the attribute named.

This property is not really an index in the way PIB Index, Augments and Extends are, and cannot be used in place of one of those. However, it is similar in that it be thought of as a way to have one table define collections of rows in another table, via their TagId value.

This property is required for COPS-PR-SPPI attributes of type TagReferenceId. It may not be used with any other version or type.

Augmented Table

This property, which may only be specified if the OBJECT-TYPE has an underlying base type of 'SEQUENCE' indicating a conceptual row, is an alternative to the 'Index' property. Every SMIv2 conceptual row must have either an 'Index' or 'Augments' property specified, but not both. Every COPS-PR-SPPI row must have either a 'PIB Index', 'Augments' or 'Extends' property (see below).

The 'Augments' property allows the subordinate columnar objects of the table to augment another external table. In effect, the augmenting table defines a one-to-one relationship between its rows and the rows of the table it references: for every row in the augmented table, there will be a row with the same indices in the augmenting table, and vise-versa.

The value of this property, if specified, must be a reference to the external table OBJECT-TYPE, which has an underlying base type of 'SEQUENCE OF'. It can be an object identifier value, but normally (and for compatibility) it is usually the descriptor for the table.

This property is optional, may only be specified in SMIv2 and COPS-PR-SPPI OBJECT-TYPEs defining rows (type SEQUENCE) and cannot be used with Index, PIB Index or Extends. It may not be used in SMIv1 modules.

PIB Extends

This property, which may only be specified in COPS-PR-SPPI OBJECT-TYPEs with underlying base types of 'SEQUENCE', indicating a conceptual row, is an alternative to the 'PIB Index' and 'Augments' properties. Every COPS-PR-SPPI row must define either a 'PIB Index', 'Augments' or 'Extends' property.

The 'Extends' property is very closely related to 'Augments'. It allows the subordinate columnar objects of the table to augment another external table without necessarily implying a one-to-one relationship between its rows and the rows of the table it references. A row in the table must be paired with a row in the table it extends with the same instance, but unlike 'Augments' not every row in the extended table requires a corresponding row in the table extending it. This is sometimes referred to as a "sparse augmentation", and it also means that if a row is deleted from the extended table all of the rows having the same instance in other tables that extend it must also be deleted.

The value of this property, if specified, must be a reference to the external table OBJECT-TYPE, which has an underlying base type of 'SEQUENCE OF'. It can be an object identifier value, but normally (and for compatibility) it is usually the descriptor for the table.

This property is optional, may only be specified in COPS-PR-SPPI OBJECT-TYPEs defining rows (type SEQUENCE), and cannot be used with PIB Index or Extends.

Uniqueness Property

The Uniqueness property, which may only be specified in COPS-PR-SPPI OBJECT-TYPEs with underlying base type of 'SEQUENCE', indicating a conceptual row, is somewhat similar in function to the 'Index' property used in tables defined in MIB modules. It defines zero or more attributes (columns) within the table, the union of which comprises a value unique among allow rows in the table.

However, the attributes listed in the Uniqueness clause are not used in construction of the instance identifiers for a row, which are instead always derived from the value of an InstanceId attribute; thus the Uniqueness property is not a sustitute for PIB Index, Augments or Extends. Also, this means the attribute referenced by PIB Index may not also be used in the Uniqueness clause, nor can any attribute appear more than once, since such information would be redundant.

This property is optional and may only be specified in COPS-PR-SPPI OBJECT-TYPEs defining rows (type SEQUENCE). It is, however, recommended when it provides additional useful information.

Reference Property

The OBJECT-TYPE's Reference property may be used to provide the reader or implementor a reference to additional supporting documentation that may be of assistance in interpreting the rules or basis for the type. MIB Smithy will apply the same formatting rules to this property as it does for other similar quoted-text fields such as descriptions.

This property is optional, and requires RFC 1212 or later versions.

See Also

Formatting Text Fields

PIB References Property

The PIB References clause is used with all attributes of type ReferenceId. The property value references to a Provisioning Class (table), where the value of this attribute references an instance of the PRC.

This property is required for COPS-PR-SPPI OBJECT-TYPEs of type ReferenceId, and is forbidden otherwise.

Install Errors Property

The Install Errors property is used to define one or more potential reasons that an install or a removal of an instance of a PRC may be rejected. The property defines a list of named-number enumerations, where the label provides a textual description of the PRC-specific error code, represented by the enumeration's value, used as the Error Sub-code in a COPS protocol message when the Error-Code is priSpecificError. Error codes must be in the range 1..65535.

This property is optional for COPS-PR-SPPI OBJECT-TYPEs defining tables with PIB-ACCESS 'install' or 'install-notify'. It may not be used otherwise.

Comments Property

The Comments Property, which is common to all MIB Smithy records for which ASN.1 is generated (including modules, type assignments, OBJECT-TYPEs, etc.), allows you to specify optional comments that are to be associated with the record. Like comments in programming languages, ASN.1 comments are bits of text that allow extra descriptive text to be provided that are discarded by normal parsers. When MIB Smithy generates the module, either when saving or previewing, the comments for a particular record will be generated immediately above the record they are associated with.

See Also

Formatting Comments