idnits 2.17.1 draft-ietf-rtgwg-policy-model-07.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 275 has weird spacing: '...h-lower uin...' == Line 276 has weird spacing: '...h-upper uin...' == Line 464 has weird spacing: '...h-lower uin...' == Line 465 has weird spacing: '...h-upper uin...' == Line 477 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 (September 10, 2019) is 1689 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 1391, but no explicit reference was found in the text == Outdated reference: A later version (-13) exists of draft-ietf-netmod-intf-ext-yang-07 == Outdated reference: A later version (-10) exists of draft-ietf-netmod-sub-intf-vlan-model-05 == Outdated reference: A later version (-17) exists of draft-ietf-idr-bgp-model-06 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: March 13, 2020 Apstra 6 A. Lindem 7 Cisco 8 X. Liu 9 Volta Networks 10 September 10, 2019 12 A YANG Data Model for Routing Policy Management 13 draft-ietf-rtgwg-policy-model-07 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 March 13, 2020. 39 Copyright Notice 41 Copyright (c) 2019 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 . . . . . . . . . . . . . . . . . . . . . . . 30 75 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 30 76 12.1. Normative references . . . . . . . . . . . . . . . . . . 31 77 12.2. Informative references . . . . . . . . . . . . . . . . . 32 78 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 32 79 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 32 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-cmn | ietf-interfaces-common | [I-D.ietf-netmod-intf-ext-yang] | 196 +--------+------------------------+---------------------------------+ 198 Table 1: Prefixes and Corresponding YANG Modules 200 3. Model overview 202 The routing policy module has three main parts: 204 o A generic framework to express policies as sets of related 205 conditions and actions. This includes match sets and actions that 206 are useful across many routing protocols. 208 o A structure that allows routing protocol models to add protocol- 209 specific policy conditions and actions though YANG augmentations. 210 There is a complete example of this for BGP [RFC4271] policies in 211 the proposed vendor-neutral BGP data model 212 [I-D.ietf-idr-bgp-model]. 214 o A reusable grouping for attaching import and export rules in the 215 context of routing configuration for different protocols, VRFs, 216 etc. This also enables creation of policy chains and expressing 217 default policy behavior. 219 The module makes use of the standard Internet types, such as IP 220 addresses, autonomous system numbers, etc., defined in RFC 6991 221 [RFC6991]. 223 4. Route policy expression 225 Policies are expressed as a sequence of top-level policy definitions 226 each of which consists of a sequence of policy statements. Policy 227 statements in turn consist of simple condition-action tuples. 228 Conditions may include multiple match or comparison operations, and 229 similarly, actions may effect multiple changes to route attributes, 230 or indicate a final disposition of accepting or rejecting the route. 231 This structure is shown below. 233 +--rw routing-policy 234 +--rw policy-definitions 235 +--rw policy-definition* [name] 236 +--rw name string 237 +--rw statements 238 +--rw statement* [name] 239 +--rw name string 240 +--rw conditions 241 | ... 242 +--rw actions 243 ... 245 4.1. Defined sets for policy matching 247 The models provides a set of generic sets that can be used for 248 matching in policy conditions. These sets are applicable for route 249 selection across multiple routing protocols. They may be further 250 augmented by protocol-specific models which have their own defined 251 sets. The supported defined sets include: 253 o prefix sets - define a set of IP prefixes, each with an associated 254 CIDR netmask range (or exact length) 256 o neighbor sets - define a set of neighboring nodes by their IP 257 addresses. These sets are used for selecting routes based on the 258 neighbors advertising the routes. 260 o tag set - define a set of generic tag values that can be used in 261 matches for filtering routes 263 The model structure for defined sets is shown below. 265 +--rw routing-policy 266 +--rw defined-sets 267 | +--rw prefix-sets 268 | | +--rw prefix-set* [name] 269 | | +--rw name string 270 | | +--rw mode? enumeration 271 | | +--rw prefixes 272 | | +--rw prefix-list* [ip-prefix masklength-lower 273 | | masklength-upper] 274 | | +--rw ip-prefix inet:ip-prefix 275 | | +--rw masklength-lower uint8 276 | | +--rw masklength-upper uint8 277 | +--rw neighbor-sets 278 | | +--rw neighbor-set* [name] 279 | | +--rw name string 280 | | +--rw address* inet:ip-address 281 | +--rw tag-sets 282 | +--rw tag-set* [name] 283 | +--rw name string 284 | +--rw tag-value* tag-type 286 4.2. Policy conditions 288 Policy statements consist of a set of conditions and actions (either 289 of which may be empty). Conditions are used to match route 290 attributes against a defined set (e.g., a prefix set), or to compare 291 attributes against a specific value. 293 Match conditions may be further modified using the match-set-options 294 configuration which allows operators to change the behavior of a 295 match. Three options are supported: 297 o ALL - match is true only if the given value matches all members of 298 the set. 300 o ANY - match is true if the given value matches any member of the 301 set. 303 o INVERT - match is true if the given value does not match any 304 member of the given set. 306 Not all options are appropriate for matching against all defined sets 307 (e.g., match ALL in a prefix set does not make sense). In the model, 308 a restricted set of match options is used where applicable. 310 Comparison conditions may similarly use options to change how route 311 attributes should be tested, e.g., for equality or inequality, 312 against a given value. 314 While most policy conditions will be added by individual routing 315 protocol models via augmentation, this routing policy model includes 316 several generic match conditions and also the ability to test which 317 protocol or mechanism installed a route (e.g., BGP, IGP, static, 318 etc.). The conditions included in the model are shown below. 320 +--rw routing-policy 321 +--rw policy-definitions 322 +--rw policy-definition* [name] 323 +--rw name string 324 +--rw statements 325 +--rw statement* [name] 326 +--rw conditions 327 | +--rw call-policy? 328 | +--rw install-protocol-eq? 329 | +--rw match-interface 330 | | +--rw interface? 331 | | +--rw subinterface? 332 | +--rw match-prefix-set 333 | | +--rw prefix-set? 334 | | +--rw match-set-options? 335 | +--rw match-neighbor-set 336 | | +--rw neighbor-set? 337 | +--rw match-tag-set 338 | +--rw tag-set? 339 | +--rw match-set-options? 341 4.3. Policy actions 343 When policy conditions are satisfied, policy actions are used to set 344 various attributes of the route being processed, or to indicate the 345 final disposition of the route, i.e., accept or reject. 347 Similar to policy conditions, the routing policy model includes 348 generic actions in addition to the basic route disposition actions. 349 These are shown below. 351 +--rw routing-policy 352 +--rw policy-definitions 353 +--rw policy-definition* [name] 354 +--rw statements 355 +--rw statement* [name] 356 +--rw actions 357 +--rw policy-result? policy-result-type 358 +--rw set-metric? uint32 359 +--rw set-preference? uint16 361 4.4. Policy subroutines 363 Policy 'subroutines' (or nested policies) are supported by allowing 364 policy statement conditions to reference other policy definitions 365 using the call-policy configuration. Called policies apply their 366 conditions and actions before returning to the calling policy 367 statement and resuming evaluation. The outcome of the called policy 368 affects the evaluation of the calling policy. If the called policy 369 results in an accept-route, then the subroutine returns an effective 370 boolean true value to the calling policy. For the calling policy, 371 this is equivalent to a condition statement evaluating to a true 372 value and evaluation of the policy continues (see Section 5). Note 373 that the called policy may also modify attributes of the route in its 374 action statements. Similarly, a reject-route action returns false 375 and the calling policy evaluation will be affected accordingly. When 376 the end of the subroutine policy chain is reached, the default route 377 disposition action is returned (i.e., boolean false for reject-route 378 unless an alternate default action is specified for the chain). 379 Consequently, a subroutine cannot explicitly accept or reject a 380 route. Rather it merely provides an indication that 'call-policy' 381 condition returns boolean true or false indicating whether or not the 382 condition matches. Route acceptance or rejection is solely 383 determined by the top-level policy. 385 Note that the called policy may itself call other policies (subject 386 to implementation limitations). The model does not prescribe a 387 nesting depth because this varies among implementations. For 388 example, some major implementation may only support a single level of 389 subroutine recursion. As with any routing policy construction, care 390 must be taken with nested policies to ensure that the effective 391 return value results in the intended behavior. Nested policies are a 392 convenience in many routing policy constructions but creating 393 policies nested beyond a small number of levels (e.g., 2-3) should be 394 discouraged. 396 5. Policy evaluation 398 Evaluation of each policy definition proceeds by evaluating its 399 corresponding individual policy statements in order. When all the 400 condition statements in a policy statement are satisfied, the 401 corresponding action statements are executed. If the actions include 402 either accept-route or reject-route actions, evaluation of the 403 current policy definition stops, and no further policy definitions in 404 the chain are evaluated. 406 If the conditions are not satisfied, then evaluation proceeds to the 407 next policy statement. If none of the policy statement conditions 408 are satisfied, then evaluation of the current policy definition 409 stops, and the next policy definition in the chain is evaluated. 410 When the end of the policy chain is reached, the default route 411 disposition action is performed (i.e., reject-route unless an 412 alternate default action is specified for the chain). 414 Note that the route's pre-policy attributes are always used for 415 testing policy statement conditions. In other words, if actions 416 modify the policy application specific attributes, those 417 modifications are not used for policy statement conditions. 419 6. Applying routing policy 421 Routing policy is applied by defining and attaching policy chains in 422 various routing contexts. Policy chains are sequences of policy 423 definitions (described in Section 4) that have an associated 424 direction (import or export) with respect to the routing context in 425 which they are defined. The routing policy model defines an apply- 426 policy grouping that can be imported and used by other models. As 427 shown below, it allows definition of import and export policy chains, 428 as well as specifying the default route disposition to be used when 429 no policy definition in the chain results in a final decision. 431 +--rw apply-policy 432 | +--rw import-policy* 433 | +--rw default-import-policy? default-policy-type 434 | +--rw export-policy* 435 | +--rw default-export-policy? default-policy-type 437 The default policy defined by the model is to reject the route for 438 both import and export policies. 440 7. Routing protocol-specific policies 442 Routing models that require the ability to apply routing policy may 443 augment the routing policy model with protocol or other specific 444 policy configuration. The routing policy model assumes that 445 additional defined sets, conditions, and actions may all be added by 446 other models. 448 An example of this is shown below, in which the BGP configuration 449 model in [I-D.ietf-idr-bgp-model] adds new defined sets to match on 450 community values or AS paths. The model similarly augments BGP- 451 specific conditions and actions in the corresponding sections of the 452 routing policy model. 454 +--rw routing-policy 455 +--rw defined-sets 456 | +--rw prefix-sets 457 | | +--rw prefix-set* [name] 458 | | +--rw name string 459 | | +--rw mode? enumeration 460 | | +--rw prefixes 461 | | +--rw prefix-list* [ip-prefix masklength-lower 462 | | masklength-upper] 463 | | +--rw ip-prefix inet:ip-prefix 464 | | +--rw masklength-lower uint8 465 | | +--rw masklength-upper uint8 466 | +--rw neighbor-sets 467 | | +--rw neighbor-set* [name] 468 | | +--rw name string 469 | | +--rw address* inet:ip-address 470 | +--rw tag-sets 471 | | +--rw tag-set* [name] 472 | | +--rw name string 473 | | +--rw tag-value* tag-type 474 | +--rw bgp-pol:bgp-defined-sets 475 | +--rw bgp-pol:community-sets 476 | | +--rw bgp-pol:community-set* [community-set-name] 477 | | +--rw bgp-pol:community-set-name string 478 | | +--rw bgp-pol:community-member* union 479 | +--rw bgp-pol:ext-community-sets 480 | | +--rw bgp-pol:ext-community-set* [ext-community-set-name] 481 | | +--rw bgp-pol:ext-community-set-name string 482 | | +--rw bgp-pol:ext-community-member* union 483 | +--rw bgp-pol:as-path-sets 484 | +--rw bgp-pol:as-path-set* [as-path-set-name] 485 | +--rw bgp-pol:as-path-set-name string 486 | +--rw bgp-pol:as-path-set-member* string 487 +--rw policy-definitions 488 +--rw policy-definition* [name] 489 +--rw name string 490 +--rw statements 491 +--rw statement* [name] 492 +--rw name string 493 +--rw conditions 494 | +--rw call-policy? 495 | +--rw source-protocol? identityref 496 | +--rw match-interface 497 | | +--rw interface? 498 | | +--rw subinterface? 499 | +--rw match-prefix-set 500 | | +--rw prefix-set? 501 | | +--rw match-set-options? match-set-options-type 502 | +--rw match-neighbor-set 503 | | +--rw neighbor-set? 504 | +--rw match-tag-set 505 | | +--rw tag-set? 506 | | +--rw match-set-options? match-set-options-type 507 | +--rw bgp-pol:bgp-conditions 508 | +--rw bgp-pol:med-eq? uint32 509 | +--rw bgp-pol:origin-eq? 510 | bgp-types:bgp-origin-attr-type 511 | +--rw bgp-pol:next-hop-in* 512 | inet:ip-address-no-zone 513 | +--rw bgp-pol:afi-safi-in* identityref 514 | +--rw bgp-pol:local-pref-eq? uint32 515 | +--rw bgp-pol:route-type? enumeration 516 | +--rw bgp-pol:community-count 517 | +--rw bgp-pol:as-path-length 518 | +--rw bgp-pol:match-community-set 519 | | +--rw bgp-pol:community-set? 520 | | +--rw bgp-pol:match-set-options? 521 | match-set-options-type 522 | +--rw bgp-pol:match-ext-community-set 523 | | +--rw bgp-pol:ext-community-set? 524 | | +--rw bgp-pol:match-set-options? 525 | | match-set-options-type 526 | +--rw bgp-pol:match-as-path-set 527 | +--rw bgp-pol:as-path-set? 528 | +--rw bgp-pol:match-set-options? 529 | match-set-options-type 530 +--rw actions 531 +--rw policy-result? policy-result-type 532 +--rw set-metric? uint32 533 +--rw set-preference? uint16 534 +--rw bgp-pol:bgp-actions 535 +--rw bgp-pol:set-route-origin? 536 bgp-types:bgp-origin-attr-type 537 +--rw bgp-pol:set-local-pref? uint32 538 +--rw bgp-pol:set-next-hop? bgp-next-hop-type 539 +--rw bgp-pol:set-med? bgp-set-med-type 540 +--rw bgp-pol:set-as-path-prepend 541 | +--rw bgp-pol:repeat-n? uint8 542 +--rw bgp-pol:set-community 543 | +--rw bgp-pol:method? enumeration 544 | +--rw bgp-pol:options? 545 bgp-set-community-option-type 546 | +--rw bgp-pol:inline 547 | | +--rw bgp-pol:communities* union 548 | +--rw bgp-pol:reference 549 | +--rw bgp-pol:community-set-ref? 550 +--rw bgp-pol:set-ext-community 551 +--rw bgp-pol:method? enumeration 552 +--rw bgp-pol:options? 553 bgp-set-community-option-type 554 +--rw bgp-pol:inline 555 | +--rw bgp-pol:communities* union 556 +--rw bgp-pol:reference 557 +--rw bgp-pol:ext-community-set-ref? 559 8. Security Considerations 561 Routing policy configuration has a significant impact on network 562 operations, and, as such, any related model carries potential 563 security risks. 565 YANG data models are generally designed to be used with the NETCONF 566 protocol over an SSH transport. This provides an authenticated and 567 secure channel over which to transfer configuration and operational 568 data. Note that use of alternate transport or data encoding (e.g., 569 JSON over HTTPS) would require similar mechanisms for authenticating 570 and securing access to configuration data. 572 Most of the data elements in the policy model could be considered 573 sensitive from a security standpoint. Unauthorized access or invalid 574 data could cause major disruption. 576 9. IANA Considerations 578 This YANG data model and the component modules currently use a 579 temporary ad-hoc namespace. If and when it is placed on redirected 580 for the standards track, an appropriate namespace URI will be 581 registered in the IETF XML Registry" [RFC3688]. The routing policy 582 YANG modules will be registered in the "YANG Module Names" registry 583 [RFC6020]. 585 10. YANG modules 587 The routing policy model is described by the YANG modules in the 588 sections below. 590 10.1. Routing policy model 592 file "ietf-routing-policy@2019-03-06.yang" 593 module ietf-routing-policy { 595 yang-version "1.1"; 596 namespace "urn:ietf:params:xml:ns:yang:ietf-routing-policy"; 597 prefix rt-pol; 599 import ietf-inet-types { 600 prefix "inet"; 601 } 603 import ietf-yang-types { 604 prefix "yang"; 605 } 607 import ietf-interfaces { 608 prefix "if"; 609 } 611 import ietf-routing { 612 prefix "rt"; 613 } 615 import ietf-interfaces-common { 616 prefix if-cmn; 617 } 619 import ietf-if-l3-vlan { 620 prefix "if-l3-vlan"; 621 } 623 organization 624 "IETF RTGWG - Routing Area Working Group"; 625 contact 626 "WG Web: 627 WG List: 629 Editor: Yingzhen Qu 630 631 Jeff Tantsura 632 633 Acee Lindem 634 635 Xufeng Liu 636 637 Anees Shaikh 638 "; 640 description 641 "This module describes a YANG model for routing policy 642 configuration. It is a limited subset of all of the policy 643 configuration parameters available in the variety of vendor 644 implementations, but supports widely used constructs for 645 managing how routes are imported, exported, and modified across 646 different routing protocols. This module is intended to be 647 used in conjunction with routing protocol configuration modules 648 (e.g., BGP) defined in other models. 650 Route policy expression: 652 Policies are expressed as a set of top-level policy 653 definitions, each of which consists of a sequence of policy 654 statements. Policy statements consist of simple 655 condition-action tuples. Conditions may include mutiple match 656 or comparison operations, and similarly actions may be 657 multitude of changes to route attributes or a final disposition 658 of accepting or rejecting the route. 660 Route policy evaluation: 662 Policy definitions are referenced in routing protocol 663 configurations using import and export configuration 664 statements. The arguments are members of an ordered list of 665 named policy definitions which comprise a policy chain, and 666 optionally, an explicit default policy action (i.e., reject 667 or accept). 669 Evaluation of each policy definition proceeds by evaluating its 670 corresponding individual policy statements in order. When a 671 condition statement in a policy statement is satisfied, the 672 corresponding action statement is executed. If the action 673 statement has either accept-route or reject-route actions, 674 policy evaluation of the current policy definition stops, and 675 no further policy definitions in the chain are evaluated. 677 If the condition is not satisfied, then evaluation proceeds to 678 the next policy statement. If none of the policy statement 679 conditions are satisfied, then evaluation of the current policy 680 definition stops, and the next policy definition in the chain 681 is evaluated. When the end of the policy chain is reached, the 682 default route disposition action is performed (i.e., 683 reject-route unless an alternate default action is specified 684 for the chain). 686 Policy 'subroutines' (or nested policies) are supported by 687 allowing policy statement conditions to reference another 688 policy definition which applies conditions and actions from 689 the referenced policy before returning to the calling policy 690 statement and resuming evaluation. If the called policy 691 results in an accept-route (either explicit or by default), 692 then the subroutine returns an effective true value to the 693 calling policy. Similarly, a reject-route action returns 694 false. If the subroutine returns true, the calling policy 695 continues to evaluate the remaining conditions (using a 696 modified route if the subroutine performed any changes to the 697 route)."; 699 revision "2019-03-06" { 700 description 701 "Initial revision."; 702 reference 703 "RFC XXXX: Routing Policy Configuration Model for Service 704 Provider Networks"; 705 } 707 // typedef statements 709 typedef default-policy-type { 710 // this typedef retained for name compatibiity with default 711 // import and export policy 712 type enumeration { 713 enum accept-route { 714 description 715 "Default policy to accept the route"; 716 } 717 enum reject-route { 718 description 719 "Default policy to reject the route"; 720 } 721 } 722 description 723 "Type used to specify route disposition in 724 a policy chain"; 726 } 728 typedef policy-result-type { 729 type enumeration { 730 enum accept-route { 731 description "Policy accepts the route"; 732 } 733 enum reject-route { 734 description "Policy rejects the route"; 735 } 736 } 737 description 738 "Type used to specify route disposition in 739 a policy chain"; 740 } 742 typedef tag-type { 743 type union { 744 type uint32; 745 type yang:hex-string; 746 } 747 description "Type for expressing route tags on a local system, 748 including IS-IS and OSPF; may be expressed as either decimal 749 or hexadecimal integer"; 750 reference 751 "RFC 2178 - OSPF Version 2 752 RFC 5130 - A Policy Control Mechanism in IS-IS Using 753 Administrative Tags"; 754 } 756 typedef match-set-options-type { 757 type enumeration { 758 enum any { 759 description "Match is true if given value matches any member 760 of the defined set"; 761 } 762 enum all { 763 description "Match is true if given value matches all 764 members of the defined set"; 765 } 766 enum invert { 767 description "Match is true if given value does not match any 768 member of the defined set"; 769 } 770 } 771 default any; 772 description 773 "Options that govern the behavior of a match statement. The 774 default behavior is any, i.e., the given value matches any 775 of the members of the defined set"; 776 } 778 // grouping statements 780 grouping prefix-set { 781 description 782 "Configuration data for prefix sets used in policy 783 definitions."; 785 leaf name { 786 type string; 787 description 788 "Name of the prefix set -- this is used as a label to 789 reference the set in match conditions"; 790 } 792 leaf mode { 793 type enumeration { 794 enum ipv4 { 795 description 796 "Prefix set contains IPv4 prefixes only"; 797 } 798 enum ipv6 { 799 description 800 "Prefix set contains IPv6 prefixes only"; 801 } 802 enum mixed { 803 description 804 "Prefix set contains mixed IPv4 and IPv6 prefixes"; 805 } 806 } 807 description 808 "Indicates the mode of the prefix set, in terms of which 809 address families (IPv4, IPv6, or both) are present. The 810 mode provides a hint, but the device must validate that all 811 prefixes are of the indicated type, and is expected to 812 reject the configuration if there is a discrepancy. The 813 MIXED mode may not be supported on devices that require 814 prefix sets to be of only one address family."; 815 } 817 } 819 grouping prefix-set-top { 820 description 821 "Top-level data definitions for a list of IPv4 or IPv6 822 prefixes which are matched as part of a policy"; 824 container prefix-sets { 825 description 826 "Enclosing container "; 828 list prefix-set { 829 key "name"; 830 description 831 "List of the defined prefix sets"; 833 uses prefix-set; 835 uses prefix-top; 836 } 837 } 838 } 840 grouping prefix { 841 description 842 "Configuration data for a prefix definition"; 844 leaf ip-prefix { 845 type inet:ip-prefix; 846 mandatory true; 847 description 848 "The prefix member in CIDR notation -- while the 849 prefix may be either IPv4 or IPv6, most 850 implementations require all members of the prefix set 851 to be the same address family. Mixing address types in 852 the same prefix set is likely to cause an error."; 853 } 855 leaf masklength-lower { 856 type uint8; 857 description 858 "Masklength range lower bound."; 859 } 860 leaf masklength-upper { 861 type uint8 { 862 range "1..128"; 863 } 864 must "../masklength-upper >= ../masklength-lower" { 865 error-message "The upper bound should not be less" 866 + "than lower bound."; 867 } 868 description 869 "Masklength range upper bound. 871 The combination of masklength-lower and masklength-upper 872 define a range for the mask length, or single 'exact' 873 length if masklength-lower and masklenght-upper are equal. 875 Example: 10.3.192.0/21 through 10.3.192.0/24 would be 876 expressed as prefix: 10.3.192.0/21, 877 masklength-lower=21, 878 masklength-upper=24 880 Example: 10.3.192.0/21 (an exact match) would be 881 expressed as prefix: 10.3.192.0/21, 882 masklength-lower=21, 883 masklength-upper=21"; 884 } 885 } 887 grouping prefix-top { 888 description 889 "Top-level grouping for prefixes in a prefix list"; 891 container prefixes { 892 description 893 "Enclosing container for the list of prefixes in a policy 894 prefix list"; 896 list prefix-list { 897 key "ip-prefix masklength-lower masklength-upper"; 898 description 899 "List of prefixes in the prefix set"; 901 uses prefix; 902 } 903 } 904 } 906 grouping neighbor-set { 907 description 908 "This grouping provides neighbor set definitions"; 910 leaf name { 911 type string; 912 description 913 "Name of the neighbor set -- this is used as a label 914 to reference the set in match conditions"; 915 } 916 leaf-list address { 917 type inet:ip-address; 918 description 919 "List of IP addresses in the neighbor set"; 920 } 921 } 923 grouping neighbor-set-top { 924 description 925 "Top-level data definition for a list of IPv4 or IPv6 926 neighbors which can be matched in a routing policy"; 928 container neighbor-sets { 929 description 930 "Enclosing container for the list of neighbor set 931 definitions"; 933 list neighbor-set { 934 key "name"; 935 description 936 "List of defined neighbor sets for use in policies."; 938 uses neighbor-set; 939 } 940 } 941 } 943 grouping tag-set { 944 description 945 "This grouping provides tag set definitions."; 947 leaf name { 948 type string; 949 description 950 "Name of the tag set -- this is used as a label to reference 951 the set in match conditions"; 952 } 954 leaf-list tag-value { 955 type tag-type; 956 description 957 "Value of the tag set member"; 958 } 959 } 961 grouping tag-set-top { 962 description 963 "Top-level data definitions for a list of tags which can 964 be matched in policies"; 966 container tag-sets { 967 description 968 "Enclosing container for the list of tag sets."; 970 list tag-set { 971 key "name"; 972 description 973 "List of tag set definitions."; 975 uses tag-set; 977 } 978 } 979 } 981 grouping match-set-options-group { 982 description 983 "Grouping containing options relating to how a particular set 984 should be matched"; 986 leaf match-set-options { 987 type match-set-options-type; 988 description 989 "Optional parameter that governs the behavior of the 990 match operation"; 991 } 992 } 994 grouping match-set-options-restricted-group { 995 description 996 "Grouping for a restricted set of match operation modifiers"; 998 leaf match-set-options { 999 type match-set-options-type { 1000 enum any { 1001 description "Match is true if given value matches any 1002 member of the defined set"; 1003 } 1004 enum invert { 1005 description "Match is true if given value does not match 1006 any member of the defined set"; 1007 } 1008 } 1009 description 1010 "Optional parameter that governs the behavior of the 1011 match operation. This leaf only supports matching on ANY 1012 member of the set or inverting the match. Matching on ALL 1013 is not supported"; 1014 } 1015 } 1017 grouping match-interface-condition { 1018 description 1019 "This grouping provides interface match condition"; 1021 container match-interface { 1022 leaf interface { 1023 type leafref { 1024 path "/if:interfaces/if:interface/if:name"; 1025 } 1026 description 1027 "Reference to a base interface. If a reference to a 1028 subinterface is required, this leaf must be specified 1029 to indicate the base interface."; 1030 } 1031 leaf subinterface { 1032 type leafref { 1033 path "/if:interfaces/if:interface/if-cmn:encapsulation" 1034 + "/if-l3-vlan:dot1q-vlan" 1035 + "/if-l3-vlan:outer-tag/if-l3-vlan:vlan-id"; 1036 } 1037 description 1038 "Reference to a subinterface -- this requires the base 1039 interface to be specified using the interface leaf in 1040 this container. If only a reference to a base interface 1041 is requuired, this leaf should not be set."; 1042 } 1044 description 1045 "Container for interface match conditions"; 1046 } 1047 } 1049 grouping prefix-set-condition { 1050 description 1051 "This grouping provides prefix-set conditions"; 1053 container match-prefix-set { 1054 leaf prefix-set { 1055 type leafref { 1056 path "../../../../../../../defined-sets/" + 1057 "prefix-sets/prefix-set/name"; 1058 } 1059 description "References a defined prefix set"; 1060 } 1061 uses match-set-options-restricted-group; 1063 description 1064 "Match a referenced prefix-set according to the logic 1065 defined in the match-set-options leaf"; 1066 } 1067 } 1069 grouping neighbor-set-condition { 1070 description 1071 "This grouping provides neighbor-set conditions"; 1073 container match-neighbor-set { 1074 leaf neighbor-set { 1075 type leafref { 1076 path "../../../../../../../defined-sets/neighbor-sets/" + 1077 "neighbor-set/name"; 1078 require-instance true; 1079 } 1080 description "References a defined neighbor set"; 1081 } 1083 description 1084 "Match a referenced neighbor set according to the logic 1085 defined in the match-set-options-leaf"; 1086 } 1087 } 1089 grouping tag-set-condition { 1090 description 1091 "This grouping provides tag-set conditions"; 1093 container match-tag-set { 1094 leaf tag-set { 1095 type leafref { 1096 path "../../../../../../../defined-sets/tag-sets" + 1097 "/tag-set/name"; 1098 require-instance true; 1099 } 1100 description "References a defined tag set"; 1101 } 1102 uses match-set-options-restricted-group; 1104 description 1105 "Match a referenced tag set according to the logic defined 1106 in the match-options-set leaf"; 1107 } 1108 } 1110 grouping generic-conditions { 1111 description "Condition statement definitions for checking 1112 membership in a generic defined set"; 1114 uses match-interface-condition; 1115 uses prefix-set-condition; 1116 uses neighbor-set-condition; 1117 uses tag-set-condition; 1119 } 1121 grouping policy-conditions { 1122 description 1123 "Data for general policy conditions, i.e., those 1124 not related to match-sets"; 1126 leaf call-policy { 1127 type leafref { 1128 path "../../../../../../" + 1129 "rt-pol:policy-definitions/" + 1130 "rt-pol:policy-definition/rt-pol:name"; 1131 require-instance true; 1132 } 1133 description 1134 "Applies the statements from the specified policy 1135 definition and then returns control the current 1136 policy statement. Note that the called policy may 1137 itself call other policies (subject to 1138 implementation limitations). This is intended to 1139 provide a policy 'subroutine' capability. The 1140 called policy should contain an explicit or a 1141 default route disposition that returns an 1142 effective true (accept-route) or false 1143 (reject-route), otherwise the behavior may be 1144 ambiguous and implementation dependent"; 1145 } 1147 leaf source-protocol { 1148 type identityref { 1149 base rt:control-plane-protocol; 1150 } 1151 description 1152 "Condition to check the protocol / method used to install 1153 the route into the local routing table"; 1154 } 1155 } 1157 grouping policy-conditions-top { 1158 description 1159 "Top-level grouping for policy conditions"; 1161 container conditions { 1162 description 1163 "Condition statements for the current policy statement"; 1165 uses policy-conditions; 1167 uses generic-conditions; 1168 } 1169 } 1171 grouping policy-statements { 1172 description 1173 "Data for policy statements"; 1175 leaf name { 1176 type string; 1177 description 1178 "Name of the policy statement"; 1179 } 1180 } 1182 grouping policy-actions { 1183 description 1184 "Top-level grouping for policy actions"; 1186 container actions { 1187 description 1188 "Top-level container for policy action statements"; 1190 leaf policy-result { 1191 type policy-result-type; 1192 description 1193 "Select the final disposition for the route, either 1194 accept or reject."; 1195 } 1196 leaf set-metric { 1197 type uint32; 1198 description 1199 "Set a new metric for the route."; 1201 } 1202 leaf set-preference { 1203 type uint16; 1204 description 1205 "Set a new preference for the route."; 1206 } 1207 } 1208 } 1210 grouping policy-statements-top { 1211 description 1212 "Top-level grouping for the policy statements list"; 1214 container statements { 1215 description 1216 "Enclosing container for policy statements"; 1218 list statement { 1219 key "name"; 1220 ordered-by user; 1221 description 1222 "Policy statements group conditions and actions 1223 within a policy definition. They are evaluated in 1224 the order specified (see the description of policy 1225 evaluation at the top of this module."; 1227 uses policy-statements; 1229 uses policy-conditions-top; 1230 uses policy-actions; 1231 } 1232 } 1233 } 1235 grouping policy-definitions { 1236 description 1237 "This grouping provides policy definitions"; 1239 leaf name { 1240 type string; 1241 description 1242 "Name of the top-level policy definition -- this name 1243 is used in references to the current policy"; 1244 } 1245 } 1247 grouping apply-policy-import { 1248 description 1249 "Grouping for applying import policies"; 1251 leaf-list import-policy { 1252 type leafref { 1253 path "/rt-pol:routing-policy/rt-pol:policy-definitions/" + 1254 "rt-pol:policy-definition/rt-pol:name"; 1255 require-instance true; 1256 } 1257 ordered-by user; 1258 description 1259 "List of policy names in sequence to be applied on 1260 receiving a routing update in the current context, e.g., 1261 for the current peer group, neighbor, address family, 1262 etc."; 1263 } 1265 leaf default-import-policy { 1266 type default-policy-type; 1267 default reject-route; 1268 description 1269 "Explicitly set a default policy if no policy definition 1270 in the import policy chain is satisfied."; 1271 } 1273 } 1275 grouping apply-policy-export { 1276 description 1277 "Grouping for applying export policies"; 1279 leaf-list export-policy { 1280 type leafref { 1281 path "/rt-pol:routing-policy/rt-pol:policy-definitions/" + 1282 "rt-pol:policy-definition/rt-pol:name"; 1283 require-instance true; 1284 } 1285 ordered-by user; 1286 description 1287 "List of policy names in sequence to be applied on 1288 sending a routing update in the current context, e.g., 1289 for the current peer group, neighbor, address family, 1290 etc."; 1291 } 1293 leaf default-export-policy { 1294 type default-policy-type; 1295 default reject-route; 1296 description 1297 "Explicitly set a default policy if no policy definition 1298 in the export policy chain is satisfied."; 1299 } 1300 } 1302 grouping apply-policy { 1303 description 1304 "Configuration data for routing policies"; 1306 uses apply-policy-import; 1307 uses apply-policy-export; 1309 container apply-policy-state { 1310 description 1311 "Operational state associated with routing policy"; 1313 //TODO: identify additional state data beyond the intended 1314 //policy configuration. 1315 } 1317 } 1319 grouping apply-policy-group { 1320 description 1321 "Top level container for routing policy applications. This 1322 grouping is intended to be used in routing models where 1323 needed."; 1325 container apply-policy { 1326 description 1327 "Anchor point for routing policies in the model. 1328 Import and export policies are with respect to the local 1329 routing table, i.e., export (send) and import (receive), 1330 depending on the context."; 1332 uses apply-policy; 1334 } 1335 } 1337 container routing-policy { 1338 description 1339 "Top-level container for all routing policy"; 1341 container defined-sets { 1342 description 1343 "Predefined sets of attributes used in policy match 1344 statements"; 1346 uses prefix-set-top; 1347 uses neighbor-set-top; 1348 uses tag-set-top; 1349 } 1351 container policy-definitions { 1352 description 1353 "Enclosing container for the list of top-level policy 1354 definitions"; 1356 list policy-definition { 1357 key "name"; 1358 description 1359 "List of top-level policy definitions, keyed by unique 1360 name. These policy definitions are expected to be 1361 referenced (by name) in policy chains specified in import 1362 or export configuration statements."; 1364 uses policy-definitions; 1366 uses policy-statements-top; 1367 } 1368 } 1369 } 1370 } 1371 1373 11. Policy examples 1375 Below we show an example of XML-encoded configuration data using the 1376 routing policy and BGP models to illustrate both how policies are 1377 defined, and also how they can be applied. Note that the XML has 1378 been simplified for readability. 1380 1382 12. References 1383 12.1. Normative references 1385 [I-D.ietf-netmod-intf-ext-yang] 1386 Wilton, R., Ball, D., tsingh@juniper.net, t., and S. 1387 Sivaraj, "Common Interface Extension YANG Data Models", 1388 draft-ietf-netmod-intf-ext-yang-07 (work in progress), 1389 March 2019. 1391 [I-D.ietf-netmod-sub-intf-vlan-model] 1392 Wilton, R., Ball, D., tapsingh@cisco.com, t., and S. 1393 Sivaraj, "Sub-interface VLAN YANG Data Models", draft- 1394 ietf-netmod-sub-intf-vlan-model-05 (work in progress), 1395 March 2019. 1397 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1398 Requirement Levels", BCP 14, RFC 2119, 1399 DOI 10.17487/RFC2119, March 1997, 1400 . 1402 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1403 DOI 10.17487/RFC3688, January 2004, 1404 . 1406 [RFC4271] Rekhter, Y., Ed., Li, T., Ed., and S. Hares, Ed., "A 1407 Border Gateway Protocol 4 (BGP-4)", RFC 4271, 1408 DOI 10.17487/RFC4271, January 2006, 1409 . 1411 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 1412 the Network Configuration Protocol (NETCONF)", RFC 6020, 1413 DOI 10.17487/RFC6020, October 2010, 1414 . 1416 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 1417 RFC 6991, DOI 10.17487/RFC6991, July 2013, 1418 . 1420 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1421 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1422 . 1424 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1425 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1426 May 2017, . 1428 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 1429 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 1430 . 1432 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 1433 and R. Wilton, "Network Management Datastore Architecture 1434 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 1435 . 1437 [RFC8343] Bjorklund, M., "A YANG Data Model for Interface 1438 Management", RFC 8343, DOI 10.17487/RFC8343, March 2018, 1439 . 1441 [RFC8349] Lhotka, L., Lindem, A., and Y. Qu, "A YANG Data Model for 1442 Routing Management (NMDA Version)", RFC 8349, 1443 DOI 10.17487/RFC8349, March 2018, 1444 . 1446 12.2. Informative references 1448 [I-D.ietf-idr-bgp-model] 1449 Jethanandani, M., Patel, K., and S. Hares, "BGP YANG Model 1450 for Service Provider Networks", draft-ietf-idr-bgp- 1451 model-06 (work in progress), June 2019. 1453 Appendix A. Acknowledgements 1455 The routing policy module defined in this draft is based on the 1456 OpenConfig route policy model. The authors would like to thank to 1457 OpenConfig for their contributions, especially Anees Shaikh, Rob 1458 Shakir, Kevin D'Souza, and Chris Chase. 1460 The authors are grateful for valuable contributions to this document 1461 and the associated models from: Ebben Aires, Luyuan Fang, Josh 1462 George, Stephane Litkowski, Ina Minei, Carl Moberg, Eric Osborne, 1463 Steve Padgett, Juergen Schoenwaelder, Jim Uttaro, Russ White, and 1464 John Heasley. 1466 Authors' Addresses 1468 Yingzhen Qu 1469 Futurewei 1470 2330 Central Expressway 1471 Santa Clara CA 95050 1472 USA 1474 Email: yingzhen.qu@futurewei.com 1475 Jeff Tantsura 1476 Apstra 1478 Email: jefftant.ietf@gmail.com 1480 Acee Lindem 1481 Cisco 1482 301 Mindenhall Way 1483 Cary, NC 27513 1484 US 1486 Email: acee@cisco.com 1488 Xufeng Liu 1489 Volta Networks 1491 Email: xufeng.liu.ietf@gmail.com