Draft Textual Conventions for SMP Jul 92
Textual Conventions
for the
Simple Management Protocol (SMP) Framework
Sat Jul 4 17:76:03 1992
Jeffrey D. Case
SNMP Research, Inc.
University of Tennessee, Knoxville
case@cs.utk.edu
Keith McCloghrie
Hughes LAN Systems
kzm@hls.com
Marshall T. Rose
Dover Beach Consulting, Inc.
mrose@dbc.mtview.ca.us
Steven L. Waldbusser
Carnegie Mellon University
waldbusser@andrew.cmu.edu
1. Status of this Memo
This document is an Internet Draft. Internet Drafts are
working documents of the Internet Engineering Task Force
(IETF), its Areas, and its Working Groups. Note that other
groups may also distribute working documents as Internet
Drafts.
Internet Drafts are draft documents valid for a maximum of six
months. Internet Drafts may be updated, replaced, or
obsoleted by other documents at any time. It is not
appropriate to use Internet Drafts as reference material or to
cite them other than as a "working draft" or "work in
Expires January 4, 1993 [Page 1]
Draft Textual Conventions for SMP Jul 92
progress".
Please check the 1id-abstracts.txt listing contained in the
internet-drafts Shadow Directories on nic.ddn.mil,
nnsc.nsf.net, nic.nordu.net, ftp.nisc.sri.com, or
munnari.oz.au to learn the current status of any Internet
Draft.
Please send comments to the SNMP discussion group,
<snmp@psi.com>.
Expires January 4, 1993 [Page 2]
Draft Textual Conventions for SMP Jul 92
2. Introduction
A network management system contains: several (potentially
many) nodes, each with management instrumentation termed an
agent; at least one management station; and, a management
protocol, which is used to convey management information
between the agents and management stations. Operations of the
management protocol are carried out under an administrative
framework which defines both authentication and authorization
policies.
Network management stations execute management applications
which monitor and control network elements. Network elements
are devices such as hosts, routers, terminal servers, etc.,
which are monitored and controlled through access to their
management information.
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 a subset of OSI's Abstract Syntax Notation One (ASN.1)
[1], termed the Structure of Management Information (SMI).
When designing a MIB module, it is often useful to define
types, with a different name, but the same syntax, as one of
the types defined in the SMI. These 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.
Expires January 4, 1993 [Page 3]
Draft Textual Conventions for SMP Jul 92
3. Definitions
SMP-TC DEFINITIONS ::= BEGIN
IMPORTS
ObjectSyntax, Integer32, TimeTicks
FROM SMP-SMI;
-- definition of textual conventions
TEXTUAL-CONVENTION MACRO ::=
BEGIN
TYPE NOTATION ::=
DisplayPart
"DESCRIPTION" value(description Text)
ReferPart
VALUE NOTATION ::=
type(VALUE ObjectSyntax)
DisplayPart ::=
"DISPLAY-HINT" value(display Text)
| empty
ReferPart ::=
"REFERENCE" value(reference Text)
| empty
-- uses the NVT ASCII character set
Text ::= OCTET STRING
END
DisplayString TEXTUAL-CONVENTION
DISPLAY-HINT "255a"
DESCRIPTION
"Represents textual information taken from the NVT
ASCII character set, as defined in pages 4, 10-11
of RFC 854. Any object defined using this syntax
may not exceed 255 characters in length."
::= OCTET STRING
PhysAddress TEXTUAL-CONVENTION
Expires January 4, 1993 [Page 4]
Draft Textual Conventions for SMP Jul 92
DISPLAY-HINT "1x:"
DESCRIPTION
"Represents media- or physical-level addresses."
::= OCTET STRING
MacAddress TEXTUAL-CONVENTION
DISPLAY-HINT "1x:"
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."
::= OCTET STRING (SIZE (6))
TruthValue TEXTUAL-CONVENTION
DESCRIPTION
"Represents a boolean value."
::= INTEGER { true(1), false(2) }
TestAndIncr TEXTUAL-CONVENTION
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 previous value held by the
instance is returned.)
The value of the ACCESS clause for objects having
this syntax is either `read-write' or `read-
Expires January 4, 1993 [Page 5]
Draft Textual Conventions for SMP Jul 92
create'. When an instance of a columnar object
having this syntax is created, any value may be
supplied via the management protocol."
::= INTEGER (0..2147483647)
AutonomousType TEXTUAL-CONVENTION
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."
::= OBJECT IDENTIFIER
InstancePointer TEXTUAL-CONVENTION
DESCRIPTION
"A pointer to a specific instance of a conceptual
row of a MIB table in the managed device. By
convention, it is the name of the particular
instance of the first columnar object in the
conceptual row."
::= OBJECT IDENTIFIER
RowStatus TEXTUAL-CONVENTION
DESCRIPTION
"The syntax used for the status column for a
conceptual row. If present, the value of the
DEFVAL clause for an object having this syntax is
either `underModification(3)' or `active(4)'.
To create new object instances for a conceptual
row, a management protocol set operation is issued
which sets the new instance of the status column
to `underCreation(1)'. If the instance already
exists, then the management protocol set operation
fails with an error of `inconsistentValue'.
Otherwise, the instance is created. If the
management protocol set operation created
sufficient instances so that this conceptual row
may be used by the correspondent SMP entity, and
the value of the DEFVAL clause for the status
column is `active(4)', then the SMP entity acting
Expires January 4, 1993 [Page 6]
Draft Textual Conventions for SMP Jul 92
in an agent role immediately sets the value of
this instance to `active(4)'. Otherwise, the SMP
entity acting in an agent role immediately sets
the value of this instance to
`underModification(3)'.
This suggests that the algorithm to create a new
conceptual row is as follows:
First, the management station ascertains the
identity of an unused slot in the conceptual
table of interest.
Second, the management station issues a
management protocol set operation to create
the status column for the desired conceptual
row.
Third, the management station issues a
management protocol get operation to examine
all columns in that conceptual row. For each
column, if the get operation returns a value
for that column, then the management station
may issue an additional management protocol
set operation to change that value; if the
`noSuchInstance' exception is returned, then
the management station must issue an
additional management protocol set operation
to create that instance prior to changing the
status column to `active'; and, if the
`noSuchObject' exception is returned, then
the management station learns that it must
not issue a management protocol set operation
to create an instance of this column.
When an instance of the status column has the
value `underModification(3)' or `active(4)', then
management operations may be issued to manipulate
the columns in the conceptual row. However, only
when the value of an instance of the status column
is `active(4)', will the information in the
conceptual row be available outside of the
management subsystem, i.e., whilst the information
is available to authorized SMP entities acting in
a manager role, the information is independent of
Expires January 4, 1993 [Page 7]
Draft Textual Conventions for SMP Jul 92
the operational state of the managed device. As
such, note that while the status is
`underModification(3)', it is possible for a
managed device to create (or otherwise manipulate)
its own instances which effectively supersede
those held by the SMP entity acting in an agent
role. If the management station doesn't finish
this algorithm (due to a management station or
network failure, for example) conceptual rows may
be left in the `underModification(3)' state,
consuming resources indefinitely. The SMP entity
acting in an agent role may detect conceptual rows
that have been in the `underModification(3) state
for an abnormally long period of time and remove
them from the table. 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(4)'. It is suggested that this period
be approximately 5 minutes in length.
For deletion of conceptual rows, a management
protocol set operation is issued which sets the
instance of the status column to
`underDestruction(2)'. If the operation succeeds,
then the entire conceptual row is immediately
removed from the table."
::= INTEGER {
underCreation(1),
underDestruction(2),
underModification(3),
active(4)
}
TimeStamp TEXTUAL-CONVENTION
DESCRIPTION
"The value of MIB-II's sysUpTime object at which a
specific occurrence happened. The specific
occurrence must be defined in the description of
any object defined using this type."
::= TimeTicks
TimeInterval TEXTUAL-CONVENTION
DESCRIPTION
"A period of time, measured in units of 0.01
Expires January 4, 1993 [Page 8]
Draft Textual Conventions for SMP Jul 92
seconds."
::= Integer32
END
Expires January 4, 1993 [Page 9]
Draft Textual Conventions for SMP Jul 92
4. 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.
4.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 may only be present when
the syntax has an underlying primitive type of INTEGER or
OCTET STRING.
When the syntax has an underlying primitive type of INTEGER,
the hint consists of a single character suggesting a display
format, either: `x' for hexadecimal, `d' for decimal, or `o'
for octal, or `b' for binary.
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.
(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
Expires January 4, 1993 [Page 10]
Draft Textual Conventions for SMP Jul 92
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, or `a' for ascii.
(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.
4.2. 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. Note that, in order to conform to the ASN.1
Expires January 4, 1993 [Page 11]
Draft Textual Conventions for SMP Jul 92
syntax, the entire value of this clause must be enclosed in
double quotation marks, and therefore cannot itself contain
double quotation marks, although the value may be multi-line.
4.3. Mapping of the REFERENCE clause
The REFERENCE clause, which need not be present, contains a
textual cross-reference to a related item defined in some
other published work.
4.4. Mapping of the TEXTUAL-CONVENTION value
The value of an invocation of the TEXTUAL-CONVENTION macro
defines the abstract data structure corresponding to the
textual convention. The data structure must be one of the
alternatives defined in the ObjectSyntax CHOICE from [2].
Expires January 4, 1993 [Page 12]
Draft Textual Conventions for SMP Jul 92
5. Acknowledgements
PhysAddress (and textual conventions) originated in RFC 1213.
MacAddress originated in RFCs 1230 and 1231.
TruthValue originated in RFC 1253.
AutonomousType and InstancePointer originated in RFC 1316.
RowStatus originated in RFC 1271.
Expires January 4, 1993 [Page 13]
Draft Textual Conventions for SMP Jul 92
6. 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] J.D. Case, K. McCloghrie, M.T. Rose, S.L. Waldbusser,
Structure of Management Information for the Simple
Management Protocol (SMP) Framework, (July, 1992).
Expires January 4, 1993 [Page 14]
Draft Textual Conventions for SMP Jul 92
Table of Contents
1 Status of this Memo ................................... 1
2 Introduction .......................................... 3
3 Definitions ........................................... 4
4 Mapping of the TEXTUAL-CONVENTION macro ............... 10
4.1 Mapping of the DISPLAY-HINT clause .................. 10
4.2 Mapping of the DESCRIPTION clause ................... 11
4.3 Mapping of the REFERENCE clause ..................... 12
4.4 Mapping of the TEXTUAL-CONVENTION value ............. 12
5 Acknowledgements ...................................... 13
6 References ............................................ 14
Expires January 4, 1993 [Page 15]