diff options
Diffstat (limited to 'doc/rfc/rfc6470.txt')
| -rw-r--r-- | doc/rfc/rfc6470.txt | 843 |
1 files changed, 843 insertions, 0 deletions
diff --git a/doc/rfc/rfc6470.txt b/doc/rfc/rfc6470.txt new file mode 100644 index 0000000..40cd45b --- /dev/null +++ b/doc/rfc/rfc6470.txt @@ -0,0 +1,843 @@ + + + + + + +Internet Engineering Task Force (IETF) A. Bierman +Request for Comments: 6470 Brocade +Category: Standards Track February 2012 +ISSN: 2070-1721 + + + Network Configuration Protocol (NETCONF) Base Notifications + +Abstract + + The Network Configuration Protocol (NETCONF) provides mechanisms to + manipulate configuration datastores. However, client applications + often need to be aware of common events, such as a change in NETCONF + server capabilities, that may impact management applications. + Standard mechanisms are needed to support the monitoring of the base + system events within the NETCONF server. This document defines a + YANG module that allows a NETCONF client to receive notifications for + some common system events. + +Status of This Memo + + This is an Internet Standards Track document. + + This document is a product of the Internet Engineering Task Force + (IETF). It represents the consensus of the IETF community. It has + received public review and has been approved for publication by the + Internet Engineering Steering Group (IESG). Further information on + Internet Standards is available in Section 2 of RFC 5741. + + Information about the current status of this document, any errata, + and how to provide feedback on it may be obtained at + http://www.rfc-editor.org/info/rfc6470. + +Copyright Notice + + Copyright (c) 2012 IETF Trust and the persons identified as the + document authors. All rights reserved. + + This document is subject to BCP 78 and the IETF Trust's Legal + Provisions Relating to IETF Documents + (http://trustee.ietf.org/license-info) in effect on the date of + publication of this document. Please review these documents + carefully, as they describe your rights and restrictions with respect + to this document. Code Components extracted from this document must + include Simplified BSD License text as described in Section 4.e of + the Trust Legal Provisions and are provided without warranty as + described in the Simplified BSD License. + + + + +Bierman Standards Track [Page 1] + +RFC 6470 NETCONF Base Notifications February 2012 + + +Table of Contents + + 1. Introduction ....................................................2 + 1.1. Terminology ................................................2 + 2. YANG Module for NETCONF Base Notifications ......................3 + 2.1. Overview ...................................................3 + 2.2. Definitions ................................................4 + 3. IANA Considerations ............................................11 + 4. Security Considerations ........................................12 + 5. Acknowledgements ...............................................14 + 6. Normative References ...........................................14 + +1. Introduction + + The NETCONF protocol [RFC6241] provides mechanisms to manipulate + configuration datastores. However, client applications often need to + be aware of common events, such as a change in NETCONF server + capabilities, that may impact management applications. Standard + mechanisms are needed to support the monitoring of the base system + events within the NETCONF server. This document defines a YANG + module [RFC6020] that allows a NETCONF client to receive + notifications for some common system events. + +1.1. Terminology + + 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 [RFC2119]. + + The following terms are defined in [RFC6241]: + + o client + o datastore + o protocol operation + o server + + The following terms are defined in [RFC5277]: + + o event + o stream + o subscription + + The following term is defined in [RFC6020]: + + o data node + + + + + + +Bierman Standards Track [Page 2] + +RFC 6470 NETCONF Base Notifications February 2012 + + +2. YANG Module for NETCONF Base Notifications + +2.1. Overview + + The YANG module defined within this document specifies a small number + of event notification messages for use within the 'NETCONF' stream, + and accessible to clients via the subscription mechanism described in + [RFC5277]. This module imports data types from the 'ietf-netconf' + module defined in [RFC6241] and 'ietf-inet-types' module defined in + [RFC6021]. + + These notifications pertain to configuration and monitoring portions + of the managed system, not the entire system. A server MUST report + events that are directly related to the NETCONF protocol. A server + MAY report events for non-NETCONF management sessions, using the + 'session-id' value of zero. + + This module defines the following notifications for the 'NETCONF' + stream to notify a client application that the NETCONF server state + has changed: + + netconf-config-change: + Generated when the NETCONF server detects that the <running> or + <startup> configuration datastore has been changed by a management + session. The notification summarizes the edits that have been + detected. + + netconf-capability-change: + Generated when the NETCONF server detects that the server + capabilities have changed. Indicates which capabilities have been + added, deleted, and/or modified. The manner in which a server + capability is changed is outside the scope of this document. + + netconf-session-start: + Generated when a NETCONF server detects that a NETCONF session has + started. A server MAY generate this event for non-NETCONF + management sessions. Indicates the identity of the user that + started the session. + + netconf-session-end: + Generated when a NETCONF server detects that a NETCONF session has + terminated. A server MAY optionally generate this event for + non-NETCONF management sessions. Indicates the identity of the + user that owned the session, and why the session was terminated. + + + + + + + +Bierman Standards Track [Page 3] + +RFC 6470 NETCONF Base Notifications February 2012 + + + netconf-confirmed-commit: + Generated when a NETCONF server detects that a confirmed-commit + event has occurred. Indicates the event and the current state of + the confirmed-commit procedure in progress. + +2.2. Definitions + + <CODE BEGINS> file="ietf-netconf-notifications@2011-12-09.yang" + + module ietf-netconf-notifications { + + namespace + "urn:ietf:params:xml:ns:yang:ietf-netconf-notifications"; + + prefix ncn; + + import ietf-inet-types { prefix inet; } + import ietf-netconf { prefix nc; } + + organization + "IETF NETCONF (Network Configuration Protocol) Working Group"; + + contact + "WG Web: <http://tools.ietf.org/wg/netconf/> + WG List: <mailto:netconf@ietf.org> + + WG Chair: Bert Wijnen + <mailto:bertietf@bwijnen.net> + + WG Chair: Mehmet Ersue + <mailto:mehmet.ersue@nsn.com> + + Editor: Andy Bierman + <mailto:andy@netconfcentral.org>"; + + description + "This module defines a YANG data model for use with the + NETCONF protocol that allows the NETCONF client to + receive common NETCONF base event notifications. + + Copyright (c) 2012 IETF Trust and the persons identified as + the document authors. All rights reserved. + + Redistribution and use in source and binary forms, with or + without modification, is permitted pursuant to, and subject + to the license terms contained in, the Simplified BSD License + + + + + +Bierman Standards Track [Page 4] + +RFC 6470 NETCONF Base Notifications February 2012 + + + set forth in Section 4.c of the IETF Trust's Legal Provisions + Relating to IETF Documents + (http://trustee.ietf.org/license-info). + + This version of this YANG module is part of RFC 6470; see + the RFC itself for full legal notices."; + + revision "2012-02-06" { + description + "Initial version."; + reference + "RFC 6470: NETCONF Base Notifications"; + } + + grouping common-session-parms { + description + "Common session parameters to identify a + management session."; + + leaf username { + type string; + mandatory true; + description + "Name of the user for the session."; + } + + leaf session-id { + type nc:session-id-or-zero-type; + mandatory true; + description + "Identifier of the session. + A NETCONF session MUST be identified by a non-zero value. + A non-NETCONF session MAY be identified by the value zero."; + } + + leaf source-host { + type inet:ip-address; + description + "Address of the remote host for the session."; + } + } + + + + + + + + + + +Bierman Standards Track [Page 5] + +RFC 6470 NETCONF Base Notifications February 2012 + + + grouping changed-by-parms { + description + "Common parameters to identify the source + of a change event, such as a configuration + or capability change."; + + container changed-by { + description + "Indicates the source of the change. + If caused by internal action, then the + empty leaf 'server' will be present. + If caused by a management session, then + the name, remote host address, and session ID + of the session that made the change will be reported."; + choice server-or-user { + mandatory true; + leaf server { + type empty; + description + "If present, the change was caused + by the server."; + } + + case by-user { + uses common-session-parms; + } + } // choice server-or-user + } // container changed-by-parms + } + + + notification netconf-config-change { + description + "Generated when the NETCONF server detects that the + <running> or <startup> configuration datastore + has been changed by a management session. + The notification summarizes the edits that + have been detected. + + The server MAY choose to also generate this + notification while loading a datastore during the + boot process for the device."; + + uses changed-by-parms; + + + + + + + +Bierman Standards Track [Page 6] + +RFC 6470 NETCONF Base Notifications February 2012 + + + leaf datastore { + type enumeration { + enum running { + description "The <running> datastore has changed."; + } + enum startup { + description "The <startup> datastore has changed"; + } + } + default "running"; + description + "Indicates which configuration datastore has changed."; + } + + list edit { + description + "An edit record SHOULD be present for each distinct + edit operation that the server has detected on + the target datastore. This list MAY be omitted + if the detailed edit operations are not known. + The server MAY report entries in this list for + changes not made by a NETCONF session (e.g., CLI)."; + + leaf target { + type instance-identifier; + description + "Topmost node associated with the configuration change. + A server SHOULD set this object to the node within + the datastore that is being altered. A server MAY + set this object to one of the ancestors of the actual + node that was changed, or omit this object, if the + exact node is not known."; + } + + leaf operation { + type nc:edit-operation-type; + description + "Type of edit operation performed. + A server MUST set this object to the NETCONF edit + operation performed on the target datastore."; + } + } // list edit + } // notification netconf-config-change + + + + + + + + +Bierman Standards Track [Page 7] + +RFC 6470 NETCONF Base Notifications February 2012 + + + notification netconf-capability-change { + description + "Generated when the NETCONF server detects that + the server capabilities have changed. + Indicates which capabilities have been added, deleted, + and/or modified. The manner in which a server + capability is changed is outside the scope of this + document."; + + uses changed-by-parms; + + leaf-list added-capability { + type inet:uri; + description + "List of capabilities that have just been added."; + } + + leaf-list deleted-capability { + type inet:uri; + description + "List of capabilities that have just been deleted."; + } + + leaf-list modified-capability { + type inet:uri; + description + "List of capabilities that have just been modified. + A capability is considered to be modified if the + base URI for the capability has not changed, but + one or more of the parameters encoded at the end of + the capability URI have changed. + The new modified value of the complete URI is returned."; + } + } // notification netconf-capability-change + + + notification netconf-session-start { + description + "Generated when a NETCONF server detects that a + NETCONF session has started. A server MAY generate + this event for non-NETCONF management sessions. + Indicates the identity of the user that started + the session."; + uses common-session-parms; + } // notification netconf-session-start + + + + + + +Bierman Standards Track [Page 8] + +RFC 6470 NETCONF Base Notifications February 2012 + + + notification netconf-session-end { + description + "Generated when a NETCONF server detects that a + NETCONF session has terminated. + A server MAY optionally generate this event for + non-NETCONF management sessions. Indicates the + identity of the user that owned the session, + and why the session was terminated."; + + uses common-session-parms; + + leaf killed-by { + when "../termination-reason = 'killed'"; + type nc:session-id-type; + description + "The ID of the session that directly caused this session + to be abnormally terminated. If this session was abnormally + terminated by a non-NETCONF session unknown to the server, + then this leaf will not be present."; + } + + leaf termination-reason { + type enumeration { + enum "closed" { + description + "The session was terminated by the client in normal + fashion, e.g., by the NETCONF <close-session> + protocol operation."; + } + enum "killed" { + description + "The session was terminated in abnormal + fashion, e.g., by the NETCONF <kill-session> + protocol operation."; + } + enum "dropped" { + description + "The session was terminated because the transport layer + connection was unexpectedly closed."; + } + enum "timeout" { + description + "The session was terminated because of inactivity, + e.g., waiting for the <hello> message or <rpc> + messages."; + } + + + + + +Bierman Standards Track [Page 9] + +RFC 6470 NETCONF Base Notifications February 2012 + + + enum "bad-hello" { + description + "The client's <hello> message was invalid."; + } + enum "other" { + description + "The session was terminated for some other reason."; + } + } + mandatory true; + description + "Reason the session was terminated."; + } + } // notification netconf-session-end + + + notification netconf-confirmed-commit { + description + "Generated when a NETCONF server detects that a + confirmed-commit event has occurred. Indicates the event + and the current state of the confirmed-commit procedure + in progress."; + reference + "RFC 6241, Section 8.4"; + + uses common-session-parms { + when "../confirm-event != 'timeout'"; + } + + leaf confirm-event { + type enumeration { + enum "start" { + description + "The confirmed-commit procedure has started."; + } + enum "cancel" { + description + "The confirmed-commit procedure has been canceled, + e.g., due to the session being terminated, or an + explicit <cancel-commit> operation."; + } + enum "timeout" { + description + "The confirmed-commit procedure has been canceled + due to the confirm-timeout interval expiring. + The common session parameters will not be present + in this sub-mode."; + } + + + +Bierman Standards Track [Page 10] + +RFC 6470 NETCONF Base Notifications February 2012 + + + enum "extend" { + description + "The confirmed-commit timeout has been extended, + e.g., by a new <confirmed-commit> operation."; + } + enum "complete" { + description + "The confirmed-commit procedure has been completed."; + } + } + mandatory true; + description + "Indicates the event that caused the notification."; + } + + leaf timeout { + when + "../confirm-event = 'start' or ../confirm-event = 'extend'"; + type uint32; + units "seconds"; + description + "The configured timeout value if the event type + is 'start' or 'extend'. This value represents + the approximate number of seconds from the event + time when the 'timeout' event might occur."; + } + } // notification netconf-confirmed-commit + + } + + <CODE ENDS> + +3. IANA Considerations + + This document registers one XML namespace URN in the 'IETF XML + registry', following the format defined in [RFC3688]. + + URI: urn:ietf:params:xml:ns:yang:ietf-netconf-notifications + + Registrant Contact: The IESG. + + XML: N/A; the requested URI is an XML namespace. + + + + + + + + + +Bierman Standards Track [Page 11] + +RFC 6470 NETCONF Base Notifications February 2012 + + + This document registers one module name in the 'YANG Module Names' + registry, defined in [RFC6020]. + + name: ietf-netconf-notifications + prefix: ncn + namespace: urn:ietf:params:xml:ns:yang:ietf-netconf-notifications + RFC: 6470 + +4. Security Considerations + + The YANG module defined in this memo is designed to be accessed via + the NETCONF protocol [RFC6241]. The lowest NETCONF layer is the + secure transport layer and the mandatory-to-implement secure + transport is SSH, defined in [RFC6242]. + + Some of the readable data nodes in this YANG module may be considered + sensitive or vulnerable in some network environments. It is thus + important to control read access (e.g., via get, get-config, or + notification) to these data nodes. These are the subtrees and data + nodes and their sensitivity/vulnerability: + + /netconf-config-change: + Event type itself indicates that the system configuration has + changed. This event could alert an attacker that specific + configuration data nodes have been altered. + /netconf-config-change/changed-by: + Indicates whether the server or a specific user management session + made the configuration change. Identifies the user name, + session-id, and source host address associated with the + configuration change, if any. + /netconf-config-change/datastore: + Indicates which datastore has been changed. This data can be used + to determine if the non-volatile startup configuration data has + been changed. + /netconf-config-change/edit: + Identifies the specific edit operations and specific datastore + subtree(s) that have changed. This data could be used to + determine if specific server vulnerabilities may now be present. + + + + + + + + + + + + + +Bierman Standards Track [Page 12] + +RFC 6470 NETCONF Base Notifications February 2012 + + + /netconf-capability-change: + Event type itself indicates that the system capabilities have + changed, and may now be vulnerable to unspecified attacks. An + attacker will likely need to understand the content represented by + specific capability URI strings. For example, knowing that a + packet capture monitoring capability has been added to the system + might help an attacker identify the device for possible + unauthorized eavesdropping. + /netconf-capability-change/changed-by: + Indicates whether the server or a specific user management session + made the capability change. Identifies the user name, session-id, + and source host address associated with the capability change, if + any. + /netconf-capability-change/added-capability: + Indicates the specific capability URIs that have been added. This + data could be used to determine if specific server vulnerabilities + may now be present. + /netconf-capability-change/deleted-capability: + Indicates the specific capability URIs that have been deleted. + This data could be used to determine if specific server + vulnerabilities may now be present. + /netconf-capability-change/modified-capability: + Indicates the specific capability URIs that have been modified. + This data could be used to determine if specific server + vulnerabilities may now be present. + + /netconf-session-start: + Event type itself indicates that a NETCONF or other management + session may start altering the device configuration and/or state. + It may be possible for an attacker to alter the configuration by + somehow taking advantage of another session concurrently editing + an unlocked datastore. + /netconf-session-start/username: + Indicates the user name associated with the session. + /netconf-session-start/source-host: + Indicates the source host address associated with the session. + + /netconf-session-end: + Event type itself indicates that a NETCONF or other management + session may be finished altering the device configuration. This + event could alert an attacker that a datastore may have been + altered. + /netconf-session-end/username: + Indicates the user name associated with the session. + /netconf-session-end/source-host: + Indicates the source host address associated with the session. + + + + + +Bierman Standards Track [Page 13] + +RFC 6470 NETCONF Base Notifications February 2012 + + + /netconf-confirmed-commit: + Event type itself indicates that the <running> datastore may have + changed. This event could alert an attacker that the device + behavior has changed. + /netconf-confirmed-commit/username: + Indicates the user name associated with the session. + /netconf-confirmed-commit/source-host: + Indicates the source host address associated with the session. + /netconf-confirmed-commit/confirm-event: + Indicates the specific confirmed-commit state change that + occurred. A value of 'complete' probably indicates that the + <running> datastore has changed. + /netconf-confirmed-commit/timeout: + Indicates the number of seconds in the future when the <running> + datastore may change, due to the server reverting to an older + configuration. + +5. Acknowledgements + + Thanks to Martin Bjorklund, Juergen Schoenwaelder, Kent Watsen, and + many other members of the NETCONF WG for providing important input to + this document. + +6. Normative References + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, + January 2004. + + [RFC5277] Chisholm, S. and H. Trevino, "NETCONF Event + Notifications", RFC 5277, July 2008. + + [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for + the Network Configuration Protocol (NETCONF)", RFC 6020, + October 2010. + + [RFC6021] Schoenwaelder, J., Ed., "Common YANG Data Types", + RFC 6021, October 2010. + + [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., + and A. Bierman, Ed., "Network Configuration Protocol + (NETCONF)", RFC 6241, June 2011. + + [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure + Shell (SSH)", RFC 6242, June 2011. + + + + +Bierman Standards Track [Page 14] + +RFC 6470 NETCONF Base Notifications February 2012 + + +Author's Address + + Andy Bierman + Brocade + + EMail: andy@netconfcentral.org + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Bierman Standards Track [Page 15] + |