idnits 2.17.1 draft-smith-opflex-03.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- 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 (April 25, 2016) is 2921 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: October 27, 2016 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 April 25, 2016 16 OpFlex Control Protocol 17 draft-smith-opflex-03 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 October 27, 2016. 46 Copyright Notice 48 Copyright (c) 2016 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 . . . . . . . . . . . . . . . . . . . 12 81 4.2.5. Policy Unresolve . . . . . . . . . . . . . . . . . . 14 82 4.2.6. Policy Update . . . . . . . . . . . . . . . . . . . . 15 83 4.2.7. Endpoint Declare . . . . . . . . . . . . . . . . . . 16 84 4.2.8. Endpoint Undeclare . . . . . . . . . . . . . . . . . 16 85 4.2.9. Endpoint Resolve . . . . . . . . . . . . . . . . . . 17 86 4.2.10. Endpoint Unresolve . . . . . . . . . . . . . . . . . 19 87 4.2.11. Endpoint Update . . . . . . . . . . . . . . . . . . . 20 88 4.2.12. State Report . . . . . . . . . . . . . . . . . . . . 21 89 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 22 90 6. Security Considerations . . . . . . . . . . . . . . . . . . . 22 91 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 22 92 8. Normative References . . . . . . . . . . . . . . . . . . . . 22 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 "ELOCATION" 389 An authoritative location is required but could not be 390 determined. 392 An OpFlex component MUST be capable of receiving an error response 393 containing a code that is not in the above list, in which case it MAY 394 treat the code the same as "ERROR". 396 The "message" parameter is a human-readable error message that 397 corresponds to the error code. The message field is optional, but it 398 MAY contain additional details not conveyed by the code. 400 The "trace" parameter is a JSON object that MAY convey debug or trace 401 information, such as a stack trace, in an implementation-dependent 402 way. This parameter is optional. 404 The "data" parameter is a JSON object that can contain additional 405 data related to the specific request. This parameter MUST be present 406 if required by the request. 408 The "id" parameter is the same ID as was sent in the request. 410 4.2.2. Identity 412 This method identifies the participant to its peer in the protocol 413 exchange and MUST be sent as the first OpFlex protocol method. The 414 method indicates the transmitter's role and the policy domain to 415 which it belongs. Upon receiving an Identity message, the response 416 will contain the configured connectivity information that the 417 participant is using to communicate with each of the OpFlex 418 components. If the response receiver is a Policy Element and is not 419 configured with connectivity information for certain OpFlex logical 420 components, it SHOULD use the peer's connectivity information to 421 establish communication with the OpFlex logical components that have 422 not been locally configured. 424 If a request type other than Identity is received before the Identity 425 message, then the OpFlex Component MUST response with an error 426 response with the error code set to ESTATE. 428 The Identity request is as follows: 430 { 431 "method": "send_identity", 432 "params": [{ 433 "proto_version": "1.0", 434 "name": , 435 "domain": , 436 "my_location": , 437 "my_role": [+] 438 }], 439 "id": 440 } 442 The "proto_version" is a string that represents the version of the 443 OpFlex protocol. This is the fixed value "1.0". 445 The "name" is an identifier of the OpFlex control protocol 446 participant that is unique within the policy domain. 448 The "domain" is a globally unique identifier indicating the policy 449 domain that this participant exists. 451 The "my_location" is an optional identifier that identifies the 452 location of the OpFlex control protocol participant that is making 453 the request. This is a string in a format appropriate for the 454 specific OpFlex policy domain. 456 The "my_role" states the particular OpFlex component contained within 457 this participant. Since a participant may be capable of acting as 458 more than 1 type of component, there may be multiple "my_role" 459 parameters passed. 461 The response object is as follows: 463 { 464 "result": { 465 "name": , 466 "my_role": [+], 467 "domain": , 468 "my_location": , 469 "your_location": , 470 "peers": 471 [ {"role": [+], 472 "connectivity_info": }* ] 473 }, 474 "id": same "id" as request 475 } 476 The "name" is the identifier of the OpFlex Control Protocol 477 participant sending the response. 479 The "my_role" states the OpFlex component roles contained within the 480 participant sending the response. 482 The "domain" is a globally unique identifier indicating the policy 483 domain that the participant sending the response exists. 485 The "my_location" is an optional identifier that identifies the 486 location of the OpFlex control protocol participant that is sending 487 the response. This is a string in a format appropriate for the 488 specific OpFlex policy domain. 490 The "your_location" is an optional identifier that identifies the 491 location of the OpFlex control protocol participant that sent the 492 request. This is a string in a format appropriate for the specific 493 OpFlex policy domain. If the requesting participant included a 494 "my_location" field in the request, this field MAY indicate a new, 495 authoritative location. 497 The "role" and associated "connectivity_info" give the reachability 498 information (i.e. IP address or DNS name) and the role of the entity 499 that the participant is communicating using the OpFlex Control 500 Protocol. This information MAY be gleaned by a receiving participant 501 to resolve reachability for various OpFlex components. 503 If the protocol version is not supported by the recipient of the 504 Identity request, then it MUST reply with an error response with the 505 "code" field set to "EPROTO". If the policy domain does not match 506 the policy domain of the recipient, then it MUST reply with an error 507 response with the "code" field set to "EDOMAIN". 509 If the requesting participant did not include a "my_location" field 510 in the request, and the responding participant is unable to determine 511 an authoritative location field for the requesting participant, the 512 responding participant MAY reply with an error response with the 513 "code" field set to "ELOCATION". 515 4.2.3. Echo 517 The "echo" method can be used by OpFlex Control Protocol peers to 518 verify the liveness of a connection. It MUST be implemented by all 519 participants. 521 The request is as follows: 523 { 524 "method": "echo", 525 "params": [], 526 "id": 527 } 529 The response object is as follows: 531 { 532 "result": {}, 533 "id": same "id" as request 534 } 536 4.2.4. Policy Resolve 538 This method retrieves the policy associated with the given policy 539 name. The policy is returned as a set of managed objects. This 540 method is typically sent by the PE to the PR. 542 The request is as follows: 544 { 545 "method": "policy_resolve", 546 "params": [{ 547 "subject": , 548 "policy_uri": , 549 "policy_ident": { 550 "name": , 551 "context": 552 } 553 "data": , 554 "prr": 555 }*], 556 "id": 557 } 559 The "subject" provides the class of entity for which the policy is 560 being resolved. The applicable object classes are dependent on the 561 particular MIT. 563 The "policy_uri" is the URI of the policy that needs to be resolved. 564 Exactly one of "policy_uri" and "policy_ident" MUST be set. 566 The "policy_ident" is an identifier for the policy that needs to be 567 resolved. It contains a "context" which is a scope or namespace in 568 which the policy should be resolved, and a "name" which is a name 569 that uniquely identifies the policy within the context. A common 570 example of a context would be the URI of a tenant object. Exactly 571 one of "policy_uri" and "policy_ident" MUST be set. 573 The "data" provides additional opaque data that may be used to assist 574 in the policy resolution. This parameter is optional. 576 The "prr" or Policy Refresh Rate provides the amount of time that a 577 PE should use the policy as provided in the request. The 578 indicates the time in seconds that the policy should be kept by the 579 PE. A PE SHOULD issue another policy resolution request before the 580 expiration of the prr timer if the PE still requires the policy. If 581 the PE is unable to subsequently resolve the policy after the prr 582 timer expires, the PE MAY continue to use the resolved policy. The 583 PE SHOULD raise an alarm if the policy cannot be resolved after 584 multiple attempts. 586 Note that a policy resolve request can contain more than one request. 588 Upon successful policy resolution, the response object is as follows: 590 { 591 "result": { 592 "policy": [*], 593 }, 594 "id": same "id" as request 595 } 597 The "policy" parameter contains the managed objects that represent 598 the resolved policy. This includes the requested object and all of 599 its transitive children. These objects are used by the Policy 600 Element to render and apply the local policy. If the requested 601 policy is not currently known, then the policy response MAY be the 602 empty array. 604 When a policy resolution request is received by an OpFlex component, 605 it MAY reply with the requested policy in the response. It MAY also 606 reply with an empty response, and send the requested policy later 607 with a policy update. 609 If the requested policy or any of its children are modified, deleted, 610 or created, before the expiration of the PRR, the policy repository 611 MUST send a policy update that represents the policy modifications. 612 If the PRR expires before a new policy resolve message is received, 613 then the policy repository SHOULD stop sending the updates. Note 614 that these updates MUST be sent even if the requested policy is 615 unknown at the time of the resolve request. 617 4.2.5. Policy Unresolve 619 This method indicates that the policy element is no longer interested 620 in updates to a particular policy. Upon receipt of this message, the 621 policy repository SHOULD stop sending updates related to the 622 indicated policy object. 624 The request is as follows: 626 { 627 "method": "policy_unresolve", 628 "params": [{ 629 "subject": , 630 "policy_uri": , 631 "policy_ident": { 632 "name": , 633 "context": 634 }}* 635 ], 636 "id": 637 } 639 The "subject" provides the class of entity to which the request 640 applies. The applicable object classes are dependent on the 641 particular MIT. 643 The "policy_uri" is a URI to unresolve that corresponds to an earlier 644 resolve request. Exactly one of "policy_uri" and "policy_ident" MUST 645 be set for each unresolve request. 647 The "policy_ident" is an identifier to unresolve that corresponds to 648 an earlier resolve request. Note that a policy that was resolved 649 using the "policy_ident" field can only be unresolved in the same 650 way. Exactly one of "policy_uri" and "policy_ident" MUST be set for 651 each unresolve request. 653 Note that a policy that was resolved using the "policy_uri" or 654 "policy_ident" field can only be unresolved in the same way. If a 655 policy is resolved multiple times in different ways, then the policy 656 repository MUST continue to provide updates until all unique 657 resolutions are either unresolved or timed out. 659 Further note that a policy unresolve request can contain multiple 660 requests in the params list. 662 Upon successful completion, the response object is as follows: 664 { 665 "result": {}, 666 "id": same "id" as request 667 } 669 4.2.6. Policy Update 671 This method is sent to Policy Elements when there has been a change 672 of policy definition for policies for which the Policy Element has 673 requested resolution. Policy Updates will only be sent to Policy 674 Element for which the policy refresh rate timer has not expired. 676 The Policy Update contains the following members: 678 { 679 "method": "policy_update", 680 "params": [{ 681 "replace": [*], 682 "merge_children": [*], 683 "delete": [{"subject": , 684 "uri": }*] 685 }], 686 "id": 687 } 689 The "replace" parameter contains a list of changed managed objects. 690 These objects completely replace the managed objects specified. If 691 the existing object has any child elements that do not appear in the 692 specified object's child list, then these child elements MUST be 693 deleted. 695 The "merge_children" parameter contains a list of objects that will 696 replace the properties of any existing object, including unsetting 697 any properties that are set in the existing object but not set in the 698 specified object. Any children that are specified will added to the 699 set of children already present, but no children will be deleted. 701 The "delete" parameter specifies a list of objects that no longer 702 exist and should be deleted. The "subject" field is the class of 703 entity to be deleted and the "uri" field is the URI for the specific 704 object to delete. 706 The response object is as follows: 708 { 709 "result": {}, 710 "id": same "id" as request 711 } 713 4.2.7. Endpoint Declare 715 This method is used to indicate the attachment or modification of an 716 endpoint. It is sent from the Policy Element to the Endpoint 717 Registry. 719 The request is as follows: 721 { 722 "method": "endpoint_declare", 723 "params": [{ 724 "endpoint": [+], 725 "prr": }+ 726 ], 727 "id": 728 } 730 The "endpoint" parameter is a list of managed objects representing 731 the endpoints to declare. The endpoint managed object will contain 732 one or more identifiers that can be used to look up the endpoint with 733 an endpoint resolve request. 735 The "prr" or Policy Refresh Rate provides provides the amount of time 736 that the endpoint declaration will remain valid. The 737 indicates the time in seconds that the endpoint declaration should be 738 kept by the EPR. A PE SHOULD issue another endpoint declaration 739 before the expiration of the prr timer if the endpoint is to continue 740 existing within the system. 742 Note that an endpoint declare request can contain more than one 743 endpoint declaration. 745 The response object is as follows: 747 { 748 "result": {}, 749 "id": same "id" as request 750 } 752 4.2.8. Endpoint Undeclare 754 This method is used to indicate the detachment of an endpoint. It is 755 sent from the Policy Element to the Endpoint Registry. 757 The request is as follows: 759 { 760 "method": "endpoint_undeclare", 761 "params": [{"subject": , 762 "endpoint_uri": }+ 763 ], 764 "id": 765 } 767 The "subject" provides the class of entity to which the declaration 768 applies. This will typically be the class representing the endpoint. 769 The applicable object classes are dependent on the particular MIT. 771 The "endpoint_uri" is used to identify the endpoint or endpoints that 772 are being detached. 774 Note that an endpoint undeclare request can contain more than one 775 endpoint undeclaration. 777 The response object is as follows: 779 { 780 "result": {}, 781 "id": same "id" as request 782 } 784 4.2.9. Endpoint Resolve 786 This method resolves the registration of a particular EP from the 787 EPR. The request is made using the identifiers of the endpoint. 788 Since multiple identifiers may be used to uniquely identify a 789 particular endpoint, there may be more than 1 endpoint returned in 790 the reply if the identifiers presented do not uniquely specify the 791 endpoint. 793 The request is as follows: 795 { 796 "method": "endpoint_resolve", 797 "params": [{ 798 "subject": , 799 "endpoint_uri": , 800 "endpoint_ident": { 801 "context": , 802 "identifier": 803 }, 804 "prr": }+ 805 ], 806 "id": 807 } 809 The "subject" provides the class of entity to which the request 810 applies. This will typically be the class representing the endpoint. 811 The applicable object classes are dependent on the particular MIT. 813 The "endpoint_uri" is the URI of the endpoint that needs to be 814 resolved. Exactly one of "endpoint_uri" and "endpoint_ident" MUST be 815 set. 817 The "endpoint_ident" is an identifier for the endpoint that needs to 818 be resolved. It contains a "context" which is a scope or namespace 819 in which the endpoint should be resolved, and a "identifier" which is 820 a name that uniquely identifies the endpoint within the context. A 821 common example of a context would be the URI of an IP namespace 822 object, and an within this namespace would be an IP address. Exactly 823 one of "endpoint_uri" and "endpoint_ident" MUST be set. 825 The "prr" or Policy Refresh Rate provides provides the amount of time 826 that the endpoint information will remain valid. The 827 indicates the time in seconds that the endpoint information should be 828 kept by the PE. A PE SHOULD issue another endpoint request before 829 the expiration of the prr timer if the communication is still 830 required with the endpoint. 832 Note that the endpoint resolve request can contain multiple endpoints 833 to resolve. 835 The response object contains the registrations of zero or more 836 endpoints. Each endpoint contains the same information that was 837 present in the original registration. The following members are 838 present in the response: 840 The response object is as follows: 842 { 843 "result": { 844 "endpoint": [*], 845 }, 846 "id": same "id" as request 847 } 849 The "endpoint" parameter contains the managed objects that represent 850 the endpoint registrations. This includes the requested object and 851 all of its transitive children. If the requested endpoint is not 852 currently known, then the policy response MAY be the empty array. 854 When an endpoint resolution request is received by an OpFlex 855 component, it MAY reply with the requested endpoint registration in 856 the response. It MAY also reply with an empty response, and send the 857 requested policy later with an endpoint update. 859 If the requested endpoint object or any of its children are modified 860 before the expiration of the PRR, the endpoint repository MUST send 861 an endpoint update that represents the endpoint modifications. If 862 the PRR expires before a new endpoint resolve message is received, 863 then the endpoint repository SHOULD stop sending the updates. Note 864 that these updates MUST be sent even if the requested endpoint is 865 unknown at the time of the resolve request. 867 4.2.10. Endpoint Unresolve 869 This method indicates that the policy element is no longer interested 870 in updates to a particular endpoint. Upon receipt of this message, 871 the policy repository SHOULD stop sending updates related to the 872 indicated policy object. 874 The request is as follows: 876 { 877 "method": "endpoint_unresolve", 878 "params": [{ 879 "subject": , 880 "endpoint_uri": , 881 "endpoint_ident": { 882 "context": , 883 "identifier": 884 }}+ 885 ], 886 "id": 887 } 888 The "subject" provides the class of entity for which the policy is 889 being resolved. The applicable object classes are dependent on the 890 particular MIT. 892 The "endpoint_uri" is a URI to unresolve that corresponds to an 893 earlier resolve request. Exactly one of "endpoint_uri" and 894 "endpoint_ident" MUST be set for each unresolve request. 896 The "endpoint_ident" is an identifier to unresolve that corresponds 897 to an earlier resolve request. Exactly one of "endpoint_uri" and 898 "endpoint_ident" MUST be set for each unresolve request. 900 Note that an endpoint that was resolved using the "endpoint_uri" or 901 "endpoint_ident" field can only be unresolved in the same way. If an 902 endpoint is resolved multiple times in different ways, then the 903 endpoint registry MUST continue to provide updates until all unique 904 resolutions are either unresolved or timed out. 906 Note that an endpoint unresolve request can can contain multiple 907 unresolve requests in the params list. 909 Upon successful completion, the response object is as follows: 911 { 912 "result": {}, 913 "id": same "id" as request 914 } 916 4.2.11. Endpoint Update 918 This method is sent to Policy Elements by the EPR when there has been 919 a change relating to the EP Declaration for an Endpoint that the 920 Policy Element has requested. Policy Updates will only be sent to 921 Policy Elements for which the Policy Refresh Rate timer timer for the 922 Endpoint Request has not expired. 924 The Endpoint Update contains the following members: 926 { 927 "method": "endpoint_update", 928 "params": [{ 929 "replace": [*], 930 "delete": [{"subject": , 931 "uri": }*] 932 }], 933 "id": 934 } 935 The "replace" parameter contains a list of changed managed objects. 936 These objects completely replace the managed objects specified. If 937 the existing object has any child elements that do not appear in the 938 specified object's child list, then these child elements MUST be 939 deleted. 941 The "delete" parameter specifies a list of objects that no longer 942 exist and should be deleted. The "subject" field is the class of 943 entity to be deleted and the "uri" field is the URI for the specific 944 object to delete. 946 The response object is as follows: 948 { 949 "result": {}, 950 "id": same "id" as request 951 } 953 4.2.12. State Report 955 This method is sent by the Policy Element to the Observer. It 956 provides fault, event, statistics, and health information in the form 957 of managed objects. 959 The state report contains the following members: 961 { 962 "method": "state_report", 963 "params": [{ 964 "observable": [*]}+ 965 ], 966 "id": 967 } 969 The "observable" parameter is a list of managed objects that will be 970 updated in this state report. Each of these managed objects will 971 completely replace any existing observable managed object with the 972 same URI. 974 The response object is as follows: 976 { 977 "result": {}, 978 "id": same "id" as request 979 } 981 5. IANA Considerations 983 A TCP port will be requested from IANA for the OpFlex Control 984 Protocol. 986 6. Security Considerations 988 The OpFlex Control Protocol itself does not address authentication, 989 integrity, and privacy of the communication between the various 990 OpFlex components. In order to protect the communication, the OpFlex 991 Control Protocol SHOULD be secured using Transport Layer Security 992 (TLS) [RFC5246]. The distribution of credentials will vary depending 993 on the deployment. In some deployments, existing secure channels can 994 be used to distribute the credentials. 996 7. Acknowledgements 998 The authors would like to thank Vijay Chander, Mike Cohen, and Brad 999 McConnell for their comments and contributions. 1001 8. Normative References 1003 [JSON-RPC] 1004 Kollhof, J., "JSON-RPC Specification, Version 1.0", 1005 January 2006, . 1007 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1008 Requirement Levels", BCP 14, RFC 2119, March 1997. 1010 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 1011 Resource Identifier (URI): Generic Syntax", STD 66, RFC 1012 3986, January 2005. 1014 [RFC4627] Crockford, D., "The application/json Media Type for 1015 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 1017 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1018 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 1020 Authors' Addresses 1022 Michael Smith 1023 Cisco Systems, Inc. 1024 170 West Tasman Drive 1025 San Jose, California 95134 1026 USA 1028 Email: michsmit@cisco.com 1029 Robert Edward Adams 1030 Cisco Systems, Inc. 1031 170 West Tasman Drive 1032 San Jose, California 95134 1033 USA 1035 Email: readams@readams.net 1037 Mike Dvorkin 1038 Cisco Systems, Inc. 1039 170 West Tasman Drive 1040 San Jose, California 95134 1041 USA 1043 Email: midvorki@cisco.com 1045 Youcef Laribi 1046 Citrix 1047 4988 Great America Parkway 1048 Santa Clara, California 95054 1049 USA 1051 Email: Youcef.Laribi@citrix.com 1053 Vijoy Pandey 1054 IBM 1055 4400 N First Street 1056 San Jose, California 95134 1057 USA 1059 Email: vijoy.pandey@us.ibm.com 1061 Pankaj Garg 1062 Microsoft Corporation 1063 1 Microsoft Way 1064 Redmond, Washington 98052 1065 USA 1067 Email: pankajg@microsoft.com 1068 Nik Weidenbacher 1069 Sungard Availability Services 1070 Philadelphia, Pennsylvania 1071 USA 1073 Email: nik.weidenbacher@sungard.com