idnits 2.17.1 draft-smith-opflex-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: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (November 10, 2014) is 3454 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) Summary: 2 errors (**), 0 flaws (~~), 1 warning (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Internet Engineering Task Force M. Smith 3 Internet-Draft R. Adams 4 Intended status: Informational M. Dvorkin 5 Expires: May 14, 2015 Cisco Systems, Inc. 6 Y. Laribi 7 Citrix 8 V. Pandey 9 IBM 10 P. Garg 11 Microsoft Corporation 12 N. Weidenbacher 13 Sungard Availability Services 14 November 10, 2014 16 OpFlex Control Protocol 17 draft-smith-opflex-01 19 Abstract 21 The OpFlex architecture provides a distributed control system based 22 on a declarative policy information model. The policies are defined 23 at a logically centralized policy repository (PR) and enforced within 24 a set of distributed policy elements (PE). The PR communicates with 25 the subordinate PEs using the OpFlex Control protocol. This protocol 26 allows for bidirectional communication of policy, events, statistics, 27 and faults. This document defines the OpFlex Control Protocol. 29 Status of This Memo 31 This Internet-Draft is submitted in full conformance with the 32 provisions of BCP 78 and BCP 79. 34 Internet-Drafts are working documents of the Internet Engineering 35 Task Force (IETF). Note that other groups may also distribute 36 working documents as Internet-Drafts. The list of current Internet- 37 Drafts is at http://datatracker.ietf.org/drafts/current/. 39 Internet-Drafts are draft documents valid for a maximum of six months 40 and may be updated, replaced, or obsoleted by other documents at any 41 time. It is inappropriate to use Internet-Drafts as reference 42 material or to cite them other than as "work in progress." 44 This Internet-Draft will expire on May 14, 2015. 46 Copyright Notice 48 Copyright (c) 2014 IETF Trust and the persons identified as the 49 document authors. All rights reserved. 51 This document is subject to BCP 78 and the IETF Trust's Legal 52 Provisions Relating to IETF Documents 53 (http://trustee.ietf.org/license-info) in effect on the date of 54 publication of this document. Please review these documents 55 carefully, as they describe your rights and restrictions with respect 56 to this document. Code Components extracted from this document must 57 include Simplified BSD License text as described in Section 4.e of 58 the Trust Legal Provisions and are provided without warranty as 59 described in the Simplified BSD License. 61 Table of Contents 63 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 64 1.1. Requirements Language . . . . . . . . . . . . . . . . . . 3 65 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 66 2. Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 67 3. System Overview . . . . . . . . . . . . . . . . . . . . . . . 4 68 3.1. Policy Repository . . . . . . . . . . . . . . . . . . . . 4 69 3.1.1. Management Information Model . . . . . . . . . . . . 4 70 3.1.1.1. Managed Object . . . . . . . . . . . . . . . . . 4 71 3.2. Endpoint Registry . . . . . . . . . . . . . . . . . . . . 5 72 3.3. Observer . . . . . . . . . . . . . . . . . . . . . . . . 5 73 3.4. Policy Element . . . . . . . . . . . . . . . . . . . . . 5 74 4. OpFlex Control Protocol . . . . . . . . . . . . . . . . . . . 6 75 4.1. JSON Usage . . . . . . . . . . . . . . . . . . . . . . . 6 76 4.2. RPC Methods . . . . . . . . . . . . . . . . . . . . . . . 8 77 4.2.1. Error Responses . . . . . . . . . . . . . . . . . . . 8 78 4.2.2. Identity . . . . . . . . . . . . . . . . . . . . . . 9 79 4.2.3. Echo . . . . . . . . . . . . . . . . . . . . . . . . 11 80 4.2.4. Policy Resolve . . . . . . . . . . . . . . . . . . . 11 81 4.2.5. Policy Unresolve . . . . . . . . . . . . . . . . . . 13 82 4.2.6. Policy Update . . . . . . . . . . . . . . . . . . . . 14 83 4.2.7. Endpoint Declare . . . . . . . . . . . . . . . . . . 15 84 4.2.8. Endpoint Undeclare . . . . . . . . . . . . . . . . . 16 85 4.2.9. Endpoint Resolve . . . . . . . . . . . . . . . . . . 17 86 4.2.10. Endpoint Unresolve . . . . . . . . . . . . . . . . . 18 87 4.2.11. Endpoint Update . . . . . . . . . . . . . . . . . . . 19 88 4.2.12. State Report . . . . . . . . . . . . . . . . . . . . 20 89 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 21 90 6. Security Considerations . . . . . . . . . . . . . . . . . . . 21 91 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 21 92 8. Normative References . . . . . . . . . . . . . . . . . . . . 21 93 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 22 95 1. Introduction 97 As software development processes merge with IT operations, there is 98 an increasing demand for automation and agility within the IT 99 infrastructure. Application deployment has been impeded due to the 100 existing IT infrastructure operational models. Management at scale 101 is a very difficult problem and existing imperative management models 102 typically falter when challenged with the heterogeneity of various 103 platforms, applications, and releases. In such environments, 104 declarative management models have shown to cope quite well. In 105 these systems, agents have autonomy of control and provide a 106 declaration of intent regarding behavior. Declarative policy is 107 rendered locally to provide desired system behavior. The OpFlex 108 architecture is founded in these concepts. 110 1.1. Requirements Language 112 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 113 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 114 document are to be interpreted as described in RFC 2119 [RFC2119]. 116 1.2. Terminology 118 PD: Policy Domain. A logical instantiation of the OpFlex 119 system components controlled by a single 120 administrative policy. 122 EP: Endpoint. A device connected to the system. 124 OC: OpFlex Component. An entity that communicates using 125 the OpFlex protocol. 127 EPR: Endpoint Registry. A logically centralized entity 128 containing the endpoint registrations within 129 associated policy domain. 131 OB: Observer. A logically centralized entity that serves 132 as a repository for statistics, faults, and events. 134 PE: Policy Element. A function associated with entities 135 comprising the policy policy domain that is 136 responsible for local rendering of policy. 138 PR: Policy Repository. A logically centralized entity 139 containing the definition of all policies governing 140 the behavior of the associated policy domain. 142 OpFlex Device: Entity under the management of a Policy Element. 144 JSON: Javascript Object Notation [RFC4627] 146 2. Scope 148 This document defines the OpFlex Control Protocol used between OpFlex 149 system components. It does not define the policy object model or the 150 policy object model schemas. A System Overview section is provided 151 for reference. 153 3. System Overview 155 OpFlex is a policy driven system used to control a large set of 156 physical and virtual devices. The OpFlex system architecture 157 consists of a number of logical components. These are the Policy 158 Repository (PR), Endpoint Registry (EPR), Observer, and the Policy 159 Elements (PE). These components and their interactions are described 160 in the following subsections. 162 3.1. Policy Repository 164 Within each policy domain of the OpFlex system, there is a single 165 logical entity referred to as the Policy Repository (PR) that serves 166 as the single source of all policies. The PR handles policy 167 resolution requests from the Policy Elements within the same policy 168 domain. An example scope of an policy domain would be a datacenter 169 fabric. These policies are configured directly by the user via a 170 policy administration interface (API/UI/CLI/etc.) or indirectly 171 (implicitly through the application of higher order policy 172 constructs). These policies represent a declarative statement of 173 desired state. Policies are typically abstracted from the underlying 174 implementation. 176 3.1.1. Management Information Model 178 All of the physical and logical components that comprise the policy 179 domain are represented in a hierarchical management information model 180 (MIM), also referred to as the management information tree (MIT). 181 The hierarchical structure starts at a root node and all policies 182 within the system can be reached via parent and child containment 183 relationships. Each node has a unique Uniform Resource Identifier 184 (URI) [RFC3986] that indicates its place in the tree. 186 3.1.1.1. Managed Object 188 Each node in the tree represents a managed object (MO) or group of 189 objects and contains its administrative state and operational state. 190 An MO can represent a concrete object, such as a switch or adapter, 191 or a logical object, such as a policy or fault. An MO consists of 192 the following items: 194 Properties: A property is a named instance of policy data and 195 is interpreted by the Policy Element in local 196 rendering of the policy. 198 Child Relations: A containment relationship between MOs where the 199 children MOs are contained within the parent MO. 201 Parent Relation: The inverse of the children relationship. This 202 relation is implicit and is implied through the 203 hierarchical name of the MO name. 205 Observables: These are MOs that track state relevant to the 206 observed MOs, such as statistics, faults, or health 207 information. These MOs are reported to the 208 Observer. 210 3.2. Endpoint Registry 212 The Endpoint Registry (EPR) is the component that stores the current 213 operational state of the endpoints (EP) within the system. PEs 214 register the EPs with the EPR upon EP attachment to the local device 215 where the PE is resident. Upon EP detachment, the registration will 216 be withdrawn. The EP registration information contains the scope of 217 the EP such as the Tenant or logical network as well as location 218 information such as the hypervisor where the EP resides, or other 219 metadata and labels as required by the policy model. The EPR can be 220 used by PEs to resolve the current EPR registrations as well as 221 receive updates when the information changes. 223 3.3. Observer 225 The Observer serves as the monitoring subsystem that provides a 226 detailed view of the system operational state and performance. It 227 serves as a data repository for performance and state data that 228 pertains to the devices under control. This could include 229 information related to trending, forensics, and long-term visibility 230 data such as statistics, events, and faults. Statistical data is 231 reported to the Observer at expiration of reporting intervals and 232 statistics will be rolled up for longer-term trend analysis. 234 3.4. Policy Element 236 Policy elements (PEs) are a policy enforcement entity that is part of 237 the policy domain. Policy elements reside on physical or virtual 238 devices that are subjected to policy control under a given policy 239 domain. In addition, a policy element might serve as a proxy for a 240 device that lacks an embedded policy element. Policies are resolved 241 with the PR using the OpFlex protocol. This protocol allows 242 bidirectional communication, and allows the exchange of policy 243 information. Policies are represented as managed object "sub-trees". 244 Upon policy resolution, the PE renders the policy to the 245 configuration of the underlying subsystem, and continuously performs 246 health monitoring of the subsystem. PEs perform local corrective 247 actions as needed for the enforcement of policies in its scope. The 248 PE performs this enforcement continuously rather than only when the 249 policy is changed, which is a departure from a more traditional 250 orchestrated scheme. Operational transitions can also cause new or 251 additional/incremental policy resolutions such as the attachment of 252 new EPs to the corresponding device. 254 4. OpFlex Control Protocol 256 The OpFlex Control Protocol is used by OpFlex system components to 257 communicate policy and operational data. This document describes a 258 JSON format and uses JSON-RPC version 1.0 [JSON-RPC]. The JSON-RPC 259 transport SHOULD be over TCP. 261 4.1. JSON Usage 263 The descriptions below use the following shorthand notations for JSON 264 values. Terminology follows [RFC4627]. 266 : 267 A JSON string. Any Unicode string is allowed. Implementations 268 SHOULD disallow null bytes. 270 : 271 A JSON number with an integer value, within the range - 272 (2**63)...+(2**63)-1. 274 : 275 Any JSON value. 277 : 278 Any JSON value except null. 280 : 281 A JSON string in the form of a Uniform Resource 282 Identifier[RFC3986]. 284 : 285 An enumeration specifying one of the following set of strings: 286 "created", "modified", or "deleted". 288 : 289 An enumeration specifying one of the following set of strings: 290 "policy_element", "observer", "policy_repository", or 291 "endpoint_registry". 293 : 294 A JSON object with the following members: 296 "subject": 297 "uri": 298 "properties": [{"name":, "data": }*] 299 "parent_subject": 300 "parent_uri": 301 "parent_relation": 302 "children": [*] 304 All of the members of the JSON object are REQUIRED. However, the 305 corresponding value MAY consist of the empty set for all members 306 except for "name". It is REQUIRED that the "name" be specified. 308 The "subject" provides the class of entity for which the 309 declaration applies. The applicable object classes are dependent 310 on the particular MIT. 312 The "uri" uniquely identifies the managed object within the scope 313 of the policy domain and indicates its location within the MIT. 315 The "properties" holds a set of named policy data. 317 The "parent_subject" provides the class of entity for the parent 318 of the managed object. This field is optional. If omitted, then 319 the managed object is a root element. 321 The "parent_uri" the uri of the parent managed object. The 322 parent URI MUST be a prefix of the URI of the child object. This 323 field is optional. If omitted, then the managed object is a root 324 element. 326 The "parent_relation" is the name of the relation from parent to 327 child. This field is optional. If omitted, the parent relation 328 is considered equal to the subject field. 330 The "children" identifies a set of MOs where each MO is 331 considered a child of this particular MO. 333 4.2. RPC Methods 335 The following subsections describe the RPC methods that are 336 supported. As described in the JSON-RPC 1.0 specification, each 337 request comprises a string containing the name of the method, a 338 (possibly null) array of parameters to pass to the method, and a 339 request ID, which can be used to match the response to the request. 340 Each response comprises a result object (non-null in the event of a 341 successful invocation), an error object (non-null in the event of an 342 error), and the ID of the matching request. More details on each 343 method, its parameters, and its results are described below. 345 A Policy Element is configured with the connectivity information of 346 at least one peer OpFlex Control Protocol participant. The 347 connectivity information consists of the information necessary to 348 establish the initial connection such as the IP address and wire 349 encapsulation. A Policy Element MAY be configured with the 350 connectivity information for one or more of the OpFlex logical 351 components. A Policy Element MUST connect to each of the configured 352 OpFlex logical components. 354 4.2.1. Error Responses 356 In the event of an error, the response contains an error object, and 357 the response object is null or omitted. The error response is as 358 follows: 360 { 361 "error": { 362 "code": , 363 "message": , 364 "trace": , 365 "data": 366 }, 367 "id": 368 } 370 The "code" parameter is an error code that indicates the type of 371 failure. The code MUST be one of the following strings: 373 "ERROR" 374 A generic error not covered by any of the following errors. 376 "EUNSUPPORTED" 377 The request could not be fulfilled because it is not supported. 379 "ESTATE" 380 The session is not in a state that allows the specified request. 382 "EPROTO" 383 The OpFlex protocol version is not supported. 385 "EDOMAIN" 386 The policy domains do not match. 388 An OpFlex component MUST be capable of receiving an error response 389 containing a code that is not in the above list, in which case it MAY 390 treat the code the same as "ERROR". 392 The "message" parameter is a human-readable error message that 393 corresponds to the error code. The message field is optional, but it 394 MAY contain additional details not conveyed by the code. 396 The "trace" parameter is a JSON object that MAY convey debug or trace 397 information, such as a stack trace, in an implementation-dependent 398 way. This parameter is optional. 400 The "data" parameter is a JSON object that can contain additional 401 data related to the specific request. This parameter MUST be present 402 if required by the request. 404 The "id" parameter is the same ID as was sent in the request. 406 4.2.2. Identity 408 This method identifies the participant to its peer in the protocol 409 exchange and MUST be sent as the first OpFlex protocol method. The 410 method indicates the transmitter's role and the policy domain to 411 which it belongs. Upon receiving an Identity message, the response 412 will contain the configured connectivity information that the 413 participant is using to communicate with each of the OpFlex 414 components. If the response receiver is a Policy Element and is not 415 configured with connectivity information for certain OpFlex logical 416 components, it SHOULD use the peer's connectivity information to 417 establish communication with the OpFlex logical components that have 418 not been locally configured. 420 If a request type other than Identity is received before the Identity 421 message, then the OpFlex Component MUST response with an error 422 response with the error code set to ESTATE. 424 The Identity request is as follows: 426 { 427 "method": "send_identity", 428 "params": [{ 429 "proto_version": "1.0", 430 "name": , 431 "domain": , 432 "my_role": [+] 433 }], 434 "id": 435 } 437 The "proto_version" is a string that represents the version of the 438 OpFlex protocol. This is the fixed value "1.0". 440 The "name" is an identifier of the OpFlex Control Protocol 441 participant that is unique within the policy domain. 443 The "domain" is a globally unique identifier indicating the policy 444 domain that this participant exists. 446 The "my_role" states the particular OpFlex component contained within 447 this participant. Since a participant may be capable of acting as 448 more than 1 type of component, there may be multiple "my_role" 449 parameters passed. 451 The response object is as follows: 453 { 454 "result": { 455 "name": , 456 "my_role": [+], 457 "domain": 458 [ {"role": , 459 "connectivity_info": }* ] 460 }, 461 "error": null, 462 "id": same "id" as request 463 } 465 The "name" is the identifier of the OpFlex Control Protocol 466 participant sending the response. 468 The "my_role" states the OpFlex component roles contained within the 469 participant sending the response. 471 The "domain" is a globally unique identifier indicating the policy 472 domain that the participant sending the response exists. 474 The "role" and associated "connectivity_info" give the reachability 475 information (i.e. IP address or DNS name) and the role of the entity 476 that the participant is communicating using the OpFlex Control 477 Protocol. This information MAY be gleaned by a receiving participant 478 to resolve reachability for various OpFlex components. 480 If the protocol version is not supported by the recipient of the 481 Identity request, then it MUST reply with an error response with the 482 "code" field set to "EPROTO". If the policy domain does not match 483 the policy domain of the recipient, then it MUST reply with an error 484 response with the "code" field set to "EDOMAIN". 486 4.2.3. Echo 488 The "echo" method can be used by OpFlex Control Protocol peers to 489 verify the liveness of a connection. It MUST be implemented by all 490 participants. 492 The request is as follows: 494 { 495 "method": "echo", 496 "params": [], 497 "id": 498 } 500 The response object is as follows: 502 { 503 "result": {}, 504 "id": same "id" as request 505 } 507 4.2.4. Policy Resolve 509 This method retrieves the policy associated with the given policy 510 name. The policy is returned as a set of managed objects. This 511 method is typically sent by the PE to the PR. 513 The request is as follows: 515 { 516 "method": "policy_resolve", 517 "params": [{ 518 "subject": , 519 "policy_uri": , 520 "policy_ident": { 521 "name": , 522 "context": 523 } 524 "data": , 525 "prr": 526 }*], 527 "id": 528 } 530 The "subject" provides the class of entity for which the policy is 531 being resolved. The applicable object classes are dependent on the 532 particular MIT. 534 The "policy_uri" is the URI of the policy that needs to be resolved. 535 Exactly one of "policy_uri" and "policy_ident" MUST be set. 537 The "policy_ident" is an identifier for the policy that needs to be 538 resolved. It contains a "context" which is a scope or namespace in 539 which the policy should be resolved, and a "name" which is a name 540 that uniquely identifies the policy within the context. A common 541 example of a context would be the URI of a tenant object. Exactly 542 one of "policy_uri" and "policy_ident" MUST be set. 544 The "data" provides additional opaque data that may be used to assist 545 in the policy resolution. This parameter is optional. 547 The "prr" or Policy Refresh Rate provides the amount of time that a 548 PE should use the policy as provided in the request. The 549 indicates the time in seconds that the policy should be kept by the 550 PE. A PE SHOULD issue another policy resolution request before the 551 expiration of the prr timer if the PE still requires the policy. If 552 the PE is unable to subsequently resolve the policy after the prr 553 timer expires, the PE MAY continue to use the resolved policy. The 554 PE SHOULD raise an alarm if the policy cannot be resolved after 555 multiple attempts. 557 Note that a policy resolve request can contain more than one request. 559 Upon successful policy resolution, the response object is as follows: 561 { 562 "result": { 563 "policy": [*], 564 }, 565 "id": same "id" as request 566 } 568 The "policy" parameter contains the managed objects that represent 569 the resolved policy. This includes the requested object and all of 570 its transitive children. These objects are used by the Policy 571 Element to render and apply the local policy. If the requested 572 policy is not currently known, then the policy response MAY be the 573 empty array. 575 When a policy resolution request is received by an OpFlex component, 576 it MAY reply with the requested policy in the response. It MAY also 577 reply with an empty response, and send the requested policy later 578 with a policy update. 580 If the requested policy or any of its children are modified, deleted, 581 or created, before the expiration of the PRR, the policy repository 582 MUST send a policy update that represents the policy modifications. 583 If the PRR expires before a new policy resolve message is received, 584 then the policy repository SHOULD stop sending the updates. Note 585 that these updates MUST be sent even if the requested policy is 586 unknown at the time of the resolve request. 588 4.2.5. Policy Unresolve 590 This method indicates that the policy element is no longer interested 591 in updates to a particular policy. Upon receipt of this message, the 592 policy repository SHOULD stop sending updates related to the 593 indicated policy object. 595 The request is as follows: 597 { 598 "method": "policy_unresolve", 599 "params": [{ 600 "subject": , 601 "policy_uri": , 602 "policy_ident": { 603 "name": , 604 "context": 605 }}* 606 ], 607 "id": 608 } 609 The "subject" provides the class of entity to which the request 610 applies. The applicable object classes are dependent on the 611 particular MIT. 613 The "policy_uri" is a URI to unresolve that corresponds to an earlier 614 resolve request. Exactly one of "policy_uri" and "policy_ident" MUST 615 be set for each unresolve request. 617 The "policy_ident" is an identifier to unresolve that corresponds to 618 an earlier resolve request. Note that a policy that was resolved 619 using the "policy_ident" field can only be unresolved in the same 620 way. Exactly one of "policy_uri" and "policy_ident" MUST be set for 621 each unresolve request. 623 Note that a policy that was resolved using the "policy_uri" or 624 "policy_ident" field can only be unresolved in the same way. If a 625 policy is resolved multiple times in different ways, then the policy 626 repository MUST continue to provide updates until all unique 627 resolutions are either unresolved or timed out. 629 Further note that a policy unresolve request can contain multiple 630 requests in the params list. 632 Upon successful completion, the response object is as follows: 634 { 635 "result": {}, 636 "id": same "id" as request 637 } 639 4.2.6. Policy Update 641 This method is sent to Policy Elements when there has been a change 642 of policy definition for policies for which the Policy Element has 643 requested resolution. Policy Updates will only be sent to Policy 644 Element for which the policy refresh rate timer has not expired. 646 The Policy Update contains the following members: 648 { 649 "method": "policy_update", 650 "params": [{ 651 "replace": [*], 652 "merge-children": [*], 653 "delete": [*], 654 }], 655 "id": 656 } 657 The "replace" parameter contains a list of changed managed objects. 658 These objects completely replace the managed objects specified. If 659 the existing object has any child elements that do not appear in the 660 specified object's child list, then these child elements MUST be 661 deleted. 663 The "merge-children" parameter contains a list of objects that will 664 replace the properties of any existing object, including unsetting 665 any properties that are set in the existing object but not set in the 666 specified object. Any children that are specified will added to the 667 set of children already present, but no children will be deleted. 669 The "delete" parameter specifies a list of URIs that reference 670 objects that no longer exist and should be deleted. 672 The response object is as follows: 674 { 675 "result": {}, 676 "id": same "id" as request 677 } 679 4.2.7. Endpoint Declare 681 This method is used to indicate the attachment or modification of an 682 endpoint. It is sent from the Policy Element to the Endpoint 683 Registry. 685 The request is as follows: 687 { 688 "method": "endpoint_declare", 689 "params": [{ 690 "endpoint": [+], 691 "prr": }+ 692 ], 693 "id": 694 } 696 The "endpoint" parameter is a list of managed objects representing 697 the endpoints to declare. The endpoint managed object will contain 698 one or more identifiers that can be used to look up the endpoint with 699 an endpoint resolve request. 701 The "prr" or Policy Refresh Rate provides provides the amount of time 702 that the endpoint declaration will remain valid. The 703 indicates the time in seconds that the endpoint declaration should be 704 kept by the EPR. A PE SHOULD issue another endpoint declaration 705 before the expiration of the prr timer if the endpoint is to continue 706 existing within the system. 708 Note that an endpoint declare request can contain more than one 709 endpoint declaration. 711 The response object is as follows: 713 { 714 "result": {}, 715 "id": same "id" as request 716 } 718 4.2.8. Endpoint Undeclare 720 This method is used to indicate the detachment of an endpoint. It is 721 sent from the Policy Element to the Endpoint Registry. 723 The request is as follows: 725 { 726 "method": "endpoint_undeclare", 727 "params": [{"subject": , 728 "endpoint_uri": }+ 729 ], 730 "id": 731 } 733 The "subject" provides the class of entity to which the declaration 734 applies. This will typically be the class representing the endpoint. 735 The applicable object classes are dependent on the particular MIT. 737 The "endpoint_uri" is used to identify the endpoint or endpoints that 738 are being detached. 740 Note that an endpoint undeclare request can contain more than one 741 endpoint undeclaration. 743 The response object is as follows: 745 { 746 "result": {}, 747 "id": same "id" as request 748 } 750 4.2.9. Endpoint Resolve 752 This method resolves the registration of a particular EP from the 753 EPR. The request is made using the identifiers of the endpoint. 754 Since multiple identifiers may be used to uniquely identify a 755 particular endpoint, there may be more than 1 endpoint returned in 756 the reply if the identifiers presented do not uniquely specify the 757 endpoint. 759 The request is as follows: 761 { 762 "method": "endpoint_resolve", 763 "params": [{ 764 "subject": , 765 "endpoint_uri": , 766 "endpoint_ident": { 767 "context": , 768 "identifier": 769 }, 770 "prr": }+ 771 ], 772 "id": 773 } 775 The "subject" provides the class of entity to which the request 776 applies. This will typically be the class representing the endpoint. 777 The applicable object classes are dependent on the particular MIT. 779 The "endpoint_uri" is the URI of the endpoint that needs to be 780 resolved. Exactly one of "endpoint_uri" and "endpoint_ident" MUST be 781 set. 783 The "endpoint_ident" is an identifier for the endpoint that needs to 784 be resolved. It contains a "context" which is a scope or namespace 785 in which the endpoint should be resolved, and a "identifier" which is 786 a name that uniquely identifies the endpoint within the context. A 787 common example of a context would be the URI of an IP namespace 788 object, and an within this namespace would be an IP address. Exactly 789 one of "endpoint_uri" and "endpoint_ident" MUST be set. 791 The "prr" or Policy Refresh Rate provides provides the amount of time 792 that the endpoint information will remain valid. The 793 indicates the time in seconds that the endpoint information should be 794 kept by the PE. A PE SHOULD issue another endpoint request before 795 the expiration of the prr timer if the communication is still 796 required with the endpoint. 798 Note that the endpoint resolve request can contain multiple endpoints 799 to resolve. 801 The response object contains the registrations of zero or more 802 endpoints. Each endpoint contains the same information that was 803 present in the original registration. The following members are 804 present in the response: 806 The response object is as follows: 808 { 809 "result": { 810 "endpoint": [*], 811 }, 812 "id": same "id" as request 813 } 815 The "endpoint" parameter contains the managed objects that represent 816 the endpoint registrations. This includes the requested object and 817 all of its transitive children. If the requested endpoint is not 818 currently known, then the policy response MAY be the empty array. 820 When an endpoint resolution request is received by an OpFlex 821 component, it MAY reply with the requested endpoint registration in 822 the response. It MAY also reply with an empty response, and send the 823 requested policy later with an endpoint update. 825 If the requested endpoint object or any of its children are modified 826 before the expiration of the PRR, the endpoint repository MUST send 827 an endpoint update that represents the endpoint modifications. If 828 the PRR expires before a new endpoint resolve message is received, 829 then the endpoint repository SHOULD stop sending the updates. Note 830 that these updates MUST be sent even if the requested endpoint is 831 unknown at the time of the resolve request. 833 4.2.10. Endpoint Unresolve 835 This method indicates that the policy element is no longer interested 836 in updates to a particular endpoint. Upon receipt of this message, 837 the policy repository SHOULD stop sending updates related to the 838 indicated policy object. 840 The request is as follows: 842 { 843 "method": "endpoint_unresolve", 844 "params": [{ 845 "subject": , 846 "endpoint_uri": , 847 "endpoint_ident": { 848 "context": , 849 "identifier": 850 }}+ 851 ], 852 "id": 853 } 855 The "subject" provides the class of entity for which the policy is 856 being resolved. The applicable object classes are dependent on the 857 particular MIT. 859 The "endpoint_uri" is a URI to unresolve that corresponds to an 860 earlier resolve request. Exactly one of "endpoint_uri" and 861 "endpoint_ident" MUST be set for each unresolve request. 863 The "endpoint_ident" is an identifier to unresolve that corresponds 864 to an earlier resolve request. Exactly one of "endpoint_uri" and 865 "endpoint_ident" MUST be set for each unresolve request. 867 Note that an endpoint that was resolved using the "endpoint_uri" or 868 "endpoint_ident" field can only be unresolved in the same way. If an 869 endpoint is resolved multiple times in different ways, then the 870 endpoint registry MUST continue to provide updates until all unique 871 resolutions are either unresolved or timed out. 873 Note that an endpoint unresolve request can can contain multiple 874 unresolve requests in the params list. 876 Upon successful completion, the response object is as follows: 878 { 879 "result": {}, 880 "id": same "id" as request 881 } 883 4.2.11. Endpoint Update 885 This method is sent to Policy Elements by the EPR when there has been 886 a change relating to the EP Declaration for an Endpoint that the 887 Policy Element has requested. Policy Updates will only be sent to 888 Policy Elements for which the Policy Refresh Rate timer timer for the 889 Endpoint Request has not expired. 891 The Endpoint Update contains the following members: 893 { 894 "method": "endpoint_update", 895 "params": [{ 896 "replace": [*], 897 "delete": [*], 898 }], 899 "id": 900 } 902 The "replace" parameter contains a list of changed managed objects. 903 These objects completely replace the managed objects specified. If 904 the existing object has any child elements that do not appear in the 905 specified object's child list, then these child elements MUST be 906 deleted. 908 The "delete" parameter specifies a list of URIs that reference 909 objects that no longer exist and should be deleted. 911 The response object is as follows: 913 { 914 "result": {}, 915 "id": same "id" as request 916 } 918 4.2.12. State Report 920 This method is sent by the Policy Element to the Observer. It 921 provides fault, event, statistics, and health information in the form 922 of managed objects. 924 The state report contains the following members: 926 { 927 "method": "state_report", 928 "params": [{ 929 "object": , 930 "observable": [*]}+ 931 ], 932 "id": 933 } 935 The "object" parameter is a URI that indicates the managed object to 936 which this state report applies. 938 The "observable" parameter is a list of managed objects that will be 939 updated in this state report. Each of these managed objects will 940 completely replace any existing observable managed object with the 941 same URI. 943 The response object is as follows: 945 { 946 "result": {}, 947 "id": same "id" as request 948 } 950 5. IANA Considerations 952 A TCP port will be requested from IANA for the OpFlex Control 953 Protocol. 955 6. Security Considerations 957 The OpFlex Control Protocol itself does not address authentication, 958 integrity, and privacy of the communication between the various 959 OpFlex components. In order to protect the communication, the OpFlex 960 Control Protocol SHOULD be secured using Transport Layer Security 961 (TLS) [RFC5246]. The distribution of credentials will vary depending 962 on the deployment. In some deployments, existing secure channels can 963 be used to distribute the credentials. 965 7. Acknowledgements 967 The authors would like to thank Vijay Chander, Mike Cohen, and Brad 968 McConnell for their comments and contributions. 970 8. Normative References 972 [JSON-RPC] 973 Kollhof, J., "JSON-RPC Specification, Version 1.0", 974 January 2006, . 976 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 977 Requirement Levels", BCP 14, RFC 2119, March 1997. 979 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 980 Resource Identifier (URI): Generic Syntax", STD 66, RFC 981 3986, January 2005. 983 [RFC4627] Crockford, D., "The application/json Media Type for 984 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 986 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 987 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 989 Authors' Addresses 991 Michael Smith 992 Cisco Systems, Inc. 993 170 West Tasman Drive 994 San Jose, California 95134 995 USA 997 Email: michsmit@cisco.com 999 Robert Edward Adams 1000 Cisco Systems, Inc. 1001 170 West Tasman Drive 1002 San Jose, California 95134 1003 USA 1005 Email: readams@readams.net 1007 Mike Dvorkin 1008 Cisco Systems, Inc. 1009 170 West Tasman Drive 1010 San Jose, California 95134 1011 USA 1013 Email: midvorki@cisco.com 1015 Youcef Laribi 1016 Citrix 1017 4988 Great America Parkway 1018 Santa Clara, California 95054 1019 USA 1021 Email: Youcef.Laribi@citrix.com 1023 Vijoy Pandey 1024 IBM 1025 4400 N First Street 1026 San Jose, California 95134 1027 USA 1029 Email: vijoy.pandey@us.ibm.com 1030 Pankaj Garg 1031 Microsoft Corporation 1032 1 Microsoft Way 1033 Redmond, Washington 98052 1034 USA 1036 Email: pankajg@microsoft.com 1038 Nik Weidenbacher 1039 Sungard Availability Services 1040 Philadelphia, Pennsylvania 1041 USA 1043 Email: nik.weidenbacher@sungard.com