| TOC |
|
This document extends the capabilities of the NETCONF configuration management protocol in order to standardize mechanisms to perform sets of active tests (i.e., verification) against servers' running configuration to afford the client and server a more robust and resilient configuration management capability. Specifically, this document defines a transaction test module based upon the defined set of Uniform Resource Locators. The transaction tests in this module are executed by the NETCONF verify operation.
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at http://datatracker.ietf.org/drafts/current/.
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.”
This Internet-Draft will expire on January 6, 2011.
Copyright (c) 2010 IETF Trust and the persons identified as the document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.
1.
Introduction
1.1.
Benefits of This Work
1.2.
Requirements Language
1.3.
Outline
2.
The Transation Test Module
2.1.
Verify Capability
2.2.
Transaction Test Module Construction and Use
3.
IANA Considerations
4.
Security Considerations
5.
References
5.1.
Normative References
5.2.
Informative References
Appendix A.
transaction.yang Module
§
Authors' Addresses
| TOC |
This document identifies enhancements to NETCONF capabilities to achieve a more robust model of configuration management for future IETF systems. Most network management systems which are required to provide a highly robust network service rely upon some form of out-of-band access for configuration management. This provides an alternative management entry into devices in the event that in-band access is unavailable due to, e.g., mis-configuration. However, not all network deployments can afford the luxury of alternative networks for management access to all networking devices, nor should this be necessary. Examples include Mobile Ad-Hoc Wireless Networks (MANETs) and other forms of Disruption Tolerant Networks (DTNs). All managed networks, as well, would benefit from a more robust and extensive configuration management capability from the IETF, e.g., to provide equivalent network reliability at reduced infrastructure costs. Towards this objective, we propose that the NETCONF protocol RFC 4741 (Enns, R., “NETCONF Configuration Protocol,” December 2006.) [RFC4741] requires extension of capabilities to define and manage active tests and assess success, i.e., Verification, (from both the client and the servers) involving server-side running configuration. This document augments the verify capability within NETCONF by defining a transaction test module. This allows the network management application to exercise the transaction tests through a standard mechanism. In this test module, the transactions are defined within the context of defined Uniform Resource Locators (URLs). This allows the network management application to exercise the transaction tests through an extensible mechanism.
As an example, we envision a NETCONF client-server interaction model shown in the below figure. Here, the client issues a <commit> with the confirming option. As part of testing prior to issuing the confirming <commit> the client wishes to execute a set of verification transaction tests from the server. It issues the <verify> operation to manage this aspect of verification transaction testing. The client passes a reference to the server indicating instances of specific pre-configured transaction tests within this module that define the specific test suite. The server executes these as part of the NETCONF <verify> testing process. Simultaneously, the client may also run a set of tests to gain confidence in the proposed configuration changes to the server. Once the server completes its test execution, it indicates success through notification messages. Once the client is comfortable with its own tests and those of the server, it issues the confirming <commit> to the server which forces the server to commit to the proposed configuration change; else the server backs out of the proposed configuration changes.
+------+ +------+
|Client| |Server|
+------+ +------+
+------------------------------>
Sets up <candidate> config
+------------------------------>
Sets up test control
--- +------------------------------>
| Sends <commit>
(set - timeout
timeout) - confirm option
|
|
| +------------------------------>
| Sends <verify>
| - timeout
| - test-template:instanceIDs
|
(running (running
client-side server-side tests)
tests) +--------+
| |
| |
| <--------+
| (server-side tests
| complete)
| <-----------------------------+
| <verifyComplete = ok> notification
|
|
| +----------------------------->
| Sends <commit>
|
|
---
| Figure 1 |
This, and other Use Cases, are discussed further in the document defining the verify operation VERIFY (Cole, R., Romascanu, D., and A. Bierman, “A Verification Procedure for Configuration Management within NETCONF,” July 2010.) [VERIFY] of NETCONF.
NETCONF defines the term 'validation' as the set of checks performed on proposed configuration code up to the point that the server places it into its running-configuration. We use the term 'verification' as the act of performing active tests against configuration code in the running-configuration on the server. Verification tests can be executed from either the NETCONF client or the NETCONF server, or from a NETCONF server(a) against running configuration code on a NETCONF server(b), or all combinations.
In this document, we define the transaction.yang module as a first example of a test module supporting the NETCONF verify operation. This allows for extensible verification testing of configuration across the base of IETF compliant devices. This leads to more resilient configuration management for operators manging multi-vendor networks of devices. This will promote future integrated network management capabilities as opposed to device management capabilities.
| TOC |
Our objective is to promote the development of a robust and resilient network configuration capability, building upon the improvements afforded by the NETCONF protocol and it's associated modeling language, YANG (Bjorklund, M., “YANG - A data modeling language for NETCONF,” June 2010.) [YANG].
The envisioned benefits of a standardized set of mechanisms and capabilities for verification testing include:
| TOC |
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 (Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” March 1997.) [RFC2119].
| TOC |
In the remainder of this document we present a description of the transaction.yang test module. This is followed with 'Acknowledgments' and 'IANA Considerations' sections. A section on 'Security Considerations' is provided concluding the main body of the document. In the appendix, i.e., 'Appendix A: transaction.yang', we define the transaction.yang module.
| TOC |
The transaction.yang module defines a set of transaction tests that can be instrumented via NETCONF and executed through the verify operation. We briefly discuss the verify operation in the context of executing the transaction tests. We then discuss the construction of the transaction.yang module. The definitive definition of the transaction.yang module is found in Appendix A of this document.
| TOC |
The verify operation, defined in VERIFY (Cole, R., Romascanu, D., and A. Bierman, “A Verification Procedure for Configuration Management within NETCONF,” July 2010.) [VERIFY], allows for the execution of verification tests within the NETCONF protocol. The construction of the verify operation is illustrated in the following diagram. Here a verify command is given with associated timeout and test-template parameters. The multiple test-template parameters each indicate a specific set of tests defined within the transaction.yang module resident on the server. The specific tests are pre-configured through standard NETCONF commands prior to issuing the verify operation. The definition of the verify operation allows various levels of reporting of the test results back to the NETCONF client.
<rpc xmlns="netconf-base" message-id="101">
<verify xmlns="verify-module">
<timeout>3600</timeout>
<test-template xmlns:as="transaction-module">
/tt:transaction/tt:controlTableEntry[tt:controlTableIndex=21]
/tt:transaction/tt:controlTableEntry[tt:controlTableIndex=42]
/tt:transaction/tt:controlTableEntry[tt:controlTableIndex=48]
</test-template>
<verifyStatus>true</verifyStatus>
<extendedStatus>false</extendedStatus>
</verify>
</rpc>
| Figure 2 |
| TOC |
The transaction.yang module is designed to support an extensible set of transaction test for the purpose of verification testing of proposed configuration changes. As such, we have modeled the module after the Uniform Resource Locator (URL) definition. The module is defined in six basic functions:
Refer to Appendix A for the definitive statement of the transaction.yang module.
| TOC |
This memo includes no request to IANA.
All drafts are required to have an IANA considerations section (see the update of RFC 2434 (Narten, T. and H. Alvestrand, “Guidelines for Writing an IANA Considerations Section in RFCs,” March 2008.) [I‑D.narten‑iana‑considerations‑rfc2434bis] for a guide). If the draft does not require IANA to do anything, the section contains an explicit statement that this is the case (as above). If there are no requirements for IANA, the section will be removed during conversion into an RFC by the RFC Editor.
| TOC |
This section presents the required security considerations for all IETF protocols and capabilities. This section was developed following guidelines within RFC 3552 (Rescorla, E. and B. Korver, “Guidelines for Writing RFC Text on Security Considerations,” July 2003.) [RFC3552].
This section addresses the security concerns and objectives for the for the use of the transaction.yang module within the context of the :verify capability in NETCONF. (NOTE: This section is currently TBD.)
Security issues related to the use of the transaction.yang module should address issues specific to the remote execution of verification tests. Here is an initial list of potential considerations:
| TOC |
| TOC |
| [RFC2119] | Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” BCP 14, RFC 2119, March 1997 (TXT, HTML, XML). |
| [RFC4741] | Enns, R., “NETCONF Configuration Protocol,” RFC 4741, December 2006 (TXT). |
| TOC |
| [I-D.narten-iana-considerations-rfc2434bis] | Narten, T. and H. Alvestrand, “Guidelines for Writing an IANA Considerations Section in RFCs,” draft-narten-iana-considerations-rfc2434bis-09 (work in progress), March 2008 (TXT). |
| [RFC3552] | Rescorla, E. and B. Korver, “Guidelines for Writing RFC Text on Security Considerations,” BCP 72, RFC 3552, July 2003 (TXT). |
| [VERIFY] | Cole, R., Romascanu, D., and A. Bierman, “A Verification Procedure for Configuration Management within NETCONF,” July 2010. |
| [YANG] | Bjorklund, M., “YANG - A data modeling language for NETCONF,” June 2010. |
| TOC |
In this appendix we define the transaction.yang model for use in conjunction with the robust-netconf capabilities.
=========Contents of "transaction.yang"============
module transaction {
namespace "unassigned";
prefix "tt";
import ietf-yang-types { prefix yang; }
import ietf-inet-types { prefix inet; }
organization "IETF";
contact
"Andy Bierman
InterWorking Labs
EMail: andyb@iwl.com
Robert G. Cole
US Army CERDEC
Space and Terrestrial Communications
Email: robert.g.cole@us.army.mil
Dan Romascanu
Avaya, Inc.
Email:dromasc@avaya.com";
description
"The module for entities implementing
the transaction test set in support
of the NETCONF verify capability.";
revision 2010-05-07 {
description "Zeroth revision:
Initial version of the transaction
testing module. This is modeled after
the draft ping.yang module from
draft-cole-netconf-verify-00.txt and
from the definition of Uniform Resource
Locators (URLs) [RFC 1738].
This module allows a management
agent to instrument and execute
a broad set of protocol transactions
in order to perform a broad range of
connectivity tests. These tests, executed
in conjunction with the NETCONF verify
operation, can be used to provide a
robust configuration change capability.
This capability is described in
draft-cole-netconf-verify-00.txt.";
}
---------------------------------------------------
---------------------------------------------------
-- The Protocol defines a set of protocol --
-- transactions supported by the device and --
-- are referenced through the 'scheme from --
-- IANA registered URLs. --
---------------------------------------------------
---------------------------------------------------
list transactionProtocolEntry {
key "transactionProtocolIndex";
config false;
leaf transactionProtocolIndex {
type uint32;
description
"Identifies a specific protocol
transaction supported by this device.
The transaction protocol is defined
in the definition of the 'scheme'
of the associated URL. These are
registered by IANA [RFC 4395].";
}
leaf transactionProtocolScheme {
type string;
description
"Identifies the specific protocol
scheme associated with this protocol
transaction, e.g., http, ftp, dns, sip, etc.,
supported by this device. The term
'scheme' is defined in the context of the
URL defintions in RFC [1738].";
}
leaf protocolReference {
type string;
config false;
description "URL for the definition of this
URL scheme. This could be a reference
to an RFC or to a publically
available reference.";
}
}
-- ends the transactionProtocolEntry list --
---------------------------------------------------
---------------------------------------------------
-- The Location Profile defines a set of URLs --
-- which are pre-defined in the server for the --
-- purpose of executing verification tests --
-- controlled by the NETCONF verify operation. --
---------------------------------------------------
---------------------------------------------------
list locationProfileEntry {
key "locationProfileIndex";
config true;
leaf locationProfileIndex {
type uint32;
description
"Identifies the specific URL to be
accessed by execution of the transaction
test.";
}
leaf locationProfileSchemeIndex {
type uint32;
description
"Contains the integer referencing the
transactionProtocolIndex in the capabilities
set found in the transactionProtocolEntry
in this module.";
}
leaf locationProfileUser {
type string;
description
"The username associated with the URL
defined within this locationProfileEntry.
Some URLs do not allow user entries, in which
case this string should be NULL.";
}
leaf locationProfilePassword {
type string;
description
"The password associated with the URL
defined within this loactionProfileEntry.
If the specific scheme associated with
this URL does not allow user and password,
then this string should be set to NULL.";
}
leaf locationProfileHost {
type string;
description
"The fully qualified domain name of a
network host, or its IPv4 or IPv6
address.";
}
leaf locationProfilePort {
type uint32;
description
"The port number with which to connect.
Most schemes designate protocols that
have a default port number. If this
is set to NULL, then the default port
number is to be used. Else another
port number may be supplied here.";
}
leaf locationProfilePath {
type string;
description
"The reaming parts of the URL necessary
to completely define the desired
transaction.";
}
}
-- ends the locationProfileEntry --
---------------------------------------------------
---------------------------------------------------
-- The Network Profile defines a set of --
-- reuseable network layer parameters to fully --
-- define the transaction test ultimately --
-- defined in the Test Control. --
---------------------------------------------------
---------------------------------------------------
list networkProfileEntry {
key "networkProfileIndex";
config true;
leaf locationProfileIndex {
type uint32;
description
"Identifies the specific network layer
parameters for the transaction tests
ultimately defined in the Control Table.";
}
leaf dstAddr {
type inet:ip-address;
description
"Identifies the destination address in
the packet headers of the transaction
request message.";
}
leaf srcAddr {
type inet:ip-address;
description
"Identifies the source address in the
packet headers of the transaction
request message.";
}
leaf noFrag {
type Boolean;
description
"Defines the 'No Fragmentation' header
setting in the IP packet headers of the
transaction request message.";
}
leaf TOS {
type uint8;
description
"Identifies the TOS field of the IPv4
or IPv6 packet headers of the transaction
request message. The TOS field is eight bits
in length and this integer is to be converted
to an 8 bit binary to define the appropriate
TOS Field setting.";
}
leaf flowLabel {
type uint16;
description
"Identifies the Flow Label field of the IPv6
packet headers of the transaction request
message. The Flow Label field is 16 bits
in length and this integer is to be converted
to an 16 bit binary to define the appropriate
Flow Label Field setting. In the event that
the protocolType is set to 'IPv4', then this
value is to be set to zero and is to be
ignored in the creation of the IPv4 packets.";
}
leaf protocolType {
type inet:ip-address-type;
description
"Identifies the network protocol type for the
network packets generated as part of the
transaction request messages. The allowed
values are 'IPv4' or 'IPv6'.";
}
leaf looseSrcRoute {
type string;
description
"Identifies the Loose Source Route header
extension for the IP packets forming the
transaction request message.";
}
}
-- ends the networkProfileEntry --
---------------------------------------------------
---------------------------------------------------
-- The Metric Profile performance aspects of --
-- tests, including, e.g., frequency, metric, --
-- success criteria, etc. --
---------------------------------------------------
---------------------------------------------------
list metricProfileEntry {
key "metricProfileIndex";
config true;
leaf metricProfileIndex {
type uint32;
description
"Identifies the specific metric
profile for use in the definition of
the transaction tests in the Control Table.";
}
leaf spacing {
type uint32;
description
"The number of seconds between executing
subsequent transactions.";
}
leaf number {
type uint32;
description
"The number of transactions to be executed.";
}
leaf metric {
type enumeration;
enum loss {
description
"Holds the indication of whether
the transaction was successful (1)
or failed (0).";
}
enum delay {
description
"Holds the number of milliseconds
for the successful transaction
or '0' if the transaction failed.";
}
enum throughput {
description
"Holds the measured throughput
in units of bytes/millisecond for
the transaction if successful
or '0' if failed.";
}
default "loss";
description
"The metric tracked by this specific test.
These values are held on the rawResults
if the specific test indicates storage
of raw data values.";
}
leaf target {
type uint32;
description
"The preformance target for each transaction
measurement. A measured transaction is deemed
successful if its measured 'metric' value
falls within the limits defined by this
'target'. E.g.,
if 'metric = loss', then 'target' must
equal '1' indicating success if repsonse
recieved.
if 'metric = delay', then responses
received within 'target' milliseconds
are counted as successful.
if 'metric = throughput', then responses
recieved with throughputs greater than
'target' are counted as successful.
The target value carries the
units defined by the 'metric', i.e.,
unitless if 'metric = loss',
milliseconds if 'metric = delay',
bytes/milliseconds if
'metric = throughput'.
The server counts the number of transaction
measurements that are deemed successful. This
count is compared against 'threshold' to
determine overall success or failure of the
test.";
default "1";
}
leaf threshold {
type uint32;
description
"The threshold value that determines the
pass/fail status reported to the client
by this server in the 'verifyStatus'
notification.";
}
}
-- ends the metricProfileEntry --
---------------------------------------------------
---------------------------------------------------
-- The Control Table defines the test sets. --
---------------------------------------------------
---------------------------------------------------
list controlTableEntry {
key "controlTableIndex";
config true;
leaf controlTableIndex {
type uint32;
description
"Identifies the specific control table
row of the transaction test template to be
executed, which represents the
verification test sets to be performed
on the device as part of the verify
operation.";
}
leaf locationProfileIndex {
type uint32;
description
"The index from the locationProfileEntry
indicating the URL for this test.";
}
leaf networkProfileIndex {
type uint32;
description
"The index from the locationPprofileEntry
indicating the URL for this test.";
}
leaf metricProfileIndex {
type uint32;
description
"The index from the locationPprofileEntry
indicating the URL for this test.";
}
leaf rawResultCollection {
type enumeration;
enum off {
description
"Indicates that the server will
not store the raw transaction
measurement values of type indicated
by metric.";
}
enum on {
description
"Indicates that the server will
store the raw transaction
measurement values of type indicated
by metric. Further, these raw
measurement values will be passed
to the client throught 'verifyStatus'
notification's 'extendedStatus'
node.";
}
config true;
default "off";
description
"A switch to turn ON or OFF the raw
data collection and notification.";
}
}
-- ends the controlTableEntry --
---------------------------------------------------
---------------------------------------------------
-- The Results Table contains --
-- the results from the test. --
---------------------------------------------------
---------------------------------------------------
list resultsTableEntry {
key "resultsTableIndex";
config true;
leaf resultsTableIndex {
type uint32;
description
"Identifies the specific Control Table
row of the transaction test template to be
executed, which represents the
verification test sets performed
on the device as part of the verify
operation.";
}
leaf startTime {
type yang:date-and-time;
config false;
description
"The time the first transaction
was sent for the previous test.
This is set each time the test
is initiated from a client. When this
value is reset, the value of the
'result' node is set to
'indeterminant' and the value of the
'received' node is set to zero.";
}
leaf received {
type uint32;
config false;
description
"The number of successful
transactions received during
the previous test. This value
is initialized to zero prior to
the instantiation of the test
and is incremented by one for
each received transaction response
message. This is set each time the
test is initiated from a client.";
}
leaf result {
type enumeration {
enum indeterminant{
description
"Set to 'indeterminant' upon
the initiation of a test.";
}
enum success{
description
"Set to 'success' if the
number of successful transactions
exceeded the 'threshold'.";
}
enum failure{
description
"Set to 'failure' if the number
of successful transactions is less
than or equal to the 'threshold'.";
}
config false;
description
"The result of the previous test.";
}
leaf-list rawResults {
description
"Holds the raw metric value for each transaction
successfully recorded as part of the specific
test. The units used for these values conform
to the units defined with the 'metric' measured.
Upon completion of this specific test, the server
passes this measurement data to the requesting
client through the 'verifyStatus' notification's
'anyxml extendedStatus'.";
ordered-by system;
type uint32;
config false;
min-elements 1;
}
}
-- ends the Results Table --
}
| Figure 3 |
| TOC |
| Robert G. Cole | |
| U.S. Army CERDEC | |
| 328 Hopkins Road | |
| Aberdeen Proving Ground, MD 21005 | |
| USA | |
| Phone: | +1.410.278.6779 |
| Email: | robert.g.cole@us.army.mil |
| URI: | http://www.cs.jhu/~rgcole/ |
| Dan Romascanu | |
| Avaya | |
| Atidim Technology Park, Bldg. #3 | |
| Tel Aviv 61131 | |
| Israel | |
| Email: | dromasca@avaya.com |
| Andy Bierman | |
| InterWorking Labs | |
| 303 Potrero Street, Suite 52 | |
| Santa Cruz, CA 95060-2760 | |
| USA | |
| Email: | andyb@iwl.com |