idnits 2.17.1 draft-ietf-snmpv2-tc-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Cannot find the required boilerplate sections (Copyright, IPR, etc.) in this document. Expected boilerplate is as follows today (2024-04-19) according to https://trustee.ietf.org/license-info : IETF Trust Legal Provisions of 28-dec-2009, Section 6.a: This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 2: Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 3: This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing document type: Expected "INTERNET-DRAFT" in the upper left hand corner of the first page ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity. ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. ** Expected the document's filename to be given on the first page, but didn't find any == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an Abstract section. ** The document seems to lack an Introduction section. (A line matching the expected section header was found, but with an unexpected indentation: ' 2. Introduction' ) ** The document seems to lack a Security Considerations section. ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack an Authors' Addresses Section. ** There are 9 instances of too long lines in the document, the longest one being 3 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 355 has weird spacing: '... field octet...' == Couldn't figure out when the document was first submitted -- there may comments or warnings related to the use of a disclaimer for pre-RFC5378 work that could not be issued because of this. Please check the Legal Provisions document at https://trustee.ietf.org/license-info to determine if you need the pre-RFC5378 disclaimer. -- Couldn't find a document date in the document -- date freshness check skipped. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Missing reference section? '1' on line 570 looks like a reference -- Missing reference section? '2' on line 576 looks like a reference Summary: 14 errors (**), 0 flaws (~~), 3 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Draft Textual Conventions for SNMPv2 Oct 92 4 Textual Conventions 5 for version 2 of the 6 Simple Network Management Protocol (SNMPv2) 8 Thu Nov 12 08:51:15 1992 | 10 Jeffrey D. Case 11 SNMP Research, Inc. 12 University of Tennessee, Knoxville 13 case@cs.utk.edu 15 Keith McCloghrie 16 Hughes LAN Systems 17 kzm@hls.com 19 Marshall T. Rose 20 Dover Beach Consulting, Inc. 21 mrose@dbc.mtview.ca.us 23 Steven L. Waldbusser 24 Carnegie Mellon University 25 waldbusser@andrew.cmu.edu 27 1. Status of this Memo 29 This document is an Internet Draft. Internet Drafts are 30 working documents of the Internet Engineering Task Force 31 (IETF), its Areas, and its Working Groups. Note that other 32 groups may also distribute working documents as Internet 33 Drafts. 35 Internet Drafts are valid for a maximum of six months and may 36 be updated, replaced, or obsoleted by other documents at any 37 time. It is inappropriate to use Internet Drafts as reference 38 material or to cite them other than as a "work in progress". 40 Draft Textual Conventions for SNMPv2 Oct 92 42 2. Introduction 44 A network management system contains: several (potentially 45 many) nodes, each with management instrumentation termed an 46 agent; at least one management station; and, a management 47 protocol, which is used to convey management information 48 between the agents and management stations. Operations of the 49 management protocol are carried out under an administrative 50 framework which defines both authentication and authorization 51 policies. 53 Network management stations execute management applications 54 which monitor and control network elements. Network elements 55 are devices such as hosts, routers, terminal servers, etc., 56 which are monitored and controlled through access to their 57 management information. 59 Management information is viewed as a collection of managed 60 objects, residing in a virtual information store, termed the 61 Management Information Base (MIB). Collections of related 62 objects are defined in MIB modules. These modules are written 63 using a subset of OSI's Abstract Syntax Notation One (ASN.1) 64 [1], termed the Structure of Management Information (SMI) [2]. 66 When designing a MIB module, it is often useful to define 67 types, with a different name, but the same syntax, as one of 68 the types defined in the SMI. These are termed textual 69 conventions, and are used for the convenience of humans 70 reading the MIB module. It is the purpose of this document to 71 define the initial set of textual conventions available to all 72 MIB modules. 74 Objects defined using a textual convention are always encoded 75 by means of the rules that define their primitive type. 76 However, textual conventions often have special semantics 77 associated with them. As such, an ASN.1 macro, TEXTUAL- 78 CONVENTION, is used to concisely convey the syntax and 79 semantics of a textual convention. 81 For all textual conventions defined in an information module, 82 the name shall be unique and mnemonic, and shall not exceed 64 83 characters in length. All names used for the textual 84 conventions defined in all "standard" information modules 85 shall be unique. 87 Draft Textual Conventions for SNMPv2 Oct 92 89 2.1. A Note on Terminology 91 For the purpose of exposition, the original Internet-standard + 92 Network Management Framework, as described in RFCs 1155, 1157, + 93 and 1212, is termed the SNMP version 1 framework (SNMPv1). + 94 The current framework is termed the SNMP version 2 framework + 95 (SNMPv2). + 96 Draft Textual Conventions for SNMPv2 Oct 92 98 3. Definitions 100 SNMPv2-TC DEFINITIONS ::= BEGIN 102 IMPORTS 103 ObjectSyntax, Integer32, TimeTicks 104 FROM SNMPv2-SMI; 106 -- definition of textual conventions 108 TEXTUAL-CONVENTION MACRO ::= 109 BEGIN 110 TYPE NOTATION ::= 111 DisplayPart 112 "STATUS" Status 113 "DESCRIPTION" value(description Text) 114 ReferPart 116 VALUE NOTATION ::= 117 type(VALUE ObjectSyntax) 119 DisplayPart ::= 120 "DISPLAY-HINT" value(display Text) 121 | empty 123 Status ::= 124 "current" 125 | "deprecated" 126 | "obsolete" 128 ReferPart ::= 129 "REFERENCE" value(reference Text) 130 | empty 132 -- uses the NVT ASCII character set 133 Text ::= OCTET STRING 134 END 136 DisplayString TEXTUAL-CONVENTION 137 DISPLAY-HINT "255a" 138 STATUS current 139 DESCRIPTION 140 "Represents textual information taken from the NVT 142 Draft Textual Conventions for SNMPv2 Oct 92 144 ASCII character set, as defined in pages 4, 10-11 145 of RFC 854. Any object defined using this syntax 146 may not exceed 255 characters in length." 147 ::= OCTET STRING 149 PhysAddress TEXTUAL-CONVENTION 150 DISPLAY-HINT "1x:" 151 STATUS current 152 DESCRIPTION 153 "Represents media- or physical-level addresses." 154 ::= OCTET STRING 156 MacAddress TEXTUAL-CONVENTION 157 DISPLAY-HINT "1x:" 158 STATUS current 159 DESCRIPTION 160 "Represents an 802 MAC address represented in the 161 `canonical' order defined by IEEE 802.1a, i.e., as 162 if it were transmitted least significant bit 163 first, even though 802.5 (in contrast to other 164 802.x protocols) requires MAC addresses to be 165 transmitted most significant bit first." 166 ::= OCTET STRING (SIZE (6)) 168 TruthValue TEXTUAL-CONVENTION 169 STATUS current 170 DESCRIPTION 171 "Represents a boolean value." 172 ::= INTEGER { true(1), false(2) } 174 TestAndIncr TEXTUAL-CONVENTION 175 STATUS current 176 DESCRIPTION 177 "Represents integer-valued information used for 178 atomic operations. When the management protocol 179 is used to specify that an object instance having 180 this syntax is to be modified, the new value 181 supplied via the management protocol must 182 precisely match the value presently held by the 183 instance. If not, the management protocol set 184 operation fails with an error of 186 Draft Textual Conventions for SNMPv2 Oct 92 188 `inconsistentValue'. Otherwise, if the current 189 value is the maximum value of 2^31-1 (2147483647 190 decimal), then the value held by the instance is 191 wrapped to zero; otherwise, the value held by the 192 instance is incremented by one. (Note that 193 regardless of whether the management protocol set 194 operation succeeds, the variable-binding in the 195 request and response PDUs are identical.) 197 The value of the ACCESS clause for objects having 198 this syntax is either `read-write' or `read- 199 create'. When an instance of a columnar object 200 having this syntax is created, any value may be 201 supplied via the management protocol." 202 ::= INTEGER (0..2147483647) 204 AutonomousType TEXTUAL-CONVENTION 205 STATUS current 206 DESCRIPTION 207 "Represents an independently extensible type 208 identification value. It may, for example, 209 indicate a particular sub-tree with further MIB 210 definitions, or define a particular type of 211 protocol or hardware." 212 ::= OBJECT IDENTIFIER 214 InstancePointer TEXTUAL-CONVENTION 215 STATUS current 216 DESCRIPTION 217 "A pointer to a specific instance of a conceptual 218 row of a MIB table in the managed device. By 219 convention, it is the name of the particular 220 instance of the first columnar object in the 221 conceptual row." 222 ::= OBJECT IDENTIFIER 224 RowStatus TEXTUAL-CONVENTION 225 STATUS current 226 DESCRIPTION 227 "The syntax used for the status column for a 228 conceptual row. If present, the value of the 229 DEFVAL clause for an object having this syntax is 231 Draft Textual Conventions for SNMPv2 Oct 92 233 either `underModification(4)' or `active(1)'. 235 To create new object instances for a conceptual 236 row, a management protocol set operation is issued 237 which sets the new instance of the status column 238 to `underConstruction(2)'. If the instance 239 already exists, then the management protocol set 240 operation fails with an error of 241 `inconsistentValue'. Otherwise, the instance is 242 created. If the management protocol set operation 243 created sufficient instances so that this 244 conceptual row may be used by the correspondent 245 SNMPv2 entity, and the value of the DEFVAL clause 246 for the status column is `active(1)', then the 247 SNMPv2 entity acting in an agent role immediately 248 sets the value of this instance to `active(1)'. 249 Otherwise, the SNMPv2 entity acting in an agent 250 role immediately sets the value of this instance 251 to `underModification(4)'. 253 This suggests that the algorithm to create a new 254 conceptual row is as follows: 256 First, the management station ascertains the 257 identity of an unused slot in the conceptual 258 table of interest. 260 Second, the management station issues a 261 management protocol set operation to create 262 the status column for the desired conceptual 263 row. 265 Third, the management station issues a 266 management protocol get operation to examine 267 all columns in that conceptual row. For each 268 column, if the get operation returns a value 269 for that column, then the management station 270 may issue an additional management protocol 271 set operation to change that value; if the 272 `noSuchInstance' exception is returned, then 273 the management station must issue an 274 additional management protocol set operation 275 to create that instance prior to changing the 276 status column to `active'; and, if the 277 `noSuchObject' exception is returned, then 279 Draft Textual Conventions for SNMPv2 Oct 92 281 the management station learns that it must 282 not issue a management protocol set operation 283 to create an instance of this column. 285 When an instance of the status column has the 286 value `underModification(4)' or `active(1)', then 287 management operations may be issued to manipulate 288 the columns in the conceptual row. However, only 289 when the value of an instance of the status column 290 is `active(1)', will the information in the 291 conceptual row be available outside of the 292 management subsystem, i.e., whilst the information 293 is available to authorized SNMPv2 entities acting 294 in a manager role, the information is independent 295 of the operational state of the managed device. 296 As such, note that while the status is 297 `underModification(4)', it is possible for a 298 managed device to create (or otherwise manipulate) 299 its own instances which effectively supersede 300 those held by the SNMPv2 entity acting in an agent 301 role. If the management station doesn't finish 302 this algorithm (due to a management station or 303 network failure, for example) conceptual rows may 304 be left in the `underModification(4)' state, 305 consuming resources indefinitely. The SNMPv2 306 entity acting in an agent role may detect 307 conceptual rows that have been in the 308 `underModification(4) state for an abnormally long 309 period of time and remove them from the table. 310 This period of time should be long enough to allow 311 for human response time (including `think time') 312 between the creation of the conceptual row and the 313 setting of the status to `active(1)'. It is 314 suggested that this period be approximately 5 315 minutes in length. 317 For deletion of conceptual rows, a management 318 protocol set operation is issued which sets the 319 instance of the status column to 320 `underDestruction(3)'. If the operation succeeds, 321 then the entire conceptual row is immediately 322 removed from the table." 323 ::= INTEGER { 324 active(1) 325 underConstruction(2), 327 Draft Textual Conventions for SNMPv2 Oct 92 329 underDestruction(3), 330 underModification(4), 331 } 333 TimeStamp TEXTUAL-CONVENTION 334 STATUS current 335 DESCRIPTION 336 "The value of MIB-II's sysUpTime object at which a 337 specific occurrence happened. The specific 338 occurrence must be defined in the description of 339 any object defined using this type." 340 ::= TimeTicks 342 TimeInterval TEXTUAL-CONVENTION 343 STATUS current 344 DESCRIPTION 345 "A period of time, measured in units of 0.01 346 seconds." 347 ::= INTEGER (0..2147483647) 349 DateAndTime TEXTUAL-CONVENTION 350 DISPLAY-HINT "2d-1d-1d,1d:1d:1d.1d,1a1d:1d" 351 STATUS current 352 DESCRIPTION 353 "A date-time specification. 355 field octets contents range 356 ----- ------ -------- ----- 357 1 1-2 year 0..65536 358 2 3 month 1..12 359 3 4 day 1..31 360 4 5 hour 0..23 361 5 6 minutes 0..59 362 6 7 seconds 0..60 363 (use 60 for leap-second) 364 7 8 deci-seconds 0..9 365 8 9 direction from UTC '+' / '-' | 366 9 10 hours from UTC 0..11 | 367 10 11 minutes from UTC 0..59 | 369 For example, Tuesday May 26, 1992 at 1:30:15 PM 370 EDT would be displayed as: 372 1992-5-26,13:30:15.0,-4:0 374 Draft Textual Conventions for SNMPv2 Oct 92 376 Note that if only local time is known, then 377 timezone information (fields 8-10) is not present. 378 " 379 ::= OCTET STRING (SIZE (8 | 11)) 381 END 382 Draft Textual Conventions for SNMPv2 Oct 92 384 4. Mapping of the TEXTUAL-CONVENTION macro 386 The TEXTUAL-CONVENTION macro is used to convey the syntax and 387 semantics associated with a textual convention. It should be 388 noted that the expansion of the TEXTUAL-CONVENTION macro is 389 something which conceptually happens during implementation and 390 not during run-time. 392 4.1. Mapping of the DISPLAY-HINT clause 394 The DISPLAY-HINT clause, which need not be present, gives a 395 hint as to how the value of an instance of an object with the 396 syntax defined using this textual convention might be 397 displayed. The DISPLAY-HINT clause may only be present when 398 the syntax has an underlying primitive type of INTEGER or 399 OCTET STRING. 401 When the syntax has an underlying primitive type of INTEGER, 402 the hint consists of a single character suggesting a display 403 format, either: `x' for hexadecimal, `d' for decimal, or `o' 404 for octal, or `b' for binary. 406 When the syntax has an underlying primitive type of OCTET 407 STRING, the hint consists of one or more octet-format 408 specifications. Each specification consists of five parts, 409 with each part using and removing zero or more of the next 410 octets from the value and producing the next zero or more 411 characters to be displayed. The octets within the value are 412 processed in order of significance, most significant first. 414 The five parts of a octet-format specification are: 416 (1) the (optional) repeat indicator; if present, this part is 417 a `*', and indicates that the current octet of the value 418 is to be used as the repeat count. The repeat count is 419 an unsigned integer (which may be zero) which specifies 420 how many times the remainder of this octet-format 421 specification should be successively applied. If the 422 repeat indicator is not present, the repeat count is one. 424 (2) the octet length: one or more decimal digits specifying 425 the number of octets of the value to be used and 426 formatted by this octet-specification. Note that the 427 octet length can be zero. If less than this number of 429 Draft Textual Conventions for SNMPv2 Oct 92 431 octets remain in the value, then the lesser number of 432 octets are used. 434 (3) the display format, either: `x' for hexadecimal, `d' for 435 decimal, `o' for octal, or `a' for ascii. If the octet 436 length part is greater than one, and the display format 437 part refers to a numeric format, then network-byte 438 ordering (big-endian encoding) is used interpreting the 439 octets in the value. 441 (4) the (optional) display separator character; if present, 442 this part is a single character which is produced for 443 display after each application of this octet- 444 specification; however, this character is not produced 445 for display if it would be immediately followed by the 446 display of the repeat terminator character for this 447 octet-specification. This character can be any character 448 other than a decimal digit and a `*'. 450 (5) the (optional) repeat terminator character, which can be 451 present only if the display separator character is 452 present and this octet-specification begins with a repeat 453 indicator; if present, this part is a single character 454 which is produced after all the zero or more repeated 455 applications (as given by the repeat count) of this 456 octet-specification. This character can be any character 457 other than a decimal digit and a `*'. 459 Output of a display separator character or a repeat terminator 460 character is suppressed if it would occur as the last 461 character of the display. 463 If the octets of the value are exhausted before all the 464 octet-format specification have been used, then the excess 465 specifications are ignored. If additional octets remain in 466 the value after interpreting all the octet-format 467 specifications, then the last octet-format specification is 468 re-interpreted to process the additional octets, until no 469 octets remain in the value. 471 4.2. Mapping of the STATUS clause 473 The STATUS clause, which must be present, indicates whether 474 this definition is current or historic. 476 Draft Textual Conventions for SNMPv2 Oct 92 478 The values "current", and "obsolete" are self-explanatory. 479 The "deprecated" value indicates that that object is obsolete, 480 but that an implementor may wish to support that object to 481 foster interoperability with older implementations. 483 4.3. Mapping of the DESCRIPTION clause 485 The DESCRIPTION clause, which must be present, contains a 486 textual definition of the textual convention, which provides 487 all semantic definitions necessary for implementation, and 488 should embody any information which would otherwise be 489 communicated in any ASN.1 commentary annotations associated 490 with the object. 492 Note that, in order to conform to the ASN.1 syntax, the entire 493 value of this clause must be enclosed in double quotation 494 marks, and therefore cannot itself contain double quotation 495 marks, although the value may be multi-line. 497 4.4. Mapping of the REFERENCE clause 499 The REFERENCE clause, which need not be present, contains a 500 textual cross-reference to a related item defined in some 501 other published work. 503 4.5. Mapping of the TEXTUAL-CONVENTION value 505 The value of an invocation of the TEXTUAL-CONVENTION macro 506 defines the abstract data structure corresponding to the 507 textual convention. The data structure must be one of the 508 alternatives defined in the ObjectSyntax CHOICE from [2], a 509 refinement of one of the alternatives, or the value of a 510 previously defined TEXTUAL-CONVENTION. Consult Section 11 of 511 [2] for more information on refined syntax. 513 Draft Textual Conventions for SNMPv2 Oct 92 515 5. Acknowledgements 517 PhysAddress (and textual conventions) originated in RFC 1213. 519 MacAddress originated in RFCs 1230 and 1231. 521 TruthValue originated in RFC 1253. 523 AutonomousType and InstancePointer originated in RFC 1316. 525 RowStatus originated in RFC 1271. 527 Finally, the comments of the SNMP Version 2 working group are 528 gratefully acknowledged: 530 Steve Alexander, Interactive Systems 531 Uri Blumenthal, International Business Machines 532 Jeffrey D. Case, SNMP Research, Inc. 533 Tracy Cox, Bellcore 534 James R. (Chuck) Davin, Bellcore 535 Mike Davison, FiberCom 536 Taso N. Devetzis, Bellcore 537 Gary W. Haney, Martin Marietta Energy Systems 538 Matt Hecht, SNMP Research, Inc. 539 Susan E. Hicks, Martin Marietta Energy Systems 540 Satish Joshi, SynOptics 541 Mark Kepke, Hewlett-Packard 542 Ken Key, SNMP Research, Inc. 543 Michael Kornegay, Visisoft 544 Deidre C. Kostick, Bellcore 545 Cheryl Krupczak, Georgia Tech 546 Robert C. Lushbaugh, Martin Marietta Energy Systems 547 Keith McCloghrie, Hughes LAN Systems 548 Dave Minnich, FiberCom 549 Dave Perkins, SynOptics 550 Marshall T. Rose, Dover Beach Consulting, Inc. 551 Shawn A. Routhier, Epilogue Technology 552 Jon Saperia, Digital Equipment Corporation 553 Bob Stewart, Xyplex (chair) 554 Robert Synder, Cisco Systems 555 Maurice Turcotte, Racal Datacom 556 Steven L. Waldbusser, Carnegie Mellon University 557 Bert Wijnen, International Business Machines 558 Peter Wilson, 3Com 559 Steven Wong, Digital Equipment Corporation 561 Draft Textual Conventions for SNMPv2 Oct 92 563 Chris Young, Cabletron 564 Kiho Yum, 3Com 566 Draft Textual Conventions for SNMPv2 Oct 92 568 6. References 570 [1] Information processing systems - Open Systems 571 Interconnection - Specification of Abstract Syntax 572 Notation One (ASN.1), International Organization for 573 Standardization. International Standard 8824, (December, 574 1987). 576 [2] J.D. Case, K. McCloghrie, M.T. Rose, S.L. Waldbusser, 577 Structure of Management Information for version 2 of the 578 Simple Network Management Protocol, Internet-Draft, 579 (October 7, 1992). 581 Draft Textual Conventions for SNMPv2 Oct 92 583 Table of Contents 585 1 Status of this Memo ................................... 1 586 2 Introduction .......................................... 2 587 2.1 A Note on Terminology ............................... 3 588 3 Definitions ........................................... 4 589 4 Mapping of the TEXTUAL-CONVENTION macro ............... 11 590 4.1 Mapping of the DISPLAY-HINT clause .................. 11 591 4.2 Mapping of the STATUS clause ........................ 12 592 4.3 Mapping of the DESCRIPTION clause ................... 13 593 4.4 Mapping of the REFERENCE clause ..................... 13 594 4.5 Mapping of the TEXTUAL-CONVENTION value ............. 13 595 5 Acknowledgements ...................................... 14 596 6 References ............................................ 16