idnits 2.17.1 draft-ietf-rtgwg-policy-model-04.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 456 has weird spacing: '...h-lower uin...' == Line 457 has weird spacing: '...h-upper uin...' == Line 469 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 (October 19, 2018) is 2016 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Outdated reference: A later version (-13) exists of draft-ietf-netmod-intf-ext-yang-06 == Outdated reference: A later version (-17) exists of draft-ietf-idr-bgp-model-03 Summary: 0 errors (**), 0 flaws (~~), 11 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 RTGWG Y. Qu 3 Internet-Draft Huawei 4 Intended status: Informational J. Tantsura 5 Expires: April 22, 2019 Apstra 6 A. Lindem 7 Cisco 8 X. Liu 9 Volta Networks 10 October 19, 2018 12 A YANG Data Model for Routing Policy Management 13 draft-ietf-rtgwg-policy-model-04 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 April 22, 2019. 39 Copyright Notice 41 Copyright (c) 2018 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 . . . . . . . . . . . . . . . . . . . . . . 9 68 6. Applying routing policy . . . . . . . . . . . . . . . . . . . 10 69 7. Routing protocol-specific policies . . . . . . . . . . . . . 10 70 8. Security Considerations . . . . . . . . . . . . . . . . . . . 13 71 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13 72 10. YANG modules . . . . . . . . . . . . . . . . . . . . . . . . 13 73 10.1. Routing policy model . . . . . . . . . . . . . . . . . . 13 74 11. Policy examples . . . . . . . . . . . . . . . . . . . . . . . 30 75 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 30 76 12.1. Normative references . . . . . . . . . . . . . . . . . . 30 77 12.2. Informative references . . . . . . . . . . . . . . . . . 31 78 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 31 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 (either explicit or by default), then the 370 subroutine returns an effective boolean true value to the calling 371 policy. For the calling policy, this is equivalent to a condition 372 statement evaluating to a true value and evaluation of the policy 373 continues (see Section 5). Note that the called policy may also 374 modify attributes of the route in its action statements. Similarly, 375 a reject-route action returns false and the calling policy evaluation 376 will be affected accordingly. Consequently, a subroutine cannot 377 explicitly accept or reject a route. Rather it merely provides an 378 indication that 'call-policy' condition returns boolean true or false 379 indicating whether or not the condition matches. Route acceptance or 380 rejection is solely determined by the top-level policy. 382 Note that the called policy may itself call other policies (subject 383 to implementation limitations). The model does not prescribe a 384 nesting depth because this varies among implementations. For 385 example, some major implementation may only support a single level of 386 subroutine recursion. As with any routing policy construction, care 387 must be taken with nested policies to ensure that the effective 388 return value results in the intended behavior. Nested policies are a 389 convenience in many routing policy constructions but creating 390 policies nested beyond a small number of levels (e.g., 2-3) should be 391 discouraged. 393 5. Policy evaluation 395 Evaluation of each policy definition proceeds by evaluating its 396 corresponding individual policy statements in order. When a 397 condition statement in a policy statement is satisfied, the 398 corresponding action statement is executed. If the action statement 399 has either accept-route or reject-route actions, evaluation of the 400 current policy definition stops, and no further policy definitions in 401 the chain are evaluated. 403 If the condition is not satisfied, then evaluation proceeds to the 404 next policy statement. If none of the policy statement conditions 405 are satisfied, then evaluation of the current policy definition 406 stops, and the next policy definition in the chain is evaluated. 407 When the end of the policy chain is reached, the default route 408 disposition action is performed (i.e., reject-route unless an 409 alternate default action is specified for the chain). 411 6. Applying routing policy 413 Routing policy is applied by defining and attaching policy chains in 414 various routing contexts. Policy chains are sequences of policy 415 definitions (described in Section 4) that have an associated 416 direction (import or export) with respect to the routing context in 417 which they are defined. The routing policy model defines an apply- 418 policy grouping that can be imported and used by other models. As 419 shown below, it allows definition of import and export policy chains, 420 as well as specifying the default route disposition to be used when 421 no policy definition in the chain results in a final decision. 423 +--rw apply-policy 424 | +--rw import-policy* 425 | +--rw default-import-policy? default-policy-type 426 | +--rw export-policy* 427 | +--rw default-export-policy? default-policy-type 429 The default policy defined by the model is to reject the route for 430 both import and export policies. 432 7. Routing protocol-specific policies 434 Routing models that require the ability to apply routing policy may 435 augment the routing policy model with protocol or other specific 436 policy configuration. The routing policy model assumes that 437 additional defined sets, conditions, and actions may all be added by 438 other models. 440 An example of this is shown below, in which the BGP configuration 441 model in [I-D.ietf-idr-bgp-model] adds new defined sets to match on 442 community values or AS paths. The model similarly augments BGP- 443 specific conditions and actions in the corresponding sections of the 444 routing policy model. 446 +--rw routing-policy 447 +--rw defined-sets 448 | +--rw prefix-sets 449 | | +--rw prefix-set* [name] 450 | | +--rw name string 451 | | +--rw mode? enumeration 452 | | +--rw prefixes 453 | | +--rw prefix-list* [ip-prefix masklength-lower 454 | | masklength-upper] 455 | | +--rw ip-prefix inet:ip-prefix 456 | | +--rw masklength-lower uint8 457 | | +--rw masklength-upper uint8 458 | +--rw neighbor-sets 459 | | +--rw neighbor-set* [name] 460 | | +--rw name string 461 | | +--rw address* inet:ip-address 462 | +--rw tag-sets 463 | | +--rw tag-set* [name] 464 | | +--rw name string 465 | | +--rw tag-value* tag-type 466 | +--rw bgp-pol:bgp-defined-sets 467 | +--rw bgp-pol:community-sets 468 | | +--rw bgp-pol:community-set* [community-set-name] 469 | | +--rw bgp-pol:community-set-name string 470 | | +--rw bgp-pol:community-member* union 471 | +--rw bgp-pol:ext-community-sets 472 | | +--rw bgp-pol:ext-community-set* [ext-community-set-name] 473 | | +--rw bgp-pol:ext-community-set-name string 474 | | +--rw bgp-pol:ext-community-member* union 475 | +--rw bgp-pol:as-path-sets 476 | +--rw bgp-pol:as-path-set* [as-path-set-name] 477 | +--rw bgp-pol:as-path-set-name string 478 | +--rw bgp-pol:as-path-set-member* string 479 +--rw policy-definitions 480 +--rw policy-definition* [name] 481 +--rw name string 482 +--rw statements 483 +--rw statement* [name] 484 +--rw name string 485 +--rw conditions 486 | +--rw call-policy? 487 | +--rw source-protocol? identityref 488 | +--rw match-interface 489 | | +--rw interface? 490 | | +--rw subinterface? 491 | +--rw match-prefix-set 492 | | +--rw prefix-set? 493 | | +--rw match-set-options? match-set-options-type 494 | +--rw match-neighbor-set 495 | | +--rw neighbor-set? 496 | +--rw match-tag-set 497 | | +--rw tag-set? 498 | | +--rw match-set-options? match-set-options-type 499 | +--rw bgp-pol:bgp-conditions 500 | +--rw bgp-pol:med-eq? uint32 501 | +--rw bgp-pol:origin-eq? 502 | bgp-types:bgp-origin-attr-type 503 | +--rw bgp-pol:next-hop-in* 504 | inet:ip-address-no-zone 505 | +--rw bgp-pol:afi-safi-in* identityref 506 | +--rw bgp-pol:local-pref-eq? uint32 507 | +--rw bgp-pol:route-type? enumeration 508 | +--rw bgp-pol:community-count 509 | +--rw bgp-pol:as-path-length 510 | +--rw bgp-pol:match-community-set 511 | | +--rw bgp-pol:community-set? 512 | | +--rw bgp-pol:match-set-options? 513 | match-set-options-type 514 | +--rw bgp-pol:match-ext-community-set 515 | | +--rw bgp-pol:ext-community-set? 516 | | +--rw bgp-pol:match-set-options? 517 | | match-set-options-type 518 | +--rw bgp-pol:match-as-path-set 519 | +--rw bgp-pol:as-path-set? 520 | +--rw bgp-pol:match-set-options? 521 | match-set-options-type 522 +--rw actions 523 +--rw policy-result? policy-result-type 524 +--rw set-metric? uint32 525 +--rw set-preference? uint16 526 +--rw bgp-pol:bgp-actions 527 +--rw bgp-pol:set-route-origin? 528 bgp-types:bgp-origin-attr-type 529 +--rw bgp-pol:set-local-pref? uint32 530 +--rw bgp-pol:set-next-hop? bgp-next-hop-type 531 +--rw bgp-pol:set-med? bgp-set-med-type 532 +--rw bgp-pol:set-as-path-prepend 533 | +--rw bgp-pol:repeat-n? uint8 534 +--rw bgp-pol:set-community 535 | +--rw bgp-pol:method? enumeration 536 | +--rw bgp-pol:options? 537 bgp-set-community-option-type 538 | +--rw bgp-pol:inline 539 | | +--rw bgp-pol:communities* union 540 | +--rw bgp-pol:reference 541 | +--rw bgp-pol:community-set-ref? 542 +--rw bgp-pol:set-ext-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:ext-community-set-ref? 551 8. Security Considerations 553 Routing policy configuration has a significant impact on network 554 operations, and, as such, any related model carries potential 555 security risks. 557 YANG data models are generally designed to be used with the NETCONF 558 protocol over an SSH transport. This provides an authenticated and 559 secure channel over which to transfer configuration and operational 560 data. Note that use of alternate transport or data encoding (e.g., 561 JSON over HTTPS) would require similar mechanisms for authenticating 562 and securing access to configuration data. 564 Most of the data elements in the policy model could be considered 565 sensitive from a security standpoint. Unauthorized access or invalid 566 data could cause major disruption. 568 9. IANA Considerations 570 This YANG data model and the component modules currently use a 571 temporary ad-hoc namespace. If and when it is placed on redirected 572 for the standards track, an appropriate namespace URI will be 573 registered in the IETF XML Registry" [RFC3688]. The routing policy 574 YANG modules will be registered in the "YANG Module Names" registry 575 [RFC6020]. 577 10. YANG modules 579 The routing policy model is described by the YANG modules in the 580 sections below. 582 10.1. Routing policy model 584 file "ietf-routing-policy@2018-10-19.yang" 585 module ietf-routing-policy { 587 yang-version "1.1"; 588 namespace "urn:ietf:params:xml:ns:yang:ietf-routing-policy"; 589 prefix rt-pol; 590 import ietf-inet-types { 591 prefix "inet"; 592 } 594 import ietf-yang-types { 595 prefix "yang"; 596 } 598 import ietf-interfaces { 599 prefix "if"; 600 } 602 import ietf-routing { 603 prefix "rt"; 604 } 606 import ietf-interfaces-common { 607 prefix if-cmn; 608 } 610 import ietf-if-l3-vlan { 611 prefix "if-l3-vlan"; 612 } 614 organization 615 "IETF RTGWG - Routing Area Working Group"; 616 contact 617 "WG Web: 618 WG List: 620 Editor: Yingzhen Qu 621 622 Jeff Tantsura 623 624 Acee Lindem 625 626 Xufeng Liu 627 628 Anees Shaikh 629 "; 631 description 632 "This module describes a YANG model for routing policy 633 configuration. It is a limited subset of all of the policy 634 configuration parameters available in the variety of vendor 635 implementations, but supports widely used constructs for 636 managing how routes are imported, exported, and modified across 637 different routing protocols. This module is intended to be used 638 in conjunction with routing protocol configuration modules 639 (e.g., BGP) defined in other models. 641 Route policy expression: 643 Policies are expressed as a set of top-level policy definitions, 644 each of which consists of a sequence of policy statements. 645 Policy statements consist of simple condition-action tuples. 646 Conditions may include mutiple match or comparison operations, 647 and similarly actions may be multitude of changes to route 648 attributes or a final disposition of accepting or rejecting the 649 route. 651 Route policy evaluation: 653 Policy definitions are referenced in routing protocol 654 configurations using import and export configuration statements. 655 The arguments are members of an ordered list of named policy 656 definitions which comprise a policy chain, and optionally, an 657 explicit default policy action (i.e., reject or accept). 659 Evaluation of each policy definition proceeds by evaluating its 660 corresponding individual policy statements in order. When a 661 condition statement in a policy statement is satisfied, the 662 corresponding action statement is executed. If the action 663 statement has either accept-route or reject-route actions, 664 policy evaluation of the current policy definition stops, and 665 no further policy definitions in the chain are evaluated. 667 If the condition is not satisfied, then evaluation proceeds to 668 the next policy statement. If none of the policy statement 669 conditions are satisfied, then evaluation of the current policy 670 definition stops, and the next policy definition in the chain is 671 evaluated. When the end of the policy chain is reached, the 672 default route disposition action is performed (i.e., 673 reject-route unless an alternate default action is specified 674 for the chain). 676 Policy 'subroutines' (or nested policies) are supported by 677 allowing policy statement conditions to reference another policy 678 definition which applies conditions and actions from the 679 referenced policy before returning to the calling policy 680 statement and resuming evaluation. If the called policy 681 results in an accept-route (either explicit or by default), then 682 the subroutine returns an effective true value to the calling 683 policy. Similarly, a reject-route action returns false. If the 684 subroutine returns true, the calling policy continues to 685 evaluate the remaining conditions (using a modified route if the 686 subroutine performed any changes to the route)."; 688 revision "2018-10-19" { 689 description 690 "Initial revision."; 691 reference 692 "RFC XXXX: Routing Policy Configuration Model for Service 693 Provider Networks"; 694 } 696 // typedef statements 698 typedef default-policy-type { 699 // this typedef retained for name compatibiity with default 700 // import and export policy 701 type enumeration { 702 enum accept-route { 703 description 704 "Default policy to accept the route"; 705 } 706 enum reject-route { 707 description 708 "Default policy to reject the route"; 709 } 710 } 711 description 712 "Type used to specify route disposition in 713 a policy chain"; 714 } 716 typedef policy-result-type { 717 type enumeration { 718 enum accept-route { 719 description "Policy accepts the route"; 720 } 721 enum reject-route { 722 description "Policy rejects the route"; 723 } 724 } 725 description 726 "Type used to specify route disposition in 727 a policy chain"; 728 } 729 typedef tag-type { 730 type union { 731 type uint32; 732 type yang:hex-string; 733 } 734 description "Type for expressing route tags on a local system, 735 including IS-IS and OSPF; may be expressed as either decimal 736 or hexadecimal integer"; 737 reference 738 "RFC 2178 - OSPF Version 2 739 RFC 5130 - A Policy Control Mechanism in IS-IS Using 740 Administrative Tags"; 741 } 743 typedef match-set-options-type { 744 type enumeration { 745 enum any { 746 description "Match is true if given value matches any member 747 of the defined set"; 748 } 749 enum all { 750 description "Match is true if given value matches all 751 members of the defined set"; 752 } 753 enum invert { 754 description "Match is true if given value does not match any 755 member of the defined set"; 756 } 757 } 758 default any; 759 description 760 "Options that govern the behavior of a match statement. The 761 default behavior is any, i.e., the given value matches any 762 of the members of the defined set"; 763 } 765 // grouping statements 767 grouping prefix-set { 768 description 769 "Configuration data for prefix sets used in policy 770 definitions."; 772 leaf name { 773 type string; 774 description 775 "Name of the prefix set -- this is used as a label to 776 reference the set in match conditions"; 777 } 779 leaf mode { 780 type enumeration { 781 enum ipv4 { 782 description 783 "Prefix set contains IPv4 prefixes only"; 784 } 785 enum ipv6 { 786 description 787 "Prefix set contains IPv6 prefixes only"; 788 } 789 enum mixed { 790 description 791 "Prefix set contains mixed IPv4 and IPv6 prefixes"; 792 } 793 } 794 description 795 "Indicates the mode of the prefix set, in terms of which 796 address families (IPv4, IPv6, or both) are present. The 797 mode provides a hint, but the device must validate that all 798 prefixes are of the indicated type, and is expected to 799 reject the configuration if there is a discrepancy. The 800 MIXED mode may not be supported on devices that require 801 prefix sets to be of only one address family."; 802 } 804 } 806 grouping prefix-set-top { 807 description 808 "Top-level data definitions for a list of IPv4 or IPv6 809 prefixes which are matched as part of a policy"; 811 container prefix-sets { 812 description 813 "Enclosing container "; 815 list prefix-set { 816 key "name"; 817 description 818 "List of the defined prefix sets"; 820 uses prefix-set; 822 uses prefix-top; 823 } 825 } 826 } 828 grouping prefix { 829 description 830 "Configuration data for a prefix definition"; 832 leaf ip-prefix { 833 type inet:ip-prefix; 834 mandatory true; 835 description 836 "The prefix member in CIDR notation -- while the 837 prefix may be either IPv4 or IPv6, most 838 implementations require all members of the prefix set 839 to be the same address family. Mixing address types in 840 the same prefix set is likely to cause an error."; 841 } 843 leaf masklength-lower { 844 type uint8; 845 description 846 "Masklength range lower bound."; 847 } 848 leaf masklength-upper { 849 type uint8 { 850 range "1..128"; 851 } 852 must "../masklength-upper >= ../masklength-lower" { 853 error-message "The upper bound should not be less" 854 + "than lower bound."; 855 } 856 description 857 "Masklength range upper bound. 859 The combination of masklength-lower and masklength-upper 860 define a range for the mask length, or single 'exact' 861 length if masklength-lower and masklenght-upper are equal. 863 Example: 10.3.192.0/21 through 10.3.192.0/24 would be 864 expressed as prefix: 10.3.192.0/21, 865 masklength-lower=21, 866 masklength-upper=24 868 Example: 10.3.192.0/21 (an exact match) would be 869 expressed as prefix: 10.3.192.0/21, 870 masklength-lower=21, 871 masklength-upper=21"; 872 } 874 } 876 grouping prefix-top { 877 description 878 "Top-level grouping for prefixes in a prefix list"; 880 container prefixes { 881 description 882 "Enclosing container for the list of prefixes in a policy 883 prefix list"; 885 list prefix-list { 886 key "ip-prefix masklength-lower masklength-upper"; 887 description 888 "List of prefixes in the prefix set"; 890 uses prefix; 891 } 892 } 893 } 895 grouping neighbor-set { 896 description 897 "This grouping provides neighbor set definitions"; 899 leaf name { 900 type string; 901 description 902 "Name of the neighbor set -- this is used as a label 903 to reference the set in match conditions"; 904 } 906 leaf-list address { 907 type inet:ip-address; 908 description 909 "List of IP addresses in the neighbor set"; 910 } 911 } 913 grouping neighbor-set-top { 914 description 915 "Top-level data definition for a list of IPv4 or IPv6 916 neighbors which can be matched in a routing policy"; 918 container neighbor-sets { 919 description 920 "Enclosing container for the list of neighbor set 921 definitions"; 923 list neighbor-set { 924 key "name"; 925 description 926 "List of defined neighbor sets for use in policies."; 928 uses neighbor-set; 929 } 930 } 931 } 933 grouping tag-set { 934 description 935 "This grouping provides tag set definitions."; 937 leaf name { 938 type string; 939 description 940 "Name of the tag set -- this is used as a label to reference 941 the set in match conditions"; 942 } 944 leaf-list tag-value { 945 type tag-type; 946 description 947 "Value of the tag set member"; 948 } 949 } 951 grouping tag-set-top { 952 description 953 "Top-level data definitions for a list of tags which can 954 be matched in policies"; 956 container tag-sets { 957 description 958 "Enclosing container for the list of tag sets."; 960 list tag-set { 961 key "name"; 962 description 963 "List of tag set definitions."; 965 uses tag-set; 967 } 968 } 969 } 970 grouping match-set-options-group { 971 description 972 "Grouping containing options relating to how a particular set 973 should be matched"; 975 leaf match-set-options { 976 type match-set-options-type; 977 description 978 "Optional parameter that governs the behavior of the 979 match operation"; 980 } 981 } 983 grouping match-set-options-restricted-group { 984 description 985 "Grouping for a restricted set of match operation modifiers"; 987 leaf match-set-options { 988 type match-set-options-type { 989 enum any { 990 description "Match is true if given value matches any 991 member of the defined set"; 992 } 993 enum invert { 994 description "Match is true if given value does not match 995 any member of the defined set"; 996 } 997 } 998 description 999 "Optional parameter that governs the behavior of the 1000 match operation. This leaf only supports matching on ANY 1001 member of the set or inverting the match. Matching on ALL 1002 is not supported"; 1003 } 1004 } 1006 grouping match-interface-condition { 1007 description 1008 "This grouping provides interface match condition"; 1010 container match-interface { 1011 leaf interface { 1012 type leafref { 1013 path "/if:interfaces/if:interface/if:name"; 1014 } 1015 description 1016 "Reference to a base interface. If a reference to a 1017 subinterface is required, this leaf must be specified 1018 to indicate the base interface."; 1019 } 1020 leaf subinterface { 1021 type leafref { 1022 path "/if:interfaces/if:interface/if-cmn:encapsulation" 1023 + "/if-l3-vlan:dot1q-vlan" 1024 + "/if-l3-vlan:outer-tag/if-l3-vlan:vlan-id"; 1025 } 1026 description 1027 "Reference to a subinterface -- this requires the base 1028 interface to be specified using the interface leaf in 1029 this container. If only a reference to a base interface 1030 is requuired, this leaf should not be set."; 1031 } 1033 description 1034 "Container for interface match conditions"; 1035 } 1036 } 1038 grouping prefix-set-condition { 1039 description 1040 "This grouping provides prefix-set conditions"; 1042 container match-prefix-set { 1043 leaf prefix-set { 1044 type leafref { 1045 path "../../../../../../../defined-sets/" + 1046 "prefix-sets/prefix-set/name"; 1047 } 1048 description "References a defined prefix set"; 1049 } 1050 uses match-set-options-restricted-group; 1052 description 1053 "Match a referenced prefix-set according to the logic 1054 defined in the match-set-options leaf"; 1055 } 1056 } 1058 grouping neighbor-set-condition { 1059 description 1060 "This grouping provides neighbor-set conditions"; 1062 container match-neighbor-set { 1063 leaf neighbor-set { 1064 type leafref { 1065 path "../../../../../../../defined-sets/neighbor-sets/" + 1066 "neighbor-set/name"; 1067 require-instance true; 1068 } 1069 description "References a defined neighbor set"; 1070 } 1072 description 1073 "Match a referenced neighbor set according to the logic 1074 defined in the match-set-options-leaf"; 1075 } 1076 } 1078 grouping tag-set-condition { 1079 description 1080 "This grouping provides tag-set conditions"; 1082 container match-tag-set { 1083 leaf tag-set { 1084 type leafref { 1085 path "../../../../../../../defined-sets/tag-sets/tag-set" + 1086 "/name"; 1087 require-instance true; 1088 } 1089 description "References a defined tag set"; 1090 } 1091 uses match-set-options-restricted-group; 1093 description 1094 "Match a referenced tag set according to the logic defined 1095 in the match-options-set leaf"; 1096 } 1097 } 1099 grouping generic-conditions { 1100 description "Condition statement definitions for checking 1101 membership in a generic defined set"; 1103 uses match-interface-condition; 1104 uses prefix-set-condition; 1105 uses neighbor-set-condition; 1106 uses tag-set-condition; 1108 } 1110 grouping policy-conditions { 1111 description 1112 "Data for general policy conditions, i.e., those 1113 not related to match-sets"; 1115 leaf call-policy { 1116 type leafref { 1117 path "../../../../../../" + 1118 "rt-pol:policy-definitions/" + 1119 "rt-pol:policy-definition/rt-pol:name"; 1120 require-instance true; 1121 } 1122 description 1123 "Applies the statements from the specified policy 1124 definition and then returns control the current 1125 policy statement. Note that the called policy may 1126 itself call other policies (subject to 1127 implementation limitations). This is intended to 1128 provide a policy 'subroutine' capability. The 1129 called policy should contain an explicit or a 1130 default route disposition that returns an 1131 effective true (accept-route) or false 1132 (reject-route), otherwise the behavior may be 1133 ambiguous and implementation dependent"; 1134 } 1136 leaf source-protocol { 1137 type identityref { 1138 base rt:control-plane-protocol; 1139 } 1140 description 1141 "Condition to check the protocol / method used to install 1142 the route into the local routing table"; 1143 } 1144 } 1146 grouping policy-conditions-top { 1147 description 1148 "Top-level grouping for policy conditions"; 1150 container conditions { 1151 description 1152 "Condition statements for the current policy statement"; 1154 uses policy-conditions; 1156 uses generic-conditions; 1157 } 1158 } 1159 grouping policy-statements { 1160 description 1161 "Data for policy statements"; 1163 leaf name { 1164 type string; 1165 description 1166 "Name of the policy statement"; 1167 } 1168 } 1170 grouping policy-actions { 1171 description 1172 "Top-level grouping for policy actions"; 1174 container actions { 1175 description 1176 "Top-level container for policy action statements"; 1178 leaf policy-result { 1179 type policy-result-type; 1180 description 1181 "Select the final disposition for the route, either 1182 accept or reject."; 1183 } 1184 leaf set-metric { 1185 type uint32; 1186 description 1187 "Set a new metric for the route."; 1188 } 1189 leaf set-preference { 1190 type uint16; 1191 description 1192 "Set a new preference for the route."; 1193 } 1194 } 1195 } 1197 grouping policy-statements-top { 1198 description 1199 "Top-level grouping for the policy statements list"; 1201 container statements { 1202 description 1203 "Enclosing container for policy statements"; 1205 list statement { 1206 key "name"; 1207 ordered-by user; 1208 description 1209 "Policy statements group conditions and actions 1210 within a policy definition. They are evaluated in 1211 the order specified (see the description of policy 1212 evaluation at the top of this module."; 1214 uses policy-statements; 1216 uses policy-conditions-top; 1217 uses policy-actions; 1218 } 1219 } 1220 } 1222 grouping policy-definitions { 1223 description 1224 "This grouping provides policy definitions"; 1226 leaf name { 1227 type string; 1228 description 1229 "Name of the top-level policy definition -- this name 1230 is used in references to the current policy"; 1231 } 1232 } 1234 grouping apply-policy-import { 1235 description 1236 "Grouping for applying import policies"; 1238 leaf-list import-policy { 1239 type leafref { 1240 path "/rt-pol:routing-policy/rt-pol:policy-definitions/" + 1241 "rt-pol:policy-definition/rt-pol:name"; 1242 require-instance true; 1243 } 1244 ordered-by user; 1245 description 1246 "List of policy names in sequence to be applied on 1247 receiving a routing update in the current context, e.g., 1248 for the current peer group, neighbor, address family, 1249 etc."; 1250 } 1252 leaf default-import-policy { 1253 type default-policy-type; 1254 default reject-route; 1255 description 1256 "Explicitly set a default policy if no policy definition 1257 in the import policy chain is satisfied."; 1258 } 1260 } 1262 grouping apply-policy-export { 1263 description 1264 "Grouping for applying export policies"; 1266 leaf-list export-policy { 1267 type leafref { 1268 path "/rt-pol:routing-policy/rt-pol:policy-definitions/" + 1269 "rt-pol:policy-definition/rt-pol:name"; 1270 require-instance true; 1271 } 1272 ordered-by user; 1273 description 1274 "List of policy names in sequence to be applied on 1275 sending a routing update in the current context, e.g., 1276 for the current peer group, neighbor, address family, 1277 etc."; 1278 } 1280 leaf default-export-policy { 1281 type default-policy-type; 1282 default reject-route; 1283 description 1284 "Explicitly set a default policy if no policy definition 1285 in the export policy chain is satisfied."; 1286 } 1287 } 1289 grouping apply-policy { 1290 description 1291 "Configuration data for routing policies"; 1293 uses apply-policy-import; 1294 uses apply-policy-export; 1296 container apply-policy-state { 1297 description 1298 "Operational state associated with routing policy"; 1300 //TODO: identify additional state data beyond the intended 1301 //policy configuration. 1302 } 1304 } 1306 grouping apply-policy-group { 1307 description 1308 "Top level container for routing policy applications. This 1309 grouping is intended to be used in routing models where 1310 needed."; 1312 container apply-policy { 1313 description 1314 "Anchor point for routing policies in the model. 1315 Import and export policies are with respect to the local 1316 routing table, i.e., export (send) and import (receive), 1317 depending on the context."; 1319 uses apply-policy; 1321 } 1322 } 1324 container routing-policy { 1325 description 1326 "Top-level container for all routing policy"; 1328 container defined-sets { 1329 description 1330 "Predefined sets of attributes used in policy match 1331 statements"; 1333 uses prefix-set-top; 1334 uses neighbor-set-top; 1335 uses tag-set-top; 1336 } 1338 container policy-definitions { 1339 description 1340 "Enclosing container for the list of top-level policy 1341 definitions"; 1343 list policy-definition { 1344 key "name"; 1345 description 1346 "List of top-level policy definitions, keyed by unique 1347 name. These policy definitions are expected to be 1348 referenced (by name) in policy chains specified in import 1349 or export configuration statements."; 1351 uses policy-definitions; 1353 uses policy-statements-top; 1354 } 1355 } 1356 } 1357 } 1358 1360 11. Policy examples 1362 Below we show an example of XML-encoded configuration data using the 1363 routing policy and BGP models to illustrate both how policies are 1364 defined, and also how they can be applied. Note that the XML has 1365 been simplified for readability. 1367 1369 12. References 1371 12.1. Normative references 1373 [I-D.ietf-netmod-intf-ext-yang] 1374 Wilton, R., Ball, D., tsingh@juniper.net, t., and S. 1375 Sivaraj, "Common Interface Extension YANG Data Models", 1376 draft-ietf-netmod-intf-ext-yang-06 (work in progress), 1377 July 2018. 1379 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1380 Requirement Levels", BCP 14, RFC 2119, 1381 DOI 10.17487/RFC2119, March 1997, 1382 . 1384 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 1385 DOI 10.17487/RFC3688, January 2004, 1386 . 1388 [RFC4271] Rekhter, Y., Ed., Li, T., Ed., and S. Hares, Ed., "A 1389 Border Gateway Protocol 4 (BGP-4)", RFC 4271, 1390 DOI 10.17487/RFC4271, January 2006, 1391 . 1393 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 1394 the Network Configuration Protocol (NETCONF)", RFC 6020, 1395 DOI 10.17487/RFC6020, October 2010, 1396 . 1398 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 1399 RFC 6991, DOI 10.17487/RFC6991, July 2013, 1400 . 1402 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1403 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1404 . 1406 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1407 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 1408 May 2017, . 1410 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 1411 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 1412 . 1414 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 1415 and R. Wilton, "Network Management Datastore Architecture 1416 (NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018, 1417 . 1419 [RFC8343] Bjorklund, M., "A YANG Data Model for Interface 1420 Management", RFC 8343, DOI 10.17487/RFC8343, March 2018, 1421 . 1423 [RFC8349] Lhotka, L., Lindem, A., and Y. Qu, "A YANG Data Model for 1424 Routing Management (NMDA Version)", RFC 8349, 1425 DOI 10.17487/RFC8349, March 2018, 1426 . 1428 12.2. Informative references 1430 [I-D.ietf-idr-bgp-model] 1431 Patel, K., Jethanandani, M., and S. Hares, "BGP Model for 1432 Service Provider Networks", draft-ietf-idr-bgp-model-03 1433 (work in progress), May 2018. 1435 Appendix A. Acknowledgements 1437 The routing policy module defined in this draft is based on the 1438 OpenConfig route policy model. The authors would like to thank to 1439 OpenConfig for their contributions, especially Anees Shaikh, Rob 1440 Shakir, Kevin D'Souza, and Chris Chase. 1442 The authors are grateful for valuable contributions to this document 1443 and the associated models from: Ebben Aires, Luyuan Fang, Josh 1444 George, Stephane Litkowski, Ina Minei, Carl Moberg, Eric Osborne, 1445 Steve Padgett, Juergen Schoenwaelder, Jim Uttaro, and Russ White. 1447 Authors' Addresses 1449 Yingzhen Qu 1450 Huawei 1451 2330 Central Expressway 1452 Santa Clara CA 95050 1453 USA 1455 Email: yingzhen.qu@huawei.com 1457 Jeff Tantsura 1458 Apstra 1460 Email: jefftant.ietf@gmail.com 1462 Acee Lindem 1463 Cisco 1464 301 Mindenhall Way 1465 Cary, NC 27513 1466 US 1468 Email: acee@cisco.com 1470 Xufeng Liu 1471 Volta Networks 1473 Email: xufeng.liu.ietf@gmail.com