| NETCONF Working Group | R. Varga |
| Internet-Draft | Pantheon Technologies SRO |
| Intended status: Standards Track | March 03, 2014 |
| Expires: September 04, 2014 |
Efficient XML Interchange Capability for NETCONF
draft-varga-netconf-exi-capability-02
The Network Configuration Protocol (NETCONF) provides mechanisms to install, manipulate, and delete the configuration of network devices via exchange of XML messages in textual representation. Efficient XML Interchange (EXI) is a W3C-recommended binary representation of XML Information Set, which is more efficient from both CPU and bandwidth utilization perspective. This document defines a capability-based extension to the NETCONF protocol that allows peers to agree to exchange protocol messages using EXI encoding.
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].
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 September 04, 2014.
Copyright (c) 2014 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.
The NETCONF protocol [RFC6241] is defined in terms of two peers, client and server, exchanging XML messages in an RPC pattern. These messages are encoded as XML text documents, which makes the exchange easily understandable by human operators by simply observing them on the wire. Unfortunately, this feature takes its toll on both computation and network resources, as the representation contains redundant information and verbose names.
Efficient XML Interchange [W3C.REC-exi-20110310] is a W3C Recommendation which defines a more efficient way of encoding XML Information Set than the usual text representation. This is achieved by a combination of reduced verbosity, binary encoding and, optionally, pruning of non-essential information like comments.
It seems advantageous to allow clients and servers participating on a NETCONF session to sacrifice human readability to increase processing efficiency, especially in environments with high transactional activity and/or limited computing resources.
This document uses the following terms defined in [RFC6241]:
The :exi capability indicates that the peer supports EXI message encoding and is willing to use it. The capability has no effect on data being handled by the NETCONF protocol, nor does it affect protocol message exchanges.
EXI-encoded documents are binary data, this capability may only be used when the underlying transport is 8-bit clean and preserves message boundaries in face of arbitrary binary data. Notably this requires use of Chunked Framing mechanism as described in [RFC6242] when used with SSH transport.
The optional Dynamic Schema-informed Encoding Negotiation mechanism relies on NETCONF Monitoring as defined in [RFC6022].
The EXI capability is identified by the following capability string:
urn:ietf:params:netconf:capability:exi:1.0
The identifier MAY have a the following parameters:
Examples:
The core of this extension relies on shared knowledge between the server and the client where schema-informed encoding is concerned. This limits the encoding efficiency as the actual data transferred over the session is encoded using the equivalent of the builtin schema. Alleviating this limitation requires a mechanism for discovering data schemas and a protocol for synchronizing their activation.
The base schema discovery mechanism is already present in [RFC6022]. This document extends the /netconf-state/schemas/schema subtree with a new leaf, exi-useable, which indicates whether the server supports the use of that particular schema in the EXI schema-informed encoding process.
The negotiation of use of a particular schema for encoding has multiple aspects. First and foremost is the concern of constrained environments, which may have limited resources and thus their ability to dedicate them to improving encoding efficiency may change over lifetime of a NETCONF session. The second issue comes from the need to synchronize the values used in the "schema" EXI header field. Both end of the session need to map names to the same schemas, otherwise the decoding process will not succeed. This name is carried verbatim in the stream, so it should be as concise as possible.
When the peers have both indicated support for Dynamic Schema-informed Encoding, encoding starts in base:1.1 mode. The client then queries the server for the list of schemas, looking for schemas which have the exi-useable leaf set to true. It then selects the schemas it can use in EXI encoding process, potentially requesting them from the server. Finally it prioritizes them and sends a <enable-schema-encoding> request for each of them. Once the server has assigned a EXI schema-id and communicated it back the the client, both parties can use this schema in EXI encoding. The client can request the end of use of a particular schema via the <disable-schema-encoding> RPC, which the server SHOULD NOT fail.
Example:
<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <start-exi> <alignment>pre-compression</alignment> <fidelity> <dtd/> <lexical-values/> </fidelity> </start-exi> </rpc> <rpc-reply message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <ok/> </rpc-reply>
Example:
<rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <stop-exi/> </rpc> <rpc-reply message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <ok/> </rpc-reply>
The following YANG module defines the new operations introduced in this document. The YANG language is defined in [RFC6020]. Every NETCONF speaker that supports the :exi capability MUST implement this YANG module.
<CODE BEGINS> file "ietf-netconf-exi@2014-03-03.yang"
module ietf-netconf-exi {
// vi: set et smarttab sw=4 tabstop=4:
namespace "urn:ietf:params:xml:ns:netconf:exi:1.0";
prefix exi;
import ietf-netconf-monitoring {
prefix ncm;
revision-date "2010-10-04";
}
organization
"IETF NETCONF (Network Configuration) Working Group";
contact
"Robert Varga <robert.varga@pantheon.sk>";
description
"NETCONF Protocol Operations for Efficient XML Interchange.";
revision 2014-03-03 {
description
"Updated with dynamic schema negotiation.";
reference
"I-D.varga-netconf-exi-capability-02";
}
revision 2013-10-21 {
description
"Initial revision";
reference
"I-D.varga-netconf-exi-capability-01";
}
typedef exi-alignment {
type enumeration {
enum bit-packed {
description
"Use bit-packed EXI alignment";
}
enum byte-aligned {
description
"Use byte-aligned EXI alignment";
}
enum pre-compression {
description
"Use pre-compression EXI alignment";
}
enum compressed {
description
"Do not set EXI alignment, use EXI compression
instead";
}
}
description "EXI alignment specification.";
}
typedef exi-fidelity {
type enumeration {
enum comments {
description
"Preserve.comments EXI Fidelity option";
}
enum dtd {
description
"Preserve.dtd EXI Fidelity option";
}
enum lexical-values {
description
"Preserve.lexicalValues EXI Fidelity option";
}
enum pis {
description
"Preserve.pis EXI Fidelity option";
}
enum prefixes {
description
"Preserve.prefixes EXI Fidelity option";
}
}
description "EXI fidelity options.";
}
rpc start-exi {
description
"Start encoding protocol messages in Efficient XML
Interchange format.";
reference "I-D.varga-netconf-exi-capability";
input {
leaf alignment {
type exi-alignment;
default "bit-packed";
description "EXI alignment to use.";
}
leaf-list fidelity {
type exi-fidelity;
description "EXI fidelity options to use.";
}
}
}
rpc stop-exi {
description
"Stop encoding protocol messages in Efficient XML
Interchange format. Revert back to using the usual text
XML encoding.";
}
grouping schema-identifier {
description
"The globally-unique identifier of a schema. This
grouping contains the verbatim transcription of arguments
to <get-schema> RPC as defined in RFC6022, except all
leaves are made mandatory.";
leaf identifier {
type string;
mandatory true;
description
"Identifier for the schema list entry.";
}
leaf version {
type string;
description
"Version of the schema requested. If this parameter
is not present, and more than one version of the
schema exists on the server, a 'data-not-unique'
error is returned, as described above.";
}
leaf format {
type identityref {
base ncm:schema-format;
}
description
"The data modeling language of the schema. If this
parameter is not present, and more than one formats
of the schema exists on the server, a
'data-not-unique' error is returned, as described
above.";
}
}
typedef exi-schema-id {
type uint16;
description
"Schema identifier for use in the EXI stream header.";
}
augment "/ncm:netconf-state/ncm:schemas/ncm:schema" {
description
"Additional information about schemas useful for EXI
encoding";
leaf exi-useable {
type boolean;
default false;
description
"Set to true if the device can use the schema for EXI
Schema-informed encoding.";
}
leaf exi-schema-id {
type exi-schema-id;
description
"The EXI schema ID currently assigned to this schema.
This value has meaning only within the session and
may differ on other sessions.";
}
}
rpc enable-schema-encoding {
description
"Request the use of specificied schema in EXI message
encoding. This request is sent by the client to the
server. If the server is able to transition into using
the schema, it assigns it a unique EXI integer
identifier. This identifier is to be used in the EXI
header as schema identifier.
The server may start using the identifier as soon as it
enqueus the response. The client may start using the
identifier as soon as it sees this RPC complete.";
input {
uses schema-identifier;
}
output {
leaf exi-schema-id {
type exi-schema-id;
mandatory true;
description
"The EXI Schema ID assigned to this schema for
encoding purposes.";
}
}
}
rpc disable-schema-encoding {
description
"This RPC is send by the client when it stops using a
particular exi-schema-id.";
input {
leaf exi-schema-id {
type exi-schema-id;
mandatory true;
description
"The EXI Schema ID which should be disabled.";
}
}
}
}
This document registers the following capability identifier URN in the 'Network Configuration Protocol (NETCONF) Capability URNs' registry: urn:ietf:params:netconf:capability:exi:1.0
The compression option present in EXI specification may increase CPU and memory requirements for encoding the response. Devices should ensure this overhead is acceptable before agreeing to using EXI encoding, such that no operational risks are introduced.
The author would like to thank Anton Tkacik, Miroslav Miklus and Stefan Kobza for their contributions to this document.
| [RFC2119] | Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. |
| [RFC6020] | Bjorklund, M., "YANG - A Data Modeling Language for the Network Configuration Protocol (NETCONF)", RFC 6020, October 2010. |
| [RFC6022] | Scott, M. and M. Bjorklund, "YANG Module for NETCONF Monitoring", RFC 6022, October 2010. |
| [RFC6241] | Enns, R., Bjorklund, M., Schoenwaelder, J. and A. Bierman, "Network Configuration Protocol (NETCONF)", RFC 6241, June 2011. |
| [RFC6242] | Wasserman, M., "Using the NETCONF Protocol over Secure Shell (SSH)", RFC 6242, June 2011. |
| [W3C.REC-exi-20110310] | Schneider, J. and T. Kamiya, "Efficient XML Interchange (EXI) Format 1.0", World Wide Web Consortium Recommendation REC-exi-20110310, March 2011. |