idnits 2.17.1 draft-chisholm-netconf-model-05.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3978, Section 5.1 on line 16. -- Found old boilerplate from RFC 3978, Section 5.5 on line 1464. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 1436. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 1443. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 1449. ** This document has an original RFC 3978 Section 5.4 Copyright Line, instead of the newer IETF Trust Copyright according to RFC 4748. ** This document has an original RFC 3978 Section 5.5 Disclaimer, instead of the newer disclaimer which includes the IETF Trust according to RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == 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 432 has weird spacing: '... end of an ac...' == Line 433 has weird spacing: '...tomated maint...' == Line 505 has weird spacing: '...pErrors appin...' == Line 701 has weird spacing: '...sidered accep...' == Line 814 has weird spacing: '...element name=...' == (6 more instances...) -- 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 (April 24, 2006) is 6576 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) == Missing Reference: 'NETCONF-PROTO' is mentioned on line 108, but not defined -- Looks like a reference, but probably isn't: '3' on line 141 == Missing Reference: 'RFC3877' is mentioned on line 409, but not defined == Missing Reference: 'XML-SCHEMA-2' is mentioned on line 607, but not defined == Missing Reference: 'XPATH' is mentioned on line 662, but not defined == Unused Reference: 'URI' is defined on line 1291, but no explicit reference was found in the text == Outdated reference: A later version (-12) exists of draft-ietf-netconf-prot-06 ** Obsolete normative reference: RFC 2396 (ref. 'URI') (Obsoleted by RFC 3986) -- Possible downref: Non-RFC (?) normative reference: ref. 'XML' Summary: 6 errors (**), 0 flaws (~~), 14 warnings (==), 9 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group S. Chisholm 3 Internet-Draft Nortel 4 Expires: October 26, 2006 S. Adwankar 5 Motorola 6 April 24, 2006 8 Framework for Netconf Content 9 draft-chisholm-netconf-model-05.txt 11 Status of this Memo 13 By submitting this Internet-Draft, each author represents that any 14 applicable patent or other IPR claims of which he or she is aware 15 have been or will be disclosed, and any of which he or she becomes 16 aware will be disclosed, in accordance with Section 6 of BCP 79. 18 Internet-Drafts are working documents of the Internet Engineering 19 Task Force (IETF), its areas, and its working groups. Note that 20 other groups may also distribute working documents as Internet- 21 Drafts. 23 Internet-Drafts are draft documents valid for a maximum of six months 24 and may be updated, replaced, or obsoleted by other documents at any 25 time. It is inappropriate to use Internet-Drafts as reference 26 material or to cite them other than as "work in progress." 28 The list of current Internet-Drafts can be accessed at 29 http://www.ietf.org/ietf/1id-abstracts.txt. 31 The list of Internet-Draft Shadow Directories can be accessed at 32 http://www.ietf.org/shadow.html. 34 This Internet-Draft will expire on October 26, 2006. 36 Copyright Notice 38 Copyright (C) The Internet Society (2006). 40 Abstract 42 This memo defines a framework for defining content for Netconf. It 43 defines requirements to enable interoperability, extensibility, easy 44 parsing, usability and predictable modelling. 46 Table of Contents 48 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 49 1.1 Definition of Terms . . . . . . . . . . . . . . . . . . . 4 50 2. Requirements . . . . . . . . . . . . . . . . . . . . . . . . . 5 51 2.1 Data Modelling Language . . . . . . . . . . . . . . . . . 5 52 2.2 Conformance . . . . . . . . . . . . . . . . . . . . . . . 5 53 2.2.1 Fine Grain Conformance . . . . . . . . . . . . . . . . 5 54 2.2.2 Operations on managed objects . . . . . . . . . . . . 5 55 2.2.3 Element Status . . . . . . . . . . . . . . . . . . . . 6 56 2.2.4 Additional Conformance Information . . . . . . . . . . 6 57 2.3 Backwards Compatibility . . . . . . . . . . . . . . . . . 7 58 2.4 Versioning . . . . . . . . . . . . . . . . . . . . . . . . 7 59 2.5 Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 60 2.6 Defining Relationships . . . . . . . . . . . . . . . . . . 8 61 2.6.1 Association Relationship . . . . . . . . . . . . . . . 9 62 2.7 Defining Event Messages . . . . . . . . . . . . . . . . . 10 63 2.8 Considerations for Parse-ability . . . . . . . . . . . . . 11 64 2.8.1 Well-formed XML . . . . . . . . . . . . . . . . . . . 11 65 2.9 Use an Explicit Namespace on Attributes . . . . . . . . . 12 66 2.10 Naming . . . . . . . . . . . . . . . . . . . . . . . . . . 12 67 2.11 Error Messages . . . . . . . . . . . . . . . . . . . . . . 12 68 2.12 Schema Documentation . . . . . . . . . . . . . . . . . . . 13 69 2.13 Specifying Statistics, Status and Configuration 70 Information . . . . . . . . . . . . . . . . . . . . . . . 13 71 2.14 Schema Identity Information . . . . . . . . . . . . . . . 14 72 3. Modelling Considerations . . . . . . . . . . . . . . . . . . . 15 73 3.1 Modularity . . . . . . . . . . . . . . . . . . . . . . . . 15 74 3.2 Data Types . . . . . . . . . . . . . . . . . . . . . . . . 15 75 3.3 Elements and Attributes . . . . . . . . . . . . . . . . . 15 76 3.4 Use Container Elements for Lists . . . . . . . . . . . . . 15 77 3.5 Naming implications of using XPATH . . . . . . . . . . . . 16 78 3.5.1 Proper Tag Names . . . . . . . . . . . . . . . . . . . 17 79 3.6 Granularity of Data Model . . . . . . . . . . . . . . . . 17 80 3.7 Avoid Mixed Content . . . . . . . . . . . . . . . . . . . 17 81 4. Summary and Example . . . . . . . . . . . . . . . . . . . . . 19 82 4.1 Summary of Netconf Appinfo Elements & Attributes . . . . . 19 83 4.2 XML Schema for Identity appInfo . . . . . . . . . . . . . 20 84 4.3 XML Schema for per element appInfo . . . . . . . . . . . . 20 85 4.4 Managed Object Example . . . . . . . . . . . . . . . . . . 22 86 5. Relationship to Netconf Protocol . . . . . . . . . . . . . . . 26 87 5.1 Merge Operation . . . . . . . . . . . . . . . . . . . . . 26 88 5.2 Replace Operation . . . . . . . . . . . . . . . . . . . . 27 89 5.3 Delete Operation . . . . . . . . . . . . . . . . . . . . . 28 90 5.4 Create Operation . . . . . . . . . . . . . . . . . . . . . 29 91 5.5 Get Operation . . . . . . . . . . . . . . . . . . . . . . 30 92 5.6 Get Operation with subtree filtering . . . . . . . . . . . 31 93 5.7 Get All Operation . . . . . . . . . . . . . . . . . . . . 31 95 6. Security Considerations . . . . . . . . . . . . . . . . . . . 33 96 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 34 97 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 34 98 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . 34 99 A. Appendix . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 100 A.1 Access Control . . . . . . . . . . . . . . . . . . . . . . 36 101 A.1.1 Overview . . . . . . . . . . . . . . . . . . . . . . . 36 102 A.1.2 Proposed Solution . . . . . . . . . . . . . . . . . . 36 103 A.2 Open Issues . . . . . . . . . . . . . . . . . . . . . . . 37 104 Intellectual Property and Copyright Statements . . . . . . . . 39 106 1. Introduction 108 NETCONF [NETCONF-PROTO] can be conceptually partitioned into four 109 layers: 111 Layer Example 112 +-------------+ +-----------------------------+ 113 | Content | | Configuration data | 114 +-------------+ +-----------------------------+ 115 | | 116 +-------------+ +-----------------------------+ 117 | Operations | | , | 118 +-------------+ +-----------------------------+ 119 | | 120 +-------------+ +-----------------------------+ 121 | RPC | | , | 122 +-------------+ +-----------------------------+ 123 | | 124 +-------------+ +-----------------------------+ 125 | Application | | BEEP, SSH, SSL, console | 126 | Protocol | | | 127 +-------------+ +-----------------------------+ 129 This document defines a framework for Netconf content. This 130 framework is intended to provide guidance for the creation of Netconf 131 content for the purposes of enabling interoperability, extensibility, 132 parse-ability and usability. 134 Figure 1 136 1.1 Definition of Terms 138 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 139 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 140 document are to be interpreted as described in RFC 2119 [3]. 142 Element: An XML Element[XML]. 144 Managed Entity: A node, which supports netconf[NETCONF] and has 145 access to management instrumentation. This is also referred to as 146 the netconf server. 148 Managed Object: A collection of one of more Elements that define an 149 abstract thing of interest. 151 2. Requirements 153 This section describes some restrictions on Netconf content and the 154 specifications that describe this content, which will increase 155 interoperability between implementations and between different 156 versions of a given implementation. 158 2.1 Data Modelling Language 160 XML Schema should be used to define the XML-formatted data that will 161 be transported via Netconf. 163 2.2 Conformance 165 When defining netconf content, it is also necessary to define 166 machine-readable conformance for that content. The following are the 167 requirements that have been identified for the conformance and 168 compliance aspects of Netconf data models. This conformance is 169 defined for both the individual elements with the Schema, and' also 170 for the entire schema. 172 Conformance specifies not only whether to object must be supported, 173 but also the level of access, read versus write for example that is 174 minimally required 176 2.2.1 Fine Grain Conformance 178 When defining elements, the "minOccurs" and "maxOccurs" tags MUST be 179 used to specify whether that object is required to have a compliant 180 schema. When defining an attribute, the "use" tag must be used to 181 define whether the attribute is required. 183 2.2.2 Operations on managed objects 185 Operations that can be performed on managed objects fall into one of 186 the following equivalence classes: "Create", "Delete","Read", 187 "Write", and "Execute". 189 A value of "create" means it is possible to create new instances of 190 this element using commands like the netconf or commands. A value of "delete" means it is possible to 192 destroy instances of this element using commands like the netconf 193 , or operations. A 194 value of "read" means that it is possible to view values of this 195 element using commands like the , or 196 operations. A value of "write" means it is possible to modify an 197 instance of this element using commands like the netconf or commands. A value of "execute" means that 199 there is a side effect execution such as rebooting that is 200 permissible as a result of commands like the netconf 201 or a command or the ability to execute a commands like 202 the , or command. 204 This memo introduces the appinfo element of "minAccess" and an 205 optional one of "maxAccess" which contain a non-empty list of values. 206 The "minAccess" element defines the set of operations that must be 207 supported in order to claim compliance to this schema. The 208 "maxAccess" element contains the full set of operations that make 209 operational sense for this object. If not present, it assumes the 210 same value as the minAccess tag. 212 For example, a status object might have a "minAccess" of "read" but a 213 "maxAccess" of "read write" to indicate that it must be possible to 214 perform a get operation the status, but implementations could also 215 allow configuration operations on it as well. In the case of a 216 statistic, both the "minAccess" and "maxAccess" might have values of 217 "read". 219 220 222 2.2.3 Element Status 224 As a schema evolves, certain elements may become obsolete. Simply 225 deleting these from the Schema may be acceptable for elements that 226 did not see implementation, but others will require a strategy to 227 allow implementers to migrate away from the old elements. 229 An optional appinfo element called "status" SHOULD be used to provide 230 the status of the element. When not present, it will assume a value 231 of "current". The other value of this object is "obsolete" which 232 indicates that implementations should consider migrating away from 233 this object and that its implementation is no longer required to be 234 considered conformant. Obsolete content is never removed from the 235 document and its element name can never be re-used 237 For example 238 current 240 2.2.4 Additional Conformance Information 242 Additional information about conformance should be specified using a 243 documentation tag. 245 Examples of additional conformance information that may be useful to 246 provide includes how implementations can specify specific exceptions 247 to required conformance, dependencies between elements (in order to 248 do A, you need to first do B) and conditional conformance (if BGP, 249 then ...). 251 2.2.4.1 Schema Level Conformance 253 In order to claim compliant Netconf content, all elements MUST 254 conform to their given minOccurs and maxOccurs definitions and all 255 elements with a status of "current" and with a minOccurs greater than 256 or equal to one MUST be supported. In addition, all of the 257 operations listed by the minAccess attribute MUST be supported. 259 2.3 Backwards Compatibility 261 Backwards compatibility means that new versions of an XML Schema that 262 defines Netconf Content can be rolled out in a way that does not 263 break existing supporters. 265 Changes introduced as a result of an update to an existing 266 specification of Netconf content fall into three categories: new 267 concept are added; existing concepts are changed; or existing 268 concepts are obsoleted. Adding new optional content or adding 269 optional new content to the content of a component, such as a new 270 enumeration in a list, are changes that maintain backwards 271 compatibility. Changing the meaning or semantics of existing 272 content, restricting the content of an existing component, or adding 273 or removing required components are changes that do not maintain 274 backwards compatibility. 276 If an update to an XML Schema is backwards compatibility, then it 277 must use the same element name. A new element name must be used when 278 backwards compatibility is not possible. 280 2.4 Versioning 282 Each version of a schema needs to be complete, not a delta from the 283 previous version. 285 [Editor's Note: there has been discussion about whether all versions 286 of a Schema maintain backwards compatibility, or if only minor 287 version number changes do. Major version number changes could 288 potentially signify a break in backwards compatibility. For example, 289 version 1.2 would be backwards compatible to version 1.0, while 290 version 2.0 may not be.] 291 The XML Schema version attribute will be used to signify version 293 For example: 295 296 298 299 300 302 This allows applications to be aware of XML Schema versions, and 303 changes to XML Schema version, without forcing instance documents to 304 change to a new schema if the new schema is backwards compatible. 306 2.5 Keys 308 Keys are an optional construct for specifying the element or set of 309 element that uniquely identifies an instance of a managed object. 310 The XML Schema 'key' construct is used to specify keys. 312 In the absence of explicitly defined keys, everything can be 313 considered a key from the perspective of the collection of fields 314 that uniquely define an entry. 316 [Editor's Note: we may also want to define an attribute called keys 317 so it can be sent over the wire in the instance document.] 319 321 Note that being able to query on arbitrary pieces of information 322 provides for multiple views of the managed object, and the optional 323 definition of keys does not preclude this. 325 2.6 Defining Relationships 327 Relationships between elements come in three forms: associations, 328 extensions and specializations. 330 An extension to existing element defines information about the same 331 managed object, but just does it in a separate piece of Schema. For 332 example, if a common Schema define information about interfaces, a 333 particular product might define an extension to define information 334 for that interface that is only applicable to that product. To 335 return to our book example, a particular publisher may wish the 336 extend the general book definition to include information specific to 337 their own books, such as the name of the animal depicted on the 338 cover. 340 A specialization of an existing element is an extension that only 341 applies to a subset of the instances of the managed object that the 342 original definition applied to. For example, the original element 343 may define information about interfaces, with a specialization being 344 defined that is information only applicable to ATM interfaces. With 345 our book example, a specialization of children's books might be 346 defined that defines information such as suggested age of reader. 348 An association exists between two different managed objects. For 349 example, a port is associated with an interface or a book within a 350 bookshelf. 352 It is important to be able to learn the relationships between the 353 managed objects that are represented in the XML Schema in order to be 354 able to take full advantage of information provided. In addition to 355 this, it is also important to be able to understand these 356 relationships to help predict the behaviour of the system. When a 357 configuration command causes the creation of a managed object 358 represented by a piece of XML schema, it causes the creation of all 359 other bits of XML Schema that represent that managed object as well 360 as any applicable specializations of that object. 362 Relationships need to be understood in general as well as the 363 specific run-time instances. The first is what is defined in the XML 364 Schema and the second is what we see only over the wire. The general 365 relationship needs to be understood when reading the schema or when 366 designing tools and scripts to use the Schema. For example, 367 interfaces are associated with ports and there is a specific method 368 of learning more about this relationship. The run-time instance 369 relationship, for example that port 3 is associated with interface 370 number 324, or that the Encyclopaedia is on shelf 3 is learned using 371 the general method learned while learning about the generalized 372 relationships./ 374 2.6.1 Association Relationship 376 The easiest way to define an association relationship is using 377 containment. A book is on a bookshelf, so the following XML makes 378 this relationship obvious and unambiguous 380 381 382 383 385 387 It is not always possible or desirable to model all associations via 388 containment. Managed objects are often associated with more than one 389 other managed object and containment within both might cause 390 confusion and certainly causes extra XML to be generated. In 391 addition, in some associations, it might not be obvious to decide 392 which objects is contained in which object. And finally, it may be 393 more workable to break the definition of managed objects into 394 smaller, related pieces of XML Schema. 396 The XML Schema 'keyref' construct will be used to define 397 relationships between managed objects. 399 [Editor's Note: ensure 'keyref' can be used to point at elements not 400 within the same scope. If not, define a similar construct that can 401 be.] 403 405 2.7 Defining Event Messages 407 An event is something that happens which may be of interest. A 408 fault, a change in status, crossing a threshold, or an external input 409 to the system, for example [RFC3877]. Often this results in an 410 asynchronous message, sometimes referred to as a notification or 411 event message, being sent out to interested parties to notify them 412 that this event has occurred. Event messages will be defined in XML 413 Schema with an appinfo of 'eventClasses' used to both identify which 414 bits of XML Schema define event messages but also what type of event. 415 An event belongs to one or more classes. 417 The initial set of classes is fault, information, state, audit, 418 configuration, data, maintenance, metrics, security and heartbeat. A 419 fault event message is generated when a fault condition (error or 420 warning) occurs. An Information event is something that happens of 421 interest which is within the expected operational behaviour and not 422 otherwise covered by another class. A state event indicates a change 423 from one state to another, where a state is a condition or stage in 424 the existence of a managed entity. Audit events provide notification 425 of very specific actions within a managed device. In isolation an 426 audit event provides very limited data. A collection of audit 427 information forms an audit trail. A configuration event, 428 alternatively known as an inventory event, is used to notify that 429 hardware, software, or a service has been added/changed/removed. A 430 data dump event is an asynchronous event containing information about 431 a system, its configuration, state, etc. A maintenance event signals 432 the beginning, process or end of an action either generated by a 433 manual or automated maintenance action. A metrics event contains a 434 metric or a collection of metrics. This includes performance 435 metrics. A heart beat event is sent periodically to enable testing 436 that the communications channel is still functional. 438 Note that it may make operational sense to set the minAccess or 439 maxAccess of an element with element classes defined against it to be 440 a null list to indicate that this information can not be read or 441 configured using other commands. 443 444 446 2.8 Considerations for Parse-ability 448 Netconf content can affect the efficiency and robustness of parsing 449 routines in two ways. The first has to do with whether anything 450 within the Netconf content could be confused with any aspect of the 451 operations, RPC or application protocol layers. If this is possible, 452 then more careful routines need to be written. In particular, it 453 might be difficult to separate out an implementation into separate 454 methods to parse these different layers if it is necessary to parse 455 the Netconf content and match open and close brackets rather than 456 just looking for an appropriate close tag. 458 Another aspect where the content will affect performance of the 459 parsing routines is on the assumptions that the parsing routine can 460 make. The following section outlines some restrictions on the 461 Netconf content that will positively impact the performance of 462 parsing routines with minimum impact on the usability of the 463 solution. 465 2.8.1 Well-formed XML 467 All XML used within a Netconf solution needs to be well formed [XML] 468 and conform to an XML Schema specification that conforms to the 469 guidelines in this document. 471 2.9 Use an Explicit Namespace on Attributes 473 All attributes should be prefixed so that they belong to a specific 474 namespace. This encourages meaningful definitions that are free of 475 collisions. 477 479 481 2.10 Naming 483 All NetMod base elements SHOULD be defined in the namespace 484 urn:ietf:params:xml:ns:netmod:base:1.0 486 All NetMod defined datatypes SHOULD be defined in the namespace 488 urn:ietf:params:xml:ns:netmod:datatypes:1.0 490 The name of an element SHOULD be unique in a given namespace and 491 should be addressed in a reference to a given namespace. 493 2.11 Error Messages 495 Within Netconf, the element is used to provide 496 application-level error codes. If implementations don't understand 497 the application-level specific error codes, they still have the 498 generic one to go by, but the application-level specific error codes 499 can provide information about the specific problem that has happened. 500 A non-exhaustive set of error messages that may get generated by the 501 application as a result of performing netconf operations against that 502 data model is included within the XML Schema that defines the Netconf 503 content. 505 [Editor's Note: The definition of the appErrors appinfo could in 506 theory be made richer than it is, so long as the information still 507 goes over the wire as specified in the base netconf specification. 508 We could specify which of the operation equivalence classes can 509 trigger this message (read, for example) as well as any additional 510 fields that should get reported in the message. Note that we can't 511 mix content on the wire, so any additional fields would need to be 512 embedded - "I can't read Les Miserable" as appose to "I can't read 513 Les Miserable". ] 514 An optional appinfo called 'appErrors ' is used to specify these 515 application-level error messages. 517 518 519 Book is in language you do not understand. 520 521 appErrors> 523 These are applicable to any element. 525 [Editor's Note: How closely tied are these to the known set of 526 operations that can be performed on the data? How is this 527 determined?] 529 2.12 Schema Documentation 531 The "documentation" tag must be used to provide all addition 532 information to implementers and users of a schema that can not be 533 modelled within the schema itself or using the appinfo defined within 534 this memo. This includes further restrictions and additional 535 complexities as well as any information that will be helpful in 536 understanding the element. 538 Note that other means of documenting, including the 539 construct are not as easily associated within specific elements and 540 not necessarily understood by all tools. 542 2.13 Specifying Statistics, Status and Configuration Information 544 [Editors Note: What about historical performance statistics?] 546 There may be potential value in being able to easily distinguish 547 between configuration, status and statistical information within a 548 data model. This would allow better understanding of nature of each 549 piece of information without requiring specific knowledge of the 550 context. 552 Propose adding an optional appinfo called dataType which takes a 553 value of 'configuration', 'statistics', or 'status'. 555 [Editor's Note: rework these examples to use appinfo] 557 For example 558 configuration 560 [Editor's Note: Test on existing data models?] 562 2.14 Schema Identity Information 564 Replacing the following with something from Dublin Core 565 (http://dublincore.org) is for further study. 567 A schema must contain a schema Identity annotation as part of the 568 appinfo on the highest level schema element. The Identity provides 569 schema information such as last update of this schema, organization, 570 contact, description and revision history. The contact and revision 571 information can occur multiple times in a schema identity. 573 An example of identity element is as given below 575 576 577 NetConf State Schema 578 2001-12-17T09:30:47-05:00 579 580 Example.com 581 582 ExampleName 583 ExampleAddress 584 http://www.example.com 585 0000000 586 Any other Info 587 588 The Description of NetConf State Schema 589 590 591 2004-12-17T09:30:47-05:00 592 The first version of the schema 593 594 595 596 598 3. Modelling Considerations 600 3.1 Modularity 602 It is better to publish Netconf content as a series of XML Schema 603 rather then as a single monolithic data model. 605 3.2 Data Types 607 XML Schema has 44 built in data types [XML-SCHEMA-2]. Potentially 608 reusable data types should be declared as simple or complex type, 609 rather than element. 611 Emphasis should be replaced on creating reusable application-level 612 data types such as IP addresses, DateAndTime or OSI states, rather 613 than developing 20 different flavours of integers. 615 3.3 Elements and Attributes 617 When designing encoding rules for NETCONF content, the following 618 guidelines should be used to determine when use of elements is 619 appropriate and when is use of attributes. 621 Attributes should contain metadata about the element, not true data. 622 Therefore, information about the managed entity should not be encoded 623 in attributes. 625 In addition, attributes are unordered, can appear only once, and can 626 have no children. When modelling data in an XML Schema, it is 627 important to leave room for future expansion - in future 628 specifications or future software releases. This is another reason 629 to only use attributes for metadata. 631 3.4 Use Container Elements for Lists 633 A distinct container should be used when encoding lists with multiple 634 instances (maxOccurs > 1), use a distinct container element. 635 Sometimes this will be the plural form of the instance element, but 636 often there is a more natural container available. Some containers 637 exist in the 'real world' and some are only modelling artefacts. 638 When an appropriate real-world container is available, it is not 639 necessary to create a modelling artefact to artificially contain the 640 list. 642 In this example, the element 'book' is contained within the "books" 643 element. 645 646 .... 647 .... 648 .... 649 651 652 .... 653 .... 654 .... 655 657 Use of container elements allows simpler manipulation of lists and 658 list members. 660 3.5 Naming implications of using XPATH 662 XPath [XPATH] can be used to locate managed objects in a given 663 namespace. XPATH based addressing can also be used to select a set 664 of managed objects based on a set of criteria's, select content that 665 is combination of different managed object values and to create 666 simple expressions of managed objects. 668 Examples of XPATH based addressing are shown below: 670 1. Provide all book titles in a . //bk:book/bk:bookTitle/@bk:value 672 2. Provide ACL information of the . /bk:/ACL 674 3. Determine book title for a book whose ISBN number is 0596002923 675 //bk:book[bk:ISBN/@bk:value="0596002923"]/bk:bookTitle/@bk:value 677 4. List all book names where the average review rating is greater 678 than 4. //bk:book[bk:AverageReview/@bk:value>4]/ 679 bk:bookTitle/@bk:value //if:ifEntry[if:ifMtu/@if:value>'500'] 681 5. Select all books that have "NetMod" in their description and 682 average review rating is greater than 4. //bk:book[(contains(bk: 683 bookTitle/@bk:value,'NetMod')) and (bk:AverageReview/@bk:value>'4')] 685 6. Find number of books whose publication year is greater than 2003. 686 count(//bk:book[bk:PublicationYear/@bk:value>'2003']) 688 3.5.1 Proper Tag Names 690 When choosing element names, they should: 692 o use ASCII (7-bit) 694 o be lower camel, a method of writing compound words or phrases 695 where the words are joined without spaces, and each word is 696 capitalized within the compound. The first letter of the compound 697 is lower case. An example would be lowerCamel. 699 o Whenever possible, use full words. There are some well-known 700 abbreviations and short forms, such as "config" that would be 701 considered acceptable 702 o Should be consistent with existing vocabularies 704 These are guidelines only and should be considered secondary to the 705 need for consistency with existing vocabularies. For example, when 706 encoding SNMP MIB variables names in NETCONF, use the existing names 707 (ifAddr) instead of shifting to these guidelines (ifAddress). These 708 guidelines are valuable when no common vocabulary exists, because 709 they help to avoid the scenario in which a dozen developers choose a 710 dozen names that differ in ways that lead to frustrating 711 inconsistencies, such as ifaddr, if-addr, if-address, interface- 712 address, intf-addr, iaddr, and iface-addr. 714 3.6 Granularity of Data Model 716 Designers should give some thought to the high level information they 717 users need to manage the device and not simple expose the low level 718 information that they have available. Ideally, it should be possible 719 to make a small change to the data model and have it trigger a big 720 change in the managed entity. 722 3.7 Avoid Mixed Content 724 Mixed content is defined as elements that can contain both data and 725 other elements. Elements in NETCONF can contain either data or 726 additional elements only. 728 This greatly simplifies the complexity of parsing XML, especially in 729 the area of significant whitespace. Whitespace inside data elements 730 is significant. Whitespace outside data elements is not. 732 733 data 734 data 735 737 738 datadatamaybe some 739 741 4. Summary and Example 743 4.1 Summary of Netconf Appinfo Elements & Attributes 745 The following table summarizes the XML Schema appinfo introduced in 746 this memo When these appinfo are used in the definition of XML Schema 747 for use with netconf, they are applicable to all instances of that 748 Schema. 750 -------------------------------------- 751 | appinfo item | | Compliance | 752 -------------------------------------- 753 | minAccess | | Mandatory | 754 | maxAccess | | Optional | 755 | status | | Optional | 756 | appErrors | | Recommended | 757 | identity | | Mandatory | 758 | eventClass | | Optional | 759 | dataType | | Optional | 760 -------------------------------------- 762 Figure 17 764 4.2 XML Schema for Identity appInfo 766 767 768 769 770 771 773 774 776 777 779 780 781 782 783 784 786 787 788 789 790 791 792 793 794 796 4.3 XML Schema for per element appInfo 798 799 806 807 808 809 This is a set of information that can be applied to any 810 element. 811 812 813 814 815 816 817 818 820 821 823 825 826 827 828 829 830 832 833 834 836 837 839 840 842 844 846 848 850 853 854 855 857 858 860 861 863 865 867 869 871 873 875 877 879 882 883 884 886 887 889 891 4.4 Managed Object Example 893 An example of a node that describes a system description is shown 894 below. . 896 898 905 906 907 908 909 910 This element defines information about books 911 912 913 914 915 916 917 current 918 919 Book lent out 920 Book not interesting 921 922 Book in language you don't know 923 924 Book eaten by book worm 925 926 927 928 930 931 932 933 934 935 936 The ISBN for this book. 937 938 939 940 941 942 943 current 944 945 946 948 949 950 951 952 The author of this book. 953 954 955 956 957 958 959 current 960 961 962 963 964 965 966 967 The year this book was published 968 969 970 971 972 973 974 current 975 976 977 978 979 980 981 982 The last issue date for this book. 983 984 985 986 987 988 989 current 990 991 992 993 994 995 996 997 The average review for this book. 998 999 1000 1001 1002 1003 1004 current 1005 1006 1007 1008 1009 1010 1011 1012 1013 1015 An example of an instance of a book node is 1017 1018 XYZ 1019 0000000123 1020 ABC 1021 2005 1022 2005-02-02 1023 5 1024 1026 5. Relationship to Netconf Protocol 1028 The Netconf architecture supports a clear separation between content 1029 and protocol. This is an important architectural separation that 1030 should be maintained. That having been said, there are major 1031 advantages to ensuring that the content of Netconf is well behaved 1032 and predictable 1034 Whether a Netconf implementation can be said to be compliant without 1035 also being compliant to the guidelines within this memo is an area of 1036 further study. 1038 The following examples illustrate the netconf protocol commands being 1039 executed against netmod compliant Schemas. 1041 5.1 Merge Operation 1043 RPC Request : 1044 1046 1047 1048 1049 1050 replace 1051 1052 1053 NetMod for Dummies: Part2 1054 0596002923 1055 NetMod Experts 1056 2003 1057 2003-10-15 1058 1 1059 1060 1061 1062 1064 RPC Reply : 1065 1067 1068 1070 5.2 Replace Operation 1072 RPC Request : 1073 1075 1076 1077 1078 1079 replace 1080 1081 1082 NetMod for Dummies: Part2 1083 0596002924 1084 NetMod Experts 1085 2003 1086 2003-10-15 1087 1 1088 1089 1090 1091 1093 RPC Reply : 1094 1096 1097 1099 5.3 Delete Operation 1101 RPC Request : 1102 1104 1105 1106 1107 1108 1109 1111 RPC Reply : 1112 1114 1115 1117 5.4 Create Operation 1119 RPC Request : 1121 1123 1124 1125 1126 1127 replace 1128 1129 1130 NetMod for Dummies: Part6 1131 0596002 1132 NetMod Experts 1133 2003 1134 2003-10-15 1135 1 1136 1137 1138 1139 1141 RPC Reply : 1142 1144 1145 1147 5.5 Get Operation 1149 RPC Request : 1150 1152 1153 1154 1155 1156 1157 1159 RPC Reply : 1160 1162 1163 1164 NetMod for Dummies: Part2 1165 0596002923 1166 NetMod Experts 1167 2003 1168 2003-10-15 1169 1 1170 1171 1172 NetMod for Dummies: Part2 1173 0596002924 1174 NetMod Experts 1175 2003 1176 2003-10-15 1177 1 1178 1179 1180 1182 5.6 Get Operation with subtree filtering 1184 RPC Request : 1185 1187 1188 1189 1190 1191 //bk:ISBN 1192 1193 1195 RPC Reply : 1196 1198 1199 1201 0596002924 1202 1203 1204 1206 5.7 Get All Operation 1208 RPC Request : 1209 1211 1212 1214 RPC Reply : 1215 1217 1218 1219 1220 1221 locked 1222 7 1223 1224 1225 1226 1227 1228 1229 1230 unlocked 1231 1232 1233 1234 1235 1236 1237 1238 1239 unlocked 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 6 1251 Bob 1252 2:56:01 PM 1253 1254 1255 1256 1257 1258 NetMod for Dummies: Part2 1259 0596002924 1260 NetMod Experts 1261 2003 1262 2003-10-15 1263 1 1264 1265 1266 1267 1269 6. Security Considerations 1271 To be determined once specific aspects of this solution are better 1272 understood. In particular, the access control framework and the 1273 choice of transport will have a major impact on the security of the 1274 solution 1276 7. Acknowledgements 1278 This document is a result of discussions at IETF 59, 60 and 64, as 1279 well as on the mailing list by the following people: Sharon Chisholm, 1280 David Harrington, Ray Atarashi, Yoshifumi Atarashi, Bert Wijnen, Dan 1281 Romascanu, Andy Bierman, Randy Presuhn, Chris Lonvick, Eliot Lear, 1282 Avri Doria, Juergen Schoenwaelder, Rob Enns, Faye Ly, Andre 1283 Westerinen, Orly Nicklass, Alexander Clemm, Keith McCloghrie, Hector 1284 Trevino , James Balestriere Simon Leinen and Ladislav Lhotka. 1286 8. References 1288 [NETCONF] Enns, R., "NETCONF Configuration Protocol", 1289 ID draft-ietf-netconf-prot-06, April 2005. 1291 [URI] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1292 Resource Identifiers (URI): Generic Syntax", RFC 2396, 1293 August 1998. 1295 [XML] World Wide Web Consortium, "Extensible Markup Language 1296 (XML) 1.0", W3C XML, February 1998, 1297 . 1299 [refs.RFC2026] 1300 Bradner, S., "The Internet Standards Process -- Revision 1301 3", RFC 2026, BCP 9, October 1996. 1303 [refs.RFC2119] 1304 Bradner, s., "Key words for RFCs to Indicate Requirements 1305 Levels", RFC 2119, March 1997. 1307 [refs.RFC2223] 1308 Postel, J. and J. Reynolds, "Instructions to RFC Authors", 1309 RFC 2223, October 1997. 1311 Authors' Addresses 1313 Sharon Chisholm 1314 Nortel 1315 3500 Carling Ave 1316 Nepean, Ontario K2H 8E9 1317 Canada 1319 Email: schishol@nortelcom 1320 Sandeep Admankar 1321 Motorola 1322 1301 East Algonquin Road 1323 MS IL02-2240 1324 Schaumburg, Il 60196 1325 USA 1327 Email: sandeep.adwankar@motorola.com 1329 Appendix A. Appendix 1331 A.1 Access Control 1333 A.1.1 Overview 1335 For discussing access control, we shall use the same equivalence 1336 classes for operations on managed objects: "Create", "Delete", 1337 "Read", "Write", and "Execute". 1339 Access control is defined only for the node it is associated with. 1340 It does not cascade throughout a containment hierarchy. 1342 There are four classes of access control that can possibly be 1343 defined: 1345 1. Resource Category: High Level like BGP or DNS, similar to syslog 1346 concept 1348 2. Resource Type: Lowest level before instance 1350 3. Resource Instance 1352 4. Operation Type 1354 There is a fifth class that enables access control within an instance 1355 to specific values. This level of control is beyond the scope of 1356 this specification. 1358 [Editor's Note: What about permission to traverse through a 1359 hierarchy? This naturally imparts information about the hierarchy 1360 that might allow a user to gleam things they should not. 1362 The two main use cases for consideration are single customer and 1363 multiple customers on a single box. Note that the concept of a 1364 virtual router has been successful in solving the latter problem in 1365 SNMP and CLI. 1367 Ideally the security model used in netconf is integratable with well- 1368 deployed solutions like RADIUS and TACACS+. 1370 Netconf may only need a mechanism to report information about access 1371 control and an API to enable easy integration to an existing 1372 solution. 1374 A.1.2 Proposed Solution 1376 [Editors Note: This area is for further study. Which bits belong in 1377 the data model and which in the protocol? Can define a simple 1378 security model that modelled on what CLIs do and integrate with 1379 radius? What impacts would this have on the data model? Do we want 1380 to a fully exposed and described model or just the ability to answer 1381 the question "Is user A allows to run this command?". How do we 1382 identify users, or do we need to (is it out of scope?)? The 1383 requirement is to identify it so it can be deployed in deployed 1384 security infrastructure.] 1386 A solution will need to identify the type off access that is 1387 permitted, profile an identifier for this instance of access 1388 permissions and potentially identify a timeframe that this access is 1389 good for. This access would then need to be associated with 1390 particular class and instance data, as described above. 1392 1393 1394 1395 1396 1398 1399 1401 A.2 Open Issues 1403 What happens when we are importing from other organizations, and they 1404 have different rules. This needs to be thought through for version, 1405 backwards compatibility, mixed model, etc to ensure this won't cause 1406 any problems. 1408 Do we actually needed minAccess and maxAccess or can it be deleted. 1409 It was suggested that it could be added back later if it was 1410 determined to be necessary. Some people felt that conformance, even 1411 run-time indication of what is actually supported, was important. 1412 Others felt it didn't work well in SNMP, so perhaps native minOccurs/ 1413 maxOccurs would be sufficient. It was suggested that it might be 1414 more interesting to distinguish between state, statistics and 1415 configuration when defining data rather than providing min and max 1416 access. 1418 Around section 2.5.1, there was discussion about whether keys could 1419 change over time (across reboots, if cards moved, etc) and if so, if 1420 perhaps some other less meaningful but more permanent index was also 1421 useful. There were some concerns raised about the usability of these 1422 sort of arbitrary number indices. There was also discussion about 1423 the difference between internal and external identifiers - those 1424 generated by the system and those input from external systems. The 1425 latter will not change unless the user actually wants it to change. 1427 Intellectual Property Statement 1429 The IETF takes no position regarding the validity or scope of any 1430 Intellectual Property Rights or other rights that might be claimed to 1431 pertain to the implementation or use of the technology described in 1432 this document or the extent to which any license under such rights 1433 might or might not be available; nor does it represent that it has 1434 made any independent effort to identify any such rights. Information 1435 on the procedures with respect to rights in RFC documents can be 1436 found in BCP 78 and BCP 79. 1438 Copies of IPR disclosures made to the IETF Secretariat and any 1439 assurances of licenses to be made available, or the result of an 1440 attempt made to obtain a general license or permission for the use of 1441 such proprietary rights by implementers or users of this 1442 specification can be obtained from the IETF on-line IPR repository at 1443 http://www.ietf.org/ipr. 1445 The IETF invites any interested party to bring to its attention any 1446 copyrights, patents or patent applications, or other proprietary 1447 rights that may cover technology that may be required to implement 1448 this standard. Please address the information to the IETF at 1449 ietf-ipr@ietf.org. 1451 The IETF has been notified of intellectual property rights claimed in 1452 regard to some or all of the specification contained in this 1453 document. For more information consult the online list of claimed 1454 rights. 1456 Disclaimer of Validity 1458 This document and the information contained herein are provided on an 1459 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 1460 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 1461 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 1462 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 1463 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 1464 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 1466 Copyright Statement 1468 Copyright (C) The Internet Society (2006). This document is subject 1469 to the rights, licenses and restrictions contained in BCP 78, and 1470 except as set forth therein, the authors retain all their rights. 1472 Acknowledgment 1474 Funding for the RFC Editor function is currently provided by the 1475 Internet Society.