]> git.ipfire.org Git - thirdparty/cups.git/blame - standards/rfc2579.txt
projects / thirdparty / cups.git / blame
? search:
summary | shortlog | log | commit | commitdiff | tree
blob | blame (incremental) | history | HEAD
Merge changes from CUPS 1.5rc1-r9834.
[thirdparty/cups.git] / standards / rfc2579.txt
CommitLineData
68b10830
MS		 1
2
3
4
5
6
7
8Network Working Group Editors of this version:
9Request for Comments: 2579 K. McCloghrie
10STD: 58 Cisco Systems
11Obsoletes: 1903 D. Perkins
12Category: Standards Track SNMPinfo
13 J. Schoenwaelder
14 TU Braunschweig
15 Authors of previous version:
16 J. Case
17 SNMP Research
18 K. McCloghrie
19 Cisco Systems
20 M. Rose
21 First Virtual Holdings
22 S. Waldbusser
23 International Network Services
24 April 1999
25
26
27 Textual Conventions for SMIv2
28
29
30Status of this Memo
31
32 This document specifies an Internet standards track protocol for the
33 Internet community, and requests discussion and suggestions for
34 improvements. Please refer to the current edition of the "Internet
35 Official Protocol Standards" (STD 1) for the standardization state
36 and status of this protocol. Distribution of this memo is unlimited.
37
38Copyright Notice
39
40 Copyright (C) The Internet Society (1999). All Rights Reserved.
41
42
43Table of Contents
44
45 1 Introduction ..................................................2
46 1.1 A Note on Terminology .......................................2
47 2 Definitions ...................................................2
48 3 Mapping of the TEXTUAL-CONVENTION macro ......................20
49 3.1 Mapping of the DISPLAY-HINT clause .........................21
50 3.2 Mapping of the STATUS clause ...............................22
51 3.3 Mapping of the DESCRIPTION clause ..........................23
52 3.4 Mapping of the REFERENCE clause ............................23
53 3.5 Mapping of the SYNTAX clause ...............................23
54 4 Sub-typing of Textual Conventions ............................23
55 5 Revising a Textual Convention Definition .....................23
56
57
58McCloghrie, et al. Standards Track [Page 1]
59\f
60
61
62
63
64RFC 2579 Textual Conventions for SMIv2 April 1999
65
66
67 6 Security Considerations ......................................24
68 7 Editors' Addresses ...........................................25
69 8 References ...................................................25
70 9 Full Copyright Statement .....................................26
71
721. Introduction
73
74 Management information is viewed as a collection of managed objects,
75 residing in a virtual information store, termed the Management
76 Information Base (MIB). Collections of related objects are defined
77 in MIB modules. These modules are written using an adapted subset of
78 OSI's Abstract Syntax Notation One, ASN.1 (1988) [1], termed the
79 Structure of Management Information (SMI) [2].
80
81 When designing a MIB module, it is often useful to define new types
82 similar to those defined in the SMI. In comparison to a type defined
83 in the SMI, each of these new types has a different name, a similar
84 syntax, but a more precise semantics. These newly defined types are
85 termed textual conventions, and are used for the convenience of
86 humans reading the MIB module. It is the purpose of this document to
87 define the initial set of textual conventions available to all MIB
88 modules.
89
90 Objects defined using a textual convention are always encoded by
91 means of the rules that define their primitive type. However,
92 textual conventions often have special semantics associated with
93 them. As such, an ASN.1 macro, TEXTUAL-CONVENTION, is used to
94 concisely convey the syntax and semantics of a textual convention.
95
961.1. A Note on Terminology
97
98 For the purpose of exposition, the original Structure of Management
99 Information, as described in RFCs 1155 (STD 16), 1212 (STD 16), and
100 RFC 1215, is termed the SMI version 1 (SMIv1). The current version
101 of the Structure of Management Information is termed SMI version 2
102 (SMIv2).
103
1042. Definitions
105
106SNMPv2-TC DEFINITIONS ::= BEGIN
107
108IMPORTS
109 TimeTicks FROM SNMPv2-SMI;
110
111
112-- definition of textual conventions
113
114TEXTUAL-CONVENTION MACRO ::=
115
116
117McCloghrie, et al. Standards Track [Page 2]
118\f
119
120
121
122
123RFC 2579 Textual Conventions for SMIv2 April 1999
124
125
126BEGIN
127 TYPE NOTATION ::=
128 DisplayPart
129 "STATUS" Status
130 "DESCRIPTION" Text
131 ReferPart
132 "SYNTAX" Syntax
133
134 VALUE NOTATION ::=
135 value(VALUE Syntax) -- adapted ASN.1
136
137 DisplayPart ::=
138 "DISPLAY-HINT" Text
139 | empty
140
141 Status ::=
142 "current"
143 | "deprecated"
144 | "obsolete"
145
146 ReferPart ::=
147 "REFERENCE" Text
148 | empty
149
150 -- a character string as defined in [2]
151 Text ::= value(IA5String)
152
153 Syntax ::= -- Must be one of the following:
154 -- a base type (or its refinement), or
155 -- a BITS pseudo-type
156 type
157 | "BITS" "{" NamedBits "}"
158
159 NamedBits ::= NamedBit
160 | NamedBits "," NamedBit
161
162 NamedBit ::= identifier "(" number ")" -- number is nonnegative
163
164END
165
166
167
168
169DisplayString ::= TEXTUAL-CONVENTION
170 DISPLAY-HINT "255a"
171 STATUS current
172 DESCRIPTION
173 "Represents textual information taken from the NVT ASCII
174
175
176McCloghrie, et al. Standards Track [Page 3]
177\f
178
179
180
181
182RFC 2579 Textual Conventions for SMIv2 April 1999
183
184
185 character set, as defined in pages 4, 10-11 of RFC 854.
186
187 To summarize RFC 854, the NVT ASCII repertoire specifies:
188
189 - the use of character codes 0-127 (decimal)
190
191 - the graphics characters (32-126) are interpreted as
192 US ASCII
193
194 - NUL, LF, CR, BEL, BS, HT, VT and FF have the special
195 meanings specified in RFC 854
196
197 - the other 25 codes have no standard interpretation
198
199 - the sequence 'CR LF' means newline
200
201 - the sequence 'CR NUL' means carriage-return
202
203 - an 'LF' not preceded by a 'CR' means moving to the
204 same column on the next line.
205
206 - the sequence 'CR x' for any x other than LF or NUL is
207 illegal. (Note that this also means that a string may
208 end with either 'CR LF' or 'CR NUL', but not with CR.)
209
210 Any object defined using this syntax may not exceed 255
211 characters in length."
212 SYNTAX OCTET STRING (SIZE (0..255))
213
214PhysAddress ::= TEXTUAL-CONVENTION
215 DISPLAY-HINT "1x:"
216 STATUS current
217 DESCRIPTION
218 "Represents media- or physical-level addresses."
219 SYNTAX OCTET STRING
220
221
222MacAddress ::= TEXTUAL-CONVENTION
223 DISPLAY-HINT "1x:"
224 STATUS current
225 DESCRIPTION
226 "Represents an 802 MAC address represented in the
227 `canonical' order defined by IEEE 802.1a, i.e., as if it
228 were transmitted least significant bit first, even though
229 802.5 (in contrast to other 802.x protocols) requires MAC
230 addresses to be transmitted most significant bit first."
231 SYNTAX OCTET STRING (SIZE (6))
232
233
234
235McCloghrie, et al. Standards Track [Page 4]
236\f
237
238
239
240
241RFC 2579 Textual Conventions for SMIv2 April 1999
242
243
244TruthValue ::= TEXTUAL-CONVENTION
245 STATUS current
246 DESCRIPTION
247 "Represents a boolean value."
248 SYNTAX INTEGER { true(1), false(2) }
249
250TestAndIncr ::= TEXTUAL-CONVENTION
251 STATUS current
252 DESCRIPTION
253 "Represents integer-valued information used for atomic
254 operations. When the management protocol is used to specify
255 that an object instance having this syntax is to be
256 modified, the new value supplied via the management protocol
257 must precisely match the value presently held by the
258 instance. If not, the management protocol set operation
259 fails with an error of `inconsistentValue'. Otherwise, if
260 the current value is the maximum value of 2^31-1 (2147483647
261 decimal), then the value held by the instance is wrapped to
262 zero; otherwise, the value held by the instance is
263 incremented by one. (Note that regardless of whether the
264 management protocol set operation succeeds, the variable-
265 binding in the request and response PDUs are identical.)
266
267 The value of the ACCESS clause for objects having this
268 syntax is either `read-write' or `read-create'. When an
269 instance of a columnar object having this syntax is created,
270 any value may be supplied via the management protocol.
271
272 When the network management portion of the system is re-
273 initialized, the value of every object instance having this
274 syntax must either be incremented from its value prior to
275 the re-initialization, or (if the value prior to the re-
276 initialization is unknown) be set to a pseudo-randomly
277 generated value."
278 SYNTAX INTEGER (0..2147483647)
279
280AutonomousType ::= TEXTUAL-CONVENTION
281 STATUS current
282 DESCRIPTION
283 "Represents an independently extensible type identification
284 value. It may, for example, indicate a particular sub-tree
285 with further MIB definitions, or define a particular type of
286 protocol or hardware."
287 SYNTAX OBJECT IDENTIFIER
288
289
290InstancePointer ::= TEXTUAL-CONVENTION
291 STATUS obsolete
292
293
294McCloghrie, et al. Standards Track [Page 5]
295\f
296
297
298
299
300RFC 2579 Textual Conventions for SMIv2 April 1999
301
302
303 DESCRIPTION
304 "A pointer to either a specific instance of a MIB object or
305 a conceptual row of a MIB table in the managed device. In
306 the latter case, by convention, it is the name of the
307 particular instance of the first accessible columnar object
308 in the conceptual row.
309
310 The two uses of this textual convention are replaced by
311 VariablePointer and RowPointer, respectively."
312 SYNTAX OBJECT IDENTIFIER
313
314
315VariablePointer ::= TEXTUAL-CONVENTION
316 STATUS current
317 DESCRIPTION
318 "A pointer to a specific object instance. For example,
319 sysContact.0 or ifInOctets.3."
320 SYNTAX OBJECT IDENTIFIER
321
322
323RowPointer ::= TEXTUAL-CONVENTION
324 STATUS current
325 DESCRIPTION
326 "Represents a pointer to a conceptual row. The value is the
327 name of the instance of the first accessible columnar object
328 in the conceptual row.
329
330 For example, ifIndex.3 would point to the 3rd row in the
331 ifTable (note that if ifIndex were not-accessible, then
332 ifDescr.3 would be used instead)."
333 SYNTAX OBJECT IDENTIFIER
334
335RowStatus ::= TEXTUAL-CONVENTION
336 STATUS current
337 DESCRIPTION
338 "The RowStatus textual convention is used to manage the
339 creation and deletion of conceptual rows, and is used as the
340 value of the SYNTAX clause for the status column of a
341 conceptual row (as described in Section 7.7.1 of [2].)
342
343
344
345
346
347
348
349
350
351
352
353McCloghrie, et al. Standards Track [Page 6]
354\f
355
356
357
358
359RFC 2579 Textual Conventions for SMIv2 April 1999
360
361
362 The status column has six defined values:
363
364 - `active', which indicates that the conceptual row is
365 available for use by the managed device;
366
367 - `notInService', which indicates that the conceptual
368 row exists in the agent, but is unavailable for use by
369 the managed device (see NOTE below); 'notInService' has
370 no implication regarding the internal consistency of
371 the row, availability of resources, or consistency with
372 the current state of the managed device;
373
374 - `notReady', which indicates that the conceptual row
375 exists in the agent, but is missing information
376 necessary in order to be available for use by the
377 managed device (i.e., one or more required columns in
378 the conceptual row have not been instanciated);
379
380 - `createAndGo', which is supplied by a management
381 station wishing to create a new instance of a
382 conceptual row and to have its status automatically set
383 to active, making it available for use by the managed
384 device;
385
386 - `createAndWait', which is supplied by a management
387 station wishing to create a new instance of a
388 conceptual row (but not make it available for use by
389 the managed device); and,
390
391 - `destroy', which is supplied by a management station
392 wishing to delete all of the instances associated with
393 an existing conceptual row.
394
395 Whereas five of the six values (all except `notReady') may
396 be specified in a management protocol set operation, only
397 three values will be returned in response to a management
398 protocol retrieval operation: `notReady', `notInService' or
399 `active'. That is, when queried, an existing conceptual row
400 has only three states: it is either available for use by
401 the managed device (the status column has value `active');
402 it is not available for use by the managed device, though
403 the agent has sufficient information to attempt to make it
404 so (the status column has value `notInService'); or, it is
405 not available for use by the managed device, and an attempt
406 to make it so would fail because the agent has insufficient
407 information (the state column has value `notReady').
408
409
410
411
412McCloghrie, et al. Standards Track [Page 7]
413\f
414
415
416
417
418RFC 2579 Textual Conventions for SMIv2 April 1999
419
420
421 NOTE WELL
422
423 This textual convention may be used for a MIB table,
424 irrespective of whether the values of that table's
425 conceptual rows are able to be modified while it is
426 active, or whether its conceptual rows must be taken
427 out of service in order to be modified. That is, it is
428 the responsibility of the DESCRIPTION clause of the
429 status column to specify whether the status column must
430 not be `active' in order for the value of some other
431 column of the same conceptual row to be modified. If
432 such a specification is made, affected columns may be
433 changed by an SNMP set PDU if the RowStatus would not
434 be equal to `active' either immediately before or after
435 processing the PDU. In other words, if the PDU also
436 contained a varbind that would change the RowStatus
437 value, the column in question may be changed if the
438 RowStatus was not equal to `active' as the PDU was
439 received, or if the varbind sets the status to a value
440 other than 'active'.
441
442
443 Also note that whenever any elements of a row exist, the
444 RowStatus column must also exist.
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471McCloghrie, et al. Standards Track [Page 8]
472\f
473
474
475
476
477RFC 2579 Textual Conventions for SMIv2 April 1999
478
479
480 To summarize the effect of having a conceptual row with a
481 status column having a SYNTAX clause value of RowStatus,
482 consider the following state diagram:
483
484
485 STATE
486 +--------------+-----------+-------------+-------------
487 | A | B | C | D
488 | |status col.|status column|
489 |status column | is | is |status column
490 ACTION |does not exist| notReady | notInService| is active
491--------------+--------------+-----------+-------------+-------------
492set status |noError ->D|inconsist- |inconsistent-|inconsistent-
493column to | or | entValue| Value| Value
494createAndGo |inconsistent- | | |
495 | Value| | |
496--------------+--------------+-----------+-------------+-------------
497set status |noError see 1|inconsist- |inconsistent-|inconsistent-
498column to | or | entValue| Value| Value
499createAndWait |wrongValue | | |
500--------------+--------------+-----------+-------------+-------------
501set status |inconsistent- |inconsist- |noError |noError
502column to | Value| entValue| |
503active | | | |
504 | | or | |
505 | | | |
506 | |see 2 ->D|see 8 ->D| ->D
507--------------+--------------+-----------+-------------+-------------
508set status |inconsistent- |inconsist- |noError |noError ->C
509column to | Value| entValue| |
510notInService | | | |
511 | | or | | or
512 | | | |
513 | |see 3 ->C| ->C|see 6
514--------------+--------------+-----------+-------------+-------------
515set status |noError |noError |noError |noError ->A
516column to | | | | or
517destroy | ->A| ->A| ->A|see 7
518--------------+--------------+-----------+-------------+-------------
519set any other |see 4 |noError |noError |see 5
520column to some| | | |
521value | | see 1| ->C| ->D
522--------------+--------------+-----------+-------------+-------------
523
524 (1) goto B or C, depending on information available to the
525 agent.
526
527 (2) if other variable bindings included in the same PDU,
528
529
530McCloghrie, et al. Standards Track [Page 9]
531\f
532
533
534
535
536RFC 2579 Textual Conventions for SMIv2 April 1999
537
538
539 provide values for all columns which are missing but
540 required, and all columns have acceptable values, then
541 return noError and goto D.
542
543 (3) if other variable bindings included in the same PDU,
544 provide legal values for all columns which are missing but
545 required, then return noError and goto C.
546
547 (4) at the discretion of the agent, the return value may be
548 either:
549
550 inconsistentName: because the agent does not choose to
551 create such an instance when the corresponding
552 RowStatus instance does not exist, or
553
554 inconsistentValue: if the supplied value is
555 inconsistent with the state of some other MIB object's
556 value, or
557
558 noError: because the agent chooses to create the
559 instance.
560
561 If noError is returned, then the instance of the status
562 column must also be created, and the new state is B or C,
563 depending on the information available to the agent. If
564 inconsistentName or inconsistentValue is returned, the row
565 remains in state A.
566
567 (5) depending on the MIB definition for the column/table,
568 either noError or inconsistentValue may be returned.
569
570 (6) the return value can indicate one of the following
571 errors:
572
573 wrongValue: because the agent does not support
574 notInService (e.g., an agent which does not support
575 createAndWait), or
576
577 inconsistentValue: because the agent is unable to take
578 the row out of service at this time, perhaps because it
579 is in use and cannot be de-activated.
580
581 (7) the return value can indicate the following error:
582
583 inconsistentValue: because the agent is unable to
584 remove the row at this time, perhaps because it is in
585 use and cannot be de-activated.
586
587
588
589McCloghrie, et al. Standards Track [Page 10]
590\f
591
592
593
594
595RFC 2579 Textual Conventions for SMIv2 April 1999
596
597
598 (8) the transition to D can fail, e.g., if the values of the
599 conceptual row are inconsistent, then the error code would
600 be inconsistentValue.
601
602 NOTE: Other processing of (this and other varbinds of) the
603 set request may result in a response other than noError
604 being returned, e.g., wrongValue, noCreation, etc.
605
606
607 Conceptual Row Creation
608
609 There are four potential interactions when creating a
610 conceptual row: selecting an instance-identifier which is
611 not in use; creating the conceptual row; initializing any
612 objects for which the agent does not supply a default; and,
613 making the conceptual row available for use by the managed
614 device.
615
616 Interaction 1: Selecting an Instance-Identifier
617
618 The algorithm used to select an instance-identifier varies
619 for each conceptual row. In some cases, the instance-
620 identifier is semantically significant, e.g., the
621 destination address of a route, and a management station
622 selects the instance-identifier according to the semantics.
623
624 In other cases, the instance-identifier is used solely to
625 distinguish conceptual rows, and a management station
626 without specific knowledge of the conceptual row might
627 examine the instances present in order to determine an
628 unused instance-identifier. (This approach may be used, but
629 it is often highly sub-optimal; however, it is also a
630 questionable practice for a naive management station to
631 attempt conceptual row creation.)
632
633 Alternately, the MIB module which defines the conceptual row
634 might provide one or more objects which provide assistance
635 in determining an unused instance-identifier. For example,
636 if the conceptual row is indexed by an integer-value, then
637 an object having an integer-valued SYNTAX clause might be
638 defined for such a purpose, allowing a management station to
639 issue a management protocol retrieval operation. In order
640 to avoid unnecessary collisions between competing management
641 stations, `adjacent' retrievals of this object should be
642 different.
643
644 Finally, the management station could select a pseudo-random
645 number to use as the index. In the event that this index
646
647
648McCloghrie, et al. Standards Track [Page 11]
649\f
650
651
652
653
654RFC 2579 Textual Conventions for SMIv2 April 1999
655
656
657 was already in use and an inconsistentValue was returned in
658 response to the management protocol set operation, the
659 management station should simply select a new pseudo-random
660 number and retry the operation.
661
662 A MIB designer should choose between the two latter
663 algorithms based on the size of the table (and therefore the
664 efficiency of each algorithm). For tables in which a large
665 number of entries are expected, it is recommended that a MIB
666 object be defined that returns an acceptable index for
667 creation. For tables with small numbers of entries, it is
668 recommended that the latter pseudo-random index mechanism be
669 used.
670
671 Interaction 2: Creating the Conceptual Row
672
673 Once an unused instance-identifier has been selected, the
674 management station determines if it wishes to create and
675 activate the conceptual row in one transaction or in a
676 negotiated set of interactions.
677
678 Interaction 2a: Creating and Activating the Conceptual Row
679
680 The management station must first determine the column
681 requirements, i.e., it must determine those columns for
682 which it must or must not provide values. Depending on the
683 complexity of the table and the management station's
684 knowledge of the agent's capabilities, this determination
685 can be made locally by the management station. Alternately,
686 the management station issues a management protocol get
687 operation to examine all columns in the conceptual row that
688 it wishes to create. In response, for each column, there
689 are three possible outcomes:
690
691 - a value is returned, indicating that some other
692 management station has already created this conceptual
693 row. We return to interaction 1.
694
695 - the exception `noSuchInstance' is returned,
696 indicating that the agent implements the object-type
697 associated with this column, and that this column in at
698 least one conceptual row would be accessible in the MIB
699 view used by the retrieval were it to exist. For those
700 columns to which the agent provides read-create access,
701 the `noSuchInstance' exception tells the management
702 station that it should supply a value for this column
703 when the conceptual row is to be created.
704
705
706
707McCloghrie, et al. Standards Track [Page 12]
708\f
709
710
711
712
713RFC 2579 Textual Conventions for SMIv2 April 1999
714
715
716 - the exception `noSuchObject' is returned, indicating
717 that the agent does not implement the object-type
718 associated with this column or that there is no
719 conceptual row for which this column would be
720 accessible in the MIB view used by the retrieval. As
721 such, the management station can not issue any
722 management protocol set operations to create an
723 instance of this column.
724
725 Once the column requirements have been determined, a
726 management protocol set operation is accordingly issued.
727 This operation also sets the new instance of the status
728 column to `createAndGo'.
729
730 When the agent processes the set operation, it verifies that
731 it has sufficient information to make the conceptual row
732 available for use by the managed device. The information
733 available to the agent is provided by two sources: the
734 management protocol set operation which creates the
735 conceptual row, and, implementation-specific defaults
736 supplied by the agent (note that an agent must provide
737 implementation-specific defaults for at least those objects
738 which it implements as read-only). If there is sufficient
739 information available, then the conceptual row is created, a
740 `noError' response is returned, the status column is set to
741 `active', and no further interactions are necessary (i.e.,
742 interactions 3 and 4 are skipped). If there is insufficient
743 information, then the conceptual row is not created, and the
744 set operation fails with an error of `inconsistentValue'.
745 On this error, the management station can issue a management
746 protocol retrieval operation to determine if this was
747 because it failed to specify a value for a required column,
748 or, because the selected instance of the status column
749 already existed. In the latter case, we return to
750 interaction 1. In the former case, the management station
751 can re-issue the set operation with the additional
752 information, or begin interaction 2 again using
753 `createAndWait' in order to negotiate creation of the
754 conceptual row.
755
756
757
758
759
760
761
762
763
764
765
766McCloghrie, et al. Standards Track [Page 13]
767\f
768
769
770
771
772RFC 2579 Textual Conventions for SMIv2 April 1999
773
774
775 NOTE WELL
776
777 Regardless of the method used to determine the column
778 requirements, it is possible that the management
779 station might deem a column necessary when, in fact,
780 the agent will not allow that particular columnar
781 instance to be created or written. In this case, the
782 management protocol set operation will fail with an
783 error such as `noCreation' or `notWritable'. In this
784 case, the management station decides whether it needs
785 to be able to set a value for that particular columnar
786 instance. If not, the management station re-issues the
787 management protocol set operation, but without setting
788 a value for that particular columnar instance;
789 otherwise, the management station aborts the row
790 creation algorithm.
791
792 Interaction 2b: Negotiating the Creation of the Conceptual
793 Row
794
795 The management station issues a management protocol set
796 operation which sets the desired instance of the status
797 column to `createAndWait'. If the agent is unwilling to
798 process a request of this sort, the set operation fails with
799 an error of `wrongValue'. (As a consequence, such an agent
800 must be prepared to accept a single management protocol set
801 operation, i.e., interaction 2a above, containing all of the
802 columns indicated by its column requirements.) Otherwise,
803 the conceptual row is created, a `noError' response is
804 returned, and the status column is immediately set to either
805 `notInService' or `notReady', depending on whether it has
806 sufficient information to (attempt to) make the conceptual
807 row available for use by the managed device. If there is
808 sufficient information available, then the status column is
809 set to `notInService'; otherwise, if there is insufficient
810 information, then the status column is set to `notReady'.
811 Regardless, we proceed to interaction 3.
812
813 Interaction 3: Initializing non-defaulted Objects
814
815 The management station must now determine the column
816 requirements. It issues a management protocol get operation
817 to examine all columns in the created conceptual row. In
818 the response, for each column, there are three possible
819 outcomes:
820
821
822
823
824
825McCloghrie, et al. Standards Track [Page 14]
826\f
827
828
829
830
831RFC 2579 Textual Conventions for SMIv2 April 1999
832
833
834 - a value is returned, indicating that the agent
835 implements the object-type associated with this column
836 and had sufficient information to provide a value. For
837 those columns to which the agent provides read-create
838 access (and for which the agent allows their values to
839 be changed after their creation), a value return tells
840 the management station that it may issue additional
841 management protocol set operations, if it desires, in
842 order to change the value associated with this column.
843
844 - the exception `noSuchInstance' is returned,
845 indicating that the agent implements the object-type
846 associated with this column, and that this column in at
847 least one conceptual row would be accessible in the MIB
848 view used by the retrieval were it to exist. However,
849 the agent does not have sufficient information to
850 provide a value, and until a value is provided, the
851 conceptual row may not be made available for use by the
852 managed device. For those columns to which the agent
853 provides read-create access, the `noSuchInstance'
854 exception tells the management station that it must
855 issue additional management protocol set operations, in
856 order to provide a value associated with this column.
857
858 - the exception `noSuchObject' is returned, indicating
859 that the agent does not implement the object-type
860 associated with this column or that there is no
861 conceptual row for which this column would be
862 accessible in the MIB view used by the retrieval. As
863 such, the management station can not issue any
864 management protocol set operations to create an
865 instance of this column.
866
867 If the value associated with the status column is
868 `notReady', then the management station must first deal with
869 all `noSuchInstance' columns, if any. Having done so, the
870 value of the status column becomes `notInService', and we
871 proceed to interaction 4.
872
873
874
875
876
877
878
879
880
881
882
883
884McCloghrie, et al. Standards Track [Page 15]
885\f
886
887
888
889
890RFC 2579 Textual Conventions for SMIv2 April 1999
891
892
893 Interaction 4: Making the Conceptual Row Available
894
895 Once the management station is satisfied with the values
896 associated with the columns of the conceptual row, it issues
897 a management protocol set operation to set the status column
898 to `active'. If the agent has sufficient information to
899 make the conceptual row available for use by the managed
900 device, the management protocol set operation succeeds (a
901 `noError' response is returned). Otherwise, the management
902 protocol set operation fails with an error of
903 `inconsistentValue'.
904
905 NOTE WELL
906
907 A conceptual row having a status column with value
908 `notInService' or `notReady' is unavailable to the
909 managed device. As such, it is possible for the
910 managed device to create its own instances during the
911 time between the management protocol set operation
912 which sets the status column to `createAndWait' and the
913 management protocol set operation which sets the status
914 column to `active'. In this case, when the management
915 protocol set operation is issued to set the status
916 column to `active', the values held in the agent
917 supersede those used by the managed device.
918
919 If the management station is prevented from setting the
920 status column to `active' (e.g., due to management station
921 or network failure) the conceptual row will be left in the
922 `notInService' or `notReady' state, consuming resources
923 indefinitely. The agent must detect conceptual rows that
924 have been in either state for an abnormally long period of
925 time and remove them. It is the responsibility of the
926 DESCRIPTION clause of the status column to indicate what an
927 abnormally long period of time would be. This period of
928 time should be long enough to allow for human response time
929 (including `think time') between the creation of the
930 conceptual row and the setting of the status to `active'.
931 In the absence of such information in the DESCRIPTION
932 clause, it is suggested that this period be approximately 5
933 minutes in length. This removal action applies not only to
934 newly-created rows, but also to previously active rows which
935 are set to, and left in, the notInService state for a
936 prolonged period exceeding that which is considered normal
937 for such a conceptual row.
938
939
940
941
942
943McCloghrie, et al. Standards Track [Page 16]
944\f
945
946
947
948
949RFC 2579 Textual Conventions for SMIv2 April 1999
950
951
952 Conceptual Row Suspension
953
954 When a conceptual row is `active', the management station
955 may issue a management protocol set operation which sets the
956 instance of the status column to `notInService'. If the
957 agent is unwilling to do so, the set operation fails with an
958 error of `wrongValue' or `inconsistentValue'. Otherwise,
959 the conceptual row is taken out of service, and a `noError'
960 response is returned. It is the responsibility of the
961 DESCRIPTION clause of the status column to indicate under
962 what circumstances the status column should be taken out of
963 service (e.g., in order for the value of some other column
964 of the same conceptual row to be modified).
965
966
967 Conceptual Row Deletion
968
969 For deletion of conceptual rows, a management protocol set
970 operation is issued which sets the instance of the status
971 column to `destroy'. This request may be made regardless of
972 the current value of the status column (e.g., it is possible
973 to delete conceptual rows which are either `notReady',
974 `notInService' or `active'.) If the operation succeeds,
975 then all instances associated with the conceptual row are
976 immediately removed."
977 SYNTAX INTEGER {
978 -- the following two values are states:
979 -- these values may be read or written
980 active(1),
981 notInService(2),
982
983 -- the following value is a state:
984 -- this value may be read, but not written
985 notReady(3),
986
987 -- the following three values are
988 -- actions: these values may be written,
989 -- but are never read
990 createAndGo(4),
991 createAndWait(5),
992 destroy(6)
993 }
994
995TimeStamp ::= TEXTUAL-CONVENTION
996 STATUS current
997 DESCRIPTION
998 "The value of the sysUpTime object at which a specific
999 occurrence happened. The specific occurrence must be
1000
1001
1002McCloghrie, et al. Standards Track [Page 17]
1003\f
1004
1005
1006
1007
1008RFC 2579 Textual Conventions for SMIv2 April 1999
1009
1010
1011 defined in the description of any object defined using this
1012 type.
1013
1014 If sysUpTime is reset to zero as a result of a re-
1015 initialization of the network management (sub)system, then
1016 the values of all TimeStamp objects are also reset.
1017 However, after approximately 497 days without a re-
1018 initialization, the sysUpTime object will reach 2^^32-1 and
1019 then increment around to zero; in this case, existing values
1020 of TimeStamp objects do not change. This can lead to
1021 ambiguities in the value of TimeStamp objects."
1022 SYNTAX TimeTicks
1023
1024
1025TimeInterval ::= TEXTUAL-CONVENTION
1026 STATUS current
1027 DESCRIPTION
1028 "A period of time, measured in units of 0.01 seconds."
1029 SYNTAX INTEGER (0..2147483647)
1030
1031DateAndTime ::= TEXTUAL-CONVENTION
1032 DISPLAY-HINT "2d-1d-1d,1d:1d:1d.1d,1a1d:1d"
1033 STATUS current
1034 DESCRIPTION
1035 "A date-time specification.
1036
1037 field octets contents range
1038 ----- ------ -------- -----
1039 1 1-2 year* 0..65536
1040 2 3 month 1..12
1041 3 4 day 1..31
1042 4 5 hour 0..23
1043 5 6 minutes 0..59
1044 6 7 seconds 0..60
1045 (use 60 for leap-second)
1046 7 8 deci-seconds 0..9
1047 8 9 direction from UTC '+' / '-'
1048 9 10 hours from UTC* 0..13
1049 10 11 minutes from UTC 0..59
1050
1051 * Notes:
1052 - the value of year is in network-byte order
1053 - daylight saving time in New Zealand is +13
1054
1055 For example, Tuesday May 26, 1992 at 1:30:15 PM EDT would be
1056 displayed as:
1057
1058 1992-5-26,13:30:15.0,-4:0
1059
1060
1061McCloghrie, et al. Standards Track [Page 18]
1062\f
1063
1064
1065
1066
1067RFC 2579 Textual Conventions for SMIv2 April 1999
1068
1069
1070 Note that if only local time is known, then timezone
1071 information (fields 8-10) is not present."
1072 SYNTAX OCTET STRING (SIZE (8 | 11))
1073
1074
1075StorageType ::= TEXTUAL-CONVENTION
1076 STATUS current
1077 DESCRIPTION
1078 "Describes the memory realization of a conceptual row. A
1079 row which is volatile(2) is lost upon reboot. A row which
1080 is either nonVolatile(3), permanent(4) or readOnly(5), is
1081 backed up by stable storage. A row which is permanent(4)
1082 can be changed but not deleted. A row which is readOnly(5)
1083 cannot be changed nor deleted.
1084
1085 If the value of an object with this syntax is either
1086 permanent(4) or readOnly(5), it cannot be written.
1087 Conversely, if the value is either other(1), volatile(2) or
1088 nonVolatile(3), it cannot be modified to be permanent(4) or
1089 readOnly(5). (All illegal modifications result in a
1090 'wrongValue' error.)
1091
1092 Every usage of this textual convention is required to
1093 specify the columnar objects which a permanent(4) row must
1094 at a minimum allow to be writable."
1095 SYNTAX INTEGER {
1096 other(1), -- eh?
1097 volatile(2), -- e.g., in RAM
1098 nonVolatile(3), -- e.g., in NVRAM
1099 permanent(4), -- e.g., partially in ROM
1100 readOnly(5) -- e.g., completely in ROM
1101 }
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120McCloghrie, et al. Standards Track [Page 19]
1121\f
1122
1123
1124
1125
1126RFC 2579 Textual Conventions for SMIv2 April 1999
1127
1128
1129TDomain ::= TEXTUAL-CONVENTION
1130 STATUS current
1131 DESCRIPTION
1132 "Denotes a kind of transport service.
1133
1134 Some possible values, such as snmpUDPDomain, are defined in
1135 the SNMPv2-TM MIB module. Other possible values are defined
1136 in other MIB modules."
1137 REFERENCE "The SNMPv2-TM MIB module is defined in RFC 1906."
1138 SYNTAX OBJECT IDENTIFIER
1139
1140
1141TAddress ::= TEXTUAL-CONVENTION
1142 STATUS current
1143 DESCRIPTION
1144 "Denotes a transport service address.
1145
1146 A TAddress value is always interpreted within the context of a
1147 TDomain value. Thus, each definition of a TDomain value must
1148 be accompanied by a definition of a textual convention for use
1149 with that TDomain. Some possible textual conventions, such as
1150 SnmpUDPAddress for snmpUDPDomain, are defined in the SNMPv2-TM
1151 MIB module. Other possible textual conventions are defined in
1152 other MIB modules."
1153 REFERENCE "The SNMPv2-TM MIB module is defined in RFC 1906."
1154 SYNTAX OCTET STRING (SIZE (1..255))
1155
1156
1157END
1158
11593. Mapping of the TEXTUAL-CONVENTION macro
1160
1161 The TEXTUAL-CONVENTION macro is used to convey the syntax and
1162 semantics associated with a textual convention. It should be noted
1163 that the expansion of the TEXTUAL-CONVENTION macro is something which
1164 conceptually happens during implementation and not during run-time.
1165
1166 The name of a textual convention must consist of one or more letters
1167 or digits, with the initial character being an upper case letter.
1168 The name must not conflict with any of the reserved words listed in
1169 section 3.7 of [2], should not consist of all upper case letters, and
1170 shall not exceed 64 characters in length. (However, names longer
1171 than 32 characters are not recommended.) The hyphen is not allowed
1172 in the name of a textual convention (except for use in information
1173 modules converted from SMIv1 which allowed hyphens in ASN.1 type
1174 assignments). Further, all names used for the textual conventions
1175 defined in all "standard" information modules shall be unique.
1176
1177
1178
1179McCloghrie, et al. Standards Track [Page 20]
1180\f
1181
1182
1183
1184
1185RFC 2579 Textual Conventions for SMIv2 April 1999
1186
1187
11883.1. Mapping of the DISPLAY-HINT clause
1189
1190 The DISPLAY-HINT clause, which need not be present, gives a hint as
1191 to how the value of an instance of an object with the syntax defined
1192 using this textual convention might be displayed. The DISPLAY-HINT
1193 clause must not be present if the Textual Convention is defined with
1194 a syntax of: OBJECT IDENTIFIER, IpAddress, Counter32, Counter64, or
1195 any enumerated syntax (BITS or INTEGER). The determination of
1196 whether it makes sense for other syntax types is dependent on the
1197 specific definition of the Textual Convention.
1198
1199 When the syntax has an underlying primitive type of INTEGER, the hint
1200 consists of an integer-format specification, containing two parts.
1201 The first part is a single character suggesting a display format,
1202 either: `x' for hexadecimal, or `d' for decimal, or `o' for octal, or
1203 `b' for binary. For all types, when rendering the value, leading
1204 zeros are omitted, and for negative values, a minus sign is rendered
1205 immediately before the digits. The second part is always omitted for
1206 `x', `o' and `b', and need not be present for `d'. If present, the
1207 second part starts with a hyphen and is followed by a decimal number,
1208 which defines the implied decimal point when rendering the value.
1209 For example:
1210
1211 Hundredths ::= TEXTUAL-CONVENTION
1212 DISPLAY-HINT "d-2"
1213 ...
1214 SYNTAX INTEGER (0..10000)
1215
1216 suggests that a Hundredths value of 1234 be rendered as "12.34"
1217
1218
1219 When the syntax has an underlying primitive type of OCTET STRING, the
1220 hint consists of one or more octet-format specifications. Each
1221 specification consists of five parts, with each part using and
1222 removing zero or more of the next octets from the value and producing
1223 the next zero or more characters to be displayed. The octets within
1224 the value are processed in order of significance, most significant
1225 first.
1226
1227 The five parts of a octet-format specification are:
1228
1229(1) the (optional) repeat indicator; if present, this part is a `*',
1230 and indicates that the current octet of the value is to be used as
1231 the repeat count. The repeat count is an unsigned integer (which
1232 may be zero) which specifies how many times the remainder of this
1233 octet-format specification should be successively applied. If the
1234 repeat indicator is not present, the repeat count is one.
1235
1236
1237
1238McCloghrie, et al. Standards Track [Page 21]
1239\f
1240
1241
1242
1243
1244RFC 2579 Textual Conventions for SMIv2 April 1999
1245
1246
1247(2) the octet length: one or more decimal digits specifying the number
1248 of octets of the value to be used and formatted by this octet-
1249 specification. Note that the octet length can be zero. If less
1250 than this number of octets remain in the value, then the lesser
1251 number of octets are used.
1252
1253(3) the display format, either: `x' for hexadecimal, `d' for decimal,
1254 `o' for octal, `a' for ascii, or `t' for UTF-8. If the octet
1255 length part is greater than one, and the display format part refers
1256 to a numeric format, then network-byte ordering (big-endian
1257 encoding) is used interpreting the octets in the value. The octets
1258 processed by the `t' display format do not necessarily form an
1259 integral number of UTF-8 characters. Trailing octets which do not
1260 form a valid UTF-8 encoded character are discarded.
1261
1262(4) the (optional) display separator character; if present, this part
1263 is a single character which is produced for display after each
1264 application of this octet-specification; however, this character is
1265 not produced for display if it would be immediately followed by the
1266 display of the repeat terminator character for this octet-
1267 specification. This character can be any character other than a
1268 decimal digit and a `*'.
1269
1270(5) the (optional) repeat terminator character, which can be present
1271 only if the display separator character is present and this octet-
1272 specification begins with a repeat indicator; if present, this part
1273 is a single character which is produced after all the zero or more
1274 repeated applications (as given by the repeat count) of this
1275 octet-specification. This character can be any character other
1276 than a decimal digit and a `*'.
1277
1278 Output of a display separator character or a repeat terminator
1279 character is suppressed if it would occur as the last character of
1280 the display.
1281
1282 If the octets of the value are exhausted before all the octet-format
1283 specification have been used, then the excess specifications are
1284 ignored. If additional octets remain in the value after interpreting
1285 all the octet-format specifications, then the last octet-format
1286 specification is re-interpreted to process the additional octets,
1287 until no octets remain in the value.
1288
12893.2. Mapping of the STATUS clause
1290
1291 The STATUS clause, which must be present, indicates whether this
1292 definition is current or historic.
1293
1294 The value "current" means that the definition is current and valid.
1295
1296
1297McCloghrie, et al. Standards Track [Page 22]
1298\f
1299
1300
1301
1302
1303RFC 2579 Textual Conventions for SMIv2 April 1999
1304
1305
1306 The value "obsolete" means the definition is obsolete and should not
1307 be implemented and/or can be removed if previously implemented.
1308 While the value "deprecated" also indicates an obsolete definition,
1309 it permits new/continued implementation in order to foster
1310 interoperability with older/existing implementations.
1311
13123.3. Mapping of the DESCRIPTION clause
1313
1314 The DESCRIPTION clause, which must be present, contains a textual
1315 definition of the textual convention, which provides all semantic
1316 definitions necessary for implementation, and should embody any
1317 information which would otherwise be communicated in any ASN.1
1318 commentary annotations associated with the object.
1319
13203.4. Mapping of the REFERENCE clause
1321
1322 The REFERENCE clause, which need not be present, contains a textual
1323 cross-reference to some other document, either another information
1324 module which defines a related assignment, or some other document
1325 which provides additional information relevant to this definition.
1326
13273.5. Mapping of the SYNTAX clause
1328
1329 The SYNTAX clause, which must be present, defines abstract data
1330 structure corresponding to the textual convention. The data
1331 structure must be one of the alternatives defined in the ObjectSyntax
1332 CHOICE or the BITS construct (see section 7.1 in [2]). Note that
1333 this means that the SYNTAX clause of a Textual Convention can not
1334 refer to a previously defined Textual Convention.
1335
1336 An extended subset of the full capabilities of ASN.1 (1988) sub-
1337 typing is allowed, as appropriate to the underlying ASN.1 type. Any
1338 such restriction on size, range or enumerations specified in this
1339 clause represents the maximal level of support which makes "protocol
1340 sense". Restrictions on sub-typing are specified in detail in
1341 Section 9 and Appendix A of [2].
1342
13434. Sub-typing of Textual Conventions
1344
1345 The SYNTAX clause of a TEXTUAL CONVENTION macro may be sub-typed in
1346 the same way as the SYNTAX clause of an OBJECT-TYPE macro (see
1347 section 11 of [2]).
1348
13495. Revising a Textual Convention Definition
1350
1351 It may be desirable to revise the definition of a textual convention
1352 after experience is gained with it. However, changes are not allowed
1353 if they have any potential to cause interoperability problems "over
1354
1355
1356McCloghrie, et al. Standards Track [Page 23]
1357\f
1358
1359
1360
1361
1362RFC 2579 Textual Conventions for SMIv2 April 1999
1363
1364
1365 the wire" between an implementation using an original specification
1366 and an implementation using an updated specification(s). Such
1367 changes can only be accommodated by defining a new textual convention
1368 (i.e., a new name).
1369
1370 The following revisions are allowed:
1371
1372(1) A SYNTAX clause containing an enumerated INTEGER may have new
1373 enumerations added or existing labels changed. Similarly, named
1374 bits may be added or existing labels changed for the BITS
1375 construct.
1376
1377(2) A STATUS clause value of "current" may be revised as "deprecated"
1378 or "obsolete". Similarly, a STATUS clause value of "deprecated"
1379 may be revised as "obsolete". When making such a change, the
1380 DESCRIPTION clause should be updated to explain the rationale.
1381
1382(3) A REFERENCE clause may be added or updated.
1383
1384(4) A DISPLAY-HINTS clause may be added or updated.
1385
1386(5) Clarifications and additional information may be included in the
1387 DESCRIPTION clause.
1388
1389(6) Any editorial change.
1390
1391 Note that with the introduction of the TEXTUAL-CONVENTION macro,
1392 there is no longer any need to define types in the following manner:
1393
1394 DisplayString ::= OCTET STRING (SIZE (0..255))
1395
1396 When revising an information module containing a definition such as
1397 this, that definition should be replaced by a TEXTUAL-CONVENTION
1398 macro.
1399
14006. Security Considerations
1401
1402 This document defines the means to define new data types for the
1403 language used to write and read descriptions of management
1404 information. These data types have no security impact on the
1405 Internet.
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415McCloghrie, et al. Standards Track [Page 24]
1416\f
1417
1418
1419
1420
1421RFC 2579 Textual Conventions for SMIv2 April 1999
1422
1423
14247. Editors' Addresses
1425
1426 Keith McCloghrie
1427 Cisco Systems, Inc.
1428 170 West Tasman Drive
1429 San Jose, CA 95134-1706
1430 USA
1431 Phone: +1 408 526 5260
1432 EMail: kzm@cisco.com
1433
1434 David Perkins
1435 SNMPinfo
1436 3763 Benton Street
1437 Santa Clara, CA 95051
1438 USA
1439 Phone: +1 408 221-8702
1440 EMail: dperkins@snmpinfo.com
1441
1442 Juergen Schoenwaelder
1443 TU Braunschweig
1444 Bueltenweg 74/75
1445 38106 Braunschweig
1446 Germany
1447 Phone: +49 531 391-3283
1448 EMail: schoenw@ibr.cs.tu-bs.de
1449
1450
14518. References
1452
1453[1] Information processing systems - Open Systems Interconnection -
1454 Specification of Abstract Syntax Notation One (ASN.1),
1455 International Organization for Standardization. International
1456 Standard 8824, (December, 1987).
1457
1458[2] McCloghrie, K., Perkins, D., Schoenwaelder, J., Case, J., Rose, M.
1459 and S. Waldbusser, "Structure of Management Information Version 2
1460 (SMIv2)", STD 58, RFC 2578, April 1999.
1461
1462[3] The SNMPv2 Working Group, Case, J., McCloghrie, K., Rose, M. and
1463 Waldbusser, S., "Transport Mappings for Version 2 of the" Simple
1464 Network Management Protocol (SNMPv2)", RFC 1906, January 1996.
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474McCloghrie, et al. Standards Track [Page 25]
1475\f
1476
1477
1478
1479
1480RFC 2579 Textual Conventions for SMIv2 April 1999
1481
1482
14839. Full Copyright Statement
1484
1485 Copyright (C) The Internet Society (1999). All Rights Reserved.
1486
1487 This document and translations of it may be copied and furnished to
1488 others, and derivative works that comment on or otherwise explain it
1489 or assist in its implementation may be prepared, copied, published
1490 and distributed, in whole or in part, without restriction of any
1491 kind, provided that the above copyright notice and this paragraph are
1492 included on all such copies and derivative works. However, this
1493 document itself may not be modified in any way, such as by removing
1494 the copyright notice or references to the Internet Society or other
1495 Internet organizations, except as needed for the purpose of
1496 developing Internet standards in which case the procedures for
1497 copyrights defined in the Internet Standards process must be
1498 followed, or as required to translate it into languages other than
1499 English.
1500
1501 The limited permissions granted above are perpetual and will not be
1502 revoked by the Internet Society or its successors or assigns.
1503
1504 This document and the information contained herein is provided on an
1505 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
1506 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
1507 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
1508 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
1509 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE."
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533McCloghrie, et al. Standards Track [Page 26]
Unnamed repository; edit this file 'description' to name the repository.