NETCONF J. Lindblad
Internet-Draft Cisco Systems
Intended status: Standards Track 2 November 2020
Expires: 6 May 2021
Transaction ID Mechanism for NETCONF
draft-lindblad-netconf-transaction-id-00
Abstract
TODO Abstract
Discussion Venues
This note is to be removed before publishing as an RFC.
Source for this draft and an issue tracker can be found at
https://github.com/janlindblad/netconf-transaction-id.
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 https://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 6 May 2021.
Copyright Notice
Copyright (c) 2020 IETF Trust and the persons identified as the
document authors. All rights reserved.
Lindblad Expires 6 May 2021 [Page 1]
Internet-Draft NCTID November 2020
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents (https://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
2. Conventions and Definitions . . . . . . . . . . . . . . . . . 3
3. NETCONF Extension . . . . . . . . . . . . . . . . . . . . . . 3
4. Configuration Retreival . . . . . . . . . . . . . . . . . . . 4
4.1. Configuration Response Pruning . . . . . . . . . . . . . 5
5. Configuration Update . . . . . . . . . . . . . . . . . . . . 7
5.1. Conditional Configuration Update . . . . . . . . . . . . 10
6. YANG Modules . . . . . . . . . . . . . . . . . . . . . . . . 13
7. Security Considerations . . . . . . . . . . . . . . . . . . . 16
8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16
9. Normative References . . . . . . . . . . . . . . . . . . . . 16
Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 16
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 16
1. Introduction
When a NETCONF client connects with a NETCONF server, a frequently
occurring use case is for the client to find out if the configuration
has changed since it was last connected. Such changes could occur
for example if another NETCONF client has made changes, or another
system or operator made changes through other means than NETCONF.
One way of detecting a change for a client would be to retrieve the
entire configuration from the server, then compare the result with a
previously stored copy at the client side. This approach is not
popular with most NETCONF users, however, since it would often be
very expensive in terms of communications and computation cost.
Furthermore, even if the configuration is reported to be unchanged,
that will not guarantee that the configuration remains unchanged when
a client sends a subsequent change request, which arrives soon
thereafter.
Evidence of a transaction-id feature being demanded by clients is
that several server implementors have built proprietary and mutually
incompatible mechanisms for obtaining a transaction id from a NETCONF
server.
Lindblad Expires 6 May 2021 [Page 2]
Internet-Draft NCTID November 2020
RESTCONF, RFC 8040 RFC8040 (https://tools.ietf.org/html/rfc8040),
defines a mechanism for detecting changes in configuration subtrees
based on Entity-tags (ETags). In conjunction with this, RESTCONF
provides a way to make configuration changes conditional on the
server confiuguration being untouched by others. This mechanism
leverages RFC 7232 RFC7232 (https://tools.ietf.org/html/rfc7232)
"Hypertext Transfer Protocol (HTTP/1.1): Conditional Requests".
This document defines similar functionality for NETCONF, RFC 6241
RFC6241 (https://tools.ietf.org/html/rfc6241).
2. Conventions and Definitions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in BCP
14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here.
3. NETCONF Extension
This document describes a NETCONF extension which modifies the
behavior of get-config, get-data, edit-config and edit-data such that
clients are able to conditionally retrieve and update the
configuration in a NETCONF server. NETCONF servers that supports
this extension MUST announce the capability "FIXME".
The extended operations defined in this document pertains to YANG
containers and list elements. It is NOT REQUIRED that a conforming
server allows the extended operations to apply to all containers and
list elements in the server configuration. The set of containers and
list elements that the server supports with respect to this NETCONF
extension are collectively referred to as the "versioned elements".
The NETCONF server will maintain a record of the transaction that
last changed each versioned element. This transaction-id meta level
data is communicated between the server and client in the form of an
XML attribute called "entag". The values for the entag attribute is
up to the clients and servers to decice as opaque quantities. It is
essential that the entag values have a large value space in order to
not run out or collide. They SHOULD be at least 32-bit quantities.
Entag attribute values are encoded as YANG strings.
Comment, to be removed
Do we want to limit the entag attribute strings in some way? E.g.
only base64 characters, some min or max length, ...?
Lindblad Expires 6 May 2021 [Page 3]
Internet-Draft NCTID November 2020
4. Configuration Retreival
When a NETCONF client retrieves the configuration from a NETCONF
server that implement this specification, it may request that the
configuration is entity tagged. The entity tags are XML attributes
added to some of the retrieved configuration elements by the server.
These elements are collectively called the "versioned elements".
The entity-tag (entag) attributes are guaranteed to change every time
there has been a configuration change at or below the element bearing
the attribute.
Clients request entity tags to be added by setting the ietf-netconf-
transaction-id:entag attribute to the value "?" on one or more
elements in the request. Entags MUST be returned for all descendant
versioned elements. In order to request that entags are returned for
the entire configuration, the client can place the attribute on the
top edit-config or edit-data tags. For more specific retrieval, the
client inserts entag attributes in the filter section.
To retrieve entag attributes across the entire NETCONF server
configuration, a client might send:
To retrieve entag attributes for "ietf-interfaces", but not for
"nacm", a client might send:
Lindblad Expires 6 May 2021 [Page 4]
Internet-Draft NCTID November 2020
When a NETCONF server receives a get-config or get-data request
containing ietf-netconf-transaction-id:entag attributes with the
value "?", it MUST return entag attributes for all versioned elements
below this point included in the reply.
The server's response to request above might look like:
GigabitEthernet-0/0Management Interfaceianaift:ethernetCsmacdtrueGigabitEthernet-0/1Upward Interfaceianaift:ethernetCsmacdtrueadminsakurajoe
4.1. Configuration Response Pruning
A NETCONF client that already knows some entag values may request
that the configuration retrieval request is pruned with respect to
the client's prior knowledge.
Lindblad Expires 6 May 2021 [Page 5]
Internet-Draft NCTID November 2020
By specifying the previously received entag attribute values in the
get-config or get-data request, the client indicates that child
elements of already known parts of the configuration SHALL be
omitted.
To retrieve only changes for "ietf-interfaces" since the last known
transaction-id "abc12345678", but include the entire configuration
for "nacm", a client might send:
When a NETCONF server receives a get-config or get-data request
containing ietf-netconf-transaction-id:entag attributes with the same
value as the entag value known by the server for that element, it
MUST prune the contents of that subtree.
In case the element with a matching entag value is a container, the
container tag is returned with an entag attribute value of "=". No
child elements are returned for the container.
In case the element with a matching entag value is a list element,
the list element tag is returned with an entag attribute value of
"=". The list element will include the list elemenet keys, but no
other child elements.
For example, assuming the NETCONF server configuration is the same as
in the previous rpc-reply example, the server's response to request
above might look like:
Lindblad Expires 6 May 2021 [Page 6]
Internet-Draft NCTID November 2020
GigabitEthernet-0/0Management Interfaceianaift:ethernetCsmacdtrueGigabitEthernet-0/1adminsakurajoe
5. Configuration Update
When a NETCONF client sends an edit-config or edit-data request to a
NETCONF server that implements this specification, the client MAY
specify a transaction-id value.
If specified, the server MUST use this value as the new value for all
entag attribute values of any versioned element touched by the
transaction, if and only if the operation is successful. The entag
value must be updated regardless of whether an actual value change
took place or not. An element is touched if it is mentioned in the
transaction, even if it merely sets the element to the same value it
already has.
If the server side configuration changes for any reason, and there is
no transaction-id value specified by a client, servers that supports
this specification MUST update the entag values as if a NETCONF
client had made the change and specified a transaction-id. In this
case, the server MUST choose a random transaction-id value to use.
Lindblad Expires 6 May 2021 [Page 7]
Internet-Draft NCTID November 2020
Comment, to be removed
Is talk about "random" good enough, or do we need to get specific?
Every time a versioned element has its entag value updated, the same
value must be set to all parent versioned elements' entag attributes,
cascading all the way to the datastore root.
For example, if a client wishes to update the interface description
for interface "GigabitEthernet-0/1" to "Downward Interface", under
transaction-id "ghi55550101", it might send:
test-then-set
ghi55550101
GigabitEthernet-0/1Downward Interface
A subsequent get-config request for "ietf-interfaces", with ietf-
netconf-transaction-id:entag="?" might then return:
Lindblad Expires 6 May 2021 [Page 8]
Internet-Draft NCTID November 2020
GigabitEthernet-0/0Management Interfaceianaift:ethernetCsmacdtrueGigabitEthernet-0/1Downward Interfaceianaift:ethernetCsmacdtrue
In case the server received a configuration change from another
source, such as a CLI operator, adding an MTU value for the interface
"GigabitEthernet-0/0", a subsequent get-config request for "ietf-
interfaces", with ietf-netconf-transaction-id:entag="?" might then
return:
Lindblad Expires 6 May 2021 [Page 9]
Internet-Draft NCTID November 2020
GigabitEthernet-0/0Management Interfaceianaift:ethernetCsmacdtrue768GigabitEthernet-0/1Downward Interfaceianaift:ethernetCsmacdtrue
5.1. Conditional Configuration Update
Conditional Transactions are useful when a client is interested to
make a configuration change, being sure that the server configuration
has not changed since the client last inspected it.
By supplying the latest entag values known to the client in its
change requests (edit-config etc.), it can request the server to
reject the transaction in case any changes have occurred at the
server that the client is not yet aware of.
Even if a client is constantly connected to a device, and even
possibly receiving notifications when a server device's configuration
changes, there is always a possibility that a change is introduced by
another party in the time window between when the client last
received an update about the server's configuration until the server
executes a configuration change request.
By leveraging conditional transactions, this race condition can be
eliminated efficiently. If the client provides the transaction-id it
expects the device to have as part of it's configuration change
request, and the device guarantees to only execute the request in
case the transaction-id in the request matches that on the server,
the race condition is removed.
Lindblad Expires 6 May 2021 [Page 10]
Internet-Draft NCTID November 2020
When a NETCONF client sends an edit-config or edit-data request to a
NETCONF server that implements this specification, the client MAY
specify expected entag values on the versioned elements touched by
the transaction.
If such an entag value differs from the entag value stored on the
server, the server MUST reject the transaction.
If the server rejects the transaction because the configuration entag
value differs from the client's expectation, ther server MUST return
an rpc-error with the following values:
error-tag: operation-failed
error-type: protocol
error-severity: error
Additionally, the error-info tag MUST contain a sx:structure entag-
value-mismatch-error-info, with mismatch-path set to the instance
identifier value identifying one of the versioned elements that had
an entag value mismatch, and mismatch-entag-value set to the server's
current value of the entag attribute for that versioned element.
For example, if a client wishes to delete the interface
"GigabitEthernet-0/1" if and only if its configuration has not been
altered since this client last synchronized its configuration with
the server (at which point it received a transaction-id
"ghi55550101"), regardless of any possible changes to other
interfaces, it might send:
Lindblad Expires 6 May 2021 [Page 11]
Internet-Draft NCTID November 2020
test-then-setGigabitEthernet-0/1
If interface "GigabitEthernet-0/1" has the entag value "ghi55550101",
as expected by the client, the transaction goes through.
A subsequent get-config request for "ietf-interfaces", with ietf-
netconf-transaction-id:entag="?" might then return:
GigabitEthernet-0/0Management Interfaceianaift:ethernetCsmacdtrue
If interface "GigabitEthernet-0/1" did not have the entag value
"ghi55550101", the server rejects the transaction, and might send:
Lindblad Expires 6 May 2021 [Page 12]
Internet-Draft NCTID November 2020
message-id="1">
protocoloperation-failederror
/if:interfaces/if:interface[if:name="GigabitEthernet-0/0"]
auto77775511
Comment, to be removed
In order to reach the full flexibility with the above transaction
rejection mechanism, it might make sense to reference parts of the
configuration just to see that they have not moved, with no intent
to make changes there. To support this use case, a new operation
mode "nocreate" might be useful. This would allow an edit config
to talk about parts of the configuration which are expected to
exist with a particular confiuguration, and to abort the
transaction if they do not exist.
Comment, to be removed
NETCONF clients may be equally interested to apply a mechanism
similar to entags when retrieving operational state as well, since
there is often vey much of this data, and some if changes rather
rarely. To support this use case, some sort of server maintained
change indicators may be invented, and combined with a similar
retrieval filter.
6. YANG Modules
Comment, to be removed
This is YANG 1.1. Do we also want 1.0? Makes it possible to
implement on 1.0 servers
Lindblad Expires 6 May 2021 [Page 13]
Internet-Draft NCTID November 2020
module ietf-netconf-transaction-id {
yang-version 1.1;
namespace
'urn:ietf:params:xml:ns:yang:ietf-netconf-transaction-id';
prefix ietf-netconf-transaction-id;
import ietf-netconf {
prefix nc;
}
import ietf-netconf-nmda {
prefix ncds;
}
import ietf-yang-structure-ext {
prefix sx;
}
organization
"IETF NETCONF (Network Configuration) Working Group";
contact
"WG Web:
WG List:
Author: Jan Lindblad
";
description
"NETCONF Transaction ID aware operations for NMDA.
Copyright (c) 2020 IETF Trust and the persons identified as
the document authors. All rights reserved.
Redistribution and use in source and binary forms, with or
without modification, is permitted pursuant to, and subject
to the license terms contained in, the Simplified BSD License
set forth in Section 4.c of the IETF Trust's Legal Provisions
Relating to IETF Documents
(http://trustee.ietf.org/license-info).
This version of this YANG module is part of RFC XXXX; see
the RFC itself for full legal notices.";
revision 2020-10-01 {
description
"Initial revision";
reference
Lindblad Expires 6 May 2021 [Page 14]
Internet-Draft NCTID November 2020
"RFC XXXX: Xxxxxxxxx";
}
typedef transaction-id-t {
type string;
description
"Unique value representing a specific transaction";
}
grouping transaction-id-grouping {
leaf transaction-id {
type transaction-id-t;
description
"Transaction-id value selected by the client. This string
should be chosen to give a high probability to be unique on
the server.";
}
description
"Grouping for transaction-id, to be augmented into rpcs
that modify configuration data stores.";
}
augment /nc:edit-config/nc:input {
uses transaction-id-grouping;
description
"Injects the transaction-id leaf into the edit-config
operation";
}
augment /ncds:edit-data/ncds:input {
uses transaction-id-grouping;
description
"Injects the transaction-id leaf into the edit-data
operation";
}
sx:structure entag-value-mismatch-error-info {
container entag-value-mismatch-error-info {
description
"This error is returned by a NETCONF server when a client
sends a configuration change request, with the additonal
condition that the server aborts the transaction if the
server's configuration has changed from what the client
expects, and the configuration is found not to actually
not match the client's expectation.";
leaf mismatch-path {
type instance-identifier;
description
Lindblad Expires 6 May 2021 [Page 15]
Internet-Draft NCTID November 2020
"Indicates the YANG path to the element with a mismatching
entag value.";
}
leaf mismatch-entag-value {
type transaction-id-t;
description
"Indicates server's value of the entag attribute for one
mismatching element.";
}
}
}
}
7. Security Considerations
TODO Security
8. IANA Considerations
This document has no IANA actions.
9. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, .
Acknowledgments
TODO acknowledge.
Author's Address
Jan Lindblad
Cisco Systems
Email: jlindbla@cisco.com
Lindblad Expires 6 May 2021 [Page 16]