idnits 2.17.1 draft-ietf-rtgwg-policy-model-08.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 : ---------------------------------------------------------------------------- == There are 4 instances of lines with private range IPv4 addresses in the document. If these are generic example addresses, they should be changed to use any of the ranges defined in RFC 6890 (or successor): 192.0.2.x, 198.51.100.x or 203.0.113.x. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 280 has weird spacing: '...h-lower uin...' == Line 281 has weird spacing: '...h-upper uin...' == Line 469 has weird spacing: '...h-lower uin...' == Line 470 has weird spacing: '...h-upper uin...' == Line 482 has weird spacing: '...et-name str...' == (1 more instance...) == The document doesn't use any RFC 2119 keywords, yet seems to have RFC 2119 boilerplate text. -- The document date (January 2, 2020) is 1568 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Unused Reference: 'I-D.ietf-netmod-sub-intf-vlan-model' is defined on line 1410, but no explicit reference was found in the text == Outdated reference: A later version (-13) exists of draft-ietf-netmod-intf-ext-yang-08 == Outdated reference: A later version (-10) exists of draft-ietf-netmod-sub-intf-vlan-model-06 == Outdated reference: A later version (-17) exists of draft-ietf-idr-bgp-model-07 Summary: 0 errors (**), 0 flaws (~~), 13 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 RTGWG Y. Qu 3 Internet-Draft Futurewei 4 Intended status: Standards Track J. Tantsura 5 Expires: July 5, 2020 Apstra 6 A. Lindem 7 Cisco 8 X. Liu 9 Volta Networks 10 January 2, 2020 12 A YANG Data Model for Routing Policy Management 13 draft-ietf-rtgwg-policy-model-08 15 Abstract 17 This document defines a YANG data model for configuring and managing 18 routing policies in a vendor-neutral way and based on actual 19 operational practice. The model provides a generic policy framework 20 which can be augmented with protocol-specific policy configuration. 22 Status of This Memo 24 This Internet-Draft is submitted in full conformance with the 25 provisions of BCP 78 and BCP 79. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF). Note that other groups may also distribute 29 working documents as Internet-Drafts. The list of current Internet- 30 Drafts is at https://datatracker.ietf.org/drafts/current/. 32 Internet-Drafts are draft documents valid for a maximum of six months 33 and may be updated, replaced, or obsoleted by other documents at any 34 time. It is inappropriate to use Internet-Drafts as reference 35 material or to cite them other than as "work in progress." 37 This Internet-Draft will expire on July 5, 2020. 39 Copyright Notice 41 Copyright (c) 2020 IETF Trust and the persons identified as the 42 document authors. All rights reserved. 44 This document is subject to BCP 78 and the IETF Trust's Legal 45 Provisions Relating to IETF Documents 46 (https://trustee.ietf.org/license-info) in effect on the date of 47 publication of this document. Please review these documents 48 carefully, as they describe your rights and restrictions with respect 49 to this document. Code Components extracted from this document must 50 include Simplified BSD License text as described in Section 4.e of 51 the Trust Legal Provisions and are provided without warranty as 52 described in the Simplified BSD License. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 57 1.1. Goals and approach . . . . . . . . . . . . . . . . . . . 3 58 2. Terminology and Notation . . . . . . . . . . . . . . . . . . 3 59 2.1. Tree Diagrams . . . . . . . . . . . . . . . . . . . . . . 4 60 2.2. Prefixes in Data Node Names . . . . . . . . . . . . . . . 4 61 3. Model overview . . . . . . . . . . . . . . . . . . . . . . . 5 62 4. Route policy expression . . . . . . . . . . . . . . . . . . . 5 63 4.1. Defined sets for policy matching . . . . . . . . . . . . 6 64 4.2. Policy conditions . . . . . . . . . . . . . . . . . . . . 7 65 4.3. Policy actions . . . . . . . . . . . . . . . . . . . . . 8 66 4.4. Policy subroutines . . . . . . . . . . . . . . . . . . . 9 67 5. Policy evaluation . . . . . . . . . . . . . . . . . . . . . . 10 68 6. Applying routing policy . . . . . . . . . . . . . . . . . . . 10 69 7. Routing protocol-specific policies . . . . . . . . . . . . . 11 70 8. Security Considerations . . . . . . . . . . . . . . . . . . . 13 71 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13 72 10. YANG modules . . . . . . . . . . . . . . . . . . . . . . . . 14 73 10.1. Routing policy model . . . . . . . . . . . . . . . . . . 14 74 11. Policy examples . . . . . . . . . . . . . . . . . . . . . . . 31 75 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 31 76 12.1. Normative references . . . . . . . . . . . . . . . . . . 31 77 12.2. Informative references . . . . . . . . . . . . . . . . . 32 78 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 32 79 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 33 81 1. Introduction 83 This document describes a YANG [RFC6020] [RFC7950] data model for 84 routing policy configuration based on operational usage and best 85 practices in a variety of service provider networks. The model is 86 intended to be vendor-neutral, in order to allow operators to manage 87 policy configuration in a consistent, intuitive way in heterogeneous 88 environments with routers supplied by multiple vendors. 90 The YANG modules in this document conform to the Network Management 91 Datastore Architecture (NMDA) [RFC8342]. 93 1.1. Goals and approach 95 This model does not aim to be feature complete -- it is a subset of 96 the policy configuration parameters available in a variety of vendor 97 implementations, but supports widely used constructs for managing how 98 routes are imported, exported, and modified across different routing 99 protocols. The model development approach has been to examine actual 100 policy configurations in use across a number of operator networks. 101 Hence the focus is on enabling policy configuration capabilities and 102 structure that are in wide use. 104 Despite the differences in details of policy expressions and 105 conventions in various vendor implementations, the model reflects the 106 observation that a relatively simple condition-action approach can be 107 readily mapped to several existing vendor implementations, and also 108 gives operators an intuitive and straightforward way to express 109 policy without sacrificing flexibility. A side affect of this design 110 decision is that legacy methods for expressing policies are not 111 considered. Such methods could be added as an augmentation to the 112 model if needed. 114 Consistent with the goal to produce a data model that is vendor 115 neutral, only policy expressions that are deemed to be widely 116 available in existing major implementations are included in the 117 model. Those configuration items that are only available from a 118 single implementation are omitted from the model with the expectation 119 they will be available in separate vendor-provided modules that 120 augment the current model. 122 2. Terminology and Notation 124 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 125 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 126 "OPTIONAL" in this document are to be interpreted as described in BCP 127 14 [RFC2119] [RFC8174] when, and only when, they appear in all 128 capitals, as shown here. 130 The following terms are defined in [RFC8342]: 132 o client 134 o server 136 o configuration 138 o system state 140 o operational state 141 o intended configuration 143 The following terms are defined in [RFC7950]: 145 o action 147 o augment 149 o container 151 o container with presence 153 o data model 155 o data node 157 o feature 159 o leaf 161 o list 163 o mandatory node 165 o module 167 o schema tree 169 o RPC (Remote Procedure Call) operation 171 2.1. Tree Diagrams 173 Tree diagrams used in this document follow the notation defined in 174 [RFC8340]. 176 2.2. Prefixes in Data Node Names 178 In this document, names of data nodes, actions, and other data model 179 objects are often used without a prefix, as long as it is clear from 180 the context in which YANG module each name is defined. Otherwise, 181 names are prefixed using the standard prefix associated with the 182 corresponding YANG module, as shown in Table 1. 184 +-----------+------------------+------------------------------------+ 185 | Prefix | YANG module | Reference | 186 +-----------+------------------+------------------------------------+ 187 | if | ietf-interfaces | [RFC8343] | 188 | | | | 189 | rt | ietf-routing | [RFC8349] | 190 | | | | 191 | yang | ietf-yang-types | [RFC6991] | 192 | | | | 193 | inet | ietf-inet-types | [RFC6991] | 194 | | | | 195 | if-ext | ietf-if- | [I-D.ietf-netmod-intf-ext-yang] | 196 | | extensions | | 197 | | | | 198 | if-l3-vla | ietf-if-l3-vlan | [I-D.ietf-netmod-sub-intf-vlan-mod | 199 | n | | el] | 200 +-----------+------------------+------------------------------------+ 202 Table 1: Prefixes and Corresponding YANG Modules 204 3. Model overview 206 The routing policy module has three main parts: 208 o A generic framework to express policies as sets of related 209 conditions and actions. This includes match sets and actions that 210 are useful across many routing protocols. 212 o A structure that allows routing protocol models to add protocol- 213 specific policy conditions and actions though YANG augmentations. 214 There is a complete example of this for BGP [RFC4271] policies in 215 the proposed vendor-neutral BGP data model 216 [I-D.ietf-idr-bgp-model]. 218 o A reusable grouping for attaching import and export rules in the 219 context of routing configuration for different protocols, VRFs, 220 etc. This also enables creation of policy chains and expressing 221 default policy behavior. 223 The module makes use of the standard Internet types, such as IP 224 addresses, autonomous system numbers, etc., defined in RFC 6991 225 [RFC6991]. 227 4. Route policy expression 229 Policies are expressed as a sequence of top-level policy definitions 230 each of which consists of a sequence of policy statements. Policy 231 statements in turn consist of simple condition-action tuples. 233 Conditions may include multiple match or comparison operations, and 234 similarly, actions may effect multiple changes to route attributes, 235 or indicate a final disposition of accepting or rejecting the route. 236 This structure is shown below. 238 +--rw routing-policy 239 +--rw policy-definitions 240 +--rw policy-definition* [name] 241 +--rw name string 242 +--rw statements 243 +--rw statement* [name] 244 +--rw name string 245 +--rw conditions 246 | ... 247 +--rw actions 248 ... 250 4.1. Defined sets for policy matching 252 The models provides a set of generic sets that can be used for 253 matching in policy conditions. These sets are applicable for route 254 selection across multiple routing protocols. They may be further 255 augmented by protocol-specific models which have their own defined 256 sets. The supported defined sets include: 258 o prefix sets - define a set of IP prefixes, each with an associated 259 CIDR netmask range (or exact length) 261 o neighbor sets - define a set of neighboring nodes by their IP 262 addresses. These sets are used for selecting routes based on the 263 neighbors advertising the routes. 265 o tag set - define a set of generic tag values that can be used in 266 matches for filtering routes 268 The model structure for defined sets is shown below. 270 +--rw routing-policy 271 +--rw defined-sets 272 | +--rw prefix-sets 273 | | +--rw prefix-set* [name] 274 | | +--rw name string 275 | | +--rw mode? enumeration 276 | | +--rw prefixes 277 | | +--rw prefix-list* [ip-prefix masklength-lower 278 | | masklength-upper] 279 | | +--rw ip-prefix inet:ip-prefix 280 | | +--rw masklength-lower uint8 281 | | +--rw masklength-upper uint8 282 | +--rw neighbor-sets 283 | | +--rw neighbor-set* [name] 284 | | +--rw name string 285 | | +--rw address* inet:ip-address 286 | +--rw tag-sets 287 | +--rw tag-set* [name] 288 | +--rw name string 289 | +--rw tag-value* tag-type 291 4.2. Policy conditions 293 Policy statements consist of a set of conditions and actions (either 294 of which may be empty). Conditions are used to match route 295 attributes against a defined set (e.g., a prefix set), or to compare 296 attributes against a specific value. 298 Match conditions may be further modified using the match-set-options 299 configuration which allows operators to change the behavior of a 300 match. Three options are supported: 302 o ALL - match is true only if the given value matches all members of 303 the set. 305 o ANY - match is true if the given value matches any member of the 306 set. 308 o INVERT - match is true if the given value does not match any 309 member of the given set. 311 Not all options are appropriate for matching against all defined sets 312 (e.g., match ALL in a prefix set does not make sense). In the model, 313 a restricted set of match options is used where applicable. 315 Comparison conditions may similarly use options to change how route 316 attributes should be tested, e.g., for equality or inequality, 317 against a given value. 319 While most policy conditions will be added by individual routing 320 protocol models via augmentation, this routing policy model includes 321 several generic match conditions and also the ability to test which 322 protocol or mechanism installed a route (e.g., BGP, IGP, static, 323 etc.). The conditions included in the model are shown below. 325 +--rw routing-policy 326 +--rw policy-definitions 327 +--rw policy-definition* [name] 328 +--rw name string 329 +--rw statements 330 +--rw statement* [name] 331 +--rw conditions 332 | +--rw call-policy? 333 | +--rw install-protocol-eq? 334 | +--rw match-interface 335 | | +--rw interface? 336 | | +--rw subinterface? 337 | +--rw match-prefix-set 338 | | +--rw prefix-set? 339 | | +--rw match-set-options? 340 | +--rw match-neighbor-set 341 | | +--rw neighbor-set? 342 | +--rw match-tag-set 343 | +--rw tag-set? 344 | +--rw match-set-options? 346 4.3. Policy actions 348 When policy conditions are satisfied, policy actions are used to set 349 various attributes of the route being processed, or to indicate the 350 final disposition of the route, i.e., accept or reject. 352 Similar to policy conditions, the routing policy model includes 353 generic actions in addition to the basic route disposition actions. 354 These are shown below. 356 +--rw routing-policy 357 +--rw policy-definitions 358 +--rw policy-definition* [name] 359 +--rw statements 360 +--rw statement* [name] 361 +--rw actions 362 +--rw policy-result? policy-result-type 363 +--rw set-metric? uint32 364 +--rw set-preference? uint16 366 4.4. Policy subroutines 368 Policy 'subroutines' (or nested policies) are supported by allowing 369 policy statement conditions to reference other policy definitions 370 using the call-policy configuration. Called policies apply their 371 conditions and actions before returning to the calling policy 372 statement and resuming evaluation. The outcome of the called policy 373 affects the evaluation of the calling policy. If the called policy 374 results in an accept-route, then the subroutine returns an effective 375 boolean true value to the calling policy. For the calling policy, 376 this is equivalent to a condition statement evaluating to a true 377 value and evaluation of the policy continues (see Section 5). Note 378 that the called policy may also modify attributes of the route in its 379 action statements. Similarly, a reject-route action returns false 380 and the calling policy evaluation will be affected accordingly. When 381 the end of the subroutine policy chain is reached, the default route 382 disposition action is returned (i.e., boolean false for reject-route 383 unless an alternate default action is specified for the chain). 384 Consequently, a subroutine cannot explicitly accept or reject a 385 route. Rather it merely provides an indication that 'call-policy' 386 condition returns boolean true or false indicating whether or not the 387 condition matches. Route acceptance or rejection is solely 388 determined by the top-level policy. 390 Note that the called policy may itself call other policies (subject 391 to implementation limitations). The model does not prescribe a 392 nesting depth because this varies among implementations. For 393 example, some major implementation may only support a single level of 394 subroutine recursion. As with any routing policy construction, care 395 must be taken with nested policies to ensure that the effective 396 return value results in the intended behavior. Nested policies are a 397 convenience in many routing policy constructions but creating 398 policies nested beyond a small number of levels (e.g., 2-3) should be 399 discouraged. 401 5. Policy evaluation 403 Evaluation of each policy definition proceeds by evaluating its 404 corresponding individual policy statements in order. When all the 405 condition statements in a policy statement are satisfied, the 406 corresponding action statements are executed. If the actions include 407 either accept-route or reject-route actions, evaluation of the 408 current policy definition stops, and no further policy definitions in 409 the chain are evaluated. 411 If the conditions are not satisfied, then evaluation proceeds to the 412 next policy statement. If none of the policy statement conditions 413 are satisfied, then evaluation of the current policy definition 414 stops, and the next policy definition in the chain is evaluated. 415 When the end of the policy chain is reached, the default route 416 disposition action is performed (i.e., reject-route unless an 417 alternate default action is specified for the chain). 419 Note that the route's pre-policy attributes are always used for 420 testing policy statement conditions. In other words, if actions 421 modify the policy application specific attributes, those 422 modifications are not used for policy statement conditions. 424 6. Applying routing policy 426 Routing policy is applied by defining and attaching policy chains in 427 various routing contexts. Policy chains are sequences of policy 428 definitions (described in Section 4) that have an associated 429 direction (import or export) with respect to the routing context in 430 which they are defined. The routing policy model defines an apply- 431 policy grouping that can be imported and used by other models. As 432 shown below, it allows definition of import and export policy chains, 433 as well as specifying the default route disposition to be used when 434 no policy definition in the chain results in a final decision. 436 +--rw apply-policy 437 | +--rw import-policy* 438 | +--rw default-import-policy? default-policy-type 439 | +--rw export-policy* 440 | +--rw default-export-policy? default-policy-type 442 The default policy defined by the model is to reject the route for 443 both import and export policies. 445 7. Routing protocol-specific policies 447 Routing models that require the ability to apply routing policy may 448 augment the routing policy model with protocol or other specific 449 policy configuration. The routing policy model assumes that 450 additional defined sets, conditions, and actions may all be added by 451 other models. 453 An example of this is shown below, in which the BGP configuration 454 model in [I-D.ietf-idr-bgp-model] adds new defined sets to match on 455 community values or AS paths. The model similarly augments BGP- 456 specific conditions and actions in the corresponding sections of the 457 routing policy model. 459 +--rw routing-policy 460 +--rw defined-sets 461 | +--rw prefix-sets 462 | | +--rw prefix-set* [name] 463 | | +--rw name string 464 | | +--rw mode? enumeration 465 | | +--rw prefixes 466 | | +--rw prefix-list* [ip-prefix masklength-lower 467 | | masklength-upper] 468 | | +--rw ip-prefix inet:ip-prefix 469 | | +--rw masklength-lower uint8 470 | | +--rw masklength-upper uint8 471 | +--rw neighbor-sets 472 | | +--rw neighbor-set* [name] 473 | | +--rw name string 474 | | +--rw address* inet:ip-address 475 | +--rw tag-sets 476 | | +--rw tag-set* [name] 477 | | +--rw name string 478 | | +--rw tag-value* tag-type 479 | +--rw bgp-pol:bgp-defined-sets 480 | +--rw bgp-pol:community-sets 481 | | +--rw bgp-pol:community-set* [community-set-name] 482 | | +--rw bgp-pol:community-set-name string 483 | | +--rw bgp-pol:community-member* union 484 | +--rw bgp-pol:ext-community-sets 485 | | +--rw bgp-pol:ext-community-set* [ext-community-set-name] 486 | | +--rw bgp-pol:ext-community-set-name string 487 | | +--rw bgp-pol:ext-community-member* union 488 | +--rw bgp-pol:as-path-sets 489 | +--rw bgp-pol:as-path-set* [as-path-set-name] 490 | +--rw bgp-pol:as-path-set-name string 491 | +--rw bgp-pol:as-path-set-member* string 492 +--rw policy-definitions 493 +--rw policy-definition* [name] 494 +--rw name string 495 +--rw statements 496 +--rw statement* [name] 497 +--rw name string 498 +--rw conditions 499 | +--rw call-policy? 500 | +--rw source-protocol? identityref 501 | +--rw match-interface 502 | | +--rw interface? 503 | | +--rw subinterface? 504 | +--rw match-prefix-set 505 | | +--rw prefix-set? 506 | | +--rw match-set-options? match-set-options-type 507 | +--rw match-neighbor-set 508 | | +--rw neighbor-set? 509 | +--rw match-tag-set 510 | | +--rw tag-set? 511 | | +--rw match-set-options? match-set-options-type 512 | +--rw bgp-pol:bgp-conditions 513 | +--rw bgp-pol:med-eq? uint32 514 | +--rw bgp-pol:origin-eq? 515 | bgp-types:bgp-origin-attr-type 516 | +--rw bgp-pol:next-hop-in* 517 | inet:ip-address-no-zone 518 | +--rw bgp-pol:afi-safi-in* identityref 519 | +--rw bgp-pol:local-pref-eq? uint32 520 | +--rw bgp-pol:route-type? enumeration 521 | +--rw bgp-pol:community-count 522 | +--rw bgp-pol:as-path-length 523 | +--rw bgp-pol:match-community-set 524 | | +--rw bgp-pol:community-set? 525 | | +--rw bgp-pol:match-set-options? 526 | match-set-options-type 527 | +--rw bgp-pol:match-ext-community-set 528 | | +--rw bgp-pol:ext-community-set? 529 | | +--rw bgp-pol:match-set-options? 530 | | match-set-options-type 531 | +--rw bgp-pol:match-as-path-set 532 | +--rw bgp-pol:as-path-set? 533 | +--rw bgp-pol:match-set-options? 534 | match-set-options-type 535 +--rw actions 536 +--rw policy-result? policy-result-type 537 +--rw set-metric? uint32 538 +--rw set-preference? uint16 539 +--rw bgp-pol:bgp-actions 540 +--rw bgp-pol:set-route-origin? 541 bgp-types:bgp-origin-attr-type 542 +--rw bgp-pol:set-local-pref? uint32 543 +--rw bgp-pol:set-next-hop? bgp-next-hop-type 544 +--rw bgp-pol:set-med? bgp-set-med-type 545 +--rw bgp-pol:set-as-path-prepend 546 | +--rw bgp-pol:repeat-n? uint8 547 +--rw bgp-pol:set-community 548 | +--rw bgp-pol:method? enumeration 549 | +--rw bgp-pol:options? 550 bgp-set-community-option-type 551 | +--rw bgp-pol:inline 552 | | +--rw bgp-pol:communities* union 553 | +--rw bgp-pol:reference 554 | +--rw bgp-pol:community-set-ref? 555 +--rw bgp-pol:set-ext-community 556 +--rw bgp-pol:method? enumeration 557 +--rw bgp-pol:options? 558 bgp-set-community-option-type 559 +--rw bgp-pol:inline 560 | +--rw bgp-pol:communities* union 561 +--rw bgp-pol:reference 562 +--rw bgp-pol:ext-community-set-ref? 564 8. Security Considerations 566 Routing policy configuration has a significant impact on network 567 operations, and, as such, any related model carries potential 568 security risks. 570 YANG data models are generally designed to be used with the NETCONF 571 protocol over an SSH transport. This provides an authenticated and 572 secure channel over which to transfer configuration and operational 573 data. Note that use of alternate transport or data encoding (e.g., 574 JSON over HTTPS) would require similar mechanisms for authenticating 575 and securing access to configuration data. 577 Most of the data elements in the policy model could be considered 578 sensitive from a security standpoint. Unauthorized access or invalid 579 data could cause major disruption. 581 9. IANA Considerations 583 This YANG data model and the component modules currently use a 584 temporary ad-hoc namespace. If and when it is placed on redirected 585 for the standards track, an appropriate namespace URI will be 586 registered in the IETF XML Registry" [RFC3688]. The routing policy 587 YANG modules will be registered in the "YANG Module Names" registry 588 [RFC6020]. 590 10. YANG modules 592 The routing policy model is described by the YANG modules in the 593 sections below. 595 10.1. Routing policy model 597 file "ietf-routing-policy@2020-01-02.yang" 598 module ietf-routing-policy { 600 yang-version "1.1"; 601 namespace "urn:ietf:params:xml:ns:yang:ietf-routing-policy"; 602 prefix rt-pol; 604 import ietf-inet-types { 605 prefix "inet"; 606 } 608 import ietf-yang-types { 609 prefix "yang"; 610 } 612 import ietf-interfaces { 613 prefix "if"; 614 } 616 import ietf-routing { 617 prefix "rt"; 618 } 620 import ietf-if-extensions { 621 prefix if-ext; 622 } 624 import ietf-if-l3-vlan { 625 prefix "if-l3-vlan"; 626 } 628 organization 629 "IETF RTGWG - Routing Area Working Group"; 630 contact 631 "WG Web: 632 WG List: 634 Editor: Yingzhen Qu 635 636 Jeff Tantsura 637 638 Acee Lindem 639 640 Xufeng Liu 641 642 Anees Shaikh 643 "; 645 description 646 "This module describes a YANG model for routing policy 647 configuration. It is a limited subset of all of the policy 648 configuration parameters available in the variety of vendor 649 implementations, but supports widely used constructs for 650 managing how routes are imported, exported, and modified across 651 different routing protocols. This module is intended to be 652 used in conjunction with routing protocol configuration modules 653 (e.g., BGP) defined in other models. 655 Copyright (c) 2020 IETF Trust and the persons identified as 656 authors of the code. All rights reserved. 658 Redistribution and use in source and binary forms, with or 659 without modification, is permitted pursuant to, and subject to 660 the license terms contained in, the Simplified BSD License set 661 forth in Section 4.c of the IETF Trust's Legal Provisions 662 Relating to IETF Documents 663 (https://trustee.ietf.org/license-info). 665 This version of this YANG module is part of RFC XXXX 666 (https://www.rfc-editor.org/info/rfcXXXX); see the RFC itself 667 for full legal notices. 669 Route policy expression: 671 Policies are expressed as a set of top-level policy 672 definitions, each of which consists of a sequence of policy 673 statements. Policy statements consist of simple 674 condition-action tuples. Conditions may include mutiple match 675 or comparison operations, and similarly actions may be 676 multitude of changes to route attributes or a final disposition 677 of accepting or rejecting the route. 679 Route policy evaluation: 681 Policy definitions are referenced in routing protocol 682 configurations using import and export configuration 683 statements. The arguments are members of an ordered list of 684 named policy definitions which comprise a policy chain, and 685 optionally, an explicit default policy action (i.e., reject 686 or accept). 688 Evaluation of each policy definition proceeds by evaluating its 689 corresponding individual policy statements in order. When a 690 condition statement in a policy statement is satisfied, the 691 corresponding action statement is executed. If the action 692 statement has either accept-route or reject-route actions, 693 policy evaluation of the current policy definition stops, and 694 no further policy definitions in the chain are evaluated. 696 If the condition is not satisfied, then evaluation proceeds to 697 the next policy statement. If none of the policy statement 698 conditions are satisfied, then evaluation of the current policy 699 definition stops, and the next policy definition in the chain 700 is evaluated. When the end of the policy chain is reached, the 701 default route disposition action is performed (i.e., 702 reject-route unless an alternate default action is specified 703 for the chain). 705 Policy 'subroutines' (or nested policies) are supported by 706 allowing policy statement conditions to reference another 707 policy definition which applies conditions and actions from 708 the referenced policy before returning to the calling policy 709 statement and resuming evaluation. If the called policy 710 results in an accept-route (either explicit or by default), 711 then the subroutine returns an effective true value to the 712 calling policy. Similarly, a reject-route action returns 713 false. If the subroutine returns true, the calling policy 714 continues to evaluate the remaining conditions (using a 715 modified route if the subroutine performed any changes to the 716 route)."; 718 revision "2020-01-02" { 719 description 720 "Initial revision."; 721 reference 722 "RFC XXXX: Routing Policy Configuration Model for Service 723 Provider Networks"; 724 } 726 // typedef statements 728 typedef default-policy-type { 729 // this typedef retained for name compatibiity with default 730 // import and export policy 731 type enumeration { 732 enum accept-route { 733 description 734 "Default policy to accept the route"; 735 } 736 enum reject-route { 737 description 738 "Default policy to reject the route"; 739 } 740 } 741 description 742 "Type used to specify route disposition in 743 a policy chain"; 744 } 746 typedef policy-result-type { 747 type enumeration { 748 enum accept-route { 749 description "Policy accepts the route"; 750 } 751 enum reject-route { 752 description "Policy rejects the route"; 753 } 754 } 755 description 756 "Type used to specify route disposition in 757 a policy chain"; 758 } 760 typedef tag-type { 761 type union { 762 type uint32; 763 type yang:hex-string; 764 } 765 description "Type for expressing route tags on a local system, 766 including IS-IS and OSPF; may be expressed as either decimal 767 or hexadecimal integer"; 768 reference 769 "RFC 2178 - OSPF Version 2 770 RFC 5130 - A Policy Control Mechanism in IS-IS Using 771 Administrative Tags"; 772 } 774 typedef match-set-options-type { 775 type enumeration { 776 enum any { 777 description "Match is true if given value matches any member 778 of the defined set"; 779 } 780 enum all { 781 description "Match is true if given value matches all 782 members of the defined set"; 783 } 784 enum invert { 785 description "Match is true if given value does not match any 786 member of the defined set"; 787 } 788 } 789 default any; 790 description 791 "Options that govern the behavior of a match statement. The 792 default behavior is any, i.e., the given value matches any 793 of the members of the defined set"; 794 } 796 // grouping statements 798 grouping prefix-set { 799 description 800 "Configuration data for prefix sets used in policy 801 definitions."; 803 leaf name { 804 type string; 805 description 806 "Name of the prefix set -- this is used as a label to 807 reference the set in match conditions"; 808 } 810 leaf mode { 811 type enumeration { 812 enum ipv4 { 813 description 814 "Prefix set contains IPv4 prefixes only"; 815 } 816 enum ipv6 { 817 description 818 "Prefix set contains IPv6 prefixes only"; 819 } 820 enum mixed { 821 description 822 "Prefix set contains mixed IPv4 and IPv6 prefixes"; 823 } 824 } 825 description 826 "Indicates the mode of the prefix set, in terms of which 827 address families (IPv4, IPv6, or both) are present. The 828 mode provides a hint, but the device must validate that all 829 prefixes are of the indicated type, and is expected to 830 reject the configuration if there is a discrepancy. The 831 MIXED mode may not be supported on devices that require 832 prefix sets to be of only one address family."; 833 } 835 } 837 grouping prefix-set-top { 838 description 839 "Top-level data definitions for a list of IPv4 or IPv6 840 prefixes which are matched as part of a policy"; 842 container prefix-sets { 843 description 844 "Enclosing container "; 846 list prefix-set { 847 key "name"; 848 description 849 "List of the defined prefix sets"; 851 uses prefix-set; 853 uses prefix-top; 854 } 855 } 856 } 858 grouping prefix { 859 description 860 "Configuration data for a prefix definition"; 862 leaf ip-prefix { 863 type inet:ip-prefix; 864 mandatory true; 865 description 866 "The prefix member in CIDR notation -- while the 867 prefix may be either IPv4 or IPv6, most 868 implementations require all members of the prefix set 869 to be the same address family. Mixing address types in 870 the same prefix set is likely to cause an error."; 871 } 872 leaf masklength-lower { 873 type uint8; 874 description 875 "Masklength range lower bound."; 876 } 877 leaf masklength-upper { 878 type uint8 { 879 range "1..128"; 880 } 881 must "../masklength-upper >= ../masklength-lower" { 882 error-message "The upper bound should not be less" 883 + "than lower bound."; 884 } 885 description 886 "Masklength range upper bound. 888 The combination of masklength-lower and masklength-upper 889 define a range for the mask length, or single 'exact' 890 length if masklength-lower and masklenght-upper are equal. 892 Example: 10.3.192.0/21 through 10.3.192.0/24 would be 893 expressed as prefix: 10.3.192.0/21, 894 masklength-lower=21, 895 masklength-upper=24 897 Example: 10.3.192.0/21 (an exact match) would be 898 expressed as prefix: 10.3.192.0/21, 899 masklength-lower=21, 900 masklength-upper=21"; 901 } 902 } 904 grouping prefix-top { 905 description 906 "Top-level grouping for prefixes in a prefix list"; 908 container prefixes { 909 description 910 "Enclosing container for the list of prefixes in a policy 911 prefix list"; 913 list prefix-list { 914 key "ip-prefix masklength-lower masklength-upper"; 915 description 916 "List of prefixes in the prefix set"; 918 uses prefix; 919 } 921 } 922 } 924 grouping neighbor-set { 925 description 926 "This grouping provides neighbor set definitions"; 928 leaf name { 929 type string; 930 description 931 "Name of the neighbor set -- this is used as a label 932 to reference the set in match conditions"; 933 } 935 leaf-list address { 936 type inet:ip-address; 937 description 938 "List of IP addresses in the neighbor set"; 939 } 940 } 942 grouping neighbor-set-top { 943 description 944 "Top-level data definition for a list of IPv4 or IPv6 945 neighbors which can be matched in a routing policy"; 947 container neighbor-sets { 948 description 949 "Enclosing container for the list of neighbor set 950 definitions"; 952 list neighbor-set { 953 key "name"; 954 description 955 "List of defined neighbor sets for use in policies."; 957 uses neighbor-set; 958 } 959 } 960 } 962 grouping tag-set { 963 description 964 "This grouping provides tag set definitions."; 966 leaf name { 967 type string; 968 description 969 "Name of the tag set -- this is used as a label to reference 970 the set in match conditions"; 971 } 973 leaf-list tag-value { 974 type tag-type; 975 description 976 "Value of the tag set member"; 977 } 978 } 980 grouping tag-set-top { 981 description 982 "Top-level data definitions for a list of tags which can 983 be matched in policies"; 985 container tag-sets { 986 description 987 "Enclosing container for the list of tag sets."; 989 list tag-set { 990 key "name"; 991 description 992 "List of tag set definitions."; 994 uses tag-set; 996 } 997 } 998 } 1000 grouping match-set-options-group { 1001 description 1002 "Grouping containing options relating to how a particular set 1003 should be matched"; 1005 leaf match-set-options { 1006 type match-set-options-type; 1007 description 1008 "Optional parameter that governs the behavior of the 1009 match operation"; 1010 } 1011 } 1013 grouping match-set-options-restricted-group { 1014 description 1015 "Grouping for a restricted set of match operation modifiers"; 1017 leaf match-set-options { 1018 type match-set-options-type { 1019 enum any { 1020 description "Match is true if given value matches any 1021 member of the defined set"; 1022 } 1023 enum invert { 1024 description "Match is true if given value does not match 1025 any member of the defined set"; 1026 } 1027 } 1028 description 1029 "Optional parameter that governs the behavior of the 1030 match operation. This leaf only supports matching on ANY 1031 member of the set or inverting the match. Matching on ALL 1032 is not supported"; 1033 } 1034 } 1036 grouping match-interface-condition { 1037 description 1038 "This grouping provides interface match condition"; 1040 container match-interface { 1041 leaf interface { 1042 type leafref { 1043 path "/if:interfaces/if:interface/if:name"; 1044 } 1045 description 1046 "Reference to a base interface. If a reference to a 1047 subinterface is required, this leaf must be specified 1048 to indicate the base interface."; 1049 } 1050 leaf subinterface { 1051 type leafref { 1052 path "/if:interfaces/if:interface/if-ext:encapsulation" 1053 + "/if-l3-vlan:dot1q-vlan" 1054 + "/if-l3-vlan:outer-tag/if-l3-vlan:vlan-id"; 1055 } 1056 description 1057 "Reference to a subinterface -- this requires the base 1058 interface to be specified using the interface leaf in 1059 this container. If only a reference to a base interface 1060 is requuired, this leaf should not be set."; 1061 } 1062 description 1063 "Container for interface match conditions"; 1064 } 1065 } 1067 grouping prefix-set-condition { 1068 description 1069 "This grouping provides prefix-set conditions"; 1071 container match-prefix-set { 1072 leaf prefix-set { 1073 type leafref { 1074 path "../../../../../../../defined-sets/" + 1075 "prefix-sets/prefix-set/name"; 1076 } 1077 description "References a defined prefix set"; 1078 } 1079 uses match-set-options-restricted-group; 1081 description 1082 "Match a referenced prefix-set according to the logic 1083 defined in the match-set-options leaf"; 1084 } 1085 } 1087 grouping neighbor-set-condition { 1088 description 1089 "This grouping provides neighbor-set conditions"; 1091 container match-neighbor-set { 1092 leaf neighbor-set { 1093 type leafref { 1094 path "../../../../../../../defined-sets/neighbor-sets/" + 1095 "neighbor-set/name"; 1096 require-instance true; 1097 } 1098 description "References a defined neighbor set"; 1099 } 1101 description 1102 "Match a referenced neighbor set according to the logic 1103 defined in the match-set-options-leaf"; 1104 } 1105 } 1107 grouping tag-set-condition { 1108 description 1109 "This grouping provides tag-set conditions"; 1111 container match-tag-set { 1112 leaf tag-set { 1113 type leafref { 1114 path "../../../../../../../defined-sets/tag-sets" + 1115 "/tag-set/name"; 1116 require-instance true; 1117 } 1118 description "References a defined tag set"; 1119 } 1120 uses match-set-options-restricted-group; 1122 description 1123 "Match a referenced tag set according to the logic defined 1124 in the match-options-set leaf"; 1125 } 1126 } 1128 grouping generic-conditions { 1129 description "Condition statement definitions for checking 1130 membership in a generic defined set"; 1132 uses match-interface-condition; 1133 uses prefix-set-condition; 1134 uses neighbor-set-condition; 1135 uses tag-set-condition; 1137 } 1139 grouping policy-conditions { 1140 description 1141 "Data for general policy conditions, i.e., those 1142 not related to match-sets"; 1144 leaf call-policy { 1145 type leafref { 1146 path "../../../../../../" + 1147 "rt-pol:policy-definitions/" + 1148 "rt-pol:policy-definition/rt-pol:name"; 1149 require-instance true; 1150 } 1151 description 1152 "Applies the statements from the specified policy 1153 definition and then returns control the current 1154 policy statement. Note that the called policy may 1155 itself call other policies (subject to 1156 implementation limitations). This is intended to 1157 provide a policy 'subroutine' capability. The 1158 called policy should contain an explicit or a 1159 default route disposition that returns an 1160 effective true (accept-route) or false 1161 (reject-route), otherwise the behavior may be 1162 ambiguous and implementation dependent"; 1163 } 1165 leaf source-protocol { 1166 type identityref { 1167 base rt:control-plane-protocol; 1168 } 1169 description 1170 "Condition to check the protocol / method used to install 1171 the route into the local routing table"; 1172 } 1173 } 1175 grouping policy-conditions-top { 1176 description 1177 "Top-level grouping for policy conditions"; 1179 container conditions { 1180 description 1181 "Condition statements for the current policy statement"; 1183 uses policy-conditions; 1185 uses generic-conditions; 1186 } 1187 } 1189 grouping policy-statements { 1190 description 1191 "Data for policy statements"; 1193 leaf name { 1194 type string; 1195 description 1196 "Name of the policy statement"; 1197 } 1198 } 1200 grouping policy-actions { 1201 description 1202 "Top-level grouping for policy actions"; 1204 container actions { 1205 description 1206 "Top-level container for policy action statements"; 1208 leaf policy-result { 1209 type policy-result-type; 1210 description 1211 "Select the final disposition for the route, either 1212 accept or reject."; 1213 } 1214 leaf set-metric { 1215 type uint32; 1216 description 1217 "Set a new metric for the route."; 1218 } 1219 leaf set-preference { 1220 type uint16; 1221 description 1222 "Set a new preference for the route."; 1223 } 1224 } 1225 } 1227 grouping policy-statements-top { 1228 description 1229 "Top-level grouping for the policy statements list"; 1231 container statements { 1232 description 1233 "Enclosing container for policy statements"; 1235 list statement { 1236 key "name"; 1237 ordered-by user; 1238 description 1239 "Policy statements group conditions and actions 1240 within a policy definition. They are evaluated in 1241 the order specified (see the description of policy 1242 evaluation at the top of this module."; 1244 uses policy-statements; 1246 uses policy-conditions-top; 1247 uses policy-actions; 1248 } 1249 } 1250 } 1252 grouping policy-definitions { 1253 description 1254 "This grouping provides policy definitions"; 1256 leaf name { 1257 type string; 1258 description 1259 "Name of the top-level policy definition -- this name 1260 is used in references to the current policy"; 1261 } 1262 } 1264 grouping apply-policy-import { 1265 description 1266 "Grouping for applying import policies"; 1268 leaf-list import-policy { 1269 type leafref { 1270 path "/rt-pol:routing-policy/rt-pol:policy-definitions/" + 1271 "rt-pol:policy-definition/rt-pol:name"; 1272 require-instance true; 1273 } 1274 ordered-by user; 1275 description 1276 "List of policy names in sequence to be applied on 1277 receiving a routing update in the current context, e.g., 1278 for the current peer group, neighbor, address family, 1279 etc."; 1280 } 1282 leaf default-import-policy { 1283 type default-policy-type; 1284 default reject-route; 1285 description 1286 "Explicitly set a default policy if no policy definition 1287 in the import policy chain is satisfied."; 1288 } 1290 } 1292 grouping apply-policy-export { 1293 description 1294 "Grouping for applying export policies"; 1296 leaf-list export-policy { 1297 type leafref { 1298 path "/rt-pol:routing-policy/rt-pol:policy-definitions/" + 1299 "rt-pol:policy-definition/rt-pol:name"; 1300 require-instance true; 1302 } 1303 ordered-by user; 1304 description 1305 "List of policy names in sequence to be applied on 1306 sending a routing update in the current context, e.g., 1307 for the current peer group, neighbor, address family, 1308 etc."; 1309 } 1311 leaf default-export-policy { 1312 type default-policy-type; 1313 default reject-route; 1314 description 1315 "Explicitly set a default policy if no policy definition 1316 in the export policy chain is satisfied."; 1317 } 1318 } 1320 grouping apply-policy { 1321 description 1322 "Configuration data for routing policies"; 1324 uses apply-policy-import; 1325 uses apply-policy-export; 1327 container apply-policy-state { 1328 description 1329 "Operational state associated with routing policy"; 1331 //TODO: identify additional state data beyond the intended 1332 //policy configuration. 1333 } 1335 } 1337 grouping apply-policy-group { 1338 description 1339 "Top level container for routing policy applications. This 1340 grouping is intended to be used in routing models where 1341 needed."; 1343 container apply-policy { 1344 description 1345 "Anchor point for routing policies in the model. 1346 Import and export policies are with respect to the local 1347 routing table, i.e., export (send) and import (receive), 1348 depending on the context."; 1350 uses apply-policy; 1352 } 1353 } 1355 container routing-policy { 1356 description 1357 "Top-level container for all routing policy"; 1359 container defined-sets { 1360 description 1361 "Predefined sets of attributes used in policy match 1362 statements"; 1364 uses prefix-set-top; 1365 uses neighbor-set-top; 1366 uses tag-set-top; 1367 } 1369 container policy-definitions { 1370 description 1371 "Enclosing container for the list of top-level policy 1372 definitions"; 1374 list policy-definition { 1375 key "name"; 1376 description 1377 "List of top-level policy definitions, keyed by unique 1378 name. These policy definitions are expected to be 1379 referenced (by name) in policy chains specified in import 1380 or export configuration statements."; 1382 uses policy-definitions; 1384 uses policy-statements-top; 1385 } 1386 } 1387 } 1388 } 1389 1391 11. Policy examples 1393 Below we show an example of XML-encoded configuration data using the 1394 routing policy and BGP models to illustrate both how policies are 1395 defined, and also how they can be applied. Note that the XML has 1396 been simplified for readability. 1398 1400 12. References 1402 12.1. Normative references 1404 [I-D.ietf-netmod-intf-ext-yang] 1405 Wilton, R., Ball, D., tapsingh@cisco.com, t., and S. 1406 Sivaraj, "Common Interface Extension YANG Data Models", 1407 draft-ietf-netmod-intf-ext-yang-08 (work in progress), 1408 November 2019. 1410 [I-D.ietf-netmod-sub-intf-vlan-model] 1411 Wilton, R., Ball, D., tapsingh@cisco.com, t., and S. 1412 Sivaraj, "Sub-interface VLAN YANG Data Models", draft- 1413 ietf-netmod-sub-intf-vlan-model-06 (work in progress), 1414 November 2019. 1416 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1417 Requirement Levels", BCP 14, RFC 2119, 1418 DOI 10.17487/RFC2119, March 1997, 1419 . 1421 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1422 DOI 10.17487/RFC3688, January 2004, 1423 . 1425 [RFC4271] Rekhter, Y., Ed., Li, T., Ed., and S. Hares, Ed., "A 1426 Border Gateway Protocol 4 (BGP-4)", RFC 4271, 1427 DOI 10.17487/RFC4271, January 2006, 1428 . 1430 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 1431 the Network Configuration Protocol (NETCONF)", RFC 6020, 1432 DOI 10.17487/RFC6020, October 2010, 1433 . 1435 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 1436 RFC 6991, DOI 10.17487/RFC6991, July 2013, 1437 . 1439 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1440 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1441 . 1443 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1444 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1445 May 2017, . 1447 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 1448 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 1449 . 1451 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 1452 and R. Wilton, "Network Management Datastore Architecture 1453 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 1454 . 1456 [RFC8343] Bjorklund, M., "A YANG Data Model for Interface 1457 Management", RFC 8343, DOI 10.17487/RFC8343, March 2018, 1458 . 1460 [RFC8349] Lhotka, L., Lindem, A., and Y. Qu, "A YANG Data Model for 1461 Routing Management (NMDA Version)", RFC 8349, 1462 DOI 10.17487/RFC8349, March 2018, 1463 . 1465 12.2. Informative references 1467 [I-D.ietf-idr-bgp-model] 1468 Jethanandani, M., Patel, K., Hares, S., and J. Haas, "BGP 1469 YANG Model for Service Provider Networks", draft-ietf-idr- 1470 bgp-model-07 (work in progress), October 2019. 1472 Appendix A. Acknowledgements 1474 The routing policy module defined in this draft is based on the 1475 OpenConfig route policy model. The authors would like to thank to 1476 OpenConfig for their contributions, especially Anees Shaikh, Rob 1477 Shakir, Kevin D'Souza, and Chris Chase. 1479 The authors are grateful for valuable contributions to this document 1480 and the associated models from: Ebben Aires, Luyuan Fang, Josh 1481 George, Stephane Litkowski, Ina Minei, Carl Moberg, Eric Osborne, 1482 Steve Padgett, Juergen Schoenwaelder, Jim Uttaro, Russ White, and 1483 John Heasley. 1485 Authors' Addresses 1487 Yingzhen Qu 1488 Futurewei 1489 2330 Central Expressway 1490 Santa Clara CA 95050 1491 USA 1493 Email: yingzhen.qu@futurewei.com 1495 Jeff Tantsura 1496 Apstra 1498 Email: jefftant.ietf@gmail.com 1500 Acee Lindem 1501 Cisco 1502 301 Mindenhall Way 1503 Cary, NC 27513 1504 US 1506 Email: acee@cisco.com 1508 Xufeng Liu 1509 Volta Networks 1511 Email: xufeng.liu.ietf@gmail.com