Internet DRAFT - draft-bierman-ncx-smi
draft-bierman-ncx-smi
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 <appinfo> 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 |
| <config> |
+- - - - - --+
|
+------------------------+--------------------+
V V V
+-------------+ +-----------+ +-----------+
| <candidate> | | <running> | | <startup> |
| config | ------> | config | ------> | config |
+-------------+ +-----------+ +-----------+
|
+-----------------------+----------------------+
V V V
+-------------+ +-----------+ +---------------+
| 'acme' | | 'ietf' | | 'enterpriseN' |
| owner | | owner | > | owner |
+-------------+ +-----------+ +---------------+
| | |
| | |
V V V
+-----------+ +-----------+ +---------+
| <foo> | | <netconf> | | <bar> |
| app hdr | | app hdr | | app hdr |
| node | | node | | node |
+-----------+ +-----------+ +---------+
|
+--------------------+---+
V V
+----------------+ +-----------+
| <eventStreams> | | <monitor> |
| 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 <running> 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 <running> configuration, even if it
is only used to support the <get> 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 <candidate>
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 <startup>
configuration, but it must be implemented exactly as defined in
RFC 4741. The standard <copy-config> 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 <startup> 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 <copy-config>
operation.
o The <candidate> configuration is a special (optional) conceptual
database containing all the pending modifications to the <running>
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
<commit> operation.
Bierman Expires February 2, 2008 [Page 13]
Internet-Draft NCX-SMI August 2007
o The <startup> 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 <copy-
config> operation by the manager is required to store the contents
of the <running> 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 <running>
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 | <rpc> request | NETCONF |
| Manager | ----------------------> | Agent |
| | | |
| schema | <rpc-reply> response | <running> |
| apps | <--------------------- | configs |
| databases | | apps |
| | <notification> 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 <schema> 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 <capability>
element within a NETCONF <hello> 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 <hello> 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 <commit> 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:
<!--
Type for 'foo' element, child of 'config' element
-->
<xs:complexType name="fooAppType">
<xs:complexContent>
<xs:extension base="nc:configInlineType">
<xs:sequence>
<xs:element ref="fooObject" minOccurs="0"
maxOccurs="unbounded"/>
Bierman Expires February 2, 2008 [Page 18]
Internet-Draft NCX-SMI August 2007
</xs:sequence>
</xs:extension>
</xs:complexContent>
</xs:complexType>
<!--
Type for abstract child of 'foo' element
-->
<xs:complexType name="fooObjectType">
<xs:complexContent>
<xs:extension base="fooAppType"/>
</xs:complexContent>
</xs:complexType>
<!--
Element for the 'foo' application header node element
-->
<xs:element name="foo" type="fooAppType" />
<!--
Element for abstract child of 'foo' element
-->
<xs:element name="fooObject" type="fooObjectType" abstract="true"/>
<!--
Type for a concrete object 'contact' for the 'foo' application
-->
<xs:complexType name="Contact">
<xs:complexContent>
<xs:extension base="fooObjectType">
<xs:sequence>
<xs:element name="name" type="xs:string"/>
<xs:element address"address" type="xs:string"/>
</xs:sequence>
</xs:extension>
</xs:complexContent>
</xs:complexType>
<!--
Element for a concrete object 'contact' for the 'foo' application
-->
<xs:element name="contact" type="Contact" />
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.
<config xmlns="NEXCONF-base">
<foo xmlns="foo-app-NS">
<contact>
<name>Fred Flintstone</name>
<address>17 Pebble Lane, Bedrock</address>
</contact>
</foo>
</config>
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 <running> 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 <running> 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 <filter> element
within the <get> or <get-config> operations.
When generating <copy-config> output, the <config> 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 <running>
to <startup>).
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 <get-config>
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 <get-config> 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 <get-config> 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 <unlock>
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
<running> 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 <rpc> element, and
all corresponding management responses are made using an <rpc-reply>
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 <rpc> and <rpc-reply> 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 <edit-config> 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 <notification> 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
<running> (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 <notification> 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 <startup>
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 <config>, in the NETCONF base
namespace.
The 'with-defaults='false' option produces the smallest possible
output for NV-storage (or <get-config> 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 <config>. 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'
<?xml version="1.0" encoding="UTF-8"?>
<config>
<nc-agent xmlns="http://example.com/xsd/nc-agent">
<nc-transport>
<bindings>
<binding>
<id>1</id>
<protocol>ssh</protocol>
<port>830</port>
</binding>
<binding>
<id>2</id>
<protocol>ssh</protocol>
<port>22</port>
</binding>
</bindings>
</nc-transport>
</nc-agent>
<security xmlns="http://example.com/xsd/security">
<ncx-access>
<mode>strict</mode>
<groups>
<group>
<name>control-staff</name>
<users>
<user>andy</user>
<user>fred</user>
</users>
</group>
<group>
<name>monitor-staff</name>
<users>
<user>wilma</user>
<user>barney</user>
Bierman Expires February 2, 2008 [Page 28]
Internet-Draft NCX-SMI August 2007
</users>
</group>
</groups>
<rpc-type-acls>
<rpc-type-acl>
<group>control-staff</group>
<rpc-types>config monitor debug exec other</rpc-types>
</rpc-type-acl>
<rpc-type-acl>
<group>monitor-staff</group>
<rpc-types>monitor debug</rpc-types>
</rpc-type-acl>
</rpc-type-acls>
</ncx-access>
</security>
</config>
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 <error-path:gt; elements or other data model content.
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
# Always use fixed root form for <error-path> 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 <config> 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 <error-path> 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 <rpc> element for NETCONF methods and data. This fixed root
form is used when a instance identifier is included in the <error-
path> 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 <config> or <data> or <filter>.
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 <error-path> elements must
identify the entire path, starting with the <rpc> 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 <error-path> element values within
the <rpc-error> field in NETCONF RPC replies. They (of course) can
also used as the value of the 'select' attribute in the <filter>
parameter for the NETCONF <get> 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 <edit-config>, <get-config>, or <get> 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
<hello> 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
<rpc> requests from the manager.
o The NETCONF protocol does not provide for any distinction between
sessions wrt/ use of the <kill-session> 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 <rpc> 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' <rpc-error> 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 <rpc-reply>
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 <notification> message
for a particular session is essentially the same as for the <data>
element within an <rpc-reply>, with one exception. Instead of
pruning data from the reply, as done for <get-config> or <get>
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 <rpc> 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 <hello> message once
during session establishment.
o The 'operation' attribute within the <config> element for the
<edit-config> 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:
<config xmlns="NETCONF-base">
<fooApp xmlns="fooAppNS">
<widgets>
<widget>
...
</widget>
<widget>
...
</widget>
<widget>
...
</widget>
</widgets>
</fooApp>
</config>
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 <running> and/or <startup> configuration is
modified by any mechanism, even if it is external to the NETCONF
protocol.
o When generating <copy-config> operation output, the same access
control procedures are applied as for the <edit-config>, as if the
manager was 'replacing' the entire contents of the <config>
element.
o The agent may provide a list of supported data models during the
<hello> 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
<rpc> 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 <get> operation, which indicates the data models and their
versions, to a manager.
o When closing a NETCONF session, a manager should always use the
<close-session> operation, if the agent should be accepting <rpc>
requests at the time.
o When closing a NETCONF session, and the agent is currently sending
notifications, a manager should always use the <kill-session>
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
<hello> 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 <hello>
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 <hello> 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 <rpc> 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]
