idnits 2.17.1 draft-ietf-rtgwg-policy-model-02.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 200 has weird spacing: '...h-range str...' -- The document date (March 3, 2018) is 2240 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Outdated reference: A later version (-17) exists of draft-ietf-idr-bgp-model-02 Summary: 0 errors (**), 0 flaws (~~), 4 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: September 4, 2018 Nuage Networks 6 A. Lindem 7 Cisco 8 X. Liu 9 Jabil 10 A. Shaikh 11 Google 12 March 3, 2018 14 A YANG Data Model for Routing Policy Management 15 draft-ietf-rtgwg-policy-model-02 17 Abstract 19 This document defines a YANG data model for configuring and managing 20 routing policies in a vendor-neutral way and based on actual 21 operational practice. The model provides a generic policy framework 22 which can be augmented with protocol-specific policy configuration. 24 Status of This Memo 26 This Internet-Draft is submitted in full conformance with the 27 provisions of BCP 78 and BCP 79. 29 Internet-Drafts are working documents of the Internet Engineering 30 Task Force (IETF). Note that other groups may also distribute 31 working documents as Internet-Drafts. The list of current Internet- 32 Drafts is at https://datatracker.ietf.org/drafts/current/. 34 Internet-Drafts are draft documents valid for a maximum of six months 35 and may be updated, replaced, or obsoleted by other documents at any 36 time. It is inappropriate to use Internet-Drafts as reference 37 material or to cite them other than as "work in progress." 39 This Internet-Draft will expire on September 4, 2018. 41 Copyright Notice 43 Copyright (c) 2018 IETF Trust and the persons identified as the 44 document authors. All rights reserved. 46 This document is subject to BCP 78 and the IETF Trust's Legal 47 Provisions Relating to IETF Documents 48 (https://trustee.ietf.org/license-info) in effect on the date of 49 publication of this document. Please review these documents 50 carefully, as they describe your rights and restrictions with respect 51 to this document. Code Components extracted from this document must 52 include Simplified BSD License text as described in Section 4.e of 53 the Trust Legal Provisions and are provided without warranty as 54 described in the Simplified BSD License. 56 Table of Contents 58 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 59 1.1. Goals and approach . . . . . . . . . . . . . . . . . . . 3 60 2. Model overview . . . . . . . . . . . . . . . . . . . . . . . 3 61 3. Route policy expression . . . . . . . . . . . . . . . . . . . 4 62 3.1. Defined sets for policy matching . . . . . . . . . . . . 4 63 3.2. Policy conditions . . . . . . . . . . . . . . . . . . . . 5 64 3.3. Policy actions . . . . . . . . . . . . . . . . . . . . . 6 65 3.4. Policy subroutines . . . . . . . . . . . . . . . . . . . 7 66 4. Policy evaluation . . . . . . . . . . . . . . . . . . . . . . 7 67 5. Applying routing policy . . . . . . . . . . . . . . . . . . . 8 68 6. Routing protocol-specific policies . . . . . . . . . . . . . 8 69 7. Security Considerations . . . . . . . . . . . . . . . . . . . 9 70 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 71 9. YANG modules . . . . . . . . . . . . . . . . . . . . . . . . 10 72 9.1. Routing policy model . . . . . . . . . . . . . . . . . . 10 73 10. Policy examples . . . . . . . . . . . . . . . . . . . . . . . 26 74 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 27 75 11.1. Normative references . . . . . . . . . . . . . . . . . . 27 76 11.2. Informative references . . . . . . . . . . . . . . . . . 27 77 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 27 78 Appendix B. Change summary . . . . . . . . . . . . . . . . . . . 28 79 B.1. Changes between revisions -01 and -02 . . . . . . . . . . 28 80 B.2. Changes between revisions -00 and -01 . . . . . . . . . . 28 81 B.3. Changes between revisions draft-shaikh-rtgwg-policy-model 82 and -00 . . . . . . . . . . . . . . . . . . . . . . . . . 28 83 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 28 85 1. Introduction 87 This document describes a YANG [RFC6020] [RFC7950] data model for 88 routing policy configuration based on operational usage and best 89 practices in a variety of service provider networks. The model is 90 intended to be vendor-neutral, in order to allow operators to manage 91 policy configuration in a consistent, intuitive way in heterogeneous 92 environments with routers supplied by multiple vendors. 94 The YANG modules in this document conform to the Network Management 95 Datastore Architecture (NMDA)[I-D.ietf-netmod-revised-datastores]. 97 1.1. Goals and approach 99 This model does not aim to be feature complete -- it is a subset of 100 the policy configuration parameters available in a variety of vendor 101 implementations, but supports widely used constructs for managing how 102 routes are imported, exported, and modified across different routing 103 protocols. The model development approach has been to examine actual 104 policy configurations in use across a number of operator networks. 105 Hence the focus is on enabling policy configuration capabilities and 106 structure that are in wide use. 108 Despite the differences in details of policy expressions and 109 conventions in various vendor implementations, the model reflects the 110 observation that a relatively simple condition-action approach can be 111 readily mapped to several existing vendor implementations, and also 112 gives operators an intuitive and straightforward way to express 113 policy without sacrificing flexibility. A side affect of this design 114 decision is that legacy methods for expressing policies are not 115 considered. Such methods could be added as an augmentation to the 116 model if needed. 118 Consistent with the goal to produce a data model that is vendor 119 neutral, only policy expressions that are deemed to be widely 120 available in existing major implementations are included in the 121 model. Those configuration items that are only available from a 122 single implementation are omitted from the model with the expectation 123 they will be available in separate vendor-provided modules that 124 augment the current model. 126 2. Model overview 128 The routing policy module has three main parts: 130 o A generic framework to express policies as sets of related 131 conditions and actions. This includes match sets and actions that 132 are useful across many routing protocols. 134 o A structure that allows routing protocol models to add protocol- 135 specific policy conditions and actions though YANG augmentations. 136 There is a complete example of this for BGP [RFC4271] policies in 137 the proposed vendor-neutral BGP data model 138 [I-D.ietf-idr-bgp-model]. 140 o A reusable grouping for attaching import and export rules in the 141 context of routing configuration for different protocols, VRFs, 142 etc. This also enables creation of policy chains and expressing 143 default policy behavior. 145 The module makes use of the standard Internet types, such as IP 146 addresses, autonomous system numbers, etc., defined in RFC 6991 147 [RFC6991]. 149 3. Route policy expression 151 Policies are expressed as a sequence of top-level policy definitions 152 each of which consists of a sequence of policy statements. Policy 153 statements in turn consist of simple condition-action tuples. 154 Conditions may include multiple match or comparison operations, and 155 similarly, actions may effect multiple changes to route attributes, 156 or indicate a final disposition of accepting or rejecting the route. 157 This structure is shown below. 159 +--rw routing-policy 160 +--rw policy-definitions 161 +--rw policy-definition* [name] 162 +--rw name string 163 +--rw statements 164 +--rw statement* [name] 165 +--rw name string 166 +--rw conditions 167 | ... 168 +--rw actions 169 ... 171 3.1. Defined sets for policy matching 173 The models provides a set of generic sets that can be used for 174 matching in policy conditions. These sets are applicable for route 175 selection across multiple routing protocols. They may be further 176 augmented by protocol-specific models which have their own defined 177 sets. The supported defined sets include: 179 o prefix sets - define a set of IP prefixes, each with an associated 180 CIDR netmask range (or exact length) 182 o neighbor sets - define a set of neighboring nodes by their IP 183 addresses. These sets are used for selecting routes based on the 184 neighbors advertising the routes. 186 o tag set - define a set of generic tag values that can be used in 187 matches for filtering routes 189 The model structure for defined sets is shown below. 191 +--rw routing-policy 192 +--rw defined-sets 193 | +--rw prefix-sets 194 | | +--rw prefix-set* [name] 195 | | +--rw name string 196 | | +--rw mode? enumeration 197 | | +--rw prefixes 198 | | +--rw prefix* [ip-prefix masklength-range] 199 | | +--rw ip-prefix inet:ip-prefix 200 | | +--rw masklength-range string 201 | +--rw neighbor-sets 202 | | +--rw neighbor-set* [name] 203 | | +--rw name string 204 | | +--rw address* inet:ip-address 205 | +--rw tag-sets 206 | +--rw tag-set* [name] 207 | +--rw name string 208 | +--rw tag-value* tag-type 210 3.2. Policy conditions 212 Policy statements consist of a set of conditions and actions (either 213 of which may be empty). Conditions are used to match route 214 attributes against a defined set (e.g., a prefix set), or to compare 215 attributes against a specific value. 217 Match conditions may be further modified using the match-set-options 218 configuration which allows operators to change the behavior of a 219 match. Three options are supported: 221 o ALL - match is true only if the given value matches all members of 222 the set. 224 o ANY - match is true if the given value matches any member of the 225 set. 227 o INVERT - match is true if the given value does not match any 228 member of the given set. 230 Not all options are appropriate for matching against all defined sets 231 (e.g., match ALL in a prefix set does not make sense). In the model, 232 a restricted set of match options is used where applicable. 234 Comparison conditions may similarly use options to change how route 235 attributes should be tested, e.g., for equality or inequality, 236 against a given value. 238 While most policy conditions will be added by individual routing 239 protocol models via augmentation, this routing policy model includes 240 several generic match conditions and also the ability to test which 241 protocol or mechanism installed a route (e.g., BGP, IGP, static, 242 etc.). The conditions included in the model are shown below. 244 +--rw routing-policy 245 +--rw policy-definitions 246 +--rw policy-definition* [name] 247 +--rw name string 248 +--rw statements 249 +--rw statement* [name] 250 +--rw conditions 251 | +--rw call-policy? 252 | +--rw install-protocol-eq? 253 | +--rw match-interface 254 | | +--rw interface? 255 | +--rw match-prefix-set 256 | | +--rw prefix-set? 257 | | +--rw match-set-options? 258 | +--rw match-neighbor-set 259 | | +--rw neighbor-set? 260 | | +--rw match-set-options? 261 | | match-set-options-restricted-type 262 | +--rw match-tag-set 263 | +--rw tag-set? 264 | +--rw match-set-options? 265 match-set-options-restricted-type 267 3.3. Policy actions 269 When policy conditions are satisfied, policy actions are used to set 270 various attributes of the route being processed, or to indicate the 271 final disposition of the route, i.e., accept or reject. 273 Similar to policy conditions, the routing policy model includes 274 generic actions in addition to the basic route disposition actions. 275 These are shown below. 277 +--rw routing-policy 278 +--rw policy-definitions 279 +--rw policy-definition* [name] 280 +--rw statements 281 +--rw statement* [name] 282 +--rw actions 283 +--rw policy-result? policy-result-type 285 3.4. Policy subroutines 287 Policy 'subroutines' (or nested policies) are supported by allowing 288 policy statement conditions to reference other policy definitions 289 using the call-policy configuration. Called policies apply their 290 conditions and actions before returning to the calling policy 291 statement and resuming evaluation. The outcome of the called policy 292 affects the evaluation of the calling policy. If the called policy 293 results in an accept-route (either explicit or by default), then the 294 subroutine returns an effective boolean true value to the calling 295 policy. For the calling policy, this is equivalent to a condition 296 statement evaluating to a true value and evaluation of the policy 297 continues (see Section 4). Note that the called policy may also 298 modify attributes of the route in its action statements. Similarly, 299 a reject-route action returns false and the calling policy evaluation 300 will be affected accordingly. Consequently, a subroutine cannot 301 explicitly accept or reject a route. Rather it merely provides an 302 indication that 'call-policy' condition returns boolean true or false 303 indicating whether or not the condition matches. Route acceptance or 304 rejection is solely determined by the top-level policy. 306 Note that the called policy may itself call other policies (subject 307 to implementation limitations). The model does not prescribe a 308 nesting depth because this varies among implementations. For 309 example, some major implementation may only support a single level of 310 subroutine recursion. As with any routing policy construction, care 311 must be taken with nested policies to ensure that the effective 312 return value results in the intended behavior. Nested policies are a 313 convenience in many routing policy constructions but creating 314 policies nested beyond a small number of levels (e.g., 2-3) should be 315 discouraged. 317 4. Policy evaluation 319 Evaluation of each policy definition proceeds by evaluating its 320 corresponding individual policy statements in order. When a 321 condition statement in a policy statement is satisfied, the 322 corresponding action statement is executed. If the action statement 323 has either accept-route or reject-route actions, evaluation of the 324 current policy definition stops, and no further policy definitions in 325 the chain are evaluated. 327 If the condition is not satisfied, then evaluation proceeds to the 328 next policy statement. If none of the policy statement conditions 329 are satisfied, then evaluation of the current policy definition 330 stops, and the next policy definition in the chain is evaluated. 331 When the end of the policy chain is reached, the default route 332 disposition action is performed (i.e., reject-route unless an 333 alternate default action is specified for the chain). 335 5. Applying routing policy 337 Routing policy is applied by defining and attaching policy chains in 338 various routing contexts. Policy chains are sequences of policy 339 definitions (described in Section 3) that have an associated 340 direction (import or export) with respect to the routing context in 341 which they are defined. The routing policy model defines an apply- 342 policy grouping that can be imported and used by other models. As 343 shown below, it allows definition of import and export policy chains, 344 as well as specifying the default route disposition to be used when 345 no policy definition in the chain results in a final decision. 347 +--rw apply-policy 348 | +--rw import-policy* 349 | +--rw default-import-policy? default-policy-type 350 | +--rw export-policy* 351 | +--rw default-export-policy? default-policy-type 353 The default policy defined by the model is to reject the route for 354 both import and export policies. 356 6. Routing protocol-specific policies 358 Routing models that require the ability to apply routing policy may 359 augment the routing policy model with protocol or other specific 360 policy configuration. The routing policy model assumes that 361 additional defined sets, conditions, and actions may all be added by 362 other models. 364 An example of this is shown below, in which the BGP configuration 365 model in [I-D.ietf-idr-bgp-model] adds new defined sets to match on 366 community values or AS paths. The model similarly augments BGP- 367 specific conditions and actions in the corresponding sections of the 368 routing policy model. 370 +--rw routing-policy 371 +--rw defined-sets 372 +--rw prefix-sets 373 | +--rw prefix-set* [prefix-set-name] 374 | +--rw prefix-set-name 375 | +--rw prefix* [ip-prefix masklength-range] 376 | +--rw ip-prefix 377 | +--rw masklength-range 378 +--rw neighbor-sets 379 | +--rw neighbor-set* [neighbor-set-name] 380 | +--rw neighbor-set-name 381 | +--rw neighbor* [address] 382 | +--rw address 383 +--rw tag-sets 384 | +--rw tag-set* [tag-set-name] 385 | +--rw tag-set-name 386 | +--rw tag* [value] 387 | +--rw value 388 +--rw bgp-pol:bgp-defined-sets 389 +--rw bgp-pol:community-sets 390 | +--rw bgp-pol:community-set* [community-set-name] 391 | +--rw bgp-pol:community-set-name 392 | +--rw bgp-pol:community-member* 393 +--rw bgp-pol:ext-community-sets 394 | +--rw bgp-pol:ext-community-set* 395 | [ext-community-set-name] 396 | +--rw bgp-pol:ext-community-set-name 397 | +--rw bgp-pol:ext-community-member* 398 +--rw bgp-pol:as-path-sets 399 +--rw bgp-pol:as-path-set* [as-path-set-name] 400 +--rw bgp-pol:as-path-set-name 401 +--rw bgp-pol:as-path-set-member* 403 7. Security Considerations 405 Routing policy configuration has a significant impact on network 406 operations, and, as such, any related model carries potential 407 security risks. 409 YANG data models are generally designed to be used with the NETCONF 410 protocol over an SSH transport. This provides an authenticated and 411 secure channel over which to transfer configuration and operational 412 data. Note that use of alternate transport or data encoding (e.g., 413 JSON over HTTPS) would require similar mechanisms for authenticating 414 and securing access to configuration data. 416 Most of the data elements in the policy model could be considered 417 sensitive from a security standpoint. Unauthorized access or invalid 418 data could cause major disruption. 420 8. IANA Considerations 422 This YANG data model and the component modules currently use a 423 temporary ad-hoc namespace. If and when it is placed on redirected 424 for the standards track, an appropriate namespace URI will be 425 registered in the IETF XML Registry" [RFC3688]. The routing policy 426 YANG modules will be registered in the "YANG Module Names" registry 427 [RFC6020]. 429 9. YANG modules 431 The routing policy model is described by the YANG modules in the 432 sections below. 434 9.1. Routing policy model 436 file "ietf-routing-policy@2018-02-26.yang" 437 module ietf-routing-policy { 439 yang-version "1.1"; 440 namespace "urn:ietf:params:xml:ns:yang:ietf-routing-policy"; 441 prefix rt-pol; 443 import ietf-inet-types { 444 prefix "inet"; 445 } 447 import ietf-yang-types { 448 prefix "yang"; 449 } 451 import ietf-interfaces { 452 prefix "if"; 453 } 455 import ietf-routing { 456 prefix "rt"; 457 } 459 import ietf-interfaces-common { 460 prefix if-cmn; 461 } 463 import ietf-if-l3-vlan { 464 prefix "if-l3-vlan"; 465 } 467 organization 468 "IETF RTGWG - Routing Area Working Group"; 469 contact 470 "WG Web: 471 WG List: 473 Editor: Yingzhen Qu 474 475 Jeff Tantsura 476 477 Acee Lindem 478 479 Xufeng Liu 480 481 Anees Shaikh 482 "; 484 description 485 "This module describes a YANG model for routing policy 486 configuration. It is a limited subset of all of the policy 487 configuration parameters available in the variety of vendor 488 implementations, but supports widely used constructs for 489 managing how routes are imported, exported, and modified across 490 different routing protocols. This module is intended to be used 491 in conjunction with routing protocol configuration modules 492 (e.g., BGP) defined in other models. 494 Route policy expression: 496 Policies are expressed as a set of top-level policy definitions, 497 each of which consists of a sequence of policy statements. 498 Policy statements consist of simple condition-action tuples. 499 Conditions may include mutiple match or comparison operations, 500 and similarly actions may be multitude of changes to route 501 attributes or a final disposition of accepting or rejecting the 502 route. 504 Route policy evaluation: 506 Policy definitions are referenced in routing protocol 507 configurations using import and export configuration statements. 508 The arguments are members of an ordered list of named policy 509 definitions which comprise a policy chain, and optionally, an 510 explicit default policy action (i.e., reject or accept). 512 Evaluation of each policy definition proceeds by evaluating its 513 corresponding individual policy statements in order. When a 514 condition statement in a policy statement is satisfied, the 515 corresponding action statement is executed. If the action 516 statement has either accept-route or reject-route actions, 517 policy evaluation of the current policy definition stops, and 518 no further policy definitions in the chain are evaluated. 520 If the condition is not satisfied, then evaluation proceeds to 521 the next policy statement. If none of the policy statement 522 conditions are satisfied, then evaluation of the current policy 523 definition stops, and the next policy definition in the chain is 524 evaluated. When the end of the policy chain is reached, the 525 default route disposition action is performed (i.e., 526 reject-route unless an alternate default action is specified 527 for the chain). 529 Policy 'subroutines' (or nested policies) are supported by 530 allowing policy statement conditions to reference another policy 531 definition which applies conditions and actions from the 532 referenced policy before returning to the calling policy 533 statement and resuming evaluation. If the called policy 534 results in an accept-route (either explicit or by default), then 535 the subroutine returns an effective true value to the calling 536 policy. Similarly, a reject-route action returns false. If the 537 subroutine returns true, the calling policy continues to 538 evaluate the remaining conditions (using a modified route if the 539 subroutine performed any changes to the route)."; 541 revision "2018-02-26" { 542 description 543 "Initial revision."; 544 reference 545 "RFC XXXX: Routing Policy Configuration Model for Service 546 Provider Networks"; 547 } 549 // typedef statements 551 typedef default-policy-type { 552 // this typedef retained for name compatibiity with default 553 // import and export policy 554 type enumeration { 555 enum accept-route { 556 description 557 "Default policy to accept the route"; 558 } 559 enum reject-route { 560 description 561 "Default policy to reject the route"; 562 } 563 } 564 description 565 "Type used to specify route disposition in 566 a policy chain"; 567 } 569 typedef policy-result-type { 570 type enumeration { 571 enum accept-route { 572 description "Policy accepts the route"; 573 } 574 enum reject-route { 575 description "Policy rejects the route"; 576 } 577 } 578 description 579 "Type used to specify route disposition in 580 a policy chain"; 581 } 583 typedef tag-type { 584 type union { 585 type uint32; 586 type yang:hex-string; 587 } 588 description "Type for expressing route tags on a local system, 589 including IS-IS and OSPF; may be expressed as either decimal 590 or hexadecimal integer"; 591 reference 592 "RFC 2178 - OSPF Version 2 593 RFC 5130 - A Policy Control Mechanism in IS-IS Using 594 Administrative Tags"; 595 } 597 typedef match-set-options-type { 598 type enumeration { 599 enum any { 600 description "Match is true if given value matches any member 601 of the defined set"; 602 } 603 enum all { 604 description "Match is true if given value matches all 605 members of the defined set"; 606 } 607 enum invert { 608 description "Match is true if given value does not match any 609 member of the defined set"; 610 } 611 } 612 default any; 613 description 614 "Options that govern the behavior of a match statement. The 615 default behavior is any, i.e., the given value matches any 616 of the members of the defined set"; 617 } 619 // grouping statements 621 grouping prefix-set { 622 description 623 "Configuration data for prefix sets used in policy 624 definitions."; 626 leaf name { 627 type string; 628 description 629 "Name of the prefix set -- this is used as a label to 630 reference the set in match conditions"; 631 } 633 leaf mode { 634 type enumeration { 635 enum ipv4 { 636 description 637 "Prefix set contains IPv4 prefixes only"; 638 } 639 enum ipv6 { 640 description 641 "Prefix set contains IPv6 prefixes only"; 642 } 643 enum mixed { 644 description 645 "Prefix set contains mixed IPv4 and IPv6 prefixes"; 646 } 647 } 648 description 649 "Indicates the mode of the prefix set, in terms of which 650 address families (IPv4, IPv6, or both) are present. The 651 mode provides a hint, but the device must validate that all 652 prefixes are of the indicated type, and is expected to 653 reject the configuration if there is a discrepancy. The 654 MIXED mode may not be supported on devices that require 655 prefix sets to be of only one address family."; 656 } 658 } 660 grouping prefix-set-top { 661 description 662 "Top-level data definitions for a list of IPv4 or IPv6 663 prefixes which are matched as part of a policy"; 665 container prefix-sets { 666 description 667 "Enclosing container "; 669 list prefix-set { 670 key "name"; 671 description 672 "List of the defined prefix sets"; 674 uses prefix-set; 676 uses prefix-top; 677 } 678 } 679 } 681 grouping prefix { 682 description 683 "Configuration data for a prefix definition"; 685 leaf ip-prefix { 686 type inet:ip-prefix; 687 mandatory true; 688 description 689 "The prefix member in CIDR notation -- while the 690 prefix may be either IPv4 or IPv6, most 691 implementations require all members of the prefix set 692 to be the same address family. Mixing address types in 693 the same prefix set is likely to cause an error."; 694 } 696 leaf masklength-range { 697 type string { 698 pattern '([0-9]{2}\.\.[0-9]{2})|([0-9]{2})'; 700 } 701 description 702 "Defines a range for the masklength, or 'exact' if 703 the prefix has an exact length. 705 Example: 10.3.192.0/21 through 10.3.192.0/24 would be 706 expressed as prefix: 10.3.192.0/21, 707 masklength-range: 21..24. 709 Example: 10.3.192.0/21 would be expressed as 710 prefix: 10.3.192.0/21, 711 masklength-range: exact"; 712 } 713 } 715 grouping prefix-top { 716 description 717 "Top-level grouping for prefixes in a prefix list"; 719 container prefixes { 720 description 721 "Enclosing container for the list of prefixes in a policy 722 prefix list"; 724 list prefix-list { 725 key "ip-prefix masklength-range"; 726 description 727 "List of prefixes in the prefix set"; 729 uses prefix; 730 } 731 } 732 } 734 grouping neighbor-set { 735 description 736 "This grouping provides neighbor set definitions"; 738 leaf name { 739 type string; 740 description 741 "Name of the neighbor set -- this is used as a label 742 to reference the set in match conditions"; 743 } 745 leaf-list address { 746 type inet:ip-address; 747 description 748 "List of IP addresses in the neighbor set"; 749 } 750 } 752 grouping neighbor-set-top { 753 description 754 "Top-level data definition for a list of IPv4 or IPv6 755 neighbors which can be matched in a routing policy"; 757 container neighbor-sets { 758 description 759 "Enclosing container for the list of neighbor set 760 definitions"; 762 list neighbor-set { 763 key "name"; 764 description 765 "List of defined neighbor sets for use in policies."; 767 uses neighbor-set; 768 } 769 } 770 } 772 grouping tag-set { 773 description 774 "This grouping provides tag set definitions."; 776 leaf name { 777 type string; 778 description 779 "Name of the tag set -- this is used as a label to reference 780 the set in match conditions"; 781 } 783 leaf-list tag-value { 784 type tag-type; 785 description 786 "Value of the tag set member"; 787 } 788 } 790 grouping tag-set-top { 791 description 792 "Top-level data definitions for a list of tags which can 793 be matched in policies"; 795 container tag-sets { 796 description 797 "Enclosing container for the list of tag sets."; 799 list tag-set { 800 key "name"; 801 description 802 "List of tag set definitions."; 804 uses tag-set; 806 } 807 } 808 } 810 grouping match-set-options-group { 811 description 812 "Grouping containing options relating to how a particular set 813 should be matched"; 815 leaf match-set-options { 816 type match-set-options-type; 817 description 818 "Optional parameter that governs the behavior of the 819 match operation"; 820 } 821 } 823 grouping match-set-options-restricted-group { 824 description 825 "Grouping for a restricted set of match operation modifiers"; 827 leaf match-set-options { 828 type match-set-options-type { 829 enum any { 830 description "Match is true if given value matches any 831 member of the defined set"; 832 } 833 enum invert { 834 description "Match is true if given value does not match 835 any member of the defined set"; 836 } 837 } 838 description 839 "Optional parameter that governs the behavior of the 840 match operation. This leaf only supports matching on ANY 841 member of the set or inverting the match. Matching on ALL 842 is not supported"; 843 } 844 } 846 grouping match-interface-condition { 847 description 848 "This grouping provides interface match condition"; 850 container match-interface { 851 leaf interface { 852 type leafref { 853 path "/if:interfaces/if:interface/if:name"; 854 } 855 description 856 "Reference to a base interface. If a reference to a 857 subinterface is required, this leaf must be specified 858 to indicate the base interface."; 859 } 860 leaf subinterface { 861 type leafref { 862 path "/if:interfaces/if:interface/if-cmn:encapsulation" 863 + "/if-l3-vlan:dot1q-vlan" 864 + "/if-l3-vlan:outer-tag/if-l3-vlan:vlan-id"; 865 } 866 description 867 "Reference to a subinterface -- this requires the base 868 interface to be specified using the interface leaf in 869 this container. If only a reference to a base interface 870 is requuired, this leaf should not be set."; 871 } 873 description 874 "Container for interface match conditions"; 875 } 876 } 878 grouping prefix-set-condition { 879 description 880 "This grouping provides prefix-set conditions"; 882 container match-prefix-set { 883 leaf prefix-set { 884 type leafref { 885 path "../../../../../../../defined-sets/" + 886 "prefix-sets/prefix-set/name"; 887 } 888 description "References a defined prefix set"; 889 } 890 uses match-set-options-restricted-group; 892 description 893 "Match a referenced prefix-set according to the logic 894 defined in the match-set-options leaf"; 895 } 896 } 898 grouping neighbor-set-condition { 899 description 900 "This grouping provides neighbor-set conditions"; 902 container match-neighbor-set { 903 leaf neighbor-set { 904 type leafref { 905 path "../../../../../../../defined-sets/neighbor-sets/" + 906 "neighbor-set/name"; 907 require-instance true; 908 } 909 description "References a defined neighbor set"; 910 } 912 description 913 "Match a referenced neighbor set according to the logic 914 defined in the match-set-options-leaf"; 915 } 916 } 918 grouping tag-set-condition { 919 description 920 "This grouping provides tag-set conditions"; 922 container match-tag-set { 923 leaf tag-set { 924 type leafref { 925 path "../../../../../../../defined-sets/tag-sets/tag-set" + 926 "/name"; 927 require-instance true; 928 } 929 description "References a defined tag set"; 930 } 931 uses match-set-options-restricted-group; 933 description 934 "Match a referenced tag set according to the logic defined 935 in the match-options-set leaf"; 937 } 938 } 940 grouping generic-conditions { 941 description "Condition statement definitions for checking 942 membership in a generic defined set"; 944 uses match-interface-condition; 945 uses prefix-set-condition; 946 uses neighbor-set-condition; 947 uses tag-set-condition; 949 } 951 grouping generic-actions { 952 description 953 "Definitions for common set of policy action statements that 954 manage the disposition or control flow of the policy"; 956 leaf policy-result { 957 type policy-result-type; 958 description 959 "Select the final disposition for the route, either 960 accept or reject."; 961 } 962 } 964 grouping policy-conditions { 965 description 966 "Data for general policy conditions, i.e., those 967 not related to match-sets"; 969 leaf call-policy { 970 type leafref { 971 path "../../../../../../" + 972 "rt-pol:policy-definitions/" + 973 "rt-pol:policy-definition/rt-pol:name"; 974 require-instance true; 975 } 976 description 977 "Applies the statements from the specified policy 978 definition and then returns control the current 979 policy statement. Note that the called policy may 980 itself call other policies (subject to 981 implementation limitations). This is intended to 982 provide a policy 'subroutine' capability. The 983 called policy should contain an explicit or a 984 default route disposition that returns an 985 effective true (accept-route) or false 986 (reject-route), otherwise the behavior may be 987 ambiguous and implementation dependent"; 988 } 990 leaf install-protocol-eq { 991 type identityref { 992 base rt:control-plane-protocol; 993 } 994 description 995 "Condition to check the protocol / method used to install 996 the route into the local routing table"; 997 } 998 } 1000 grouping policy-conditions-top { 1001 description 1002 "Top-level grouping for policy conditions"; 1004 container conditions { 1005 description 1006 "Condition statements for the current policy statement"; 1008 uses policy-conditions; 1010 uses generic-conditions; 1011 } 1012 } 1014 grouping policy-statements { 1015 description 1016 "Data for policy statements"; 1018 leaf name { 1019 type string; 1020 description 1021 "Name of the policy statement"; 1022 } 1023 } 1025 grouping policy-actions { 1026 description 1027 "Grouping for policy actions"; 1029 uses generic-actions; 1030 } 1031 grouping policy-actions-top { 1032 description 1033 "Top-level grouping for policy actions"; 1035 container actions { 1036 description 1037 "Top-level container for policy action statements"; 1039 uses policy-actions; 1040 } 1041 } 1043 grouping policy-statements-top { 1044 description 1045 "Top-level grouping for the policy statements list"; 1047 container statements { 1048 description 1049 "Enclosing container for policy statements"; 1051 list statement { 1052 key "name"; 1053 ordered-by user; 1054 description 1055 "Policy statements group conditions and actions 1056 within a policy definition. They are evaluated in 1057 the order specified (see the description of policy 1058 evaluation at the top of this module."; 1060 uses policy-statements; 1062 uses policy-conditions-top; 1063 uses policy-actions-top; 1064 } 1065 } 1066 } 1068 grouping policy-definitions { 1069 description 1070 "This grouping provides policy definitions"; 1072 leaf name { 1073 type string; 1074 description 1075 "Name of the top-level policy definition -- this name 1076 is used in references to the current policy"; 1077 } 1079 } 1081 grouping apply-policy-import { 1082 description 1083 "Grouping for applying import policies"; 1085 leaf-list import-policy { 1086 type leafref { 1087 path "/rt-pol:routing-policy/rt-pol:policy-definitions/" + 1088 "rt-pol:policy-definition/rt-pol:name"; 1089 require-instance true; 1090 } 1091 ordered-by user; 1092 description 1093 "List of policy names in sequence to be applied on 1094 receiving a routing update in the current context, e.g., 1095 for the current peer group, neighbor, address family, 1096 etc."; 1097 } 1099 leaf default-import-policy { 1100 type default-policy-type; 1101 default reject-route; 1102 description 1103 "Explicitly set a default policy if no policy definition 1104 in the import policy chain is satisfied."; 1105 } 1107 } 1109 grouping apply-policy-export { 1110 description 1111 "Grouping for applying export policies"; 1113 leaf-list export-policy { 1114 type leafref { 1115 path "/rt-pol:routing-policy/rt-pol:policy-definitions/" + 1116 "rt-pol:policy-definition/rt-pol:name"; 1117 require-instance true; 1118 } 1119 ordered-by user; 1120 description 1121 "List of policy names in sequence to be applied on 1122 sending a routing update in the current context, e.g., 1123 for the current peer group, neighbor, address family, 1124 etc."; 1125 } 1126 leaf default-export-policy { 1127 type default-policy-type; 1128 default reject-route; 1129 description 1130 "Explicitly set a default policy if no policy definition 1131 in the export policy chain is satisfied."; 1132 } 1133 } 1135 grouping apply-policy { 1136 description 1137 "Configuration data for routing policies"; 1139 uses apply-policy-import; 1140 uses apply-policy-export; 1142 container apply-policy-state { 1143 description 1144 "Operational state associated with routing policy"; 1146 //TODO: identify additional state data beyond the intended 1147 //policy configuration. 1148 } 1150 } 1152 grouping apply-policy-group { 1153 description 1154 "Top level container for routing policy applications. This 1155 grouping is intended to be used in routing models where 1156 needed."; 1158 container apply-policy { 1159 description 1160 "Anchor point for routing policies in the model. 1161 Import and export policies are with respect to the local 1162 routing table, i.e., export (send) and import (receive), 1163 depending on the context."; 1165 uses apply-policy; 1167 } 1168 } 1170 container routing-policy { 1171 description 1172 "Top-level container for all routing policy"; 1174 container defined-sets { 1175 description 1176 "Predefined sets of attributes used in policy match 1177 statements"; 1179 uses prefix-set-top; 1180 uses neighbor-set-top; 1181 uses tag-set-top; 1182 } 1184 container policy-definitions { 1185 description 1186 "Enclosing container for the list of top-level policy 1187 definitions"; 1189 list policy-definition { 1190 key "name"; 1191 description 1192 "List of top-level policy definitions, keyed by unique 1193 name. These policy definitions are expected to be 1194 referenced (by name) in policy chains specified in import 1195 or export configuration statements."; 1197 uses policy-definitions; 1199 uses policy-statements-top; 1200 } 1201 } 1202 } 1203 } 1204 1206 10. Policy examples 1208 Below we show an example of XML-encoded configuration data using the 1209 routing policy and BGP models to illustrate both how policies are 1210 defined, and also how they can be applied. Note that the XML has 1211 been simplified for readability. 1213 1215 11. References 1217 11.1. Normative references 1219 [I-D.ietf-netmod-revised-datastores] 1220 Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 1221 and R. Wilton, "Network Management Datastore 1222 Architecture", draft-ietf-netmod-revised-datastores-10 1223 (work in progress), January 2018. 1225 [RFC3688] Mealling, M., "The IETF XML Registry", RFC 3688, January 1226 2004. 1228 [RFC4271] Rekhter, Y., Li, T., and S. Hares, "A Border Gateway 1229 Protocol 4 (BGP-4)", RFC 4271, January 2006. 1231 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 1232 Network Configuration Protocol (NETCONF)", RFC 6020, 1233 October 2014. 1235 [RFC6991] Schoenwaelder, J., "Common YANG Data Types", RFC 6991, 1236 July 2013. 1238 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1239 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1240 . 1242 11.2. Informative references 1244 [I-D.ietf-idr-bgp-model] 1245 Shaikh, A., Shakir, R., Patel, K., Hares, S., D'Souza, K., 1246 Bansal, D., Clemm, A., Zhdankin, A., Jethanandani, M., and 1247 X. Liu, "BGP Model for Service Provider Networks", draft- 1248 ietf-idr-bgp-model-02 (work in progress), July 2016. 1250 Appendix A. Acknowledgements 1252 The routing policy module defined in this draft is based on the 1253 OpenConfig route policy model. The authors would like to thank to 1254 OpenConfig for their contributions, especially Rob Shakir, Kevin 1255 D'Souza, and Chris Chase. 1257 The authors are grateful for valuable contributions to this document 1258 and the associated models from: Ebben Aires, Luyuan Fang, Josh 1259 George, Acee Lindem, Stephane Litkowski, Ina Minei, Carl Moberg, Eric 1260 Osborne, Steve Padgett, Juergen Schoenwaelder, Jim Uttaro, and Russ 1261 White. 1263 Appendix B. Change summary 1265 B.1. Changes between revisions -01 and -02 1267 Updated the model to use IETF modules and be NMDA compliant. 1269 B.2. Changes between revisions -00 and -01 1271 Updated policy model with additional condition for matching 1272 interfaces. 1274 B.3. Changes between revisions draft-shaikh-rtgwg-policy-model and -00 1276 This revision updates the draft name to reflect adoption as a working 1277 document in the RTGWG. Minor changes include updates to references 1278 and updated author contact information. 1280 Authors' Addresses 1282 Yingzhen Qu 1283 Huawei 1284 2330 Central Expressway 1285 Santa Clara CA 95050 1286 USA 1288 Email: yingzhen.qu@huawei.com 1290 Jeff Tantsura 1291 Nuage Networks 1293 Email: jefftant.ietf@gmail.com 1295 Acee Lindem 1296 Cisco 1297 301 Mindenhall Way 1298 Cary, NC 27513 1299 US 1301 Email: acee@cisco.com 1302 Xufeng Liu 1303 Jabil 1304 8281 Greensboro Drive, Suite 200 1305 Mclean, VA 22102 1306 US 1308 Email: xufeng_liu@jabil.com 1310 Anees Shaikh 1311 Google 1312 1600 Amphitheatre Pkwy 1313 Mountain View, CA 94043 1314 US 1316 Email: aashaikh@google.com