idnits 2.17.1 draft-ietf-rtgwg-policy-model-00.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 189 has weird spacing: '...et-name str...' == Line 192 has weird spacing: '...h-range str...' == Line 195 has weird spacing: '...et-name str...' == Line 197 has weird spacing: '...address ine...' == Line 200 has weird spacing: '...et-name str...' == (1 more instance...) -- The document date (September 27, 2015) is 3134 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Unused Reference: 'I-D.openconfig-netmod-opstate' is defined on line 1417, but no explicit reference was found in the text == Outdated reference: A later version (-17) exists of draft-ietf-idr-bgp-model-00 == Outdated reference: A later version (-01) exists of draft-openconfig-netmod-opstate-00 Summary: 0 errors (**), 0 flaws (~~), 11 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group A. Shaikh 3 Internet-Draft Google 4 Intended status: Informational R. Shakir 5 Expires: March 30, 2016 Individual 6 K. D'Souza 7 C. Chase 8 AT&T 9 September 27, 2015 11 Routing Policy Configuration Model for Service Provider Networks 12 draft-ietf-rtgwg-policy-model-00 14 Abstract 16 This document defines a YANG data model for configuring and managing 17 routing policies in a vendor-neutral way and based on actual 18 operational practice. The model provides a generic policy framework 19 which can be augmented with protocol-specific policy configuration. 21 Status of This Memo 23 This Internet-Draft is submitted in full conformance with the 24 provisions of BCP 78 and BCP 79. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF). Note that other groups may also distribute 28 working documents as Internet-Drafts. The list of current Internet- 29 Drafts is at http://datatracker.ietf.org/drafts/current/. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 This Internet-Draft will expire on March 30, 2016. 38 Copyright Notice 40 Copyright (c) 2015 IETF Trust and the persons identified as the 41 document authors. All rights reserved. 43 This document is subject to BCP 78 and the IETF Trust's Legal 44 Provisions Relating to IETF Documents 45 (http://trustee.ietf.org/license-info) in effect on the date of 46 publication of this document. Please review these documents 47 carefully, as they describe your rights and restrictions with respect 48 to this document. Code Components extracted from this document must 49 include Simplified BSD License text as described in Section 4.e of 50 the Trust Legal Provisions and are provided without warranty as 51 described in the Simplified BSD License. 53 Table of Contents 55 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 56 1.1. Goals and approach . . . . . . . . . . . . . . . . . . . 2 57 2. Model overview . . . . . . . . . . . . . . . . . . . . . . . 3 58 3. Route policy expression . . . . . . . . . . . . . . . . . . . 4 59 3.1. Defined sets for policy matching . . . . . . . . . . . . 4 60 3.2. Policy conditions . . . . . . . . . . . . . . . . . . . . 5 61 3.3. Policy actions . . . . . . . . . . . . . . . . . . . . . 6 62 3.4. Policy subroutines . . . . . . . . . . . . . . . . . . . 7 63 4. Policy evaluation . . . . . . . . . . . . . . . . . . . . . . 7 64 5. Applying routing policy . . . . . . . . . . . . . . . . . . . 8 65 6. Routing protocol-specific policies . . . . . . . . . . . . . 9 66 7. Security Considerations . . . . . . . . . . . . . . . . . . . 10 67 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 68 9. YANG modules . . . . . . . . . . . . . . . . . . . . . . . . 11 69 9.1. Routing policy model . . . . . . . . . . . . . . . . . . 11 70 9.2. Routing policy types . . . . . . . . . . . . . . . . . . 23 71 10. Policy examples . . . . . . . . . . . . . . . . . . . . . . . 27 72 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 31 73 11.1. Normative references . . . . . . . . . . . . . . . . . . 31 74 11.2. Informative references . . . . . . . . . . . . . . . . . 31 75 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 31 76 Appendix B. Change summary . . . . . . . . . . . . . . . . . . . 31 77 B.1. Changes between revisions draft-shaikh-rtgwg-policy-model 78 and -00 . . . . . . . . . . . . . . . . . . . . . . . . . 31 79 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 32 81 1. Introduction 83 This document describes a YANG [RFC6020] data model for routing 84 policy configuration based on operational usage and best practices in 85 a variety of service provider networks. The model is intended to be 86 vendor-neutral, in order to allow operators to manage policy 87 configuration in a consistent, intuitive way in heterogeneous 88 environments with routers supplied by multiple vendors. 90 1.1. Goals and approach 92 This model does not aim to be feature complete -- it is a subset of 93 the policy configuration parameters available in a variety of vendor 94 implementations, but supports widely used constructs for managing how 95 routes are imported, exported, and modified across different routing 96 protocols. The model development approach has been to examine actual 97 policy configurations in use across a number of operator networks. 98 Hence the focus is on enabling policy configuration capabilities and 99 structure that are in wide use. 101 Despite the differences in details of policy expressions and 102 conventions in various vendor implementations, the model reflects the 103 observation that a relatively simple condition- action approach can 104 be readily mapped to several existing vendor implementations, and 105 also gives operators an intuitive and straightforward way to express 106 policy without sacrificing flexibility. A side affect of this design 107 decision is that legacy methods for expressing policies are not 108 considered. Such methods could be added as an augmentation to the 109 model if needed. 111 Consistent with the goal to produce a data model that is vendor 112 neutral, only policy expressions that are deemed to be widely 113 available in existing major implementations are included in the 114 model. Those configuration items that are only available from a 115 single implementation are omitted from the model with the expectation 116 they will be available in separate vendor-provided modules that 117 augment the current model. 119 2. Model overview 121 The routing policy model is defined in two YANG modules, the main 122 policy module, and an auxiliary module providing additional generic 123 types. The model has three main parts: 125 o A generic framework to express policies as sets of related 126 conditions and actions. This includes match sets and actions that 127 are useful across many routing protocols. 129 o A structure that allows routing protocol models to add protocol- 130 specific policy conditions and actions though YANG augmentations. 131 There is a complete example of this for BGP [RFC4271] policies in 132 the proposed vendor-neutral BGP data model 133 [I-D.ietf-idr-bgp-model]. 135 o A reusable grouping for attaching import and export rules in the 136 context of routing configuration for different protocols, VRFs, 137 etc. This also enables creation of policy chains and expressing 138 default policy behavior. 140 These modules make use of the standard Internet types, such as IP 141 addresses, autonomous system numbers, etc., defined in RFC 6991 142 [RFC6991]. 144 3. Route policy expression 146 Policies are expressed as a sequence of top-level policy definitions 147 each of which consists of a sequence of policy statements. Policy 148 statements in turn consist of simple condition-action tuples. 149 Conditions may include multiple match or comparison operations, and 150 similarly, actions may effect multiple changes to route attributes, 151 or indicate a final disposition of accepting or rejecting the route. 152 This structure is shown below. 154 +--rw routing-policy 155 +--rw policy-definitions 156 +--rw policy-definition* [name] 157 +--rw name string 158 +--rw statements 159 +--rw statement* [name] 160 +--rw name string 161 +--rw conditions 162 | ... 163 +--rw actions 164 ... 166 3.1. Defined sets for policy matching 168 The models provides a set of generic sets that can be used for 169 matching in policy conditions. These sets are applicable across 170 multiple routing protocols, and may be further augmented by protocol- 171 specific models which have their own defined sets. The supported 172 defined sets include: 174 o prefix sets - define a set of IP prefixes, each with an associated 175 CIDR netmask range (or exact length) 177 o neighbor sets - define a set of neighboring nodes by their IP 178 addresses 180 o tag set - define a set of generic tag values that can be used in 181 matches for filtering routes 183 The model structure for defined sets is shown below. 185 +--rw routing-policy 186 +--rw defined-sets 187 +--rw prefix-sets 188 | +--rw prefix-set* [prefix-set-name] 189 | +--rw prefix-set-name string 190 | +--rw prefix* [ip-prefix masklength-range] 191 | +--rw ip-prefix inet:ip-prefix 192 | +--rw masklength-range string 193 +--rw neighbor-sets 194 | +--rw neighbor-set* [neighbor-set-name] 195 | +--rw neighbor-set-name string 196 | +--rw neighbor* [address] 197 | +--rw address inet:ip-address 198 +--rw tag-sets 199 +--rw tag-set* [tag-set-name] 200 +--rw tag-set-name string 201 +--rw tag* [value] 202 +--rw value pt:tag-type 204 3.2. Policy conditions 206 Policy statements consist of a set of conditions and actions (either 207 of which may be empty). Conditions are used to match route 208 attributes against a defined set (e.g., a prefix set), or to compare 209 attributes against a specific value. 211 Match conditions may be further modified using the match-set-options 212 configuration which allows operators to change the behavior of a 213 match. Three options are supported: 215 o ALL - match is true only if the given value matches all members of 216 the set. 218 o ANY - match is true if the given value matches any member of the 219 set. 221 o INVERT - match is true if the given value does not match any 222 member of the given set. 224 Not all options are appropriate for matching against all defined sets 225 (e.g., match ALL in a prefix set does not make sense). In the model, 226 a restricted set of match options is used where applicable. 228 Comparison conditions may similarly use options to change how route 229 attributes should be tested, e.g., for equality or inequality, 230 against a given value. 232 While most policy conditions will be added by individual routing 233 protocol models via augmentation, this routing policy model includes 234 several generic match conditions and also the ability to test which 235 protocol or mechanism installed a route (e.g., BGP, IGP, static, 236 etc.). The conditions included in the model are shown below. 238 +--rw routing-policy 239 +--rw policy-definitions 240 +--rw policy-definition* [name] 241 +--rw statements 242 +--rw statement* [name] 243 +--rw conditions 244 +--rw call-policy? 245 +--rw match-prefix-set! 246 | +--rw prefix-set? 247 | +--rw match-set-options? 248 +--rw match-neighbor-set! 249 | +--rw neighbor-set? 250 | +--rw match-set-options? 251 +--rw match-tag-set! 252 | +--rw tag-set? 253 | +--rw match-set-options? 254 +--rw install-protocol-eq? 255 +--rw igp-conditions 257 3.3. Policy actions 259 When policy conditions are satisfied, policy actions are used to set 260 various attributes of the route being processed, or to indicate the 261 final disposition of the route, i.e., accept or reject. 263 Similar to policy conditions, the routing policy model includes 264 generic actions in addition to the basic route disposition actions. 265 These are shown below. 267 +--rw routing-policy 268 +--rw policy-definitions 269 +--rw policy-definition* [name] 270 +--rw statements 271 +--rw statement* [name] 272 +--rw actions 273 +--rw (route-disposition)? 274 | +--:(accept-route) 275 | | +--rw accept-route? empty 276 | +--:(reject-route) 277 | +--rw reject-route? empty 278 +--rw igp-actions 279 +--rw set-tag? pt:tag-type 281 3.4. Policy subroutines 283 Policy 'subroutines' (or nested policies) are supported by allowing 284 policy statement conditions to reference other policy definitions 285 using the call-policy configuration. Called policies apply their 286 conditions and actions before returning to the calling policy 287 statement and resuming evaluation. The outcome of the called policy 288 affects the evaluation of the calling policy. If the called policy 289 results in an accept-route (either explicit or by default), then the 290 subroutine returns an effective boolean true value to the calling 291 policy. For the calling policy, this is equivalent to a condition 292 statement evaluating to a true value and evaluation of the policy 293 continues (see Section 4). Note that the called policy may also 294 modify attributes of the route in its action statements. Similarly, 295 a reject-route action returns false and the calling policy evaluation 296 will be affected accordingly. 298 Note that the called policy may itself call other policies (subject 299 to implementation limitations). The model does not prescribe a 300 nesting depth because this varies among implementations, with some 301 major implementations only supporting a single subroutine, for 302 example. As with any routing policy construction, care must be taken 303 with nested policies to ensure that the effective return value 304 results in the intended behavior. Nested policies are a convenience 305 in many routing policy constructions but creating policies nested 306 beyond a small number of levels (e.g., 2-3) should be discouraged. 308 4. Policy evaluation 310 Evaluation of each policy definition proceeds by evaluating its 311 corresponding individual policy statements in order. When a 312 condition statement in a policy statement is satisfied, the 313 corresponding action statement is executed. If the action statement 314 has either accept-route or reject-route actions, evaluation of the 315 current policy definition stops, and no further policy definitions in 316 the chain are evaluated. 318 If the condition is not satisfied, then evaluation proceeds to the 319 next policy statement. If none of the policy statement conditions 320 are satisfied, then evaluation of the current policy definition 321 stops, and the next policy definition in the chain is evaluated. 322 When the end of the policy chain is reached, the default route 323 disposition action is performed (i.e., reject-route unless an an 324 alternate default action is specified for the chain). 326 5. Applying routing policy 328 Routing policy is applied by defining and attaching policy chains in 329 various routing contexts. Policy chains are sequences of policy 330 definitions (described in Section 3) that have an associated 331 direction (import or export) with respect to the routing context in 332 which they are defined. The routing policy model defines an apply- 333 policy grouping that can be imported and used by other models. As 334 shown below, it allows definition of import and export policy chains, 335 as well as specifying the default route disposition to be used when 336 no policy definition in the chain results in a final decision. 338 +--rw apply-policy 339 | +--rw config 340 | | +--rw import-policy* 341 | | +--rw default-import-policy? default-policy-type 342 | | +--rw export-policy* 343 | | +--rw default-export-policy? default-policy-type 345 The default policy defined by the model is to reject the route for 346 both import and export policies. 348 An example of using the apply-policy group in another routing model 349 is shown below for BGP. Here, import and export policies are applied 350 in the context of a particular BGP peer group. Note that the policy 351 chains reference policy definitions by name that are defined in the 352 routing policy model. 354 +--rw bgp! 355 +--rw peer-groups 356 +--rw peer-group* [peer-group-name] 357 +--rw peer-group-name 358 +--rw config 359 | +--rw peer-as? 360 | +--rw local-as? 361 | +--rw peer-type? 362 | +--rw auth-password? 363 | +--rw remove-private-as? 364 | +--rw route-flap-damping? 365 | +--rw send-community? 366 | +--rw description? 367 | +--rw peer-group-name? 368 +--ro state 369 | +--ro peer-as? 370 | +--ro local-as? 371 | +--ro peer-type? 372 | +--ro auth-password? 373 | +--ro remove-private-as? 374 | +--ro route-flap-damping? 375 | +--ro send-community? 376 | +--ro description? 377 | +--ro peer-group-name? 378 | +--ro total-paths? 379 | +--ro total-prefixes? 380 +--rw apply-policy 381 | +--rw config 382 | | +--rw import-policy* 383 | | +--rw default-import-policy? 384 | | +--rw export-policy* 385 | | +--rw default-export-policy? 386 | +--ro state 387 | +--ro import-policy* 388 | +--ro default-import-policy? 389 | +--ro export-policy* 390 | +--ro default-export-policy? 391 ... 393 6. Routing protocol-specific policies 395 Routing models that require the ability to apply routing policy may 396 augment the routing policy model with protocol or other specific 397 policy configuration. The routing policy model assumes that 398 additional defined sets, conditions, and actions may all be added by 399 other models. 401 An example of this is shown below, in which the BGP configuration 402 model in [I-D.ietf-idr-bgp-model] adds new defined sets to match on 403 community values or AS paths. The model similarly augments BGP- 404 specific conditions and actions into the corresponding sections of 405 the routing policy model. 407 +--rw routing-policy 408 +--rw defined-sets 409 +--rw prefix-sets 410 | +--rw prefix-set* [prefix-set-name] 411 | +--rw prefix-set-name 412 | +--rw prefix* [ip-prefix masklength-range] 413 | +--rw ip-prefix 414 | +--rw masklength-range 415 +--rw neighbor-sets 416 | +--rw neighbor-set* [neighbor-set-name] 417 | +--rw neighbor-set-name 418 | +--rw neighbor* [address] 419 | +--rw address 420 +--rw tag-sets 421 | +--rw tag-set* [tag-set-name] 422 | +--rw tag-set-name 423 | +--rw tag* [value] 424 | +--rw value 425 +--rw bgp-pol:bgp-defined-sets 426 +--rw bgp-pol:community-sets 427 | +--rw bgp-pol:community-set* [community-set-name] 428 | +--rw bgp-pol:community-set-name 429 | +--rw bgp-pol:community-member* 430 +--rw bgp-pol:ext-community-sets 431 | +--rw bgp-pol:ext-community-set* [ext-community-set-name] 432 | +--rw bgp-pol:ext-community-set-name 433 | +--rw bgp-pol:ext-community-member* 434 +--rw bgp-pol:as-path-sets 435 +--rw bgp-pol:as-path-set* [as-path-set-name] 436 +--rw bgp-pol:as-path-set-name 437 +--rw bgp-pol:as-path-set-member* 439 7. Security Considerations 441 Routing policy configuration has a significant impact on network 442 operations, and as such any related model carries potential security 443 risks. 445 YANG data models are generally designed to be used with the NETCONF 446 protocol over an SSH transport. This provides an authenticated and 447 secure channel over which to transfer configuration and operational 448 data. Note that use of alternate transport or data encoding (e.g., 449 JSON over HTTPS) would require similar mechanisms for authenticating 450 and securing access to configuration data. 452 Most of the data elements in the policy model could be considered 453 sensitive from a security standpoint. Unauthorized access or invalid 454 data could cause major disruption. 456 8. IANA Considerations 458 This YANG data model and the component modules currently use a 459 temporary ad-hoc namespace. If and when it is placed on redirected 460 for the standards track, an appropriate namespace URI will be 461 registered in the IETF XML Registry" [RFC3688]. The routing policy 462 YANG modules will be registered in the "YANG Module Names" registry 463 [RFC6020]. 465 9. YANG modules 467 The routing policy model is described by the YANG modules in the 468 sections below. 470 9.1. Routing policy model 472 file routing-policy.yang 473 module routing-policy { 475 yang-version "1"; 477 // namespace 478 namespace "http://openconfig.net/yang/routing-policy"; 480 prefix "rpol"; 482 // import some basic types 483 import ietf-inet-types { prefix inet; } 484 import policy-types {prefix pt; } 486 // meta 487 organization 488 "OpenConfig working group"; 490 contact 491 "OpenConfig working group 492 netopenconfig@googlegroups.com"; 494 description 495 "This module describes a YANG model for routing policy 496 configuration. It is a limited subset of all of the policy 497 configuration parameters available in the variety of vendor 498 implementations, but supports widely used constructs for managing 499 how routes are imported, exported, and modified across different 500 routing protocols. This module is intended to be used in 501 conjunction with routing protocol configuration models (e.g., 502 BGP) defined in other modules. 504 Route policy expression: 506 Policies are expressed as a set of top-level policy definitions, 507 each of which consists of a sequence of policy statements. Policy 508 statements consist of simple condition-action tuples. Conditions 509 may include mutiple match or comparison operations, and similarly 510 actions may be multitude of changes to route attributes or a 511 final disposition of accepting or rejecting the route. 513 Route policy evaluation: 515 Policy definitions are referenced in routing protocol 516 configurations using import and export configuration statements. 517 The arguments are members of an ordered list of named policy 518 definitions which comprise a policy chain, and optionally, an 519 explicit default policy action (i.e., reject or accept). 521 Evaluation of each policy definition proceeds by evaluating its 522 corresponding individual policy statements in order. When a 523 condition statement in a policy statement is satisfied, the 524 corresponding action statement is executed. If the action 525 statement has either accept-route or reject-route actions, policy 526 evaluation of the current policy definition stops, and no further 527 policy definitions in the chain are evaluated. 529 If the condition is not satisfied, then evaluation proceeds to 530 the next policy statement. If none of the policy statement 531 conditions are satisfied, then evaluation of the current policy 532 definition stops, and the next policy definition in the chain is 533 evaluated. When the end of the policy chain is reached, the 534 default route disposition action is performed (i.e., reject-route 535 unless an an alternate default action is specified for the 536 chain). 538 Policy 'subroutines' (or nested policies) are supported by 539 allowing policy statement conditions to reference another policy 540 definition which applies conditions and actions from the 541 referenced policy before returning to the calling policy 542 statement and resuming evaluation. If the called policy 543 results in an accept-route (either explicit or by default), then 544 the subroutine returns an effective true value to the calling 545 policy. Similarly, a reject-route action returns false. If the 546 subroutine returns true, the calling policy continues to evaluate 547 the remaining conditions (using a modified route if the 548 subroutine performed any changes to the route)."; 550 revision "2015-05-15" { 551 description 552 "Initial revision"; 553 reference "TBD"; 554 } 556 // typedef statements 558 typedef default-policy-type { 559 type enumeration { 560 enum ACCEPT-ROUTE { 561 description "default policy to accept the route"; 562 } 563 enum REJECT-ROUTE { 564 description "default policy to reject the route"; 565 } 566 } 567 description "type used to specify default route disposition in 568 a policy chain"; 569 } 571 // grouping statements 573 grouping generic-defined-sets { 574 description 575 "Data definitions for pre-defined sets of attributes used in 576 policy match conditions. These sets are generic and can 577 be used in matching conditions in different routing 578 protocols."; 580 container prefix-sets { 581 description 582 "Enclosing container for defined prefix sets for matching"; 584 list prefix-set { 585 key prefix-set-name; 586 description 587 "List of the defined prefix sets"; 589 leaf prefix-set-name { 590 type string; 591 description 592 "name / label of the prefix set -- this is used to 593 reference the set in match conditions"; 594 } 596 list prefix { 597 key "ip-prefix masklength-range"; 598 description 599 "List of prefix expressions that are part of the set"; 601 leaf ip-prefix { 602 type inet:ip-prefix; 603 mandatory true; 604 description 605 "The prefix member in CIDR notation -- while the 606 prefix may be either IPv4 or IPv6, most 607 implementations require all members of the prefix set 608 to be the same address family. Mixing address types in 609 the same prefix set is likely to cause an error."; 610 } 612 leaf masklength-range { 613 type string { 614 pattern '^([0-9]+\.\.[0-9]+)|exact$'; 615 } 616 description 617 "Defines a range for the masklength, or 'exact' if 618 the prefix has an exact length. 620 Example: 10.3.192.0/21 through 10.3.192.0/24 would be 621 expressed as prefix: 10.3.192.0/21, 622 masklength-range: 21..24. 624 Example: 10.3.192.0/21 would be expressed as 625 prefix: 10.3.192.0/21, 626 masklength-range: exact"; 627 } 628 } 629 } 630 } 632 container neighbor-sets { 633 description 634 "Enclosing container for defined neighbor sets for matching"; 636 list neighbor-set { 637 key neighbor-set-name; 638 description 639 "Definitions for neighbor sets"; 641 leaf neighbor-set-name { 642 type string; 643 description 644 "name / label of the neighbor set -- this is used to 645 reference the set in match conditions"; 646 } 648 list neighbor { 649 key "address"; 650 description 651 "list of addresses that are part of the neighbor set"; 653 leaf address { 654 type inet:ip-address; 655 description 656 "IP address of the neighbor set member"; 657 } 658 } 659 } 660 } 662 container tag-sets { 663 description 664 "Enclosing container for defined tag sets for matching"; 666 list tag-set { 667 key tag-set-name; 668 description 669 "Definitions for tag sets"; 671 leaf tag-set-name { 672 type string; 673 description 674 "name / label of the tag set -- this is used to reference 675 the set in match conditions"; 676 } 678 list tag { 679 key "value"; 680 description 681 "list of tags that are part of the tag set"; 683 leaf value { 684 type pt:tag-type; 685 description 686 "Value of the tag set member"; 687 } 688 } 689 } 690 } 691 } 693 grouping local-generic-conditions { 694 description 695 "Condition statement definitions for consideration of a local 696 characteristic of a route"; 698 leaf install-protocol-eq { 699 type identityref { 700 base pt:install-protocol-type; 701 } 702 description 703 "Condition to check the protocol / method used to install 704 which installed the route into the local routing table"; 705 } 706 } 708 grouping match-set-options-group { 709 description 710 "Grouping containing options relating to how a particular set 711 should be matched"; 713 leaf match-set-options { 714 type pt:match-set-options-type; 715 description 716 "Optional parameter that governs the behaviour of the 717 match operation"; 718 } 719 } 721 grouping match-set-options-restricted-group { 722 description 723 "Grouping for a restricted set of match operation modifiers"; 725 leaf match-set-options { 726 type pt:match-set-options-restricted-type; 727 description 728 "Optional parameter that governs the behaviour of the 729 match operation. This leaf only supports matching on ANY 730 member of the set or inverting the match. Matching on ALL is 731 not supported)"; 732 } 733 } 734 grouping generic-conditions { 735 description "Condition statement definitions for checking 736 membership in a generic defined set"; 738 container match-prefix-set { 739 presence 740 "The presence of this container indicates that the routes 741 should match the prefix-set referenced."; 743 description 744 "Match a referenced prefix-set according to the logic 745 defined in the match-set-options leaf"; 747 leaf prefix-set { 748 type leafref { 749 path "/routing-policy/defined-sets/prefix-sets/" + 750 "prefix-set/prefix-set-name"; 751 //TODO: require-instance should be added when it's 752 //supported in YANG 1.1 753 //require-instance true; 754 } 755 description "References a defined prefix set"; 756 } 757 uses match-set-options-restricted-group; 758 } 760 container match-neighbor-set { 761 presence 762 "The presence of this container indicates that the routes 763 should match the neighbour set referenced"; 765 description 766 "Match a referenced neighbor set according to the logic 767 defined in the match-set-options-leaf"; 769 leaf neighbor-set { 770 type leafref { 771 path "/routing-policy/defined-sets/neighbor-sets/" + 772 "neighbor-set/neighbor-set-name"; 773 //TODO: require-instance should be added when it's 774 //supported in YANG 1.1 775 //require-instance true; 776 } 777 description "References a defined neighbor set"; 778 } 779 uses match-set-options-restricted-group; 780 } 781 container match-tag-set { 782 presence 783 "The presence of this container indicates that the routes 784 should match the tag-set referenced"; 786 description 787 "Match a referenced tag set according to the logic defined 788 in the match-options-set leaf"; 790 leaf tag-set { 791 type leafref { 792 path "/routing-policy/defined-sets/tag-sets/tag-set" + 793 "/tag-set-name"; 794 //TODO: require-instance should be added when it's 795 //supported in YANG 1.1 796 //require-instance true; 797 } 798 description "References a defined tag set"; 799 } 800 uses match-set-options-restricted-group; 801 } 803 uses local-generic-conditions; 804 } 806 grouping igp-generic-conditions { 807 description "grouping for IGP policy conditions"; 809 } 811 grouping igp-conditions { 812 description "grouping for IGP-specific policy conditions"; 814 container igp-conditions { 815 description "Policy conditions for IGP attributes"; 817 uses igp-generic-conditions; 819 } 820 } 822 grouping generic-actions { 823 description 824 "Definitions for common set of policy action statements that 825 manage the disposition or control flow of the policy"; 827 choice route-disposition { 828 description 829 "Select the final disposition for the route, either 830 accept or reject."; 831 leaf accept-route { 832 type empty; 833 description "accepts the route into the routing table"; 834 } 836 leaf reject-route { 837 type empty; 838 description "rejects the route"; 839 } 840 } 841 } 843 grouping igp-actions { 844 description "grouping for IGP-specific policy actions"; 846 container igp-actions { 847 description "Actions to set IGP route attributes; these actions 848 apply to multiple IGPs"; 850 leaf set-tag { 851 type pt:tag-type; 852 description 853 "Set the tag value for OSPF or IS-IS routes."; 854 } 855 } 856 } 858 container routing-policy { 859 description 860 "top-level container for all routing policy configuration"; 862 container defined-sets { 863 description 864 "Predefined sets of attributes used in policy match 865 statements"; 867 uses generic-defined-sets; 868 // uses bgp-defined-sets; 869 // don't see a need for IGP-specific defined sets at this point 870 // e.g., for OSPF, IS-IS, etc. 871 } 873 container policy-definitions { 874 description 875 "Enclosing container for the list of top-level policy 876 definitions"; 878 list policy-definition { 880 key name; 881 description 882 "List of top-level policy definitions, keyed by unique 883 name. These policy definitions are expected to be 884 referenced (by name) in policy chains specified in import/ 885 export configuration statements."; 887 leaf name { 888 type string; 889 description 890 "Name of the top-level policy definition -- this name 891 is used in references to the current policy"; 892 } 894 container statements { 895 description 896 "Enclosing container for policy statements"; 898 list statement { 899 key name; 900 // TODO: names of policy statements within a policy defn 901 // should be optional, however, YANG requires a unique id 902 // for lists; not sure that a compound key works either; 903 // need to investigate further. 904 ordered-by user; 905 description 906 "Policy statements group conditions and actions within 907 a policy definition. They are evaluated in the order 908 specified (see the description of policy evaluation 909 at the top of this module."; 911 leaf name { 912 type string; 913 description "name of the policy statement"; 914 } 916 container conditions { 918 description "Condition statements for this 919 policy statement"; 921 leaf call-policy { 922 type leafref { 923 path "/rpol:routing-policy/" + 924 "rpol:policy-definitions/" + 925 "rpol:policy-definition/rpol:name"; 926 //TODO: require-instance should be added when it's 927 //supported in YANG 1.1 928 //require-instance true; 929 } 930 description 931 "Applies the statements from the specified policy 932 definition and then returns control the current 933 policy statement. Note that the called policy may 934 itself call other policies (subject to 935 implementation limitations). This is intended to 936 provide a policy 'subroutine' capability. The 937 called policy should contain an explicit or a 938 default route disposition that returns an effective 939 true (accept-route) or false (reject-route), 940 otherwise the behavior may be ambiguous and 941 implementation dependent"; 942 } 943 uses generic-conditions; 944 uses igp-conditions; 945 } 947 container actions { 949 description "Action statements for this policy 950 statement"; 952 uses generic-actions; 953 uses igp-actions; 954 } 955 } 956 } 957 } 958 } 959 } 961 grouping apply-policy-config { 962 description 963 "Configuration data for routing policies"; 965 leaf-list import-policy { 966 type leafref { 967 path "/rpol:routing-policy/rpol:policy-definitions/" + 968 "rpol:policy-definition/rpol:name"; 969 //TODO: require-instance should be added when it's 970 //supported in YANG 1.1 971 //require-instance true; 972 } 973 ordered-by user; 974 description 975 "list of policy names in sequence to be applied on 976 receiving a routing update in the current context, e.g., 977 for the current peer group, neighbor, address family, 978 etc."; 979 } 981 leaf default-import-policy { 982 type default-policy-type; 983 default REJECT-ROUTE; 984 description 985 "explicitly set a default policy if no policy definition 986 in the import policy chain is satisfied."; 987 } 989 leaf-list export-policy { 990 type leafref { 991 path "/rpol:routing-policy/rpol:policy-definitions/" + 992 "rpol:policy-definition/rpol:name"; 993 //TODO: require-instance should be added when it's 994 //supported in YANG 1.1 995 //require-instance true; 996 } 997 ordered-by user; 998 description 999 "list of policy names in sequence to be applied on 1000 sending a routing update in the current context, e.g., 1001 for the current peer group, neighbor, address family, 1002 etc."; 1003 } 1005 leaf default-export-policy { 1006 type default-policy-type; 1007 default REJECT-ROUTE; 1008 description 1009 "explicitly set a default policy if no policy definition 1010 in the export policy chain is satisfied."; 1011 } 1012 } 1014 grouping apply-policy-state { 1015 description 1016 "Operational state associated with routing policy"; 1018 //TODO: identify additional state data beyond the intended 1019 //policy configuration. 1020 } 1022 grouping apply-policy-group { 1023 description 1024 "Top level container for routing policy applications. This 1025 grouping is intended to be used in routing models where 1026 needed."; 1028 container apply-policy { 1029 description 1030 "Anchor point for routing policies in the model. 1031 Import and export policies are with respect to the local 1032 routing table, i.e., export (send) and import (receive), 1033 depending on the context."; 1035 container config { 1036 description 1037 "Policy configuration data."; 1039 uses apply-policy-config; 1040 } 1042 container state { 1044 config false; 1045 description 1046 "Operational state for routing policy"; 1048 uses apply-policy-config; 1049 uses apply-policy-state; 1050 } 1051 } 1052 } 1053 } 1054 1056 9.2. Routing policy types 1058 file policy-types.yang 1059 module policy-types { 1061 yang-version "1"; 1063 // namespace 1064 namespace "http://openconfig.net/yang/policy-types"; 1065 prefix "ptypes"; 1067 // import some basic types 1068 import ietf-yang-types { prefix yang; } 1070 // meta 1071 organization 1072 "OpenConfig working group"; 1074 contact 1075 "OpenConfig working group 1076 netopenconfig@googlegroups.com"; 1078 description 1079 "This module contains general data definitions for use in routing 1080 policy. It can be imported by modules that contain protocol- 1081 specific policy conditions and actions."; 1083 revision "2015-05-15" { 1084 description 1085 "Initial revision"; 1086 reference "TBD"; 1087 } 1089 // identity statements 1091 identity attribute-comparison { 1092 description 1093 "base type for supported comparison operators on route 1094 attributes"; 1095 } 1097 identity attribute-eq { 1098 base attribute-comparison; 1099 description "== comparison"; 1100 } 1102 identity attribute-ge { 1103 base attribute-comparison; 1104 description ">= comparison"; 1105 } 1107 identity attribute-le { 1108 base attribute-comparison; 1109 description "<= comparison"; 1110 } 1111 typedef match-set-options-type { 1112 type enumeration { 1113 enum ANY { 1114 description "match is true if given value matches any member 1115 of the defined set"; 1116 } 1117 enum ALL { 1118 description "match is true if given value matches all 1119 members of the defined set"; 1120 } 1121 enum INVERT { 1122 description "match is true if given value does not match any 1123 member of the defined set"; 1124 } 1125 } 1126 default ANY; 1127 description 1128 "Options that govern the behavior of a match statement. The 1129 default behavior is ANY, i.e., the given value matches any 1130 of the members of the defined set"; 1131 } 1133 typedef match-set-options-restricted-type { 1134 type enumeration { 1135 enum ANY { 1136 description "match is true if given value matches any member 1137 of the defined set"; 1138 } 1139 enum INVERT { 1140 description "match is true if given value does not match any 1141 member of the defined set"; 1142 } 1143 } 1144 default ANY; 1145 description 1146 "Options that govern the behavior of a match statement. The 1147 default behavior is ANY, i.e., the given value matches any 1148 of the members of the defined set. Note this type is a 1149 restricted version of the match-set-options-type."; 1150 //TODO: restriction on enumerated types is only allowed in 1151 //YANG 1.1. Until then, we will require this additional type 1152 } 1154 grouping attribute-compare-operators { 1155 description "common definitions for comparison operations in 1156 condition statements"; 1158 leaf operator { 1159 type identityref { 1160 base attribute-comparison; 1161 } 1162 description 1163 "type of comparison to be performed"; 1164 } 1166 leaf value { 1167 type uint32; 1168 description 1169 "value to compare with the community count"; 1170 } 1171 } 1173 typedef tag-type { 1174 type union { 1175 type uint32; 1176 type yang:hex-string; 1177 } 1178 description "type for expressing route tags on a local system, 1179 including IS-IS and OSPF; may be expressed as either decimal or 1180 hexidecimal integer"; 1181 reference 1182 "RFC 2178 OSPF Version 2 1183 RFC 5130 A Policy Control Mechanism in IS-IS Using 1184 Administrative Tags"; 1185 } 1187 identity install-protocol-type { 1188 description 1189 "Base type for protocols which can install prefixes into the 1190 RIB"; 1191 } 1193 identity BGP { 1194 base install-protocol-type; 1195 description "BGP"; 1196 reference "RFC 4271"; 1197 } 1199 identity ISIS { 1200 base install-protocol-type; 1201 description "IS-IS"; 1202 reference "ISO/IEC 10589"; 1203 } 1205 identity OSPF { 1206 base install-protocol-type; 1207 description "OSPFv2"; 1208 reference "RFC 2328"; 1209 } 1211 identity OSPF3 { 1212 base install-protocol-type; 1213 description "OSPFv3"; 1214 reference "RFC 5340"; 1215 } 1217 identity STATIC { 1218 base install-protocol-type; 1219 description "Locally-installed static route"; 1220 } 1222 identity DIRECTLY-CONNECTED { 1223 base install-protocol-type; 1224 description "A directly connected route"; 1225 } 1227 identity LOCAL-AGGREGATE { 1228 base install-protocol-type; 1229 description "Locally defined aggregate route"; 1230 } 1231 } 1232 1234 10. Policy examples 1236 Below we show an example of XML-encoded configuration data using the 1237 routing policy and BGP models to illustrate both how policies are 1238 defined, and also how they can be applied. Note that the XML has 1239 been simplified for readability. 1241 1243 1244 1245 1246
A1
1247 M1 1248 1249 1250
A2
1251 M2 1252 1253 1254
A3
1255 M3 1256 1257 1259 1260 cust-tag1 1261 1262 1264 1265 C1 1266 C2 1267 C3 1268 1269 1270 C5 1271 C6 1272 C7 1273 1275 1276 AS1 1277 AS2 1278 ASx 1279 1281 1283 1287 1288 1289 1290 1291 1292 community-set-A 1293 1294 1295 1296 10 1297 1298 1299 1300 1301 IGP 1302 1303 1304 1305 1306 1307 1308 1310 1315 1316 1317 1318 1319 community-set-B 1320 ALL 1321 1322 1323 as-path-set-A 1324 1325 1326 1327 1328 1329 1330 1332 1337 1338 1339 1340 1341 community-set-A 1342 ALL 1343 1344 1345 1346 1347 1348 1350 1352 1357 1358 1359 1360 OSPFV3 1361 cust-tag1 1362 1363 1364 1365 1366 1367 1369 1371 1372 1373 1374 172.95.25.2 1375 ASY 1376 regional peer ASY 1377 EXTERNAL 1378 true 1379 1380 1381 4 1382 1383 1384 1385 policy 2 1386 policy 3 1387 REJECT-ROUTE 1388 1389 1390 1392 11. References 1394 11.1. Normative references 1396 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 1397 Network Configuration Protocol (NETCONF)", RFC 6020, 1398 October 2014. 1400 [RFC4271] Rekhter, Y., Li, T., and S. Hares, "A Border Gateway 1401 Protocol 4 (BGP-4)", RFC 4271, January 2006. 1403 [RFC6991] Schoenwaelder, J., "Common YANG Data Types", RFC 6991, 1404 July 2013. 1406 [RFC3688] Mealling, M., "The IETF XML Registry", RFC 3688, January 1407 2004. 1409 11.2. Informative references 1411 [I-D.ietf-idr-bgp-model] 1412 Shaikh, A., Shakir, R., Patel, K., Hares, S., D'Souza, K., 1413 Bansal, D., Clemm, A., Alex, A., Jethanandani, M., and X. 1414 Liu, "BGP Model for Service Provider Networks", draft- 1415 ietf-idr-bgp-model-00 (work in progress), July 2015. 1417 [I-D.openconfig-netmod-opstate] 1418 Shakir, R., Shaikh, A., and M. Hines, "Consistent Modeling 1419 of Operational State Data in YANG", draft-openconfig- 1420 netmod-opstate-00 (work in progress), March 2015. 1422 Appendix A. Acknowledgements 1424 The authors are grateful for valuable contributions to this document 1425 and the associated models from: Ebben Aires, Luyuan Fang, Josh 1426 George, Acee Lindem, Stephane Litkowski, Ina Minei, Carl Moberg, Eric 1427 Osborne, Steve Padgett, Juergen Schoenwaelder, Jim Uttaro, and Russ 1428 White. 1430 Appendix B. Change summary 1432 B.1. Changes between revisions draft-shaikh-rtgwg-policy-model and -00 1434 This revision updates the draft name to reflect adoption as a working 1435 document in the RTGWG. Minor changes include updates to references 1436 and updated author contact information. 1438 Authors' Addresses 1440 Anees Shaikh 1441 Google 1442 1600 Amphitheatre Pkwy 1443 Mountain View, CA 94043 1444 US 1446 Email: aashaikh@google.com 1448 Rob Shakir 1449 Individual 1451 Email: rjs@rob.sh 1453 Kevin D'Souza 1454 AT&T 1455 200 S. Laurel Ave 1456 Middletown, NJ 1457 US 1459 Email: kd6913@att.com 1461 Chris Chase 1462 AT&T 1463 9505 Arboretum Blvd 1464 Austin, TX 1465 US 1467 Email: chase@labs.att.com