idnits 2.17.1 draft-ietf-netmod-arch-10.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an Introduction section. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to contain a disclaimer for pre-RFC5378 work, but was first submitted on or after 10 November 2008. The disclaimer is usually necessary only for documents that revise or obsolete older RFCs, and that take significant amounts of text from those RFCs. If you can contact all authors of the source material and they are willing to grant the BCP78 rights to the IETF Trust, you can and should remove the disclaimer. Otherwise, the disclaimer is needed and you can ignore this comment. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (September 23, 2010) is 4962 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Missing Reference: 'C' is mentioned on line 648, but not defined == Missing Reference: 'S' is mentioned on line 643, but not defined ** Obsolete normative reference: RFC 4741 (Obsoleted by RFC 6241) ** Obsolete normative reference: RFC 4742 (Obsoleted by RFC 6242) ** Obsolete normative reference: RFC 5539 (Obsoleted by RFC 7589) == Outdated reference: A later version (-14) exists of draft-ietf-netconf-with-defaults-11 == Outdated reference: A later version (-10) exists of draft-ietf-netmod-dsdl-map-07 == Outdated reference: A later version (-11) exists of draft-ietf-netmod-yang-usage-10 Summary: 4 errors (**), 0 flaws (~~), 7 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group P. Shafer 3 Internet-Draft Juniper Networks 4 Intended status: Informational September 23, 2010 5 Expires: March 27, 2011 7 An Architecture for Network Management using NETCONF and YANG 8 draft-ietf-netmod-arch-10 10 Abstract 12 The Network Configuration Protocol (NETCONF) gives access to native 13 capabilities of the devices within a network, defining methods for 14 manipulating configuration databases, retrieving operational data, 15 and invoking specific operations. YANG provides the means to define 16 the content carried via NETCONF, both data and operations. Using 17 both technologies, standard modules can be defined to give 18 interoperability and commonality to devices, while still allowing 19 devices to express their unique capabilities. 21 This document describes how NETCONF and YANG help build network 22 management applications that meet the needs of network operators. 24 Status of this Memo 26 This Internet-Draft is submitted in full conformance with the 27 provisions of BCP 78 and BCP 79. 29 Internet-Drafts are working documents of the Internet Engineering 30 Task Force (IETF). Note that other groups may also distribute 31 working documents as Internet-Drafts. The list of current Internet- 32 Drafts is at http://datatracker.ietf.org/drafts/current/. 34 Internet-Drafts are draft documents valid for a maximum of six months 35 and may be updated, replaced, or obsoleted by other documents at any 36 time. It is inappropriate to use Internet-Drafts as reference 37 material or to cite them other than as "work in progress." 39 This Internet-Draft will expire on March 27, 2011. 41 Copyright Notice 43 Copyright (c) 2010 IETF Trust and the persons identified as the 44 document authors. All rights reserved. 46 This document is subject to BCP 78 and the IETF Trust's Legal 47 Provisions Relating to IETF Documents 48 (http://trustee.ietf.org/license-info) in effect on the date of 49 publication of this document. Please review these documents 50 carefully, as they describe your rights and restrictions with respect 51 to this document. Code Components extracted from this document must 52 include Simplified BSD License text as described in Section 4.e of 53 the Trust Legal Provisions and are provided without warranty as 54 described in the Simplified BSD License. 56 This document may contain material from IETF Documents or IETF 57 Contributions published or made publicly available before November 58 10, 2008. The person(s) controlling the copyright in some of this 59 material may not have granted the IETF Trust the right to allow 60 modifications of such material outside the IETF Standards Process. 61 Without obtaining an adequate license from the person(s) controlling 62 the copyright in such materials, this document may not be modified 63 outside the IETF Standards Process, and derivative works of it may 64 not be created outside the IETF Standards Process, except to format 65 it for publication as an RFC or to translate it into languages other 66 than English. 68 Table of Contents 70 1. Origins of NETCONF and YANG . . . . . . . . . . . . . . . . . 4 71 2. Elements of the Architecture . . . . . . . . . . . . . . . . . 6 72 2.1. NETCONF . . . . . . . . . . . . . . . . . . . . . . . . . 6 73 2.1.1. NETCONF Transport Mappings . . . . . . . . . . . . . . 8 74 2.2. YANG . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 75 2.2.1. Constraints . . . . . . . . . . . . . . . . . . . . . 11 76 2.2.2. Flexibility . . . . . . . . . . . . . . . . . . . . . 12 77 2.2.3. Extensibility Model . . . . . . . . . . . . . . . . . 12 78 2.3. YANG Translations . . . . . . . . . . . . . . . . . . . . 13 79 2.3.1. YIN . . . . . . . . . . . . . . . . . . . . . . . . . 14 80 2.3.2. DSDL (RELAX NG) . . . . . . . . . . . . . . . . . . . 14 81 2.4. YANG Types . . . . . . . . . . . . . . . . . . . . . . . . 15 82 2.5. IETF Guidelines . . . . . . . . . . . . . . . . . . . . . 15 83 3. Working with YANG . . . . . . . . . . . . . . . . . . . . . . 16 84 3.1. Building NETCONF- and YANG-based Solutions . . . . . . . . 16 85 3.2. Addressing Operator Requirements . . . . . . . . . . . . . 17 86 3.3. Roles in Building Solutions . . . . . . . . . . . . . . . 20 87 3.3.1. Modeler . . . . . . . . . . . . . . . . . . . . . . . 20 88 3.3.2. Reviewer . . . . . . . . . . . . . . . . . . . . . . . 20 89 3.3.3. Device Developer . . . . . . . . . . . . . . . . . . . 20 90 3.3.4. Application Developer . . . . . . . . . . . . . . . . 21 91 4. Modeling Considerations . . . . . . . . . . . . . . . . . . . 24 92 4.1. Default Values . . . . . . . . . . . . . . . . . . . . . . 24 93 4.2. Compliance . . . . . . . . . . . . . . . . . . . . . . . . 25 94 4.3. Data Distinctions . . . . . . . . . . . . . . . . . . . . 26 95 4.3.1. Background . . . . . . . . . . . . . . . . . . . . . . 26 96 4.3.2. Definitions . . . . . . . . . . . . . . . . . . . . . 27 97 4.3.3. Implications . . . . . . . . . . . . . . . . . . . . . 28 98 4.4. Direction . . . . . . . . . . . . . . . . . . . . . . . . 29 99 5. Security Considerations . . . . . . . . . . . . . . . . . . . 30 100 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 31 101 7. Normative References . . . . . . . . . . . . . . . . . . . . . 32 102 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 34 104 1. Origins of NETCONF and YANG 106 Networks are increasing in complexity and capacity, as well as the 107 density of the services deployed upon them. Uptime, reliability, and 108 predictable latency requirements drive the need for automation. The 109 problems with network management are not simple. They are complex 110 and intricate. But these problems must be solved for networks to 111 meet the stability needs of existing services while incorporating new 112 services in a world where the growth of networks is exhausting the 113 supply of qualified networking engineers. 115 In June of 2002, Internet Architecture Board (IAB) held a workshop on 116 Network Management ([RFC3535]). The members of this workshop made a 117 number of observations and recommendations for the IETF's 118 consideration concerning the issues operators were facing in their 119 network management-related work as well as issues they were having 120 with the direction of the IETF activities in this area. 122 The output of this workshop was focused on current problems. The 123 observations were reasonable and straight forward, including the need 124 for transactions, rollback, low implementation costs, and the ability 125 to save and restore the device's configuration data. Many of the 126 observations give insight into the problems operators were having 127 with existing network management solutions, such as the lack of full 128 coverage of device capabilities and the ability to distinguish 129 between configuration data and other types of data. 131 Based on these directions, the NETCONF working group was formed and 132 the Network Configuration (NETCONF) protocol was created. This 133 protocol defines a simple mechanism where network management 134 applications, acting as clients, can invoke operations on the 135 devices, which act as servers. The NETCONF specification ([RFC4741]) 136 defines a small set of operations, but goes out of its way to avoid 137 making any requirements on the data carried in those operations, 138 preferring to allow the protocol to carry any data. This "data model 139 agnostic" approach allows data models to be defined independently. 141 But lacking a means of defining data models, the NETCONF protocol was 142 not usable for standards-based work. Existing data modeling 143 languages such as the XML Schema Language (XSD) ([W3CXSD]) and the 144 Document Schema Definition Languages (DSDL) ([ISODSDL]) were 145 considered, but were rejected because the problem domains have little 146 natural overlap. Defining a data model or protocol that is encoded 147 in XML is a distinct problem from defining an XML document. The use 148 of NETCONF operations place requirements on the data content that are 149 not shared with the static document problem domain addressed by 150 schema languages like XSD or RELAX NG. 152 In 2007 and 2008, the issue of a data modeling language for NETCONF 153 was discussed in the OPS and APPS areas of IETF 70 and 71, and a 154 design team was tasked with creating a requirements document (expired 155 I-D draft-presuhn-rcdml-03.txt). After discussing the available 156 options at the CANMOD BoF at IETF71, the community wrote a charter 157 for the NETMOD working group. An excellent description of this time 158 period is available at 159 http://www.ietf.org/mail-archive/web/ietf/current/msg51644.html 161 In 2008 and 2009, the NETMOD working group produced a specification 162 for YANG ([RFCYANG]) as a means for defining data models for NETCONF, 163 allowing both standard and proprietary data models to be published in 164 a form that is easily digestible by human readers and satisfies many 165 of the issues raised in the IAB NM workshop. This brings NETCONF to 166 a point where is can be used to develop standard data models within 167 the IETF. 169 YANG allows a modeler to create a data model, to define the 170 organization of the data in that model, and to define constraints on 171 that data. Once published, the YANG module acts as a contract 172 between the client and server, with both parties understanding how 173 their peer will expect them to behave. A client knows how to create 174 valid data for the server, and knows what data will be sent from the 175 server. A server knows the rules that govern the data and how it 176 should behave. 178 YANG also incorporates a level of extensibility and flexibility not 179 present in other model languages. New modules can augment the data 180 hierarchies defined in other modules, seamlessly adding data at 181 appropriate places in the existing data organization. YANG also 182 allows new statements to be defined, allowing the language itself to 183 be expanded in a consistent way. 185 This document presents an architecture for YANG, describing how YANG- 186 related technologies work and how solutions built on them can address 187 the network management problem domain. 189 2. Elements of the Architecture 191 2.1. NETCONF 193 NETCONF defines an XML-based remote procedure call (RPC) mechanism 194 that leverages the simplicity and availability of high-quality XML 195 parsers. XML gives a rich, flexible, hierarchical, standard 196 representation of data that matches the needs of networking devices. 197 NETCONF carries configuration data and operations as requests and 198 replies using RPCs encoded in XML over a connection-oriented 199 transport. 201 XML's hierarchical data representation allows complex networking data 202 to be rendered in a natural way. For example, the following 203 configuration places interfaces in OSPF areas. The element 204 contains a list of elements, each of which contain a list of 205 elements. The element identifies the specific 206 area or interface. Additional configuration for each area or 207 interface appears directly inside the appropriate element. 209 211 212 0.0.0.0 214 215 ge-0/0/0.0 216 217 30 218 100 219 120 220 222 223 ge-0/0/1.0 224 140 225 226 228 229 10.1.2.0 231 232 ge-0/0/2.0 233 100 234 236 237 ge-0/0/3.0 238 140 239 120 240 241 242 244 NETCONF includes mechanisms for controlling configuration datastores. 245 Each datastore is a specific collection of configuration data that 246 can be used as source or target of the configuration-related 247 operations. The device can indicate whether it has a distinct 248 "startup" configuration datastore, whether the current or "running" 249 datastore is directly writable, or whether there is a "candidate" 250 configuration datastore where configuration changes can be made that 251 will not affect the device until a "commit-configuration" operation 252 is invoked. 254 NETCONF defines operations that are invoked as RPCs from the client 255 (the application) to the server (running on the device). The 256 following table lists some of these operations: 258 +---------------+---------------------------------------------------+ 259 | Operation | Description | 260 +---------------+---------------------------------------------------+ 261 | commit | Commits the "candidate" configuration to | 262 | | "running" | 263 | copy-config | Copy one configuration datastore to another | 264 | delete-config | Delete a configuration datastore | 265 | edit-config | Change the contents of a configuration datastore | 266 | get-config | Retrieve all or part of a configuration datastore | 267 | lock | Prevent changes to a datastore from another party | 268 | unlock | Release a lock on a datastore | 269 +---------------+---------------------------------------------------+ 271 NETCONF's "capability" mechanism allows the device to announce the 272 set of capabilities that the device supports, including protocol 273 operations, datastores, data models, and other abilities. These are 274 announced during session establishment as part of the 275 message. A client can inspect the hello message to determine what 276 the device is capable of and how to interact with the device to 277 perform the desired tasks. 279 NETCONF also defines a means of sending asynchronous notifications 280 from the server to the client, described in [RFC5277]. 282 In addition, NETCONF can fetch state data, receive notifications, and 283 invoke additional RPC methods defined as part of a capability. 284 Complete information about NETCONF can be found in [RFC4741]. 286 2.1.1. NETCONF Transport Mappings 288 NETCONF can run over any transport protocol that meets the 289 requirements defined in RFC4741, including 291 o connection-oriented operation 293 o authentication 295 o integrity 297 o confidentiality 299 [RFC4742] defines an mapping for the SSH ([RFC4251]) protocol, which 300 is the mandatory transport protocol. Others include SOAP 301 ([RFC4743]), BEEP ([RFC4744]), and TLS ([RFC5539]). 303 2.2. YANG 305 YANG is a data modeling language for NETCONF. It allows the 306 description of hierarchies of data nodes ("nodes") and the 307 constraints that exist among them. YANG defines data models and how 308 to manipulate those models via NETCONF protocol operations. 310 Each YANG module defines a data model, uniquely identified by a 311 namespace URI. These data models are extensible in a manner that 312 allows tight integration of standard data models and proprietary data 313 models. Models are built from organizational containers, lists of 314 data nodes and data node forming leafs of the data tree. 316 module example-ospf { 317 namespace "http://example.org/netconf/ospf"; 318 prefix ospf; 320 import network-types { // Access another module's def'ns 321 prefix nett; 322 } 324 container ospf { // Declare the top-level tag 325 list area { // Declare a list of "area" nodes 326 key name; // The key "name" identifies list members 327 leaf name { 328 type nett:area-id; 329 } 330 list interface { 331 key name; 332 leaf name { 333 type nett:interface-name; 334 } 335 leaf priority { 336 description "Designated router priority"; 337 type uint8; // The type is a constraint on 338 // valid values for "priority". 339 } 340 leaf metric { 341 type uint16 { 342 range 1..65535; 343 } 344 } 345 leaf dead-interval { 346 units seconds; 347 type uint16 { 348 range 1..65535; 349 } 350 } 351 } 352 } 353 } 354 } 356 A YANG module defines a data model in terms of the data, its 357 hierarchical organization, and the constraints on that data. YANG 358 defines how this data is represented in XML and how that data is used 359 in NETCONF operations. 361 The following table briefly describes some common YANG statements: 363 +--------------+----------------------------------------------------+ 364 | Statement | Description | 365 +--------------+----------------------------------------------------+ 366 | augment | Extends existing data hierarchies | 367 | choice | Defines mutually exclusive alternatives | 368 | container | Defines a layer of the data hierarchy | 369 | extension | Allows new statements to be added to YANG | 370 | feature | Indicates parts of the model are optional | 371 | grouping | Groups data definitions into reusable sets | 372 | key | Defines the key leafs for lists | 373 | leaf | Defines a leaf node in the data hierarchy | 374 | leaf-list | A leaf node that can appear multiple times | 375 | list | A hierarchy that can appear multiple times | 376 | notification | Defines notification | 377 | rpc | Defines input and output parameters for an RPC | 378 | | operation | 379 | typedef | Defines a new type | 380 | uses | Incorporates the contents of a "grouping" | 381 +--------------+----------------------------------------------------+ 383 2.2.1. Constraints 385 YANG allows the modeler to add constraints to the data model to 386 prevent impossible or illogical data. These constraints give clients 387 information about the data being sent from the device, and also allow 388 the client to know as much as possible about the data the device will 389 accept, so the client can send correct data. These constraints apply 390 to configuration data, but can also be used for rpc and notification 391 data. 393 The principal constraint is the "type" statement, which limits the 394 contents of a leaf node to that of the named type. The following 395 table briefly describes some other common YANG constraints: 397 +--------------+----------------------------------------------------+ 398 | Statement | Description | 399 +--------------+----------------------------------------------------+ 400 | length | Limits the length of a string | 401 | mandatory | Requires the node appear | 402 | max-elements | Limits the number of instances in a list | 403 | min-elements | Limits the number of instances in a list | 404 | must | XPath expression must be true | 405 | pattern | Regular expression must be satisfied | 406 | range | Value must appear in range | 407 | reference | Value must appear elsewhere in the data | 408 | unique | Value must be unique within the data | 409 | when | Node is only present when XPath expression is true | 410 +--------------+----------------------------------------------------+ 411 The "must" and "when" statements use XPath ([W3CXPATH]) expressions 412 to specify conditions that are semantically evaluated against the 413 data hierarchy, but neither the client nor the server are required to 414 implement the XPath specification. Instead they can use any means to 415 ensure these conditions are met. 417 2.2.2. Flexibility 419 YANG uses the "union" type and the "choice" and "feature" statements 420 to give modelers flexibility in defining their data models. The 421 "union" type allows a single leaf to accept multiple types, like an 422 integer or the word "unbounded": 424 type union { 425 type int32; 426 type enumeration { 427 enum "unbounded"; 428 } 429 } 431 The "choice" statement lists a set of mutually exclusive nodes, so a 432 valid configuration can choose any one node (or case). The "feature" 433 statement allows the modeler to identify parts of the model which can 434 be optional, and allows the device to indicate whether it implements 435 these optional portions. 437 The "deviation" statement allows the device, to indicate parts of a 438 YANG module which the device does not faithfully implement. While 439 devices are encouraged to fully abide according to the contract 440 presented in the YANG module, real world situations may force the 441 device to break the contract. Deviations give a means of declaring 442 this limitation, rather than leaving it to be discovered via run-time 443 errors. 445 2.2.3. Extensibility Model 447 XML includes the concept of namespaces, allowing XML elements from 448 different sources to be combined in the same hierarchy without 449 risking collision. YANG modules define content for specific 450 namespaces, but one module may augment the definition of another 451 module, introducing elements from that module's namespace into the 452 first module's hierarchy. 454 Since one module can augment another module's definition, hierarchies 455 of definitions are allowed to grow, as definitions from multiple 456 sources are added to the base hierarchy. These augmentations are 457 qualified using the namespace of the source module, helping to avoid 458 issues with name conflicts as the modules change over time. 460 For example, if the above OSPF configuration were the standard, a 461 vendor module may augment this with vendor-specific extensions. 463 module vendorx-ospf { 464 namespace "http://vendorx.example.com/ospf"; 465 prefix vendorx; 467 import example-ospf { 468 prefix ospf; 469 } 471 augment /ospf:ospf/ospf:area/ospf:interfaces { 472 leaf no-neighbor-down-notification { 473 type empty; 474 description "Don't inform other protocols about" 475 + " neighbor down events"; 476 } 477 } 478 } 480 The element is then placed in the 481 vendorx namespace: 483 486 487 0.0.0.0 489 490 ge-0/0/0.0 491 30 492 493 495 496 498 Augmentations are seamlessly integrated with base modules, allowing 499 them to be fetched, archived, loaded, and deleted within their 500 natural hierarchy. If a client application asks for the 501 configuration for a specific OSPF area, it will receive the sub- 502 hierarchy for that area, complete with any augmented data. 504 2.3. YANG Translations 506 The YANG data modeling language is the central piece of a group of 507 related technologies. The YANG language itself, described in 509 [RFCYANG], defines the syntax of the language and its statements, the 510 meaning of those statements, and how to combine them to build the 511 hierarchy of nodes that describe a data model. 513 That document also defines the "on the wire" XML content for NETCONF 514 operations on data models defined in YANG modules. This includes the 515 basic mapping between YANG data tree nodes and XML elements, as well 516 as mechanisms used in content to manipulate that data, 517 such as arranging the order of nodes within a list. 519 YANG uses a syntax that is regular and easily described, primarily 520 designed for human readability. YANG's syntax is friendly to email, 521 diff, patch, and the constraints of RFC formatting. 523 2.3.1. YIN 525 In some environments, incorporating a YANG parser may not be an 526 acceptable option. For those scenarios, an XML grammar for YANG is 527 defined as YIN (YANG Independent Notation). YIN allows the use of 528 XML parsers which are readily available in both open source and 529 commercial versions. Conversion between YANG and YIN is direct, 530 loss-less and reversible. YANG statements are converted to XML 531 elements, preserving the structure and content of YANG, but enabling 532 the use of off-the-shelf XML parsers rather than requiring the 533 integration of a YANG parser. YIN maintains complete semantic 534 equivalence with YANG. 536 2.3.2. DSDL (RELAX NG) 538 Since NETCONF content is encoded in XML, it is natural to use XML 539 schema languages for their validation. To facilitate this, YANG 540 offers a standardized mapping of YANG modules into Document Schema 541 Description Languages ([RFCYANGDSDL]), of which RELAX NG is a major 542 component. 544 DSDL is considered to be the best choice as a standard schema 545 language because it addresses not only grammar and datatypes of XML 546 documents but also semantic constraints and rules for modifying the 547 information set of the document. 549 In addition, DSDL offers formal means for coordinating multiple 550 independent schemas and specifying how to apply the schemas to the 551 various parts of the document. This is useful since YANG content is 552 typically composed of multiple vocabularies. 554 2.4. YANG Types 556 YANG supports a number of builtin types, and allows additional types 557 to be derived from those types in an extensible manner. New types 558 can add additional restrictions to allowable data values. 560 A standard type library for use by YANG is available [RFCYANGTYPES]. 561 These YANG modules define commonly used data types for IETF-related 562 standards. 564 2.5. IETF Guidelines 566 A set of additional guidelines are defined that indicate desirable 567 usage for authors and reviewers of standards track specifications 568 containing YANG data model modules ([RFCYANGUSAGE]). These 569 guidelines should be used as a basis for reviews of other YANG data 570 model documents. 572 3. Working with YANG 574 3.1. Building NETCONF- and YANG-based Solutions 576 In the typical YANG-based solution, the client and server are driven 577 by the content of YANG modules. The server includes the definitions 578 of the modules as meta-data that is available to the NETCONF engine. 579 This engine processes incoming requests, uses the meta-data to parse 580 and verify the request, performs the requested operation, and returns 581 the results to the client. 583 +----------------------------+ 584 |Server (device) | 585 | +--------------------+ | 586 | | configuration | | 587 +----+ | | ---------------| | 588 |YANG|+ | | m d state data | | 589 |mods||+ | | e a ---------------| | 590 +----+|| -----> | t t notifications | | 591 +----+| | | a a ---------------| | 592 +----+ | | operations | | 593 | +--------------------+ | 594 | ^ | 595 | | | 596 | v | 597 +------+ | +-------------+ | 598 | | -------------> | | | 599 |Client| | | NETCONF | | 600 | (app)| | | engine | | 601 | | <------------ | | | 602 +------+ +-------------+ | 603 | / \ | 604 | / \ | 605 | / \ | 606 | +--------+ +---------+ | 607 | | config | |system |+ | 608 | | data- | |software ||+ | 609 | | base | |component||| | 610 | +--------+ +---------+|| | 611 | +---------+| | 612 | +---------+ | 613 +----------------------------+ 615 To use YANG, YANG modules must be defined to model the specific 616 problem domain. These modules are then loaded, compiled, or coded 617 into the server. 619 The sequence of events for the typical client/server interaction may 620 be as follows: 622 o A client application ([C]) opens a NETCONF session to the server 623 (device) ([S]) 625 o [C] and [S] exchange messages containing the list of 626 capabilities supported by each side, allowing [C] to learn the 627 modules supported by [S] 629 o [C] builds and sends an operation defined in the YANG module, 630 encoded in XML, within NETCONF's element 632 o [S] receives and parses the element 634 o [S] verifies the contents of the request against the data model 635 defined in the YANG module 637 o [S] performs the requested operation, possibly changing the 638 configuration datastore 640 o [S] builds the response, containing the response, any requested 641 data, and any errors 643 o [S] sends the response, encoded in XML, within NETCONF's 644 element 646 o [C] receives and parses the element 648 o [C] inspects the response and processes it as needed 650 Note that there is no requirement for the client or server to process 651 the YANG modules in this way. The server may hard code the contents 652 of the data model, rather than handle the content via a generic 653 engine. Or the client may be targeted at the specific YANG model, 654 rather than being driven generically. Such a client might be a 655 simple shell script that stuffs arguments into an XML payload 656 template and sends it to the server. 658 3.2. Addressing Operator Requirements 660 NETCONF and YANG address many of the issues raised in the IAB NM 661 workshop. 663 o Ease of use: YANG is designed to be human friendly, simple and 664 readable. Many tricky issues remain due to the complexity of the 665 problem domain, but YANG strives to make them more visible and 666 easier to deal with. 668 o Configuration and state data: YANG clearly divides configuration 669 data from other types of data. 671 o Transactions: NETCONF provides a simple transaction mechanism. 673 o Generation of deltas: A YANG module gives enough information to 674 generate the delta needed to change between two configuration data 675 sets. 677 o Dump and restore: NETCONF gives the ability to save and restore 678 configuration data. This can also performed for a specific YANG 679 module. 681 o Network-wide configuration: NETCONF supports robust network-wide 682 configuration transactions via the commit and confirmed-commit 683 capability. When a change is attempted that affects multiple 684 devices, these capabilities simplifies the management of failure 685 scenarios, resulting in the ability to have transactions that will 686 dependably succeed or fail atomically. 688 o Text-friendly: YANG modules are very text friendly, as is the data 689 they define. 691 o Configuration handling: NETCONF addresses the ability to 692 distinguish between distributing configuration data and activating 693 it. 695 o Task-oriented: A YANG module can define specific tasks as RPC 696 operations. A client can choose to invoke the RPC operation or to 697 access any underlying data directly. 699 o Full coverage: YANG modules can be defined that give full coverage 700 to all the native abilities of the device. Giving this access 701 avoids the need to resort to the command line interface (CLI) 702 using tools such as Expect ([SWEXPECT]). 704 o Timeliness: YANG modules can be tied to CLI operations, so all 705 native operations and data are immediately available. 707 o Implementation difficulty: YANG's flexibility enables modules that 708 can be more easily implemented. Adding "features" and replacing 709 "third normal form" with a natural data hierarchy should reduce 710 complexity. 712 o Simple data modeling language: YANG has sufficient power to be 713 usable in other situations. In particular, on-box API and native 714 CLI can be integrated to achieve simplification of the 715 infrastructure. 717 o Internationalization: YANG uses UTF-8 ([RFC3629]) encoded unicode 718 characters. 720 o Event correlation: YANG integrates RPC operations, notification, 721 configuration and state data, enabling internal references. For 722 example, a field in a notification can be tagged as pointing to a 723 BGP peer, and the client application can easily find that peer in 724 the configuration data. 726 o Implementation costs: Significant effort has been made to keep 727 implementation costs as low as possible. 729 o Human friendly syntax: YANG's syntax is optimized for the reader, 730 specifically the reviewer on the basis that this is the most 731 common human interaction. 733 o Post-processing: Use of XML will maximize the opportunities for 734 post-processing of data, possibly using XML-based technologies 735 like XPath ([W3CXPATH], XQuery ([W3CXQUERY]), and XSLT 736 ([W3CXSLT]). 738 o Semantic mismatch: Richer, more descriptive data models will 739 reduce the possibility of semantic mismatch. With the ability to 740 define new primitives, YANG modules will be more specific in 741 content, allowing more enforcement of rules and constraints. 743 o Security: NETCONF runs over transport protocols secured by SSH or 744 TLS, allowing secure communications and authentication using well- 745 trusted technology. The secure transport can use existing key and 746 credential management infrastructure, reducing deployment costs. 748 o Reliable: NETCONF and YANG are solid and reliable technologies. 749 NETCONF is connection based, and includes automatic recovery 750 mechanisms when the connection is lost. 752 o Delta friendly: YANG-based models support operations that are 753 delta friendly. Add, change, insert, and delete operations are 754 all well defined. 756 o Method-oriented: YANG allows new RPC operations to be defined, 757 including an operation name, which is essentially a method. The 758 input and output parameters of the RPC operations are also defined 759 in the YANG module. 761 3.3. Roles in Building Solutions 763 Building NETCONF- and YANG-based solutions requires interacting with 764 many distinct groups. Modelers must understand how to build useful 765 models that give structure and meaning to data while maximizing the 766 flexibility of that data to "future proof" their work. Reviewers 767 need to quickly determine if that structure is accurate. Device 768 developers need to code that data model into their devices, and 769 application developers need to code their applications to take 770 advantage of that data model. There are a variety of strategies for 771 performing each piece of this work. This section discusses some of 772 those strategies. 774 3.3.1. Modeler 776 The modeler defines a data model based on their in-depth knowledge of 777 the problem domain being modeled. This model should be as simple as 778 possible, but should balance complexity with expressiveness. The 779 organization of the model should target not only the current model, 780 but should allow for extensibility from other modules and for 781 adaptability to future changes. 783 Additional modeling issues are discussed in Section 4. 785 3.3.2. Reviewer 787 The reviewer role is perhaps the most important and the time 788 reviewers are willing to give is precious. To help the reviewer, 789 YANG stresses readability, with a human-friendly syntax, natural data 790 hierarchy, and simple, concise statements. 792 3.3.3. Device Developer 794 The YANG model tells the device developer what data is being modeled. 795 The developer reads the YANG models and writes code that supports the 796 model. The model describes the data hierarchy and associated 797 constraints, and the description and reference material helps the 798 developer understand how to transform the models view into the 799 device's native implementation. 801 3.3.3.1. Generic Content Support 803 The YANG model can be compiled into a YANG-based engine for either 804 the client or server side. Incoming data can be validated, as can 805 outgoing data. The complete configuration datastore may be validated 806 in accordance with the constraints described in the data model. 808 Serializers and deserializers for generating and receiving NETCONF 809 content can be driven by the meta-data in the model. As data is 810 received, the meta-data is consulted to ensure the validity of 811 incoming XML elements. 813 3.3.3.2. XML Definitions 815 The YANG module dictates the XML encoding for data sent via NETCONF. 816 The rules that define the encoding are fixed, so the YANG module can 817 be used to ascertain whether a specific NETCONF payload is obeying 818 the rules. 820 3.3.4. Application Developer 822 The YANG module tells the application developer what data can be 823 modeled. Developers can inspect the modules and take one of three 824 distinct views. In this section, we will consider them and the 825 impact of YANG on their design. In the real world, most applications 826 are a mixture of these approaches. 828 3.3.4.1. Hard Coded 830 An application can be coded against the specific, well-known contents 831 of YANG modules, implementing their organization, rules, and logic 832 directly with explicit knowledge. For example, a script could be 833 written to change the domain name of a set of devices using a 834 standard YANG module that includes such a leaf node. This script 835 takes the new domain name as an argument and inserts it into a string 836 containing the rest of the XML encoding as required by the YANG 837 module. This content is then sent via NETCONF to each of the 838 devices. 840 This type of application is useful for small, fixed problems where 841 the cost and complexity of flexibility is overwhelmed by the ease of 842 hard coding direct knowledge into the application. 844 3.3.4.2. Bottom Up 846 An application may take a generic, bottom up approach to 847 configuration, concentrating on the device's data directly and 848 treating that data without specific understanding. 850 YANG modules may be used to drive the operation of the YANG 851 equivalent of a "MIB Browser". Such an application manipulates the 852 device's configuration data based on the data organization contained 853 in the YANG module. For example, a GUI may present a straight- 854 forward visualization where elements of the YANG hierarchy are 855 depicted in a hierarchy of folders or GUI panels. Clicking on a line 856 expands to the contents of the matching XML hierarchy. 858 This type of GUI can easily be built by generating XSLT stylesheets 859 from the YANG data models. An XSLT engine can then be used to turn 860 configuration data into a set of web pages. 862 The YANG modules allow the application to enforce a set of 863 constraints without understanding the semantics of the YANG module. 865 3.3.4.3. Top Down 867 In contrast to the bottom-up approach, the top-down approach allows 868 the application to take a view of the configuration data which is 869 distinct from the standard and/or proprietary YANG modules. The 870 application is free to construct its own model for data organization 871 and to present this model to the user. When the application needs to 872 transmit data to a device, the application transforms its data from 873 the problem-oriented view of the world into the data needed for that 874 particular device. This transformation is under the control and 875 maintenance of the application, allowing the transformation to be 876 changed and updated without affecting the device. 878 For example, an application could be written that models VPNs in a 879 network-oriented view. The application would need to transform these 880 high-level VPN definitions into the configuration data that would be 881 handed to any particular device within a VPN. 883 Even in this approach, YANG is useful since it can be used to model 884 the VPN. For example, the following VPN straw-man models a list of 885 VPNs, each with a protocol, a topology, a list of member interfaces, 886 and a list of classifiers. 888 list example-bgpvpn { 889 key name; 890 leaf name { ... } 891 leaf protocol { 892 type enumeration { 893 enum bgpvpn; 894 enum l2vpn; 895 } 896 } 897 leaf topology { 898 type enumeration { 899 enum hub-n-spoke; 900 enum mesh; 901 } 902 } 903 list members { 904 key "device interface"; 905 leaf device { ... } 906 leaf interface { ... } 907 } 908 list classifiers { 909 ... 910 } 911 } 913 The application can use such a YANG module to drive its operation, 914 building VPN instances in a database and then pushing the 915 configuration for those VPNs to individual devices using either a 916 standard device model (e.g. example-bgpvpn.yang) or by transforming 917 that standard device content into some proprietary format for devices 918 that do not support that standard. 920 4. Modeling Considerations 922 This section discusses considerations the modeler should be aware of 923 while developing models in YANG. 925 4.1. Default Values 927 The concept of default values is simple, but their details, 928 representation, and interaction with configuration data can be 929 difficult issues. NETCONF leaves default values as a data model 930 issue, and YANG gives flexibility to the device implementation in 931 terms of how default values are handled. The requirement is that the 932 device "MUST operationally behave as if the leaf was present in the 933 data tree with the default value as its value". This gives the 934 device implementation choices in how default values are handled. 936 One choice is to view the configuration as a set of instructions for 937 how the device should be configured. If a data value that is given 938 as part of those instructions is the default value, then it should be 939 retained as part of the configuration, but if it is not explicitly 940 given, then the value is not considered to be part of configuration. 942 Another choice is to trim values that are identical to the default 943 values, implicitly removing them from the configuration datastore. 944 The act of setting a leaf to its default value effectively deletes 945 that leaf. 947 The device could also choose to report all default values, regardless 948 of whether they were explicitly set. This choice eases the work of a 949 client that needs default values, but may significantly increase the 950 size of the configuration data. 952 These choices reflect the default handling schemes of widely deployed 953 networking devices and supporting them allows YANG to reduce 954 implementation and deployment costs of YANG-based models. 956 When the client retrieves data from the device, it must be prepared 957 to handle the absence of leaf nodes with the default value, since the 958 server is not required to send such leaf elements. This permits the 959 device to implement either of the first two default handling schemes 960 given above. 962 Regardless of the implementation choice, the device can support the 963 "with-defaults" capability ([RFCWITHDEFAULTS]) and give the client 964 the ability to select the desired handling of default values. 966 When evaluating the XPath expressions for constraints like "must" and 967 "when", the evaluation context for the expressions will include any 968 appropriate default values, so the modeler can depend on consistent 969 behavior from all devices. 971 4.2. Compliance 973 In developing good data models, there are many conflicting interests 974 the data modeler must keep in mind. Modelers need to be aware of 975 five issues with models and devices: 977 o usefulness 979 o compliance 981 o flexibility 983 o extensibility 985 o deviations 987 For a model to be interesting, it must be useful, solving a problem 988 in a more direct or more powerful way than can be accomplished 989 without the model. The model should maximize the usefulness of the 990 model with in the problem domain. 992 Modelers should build models that maximize the number of devices that 993 can faithfully implement the model. If the model is drawn too 994 narrowly, or includes too many assumptions about the device, then the 995 difficulty and cost of accurately implementing the model will lead to 996 low quality implementations, interoperability issues, and will reduce 997 the value of the model. 999 Modelers can use the "feature" statement in their models to give the 1000 device some flexibility by partitioning their model and allowing the 1001 device to indicate which portions of the model are implemented on the 1002 device. For example, if the model includes some a "logging" feature 1003 , a device with no storage facilities for the log can tell the client 1004 that it does not support this feature of the model. 1006 Models can be extended via the "augment" statement, and the modeler 1007 should consider how their model is likely to be extended. These 1008 augmentations can be defined by vendors, applications, or standards 1009 bodies. 1011 Deviations are a means of allowing the devices to indicate where its 1012 implementation is not in full compliance with the model. For 1013 example, once a model is published, an implementer may decide to make 1014 a particular node configurable, where the standard model describes it 1015 as state data. The implementation reports the value normally and may 1016 declare a deviation that this device behaves in a different manner 1017 than the standard. Applications capable of discovering this 1018 deviation can make allowances, but applications that do not discover 1019 the deviation can continue treating the implementation as if it were 1020 compliant. 1022 Rarely, implementations may make decisions that prevent compliance 1023 with the standard. Such occasions are regrettable, but they remain a 1024 part of reality, and modelers and application writers ignore them at 1025 their own risk. An implementation that emits an integer leaf as 1026 "cow" would be difficult to manage, but applications should expect to 1027 encounter such misbehaving devices in the field. 1029 Despite this, both client and server should view the YANG module as a 1030 contract, with both sides agreeing to abide by the terms. The 1031 modeler should be explicit about the terms of such a contract, and 1032 both client and server implementations should strive to faithfully 1033 and accurately implement the data model described in the YANG module. 1035 4.3. Data Distinctions 1037 The distinction between configuration data, operational state data, 1038 and statistics is important to understand for data model writers and 1039 people who plan to extend the NETCONF protocol. This section first 1040 discusses some background and then provides a definition and some 1041 examples. 1043 4.3.1. Background 1045 During the IAB NM workshop, operators did formulate the following two 1046 requirements: 1048 2. It is necessary to make a clear distinction between 1049 configuration data, data that describes operational state 1050 and statistics. Some devices make it very hard to determine 1051 which parameters were administratively configured and which 1052 were obtained via other mechanisms such as routing 1053 protocols. 1055 3. It is required to be able to fetch separately configuration 1056 data, operational state data, and statistics from devices, 1057 and to be able to compare these between devices. 1059 The NETCONF protocol defined in RFC 4741 distinguishes two types of 1060 data, namely configuration data and state data: 1062 Configuration data is the set of writable data that is 1063 required to transform a system from its initial default state 1064 into its current state. 1066 State data is the additional data on a system that is not 1067 configuration data such as read-only status information and 1068 collected statistics. 1070 NETCONF does not follow the distinction formulated by the operators 1071 between configuration data, operational state data, and statistical 1072 data, since it considers state data to include both statistics and 1073 operational state data. 1075 4.3.2. Definitions 1077 Below is a definition for configuration data, operational state data, 1078 and statistical data. The definition borrows from previous work. 1080 o Configuration data is the set of writable data that is required to 1081 transform a system from its initial default state into its current 1082 state. [RFC4741] 1084 o Operational state data is a set of data that has been obtained by 1085 the system at runtime and influences the system's behaviour 1086 similar to configuration data. In contrast to configuration data, 1087 operational state is transient and modified by interactions with 1088 internal components or other systems via specialized protocols. 1090 o Statistical data is the set of read-only data created by a system 1091 itself. It describes the performance of the system and its 1092 components. 1094 The following examples help to clarify the difference between 1095 configuration data, operational state data and statistical data. 1097 4.3.2.1. Example 1: IP Routing Table 1099 IP routing tables can contain entries that are statically configured 1100 (configuration data) as well as entries obtained from routing 1101 protocols such as OSPF (operational state data). In addition, a 1102 routing engine might collect statistics like how often a particular 1103 routing table entry has been used. 1105 4.3.2.2. Example 2: Interfaces 1107 Network interfaces usually come with a large number of attributes 1108 that are specific to the interface type and in some cases specific to 1109 the cable plugged into an interface. Examples are the maximum 1110 transmission unit of an interface or the speed detected by an 1111 Ethernet interface. 1113 In many deployments, systems use the interface attributes detected 1114 when an interface is initialized. As such, these attributes 1115 constitute operational state. However, there are usually provisions 1116 to overwrite the discovered attributes with static configuration 1117 data, like for example configuring the interface MTU to use a 1118 specific value or forcing an Ethernet interface to run at a given 1119 speed. 1121 The system will record statistics (counters) measuring the number of 1122 packets, bytes, and errors received and transmitted on each 1123 interface. 1125 4.3.2.3. Example 3: Account Information 1127 Systems usually maintain static configuration information about the 1128 accounts on the system. In addition, systems can obtain information 1129 about accounts from other sources (e.g. LDAP, NIS) dynamically, 1130 leading to operational state data. Information about account usage 1131 are examples of statistic data. 1133 Note that configuration data supplied to a system in order to create 1134 a new account might be supplemented with additional configuration 1135 information determined by the system when the account is being 1136 created (such as a unique account id). Even though the system might 1137 create such information, it usually becomes part of the static 1138 configuration of the system since this data is not transient. 1140 4.3.3. Implications 1142 The primary focus of YANG is configuration data. There is no single 1143 mechanism defined for the separation of operational state data and 1144 statistics since NETCONF treats them both as state data. This 1145 section describes several different options for addressing this 1146 issue. 1148 4.3.3.1. Data Models 1150 The first option is to have data models that explicitly differentiate 1151 between configuration data and operational state data. This leads to 1152 duplication of data structures and might not scale well from a 1153 modeling perspective. 1155 For example, the configured duplex value and the operational duplex 1156 value would be distinct leafs in the data model. 1158 4.3.3.2. Additional Operations to Retrieve Operational State 1160 The NETCONF protocol can be extended with new protocol operations 1161 that specifically allow the retrieval of all operational state, e.g. 1162 by introducing a operation (and perhaps also a 1163 operation). 1165 4.3.3.3. Introduction of an Operational State Datastore 1167 Another option could be to introduce a new "configuration" data store 1168 that represents the operational state. A operation on 1169 the data store would then return the operational state 1170 determining the behaviour of the box instead of its static and 1171 explicit configuration state. 1173 4.4. Direction 1175 At this time, the only viable solution is to distinctly model the 1176 configuration and operational values. The configuration leaf would 1177 indicate the desired value, as given by the user, and the operational 1178 leaf would indicate the current value, as observed on the device. 1180 In the duplex example, this would result in two distinct leafs being 1181 defined, "duplex" and "op-duplex", one with "config true" and one 1182 with "config false". 1184 In some cases, distinct leafs would be used, but in others, distinct 1185 lists might be used. Distinct lists allows the list to be organized 1186 in different ways, with different constraints. Keys, sorting, and 1187 constraint statements like must, unique, or when may differ between 1188 configuration data and operational data. 1190 For example, configured static routes might be a distinct list from 1191 the operational routing table, since the use of keys and sorting 1192 might differ. 1194 5. Security Considerations 1196 This document discusses an architecture for network management using 1197 NETCONF and YANG. It has no security impact on the Internet. 1199 6. IANA Considerations 1201 This document has no actions for IANA. 1203 7. Normative References 1205 [ISODSDL] International Organization for Standardization, "Document 1206 Schema Definition Languages (DSDL) - Part 1: Overview", 1207 ISO/IEC 19757-1, November 2004. 1209 [RFC3535] Schoenwaelder, J., "Overview of the 2002 IAB Network 1210 Management Workshop", RFC 3535, May 2003. 1212 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 1213 10646", STD 63, RFC 3629, November 2003. 1215 [RFC4251] Ylonen, T. and C. Lonvick, "The Secure Shell (SSH) 1216 Protocol Architecture", RFC 4251, January 2006. 1218 [RFC4741] Enns, R., "NETCONF Configuration Protocol", RFC 4741, 1219 December 2006. 1221 [RFC4742] Wasserman, M. and T. Goddard, "Using the NETCONF 1222 Configuration Protocol over Secure SHell (SSH)", RFC 4742, 1223 December 2006. 1225 [RFC4743] Goddard, T., "Using NETCONF over the Simple Object Access 1226 Protocol (SOAP)", RFC 4743, December 2006. 1228 [RFC4744] Lear, E. and K. Crozier, "Using the NETCONF Protocol over 1229 the Blocks Extensible Exchange Protocol (BEEP)", RFC 4744, 1230 December 2006. 1232 [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event 1233 Notifications", RFC 5277, July 2008. 1235 [RFC5539] Badra, M., "NETCONF over Transport Layer Security (TLS)", 1236 RFC 5539, May 2009. 1238 [RFCWITHDEFAULTS] 1239 Bierman, A. and B. Lengyel, "With-defaults capability for 1240 NETCONF", draft-ietf-netconf-with-defaults-11.txt (work in 1241 progress). 1243 [RFCYANG] Bjorklund, M., Ed., "YANG - A data modeling language for 1244 the Network Configuration Protocol (NETCONF)", 1245 draft-ietf-netmod-yang-13 (work in progress). 1247 [RFCYANGDSDL] 1248 Lhotka, L., Mahy, R., and S. Chishom, "Mapping YANG to 1249 Document Schema Definition Languages and Validating 1250 NETCONF Content", draft-ietf-netmod-dsdl-map-07 (work in 1251 progress). 1253 [RFCYANGTYPES] 1254 Schoenwaelder, J., "Common YANG Data Types", 1255 draft-ietf-netmod-yang-types-09.txt (work in progress). 1257 [RFCYANGUSAGE] 1258 Bierman, A., "Guidelines for Authors and Reviewers of YANG 1259 Data Model Documents", draft-ietf-netmod-yang-usage-10.txt 1260 (work in progress). 1262 [SWEXPECT] 1263 "The Expect Home Page", . 1265 [W3CXPATH] 1266 DeRose, S. and J. Clark, "XML Path Language (XPath) 1267 Version 1.0", World Wide Web Consortium 1268 Recommendation REC-xpath-19991116, November 1999, 1269 . 1271 [W3CXQUERY] 1272 Boag, S., "XQuery 1.0: An XML Query Language", W3C WD WD- 1273 xquery-20050915, September 2005. 1275 [W3CXSD] Walmsley, P. and D. Fallside, "XML Schema Part 0: Primer 1276 Second Edition", World Wide Web Consortium 1277 Recommendation REC-xmlschema-0-20041028, October 2004, 1278 . 1280 [W3CXSLT] Clark, J., "XSL Transformations (XSLT) Version 1.0", World 1281 Wide Web Consortium Recommendation REC-xslt-19991116, 1282 November 1999, 1283 . 1285 Author's Address 1287 Phil Shafer 1288 Juniper Networks 1290 Email: phil@juniper.net