]>
Commit | Line | Data |
---|---|---|
68b10830 MS |
1 | |
2 | ||
3 | ||
4 | ||
5 | ||
6 | ||
7 | ||
8 | Network Working Group Editors of this version: | |
9 | Request for Comments: 2579 K. McCloghrie | |
10 | STD: 58 Cisco Systems | |
11 | Obsoletes: 1903 D. Perkins | |
12 | Category: 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 | ||
30 | Status 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 | ||
38 | Copyright Notice | |
39 | ||
40 | Copyright (C) The Internet Society (1999). All Rights Reserved. | |
41 | ||
42 | ||
43 | Table 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 | ||
58 | McCloghrie, et al. Standards Track [Page 1] | |
59 | \f | |
60 | ||
61 | ||
62 | ||
63 | ||
64 | RFC 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 | ||
72 | 1. 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 | ||
96 | 1.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 | ||
104 | 2. Definitions | |
105 | ||
106 | SNMPv2-TC DEFINITIONS ::= BEGIN | |
107 | ||
108 | IMPORTS | |
109 | TimeTicks FROM SNMPv2-SMI; | |
110 | ||
111 | ||
112 | -- definition of textual conventions | |
113 | ||
114 | TEXTUAL-CONVENTION MACRO ::= | |
115 | ||
116 | ||
117 | McCloghrie, et al. Standards Track [Page 2] | |
118 | \f | |
119 | ||
120 | ||
121 | ||
122 | ||
123 | RFC 2579 Textual Conventions for SMIv2 April 1999 | |
124 | ||
125 | ||
126 | BEGIN | |
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 | ||
164 | END | |
165 | ||
166 | ||
167 | ||
168 | ||
169 | DisplayString ::= TEXTUAL-CONVENTION | |
170 | DISPLAY-HINT "255a" | |
171 | STATUS current | |
172 | DESCRIPTION | |
173 | "Represents textual information taken from the NVT ASCII | |
174 | ||
175 | ||
176 | McCloghrie, et al. Standards Track [Page 3] | |
177 | \f | |
178 | ||
179 | ||
180 | ||
181 | ||
182 | RFC 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 | ||
214 | PhysAddress ::= TEXTUAL-CONVENTION | |
215 | DISPLAY-HINT "1x:" | |
216 | STATUS current | |
217 | DESCRIPTION | |
218 | "Represents media- or physical-level addresses." | |
219 | SYNTAX OCTET STRING | |
220 | ||
221 | ||
222 | MacAddress ::= 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 | ||
235 | McCloghrie, et al. Standards Track [Page 4] | |
236 | \f | |
237 | ||
238 | ||
239 | ||
240 | ||
241 | RFC 2579 Textual Conventions for SMIv2 April 1999 | |
242 | ||
243 | ||
244 | TruthValue ::= TEXTUAL-CONVENTION | |
245 | STATUS current | |
246 | DESCRIPTION | |
247 | "Represents a boolean value." | |
248 | SYNTAX INTEGER { true(1), false(2) } | |
249 | ||
250 | TestAndIncr ::= 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 | ||
280 | AutonomousType ::= 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 | ||
290 | InstancePointer ::= TEXTUAL-CONVENTION | |
291 | STATUS obsolete | |
292 | ||
293 | ||
294 | McCloghrie, et al. Standards Track [Page 5] | |
295 | \f | |
296 | ||
297 | ||
298 | ||
299 | ||
300 | RFC 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 | ||
315 | VariablePointer ::= 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 | ||
323 | RowPointer ::= 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 | ||
335 | RowStatus ::= 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 | ||
353 | McCloghrie, et al. Standards Track [Page 6] | |
354 | \f | |
355 | ||
356 | ||
357 | ||
358 | ||
359 | RFC 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 | ||
412 | McCloghrie, et al. Standards Track [Page 7] | |
413 | \f | |
414 | ||
415 | ||
416 | ||
417 | ||
418 | RFC 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 | ||
471 | McCloghrie, et al. Standards Track [Page 8] | |
472 | \f | |
473 | ||
474 | ||
475 | ||
476 | ||
477 | RFC 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 | --------------+--------------+-----------+-------------+------------- | |
492 | set status |noError ->D|inconsist- |inconsistent-|inconsistent- | |
493 | column to | or | entValue| Value| Value | |
494 | createAndGo |inconsistent- | | | | |
495 | | Value| | | | |
496 | --------------+--------------+-----------+-------------+------------- | |
497 | set status |noError see 1|inconsist- |inconsistent-|inconsistent- | |
498 | column to | or | entValue| Value| Value | |
499 | createAndWait |wrongValue | | | | |
500 | --------------+--------------+-----------+-------------+------------- | |
501 | set status |inconsistent- |inconsist- |noError |noError | |
502 | column to | Value| entValue| | | |
503 | active | | | | | |
504 | | | or | | | |
505 | | | | | | |
506 | | |see 2 ->D|see 8 ->D| ->D | |
507 | --------------+--------------+-----------+-------------+------------- | |
508 | set status |inconsistent- |inconsist- |noError |noError ->C | |
509 | column to | Value| entValue| | | |
510 | notInService | | | | | |
511 | | | or | | or | |
512 | | | | | | |
513 | | |see 3 ->C| ->C|see 6 | |
514 | --------------+--------------+-----------+-------------+------------- | |
515 | set status |noError |noError |noError |noError ->A | |
516 | column to | | | | or | |
517 | destroy | ->A| ->A| ->A|see 7 | |
518 | --------------+--------------+-----------+-------------+------------- | |
519 | set any other |see 4 |noError |noError |see 5 | |
520 | column to some| | | | | |
521 | value | | 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 | ||
530 | McCloghrie, et al. Standards Track [Page 9] | |
531 | \f | |
532 | ||
533 | ||
534 | ||
535 | ||
536 | RFC 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 | ||
589 | McCloghrie, et al. Standards Track [Page 10] | |
590 | \f | |
591 | ||
592 | ||
593 | ||
594 | ||
595 | RFC 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 | ||
648 | McCloghrie, et al. Standards Track [Page 11] | |
649 | \f | |
650 | ||
651 | ||
652 | ||
653 | ||
654 | RFC 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 | ||
707 | McCloghrie, et al. Standards Track [Page 12] | |
708 | \f | |
709 | ||
710 | ||
711 | ||
712 | ||
713 | RFC 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 | ||
766 | McCloghrie, et al. Standards Track [Page 13] | |
767 | \f | |
768 | ||
769 | ||
770 | ||
771 | ||
772 | RFC 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 | ||
825 | McCloghrie, et al. Standards Track [Page 14] | |
826 | \f | |
827 | ||
828 | ||
829 | ||
830 | ||
831 | RFC 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 | ||
884 | McCloghrie, et al. Standards Track [Page 15] | |
885 | \f | |
886 | ||
887 | ||
888 | ||
889 | ||
890 | RFC 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 | ||
943 | McCloghrie, et al. Standards Track [Page 16] | |
944 | \f | |
945 | ||
946 | ||
947 | ||
948 | ||
949 | RFC 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 | ||
995 | TimeStamp ::= 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 | ||
1002 | McCloghrie, et al. Standards Track [Page 17] | |
1003 | \f | |
1004 | ||
1005 | ||
1006 | ||
1007 | ||
1008 | RFC 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 | ||
1025 | TimeInterval ::= 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 | ||
1031 | DateAndTime ::= 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 | ||
1061 | McCloghrie, et al. Standards Track [Page 18] | |
1062 | \f | |
1063 | ||
1064 | ||
1065 | ||
1066 | ||
1067 | RFC 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 | ||
1075 | StorageType ::= 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 | ||
1120 | McCloghrie, et al. Standards Track [Page 19] | |
1121 | \f | |
1122 | ||
1123 | ||
1124 | ||
1125 | ||
1126 | RFC 2579 Textual Conventions for SMIv2 April 1999 | |
1127 | ||
1128 | ||
1129 | TDomain ::= 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 | ||
1141 | TAddress ::= 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 | ||
1157 | END | |
1158 | ||
1159 | 3. 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 | ||
1179 | McCloghrie, et al. Standards Track [Page 20] | |
1180 | \f | |
1181 | ||
1182 | ||
1183 | ||
1184 | ||
1185 | RFC 2579 Textual Conventions for SMIv2 April 1999 | |
1186 | ||
1187 | ||
1188 | 3.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 | ||
1238 | McCloghrie, et al. Standards Track [Page 21] | |
1239 | \f | |
1240 | ||
1241 | ||
1242 | ||
1243 | ||
1244 | RFC 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 | ||
1289 | 3.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 | ||
1297 | McCloghrie, et al. Standards Track [Page 22] | |
1298 | \f | |
1299 | ||
1300 | ||
1301 | ||
1302 | ||
1303 | RFC 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 | ||
1312 | 3.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 | ||
1320 | 3.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 | ||
1327 | 3.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 | ||
1343 | 4. 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 | ||
1349 | 5. 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 | ||
1356 | McCloghrie, et al. Standards Track [Page 23] | |
1357 | \f | |
1358 | ||
1359 | ||
1360 | ||
1361 | ||
1362 | RFC 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 | ||
1400 | 6. 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 | ||
1415 | McCloghrie, et al. Standards Track [Page 24] | |
1416 | \f | |
1417 | ||
1418 | ||
1419 | ||
1420 | ||
1421 | RFC 2579 Textual Conventions for SMIv2 April 1999 | |
1422 | ||
1423 | ||
1424 | 7. 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 | ||
1451 | 8. 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 | ||
1474 | McCloghrie, et al. Standards Track [Page 25] | |
1475 | \f | |
1476 | ||
1477 | ||
1478 | ||
1479 | ||
1480 | RFC 2579 Textual Conventions for SMIv2 April 1999 | |
1481 | ||
1482 | ||
1483 | 9. 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 | ||
1533 | McCloghrie, et al. Standards Track [Page 26] |