module ietf-netconf-ex {
namespace "urn:ietf:params:xml:ns:yang:ietf-netconf-ex";
prefix ncex;
import ietf-inet-types {
prefix inet;
}
import ietf-netconf {
prefix nc;
}
import ietf-netconf-notifications {
prefix ncn;
}
import ietf-netconf-with-defaults {
prefix ncwd;
}
import ietf-yang-patch {
prefix yp;
}
import ietf-yang-types {
prefix yang;
}
organization
"IETF NETCONF (Network Configuration Protocol) Working Group";
contact
"WG Web:
WG List:
WG Chair: Mehmet Ersue
WG Chair: Bert Wijnen
Editor: Andy Bierman
";
description
"This module contains a collection of YANG definitions for the
efficient operation of a NETCONF server. Protocol operations
are defined to reduce network usage and transaction complexity.
Copyright (c) 2014 IETF Trust and the persons identified as
authors of the code. 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.";
// RFC Ed.: replace XXXX with actual RFC number and remove this
// note.
// RFC Ed.: remove this note
// Note: extracted from
// draft-bierman-netconf-efficiency-extensions-01.txt
// RFC Ed.: update the date below with the date of RFC publication
// and remove this note.
revision "2014-04-21" {
description
"Initial revision. operation originally published
in draft-bierman-netconf-get2-03.txt";
reference
"RFC XXXX: NETCONF Efficiency Extensions";
}
/* Features */
feature timestamps {
description
"This feature indicates that the server implements
the operations parameters which require
last modification timestamps to be maintained by
the server.
If this feature is advertised then one global
'last-modified' timestamp for the entire
running configuration datastore MUST be supported.
The server MAY support additional timestamps
for additional datastores and data nodes
within a datastore. The 'with-metadata'
parameter can be used to identify
which data nodes support a 'last-modified'
timestamp.";
}
feature with-defaults {
description
"This feature indicates that the server supports the
'with-defaults' parameter for the operation.
A NETCONF server SHOULD support this feature.";
reference
"RFC 6243: With-defaults Capability for NETCONF";
}
feature confirmed-edit {
description
"This feature indicates that the server supports the
confirmed commit procedure for the protocol
operation.";
}
/* Identities */
identity metadata {
description
"Base for all metadata identifiers used by the
'with-metadata' parameter in the operation.";
}
identity timestamps {
base metadata;
description
"Describes metadata identifying the last modification
time of the associated datastore or data resource.";
}
identity etags {
base metadata;
description
"Describes metadata identifying the entity tag value
of the associated datastore or data resource.";
}
identity config-id {
base metadata;
description
"Describes metadata identifying the config ID
of the associated datastore or data resource.";
}
/* Typedefs */
typedef yang-entity-tag {
type string;
description
"Contains an opaque string representing a specific instance
of a datastore or data resource. A client can use this
string for equality comparisons between yang-entity-tag
values.
If any configuration data node values changes, or the
relative order of any user-ordered data changes, then
the server MUST change the entity tag value for the
running datastore to a different value. If the server
maintains entity-tag values for configuration data nodes,
then the server MUST change the yang-entity-tag value for
any affected data node.
Only yang-entity-tag values for the same target resource
instance can be compared. Only the 'strong entity tag'
form is required. A server MAY support the 'weak
entity tag' form. If so, then 2 YANG data node resource
instances are considered to be equivalent if they
contain the same value subtrees and all user-ordered
data nodes share the same relative order.";
reference
"RFC 2616, section 3.11.";
}
/* Groupings */
grouping lock-parms {
description
"Common parameters to control datastore locking.";
leaf with-locking {
type empty;
description
"If this parameter is present then the request MUST be
performed with exclusive write access to all datastores
involved in the operation. An 'operation-not-supported'
error-tag value is returned if the target datastore for
the operation does not support locking (e.g., 'url' or
'operational').
If the server cannot provide exclusive write access
for the entire requested operation then an 'in-use'
error-tag value is returned.
If the 'max-lock-wait' parameter is also present then
the server MAY choose to wait up to that amount of
time attempting to obtain exclusive write access,
before returning an error.";
}
leaf max-lock-wait {
when "../with-locking" {
description
"Only relevant if locking is requested.";
}
type uint32 {
range "1 .. 600";
}
units seconds;
description
"If this parameter is present and the 'with-locking'
parameter is also present, then the server MAY wait
up to the specified number of seconds attempting
to obtain exclusive write access for the requested
operation.";
}
}
/* Protocol Operations */
rpc get2 {
description
"Retrieve NETCONF datastore information";
input {
container source {
description
"The datastore (or non-configuration data)
to use for the source for the retrieval operation.";
choice datastore-source {
default running;
description
"The configuration source for the retrieval operation.
The running configuration is the default choice if
this parameter is not present.";
leaf candidate {
if-feature nc:candidate;
type empty;
description
"The candidate configuration datastore is the
retrieval source.";
}
leaf running {
type empty;
description
"The running configuration datastore is the
retrieval source.";
}
leaf startup {
if-feature nc:startup;
type empty;
description
"The startup configuration datastore is the
retrieval source.";
}
leaf url {
if-feature nc:url;
type inet:uri;
description
"The URL-based configuration is the
retrieval source.";
}
leaf operational {
type empty;
description
"The retrieval source is the collection of all
operational (non-configuration) data nodes supported
by the server.
Any ancestor container and/or list and list key nodes
are also returned. No other leafs or leaf-lists will
be included in the reply.
The server MAY return ancestor container, and/or list
and list key nodes that do not contain any
non-configuration nodes. This can occur for several
reasons, e.g., the implementation streams replies
and cannot defer instrumentation or access control
filtering of descendant data nodes.";
}
}
}
choice filter-spec {
description
"The content filter specification for this request";
anyxml subtree-filter {
description
"This parameter identifies the portions of the
target datastore to retrieve.";
reference "RFC 6241, Section 6.";
}
leaf xpath-filter {
if-feature nc:xpath;
type yang:xpath1.0;
description
"This parameter contains an XPath expression
identifying the portions of the target
datastore to retrieve.";
}
}
leaf keys-only {
type empty;
description
"This parameter selects only data nodes which
are key leaf nodes. Parent container and
list nodes are also returned, but no other leafs,
or any leaf-lists will be included in the reply.";
}
leaf if-modified-since {
if-feature timestamps;
type yang:date-and-time;
description
"This parameter selects the target datastore
only if the last-modified timestamp for the
datastore is more recent than the specified time.
If not, then an empty element is returned.
If the target datastore does not maintain a
last-modified timestamp, then this parameter is
ignored.";
}
leaf full-delta {
if-feature timestamps;
type empty;
description
"This parameter selects only data nodes which
have been modified since the specified time.
It is ignored unless the 'if-modified-since'
parameter is also provided and the target datastore
supports a last-modified timestamp.";
}
leaf depth {
type uint32;
default 0;
description
"This parameter selects how many conceptual
sub-tree levels should be returned in the
.
If this parameter is equal to '0', then entire
subtrees will be returned.
If this parameter is greater than '0', then
only the specified number of subtree levels will
be returned.";
}
uses ncwd:with-defaults-parameters {
if-feature with-defaults;
description
"This parameter controls the retrieval of
default values.";
reference
"RFC 6243: With-defaults Capability for NETCONF";
}
leaf-list with-metadata {
type identityref {
base metadata;
}
description
"This parameter will cause the server to return
metadata in the (e.g. as XML attributes
in XML encoding) associated with the specified
metadata identity. If the server does not support
any specified metadata identifier, then the
operation fails with an 'invalid-value' error.";
}
uses lock-parms {
description
"Exclusive write access can be requested to
ensure that no other sessions modify the
configuration data during the retrieval operation";
}
}
output {
anyxml data {
description
"Copy of the requested datastore subset which
matched the filter criteria (if any).
An empty data container indicates that the
request did not produce any results.";
}
}
}
rpc edit2 {
description
"Edit NETCONF datastore contents.
All operations requested in the yang-patch edit list
are applied, or the target datastore is left unchanged.";
input {
container target {
description
"The datastore to use as the target for this
edit operation.";
choice datastore-target {
mandatory true;
description
"The configuration target for the edit operation.";
leaf candidate {
if-feature nc:candidate;
type empty;
description
"The candidate configuration datastore is the
edit target.";
}
leaf running {
if-feature nc:writable-running;
type empty;
description
"The running configuration datastore is the
edit target.";
}
}
}
leaf target-resource {
if-feature nc:xpath;
type yang:xpath1.0;
description
"This parameter identifies 1 or more data node
instances for which the yang-patch edits
will be applied. The target-resource expression
MUST evaluate to a node-set result.
Each operation in the yang-patch edit list will
be applied to each target-resource instance, as if
it were the document root for the operation.
If multiple instances are represented by the
target-resource value, then the server will apply
all edits to all instances. If any errors occur,
then all edits from this request will be undone
from the target datastore.
The user MUST have appropriate write permissions for
all data accessed by every operation within the edit
list.
If this parameter is not present or not supported
then the target resource is the root node of the
datastore identified by the 'target' parameter.";
}
uses yp:yang-patch {
description
"The yang-patch parameter contains the ordered list
of edits to perform on the target resource(s).
The conceptual document root for the 'target'
parameter is defined to be the value of a data node
represented by the 'target-resource' parameter or the
target datastore conceptual root node if that parameter
is not present.";
}
leaf test-only {
type empty;
description
"If this parameter is present the server will not
actually perform the requested edits. Instead the
edit request will be validated as if it were going
to be applied. Any parameter errors or datastore
validation errors SHOULD be reported in the response.
No attempt to apply, activate the edits or save them
in non-volatile storage will be made if this parameter
is present.";
}
leaf if-match {
type yang-entity-tag;
description
"If this parameter is set, then the entire edit request
will be rejected unless the entity tag for the target
resource matches this value. An rpc-error with
an 'operation-failed' error-tag value MUST returned,
and the edit operation MUST NOT be attempted.
The 'error-app-tag' field SHOULD be set to
'precondition-failed'.
If the target datastore does not maintain a
last-modified timestamp, then this parameter is
ignored.";
}
uses lock-parms {
description
"Exclusive write access can be requested to
ensure that no other sessions modify the
configuration data during the edit operation
and possibly the entire confirmed commit procedure.
If the 'with-locking' parameter is used to start or
extend a confirmed commit procedure, then the
exclusive write access will be maintained until the
confirmed commit procedure terminates somehow.
If the 'with-locking' parameter is used for a
plain edit operation, then exclusive write access
will be maintained until this operation has completed.";
}
leaf activate-now {
type empty;
description
"If present and the edit operation succeeds,
then the server will activate the configuration
changes right away. The server will conceptually
perform a operation after the edit
operation. The user MUST have execute
permission for the operation or
the operation fails with an 'access-denied' error.
This parameter has no affect unless the
'datasource-target' choice is the 'candidate' leaf.";
}
leaf nvstore-now {
type empty;
description
"If present and the edit operation succeeds,
and the configuration changes are activated
in the running datastore, then the server
will persist the configuration changes right away
in non-volatile store. The server will conceptually
perform a operation from the running
to the startup datastore. The user MUST have execute
permission for the operation or
the operation fails with an 'access-denied' error.
This parameter has no affect unless the
'startup' capability is supported by the server.";
}
leaf confirmed {
if-feature confirmed-edit;
type empty;
description
"If the requested edit operation succeeds and the
configuration changes are applied to the running
datastore, then a confirmed commit procedure is
requested by the client.
A confirmed commit procedure is an operation
that contains this parameter. The
operation is used to complete the confirmed commit
procedure. The operation is used
to cancel the confirmed commit procedure and
revert the running datastore back to the contents
before the first confirmed commit operation.
If no or operation
is invoked within the timeout interval then
the server will revert the running datastore
back to the contents before the first confirmed
edit operation.
This is the same as the confirmed commit procedure
in RFC 6241 except the candidate capability is
not required.
The server will save the running datastore contents
before the edit operation is activated, if there
is no confirmed edit already in progress.
If the 'with-locking' parameter is present then
the server will maintain exclusive write access
for the specified session until the confirmed
edit procedure is completed somehow.";
reference
"RFC 6241, Section 8.3.4.1";
}
leaf confirm-timeout {
when "../confirmed" {
description
"Only relevant if the parameter is present";
}
if-feature confirmed-edit;
type uint32 {
range "1..max";
}
units "seconds";
default "600"; // 10 minutes
description
"The timeout interval for a confirmed edit procedure.
If exclusive write access was granted for this confirmed
commit procedure, then it is removed if the timeout
occurs and the confirmed commit procedure is terminated.";
reference "RFC 6241, Section 8.3.4.1";
}
leaf persist {
if-feature confirmed-edit;
type string;
description
"This parameter is used to make a confirmed commit
procedure persistent. A persistent confirmed commit
is not aborted if the NETCONF session terminates.
The only way to abort a persistent confirmed commit
is to let the timer expire, or to use the
operation.
The value of this parameter is a token that MUST be
given in the 'persist-id' parameter of the ,
, or operations in
order to extend, confirm, or cancel the persistent
confirmed commit procedure.
The token SHOULD be a random string.";
reference "RFC 6241, Section 8.3.4.1";
}
leaf persist-id {
if-feature confirmed-edit;
type string;
description
"This parameter is given in order to extend a persistent
confirmed edit. The value must be equal to the value
given in the 'persist' parameter to the
operation. If it does not match, the operation fails
with an 'invalid-value' error.";
reference "RFC 6241, Section 8.3.4.1";
}
}
output {
uses yp:yang-patch-status;
}
}
rpc complete-commit {
if-feature confirmed-edit;
description
"This operation is used to complete an ongoing confirmed
commit procedure. If exclusive write access was granted
for this confirmed commit procedure, then it is removed
if this operation is successfully completed.
If the confirmed commit is persistent, the parameter
'persist-id' MUST be given, and it MUST match the value of
the 'persist' parameter given in the operation.
If not confirmed commit procedure is in progress then
the operation fails with an 'operation-failed' error.";
reference "RFC 6241, Section 8.4.5.1";
input {
leaf persist-id {
type string;
description
"This parameter is given in order to complete a
persistent confirmed commit procedure. The
value MUST be equal to the value given in the
'persist' parameter to the operation.
If it does not match, the operation fails with
an 'invalid-value' error.";
}
}
}
rpc revert-commit {
if-feature confirmed-edit;
description
"This operation is used to cancel an ongoing confirmed commit.
If exclusive write access was granted for this confirmed
commit procedure, then it is removed if this operation
is successfully completed.
If the confirmed commit is persistent, the parameter
'persist-id' MUST be given, and it MUST match the value of
the 'persist' parameter. If not confirmed commit
procedure is in progress then the operation fails
with an 'operation-failed' error.";
reference "RFC 6241, Section 8.4.4.1";
input {
leaf persist-id {
type string;
description
"This parameter is given in order to cancel a persistent
confirmed commit and revert the running configuration
datastore to its state before the confirmed commit
procedure started. The value MUST be equal to the value
given in the 'persist' parameter to the
operation.
If it does not match, the operation fails with an
'invalid-value' error.";
}
}
}
/* Notifications */
augment /ncn:netconf-config-change {
description
"Add the updated config-id capability value
to a configuration change event.";
leaf config-id {
type string;
description
"Contains the new configuration ID for the
running datastore on the server, representing
the datastore after the configuration changes.";
}
}
}