Internet Engineering Task Force A. Bierman Internet-Draft netconfcentral.org Intended status: Standards Track August 2007 Expires: February 2, 2008 Network Configuration Extensions : Structure of Management Information draft-bierman-ncx-smi-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 February 2, 2008. Copyright Notice Copyright (C) The IETF Trust (2007). Bierman Expires February 2, 2008 [Page 1] Internet-Draft NCX-SMI August 2007 Abstract The standardization of network configuration interfaces for use with the NETCONF protocol requires a structured data modeling environment which promotes human usability, multi-vendor interoperability, and reuse of existing IETF data models written in SMIv2. The Network Configuration Extensions (NCX) are a set of specifications intended to address NETCONF data modeling issues. This document defines a Structure of Management Information (SMI) suitable for use with the NETCONF protocol, intended to promote a more consistent, manageable, and interoperable infra-structure for ongoing development of NETCONF- based management interfaces. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4 1.1.1. Requirements Notation . . . . . . . . . . . . . . . . 4 1.1.2. NETCONF Terms . . . . . . . . . . . . . . . . . . . . 4 1.1.3. Terms . . . . . . . . . . . . . . . . . . . . . . . . 5 1.2. Problem Statement . . . . . . . . . . . . . . . . . . . . 6 1.3. Solution Requirements . . . . . . . . . . . . . . . . . . 9 2. NCX Framework . . . . . . . . . . . . . . . . . . . . . . . . 11 2.1. Framework Overview . . . . . . . . . . . . . . . . . . . . 11 2.2. Owners . . . . . . . . . . . . . . . . . . . . . . . . . . 15 2.3. Namespaces . . . . . . . . . . . . . . . . . . . . . . . . 15 2.3.1. Reserved Namespaces . . . . . . . . . . . . . . . . . 15 2.3.2. User-Defined Namespaces . . . . . . . . . . . . . . . 16 2.4. Capabilities . . . . . . . . . . . . . . . . . . . . . . . 16 2.5. Data Types . . . . . . . . . . . . . . . . . . . . . . . . 17 2.6. Applications . . . . . . . . . . . . . . . . . . . . . . . 17 2.6.1. Application Header Nodes . . . . . . . . . . . . . . . 18 2.6.2. Application Independent Definitions . . . . . . . . . 20 2.6.3. Application Specific Definitions . . . . . . . . . . . 20 2.7. Configuration Databases . . . . . . . . . . . . . . . . . 21 2.7.1. Configuration Root . . . . . . . . . . . . . . . . . . 21 2.7.2. Configuration Data Classification . . . . . . . . . . 22 2.7.3. Configuration Locking . . . . . . . . . . . . . . . . 22 2.8. RPC Methods . . . . . . . . . . . . . . . . . . . . . . . 23 2.8.1. RPC Classification . . . . . . . . . . . . . . . . . . 23 2.8.2. Reserved RPC Methods . . . . . . . . . . . . . . . . . 24 2.8.3. User-Defined RPC Methods . . . . . . . . . . . . . . . 25 2.9. Objects . . . . . . . . . . . . . . . . . . . . . . . . . 25 2.10. Notifications . . . . . . . . . . . . . . . . . . . . . . 26 2.10.1. Notification Event Classes . . . . . . . . . . . . . . 27 2.11. Non-Volatile Configuration Storage . . . . . . . . . . . . 27 Bierman Expires February 2, 2008 [Page 2] Internet-Draft NCX-SMI August 2007 3. NCX Naming Conventions . . . . . . . . . . . . . . . . . . . . 30 3.1. Names . . . . . . . . . . . . . . . . . . . . . . . . . . 30 3.2. Identifiers . . . . . . . . . . . . . . . . . . . . . . . 30 3.2.1. Definition Identifiers . . . . . . . . . . . . . . . . 31 3.2.2. Object Identifiers . . . . . . . . . . . . . . . . . . 31 3.2.3. Instance Identifiers . . . . . . . . . . . . . . . . . 33 4. NCX Agent Security Requirements . . . . . . . . . . . . . . . 37 4.1. Configuration Database Security . . . . . . . . . . . . . 37 4.2. NETCONF Session Security . . . . . . . . . . . . . . . . . 37 4.3. RPC Security . . . . . . . . . . . . . . . . . . . . . . . 38 4.4. Data Model Access Control . . . . . . . . . . . . . . . . 38 5. NETCONF Interoperability Guidelines . . . . . . . . . . . . . 40 5.1. NETCONF Protocol Operation Usage Guidelines . . . . . . . 40 5.2. Agent Conformance Requirements . . . . . . . . . . . . . . 42 5.3. Definition Change Control Guidelines . . . . . . . . . . . 42 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 45 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 46 7.1. Owner Registry . . . . . . . . . . . . . . . . . . . . . . 46 7.2. Application Header Node Registry . . . . . . . . . . . . . 47 7.3. Data Model Schema Location Registry . . . . . . . . . . . 47 8. Security Considerations . . . . . . . . . . . . . . . . . . . 48 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 49 9.1. Normative References . . . . . . . . . . . . . . . . . . . 49 9.2. Informative References . . . . . . . . . . . . . . . . . . 49 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 50 Intellectual Property and Copyright Statements . . . . . . . . . . 51 Bierman Expires February 2, 2008 [Page 3] Internet-Draft NCX-SMI August 2007 1. Introduction The standardization of network configuration interfaces for use with the NETCONF [RFC4741] protocol requires a structured data modeling environment which promotes human usability, multi-vendor interoperability, and reuse of existing IETF data models written in SMIv2 [RFC2578]. This document defines a Structure of Management Information suitable for use with the NETCONF protocol, in order to help promote a more consistent, manageable, and interoperable infra- structure for ongoing development of NETCONF-based management interfaces. The Network Configuration Protocol defines an XML-based protocol for managing network device configuration databases. However, there is no specifications for the inter-operable organization of a conceptual NETCONF configuration database, and precisely how the standard NETCONF protocol operations behave on the configuration database. This document discusses the following concepts: o NCX Framework o NCX Naming Conventions o NCX Agent Security Requirements o NETCONF Interoperability Guidelines 1.1. Terminology 1.1.1. Requirements Notation 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]. 1.1.2. NETCONF Terms The following terms are defined in RFC 4741 and are not redefined here: o agent o client o manager Bierman Expires February 2, 2008 [Page 4] Internet-Draft NCX-SMI August 2007 o operation o RPC o RPC method o server o session o user 1.1.3. Terms The following terms are used throughout this documentation: application: A set of functionally-related, owner-specific, conceptual data modeling interfaces. data model: Formal representation of the application and protocol specific components of a conceptual network management programmatic interface. data model module: Container of definitions pertaining to some portion of one or more data models. object: A definition within a data model module that represents conceptual management data, which can be accessed by a manager via a network management protocol. The data contained within an object should be functionally related in some manner. notification: A definition within a data model module that represents a conceptual notification message construct. method: A definition within a data model module that represents a conceptual remote procedure call (RPC) construct. owner: The naming authority for a data model definition. All owner names must be globally unique, maintained in a registry by IANA. All data model definition names within the scope of a single owner must be unique. NETCONF base: This term usually refers to the namespace URI value assigned to the NETCONF base schema in RFC 4741. It has also been used to refer to the core set of operations mandated by the advertisement of the capability URI for the NETCONF 'base', or the capability itself. Bierman Expires February 2, 2008 [Page 5] Internet-Draft NCX-SMI August 2007 NETCONF data model: The high-level organization and framework which encompasses all protocol operations, conceptual data definitions, and instances of those definitions. object identifier: A string which identifies a particular object. instance identifier: A string which identifies a particular instance of an object. 1.2. Problem Statement Network operators and network equipment (NE) software developers need a lot of expertise, and spend a lot of time, to configure, control, and monitor network devices. Network configuration has traditionally been very proprietary in nature, and based on screen-scraping Command Line Interface (CLI) commands that can be stored in a textual file. Configuration management is usually done manually, and is prone to human-introduced error. Often, scripts or applications which use the CLI as a programmatic interface are developed ad-hoc to automate and simplify some repetitive management tasks. Programmatic interfaces built on top of the CLI are insufficient for the following reasons: o CLI is proprietary, requiring extra effort by operators to learn and manage different CLIs for different equipment. o CLI lacks a formal description language to completely define all properties of the programmatic interface o CLI lacks any structured error responses, and very little information about specific errors is available to applications o CLI lacks any sort of formalized transaction mechanism, to safely lock, alter, and unlock configuration databases in a multi- application environment. NETCONF (by design) separates the application-specific content within a network management operation from the operation itself. There is currently no standard data model content defined for NETCONF. Since it uses XML encoding, any data modeling language that describe XML instance documents can be used to define management definitions for use with the NETCONF protocol. Typically, XML Schema Definition (XSD) is used to describe valid XML instance documents for a particular XML application. However, XSD is Bierman Expires February 2, 2008 [Page 6] Internet-Draft NCX-SMI August 2007 rather difficult for humans to work with efficiently. It is verbose and complex, difficult to read and write, but is still an excellent formal description mechanism for applications to use. Because XSD is so difficult for humans to understand and define without errors, moving from CLI to XML based configuration management is not that easy. An application cannot really use an XSD schema to manage a network device until the data model definitions accurately reflect the native programmatic interface available from the NETCONF agent. This 'human usability' problem is especially important in the area of network management because increased complexity increases the risk that something will break in an unexpected way. Network operators and protocol developers need to fully understand that the XML data model correctly reflects the normative specification found in text. This has proved difficult when using XSD to define the XML syntax. Just as important as the human usability problems is the fact that XSD is designed and intended for use as a generalized formal definition of the content of XML instance documents. XSD does not address network management problems that have long been recognized and partially solved: o extensible modularity o definition and module lifecycle o change control guidelines o user documentation o implementation conformance o maximum protocol access o integration with existing SNMP-based data structures o agent implementation conformance o conditional presence tests based on referential integrity or protocol functionality o user-defined RPC methods o user-defined notifications Bierman Expires February 2, 2008 [Page 7] Internet-Draft NCX-SMI August 2007 o protocol operation dependent schema o conditional definitions based on platform capabilities o data model conformance requirements Although it is possible to arbitrarily extend the element, this XSD mechanism is by definition non-standard, and 'off-the-shelf' XSD-based applications will not be able to do anything useful with information encoded in this manner. In addition to the many aspects of standards-based data model definition and maintenance that are not directly addressed by XSD. The NETCONF protocol uses data model schema differently, depending on the protocol operation mode. There are four different usage-based representations, which would each require its own XSD schema, that are conceptually and simultaneously supported by a NETCONF Data Model: full: Conceptualization of all objects and all possible instances. This is the canonical representation that is defined as the combined contents of all data model modules used within all managed systems. The data properties represent the syntax, semantics, and requirements of a data model, independent of all protocol operations. concise: Conceptualization of all object instances within a managed system. Only the writable object values which have actually been configured to non-default values by a management application are within this representation. This is also called the no-defaults representation. filter Conceptualization of all permutations of all valid subtree filter expressions which are possible for a particular object. An XSD would need to treat every element and every attribute as optional in order to support this representation. In addition, unknown namespaces, elements and attributes are not errors, but rather valid filter components which simply produce no matching output from the underlying data model instances within the agent. This is also called the subtree filter representation. edit-config Conceptualization of all permutations of all valid data model instances which are possible for a particular object, which permit the NETCONF edit-mode 'operation' attribute (for the edit- config protocol operation) to be present. An XSD would need to include this XML attribute in every XML element within the conceptual configuration data model to represent this mode. Bierman Expires February 2, 2008 [Page 8] Internet-Draft NCX-SMI August 2007 1.3. Solution Requirements There is a need for a comprehensive management framework for the NETCONF protocol which provides the following features: o An extensible and interoperable conceptual model of the correct behavior of a NETCONF agent must be defined. o A framework completely compatible with the multiple configuration database architecture defined in the NETCONF protocol. o A mechanism to classify objects wrt/ the NETCONF protocol operations (e.g., 'config' vs. 'state') must be supported. o A mechanism to identify session-specific and/or transient (i.e., not NV-stored) configuration data is needed. o Multiple owners must be able to define and maintain data model interfaces within a single management framework. o Support for user-defined RPC methods and notifications must be supported. o Data model lifecycle mechanisms to evolve management interfaces over time must be supported. o One set of data model naming conventions must be defined. o Mechanisms for modular data definitions (such as found in SMIv2) must be supported. o Mechanisms for arbitrarily complex indexed, tabular data, must be supported. o All data types found in XSD must be supported. o All data types found in SMIv2 must be supported. o The data naming scheme must be compatible with NETCONF Xpath filter 'select' and 'error-path' strings. o A conceptual framework for standardized, interoperable application of the NETCONF 'edit-config' protocol operation on arbitrary data models must be specified. o A conceptual framework for standardized, interoperable enforcement of user-configured access control mechanisms on arbitrary data models must be defined. Bierman Expires February 2, 2008 [Page 9] Internet-Draft NCX-SMI August 2007 o A conceptual framework for standardized, interoperable identification of NETCONF notification message content must be defined. o Mechanisms to reuse SMIv2-defined network management data and agent instrumentation must be defined. o Mechanisms to translate SMIv2 MIB object definitions into conceptual NETCONF MIB objects must be defined. o Mechanisms for augmentation of conceptual data structures must be provided, such that any owner can extend any object definition in a easy-to-use and interoperable manner. Bierman Expires February 2, 2008 [Page 10] Internet-Draft NCX-SMI August 2007 2. NCX Framework This section discusses the following concepts related to the NCX framework: o Owners o Namespaces o Capabilities o Data Types o Applications o Configuration Databases o RPC Methods o Objects o Notifications o Non-Volatile Configuration Storage o Agent Conformance Requirements o Definition Change Control Guidelines 2.1. Framework Overview The NCX framework imposes some clarifying language restrictions upon the XML usage within the contents of a configuration database. This is done to help promote a more consistent, manageable, and interoperable infra-structure for ongoing development of NETCONF- based management interfaces. Not every possible construct available in XML is utilized in the framework. Instead, a user-friendly, yet comprehensive subset of all well-formed XML is defined, providing data modeling constructs compatible with SMIv2, XSD, and XPath. The NCX framework is designed to be independent of the particular data modeling language one might use to describe schema for valid instances of the data model conceptual data structures. The XML structure itself is discussed instead. The basic data organization of the conceptual NETCONF MIB (as Bierman Expires February 2, 2008 [Page 11] Internet-Draft NCX-SMI August 2007 utilized within an NCX agent) is shown in the diagram below: NCX agent +------------+ | conceptual | | root | | | +- - - - - --+ | +------------------------+--------------------+ V V V +-------------+ +-----------+ +-----------+ | | | | | | | config | ------> | config | ------> | config | +-------------+ +-----------+ +-----------+ | +-----------------------+----------------------+ V V V +-------------+ +-----------+ +---------------+ | 'acme' | | 'ietf' | | 'enterpriseN' | | owner | | owner | > | owner | +-------------+ +-----------+ +---------------+ | | | | | | V V V +-----------+ +-----------+ +---------+ | | | | | | | app hdr | | app hdr | | app hdr | | node | | node | | node | +-----------+ +-----------+ +---------+ | +--------------------+---+ V V +----------------+ +-----------+ | | | | | data model | | data | | object | | model obj | +----------------+ +-----------+ | +------------------------+----------------------+ V V V {Additional layers, e.g., child nodes and nested objects) Figure 1 Bierman Expires February 2, 2008 [Page 12] Internet-Draft NCX-SMI August 2007 An NCX agent is a NETCONF agent that has the following properties: o An agent consists of one or more configuration databases, which can be accessed with the NETCONF protocol, and likely other protocols. o A configuration database is a conceptual construct. It must be administered as if there is only one of them. The contents of a configuration database be remain conceptually identical, regardless of the particular configuration database being used for any protocol operation. o The configuration is a special (mandatory) conceptual database containing all the current configuration and state parameters in affect at the moment. o An NCX agent must support the configuration, even if it is only used to support the operation. The responses for NETCONF retrieval operations must return data from this configuration database in XML encoding. o An NCX agent may optionally support the global configuration, but it must be implemented exactly as defined in RFC 4741. A separate capability and different configuration database must be defined if a different model is needed instead (e.g., multiple per-session candidate configurations). This configuration database must be encoded in XML. o An NCX agent may optionally support the global configuration, but it must be implemented exactly as defined in RFC 4741. The standard operation must be supported to update the contents of non-volatile storage, even if other mechanisms are made available as well. The '#distinct-startup' capability must be advertised in the capability list. o The actual output format of the configuration is not required to be XML, like the other configuration databases. An agent is not required to support any protocol operations for this database at all, except as the target of a operation. o The configuration is a special (optional) conceptual database containing all the pending modifications to the configuration database. It is part of the standard ':candidate' capability, which allows configuration changes to be gathered in multiple steps, and applied to the device all at once, using the operation. Bierman Expires February 2, 2008 [Page 13] Internet-Draft NCX-SMI August 2007 o The configuration is a special (optional) conceptual database containing all the configuration parameters which should be used upon the next reboot of the device. o If this configuration database is present, then an explicit operation by the manager is required to store the contents of the configuration database to non-volatile storage. o If this configuration database is not present, then the agent is responsible for keeping the contents of the configuration database in synch with non-volatile storage. o Each application header node contains zero or more data objects, which can use the syntax of any valid XML data type, and contain simple or complex content. The following diagram shows the basic conceptual system components and how they relate to each other within the context of the NETCONF protocol messages, or PDUs. The framework does not consider any additional management infra-structures which are not supported by the NETCONF protocol. For example, proxy, tiered, multi-manager-to- agent, and manager-to-multi-agent network management architectures are outside the scope of this document. +-----------+ +-----------+ | | | | | NETCONF | request | NETCONF | | Manager | ----------------------> | Agent | | | | | | schema | response | | | apps | <--------------------- | configs | | databases | | apps | | | message | objects | | | <--------------------- | methods | | | | events | +-----------+ +-----------+ Figure 2 Bierman Expires February 2, 2008 [Page 14] Internet-Draft NCX-SMI August 2007 2.2. Owners All NCX definitions are specified within the scope of one owner, indicated by a globally unique owner name string. It is expected that the IANA registration service will be used to maintain the registry owner name strings. Ownership of a data model definition implies publication and change control responsibility for the entire data model. It does not imply any restrictions on use or interoperability of XML instance documents utilizing those data model definitions, within a NETCONF session. There are two reserved owner string names at this time: ietf Owner of all standards-track, NETCONF-related protocol definitions, SMI definitions, and IETF defined textual conventions and data models. ncx Owner of the data definitions associated with NCX itself. There are also reserved owner name strings that correspond to Enterprise Identifiers in IANA, which are used in SMIv2 to provide a subtree within the entire MIB for vendor-specific definitions. The following URL identifies the Enterprise numbers already in use: http://www.iana.org/assignments/enterprise-numbers The special string 'enterprise' concatenated with the Enterprise Identifier value (with no leading zeros) is the default owner string for the organization that owns the specific Id assignment in IANA. For example, the owner string value 'enterprise9' would indicate Enterprise number nine, which is registered to 'ciscoSystems'. The owner name 'enterprise0' is reserved, and identifies the owner named 'ietf'. 2.3. Namespaces All definitions are specified within a particular XML Namespace. This is a globally unique URI string value. It is expected that a registration process such as IANA will be used to register namespace URI values and their meaning. 2.3.1. Reserved Namespaces There are three reserved namespace URI string values at this time. Bierman Expires February 2, 2008 [Page 15] Internet-Draft NCX-SMI August 2007 1. urn:ietf:params:xml:ns:netconf:base:1.0 2. http://www.w3.org/2000/xmlns 3. http://netconfcentral.org/ncx/1.0 2.3.2. User-Defined Namespaces It is expected that many additional namespaces will be defined as more data models are created. Some conventions to manage these namespace assignments are needed to encourage robust interoperable implementations. It is strongly suggested that namespace URIs do not contain module version information, which is likely to change several times over the lifetime of the module containing definitions within that namespace. Instead, the schema document file names, and or meta-data within the file itself should be used to identify the various versions (of the module) over time. If XSD is used to specify the schema, then the 'version' attribute within the element should be updated appropriately each time the published version of the document is changed. 2.4. Capabilities NETCONF capabilities are an important part of the NETCONF protocol. However, agent vendors should use this tool carefully. Capabilities should be used only as a last resort, or if the capability represents some physical aspect of the managed device (e.g., card type 'foo' is present). There are no restrictions on what can be advertised in a element within a NETCONF message. An agent must advertise a 'NETCONF base' capability for every version of the protocol it supports. An agent must support version 1.0, as specified in RFC 4741. An agent may choose to advertise the modules or namespaces or schema it supports in the message, but this must be done in a non- standard way at this time. By convention, a capability contains version information, since it is just a string, and cannot contain meta-data, such as a 'version' attribute. Bierman Expires February 2, 2008 [Page 16] Internet-Draft NCX-SMI August 2007 Capabilities cannot be changed once they are published. The 'contract' established by the defined agent behavior associated with the capability must never change. I different capability string must be used for each variant of the capability. Capability definitions must not contradict or negate any specified behavior in any other concurrently advertised capability definition. A capability may extend the behavior of another capability in some fashion, such as the '#confirmed-commit' capability which extends the behavior of the operation, which is defined by the '#candidate' capability. 2.5. Data Types Data type definitions are considered to be abstract constructs that cannot be accessed by any protocol mechanism. They are purely conceptual, like a TEXTUAL-CONVENTION macro in SMIv2. High level conceptual data types should be defined in a reusable manner whenever possible. All the conceptual base data types defines in XSD and SMIv2 should be supported by an agent, but the actual data models present will determine which data types are actually supported. 2.6. Applications All definitions are specified within the context of a particular NCX Application. This is owner-unique string value, which follows the NCX Name syntax and semantics. An application has significance within XML. Each application has its own namespace, and all accessible objects for the application are defined in this namespace. [A future version of NCX may allow unique namespace assignments for application-independent objects.] Protocol-accessible constructs (e.g., RPC methods, objects, and notifications) must be associated with a single application. Conceptually, NCX data type definitions do not need a namespace assignment, since only objects are accessible via protocol operations, but they are assigned one anyway for XSD translation purposes. The special application name types is used (by convention) in modules which contain only reusable data types and no accessible objects. Bierman Expires February 2, 2008 [Page 17] Internet-Draft NCX-SMI August 2007 Application names should be unique within the scope of a single owner, and must be unique within the scope of a single XML namespace. 2.6.1. Application Header Nodes An application header node is the top-level container for object instances, for a specific application. All application header nodes are child nodes of the conceptual configuration root. An application header node is a top-level element within the NETCONF MIB. It must be defined within a globally unique namespace. The name of the application must match the name of the element. There is a 1:1 static relationship between the namespace URI for an application header node and the element name. This node serves as the one and only 'root' for all data model objects defined within the application. This restriction makes it easier for humans to remember the MIB structure and make filtering simpler, especially subtree filtering, which cannot be used to discover the elements present in a single namespace. There are no restrictions on the namespaces used for objects (which are child nodes of the application header node). It is suggested that the application namespace be used if possible, to simplify namespace usage, but the selection of target namespace for a particular object is up to the data model publisher. Application header nodes should be defined with an XSD, in a manner that allows substitution group replacement and extensible addition of objects to the application over time. An application header node should be defined as an extension to the 'configInlineType', found in the XSD in RFC 4741. The following XSD fragment example shows how an application header node and an object within it could be defined using XSD: Bierman Expires February 2, 2008 [Page 18] Internet-Draft NCX-SMI August 2007 Figure 3 The following XML fragment example shows an instance document for the Bierman Expires February 2, 2008 [Page 19] Internet-Draft NCX-SMI August 2007 object and application from the previous example. Fred Flintstone
17 Pebble Lane, Bedrock
 Figure 4 2.6.2. Application Independent Definitions All conceptual data types are application-independent. They are considered to be abstractions, similar to a TEXTUAL-CONVENTION in SMIv2. Other definitions, such as owner names and namespace URIs, are also used independent of any particular application. 2.6.3. Application Specific Definitions XSD schema or NCX data model modules are used to specify management definitions for use with the NETCONF protocol. Mechanisms to specify the following constructs should be provided: o Configuration Database Data Objects o Event Notification Messages o RPC Method Definitions Every NCX module must represent definitions for exactly one owner. Any number of modules can be used to contain the definitions for an application, which all share the same owner-specific naming scope and application-specific XML namespace. Data type definitions are owner-specific, and can be used by any owner or any application. Bierman Expires February 2, 2008 [Page 20] Internet-Draft NCX-SMI August 2007 2.7. Configuration Databases A NETCONF configuration database is a conceptual collection of network management information, which can be manipulated and retrieved with standard protocol operations and user-defined operations. The configuration database is the central component of a NETCONF-managed agent. It is a mandatory database, which represents the current configuration and state of the entire managed device. All NCX configuration databases contain only applications and their associated objects, except the special configuration, which can contain configuration and other state-related data, such as statistics. Configuration databases are defined in detail in RFC 4741, and are used in NCX exactly as defined in that RFC, except that the conceptual database is considered to contain a collection of application header nodes, as supported by a particular agent. Each application node in turn will contain the modeling data associated with that application. An XML instance documentation or XML PDU representation of a configuration database must use a top-node element to contain all of the application header nodes. For example, the element within the or operations. When generating output, the element from the NETCONF base namespace should be used to contain all the application header nodes. 2.7.1. Configuration Root One of the basic components of the NCX Data Model is the concept of the configuration root. This is a conceptual container, which represents the root of all contents of a NETCONF configuration database. A configuration root is not bound to a specific configuration database. The contents (i.e., child nodes) can conceptually be copied or moved between configuration databases (e.g., copy to ). All configuration databases have a configuration root, represented in Xpath with the instance identifier value '/'; Bierman Expires February 2, 2008 [Page 21] Internet-Draft NCX-SMI August 2007 2.7.2. Configuration Data Classification All NCX data model content accessible via a protocol operation must specify a configuration data classification value, and conform to its particular semantics. There are three classifications defined at this time: config: All objects using the data type are considered to be configuration data, and will be affected by protocol operations which alter non-volatile configuration storage. Objects with this classification will be saved in non-volatile configuration storage, and also be returned when retrieved with the protocol operation. tconfig: All objects using the data type are considered to be transient configuration data, and will not be affected by protocol operations which alter non-volatile configuration storage. Objects with this classification will not be saved in non-volatile configuration storage, but will be returned when retrieved with the protocol operation. state: All objects using the data type are considered to be state data, and will not be affected by protocol operations which alter non-volatile configuration storage. Objects with this classification will not be saved in non-volatile configuration storage, and will not be returned (i.e., filtered-out) when retrieved with the protocol operation. 2.7.3. Configuration Locking NETCONF locking mechanisms provide a way to restrict write access to the specified configuration database to the NETCONF session that requested the lock. This lock will be in affect until the operation is invoked by the manager (on that session). A lock must be dropped if the session that hold the session is terminated, If an agent discovers an session in a non-recoverable error condition, it should immediately terminate that session and release any configuration locks it holds. All NCX agent implementations must support the global configuration database locking mechanism defined in the NETCONF protocol. An agent may optionally support a partial database locking capability, in which only a static subset of the entire database is Bierman Expires February 2, 2008 [Page 22] Internet-Draft NCX-SMI August 2007 locked. A global configuration lock must apply to all access to the database, nut just by the NETCONF protocol. The agent must use locking mechanisms outside the scope of this document to ensure this requirement is met. If a NETCONF-specific partial lock is held by a session, and external access mechanisms (e.g., SNMP protocol) cannot correctly lock the exact subset of data, then the agent must ensure that the database is globally locked wrt/ these external access mechanisms. A manager should lock the configuration databases within a session as short a time period as possible. An agent should support some form of configuration change event notification, if NETCONF Notifications are supported, and generate a configuration change event in a timely manner, when changes to the configuration are detected. The agent may choose not to generate more than one such event within a given time interval (e.g., 1 minute) in order to save system resources. 2.8. RPC Methods The top-level interface in NCX (and NETCONF) is the remote procedure call. All management requests are made using an element, and all corresponding management responses are made using an element, as defined in the NETCONF standard. 2.8.1. RPC Classification All RPC methods must be classified by the data model writer according to the main purpose of the RPC method. This is a general classification and is not intended to be used as a robust filtering mechanism. Instead, it is intended to provide a simple mandatory classification mechanism to help enforce access control rules during RPC method invocation. The following classifications are defined: other The RPC method is some unknown type, defined outside the scope of the NCX data model framework. config The RPC method is related to configuration management, and may modify and/or retrieve configuration database content in some manner. Bierman Expires February 2, 2008 [Page 23] Internet-Draft NCX-SMI August 2007 exec The RPC method is related to some sort of executable procedure, such as a ping operation. The operation should not modify any configuration databases. monitor The RPC method is related to some sort of monitoring procedure, such as statistics retrieval, or retrieval of configuration data. The operation must not modify any configuration databases. debug The RPC method is related to some sort of debugging procedure, and may enable, modify, or disable some sort of debugging or logging service on the agent. The operation must not modify any configuration databases. Combinations of these classification values are discouraged within a single RPC method. They are not supported within the NCX data model framework at this time. Data model designers should avoid changing the RPC method classification based on different values of RPC parameters, determined at RPC invocation time. 2.8.2. Reserved RPC Methods There are several standard RPC methods, owned by 'ietf', that are defined within the NETCONF protocol, The RPC classification for each operation is also shown: o get-config (monitor) o edit-config (config) o copy-config (config) o delete-config (config) o get (monitor) o lock (config) o unlock (config) o validate (monitor) o commit (config) o discard-changes (config) o close-session (exec) Bierman Expires February 2, 2008 [Page 24] Internet-Draft NCX-SMI August 2007 o kill-session (exec) o create-subscription (config) It is strongly suggested that these RPC method names never be used in user-defined data models, regardless of the namespace specified. 2.8.3. User-Defined RPC Methods User-defined RPC methods are associated with a specific namespace and application. Any number of input and output parameters can be specified, as long as the and elements conform to the definition in RFC 4741. All user-defined RPC methods must be appropriately classified somehow, such that the agent and manager can identify potential security risks resulting from side effects of an RPC method invocation. 2.9. Objects Objects are application-specific conceptual data structures located within a configuration database. They are similar to MIB objects in SNMP, and can be directly accessed or manipulated with standard or user-defined RPC methods. Every object has the following basic properties: namespace: An globally unique namespace assignment. This should not change over the lifetime of the object. identifier A globally unique identifier string associated with the object. It must be complete and unambiguous. semantics Each object has specific semantics associated with it, defined with some sort of data modeling language, such as XSD. syntax Each object has a specific syntax, which must be well-formed XML, must not contain any DTDs, and should not include any mixed- mode XML. The syntax is defined with a data modeling language such as XSD. An NCX agent must follow a more restrictive set of naming guidelines than XML permits. o Every object must be defined within a namespace. Bierman Expires February 2, 2008 [Page 25] Internet-Draft NCX-SMI August 2007 o Every object name within the same namespace must be unique, (as specified in XML). o Every object name for sibling child nodes of same application header node must be unique, regardless of the namespace used. o Every application header node name defined by the same owner must be unique, regardless of namespace used. Objects can be nested within other objects. There are some guidelines, but no strict rules, for placement of an object within the subtree of its application header node. A simple scalar object or complex, nested tabular object can be defined to be located as a direct child of the application header node. NETCONF protocol error processing is affected by the conceptual containment boundary implied by an object's contents. The object boundary represents the fate-sharing boundary for a single invocation of any configuration database edit operation. If the 'continue-on-error' option in the operation is used, then errors detected within the a particular conceptual object will not impact execution of the edit operation on other objects (if any). 2.10. Notifications The element is generated by a NETCONF agent if notification delivery is configured for a particular session. A notification message can contain an arbitrary amount of data from the (or other) configuration. There are no restrictions on the data placed within notification messages, however, care should be taken to secure the transfer of sensitive data. Every NCX notification has shares the same basic structure, and should support these basic properties: event type: The event type is a owner-unique name string (QName) used to identify a particular event notification message type. This string value is used to define the name of the child element of the element. The namespace for this element is specified by the data model writer, event class: Each event notification should be associated with one event classification type, defined in the next section. this functional classification can be used for filtering and access control purposes. Bierman Expires February 2, 2008 [Page 26] Internet-Draft NCX-SMI August 2007 event data: Each event notification may optionally include an arbitrary amount of XML-encoded data, within the XML element associated with the event type. Only complex data (i.e., no mixed mode data) should be included in this part of a notification message. Care must be taken to ensure that a notification which contains restricted data (for a particular session) not be delivered to that unauthorized session. 2.10.1. Notification Event Classes The event classification mechanism uses a set of generalized enumeration value to assist a manager configure filtering or access control mechanisms, to control the delivery of notifications to a NETCONF session. It is expected that the IETF will standardize specific values and semantics for this generalized classification string. At this time, the format of this string is limited to any valid UTF-8 string between 1 and 1024 characters in length. It is expected that vendors will develop additional, more complex, event classification mechanisms which could be used in addition to this mandatory but generalized event classification mechanism. 2.11. Non-Volatile Configuration Storage The data representation capabilities of every configuration database may not be the same within an agent. For example, it is not required in the NETCONF protocol to allow edit operations on the configuration. Some implementations store configurations in non- volatile memory in a different format than XML. This is a common practice an routers and switches. Although the NETCONF protocol does not prohibit alternate formats for configuration storage, it does not support it either. Therefore, the 'with-defaults' extension has been added to suppress the output of configuration data instances which contain the default value for that parameter. By default, an NCX configuration database is saved in XML format, using a top-level (root) element named , in the NETCONF base namespace. The 'with-defaults='false' option produces the smallest possible output for NV-storage (or retrieval), but assumes the default value will never change. Care must be taken by an agent, such that a newer software release does not change the default value defined for a particular configuration parameter. Bierman Expires February 2, 2008 [Page 27] Internet-Draft NCX-SMI August 2007 By default, configurations are saved as XML instance documents, in which the top-level element is called . The following example shows an XML configuration file. The XML directive on the first line should be present to identify the content and its encoding. The following example shows a top-level 'config' container with application header nodes for the 'nc-agent' and 'security', containing some data object values. The 'nc-agent' application shows an 'nc-transport' object configured, and the 'security' application contains an 'ncx-access' 1 ssh 830 2 ssh 22 strict control-staff andy fred monitor-staff wilma barney Bierman Expires February 2, 2008 [Page 28] Internet-Draft NCX-SMI August 2007 control-staff config monitor debug exec other monitor-staff monitor debug Figure 5 Bierman Expires February 2, 2008 [Page 29] Internet-Draft NCX-SMI August 2007 3. NCX Naming Conventions This section discusses the following concepts related to the NCX naming conventions: o Definition Identifiers o Object Identifiers o Instance Identifiers In NCX, a name is just a language token. There is no concept of uniqueness for a name. An Identifier is used to attach a name to a conceptual entity, and is required to be unique within the scope of the entire NETCONF MIB. 3.1. Names An NCX name has the following properties: o NCX name strings are fields used within identifiers in some fashion. o An NCX name string can be 1 to 1023 characters in length, but must not exceed 64 characters in length if SMIv2 compatibility is required. o All names are case-sensitive. o The first character must be a letter ('a'..'z' or 'A'..'Z') o The rest of the characters in an NCX name can be any of: * letter ('a'..'z' or 'A'..'Z') * number ('0'..'9') * underscore ('_') * dash ('-') 3.2. Identifiers There are three types of identifiers: Bierman Expires February 2, 2008 [Page 30] Internet-Draft NCX-SMI August 2007 Definition Identifier>: Used to identify an object definition within a schema module. Object Identifier: Used to identify conceptual object definitions. Instance Identifier Used to identify conceptual instances of an object. 3.2.1. Definition Identifiers A definition identifier is used within an data model module to reuse a pre-defined user type within other constructs, and to specify index clause components. Other uses are also possible as well. 3.2.2. Object Identifiers If an NCX object identifier is used within an XML instance document (e.g., NETCONF PDU), it is represented as an XPath Absolute Path Expression, which is used to specify a particular conceptual node within the NETCONF MIB. It is similar to an OBJECT IDENTIFIER in SMIv2. An object identifier (within a PDU) begins with a forward slash, and is followed by zero or more node identifiers. A node identifier consists of a node-name (Name or QName) followed by a forward-slash, except the last identifier, which contains just a node-name. Although the syntax for XPath allows any element name (Name) or qualified element name (QName), in practice, the element names are constrained by the NCX 'name' syntax. Whitespace is not allowed within an object identifier. The following ABNF defines the object identifier syntax, as it used within an XML instance document: ncx-obj-id = "/" [ncx-obj-id-nodes] ncx-obj-id-nodes = 0*(ncx-obj-id-namepair) name ncx-obj-id-namepair = name "/" name = Name / QName Figure 6 Bierman Expires February 2, 2008 [Page 31] Internet-Draft NCX-SMI August 2007 The following examples show some object identifiers that might appear in content # The default namespace is set to NETCONF Base # The NCX module named 'ifexamples.ncx' contains the # data model definition used in these examples http://www.netconfcentral.org/ncx/ncx-modules/ifexamples.ncx # The XSD corresponding to the NCX module is named 'ifexamples.xsd'. http://www.netconfcentral.org/ncx/xsd/ncx/ifexamples.xsd # 'itf' is the prefix for the 'ifdata' application namespace ID # an error-option is invalid or not supported /rpc/edit-config/error-option # a non-specific error occurred with the element /rpc/edit-config/config # reset-interface RPC operation /rpc/itf:reset-interface # name parameter for the reset-interface RPC operation /rpc/itf:reset-interface/name # reset-mode parameter for the reset-interface RPC operation /rpc/itf:reset-interface/reset-mode Figure 7 Bierman Expires February 2, 2008 [Page 32] Internet-Draft NCX-SMI August 2007 3.2.3. Instance Identifiers Instance identifiers are used to uniquely identify conceptual object instances. For purposes, it might also identify a particular node within the input parameter set for a specific RPC operation. An NCX instance identifier is represented with an Absolute Xpath Expression. The Xpath Specification defines the allowable syntax for a valid XPath expression. The NCX language imposes the following constraints and procedures for an NCX instance identifier: o An instance identifier must represent a single conceptual instance of a object. o An instance identifier (like an object identifier) can be namespace qualified by using a namespace prefix, previously defined within the XML instance document. o If no namespace prefix is encountered, starting after the first forward slash ('/'), then the current namespace in effect is used. If none, then the instance identifier is invalid. o If the namespace for the first node is valid, then that namespace remains in affect until explicitly changed. A subsequent node without a prefix is not assumed to be in the default namespace. o Instance identifiers have a common fixed root, i.e., starting with the element for NETCONF methods and data. This fixed root form is used when a instance identifier is included in the element within an RPC error response. o Instance identifiers for conceptual data within a configuration database can also be used, using a conceptual relative root for database. This is represented by the special Xpath expression '/'. Within an actual PDU, this relative root will actually be an RPC parameter node, such as or or . o There is no default namespace associated with the root, so it must be specified within the PDU with appropriate 'xmlns' directives, so the prefixes used within the Xpath expression can be resolved. o RPC methods are identified by their path from the absolute root. Instance identifiers used within elements must identify the entire path, starting with the element. Simple Instance Identifier Examples: Bierman Expires February 2, 2008 [Page 33] Internet-Draft NCX-SMI August 2007 # the entire set of interface entries /itf:ifdata/interfaces # interface for 'eth0', fixed root version /rpc/edit-config/config/itf:ifdata/interfaces/interface[name='eth0'] # interface for 'eth0', relative root version # relative root applies only to data object /itf:ifdata/interfaces/interface[name='eth0'] # ifMtu node for the 'eth0' interface, relative root version /itf:ifdata/interfaces/interface[name='eth0']/ifMtu Figure 8 The following assumptions are made regarding the NCX instance identifiers in the following examples: o An absolute Xpath expression containing sub-clauses for all relevant conceptual index (key) components represents an instance of conceptual data. o Index component expressions are simple equality expressions, concatenated to form a logical 'AND' expression, in which all the terms must be true for the expression to be true. o The order of components within a conceptual index is not significant within Xpath. o By convention, the leftmost index component is called the 'major' index. o By convention, Each 'minor' index in succession (if any) is listed left to right, after the major index, in the order the index is defined within the conceptual data model. Bierman Expires February 2, 2008 [Page 34] Internet-Draft NCX-SMI August 2007 # In this example, the data models for 'Parmset1' and 'Parmset2' # from the module 'test.ncx' are used. http://www.netconfcentral.org/ncx/ncx-modules/test.ncx # The XSD corresponding to the NCX module is named 'test.ncx'. http://www.netconfcentral.org/ncx/ncx-modules/test.ncx # The XSD corresponding to the NCX module is named 'test.xsd'. http://www.netconfcentral.org/xsd/ncx/test.xsd # The 'ts' prefix represents the namespace for the # 'test' application namespace. # All examples are shown in relative root form # row 'foo' of table in parm 'p1', defined in 'Container1' /ts:test/Parmset1/p1/testrow[str1='foo'] # 'name' field for row 'bar' in parm 'p5', defined in 'Table1' /ts:test/Parmset1/p5[str1='bar']/name # field 'y' of row '3' of 'childtable', within row 'bar' # in parm 'p5', defined in 'Table1' /ts:test/Parmset1/p5[str1='bar']/childtable[x=3]/y # entire row ('testing one two',-42) for parm 'p6' # defined in 'Table1a' /ts:test/Parmset2/p6[name='testing one two'][num=-42] # 'str1' field within row ('testing 3 4',27) of parm 'p2' # defined in 'Table1a' /ts:test/Parmset2/p6[name='testing 3 4'][num=27]/str1 # entire row ('fred', 'baz') for 'testrow', # within the 'testrows' container, # which is part of row (17) for parm 'p8' # defined in 'Table2' /ts:test/Parmset2/p8[x=17]/testrows/testrow[name='fred'][str1='baz'] # field 'bytes' within the row described above /ts:test/Parmset2/p8[x=2]/testrows/testrow[name='jo'][str1='baz']/bytes Figure 9 Instances of unnamed data (e.g. maxOccurs="unbounded" and no 'key' defined) are identified by their position, relative to other Bierman Expires February 2, 2008 [Page 35] Internet-Draft NCX-SMI August 2007 instances of the same element. The short form of the 'position()' function in Xpath (e.g., foo[3] for the third instance of the 'foo' element) is used to identify unnamed data instances in this case. The first occurrence of an unnamed instance is identified with the position value '1'. Unnamed instances are only identified by their integer position, and can only be accessed by this position within a configuration database. Named instances are only identified by their associated 'index' clause (i.e. key), and should not be accessed by their position instead of the defined key for the data structure. Instance identifiers are used as element values within the field in NETCONF RPC replies. They (of course) can also used as the value of the 'select' attribute in the parameter for the NETCONF operation. Bierman Expires February 2, 2008 [Page 36] Internet-Draft NCX-SMI August 2007 4. NCX Agent Security Requirements The security requirements for NCX pertain mostly to the content layer within the protocol stack. These are in addition to the security requirements for NETCONF agents defined in RFC 4741. There is a hard-wired set of resources that can be secured within a NETCONF agent. The lack of flexibility allows a very simple data model to be used to configure access control mechanisms on a device. 4.1. Configuration Database Security Operators and agent developers must take precautions to ensure that the contents of the configuration databases within an agent are not exposed inadvertently, or insecurely, via some protocol other than NETCONF. An agent must provide some distinction between a super-user account (e.g., 'root'), an administrator account (e.g., 'admin'), and optionally other types of login accounts. An agent should provide access control for every database that can be accessed with the , , or operations. 4.2. NETCONF Session Security The following requirements are defined for NCX agent session behavior: o An agent must allow NETCONF session establishment service for the mandatory transport, which is NETCONF over SSH, on port 830. o An agent must not allow session establishment if the 'netconf' subsystem is not used during SSH session establishment. o An agent may provide additional transport mappings as configured by the manager or hard-wired into the agent. o Once a session has been properly established, and the NETCONF exchange successfully completed, the agent may assume that the manager identity has been authenticated and access to the agent is authorized. The agent is in its idle mode, waiting for requests from the manager. o The NETCONF protocol does not provide for any distinction between sessions wrt/ use of the operation. An agent may choose not to allow a session associated with 'super-user' privileges not to be terminated by an 'administrator' or other Bierman Expires February 2, 2008 [Page 37] Internet-Draft NCX-SMI August 2007 type of login account. o Agent access rights are granted to a particular session, associated (during session establishment) with a 'group', identified by a name string. Membership to a group is outside the scope of this document, but user name strings should be supported, and address strings may be supported as well. A special group called 'root' is reserved and an agent should not redefine the default access rights associated with this group. 4.3. RPC Security The following requirements are defined for NCX RPC processing behavior: o When an request is received, and it has been validated as a well-formed message, the agent must determine if the associated group has permission to invoke the specified RPC method. o If the group has permission to invoke the RPC method, then the general protocol operation is checked further, if it accesses any part of a configuration database. Otherwise, the security check is complete for the RPC request, and it is processed by the agent. o If the RPC method accesses any configuration database, then the agent must verify that the group has the appropriate access rights to perform the requested operation. 4.4. Data Model Access Control Access rights are determined by the NETCONF protocol: o merge o replace o create o delete o read Data access is granted to a group within a particular session based on the maximum allowed access configured for the objects (and perhaps object instances). If the general operation type is permitted for the group, then the RPC method is processed by the agent. Otherwise an 'access-denied' is returned to the manager instead of processing the RPC request further. Bierman Expires February 2, 2008 [Page 38] Internet-Draft NCX-SMI August 2007 After the RPC method processing is complete, and an message is generated to be sent to the manager, the response should be checked for any unauthorized data within it. If the response contains any unauthorized data, then the agent must remove all of it before sending the reply. Agent security procedures for generating the message for a particular session is essentially the same as for the element within an , with one exception. Instead of pruning data from the reply, as done for or operation responses, the entire notification is dropped for that session. If an agent supports NETCONF notifications, it should generate some sort of a 'agent-shutdown' event all all active sessions, whenever it is resetting or shutting down in an anticipated fashion. If an agent supports NETCONF notifications, it may wish to generate some sort of a 'session-started' event whenever a new NETCONF session is activated. If an agent supports NETCONF notifications, it should generate some sort of a 'session-terminated' event whenever a session is terminated unexpectedly. If an agent supports NETCONF notifications, it may choose to generate some sort of a 'session-terminated' event whenever a session is terminated in normal protocol fashion. Bierman Expires February 2, 2008 [Page 39] Internet-Draft NCX-SMI August 2007 5. NETCONF Interoperability Guidelines This section addresses data modeling practices which are deemed to impact multi-vendor or even simple manager/agent interoperability. The following recommendations deal with NETCONF protocol usage and XML design considerations. 5.1. NETCONF Protocol Operation Usage Guidelines This section contains guidelines for defining data models for use with the NETCONF protocol, within the NCX framework: o All configuration data must be defined within the appropriate namespace, and all NETCONF protocol operations should use the correct namespace for each element in an request. o An agent may determine the correct namespace for a given element if none is provided, in a manner outside the scope of this document. However, this is not strictly correct XML usage. o A manager and agent should only send the message once during session establishment. o The 'operation' attribute within the element for the operation should only be used once within a given XML sub-tree. o A 'key' construct (e.g., INDEX clause in SMIv2) should be used for all data contained within a configuration. Unnamed data should not be used within the definition of objects. o XML attributes should only be used for meta-data. The 'operation' attribute (as defined in NETCONF) can only be applied to an XML subtree, not an individual XML attribute. o XML elements should be used for configuration data values. The 'operation' attribute can only be applied to an XML element or subtree. Agent-supplied XML attributes representing meta-data such as a 'last-changed' timestamp, cannot be defined other XML attributes. o Indexed data should be located within a container, especially if access is likely to be relevant for that data. Typically, a container only contains zero or more instances of the same child data object node. o This container convention allows for easier support for SMIv2 type of tabular data within a NETCONF configuration database. Bierman Expires February 2, 2008 [Page 40] Internet-Draft NCX-SMI August 2007 o The following example shows a container naming example: ... ... ... Figure 10 o The 'anyType' XSD data type should not be used within a NETCONF configuration database. If it is, then the edit-config sub- operations (e.g., create, merge) are not interoperable across agent implementations, if they appear within any of the child nodes of the node content. o If the agent supports the '#notification' capability, then it should generate some sort of 'configuration change' event notification when the and/or configuration is modified by any mechanism, even if it is external to the NETCONF protocol. o When generating operation output, the same access control procedures are applied as for the , as if the manager was 'replacing' the entire contents of the element. o The agent may provide a list of supported data models during the exchange. However, an operator should be aware that sensitive information may be revealed by including the list of supported data models within this message. There is no mandatory access control in effect until the session is ready to process requests. Bierman Expires February 2, 2008 [Page 41] Internet-Draft NCX-SMI August 2007 o The agent should provide a data model which can be retrieved with the operation, which indicates the data models and their versions, to a manager. o When closing a NETCONF session, a manager should always use the operation, if the agent should be accepting requests at the time. o When closing a NETCONF session, and the agent is currently sending notifications, a manager should always use the operation (from a different session). o A manager should avoid terminating a NETCONF session by simply closing the transport connection. o Exception might occur if the agent is not responding, or the agent is not sending well-formed XML, or if the manager receives a message from the agent that it does not understand or support. 5.2. Agent Conformance Requirements The following requirements apply to NETCONF capabilities: o An agent must implement all of the required functionality associated with a capability in order to advertise it in a message. o Capabilities must represent behavior which applies to the entire agent, not to some sub-agent or subset of the configuration database. o Capabilities values should not change dynamically during normal operation of the agent. o The capabilities returned by the agent in a message, should remain in effect for the lifetime of the session. If this is not possible, the agent should terminate the session instead of processing new requests for the session. [More requirements TBD.] 5.3. Definition Change Control Guidelines There are some guidelines for ensuring that different versions of the same object are backward-compatible across different versions of an agent implementation. Bierman Expires February 2, 2008 [Page 42] Internet-Draft NCX-SMI August 2007 The following types of definitions must never be changed, once they are published and implemented by the agent: o owner names o application header node names o XML element names o XML attribute names o object names o RPC method names o RPC method parameter names o notification event type names o Basic XML syntax of an object o Basic conceptual semantics of an object, RPC method or its existing parameters, or a notification. The following types of definitions should not be changed, once they are published and implemented by the agent: o data object default values o RPC method classification values o configuration object classification values o notification event classification values A data model (module) version identifier should be updated to a previously unused value whenever any part of it is modified by the data model publisher. Several type of data model extensions are permitted, except that the version identifier should be updated appropriately when the modified schema definition is published. o Add any new objects, RPC methods, and/or notifications. o Add new parameters to an RPC method. Bierman Expires February 2, 2008 [Page 43] Internet-Draft NCX-SMI August 2007 o Add new child nodes to objects. o Change, add, or remove a range definition. o Change, add, or remove a range definition, or other such data type restrictions. o Change, add, or remove the access control semantics for an object. o Change, add, or remove any data object content within an event notification message. Bierman Expires February 2, 2008 [Page 44] Internet-Draft NCX-SMI August 2007 6. Acknowledgements The author wishes to thank Keith McCloghrie for review comments and Martin Bjorklund for help on the Instance Identifier details. Bierman Expires February 2, 2008 [Page 45] Internet-Draft NCX-SMI August 2007 7. IANA Considerations There are three registries that need to be maintained by IANA to simplify XML usage within the NETCONF protocol. 1. owner strings 2. application header nodes 3. data model schema locations 7.1. Owner Registry A registry is needed for short name strings that uniquely identify an NCX owner name. Each owner string should be associated with the organization name and some contact information, similar to the Enterprise numbers registry. Each registry entry will include: o the owner name string o organization name o contact info o enterpriseN owner name (if any) The initial registry will contain an entry for the 'ietf' owner: Owner name: ietf Organization name: Internet Engineering Task Force Contact Info: (TBD) netconf@ops.ietf.org Enterprise ID: enterprise0 Figure 11 In addition to 'ietf', reserved entries for each Enterprise number are also implicitly defined. Therefore, no assignments of the form 'enterpriseN' are allowed, where N is any non-negative integer. [open issue: owner string format: US-ASCII or UTF-8?] Bierman Expires February 2, 2008 [Page 46] Internet-Draft NCX-SMI August 2007 [open issue: owner string length restrictions?] 7.2. Application Header Node Registry A registry is needed for the QName assignments (namespace URI and element name) for each application header node in the standard NETCONF MIB. It is also desirable for vendors to register their own application header nodes as needed. Each registry entry will include: o the owner name associated with the application o the application element name o the application element namespace URI o the URL for the schema containing the application element definition o A short description of the application purpose. The initial registry will be empty. 7.3. Data Model Schema Location Registry A registry is needed for information related to the various (standard or proprietary) data models potentially available for use with the NETCONF protocol. Each registry entry will include: o the owner name associated with the data model o the application name (if any) associated with the data model o the data model version string o the data model target namespace URI o the data model schema location URL o the data model top-level object element name(s) o A short description of the data model's purpose. The initial registry will be empty. Bierman Expires February 2, 2008 [Page 47] Internet-Draft NCX-SMI August 2007 8. Security Considerations This entire document discusses guidelines for organizing NETCONF configuration data, and improving NETCONF protocol operational security. Some NETCONF agent security and deployment guidelines are discussed as well. However, this document does not define any new protocol mechanisms or extensions. It does not contradict or alter any of the security requirements defined for NETCONF in RFC 4741. This document does not define any data models as well. [Real security considerations section TBD.] Bierman Expires February 2, 2008 [Page 48] Internet-Draft NCX-SMI August 2007 9. References 9.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC4741] Enns, R., "NETCONF Configuration Protocol", RFC 4741, December 2006. 9.2. Informative References [RFC2578] McCloghrie, K., Ed., Perkins, D., Ed., and J. Schoenwaelder, Ed., "Structure of Management Information Version 2 (SMIv2)", STD 58, RFC 2578, April 1999. Bierman Expires February 2, 2008 [Page 49] Internet-Draft NCX-SMI August 2007 Author's Address Andy Bierman netconfcentral.org Simi Valley, CA USA Email: ietf@andybierman.com Bierman Expires February 2, 2008 [Page 50] Internet-Draft NCX-SMI August 2007 Full Copyright Statement Copyright (C) The IETF Trust (2007). 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, THE IETF TRUST 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). Bierman Expires February 2, 2008 [Page 51]