idnits 2.17.1 draft-ietf-rtgwg-policy-model-03.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 is 1 instance of too long lines in the document, the longest one being 1 character in excess of 72. == 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 201 has weird spacing: '...h-lower uin...' == Line 202 has weird spacing: '...h-upper uin...' == Line 383 has weird spacing: '...h-lower uin...' == Line 384 has weird spacing: '...h-upper uin...' == Line 396 has weird spacing: '...et-name str...' == (1 more instance...) -- The document date (June 29, 2018) is 2121 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-03 Summary: 1 error (**), 0 flaws (~~), 9 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: December 31, 2018 Nuage Networks 6 A. Lindem 7 Cisco 8 X. Liu 9 Jabil 10 A. Shaikh 11 Google 12 June 29, 2018 14 A YANG Data Model for Routing Policy Management 15 draft-ietf-rtgwg-policy-model-03 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 December 31, 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 . . . . . . . . . . . . . . . . . . . 11 70 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 71 9. YANG modules . . . . . . . . . . . . . . . . . . . . . . . . 11 72 9.1. Routing policy model . . . . . . . . . . . . . . . . . . 11 73 10. Policy examples . . . . . . . . . . . . . . . . . . . . . . . 28 74 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 28 75 11.1. Normative references . . . . . . . . . . . . . . . . . . 28 76 11.2. Informative references . . . . . . . . . . . . . . . . . 29 77 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 29 78 Appendix B. Change summary . . . . . . . . . . . . . . . . . . . 29 79 B.1. Changes between revisions -01 and -02 . . . . . . . . . . 29 80 B.2. Changes between revisions -00 and -01 . . . . . . . . . . 29 81 B.3. Changes between revisions draft-shaikh-rtgwg-policy-model 82 and -00 . . . . . . . . . . . . . . . . . . . . . . . . . 29 83 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 29 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-list* [ip-prefix masklength-lower 199 | | masklength-upper] 200 | | +--rw ip-prefix inet:ip-prefix 201 | | +--rw masklength-lower uint8 202 | | +--rw masklength-upper uint8 203 | +--rw neighbor-sets 204 | | +--rw neighbor-set* [name] 205 | | +--rw name string 206 | | +--rw address* inet:ip-address 207 | +--rw tag-sets 208 | +--rw tag-set* [name] 209 | +--rw name string 210 | +--rw tag-value* tag-type 212 3.2. Policy conditions 214 Policy statements consist of a set of conditions and actions (either 215 of which may be empty). Conditions are used to match route 216 attributes against a defined set (e.g., a prefix set), or to compare 217 attributes against a specific value. 219 Match conditions may be further modified using the match-set-options 220 configuration which allows operators to change the behavior of a 221 match. Three options are supported: 223 o ALL - match is true only if the given value matches all members of 224 the set. 226 o ANY - match is true if the given value matches any member of the 227 set. 229 o INVERT - match is true if the given value does not match any 230 member of the given set. 232 Not all options are appropriate for matching against all defined sets 233 (e.g., match ALL in a prefix set does not make sense). In the model, 234 a restricted set of match options is used where applicable. 236 Comparison conditions may similarly use options to change how route 237 attributes should be tested, e.g., for equality or inequality, 238 against a given value. 240 While most policy conditions will be added by individual routing 241 protocol models via augmentation, this routing policy model includes 242 several generic match conditions and also the ability to test which 243 protocol or mechanism installed a route (e.g., BGP, IGP, static, 244 etc.). The conditions included in the model are shown below. 246 +--rw routing-policy 247 +--rw policy-definitions 248 +--rw policy-definition* [name] 249 +--rw name string 250 +--rw statements 251 +--rw statement* [name] 252 +--rw conditions 253 | +--rw call-policy? 254 | +--rw install-protocol-eq? 255 | +--rw match-interface 256 | | +--rw interface? 257 | | +--rw subinterface? 258 | +--rw match-prefix-set 259 | | +--rw prefix-set? 260 | | +--rw match-set-options? 261 | +--rw match-neighbor-set 262 | | +--rw neighbor-set? 263 | +--rw match-tag-set 264 | +--rw tag-set? 265 | +--rw match-set-options? 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 284 +--rw set-metric? uint16 285 +--rw set-preference? uint8 287 3.4. Policy subroutines 289 Policy 'subroutines' (or nested policies) are supported by allowing 290 policy statement conditions to reference other policy definitions 291 using the call-policy configuration. Called policies apply their 292 conditions and actions before returning to the calling policy 293 statement and resuming evaluation. The outcome of the called policy 294 affects the evaluation of the calling policy. If the called policy 295 results in an accept-route (either explicit or by default), then the 296 subroutine returns an effective boolean true value to the calling 297 policy. For the calling policy, this is equivalent to a condition 298 statement evaluating to a true value and evaluation of the policy 299 continues (see Section 4). Note that the called policy may also 300 modify attributes of the route in its action statements. Similarly, 301 a reject-route action returns false and the calling policy evaluation 302 will be affected accordingly. Consequently, a subroutine cannot 303 explicitly accept or reject a route. Rather it merely provides an 304 indication that 'call-policy' condition returns boolean true or false 305 indicating whether or not the condition matches. Route acceptance or 306 rejection is solely determined by the top-level policy. 308 Note that the called policy may itself call other policies (subject 309 to implementation limitations). The model does not prescribe a 310 nesting depth because this varies among implementations. For 311 example, some major implementation may only support a single level of 312 subroutine recursion. As with any routing policy construction, care 313 must be taken with nested policies to ensure that the effective 314 return value results in the intended behavior. Nested policies are a 315 convenience in many routing policy constructions but creating 316 policies nested beyond a small number of levels (e.g., 2-3) should be 317 discouraged. 319 4. Policy evaluation 321 Evaluation of each policy definition proceeds by evaluating its 322 corresponding individual policy statements in order. When a 323 condition statement in a policy statement is satisfied, the 324 corresponding action statement is executed. If the action statement 325 has either accept-route or reject-route actions, evaluation of the 326 current policy definition stops, and no further policy definitions in 327 the chain are evaluated. 329 If the condition is not satisfied, then evaluation proceeds to the 330 next policy statement. If none of the policy statement conditions 331 are satisfied, then evaluation of the current policy definition 332 stops, and the next policy definition in the chain is evaluated. 333 When the end of the policy chain is reached, the default route 334 disposition action is performed (i.e., reject-route unless an 335 alternate default action is specified for the chain). 337 5. Applying routing policy 339 Routing policy is applied by defining and attaching policy chains in 340 various routing contexts. Policy chains are sequences of policy 341 definitions (described in Section 3) that have an associated 342 direction (import or export) with respect to the routing context in 343 which they are defined. The routing policy model defines an apply- 344 policy grouping that can be imported and used by other models. As 345 shown below, it allows definition of import and export policy chains, 346 as well as specifying the default route disposition to be used when 347 no policy definition in the chain results in a final decision. 349 +--rw apply-policy 350 | +--rw import-policy* 351 | +--rw default-import-policy? default-policy-type 352 | +--rw export-policy* 353 | +--rw default-export-policy? default-policy-type 355 The default policy defined by the model is to reject the route for 356 both import and export policies. 358 6. Routing protocol-specific policies 360 Routing models that require the ability to apply routing policy may 361 augment the routing policy model with protocol or other specific 362 policy configuration. The routing policy model assumes that 363 additional defined sets, conditions, and actions may all be added by 364 other models. 366 An example of this is shown below, in which the BGP configuration 367 model in [I-D.ietf-idr-bgp-model] adds new defined sets to match on 368 community values or AS paths. The model similarly augments BGP- 369 specific conditions and actions in the corresponding sections of the 370 routing policy model. 372 module: ietf-routing-policy 373 +--rw routing-policy 374 +--rw defined-sets 375 | +--rw prefix-sets 376 | | +--rw prefix-set* [name] 377 | | +--rw name string 378 | | +--rw mode? enumeration 379 | | +--rw prefixes 380 | | +--rw prefix-list* [ip-prefix masklength-lower 381 | | masklength-upper] 382 | | +--rw ip-prefix inet:ip-prefix 383 | | +--rw masklength-lower uint8 384 | | +--rw masklength-upper uint8 385 | +--rw neighbor-sets 386 | | +--rw neighbor-set* [name] 387 | | +--rw name string 388 | | +--rw address* inet:ip-address 389 | +--rw tag-sets 390 | | +--rw tag-set* [name] 391 | | +--rw name string 392 | | +--rw tag-value* tag-type 393 | +--rw bgp-pol:bgp-defined-sets 394 | +--rw bgp-pol:community-sets 395 | | +--rw bgp-pol:community-set* [community-set-name] 396 | | +--rw bgp-pol:community-set-name string 397 | | +--rw bgp-pol:community-member* union 398 | +--rw bgp-pol:ext-community-sets 399 | | +--rw bgp-pol:ext-community-set* [ext-community-set-name] 400 | | +--rw bgp-pol:ext-community-set-name string 401 | | +--rw bgp-pol:ext-community-member* union 402 | +--rw bgp-pol:as-path-sets 403 | +--rw bgp-pol:as-path-set* [as-path-set-name] 404 | +--rw bgp-pol:as-path-set-name string 405 | +--rw bgp-pol:as-path-set-member* string 406 +--rw policy-definitions 407 +--rw policy-definition* [name] 408 +--rw name string 409 +--rw statements 410 +--rw statement* [name] 411 +--rw name string 412 +--rw conditions 413 | +--rw call-policy? 414 | +--rw source-protocol? identityref 415 | +--rw match-interface 416 | | +--rw interface? 417 | | +--rw subinterface? 418 | +--rw match-prefix-set 419 | | +--rw prefix-set? 420 | | +--rw match-set-options? match-set-options-type 421 | +--rw match-neighbor-set 422 | | +--rw neighbor-set? 423 | +--rw match-tag-set 424 | | +--rw tag-set? 425 | | +--rw match-set-options? match-set-options-type 426 | +--rw bgp-pol:bgp-conditions 427 | +--rw bgp-pol:med-eq? uint32 428 | +--rw bgp-pol:origin-eq? 429 | bgp-types:bgp-origin-attr-type 430 | +--rw bgp-pol:next-hop-in* 431 | inet:ip-address-no-zone 432 | +--rw bgp-pol:afi-safi-in* identityref 433 | +--rw bgp-pol:local-pref-eq? uint32 434 | +--rw bgp-pol:route-type? enumeration 435 | +--rw bgp-pol:community-count 436 | +--rw bgp-pol:as-path-length 437 | +--rw bgp-pol:match-community-set 438 | | +--rw bgp-pol:community-set? 439 | | +--rw bgp-pol:match-set-options? 440 | match-set-options-type 441 | +--rw bgp-pol:match-ext-community-set 442 | | +--rw bgp-pol:ext-community-set? 443 | | +--rw bgp-pol:match-set-options? 444 | | match-set-options-type 445 | +--rw bgp-pol:match-as-path-set 446 | +--rw bgp-pol:as-path-set? 447 | +--rw bgp-pol:match-set-options? 448 | match-set-options-type 449 +--rw actions 450 +--rw policy-result? policy-result-type 451 +--rw set-metric? uint16 452 +--rw set-preference? uint8 453 +--rw bgp-pol:bgp-actions 454 +--rw bgp-pol:set-route-origin? 455 bgp-types:bgp-origin-attr-type 456 +--rw bgp-pol:set-local-pref? uint32 457 +--rw bgp-pol:set-next-hop? bgp-next-hop-type 458 +--rw bgp-pol:set-med? bgp-set-med-type 459 +--rw bgp-pol:set-as-path-prepend 460 | +--rw bgp-pol:repeat-n? uint8 461 +--rw bgp-pol:set-community 462 | +--rw bgp-pol:method? enumeration 463 | +--rw bgp-pol:options? 464 bgp-set-community-option-type 465 | +--rw bgp-pol:inline 466 | | +--rw bgp-pol:communities* union 467 | +--rw bgp-pol:reference 468 | +--rw bgp-pol:community-set-ref? 469 +--rw bgp-pol:set-ext-community 470 +--rw bgp-pol:method? enumeration 471 +--rw bgp-pol:options? 472 bgp-set-community-option-type 473 +--rw bgp-pol:inline 474 | +--rw bgp-pol:communities* union 475 +--rw bgp-pol:reference 476 +--rw bgp-pol:ext-community-set-ref? 478 7. Security Considerations 480 Routing policy configuration has a significant impact on network 481 operations, and, as such, any related model carries potential 482 security risks. 484 YANG data models are generally designed to be used with the NETCONF 485 protocol over an SSH transport. This provides an authenticated and 486 secure channel over which to transfer configuration and operational 487 data. Note that use of alternate transport or data encoding (e.g., 488 JSON over HTTPS) would require similar mechanisms for authenticating 489 and securing access to configuration data. 491 Most of the data elements in the policy model could be considered 492 sensitive from a security standpoint. Unauthorized access or invalid 493 data could cause major disruption. 495 8. IANA Considerations 497 This YANG data model and the component modules currently use a 498 temporary ad-hoc namespace. If and when it is placed on redirected 499 for the standards track, an appropriate namespace URI will be 500 registered in the IETF XML Registry" [RFC3688]. The routing policy 501 YANG modules will be registered in the "YANG Module Names" registry 502 [RFC6020]. 504 9. YANG modules 506 The routing policy model is described by the YANG modules in the 507 sections below. 509 9.1. Routing policy model 511 file "ietf-routing-policy@2018-06-25.yang" 512 module ietf-routing-policy { 514 yang-version "1.1"; 515 namespace "urn:ietf:params:xml:ns:yang:ietf-routing-policy"; 516 prefix rt-pol; 517 import ietf-inet-types { 518 prefix "inet"; 519 } 521 import ietf-yang-types { 522 prefix "yang"; 523 } 525 import ietf-interfaces { 526 prefix "if"; 527 } 529 import ietf-routing { 530 prefix "rt"; 531 } 533 import ietf-interfaces-common { 534 prefix if-cmn; 535 } 537 import ietf-if-l3-vlan { 538 prefix "if-l3-vlan"; 539 } 541 organization 542 "IETF RTGWG - Routing Area Working Group"; 543 contact 544 "WG Web: 545 WG List: 547 Editor: Yingzhen Qu 548 549 Jeff Tantsura 550 551 Acee Lindem 552 553 Xufeng Liu 554 555 Anees Shaikh 556 "; 558 description 559 "This module describes a YANG model for routing policy 560 configuration. It is a limited subset of all of the policy 561 configuration parameters available in the variety of vendor 562 implementations, but supports widely used constructs for 563 managing how routes are imported, exported, and modified across 564 different routing protocols. This module is intended to be used 565 in conjunction with routing protocol configuration modules 566 (e.g., BGP) defined in other models. 568 Route policy expression: 570 Policies are expressed as a set of top-level policy definitions, 571 each of which consists of a sequence of policy statements. 572 Policy statements consist of simple condition-action tuples. 573 Conditions may include mutiple match or comparison operations, 574 and similarly actions may be multitude of changes to route 575 attributes or a final disposition of accepting or rejecting the 576 route. 578 Route policy evaluation: 580 Policy definitions are referenced in routing protocol 581 configurations using import and export configuration statements. 582 The arguments are members of an ordered list of named policy 583 definitions which comprise a policy chain, and optionally, an 584 explicit default policy action (i.e., reject or accept). 586 Evaluation of each policy definition proceeds by evaluating its 587 corresponding individual policy statements in order. When a 588 condition statement in a policy statement is satisfied, the 589 corresponding action statement is executed. If the action 590 statement has either accept-route or reject-route actions, 591 policy evaluation of the current policy definition stops, and 592 no further policy definitions in the chain are evaluated. 594 If the condition is not satisfied, then evaluation proceeds to 595 the next policy statement. If none of the policy statement 596 conditions are satisfied, then evaluation of the current policy 597 definition stops, and the next policy definition in the chain is 598 evaluated. When the end of the policy chain is reached, the 599 default route disposition action is performed (i.e., 600 reject-route unless an alternate default action is specified 601 for the chain). 603 Policy 'subroutines' (or nested policies) are supported by 604 allowing policy statement conditions to reference another policy 605 definition which applies conditions and actions from the 606 referenced policy before returning to the calling policy 607 statement and resuming evaluation. If the called policy 608 results in an accept-route (either explicit or by default), then 609 the subroutine returns an effective true value to the calling 610 policy. Similarly, a reject-route action returns false. If the 611 subroutine returns true, the calling policy continues to 612 evaluate the remaining conditions (using a modified route if the 613 subroutine performed any changes to the route)."; 615 revision "2018-06-25" { 616 description 617 "Initial revision."; 618 reference 619 "RFC XXXX: Routing Policy Configuration Model for Service 620 Provider Networks"; 621 } 623 // typedef statements 625 typedef default-policy-type { 626 // this typedef retained for name compatibiity with default 627 // import and export policy 628 type enumeration { 629 enum accept-route { 630 description 631 "Default policy to accept the route"; 632 } 633 enum reject-route { 634 description 635 "Default policy to reject the route"; 636 } 637 } 638 description 639 "Type used to specify route disposition in 640 a policy chain"; 641 } 643 typedef policy-result-type { 644 type enumeration { 645 enum accept-route { 646 description "Policy accepts the route"; 647 } 648 enum reject-route { 649 description "Policy rejects the route"; 650 } 651 } 652 description 653 "Type used to specify route disposition in 654 a policy chain"; 655 } 656 typedef tag-type { 657 type union { 658 type uint32; 659 type yang:hex-string; 660 } 661 description "Type for expressing route tags on a local system, 662 including IS-IS and OSPF; may be expressed as either decimal 663 or hexadecimal integer"; 664 reference 665 "RFC 2178 - OSPF Version 2 666 RFC 5130 - A Policy Control Mechanism in IS-IS Using 667 Administrative Tags"; 668 } 670 typedef match-set-options-type { 671 type enumeration { 672 enum any { 673 description "Match is true if given value matches any member 674 of the defined set"; 675 } 676 enum all { 677 description "Match is true if given value matches all 678 members of the defined set"; 679 } 680 enum invert { 681 description "Match is true if given value does not match any 682 member of the defined set"; 683 } 684 } 685 default any; 686 description 687 "Options that govern the behavior of a match statement. The 688 default behavior is any, i.e., the given value matches any 689 of the members of the defined set"; 690 } 692 // grouping statements 694 grouping prefix-set { 695 description 696 "Configuration data for prefix sets used in policy 697 definitions."; 699 leaf name { 700 type string; 701 description 702 "Name of the prefix set -- this is used as a label to 703 reference the set in match conditions"; 704 } 706 leaf mode { 707 type enumeration { 708 enum ipv4 { 709 description 710 "Prefix set contains IPv4 prefixes only"; 711 } 712 enum ipv6 { 713 description 714 "Prefix set contains IPv6 prefixes only"; 715 } 716 enum mixed { 717 description 718 "Prefix set contains mixed IPv4 and IPv6 prefixes"; 719 } 720 } 721 description 722 "Indicates the mode of the prefix set, in terms of which 723 address families (IPv4, IPv6, or both) are present. The 724 mode provides a hint, but the device must validate that all 725 prefixes are of the indicated type, and is expected to 726 reject the configuration if there is a discrepancy. The 727 MIXED mode may not be supported on devices that require 728 prefix sets to be of only one address family."; 729 } 731 } 733 grouping prefix-set-top { 734 description 735 "Top-level data definitions for a list of IPv4 or IPv6 736 prefixes which are matched as part of a policy"; 738 container prefix-sets { 739 description 740 "Enclosing container "; 742 list prefix-set { 743 key "name"; 744 description 745 "List of the defined prefix sets"; 747 uses prefix-set; 749 uses prefix-top; 750 } 752 } 753 } 755 grouping prefix { 756 description 757 "Configuration data for a prefix definition"; 759 leaf ip-prefix { 760 type inet:ip-prefix; 761 mandatory true; 762 description 763 "The prefix member in CIDR notation -- while the 764 prefix may be either IPv4 or IPv6, most 765 implementations require all members of the prefix set 766 to be the same address family. Mixing address types in 767 the same prefix set is likely to cause an error."; 768 } 770 leaf masklength-lower { 771 type uint8; 772 description 773 "Masklength range lower bound."; 774 } 775 leaf masklength-upper { 776 type uint8 { 777 range "1..128"; 778 } 779 must "../masklength-upper >= ../masklength-lower" { 780 error-message "The upper bound should not be less" 781 + "than lower bound."; 782 } 783 description 784 "Masklength range upper bound. 786 The combination of masklength-lower and masklength-upper 787 define a range for the mask length, or single 'exact' 788 length if masklength-lower and masklenght-upper are equal. 790 Example: 10.3.192.0/21 through 10.3.192.0/24 would be 791 expressed as prefix: 10.3.192.0/21, 792 masklength-lower=21, 793 masklength-upper=24 795 Example: 10.3.192.0/21 (an exact match) would be 796 expressed as prefix: 10.3.192.0/21, 797 masklength-lower=21, 798 masklength-upper=21"; 799 } 801 } 803 grouping prefix-top { 804 description 805 "Top-level grouping for prefixes in a prefix list"; 807 container prefixes { 808 description 809 "Enclosing container for the list of prefixes in a policy 810 prefix list"; 812 list prefix-list { 813 key "ip-prefix masklength-lower masklength-upper"; 814 description 815 "List of prefixes in the prefix set"; 817 uses prefix; 818 } 819 } 820 } 822 grouping neighbor-set { 823 description 824 "This grouping provides neighbor set definitions"; 826 leaf name { 827 type string; 828 description 829 "Name of the neighbor set -- this is used as a label 830 to reference the set in match conditions"; 831 } 833 leaf-list address { 834 type inet:ip-address; 835 description 836 "List of IP addresses in the neighbor set"; 837 } 838 } 840 grouping neighbor-set-top { 841 description 842 "Top-level data definition for a list of IPv4 or IPv6 843 neighbors which can be matched in a routing policy"; 845 container neighbor-sets { 846 description 847 "Enclosing container for the list of neighbor set 848 definitions"; 850 list neighbor-set { 851 key "name"; 852 description 853 "List of defined neighbor sets for use in policies."; 855 uses neighbor-set; 856 } 857 } 858 } 860 grouping tag-set { 861 description 862 "This grouping provides tag set definitions."; 864 leaf name { 865 type string; 866 description 867 "Name of the tag set -- this is used as a label to reference 868 the set in match conditions"; 869 } 871 leaf-list tag-value { 872 type tag-type; 873 description 874 "Value of the tag set member"; 875 } 876 } 878 grouping tag-set-top { 879 description 880 "Top-level data definitions for a list of tags which can 881 be matched in policies"; 883 container tag-sets { 884 description 885 "Enclosing container for the list of tag sets."; 887 list tag-set { 888 key "name"; 889 description 890 "List of tag set definitions."; 892 uses tag-set; 894 } 895 } 896 } 897 grouping match-set-options-group { 898 description 899 "Grouping containing options relating to how a particular set 900 should be matched"; 902 leaf match-set-options { 903 type match-set-options-type; 904 description 905 "Optional parameter that governs the behavior of the 906 match operation"; 907 } 908 } 910 grouping match-set-options-restricted-group { 911 description 912 "Grouping for a restricted set of match operation modifiers"; 914 leaf match-set-options { 915 type match-set-options-type { 916 enum any { 917 description "Match is true if given value matches any 918 member of the defined set"; 919 } 920 enum invert { 921 description "Match is true if given value does not match 922 any member of the defined set"; 923 } 924 } 925 description 926 "Optional parameter that governs the behavior of the 927 match operation. This leaf only supports matching on ANY 928 member of the set or inverting the match. Matching on ALL 929 is not supported"; 930 } 931 } 933 grouping match-interface-condition { 934 description 935 "This grouping provides interface match condition"; 937 container match-interface { 938 leaf interface { 939 type leafref { 940 path "/if:interfaces/if:interface/if:name"; 941 } 942 description 943 "Reference to a base interface. If a reference to a 944 subinterface is required, this leaf must be specified 945 to indicate the base interface."; 946 } 947 leaf subinterface { 948 type leafref { 949 path "/if:interfaces/if:interface/if-cmn:encapsulation" 950 + "/if-l3-vlan:dot1q-vlan" 951 + "/if-l3-vlan:outer-tag/if-l3-vlan:vlan-id"; 952 } 953 description 954 "Reference to a subinterface -- this requires the base 955 interface to be specified using the interface leaf in 956 this container. If only a reference to a base interface 957 is requuired, this leaf should not be set."; 958 } 960 description 961 "Container for interface match conditions"; 962 } 963 } 965 grouping prefix-set-condition { 966 description 967 "This grouping provides prefix-set conditions"; 969 container match-prefix-set { 970 leaf prefix-set { 971 type leafref { 972 path "../../../../../../../defined-sets/" + 973 "prefix-sets/prefix-set/name"; 974 } 975 description "References a defined prefix set"; 976 } 977 uses match-set-options-restricted-group; 979 description 980 "Match a referenced prefix-set according to the logic 981 defined in the match-set-options leaf"; 982 } 983 } 985 grouping neighbor-set-condition { 986 description 987 "This grouping provides neighbor-set conditions"; 989 container match-neighbor-set { 990 leaf neighbor-set { 991 type leafref { 992 path "../../../../../../../defined-sets/neighbor-sets/" + 993 "neighbor-set/name"; 994 require-instance true; 995 } 996 description "References a defined neighbor set"; 997 } 999 description 1000 "Match a referenced neighbor set according to the logic 1001 defined in the match-set-options-leaf"; 1002 } 1003 } 1005 grouping tag-set-condition { 1006 description 1007 "This grouping provides tag-set conditions"; 1009 container match-tag-set { 1010 leaf tag-set { 1011 type leafref { 1012 path "../../../../../../../defined-sets/tag-sets/tag-set" + 1013 "/name"; 1014 require-instance true; 1015 } 1016 description "References a defined tag set"; 1017 } 1018 uses match-set-options-restricted-group; 1020 description 1021 "Match a referenced tag set according to the logic defined 1022 in the match-options-set leaf"; 1023 } 1024 } 1026 grouping generic-conditions { 1027 description "Condition statement definitions for checking 1028 membership in a generic defined set"; 1030 uses match-interface-condition; 1031 uses prefix-set-condition; 1032 uses neighbor-set-condition; 1033 uses tag-set-condition; 1035 } 1037 grouping policy-conditions { 1038 description 1039 "Data for general policy conditions, i.e., those 1040 not related to match-sets"; 1042 leaf call-policy { 1043 type leafref { 1044 path "../../../../../../" + 1045 "rt-pol:policy-definitions/" + 1046 "rt-pol:policy-definition/rt-pol:name"; 1047 require-instance true; 1048 } 1049 description 1050 "Applies the statements from the specified policy 1051 definition and then returns control the current 1052 policy statement. Note that the called policy may 1053 itself call other policies (subject to 1054 implementation limitations). This is intended to 1055 provide a policy 'subroutine' capability. The 1056 called policy should contain an explicit or a 1057 default route disposition that returns an 1058 effective true (accept-route) or false 1059 (reject-route), otherwise the behavior may be 1060 ambiguous and implementation dependent"; 1061 } 1063 leaf source-protocol { 1064 type identityref { 1065 base rt:control-plane-protocol; 1066 } 1067 description 1068 "Condition to check the protocol / method used to install 1069 the route into the local routing table"; 1070 } 1071 } 1073 grouping policy-conditions-top { 1074 description 1075 "Top-level grouping for policy conditions"; 1077 container conditions { 1078 description 1079 "Condition statements for the current policy statement"; 1081 uses policy-conditions; 1083 uses generic-conditions; 1084 } 1085 } 1086 grouping policy-statements { 1087 description 1088 "Data for policy statements"; 1090 leaf name { 1091 type string; 1092 description 1093 "Name of the policy statement"; 1094 } 1095 } 1097 grouping policy-actions { 1098 description 1099 "Top-level grouping for policy actions"; 1101 container actions { 1102 description 1103 "Top-level container for policy action statements"; 1105 leaf policy-result { 1106 type policy-result-type; 1107 description 1108 "Select the final disposition for the route, either 1109 accept or reject."; 1110 } 1111 leaf set-metric { 1112 type uint16; 1113 description 1114 "Set a new metric for the route."; 1115 } 1116 leaf set-preference { 1117 type uint8; 1118 description 1119 "Set a new preference for the route."; 1120 } 1121 } 1122 } 1124 grouping policy-statements-top { 1125 description 1126 "Top-level grouping for the policy statements list"; 1128 container statements { 1129 description 1130 "Enclosing container for policy statements"; 1132 list statement { 1133 key "name"; 1134 ordered-by user; 1135 description 1136 "Policy statements group conditions and actions 1137 within a policy definition. They are evaluated in 1138 the order specified (see the description of policy 1139 evaluation at the top of this module."; 1141 uses policy-statements; 1143 uses policy-conditions-top; 1144 uses policy-actions; 1145 } 1146 } 1147 } 1149 grouping policy-definitions { 1150 description 1151 "This grouping provides policy definitions"; 1153 leaf name { 1154 type string; 1155 description 1156 "Name of the top-level policy definition -- this name 1157 is used in references to the current policy"; 1158 } 1159 } 1161 grouping apply-policy-import { 1162 description 1163 "Grouping for applying import policies"; 1165 leaf-list import-policy { 1166 type leafref { 1167 path "/rt-pol:routing-policy/rt-pol:policy-definitions/" + 1168 "rt-pol:policy-definition/rt-pol:name"; 1169 require-instance true; 1170 } 1171 ordered-by user; 1172 description 1173 "List of policy names in sequence to be applied on 1174 receiving a routing update in the current context, e.g., 1175 for the current peer group, neighbor, address family, 1176 etc."; 1177 } 1179 leaf default-import-policy { 1180 type default-policy-type; 1181 default reject-route; 1182 description 1183 "Explicitly set a default policy if no policy definition 1184 in the import policy chain is satisfied."; 1185 } 1187 } 1189 grouping apply-policy-export { 1190 description 1191 "Grouping for applying export policies"; 1193 leaf-list export-policy { 1194 type leafref { 1195 path "/rt-pol:routing-policy/rt-pol:policy-definitions/" + 1196 "rt-pol:policy-definition/rt-pol:name"; 1197 require-instance true; 1198 } 1199 ordered-by user; 1200 description 1201 "List of policy names in sequence to be applied on 1202 sending a routing update in the current context, e.g., 1203 for the current peer group, neighbor, address family, 1204 etc."; 1205 } 1207 leaf default-export-policy { 1208 type default-policy-type; 1209 default reject-route; 1210 description 1211 "Explicitly set a default policy if no policy definition 1212 in the export policy chain is satisfied."; 1213 } 1214 } 1216 grouping apply-policy { 1217 description 1218 "Configuration data for routing policies"; 1220 uses apply-policy-import; 1221 uses apply-policy-export; 1223 container apply-policy-state { 1224 description 1225 "Operational state associated with routing policy"; 1227 //TODO: identify additional state data beyond the intended 1228 //policy configuration. 1229 } 1231 } 1233 grouping apply-policy-group { 1234 description 1235 "Top level container for routing policy applications. This 1236 grouping is intended to be used in routing models where 1237 needed."; 1239 container apply-policy { 1240 description 1241 "Anchor point for routing policies in the model. 1242 Import and export policies are with respect to the local 1243 routing table, i.e., export (send) and import (receive), 1244 depending on the context."; 1246 uses apply-policy; 1248 } 1249 } 1251 container routing-policy { 1252 description 1253 "Top-level container for all routing policy"; 1255 container defined-sets { 1256 description 1257 "Predefined sets of attributes used in policy match 1258 statements"; 1260 uses prefix-set-top; 1261 uses neighbor-set-top; 1262 uses tag-set-top; 1263 } 1265 container policy-definitions { 1266 description 1267 "Enclosing container for the list of top-level policy 1268 definitions"; 1270 list policy-definition { 1271 key "name"; 1272 description 1273 "List of top-level policy definitions, keyed by unique 1274 name. These policy definitions are expected to be 1275 referenced (by name) in policy chains specified in import 1276 or export configuration statements."; 1278 uses policy-definitions; 1280 uses policy-statements-top; 1281 } 1282 } 1283 } 1284 } 1285 1287 10. Policy examples 1289 Below we show an example of XML-encoded configuration data using the 1290 routing policy and BGP models to illustrate both how policies are 1291 defined, and also how they can be applied. Note that the XML has 1292 been simplified for readability. 1294 1296 11. References 1298 11.1. Normative references 1300 [I-D.ietf-netmod-revised-datastores] 1301 Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 1302 and R. Wilton, "Network Management Datastore 1303 Architecture", draft-ietf-netmod-revised-datastores-10 1304 (work in progress), January 2018. 1306 [RFC3688] Mealling, M., "The IETF XML Registry", RFC 3688, January 1307 2004. 1309 [RFC4271] Rekhter, Y., Li, T., and S. Hares, "A Border Gateway 1310 Protocol 4 (BGP-4)", RFC 4271, January 2006. 1312 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 1313 Network Configuration Protocol (NETCONF)", RFC 6020, 1314 October 2014. 1316 [RFC6991] Schoenwaelder, J., "Common YANG Data Types", RFC 6991, 1317 July 2013. 1319 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1320 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1321 . 1323 11.2. Informative references 1325 [I-D.ietf-idr-bgp-model] 1326 Patel, K., Jethanandani, M., and S. Hares, "BGP Model for 1327 Service Provider Networks", draft-ietf-idr-bgp-model-03 1328 (work in progress), May 2018. 1330 Appendix A. Acknowledgements 1332 The routing policy module defined in this draft is based on the 1333 OpenConfig route policy model. The authors would like to thank to 1334 OpenConfig for their contributions, especially Rob Shakir, Kevin 1335 D'Souza, and Chris Chase. 1337 The authors are grateful for valuable contributions to this document 1338 and the associated models from: Ebben Aires, Luyuan Fang, Josh 1339 George, Acee Lindem, Stephane Litkowski, Ina Minei, Carl Moberg, Eric 1340 Osborne, Steve Padgett, Juergen Schoenwaelder, Jim Uttaro, and Russ 1341 White. 1343 Appendix B. Change summary 1345 B.1. Changes between revisions -01 and -02 1347 Updated the model to use IETF modules and be NMDA compliant. 1349 B.2. Changes between revisions -00 and -01 1351 Updated policy model with additional condition for matching 1352 interfaces. 1354 B.3. Changes between revisions draft-shaikh-rtgwg-policy-model and -00 1356 This revision updates the draft name to reflect adoption as a working 1357 document in the RTGWG. Minor changes include updates to references 1358 and updated author contact information. 1360 Authors' Addresses 1361 Yingzhen Qu 1362 Huawei 1363 2330 Central Expressway 1364 Santa Clara CA 95050 1365 USA 1367 Email: yingzhen.qu@huawei.com 1369 Jeff Tantsura 1370 Nuage Networks 1372 Email: jefftant.ietf@gmail.com 1374 Acee Lindem 1375 Cisco 1376 301 Mindenhall Way 1377 Cary, NC 27513 1378 US 1380 Email: acee@cisco.com 1382 Xufeng Liu 1383 Jabil 1384 8281 Greensboro Drive, Suite 200 1385 Mclean, VA 22102 1386 US 1388 Email: xufeng_liu@jabil.com 1390 Anees Shaikh 1391 Google 1392 1600 Amphitheatre Pkwy 1393 Mountain View, CA 94043 1394 US 1396 Email: aashaikh@google.com