idnits 2.17.1 draft-shaikh-rtgwg-policy-model-01.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: ---------------------------------------------------------------------------- ** The document is more than 15 pages and seems to lack a Table of Contents. 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 161 has weird spacing: '...et-name str...' == Line 164 has weird spacing: '...h-range str...' == Line 167 has weird spacing: '...et-name str...' == Line 169 has weird spacing: '...address ine...' == Line 172 has weird spacing: '...et-name str...' == (1 more instance...) -- The document date (July 4, 2015) is 3219 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Outdated reference: A later version (-01) exists of draft-openconfig-netmod-opstate-00 Summary: 1 error (**), 0 flaws (~~), 9 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: January 5, 2016 BT 6 K. D'Souza 7 C. Chase 8 AT&T 9 July 4, 2015 11 Routing Policy Configuration Model for Service Provider Networks 12 draft-shaikh-rtgwg-policy-model-01 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 January 5, 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 1. Introduction 55 This document describes a YANG [RFC6020] data model for routing 56 policy configuration based on operational usage and best practices in 57 a variety of service provider networks. The model is intended to be 58 vendor-neutral, in order to allow operators to manage policy 59 configuration in a consistent, intuitive way in heterogeneous 60 environments with routers supplied by multiple vendors. 62 1.1. Goals and approach 64 This model does not aim to be feature complete -- it is a subset of 65 the policy configuration parameters available in a variety of vendor 66 implementations, but supports widely used constructs for managing how 67 routes are imported, exported, and modified across different routing 68 protocols. The model development approach has been to examine actual 69 policy configurations in use across a number of operator networks. 70 Hence the focus is on enabling policy configuration capabilities and 71 structure that are in wide use. 73 Despite the differences in details of policy expressions and 74 conventions in various vendor implementations, the model reflects the 75 observation that a relatively simple condition- action approach can 76 be readily mapped to several existing vendor implementations, and 77 also gives operators an intuitive and straightforward way to express 78 policy without sacrificing flexibility. A side affect of this design 79 decision is that legacy methods for expressing policies are not 80 considered. Such methods could be added as an augmentation to the 81 model if needed. 83 Consistent with the goal to produce a data model that is vendor 84 neutral, only policy expressions that are deemed to be widely 85 available in existing major implementations are included in the 86 model. Those configuration items that are only available from a 87 single implementation are omitted from the model with the expectation 88 they will be available in separate vendor-provided modules that 89 augment the current model. 91 2. Model overview 93 The routing policy model is defined in two YANG modules, the main 94 policy module, and an auxiliary module providing additional generic 95 types. The model has three main parts: 97 o A generic framework to express policies as sets of related 98 conditions and actions. This includes match sets and actions that 99 are useful across many routing protocols. 101 o A structure that allows routing protocol models to add protocol- 102 specific policy conditions and actions though YANG augmentations. 103 There is a complete example of this for BGP [RFC4271] policies in 104 the proposed vendor-neutral BGP data model 105 [I-D.shaikh-idr-bgp-model]. 107 o A reusable grouping for attaching import and export rules in the 108 context of routing configuration for different protocols, VRFs, 109 etc. This also enables creation of policy chains and expressing 110 default policy behavior. 112 These modules make use of the standard Internet types, such as IP 113 addresses, autonomous system numbers, etc., defined in RFC 6991 114 [RFC6991]. 116 3. Route policy expression 118 Policies are expressed as a sequence of top-level policy definitions 119 each of which consists of a sequence of policy statements. Policy 120 statements in turn consist of simple condition-action tuples. 121 Conditions may include multiple match or comparison operations, and 122 similarly, actions may effect multiple changes to route attributes, 123 or indicate a final disposition of accepting or rejecting the route. 124 This structure is shown below. 126 +--rw routing-policy 127 +--rw policy-definitions 128 +--rw policy-definition* [name] 129 +--rw name string 130 +--rw statements 131 +--rw statement* [name] 132 +--rw name string 133 +--rw conditions 134 | ... 135 +--rw actions 136 ... 138 3.1. Defined sets for policy matching 140 The models provides a set of generic sets that can be used for 141 matching in policy conditions. These sets are applicable across 142 multiple routing protocols, and may be further augmented by protocol- 143 specific models which have their own defined sets. The supported 144 defined sets include: 146 o prefix sets - define a set of IP prefixes, each with an associated 147 CIDR netmask range (or exact length) 149 o neighbor sets - define a set of neighboring nodes by their IP 150 addresses 152 o tag set - define a set of generic tag values that can be used in 153 matches for filtering routes 155 The model structure for defined sets is shown below. 157 +--rw routing-policy 158 +--rw defined-sets 159 +--rw prefix-sets 160 | +--rw prefix-set* [prefix-set-name] 161 | +--rw prefix-set-name string 162 | +--rw prefix* [ip-prefix masklength-range] 163 | +--rw ip-prefix inet:ip-prefix 164 | +--rw masklength-range string 165 +--rw neighbor-sets 166 | +--rw neighbor-set* [neighbor-set-name] 167 | +--rw neighbor-set-name string 168 | +--rw neighbor* [address] 169 | +--rw address inet:ip-address 170 +--rw tag-sets 171 +--rw tag-set* [tag-set-name] 172 +--rw tag-set-name string 173 +--rw tag* [value] 174 +--rw value pt:tag-type 176 3.2. Policy conditions 178 Policy statements consist of a set of conditions and actions (either 179 of which may be empty). Conditions are used to match route 180 attributes against a defined set (e.g., a prefix set), or to compare 181 attributes against a specific value. 183 Match conditions may be further modified using the match-set-options 184 configuration which allows operators to change the behavior of a 185 match. Three options are supported: 187 o ALL - match is true only if the given value matches all members of 188 the set. 190 o ANY - match is true if the given value matches any member of the 191 set. 193 o INVERT - match is true if the given value does not match any 194 member of the given set. 196 Not all options are appropriate for matching against all defined sets 197 (e.g., match ALL in a prefix set does not make sense). In the model, 198 a restricted set of match options is used where applicable. 200 Comparison conditions may similarly use options to change how route 201 attributes should be tested, e.g., for equality or inequality, 202 against a given value. 204 While most policy conditions will be added by individual routing 205 protocol models via augmentation, this routing policy model includes 206 several generic match conditions and also the ability to test which 207 protocol or mechanism installed a route (e.g., BGP, IGP, static, 208 etc.). The conditions included in the model are shown below. 210 +--rw routing-policy 211 +--rw policy-definitions 212 +--rw policy-definition* [name] 213 +--rw statements 214 +--rw statement* [name] 215 +--rw conditions 216 +--rw call-policy? 217 +--rw match-prefix-set! 218 | +--rw prefix-set? 219 | +--rw match-set-options? 220 +--rw match-neighbor-set! 221 | +--rw neighbor-set? 222 | +--rw match-set-options? 223 +--rw match-tag-set! 224 | +--rw tag-set? 225 | +--rw match-set-options? 226 +--rw install-protocol-eq? 227 +--rw igp-conditions 229 3.3. Policy actions 231 When policy conditions are satisfied, policy actions are used to set 232 various attributes of the route being processed, or to indicate the 233 final disposition of the route, i.e., accept or reject. 235 Similar to policy conditions, the routing policy model includes 236 generic actions in addition to the basic route disposition actions. 237 These are shown below. 239 +--rw routing-policy 240 +--rw policy-definitions 241 +--rw policy-definition* [name] 242 +--rw statements 243 +--rw statement* [name] 244 +--rw actions 245 +--rw (route-disposition)? 246 | +--:(accept-route) 247 | | +--rw accept-route? empty 248 | +--:(reject-route) 249 | +--rw reject-route? empty 250 +--rw igp-actions 251 +--rw set-tag? pt:tag-type 253 3.4. Policy subroutines 255 Policy 'subroutines' (or nested policies) are supported by allowing 256 policy statement conditions to reference other policy definitions 257 using the call-policy configuration. Called policies apply their 258 conditions and actions before returning to the calling policy 259 statement and resuming evaluation. The outcome of the called policy 260 affects the evaluation of the calling policy. If the called policy 261 results in an accept-route (either explicit or by default), then the 262 subroutine returns an effective boolean true value to the calling 263 policy. For the calling policy, this is equivalent to a condition 264 statement evaluating to a true value and evaluation of the policy 265 continues (see Section 4). Note that the called policy may also 266 modify attributes of the route in its action statements. Similarly, 267 a reject-route action returns false and the calling policy evaluation 268 will be affected accordingly. 270 Note that the called policy may itself call other policies (subject 271 to implementation limitations). The model does not prescribe a 272 nesting depth because this varies among implementations, with some 273 major implementations only supporting a single subroutine, for 274 example. As with any routing policy construction, care must be taken 275 with nested policies to ensure that the effective return value 276 results in the intended behavior. Nested policies are a convenience 277 in many routing policy constructions but creating policies nested 278 beyond a small number of levels (e.g., 2-3) should be discouraged. 280 4. Policy evaluation 282 Evaluation of each policy definition proceeds by evaluating its 283 corresponding individual policy statements in order. When a 284 condition statement in a policy statement is satisfied, the 285 corresponding action statement is executed. If the action statement 286 has either accept-route or reject-route actions, evaluation of the 287 current policy definition stops, and no further policy definitions in 288 the chain are evaluated. 290 If the condition is not satisfied, then evaluation proceeds to the 291 next policy statement. If none of the policy statement conditions 292 are satisfied, then evaluation of the current policy definition 293 stops, and the next policy definition in the chain is evaluated. 294 When the end of the policy chain is reached, the default route 295 disposition action is performed (i.e., reject-route unless an an 296 alternate default action is specified for the chain). 298 5. Applying routing policy 300 Routing policy is applied by defining and attaching policy chains in 301 various routing contexts. Policy chains are sequences of policy 302 definitions (described in Section 3) that have an associated 303 direction (import or export) with respect to the routing context in 304 which they are defined. The routing policy model defines an apply- 305 policy grouping that can be imported and used by other models. As 306 shown below, it allows definition of import and export policy chains, 307 as well as specifying the default route disposition to be used when 308 no policy definition in the chain results in a final decision. 310 +--rw apply-policy 311 | +--rw config 312 | | +--rw import-policy* 313 | | +--rw default-import-policy? default-policy-type 314 | | +--rw export-policy* 315 | | +--rw default-export-policy? default-policy-type 317 The default policy defined by the model is to reject the route for 318 both import and export policies. 320 An example of using the apply-policy group in another routing model 321 is shown below for BGP. Here, import and export policies are applied 322 in the context of a particular BGP peer group. Note that the policy 323 chains reference policy definitions by name that are defined in the 324 routing policy model. 326 +--rw bgp! 327 +--rw peer-groups 328 +--rw peer-group* [peer-group-name] 329 +--rw peer-group-name 330 +--rw config 331 | +--rw peer-as? 332 | +--rw local-as? 333 | +--rw peer-type? 334 | +--rw auth-password? 335 | +--rw remove-private-as? 336 | +--rw route-flap-damping? 337 | +--rw send-community? 338 | +--rw description? 339 | +--rw peer-group-name? 340 +--ro state 341 | +--ro peer-as? 342 | +--ro local-as? 343 | +--ro peer-type? 344 | +--ro auth-password? 345 | +--ro remove-private-as? 346 | +--ro route-flap-damping? 347 | +--ro send-community? 348 | +--ro description? 349 | +--ro peer-group-name? 350 | +--ro total-paths? 351 | +--ro total-prefixes? 352 +--rw apply-policy 353 | +--rw config 354 | | +--rw import-policy* 355 | | +--rw default-import-policy? 356 | | +--rw export-policy* 357 | | +--rw default-export-policy? 358 | +--ro state 359 | +--ro import-policy* 360 | +--ro default-import-policy? 361 | +--ro export-policy* 362 | +--ro default-export-policy? 363 ... 365 6. Routing protocol-specific policies 367 Routing models that require the ability to apply routing policy may 368 augment the routing policy model with protocol or other specific 369 policy configuration. The routing policy model assumes that 370 additional defined sets, conditions, and actions may all be added by 371 other models. 373 An example of this is shown below, in which the BGP configuration 374 model in [I-D.shaikh-idr-bgp-model] adds new defined sets to match on 375 community values or AS paths. The model similarly augments BGP- 376 specific conditions and actions into the corresponding sections of 377 the routing policy model. 379 +--rw routing-policy 380 +--rw defined-sets 381 +--rw prefix-sets 382 | +--rw prefix-set* [prefix-set-name] 383 | +--rw prefix-set-name 384 | +--rw prefix* [ip-prefix masklength-range] 385 | +--rw ip-prefix 386 | +--rw masklength-range 387 +--rw neighbor-sets 388 | +--rw neighbor-set* [neighbor-set-name] 389 | +--rw neighbor-set-name 390 | +--rw neighbor* [address] 391 | +--rw address 392 +--rw tag-sets 393 | +--rw tag-set* [tag-set-name] 394 | +--rw tag-set-name 395 | +--rw tag* [value] 396 | +--rw value 397 +--rw bgp-pol:bgp-defined-sets 398 +--rw bgp-pol:community-sets 399 | +--rw bgp-pol:community-set* [community-set-name] 400 | +--rw bgp-pol:community-set-name 401 | +--rw bgp-pol:community-member* 402 +--rw bgp-pol:ext-community-sets 403 | +--rw bgp-pol:ext-community-set* [ext-community-set-name] 404 | +--rw bgp-pol:ext-community-set-name 405 | +--rw bgp-pol:ext-community-member* 406 +--rw bgp-pol:as-path-sets 407 +--rw bgp-pol:as-path-set* [as-path-set-name] 408 +--rw bgp-pol:as-path-set-name 409 +--rw bgp-pol:as-path-set-member* 411 7. Security Considerations 413 Routing policy configuration has a significant impact on network 414 operations, and as such any related model carries potential security 415 risks. 417 YANG data models are generally designed to be used with the NETCONF 418 protocol over an SSH transport. This provides an authenticated and 419 secure channel over which to transfer configuration and operational 420 data. Note that use of alternate transport or data encoding (e.g., 421 JSON over HTTPS) would require similar mechanisms for authenticating 422 and securing access to configuration data. 424 Most of the data elements in the policy model could be considered 425 sensitive from a security standpoint. Unauthorized access or invalid 426 data could cause major disruption. 428 8. IANA Considerations 430 This YANG data model and the component modules currently use a 431 temporary ad-hoc namespace. If and when it is placed on redirected 432 for the standards track, an appropriate namespace URI will be 433 registered in the IETF XML Registry" [RFC3688]. The routing policy 434 YANG modules will be registered in the "YANG Module Names" registry 435 [RFC6020]. 437 9. YANG modules 439 The routing policy model is described by the YANG modules in the 440 sections below. 442 9.1. Routing policy model 444 file routing-policy.yang 445 module routing-policy { 447 yang-version "1"; 449 // namespace 450 namespace "http://openconfig.net/yang/routing-policy"; 452 prefix "rpol"; 454 // import some basic types 455 import ietf-inet-types { prefix inet; } 456 import policy-types {prefix pt; } 458 // meta 459 organization 460 "OpenConfig working group"; 462 contact 463 "OpenConfig working group 464 netopenconfig@googlegroups.com"; 466 description 467 "This module describes a YANG model for routing policy 468 configuration. It is a limited subset of all of the policy 469 configuration parameters available in the variety of vendor 470 implementations, but supports widely used constructs for managing 471 how routes are imported, exported, and modified across different 472 routing protocols. This module is intended to be used in 473 conjunction with routing protocol configuration models (e.g., 474 BGP) defined in other modules. 476 Route policy expression: 478 Policies are expressed as a set of top-level policy definitions, 479 each of which consists of a sequence of policy statements. Policy 480 statements consist of simple condition-action tuples. Conditions 481 may include mutiple match or comparison operations, and similarly 482 actions may be multitude of changes to route attributes or a 483 final disposition of accepting or rejecting the route. 485 Route policy evaluation: 487 Policy definitions are referenced in routing protocol 488 configurations using import and export configuration statements. 489 The arguments are members of an ordered list of named policy 490 definitions which comprise a policy chain, and optionally, an 491 explicit default policy action (i.e., reject or accept). 493 Evaluation of each policy definition proceeds by evaluating its 494 corresponding individual policy statements in order. When a 495 condition statement in a policy statement is satisfied, the 496 corresponding action statement is executed. If the action 497 statement has either accept-route or reject-route actions, policy 498 evaluation of the current policy definition stops, and no further 499 policy definitions in the chain are evaluated. 501 If the condition is not satisfied, then evaluation proceeds to 502 the next policy statement. If none of the policy statement 503 conditions are satisfied, then evaluation of the current policy 504 definition stops, and the next policy definition in the chain is 505 evaluated. When the end of the policy chain is reached, the 506 default route disposition action is performed (i.e., reject-route 507 unless an an alternate default action is specified for the 508 chain). 510 Policy 'subroutines' (or nested policies) are supported by 511 allowing policy statement conditions to reference another policy 512 definition which applies conditions and actions from the 513 referenced policy before returning to the calling policy 514 statement and resuming evaluation. If the called policy 515 results in an accept-route (either explicit or by default), then 516 the subroutine returns an effective true value to the calling 517 policy. Similarly, a reject-route action returns false. If the 518 subroutine returns true, the calling policy continues to evaluate 519 the remaining conditions (using a modified route if the 520 subroutine performed any changes to the route)."; 522 revision "2015-05-15" { 523 description 524 "Initial revision"; 525 reference "TBD"; 526 } 528 // typedef statements 530 typedef default-policy-type { 531 type enumeration { 532 enum ACCEPT-ROUTE { 533 description "default policy to accept the route"; 534 } 535 enum REJECT-ROUTE { 536 description "default policy to reject the route"; 537 } 538 } 539 description "type used to specify default route disposition in 540 a policy chain"; 541 } 543 // grouping statements 545 grouping generic-defined-sets { 546 description 547 "Data definitions for pre-defined sets of attributes used in 548 policy match conditions. These sets are generic and can 549 be used in matching conditions in different routing 550 protocols."; 552 container prefix-sets { 553 description 554 "Enclosing container for defined prefix sets for matching"; 556 list prefix-set { 557 key prefix-set-name; 558 description 559 "List of the defined prefix sets"; 561 leaf prefix-set-name { 562 type string; 563 description 564 "name / label of the prefix set -- this is used to 565 reference the set in match conditions"; 566 } 568 list prefix { 569 key "ip-prefix masklength-range"; 570 description 571 "List of prefix expressions that are part of the set"; 573 leaf ip-prefix { 574 type inet:ip-prefix; 575 mandatory true; 576 description 577 "The prefix member in CIDR notation -- while the 578 prefix may be either IPv4 or IPv6, most 579 implementations require all members of the prefix set 580 to be the same address family. Mixing address types in 581 the same prefix set is likely to cause an error."; 582 } 584 leaf masklength-range { 585 type string { 586 pattern '^([0-9]+\.\.[0-9]+)|exact$'; 587 } 588 description 589 "Defines a range for the masklength, or 'exact' if 590 the prefix has an exact length. 592 Example: 10.3.192.0/21 through 10.3.192.0/24 would be 593 expressed as prefix: 10.3.192.0/21, 594 masklength-range: 21..24. 596 Example: 10.3.192.0/21 would be expressed as 597 prefix: 10.3.192.0/21, 598 masklength-range: exact"; 599 } 600 } 601 } 602 } 604 container neighbor-sets { 605 description 606 "Enclosing container for defined neighbor sets for matching"; 608 list neighbor-set { 609 key neighbor-set-name; 610 description 611 "Definitions for neighbor sets"; 613 leaf neighbor-set-name { 614 type string; 615 description 616 "name / label of the neighbor set -- this is used to 617 reference the set in match conditions"; 618 } 620 list neighbor { 621 key "address"; 622 description 623 "list of addresses that are part of the neighbor set"; 625 leaf address { 626 type inet:ip-address; 627 description 628 "IP address of the neighbor set member"; 629 } 630 } 631 } 632 } 634 container tag-sets { 635 description 636 "Enclosing container for defined tag sets for matching"; 638 list tag-set { 639 key tag-set-name; 640 description 641 "Definitions for tag sets"; 643 leaf tag-set-name { 644 type string; 645 description 646 "name / label of the tag set -- this is used to reference 647 the set in match conditions"; 648 } 650 list tag { 651 key "value"; 652 description 653 "list of tags that are part of the tag set"; 655 leaf value { 656 type pt:tag-type; 657 description 658 "Value of the tag set member"; 659 } 660 } 661 } 662 } 663 } 665 grouping local-generic-conditions { 666 description 667 "Condition statement definitions for consideration of a local 668 characteristic of a route"; 670 leaf install-protocol-eq { 671 type identityref { 672 base pt:install-protocol-type; 673 } 674 description 675 "Condition to check the protocol / method used to install 676 which installed the route into the local routing table"; 677 } 678 } 680 grouping match-set-options-group { 681 description 682 "Grouping containing options relating to how a particular set 683 should be matched"; 685 leaf match-set-options { 686 type pt:match-set-options-type; 687 description 688 "Optional parameter that governs the behaviour of the 689 match operation"; 690 } 691 } 693 grouping match-set-options-restricted-group { 694 description 695 "Grouping for a restricted set of match operation modifiers"; 697 leaf match-set-options { 698 type pt:match-set-options-restricted-type; 699 description 700 "Optional parameter that governs the behaviour of the 701 match operation. This leaf only supports matching on ANY 702 member of the set or inverting the match. Matching on ALL is 703 not supported)"; 704 } 705 } 706 grouping generic-conditions { 707 description "Condition statement definitions for checking 708 membership in a generic defined set"; 710 container match-prefix-set { 711 presence 712 "The presence of this container indicates that the routes 713 should match the prefix-set referenced."; 715 description 716 "Match a referenced prefix-set according to the logic 717 defined in the match-set-options leaf"; 719 leaf prefix-set { 720 type leafref { 721 path "/routing-policy/defined-sets/prefix-sets/" + 722 "prefix-set/prefix-set-name"; 723 //TODO: require-instance should be added when it's 724 //supported in YANG 1.1 725 //require-instance true; 726 } 727 description "References a defined prefix set"; 728 } 729 uses match-set-options-restricted-group; 730 } 732 container match-neighbor-set { 733 presence 734 "The presence of this container indicates that the routes 735 should match the neighbour set referenced"; 737 description 738 "Match a referenced neighbor set according to the logic 739 defined in the match-set-options-leaf"; 741 leaf neighbor-set { 742 type leafref { 743 path "/routing-policy/defined-sets/neighbor-sets/" + 744 "neighbor-set/neighbor-set-name"; 745 //TODO: require-instance should be added when it's 746 //supported in YANG 1.1 747 //require-instance true; 748 } 749 description "References a defined neighbor set"; 750 } 751 uses match-set-options-restricted-group; 752 } 753 container match-tag-set { 754 presence 755 "The presence of this container indicates that the routes 756 should match the tag-set referenced"; 758 description 759 "Match a referenced tag set according to the logic defined 760 in the match-options-set leaf"; 762 leaf tag-set { 763 type leafref { 764 path "/routing-policy/defined-sets/tag-sets/tag-set" + 765 "/tag-set-name"; 766 //TODO: require-instance should be added when it's 767 //supported in YANG 1.1 768 //require-instance true; 769 } 770 description "References a defined tag set"; 771 } 772 uses match-set-options-restricted-group; 773 } 775 uses local-generic-conditions; 776 } 778 grouping igp-generic-conditions { 779 description "grouping for IGP policy conditions"; 781 } 783 grouping igp-conditions { 784 description "grouping for IGP-specific policy conditions"; 786 container igp-conditions { 787 description "Policy conditions for IGP attributes"; 789 uses igp-generic-conditions; 791 } 792 } 794 grouping generic-actions { 795 description 796 "Definitions for common set of policy action statements that 797 manage the disposition or control flow of the policy"; 799 choice route-disposition { 800 description 801 "Select the final disposition for the route, either 802 accept or reject."; 803 leaf accept-route { 804 type empty; 805 description "accepts the route into the routing table"; 806 } 808 leaf reject-route { 809 type empty; 810 description "rejects the route"; 811 } 812 } 813 } 815 grouping igp-actions { 816 description "grouping for IGP-specific policy actions"; 818 container igp-actions { 819 description "Actions to set IGP route attributes; these actions 820 apply to multiple IGPs"; 822 leaf set-tag { 823 type pt:tag-type; 824 description 825 "Set the tag value for OSPF or IS-IS routes."; 826 } 827 } 828 } 830 container routing-policy { 831 description 832 "top-level container for all routing policy configuration"; 834 container defined-sets { 835 description 836 "Predefined sets of attributes used in policy match 837 statements"; 839 uses generic-defined-sets; 840 // uses bgp-defined-sets; 841 // don't see a need for IGP-specific defined sets at this point 842 // e.g., for OSPF, IS-IS, etc. 843 } 845 container policy-definitions { 846 description 847 "Enclosing container for the list of top-level policy 848 definitions"; 850 list policy-definition { 852 key name; 853 description 854 "List of top-level policy definitions, keyed by unique 855 name. These policy definitions are expected to be 856 referenced (by name) in policy chains specified in import/ 857 export configuration statements."; 859 leaf name { 860 type string; 861 description 862 "Name of the top-level policy definition -- this name 863 is used in references to the current policy"; 864 } 866 container statements { 867 description 868 "Enclosing container for policy statements"; 870 list statement { 871 key name; 872 // TODO: names of policy statements within a policy defn 873 // should be optional, however, YANG requires a unique id 874 // for lists; not sure that a compound key works either; 875 // need to investigate further. 876 ordered-by user; 877 description 878 "Policy statements group conditions and actions within 879 a policy definition. They are evaluated in the order 880 specified (see the description of policy evaluation 881 at the top of this module."; 883 leaf name { 884 type string; 885 description "name of the policy statement"; 886 } 888 container conditions { 890 description "Condition statements for this 891 policy statement"; 893 leaf call-policy { 894 type leafref { 895 path "/rpol:routing-policy/" + 896 "rpol:policy-definitions/" + 897 "rpol:policy-definition/rpol:name"; 898 //TODO: require-instance should be added when it's 899 //supported in YANG 1.1 900 //require-instance true; 901 } 902 description 903 "Applies the statements from the specified policy 904 definition and then returns control the current 905 policy statement. Note that the called policy may 906 itself call other policies (subject to 907 implementation limitations). This is intended to 908 provide a policy 'subroutine' capability. The 909 called policy should contain an explicit or a 910 default route disposition that returns an effective 911 true (accept-route) or false (reject-route), 912 otherwise the behavior may be ambiguous and 913 implementation dependent"; 914 } 915 uses generic-conditions; 916 uses igp-conditions; 917 } 919 container actions { 921 description "Action statements for this policy 922 statement"; 924 uses generic-actions; 925 uses igp-actions; 926 } 927 } 928 } 929 } 930 } 931 } 933 grouping apply-policy-config { 934 description 935 "Configuration data for routing policies"; 937 leaf-list import-policy { 938 type leafref { 939 path "/rpol:routing-policy/rpol:policy-definitions/" + 940 "rpol:policy-definition/rpol:name"; 941 //TODO: require-instance should be added when it's 942 //supported in YANG 1.1 943 //require-instance true; 944 } 945 ordered-by user; 946 description 947 "list of policy names in sequence to be applied on 948 receiving a routing update in the current context, e.g., 949 for the current peer group, neighbor, address family, 950 etc."; 951 } 953 leaf default-import-policy { 954 type default-policy-type; 955 default REJECT-ROUTE; 956 description 957 "explicitly set a default policy if no policy definition 958 in the import policy chain is satisfied."; 959 } 961 leaf-list export-policy { 962 type leafref { 963 path "/rpol:routing-policy/rpol:policy-definitions/" + 964 "rpol:policy-definition/rpol:name"; 965 //TODO: require-instance should be added when it's 966 //supported in YANG 1.1 967 //require-instance true; 968 } 969 ordered-by user; 970 description 971 "list of policy names in sequence to be applied on 972 sending a routing update in the current context, e.g., 973 for the current peer group, neighbor, address family, 974 etc."; 975 } 977 leaf default-export-policy { 978 type default-policy-type; 979 default REJECT-ROUTE; 980 description 981 "explicitly set a default policy if no policy definition 982 in the export policy chain is satisfied."; 983 } 984 } 986 grouping apply-policy-state { 987 description 988 "Operational state associated with routing policy"; 990 //TODO: identify additional state data beyond the intended 991 //policy configuration. 992 } 994 grouping apply-policy-group { 995 description 996 "Top level container for routing policy applications. This 997 grouping is intended to be used in routing models where 998 needed."; 1000 container apply-policy { 1001 description 1002 "Anchor point for routing policies in the model. 1003 Import and export policies are with respect to the local 1004 routing table, i.e., export (send) and import (receive), 1005 depending on the context."; 1007 container config { 1008 description 1009 "Policy configuration data."; 1011 uses apply-policy-config; 1012 } 1014 container state { 1016 config false; 1017 description 1018 "Operational state for routing policy"; 1020 uses apply-policy-config; 1021 uses apply-policy-state; 1022 } 1023 } 1024 } 1025 } 1026 1028 9.2. Routing policy types 1030 file policy-types.yang 1031 module policy-types { 1033 yang-version "1"; 1035 // namespace 1036 namespace "http://openconfig.net/yang/policy-types"; 1037 prefix "ptypes"; 1039 // import some basic types 1040 import ietf-yang-types { prefix yang; } 1042 // meta 1043 organization 1044 "OpenConfig working group"; 1046 contact 1047 "OpenConfig working group 1048 netopenconfig@googlegroups.com"; 1050 description 1051 "This module contains general data definitions for use in routing 1052 policy. It can be imported by modules that contain protocol- 1053 specific policy conditions and actions."; 1055 revision "2015-05-15" { 1056 description 1057 "Initial revision"; 1058 reference "TBD"; 1059 } 1061 // identity statements 1063 identity attribute-comparison { 1064 description 1065 "base type for supported comparison operators on route 1066 attributes"; 1067 } 1069 identity attribute-eq { 1070 base attribute-comparison; 1071 description "== comparison"; 1072 } 1074 identity attribute-ge { 1075 base attribute-comparison; 1076 description ">= comparison"; 1077 } 1079 identity attribute-le { 1080 base attribute-comparison; 1081 description "<= comparison"; 1082 } 1083 typedef match-set-options-type { 1084 type enumeration { 1085 enum ANY { 1086 description "match is true if given value matches any member 1087 of the defined set"; 1088 } 1089 enum ALL { 1090 description "match is true if given value matches all 1091 members of the defined set"; 1092 } 1093 enum INVERT { 1094 description "match is true if given value does not match any 1095 member of the defined set"; 1096 } 1097 } 1098 default ANY; 1099 description 1100 "Options that govern the behavior of a match statement. The 1101 default behavior is ANY, i.e., the given value matches any 1102 of the members of the defined set"; 1103 } 1105 typedef match-set-options-restricted-type { 1106 type enumeration { 1107 enum ANY { 1108 description "match is true if given value matches any member 1109 of the defined set"; 1110 } 1111 enum INVERT { 1112 description "match is true if given value does not match any 1113 member of the defined set"; 1114 } 1115 } 1116 default ANY; 1117 description 1118 "Options that govern the behavior of a match statement. The 1119 default behavior is ANY, i.e., the given value matches any 1120 of the members of the defined set. Note this type is a 1121 restricted version of the match-set-options-type."; 1122 //TODO: restriction on enumerated types is only allowed in 1123 //YANG 1.1. Until then, we will require this additional type 1124 } 1126 grouping attribute-compare-operators { 1127 description "common definitions for comparison operations in 1128 condition statements"; 1130 leaf operator { 1131 type identityref { 1132 base attribute-comparison; 1133 } 1134 description 1135 "type of comparison to be performed"; 1136 } 1138 leaf value { 1139 type uint32; 1140 description 1141 "value to compare with the community count"; 1142 } 1143 } 1145 typedef tag-type { 1146 type union { 1147 type uint32; 1148 type yang:hex-string; 1149 } 1150 description "type for expressing route tags on a local system, 1151 including IS-IS and OSPF; may be expressed as either decimal or 1152 hexidecimal integer"; 1153 reference 1154 "RFC 2178 OSPF Version 2 1155 RFC 5130 A Policy Control Mechanism in IS-IS Using 1156 Administrative Tags"; 1157 } 1159 identity install-protocol-type { 1160 description 1161 "Base type for protocols which can install prefixes into the 1162 RIB"; 1163 } 1165 identity BGP { 1166 base install-protocol-type; 1167 description "BGP"; 1168 reference "RFC 4271"; 1169 } 1171 identity ISIS { 1172 base install-protocol-type; 1173 description "IS-IS"; 1174 reference "ISO/IEC 10589"; 1175 } 1177 identity OSPF { 1178 base install-protocol-type; 1179 description "OSPFv2"; 1180 reference "RFC 2328"; 1181 } 1183 identity OSPF3 { 1184 base install-protocol-type; 1185 description "OSPFv3"; 1186 reference "RFC 5340"; 1187 } 1189 identity STATIC { 1190 base install-protocol-type; 1191 description "Locally-installed static route"; 1192 } 1194 identity DIRECTLY-CONNECTED { 1195 base install-protocol-type; 1196 description "A directly connected route"; 1197 } 1199 identity LOCAL-AGGREGATE { 1200 base install-protocol-type; 1201 description "Locally defined aggregate route"; 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 1216 1217 1218 prefix-set-A 1219 1220 192.0.2.0/24 1221 24..32 1222 1223 1224 10.0.0.0/16 1225 16..32 1226 1227 1228 192.168.0.0/19 1229 19..24 1230 1231 1232 1233 1234 1235 cust-tag1 1236 1237 10 1238 1239 1240 1241 1243 1244 1245 export-tagged-BGP 1246 1247 1248 term-0 1249 1250 OSPF3 1251 1252 cust-tag1 1253 1254 1255 1256 1257 1258 1259 1260 1261 1263 1265 1266 1267 1268 65517 1269 1270 1271 1272 1273 PG1 1274 1275 65518 1276 EXTERNAL 1277 1278 1279 1280 export-tagged-BGP 1281 1282 1283 1284 1285 1287 11. References 1289 11.1. Normative references 1291 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 1292 Network Configuration Protocol (NETCONF)", RFC 6020, 1293 October 2014. 1295 [RFC4271] Rekhter, Y., Li, T., and S. Hares, "A Border Gateway 1296 Protocol 4 (BGP-4)", RFC 4271, January 2006. 1298 [RFC6991] Schoenwaelder, J., "Common YANG Data Types", RFC 6991, 1299 July 2013. 1301 [RFC3688] Mealling, M., "The IETF XML Registry", RFC 3688, January 1302 2004. 1304 11.2. Informative references 1306 [I-D.shaikh-idr-bgp-model] 1307 Shaikh, A., Shakir, R., Patel, K., Hares, S., D'Souza, K., 1308 Bansal, D., Clemm, A., Alex, A., Jethanandani, M., and X. 1309 Liu, "BGP Model for Service Provider Networks", draft- 1310 shaikh-idr-bgp-model-02 (work in progress), June 2015. 1312 [I-D.openconfig-netmod-opstate] 1313 Shakir, R., Shaikh, A., and M. Hines, "Consistent Modeling 1314 of Operational State Data in YANG", draft-openconfig- 1315 netmod-opstate-00 (work in progress), March 2015. 1317 Appendix A. Acknowledgements 1319 The authors are grateful for valuable contributions to this document 1320 and the associated models from: Ebben Aires, Luyuan Fang, Josh 1321 George, Acee Lindem, Stephane Litkowski, Ina Minei, Carl Moberg, Eric 1322 Osborne, Steve Padgett, Juergen Schoenwaelder, Jim Uttaro, and Russ 1323 White. 1325 Appendix B. Change summary 1327 B.1. Changes between revisions -00 and -01 1329 The -01 revision of the policy model reflects a number of changes to 1330 the data model based on additional operator, reviewer, and 1331 implementor feedback. 1333 o Modified the apply-policy container to use the pattern for 1334 modeling operational state described in 1335 [I-D.openconfig-netmod-opstate]. 1337 o Updated prefix lists to use ip-prefix type and masklength range to 1338 better enable range-checking and validation. Added an 'exact' 1339 option to the masklength range. 1341 o Changed accept / reject route to be within a choice statement. 1343 o Added enclosing containers to lists. 1345 o Minor changes to leaf-lists in defined sets definitions; also to 1346 apply-policy container structure. 1348 o Added second type of match-options set to handle restricted case 1349 of only ANY | INVERT (i.e., without ALL). The restricted 1350 enumerated type is now associated with the appropriate types of 1351 sets. 1353 o Moved install-protocol-type identity to policy-types module. 1355 o Removed require-instance statements from leafrefs pending 1356 availability in YANG 1.1. 1358 o Fixed discrepancies in the example shown in the document, and 1359 simplified the example. 1361 Authors' Addresses 1363 Anees Shaikh 1364 Google 1365 1600 Amphitheatre Pkwy 1366 Mountain View, CA 94043 1367 US 1369 Email: aashaikh@google.com 1371 Rob Shakir 1372 BT 1373 pp. C3L, BT Centre 1374 81, Newgate Street 1375 London EC1A 7AJ 1376 UK 1378 Email: rob.shakir@bt.com 1379 URI: http://www.bt.com/ 1381 Kevin D'Souza 1382 AT&T 1383 200 S. Laurel Ave 1384 Middletown, NJ 1385 US 1387 Email: kd6913@att.com 1389 Chris Chase 1390 AT&T 1391 9505 Arboretum Blvd 1392 Austin, TX 1393 US 1395 Email: chase@labs.att.com