Efficient XML Interchange Capability for NETCONF
draft-varga-netconf-exi-capability-01

Abstract

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.

Requirements Language

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].

Status of This Memo

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 April 24, 2014.

Copyright Notice

Copyright (c) 2013 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.

Table of Contents

• 1. Introduction
• 2. Terminology
• 3. EXI Capability
• 3.1. Overview
• 3.2. Dependencies
• 3.3. Capability Identifier
• 3.4. New Operations
• 3.4.1. <start-exi>
• 3.4.2. <stop-exi>
• 4. YANG module for <start-exi> and <stop-exi> Operations
• 5. IANA considerations
• 6. Security Considerations
• 7. Acknowledgements
• 8. Normative References
• Author's Address

1. Introduction

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.

2. Terminology

This document uses the following terms defined in [RFC6241]:

• capability
• client
• message
• protocol operation
• remote procedure call
• server

3. EXI Capability

3.1. Overview

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.

3.2. Dependencies

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.

3.3. Capability Identifier

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:

compression:

This indicates that the sender is willing to perform EXI compression. The parameter MUST contain a positive integral value, which indicates maximum compression block size which the sender can process.

schemas:

This indicates that the sender can use schema-informed grammars for EXI encoding. The parameter MUST contain a value, which has to be one of "builtin" or "base:1.1". The value "builtin" indicates the ability to use the XML schema built into the EXI specification. The value of "base:1.1" is a superset of the "builtin" value and indicates that the sender additionally supports schema-informed EXI encoding, based on netconf.xsd schema published in [RFC6241].

Examples:

• urn:ietf:params:netconf:capability:exi:1.0?compression=1000000
• urn:ietf:params:netconf:capability:exi:1.0?schemas=builtin
• urn:ietf:params:netconf:capability:exi:1.0?schemas=base:1.1
• urn:ietf:params:netconf:capability:exi:1.0?compression=20000&schemas=builtin

3.4. New Operations

3.4.1. <start-exi>

Description:

The <start-exi> operation requests that the message encoding be switched to EXI. The operation is invoked by the client and validated by the server. If the server finds the parameters acceptable, it will issue a positive response in the current session encoding. It MUST encode all subsequent messages using EXI encoding with the supplied parameters. It will also expect all incoming messages to be EXI-encoded. The client MUST NOT send any messages to the server between the time is sends this request and the time it receives a response. Once it receives a positive reply, it MUST encode all subsequent messages using the EXI encoding with the parameters supplied in the RPC. If the operation fails, the session message encoding remains unchanged.

Parameters:

alignment:

Requested EXI alignment. If this parameter is not present, bit-packed is assumed. The following values are valid:

bit-packed:

Set EXI alignment to bit-packed.

byte-aligned:

Set EXI alignment to byte-aligned.

pre-compression:

Set EXI alignment to pre-compression.

compressed:

Do not specify EXI alignment, but perform EXI compression instead.

fidelity:

Requested EXI fidelity options. If this parameter is not present or empty, all fidelity options are disabled. The following items may be specified:

<comments/>:

Preserve.comments EXI Fidelity option

<dtd/>:

Preserve.dtd EXI Fidelity option

<lexical-values/>:

Preserve.lexicalValues EXI Fidelity option

<pis/>:

Preserve.pis EXI Fidelity option

<prefixes/>:

Preserve.prefixes EXI Fidelity option

schema:

Optional parameter. This specifies what schema options should be enabled in the EXI encoding process. The following values are valid:

none

Do not use schema-informed grammars at all. This translates to using schemaId of <xsd:nil>true</xsd:nil> in the EXI Options header.

builtin

Do no use schema-informed grammars, but use the build-in XML data types. This translates to using an empty schemaId in the EXI Options header.

base:1.1

Use schema-informed grammar based on netconf.xsd as published in [RFC6241] in non-strict mode. The value "base:1.1" should be carried in the schemaId field in the EXI Options.

Positive Response:

If the device was able to satisfy the request, an <rpc-reply> is sent that contains an <ok> element.

Negative Response:

An <rpc-error> element is included in the <rpc-reply> if the request cannot be completed for any reason.

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>
						

3.4.2. <stop-exi>

Description:

The <stop-exi> operation requests that the message encoding be switched to textual XML. The operation is invoked by the client and validated by the server. If the server is able to switch the encoding to XML, it will issue a positive response in the current session encoding. It MUST encode all subsequent messages using standard XML encoding. It will also expect all incoming messages to be XML-encoded. The client MUST NOT send any messages to the server between the time is sends this request and the time it receives a response. Once it receives a positive reply, it MUST encode all subsequent messages using the standard XML encoding. If the operation fails, the session message encoding remains unchanged. If the session currently uses XML encoding, this RPC is a no-operation and SHOULD NOT fail.

Positive Response:

If the device was able to satisfy the request, an <rpc-reply> is sent that contains an <ok> element.

Negative Response:

An <rpc-error> element is included in the <rpc-reply> if the request cannot be completed for any reason.

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>
						

4. YANG module for <start-exi> and <stop-exi> Operations

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@2013-10-21.yang"

module ietf-netconf-exi {
	namespace "urn:ietf:params:xml:ns:netconf:exi:1.0";

	prefix exi;

	organization
		"IETF NETCONF (Network Configuration) Working Group";

	contact
		"Robert Varga <robert.varga@pantheon.sk>";

	description
		"NETCONF Protocol Operations for Efficient XML Interchange.";

	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.";
	}
}

				

5. IANA considerations

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

6. Security Considerations

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.

7. Acknowledgements

The author would like to thank Anton Tkacik, Miroslav Miklus and Stefan Kobza for their contributions to this document.

8. Normative References

Author's Address