Netconf B. Lengyel Internet-Draft Ericsson Hungary Intended status: Standards Track October 13, 2006 Expires: April 16, 2007 Generic Action RPC for Netconf draft-lengyel-action-rpc-00 Status of this Memo By submitting this Internet-Draft, each author represents that any applicable patent or other IPR claims of which he or she is aware have been or will be disclosed, and any of which he or she becomes aware will be disclosed, in accordance with Section 6 of BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet- Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt. The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. This Internet-Draft will expire on April 16, 2007. Copyright Notice Copyright (C) The Internet Society (2006). Lengyel Expires April 16, 2007 [Page 1] Internet-Draft Generic Action RPC for Netconf October 2006 Abstract The NETCONF protocol defines a number of operations to read and write configuration data. However, it does not define actions on the managed nodes. Such actions are useful for 1) operations that do not change the configuration data (e.g. ping) 2) reading or writing a set of data that forms a logical group but might be scattered in different parts of the management data model. This document defines a new Netconf capability supporting a generic operation. A modeling view of how the content of the generic operation can be defined is also described. Please send comments to netconf@ops.ietf.org. To subscribe, use netconf-request@ops.ietf.org. Lengyel Expires April 16, 2007 [Page 2] Internet-Draft Generic Action RPC for Netconf October 2006 1. Introduction The document introduces the Generic Action Capability. 1.1. Definition of Terms The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119. Element: An XML Element[XML]. Managed Node: A network node, which supports NETCONF[1] and has access to management instrumentation. This is also known as the NETCONF server. Managed Object: A collection of one of more Elements that define an abstract thing of interest. Calling Point: A specific Managed Object in the hierarchical data model that is passed to the action as context information. Lengyel Expires April 16, 2007 [Page 3] Internet-Draft Generic Action RPC for Netconf October 2006 2. Generic Action Capability 2.1. Overview The NETCONF protocol defines a number of operations to read and write configuration data. However, it does not define actions on the managed nodes. Such actions are useful for 1) operations that do not change the configuration data (e.g. ping) 2) reading or writing a set of data that form a logical group but might be scattered in different parts of the management data model. There are two basic ways to define such actions: define each action as an individual new operation or define a generic action operation and define the details of the individual actions elsewhere. One obvious possibility is to define actions in the management data model. Using generic action operations is a valid solution that we believe will lead to simpler implementation and usage than defining actions as separate individual operations. Netconf RPCs will often be handled by a number of software entities before they reach their final destination, e.g. intermediate management software, software stacks from third party suppliers, interface handling software, access control enforcers etc. These entities and management software in general will be prepared for different data models but will often not be prepared for changes in the protocol itself: for new node specific action RPCs. New actions might need updates to these software entities. Using generic actions defined in the data model will make it possible to write generic management software like a MIB browser that can issue such actions and at least check their contents based on the data model (name of the action, number and type of the parameters). 2.1.1. Modeling There is a need to define what kind of generic actions can be used against a specific managed node. This definition will not be part of the protocol but should be part of the management data model of the node. This allows the node to specify during the initial capability exchange the information model and actions it supports. Many of the actions will be device/manufacturer specific just like the data model itself. It will be easy to handle the action definitions as it is generally accepted that the data model (or at least the non- standardized parts of it) will be different for different products. Lengyel Expires April 16, 2007 [Page 4] Internet-Draft Generic Action RPC for Netconf October 2006 2.1.1.1. Action Definition Each action will probably be defined in the data model. The exact form of this definition is outside the scope of this document. The following is recommended practice. Name (Mandatory): Each action must have a name to identify it. Calling-Point (Optional): A specific point in the hierarchical data model that is passed to the action as context information. Often actions will be called against a specific interface, virtual router, etc. In other cases there will not be such context, in which case the calling point might be omitted. Description (Mandatory): A description of the action. Parameters (Optional): All parameters included in an action should be defined. For each parameter the following data should be provided: Data type of the parameter Optional/Mandatory Default value Direction the parameter is sent: IN/OUT/INOUT. OUT and INOUT parameters will be returned in the response message. Error Results (mandatory if applicable): Possible error results including their format and what causes the error. This item might not be applicable if the action never produces error result. 2.2. Dependencies None. 2.3. Capability Identifier The generic-action capability is identified by the following capability string: urn:ietf:params:netconf:capability:generic-action:1.0 2.4. New Operations 2.4.1. Action The operation executes an action on the managed node. An action has a name, an optional calling point and a number of parameters included in the request. From the above data only the name element is mandatory. Optional data should be passed transparently to the Lengyel Expires April 16, 2007 [Page 5] Internet-Draft Generic Action RPC for Netconf October 2006 management entity connected to the netconf server. The following XML Schema defines the action operation: Schema defining the action operation. The filter must select one specific XML element. Subtree filter: Only a restricted subset of the subtree filter may be used. The subtree filter must select exactly one node based on the use of a content match node. For actions the content match node will select the parent node of the content match node. XPATH filter: Only a restricted subset of XPATH may be used. The location path must start from the root element, use only the child axis and include checks on key elements. Lengyel Expires April 16, 2007 [Page 6] Internet-Draft Generic Action RPC for Netconf October 2006 The following example action restarts virtual router "router1" immediately. restart /top/routing/virtual-router["routerName=router1"] immediately Positive Response: If the action is successful an is sent. In case the action doesn't return any parameters, the contains a single element. If there are any OUT or INOUT parameters, then an is sent containing a element. The data element will contain all OUT and INOUT parameter elements. Lengyel Expires April 16, 2007 [Page 7] Internet-Draft Generic Action RPC for Netconf October 2006 The following reply returns a boolean parameter "restart-successful" and an integer parameter 'run-level'.

true

Negative Response: In all cases, if an error occurs, an is sent that contains an element. 2.5. Modifications to Existing Operations None. 2.6. Interactions with Other Capabilities None. Lengyel Expires April 16, 2007 [Page 8] Internet-Draft Generic Action RPC for Netconf October 2006 3. Security Considerations The same considerations as for the base Netconf Protocol [1] are valid. It is assumed that actions are only allowed for an authenticated user after passing some access control mechanism. Lengyel Expires April 16, 2007 [Page 9] Internet-Draft Generic Action RPC for Netconf October 2006 4. IANA Considerations None (except maybe the capability's URI). Lengyel Expires April 16, 2007 [Page 10] Internet-Draft Generic Action RPC for Netconf October 2006 Appendix A. Change Log draft-00 Initial version Lengyel Expires April 16, 2007 [Page 11] Internet-Draft Generic Action RPC for Netconf October 2006 5. References [1] Enns, R., "NETCONF Configuration Protocol", draft-ietf-netconf-prot-12 (work in progress), March 2006. Lengyel Expires April 16, 2007 [Page 12] Internet-Draft Generic Action RPC for Netconf October 2006 Author's Address Balazs Lengyel Ericsson Hungary Phone: +36-1-4377320 Email: balazs.lengyel@ericsson.com Lengyel Expires April 16, 2007 [Page 13] Internet-Draft Generic Action RPC for Netconf October 2006 Full Copyright Statement Copyright (C) The Internet Society (2006). This document is subject to the rights, licenses and restrictions contained in BCP 78, and except as set forth therein, the authors retain all their rights. This document and the information contained herein are provided on an "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Intellectual Property The IETF takes no position regarding the validity or scope of any Intellectual Property Rights or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; nor does it represent that it has made any independent effort to identify any such rights. Information on the procedures with respect to rights in RFC documents can be found in BCP 78 and BCP 79. Copies of IPR disclosures made to the IETF Secretariat and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this specification can be obtained from the IETF on-line IPR repository at http://www.ietf.org/ipr. The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights that may cover technology that may be required to implement this standard. Please address the information to the IETF at ietf-ipr@ietf.org. Acknowledgment Funding for the RFC Editor function is provided by the IETF Administrative Support Activity (IASA). Lengyel Expires April 16, 2007 [Page 14]