idnits 2.17.1 draft-irtf-nmrg-smi-ops-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. == 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 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 separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Line 502 has weird spacing: '...for the purpo...' -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (October 1999) is 8960 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Unused Reference: 'RFC2579' is defined on line 486, but no explicit reference was found in the text -- Possible downref: Non-RFC (?) normative reference: ref. 'ASN1' ** Obsolete normative reference: RFC 2575 (Obsoleted by RFC 3415) Summary: 5 errors (**), 0 flaws (~~), 4 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Network Working Group J. Schoenwaelder 2 Internet-Draft TU Braunschweig 3 Expires April 2000 22. October 1999 5 Operation-Types for SMIv2 7 9 Status of this Memo 11 This document is an Internet-Draft and is in full conformance with 12 all provisions of Section 10 of RFC 2026. Internet-Drafts are 13 working documents of the Internet Engineering Task Force (IETF), its 14 areas, and its working groups. Note that other groups may also 15 distribute working documents as Internet-Drafts. 17 Internet-Drafts are draft documents valid for a maximum of six months 18 and may be updated, replaced, or obsoleted by other documents at any 19 time. It is inappropriate to use Internet-Drafts as reference 20 material or to cite them other than as "work in progress." 22 The list of current Internet-Drafts can be accessed at 23 http://www.ietf.org/ietf/1id-abstracts.txt 25 The list of Internet-Draft Shadow Directories can be accessed at 26 http://www.ietf.org/shadow.html 28 Distribution of this document is unlimited. 30 Copyright Notice 32 Copyright (C) The Internet Society (1999). All Rights Reserved. 34 Abstract 36 This document defines an extension for the SMIv2 which allows to 37 define operations. Operations can among other things be used to 38 define install/remove operations on conceptual MIB tables. This can 39 result in simpler and more efficient implementations of configuration 40 management systems. 42 Warning 44 This document has not been written in order to specify a solution. 45 Instead, this document has been written to stimulate (controversial) 46 discussions within the NMRG (and elsewhere). 48 Table of Contents 50 1 Introduction ................................................. 3 51 2 Definitions .................................................. 4 52 3 Mapping of the OPERATION-TYPE macro .......................... 5 53 3.1 Mapping of the ARGUMENTS clause ............................ 6 54 3.2 Mapping of the ERRORS clause ............................... 6 55 3.3 Mapping of the RESULTS clause .............................. 6 56 3.4 Mapping of the CREATES clause .............................. 6 57 3.5 Mapping of the DELETES clause .............................. 7 58 3.6 Mapping of the STATUS clause ............................... 7 59 3.7 Mapping of the DESCRIPTION clause .......................... 7 60 3.8 Mapping of the REFERENCE clause ............................ 7 61 3.9 Mapping of the OPERATION-TYPE value ........................ 8 62 3.10 Usage Examples ............................................ 9 63 4 Revising Operation Type Definitions .......................... 10 64 5 Open Issues .................................................. 11 65 6 Security Considerations ...................................... 12 66 7 Authors' Address ............................................. 12 67 8 References ................................................... 12 68 9 Full Copyright Statement ..................................... 13 70 1. Introduction 72 Management information is viewed as a collection of managed objects, 73 residing in a virtual information store, termed the Management 74 Information Base (MIB). Collections of related objects are defined 75 in MIB modules. These modules are written using an adapted subset of 76 OSI's Abstract Syntax Notation One, ASN.1 (1988) [ASN1], termed the 77 Structure of Management Information (SMI) [RFC2578]. 79 When designing a MIB module, it is often useful to define operations 80 on collections of related objects. Operations go beyond what is 81 available with normal read and write access to individual objects: 83 - Operations have a defined name which makes it easier to communicate 84 complex operations on MIB objects. 86 - Operations have well defined input and output parameters with 87 ordering constraints which reduces variability and simplifies 88 implementations. 90 - Operations can raise operation specific errors during their 91 invocation. 93 - Operations define whether they create or delete rows in conceptual 94 tables. 96 - The defined signatures of operations allow to implement tools that 97 generate APIs and stub procedures for command responder as well as 98 command generator applications. 100 Operations can be defined on arbitrary collections of objects. 101 However, it is expected that operations will normally be defined only 102 on closely related objects (e.g. objects contained in a single 103 conceptual row) since this simplifies implementation in extensible 104 agent environments. 106 2. Definitions 108 SNMPv2-OPS DEFINITIONS ::= BEGIN 110 IMPORTS ObjectName FROM SNMPv2-SMI; 112 OPERATION-TYPE MACRO ::= 113 BEGIN 114 TYPE NOTATION ::= 115 ArgumentsPart 116 ErrorsPart 117 ResultsPart 118 CreatesPart 119 DeletesPart 120 "STATUS" Status 121 "DESCRIPTION" Text 122 ReferPart 124 VALUE NOTATION ::= 125 value(VALUE ObjectName) 127 ArgumentsPart ::= 128 "ARGUMENTS" "{" Parameters "}" 129 | empty 131 ErrorsPart ::= 132 "ERRORS" "{" NamedNumbers "}" -- INTEGER enumerations 133 | empty 135 ResultsPart ::= 136 "RESULTS" "{" Parameters "}" 137 | empty 139 CreatesPart ::= 140 "CREATES" "{" Rows "}" 141 | empty 143 DeletesPart ::= 144 "DELETES" "{" Rows "}" 145 | empty 147 Parameters ::= 148 Parameter 149 | Parameters "," Parameter 151 Parameter ::= 152 identifier Syntax 154 Syntax ::= 155 type 157 | "BITS" "{" NamedBits "}" 159 NamedBits ::= 160 NamedBit 161 | NamedBits "," NamedBit 163 NamedBit ::= 164 identifier "(" number ")" -- number is nonnegative 166 NamedNumbers ::= 167 NamedNumber 168 | NamedNumbers "," NamedNumber 170 NamedNumber ::= 171 identifier "(" number ")" 173 Rows ::= 174 Row 175 | Rows "," Row 176 Row ::= 177 value(ObjectName) 179 Status ::= 180 "current" 181 | "deprecated" 182 | "obsolete" 184 ReferPart ::= 185 "REFERENCE" Text 186 | empty 188 -- a character string as defined in [RFC2578] 189 Text ::= value(IA5String) 190 END 191 END 193 3. Mapping of the OPERATION-TYPE macro 195 The OPERATION-TYPE macro is used to define an operation. An operation 196 has a defined signature which consists of the operation name, the 197 types and names of the arguments, the types and names of the results 198 and the operation specific errors that can occur while invoking the 199 operation. Operations can create or delete rows in conceptual tables. 200 The optional CREATES and DELETES clauses of the OPERATION-TYPE macro 201 identify the tables in which rows are created or deleted. It should 202 be noted that the expansion of the OPERATION-TYPE macro is something 203 which conceptually happens during implementation and not during run- 204 time. 206 3.1. Mapping of the ARGUMENTS clause 208 The ARGUMENTS clause, which need not be present, defines an ordered 209 sequence of the types and names that form the arguments of the 210 operation. The operation's DESCRIPTION clause must specify the 211 information/meaning conveyed by each argument listed in the ARGUMENTS 212 clause. 214 The name of an argument must consist of one or more letters or 215 digits, and its initial character must be a lower-case letter. 216 Argument names must be unique across all arguments and results 217 defined in a single invocation of an OPERATION-TYPE macro. 219 3.2. Mapping of the ERRORS clause 221 The ERRORS clause, which need not be present, defines the operation 222 specific errors that can occur while invoking the operation. Errors 223 are represented as integer-valued named-number enumerations. Note 224 that although it is recommended that error values start at 1 and be 225 numbered contiguously, any valid value for an INTEGER in the range (1 226 to 2147483647 decimal) is allowed for an error value and, further, 227 error values need not be contiguously assigned. The no error case 228 does not need to be enumerated. 230 A label for a named-number enumeration within the ERRORS clause must 231 consist of one or more letters or digits, up to a maximum of 64 232 characters, and the initial character must be a lower-case letter. 233 (However, labels longer than 32 characters are not recommended.) 234 Note that hyphens are not allowed. 236 3.3. Mapping of the RESULTS clause 238 The RESULTS clause, which need not be present, defines an ordered 239 sequence of the types and names that form the results of the 240 operation. The operation's DESCRIPTION clause must specify the 241 information/meaning conveyed by each result listed in the RESULTS 242 clause. 244 The name of a result parameter must consist of one or more letters or 245 digits, and its initial character must be a lower-case letter. Result 246 names must be unique across all arguments and results defined in a 247 single invocation of an OPERATION-TYPE macro. 249 3.4. Mapping of the CREATES clause 251 The CREATES clause, which need not be present, defines the conceptual 252 table rows that will be created by invoking the operation. Rows are 253 identified by the descriptor which refers to a conceptual row, i.e. 254 has a syntax which resolves to a SEQUENCE containing columnar 255 objects. The operation's DESCRIPTION clause must specify how an 256 implementation determines the instance identifier(s) of the row(s) 257 created by the operation. 259 3.5. Mapping of the DELETES clause 261 The DELETES clause, which need not be present, defines the conceptual 262 table rows that will be deleted by invoking the operation. Rows are 263 identified by the descriptor which refers to a conceptual row, i.e. 264 has a syntax which resolves to a SEQUENCE containing columnar 265 objects. The operation's DESCRIPTION clause must specify how an 266 implementation determines the instance identifier(s) of the row(s) 267 deleted by the operation. 269 3.6. Mapping of the STATUS clause 271 The STATUS clause, which must be present, indicates whether this 272 definition is current or historic. 274 The value "current" means that the definition is current and valid. 275 The value "obsolete" means the definition is obsolete and should not 276 be implemented and/or can be removed if previously implemented. 277 While the value "deprecated" also indicates an obsolete definition, 278 it permits new/continued implementation in order to foster 279 interoperability with older/existing implementations. 281 3.7. Mapping of the DESCRIPTION clause 283 The DESCRIPTION clause, which must be present, contains a textual 284 definition of the operation type which provides all semantic 285 definitions necessary for implementation and use, and should embody 286 any information which would otherwise be communicated in any ASN.1 287 commentary annotations associated with the object. 289 3.8. Mapping of the REFERENCE clause 291 The REFERENCE clause, which need not be present, contains a textual 292 cross-reference to some other document, either another information 293 module or some other document which provides additional information 294 relevant to this definition. 296 3.9. Mapping of the OPERATION-TYPE value 298 The value of an invocation of the OPERATION-TYPE macro is the name of 299 the operation type, which is an OBJECT IDENTIFIER, an 300 administratively assigned name. 302 3.10. Usage Examples 304 The first example shows an operation which creates or allocates a new 305 entry in the vacmSecurityToGroupTable [RFC2575]. 307 vacmCreateSTGEntry OPERATION-TYPE 308 ARGUMENTS { 309 securityModel SnmpSecurityModel (1..2147483647), 310 securityName SnmpAdminString (SIZE(1..32)), 311 groupName SnmpAdminString (SIZE(1..32)), 312 storageType StorageType { 313 volatile(2), 314 nonVolatile(3) 315 } 316 } 317 ERRORS { rowAlreadyExists(1) } 318 CREATES { vacmSecurityToGroupEntry } 319 DESCRIPTION 320 "This operation installs and activates a new entry in 321 the vacmSecurityToGroupTable. The new entry is identified 322 by the securityModel and securityName parameters. 324 Implementations that do not support the creation of 325 new rows but which have permanent rows that are 326 currently notInService are expected to allocate 327 and activate one of these notInService rows. The 328 value of the storageType parameter is ignored in 329 this case. 331 The rowAlreadyExists(1) error is returned if the row 332 identified by securityModel and securityName already 333 exists." 334 ::= { vacmOperations 1 } 336 The second example shows the definition of an operation that can be 337 used to remove a row from the vacmSecurityToGroupTable. 339 vacmRemoveSTGEntry OPERATION-TYPE 340 ARGUMENTS { 341 securityModel SnmpSecurityModel (1..2147483647), 342 securityName SnmpAdminString (SIZE(1..32)) 343 } 344 ERRORS { rowDoesNotExist(1), readOnlyStorageType(2) } 345 DELETES { vacmSecurityToGroupEntry } 346 DESCRIPTION 347 "This operation removes an entry identified by the 348 securityModel and securityName parameters from the 349 vacmSecurityToGroupTable. 351 Entries which can not be removed (e.g. the value 352 of vacmSecurityToGroupStorageType is permanent) 353 will be disabled by changing the RowStatus column 354 vacmSecurityToGroupStatus to notInService. 356 The rowDoesNotExist(1) error is returned if the row 357 identified by the securityModel and securityName parameters 358 does not exist. The readOnlyStorageType(2) error is returned 359 if the row cannot be removed or disabled since it is stored 360 in ROM." 361 ::= { vacmOperations 2 } 363 The third example shows the definition of an operation which deletes 364 zero or more entries from the vacmSecurityToGroupTable. The argument 365 of the operation contains a pattern which is matched against all 366 vacmGroupName instances. 368 vacmRemoveSTGEntryByGroupName OPERATION-TYPE 369 ARGUMENTS { 370 pattern SnmpAdminString (SIZE(1..32)) 371 } 372 RESULTS { numberRemoved Unsigned32 } 373 DELETES { vacmSecurityToGroupEntry } 374 DESCRIPTION 375 "This operation removes all entries from the 376 vacmSecurityToGroupTable where the vacmGroupName 377 matches the pattern parameter. The comparison is an 378 exact match where each byte must match exactly (no 379 wildcarding). 381 Entries that can not be removed (e.g. the value 382 of vacmSecurityToGroupStorageType is permanent) 383 will be disabled by changing the RowStatus column 384 vacmSecurityToGroupStatus to notInService. 386 Entries that can not be disabled (e.g. the value 387 of vacmSecurityToGroupStorageType is readOnly) 388 will be ignored. 390 The operation returns the number of entries that 391 were actually removed from or disabled in the 392 vacmSecurityToGroupTable." 393 ::= { vacmOperations 3 } 395 4. Revising Operation Type Definitions 397 An operation definition may be revised in any of the following ways: 399 (1) The ERRORS clause may have new enumerations added. 401 (2) A STATUS clause value of "current" may be revised as 402 "deprecated" or "obsolete". Similarly, a STATUS clause value of 403 "deprecated" may be revised as "obsolete". When making such a 404 change, the DESCRIPTION clause should be updated to explain the 405 rationale. 407 (3) A REFERENCE clause may be added or updated. 409 (4) Clarifications and additional information may be included in the 410 DESCRIPTION clause. 412 (5) Entirely new operations may be defined, named with previously 413 unassigned OBJECT IDENTIFIER values. 415 Otherwise, if the semantics of any previously defined operation are 416 changed (i.e., if a non-editorial change is made to any clause other 417 than those specifically allowed above), then the OBJECT IDENTIFIER 418 value associated with that operation must also be changed. 420 Note that changing the descriptor associated with an existing 421 operation is considered a semantic change, as these strings may be 422 used in fielded implementations and APIs derived from the operation 423 type definition. 425 5. Open Issues 427 1. The current version supports three different ways to define a 428 parameter. There are valid reasons for all three alternatives. 430 First, there is a need to have input parameters for operations 431 that do not exactly match an existing object. It would be a 432 burdon to require that all parameters be defined as objects 433 since many would end up with a write-only access (which does not 434 exist) anyway. 436 Second, there is a need to refer to types that are implicitely 437 defined as part of an object definition. A good example is 438 ifAdminStatus, which is an implicitly defined enumeration 439 without a proper name. 441 Third, it is necessary to assign names to parameters in order to 442 solve problems when a single type of implicit type shows up in a 443 arguments or result clause more than once. 445 2. It is currently not allowed to return vectors as a result. There 446 are several issues to consider in this case. The most important 447 reason to allow vectors is that you can have an operation which 448 itself returns a sequence of operations to recreate the current 449 state. But the details how this would work are not yet fully 450 worked out. 452 6. Security Considerations 454 This document defines the means to define operations on collections 455 of MIB objects. The definition of operations has no direct security 456 impact on the Internet. 458 7. Authors' Address 460 Juergen Schoenwaelder 461 TU Braunschweig 462 Bueltenweg 74/75 463 38106 Braunschweig 464 Germany 466 Phone: +49 531 391-3283 467 EMail: schoenw@ibr.cs.tu-bs.de 469 8. References 471 [ASN1] Information processing systems - Open Systems 472 Interconnection - Specification of Abstract Syntax 473 Notation One (ASN.1), International Organization for 474 Standardization. International Standard 8824, December, 475 1987 477 [RFC2575] Wijnen, B., Presuhn, R., and K. McCloghrie, "View-based 478 Access Control Model (VACM) for the Simple Network 479 Management Protocol (SNMP)", RFC 2575, April 1999 481 [RFC2578] McCloghrie, K., Perkins, D., Schoenwaelder, J., Case, J., 482 Rose, M., and S. Waldbusser, "Structure of Management 483 Information Version 2 (SMIv2)", STD 58, RFC 2578, April 484 1999 486 [RFC2579] McCloghrie, K., Perkins, D., Schoenwaelder, J., Case, J., 487 Rose, M., and S. Waldbusser, "Textual Conventions for 488 SMIv2", STD 58, RFC 2579, April 1999 490 9. Full Copyright Statement 492 Copyright (C) The Internet Society (1999). All Rights Reserved. 494 This document and translations of it may be copied and furnished to 495 others, and derivative works that comment on or otherwise explain it 496 or assist in its implementation may be prepared, copied, published 497 and distributed, in whole or in part, without restriction of any 498 kind, provided that the above copyright notice and this paragraph are 499 included on all such copies and derivative works. However, this 500 document itself may not be modified in any way, such as by removing 501 the copyright notice or references to the Internet Society or other 502 Internet organizations, except as needed for the purpose of 503 developing Internet standards in which case the procedures for 504 copyrights defined in the Internet Standards process must be 505 followed, or as required to translate it into languages other than 506 English. 508 The limited permissions granted above are perpetual and will not be 509 revoked by the Internet Society or its successors or assigns. 511 This document and the information contained herein is provided on an 512 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 513 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 514 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 515 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 516 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.