../_images/logo.png

YumaPro netconfd-pro Manual

../_images/netconfd_components.png

netconfd-pro Introduction

The netconfd-pro program is a NETCONF-over-SSH server implementation. It is driven directly by YANG files, and provides a robust and secure database interface using standard NETCONF protocol operations.

All aspects of NETCONF protocol operation handling can be done automatically by the netconfd-pro server. However, the interface between the NETCONF database and the device instrumentation is not covered in this document. Refer to the YumaPro Developer Manual for details on adding YANG module instrumentation code to the netconfd-pro server.

netconfd-pro Features

The netconfd-pro server has the following features:

  • Complete implementation of NETCONF versions 1.0 and 1.1

  • Automatic support for all NETCONF operations, including the YANG 'insert' operation.

  • Supports <candidate>, <running>, and <startup> databases

  • Supports the complete NETCONF protocol defined in RFC 4741 and RFC 6241.

  • Supports the complete SSH transport binding defined in RFC 4742 and RFC 6242.

  • Supports the complete TLS transport binding defined in RFC 7589.

  • Supports the RESTCONF Protocol defined in RFC 8040

  • Supports the YANG Patch Media Type defined in RFC 8072

  • Supports the CallHome for NETCONF feature defined in RFC 8071

    • Supports CLI and YANG configuration of CallHome servers

  • Supports the Network Management Datastore Architecture (NMDA) in RFC 8342 and RFC 8526

  • Supports Notification Subscriptions defined in RFC 5277 and RFC 8639

  • Supports YANG 1.1 Nested Notification Messages defined in RFC 7950

  • Supports Notifications over NETCONF defined in RFC 8640

  • Supports YANG 1.1 Actions defined in RFC 7950

  • Supports YANG Push defined in RFC 8641

  • Full, automatic run-time support for any YANG-defined NETCONF content:

    • rpc statement automatically supported, so new operations can be added at run-time

    • all YANG data statements automatically supported, so new database objects can be added at run-time

    • notification statement automatically supported, so new notification event types can be added at run-time

  • Complete XML 1.0 implementation with full support for XML Namespaces

  • Complete JSON for YANG implementation (defined in RFC 7951)

  • Supports loading and unloading server instrumentation libraries and YANG files at run-time

  • Automatic support for all capability registration and <hello> message processing

  • Full, automatic generation of all YANG module <capability> contents, including features and deviations

  • Automatic session management, including unlimited number of concurrent sessions, session customization, and all database cleanup

  • Fully recoverable, automatic database editing, using a simple 3 phase callback model

      1. validate, 2) apply, 3) commit or rollback

  • Full support for database locking, editing, validation, including extensive user-callback capabilities to support device instrumentation.

  • Automatic support for all YANG validation mechanisms, including all XPath conditionals

  • Automatic subtree and full XPath filtering

  • Automatic confirmed-commit and rollback procedures

  • Automatic database audit log and change notification support

  • Complete <rpc-error> reporting support, including user-defined errors via YANG error-app-tag and error-message statements.

  • Several <rpc-error> extensions, including <bad-value> and <error-number>, for easier debugging

  • Comprehensive, fully NETCONF configurable, access control model, defined in ietf-netconf-acm.yang (RFC 8341).

  • Complete RFC 5277 Notification support, including notification replay, :interleave capability, and several useful notifications implemented in yuma-system.yang.

  • Dynamic Subscriptions to Event Streams defined in RFC 8639

  • Complete support for standard NETCONF notification events defined in RFC 6470

  • Unlimited configurable event streams for managing different types of notifications more effectively

  • Multiple configurable event streams in addition to the mandatory NETCONF event stream.

  • Complete RFC 5717 Partial Lock support with full XPath support, and all partial locking monitoring data defined in ietf-netconf-monitoring.yang.

  • Full support for all YANG constructs, including deviations

  • Full support of YANG sub-modules, including nested sub-modules

  • Multiple concurrent module versions supported (import-by-revision)

  • Multiple concurrent submodule versions supported (include-by-revision)

  • Optimized, full XPath 1.0 implementation, including all YANG extensions

  • Full implementation of the ietf-netconf-monitoring.yang data model, including the <get-schema> operation to retrieve YANG or YIN modules from the server.

  • Configurable default node handling, including full support of the <with-defaults> standard, in ietf-netconf-with-defaults.yang.

  • System information automatically supported, as defined in yuma-system.yang.

  • Comprehensive logging capabilities for easy debugging during YANG content development or normal operation.

  • Time filtering support for <get> and <get-config> requests with 'modified-since' and 'if-modified-since' per-datastore timestamps.

  • Complete RFC 7895 and RFC 8525 YANG Module Library support, including full support of the schema retrieval for YANG-API/RESTCONF protocols to retrieve YANG modules from the server and support of server-specific identifier representing the current set of modules and submodules.

  • Automatic server state monitoring support. ypwatcher program periodically checks if the server is alive and if not restart the server and write the event into syslog.

  • Runtime configuration of CLI parameters. The yumaworks-server.yang YANG module allows all CLI parameters to be edited. Some parameters can be changed at run-time and the rest can be changed to be activated on the next server restart.

  • Dynamic error messages using content from the configuration datastores to fill in custom error messages

  • Multi-language error messages can be configured and used instead of the default English error messages

  • gNMI and gRPC Protocol support

  • Maintenance Mode support

  • Ability to include or disable any YumaWorks module using configuration parameters

  • Ability to hide any “internal use” YANG module from northboard clients

  • Built-in support for OpenConfig YANG Extensions

    • openconfig-version

    • openconfig-hashed-value

    • regexp-posix

  • Runtime configuration of NETCONF over TLS Certificate to Name Mappings

Setting the Server Profile

The netconfd-pro server can behave in different ways, depending on the initial configuration parameters used.

The following parameters should be considered, and if the default behavior is not desired, then an explicit value should be provided instead:

  • --yumapro-home or $YUMAPRO_HOME setting will affect YANG search path.

  • --modpath or $YUMAPRO_MODPATH setting will affect YANG search path.

  • --loadpath or $YUMAPRO_LOADPATH setting will affect YANG module load path.

  • --datapath or $YUMAPRO_DATAPATH setting will affect startup-cfg.xml search path.

  • --target setting will select the edit target. The default is 'candidate', so this parameter must be set to choose 'running' as the edit target.

  • --with-startup setting will enable the <startup> database if set to 'true'.

  • --with-validate setting will enable the :validate capability if set to 'true'

  • --access-control setting will affect how access control is enforced. The default is fully on ('enforcing').

  • --superuser setting will affect access control, if it is enabled. The default is no superuser.

  • --default-style setting will affect how default leaf values are returned in retrieval requests. The default is 'trim'. This returns everything except leafs containing the YANG default-stmt value, by default. To report every leaf value by default, set this parameter to 'report-all'. To report only leafs not set by the server by default, use the 'explicit' enumeration.

  • --log, --log-level, and --log-pthread-level settings will affect what log messages are generated. The default is to send all messages to STDOUT, and use the 'info' logging level.

  • --log-stderr, --log-syslog, --log-syslog-level, --log-header, --log-console, and several other log related commands will also affect how log messages are generated. A detailed discussion on the action of the various logging related parameters is included in the YumaPro User Manual. All available commands are also documented in the :YumaPro CLI Reference section.

  • --eventlog-size setting will control the memory used by the notification replay buffer

  • --max-burst will control the of notifications sent at once to a single session

  • --hello-timeout will control how long sessions can be stuck waiting for a hello message before they are dropped.

  • --max-sessions will limit the number of concurrent sessions allowed

  • --max-cli-sessions will limit the number of concurrent CLI (yp-shell) sessions allowed

  • --idle-timeout will control how long active sessions can remain idle before they are dropped.

  • --subsys-timeout will control how long the server will wait for replies from a subsystem.

Loading YANG Modules

Loading Modules at Boot-Time

The --module parameter can be used from the CLI or .conf file to pre-load YANG modules and any related device instrumentation code into the server. A fatal error will occur if any module cannot be loaded, or it contains any YANG errors.

The --loadpath parameter can also be used to specify a sequence of directories to check for YANG modules. Any modules found in the path that have not already been loaded with --module or --bundle parameters will be loaded into the server.

Loading Modules at Run-Time

At run-time, the <load> operation (defined in yuma-system.yang and yumaworks-system.yang) can be used to load a YANG module. The server will return an <rpc-error> if the requested module cannot be loaded. By default, only a superuser can invoke the <load> operation. If the <save-config> parameter is set to 'true' then a module configuration file will be saved so the module will be loaded after a reboot.

Loading Bundles at Boot-Time

The --bundle parameter can be used to load a collection of YANG modules and the SIL code for those modules. It cannot be used to load a single YANG module without any SIL code available to the server. The make_sil_bundle script is used to create the C callback functions for all YANG modules in the SIL bundle. SIL code for all “external augments” data is also generated when a SIL bundle is created.

Loading Bundles at Run-Time

At run-time, the <load-bundle> operation (defined in yumaworks-system.yang) can be used to load a SIL bundle (SIL code + all YANG modules in the bundle). The server will return an <rpc-error> if the requested SIL bundle cannot be loaded. By default, only a superuser can invoke the <load-bundle> operation. If the <save-config> parameter is set to 'true' then a module configuration file will be saved so the bundle will be loaded after a reboot.

All modules imported by the explicitly specified modules will also be loaded.

leaf save-config {
  type boolean;
  default false;
  description
    "If 'true' then save the module or bundle load
     configuration in the --confdir directory, if the
     load or load-bundle operation is completed without
     errors.

     Ignored if the --no-config CLI parameter is used
     or the --confdir CLI parameter is not specified
     and no default configuration directory is found.

     A configuration file is created or replaced in this
     directory with the name <module-name>.conf.";
 }

Unloading YANG Modules

Any module that was loaded with the --module parameter or <load> operation can be unloaded with the <unload> operation. By default, only a superuser can invoke the <unload> operation. If the <delete-config> parameter is set to 'true' then the module configuration file will be deleted so the module will not be loaded after a reboot.

Modules imported by the module being unloaded are not unloaded.

Modules loaded as a bundle with the --bundle parameter can be unloaded with the <unload-bundle> operation. By default, only a superuser can invoke the <unload-bundle> operation. If the <delete-config> parameter is set to 'true' then the module configuration file will be deleted so the bundle will not be loaded after a reboot.

Modules imported by the bundle are unloaded.

If any modules not being removed are importing the module(s) being unloaded, then the operation will fail and an <rpc-error> will be returned.

leaf delete-config {
  type boolean;
  default false;
  description
    "If 'true' then delete the module or bundle load
     configuration in the --confdir directory, if the unload
     or unload-bundle operation is completed without errors.

     Ignored if the --no-config CLI parameter is used
     or the --confdir CLI parameter is not specified
     and no default configuration directory is found.

     A configuration file is deleted in this
     directory with the name <module-name>.conf.";
}

Starting netconfd-pro

The current working directory in use when netconfd-pro is invoked is important. It is most convenient to run netconfd-pro in the background, and save all output to a log file.

The netconfd-pro program listens for connection requests on a local socket, that is located in /tmp/ncxserver.sock.

In order for NETCONF sessions to be enabled, the SSH server and the netconf-subsystem-pro programs must be properly installed first.

The netconfd-pro program does not directly process the SSH protocol messages. Instead, it is implemented as an SSH subsystem. The number of concurrent SSH sessions that can connect to the netconfd-pro server at once may be limited by the SSH server configuration. Refer to the YumaPro Installation Guide for more details on configuring the SSH server for use with netconfd-pro.

The netconfd-pro program can be invoked several ways:

  • To get the current version and exit:

netconfd-pro --version
  • To get program help and exit:

netconfd-pro --help
netconfd-pro --help --brief
netconfd-pro --help --full
  • To start the server in the background, set the logging level to 'debug', and send logging messages to a log file

netconfd-pro --log-level=debug --log=~/mylog &
  • To start the server interactively, and send all log messages to STDOUT:

netconfd-pro
  • To start the server interactively, with a new log file:

netconfd-pro --log=mylogfile
  • To start the server interactively, and append to an existing log file:

netconfd-pro --log=mylogfile --log-append
  • To get parameters from a non-default configuration file:

netconfd-pro --config=/opt/conf/netconfd-pro.conf
  • To run as root and use the FHS file locations:

netconfd-pro --fileloc-fhs=true

Starting SIL-SA Subsystems with sil-sa-app

If the server is built using the WITH_YCONTROL=1 or EVERYTHING=1 make flag then it will listen for "sil-sa" service connections from SIL-SA subsystems. The sil-sa-app program can be used to support the SIL-SA libraries on a subsystem.

A subsystem can run on the same system as netconfd-pro or a different system.

A subsystem can be started before or after the main server. Connect and re-connect functionality is built into the program.

The following sil-sa-app CLI parameters are supported:

  • --address=ip-address

    • The IP address of the main server.

    • The default is to use the server on the same system as the sil-sa-app process.

    • If this parameter is used, then netconfd-pro must set the --socket-type parameter to 'tcp'.

    • If netconfd-pro uses the --socket-address parameter, then this parameter must match its value.

  • --library=string

    • The --library parameter keyword is optional. It specifies a SIL-SA library (module or bundle) that should be selected by this subsystem.

    • If any --library parameters are present, then only those SIL-SA libraries will be loaded by this subsystem, if the main server indicates that the module or bundle is loaded.

    • If no --library parameters are present then the sil-sa-app will attempt to load all SIL-SA modules and bundles reported by the server.

    • Example:

      # select libfoo_sa.so
      --library=foo
      
  • --log-level=enum

    • The output log level to use. The default is ‘info’.

  • --log=filespec

    • The output log file to use. The default is ‘stdout’

  • --port=uint16

    • The TCP port number to use, Ignored unless address is also present.

    • The default is 2023.

    • If this parameter is used, then netconfd-pro must use the --socket-type=tcp parameter.

    • If netconfd-pro uses the --socket-port parameter, then this parameter must match its value.

  • --subsys-id=string

    • The subsystem identifier to use.

    • The default is subsys1.

    • This value must be unique among all the subsystems registered on the same server.

The SIL-SA libraries loaded depends on 2 factors:

  • The <module> and <bundle> parameters included in the <register-response> message from the server. The sil-sa-app program will attempt to find the SIL-SA libraries for these modules and bundles.

  • The program will look in the /usr/lib/yumapro directory. If a library is not found, then the module will be skipped The SIL-SA libraries supported on a subsystem can be controlled by limiting which SIL-SA libraries are present.

Example: Start the server with a non-default socket

# server started
> netconfd-pro --socket-type=tcp --socket-address=192.168.0.45 --socket-port=8090

# sil-sa-app started
> sil-sa-app --subsys-id=sub1 --address=192.168.0.45 --port=8090

Example 2: Start 2 subsystems on the same host

# server started
> netconfd-pro --module=mod1 --module=mod2

# sil-sa-app started
> sil-sa-app --subsys-id=sub1 --library=mod1
> sil-sa-app --subsys-id=sub2 --library=mod2

Stopping netconfd-pro

To terminate the netconfd-pro program when running interactively, use the control-C character sequence. This will cause the server to cleanup and terminate gracefully.

The <shutdown> or <restart> operations can also be used to terminate or restart the server. The ietf-netconf-acm.yang access control rules must be configured to allow any user except the 'superuser' account to invoke this operation.

Signal Handling

The server will respond to Unix signals sent to the netconfd-pro process.

If the server is being run in the foreground, then the Control-C character sequence will perform the same action as a SIGINT signal.

Signals Recognized by netconfd-pro

Signal

Number

Description

SIGHUP (Hangup)

1

Restart the server.

SIGINT (Control-C)

2

Shutdown the server.

SIGQUIT

3

Shutdown the server.

SIGILL

4

Shutdown the server.

SIGTRAP

5

Shutdown the server.

SIGABRT

6

Shutdown the server.

SIGKILL

9

Kill the server process (No proper cleanup!)

SEGUSR1

10

Reload the server (Does a restart)

SEGUSR2

12

Logrotate (reopen log files)

SIGPIPE

13

Handle I/O connection error.

SIGTERM

15

Shutdown the server.

SIGVTALRM

26

Internal threads kill signal

The kill command in Unix can be used to send signals to a process running in the background. In order to shutdown the server properly with the kill command, use “kill -TERM” not “kill -9”. Refer to the Unix man pages for more details.

Example to shutdown the server with "kill -TERM":

# Get the PID of the server
> ps aux | grep netconfd-pro

user1  14166  0.1  0.0 163852 15616 pts/2    S+   19:10   0:00 netconfd-pro

# the first number is the PID
> kill -TERM 14166

Starting netconfd-pro with ypwatcher program

The ypwatcher is a program that provides monitoring mechanism to netconfd-pro server and its state. Ypwatcher Ypwatcher program periodically checks the server's state and determine if the server is still running. If the server is no longer running it cleans up the state, restarts the server, and generates a syslog message.

The ypwatcher program will be launched by the server by default unless --no-watcher parameter will be specified or the program is already running.

The ypwatcher program is running continuously and attempting to restart the server any time it exits unexpectedly.

The ypwatcher program will be invoked automatically whether the server starts interactively or in the background mode:

  • To start the server interactively, with the ypwatcher program:

netconfd-pro
  • To start the server interactively, with no ypwatcher program:

netconfd-pro --no-watcher

The --watcher-interval parameter specifies the sleep interval between ypwatcher program attempts to check availability of the server.

  • To start the server interactively, with ypwatcher program and set the watcher interval:

netconfd-pro --watcher-interval=10

Signal Handling with ypwatcher program

The ypwatcher program is running continuously and attempting to restart the server any time it exits unexpectedly.

Unexpected exit can be interpreted as a server's shut down process due to severe error, such as Segmentation fault, core dump, bus error, and invalid memory reference. The ypwatcher program will restart the server only if any of these termination actions causing the server to shut down.

During the RESTART and RELOAD operations the netconfd-pro and ypwatcher remains the same state and PID numbers.

With ypwatcher the server will still respond to Unix signals sent to the netconfd-pro process.

If the server is being run in the foreground, then the Control-C character sequence will perform the same action as a SIGINT signal and ypwatcher program will terminate as well.

The ypwatcher program will restart the server that shutdown because of the following signals:

Signals Recognized by ypwatcher

Signal

Number

Description

SIGBUS

7

Bus error.

SIGFPE

8

Floating Point exception.

SIGKILL

9

Kill

SIGSEGV

11

Invalid memory reference

The :kill command in Unix can be used to send signals to a process running in the background. Refer to the Unix man pages for more details.

netconfd-pro Error Handling

All of the error handling requirements specified by the NETCONF protocol, and the YANG language error extensions for NETCONF, are supported automatically by netconfd-pro.

The following CLI parameters affect error handling:

  • --errmsg : change the error-message for a specific error and language

  • --errmsg-lang : change the error-message language

  • --running-error : change boot-up error handling for <running> datastore

  • --startup-error : change boot-up error handling for loading startup configuration

There are 4 categories of error handling done by the server:

  • Incoming PDU validation

    • Errors for invalid PDU contents are reported immediately. The server will attempt to find all the errors in the input <rpc> request, and not stop detecting errors after one is found.

    • All machine-readable YANG statements are utilized to automate the detection and reporting of errors.

    • A node that is present, but has a false 'when' statement, is treated as an error.

  • Server instrumentation PDU validation

    • Semantic requirements expressed only in description statements will be checked by device instrumentation callbacks. The specific YANG data module should indicate which errors may be reported, and when they should be reported.

  • Database validation

    • Several automated tests are performed when a database is validated.

    • If the edit target is the <candidate> configuration, then referential integrity tests are postponed until the <commit> operation is attempted.

    • The specific conditions checked automatically are:

      • referential integrity condition test failed (must)

      • missing leaf (mandatory)

      • missing choice (mandatory)

      • extra container or leaf

      • too few instances of a list or leaf-list (min-elements)

      • too many instances of a list or leaf-list (max-elements)

      • instance not unique (unique)

    • Nodes that are unsupported by the server will automatically be removed from these tests. This can occur in the following ways:

      • node is defined within a feature that is not supported (if-feature)

      • node has conditional existence test that is false (when)

      • nodes derived from a 'uses' statement which has a conditional existence test that is false (when)

      • nodes derived from an 'augment' statement which has a conditional existence test that is false (when)

  • Server instrumentation database validation and activation

    • Errors can occur related to the specific YANG data model module, which can only be detected and reported by the server instrumentation.

    • Resource denied errors can occur while the server instrumentation is attempting to activate the networking features associated with some configuration parameters.

    • Instrumentation code can fail for a number of reasons, such as underlying hardware failure or removal.

Module Summary

The following YANG modules are built into the netconfd-pro server, and cannot be loaded manually with the --module parameter or <load> operation. YumaWorks modules can be disabled with various CLI parameters.

Pre-loaded YANG Modules

Module

Description

ietf-datastores.yang

NMDA datastore meta-data

ietf-inet-types.yang

standard data types

ietf-netconf-acm.yang

standard NETCONF access control model

ietf-netconf-monitoring.yang

standard NETCONF monitoring, and the <get-schema> operation

ietf-netconf-nmda.yang

NMDA <get-data> operation for NETCONF

ietf-netconf-notifications.yang

standard NETCONF notifications for system events

ietf-netconf-partial-lock.yang

standard NETCONF <partial-lock> and <partial-unlock> operations

ietf-netconf-with-defaults.yang

<with-defaults> extension

ietf-origin.yang

NMDA <operational> origin meta-data

ietf-subscribed-notifications.yang

Dynamic Notification Subscriptions from RFC 8639

ietf-x509-cert-to-name.yang

X.509 cert-to-name configuration used for NETCONF over TLS

ietf-yang-types.yang

standard data types

ietf-yang-library.yang

standard NETCONF YANG Module Library that represent the current set of modules and submodules.

ietf-yang-push.yang

Subscriptions to YANG Datastores from RFC 8641

nc-notifications.yang

standard replay notifications

netconfd-pro.yang

Server CLI parameters

notifications.yang

standard notification operations

openconfig-extensions.yang

Many OC extensions supported (used in other modules)

yuma-ncx.yang

Yuma NETCONF extensions

yuma-app-common.yang

Common CLI parameters

yuma-types.yang

Yuma common data types

yuma-mysession.yang

Get and Set session-specific parameters

yuma-system.yang

system monitoring, operations, and notifications. This module is deprecated. It is enabled by default, but can be removed using --with-yuma-system=false

yuma-time-filter.yang

Get only if datastore changed since a specified timestamp

yumaworks-app-common.yang

Common definitions used by yumapro modules

yumaworks-attrs.yang

Extensions to add last-modified and etag attributes

yumaworks-callhome.yang

Runtime configuration of CallHome server parameters

yumaworks-cert-usermap.yang

Add X.509 cert-to-name mapping configuration used for NETCONF over TLS

yumaworks-config-change.yang

Add edit data to the netconf-config-change notification

yumaworks-event-filter.yang

Event filters to suppress generation of notifications for the specified events

yumaworks-event-stream.yang

NETCONF Event stream configuration

yumaworks-extensions.yang

YANG extensions for meta-data data tagging

yumaworks-getbulk.yang

NETCONF <get-bulk> operation to easily iterate through YANG lists

yumaworks-ids.yang

Session type extensions for the standard monitoring module

yumaworks-restconf-commit.yang

Extensions to add confirmed-commit procedure to RESTCONF

yumaworks-support-save.yang

Contains the <get-support-save> operation

yumaworks-system.yang

Extensions to ietf-netconf-monitoring, plus extra protocol operations for back/restore, unload, etc.

yumaworks-term-msg.yang

<term-msg> Notification for yp-shell diagnostic messages

yumaworks-yangpush-dev.yang

YANG Push deviations to identify currently unimplemented portions

The following YANG modules are not built into the netconfd-pro server, but if specific build variable is set during the build, netconfd-pro will activate corresponding modules.

Optional YANG Modules

Module

Description

Status

ietf-restconf-monitoring.yang

Monitoring information for the RESTCONF protocol. Build variable: WITH_RESTCONF=1

current

yuma-arp.yang

collection of YANG definitions for configuring and monitoring ARP. Build variable: WITH_YUMA_ARP=1

obsolete

yuma-proc.yang

NETCONF /proc file system monitoring. Build variable: WITH_YUMA_PROC=1:

obsolete

yuma-interfaces.yang

Yuma interfaces table. Build variable: WITH_YUMA_INTERFACES=1.

obsolete

yumaworks-server.yang

Allows server CLI parameters to be edited at run-time

current

Notification Summary

There are some CLI parameters that affect notifications that need to be set (or default value used):

CLI Parameters for Notifications

Parameter

Description

--eventlog-size

Size of the replay buffer for the NETCONF event stream

--event-stream

Configure a notification event stream

--event-stream-map

Configure a module to event stream mapping

--idle-timeout

Has no affect if notification delivery is active

--log-event-drops

Report dropped notifications in the server log

--max-burst

Control number of notifications sent at once to a receiver

--system-notifications

Pick IETF or Yuma system notifications. Default is IETF. Yuma is deprecated and should not be used

--with-notifications

Must be set to true to enable notification delivery

--with-term-msg

Must be set to true to enable <term-msg> event

--with-yuma-system

Must be set to true if --system-notifications set to include yuma

The following notification event types are built into the netconfd-pro server:

Pre-loaded Notifications for :RFC:`5277` and :RFC:`7895`

Module

Event Type

Description

nc-notifications

<replayComplete> Event

Notification replay has ended

nc-notifications

<notificationComplete> Event

Notification delivery has ended

ietf-yang-library

<yang-library-change> Event

Set of modules or submodules in the YANG Library has changed

Pre-loaded Notifications if system-notifications includes “ietf” (Default)

Module

Event Type

Description

ietf-netconf-notifications

<netconf-session-start> Event

NETCONF session has started

ietf-netconf-notifications

<netconf-session-end> Event

NETCONF session has ended

ietf-netconf-notifications

<netconf-config-change> Event

<running> configuration has changed

ietf-netconf-notifications

<netconf-capability-change> Event

Server capabilities have changed

ietf-netconf-notifications

<netconf-confirmed-commit> Event

Confirmed commit procedure event

Pre-loaded Notifications if system-notifications includes “yuma” (Deprecated)

Module

Event Type

Description

yuma-system

<sysStartup>

server startup event

yuma-system

<sysSessionStart>

NETCONF session has started

yuma-system

<sysSessionEnd>

NETCONF session has ended

yuma-system

<sysConfigChange>

<running> configuration has changed

yuma-system

<sysCapabilityChange>

Server capabilities have changed

yuma-system

<sysConfirmedCommit>

Confirmed commit procedure event

Pre-loaded Notifications if yang-push bundle enabled

Module

Event Type

Description

ietf-subscribed-notifications

<replay-completed> Event

subscription replay complete

ietf-subscribed-notifications

<subscription-modified> Event

subscription configuration modified

ietf-subscribed-notifications

<subscription-terminated> Event

subscription terminated

ietf-yang-push

<push-update> Event

YANG Push Complete Update

ietf-yang-push

<push-change-update> Event

YANG Push Patch Update

Operation Summary

The following protocol operations are built into the netconfd-pro server. Some built-in modules need to be enabled to be present, but the code may be present in the server image.

Pre-loaded Operations

Module

Operation

Description

yumaworks-system.yang

<backup>

Backup the running configuration to a file

ietf-netconf.yang

<cancel-commit>

Cancel a confirmed-commit operation

yumaworks-system.yang

<cancel-subscription>

Cancel a notification subscription

yumaworks-event-stream.yang

<clear-eventlog>

Clear the replay buffer for an event stream

ietf-netconf.yang

<close-session>

Terminate the current session

ietf-netconf.yang

<commit>

Activate edits in <candidate>

ietf-netconf.yang

<copy-config>

Copy an entire configuration

notifications.yang

<create-subscription>

Start receiving notifications

yumaworks-system.yang

<delete-backup>

Delete a backup configuration file

ietf-netconf.yang

<delete-config>

Delete a configuration

ietf-subscribed-notifications.yang

<delete-subscription>

Delete a notification subscription by the owner session

ietf-netconf.yang

<discard-changes>

Discard edits in <candidate>

ietf-netconf.yang

<edit-config>

Edit the target configuration

ietf-subscribed-notifications.yang

<establish-subscription>

Start a notification subscription

ietf-netconf.yang

<get>

Retrieve <running> or state data

ietf-netconf.yang

<get-config>

Retrieve all or part of a configuration

ietf-netconf-nmda.yang

<get-data>

Retrieve data from an NMDA datastore

yumaworks-getbulk.yang

<get-bulk>

Retrieve N list entries at a time

yumaworks-system.yang

<get-ha-status>

Retrieve YP-HA status information

yumaworks-system.yang

<get-module-tags>

Retrieve the installed module-tags

yuma-mysession.yang

<get-my-session>

Retrieve session customization parameters

ietf-netconf-monitoring.yang

<get-schema>

Retrieve a YANG or YIN module definition file

yumaworks-system.yang

<get-server-version>

Retrieve the server version and build-date

ietf-netconf.yang

<kill-session>

Terminate a NETCONF session

ietf-subscribed-notifications.yang

<kill-subscription>

Delete a notification subscription by any session

yuma-system.yang

<load>

Load a YANG module and its SIL code [DEPRECATED]

yumaworks-system.yang

<load>

Load a YANG module and its SIL code

yumaworks-system.yang

<load-bundle>

Load a SIL bundle (SIL code + modules

yuma-netconf.yang

<load-config>

Internal RPC to load <running> datastore at boot-time

ietf-netconf.yang

<lock>

Lock a database

ietf-subscribed-notifications.yang

<modify-subscription>

Modify a notification subscription

yuma-system.yang

<no-op>

No operation. [DEPRECATED]

ietf-netconf-partial-lock.yang

<partial-lock>

Lock part of the <running> database

ietf-netconf-partial-lock

<partial-unlock>

Unlock part of the <running> database

yumaworks-system.yang

<refresh-backup-dir>

Refresh the backup-files monitoring data

yumaworks-internal.yang

<replay-config>

Internal RPC operation for configuration datastore synchronization

yuma-system.yang

<restart>

Restart the server. [DEPRECATED]

yumaworks-system.yang

<restore>

Restore the <running> database from a backup

ietf-yang-push.yang

<resync-subscription>

Re-synchronize a YANG Push notification subscription

yuma-system.yang

<set-log-level>

Set the logging verbosity level [DEPRECATED]

yumaworks-system.yang

<set-log-level>

Set the logging verbosity level

yuma-mysession.yang

<set-my-session>

Set the session customization parameters

yuma-system.yang

<shutdown>

Shutdown the server [DEPRECATED]

yumaworks-system.yang

<unload>

Unload a YANG module and its SIL code

yumaworks-system.yang

<unload-bundle>

Unload a SIL bundle, and all its YANG modules and SIL code

ietf-netconf.yang

<unlock>

Unlock a database

ietf-netconf.yang

<validate>

Validate a database

netconfd-pro Configuration Parameter List

The following configuration parameters are used by netconfd-pro. Refer to the YumaPro CLI Reference for more details.

netconfd-pro CLI Parameters

Parameter

Description

--access-control

Specifies how access control will be enforced

--allow-leaflist-delete-all

Allow delete-all operations on leaf-list objects

--allow-list-delete-all

Allow delete-all operations on list objects

--allowed-user

Limits sessions to specified user names

--alt-names

Specifies whether the server will recognize the 'alt-name' YANG extension which allows an alternate name to be used for a node in the database.`

--annotation

Specifies a YANG module to load as an annotations module

--audit-log

Specifies the audit log of changes to the running database, after initial load is done.

--no-audit-log

Specifies that no default audit log should be created when --fileloc-fhs is set to ‘true’

--audit-log-append

Append audit entries to the existing log if present; Otherwise start a new audit log.

--audit-log-candidate

Record transactions on the candidate datastore or not

--audit-log-console-level

Minimum debug level to generate console audit log messages

--audit-log-events

Select which events are recorded in the audit log

--audit-log-level

Minimum debug level to generate audit log messages

--autodelete-pdu-error

Treat false when-stmts in the edit PDU as errors

--binary-display-maxlen

Maximum number of bytes o display of binary data for a YANG object

--bundle

Specifies a SIL bundle to load into the server at boot-time

--callhome-reconnect

Specifies whether server will reconnect after client closes the session

--callhome-retry-interval

Specifies the number of seconds to wait after a connect attempt to the callhome server has failed before attempting another connect attempt to that server.

--callhome-retry-max

Specifies the number of retry attempts the server should attempt to the callhome server before giving up.

--callhome-server

Specifies a NETCONF over SSH callhome server that this server should attempt to initiate a callhome connection at boot-time.

--callhome-sshd-command

Specifies the command used in Call Home to invoke the SSH server

--callhome-sshd-config

Specifies the filespec for the config file used in CallHome to invoke the SSH server

--callhome-subsys-command

Specifies the command used in CallHome to invoke the netconf subsystem

--callhome-tls-server

Specifies a NETCONF over TLS CallHome server

--cert-default-user

Specifies the default user name to certificate mapping (DEBUG only)

--cert-usermap

Specifies a user-name to certificate mapping

--confdir

Specifies the directory for extra configuration parameter files

--config

Specifies the configuration file to use for parameters

--convert-subtree-filter

Convert subtree filters to XPath for internal processing

--create-empty-npcontainers

Specifies that empty NP containers should be created or not

--datapath

Specifies the search path for the <startup> configuration file.

--db-lock-retry-interval

Specifies the amount of time to wait before retrying a DB-Config-Lock

--db-lock-timeout

Specifies the amount of time to wait before giving up attempting to get a DB-Config-Lock

--default-style

Specifies the default <with-defaults> behavior

--delete-empty-npcontainers

Specifies that empty NP containers should be deleted or not (THIS PARAMETER IS OBSOLETE)

--deviation

Species a YANG module to load as a deviations module

--errmsg

Specifies a language-specific error message

--errmsg-lang

Specifies the error-message language to use

--eventlog-size

Specifies the maximum number of events stored in the notification replay buffer.

--event-stream

Configure a notification event stream

--event-stream-map

Configure a module to event stream mapping

--factory-startup

Force the startup and running datastores to contain the factory startup configuration

--feature-disable

Leaf list of features to disable

--feature-enable

Specifies a feature that should be enabled

--feature-enable-default

Specifies if a feature should be enabled or disabled by default

--fileloc-fhs

Selects Filesystem Hierarchy Standard (FHS) directory locations

--ha-enabled

Enable or disable the YP-HA feature

--ha-initial-active

Set the YP-HA active server to use at boot-time (for debugging only)

--ha-server

Specify a server to be a member of the YP-HA server pool

--ha-server-key

Unique string identifying the YP-HA server pool

--ha-sil-standby

Enable edit callbacks (SIL, etc.) while in YP-HA Standby mode

--hello-timeout

Set the number of seconds to wait for a <hello> PDU

--help

Get context-sensitive help with --brief or --full extension

--hide-module

Hide the specified module from clients

--home

Overrides the $HOME environment variable

--idle-timeout

Set the number of seconds to wait for a <rpc> PDU

--import-version-bestmatch

Enable import version best match feature

--indent

Specifies the indent count to use when writing data

--insecure-ok

Specifies if unverified client certificates will be accepted (DEBUG only)

--library-mode

Run the server in YANG library mode

--loadpath

Sets the module load path

--log

Specifies the log file to use instead of STDOUT. Refer to the Logging section for more details.

--log-append

Controls whether a log file will be reused or overwritten.

--log-backtrace

Append stack trace information to log messages.

--log-backtrace-detail

Add additional (compiler/OS dependent) detail to stack trace information.

--log-backtrace-level

Specify message level(s) for which stack trace information will be generated.

--log-backtrace-stream

Include stack trace information in the specified output stream(s)

--log-console

Specifies that log output will be sent to STDOUT after being sent to log file and/or syslog (assumes the presence of --log and/or --log-syslog/--log-vendor).

--log-event-drops

Indicates if log entry would be generated when a notification is dropped because the specific notification events are disabled with an event-filter configuration entry.`

--log-header

Include additional information (date/time/level) with log message.

--log-level

Specifies verbosity level of log message output

--log-mirroring

Synonym for --log-console.

--log-pthread-level

Specifies verbosity level of thread-specific log message output. Not active in non-threaded images.

--log-stderr

Specifies that error level log messages will be sent to STDERR.

--log-syslog

Send log message output to the syslog daemon.

--log-syslog-level

Specifies filter level for syslog message output. Message levels above the specified level are filtered from the syslog or vendor output stream.

--log-vendor

Directs log output to a registered, customer-written callback handler. Uses syslog if no handler is registered.

--match-names

Specifies how names are matched when performing UrlPath searches.

--max-burst

Specifies the maximum number of notifications to send at once

--max-cli-sessions

Specifies the maximum number of concurrent CLI sessions allowed

--max-getbulk

Specifies the maximum number of getbulk entries to request from a GET2 callback.

--max-sessions

Specifies the maximum number of concurrent sessions allowed

--max-strlen

Specifies tha maximum length of a quoted string to accept by the parser

--message-indent

Specifies the amount to indent in protocol messages

--modpath

Sets the module search path

--module

Specifies one or more YANG modules to load upon startup

--module-tagmap

Specifies a module name to module-tag mapping

--netconf-capability

Specifies a NETCONF capability URI to add to the server

--netconf-tls-address

Specifies the IP address to listen for NETCONF over TLS sessions

--netconf-tls-certificate

Specifies the X.509 certificate to use for NETCONF over TLS

--netconf-tls-key

Specifies the X.509 private key to use for NETCONF over TLS

--netconf-tls-port

Specifies the TCP port to list for NETCONF over TLS sessions

--netconf-tls-trust-store

Specifies the trust store file or directory for NETCONF over TLS

--no-config

If present, ignore the default configuration file

--no-log

Suppress the main log and set --log-level=none

--no-nvstore

Disable internal NV-load and NV-store operations

--no-startup

If present, the startup configuration will not be used (if present), and the factory defaults will be used instead.

--no-watcher

Disable the ypwatcher program

--port

Specifies up to 4 TCP port numbers to accept NETCONF connections from

--protocols

Specifies which NETCONF protocol versions to enable

--push-max-operational

Specifies the maximum number of on-change push subscriptions

--push-max-periodic

Specifies the maximum number of periodic push subscriptions

--push-min-dampening

Specifies the minimum value for the 'dampening-period' parameter

--push-min-period

Specifies the minimum value for the 'period' parameter

--push-simop-enabled

Specifies if the simulated on-change push subscriptions should be enabled

--push-simop-patch-update

Specifies the simulated on-change push subscription report type

--push-simop-period

Specifies the period that will be used for simulated operational on-change push subscription

--remove-schema-aug-leafs

Specifies whether deprecated leafs from a yumaworks-system.yang augmentation will be removed or not.

--restconf-capability

Specifies a RESTCONF capability URI to add to the server

--restconf-default-encoding

Specifies the default response message encoding for RESTCONF

--restconf-server-url

Specifies the starting string for the server URL to use in Location header lines returned by RESTCONF.

--restconf-strict-headers

Specifies how the RESTCONF server will validate Accept and Content type headers

--runpath

Server instrumentation library (SIL) search path

--running-error

Specifies whether the server should stop, continue, or fallback to factory default if the running configuration contains any errors at boot-time (such as missing mandatory nodes)

--save-owners

Specifies whether owner names will be saved as meta-data in the configuration data

--server-id

String identifying the server in the YP-HA server pool

--session-sync-mutex

If present, will force synchronous request processing (pthread version only)

--sil-delete-children-first

Specifies that the SIL callbacks for child nodes should be called on delete operations

--sil-invoke-for-defaults

Specifies whether SIL callbacks are invoked for loading defaults

--sil-missing-error

Specifies if a missing SIL library file will be treated as an error or not.

--sil-prio-reverse-for-deletes

Specifies whether the SIL callbacks are invoked in reserved order for deletes or not.

--sil-root-check-first

Force the YANG validation checks to be done before the SIL validate callbacks

--sil-skip-load

Specifies that the server should skip the SIL edit callbacks during the load datastore initialization phase.

--sil-test-get-when

Specifies the global default for evaluating when-stmts on operational data nodes during retrieval operations

--sil-validate-candidate

Controls whether SIL callbacks will be done for the candidate datastore

--simple-json-names

Specifies that the server should output name of the module in which the data node is defined or not.

--socket-address

Specifies the IPv4 address to listen on when the socket-type parameter is set to 'tcp'.

--socket-port

Specifies the TCP port number to listen on when the socket-type parameter is set to 'tcp'.

--socket-type

Specifies which type of socket the server should create for incoming <ncx-connect> protocol sessions.

--startup

Specifies the startup configuration file location to override the default. Not allowed if the --no-startup parameter is present.

--startup-error

Specifies whether the server should stop, continue, or fallback to factory default if the startup configuration contains any recoverable errors (the bad configuration data can be removed)`

--startup-factory-file

Specifies the YANG configuration to use as the factory default config

--startup-prune-ok

Specifies if unknown nodes can be pruned at boot-time from the startup config

--startup-skip-validation

If true then skip the root check YANG validation when loading the startup configuration at boot time.

--subdirs

If true, then sub-directories will be searched when looking for files. Otherwise just the specified directory will be used and none of its sub-directories (if any).

--subsys-timeout

The number of seconds to wait for a response from a sub-system before declaring a timeout.

--superuser

Specifies one or more user names to be given super user privileges. If ‘superuser’ is configured in your netconfd-pro.conf file, then that value will be overridden by your command line value.

--system-notifications

Specifies the YANG module(s) the server should use for system events such as a new session, configuration change, or capability change.

--system-sorted

Specifies whether system ordered lists and leaf-lists should be maintained in sorted order

--target

Specifies if the <candidate> or <running> configuration should be the edit target

--tls-crl-missing-ok

Specifies whether missing CRL Distribution Point is an error

--tls-crl-mode

Specifies how Certificate Revocation List processing is done

--trim-whitespace

Specifies if leading and trailing XML whitespace should be trimmed

--usexmlorder

Forces strict YANG XML ordering to be enforced

--version

Prints the program version string and exits

--wait-datastore-ready

Block client sessions until <running> datastore is ready to use

--warn-error

Treat all warnings as errors

--warn-idlen

Controls how identifier lengths are checked

--warn-linelen

Controls how line lengths are checked

--warn-off

Suppresses the specified warning number

--warn-up

Elevates the specified warning number to an error

--watcher-interval

Specifies the sleep interval between ypwatcher program attempts to check availability of the server.

--wildcard-keys

Controls whether the server will support YANG-API/RESTCONF URL requests that contain a dash character '-' to indicate all instances of that key leaf.

--with-callhome

Enable or disable the IETF CallHome protocol

--with-canonical

Enable or disable automatic conversion to canonical data type format

--with-config-id

Enable or disable the :config-id capability URI

--with-db-lock

Enable or disable the DB-Config-Lock (system-wide edit lock)

--with-gnmi

Enable or disable the gNMI protocol

--with-grpc

Enable or disable the gRPC protocol

--with-maintenance-mode

Enable or disable allowing maintenance mode to be used

--with-modtags

Enable or disable module-tags feature

--with-netconf

Enable or disable the NETCONF over SSH protocol

--with-netconf-tls

Enable or disable the NETCONF over TLS protocol

--with-nmda

Enable or disable NMDA support

--with-notifications

Controls whether the server will support the :notification and :interleave capabilities or not.

--with-ocpattern

Controls whether OpenConfig pattern syntax will be checked

--with-restconf

Enable or disable the RESTCONF protocol

--with-rollback-on-error

Enable or disable the :rollback-on-error NETCONF capability

--with-startup

Enable or disable the <startup> database

--with-support-save

Enable or disable the yumaworks-support-save.yang YANG module

--with-term-msg

Enable <term-msg> notification

--with-url

Enable or disable the :url capability

--with-url-ftp

Enable or disable FTP scheme in <url> parameter

--with-url-tftp

Enable or disable TFTP scheme in <url> parameter

--with-validate

Enable or disable the :validate capability

--with-warnings

Enable or disable the error-severity field set to warning

--with-yang-api

Enable or disable the YANG-API protocol

--with-yp-coap

Enable the YP-COAP protocol

--with-yp-coap-dtls

Enable the YP-COAP over DTLS protocol

--with-yp-shell

Enable or disable the YP-SHELL protocol

--with-yuma-time-filter

Enable or disable the yuma-time-filter.yang module

--with-yuma-system

Enable or disable the yuma-system.yang module

--with-yumaworks-callhome

Enable or disable the yumaworks-callhome.yang module

--with-yumaworks-cert-usermap

Enable or disable the yumaworks-cert-usermap.yang module

--with-yumaworks-config-change

Enable or disable the yumaworks-config-change.yang module

--with-yumaworks-event-filter

Enable or disable the yumaworks-event-filter.yang module

--with-yumaworks-event-stream

Enable or disable the yumaworks-event-stream.yang module

--with-yumaworks-getbulk

Enable or disable the yumaworks-getbulk.yang module

--with-yumaworks-ids

Enable or disable the yumaworks-ids.yang module

--with-yumaworks-system

Enable or disable the yumaworks-system.yang module

--with-yumaworks-templates

Enable or disable the yumaworks-templates.yang module

--yangapi-server-url

The starting string for the server URL to use in Location header lines returned by YANG-API. The default is 'http://localhost'.

--yumapro-home

Specifies the $YUMAPRO_HOME project root to use when searching for files

--yp-coap-address

IP address to use for YP-CoaP or YP-CoAP over DTLS protocols

--yp-coap-dtls-port

UDP port to use for YP-CoAP over DTLS protocol

--yp-coap-port

UDP port to use for YP-CoAP protocol

Editing CLI Parameters at Run-Time

The yumaworks-server.yang module allows client sessions to alter the configuration parameters for the next reboot. This module should be enabled at the command line or in the configuration parameter file for the libyumaworks_server.so library to be loaded and this feature enabled. This module can also be loaded at run-time with the <load> operation.

netconfd-pro {

  module yumaworks-server

}

If enabled, there will be a top-level configuration container named “server” that has all the CLI parameters as direct child nodes. Normal editing commands can be used to alter the parameter values.

> merge /server/max-sessions value=10

There are a small number of CLI parameters that can be edited at run-time and the new value will be activated immediately:

  • allowed-user

  • eventlog-size

  • hello-timeout:

  • idle-timeout

  • log-level

  • max-burst

  • max-cli-sessions: affects new sessions only

  • max-getbulk

  • max-sessions: affects new sessions only

  • subsys-timeout

The “server” configuration container is not saved in the normal YANG configuration data (e.g., startup-cfg.xml). Instead, the CLI configuration file (e.g., netconfd-pro.conf) will be updated when the server restarts or shuts down. This will only be done if the following conditions are met:

  • The --no-config CLI option was not used

  • The server has write permissions to rewrite the configuration file

If the server cannot save the CLI parameters upon restart or shutdown, then a warning log message will be generated. If the yumaworks-server.yang module is unloaded before the server exits then the CLI parameters will not be saved.

If the yumaworks-server module is loaded at runtime with the <load> operation, then the values set from the CLI parameters will be used to populate the /server container. This affects only the parameters that can be changed at run-time (listed above).

If the yumaworks-server module is unloaded at runtime with the <unload> operation, then the values set from the CLI parameters will be restored. This affects only the parameters that can be changed at run-time (listed above).

Using logrotate to Manage Log Files

The logrotate program on Linux can be used to archive log files automatically. This is typically done to manage the size of the log files.

The netconfd-pro supports logrotate using the USR2 signal. If this signal is sent to the server process, then the server will close and re-open its log file and audit-log file, if they are set. This will not be done if these logs are not being saved to file. Both files will be closed and re-opened, if present, even if the file was not rotated.

Logrotate config must be used with the "copytruncate" option and server should be started with --log-append parameter, this will not cause any data to be deleted from the log file.

There is a sample logrotate file located in the installed files. The following command can be used to copy it to the proper location.

> cp /usr/share/yumapro/util/netconfd-pro.logrotate /etc/logrotate.d/netconfd-pro

The standard log location (/var/log/netconfd-pro/) is used in this example logrotate configuration file. The parameter --fileloc-fhs should be set to 'true' to automatically use the standard FHS file locations.

The logrotate file shown is just an example. The lastaction/endscript directive is used to send the USR2 signal to the server, which causes the log files to be re-opened. Refer the the logrotate documentation for details on using this program.

/var/log/netconfd-pro/*.log {
   size 1M
   missingok
   rotate 4
   compress
   delaycompress
   copytruncate
   notifempty
   lastaction
      /bin/kill -USR2 `cat /var/run/netconfd-pro/netconfd-pro.pid`
   endscript
}

Evaluation Version Restrictions

The evaluation version of netconfd-pro is identical to the full version of netconfd-pro except for the following restrictions:

  • Only 250 client requests will be processed before the server starts returning errors. The server must be restarted once this limit has been reached.

  • Only 8 concurrent sessions can be active at any time. If this restriction is reached then new sessions will not be started.

  • Evaluation packages expire 100 days. the build date. An access-denied error will be generated if a program is invoked after the 100 day limit has expired. New EVAL packages are released every month so if this error message appears then you must update to a newer EVAL package.

If the server has reached the maximum number of requests, then the following error will be returned:

rpc-reply {
  rpc-error {
    error-type rpc
    error-tag operation-failed
    error-severity error
    error-app-tag no-access
    error-path /nc:rpc/nc:get
    error-message 'request limit reached in evaluation version'
    error-info {
      error-number 398
    }
  }
}

Maintenance Mode

If the --with-maintenance-mode parameter is set to 'true' (the default) then the server will allow the maintenance mode to be used. In maintenance mode, no client sessions can be started or used. Only YControl sessions can be used to allow server maintenance to occur without client session interference.

This mode cannot be set by clients. It can only be set through APIs in the server, either internally or through the DB-API service.

If maintenance mode is active, then the server will return an 'operation-failed' error-tag. The error-number will be '420' and the default error message is 'maintenance mode active'.

Disabling YumaWorks YANG Modules

There are several built-in YANG modules that the server normally loads without any extra configuration (E.g., ‘module parameter). The IETF standard modules cannot be disabled but the proprietary YumaWorks modules can be enabled or disabled with CLI parameters.

The following table describes the built-in modules that can be disabled:

Parameter

Module

Description

--hide-module

any

Hide the specified module from client discovery. Does not affect data returned to clients.

--with-support-save

yumaworks-support-save.yang

<get-support-save> gathers support information. Must build source WITH_SUPPORT_SAVE=1

--with-term-msg

yumaworks-term-msg.yang

<term-msg> notification used to support yp-shell terminal diagnostic messages

--with-yuma-system

Yuma /system container, various operations, various notifications. This module is deprecated and default parameter value is false

--with-yuma-time-filter

yuma-time-filter.yang

if-modified-since filter for <get> and <get-config>

--with-yumaworks-callhome

yumaworks-callhome.yang

Run-time configuration or NETCONF CallHome connections.

--with-yumaworks-cert-usermap

yumaworks-cert-usermap.yang

Configure NETCONF over TLS 'cert-to-name' mappings

--with-yumaworks-config-change

yumaworks-config-change.yang

Add edit data to <netconf-config-change> Event notification (Security Risk!! Review YANG module before use!!)

--with-yumaworks-event-filter

<event-filters> container to drop specific event types

--with-yumaworks-event-stream

<event-streams> container to configure event streams and <clear-eventlog> RPC operation

--with-yumaworks-getbulk

<get-bulk> operation to retrieve YANG list entries

--with-yumaworks-ids

yumaworks-ids.yang

Contains transport identity values to add YControl and direct sessions to ietf-netconf-monitoring.yang <session> list

--with-yumaworks-system

Various operations and augments of <get> and <get-config> operations with additional filters. Dynamic module/bundle <load> and <unload> operations are included in this module.

--with-yumaworks-templates

yumaworks-templates.yang

/templates container and 'with-template' parameter added to the <edit-config> operation. Must build the server source WITH_TEMPLATES=1.

DB-Config-Lock Mode

The DB-Config-Lock mode allows the netconfd-pro to participate in a system-wide lock for modification of the <running> configuration datastore contents. Use of this system-wide lock require that the server is built using WITH_YCONTROL=1. The 'db_api.c' module contains APIs to allow the server and the “local” system to request and release the DB-Config-Lock.

The following CLI parameters affect DB-Config-Lock mode:

The DB-Config-Lock is described in the YANG module yumaworks-db-api.yang.

The following DB-API messages are used:

  • db-lock-init: Initialize the DB-Config-Lock service. The server will not allow any configuration modifications, including booting the startup configuration, until this message is properly handled by the server.

  • db-lock: The server sends this message to the DB-Config-Lock subsystem before the Apply/Commit/Rollback portion of an edit transaction to the <running> configuration, The validate phase callbacks are invoked without any DB-Config-Lock.

  • db-unlock: The server sends this event to a subsystem to release a DB-Config-Lock.

Configuration edits by all clients are affected by this lock.

Deferred Configuration Load Mode

It is possible in certain server configurations and deployments that the server will defer loading the running configuration at boot-time. Client sessions will be allowed but access to datastores is disabled.

If desired, all client protocol sessions (e.g., NETCONF, RESTCONF) can be blocked in this state.

Use the --wait-datastore-ready=true setting in the CLI parameters or parameter configuration file (e.g., netconfd-pro.conf).

Use the <get-ha-status> operation to retrieve some HA state information that might provide more details

The following corner-cases will cause the server to return “wrong config state” or “access-denied” errors while the server is waiting to be able to load the configuration:

  • YP-HA Standby Mode: the server is waiting to connect to the YP-HA Active Server

  • YP-HA Role Unknown: YP-HA is enabled but the YP-HA role is not known yet

  • SIL-SA Bundle Mode: the server has loaded 1 or more bundles that did not have SIL libraries found. This causes the server to wait for SIL-SA subsystems to register the missing bundles so all modules can be known

  • DB-Config-Lock Init Mode: The DB-Config-Lock mode is enabled but the DB-API subsystem providing this service has not registered or has terminated the Ycontrol session.

Capabilities

Server capabilities are the primary mechanism to specify optional behavior in the NETCONF protocol. This section describes the capabilities that are supported by the netconfd-pro server.

:base:1.0

The :base:1.0 capability indicates that the RFC 4741 version of the NETCONF protocol is supported.

This capability can be controlled with the --protocols CLI parameter.

This capability is supported by default, but it will not be present if the --with-netconf parameter is set to 'false'.

:base:1.1

The :base:1.1 capability indicates that the RFC 6241 version of the NETCONF protocol is supported.

This capability can be controlled with the --protocols CLI parameter.

This capability is supported by default, but it will not be present if the --with-netconf parameter is set to 'false'.

:candidate

The :candidate capability indicates that database edits will be done to the <candidate> database, and saved with the <commit> operation.

The <candidate> configuration is a shared scratch-pad, so it should be used with the locking. Database edits are collected in the <candidate> and then applied, all or nothing, to the <running> database, with the <commit> operation.

This capability is supported by default. It is controlled by the --target configuration parameter (--target=candidate).

By default, only a superuser account can use the <delete-config> operation on the <candidate> configuration.

:config-id

The :config-id capability indicates the current configuration ID of the running datastore. It can be used by clients to cache the running configuration. The config-id attribute returned in the <rpc-reply> message for a <get-config> operation. If this value matches the value in a <hello> message, then the client knows the current configuration is the same as the cached value. This capability can be enabled or disabled with the --with-config-id CLI parameter.

:confirmed-commit

The :confirmed-commit capability indicates that the server will support the <confirmed> and <confirm-timeout> parameters to the <commit> operation. If the 'base:1.1' protocol version is in use, then the <persist> and <persist-id> parameters are also supported.

The confirmed commit procedure requires that two <commit> operations be used to apply changes from the candidate configuration to the running configuration.

If the second <commit> operation is not received before the <confirm-timeout> value (default 10 minutes), then the running and candidate configurations will be reset to the contents of the running configuration, before the first <commit> operation.

If the session that started the confirmed-commit procedure is terminated for any reason before the second <commit> operation is completed, then the running configuration will be reset, as if the confirm-timeout interval had expired.

If the confirmed-commit procedure is used, and the :startup capability is also supported, then the contents of NV-storage (e.g., startup-cfg.xml) will not be updated or altered by this procedure. Only the running configuration will be affected by the rollback,

If the <confirmed> parameter is used again, in the second <commit> operation, then the timeout interval will be extended, and any changes made to the candidate configuration will be committed. If the running and candidate configurations are reverted, any intermediate edits made since the first <commit> operation will be lost.

:interleave

The :interleave capability indicates that the server will accept <rpc> requests other than <close-session> during notification delivery. It is supported at all times, and cannot be configured. This capability is disabled if the --with-notifications CLI parameter is ‘false’.

:netconf-monitoring

The :netconf-monitoring capability indicates that the ietf-netconf-monitoring.yang data sub-trees are supported.

  • The /netconf-state/capabilities subtree can be examined to discover the active set of NETCONF capabilities.

  • The /netconf-state/datastores subtree can be examined to discover the active database locks.

  • The /netconf-state/schemas subtree can be examined for all the YANG modules that are available for download with the <get-schema> operation.

  • The /netconf-state/sessions subtree can be examined for monitoring NETCONF session activity.

  • The /netconf-state/statistics subtree can be examined for monitoring global NETCONF counters.

:notification

The :notification capability indicates that the server will accept the <create-subscription> operation, and deliver notifications to the session, according to the subscription request.

All <create-subscription> options and features are supported.

A notification log is maintained on the server, which is restarted every time the server reboots.

This log can be accessed as a 'replay subscription'.

The <replayComplete> Event and <notificationComplete> Event types are not stored in the log.

This capability can be enabled and disabled with the --with-notifications CLI parameter.

:partial-lock

The :partial-lock capability indicates that RFC 5717 is implemented, and partial locking of the <running> database is supported with the <partial-lock> and <partial-unlock> operations.

The <copy-config> operation is not supported using the <running> database as a target, so partial locks do not affect that operation.

The <edit-config> operation on the <running> database is allowed if the --target parameter is set to 'running'.

The <commit> operation will fail if any portion of the altered configuration is locked by another session. Data in the <candidate> database which is identical to the corresponding data in the <running> configuration is not affected by a <partial-lock> operation.

The constant VAL_MAX_PLOCKS in ncx/val.h controls the maximum number of concurrent locks that a single session can own on a database node. The default value is 4.

There is no hard resource limit for:

  • the number of total partial-locks

  • the number of <select> parameters in the <partial-lock> request

  • the number of nodes that can be locked by a single partial-lock

When the maximum <lock-id> is reached (MAX_UINT), the server will not reset the <lock-id> to '1' unless there are no partial locks currently held on the <running> database. The <lock-id> '0' is not used.

:rollback-on-error

The :rollback-on-error capability indicates that the server supports 'all-or-nothing' editing for a single <edit-config> operation. This is a standard enumeration value for the <error-option> parameter.

  • The server will perform all PDU validation no matter what <error-option> is selected.

  • Execution phase will not occur if any errors at all are found in the validation phase.

During execution phase, this parameter will affect error processing. When set to 'rollback-on-error', if any part of the requested configuration change cannot be performed, the database will be restored to its previous state, and server instrumentation callbacks to 'undo' any changes made will be invoked.

This capability can be enabled or disabled with the --with-rollback-on-error CLI parameter.

:schema-retrieval

The :schema-retrieval capability indicates that the <get-schema> operation is supported.

The netconfd-pro server supports this operation for all YANG modules in use at the time.

The <identifier> parameter must be set to the name of the YANG module.

The <format> parameter must be set to 'YANG'.

The <version> parameter must be set to a revision date to retrieve a specific version of the module, or the empty string to retrieve whatever version the server is using.

:startup

The :startup capability indicates that the <startup> configuration is supported by the server.

This capability is controlled by the --with-startup configuration parameter. If this parameter is set to 'true', then the ':startup' capability will be supported.

If this capability is supported:

  • the server will allow the <startup> configuration to be the source of a <get-config>.

  • the server will allow the <startup> configuration to be the target of a <copy-config> operation, if the source is the <running> configuration.

  • If the :validate capability is enabled, then the server will allow the <startup> configuration to be the target of a <validate> operation.

  • If the user is a superuser account, or access is configured in NACM to allow it, then the server will allow the <startup> configuration to be the target of a <delete-config> operation.

No other operations on the <startup> database are supported. The <startup> database cannot be edited with <edit-config>, or over-written with <copy-config>.

:validate

The :validate capability indicates that the <validate> operation is accepted, and the <test-option> for the <edit-config> operation is also accepted, by the server.

Versions supported:

  • validate:1.0

  • validate:1.1

This capability is controlled by the --with-validate configuration parameter. If it is set to 'false' then this capability will not be available in netconfd-pro.

The <validate> operation can be invoked in several ways:

  • validate the <candidate> database if the :candidate capability is supported

  • validate the <running> database

  • validate the <startup> database if the :startup capability is supported

  • validate an in-line <config> element, which represents the entire contents of a database.

The <test-option> parameter for the <edit-config> operation can be used. This parameter has a significant impact on operations, and needs to be used carefully.

  • set: This option is not the default, but it is probably the desired behavior for the <candidate> database. In order to fully utilize the incremental editing capability of this database, the 'set' value should be used.

    This will prevent any validation error messages unrelated to the current edit. The <validate> operation can be used before the <commit> is done, if desired. The same errors (if any) should be reported by <validate> or <commit>.

  • test-then-set: This option is the default, and will cause a resource intensive validation procedure to be invoked every time the <candidate> database is edited. (The validation procedure is always invoked on every edit to the <running> configuration).

    If any database validation errors are found (in addition to the requested edit), then they will be reported. Use the <error-path> field to determine which type of error is being reported by the server.

    Note

    The NETCONF default test-then-set can be resource intensive and does not need to be used since any <commit> operation will also perform the validation tests.

:url

The :url capability indicates that the server accepts the <url> parameter in NETCONF operations that use this parameter. This capability can be disabled with the --with-url CLI configuration parameter.

The following operations are affected by the :url capability:

  • <edit-config>

    • <url> accepted instead of <config> as a configuration data source

  • <copy-config>

    • <url> accepted as a source parameter.

    • <url> accepted as a target parameter.

    • <url> to <url> copy not supported (optional to implement)

  • <delete-config>

    • <url> accepted as source to delete

  • <validate>

    • <url> accepted as a configuration source to validate.

Supported Schemes:

  • The 'file' scheme is supported and enabled if --with-url is set to ‘true’.

  • The ‘ftp’ scheme is available if the --with-url-ftp CLI parameter is set to ‘true’.

  • The ‘tftp’ scheme is available if the --with-url-tftp CLI parameter is set to ‘true’.

A URL file can be specified as a simple file within the root directory.

No whitespace or special characters are allowed in the file name.

The file extension '.xml' should be used. The server only generates and expects XML configuration files. The NETCONF 'config' element is used as the top-level element in all <url> files.

The $YUMAPRO_DATAPATH environment variable or the $$datapath system variable is used to find the file names specified in the <url> URI string.

Example:

<url>file:///my-backup.xml</url>

:with-defaults

The :with-defaults capability indicates that the server will accept the <with-defaults> parameter for the following operations:

There are 4 values defined for this parameter. The server supports all of them, no matter what mode is used for the default style.

  • report-all: all nodes are reported

  • report-all-tagged: all nodes are reported with an XML attribute indicating the nodes which are considered default nodes by the server.

  • trim: nodes set to their YANG default-stmt value by the server or the client are skipped

  • explicit: nodes set by the server are skipped. (Nodes set in the <startup> are considered to be set by the client, not the server.)

The --default-style configuration parameter is used to control the behavior the server will use for these operations when the <with-defaults> parameter is missing. The server will also use this default value when automatically saving the <running> configuration to non-volatile storage.

:writable-running

The :writable-running capability indicates that the server uses the <running> configuration as its edit target. In this case, the <target> parameter for the <edit-config> operation can only be set to <running>.

All edits are activated immediately, but only if the entire database is going to be valid after the edits. A non-destructive test is performed before activating the requested changes.

If this capability is advertised, then netconfd-pro will also advertise the :startup capability. They are always used together.

Edits to the <running> configuration take affect right away, but they are only saved to non-volatile storage automatically if the --with-startup configuration parameter is set to 'false'.

:xpath

The :xpath capability indicates that XPath filtering is supported for the <get>, <get-config>, and <get-data> operations. This is a built-in capability that cannot be disabled.

The netconfd-pro server implements all of XPath 1.0, plus the following additions:

  • the 'current' function from XPath 2.0 is supported

  • a missing XML namespace will match any YANG module namespace (XPath 2.0 behavior) instead of matching the NULL namespace (XPath 1.0 behavior)

  • the 'preceding' and 'following' axes should not be used. The database is dynamic and the relative document order is not stable. This is also a very resource intensive operation.

  • Refer the the XPath Usage <https://datatracker.ietf.org/doc/html/rfc8407#section-4.6> section of RFC 8407 for more details on XPath usage.

XPath filtering affects whether the server will return particular subtrees or not. It does not change the format of the <get> or <get-config> output. The result returned by the server will not be the raw XPath node-set from evaluating the specified 'select' expression against a database.

The server will normalize the XPath search results it returns:

  • There will be no duplicate nodes, even if there were duplicates in the XPath result node-set.

  • All result nodes with common ancestor nodes will be grouped together in the <rpc-reply>.

  • All list nodes will include child nodes for any missing key leafs, even if they were not requested in the 'select' expression.

:yang-library

The :yang-library capability indicates that the server supports YANG Library mechanism for announcing conformance information. This capability is coupled to the ietf-yang-library.yang module.

The server announces the modules it implements by implementing the YANG module ietf-yang-library.yang and listing all implemented modules for a client to retrieve.

There are 2 versions of this module in use:

  • :yang-library:1.0 defined in RFC 7950

    • The YANG module in RFC 7985 is used

    • The subtree /modules-state contains the library information

    • Identified by revision date 2016-06-21

    • The server will advertise the required capability in the <hello> message. It has the form:

      urn:ietf:params:netconf:capability:yang-library:1.0?revision=<date>&module-set-id=<id>
      

      where <date> and <id> are replaced by the proper values.

  • :yang-library:1.1 defined in RFC 8526

    • The YANG module in RFC 8525 is used

    • The subtree /yang-library contains the library information

    • Identified by revision date 2019-01-04

    • This version is used if the --with-nmda=true setting is used

    • The server will advertise the required capability in the <hello> message. It has the form:

      urn:ietf:params:netconf:capability:yang-library:1.1?revision=<date>&content-id=<content-id-value>
      

      where <date> and <content-id-value> are replaced by the proper values.

Note

The 2 YANG Library revisions are very different in structure. Both variants are present in the server, if NMDA is used.

The parameter "revision" has the same value as the revision date of the ietf-yang-library.yang module implemented by the server.

The parameter "module-set-id" has the same value as the leaf /modules-state/module-set-id.

If the value of this leaf changes, the server also generates a <yang-library-change> Event notification, with the new value of "module-set-id".

With this mechanism, a client can cache the supported modules for a server and only update the cache if the "module-set-id" value in the <hello> message changes.

Databases

A NETCONF database is conceptually represented as an XML instance document.

../_images/database_variants.png

There are 3 conceptual databases, which all share the exact same structure.

  • <candidate>: scratch-pad to gather edits to apply to <running> all at once

  • <running>: configuration data in effect

  • <startup>: configuration data for the next reboot

When the <running> configuration is saved to non-volatile storage, the top-level element of this document is the <config> container element.

The XML namespace of this element is the netconfd-pro module namespace, but a client application should expect that other server implementations may use a different namespace, such as the NETCONF namespace, or perhaps no namespace at all for this top-level element.

When database contents are returned in the <get>, <get-config>, or <copy-config> operations, the top-level container will be the <data> element in the NETCONF base namespace.

The top-level YANG module data structures that are present in the configuration will be present as child nodes of the <config> or <data> container node.

The exact databases that are present in the server are controlled by 3 capabilities:

The edit target in the server is set with the --target configuration parameter. This will select either the :candidate or :writable-running capabilities.

The server behavior for non-volatile storage of the <running> configuration is set with the --with-startup configuration parameter. The :startup capability will be supported if this parameter is set to 'true'.

The following diagram shows the 4 database usage modes that netconfd-pro supports:

Database Locking

It is strongly suggested that the <lock> and <unlock> operations be used whenever a database is being edited. All the databases on the server should be locked, not just one, because different operations are controlled by different locks. The only way to insure that the entire database transaction is done in isolation is to keep all the databases locked during the entire transaction.

The affected configurations should be locked during the entire transaction, and not released until the edits have been saved in non-volatile storage.

If the edit target is the <candidate> configuration, then the <candidate> and <running> configurations should be locked.

If the edit target is the <running> configuration, then the <running> and <startup> configurations should be locked.

Whenever the lock on the <candidate> configuration is released, a <discard-changes> operation is performed by the server. This is required by the NETCONF protocol.

Of the <candidate> configuration contains any edits, then a lock will fail with a 'resource-denied' error. In this case, a lock on the <candidate> configuration cannot be granted until the <discard-changes> operation is completed.

Using the <candidate> Database

The <candidate> database is available if the :candidate capability is advertised by the server.

The <lock> operation will fail on this database if there are any edits already pending in the <candidate>. If a 'lock-failed' error occurs and no session is holding a lock, then use the <discard-changes> operation to clear the <candidate> buffer of any edits.

Once all the edits have been made, the <validate> operation can be used to check if all database validation tests will pass. This step is optional.

Once the edits are completed, the <commit> operation is used to activate the configuration changes, and save them in non-volatile storage.

The <discard-changes> operation is used to clear any edits from this database.

Using the <running> Database

The <running> database is available at all times for reading.

If the :writable-running capability is advertised by the server, then this database will be available as the target for <edit-config> operations.

Edits to the <running> configuration will take affect right away, as each <edit-config> operation is completed.

Once all the edits are completed, the <copy-config> operation can be used to save the current <running> configuration to non-volatile storage, by setting the target of the <copy-config> operation to the <startup> configuration.

Using the <startup> Database

The <startup> database is available if the :startup capability is advertised by the server.

The <copy-config> operation can be used to save the contents of the <running> configuration to the <startup> configuration.

The <get-config> operation can be used to retrieve the contents of the <startup> configuration.

The <delete-config> operation can be used to delete the <startup> configuration. Only a superuser account is allowed to do this, by default.

Sessions

All NETCONF server access is done through the NETCONF protocol, except the server can be shutdown with the Control-C character sequence if it being run interactively.

This section describes any netconfd-pro implementation details which may NETCONF sessions.

User Names

The user name string associated with a NETCONF session is derived from the $SSH_CONNECTION environment variable, which is available to the netconf-subsystem-pro program when it is called by sshd.

Any user name accepted by sshd will be accepted by netconfd-pro.

  • A user name cane be 1 to 63 characters long.

  • The first character must be a letter ['a' to 'z', or 'A' to 'Z']

  • The remaining characters must be a letter ['a' to 'z', or 'A' to 'Z'], or a number ['0' to '9'].

Session ID

The <session-id> assigned by the server is simply a monotonically increasing number:

typedef SessionId {
  description "NETCONF Session Id";
  type uint32 {
    range "1..max";
  }
}

The server will start using session ID values over again at 1, if the maximum session-id value is ever reached.

Server <hello> Message

The netconfd-pro server will send a <hello> message if a valid SSH2 session to the netconf subsystem is established.

The server will list all the capabilities it supports.

The YANG module capability URI format is supported for all modules, including ones that only contain typedefs or groupings.

The URI format is defined in the YANG specification, and follows this format:

<module-namespace>?module=<module-name>&revision=<module-date>

If the module does not have any revision statements, then the revision field will not be present in the module capability URI.

If the module contains any supported features, then the following field will be added, and each supported feature name will be listed:

&features=<feature-name>[,<feature-name>]*

If the module needs any external deviations applied, then the following field will be added, and each deviation module name will be listed:

&deviations=<deviation-module-name>[,<deviation-module-name>]*

Note

The deviation modules will be listed in the capabilities, along with other modules. The 'deviations' extension allows a client tool to know that the deviations apply to the specific module, since special processing may be required.

Example server <hello> Message:

<?xml version="1.0" encoding="UTF-8"?>
<hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <capabilities>
    <capability>urn:ietf:params:netconf:base:1.0</capability>
    <capability>urn:ietf:params:netconf:base:1.1</capability>
    <capability>urn:ietf:params:netconf:capability:candidate:1.0</capability>
    <capability>urn:ietf:params:netconf:capability:confirmed-commit:1.0</capability>
    <capability>urn:ietf:params:netconf:capability:confirmed-commit:1.1</capability>
    <capability>urn:ietf:params:netconf:capability:rollback-on-error:1.0</capability>
    <capability>urn:ietf:params:netconf:capability:validate:1.0</capability>
    <capability>urn:ietf:params:netconf:capability:validate:1.1</capability>
    <capability>urn:ietf:params:netconf:capability:url:1.0?scheme=file</capability>
    <capability>urn:ietf:params:netconf:capability:xpath:1.0</capability>
    <capability>urn:ietf:params:netconf:capability:notification:1.0</capability>
    <capability>urn:ietf:params:netconf:capability:interleave:1.0</capability>
    <capability>urn:ietf:params:netconf:capability:partial-lock:1.0</capability>
    <capability>urn:ietf:params:netconf:capability:with-defaults:1.0?basic-mode=explicit&amp;also-supported=trim,report-all,report-all-tagged</capability>
    <capability>urn:yumaworks:params:xml:ns:netconf:config-id?id=127</capability>
    <capability>urn:ietf:params:xml:ns:netconf:base:1.0?module=ietf-netconf&amp;revision=2011-06-01&amp;features=candidate,confirmed-commit,rollback-on-error,validate,url,xpath</capability>
    <capability>urn:ietf:params:xml:ns:yang:iana-crypt-hash?module=iana-crypt-hash&amp;revision=2014-08-06&amp;features=crypt-hash-md5,crypt-hash-sha-256,crypt-hash-sha-512</capability>
    <capability>urn:ietf:params:xml:ns:yang:ietf-inet-types?module=ietf-inet-types&amp;revision=2013-07-15</capability>
    <capability>urn:ietf:params:xml:ns:yang:ietf-netconf-acm?module=ietf-netconf-acm&amp;revision=2018-02-14</capability>
    <capability>urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring?module=ietf-netconf-monitoring&amp;revision=2010-10-04</capability>
    <capability>urn:ietf:params:xml:ns:yang:ietf-netconf-notifications?module=ietf-netconf-notifications&amp;revision=2012-02-06</capability>
    <capability>urn:ietf:params:xml:ns:netconf:partial-lock:1.0?module=ietf-netconf-partial-lock&amp;revision=2009-10-19</capability>
    <capability>urn:ietf:params:xml:ns:yang:ietf-netconf-with-defaults?module=ietf-netconf-with-defaults&amp;revision=2011-06-01</capability>
    <capability>urn:ietf:params:xml:ns:yang:ietf-restconf?module=ietf-restconf&amp;revision=2017-01-26</capability>
    <capability>urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring?module=ietf-restconf-monitoring&amp;revision=2017-01-26</capability>
    <capability>urn:ietf:params:xml:ns:yang:ietf-yang-library?module=ietf-yang-library&amp;revision=2016-06-21</capability>
    <capability>urn:ietf:params:xml:ns:yang:ietf-yang-patch?module=ietf-yang-patch&amp;revision=2017-02-22</capability>
    <capability>urn:ietf:params:xml:ns:yang:ietf-yang-types?module=ietf-yang-types&amp;revision=2013-07-15</capability>
    <capability>urn:ietf:params:xml:ns:netmod:notification?module=nc-notifications&amp;revision=2008-07-14</capability>
    <capability>urn:ietf:params:xml:ns:netconf:notification:1.0?module=notifications&amp;revision=2013-03-15</capability>
    <capability>urn:ietf:params:xml:ns:yang:yang-data-ext?module=yang-data-ext&amp;revision=2017-07-03</capability>
    <capability>http://netconfcentral.org/ns/yuma-app-common?module=yuma-app-common&amp;revision=2017-07-25</capability>
    <capability>http://netconfcentral.org/ns/yuma-ncx?module=yuma-ncx&amp;revision=2015-10-16</capability>
    <capability>http://netconfcentral.org/ns/yuma-system?module=yuma-system&amp;revision=2013-07-15</capability>
    <capability>http://netconfcentral.org/ns/yuma-time-filter?module=yuma-time-filter&amp;revision=2012-11-15</capability>
    <capability>http://netconfcentral.org/ns/yuma-types?module=yuma-types&amp;revision=2019-11-29</capability>
    <capability>http://yumaworks.com/ns/yumaworks-app-common?module=yumaworks-app-common&amp;revision=2019-05-22</capability>
    <capability>http://yumaworks.com/ns/yumaworks-event-filter?module=yumaworks-event-filter&amp;revision=2014-02-09</capability>
    <capability>http://yumaworks.com/ns/yumaworks-extensions?module=yumaworks-extensions&amp;revision=2019-01-04</capability>
    <capability>http://yumaworks.com/ns/yumaworks-getbulk?module=yumaworks-getbulk&amp;revision=2018-04-06</capability>
    <capability>http://yumaworks.com/ns/yumaworks-ids?module=yumaworks-ids&amp;revision=2014-07-12</capability>
    <capability>urn:ietf:params:xml:ns:yang:yumaworks-restconf?module=yumaworks-restconf&amp;revision=2017-07-03</capability>
    <capability>urn:ietf:params:xml:ns:yang:yumaworks-support-save?module=yumaworks-support-save&amp;revision=2017-07-27</capability>
    <capability>http://yumaworks.com/ns/yumaworks-system?module=yumaworks-system&amp;revision=2019-01-22</capability>
    <capability>http://yumaworks.com/ns/yumaworks-templates?module=yumaworks-templates&amp;revision=2017-02-20</capability>
    <capability>http://yumaworks.com/ns/yumaworks-term-msg?module=yumaworks-term-msg&amp;revision=2019-05-05</capability>
    <capability>http://yumaworks.com/ns/yumaworks-types?module=yumaworks-types&amp;revision=2018-05-03</capability>
    <capability>urn:ietf:params:netconf:capability:yang-library:1.0?revision=2016-06-21&amp;module-set-id=3783</capability>
  </capabilities>
  <session-id>3</session-id>
</hello>

Client <hello> Message

The netconfd-pro server requires a valid <hello> message from the client before accepting any <rpc> requests.

Only the mandatory 'netconf base' URIs will be checked by the server. All other <capability> elements may be ignored by the server.

The server can be configured with the --protocols CLI parameter to enable the 'base:1.0', and/or the 'base:1.1' NETCONF protocol versions. By default, the server will enable both protocol versions.

Both the client and server send the 'base:1.x' (where 'x' is '1' or '2') URIs they support (1 or 2 <capability> elements). The highest version in common determines the protocol version used for the session.

The following table shows the outcomes of all possible <hello> processing scenarios:

[ none ]

[ any combination ]

Session dropped

[ base:1.0 ]

[ base:1.0 ]

base:1.0 session started

[ base:1.1 ]

[ base:1.0 ]

Session dropped

[ base:1.0 base:1.1]

[ base:1.0 ]

base:1.0 session started

[ base:1.0 ]

[ base:1.1 ]

Session dropped

[ base:1.1 ]

[ base:1.1 ]

base:1.1 session started

[ base:1.0 base:1.1]

[ base:1.1 ]

base:1.1 session started

[ base:1.0 ]

[ base:1.0 base:1.1 ]

base:1.0 session started

[ base:1.1 ]

[ base:1.0 base:1.1 ]

base:1.1 session started

[ base:1.0 base:1.1]

[ base:1.0 base:1.1 ]

base:1.1 session started

Example client <hello> Message:

<?xml version="1.0" encoding="UTF-8"?>
<nc:hello xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0">
  <nc:capabilities>
    <nc:capability>urn:ietf:params:netconf:base:1.0</nc:capability>
  </nc:capabilities>
</nc:hello>

Note

If there are no common versions found, the session will be dropped.

RPC Request Processing

The only PDU the netconfd-pro server will accept during a NETCONF session is the <rpc> message.

All aspects of NETCONF protocol conformance are supported for contents of the <rpc> elements:

  • All XML attributes in the <rpc> start tag will be returned to the client (unchanged) in the <rpc-reply> element. The order of the XML attributes may not be preserved.

  • All XML namespace prefix assignments declared in the <rpc> element (via the 'xmlns' attribute) will be used within the <rpc-reply>, and most descendant nodes of the <rpc-reply. The exception is the <error-path> element, which may use the default XML prefix for a given module, by declaring a new xmlns attribute for the namespace.

  • The so-called mandatory 'message-id' attribute is ignored by the server, along will all other XML attributes in the <rpc> element. The server will not generate an error if this attribute is missing, as specified in RFC 4741. The new version of the NETCONF protocol removes this rule.

All <rpc> element contents must be declared within the proper namespace, except the contents of a subtree <filter> element for a <get> or <get-config> operation.

Access control will be enforced as follows:

  • All <rpc> operation requests except <close-session> will be checked in the access control model (:ref:ietf-netconf-acm.yang). This operation can always be invoked by any user, to allow graceful session termination in all cases.

  • If the user name for the session matches a --superuser configuration parameter, then the operation will always be allowed.

  • If the access control 'no-rule' default for RPC execution is set to 'permit', and there is no access control rule found to match the current <rpc> request, the the operation will always be allowed. The default for this parameter is 'permit'.

  • If a matching access control rule is found, execution access will be permitted or denied, based on the specific rule, (i.e., 'exec' privilege bit set or not).

  • If the operation reads or writes any database data, then the access control model will be checked again, for each database node specified in the request.

    • If the operation is requesting read access, then any nodes for which read permission is not granted will simply be skipped in the result. No error or warning will be reported.

    • If the operation is requesting write access, then any nodes for which write permission is not granted will cause an 'access-denied' error.

The server does not generate inline <rpc-error> elements at this time, for any runtime exceptions that occur while retrieving data for a <get>, <get-config>, or <copy-config> operation. Instead, unavailable nodes are just skipped.

A future version will support this feature, so managers should expect that <rpc-error> might appear within the data in a reply, not just a child node of the <rpc-reply> element.

Session Termination

A session can terminate for several reasons:

When a session terminates, the server does the following:

  • release any locks the session had (if any)

  • discard all changes in the <candidate> configuration, if this database was locked by the session.

  • remove the <session> list entry from the /netconf-state/sessions container

  • generate a <netconf-session-end> Event notification for the closed or killed session

Error Reporting

All errors are reported using the standard <rpc-error> element.

If the operation does not return any data, then the <rpc-reply> element will either contain 1 <ok/> element, or 1 or more <rpc-error> elements.

If the operation returns any data (i.e., the YANG rpc definition for the operation has an 'output' section), then the <rpc-reply> element may have both <rpc-error> and data elements within it. If there were errors in the input, then only 1 or more <rpc-error> elements will be returned. It is possible that the required data will be returned, after any errors, but not likely.

The internal netconfd-pro error code for each <rpc-error> is returned in an <error-info> extension called <error-number>.

Normally, the same <error-app-tag> and <error-message> values are returned for a specific error number. However, some YANG errors allow these fields to be user-defined. If there is a user-defined <error-app-tag> and/or <error-message> values, then they will be used instead of the default values.

This section describes the netconfd-pro implementation details which may affect <rpc-error> processing by a client application.

<error-severity> Element

The <error-severity> field will usually be set to 'error'. There are no warnings generated by netconfd-pro. However, the --with-warnings parameter can enable the non-standard use of the 'warning' value for this field.

<error-tag> Element

All NETCONF <error-tag> enumerations are supported, except 'partial-operation'. This error is being deprecated in the standard because nobody has implemented it.

If this field is set to 'invalid-value', then the <bad-value> element should be present in the <error-info>, identifying the invalid value that caused the problem.

All standard <error-info> contents are supported. The following table summarizes the different <error-tag> values. The <error-number> parameter is not shown in the 'error-info' column because it is added for every error-tag.

<error-tag> Summary

error-tag

error-info

description

access-denied

none

NACM denied access

bad-attribute

<bad-attribute> <bad-element> <bad-value>

just for the few attributes used in NETCONF

bad-element

<bad-element> <bad-value>

sometimes used instead of invalid-value

data-exists

none

nc:operation='create'

data-missing

none

nc:operation='delete' or 'replace'

in-use

none

edit on locked database

invalid-value

<bad-value>

for typedef constraints

lock-denied

<session-id>

for <lock> only

missing-attribute

<bad-attribute>

just for the few attributes used in NETCONF

missing-element

<bad-element>

mandatory parameters

o peration-not-supported

none

unsupported, false if-feature inside rpc

operation-failed

none

when no other error-tag applies

partial-operation

<ok-element> <err-element> <noop-element>

not implemented

resource-denied

none

malloc failed

rollback-failed

none

rollback-on-error failed

too-big

none

input too big to buffer

unknown-attribute

<bad-attribute> <bad-element>

for any non-NETCONF attributes found

unknown-element

<bad-element>

wrong element name in a known namespace

unknown-namespace

<bad-element>

module not loaded

malformed-message

None

base:1.1 framing lost in transport layer

<error-app-tag> Element

The <error-app-tag> field provided a more specific error classification than the <error-tag> field. It is included in every <rpc-error> response.

This field is encoded as a simple string.

It is possible that error-app-tag values from different vendors will use the same string. A client application needs to account for this shared namespace.

If the YANG 'error-app-tag' statement is defined for the specific error that occurred, then it will be used instead of the default value.

The following table describes the default <error-app-tag> values used by netconfd-pro:

<error-app-tag> Summary

error-app-tag

description

data-incomplete

the input parameters are incomplete

data-invalid

one or more input parameters are invalid

data-not-unique

unique statement violation (YANG, sec. 13.1)

duplicate-error

trying to create a duplicate list or leaf-list entry

general-error

no other description fits

instance-required

missing mandatory node (YANG, sec. 13.5)

internal-error

internal software error

io-error

NETCONF session IO error

libxml2-error

libxml2 internal error or parsing error

limit-reached

some sort of defined limit was reached

malloc-error

malloc function call failed

missing-choice

mandatory choice not found (YANG, sec. 13.6)

missing-instance

mandatory leaf not found (YANG, sec. 13.7)

must-violation

must expression is false (YANG, sec. 13.4)

no-access

access control violation

no-matches

<get-schema> module or revision search failed

no-support

operation or sub-operation not implemented

not-in-range

YANG range test failed

not-in-value-set

YANG enumeration or bits name is invalid

pattern-test-failed

YANG pattern test failed

recover-failed

commit or rollback-on-error failed to leave the target database unchanged

resource-in-use

in-use error or <create-subscription> while a subscription is already active

ssh-error

SSH transport error

too-few-elements

min-elements violation (YANG, sec. 13.3)

too-many-elements

max-elements violation (YANG, sec. 13.2)

<error-path> Element

The <error-path> field indicates the node that caused the error.

It is encoded as a YANG instance-identifier.

If the node that caused the error is within the incoming <rpc> request, then the error path will start with the <rpc> element, and contain all the node identifiers from this document root to the node that caused the error.

<error-path>/nc:rpc/nc:edit-config/nc:config/nacm:nacm/nacm:groups/nacm:group</error-path>

The 'xmlns' attributes which define the 'nc' and 'nacm' prefixes would be present in the <rpc-reply> or the <rpc-error> element start tags.

If the node that caused the error is not within the incoming <rpc> request, then the error path will start with the top-level YANG module element that contains the error, not the <rpc> element.

This extended usage of the <error-path> field is defined in the YANG specification, not the NETCONF specification. This situation will occur if <validate> or <commit> operations detect errors. It can also occur if the <test-option> for the <edit-config> operation is 'test-then-set', and errors unrelated to the provided in-line <config> content are reported. and contain all the node identifiers from this document root to the node that caused the error.

<error-path>/nacm:nacm/nacm:groups/nacm:group[name='admin']/groupIdentity</error-path>

<error-message> Element

The <error-message> field provides a short English language description of the error that usually corresponds to the <error-number> field.

If the YANG <error-message> statement is available for the error that occurred, it will be used instead of the default error message.

<error-info> Element

The <error-info> container is used to add error-specific data to the error report.

There are some standard elements that are returned for specific errors, and some elements specific to the netconfd-pro server.

<error-info> Summary

child node

description

<bad-attribute>

name of the XML attribute that caused the error

<bad-element>

name of the element that caused the error or contains the attribute that caused the error

<bad-value>

value that caused the error

<error-number>

internal error number for the error condition

<missing-choice>

name of the missing mandatory YANG choice

<session-id>

session number of the current lock holder

Dynamic Error Messages

Dynamic error messages can include content from the configuration data, such as an interface name, or other administrative details.

A set of YANG extensions are used to configure the dynamic error strings.

The “errmsg” extension is used to specify a single dynamic error message. Zero or more of these statements can appear within a data node. The “errmsg” statement can appear within a “must” statement as well. It will resolve to the data node containing the “must” statement.

The “errmsg” statement has 3 sub-statements:

  • errmsg-parm: specifies a parameter to use within the errmsg

  • errmsg-tag: specifies an “error-tag” filter for this errmsg

  • errmsg-apptag: specifies an “error-app-tag” filter for this errmsg

  • errmsg-lang: specifies a language for the errmsg. The --errmsg-lang CLI parameter value will be used to select an errmsg if this sub-statement is present

errmsg Statements

extension errmsg {
  description
    "Used within a data node statement to define
     a custom error-message filed within an 'rpc-error'
     or 'error' structure for some or all error conditions.

     The string format is restricted to plain text with
     the exception of the 2 character sequence '%s'.
     This special sequence will be replaced in the
     dynamic error message generation if an errmsg-parm
     statement is found to match the escape sequence.

     If this extension statement has no sub-statements,
     then it matches all errors for the object.
     If 'errmsg-tag' sub-statements are found, then
     this entry will match only those error-tag values.
     If 'errmsg-apptag' sub-statements are found, then
     this entry will match only those error-app-tag values.

     The 'basestr' argument must be formatted string.
     If any parameters are specified, then the corresponding
     'errmsg-parm' extension statements must be encoded within
     this errmsg statement.

     Multiple errmsg statements can be present in the same
     data node statement. They will be processed in order
     and the first matching statement will be used to
     generate the error-message value.

     Example:

        leaf my-network-id {
          type int32;
          ywx:errmsg 'Not a valid network ID for interface %s' {
            ywx:errmsg-parm '../../if:name';
            ywx:errmsg-apptag 'network-error';
          }
        }
    ";
  argument basestr;
}

extension errmsg-parm {
  description
    "Used within an errmsg statement to define
     a parameter for expansion within the errmsg basestr.
     There should be the correct number of expected parameters
     for the corresponding 'basestr' format string.

     The 'parmstr' argument must be an XPath path expression.
     The context node will be the data node containing the
     errmsg statement.
    ";
   argument parmstr;
 }

extension errmsg-tag {
  description
    "Used within an errmsg statement to define an
     error-tag value that will filter this errmsg.
     Multiple errmsg-tag and/or errmsg-apptag values
     form a conceptual OR expression.

     The 'tagstr' argument must be the error-tag value
     that will be matched.
    ";
  argument tagstr;
}

extension errmsg-apptag {
  description
    "Used within an errmsg statement to define an
     error-app-tag value that will filter this errmsg.
     Multiple errmsg-tag and/or errmsg-apptag values
     form a conceptual OR expression.

     The 'apptagstr' argument must be the error-app-tag
     value that will be matched.
    ";
  argument apptagstr;
}

extension errmsg-lang {
  description
    "Used within an errmsg statement to define the
     language code value that will filter this errmsg.
     Only one errmsg-lang statement may appear within
     an errmsg statement. The 'langstr' value will
     be compared to the 'errmsg-lang' CLI variable setting.
     If the strings are the same, the entry is used.

     If this statement is not present, then the errmsg entry
     will be used regardless of the 'errmsg-lang' CLI variable
     setting.

     The 'langstr' argument must be the language code
     value that will be matched.
    ";
  argument langstr;
}

The test-errmsg.yang module contains examples of the errmsg statement:

module test-errmsg {
  namespace "http://yumaworks.com/ns/test-errmsg";
  prefix "tm";
  import yumaworks-extensions { prefix ywx; }
  revision 2018-03-05;

  container top {
    list list1 {
      key a;
      leaf a { type string; }
      leaf b { type int32; }
      leaf test1 {
        ywx:errmsg "The value '%s' is invalid for the %s list entry" {
          ywx:errmsg-parm ".";
          ywx:errmsg-parm "../a";
          ywx:errmsg-tag "invalid-value";
        }
        type int8;
      }

      leaf test2 {
        must "../test1 != 8" {
          ywx:errmsg "The test1 value '%s' is not allowed if test2 is '%s'" {
             ywx:errmsg-parm "../test1";
             ywx:errmsg-parm ".";
             ywx:errmsg-apptag "must-violation";
          }
        }
        type uint32;

        ywx:errmsg "The b value is %s and the key is %s "
        + "for the invalid-value %s" {
          ywx:errmsg-tag "invalid-value";
          ywx:errmsg-parm "../b";
          ywx:errmsg-parm "../a";
          ywx:errmsg-parm ".";
        }
      }

      leaf test3 {
        type string;
        ywx:errmsg "This is %s the %s operation-failed %s msg" {
          ywx:errmsg-parm "../b";
          ywx:errmsg-parm "../test1";
          ywx:errmsg-parm ".";
          ywx:errmsg-lang "en";
        }

        ywx:errmsg "C'est %s l'opération %s a échoué %s msg" {
          ywx:errmsg-parm "../b";
          ywx:errmsg-parm "../test1";
          ywx:errmsg-parm ".";
          ywx:errmsg-lang "fr";
        }
      }
    }
  }

}

Using Annotations to Define Dynamic Error Messages

It is often undesirable to define YANG annotations like the ‘errmsg’ statement in YANG modules that are visible to customers. The --annotation CLI parameter can be used to specify a YANG module that contains annotations for another YANG module. The annotation YANG module is not advertised to clients. It is only used internally to “patch” the target YANG module with annotations and deviations.

The following example shows how a dynamic error message could be specified for the “type” leaf in the ietf-interfaces module. The annotation YANG module is called “errmsg-if.yang”. The server could be invoked with these configuration file parameters:

netconfd-pro {
  module ietf-interfaces
  module iana-if-type
  annotation errmsg-if
}

The errmsg-if.yang module is loaded at boot-time and the errmsg statements are applied to the /interfaces/interface/ltype leaf node.

module errmsg-if {

  namespace "http://netconfcentral.org/ns/errmsg-if";
  prefix "em";

  import yumaworks-extensions { prefix ywx; }
  import ietf-interfaces { prefix if; }

  revision 2018-04-12 {
      description "Initial revision.";
  }

  deviation /if:interfaces/if:interface/if:type {
    deviate add {
        ywx:errmsg "This is the name %s and type %s of the interface" {
          ywx:errmsg-parm "../name";
          ywx:errmsg-parm ".";
          ywx:errmsg-lang "en";
        }

    }
  }
}

Replacing a Standard Error Message

The --errmsg CLI parameter can be used to replace the standard error message for a specific error number.

  • The error numbers are listed with the error enumerations in the file ncx/status_enum.h.

  • For example, the error code 313 is assigned to the enumeration ERR_NCX_INVALID_PATTERN.

  • The default error message is “invalid pattern”.

  • The errmsg parameter is a string with 3 fields:

    <errnum>:<lang>:<msg>
    
    • <errnum> is the error number

    • <lang> is the language code (must be “en” for English to replace the default error string)

    • <msg> is the desired error message

To replace this default error message with the string

This is an invalid pattern specification

use the errmsg parameter as follows:

errmsg “313:en:”This is an invalid pattern specification”

Multi-Language Error Messages

The server can be configured to use error-message strings in a language other than English.

  • The --errmsg parameter is a leaf-list that allows a static error message to be configured at boot-time.

  • Each errmsg string contains an error number, language code, and error message.

  • See the --errmsg CLI parameter for details.

  • This parameter must be used together with the --errmsg-lang parameter to select an error message language other than English.

  • The Google Translate service is used to create the pre-configured language-specific errmsg configuration files (found in /usr/share/yumapro/util/errmsg-lang).

  • The language codes used in this program correspond to the ISO-639-1 codes defined by Google Translate languages

These files can be edited if desired and the strings replaced with custom values.

There is a set of translated error messages installed in the /usr/share/yumapro/util/errmsg-lang directory.

File

Language

errmsg-cs.conf

Czech

errmsg-da.conf

Danish

errmsg-de.conf

German

errmsg-en.conf

English

errmsg-es.conf

Spanish

errmsg-fr.conf

French

errmsg-he.conf

Hebrew

errmsg-hu.conf

Hungarian

errmsg-it.conf

Italian

errmsg-ja.conf

Japanese

errmsg-ko.conf

Korean

errmsg-nl.conf

Dutch

errmsg-no.conf

Norwegian

errmsg-pl.conf

Polish

errmsg-ru.conf

Russian

errmsg-sr.conf

Serbian

errmsg-zh-CN.conf

Chinese

Any configuration file can be used to configure errmsg parameters. The default translation files can be edited to change the error message for specific error numbers.

To use a translated error file, it must be placed in the configuration sub-directory. The default is the /etc/yumapro/netconfd-pro.d directory. To use a non-default location, set the --confdir CLI parameter.

The --errmsg-lang parameter must also be used, and set to the correct language code.

Example: Set up French error messages:

> sudo mkdir -p /etc/yumapro/netconfd-pro.d
> sudo cp /usr/share/yumapro/util/errmsg-lang/errmsg-fr.conf /etc/yumapro/netconfd-pro.d/

Add to the configuration file /etc/yumapro/netconfd-pro.conf:

netconfd-pro {
  errmsg-lang fr
}

instance-required Error Example

The instance-required error-app-tag is generated when a YANG leaf is mandatory, but was not set. An error will be returned right away if the target is the <running> configuration, or if the (default) 'test-then-set' option is used for the <test-option>. Otherwise, this error is generated when the <commit> operation is invoked.

data

description

error-tag

data-missing

error-app-tag

instance-required

error-path

identifies the leaf that is missing

error-info

none

error-number

310

Example Request:

  • create /test2 (?s used to skip the mandatory <a2> leaf, but the <foo> leaf is set)

<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="2">
  <nc:edit-config>
    <nc:target>
      <nc:candidate/>
    </nc:target>
    <nc:default-operation>none</nc:default-operation>
    <nc:config>
      <t:test2 nc:operation="create" xmlns:t="http://netconfcentral.org/ns/test">
        <t:foo>xxx</t:foo>
      </t:test2>
    </nc:config>
  </nc:edit-config>
</nc:rpc>

Example Error Reply:

<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
  message-id="2" xmlns:t="http://netconfcentral.org/ns/test"
  xmlns:ncx="http://netconfcentral.org/ncx">
  <nc:rpc-error>
    <nc:error-type>application</nc:error-type>
    <nc:error-tag>data-missing</nc:error-tag>
    <nc:error-severity>error</nc:error-severity>
    <nc:error-app-tag>instance-required</nc:error-app-tag>
    <nc:error-path>/t:test2/t:a2</nc:error-path>
    <nc:error-message xml:lang="en">required value instance not found</nc:error-message>
    <nc:error-info>
      <ncx:error-number>310</ncx:error-number>
    </nc:error-info>
  </nc:rpc-error>
</nc:rpc-reply>

missing-choice Error Example

The missing-choice error is generated when a YANG choice is mandatory, but no case from the choice was set. An error will be returned right away if the target is the <running> configuration, or if the (default) 'test-then-set' option is used for the <test-option>. Otherwise, this error is generated when the <commit> operation is invoked.

data

description

error-tag

data-missing

error-app-tag

missing-choice

error-path

identifies the parent of the missing choice

error-info

<missing-choice>

error-number

296

Example Request:

  • create --target=/musttest (?s skip the mandatory choice)

<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="2">
  <nc:edit-config>
    <nc:target>
      <nc:candidate/>
    </nc:target>
    <nc:default-operation>none</nc:default-operation>
    <nc:config>
      <t:musttest nc:operation="create" xmlns:t="http://netconfcentral.org/ns/test"/>
    </nc:config>
  </nc:edit-config>
</nc:rpc>

Example Error Reply:

<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="2"
   xmlns:t="http://netconfcentral.org/ns/test" xmlns:ncx="http://netconfcentral.org/ncx">
   <nc:rpc-error xmlns:y="urn:ietf:params:xml:ns:yang:1">
     <nc:error-type>application</nc:error-type>
     <nc:error-tag>data-missing</nc:error-tag>
     <nc:error-severity>error</nc:error-severity>
     <nc:error-app-tag>missing-choice</nc:error-app-tag>
     <nc:error-path>/t:musttest</nc:error-path>
     <nc:error-message xml:lang="en">missing mandatory choice</nc:error-message>
     <nc:error-info>
       <y:missing-choice xmlns:y="urn:ietf:params:xml:ns:yang:1">musttest</y:missing-choice>
       <ncx:error-number>296</ncx:error-number>
     </nc:error-info>
   </nc:rpc-error>
 </nc:rpc-reply>

no-matches Error Example

The no-matches error is generated when parameters for the <get-schema> operation identify a non-existent YANG file.

data

description

error-tag

operation-failed

error-app-tag

no-matches

error-path

identifies the <identifier> or <revision> parameter in the <get-schema> request

error-info

<bad-value>

error-number

365

Example Request:

  • get-schema identifier=foo version= format=yang

<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="3">
  <ns:get-schema xmlns:ns="urn:ietf:params:xml:ns:netconf:state">
    <ns:identifier>foo</ns:identifier>
    <ns:version/>
    <ns:format>ns:yang</ns:format>
  </ns:get-schema>
</nc:rpc>

Example Error Reply:

<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="3"
  xmlns:ns="urn:ietf:params:xml:ns:netconf:state" xmlns:ncx="http://netconfcentral.org/ncx">
  <nc:rpc-error>
    <nc:error-type>protocol</nc:error-type>
    <nc:error-tag>operation-failed</nc:error-tag>
    <nc:error-severity>error</nc:error-severity>
    <nc:error-app-tag>no-matches</nc:error-app-tag>
    <nc:error-path>/nc:rpc/ns:get-schema/ns:input/ns:identifier</nc:error-path>
    <nc:error-message xml:lang="en">no matches found</nc:error-message>
    <nc:error-info>
      <ncx:bad-value>foo</ncx:bad-value>
      <ncx:error-number>365</ncx:error-number>
    </nc:error-info>
  </nc:rpc-error>
</nc:rpc-reply>

not-in-range Error Example

The not-in-range error is generated when a numeric type violates a YANG range statement.

data

description

error-tag

invalid-value

error-app-tag

not-in-range

error-path

identifies the leaf or leaf-list node that is not in range

error-info

<bad-value>

error-number

288

Example Request:

  • create /int8.1 value=1000

<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="4" trace-id="4" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <edit-config xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
    <target>
      <candidate/>
    </target>
    <default-operation>merge</default-operation>
    <test-option>set</test-option>
    <config>
      <int8.1 xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
        nc:operation="merge"
        xmlns="http://netconfcentral.org/ns/test">1000</int8.1>
    </config>
  </edit-config>
</rpc>

Example Error Reply:

<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="4" trace-id="4" xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
  xmlns:t="http://netconfcentral.org/ns/test"
  xmlns:ncx="http://netconfcentral.org/ns/yuma-ncx"
  xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <rpc-error>
    <error-type>protocol</error-type>
    <error-tag>invalid-value</error-tag>
    <error-severity>error</error-severity>
    <error-app-tag>not-in-range</error-app-tag>
    <error-path>/nc:rpc/nc:edit-config/nc:config/t:int8.1</error-path>
    <error-message xml:lang="en">value not in range</error-message>
    <error-info>
      <bad-value xmlns="http://netconfcentral.org/ns/yuma-ncx">1000</bad-value>
      <error-number xmlns="http://netconfcentral.org/ns/yuma-ncx">288</error-number>
    </error-info>
  </rpc-error>
</rpc-reply>

Protocol Operations

This section describes the netconfd-pro implementation details that may affect usage of the NETCONF protocol operations.

Every protocol operation is defined with a YANG rpc statement.

All NETCONF operations and several proprietary operations are supported,

<backup>

The <backup> operation is used to create a named configuration backup file on the server. This operation is used with the <restore> operation.

Only local files are supported.

The --with-yumaworks-system CLI parameter must be set to 'true' in the server configuration.

The agt_backup_dir path string must be set to a valid directory in the agt_profile struct.

By default, only a superuser account is allowed to invoke this operation.

+---x backup
   +---w input
      +---w filename     ywt:NcxFileName
      +---w overwrite?   boolean

<backup> Operation Usage

Min parameters:

1

Max parameters:

2

Return type:

status

YANG file:

yumaworks-system.yang

Capabilities needed:

none

Mandatory Parameters:

  • filename:

    • The file name with extension for the backup. The directory is determined by the agt_backup_dir profile variable. The file name string is specified by the NcxFileName typedef in yumaworks-types.yang.

Optional Parameters:

  • overwrite:

    • TRUE if it is OK to overwrite a backup with the same name, if it exists. FALSE if an error should be returned if the backup named 'filename' already exists. The default is FALSE.

Returns:

  • <ok/>

Possible Operation Errors:

  • none

Example Request:

<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="2" trace-id="2" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <backup xmlns="http://yumaworks.com/ns/yumaworks-system">
    <filename>foo.xml</filename>
  </backup>
</rpc>

Example Reply:

<rpc-reply message-id="2" trace-id="2" xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
  xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <ok/>
</rpc-reply>

<cancel-commit>

The <cancel-commit> operation is used to cancel a confirmed commit procedure in progress.

The :candidate capability .. code-block:: text

+---x cancel-commit {confirmed-commit}?
+---w input

+---w persist-id? string

<cancel-commit> Operation Usage

Min parameters:

0

Max parameters:

1

Return type:

status

YANG file:

ietf-netconf.yang

Capabilities needed:

Mandatory Parameters:

  • none

Optional Parameters:

  • persist: If the 'persist' string was provided in the <commit> operation, then this parameter must be present, and the value must match. Only the session that started the confirmed commit can use this operation without providing a 'persist' parameter.

Returns:

  • <ok/>

Possible Operation Errors:

  • none

Example Request:

<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="2">
  <nc:cancel-commit>
    <nc:persist>mycommit</nc:persist>
  </nc:cancel-commit>
</nc:rpc>

Example Reply:

<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="2">
  <nc:ok/>
</nc:rpc-reply>

<cancel-subscription>

The <cancel-subscription> operation is used to cancel a notification subscription.

If the calling session has a subscription previously created with <create-subscription>, then the subscription will be canceled and removed from memory. If no subscription is active the server will simply return <ok/>.

This operation will only be present if the --with-notifications parameter is set to 'true'.

+---x cancel-subscription

<cancel-subscription> Operation Usage

Min parameters:

0

Max parameters:

0

Return type:

status

YANG file:

ietf-netconf.yang

Capabilities needed:

Mandatory Parameters:

  • none

Optional Parameters:

  • none

Returns:

  • <ok/>

Possible Operation Errors:

  • none

Example Request:

<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="3" trace-id="3" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <cancel-subscription xmlns="http://yumaworks.com/ns/yumaworks-system"/>
</rpc>

Example Reply:

<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="3" trace-id="3" xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
  xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <ok/>
</rpc-reply>

<clear-eventlog>

Delete any events stored in the eventlog for the specified event stream. This operation has no affect if the event stream does not have any stored events or its eventlog is not enabled.

By default, only a superuser session can invoke this operation.

+---x clear-eventlog
   +---w input
      +---w stream-name    ywt:NcxNumName

<clear-eventlog> Operation Usage

Min parameters:

1

Max parameters:

1

Return type:

status

YANG file:

yumaworks-event-stream.yang

Capabilities needed:

none

Mandatory Parameters:

  • stream-name

    • type: string

    • default: none

    • capabilities needed: none

    • The name of the event-stream to clear

Optional Parameters:

  • none

Returns:

  • <ok/>

Possible Operation Errors:

  • access-denied

  • invalid-value

Example Request:

<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="2"
 xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
 <clear-eventlog xmlns="http://yumaworks.com/ns/yumaworks-event-stream">
  <stream-name>NETCONF</stream-name>
 </clear-eventlog>
</rpc>

Example Reply:

<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="2"
 xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
 <ok/>
</rpc-reply>

<close-session>

The <close-session> operation is always allowed, even if access control rules exist which somehow disallow 'exec' privileges to a session for this operation.

A <netconf-session-end> Event notification with a <termination-reason> field set to closed will be generated when this operation is invoked.

+---x close-session

<close-session> Operation Usage

Min parameters:

0

Max parameters:

0

Return type:

status

YANG file:

ietf-netconf.yang

Capabilities needed:

none

Mandatory Parameters:

  • none

Optional Parameters:

  • none

Returns:

  • <ok/>; an <rpc-reply> will be sent to the session before terminating the session.

Possible Operation Errors:

  • none

Example Request:

<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="2">
  <nc:close-session/>
</nc:rpc>

Example Reply:

<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="2">
  <nc:ok/>
</nc:rpc-reply>

<commit>

The <commit> operation is only available when the :candidate capability is supported.

The input parameters are only supported if the :confirmed-commit capability is supported.

  • This operation causes all the edits in the <candidate> configuration to be applied to the <running> configuration. If there are no edits, then this operation has no affect.

  • If multiple sessions have made edits to the <candidate> configuration (because locking was not used), then all these edits will be applied at once, not just the edits from the current session.

  • It the <candidate> or <running> configurations are locked by another session, then this operation will fail with an 'in-use' error.

Normally, if there have been no changes made to the <candidate> configuration, then this operation has no effect. An <ok/> response will be returned without altering the <running> configuration.

However, if the <running> configuration encountered any errors during the initial load from NV-storage (such as startup-cfg.xml), then the current contents of the <running> configuration will be written to NV-storage, even if there are no changes to the <candidate> configuration.

The :confirmed-commit capability is fully supported:

  • confirmed-commit:1.0

  • confirmed-commit:1.1

+---x commit {candidate}?
    +---w input
       +---w confirmed?         empty {confirmed-commit}?
       +---w confirm-timeout?   uint32 {confirmed-commit}?
       +---w persist?           string {confirmed-commit}?
       +---w persist-id?        string {confirmed-commit}?

<commit> Operation Usage

Min parameters:

0

Max parameters:

4

Return type:

status

YANG file:

ietf-netconf.yang

Capabilities needed:

Mandatory Parameters:

  • none

Optional Parameters:

  • confirmed:

    • type: empty

    • default: none

    • capabilities needed: confirmed-commit

    • This parameter indicates that a confirmed commit operation should be started or extended.

  • confirm-timeout:

    • type: number

    • default: 600

    • capabilities needed: confirmed-commit

    • This parameter indicates the number of seconds to wait before canceling the confirmed commit automatically.

  • persist:

    • type: string

    • default: none

    • capabilities needed: confirmed-commit and base:1.1

    • This parameter sets the string that all sessions can use to access this confirmed commit procedure.

  • persist-id:

    • type: string

    • default: none

    • capabilities needed: confirmed-commit and base:1.1

    • This parameter changes the 'persist' string that all sessions can use to access this confirmed commit procedure. It is used to allow access to the confirmed commit operation, if the 'persist' parameter is not present.

Returns:

  • <ok/>

Possible Operation Errors:

  • access-denied: access control configured to deny access to this operation

  • in-use: the <candidate> or <running> configuration is locked by another session.

  • operation-failed

    • must-violation: must statement is false

    • too-few-elements: min-elements expression is false

    • too-many-elements: max-elements expression is false

    • data-not-unique: unique statement violation

  • data-missing: mandatory statement violation or missing leafref path object

Example Request:

<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="5">
  <nc:commit/>
</nc:rpc>

Example Reply:

<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="5">
  <nc:ok/>
</nc:rpc-reply>

<copy-config>

The <copy-config> operation is used to transfer entire configuration databases in one operation.

The <source> and <target> parameters are simple to understand, but there are many interactions and some complexity, due to so many combinations of optional capabilities that are possible.

When in-line configuration data is used in the <source> parameter, it is applied to the <target> differently, depending on the database.

  • If the <target> is the <startup> configuration, then the new configuration simply overwrites the old one, and no validation is done at all.

  • If the <target> is the <candidate> or <running> configuration, then the new configuration overwrites the old one, but validation is done similar to the <edit-config> operation. All validation and access control procedures are followed.

The <with-defaults> parameter is also available for filtering the output as it is copied to the target.

+---x copy-config
   +---w input
      +---w target
      |  +---w (config-target)
      |     +--:(candidate)
      |     |  +---w candidate?   empty {candidate}?
      |     +--:(running)
      |     |  +---w running?     empty {writable-running}?
      |     +--:(startup)
      |     |  +---w startup?     empty {startup}?
      |     +--:(url)
      |        +---w url?         inet:uri {url}?
      +---w source
         +---w (config-source)
            +--:(candidate)
            |  +---w candidate?   empty {candidate}?
            +--:(running)
            |  +---w running?     empty
            +--:(startup)
            |  +---w startup?     empty {startup}?
            +--:(url)
            |  +---w url?         inet:uri {url}?
            +--:(config)
               +---w config?      <anyxml>

<copy-config> Operation Usage

Min parameters:

2

Max parameters:

3

Return type:

status

YANG file:

ietf-netconf.yang

Capabilities needed:

none

Capabilities optional:

Mandatory Parameters:

  • source

    • type: container with 1 of N choice of leafs

    • usage: mandatory

    • default: none

    • This parameter specifies the name of the source database for the copy operation.

    • container contents: 1 of N:

      • candidate

      • running

        • type: empty

        • capabilities needed: none

      • startup

        • type: empty

        • capabilities needed: :startup

      • config:

        • type: container (in-line configuration data)

        • capabilities needed: none

          • Access to the entire database is required for this operational mode.

      • url:

        • type: inet:uri

        • capabilities need: :url

          • The scheme ‘file’ is supported if the :url capability is supported

          • The scheme ‘ftp’ is supported if the :url capability is supported and the --with-url-ftp parameter is set to ‘true’

          • The scheme ‘tftp’ is supported if the :url capability is supported and the --with-url-ftp parameter is set to ‘true’

  • target

    • type: container with 1 of N choice of leafs

    • usage: mandatory

    • default: none

    • This parameter specifies the name of the target database for the copy operation.

    • container contents: 1 of N:

      • candidate

      • startup

        • type: empty

        • capabilities needed: :startup

      • url:

        • type: inet:uri

        • capabilities need: :url

          • The scheme ‘file’ is supported if the :url capability is supported

          • The scheme ‘ftp’ is supported if the :url capability is supported and the --with-url-ftp parameter is set to ‘true’

          • The scheme ‘tftp’ is supported if the :url capability is supported and the --with-url-ftp parameter is set to ‘true’

Optional Parameters:

  • with-defaults

    • type: enumeration (none report-all report-all-tagged trim explicit)

    • default: none

    • capabilities needed: :with-defaults

    • This parameter controls how nodes containing only default values are copied to the target database. If the <target> parameter is <candidate>, then this parameter will be ignored.

  • with-owners

    • type: empty

    • default: not present (false)

    • capabilities needed: none

    • This parameter specifies that the owner metadata should be returned in the configuration (if applicable).

    • The --save-owners CLI parameter must be 'true' in order for any owner string attributes to be returned

  • depth:

    • type: union (uint32, ‘unbounded’)

    • default: unbounded

    • capabilities needed: none

    • The --with-yumaworks-system CLI parameter must be set to 'true' for this parameter to be present

    • This parameter controls the depth of subtrees copied to the target. It is the same as the RESTCONF protocol “depth” query parameter.

Returns:

  • <ok/> or <rp-error>

Possible Operation Errors:

  • access-denied : access control configured to deny access to this operation

  • in-use: the configuration indicated by the <target> parameter is locked by another session.

  • <commit> errors, if the <target> parameter is the <running> configuration

Example Request:

<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="7">
  <nc:copy-config>
    <nc:source>
      <nc:running/>
    </nc:source>
    <nc:target>
      <nc:startup/>
    </nc:target>
  </nc:copy-config>
</nc:rpc>

Example Reply:

<?xml version="1.0" encoding="UTF-8"?>
  <nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="7">
  <nc:ok/>
</nc:rpc-reply>

<create-subscription>

The <create-subscription> operation is used to start a NETCONF notifications subscription.

The mandatory 'NETCONF' stream is supported by netconfd-pro. Event streams are created 2 ways:

A replay subscription is created by including the <startTime> parameter.

The subscription will continue until the session is closed, unless the <stopTime> parameter is present. In that case, the subscription will terminate at that time (if in the future) or when all replay notifications with a lower <eventTime> value have been delivered.

This operation will only be present if the --with-notifications parameter is set to 'true'.

The replay notification feature can be controlled with the --eventlog-size configuration parameter. If this is set to '0', then no stored notifications will be available for replay. The default is store the most recent 1000 system notification events.

An entry will be created in the 'subscriptions' data structure in the ietf-netconf-monitoring module, when the subscription is successfully started.

+---x create-subscription
   +---w input
      +---w stream?      streamNameType
      +---w filter?      <anyxml>
      +---w startTime?   yang:date-and-time
      +---w stopTime?    yang:date-and-time

<create-subscription> Operation Usage

Min parameters:

0

Max parameters:

4

Return type:

status

YANG file:

notifications.yang

Capabilities needed:

:notification

Capabilities optional:

:interleave

Mandatory Parameters:

  • none

Optional Parameters:

  • stream

    • type: string

    • default: 'NETCONF'

    • This parameter specifies the name of the notification stream for this subscription request.

  • filter

    • type: anyxml (same as the <get> or <get-config> filter parameter)

    • default: none

    • This parameter specifies a boolean filter that should be applied to the stream. This is the same format as the standard <filter> element in RFC 4741, except that instead of creating a subset of the database for an <rpc-reply> PDU, the filter is used as a boolean test to send or drop each notification delivered from the server.

      • If any nodes are left in the 'test response', the server will send the entire notification.

      • If the result is empty after the filter is applied to the “test response”, then the server will not send the notification at all.

      • It is possible that access control will either cause the a notification to be dropped entirely, or may be pruned and still delivered. The standard is not clear on this topic. The netconfd-pro server will prune any unauthorized payload from an eventType, but if the <eventType> itself is unauthorized, the entire notification will be dropped.

  • startTime

    • type: yang:date-and-time

    • This parameter causes any matching replay notifications to be delivered by the server, if notification replay is supported by the server. A notification will match if its <eventTime> value is greater or equal to the value of this parameter.

  • stopTime

    • type: yang:date-and-time

    • usage: not allowed unless startTime is also present

    • This parameter causes any matching replay notifications to be delivered by the server, if notification replay is supported by the server. A notification will match if its <eventTime> value is less than the value of this parameter.

      • This parameter must be greater than the <startTime> parameter, or an error will be returned by the server.

Returns:

  • <ok/>

Possible Operation Errors:

  • access-denied

  • subscription already active

Example Request:

<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="2">
  <ncEvent:create-subscription xmlns:ncEvent="urn:ietf:params:xml:ns:netconf:notification:1.0">
    <ncEvent:startTime>2009-01-01T00:00:00Z</ncEvent:startTime>
  </ncEvent:create-subscription>
</nc:rpc>

Example Reply:

<?xml version="1.0" encoding="UTF-8"?>
  <nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="2">
  <nc:ok/>
</nc:rpc-reply>

<delete-backup>

The <delete-backup> operation is used to delete a backup configuration file previously created with the <backup> operation.

The --with-yumaworks-system CLI parameter must be set to 'true' in the for this operation to be present.

The agt_backup_dir path string must be set to a valid directory in the agt_profile struct.

By default, only users designated as 'superuser' accounts are allowed to invoke this operation.

+---x delete-backup
   +---w input
      +---w filename    ywt:NcxFileName

<delete-backup> Operation Usage

Min parameters:

1

Max parameters:

1

Return type:

status

YANG file:

yumaworks-system.yang

Capabilities needed:

none

Mandatory Parameters:

  • filename:

    • The file name with extension for the backup. The directory is determined by the agt_backup_dir profile variable. The file name string is specified by the NcxFileName typedef in yumaworks-types.yang.

Optional Parameters:

  • none

Returns:

  • <ok/>

Possible Operation Errors:

  • none

Example Request:

<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="5" trace-id="5" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <delete-backup xmlns="http://yumaworks.com/ns/yumaworks-system">
    <filename>foo.xml</filename>
  </delete-backup>
</rpc>

Example Reply:

<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="5" trace-id="5" xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
  xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <ok/>
</rpc-reply>

<delete-config>

The <delete-config> operation is used to delete the entire contents of a NETCONF database.

By default, only users designated as 'superuser' accounts are allowed to invoke this operation.

If the :startup capability is supported, then the <startup> configuration can be cleared. This will affect the startup file that was actually loaded into the server, or the default file if the --no-startup configuration parameter was used.

If the --no-nvstore parameter is used, then there will not be any startup configuration file to delete.

Note

The <running> and <candidate> configurations cannot be deleted.

The <startup> configuration can be repopulated with the <copy-config> or <commit> operations.

+---x delete-config
   +---w input
      +---w target
         +---w (config-target)
            +--:(startup)
            |  +---w startup?   empty {startup}?
            +--:(url)
               +---w url?       inet:uri {url}?

<delete-config> Operation Usage

Min parameters:

1

Max parameters:

1

Return type:

status

YANG file:

ietf-netconf.yang

Capabilities needed:

:startup

Mandatory Parameters:

  • target

    • type: container with 1 of N choice of leafs

    • This parameter specifies the name of the target database for the <delete-config> operation.

    • container contents: 1 empty leaf value supported:

      • startup

Optional Parameters:

  • none

Returns:

  • <ok/>

Possible Operation Errors:

  • access-denied

  • in-use: <startup> database is locked

Example Request:

<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="2">
  <nc:delete-config>
    <nc:target>
      <nc:startup/>
    </nc:target>
  </nc:delete-config>
</nc:rpc>

Example Reply:

<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="2">
  <nc:ok/>
</nc:rpc-reply>

<delete-subscription>

The <delete-subscription> operation is used to delete a notification subscription, using RFC 8639 subscriptions. This is required to used YANG Push. Only the session that started the subscription can delete a subscription on that session.

Note

This operation is not present unless the server is built with the WITH_YANG_PUSH=1 or EVERYTHING=1 option and the “yang-push” bundle is loaded.

+---x delete-subscription
    +---w input
        +---w id subscription-id

<delete-subscription> Operation Usage

Min parameters:

1

Max parameters:

1

Return type:

status

YANG file:

ietf-subscribed-notifications.yang

Capabilities needed:

none (--bundle=yang-push required)

Capabilities optional:

none

Mandatory Parameters:

  • id

  • type: subscription-id

  • This parameter specifies the subscription ID of the subscription to delete.

Optional Parameters:

  • none

Returns:

  • <ok/>

Possible Operation Errors:

  • access-denied

  • All error-tags and error-app-tags defined in RFC 8639 and RFC 8641 are supported

Example Request:

<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="3" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <delete-subscription
    xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications">
    <id>1</id>
  </delete-subscription>
</rpc>

Example Reply:

<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="3" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <ok/>
</rpc-reply>

When a subscription is terminated, a notification is sent to the subscription before it is deleted:

<?xml version="1.0" encoding="UTF-8"?>
<notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
  <eventTime>2020-09-07T00:44:39Z</eventTime>
  <subscription-terminated xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications">
    <id>1</id>
    <reason xmlns:sn="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications">sn:no-such-subscription</reason>
  </subscription-terminated>
</notification>

<discard-changes>

The <discard-changes> operation is used to remove any edits from the <candidate> configuration. This is done by deleting the contents of the <candidate> and re-filling it with the contents of the <running> configuration.

If the <candidate> configuration is locked by another session, this operation will fail.

+---x discard-changes {candidate}?

<discard-changes> Operation Usage

Min parameters:

0

Max parameters:

0

Return type:

status

YANG file:

ietf-netconf.yang

Capabilities needed:

:candidate

Mandatory Parameters:

  • none

Optional Parameters:

  • none

Returns:

  • <ok/>

Possible Operation Errors:

  • access-denied

Example Request:

<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="3">
  <nc:discard-changes/>
</nc:rpc>

Example Reply:

<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="3">
  <nc:ok/>
</nc:rpc-reply>

<edit-config>

The <edit-config> operation is used to alter the target database.

The target database is the <candidate> configuration if the --target configuration parameter is set to 'candidate', and the <running> configuration if it is set to 'running'.

The 'nc:operation' attribute must appear within the inline <config> parameter contents if the <default-operation> parameter is set to 'none', or the <edit-config> operation will have no affect. This is not an error condition.

This attribute may appear any number of times, and be arbitrarily nested within the <config> parameter contents. Certain combinations will cause errors, however, so this must be done carefully.

  • For example, a 'delete' operation nested within a 'create' operation is an error, because the conditions for both operations cannot possibly be satisfied at once.

  • Other combinations, such as 'merge' within 'create' are not an error because there are no conflicting conditions present for either operation.

+---x edit-config
    +---w input
       +---w target
       |  +---w (config-target)
       |     +--:(candidate)
       |     |  +---w candidate?   empty {candidate}?
       |     +--:(running)
       |        +---w running?     empty {writable-running}?
       +---w default-operation?   enumeration
       +---w test-option?         enumeration {validate}?
       +---w error-option?        enumeration
       +---w (edit-content)
          +--:(config)
          |  +---w config?        <anyxml>
          +--:(url)
             +---w url?           inet:uri {url}?

<edit-config> Operation Usage

Min parameters:

2

Max parameters:

5

Return type:

status

YANG file:

ietf-netconf.yang

Capabilities needed:

:candidate or :writable-running

Capabilities optional:

Mandatory Parameters:

  • config

    • type: anyxml

    • This parameter specifies the subset of the database that should be changed.

  • target

    • type: container with 1 of N choice of leafs

    • This parameter specifies the name of the target database for the edit operation.

    • container contents: choice: 1 of N:

Optional Parameters:

  • default-operation

    • type: enumeration (merge replace none)

    • default: merge

    • This parameter specifies which edit operation will be in effect at the start of the operation, before any 'nc:operation' attribute is found.

  • error-option

    • type: enumeration (stop-on-error continue-on-error rollback-on-error

    • default: stop-on-error

    • This parameter specifies what the server should do when an error is encountered.

  • test-option

    • type: enumeration (test-then-set set test-only)

    • default: 'test-then-set' if :validate capability is supported and 'set' otherwise

Returns:

  • <ok/>

Possible Operation Errors:

  • access-denied

  • in-use (target database is locked by another session)

  • <commit> validation errors: if test-then-set is used or the target is the <running> configuration.

Example Request:

<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="12">
  <nc:edit-config>
    <nc:target>
      <nc:candidate/>
    </nc:target>
    <nc:default-operation>merge</nc:default-operation>
    <nc:test-option>set</nc:test-option>
    <nc:error-option>rollback-on-error</nc:error-option>
    <nc:config>
      <t:musttest xmlns:t="http://netconfcentral.org/ns/test">
        <t:A nc:operation="create">'testing one two'</t:A>
      </t:musttest>
    </nc:config>
  </nc:edit-config>
</nc:rpc>

Example Reply:

<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="12">
  <nc:ok/>
</nc:rpc-reply>

<establish-subscription>

The <establish-subscription> operation is used to start a notification subscription, using RFC 8639 subscriptions. This is required to used YANG Push.

This operation is not present unless the server is build with the WITH_YANG_PUSH=1 or EVERYTHING=1 make flag and the “yang-push” bundle is loaded.

Refer to the YANG Push section for complete usage information for this feature.

This operation has two usage modes, using a YANG choice for this purpose:

  • event stream subscriptions: similar to using the <create-subscription> operation except RFC 8639 subscriptions are used.

    • Multiple subscriptions per session are allowed.

      • There is no way to tell which event stream subscription caused an event to be included.

      • This feature allows a session to subscribe to multiple event streams at once, or the same event stream (hopefully with different, non-overlapping filters).

      • It is possible for a client session to receive the same notification more than once if a session subscribes to the same event stream multiple times.

    • Each client subscribing to an event-stream has access to the same set notification events (assuming NACM rights are the same). In this way, event stream subscriptions are shared subscriptions.

  • datastore subscriptions: YANG Push subscriptions to a specific datastore.

    • These are not shared subscriptions.

    • There is no event stream or replay buffer

    • Each subscription gets its own updates and other notifications.

    • There are 2 types of dynamic subscription defined in RFC 8641, which are periodic and on-change subscriptions. There are different sets of parameters for each type.

+---x establish-subscription
    +---w input
    |  +---w (target)
    |  |  +--:(stream)
    |  |  |  +---w (stream-filter)?
    |  |  |  |  +--:(by-reference)
    |  |  |  |  |  +---w stream-filter-name                   stream-filter-ref
    |  |  |  |  +--:(within-subscription)
    |  |  |  |     +---w (filter-spec)?
    |  |  |  |        +--:(stream-subtree-filter)
    |  |  |  |        |  +---w stream-subtree-filter?         <anydata> {subtree}?
    |  |  |  |        +--:(stream-xpath-filter)
    |  |  |  |           +---w stream-xpath-filter?           yang:xpath1.0 {xpath}?
    |  |  |  +---w stream                                     stream-ref
    |  |  |  +---w replay-start-time?                         yang:date-and-time {replay}?
    |  |  +--:(yp:datastore)
    |  |     +---w yp:datastore                               identityref
    |  |     +---w (yp:selection-filter)?
    |  |        +--:(yp:by-reference)
    |  |        |  +---w yp:selection-filter-ref              selection-filter-ref
    |  |        +--:(yp:within-subscription)
    |  |           +---w (yp:filter-spec)?
    |  |              +--:(yp:datastore-subtree-filter)
    |  |              |  +---w yp:datastore-subtree-filter?   <anydata> {sn:subtree}?
    |  |              +--:(yp:datastore-xpath-filter)
    |  |                 +---w yp:datastore-xpath-filter?     yang:xpath1.0 {sn:xpath}?
    |  +---w stop-time?                                       yang:date-and-time
    |  +---w dscp?                                            inet:dscp {dscp}?
    |  +---w weighting?                                       uint8 {qos}?
    |  +---w dependency?                                      subscription-id {qos}?
    |  +---w encoding?                                        encoding
    |  +---w (yp:update-trigger)?
    |     +--:(yp:periodic)
    |     |  +---w yp:periodic!
    |     |     +---w yp:period         centiseconds
    |     |     +---w yp:anchor-time?   yang:date-and-time
    |     +--:(yp:on-change) {on-change}?
    |        +---w yp:on-change!
    |           +---w yp:dampening-period?   centiseconds
    |           +---w yp:sync-on-start?      boolean
    |           +---w yp:excluded-change*    change-type
    +--ro output
       +--ro id                            subscription-id
       +--ro replay-start-time-revision?   yang:date-and-time {replay}?

<establish-subscription> Operation Usage

Min parameters:

2

Max parameters:

variable

Return type:

data (id)

YANG file:

Capabilities needed:

none (--bundle=yang-push required)

Capabilities optional:

none

Event Stream Subscription

Mandatory Parameters:

  • stream

  • type: stream-ref

  • This parameter specifies the name of the event stream to use. The NETCONF event stream should always be present. Other values are derived from the event stream configuration on the server.

Optional Parameters:

  • stream-filter: choice of 3 options

    • stream-filter-name:

      • type: stream-filter-ref

      • default: none

      • This parameter specifies the name of a stream filter to use in the /filters/stream-filter list

    • stream-subtree-filter:

      • type: anydata

      • default: none

      • This parameter specifies the inline subtree filter to use

    • stream-xpath-filter:

      • type: xpath1.0

      • default: none

      • This parameter specifies the inline XPath filter to use. Prefixes are not required but if they are provided then an “xmlns” attribute defining each prefix to namespace mapping must be present in the XML.

  • replay-start-time

    • type: date-and-time

    • default: none

    • This parameter specifies that replay mode is desired and the replay should include notifications with timestamps greater than the specified value. The replay-start-time-revision leaf is returned if the actual value used is greater than the value requested.

  • stop-time

    • type: date-and-time

    • default: none

    • This parameter specifies that replay mode is desired and the replay should stop including notifications with timestamps less than the specified value.

  • encoding

    • type: identityref

    • default: none

    • This parameter specifies the notification message encoding that is desired. The only value supported at this time is encoding-xml.

Datastore Subscription

Mandatory Parameters:

  • datastore

  • type: identityref

  • This parameter specifies the datastore that will be used for the subscription; One of:

    • candidate

    • running

    • operational

  • update-trigger: choice of 2 options

    • periodic

      • type: presence container

      • default: none

      • This parameter specifies that a periodic subscription is desired. These subscriptions are controlled by the --push-max-periodic parameter. A new subscription will only be established if the limit has not already been reached.

      • child period (mandatory)

        • type: centiseconds

        • default: none

        • This parameter specifies the period to wait between updates. The --push-min-period parameter is used to enforce restrictions beyond the standard.

      • child anchor-time

        • type: date-and-time

        • default: none

        • This parameter is not yet supported.

    • on-change

      • type: presence container

      • default: none

      • This parameter specifies that an on-change subscription is desired. These subscriptions are controlled by the --push-max-operational parameter, if the datastore parameter is ‘operational’. A new subscription will only be established if the limit has not already been reached.

      • child dampening-period (usually mandatory)

        • type: centiseconds

        • default: none

        • This parameter specifies the dampening period to wait between on-change updates. The --push-min-dampening parameter is used to enforce restrictions beyond the standard.

          This parameter can be left out for a simulated operational on-change subscription. In that case, the --push-simop-period parameter will be used instead.

          If both parameters apply, then the maximum value of both of them will be used as the dampening period value.

      • child sync-on-start (optional)

        • type: boolean

        • default: true

        • This parameter specifies that the first update should be a push-update instead of a push-change-update.

      • child excluded-change (leaf-list of change-type) (optional)

        • type: enumeration (create, delete, insert, move, replace)

        • default: none (do not exclude any events

        • This parameter specifies that the event types that should be excluded from the subscription. At least one event type must be included or a ‘cant-exclude’ error-app-tag will be returned. If the subscription is for simulated operational on-change events, then the “replace” event cannot be excluded.

Optional Parameters:

  • selection-filter: choice of 3 options

    • selection-filter-ref:

      • type: selection-filter-ref

      • default: none

      • This parameter specifies the name of a selection filter to use in the /filters/selection-filter list

    • datastore-subtree-filter:

      • type: anydata

      • default: none

      • This parameter specifies the inline subtree filter to use

    • datastore-xpath-filter:

      • type: xpath1.0

      • default: none

      • This parameter specifies the inline XPath filter to use. Prefixes are not required but if they are provided then an “xmlns” attribute defining each prefix to namespace mapping must be present in the XML.

  • stop-time

    • type: date-and-time

    • default: none

    • This parameter specifies that replay mode is desired and the replay should stop including notifications with timestamps less than the specified value.

  • encoding

    • type: identityref

    • default: none

    • This parameter specifies the notification message encoding that is desired. The only value supported at this time is “encoding-xml”.

Returns:

  • data

    • id: subscription-id

    • replay-start-time-revision

Possible Operation Errors:

  • access-denied

  • in-use (target database is locked by another session)

  • All error-tags and error-app-tags defined in RFC 8639 and RFC 8641 are supported

Example Request for a stream subscription for the NETCONF stream with an XPath filter for the <netconf-config-change> Event.

<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="15" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <establish-subscription xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications">
    <stream-xpath-filter>/netconf-config-change</stream-xpath-filter>
    <stream>NETCONF</stream>
  </establish-subscription>
</rpc>

Example Reply: contains the subscription ID (1)

<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="15" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <id xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications">1</id>
</rpc-reply>

Example Datastore Request for the periodic subscription on the operational datastore, with an XPath filter for the /netconf-state/sessions object

<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="16" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <establish-subscription xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications">
    <datastore xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-push"
      xmlns:ds="urn:ietf:params:xml:ns:yang:ietf-datastores">ds:operational</datastore>
    <datastore-xpath-filter xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-push">/netconf-state/sessions</datastore-xpath-filter>
    <periodic xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-push">
      <period>1000</period>
    </periodic>
  </establish-subscription>
</rpc>

Example Reply: contains the subscription ID (2)

<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="16" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <id xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications">2</id>
</rpc-reply>

<get>

The <get> operation is used to retrieve data from the <running> configuration, or non-configuration data available on the server.

Warning

Using this operation without any filter will return all data nodes available on the server. This may be generate a large response and waste resources.

A filter parameter (e.g., subtree or XPath) should always be used with this operation.

To select only specific subsets of all available data, use subtree or XPath filtering by providing a <filter> parameter. Namespace prefixes are optional to use in XPath expressions. The netconfd-pro will figure out the proper namespace, if possible. If prefixes are used, then they must be valid XML prefixes with a namespace properly declared in the PDU.

The retrieval of leaf or leaf-list nodes with default values is controlled with the <with-defaults> parameter.

If a portion of the requested data is not available due to access control restrictions, then that data is silently dropped from the <rpc-reply> message. It is implicitly understood that the client is only requesting data for which it is authorized to receive, in the event such data is selected in the request.

+---x get
   +---w input
   |  +---w filter?                         <anyxml>
   |  +---w ysys:with-owners?               empty
   |  +---w ysys:depth?                     union
   |  +---w ysys:module-tag*                string
   |  +---w timefilter:if-modified-since?   yang:date-and-time
   +--ro output
      +--ro data?   <anyxml>

<get> Operation Usage

Min parameters:

0

Max parameters:

6

Return type:

data

YANG file:

ietf-netconf.yang

Capabilities needed:

none

Capabilities optional:

Mandatory Parameters:

  • none

Optional Parameters:

  • filter

    • type='subtree'

      • type: anyxml

      • This parameter specifies the subset of the database that should be retrieved.

    • type='xpath' select='expr'

      • type: empty

      • The unqualified 'select' attribute is used to specify an XPath filter.

  • with-defaults

    • type: enumeration (none report-all report-all-tagged trim explicit)

    • The --default-style parameter used as the default if no value is provided

    • This parameter controls how default leaf and leaf-list nodes are returned by the server.

  • if-modified-since

    • type: date-and-time

    • usage: optional

    • pre-requisites: --with-yuma-time-filter=true

    • This parameter requests that configuration data only be returned if any of the running datastore contents have been modified since this value.

      Monitoring data (config = false) does not affect the datastore timestamp.

      If the running datastore has not been modified since this timestamp, then an empty <data> element will be returned, and the request will not be processed.

  • with-owners

    • type: empty

    • default: not present (false)

    • pre-requisites: --with-yumaworks-system=true

    • This parameter specifies that the owner metadata should be returned in the configuration (if applicable).

    • No owner attributes will be returned unless the --save-owners parameter is set to 'true'.

  • depth:

    • type: union (uint32, ‘unbounded’)

    • default: unbounded

    • pre-requisites: --with-yumaworks-system=true

    • This parameter controls the depth of subtrees copied to the target. It is the same as the RESTCONF protocol “depth” query parameter.

  • module-tag:

    • type: string

    • default: none

    • pre-requisites: --with-yumaworks-system=true

    • This parameter is used as a filter to include only data nodes from modules that match the module-tag value.

      • Multiple module-tag parameters can be used, combined to form a logical OR expression.

      • At least one module-tag must match or no data will be returned.

      • This filter is combined with the XPath or subtree filter, if present.

Returns:

  • <data> element

Possible Operation Errors:

  • access-denied

  • invalid-value

Example subtree Filter Request:

<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="4">
  <nc:get>
    <nc:filter type="subtree">
      <proc:proc xmlns:proc="http://netconfcentral.org/ns/proc">
        <proc:cpuinfo>
          <proc:cpu>
            <proc:cpu_MHz/>
          </proc:cpu>
        </proc:cpuinfo>
      </proc:proc>
    </nc:filter>
  </nc:get>
</nc:rpc>

Equivalent XPath Filter Request:

<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="4">
  <nc:get>
    <nc:filter type="xpath" select="/proc/cpuinfo/cpu/cpu_MHz"/>
  </nc:get>
</nc:rpc>

Example Reply:

<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
  last-modified="2011-08-21T17:51:46Z" message-id="4">
  <nc:data>
    <proc:proc xmlns:proc="http://netconfcentral.org/ns/proc">
      <proc:cpuinfo>
        <proc:cpu>
          <proc:cpu_MHz>1600.000</proc:cpu_MHz>
          <proc:processor>0</proc:processor>
        </proc:cpu>
        <proc:cpu>
          <proc:cpu_MHz>2667.000</proc:cpu_MHz>
          <proc:processor>1</proc:processor>
        </proc:cpu>
      </proc:cpuinfo>
    </proc:proc>
  </nc:data>
</nc:rpc-reply>

<get-bulk>

The <get-bulk> operation is used to retrieve data any type of YANG data node from the NETCONF server. It is defined in the yumaworks-getbulk.yang module.

This operation requires that WITH_RESTCONF=1 or EVERYTHING=1 is used to build the server image, even though this is a NETCONF operation.

This operation will only be present if the --with-yumaworks-getbulk parameter is set to 'true'.

A YANG list is specified, along with 1 or more optional parameters to fine-tune the retrieval filtering behavior.

The list-target parameter is used to specify that YANG list that will be retrieved.

The list-test parameter allows an XPath boolean expression to be used to test each list-target entry. It is used to select only a subset of the list entries to reduce the number of entries returned.

If a portion of the requested data is not available due to access control restrictions, then that data is silently dropped from the <rpc-reply> message. It is implicitly understood that the client is only requesting data for which it is authorized to receive, in the event such data is selected in the request.

+---x get-bulk
    +---w input
    |  +---w datastore?       enumeration
    |  +---w list-target      string
    |  +---w count?           uint32
    |  +---w depth?           union
    |  +---w with-defaults?   with-defaults-mode
    |  +---w last-keys
    |  +---w list-test        yang:xpath1.0
    |  +---w fixed-keys
    +--ro output
       +--ro bulk
           +--ro data
           +--ro last-keys

<get-bulk> Operation Usage

Min parameters:

1

Max parameters:

8

Return type:

data

YANG file:

yumaworks-getbulk.yang

Capabilities needed:

none

Capabilities optional:

Mandatory Parameters:

  • list-target

    • type: string (RESTCONF path URI)

    • usage: mandatory

    • This parameter identifies the list object that is being retrieved. This must be a path expression used to represent a list data node. It is formatted like a RESTCONF path expression, except module names are not mandatory if they are unique.

Optional Parameters:

  • datastore

    • type: enumeration (candidate running startup)

    • usage: optional

    • default: running

    • This parameter specifies the name of the source database for the retrieval operation. It is ignored if the 'list-target' specifies a non-configuration data node.

    • enum: candidate

    • enum : running

      • capabilities needed: none

    • enum: startup

  • count

    • type: unint32

    • usage: optional

    • default: 1

    • The maximum number of list entries to return.

  • content

    • type: enumeration

    • usage: optional

    • default: all

    • This parameter specifies which type of content to include, exactly the same as the RESTCONF “content” query parameter

      • enum: config

        • Include only config=true descendant data nodes

      • enum: nonconfig

        • include only config=false descendant data nodes

      • enum: all

        • include all descendant data nodes

  • depth

    • type: uint32

    • usage: optional

    • default: unbounded

    • This parameter is used as defined in the RESTCONF protocol. The value '1' is associated with the list-object node itself. This value can be used to simply test for the existence of any instances of the list-object.

  • with-defaults

    • type: enumeration (none report-all report-all-tagged trim explicit)

    • usage: --default-style configuration parameter used as the default if no value is provided

    • This parameter controls how default leaf and leaf-list nodes are returned by the server.

  • last-keys

    • type: container of leafs

    • usage: optional

    • default: start with the first list entry if this parameter not present

    • This parameter contains the key values of a list entry to start the search from. Usually this is the same as the <last-keys> container returned from the previous call to <get-bulk>.. The leafs must be in the same order as defined in the YANG list, and all key leafs must be present.

  • list-test

    • type: leaf containing an XPath expression

    • usage: optional

    • default: return all selected list-target entries

    • This parameter contains an XPath expression. The document root and the context node are set to the list instance being tested. The expression can only reference descendant-or-self nodes The XPath result will be converted with the boolean() function if needed 'true' boolean result : include list instance 'false' boolean result: exclude list instance

  • fixed-keys

    • type: container of leafs

    • usage: optional

    • default: none

    • This parameter contains the key values of a target list entry that should not be changed. These keys will be fixed instead of iterating through all possible values of that key.

Returns:

  • <bulk> element

    • <data> element

      • Contains the requested list entries. Each child element in this container will represent one instance of the list object requested by the 'list-target' parameter.

    • <last-keys> element

      • Contains the key leafs from the last list entry in the <data> element. This container can be passed back to the server as the <last-keys> parameter to continue the retrieval at the entry after the one specified by the key leafs in this container.

Possible Operation Errors:

  • access-denied

  • invalid-value

Example get-bulk Request:

<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="1" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <get-bulk xmlns="http://yumaworks.com/ns/yumaworks-getbulk">
    <list-target>/modules/module</list-target>
    <count>2</count>
  </get-bulk>
</rpc>

Example Reply:

<rpc-reply message-id="1" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <bulk xmlns="http://yumaworks.com/ns/yumaworks-getbulk">
    <data>
      <module xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-library">
        <name>ietf-netconf</name>
        <revision>2011-06-01</revision>
        <namespace>urn:ietf:params:xml:ns:netconf:base:1.0</namespace>
        <feature>candidate</feature>
        <feature>confirmed-commit</feature>
        <feature>rollback-on-error</feature>
        <feature>validate</feature>
        <feature>url</feature>
        <feature>xpath</feature>
        <conformance>true</conformance>
      </module>
      <module xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-library">
        <name>iana-crypt-hash</name>
        <revision>2014-08-06</revision>
        <schema>http://localhost/restconf/yang/iana-crypt-hash/2014-08-06</schema>
        <namespace>urn:ietf:params:xml:ns:yang:iana-crypt-hash</namespace>
        <feature>crypt-hash-md5</feature>
        <feature>crypt-hash-sha-256</feature>
        <feature>crypt-hash-sha-512</feature>
        <conformance>true</conformance>
      </module>
    </data>
    <last-keys xmlns="http://yumaworks.com/ns/yumaworks-getbulk">
      <name xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-library">iana-crypt-hash</name>
      <revision xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-library">2014-08-06</revision>
    </last-keys>
  </bulk>
</rpc-reply>

The client can then save the <last-keys> container to continue the retrieval with entry #3 and #4

<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="2" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <get-bulk xmlns="http://yumaworks.com/ns/yumaworks-getbulk">
    <list-target>/modules/module</list-target>
    <count>2</count>
    <last-keys>
      <name xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-library">iana-crypt-hash</name>
      <revision xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-library">2014-08-06</revision>
    </last-keys>
  </get-bulk>
</rpc>

Example Reply:

<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="2" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <bulk xmlns="http://yumaworks.com/ns/yumaworks-getbulk">
    <data>
      <module xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-library">
        <name>ietf-inet-types</name>
        <revision>2013-07-15</revision>
        <schema>http://localhost/restconf/yang/ietf-inet-types/2013-07-15</schema>
        <namespace>urn:ietf:params:xml:ns:yang:ietf-inet-types</namespace>
        <conformance>false</conformance>
      </module>
      <module xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-library">
        <name>ietf-netconf-acm</name>
        <revision>2012-02-22</revision>
        <schema>http://localhost/restconf/yang/ietf-netconf-acm/2012-02-22</schema>
        <namespace>urn:ietf:params:xml:ns:yang:ietf-netconf-acm</namespace>
        <conformance>true</conformance>
      </module>
    </data>
    <last-keys xmlns="http://yumaworks.com/ns/yumaworks-getbulk">
      <name xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-library">ietf-netconf-acm</name>
      <revision xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-library">2012-02-22</revision>
    </last-keys>
  </bulk>
</rpc-reply>

<get-config>

The <get-config> operation is used to retrieve data from a NETCONF configuration database.

To select only specific subsets of all available data, use subtree or XPath filtering by providing a <filter> parameter. Namespace prefixes are optional to use in XPath expressions. The netconfd-pro will figure out the proper namespace, if possible. If prefixes are used, then they must be valid XML prefixes with a namespace properly declared in the PDU.

The retrieval of leaf or leaf-list nodes with default values is controlled with the <with-defaults> parameter.

If a portion of the requested data is not available due to access control restrictions, then that data is silently dropped from the <rpc-reply> message. It is implicitly understood that the client is only requesting data for which it is authorized to receive, in the event such data is selected in the request.

+---x get-config
   +---w input
   |  +---w source
   |  |  +---w (config-source)
   |  |     +--:(candidate)
   |  |     |  +---w candidate?   empty {candidate}?
   |  |     +--:(running)
   |  |     |  +---w running?     empty
   |  |     +--:(startup)
   |  |        +---w startup?     empty {startup}?
   |  +---w filter?                         <anyxml>
   |  +---w ysys:with-owners?               empty
   |  +---w ysys:depth?                     union
   |  +---w ysys:module-tag*                string
   |  +---w timefilter:if-modified-since?   yang:date-and-time
   +--ro output
      +--ro data?   <anyxml>

<get-config> Operation Usage

Min parameters:

1

Max parameters:

7

Return type:

data

YANG file:

ietf-netconf.yang

Capabilities needed:

none

Capabilities optional:

Mandatory Parameters:

  • source

    • type: container with 1 of N choice of leafs

    • usage: mandatory

    • This parameter specifies the name of the source database for the retrieval operation.

    • container contents: 1 of N:

      • candidate

      • running

        • type: empty

        • capabilities needed: none

      • startup

        • type: empty

        • capabilities needed: startup

Optional Parameters:

  • filter

    • type='subtree'

      • type: anyxml

      • This parameter specifies the subset of the database that should be retrieved.

    • type='xpath' select='expr'

      • type: empty

      • The unqualified select attribute is used to specify an XPath filter.

  • with-defaults

    • type: enumeration (none report-all report-all-tagged trim explicit)

    • The --default-style parameter used as the default if no value is provided

    • This parameter controls how default leaf and leaf-list nodes are returned by the server.

  • if-modified-since

    • type: date-and-time

    • usage: optional

    • pre-requisites: --with-yuma-time-filter=true

    • This parameter requests that configuration data only be returned if any of the running datastore contents have been modified since this value.

      Monitoring data (config = false) does not affect the datastore timestamp.

      If the running datastore has not been modified since this timestamp, then an empty <data> element will be returned, and the request will not be processed.

  • with-owners

    • type: empty

    • default: not present (false)

    • pre-requisites: --with-yumaworks-system=true

    • This parameter specifies that the owner metadata should be returned in the configuration (if applicable).

    • No owner attributes will be returned unless the --save-owners parameter is set to 'true'.

  • depth:

    • type: union (uint32, ‘unbounded’)

    • default: unbounded

    • pre-requisites: --with-yumaworks-system=true

    • This parameter controls the depth of subtrees copied to the target. It is the same as the RESTCONF protocol “depth” query parameter.

  • module-tag:

    • type: string

    • default: none

    • pre-requisites: --with-yumaworks-system=true

    • This parameter is used as a filter to include only data nodes from modules that match the module-tag value.

      • Multiple module-tag parameters can be used, combined to form a logical OR expression.

      • At least one module-tag must match or no data will be returned.

      • This filter is combined with the XPath or subtree filter, if present.

Returns:

  • <data> element

Possible Operation Errors:

  • access-denied

  • invalid-value

Example subtree Filter Request:

<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="3">
  <nc:get-config>
    <nc:source>
      <nc:candidate/>
    </nc:source>
    <nc:filter type="subtree">
      <nacm:nacm xmlns:nacm="http://netconfcentral.org/ns/nacm">
        <nacm:rules>
          <nacm:moduleRule/>
        </nacm:rules>
      </nacm:nacm>
    </nc:filter>
  </nc:get-config>
</nc:rpc>

Equivalent XPath Filter Request:

<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="3">
  <nc:get-config>
    <nc:source>
      <nc:candidate/>
    </nc:source>
    <nc:filter type="xpath" select="/nacm/rules/moduleRule"/>
  </nc:get-config>
</nc:rpc>

Example Reply:

<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
  last-modified="2011-08-21T17:51:46Z" message-id="3">
  <nc:data>
    <nacm:nacm xmlns:nacm="http://netconfcentral.org/ns/nacm">
      <nacm:rules>
        <nacm:moduleRule>
          <nacm:moduleName>netconf</nacm:moduleName>
          <nacm:allowed-rights>read exec</nacm:allowed-rights>
          <nacm:allowed-group>nacm:guest</nacm:allowed-group>
        </nacm:moduleRule>
        <nacm:moduleRule>
          <nacm:moduleName>netconfd-pro</nacm:moduleName>
          <nacm:allowed-rights>read write exec</nacm:allowed-rights>
          <nacm:allowed-group>nacm:admin</nacm:allowed-group>
          <nacm:comment>access to shutdown and restart rpcs</nacm:comment>
        </nacm:moduleRule>
        <nacm:moduleRule>
          <nacm:moduleName>netconf</nacm:moduleName>
          <nacm:allowed-rights>read write exec</nacm:allowed-rights>
          <nacm:allowed-group>nacm:admin</nacm:allowed-group>
          <nacm:allowed-group>nacm:monitor</nacm:allowed-group>
        </nacm:moduleRule>
      </nacm:rules>
    </nacm:nacm>
  </nc:data>
</nc:rpc-reply>

<get-data>

The <get-data> operation is used to retrieve data from a NMDA datastore.

The --with-nmda parameter must be set to 'true' for this operation to be present.

To select only specific subsets of all available data, use subtree or XPath filtering by providing a <subtree-filter> or <xpath-filter> parameter. Namespace prefixes are optional to use in XPath expressions. The netconfd-pro will figure out the proper namespace, if possible. If prefixes are used, then they must be valid XML prefixes with a namespace properly declared in the PDU.

The retrieval of leaf or leaf-list nodes with default values is controlled with the <with-defaults> parameter.

If a portion of the requested data is not available due to access control restrictions, then that data is silently dropped from the <rpc-reply> message. It is implicitly understood that the client is only requesting data for which it is authorized to receive, in the event such data is selected in the request.

+---x get-data
   +---w input
   |  +---w datastore                      ds:datastore-ref
   |  +---w (filter-spec)?
   |  |  +--:(subtree-filter)
   |  |  |  +---w subtree-filter?          <anydata>
   |  |  +--:(xpath-filter)
   |  |     +---w xpath-filter?            yang:xpath1.0 {nc:xpath}?
   |  +---w config-filter?                 boolean
   |  +---w (origin-filters)? {origin}?
   |  |  +--:(origin-filter)
   |  |  |  +---w origin-filter*           or:origin-ref
   |  |  +--:(negated-origin-filter)
   |  |     +---w negated-origin-filter*   or:origin-ref
   |  +---w max-depth?                     union
   |  +---w with-origin?                   empty {origin}?
   |  +---w with-defaults?                 with-defaults-mode {with-defaults}?
   +--ro output
      +--ro data?   <anydata>

<get-data> Operation Usage

Min parameters:

1

Max parameters:

7

Return type:

data

YANG file:

ietf-netconf-nmda.yang

Capabilities needed:

none

Capabilities optional:

Mandatory Parameters:

  • datastore

    • type: leaf containing a datastore-ref

    • usage: mandatory

    • This parameter specifies the name of the source NMDA datastore for the retrieval operation.

    • enumeration:

      • candidate

      • running

        • capabilities needed: none

      • startup

        • capabilities needed: startup

      • operational

        • capabilities needed: none

Optional Parameters:

  • subtree-filter

    • type: anydata

    • This parameter specifies the subset of the database that should be retrieved.

    • Cannot be used if xpath-filter present

  • xpath-filter

    • type: XPath 1.0 string

    • This parameter specifies the subset of the database that should be retrieved.

    • Cannot be used if subtree-filter present

  • config-filter:

    • type boolean

    • Specifies the type of data based on config-stmt. Retrieve all data if this parameter is not present. This is a top-down filter. It will not select nodes within a subtree if the ancestor nodes do not match the filter.

    • Only relevant if the datastore parameter is ‘operational’.

    • If set to ‘false’ for any datastore other than ‘operational’ then an empty <data> element will be returned.

  • origin-filter:

    • type: leaf-list of type origin-ref..

    • This parameter will select data nodes with the specified origin. This is a top-down filter. It will not select nodes within a subtree if the ancestor nodes do not match the filter.

    • Cannot be used if negated-origin-filter present

    • Can only be used if the datastore parameter is ‘operational’

  • negated-origin-filter:

    • type: leaf-list of type origin-ref..

    • This parameter will select data nodes if they do not have the specified origin. This is a top-down filter. It will not select nodes within a subtree if the ancestor nodes do not match the filter.

    • Cannot be used if origin-filter present

    • Can only be used if the datastore parameter is ‘operational’

  • max-depth:

    • type: union (uint32, ‘unbounded’)

    • default: unbounded

    • capabilities needed: none

    • This parameter controls the depth of subtrees copied to the target. It is the same as the RESTCONF protocol “depth” query parameter.

  • with-origin

    • type: empty

    • This parameter will cause the origin attribute to be added to data nodes returned by the server.

    • Can only be used if the datastore parameter is ‘operational’

  • with-defaults

    • type: enumeration (none report-all report-all-tagged trim explicit)

    • usage: --default-style configuration parameter used as the default if no value is provided

    • This parameter controls how default leaf and leaf-list nodes are returned by the server.

Example Request:

<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="3" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <get-data xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-nmda">
    <datastore xmlns:ds="urn:ietf:params:xml:ns:yang:ietf-datastores">ds:operational</datastore>
    <subtree-filter>
      <addresses xmlns="http://www.yumaworks.com/ns/taddress">
        <address/>
      </addresses>
    </subtree-filter>
    <with-origin/>
  </get-data>
</rpc>

Example Reply:

<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="3" xmlns:or="urn:ietf:params:xml:ns:yang:ietf-origin"
  xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <data xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-nmda">
    <addresses xmlns="http://www.yumaworks.com/ns/taddress">
      <address or:origin="or:system">
        <last-name>adams</last-name>
        <first-name>fred</first-name>
        <street>123 elm st.</street>
        <city>anytown</city>
        <zipcode or:origin="or:learned">90024</zipcode>
        <counter>
          <i>1</i>
          <c1>41</c1>
          <c2>42</c2>
        </counter>
        <counter>
          <i>2</i>
          <c1>43</c1>
          <c2>44</c2>
        </counter>
      </address>
      <address or:origin="or:system">
        <last-name>adams</last-name>
        <first-name>zed</first-name>
        <street>900 first st.</street>
        <city>anytown</city>
        <zipcode or:origin="or:learned">90024</zipcode>
        <counter>
          <i>1</i>
          <c1>45</c1>
          <c2>46</c2>
        </counter>
        <counter>
          <i>2</i>
          <c1>47</c1>
          <c2>48</c2>
        </counter>
      </address>
      <address or:origin="or:system">
        <last-name>flintstone</last-name>
        <first-name>fred</first-name>
        <street>1200 bc drive</street>
        <city>bedrock</city>
        <zipcode or:origin="or:learned">10204</zipcode>
        <counter>
          <i>1</i>
          <c1>49</c1>
          <c2>50</c2>
        </counter>
        <counter>
          <i>2</i>
          <c1>51</c1>
          <c2>52</c2>
        </counter>
      </address>
    </addresses>
  </data>
</rpc-reply>

<get-ha-status>

The <get-ha-status> operation is used to retrieve status information about the YP-HA service.

+---x get-ha-status
   +--ro output
      +--ro ha-status
         +--ro ha-built?             boolean
         +--ro ha-role-state?        HaRoleState
         +--ro ha-role-state-time?   yang:date-and-time
         +--ro ha-enabled?           boolean
         +--ro ha-sil-standby?       boolean
         +--ro ha-server*            string
         +--ro ha-server-key?        string
         +--ro ha-initial-active?    string
         +--ro socket-type?          enumeration
         +--ro socket-address?       inet:ip-address
         +--ro socket-port?          inet:port-number
         +--ro server-id?            yt:NcxName
         +--ro config-id?            uint64
         +--ro config-stamp?         yang:date-and-time
         +--ro config-updates?       yang:counter64
         +--ro config-failures?      yang:counter64
         +--ro active-server?        yt:NcxName
         +--ro last-error-time?      yang:date-and-time
         +--ro last-error-msg?       string

HA Role State

The following typedef is used to convey the current HA role state of a server

typedef HaRoleState {
  type enumeration {
    enum none {
      description HA_STATE_NONE;
    }
    enum disabled {
      description HA_STATE_DISABLED;
    }
    enum error {
      description HA_STATE_ERROR;
    }
    enum wait-role {
      description HA_STATE_WAIT_ROLE;
    }
    enum be-active {
      description HA_STATE_BE_ACTIVE;
    }
    enum active {
      description HA_STATE_ACTIVE;
    }
    enum be-standby {
      description HA_STATE_BE_STANDBY;
    }
    enum standby {
      description HA_STATE_STANDBY;
    }
    enum shutting-down {
      description HA_STATE_SHUTTING_DOWN;
    }
  }
  description "YP-HA role state enumerations";
}

The role states that are considered “stable” are:

  • none: no HA state assigned. If ha-enabled=true then this will block all management sessions (except DB-API subrpc requests will be processed)

  • active: this is the HA active server. Only one per HA pool should exist in an HA pool.

  • standby: this is an HA standby server. One or more of these servers should exist in an HA pool.

HA Status Grouping

The following grouping is defined so the HA status information can be reused in different contexts.

It is currently used for the contents of the ha-status container in the RPC output for the <get-ha-status> operations.

grouping HaStatusParms {
  leaf ha-built {
    type boolean;
    description
      "Set to true if the WITH_YP_HA=1 parameter used to build
       the server code. Set to false otherwise. If false then no
       other parameters are actually active.  Only the HA related CLI
       parameter values will be reported.

       This must be set to 'true' for a working YP-HA configuration.";
  }

  leaf ha-role-state {
    type HaRoleState;
    description
      "Set to the current YP-HA role state enumeration.
       A 'correct' value depends on the configuration and the
       timing of the request returning the status.

       A stable YP-HA system will have one server with the ha-role-state
       value of 'active' and one or more servers with the value
       'standby'.";
  }

  leaf ha-enabled {
    type boolean;
    description
      "Set to the value of the --ha-enabled parameter.
       This must be set to 'true' for a working YP-HA configuration.";
  }

  leaf ha-sil-standby {
    type boolean;
    description
      "Set to the value of the --ha-sil-standby parameter.
       Either value can be used without affect on a working
       YP-HA configuration.";
  }

  leaf-list ha-server {
    type string;
    description
      "Set to the value of a --ha-server parameter.
       There will be one entry for each instance of
       the ha-server leaf-list, or no nodes present
       if there are none.

       There must be at least two entries for a working YP-HA
       configuration.";
  }

  leaf ha-server-key {
    type string;
    description
      "Set to the value of the --ha-server-key parameter.
       This node will not be present unless this parameter is set.

       This parameter must be set. A working YP-HA configuration
       requires this parameter to be set to the same value for
       all servers in the same HA pool.";
  }

  leaf ha-initial-active {
    type string;
    description
      "Set to the value of the --ha-initial-active parameter.
       This leaf will not be present unless it is set.

       This parameter is not required for a working YP-HA configuration.
       It will impact YP-HA behavior if it is present. In normal
       operation it should not be used.";
  }

  leaf socket-type {
    type enumeration {
      enum aflocal {
        description
          "An AF_LOCAL socket will be used for incoming sessions.";
      }
      enum tcp {
        description
          "An AF_INET socket will be used for incoming sessions.";
      }
    }
    description
      "Specifies the --socket-type parameter.
       This parameter must be set to 'tcp' in a working YP-HA configuration.";

  }

  leaf socket-address {
    when "../socket-type = 'tcp'";
    type inet:ip-address;
    description
      "Specifies the --socket-address parameter. This leaf is only relevant
       if the socket-type is set to 'tcp'. The value must match the
       address field in the ha-server entry for this server, or be set to
       the default '0.0.0.0'. The parameter actually means all IP addresses,
       not just IPv4 addresses.

       Examples:

          # if socket-address present it must match the ha-server for this server
          ha-server ha1@192.168.0.20:8989
          ha-server ha2@192.168.0.40
          socket-type tcp
          socket-address 192.168.0.20
          socket-port 8989

          # socket-address not present is OK
          ha-server ha1@192.168.0.20
          socket-type tcp
          socket-port 8088
      ";
  }

  leaf socket-port {
    when "../socket-type = 'tcp'";
    type inet:port-number;
    description
      "Specifies the --socket-port parameter. This leaf is only relevant
       if the socket-type is set to 'tcp'. The value must match the
       port field in the ha-server entry for this server. If that is
       not present then this leaf must be set to 8088 (the default)
       for a working YP-HA configuration.

       Examples:

          # if port in the ha-server then socket-port must match
          ha-server ha1@192.168.0.20:8989
          ha-server ha2@192.168.0.40
          socket-address 192.168.0.20
          socket-type tcp
          socket-port 8989

          # port must be 8088 if default used in ha-server
          ha-server ha1@192.168.0.20
          socket-type tcp
          socket-port 8088
      ";
  }

  leaf server-id {
    type yt:NcxName;
    description
       "The --server-id parameter.
        The default is 'server1' if this parameter is not set.
        This parameter must match the ha-server entry name for
        the server in a working YP-HA configuration.

       Example:

          # this ha-server is ha1
          ha-server ha1@192.168.0.20:8989
          ha-server ha2@192.168.0.40
          server-id ha1
      ";
  }

  leaf config-id {
    type uint64;
    description
      "The config-id ETag of the running datastore that is the current ID
       for YP-HA purposes. This leaf will only be present if the ha-role-state
       leaf is 'active' or 'standby'.

       This leaf should get updated to match the config-id of the
       <running> datastore if the configuration changes on the active HA server.
       It should be present on a working YP-HA configuration that has finished
       its initialization phase.";
   }

   leaf config-stamp {
     type yang:date-and-time;
      description
       "The config-id Last-Modified timestamp value for the running datastore
        for YP-HA purposes. This leaf is only present if the ha-role-state
        is set to 'active'.  It is not maintained on a standby server.

       This leaf should get updated to match the last-modified attribute of the
       <running> datastore if the configuration changes on the active HA server.
       It should be present on a working YP-HA configuration that has finished
       its initialization phase.";
   }

}

<get-ha-status> Operation Usage

Min parameters:

0

Max parameters:

0

Return type:

data

YANG file:

yumaworks-system.yang

Capabilities needed:

none

Mandatory Parameters:

  • none

Optional Parameters:

  • none

Returns:

  • ha-status container (See YANG definition above)

Possible Operation Errors:

  • access-denied

Example db-api-app Command:

> db-api-app --subrpc=get-ha-status --filespec=output1.xml

Example Reply for a server Waiting For HA Role

<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply xmlns="http://yumaworks.com/ns/yumaworks-system">
  <ha-status>
    <ha-built>true</ha-built>
    <ha-role-state>wait-role</ha-role-state>
    <ha-enabled>true</ha-enabled>
    <ha-sil-standby>false</ha-sil-standby>
    <ha-server>ha1@192.168.0.201</ha-server>
    <ha-server>ha2@192.168.0.198</ha-server>
    <ha-server-key>ha-andy-pool1</ha-server-key>
    <socket-type>tcp</socket-type>
    <socket-address>0.0.0.0</socket-address>
    <socket-port>8088</socket-port>
    <server-id>ha1</server-id>
  </ha-status>
</rpc-reply>

Example Reply for a server in Active HA Role

<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply xmlns="http://yumaworks.com/ns/yumaworks-system">
  <ha-status>
    <ha-built>true</ha-built>
    <ha-role-state>active</ha-role-state>
    <ha-enabled>true</ha-enabled>
    <ha-sil-standby>false</ha-sil-standby>
    <ha-server>ha1@192.168.0.201</ha-server>
    <ha-server>ha2@192.168.0.198</ha-server>
    <ha-server-key>ha-andy-pool1</ha-server-key>
    <socket-type>tcp</socket-type>
    <socket-address>0.0.0.0</socket-address>
    <socket-port>8088</socket-port>
    <server-id>ha1</server-id>
    <config-id>7693</config-id>
    <config-stamp>2021-08-30T20:00:44Z</config-stamp>
  </ha-status>
</rpc-reply>

Example Reply for a server in Standby HA Role

<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply xmlns="http://yumaworks.com/ns/yumaworks-system">
  <ha-status>
    <ha-built>true</ha-built>
    <ha-role-state>standby</ha-role-state>
    <ha-enabled>true</ha-enabled>
    <ha-sil-standby>false</ha-sil-standby>
    <ha-server>ha1@192.168.0.201</ha-server>
    <ha-server>ha2@192.168.0.198</ha-server>
    <ha-server-key>ha-andy-pool1</ha-server-key>
    <socket-type>tcp</socket-type>
    <socket-address>0.0.0.0</socket-address>
    <socket-port>8088</socket-port>
    <server-id>ha2</server-id>
  </ha-status>
</rpc-reply>

Example Reply for a server in stuck in be-active state.

  • This can happen if the --go-standby operation specifies an HA server that is not really the HA active server.

  • In this case the standby server needs to to reset its HA state (using the --go-none option).

<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply xmlns="http://yumaworks.com/ns/yumaworks-system">
  <ha-status>
    <ha-built>true</ha-built>
    <ha-role-state>be-standby</ha-role-state>
    <ha-enabled>true</ha-enabled>
    <ha-sil-standby>false</ha-sil-standby>
    <ha-server>ha1@192.168.0.201</ha-server>
    <ha-server>ha2@192.168.0.198</ha-server>
    <ha-server-key>ha-andy-pool1</ha-server-key>
    <socket-type>tcp</socket-type>
    <socket-address>0.0.0.0</socket-address>
    <socket-port>8088</socket-port>
    <server-id>ha2</server-id>
  </ha-status>
</rpc-reply>

<get-module-tags>

The <get-module-tags> operation is used to retrieve the installed module-tag configuration.

The module-tag and module names associated with each tag, are returned in the output.

+---x get-module-tags
   +--ro output
      +--ro module-tag* [tag]
         +--ro tag       string
         +--ro module*   string

YANG Definition

rpc get-module-tags {
   description
     "Get the list of configured module-tags.
      The --module-tagmap parameter is used to configure
      a module-tag.";
   output {
     list module-tag {
       key tag;
       leaf tag {
         type string;
         description "The module-tag value";
       }
       leaf-list module {
         type string;
         description "A module-name mapped to this module-tag";
       }
     }
   }
 }

<get-module-tags> Operation Usage

Min parameters:

0

Max parameters:

0

Return type:

data

YANG file:

yumaworks-system.yang

Capabilities needed:

none

Mandatory Parameters:

  • none

Optional Parameters:

  • none

Returns:

  • <module-tag>

    • type: list

    • Refer to the YANG definition for details

Possible Operation Errors:

  • access-denied

Example Request:

<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="3" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <get-module-tags xmlns="http://yumaworks.com/ns/yumaworks-system"/>
</rpc>

Example Reply:

<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="3" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <module-tag xmlns="http://yumaworks.com/ns/yumaworks-system">
    <tag>netconf</tag>
    <module>ietf-netconf-monitoring</module>
  </module-tag>
  <module-tag xmlns="http://yumaworks.com/ns/yumaworks-system">
    <tag>restconf</tag>
    <module>ietf-restconf-monitoring</module>
  </module-tag>
</rpc-reply>

<get-my-session>

The <get-my-session> operation is used to retrieve session customization data for the current session.

The session indent amount, line size, and default behavior for the with-defaults parameter can be controlled at this time.

The module yuma-mysession.yang must be enabled in the server configuration file or CLI parameters for this operation to be available.

+---x get-my-session
   +--ro output
      +--ro indent?           yt:IndentType
      +--ro linesize?         uint32
      +--ro with-defaults?    wd:with-defaults-mode
      +--ro message-indent?   int8

<get-my-session> Operation Usage

Min parameters:

0

Max parameters:

0

Return type:

data

YANG file:

yuma-mysession.yang

Capabilities needed:

none

Mandatory Parameters:

  • none

Optional Parameters:

  • none

Returns:

  • indent

    • type: int8 (range 0 .. 9)

    • This parameter specifies the desired logging indent amount for the session.

    • default: 2

  • linesize

    • type: uint32 (range 40 .. 1024)

    • This parameter specifies the desired line length for the session.

    • default: 72

  • with-defaults

    • type: enumeration (report-all report-all-tagged trim explicit)

    • This parameter specifies the desired default with-defaults behavior for the session. The server-wide default value is set with the --default-style configuration parameter.

    • default: none

  • message-indent

    • type: int8 (range -1 .. 9)

    • This parameter specifies the desired message indent amount for the session.

    • default: -1

Possible Operation Errors:

  • access-denied

Example Request:

<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="2">
  <myses:get-my-session xmlns:myses="http://netconfcentral.org/ns/mysession"/>
</nc:rpc>

Example Reply:

<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="2">
  <myses:indent xmlns:myses="http://netconfcentral.org/ns/mysession">3</myses:indent>
  <myses:linesize xmlns:myses="http://netconfcentral.org/ns/mysession">72</myses:linesize>
  <myses:with-defaults xmlns:myses="http://netconfcentral.org/ns/mysession">report-all</myses:with-defaults>
  <myses:message-indent xmlns:myses="http://netconfcentral.org/ns/mysession">-1</myses:message-indent>
</nc:rpc-reply>

<get-schema>

The <get-schema> operation is used to retrieve YANG modules and submodules from the server.

The 'YANG' and 'YIN' formats are supported for all YANG files loaded into the server.

If the <version> parameter is set to the empty string, then the server will return whichever version it supports. If multiple versions are supported, then the server will pick a canonical version, which may not be the most recent version.

The <identifier> parameter must contain the name of the YANG file without any path or file extension specification.

+---x get-schema
   +---w input
   |  +---w identifier    string
   |  +---w version?      string
   |  +---w format?       identityref
   +--ro output
      +--ro data?   <anyxml>

<get-schema> Operation Usage

Min parameters:

3

Max parameters:

3

Return type:

data

YANG file:

ietf-netconf-monitoring.yang

Capabilities needed:

:schema-retrieval

Mandatory Parameters:

  • identifier

    • type: string

    • This parameter specifies the name of the module to retrieve.

      • Do not use any path specification of file extension; just the module name is entered.

      • The name is case-sensitive, and must be specified exactly as defined.

  • version

    • type: string

    • This parameter specifies the version of the module to retrieve.

      • This will be the most recent YANG revision date string defined in a module revision statement.

      • If any version is acceptable, or if the specific version is not known, then use the empty string.

  • format

    • type: enumeration (XSD YANG YIN RNG)

    • This parameter specifies the format of the module to be retrieved. Only the YANG format is supported.

Returns:

  • <data> element (contents of the YANG file)

Possible Operation Errors:

  • access-denied

Example Request:

<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="55">
  <ns:get-schema xmlns:ns="urn:ietf:params:xml:ns:netconf:state">
    <ns:identifier>ietf-with-defaults</ns:identifier>
    <ns:format>YANG</ns:format>
    <ns:version/>
  </ns:get-schema>
</nc:rpc>

Example Reply:

<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="55">
  <ns:data xmlns:ns="urn:ietf:params:xml:ns:netconf:state">
    <!-- entire contents of YANG module would be here, no extra indenting -->
  </ns:data>
</nc:rpc-reply>

<get-server-version>

The <get-server-version> operation is used to retrieve the server version and build-date strings.

This information is provided in an RPC operation instead of the <operational> datadtore so it is available even if the datastores are not ready to use.

+---x get-server-version
 +--ro output
    +--ro version?      string
    +--ro build-date?   string

<get-server-version> Operation Usage

Min parameters:

0

Max parameters:

0

Return type:

data

YANG file:

yumaworks-system.yang

Capabilities needed:

none

Returns:

  • <version> element

    • The version string returned by the ncx_get_version API.

  • <build-date> element

    • The build-date string returned by the ncx_get_build_date API.

Possible Operation Errors:

  • operation-failed

    • Can occur if version string longer than 512 bytes.

Example Request:

<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="2"
  xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <get-server-version xmlns="http://yumaworks.com/ns/yumaworks-system"/>
</rpc>

Example Reply:

<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="2"
  xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <version xmlns="http://yumaworks.com/ns/yumaworks-system">21.10-5.1</version>
  <build-date xmlns="http://yumaworks.com/ns/yumaworks-system">Mar  9 2022</build-date>
</rpc-reply>

<get-support-save>

The <get-support-save> operation is used to retrieve technical support information from the server.

The XML data that is returned can be saved in a file and used by the support-save-app program to extract some data to help reproduce software issues.

This operation is tagged as nacm:default-deny-all, so normal users cannot invoke this operation.

The yumaworks-support-save.yang module must be loaded for this operation to be present.

If NACM is enabled then an explicit NACM rule must be used or a superuser session must be used. Otherwise the server will return an access-denied error.

Only one support-save operation can be in progress at once. A ‘resource-denied’ error is returned if another support-save operation is already in progress.

No duplicate local-names are allowed in the top-level child nodes of the support-save-data anydata container.

<support-save-data> Contents

container support-save-data {
   container bundles {
     list bundle {
       leaf name { type string; }
       leaf-list deviation { type string; }
       leaf-list module { type string; }
     }
   }

   container capabilities ->
     /ietf-netconf-monitoring:netconf-state/capabilities

   container config-data {
     container *name* (e.g. candidate) {
       anydata config;
     }
   }

   container datastores ->
      /ietf-netconf-monitoring:netconf-state/datastores

   container modules-state -> /ietf-yang-library:modules-state

   container modules-text {
     list module {
       leaf name { type string; }
       leaf revision { type string; }
       leaf source { type string; }
       leaf submodule { type empty; }
       leaf text { type string; }
     }
   }

   container program {
     leaf name { type string; }
     leaf version { type string; }
   }

   container sessions ->
      /ietf-netconf-monitoring:netconf-state/sessions

   container sils {
     list sil {
       leaf name { type string; }
       leaf revision { type string; }
       leaf bundle { type empty; }
       leaf sil-sa { type empty; }
     }
   }

   container system -> /yuma-system:system container
}
+---x get-support-save
    +--ro output
       +--ro support-save-data?   <anydata>

<get-support-save> Operation Usage

Min parameters:

0

Max parameters:

0

Return type:

data

YANG file:

yumaworks-support-save.yang

Capabilities needed:

None

Returns:

  • <support-save-data> element

Possible Operation Errors:

  • access-denied

  • resource-denied

Example Request:

<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="1" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <get-support-save xmlns="urn:ietf:params:xml:ns:yang:yumaworks-support-save"/>
</rpc>

Example Reply:

<rpc-reply message-id="1" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <support-save-data xmlns="urn:ietf:params:xml:ns:yang:yumaworks-support-save">
    <program>
      <name>netconfd-pro</name>
      <version>tiger-andy-supportsave-2017-08-07.14.26</version>
    </program>
    <system xmlns="http://netconfcentral.org/ns/yuma-system">
      <!-- contents removed for example -->
    </system>
    <!-- … contents removed for example -->
  </support-save-data>
</rpc-reply>

<kill-session>

The <kill-session> operation is used to force the termination of another NETCONF session. This is sometimes needed if an idle session which is holding one or more locks was abandoned. It may also be needed for security reasons. In any case, this operation should be used with extreme caution.

+---x kill-session
   +---w input
      +---w session-id    session-id-type

<kill-session> Operation Usage

Min parameters:

1

Max parameters:

1

Return type:

status

YANG file:

ietf-netconf.yang

Capabilities needed:

none

Mandatory Parameters:

  • session-id

    • type: uint32 (range: 1.. max)

    • default: none

    • This parameter specifies the session number of the currently active NETCONF session that should be terminated.

Optional Parameters:

  • none

Returns:

  • <ok/>

Possible Operation Errors:

  • access-denied

Example Request:

<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="42">
  <nc:kill-session>
    <nc:session-id>1</nc:session-id>
  </nc:kill-session>
</nc:rpc>

Example Reply:

<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="42">
  <nc:ok/>
</nc:rpc-reply>

<kill-subscription>

The <kill-subscription> operation is used to delete a notification subscription, using RFC 8639 subscriptions. This is required to used YANG Push. Any session can delete a subscription on any session, using this operation. NACM permissions are required to use this operation. By default is is not permitted.

This operation is not present unless the server is build with the WITH_YANG_PUSH=1 or EVERYTHING=1 make option and the “yang-push” bundle is loaded.

+---x kill-subscription
    +---w input
        +---w id    subscription-id

<kill-subscription> Operation Usage

Min parameters:

1

Max parameters:

1

Return type:

status

YANG file:

ietf-subscribed-notifications.yang

Capabilities needed:

none (bundle yang-push required)

Capabilities optional:

none

Mandatory Parameters:

  • id

  • type: subscription-id

  • This parameter specifies the subscription ID of the subscription to delete.

Optional Parameters:

  • none

Returns:

  • <ok/>

Possible Operation Errors:

  • access-denied

  • All error-tags and error-app-tags defined in RFC 8639 and RFC 8641 are supported

Example Request:

<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="2" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <kill-subscription xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications">
    <id>2</id>
  </kill-subscription>
</rpc>

Example Reply:

<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="2" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <ok/>
</rpc-reply>

When a subscription is terminated, a notification is sent to the subscription before it is deleted:

<?xml version="1.0" encoding="UTF-8"?>
<notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
  <eventTime>2020-09-07T00:51:08Z</eventTime>
  <subscription-terminated xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications">
    <id>2</id>
    <reason xmlns:sn="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications">sn:no-such-subscription</reason>
  </subscription-terminated>
</notification>

<load>

The <load> operation is used to load new YANG modules at run-time.

The module file must already be present in the module search path of the server.

There must not be any version of the module already loaded.

This operation is tagged as nacm:default-deny-all, so by default, only a superuser account is allowed to use it.

This operation appears in 2 YANG modules:

Note

If both yuma-system and yumaworks-system modules are loaded then the proper namespace must be used in any XML messages for these modules.

+---x load
    +---w input
    |  +---w module         nt:NcxName
    |  +---w revision?      nt:Date
    |  +---w deviation*     yt:NcModuleSpec
    |  +---w save-config?   boolean
    +--ro output
       +--ro mod-revision?   nt:Date

<load> Operation Usage

Min parameters:

1

Max parameters:

3

Return type:

data

YANG file:

Capabilities needed:

none

Mandatory Parameters:

  • module

    • The name of the YANG module to load

Optional Parameters:

  • revision

    • The revision date of the module to load. If missing, then server can select the version to use.

  • deviation

    • The name of a deviation module to load before loading this module. Zero or more instances of this parameter can be entered. Duplicates will be ignored.

  • save-config:

    • Save a module configuration file this module so it will be loaded after a server reboot. The default is 'false'.

Returns:

  • <mod-revision>

    • The revision date of the module that was already loaded, or was just loaded.

Possible Operation Errors:

  • access-denied

  • module not found

  • version not found

  • different version already loaded

  • module parsing errors

  • resource errors

Example Request:

<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="52">
  <nd:load xmlns:nd="http://netconfcentral.org/ns/netconfd">
    <nd:module>test2</nd:module>
  </nd:load>
</nc:rpc>

Example Reply:

<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="52">
  <nd:mod-revision xmlns:nd="http://netconfcentral.org/ns/netconfd">2008-10-15</nd:mod-revision>
</nc:rpc-reply>

<load-bundle>

The <load-bundle> operation is used to load new YANG modules at run-time, which are compiled together as a SIL bundle.

All modules in the SIL bundle must already be present in the module search path of the server.

There must not be any version of any modules in the bundle already loaded.

This operation is tagged as nacm:default-deny-all, so by default, only a super user account is allowed to use it.

+---x load-bundle
   +---w input
      +---w bundle         nt:NcxName
      +---w deviation*     yt:NcModuleSpec
      +---w save-config?   boolean

<load> Operation Usage

Min parameters:

1

Max parameters:

3

Return type:

status

YANG file:

yumaworks-system.yang

Capabilities needed:

none

Mandatory Parameters:

  • bundle

    • The name of the SIL bundle to load

Optional Parameters:

  • deviation

    • The name of a deviation module to load before loading this bundle. Zero or more instances of this parameter can be entered. Duplicates will be ignored.

  • save-config

    • Save a module configuration file this bundle so it will be loaded after a server reboot. The default is 'false'.

Returns:

  • status

Possible Operation Errors:

  • access-denied

  • module not found

  • SIL library not found

  • module parsing errors

  • resource errors

Example Request:

<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="166" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <load-bundle xmlns="http://yumaworks.com/ns/yumaworks-system">
    <bundle>interface-bundle</bundle>
  </load-bundle>
</rpc>

Example Reply:

<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="166">
  <nc:ok/>
</nc:rpc-reply>

<load-config>

The <load-config> operation is used internally to load the <running> datastore with the NV-stored configuration data.

Note

This is an internal API that is not accessible to any client protocols.

+---x load-config
   +---w input
      +---w config

<load-config> operation

Min parameters:

1

Max parameters:

1

Return type:

status

YANG file:

yuma-netconf.yang

Capabilities needed:

none

Mandatory Parameters:

  • config

    • The <config> element representing the datastore contents

Optional Parameters: none

Returns:

  • status

Possible Operation Errors:

  • YANG validation errors

  • file not found

  • resource errors

Example Request:

Internal RPC so not shown

Example Reply:

Internal RPC so not shown

<modify-subscription>

The <modify-subscription> operation is used to modify a notification subscription, using RFC 8639 subscriptions.

This operation is not present unless the server is build with the WITH_YANG_PUSH=1 or EVERYTHING=1 option and the “yang-push” bundle is loaded.

Refer to the <establish-subscription> operation for an introduction to the usage modes for this operation. Refer to the YANG Push section for complete usage information for this feature.

Usage Restrictions:

  • The type of subscription cannot be changed. An on-change push subscription cannot be changed to a periodic subscription and vice versa.

+---x modify-subscription
   +---w input
      +---w id                                               subscription-id
      +---w (target)
      |  +--:(stream)
      |  |  +---w (stream-filter)?
      |  |     +--:(by-reference)
      |  |     |  +---w stream-filter-name                   stream-filter-ref
      |  |     +--:(within-subscription)
      |  |        +---w (filter-spec)?
      |  |           +--:(stream-subtree-filter)
      |  |           |  +---w stream-subtree-filter?         <anydata> {subtree}?
      |  |           +--:(stream-xpath-filter)
      |  |              +---w stream-xpath-filter?           yang:xpath1.0 {xpath}?
      |  +--:(yp:datastore)
      |     +---w yp:datastore                               identityref
      |     +---w (yp:selection-filter)?
      |        +--:(yp:by-reference)
      |        |  +---w yp:selection-filter-ref              selection-filter-ref
      |        +--:(yp:within-subscription)
      |           +---w (yp:filter-spec)?
      |              +--:(yp:datastore-subtree-filter)
      |              |  +---w yp:datastore-subtree-filter?   <anydata> {sn:subtree}?
      |              +--:(yp:datastore-xpath-filter)
      |                 +---w yp:datastore-xpath-filter?     yang:xpath1.0 {sn:xpath}?
      +---w stop-time?                                       yang:date-and-time
      +---w (yp:update-trigger)?
         +--:(yp:periodic)
         |  +---w yp:periodic!
         |     +---w yp:period         centiseconds
         |     +---w yp:anchor-time?   yang:date-and-time
         +--:(yp:on-change) {on-change}?
            +---w yp:on-change!
               +---w yp:dampening-period?   centiseconds

<modify-subscription> Operation Usage

Min parameters:

2

Max parameters:

Return type:

status

YANG file:

Capabilities needed:

none (bundle yang-push required)

Capabilities optional:

none

Event Stream Subscription

Mandatory Parameters:

  • id

  • type: subscription-id

  • This parameter specifies the subscription ID of the subscription to modify.

Optional Parameters:

  • stream-filter: choice of 3 options

    • stream-filter-name:

      • type: stream-filter-ref

      • default: none

      • This parameter specifies the name of a stream filter to use in the /filters/stream-filter list

    • stream-subtree-filter:

      • type: anydata

      • default: none

      • This parameter specifies the inline subtree filter to use

    • stream-xpath-filter:

      • type: xpath1.0

      • default: none

      • This parameter specifies the inline XPath filter to use. Prefixes are not required but if they are provided then an “xmlns” attribute defining each prefix to namespace mapping must be present in the XML.

  • stop-time

    • type: date-and-time

    • default: none

    • This parameter specifies that replay mode is desired and the replay should stop including notifications with timestamps less than the specified value.

Datastore Subscription

Mandatory Parameters:

  • id

  • type: subscription-id

  • This parameter specifies the subscription ID of the subscription to modify.

Optional Parameters:

  • update-trigger: choice of 2 options

    • periodic

      • type: presence container

      • default: none

      • This parameter specifies that a periodic subscription is desired. These subscriptions are controlled by the --push-max-periodic parameter. A new subscription will only be established if the limit has not already been reached.

      • child period

        • type: centiseconds

        • default: none

        • This parameter specifies the period to wait between updates. The --push-min-period parameter is used to enforce restrictions beyond the standard.

      • child anchor-time

        • type: date-and-time

        • default: none

        • This parameter is not yet supported.

    • on-change

      • type: presence container

      • default: none

      • This parameter specifies that an on-change subscription is desired. These subscriptions are controlled by the --push-max-operational parameter, if the datastore parameter is ‘operational’. A new subscription will only be established if the limit has not already been reached.

      • child dampening-period

        • type: centiseconds

        • default: none

        • This parameter specifies the dampening period to wait between on-change updates. The --push-min-dampening parameter is used to enforce restrictions beyond the standard.

          This parameter can be left out for a simulated operational on-change subscription. In that case, the --push-simop-period parameter will be used instead. If both parameters apply, then the maximum value of both of them will be used as the dampening period value.

  • selection-filter: choice of 3 options

    • selection-filter-ref:

      • type: selection-filter-ref

      • default: none

      • This parameter specifies the name of a selection filter to use in the /filters/selection-filter list

    • datastore-subtree-filter:

      • type: anydata

      • default: none

      • This parameter specifies the inline subtree filter to use

    • datastore-xpath-filter:

      • type: xpath1.0

      • default: none

      • This parameter specifies the inline XPath filter to use. Prefixes are not required but if they are provided then an “xmlns” attribute defining each prefix to namespace mapping must be present in the XML.

  • stop-time

    • type: date-and-time

    • default: none

    • This parameter specifies that replay mode is desired and the replay should stop including notifications with timestamps less than the specified value.

Returns:

  • status

Possible Operation Errors:

  • access-denied

  • in-use (target database is locked by another session)

  • All error-tags and error-app-tags defined in RFC 8639 and RFC 8641 are supported

Example Usage:

The following example shows a request to start a get-bulk operation on the "interface" list:

<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="6"
 xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
 <get-bulk xmlns="http://yumaworks.com/ns/yumaworks-getbulk">
  <list-target>/interfaces-state/interface</list-target>
 </get-bulk>
</rpc>

The server might respond with the first list entry:

<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="6"
 xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
 <bulk xmlns="http://yumaworks.com/ns/yumaworks-getbulk">
  <data>
   <interface xmlns="urn:ietf:params:xml:ns:yang:ietf-interfaces">
    <name>lo</name>
    <type
     xmlns:ianaift="urn:ietf:params:xml:ns:yang:iana-if-type">ianaift:softwareLoopback</type>
    <admin-status>up</admin-status>
    <oper-status>up</oper-status>
    <if-index>1</if-index>
    <phys-address>00:00:00:00:00:00</phys-address>
    <speed>0</speed>
    <statistics>
     <in-octets>8001114</in-octets>
     <in-unicast-pkts>78785</in-unicast-pkts>
     <in-multicast-pkts>0</in-multicast-pkts>
     <in-discards>0</in-discards>
     <in-errors>0</in-errors>
     <out-octets>8001114</out-octets>
     <out-unicast-pkts>78785</out-unicast-pkts>
     <out-discards>0</out-discards>
     <out-errors>0</out-errors>
    </statistics>
   </interface>
  </data>
  <last-keys xmlns="http://yumaworks.com/ns/yumaworks-getbulk">
   <name xmlns="urn:ietf:params:xml:ns:yang:ietf-interfaces">lo</name>
  </last-keys>
 </bulk>
</rpc-reply>

<lock>

The <lock> operation is used to insure exclusive write access to an entire configuration database.

The <running> configuration can be locked at any time, if it is currently unlocked.

If the :startup capability is supported, the <startup> configuration can be locked at any time, if it is currently unlocked.

If the :candidate capability is supported, and it is not already locked, then it may usually be locked. However, the <candidate> configuration can only be locked if there are no edits already contained within it. A <discard-changes> operation may be needed to clear any leftover edits, if this operation fails with a 'resource-denied' error instead of a 'lock-denied' error.

If the session holding the lock is terminated for any reason, the lock will be released, as if the <unlock> operation was invoked.

+---x lock
    +---w input
       +---w target
          +---w (config-target)
             +--:(candidate)
             |  +---w candidate?   empty {candidate}?
             +--:(running)
             |  +---w running?     empty
             +--:(startup)
                +---w startup?     empty {startup}?

<lock> Operation Usage

Min parameters:

1

Max parameters:

1

Return type:

status

YANG file:

ietf-netconf.yang

Capabilities needed:

none

Capabilities optional:

Mandatory Parameters:

  • target

    • type: container with 1 of N choice of leafs

    • This parameter specifies the name of the target database to be locked.

    • container contents: 1 of N:

      • candidate

      • running

        • type: empty

        • capabilities needed: none

      • startup

        • type: empty

        • capabilities needed: startup

Optional Parameters:

  • none

Returns:

  • <ok/>

Possible Operation Errors:

  • access-denied

  • lock-denied (lock already held by <session-id> in the <error-info>)

  • resource-denied (candidate is dirty; <discard-changes> needed)

Example Request:

<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="62">
  <nc:lock>
    <nc:target>
      <nc:candidate/>
    </nc:target>
  </nc:lock>
</nc:rpc>

Example Reply:

<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="62">
  <nc:ok/>
</nc:rpc-reply>

<no-op>

The <no-op> operation is used for debugging and performance testing purposes.

This operation does not do anything. It simply returns <ok/>. It will be present in the system if --with-yuma-system=true.

+---x no-op

<no-op> Operation Usage

Min parameters:

0

Max parameters:

0

Return type:

status

YANG file:

yuma-system.yang

Capabilities needed:

none

Mandatory Parameters:

  • none

Optional Parameters:

  • none

Returns:

  • <ok/>

Possible Operation Errors:

  • access-denied

Example Request:

<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="63">
  <nd:no-op xmlns:nd="http://netconfcentral.org/ns/netconfd"/>
</nc:rpc>

Example Reply:

<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="63">
  <nc:ok/>
</nc:rpc-reply>

<partial-lock>

The <partial-lock> operation is used to lock part of the <running> database. The --target=running setting must be used for this operation to be available. Refer to RFC 5717 or the ietf-netconf-partial-lock.yang module for details on this operation.

+---x partial-lock
   +---w input
   |  +---w select*   yang:xpath1.0
   +--ro output
      +--ro lock-id        lock-id-type
      +--ro locked-node*   instance-identifier

<partial-lock> Operation Usage

Min parameters:

1

Max parameters:

1

Return type:

data

YANG file:

ietf-netconf-partial-lock.yang

Capabilities needed:

Mandatory Parameters:

  • <select>

    • type: XPath 1.0 string

    • This parameter contains an XPath expression for a node-set result, identifying the database nodes to lock.

    • One of more instances of this parameter is required.

    • The server allows relaxed XPath syntax. If prefixes are used, then a proper namespace declaration must be present in the request. If prefixes are not used, then any available namespace that matches the local name will be used.

Optional Parameters:

  • none

Returns:

  • <lock-id>

    • type: uint32 (range 1 .. MAX_UINT)

    • This data identifies the lock ID to use when releasing the lock with the <partial-unlock> operation.

    • There will be one of these elements in the reply.

  • <locked-node>

    • type: instance-identifier

    • This data identifies a locked node as a result of the request.

    • There will be one or more of these elements in the reply.

Possible Operation Errors:

  • access denied, in-use, resource-denied

Example Request:

<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="260">
  <pl:partial-lock xmlns:pl="urn:ietf:params:xml:ns:netconf:partial-lock:1.0">
    <pl:select>//interface</pl:select>
  </pl:partial-lock>
</nc:rpc>

Example Reply:

<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="260"
  xmlns:if="http://netconfcentral.org/ns/yuma-interfaces">
  <pl:lock-id xmlns:pl="urn:ietf:params:xml:ns:netconf:partial-lock:1.0">1</pl:lock-id>
  <pl:locked-node
    xmlns:pl="urn:ietf:params:xml:ns:netconf:partial-lock:1.0">/if:interfaces/if:interface[if:name='virbr0']</pl:locked-node>
  <pl:locked-node
    xmlns:pl="urn:ietf:params:xml:ns:netconf:partial-lock:1.0">/if:interfaces/if:interface[if:name='eth0']</pl:locked-node>
  <pl:locked-node
    xmlns:pl="urn:ietf:params:xml:ns:netconf:partial-lock:1.0">/if:interfaces/if:interface[if:name='lo']</pl:locked-node>
</nc:rpc-reply>

<partial-unlock>

The <partial-unlock> operation is used to unlock part of the <running> database that was previously locked with the <partial-lock> operation. Only the session that called <partial-lock> can release the lock with this operation.

The --target=running setting must be used for this operation to be available. Refer to RFC 5717 or the ietf-netconf-partial-lock.yang module for details on this operation.

+---x partial-unlock
   +---w input
      +---w lock-id    lock-id-type

<partial-unlock> Operation Usage

Min parameters:

1

Max parameters:

1

Return type:

status

YANG file:

ietf-netconf-partial-lock.yang

Capabilities needed:

Mandatory Parameters:

  • <lock-id>

    • type: unit32 (1 .. MAX_UINT)

    • This parameter contains the lock ID of the partial lock to release.

    • One of more instances of this parameter is required.

    • The server allows relaxed XPath syntax. If prefixes are used, then a proper namespace declaration must be present in the request. If prefixes are not used, then any available namespace that matches the local name will be used.

Optional Parameters:

  • none

Returns:

  • <ok/>

Possible Operation Errors:

  • access denied, invalid-value

Example Request:

<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="263">
  <pl:partial-unlock xmlns:pl="urn:ietf:params:xml:ns:netconf:partial-lock:1.0">
    <pl:lock-id>1</pl:lock-id>
  </pl:partial-unlock>
</nc:rpc>

Example Reply:

<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="263">
  <nc:ok/>
</nc:rpc-reply>

<refresh-backup-dir>

The <refresh-backup-dir> operation is used to refresh the /netconf-state/backup-files subtree. This operation allows the backup file directory contents to be altered at run-time outside the control of the server. The 'backup-file' list entries within the 'backup-files' container will be refreshed.

This operation is only present if the --with-yumaworks-system=true setting is used.

+---x refresh-backup-dir

<refresh-backup-dir> Operation Usage

Min parameters:

0

Max parameters:

0

Return type:

ok

YANG file:

yumaworks-system.yang

Capabilities needed:

none

Mandatory Parameters:

  • none

Optional Parameters:

  • none

Returns:

  • <ok>

Possible Operation Errors:

  • access denied, operation-failed

Example Request:

<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="2" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <refresh-backup-dir xmlns="http://yumaworks.com/ns/yumaworks-system"/>
</rpc>

Example Reply:

<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="2" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <ok/>
</rpc-reply>

<replay-config>

The <replay-config> operation is used internally to replay the <running> datastore contents to the internal SIL and SIL-SA callbacks. This is needed when the server instrumentation (e.g., SIL-SA subsystem) has reset and needs to be re-synched with the <running> datastore.

Note

This is an internal API that is not accessible to any client protocols.

+---x replay-config

<replay-config> Operation Usage

Min parameters:

0

Max parameters:

0

Return type:

status

YANG file:

yumaworks-internal.yang

Capabilities needed:

none

Mandatory Parameters: none

Optional Parameters: none

Returns:

  • status

Possible Operation Errors:

  • YANG validation errors

  • resource errors

Example Request:

Internal RPC so not shown

Example Reply:

Internal RPC so not shown

<restart>

The <restart> operation is used to restart the netconfd-pro server. This operation does not restart the entire operating system. The --with-yuma-system parameter must be set to 'true' for this operation to be present.

By default, only a 'superuser' account is allowed to invoke this operation. If permission is granted, then the current NETCONF session will dropped, during the server restart.

+---x restart

<restart> Operation Usage

Min parameters:

0

Max parameters:

0

Return type:

none

YANG file:

yuma-system.yang

Capabilities needed:

none

Mandatory Parameters:

  • none

Optional Parameters:

  • none

Returns:

  • none; session will be dropped upon success

Possible Operation Errors:

  • access denied

Example Request:

<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="63">
  <nd:restart xmlns:nd="http://netconfcentral.org/ns/netconfd"/>
</nc:rpc>

Example Reply: (none – server may send <ok/> before system shuts down.)

<restore>

The <restore> operation is used to load the running database from a named configuration backup file on the server. This operation is used with the <backup> operation.

Only local files are supported.

The --with-yumaworks-system parameter must be set to true for this operation to be present.

The 'agt_backup_dir' path string must be set to a valid directory.

By default, only a superuser account is allowed to invoke this operation.

+---x restore
   +---w input
      +---w filename    ywt:NcxFileName

<restore> Operation Usage

Min parameters:

1

Max parameters:

1

Return type:

status

YANG file:

yumaworks-system.yang

Capabilities needed:

none

Mandatory Parameters:

  • filename:

    • The file name with extension for the backup. The directory is determined by the agt_backup_dir profile variable. The file name string is specified by the NcxFileName typedef in yumaworks-types.yang.

Optional Parameters:

  • none

Returns:

  • <ok/>

Possible Operation Errors:

  • none

Example Request:

<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="6" trace-id="6"
  xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <restore xmlns="http://yumaworks.com/ns/yumaworks-system">
    <filename>foo.xml</filename>
  </restore>
</rpc>

Example Reply:

<rpc-reply message-id="6" trace-id="6"
  xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
  xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <ok/>
</rpc-reply>

<resync-subscription>

The <resync-subscription> operation is used to re-synchronize a push notification subscription, using RFC 8639 subscriptions. Only the session that started the subscription can use this operation on that session. The subscription must be for an on-change datastore type.

This operation is not present unless the server is build with the WITH_YANG_PUSH=1 or EVERYTHING=1 make flag and the “yang-push” bundle is loaded.

For YANG Push, a "resynch" means a full update is sent by the server, and further "patch" messages are updates to that full update.

+---x resync-subscription {on-change}?
   +---w input
      +---w id    sn:subscription-id

<resync-subscription> Operation Usage

Min parameters:

1

Max parameters:

1

Return type:

status

YANG file:

Capabilities needed:

none (bundle yang-push required)

Capabilities optional:

none

Mandatory Parameters:

  • id

  • type: subscription-id

  • This parameter specifies the subscription ID of the subscription to resynch.

Optional Parameters:

  • none

Returns:

  • <ok/>

Possible Operation Errors:

  • access-denied

  • All error-tags and error-app-tags defined in RFC 8639 and RFC 8641 are supported

Example Request:

<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="2"
 xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
 <resync-subscription xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-push">
  <id>1</id>
 </resync-subscription>
</rpc>

Example Reply:

<rpc-reply message-id="2" xmlns:ncx="http://netconfcentral.org/ns/yuma-ncx"
 xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
 <ok/>
</rpc-reply>

<set-log-level>

The <set-log-level> operation is used to configure the server logging verbosity level.

This operation is tagged as nacm:default-deny-all, so by default, only a superuser account is allowed to use it.

This operation appears in 2 YANG modules:

Note

If both yuma-system and yumaworks-system modules are loaded then the proper namespace must be used in any XML messages for these modules.

+---x set-log-level
   +---w input
      +---w log-level     nt:NcDebugType
      +---w log-stream?   enumeration

<set-log-level> Operation Usage

Min parameters:

1

Max parameters:

1

Return type:

status

YANG file:

Capabilities needed:

none

Mandatory Parameters:

  • log-level

    • type: enumeration (off, error, warn, info, debug, debug2, debug3, debug4)

    • default: none

    • This parameter specifies the server logging verbosity level.

Optional Parameters:

  • none

Returns:

  • <ok/>

Possible Operation Errors:

  • access-denied

Example Request:

<rpc message-id="2" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <set-log-level xmlns="http://netconfcentral.org/ns/yuma-system">
    <log-level>debug2</log-level>
  </set-log-level>
</rpc>

Example Reply:

<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="2">
  <nc:ok/>
</nc:rpc-reply>

<set-my-session>

The <set-my-session> operation is used to configure the session customization data for the current session.

The yuma-mysession.yang module must be enabled in the server configuration file or CLI parameters for this operation to be available.

Example:

module yuma-mysession

The following parameters can be set:

  • session indent amount for logging

  • line size for logging

  • with-defaults default behavior for this session

  • session indent amount for NETCONF XML protocol messages

+---x set-my-session
   +---w input
      +---w indent?           yt:IndentType
      +---w linesize?         uint32
      +---w with-defaults?    wd:with-defaults-mode
      +---w message-indent?   int8

<set-my-session> Operation Usage

Min parameters:

0

Max parameters:

4

Return type:

status

YANG file:

yuma-mysession.yang

Capabilities needed:

none

Mandatory Parameters:

  • none

Optional Parameters:

  • indent

    • type: uint32 (range 0 .. 9)

    • default: 3 (can be changed with the --indent configuration parameter)

    • This parameter specifies the desired indent amount for the session.

  • linesize

    • type: uint32 (range 40 .. 1024)

    • default: 72

    • This parameter specifies the desired line length for the session.

  • <with-defaults>

    • type: enumeration (report-all report-all-tagged trim explicit)

    • default: report-all

    • This parameter specifies the desired default with-defaults behavior for the session. This value will override the server-wide default value set with the --default-style configuration parameter.

  • message-indent

    • type: int8 (range -1 .. 9)

    • This parameter specifies the desired NETCONF XML message indent amount for the session.

    • default: -1

Returns:

  • <ok/>

Possible Operation Errors:

  • access-denied

  • invalid-value

Example Request:

<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="3">
  <myses:set-my-session xmlns:myses="http://netconfcentral.org/ns/mysession">
    <myses:indent>4</myses:indent>
    <myses:linesize>64</myses:linesize>
    <myses:with-defaults>trim</myses:with-defaults>
    <myses:message-indent>1</myses:message-indent>
  </myses:set-my-session>
</nc:rpc>

Example Reply:

<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="3">
  <nc:ok/>
</nc:rpc-reply>

<shutdown>

The <shutdown> operation is used to shut down the netconfd-pro server.

The <shutdown> operation is used to restart the netconfd-pro server. This operation does not restart the entire operating system. The --with-yuma-system parameter must be set to 'true' for this operation to be present.

By default, only a 'superuser' account is allowed to invoke this operation. If permission is granted, then the current NETCONF session will dropped, during the server restart.

+---x shutdown

<shutdown> Operation Usage

Min parameters:

0

Max parameters:

0

Return type:

none

YANG file:

yuma-system.yang

Capabilities needed:

none

Mandatory Parameters:

  • none

Optional Parameters:

  • none

Returns:

  • none; session will be dropped upon success

Possible Operation Errors:

  • access denied

Example Request:

<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="1">
  <nd:shutdown xmlns:nd="http://netconfcentral.org/ns/netconfd"/>
</nc:rpc>

Example Reply:

[no reply will be sent; session will be dropped instead.]

<unload>

The <unload> operation is used to remove a YANG module from the system:

  • The YANG module and all its SIL code (if any) will be removed from the running server. They will not be deleted from disk.

  • Remove any data nodes in the system from the module.

  • Remove the module from the server capabilities and NETCONF monitoring data.

  • Remove the module namespace from the system.

  • Note: this operation does not remove the --module parameter from the server configuration file if it exists.

The following conditions must be true for the unload to be attempted by the server:

  • The module is allowed to be unloaded. It is data-model and vendor specific whether a module can be removed at run-time.

  • There are no dependencies on the module being removed. No modules that import this module are also loaded.

  • The module was loaded into the server, either via the <load> operation or the --module configuration parameter.

  • No datastores are currently locked. The server will attempt to lock all datastores on behalf of the client

for the entire unload operation.

  • The candidate datastore does not contain any edits that have not been committed.

  • No confirmed-commit operation is in progress.

If all these conditions are met then the server will attempt to unload the specified module. The unload operation can fail for various reasons:

  • The client does not have write privileges for all data being deleted. This includes any top-level data nodes and any nested augment nodes in other modules.

  • The deletion of one or more nodes would cause the running datastore to fail any YANG validation tests in RFC 6020, sec. 8.3.3.

  • Server resource errors occur

The --with-yumaworks-system parameter must be set to 'true' for this operation to be present.

+---x unload
   +---w input
      +---w module           nt:NcxName
      +---w delete-config?   boolean

<unload> Operation Usage

Min parameters:

1

Max parameters:

2

Return type:

status

YANG file:

yumaworks-system.yang

Capabilities needed:

none

Mandatory Parameters:

  • module

    • type: string

    • This parameter specifies the name of the YANG module to be unloaded.

Optional Parameters:

  • delete-config

    • type: boolean

    • Delete the module configuration file for this module so it will not be loaded after a server reboot.

    • The default is 'false'.

Returns:

  • <ok/>

Possible Operation Errors:

  • access denied

  • validation errors

  • resource errors

Example Request:

<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="66" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <unload xmlns="http://yumaworks.com/ns/yumaworks-system">
    <module>test</module>
  </unload>
</rpc>

Example Reply:

<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="66">
  <nc:ok/>
</nc:rpc-reply>

<unload-bundle>

The <unload-bundle> operation is used to remove a SIL bundle (multiple YANG modules at once) from the system:

  • All the YANG modules in the bundle and all their SIL code (if any) will be removed from the running server. They will not be deleted from disk.

  • Remove any data nodes in the system from all the modules in the bundle.

  • Remove all the modules from the server capabilities and NETCONF monitoring data.

  • Remove all the module namespaces from the system.

  • Note: this operation does not remove the --bundle parameter from the server configuration file if it exists.

The following conditions must be true for the unload-bundle to be attempted by the server:

  • The bundle is allowed to be unloaded. It is data-model and vendor specific whether a bundle can be removed at run-time.

  • There are no dependencies on the modules being removed, from outside the bundle. No modules that import this module can be loaded after the bundle is unloaded.

  • The bundle was loaded into the server, either via the <load-bundle> operation or the --bundle configuration parameter.

  • No datastores are currently locked. The server will attempt to lock all datastores on behalf of the client for the entire unload-bundle operation.

  • The candidate datastore does not contain any edits that have not been committed.

  • No confirmed-commit operation is in progress.

If all these conditions are met then the server will attempt to unload-bundle the specified modules. The unload-bundle operation can fail for various reasons:

  • The client does not have write privileges for all data being deleted. This includes any top-level data nodes and any nested augment nodes in other modules.

  • The deletion of one or more nodes would cause the running datastore to fail any YANG validation tests in RFC 6020, sec. 8.3.3.

  • Server resource errors occur

The --with-yumaworks-system parameter must be set to 'true' for this operation to be present.

+---x unload-bundle
   +---w input
      +---w bundle           nt:NcxName
      +---w delete-config?   boolean

<unload-bundle> Operation Usage

Min parameters:

1

Max parameters:

2

Return type:

status

YANG file:

yumaworks-system.yang

Capabilities needed:

none

Mandatory Parameters:

  • bundle

    • type: string

    • This parameter specifies the name of the YANG module to be unloaded.

Optional Parameters:

  • delete-config

    • type: boolean

    • Delete the module configuration file for this bundle so it will not be loaded after a server reboot.

    • The default is 'false'.

Returns:

  • <ok/>

Possible Operation Errors:

  • access denied

  • validation errors

  • resource errors

Example Request:

<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="69" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <unload-bundle xmlns="http://yumaworks.com/ns/yumaworks-system">
    <bundle>bundle1</bundle>
  </unload-bundle>
</rpc>

Example Reply:

<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="69">
  <nc:ok/>
</nc:rpc-reply>

<unlock>

The <unlock> operation is used to release a global lock held by the current session.

The specified configuration database must be locked, or a 'no-access' <error-app-tag> and an <error-message> of 'wrong-config-state' will be returned.

If the <candidate> configuration contains any edits that have not been committed, then these edits will all be lost if the <unlock> operation is invoked. A <discard-changes> operation is performed automatically by the server when the <candidate> database is unlocked.

+---x unlock
   +---w input
      +---w target
         +---w (config-target)
            +--:(candidate)
            |  +---w candidate?   empty {candidate}?
            +--:(running)
            |  +---w running?     empty
            +--:(startup)
               +---w startup?     empty {startup}?

<unlock> Operation Usage

Min parameters:

1

Max parameters:

1

Return type:

status

YANG file:

ietf-netconf.yang

Capabilities needed:

none

Capabilities optional:

Mandatory Parameters:

  • target

    • type: container with 1 of N choice of leafs

    • This parameter specifies the name of the target database to be unlocked.

    • container contents: 1 of N:

      • candidate

      • running

        • type: empty

        • capabilities needed: none

      • startup

        • type: empty

        • capabilities needed: startup

Optional Parameters:

  • none

Returns:

  • <ok/>

Possible Operation Errors:

  • access denied

  • no-access (database not locked)

  • invalid-value (database not supported)

Example Request:

<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="65">
  <nc:unlock>
    <nc:target>
      <nc:candidate/>
    </nc:target>
  </nc:unlock>
</nc:rpc>

Example Reply:

<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="65">
  <nc:ok/>
</nc:rpc-reply>

<validate>

The <validate> operation is used to perform the <commit> validation tests against a database or some in-line configuration data. Refer to RFC 7950 for YANG validation details and RFC 6241 for details on this operation.

The --with-validate parameter must be set to 'true' for this operation to be present.

Note

This server may report multiple YANG validation issues for this operation and only one report error during an actual edit operation.

An edit operation is automatically terminated on the first error so the write lock can be released as quickly as possible.

+---x validate {validate}?
    +---w input
       +---w source
          +---w (config-source)
             +--:(candidate)
             |  +---w candidate?   empty {candidate}?
             +--:(running)
             |  +---w running?     empty
             +--:(startup)
             |  +---w startup?     empty {startup}?
             +--:(url)
             |  +---w url?         inet:uri {url}?
             +--:(config)
                +---w config?      <anyxml>

<validate> Operation Usage

Min parameters:

1

Max parameters:

1

Return type:

status

YANG file:

ietf-netconf.yang

Capabilities needed:

:validate

Capabilities optional:

Mandatory Parameters:

  • target

    • type: container with 1 of N choice of leafs

    • This parameter specifies the name of the target database, or the in-line configuration data, that should be validated.

    • container contents: 1 of N:

      • candidate

      • running

        • type: empty

        • capabilities needed: none

      • startup

        • type: empty

        • capabilities needed: startup

      • config

        • type anyxml

        • capabilities needed: none

Optional Parameters:

  • none

Returns:

  • <ok/>

Possible Operation Errors:

  • access denied

  • YANG validation errors

Example Request:

<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="76">
  <nc:validate>
    <nc:source>
      <nc:candidate/>
    </nc:source>
  </nc:validate>
</nc:rpc>

Example Reply:

<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="76">
  <nc:ok/>
</nc:rpc-reply>

Access Control

The netconfd-pro access control data model is defined in ietf-netconf-acm.yang (RFC 8341)

The nacm:default-deny-write and nacm:default-deny-all extensions also affect access control. If present in the YANG definition, then the default behavior (when no rule is found) is not followed. Instead, a superuser account must be used to allow default access.

There are 3 types of access control rules that can be defined:

  1. module rule

  2. RPC operation rule

  3. database rule

Rules apply to one or more groups. Each group contains zero or more user names. Database rules are applied top-down, at every level.

The user needs permission for the requested access (read or write) for all referenced nodes within the database. For example, if there was a leaf from module X that augments a container in module Y, the user would need permission to access the container from module Y, and then permission to access the leaf from module X.

The NACM data model can be used without any configuration at all. Refer to the Access Control Modes section for more details.

../_images/nacm_overview.png

Normally, some configuration is required:

  • groups: configure one or more administrative groups

  • rules: configure one or more access control rules

The entire /nacm subtree is tagged as nacm:default-deny-all. By default, only a superuser account can read or write any of its contents. It is suggested that even read access to this data structure be controlled carefully at all times.

The /nacm subtree is described in the ietf-netconf-acm.yang section and RFC 8341.

Bypassing Access Control

By default, no configuration data can be edited. Even if the NACM write-default is set to permit, the /nacm subtree cannot be edited by default.

The --superuser CLI parameter can be used to allow the specified user sessions to bypass NACM enforcement. This can be used to configure NACM groups and rule-lists, and access all API components normally protected by NACM.

Access control can also be completely disabled by setting the --access-control CLI parameter to off. This is not recommended!

Users and Groups

Access rights in NACM are given to groups.

A group entry consists of a group identifier and a list of user names that are members of the group.

By default, there are no groups created. Each /nacm/groups/group entry must be created by the client. There is no user name table either. It is assumed that the operator will know which user names are valid within each managed device.

Creating New Groups

The <edit-config> operation can be used to create new group entries.

  • A user name can appear within the same group zero or one times.

  • A user name can appear in zero or more groups.

When a user is a member of multiple groups, all these groups will be used to match against rules, in a conceptual 'OR' expression. If any of these groups matches one of the <allowed-group> leaf-list nodes within one of the 3 rule types, then that rule will be the one that is used. Rules are always searched in the order they are entered, even the system-ordered lists.

The path to the group element is /nacm:nacm/nacm:groups/nacm:group.

The following <edit-config> example shows how a group can be defined. The group name is 'admi1',and the users 'user1' and 'user2' are the initial members of this group.

<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="1" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <edit-config>
    <target>
      <candidate/>
    </target>
    <default-operation>merge</default-operation>
    <test-option>set</test-option>
    <config>
      <nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm">
        <groups>
          <group xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
            nc:operation="merge">
            <name>admin1</name>
            <user-name>user1</user-name>
            <user-name>user2</user-name>
          </group>
        </groups>
      </nacm>
    </config>
  </edit-config>
</rpc>

Access Control Modes

The --access-control configuration parameter is used to globally enable or disable the access control system. It cannot be changed at run-time, or through a NETCONF session.

  • off: no access control enforcement is done at all.

  • disabled: all nacm:default-deny-write and nacm:default-deny-all tagged objects will require a superuser account to access, but no other access control enforcement will be done.

  • permissive: all nacm:default-deny-all objects will require super user account to read. No other read access enforcement will be done. Write and exec access will be checked.

  • enforcing: all access control enforcement will be checked. This is the default behavior.

Permissions

There are 3 types of access permissions defined:

  1. read: retrieval of any kind

  2. write: modification of any kind

  3. exec: right to invoke an RPC operation

The <allowed-rights> object in each of the 3 access control rule entries is a 'bits' leaf, which is allowed to contain any of these string tokens, or none of them to deny all access to a set of groups.

When a rule is found which matches the current request, the <allowed-rights> leaf will be used to grant permission or not. If the bit for the requested operation is present, then the request is permitted. If the bit is not present, then the request is denied.

Special YANG Extensions For Access Control

There are 3 YANG language extensions defined that can be used to force access control behavior for specific data nodes in the configuration database.

  1. nacm:default-deny-write (no parameter) If present in a data node statement, this extension will cause the write default to be ignored, and any write access to instances of this object will be rejected with an 'access-denied' error unless there is an explicit NACM rule allowing write access to the user session. If present in an 'rpc' statement, then exec access will be denied unless there is an explicit NACM rule granting exec access.

  2. nacm:default-deny-all (no parameter) If present in a data node statement, this extension will cause the read and write defaults to be ignored, and any write access to instances of this object will be rejected with an 'access-denied' error unless there is an explicit NACM rule allowing write access to the user session. Read access will be denied, which causes that data to be removed from the <rpc-reply>. If present in an 'rpc' statement, then exec access will be denied unless there is an explicit NACM rule granting exec access.

  3. ncx:user-write (parameter: permitted, type: bits: create, update, delete) Used within database configuration data definition statements to control user write access to the database object containing this statement. The 'permitted' argument is a list of operations that users are permitted to invoke for the specified node. These permissions will over-ride all NACM access control rules, even if NACM is disabled. To dis-allow all user access, provide an empty string for the 'permitted' parameter.

    To allow only create and delete user access, provide the string 'create delete' for the parameter. Use this for YANG database objects that cannot be changed once they are set.

Default Enforcement Behavior

Each access type has a default behavior if no rule is found and no special YANG extensions apply:

  • read default: permit

  • write default: deny

  • exec default: permit

These defaults can be changed by the server developer, by modifying the YANG definitions in ietf-netconf-acm.yang. If the data node object definition contains the special YANG extensions described in the previous section, then the extension will define default access and the NACM default access rule will not be used.

Access Control Algorithm

The access control enforcement procedures are defined in RFC 6536, section 3.4

YANG Extensions Affecting Access Control

The YANG extension ncx:password can be used in a YANG module (leaf definition) to identify password fields.

The "obj_is_password" function will be true for these objects, and any object that uses the “crypt-hash” typedef from the iana-crypt-hash.yang module.

Note

The "ncx:password" extension is deprecated and should not be used. It does not prevent disclosure of passwords in all cases. Use the "crypt-hash" data type instead.

The OpenConfig YANG extension oc-ext:openconfig-hashed-value can be used in a YANG module (leaf definition) to identify a password field with strict requirements for non-disclosure.

The initial cleartext password string is converted to a hash right away and only the hash is stored or displayed after that.

This extension should be used instead of "ncx:password" if the "crypt-hash" data type cannot be used.

Passwords and crypt-hash

Objects that are type “crypt-hash” will be processed by the server according to the following typedef from iana-crypt-hash.yang:

typedef crypt-hash {
  type string {
    pattern
      '$0$.*'
    + '|$1$[a-zA-Z0-9./]{1,8}$[a-zA-Z0-9./]{22}'
    + '|$5$(rounds=\d+$)?[a-zA-Z0-9./]{1,16}$[a-zA-Z0-9./]{43}'
    + '|$6$(rounds=\d+$)?[a-zA-Z0-9./]{1,16}$[a-zA-Z0-9./]{86}';
  }
  description
    "The crypt-hash type is used to store passwords using
     a hash function.  The algorithms for applying the hash
     function and encoding the result are implemented in
     various UNIX systems as the function crypt(3).

     A value of this type matches one of the forms:

       $0$<clear text password>
       $<id>$<salt>$<password hash>
       $<id>$<parameter>$<salt>$<password hash>

     The '$0$' prefix signals that the value is clear text.  When
     such a value is received by the server, a hash value is
     calculated, and the string '$<id>$<salt>$' or
     $<id>$<parameter>$<salt>$ is prepended to the result.  This
     value is stored in the configuration data store.
     If a value starting with '$<id>$', where <id> is not '0', is
     received, the server knows that the value already represents a
     hashed value and stores it 'as is' in the data store.

     When a server needs to verify a password given by a user, it
     finds the stored password hash string for that user, extracts
     the salt, and calculates the hash with the salt and given
     password as input.  If the calculated hash value is the same
     as the stored value, the password given by the client is
     accepted.

     This type defines the following hash functions:

       id | hash function | feature
       ---+---------------+-------------------
        1 | MD5           | crypt-hash-md5
        5 | SHA-256       | crypt-hash-sha-256
        6 | SHA-512       | crypt-hash-sha-512

     The server indicates support for the different hash functions
     by advertising the corresponding feature.";
  reference
    "IEEE Std 1003.1-2008 - crypt() function
     RFC 1321: The MD5 Message-Digest Algorithm
     FIPS.180-4.2012: Secure Hash Standard (SHS)";
}

Values of this datatype that match the “$0$” format will be converted and stored as a hash, according to the typedef specification.

  • The agt_profile field "agt_min_password_len" field will be used to enforce a minimum password length for the crypt-hash data type. The default value is 8.

  • The agt_profile field "agt_crypt_hash_prefix" field will be used to select the hash function that will be used for the conversion of $0$ format strings. The default value is SHA-512 ($6$).

  • The obj_is_password() function will be true for any crypt-hash data node

Password Storage

  • The "crypt-hash" data type must be used (with mode 5 or 6) to avoid exposure of a cleartext password by the client in the initial password configuration edit request.

  • Otherwise, the "crypt-hash" data type (mode 0) or the "openconfig-hashed-value" extension should be used if

There are more details about password storage and password exposure during logging in the KnowledgeBase article Passwords Stored in YANG Data

Using Module Tags with NACM

There is a "module-tag" extension to NACM defined in yumaworks-system.yang

augment /nacm:nacm/nacm:rule-list/nacm:rule/nacm:rule-type {
  case module-tags {
    uses ywapp:ModuleTagParm;
  }
}

This extension adds a new rule-type called module-tags.

A list of module-tag strings can be used to select the modules that are mapped to the NACM rule.

It is similar to a data-rule which selects a path, except it selects all objects from the specified module(s) for RPC, notification, and data node access control.

Module-tags are more flexible than the module-name leaf provided in the NACM rule entry.

It is recommended that this field be set to the default ‘*’ if the module-tag parameter is used.

Example:

The following module-tag is used:

module-tagmap ietf-restconf-monitoring@restconf

The module ietf-restconf-monitoring is mapped to the module-tag “restconf”.

The following NACM configuration contains a module-tags rule:

<nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm">
  <read-default>deny</read-default>
    <groups>
      <group>
        <name>g1</name>
        <user-name>netconf1</user-name>
      </group>
    </groups>
  <rule-list>
    <name>rl1</name>
    <group>g1</group>
    <rule>
      <name>r1</name>
      <module-name>*</module-name>
      <access-operations>*</access-operations>
      <action>permit</action>
      <comment/>
      <module-tag xmlns="http://yumaworks.com/ns/yumaworks-system">restconf</module-tag>
    </rule>
  </rule-list>
</nacm>

This rule allows group “g1” all access to the modules tagged with the module-tag “restconf”.

An example <get> request returns only the data from the ietf-restconf-monitoring.yang module.

netconf1@localhost> get

RPC Data Reply 3 for session 4 [default]:

rpc-reply {
  data {
    restconf-state {
      capabilities {
        capability urn:ietf:params:restconf:capability:depth:1.0
        capability urn:ietf:params:restconf:capability:with-defaults:1.0
        capability urn:ietf:params:restconf:capability:defaults:1.0?basic-mode=report-all
        capability urn:ietf:params:restconf:capability:fields:1.0
        capability urn:ietf:params:restconf:capability:replay:1.0
        capability urn:ietf:params:restconf:capability:filter:1.0
        capability urn:ietf:params:restconf:capability:yang-patch:1.0
      }
      streams {
        stream RESTCONF {
          name RESTCONF
          description 'default RESTCONF event stream'
          replay-support true
          replay-log-creation-time 2018-04-27T21:45:56Z
          access xml {
            encoding xml
            location http://localhost/restconf/stream
          }
        }
      }
    }
  }
}

Using RESTCONF

WEB application developers have different tools and a resource-oriented data model which tends to keep them from adopting NETCONF over SSH as a programatic interface.

The RESTCONF Protocol is defined in RFC 8040.

The YANG Patch media type used by RESTCONF is defined in RFC 8072.

A WEB server is required to use RESTCONF.

It must support the FastCGI API, which is used by the restconf program for REST access to the netconfd-pro server

Refer to the RESTCONF Installation section installation instructions.

The restconf program is a FastCGI thin client that connects the WEB server to the netconfd-pro server to process HTTP requests.

It is usually installed in the /var/www/yang-api folder.

RESTCONF Features

The RESTCONF server has the following features:

  • Complete implementation of RESTCONF protocol, defined in RFC 8040

  • Complete implementation of YANG Patch, defined in RFC 8072.

  • Automatic support for all NETCONF operations, including the YANG 'insert' operation, defined in RFC 7950.

  • Supports the complete HTTP/1.1 transport defined in RFC 7230.

  • Complete XML 1.0 implementation with full support for XML Namespaces

  • Complete JSON implementation defined in RFC 7951

  • Automatic support for all capability registration and <hello> message processing

  • Fully recoverable, automatic database editing, using a simple 3 phase callback model

      1. validate, 2) apply, 3) commit or rollback

  • Full support for database locking, editing, validation, including extensive user-callback capabilities to support device instrumentation.

  • Complete <rpc-error> reporting support, including user-defined errors via YANG error-app-tag and error-message statements.

  • Several <rpc-error> extensions, including <bad-value> and <error-number>, for easier debugging

  • Extend error handling

    • HTTP status-lines are used to report success or failure for RESTCONF operations. Error information is returned for "4xx" class of status codes. This error information is adapted for use in RESTCONF.

  • Complete RFC 5277 Notification support, including notification replay via SSE W3C Working Draft

  • Complete RFC 7895 YANG Module Library support, including full support of the YANG modules schema retrieval from the server and support of server-specific identifier representing the current set of modules and submodules.

  • Support new query parameters:

    • The "depth" parameter is used to limit the number of levels of child resources that are returned by the server for a GET method request.

    • The "content" parameter is used to select the type of data child resources (configuration or not configuration, or all data) that are returned by the server for a GET method request.

    • The “with-defaults” parameter is used to select the type of data (report-all, report-all-tagged, trim, explicit) that are returned by the server for a GET method request.

  • Support GET on /restconf/data

    • This mandatory resource represents the combined configuration and operational data resources that can be accessed by a client. It cannot be created or deleted by the client.

  • Support POST /restconf/operations

    • This optional resource is a container that provides access to the data-model specific protocol operations supported by the server. The server may omit this resource if no data-model specific operations are advertised.

    • Any data-model specific operations defined in the YANG modules advertised by the server may be available as child nodes of this resource.

  • RESTCONF capability support /restconf/data/restconf-state

    • RESTCONF provides the YANG module capability information supported by the server, in case the client wants to use it. The URIs for custom protocol operations and datastore content are predictable, based on the YANG module definitions.

  • Support for new POST and PUT/create operations

    • Support POST/PUT Request based on query parameters and protocol

  • Two "edit collision detection" mechanisms are provided in RESTCONF, for datastore and data resources.

    • Timestamps

    • Entity Tag

  • Support full conformance

    • Support Accept header validation

    • Support .well-known. The root of the RESTCONF API configured on the HTTP server, discovered by getting the .well-known/host-meta

    • Support ietf-restconf-monitoring

    • Supports notifications that populate a stream resource for each notification delivery service access point. A RESTCONF client can retrieve the list of supported event streams from a RESTCONF server using the GET operation on the /restconf/data/restconf-state/streams list.

    • Supports a new event stream resource. This resource represents an SSE (Server-Sent Events) event stream. The content consists of text using the media type "text/event-stream", as defined by the HTML5 specification. Each event represents one <notification> message generated by the server. It contains a conceptual system or data-model specific event that is delivered within an event notification stream. Also called a "stream resource".

RESTCONF Resource Types

A RESTCONF client can determine the root of the RESTCONF API by getting the /.well-known/host-meta resource and using the <Link> element containing the "restconf" attribute:

Example Request:

GET /.well-known/host-meta HTTP/1.1
Host: example.com
Accept: application/xrd+xml

Example Response:

HTTP/1.1 200 OK
Content-Type: application/xrd+xml
Content-Length: 106

<XRD xmlns='http://docs.oasis-open.org/ns/xri/xrd-1.0'>
  <Link rel='restconf' href='/restconf'/>
</XRD>

Once discovering the RESTCONF API root, the client must prepend it to any subsequent request to a RESTCONF resource. For instance, using the /restconf path discovered above, the client can now determine the operations supported by the server.

Example Request:

GET /restconf/operations HTTP/1.1
Host: *example.com*
Accept: application/yang-data+xml

Example Response:

<operations xmlns="urn:ietf:params:xml:ns:yang:ietf-restconf">
  <backup xmlns="http://yumaworks.com/ns/yumaworks-system"/>
  <cancel-subscription xmlns="http://yumaworks.com/ns/yumaworks-system"/>
  <clear-eventlog xmlns="http://yumaworks.com/ns/yumaworks-event-stream"/>
  <create-subscription xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0"/>
  <delete-backup xmlns="http://yumaworks.com/ns/yumaworks-system"/>
  <delete-subscription xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications"/>
  <establish-subscription xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications"/>
  <get-bulk xmlns="http://yumaworks.com/ns/yumaworks-getbulk"/>
  <get-ha-status xmlns="http://yumaworks.com/ns/yumaworks-system"/>
  <get-module-tags xmlns="http://yumaworks.com/ns/yumaworks-system"/>
  <get-schema xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring"/>
  <get-support-save xmlns="urn:ietf:params:xml:ns:yang:yumaworks-support-save"/>
  <kill-subscription xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications"/>
  <load xmlns="http://netconfcentral.org/ns/yuma-system"/>
  <load xmlns="http://yumaworks.com/ns/yumaworks-system"/>
  <load-bundle xmlns="http://yumaworks.com/ns/yumaworks-system"/>
  <modify-subscription xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications"/>
  <no-op xmlns="http://netconfcentral.org/ns/yuma-system"/>
  <partial-lock xmlns="urn:ietf:params:xml:ns:netconf:partial-lock:1.0"/>
  <partial-unlock xmlns="urn:ietf:params:xml:ns:netconf:partial-lock:1.0"/>
  <refresh-backup-dir xmlns="http://yumaworks.com/ns/yumaworks-system"/>
  <restart xmlns="http://netconfcentral.org/ns/yuma-system"/>
  <restore xmlns="http://yumaworks.com/ns/yumaworks-system"/>
  <resync-subscription xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-push"/>
  <set-log-level xmlns="http://netconfcentral.org/ns/yuma-system"/>
  <set-log-level xmlns="http://yumaworks.com/ns/yumaworks-system"/>
  <shutdown xmlns="http://netconfcentral.org/ns/yuma-system"/>
  <unload xmlns="http://yumaworks.com/ns/yumaworks-system"/>
  <unload-bundle xmlns="http://yumaworks.com/ns/yumaworks-system"/>
</operations>

The RESTCONF resources are accessed via a set of URIs. The set of YANG modules supported by the server will determine the data model specific operations, top-level data node resources, and event notification messages supported by the server.

The RESTCONF protocol defines a set of application specific media types to identify each of the available resource types. The following resource types are defined in RESTCONF:

RESTCONF Resource Types

API

{+restconf}

{+restconf} /operations

{+restconf} /version

{+restconf} /yang-library -version

{+yang-api}

application /yang-data+xml

application/ yang-data+json

Datastore

{+restconf} /data

{+yang- api}/datastore

application /yang-data+xml

application/ yang-data+json

Data

{+restconf} /data/node

{+yang-api}/ datastore/node

application /yang-data+xml

application/ yang-data+json

Errors

RESTCONF specific error handling

Not-supported, standard NETCONF-based error handling

application /yang-data+xml

application/ yang-data+json

Operation

{+restconf} /operations/ <operation>

{+yang-ap i}/operations/ <operation>

application /yang-data+xml

application/ yang-data+json

Schema

{+restconf} /yang

not-supported

application /yang

Event Stream

{+restconf} /streams

{+ya ng-api}/events

text /event-stream

Note: Only RESTCONF protocol supports Accept header validation and media types utilization.

RESTCONF Headers

There are several HTTP header lines utilized in RESTCONF messages. Messages are not limited to the HTTP headers listed in this section.

HTTP defines which header lines are required for particular circumstances. There are some request headers that are used within RESTCONF, usually applied to data resources. The following tables summarize the headers most relevant in RESTCONF message requests:

RESTCONF Request Headers

Accept

Response Content-Types that are acceptable

Content-Type

The media type of the request body

Host

The host address of the server

If-Match

Only perform the action if the entity matches ETag

If-Modified-Since

Only perform the action if modified since time

If-Unmodified-Since

Only perform the action if unmodified since time

The following tables summarize the headers most relevant in RESTCONF message responses:

RESTCONF Response Headers

Allow

Valid actions when 405 error returned

Cache-Control

The cache control parameters for the response

Content-Type

The media type of the response message-body

Date

The date and time the message was sent

ETag

An identifier for a specific version of a resource

Last-Modified

The last modified date and time of a resource

Location

The resource identifier for a newly created resource

The --restconf-strict-headers parameter specifies the server validation rules for Accept and Content-Type headers entries. If set to 'true' the server will only accept requests with normative header entries specified in RFC 8040. If set to 'false', the server will try to accept not normative header entries. The default is false.

RESTCONF Query Parameters

Each RESTCONF operation allows zero or more query parameters to be present in the request URI. The specific parameters that are allowed depends on the resource type, and sometimes the specific target resource used, in the request.

RESTCONF Query Parameters

content

GET

Select config and/or non-config data resources

depth

GET

Request limited sub-tree depth in the

fields

GET

Return all descendant data nodes reply content

filter

GET

Boolean notification filter for event stream resources

insert

POST/ PUT

Insertion mode for user-ordered data resources

point

POST/ PUT

Insertion point for user-ordered data resources

start-time

GET

Replay buffer start time for event stream resources

stop-time

GET

Replay buffer stop time for event stream resources

with-defaults

GET

Control retrieval of default values

Query parameters can be given in any order. Each parameter can appear at most once in a request URI. A default value may apply if the parameter is missing.

If vendors define additional query parameters, they should use a prefix (such as the enterprise or organization name) for query parameter names in order to avoid collisions with other parameters.

Depth Query Parameter

In the RESTCONF implementation the "depth" parameter is used to limit the number of levels of child resources that are returned by the server for a GET method request.

leaf depth {
   type union {
     type enumeration {
       enum unbounded;
     }
     type uint32 {
       range "1..max";
     }
   }
   default unbounded;   // set to 1 in draft-01!
   description "Resource retrieval depth requested";
 }

The start level is determined by the target resource for the operation.

The first nest-level consists of the requested data node itself. Any child nodes which are contained within a parent node have a depth value that is 1 greater than its parent, so that a depth level of "1" includes just the target resource level itself. A depth level of "2" includes the target resource level and its child nodes.

To retrieve all the child resources, the "depth" parameter is not present or set to the default value "unbounded". The value of the "depth" parameter is either an integer between 1 and 65535, or the string "unbounded". "unbounded" is the default.

This parameter is only allowed for GET methods on API, datastore, and data resources. A 400 Bad Request error is returned if it used for other methods or resource types.

By default, the server will include all sub-resources within a retrieved resource, which have the same resource type as the requested resource. Only one level of sub-resources with a different media type than the target resource will be returned.

If the "depth" query parameter URI is listed in the "capability" leaf-list, then the server supports the "depth" query parameter.

Content Query Parameter

The "content" parameter is used to select the type of data child resources (configuration and/or not configuration) that are returned by the server for a GET method request.

The "content" parameter controls how descendant nodes of the requested data nodes will be processed in the reply.

The allowed values are:

config

Return only configuration descendant data nodes

nonconfig

Return only non-configuration descendant data nodes

all

Return all descendant data nodes

This parameter is only allowed for GET methods on datastore and data resources. A 400 Bad Request error is returned if used for other methods or resource types. The default value is for the "content" parameter is "nonconfig".

To retrieve all the child resources, the "content" parameter is set to "all".

The client might send:

GET /restconf/data/example-events:events?content=all HTTP/1.1
Host: example.com
Accept: application/yang-data+json

The server might respond:

HTTP/1.1 200 OK
Date: Mon, 23 Apr 2012 17:11:30 GMT
Server: example-server
Cache-Control: no-cache
Pragma: no-cache
Content-Type: application/yang-data+json

{
  "example-events:events" : {
    "event" : [
     {
       "name" : "interface-up",
       "description" : "Interface up notification count",
       "event-count" : 42
     },
     {
       "name" : "interface-down",
       "description" : "Interface down notification count",
       "event-count" : 4
      }
    ]
  }
}

YANG definition:

container query {
  ncx:abstract;
  ncx:hidden;
  description "RESTCONF Query String Parameters";

  leaf content {
    type enumeration {
      enum config;
      enum nonconfig;
      enum all;
    }
  }
  description
    "controls how descendant nodes of the requested
     data nodes will be processed in the reply .";
}

The content parameter is similar to the “config” YANG-API query parameter.

Filter Query Parameter

Currently this parameter is not supported, it will be available in the next releases.

The "filter" parameter is used to indicate which subset of all possible events are of interest. If not present, all events not precluded by other parameters will be sent.

This parameter is only allowed for GET methods on a text/event-stream data resource. A 400 Bad Request error is returned if used for other methods or resource types.

The format of this parameter is an XPath 1.0 expression, and is evaluated in the following context:

  • The set of namespace declarations is the set of prefix and namespace pairs for all supported YANG modules, where the prefix is the YANG module name, and the namespace is as defined by the "namespace" statement in the YANG module. The function library is the core function library defined in XPath 1.0.

  • The set of variable bindings is empty.

  • The context node is the root node.

If the boolean result of the expression is true when applied to the conceptual "notification" document root, then the event notification is delivered to the client.

If the "filter" query parameter URI is listed in the "capability" leaf-list, then the server supports the "filter" query parameter.

The following URIs show some examples of notification filter specifications (lines wrapped for display purposes only):

// filter = /event/event-class='fault'
GET /mystreams/NETCONF?filter=%2Fevent%2Fevent-class%3D'fault'

// filter = /event/severity<=4
GET /mystreams/NETCONF?filter=%2Fevent%2Fseverity%3C%3D4

// filter = /*/reporting-entity/card!='Ethernet0'
GET /mystreams/NETCONF?filter=%2F*%2Freporting-entity%2Fcard%21%3D'Ethernet0'

// filter = /*/email-addr[contains(.,'company.com')]
GET /mystreams/critical-syslog?filter=%2F*%2Femail-addr[contains(.%2C'company.com')]

// Note: the module name is used as prefix.
// filter = (/example-mod:event1/name='joe' and
// /example-mod:event1/status='online')
GET /mystreams/NETCONF?filter=(%2Fexample-mod%3Aevent1%2Fname%3D'joe'%20and%20%2Fexample-mod%3Aevent1%2Fstatus%3D'online')

Fields Query Parameter

The "fields" query parameter is used to optionally identify data nodes within the target resource to be retrieved in a GET method. The client can use this parameter to retrieve a subset of all nodes in a resource.

A value of the "fields" query parameter matches the following rule:

fields-expr = path '(' fields-expr / ')' /
  path ';' fields-expr / path
  path = api-identifier [ '/' path ]

The ";" character is used to select multiple nodes. For example, to retrieve only the "genre" and "year" of an album, use:

fields=genre;year

Parentheses are used to specify sub-selectors of a node. For example, to retrieve only the "label" and "catalog-number" of an album, use:

fields=admin(label;catalogue-number)

The "/" character is used in a path to retrieve a child node of a node. For example, to retrieve only the "label" of an album, use:

fields=admin/label

This parameter is only allowed for GET methods on api, datastore, and data resources. A 400 Bad Request error is returned if used for other methods or resource types.

If the "fields" query parameter URI is listed in the "capability" leaf-list, then the server supports the "fields" parameter.

In this example the client is retrieving the API resource, but retrieving only the "name" and "revision" nodes from each module, in JSON format:

GET /restconf/data?fields=modules-state/module(name;revision) HTTP/1.1
Host: example.com
Accept: application/yang-data+json

The server might respond as follows.

HTTP/1.1 200 OK
Date: Mon, 23 Apr 2012 17:01:00 GMT
Server: example-server
Content-Type: application/yang-data+json

{
  "ietf-yang-library:modules-state": {
    "module": [
      {
        "name" : "example-jukebox",
        "revision" : "2015-06-04"
      },
      {
        "name" : "ietf-inet-types",
        "revision" : "2013-07-15"
      },
      {
        "name" : "ietf-restconf-monitoring",
        "revision" : "2015-06-04"
      },
      {
        "name" : "ietf-yang-library",
        "revision" : "2015-01-30"
      },
      {
        "name" : "ietf-yang-types",
        "revision" : "2013-07-15"
      }
    ]
  }
}

Using gNMI

This section describes the gNMI (gRPC Network Management Interface) integration within the netconfd-pro server and ypgnmi-app application. The model-driven configuration and retrieval of operational data using the gNMI CAPABILITIES, GET and SET gRPCs. gNMI version 0.4.0 is supported.

Throughout this specification the following terminology is used:

  • Telemetry - refers to streaming data relating to underlying characteristics of the device - either operational state or configuration

  • Configuration - elements within the data schema which are read/write and can be manipulated by the client

  • Target - the device within the protocol which acts as the owner of the data that is being manipulated or reported on. Typically this will be a netconfd-pro server that communicate with the client with help of ypgnmi-app application

  • Client - the device or system using the protocol and the service described in this document to query/modify data on the target, or act as a collector for streamed data. Typically this will be a network management system. The client will contact the ypgnmi-app application to query/modify data on the target

yp-gNMI Features

The main gNMI service functionality contains the following requests (gRPC):

  • Capabilities - used by the client and target as an initial handshake to exchange capability information

  • Get - used to retrieve snapshots of the data on the target by the client

  • Set - used by the client to modify the state of the target

  • Subscribe - used to control subscriptions to data on the target by the client

Future revisions of the gNMI specification MAY result in additional services being introduced, and hence an implementation MUST NOT make assumptions that limit to a single service definition.

The ypgnmi-app application is capable of handling these requests and transferring them to the netconfd-pro server for further processing as well as handle replies from the netconfd-pro server and transmit them back to the gNMI clients. The following sections will describe in more details how these requests are handled internally in the netconfd-pro and how ypgnmi-app application transform original gNMI requests and how they are transmitted to and from the netconfd-pro.

Restrictions for gNMI Protocol

The YumaPro gNMI protocol has the following restrictions:

  • Only JSON encoding options

  • In a SetRequest, wildcards and all keys are not supported. Only fully-specified paths are supported

  • In Subscribe, only supported mode is ONCE

Using the gNMI Server

Using gRPC

Refer to the YumaPro gRPC Manual for details on using gRPC with the netconfd-pro server.

Monitoring

The <get> and <get-config> operations are fully supported for retrieving data from the <candidate> and <running> configuration databases.

The <get-config> operation is not supported for the <startup> configuration.

The <copy-config> operation is only supported copying the <running> configuration to the <startup> configuration.

If the NACM access control policy denies permission to read a particular node, then that node is silently skipped in the output. No error or warning messages will be generated.

client applications should be prepared to receive XML subtrees that have been pruned by access control. The <data> element will always be present, so an empty <data/> element indicates that no data was returned, either because the <filter> did not match, or because access control pruned the requested nodes.

There are really five types of filters available for retrieval operations:

Filter Types

Type

Description

is_config()

Choose the <get>operation for all objects, or <get-config> for just config=true objects

is_default()

Set the <with-defaults> parameter to 'trim'

is_client_set()

Set the <with-defaults> parameter to 'explicit'

subtree filtering

Use a subtree filter to retrieve portions of the <candidate> or <running> configurations.

XPath filtering

Use <filter type="xpath" select="expr"/> to retrieve portions of the <candidate> or <running> configurations.

module-tag filtering

Use the --module-tag parameter

Using Subtree Filters

The subtree filtering feature is fully supported.

The order of nodes within the <filter> element is not relevant. Data returned in the <rpc-reply> should follow the same top-level order as the request, but this should not be relied on to always be the case.

Duplicate or overlapping subtrees within the request will be combined in the output, so the common ancestor nodes are not duplicated in the reply.

XML namespaces are optional to use:

  • If there is no namespace in affect for a filter component, or the 'NETCONF' namespace is in effect, the server will attempt to find any top-level data node which matches.

  • Namespaces within descendant nodes of the <filter> node children are inherited from their parent. If none is in effect, then the first matching child node for the current parent node will be used.

  • Invalid namespace errors for the <filter> element are suppressed in the server. An invalid namespace or unknown element is simply a 'no-match' condition.

For example, the following PDU would be valid, even though it is not technically valid XML:

<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="8">
  <nc:get>
    <nc:filter>
      <nacm />
    </nc:filter>
  </nc:get>
</nc:rpc>

Note that there is no default namespace in effect for the <nacm> subtree. However, the server will accept this filter as if the ietf-netconf-acm.yang module namespace was properly declared.

Subtree filters can select specific list entries using content match nodes. The following example would return the entire contents of the <interface> entry for 'eth0':

<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="9">
  <nc:get>
    <nc:filter type="subtree">
      <if:interfaces xmlns:if="http://netconfcentral.org/ns/yuma-interfaces">
        <if:interface>
          <if:name>eth0</if:name>
        </if:interface>
      </if:interfaces>
    </nc:filter>
  </nc:get>
</nc:rpc>

To retrieve only specific nodes (such as counters) from a single list entry, use select nodes for the desired counter(s), and include a content match node for each key leaf. A missing key leaf will match any entry for that key.

The following example request shows how just the <inBytes> and <outBytes> counters could be retrieved from the <interface> entry for 'eth0'.

Example Request:

<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="10">
  <nc:get>
    <nc:filter type="subtree">
      <if:interfaces xmlns:if="http://netconfcentral.org/ns/yuma-interfaces">
        <if:interface>
          <if:name>eth0</if:name>
          <if:counters>
            <if:inBytes/>
            <if:outBytes/>
          </if:counters>
        </if:interface>
      </if:interfaces>
    </nc:filter>
  </nc:get>
</nc:rpc>

Example Reply:

<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="10">
  <nc:data>
    <if:interfaces xmlns:if="http://netconfcentral.org/ns/interfaces">
      <if:interface>
        <if:name>eth0</if:name>
        <if:counters>
          <if:inBytes>290046042</if:inBytes>
          <if:outBytes>112808406</if:outBytes>
        </if:counters>
      </if:interface>
    </if:interfaces>
  </nc:data>
</nc:rpc-reply>

Using XPath Filters

The :xpath capability is fully supported, including the YANG extensions to this capability.

The XPath 2.0 rule for default XML namespace behavior is used, not XPath 1.0 rules, as specified by the YANG language. This means that any module with a node with the same local-name, in the same position in the schema tree, will match a missing XML prefix. This allows much simpler specification of XPath filters, but it may match more nodes than intended. Remember that any nodes added via an external YANG augment statement may have the same local-name, even though they are bound to a different XML namespace.

If the XPath expression does not return a node-set result, then the empty <data/> element will be returned in the <rpc-reply>.

If no nodes in the node-set result exist in the specified target database, then an empty <data/> element will be returned in the <rpc-reply>.

If a node in the result node-set matches a node in the target database, then it is included in the <rpc-reply>,

If a node selected for retrieval are contained within a YANG list node, then all the key leaf nodes for the specific list entry will be returned in the response.

The powerful '//' operator (equivalent to "descendant-or-self::node()") can be used to construct really simple XPath expressions.

The following example shows how a simple filter like '//name' will return nodes from all over the database, yet they can all be fully identified because the path from root is part of the response data.

Example Request:

xget //name
<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="43">
  <nc:get>
    <nc:filter type="xpath" select="//name"/>
  </nc:get>
</nc:rpc>

Example Reply:

<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
   message-id="43">
   <nc:data>
      <nacm:nacm xmlns:nacm="http://netconfcentral.org/ns/nacm">
         <nacm:rules>
            <nacm:data-rule>
               <nacm:name>nacm-tree</nacm:name>
            </nacm:data-rule>
            <nacm:data-rule>
               <nacm:name>itf-1</nacm:name>
            </nacm:data-rule>
         </nacm:rules>
      </nacm:nacm>
      <t:xpath.1 xmlns:t="http://netconfcentral.org/ns/test">
         <t:name>barney</t:name>
      </t:xpath.1>
      <if:interfaces xmlns:if="http://netconfcentral.org/ns/interfaces">
         <if:interface>
            <if:name>lo</if:name>
         </if:interface>
         <if:interface>
            <if:name>eth0</if:name>
         </if:interface>
         <if:interface>
            <if:name>virbr0</if:name>
         </if:interface>
         <if:interface>
            <if:name>pan0</if:name>
         </if:interface>
      </if:interfaces>
      <ns:netconf-state              xmlns:ns="urn:ietf:params:xml:ns:netconf:monitoring">
         <ns:datastores>
            <ns:datastore>
               <ns:name>
                  <ns:candidate/>
               </ns:name>
            </ns:datastore>
            <ns:datastore>
               <ns:name>
                  <ns:running/>
               </ns:name>
            </ns:datastore>
            <ns:datastore>
               <ns:name>
                  <ns:startup/>
               </ns:name>
            </ns:datastore>
         </ns:datastores>
      </ns:netconf-state>
      <manageEvent:netconf   xmlns:manageEvent="urn:ietf:params:xml:ns:netmod:notification">
         <manageEvent:streams>
            <manageEvent:stream>
               <manageEvent:name>NETCONF</manageEvent:name>
            </manageEvent:stream>
         </manageEvent:streams>
      </manageEvent:netconf>
   </nc:data>
</nc:rpc-reply>

In order to refine the previous filter to select nodes from just one module, the use the XML prefix in the node identifier. The example below selects only the <name> nodes from the interfaces module.

Example Request:

xget //if:name
<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="44">
  <nc:get>
    <nc:filter type="xpath" xmlns:if="http://netconfcentral.org/ns/interfaces"
      select="//if:name"/>
  </nc:get>
</nc:rpc>

Example Reply:

<?xml version="1.0" encoding="UTF-8"?>
<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
   message-id="44">
   <nc:data>
      <if:interfaces xmlns:if="http://netconfcentral.org/ns/interfaces">
         <if:interface>
            <if:name>lo</if:name>
         </if:interface>
         <if:interface>
            <if:name>eth0</if:name>
         </if:interface>
         <if:interface>
            <if:name>virbr0</if:name>
         </if:interface>
         <if:interface>
            <if:name>pan0</if:name>
         </if:interface>
      </if:interfaces>
   </nc:data>
</nc:rpc-reply>

Using Time Filters

The module yuma-time-filter.yang defines a timestamp mechanism to help reduce polling overhead for a client.

  • Timestamps are specified in 'date-and-time' format (from the ietf-yang-types.yang module).

  • The timestamp parameter 'if-modified-since' is added to the <get> and <get-config> operations.

  • The timestamp monitoring node 'last-modified' is added to the /netconf-state/datastores/datastore list.

  • The XML attribute 'last-modified' is added to the <rpc-reply> element for replies to <get> and <get-config> operations.

  • The per-datastore last modified timestamp is for the entire datastore contents. If the 'if-modified-since' parameter is present in the <get> or <get-config> request, the the server will check the corresponding 'last-modified' timestamp.

    • If the 'last-modified' timestamp is more recent than the 'if-modified-since' value, then the <get> or <get-config> operation is processed as normal.

    • If the 'last-modified' timestamp is not more recent than the 'if-modified-since' value, then the <get> or <get-config> operation is not processed. Instead, an empty <data> element is returned. The 'last-modified' XML attribute in the <rpc-reply> will indicate the last modification timestamp for the datastore.

Example Request:

<?xml version="1.0" encoding="UTF-8"?>
 <get-config xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
    <source>
      <running/>
    </source>
    <if-modified-since
    xmlns="http://netconfcentral.org/ns/yuma-time-filter">
      2011-08-21T21:51:46Z</if-modified-since>
  </get-config>
</rpc>

An empty reply is sent because datastore not modified since specified time:

<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="4"
   xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
   last-modified="2011-08-21T17:51:46Z"
   xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
 <data></data>
</rpc-reply>

YANG Library

There is a need for standard mechanisms to identify the YANG modules and submodules that are in use by each server that utilizes YANG-based data abstraction. If a large number of YANG modules are utilized by the server, then the YANG library information needed can be relatively large. This information changes very infrequently, so it is important that clients be able to cache the YANG library and easily identify if their cache is out-of-date.

The RFC 7895 YANG Module Library defines monitoring information about all the loaded YANG modules and submodules used by a server to represent management and protocol information. This is the first version, also called the 'non-NMDA' version.

The RFC 8525 YANG Module Library defines the NMDA version of the YANG library.

Note

The NMDA version of the YANG library will only be used if the --with-nmda=``true`` setting is used.

The following information is used by the library (for each YANG module in the library) to fully utilize monitoring mechanism.

  • name: The mandatory YANG module name is unique within a YANG library. All modules and submodules share the same namespace, including modules used for deviations.

  • revision date: Each YANG module within the library has a revision date. This is derived from the most recent revision statement within the module or submodule.

  • submodule list: The name and revision date of each submodule used by main module.

  • feature list: The name of each YANG feature supported by the server.

  • deviation list: The name of each YANG module used for deviation statements.

  • conformance-type:

    • Extra leaf added if --with-yumaworks-system=true.

    • If 'implement', then the server is claiming conformance to the YANG module identified in this entry.

    • If 'import', then the server is not claiming any conformance for the YANG module identified by this entry. The module may be needed for reusable definitions, such as extensions, features, identifies, typedefs, or groupings.

  • schema: Contains a URL that represents the YANG schema resource for the module or submodule. This leaf will only be present if there is a URL available for retrieval of the schema for this entry.

  • namespace: The XML namespace identifier for this module.

The following information is used in order to identify if the YANG-Library cache is out-of-date and if the set of modules have changed.

  • module-set-id: Contains a server-specific identifier representing the current set of modules and submodules. The server will change the value of this leaf if the information represented by the 'module' list instances has changed.

Using the YANG Library

In order to retrieve the whole set of modules currently supported by the server the following command is used.

Example Request:

sget /modules-state
<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="6" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <get>
    <filter type="subtree">
      <modules-state xmlns="urn:ietf:params:xml:ns:yang:ietf-yang- library"/>
    </filter>
  </get>
</rpc>

Example Reply:

<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="6" xmlns:ncx="http://netconfcentral.org/ns/yuma-ncx"
 ncx:last-modified="2015-06-17T19:00:37Z"
 xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
 <data>
  <modules-state xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-library">
   <module>
    <name>ietf-inet-types</name>
    <revision>2013-07-15</revision>
    <namespace>urn:ietf:params:xml:ns:yang:ietf-inet-types</namespace>
    <schema>http://localhost/yang-api/yang/ietf-inet-types/2013-07-15</schema>
    <conformance-type>import</conformance-type>
   </module>
   <module>
    <name>yumaworks-system</name>
    <revision>2014-10-16</revision>
    <namespace>http://yumaworks.com/ns/yumaworks-system</namespace>
    <schema>http://localhost/yang-api/yang/yumaworks-system/2014-10-16</schema>
    <conformance-type>implement</conformance-type>
   </module>
   <module>
    <name>yumaworks-types</name>
    <revision>2014-09-06</revision>
    <namespace>http://yumaworks.com/ns/yumaworks-types</namespace>
    <schema>http://localhost/yang-api/yang/yumaworks-types/2014-09-06</schema>
    <conformance-type>import</conformance-type>
   </module>
   <module-set-id>3521</module-set-id>
  </modules-state>
 </data>
</rpc-reply>

Example RESTCONF Request:

GET /restconf/data/modules-state/module=example-jukebox,2014-07-03/schema HTTP/1.1
Host: example.com
Accept: application/yang-data+json

The server might respond:

HTTP/1.1 200 OK
Date: Mon, 25 Apr 2012 11:10:30 GMT
Server: example-server
Content-Type: application/yang-data+json

{
  "ietf-yang-library:schema": "https://example.com/mymodules/example-jukebox/2015-06-04"
}

Using the Server in Library Mode

The server supports a special mode of operation with the --library-mode CLI parameter. In this mode, the server will only operate as a YANG Library Schema Server.

Note

  • All vendor-added YANG instrumentation is ignored in Library Mode!

  • The --module, --bundle, and --loadpath CLI parameters are ignored in Library Mode.

  • The <load>, <load-bundle>, <unload> and <unload-bundle> RPC operations cannot be used in Library Mode.

  • The server will search for all valid YANG modules in the module search path.

  • All found modules will be added to the YANG Library

  • No found modules will be accessible or implemented in the server.

  • The server will scan the module search path and add all revisions of all modules it finds to the YANG library “module” list.

  • Only one copy of each revision will be loaded in case the same file existing in multiple places in the module search path.

Discover the Modules Available for Retrieval

  • The YANG library needs to be scanned by the client.

    • The non-NMDA module entry provides a schema leaf that can be used by RESTCONF to retrieve the YANG module.

    • The NMDA module entry provides a location leaf that can be used by RESTCONF to retrieve the YANG module.

  • The module list entry will contain the name and revision string for the found module. These values are used as parameters in the <get-schema> operation.

Only 6 RPC Operations are allowed in Library Mode

The Server is not Fully YANG Library Compliant in Library Mode

  • The /netconf-state/schemas/schema subtree will contain list entries for modules which are enabled in the server configuration. Not all of these modules will be usable in Library Mode.

  • The /modules-state/module subtree will contain list entries for all valid found modules in the module search path. These modules are not all implemented in the server. The conformance leaf will be set to import for all modules.

  • The /yang-library/module-set/module subtree will contain list entries for all valid found modules in the module search path. These modules are not all implemented in the server.

  • Only the <get-schema> operation will be available for the discovered modules.

netconfd-pro Notifications

The netconfd-pro server supports all the capabilities of RFC 5277, and the notification monitoring portion of the ietf-netconf-monitoring.yang data model. All standard NETCONF notifications are supported (RFC 5277 and RFC 6470). There are also some deprecated proprietary notifications defined in yuma-system.yang.

The netconfd-pro server now supports the new NETCONF notification subscription model defined in:

  • RFC 8639: Subscription to YANG Notifications

  • RFC 8640: Dynamic Subscription to YANG Events and Datastores over NETCONF

  • RFC 8641: Subscription to YANG Notifications for Datastore Updates

This data model includes traditional event stream subscriptions and YANG Push datastore subscriptions.

../_images/yang-push-overview.png

Enabling Notifications

The netconfd-pro server can be invoked with or without NETCONF notification support enabled. Notifications are enabled by default.

The --with-notifications CLI parameter is used to control this feature. This parameter only needs to be used to disable notifications. The parameter value --with-notifications=false will prevent the notification YANG modules from being loaded, prevent the :notifications and :interleave capabilities from being advertised in the <hello> message, and there will not be any event history buffer maintained.

NETCONF notifications use a generic “event stream” publishing model. The netconfd-pro server fully supports configuration of these event streams for the NETCONF protocol. Event streams allow the various notification messages to be partitioned, usually by topic, so the client can subscribe to the selected event stream and only receive the event types related to the published topic (e.g., stream name).

This form of content-filtering is much simpler to use than NETCONF notification filters specified in subtree or XPath form. There is a level of indirection added, so the exact notification messages do not need to be known in advance or maintained by the client.

Static event stream management with CLI parameters is supported. The server configuration file (E.g. netconfd-pro.conf) has to be modified, and/or the server restarted, to change the static event stream configuration.

Dynamic custom event streams allow event streams to be added and deleted at run-time. Modules can be re-mapped to different streams, to redistribute or simply reconfigure the event stream content. Event stream replay buffers can be cleared using an RPC operation.

YANG 1.1 Nested Notifications

Note

Nested notifications are only available in the 21.10T release train.

The server supports nested notification definitions defined in RFC 7950.

  • A nested notification is defined within a data node hierarchy, in the same way as a YANG 1.1 'action' statement.

  • The path to the notification node is used to identify the event type because the event type name does not have to be unique within the YANG module, like a top-level notification.

  • The <notification> element will not contain the notification directly.

  • The <notification> element will contain the hierarchy of data nodes from the notification to the top-level container or list.

  • The ancestor key leafs are the only other data nodes encoded in the data node ancestor hierarchy.

  • The notification event type is encoded as normal after the key leafs in the innermost nest level of the message.

Example YANG module showing nested notification statements:

module notif4 {
  yang-version 1.1;
  namespace "urn:yumaworks:params:xml:ns:notif4";
  prefix "n4";
  revision "2022-03-25";

  container A {
   list B {
     key "row column";
     leaf row { type uint16; }
     leaf column { type uint16; }

     list BB {
       key "idx";
       leaf idx { type string; }
       leaf col1 { type string; }

       list BBB {
         key "idx";
         leaf idx { type string; }
         leaf col1 { type string; }
         notification N1 {
           leaf parm1 { type string; }
           leaf parm2 { type int16; }
         }
       }

       notification N1 {
         leaf parm3 { type string; }
         leaf parm4 { type int16; }
       }
     }

     notification N1 {
       leaf parm1 { type string; }
       leaf parm2 { type int16; }
     }
   }

   notification N1 {
     leaf parm1 { type string; }
     leaf parm2 { type int16; }
   }
 }

 notification N1 {
   leaf parm1 { type string; }
   leaf parm2 { type int16; }
 }



}

In this test module, the 'N1' event type is defined at 5 levels:

Node Level

Example Path to N1

1 (top-level)

/N1

2 (container A)

/A/N1

3 (list B)

/A/B[row='3'][column='13']/N1

4 (list BB)

/A/B[row='2'][column='20']/BB[idx='idx-dummy2']/N1

5 (list BBB)

/A/B[row='1'][column='11']/BB[idx='idx-dummy']/BBB[idx='idx1-dummy']/N1

Nested Notification Message Examples

The following XML snippets show example messages of these nested notifications:

Level 1: /N1

<?xml version="1.0" encoding="UTF-8"?>
<notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
 <eventTime>2022-04-03T16:47:11Z</eventTime>
 <N1 xmlns="urn:yumaworks:params:xml:ns:notif4">
  <parm1>parm1-dummy4</parm1>
  <parm2>1000</parm2>
 </N1>
</notification>

Level 2: /A/N1

<?xml version="1.0" encoding="UTF-8"?>
<notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
 <eventTime>2022-04-03T16:47:11Z</eventTime>
 <A xmlns="urn:yumaworks:params:xml:ns:notif4">
  <N1>
   <parm1>parm1-dummy3</parm1>
   <parm2>800</parm2>
  </N1>
 </A>
</notification>

Level 3: /A/B[row='3'][column='13']/N1

<?xml version="1.0" encoding="UTF-8"?>
<notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
 <eventTime>2022-04-03T16:47:11Z</eventTime>
 <A xmlns="urn:yumaworks:params:xml:ns:notif4">
  <B>
   <row>3</row>
   <column>13</column>
   <N1>
    <parm1>parm1-dummy2</parm1>
    <parm2>600</parm2>
   </N1>
  </B>
 </A>
</notification>

Level 4: /A/B[row='2'][column='20']/BB[idx='idx-dummy2']/N1

<?xml version="1.0" encoding="UTF-8"?>
<notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
 <eventTime>2022-04-03T16:47:11Z</eventTime>
 <A xmlns="urn:yumaworks:params:xml:ns:notif4">
  <B>
   <row>2</row>
   <column>20</column>
   <BB>
    <idx>idx-dummy2</idx>
    <N1>
     <parm3>parm3-dummy</parm3>
     <parm4>400</parm4>
    </N1>
   </BB>
  </B>
 </A>
</notification>

Level 5: /A/B[row='1'][column='11']/BB[idx='idx-dummy']/BBB[idx='idx1-dummy']/N1

<?xml version="1.0" encoding="UTF-8"?>
<notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
 <eventTime>2022-04-03T16:47:11Z</eventTime>
 <A xmlns="urn:yumaworks:params:xml:ns:notif4">
  <B>
   <row>1</row>
   <column>11</column>
   <BB>
    <idx>idx-dummy</idx>
    <BBB>
     <idx>idx1-dummy</idx>
     <N1>
      <parm1>parm1-dummy</parm1>
      <parm2>200</parm2>
     </N1>
    </BBB>
   </BB>
  </B>
 </A>
</notification>

Using Custom Event Streams

The NETCONF notification delivery system allows for multiple event streams. Each event stream has its own subscriptions and its own notification queue (replay buffer). The server will always setup the NETCONF event stream. The notifications defined in ietf-netconf-notifications.yang are sent to this event stream.

Event streams can be used to group notification events for different reasons, such as by topic, or frequency, or severity..

The --event-stream parameter is used to configure an additional event stream.

The --event-stream-map parameter is used to assign all notifications defined in a specific module to an event stream.

Example: create the ‘hardware’ event stream and 2 event-stream-map entries:

> netconfd-pro --event-stream=hardware \
  --event-stream-map=ietf-hardware@hardware \
  --event-stream-map=openconfig-platform@hardware

Normally an event generated by internal YANG instrumentation will be sent to the NETCONF event stream. There are two ways for notifications to be sent to a configured stream:

  1. New Server API: The instrumentation can specify the event stream name. If this is configured it will be used for the queued notification. If the specified event stream is not found or no event stream is specified in the API call, then the server will check for an event-stream-map parameter for the module containing the notification.

  2. --event-stream-map CLI parameter:** The user can configure module to event stream mappings. If no event stream is specified by the event generator (e.g., SIL instrumentation) then the server will use the event-stream-map parameter to find a mapping. If no mapping is found then the default event stream NETCONF is used.

Event Stream Monitoring

The event streams that are enabled on the server can be monitored using the notifications.yang module, which contains a top-level container called /netconf.

Example: /netconf/streams/stream list contains ‘NETCONF’ and ‘hardware’ streams.

andy@localhost> sget /netconf

Filling container /netconf:

RPC Data Reply 2 for session 3 [default]:

rpc-reply {
  data {
    netconf {
      streams {
        stream  NETCONF {
          name NETCONF
          description 'default NETCONF event stream'
          replaySupport true
          replayLogCreationTime 2019-08-30T00:20:32Z
        }
        stream  hardware {
          name hardware
          description 'vendor event stream'
          replaySupport true
          replayLogCreationTime 2019-08-30T00:20:32Z
        }
      }
    }
  }
}

Using Dynamic Event Streams with yumaworks-event-streams.yang

Starting in release 20.10-7 the event streams can be configured at run-time using the yumaworks-event-stream.yang module.

This module provides configuration objects to match the --event-stream and --event-stream-map CLI parameters.

This module must be disabled using the --with-yumaworks-event-stream CLI parameter to prevent this module from being used. The default is to include this module.

The CLI parameters are still used, and any event streams configured with CLI parameters will be setup first, before any YANG-configured event streams. The name “NETCONF” is reserved and cannot be used.

  • list event-streams/event-stream: Each configured event-stream can have a different replay buffer size, or replay can be disabled per event-stream. Names cannot conflict with any --event-stream values.

  • list event-streams/module-map: Each module can be mapped to zero or one event streams. The ‘stream-name’ parameter cannot conflict with any --event-stream values. This has the same effect as the event-stream-map parameter.

  • rpc <clear-eventlog>: Clears all saved events in the replay buffer for the event stream

Subscriptions

The <create-subscription> operation is used to start receiving notification.

It can be used in 4 different modes:

  • Get all or some of the stored notifications.

    • <startTime> and <stopTime> parameters used; The stop time is in the past.

  • Get all or some of the stored notifications, then receive live notifications until some point in the future.

    • <startTime> and <stopTime> parameters used; The stop time is in the future.

  • Get all or some of the stored notifications, then start receiving live notifications until the session is terminated.

    • <startTime> parameter used, but <stopTime> parameter is not used

  • Start receiving live notifications until the session is terminated

    • neither <startTime> or <startTime> are used

Once a subscription is started, notifications may start arriving, after the <rpc-reply> for the <create-subscription> operation is sent.

If the <startTime> parameter is used, then zero or more stored notifications will be returned, followed by the <replayComplete> notification.

If the <stopTime> parameter is also used, then the <notificationComplete> notification will be sent when this stop time has passed. After that, no more notifications will be sent to the session, and the subscription is terminated. After this point, another subscription could be started.

Only one subscription can be active on a session at a time. There is no way to terminate a subscription, other than to close the session.

Notification Log

Each system event is saved to the notification replay buffer for the NETCONF event stream.

The <replayComplete> and <notificationComplete> notifications are not saved to this buffer because they are subscription-specific events, and not system events.

Each event stream has its own replay buffer. The size of each replay buffer is controlled by the --eventlog-size configuration parameter.

The default size is 1000 events.

The oldest event will be deleted when a new event is added, when this limit is reached.

If --eventlog-size is set to zero, then there will be no replayed notifications available, and the <replayComplete> notification will be sent right away, if <startTime> is present.

Each event in the replay buffer is assigned a sequential sequence ID, starting from 1. Each event stream has its own sequence ID counter. Values are only specific to one event stream and will be duplicated in each event stream.

The <sequence-id> leaf is an unsigned 32-bit integer, which is added to the <notification> element, after the event element. This sequence can be used to debug filters by comparing the sequence IDs of the notifications that were delivered against the expected sequence IDs. This leaf is only added to each notification if the agt_notif_sequence_id flag is set to 'true' in the agt_profile_t Struct for the server. By default, this flag is set to 'false'.

Using Event Filters

An event filter is a way to disable generation of specific notification event types from being added to the notification replay buffer. This can be useful if some events are not of interest to the applications, so there is no reason to use replay buffer resources to store them.

The YANG module yumaworks-event-filter.yang contains the /event-filters definitions.

A client can configure event-filter list entries in the /event-filters/event-filter list to suppress generation of specific events.

Each entry is identified by the module name and the notification event name.

An entry does not have to reference a valid module and/or notification name. This allows filters to be present before modules are loaded into the server. If a module is loaded at run-time with the <load> or <load-bundle> operation, then the event filters will be checked and applied as needed at that time.

For example, the 'foo-event1' notification in the 'acme-foo' module might be defined as followed:

module acme-foo {
   namespace “http://acme.com/ns/foo”;
    prefix af;

   notification foo-event1 {
      leaf foo-count { type uint32; }
      leaf foo-msg { type string; }
   }

}

To create an event filter, the client may send an <edit-config> operation request as follows:

<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="1" trace-id="3" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <edit-config>
    <target>
      <running/>
    </target>
    <default-operation>merge</default-operation>
    <test-option>set</test-option>
    <config>
      <event-filters xmlns="http://yumaworks.com/ns/yumaworks-event-filter">
        <event-filter xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"
          nc:operation="merge">
          <module>acme-foo</module>
          <event>foo-event1</event>
        </event-filter>
      </event-filters>
    </config>
  </edit-config>
</rpc>

Logging Event Drops

If the --log-event-drops CLI parameter is set to 'true' then a log entry will be generated each time an event is dropped because it is suppressed.

The default is 'false' (event drops due to an event filter are not logged).

Event drops due to other reasons are not affected by this CLI parameter.

Using Notification Filters

Note

A notification filter is different than a <get> or <get-config> filter.

Instead of selecting sub-trees of the specified database, it is treated as a boolean expression. If the filter matches the content in the notification, then the notification is sent to that subscription. If the filter does not match the content, then the notification is not sent to that subscription.

A filter match for notification purposes means that the filter is conceptually applied, as if it were a <get> operation, and if any nodes are selected (non-empty result node-set), then the filter is a match. If no content is selected (empty result node-set), then the filter is not a match.

The first node that can appear in the filter is the event type. The <eventTime> and <sequence-id> nodes are siblings of the event type element, so they cannot be used in a notification filter.

<notification> Element

The notification element contains 2 or 3 child elements, in this order:

  1. eventTime: timestamp for the event. The namespace URI for this element is urn:ietf:params:xml:ns:netconf:notification:1.0

  2. eventType: The real name will be the name of the YANG notification, such as 'sysStartup'. The contents of this element will depend on the YANG notification definition. The namespace URI for this element will be different for every event type. It will be the same value as the YANG namespace statement in the module that defines the notification statement for the particular event type.

  3. sequence-id: The system event sequence ID. Session or subscription specific events, such as 'replayComplete' and 'notificationComplete' do not have this element. The namespace URI for this element is http://netconfcentral.org/ns/system.

    This leaf is only added to each notification if the agt_notif_sequence_id field is set to 'true' in the agt_profile_t Struct for the server. By default, this leaf is not included in the notification. There is no CLI parameter to enable this leaf.

System Notifications

The ietf-netconf-notifications.yang module from RFC 6470 are implemented. These notifications are based on the yuma-system.yang notifications.

The --system-notifications CLI parameter can select the IETF or deprecated yuma notifications. This parameter SHOULD NOT be set to disable ietf system notifications.

Note

The yuma-system notifications are deprecated and SHOULD NOT be used.

<replayComplete> Event

The <replayComplete> event is generated on a subscription that requested notification replay (by supplying the <startTime> parameter). This event type cannot be filtered out. The server will always attempt to deliver this notification event type when it is generated.

+---n replayComplete

<replayComplete> Notification

Description:

Buffered notification delivery has ended for a subscription

Min parameters:

0

Max parameters:

0

YANG file:

nc-notifications.yang

Example:

<?xml version="1.0" encoding="UTF-8"?>
<ncEvent:notification xmlns:ncEvent="urn:ietf:params:xml:ns:netconf:notification:1.0">
  <ncEvent:eventTime>2009-07-29T17:21:37Z</ncEvent:eventTime>
  <manageEvent:replayComplete xmlns:manageEvent="urn:ietf:params:xml:ns:netmod:notification"/>
</ncEvent:notification>

<notificationComplete> Event

The <notificationComplete> event is generated on a subscription that requested notification replay, and requested that the notification delivery stop (i.e., terminate subscription), after a certain time, using the <stopTime> parameter.

This event type cannot be filtered out. The server will always attempt to deliver this notification event type when it is generated.

+---n notificationComplete

<notificationComplete> Notification

Description:

All notification delivery has ended, and the subscription is terminated.

Min parameters:

0

Max parameters:

0

YANG file:

nc-notifications.yang

Example:

<?xml version="1.0" encoding="UTF-8"?>
<ncEvent:notification xmlns:ncEvent="urn:ietf:params:xml:ns:netconf:notification:1.0">
  <ncEvent:eventTime>2009-07-29T17:31:22Z</ncEvent:eventTime>
  <manageEvent:notificationComplete xmlns:manageEvent="urn:ietf:params:xml:ns:netmod:notification"/>
</ncEvent:notification>

<sysStartup> Event

Note

The <sysStartup> notification is deprecated. So not use.

The <sysStartup> event is the first notification generated when the server starts or restarts. It contains the startup file source (if any) and lists any <rpc-error> contents that were detected at boot-time, during the copying of the startup configuration into the running configuration.

The system-notifications parameter must include “yuma” for this event to be generated.

+---n sysStartup
   +--ro startupSource?   string
   +--ro bootError* []
      +--ro error-type        enumeration
      +--ro error-tag         nc:error-tag-type
      +--ro error-severity    nc:error-severity-type
      +--ro error-app-tag?    string
      +--ro error-path?       yang:xpath1.0
      +--ro error-message?    LangString2
      +--ro error-info?       <anyxml>

<sysStartup> Notification

Description:

The netconfd-pro server has started

Min parameters:

0

Max parameters:

2

YANG file:

yuma-system.yang

Parameters:

  • startupSource

    • type: string

    • usage: optional (will not be present if --no-startup was present)

    • This parameter identifies the local file specification associated with the source of the startup configuration contents.

  • bootError

    • type: list (same structure as <rpc-error> element)

    • usage: optional (will only be present if errors were recorded during boot)

    • There will be one entry for each <rpc-error> encountered during the load config operation. The <rpc-error> fields are used directly.

    • There is no particular order, so no key is defined.

    • All fields except <error-info> will be present from the original <rpc-error> that was generated during the boot process.

Example:

<?xml version="1.0" encoding="UTF-8"?>
<ncEvent:notification xmlns:ncEvent="urn:ietf:params:xml:ns:netconf:notification:1.0">
  <ncEvent:eventTime>2009-07-29T17:21:13Z</ncEvent:eventTime>
  <sys:sysStartup xmlns:sys="http://netconfcentral.org/ns/system">
    <sys:startupSource>/home/andy/swdev/yuma/trunk/netconf/data/startup-cfg.xml</sys:startupSource>
  </sys:sysStartup>
  <sys:sequence-id xmlns:sys="http://netconfcentral.org/ns/system">1</sys:sequence-id>
</ncEvent:notification>

<netconf-session-start> Event

The <netconf-session-start> notification is generated when a NETCONF session is started.

The username, remote address, and session ID that was assigned are returned in the event payload.

+---n netconf-session-start
   +--ro username       string
   +--ro session-id     nc:session-id-or-zero-type
   +--ro source-host?   inet:ip-address

<netconf-session-start> Notification

Description:

A new NETCONF session has started.

Min parameters:

3

Max parameters:

3

YANG file:

ietf-netconf-notifications.yang

Parameters:

  • username

    • type: string

    • usage: mandatory

    • This parameter identifies the SSH user name that is associated with the session.

  • session-id

    • type: uint32 (range 1 to max)

    • usage: mandatory

    • This parameter identifies the NETCONF session ID assigned to the session.

  • source-host

    • type: inet:ip-address

    • usage: mandatory

    • This parameter identifies the remote host IP address that is associated with the session.

Example:

<?xml version="1.0" encoding="UTF-8"?>
<notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
  <eventTime>2018-04-20T18:38:08Z</eventTime>
  <netconf-session-start
        xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-notifications">
    <username>andy</username>
    <session-id>4</session-id>
    <source-host>127.0.0.1</source-host>
  </netconf-session-start>
</notification>

<netconf-session-end> Event

The <netconf-session-end> notification is generated when a NETCONF session is terminated.

The username, remote address, and session ID that was assigned are returned in the event payload. The termination reason is also included.

If the session was terminated before it properly started, it is possible that there will not be a <netconf-session-start> notification event to match the <netconf-session-end> event. For example, if the initial SSH connection setup fails before the <hello> message is processed, then only a <netconf-session-end> notification event will be generated. In this case, the user name and other session information may not be available.

+---n netconf-session-end
   +--ro username              string
   +--ro session-id            nc:session-id-or-zero-type
   +--ro source-host?          inet:ip-address
   +--ro killed-by?            nc:session-id-type
   +--ro termination-reason    enumeration

<netconf-session-end> Notification

Description:

A NETCONF session has terminated.

Min parameters:

1

Max parameters:

5

YANG file:

ietf-netconf-notifications.yang

Parameters:

  • username

    • type: string

    • usage: mandatory

    • This parameter identifies the SSH user name that is associated with the session.

  • session-id

    • type: uint32 (range 1 to max)

    • usage: mandatory

    • This parameter identifies the NETCONF session ID assigned to the session.

  • source-host

    • type: inet:ip-address

    • usage: mandatory

    • This parameter identifies the remote host IP address that is associated with the session.

  • killed-by

    • type: uint32 (range 1 to max)

    • usage: optional (will only be present if the terminationReason leaf is equal to 'killed'.

    • This parameter identifies the session number of the session that issued the <kill-session> operation.

  • termination-reason

    • type: enumeration (closed, killed, dropped, timeout, bad-start, bad-hello, other)

    • usage: mandatory

    • This parameter indicates why the session was terminated.

Example:

<?xml version="1.0" encoding="UTF-8"?>
<notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
  <eventTime>2018-04-20T18:41:01Z</eventTime>
  <netconf-session-end
      xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-notifications">
    <username>andy</username>
    <session-id>4</session-id>
    <source-host>127.0.0.1</source-host>
    <killed-by>4</killed-by>
    <termination-reason>closed</termination-reason>
  </netconf-session-end>
</notification>

<netconf-config-change> Event

The <netconf-config-change> notification is generated when the <running> configuration database is altered by a NETCONF session.

If the :candidate capability is supported, then this event is generated when the <commit> operation completes.

If the :writable-running capability is supported instead, then this even is generated when the <edit-config> operation completes.

The user name, remote address, and session ID that made the change are reported.

A summary of the changes that were made is also included in the event payload.

If multiple changes are made at once, then one <netconf-config-change> event will be generated for each change.

If the --with-yumaworks-config-change parameter is set to ‘true’ then the <new-value> and <old-value> fields will be added to each edit list entry as needed.

+---n netconf-config-change
   +--ro changed-by
   |  +--ro (server-or-user)
   |     +--:(server)
   |     |  +--ro server?        empty
   |     +--:(by-user)
   |        +--ro username       string
   |        +--ro session-id     nc:session-id-or-zero-type
   |        +--ro source-host?   inet:ip-address
   +--ro datastore?    enumeration
   +--ro edit* []
      +--ro target?      instance-identifier
      +--ro operation?   nc:edit-operation-type

<netconf-config-change> Notification

Description:

The <running> configuration has been changed by a NETCONF session.

Min parameters:

4

Max parameters:

4

YANG file:

ietf-netconf-notifications.yang

Parameters:

  • changed-by:

    • username

      • type: string

      • usage: mandatory

      • This parameter identifies the SSH user name that is associated with the session.

    • session-id

      • type: uint32 (range 1 to max)

      • usage: mandatory

      • This parameter identifies the NETCONF session ID assigned to the session.

    • source-host

      • type: inet:ip-address

      • usage: mandatory

      • This parameter identifies the remote host IP address that is associated with the session.

  • datastore

    • type: string

    • usage: mandatory

    • This parameter identifies the datastore that changed

  • edit

    • list (with no key) of edit operations performed, 1 entry for each edit:

      • target

        • type: instance-identifier

        • usage: mandatory

        • This parameter contains the absolute path expression of the database object node that was modified.

      • operation

        • type: enumeration (merge, replace, create, delete)

        • usage: mandatory

        • This parameter identifies the nc:operation that was performed on the target node in the database.

      • new-value

        • type: anyxml

        • usage: optional (if --with-yumaworks-config-change=true)

        • This parameter contains the new value for the associated 'target' if the operation is not 'delete' or 'remove'. This object should represent a container with one child node specifying the new value used in the associated edit.

      • old-value

        • type: anyxml

        • usage: optional (if --with-yumaworks-config-change=true)

        • This parameter contains the old value for the associate 'target' that was changed or deleted, if operation is not 'create', This object should represent a container with one child node specifying the current value used in the associated edit.

Example:

<?xml version="1.0" encoding="UTF-8"?>
<notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
  <eventTime>2018-04-20T19:31:44Z</eventTime>
  <netconf-config-change
      xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-notifications">
    <changed-by>
      <username>andy</username>
      <session-id>3</session-id>
      <source-host>127.0.0.1</source-host>
    </changed-by>
    <datastore>running</datastore>
    <edit>
      <target xmlns:nacm="urn:ietf:params:xml:ns:yang:ietf-netconf-acm">/nacm:nacm</target>
      <operation>create</operation>
    </edit>
  </netconf-config-change>
</notification>

Examples --with-yumaworks-config-change:

Create Operation:

<?xml version="1.0" encoding="UTF-8"?>
 <notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
  <eventTime>2019-06-11T02:39:15Z</eventTime>
  <netconf-config-change xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-notifications">
   <changed-by>
    <username>andy</username>
    <session-id>3</session-id>
    <source-host>127.0.0.1</source-host>
   </changed-by>
   <datastore>running</datastore>
   <edit>
    <target
     xmlns:t="http://netconfcentral.org/ns/test">/t:int8.1</target>
    <operation>create</operation>
    <new-value xmlns="http://yumaworks.com/ns/yumaworks-config-change">
     <int8.1 xmlns="http://netconfcentral.org/ns/test">42</int8.1>
    </new-value>
   </edit>
  </netconf-config-change>
 </notification>

Modify Operation:

<?xml version="1.0" encoding="UTF-8"?>
<notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
  <eventTime>2019-06-11T02:42:19Z</eventTime>
  <netconf-config-change xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-notifications">
    <changed-by>
      <username>andy</username>
      <session-id>3</session-id>
      <source-host>127.0.0.1</source-host>
    </changed-by>
    <datastore>running</datastore>
    <edit>
      <target xmlns:t="http://netconfcentral.org/ns/test">/t:int8.1</target>
      <operation>replace</operation>
      <new-value xmlns="http://yumaworks.com/ns/yumaworks-config-change">
       <int8.1 xmlns="http://netconfcentral.org/ns/test">1</int8.1>
      </new-value>
      <old-value xmlns="http://yumaworks.com/ns/yumaworks-config-change">
       <int8.1 xmlns="http://netconfcentral.org/ns/test">42</int8.1>
      </old-value>
    </edit>
  </netconf-config-change>
</notification>

Delete Operation:

<?xml version="1.0" encoding="UTF-8"?>
<notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
  <eventTime>2019-06-11T02:42:51Z</eventTime>
  <netconf-config-change xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-notifications">
    <changed-by>
      <username>andy</username>
      <session-id>3</session-id>
      <source-host>127.0.0.1</source-host>
    </changed-by>
    <datastore>running</datastore>
    <edit>
      <target xmlns:t="http://netconfcentral.org/ns/test">/t:int8.1</target>
      <operation>delete</operation>
      <old-value xmlns="http://yumaworks.com/ns/yumaworks-config-change">
        <int8.1 xmlns="http://netconfcentral.org/ns/test">1</int8.1>
      </old-value>
    </edit>
  </netconf-config-change>
</notification>

<netconf-capability-change> Event

The <netconf-capability-change> notification is generated when the set of active capabilities for the server has changed.

The most common way this notification is generated is after the <load> operation has been used to add a new YANG module to the system.

It is possible that this notification will be generated for removal of capabilities. However, at this time, there are no NETCONF capabilities that can be removed from the running system.

The <added-capability> leaf list will contain the capability URI for each new capability that has just been added.

The <deleted-capability> leaf list will contain the capability URI for each existing capability that has just been deleted.

The <changedBy> container will identity whether the server or a NETCONF session caused the capability change.

If the change was made by the server, then this container will have an empty leaf named <server>.

If the change was made by a NETCONF session, the user name, remote address, and session ID for the session that caused the change are reported.

When this notification is generated, the ietf-netconf-monitoring.yang data model <capabilities> data structure is updated to reflect the changes.

Note

The server generates one event for each changed capability. It does not combine multiple capability changes into one event.

+---n netconf-capability-change
   +--ro changed-by
   |  +--ro (server-or-user)
   |     +--:(server)
   |     |  +--ro server?        empty
   |     +--:(by-user)
   |        +--ro username       string
   |        +--ro session-id     nc:session-id-or-zero-type
   |        +--ro source-host?   inet:ip-address
   +--ro added-capability*      inet:uri
   +--ro deleted-capability*    inet:uri
   +--ro modified-capability*   inet:uri

<netconf-capability-change> Notification

Description:

The set of currently active <capability> URIs has changed

Min parameters:

2

Max parameters:

5

YANG file:

ietf-netconf-notifications.yang

Parameters:

  • choice changed-by (server or by-user)

    • server

      • type: empty

      • usage: mandatory

      • If this empty leaf is present, then the server caused the capability change.

    • case by-user (if a NETCONF session caused the capability change)

      • username

        • type: string

        • usage: mandatory

        • This parameter identifies the SSH user name that is associated with the session.

      • session-id

        • type: uint32 (range 1 to max)

        • usage: mandatory

        • This parameter identifies the NETCONF session ID assigned to the session.

      • source-host

        • type: inet:ip-address

        • usage: mandatory

        • This parameter identifies the remote host IP address that is associated with the session.

  • added-capability

    • type:leaf-list of capability URI strings

    • usage: optional

    • This parameter contains one entry for each capability that was just added

  • deleted-capability

    • type:leaf-list of capability URI strings

    • usage: optional

    • This parameter contains one entry for each capability that was just deleted.

Example:

<?xml version="1.0" encoding="UTF-8"?>
<notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
  <eventTime>2018-04-20T19:37:34Z</eventTime>
  <netconf-capability-change
     xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-notifications">
    <changed-by>
      <username>andy</username>
      <session-id>3</session-id>
      <source-host>127.0.0.1</source-host>
    </changed-by>
    <added-capability>http://netconfcentral.org/ns/test4?module=test4&amp;revision=2009-09-09</added-capability>
  </netconf-capability-change>
</notification>

<netconf-confirmed-commit> Event

The <netconf-confirmed-commit> notification is generated when the state of the confirmed-commit procedure has changed.

The confirmed-commit procedure is started when a <commit> operation with a <confirmed/> parameter is executed.

A <netconf-confirmed-commit> notification is generated several times for a single confirmed-commit procedure. One or more of the following sub-events will be generated:

  • start: A confirmed-commit procedure has started.

    • Sent once when the first <commit> operation is executed.

    • This event starts the confirmed-commit procedure.

    • If the <candidate> database is not altered, then the confirmed commit procedure will be skipped.

  • cancel: A confirmed-commit procedure has been canceled

    • Sent only if the original session is terminated.

    • This event terminates the confirmed-commit procedure.

  • timeout: A confirmed-commit procedure has timed out.

    • Sent only if the confirm-timeout interval expires.

    • This event terminates the confirmed-commit procedure.

  • extend: A confirmed-commit procedure has been extended.

    • Sent if the 2nd to N-1th <confirm> operation contains a <confirmed/> parameter.

    • This event restarts the confirm-timeout interval, but does not reset the backup database.

    • Any new changes in the <candidate> database will be committed.

  • complete: A confirmed-commit procedure has completed.

    • Sent if the 2nd to Nth <commit> operation is executed before the confirm-timeout interval expires.

    • This event terminates the confirmed-commit procedure.

+---n netconf-confirmed-commit
   +--ro username         string
   +--ro session-id       nc:session-id-or-zero-type
   +--ro source-host?     inet:ip-address
   +--ro confirm-event    enumeration
   +--ro timeout?         uint32

<netconf-confirmed-commit> Notification

Description:

The state of the confirmed-commit procedure has changed.

Min parameters:

1

Max parameters:

4

YANG file:

ietf-netconf-notifications.yang

Parameters:

  • username

    • type: string

    • usage: mandatory

    • This parameter identifies the SSH user name that is associated with the session that caused the confirmed-commit procedure state change.

  • session-id

    • type: uint32 (range 1 to max)

    • usage: mandatory

    • This parameter identifies the NETCONF session ID assigned to the session.

  • source-host

    • type: inet:ip-address

    • usage: mandatory

    • This parameter identifies the remote host IP address that is associated with the session.

  • confirm-event

    • type: enumeration (start, cancel, timeout, extend, complete)

    • usage: mandatory

    • This parameter indicates why the confirmed-commit procedure changed state.

Example Confirm Commit Start Event:

<?xml version="1.0" encoding="UTF-8"?>
 <notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
  <eventTime>2018-04-20T19:41:34Z</eventTime>
  <netconf-confirmed-commit
      xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-notifications">
   <username>andy</username>
   <session-id>3</session-id>
   <source-host>127.0.0.1</source-host>
   <confirm-event>start</confirm-event>
   <timeout>10</timeout>
  </netconf-confirmed-commit>
 </notification>

Example Confirm Commit Timeout Event:

<?xml version="1.0" encoding="UTF-8"?>
<notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
  <eventTime>2018-04-20T19:41:44Z</eventTime>
  <netconf-confirmed-commit
      xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-notifications">
    <confirm-event>timeout</confirm-event>
  </netconf-confirmed-commit>
</notification>

<yang-library-change> Event

The <yang-library-change> notification is generated when the set of modules and submodules supported by the server has changed.

The most common way this notification is generated is after the <load> or <unload> operation has been used to add a new YANG module to the system.

Note that for a NETCONF server that implements YANG 1.1, a change of the "module-set-id" value results in a new value for the :yang-library capability. Thus, if such a server implements NETCONF notifications, and the notification <netconf-capability-change>, a <netconf-capability-change> and <yang-library-change> notifications are generated whenever the "module-set-id" changes.

x---n yang-library-change
   x--ro module-set-id    -> /modules-state/module-set-id

<yang-library-change> Notification

Description:

The module-set-id value has changed

Min parameters:

1

Max parameters:

1

YANG file:

ietf-yang-library.yang

Parameters:

  • leaf module-set-id

    • type:leafref. Path: /yanglib:modules-state/yanglib:module-set-id

    • usage: mandatory

    • Contains the module-set-id value representing the set of modules and submodules supported at the server at the time the notification is generated

Example:

<?xml version="1.0" encoding="UTF-8"?>
<notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
  <eventTime>2016-11-15T18:03:29Z</eventTime>
  <yang-library-change xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-library">
    <module-set-id>6765</module-set-id>
  </yang-library-change>
</notification>

<replay-completed> Event

The <replay-completed> notification is generated for an RFC 8639 subscription when the replay portion of the subscription has been completed.

+---n replay-completed {replay}?
   +--ro id    subscription-id

<replay-complete> Notification

Description:

The replay events have completed

Min parameters:

1

Max parameters:

1

YANG file:

ietf-subscribed-notifications.yang

Parameters:

  • leaf subscription-id

    • type: uint32

    • usage: mandatory

    • Contains the subscription ID that has completed all replay events.

<subscription-modified> Event

The <subscription-modified> notification is generated for an RFC 8639 subscription when it has been modified using the <modify-subscription> operation.

+---n subscription-modified
    +--ro id                                               subscription-id
    +--ro (target)
    |  +--:(stream)
    |  |  +--ro (stream-filter)?
    |  |  |  +--:(by-reference)
    |  |  |  |  +--ro stream-filter-name                   stream-filter-ref
    |  |  |  +--:(within-subscription)
    |  |  |     +--ro (filter-spec)?
    |  |  |        +--:(stream-subtree-filter)
    |  |  |        |  +--ro stream-subtree-filter?         <anydata> {subtree}?
    |  |  |        +--:(stream-xpath-filter)
    |  |  |           +--ro stream-xpath-filter?           yang:xpath1.0 {xpath}?
    |  |  +--ro stream                                     stream-ref
    |  |  +--ro replay-start-time?                         yang:date-and-time {replay}?
    |  +--:(yp:datastore)
    |     +--ro yp:datastore                               identityref
    |     +--ro (yp:selection-filter)?
    |        +--:(yp:by-reference)
    |        |  +--ro yp:selection-filter-ref              selection-filter-ref
    |        +--:(yp:within-subscription)
    |           +--ro (yp:filter-spec)?
    |              +--:(yp:datastore-subtree-filter)
    |              |  +--ro yp:datastore-subtree-filter?   <anydata> {sn:subtree}?
    |              +--:(yp:datastore-xpath-filter)
    |                 +--ro yp:datastore-xpath-filter?     yang:xpath1.0 {sn:xpath}?
    +--ro stop-time?                                       yang:date-and-time
    +--ro dscp?                                            inet:dscp {dscp}?
    +--ro weighting?                                       uint8 {qos}?
    +--ro dependency?                                      subscription-id {qos}?
    +--ro transport?                                       transport {configured}?
    +--ro encoding?                                        encoding
    +--ro purpose?                                         string {configured}?
    +--ro (yp:update-trigger)?
       +--:(yp:periodic)
       |  +--ro yp:periodic!
       |     +--ro yp:period         centiseconds
       |     +--ro yp:anchor-time?   yang:date-and-time
       +--:(yp:on-change) {on-change}?
          +--ro yp:on-change!
             +--ro yp:dampening-period?   centiseconds
             +--ro yp:sync-on-start?      boolean
             +--ro yp:excluded-change*    change-type

<subscription-modified> Notification

Description:

The subscription parameters have changed

Min parameters:

1

Max parameters:

7

YANG file:

Parameters:

  • leaf id

    • type: uint32

    • usage: mandatory

    • Contains the subscription ID that has been modified.

<subscription-terminated> Event

The <subscription-terminated> notification is generated for an RFC 8639 subscription that has been terminated for any reason.

+---n subscription-terminated
   +--ro id        subscription-id
   +--ro reason    identityref

<subscription-terminated> Notification

Description:

The subscription has been terminated

Min parameters:

2

Max parameters:

2

YANG file:

ietf-subscribed-notifications.yang

Parameters:

  • leaf id

    • type: uint32

    • usage: mandatory

    • Contains the subscription ID that has been terminated

  • leaf reason

    • type: identityref

    • usage: mandatory

    • Contains the identity describing the reason the subscription has been terminated

<push-update> Event

The <push-update> notification is generated for an RFC 8639 subscription when new datastore update information needs to be sent for a YANG Push subscription. This form of a PUSH update is used to send the complete contents of the target data nodes.

+---n push-update
   +--ro id?                   sn:subscription-id
   +--ro datastore-contents?   <anydata>
   +--ro incomplete-update?    empty

<push-update> Notification

Description:

Datastore contents have been updated

Min parameters:

2

Max parameters:

3

YANG file:

ietf-yang-push.yang

Parameters:

  • leaf id

    • type: uint32

    • usage: mandatory

    • Contains the subscription ID that is being updated

  • anydata datastore-contents

    • type: anydata

    • usage: mandatory

    • Container with the YANG data nodes sent in this update

  • leaf incomplete-update

    • type: empty

    • usage: optional

    • Flag indicating the datastore-contents are incomplete somehow

<push-change-update> Event

The <push-change-update> notification is generated for an RFC 8639 subscription when new datastore update information needs to be sent for a YANG Push subscription. This form of a PUSH update is used to send a patch since the last update. The YANG Patch data structure defined in RFC 8072 is used to convey the patch information.

+---n push-change-update {on-change}?
   +--ro id?                  sn:subscription-id
   +--ro datastore-changes
   |  +--ro yang-patch
   |     +--ro patch-id    string
   |     +--ro comment?    string
   |     +--ro edit* [edit-id]
   |        +--ro edit-id      string
   |        +--ro operation    enumeration
   |        +--ro target       target-resource-offset
   |        +--ro point?       target-resource-offset
   |        +--ro where?       enumeration
   |        +--ro value?       <anydata>
   +--ro incomplete-update?   empty

<push-change-update> Notification

Description:

Datastore contents have been updated

Min parameters:

2

Max parameters:

3

YANG file:

ietf-yang-push.yang

Parameters:

  • leaf id

    • type: uint32

    • usage: mandatory

    • Contains the subscription ID that is being updated

  • container datastore-changes

    • type: anydata

    • usage: mandatory

    • Container with the YANG Patch sent in this update

  • leaf incomplete-update

    • type: empty

    • usage: optional

    • Flag indicating the datastore-contents are incomplete somehow

High Availability (YP-HA)

The netconfd-pro server supports the following hardware-based high-availability features:

  • The configuration data on the active server can be replicated on multiple standby servers.

  • The module and bundle configuration on the active server can be replicated on multiple standby servers, even if modules or bundles are loaded or unloaded at run-time.

  • An HA server pool is configured through the CLI or configuration file. Only servers specified in the configuration are allowed to join the YP-HA server pool.

  • Each HA server operates in a specific HA Role

    • active: There is one active server in the HA pool providing full service and management features.

    • standby: All but one server can be in Standby mode. Only superuser sessions are allowed in this mode. Notifications are disabled. The server will connect to the active server and participate in the YP-HA protocol.

    • none: The server is waiting its HA role. It is not attempting to connect to any active server. Only superuser sessions are allowed in this mode. Notifications are disabled.

  • The server HA Role (Active, Standby, or None) can be switched in several ways

    • yp-system library init1 function callback (to set initial role)

    • agt_timer callbacks at run-time

    • DB-API subsystem using the <yp-ha-mode> subsystem event message

    • yp-ha-app program

      • yp-ha-app --go-active

      • yp-ha-app --go-standby=new-active

      • yp-ha-app --go-none

  • Management sessions and notification processing are disabled if the server is in HA standby mode

    • Management sessions are enabled for the “superuser” user name if configured

  • SIL-SA and DB-API sessions are always allowed, even if YP-HA is in standby mode

  • DB-API edit requests for system edits will be enabled in a future release

  • DB-API edit requests for user edits are disabled if the server is in HA standby mode

  • The --ha-sil-standby parameter can be used to enable edit callbacks (SIL, SIL-SA, HOOK) on a server running in HA standby mode. The server callback code must understand that YP-HA is enabled and the server is running in HA standby mode.

If YP-HA is enabled, then the server will wait for its HA role unless the --ha-initial-active CLI parameter is set. This parameter should only be used for debugging because if the server reboots it will use the assigned role.

In normal operation all YP-HA roles are set and changed by external code (external process of same process).

If the server boots waiting for its HA role, then an empty factory default configuration will be loaded in order to validate the YANG modules loaded. If the server starts the HA active role, then the configuration will be loaded for real before management sessions and notifications are enabled. If the server starts the HA standby role, then it will get its configuration from the active server.

YP-HA Configuration

YP-HA CLI Parameters

Parameter

Description

--ha-enabled

Enabled the YP-HA feature

--ha-initial-active

Set the HA role from the CLI at boot-time (for debugging only)

--ha-server

Configure a server in the YP-HA server pool

--ha-server-key

String identifying the HA server pool for the server

--ha-sil-standby

Enable edit callbacks (SIL, SIL-SA, HOOK) in YP HA standby mode

--server-id

Identifies a server within a YP-HA pool, default value is server1

--socket-type=tcp`

The YControl socket type must be set to “tcp”

--socket-address

The YControl socket address must be set

--socket-port

The YControl socket port number must be set

../_images/yp_ha_example.png

In this example there are 3 separate systems, each running netconfd-pro.

Configuration parameters for Server ha-1:

ha-enabled true
ha-server ha-1@192.168.0.100
ha-server ha-2@192.168.0.105
ha-server ha-3@192.168.0.108
ha-server-key ha-pool-1
server-id ha-1
socket-type tcp
socket-address 192.168.0.100
socket-port 8088

Configuration parameters for Server ha-2:

ha-enabled true
ha-server ha-1@192.168.0.100
ha-server ha-2@192.168.0.105
ha-server ha-3@192.168.0.108
ha-server-key ha-pool-1
server-id ha-2
socket-type tcp
socket-address 192.168.0.105
socket-port 8088

Configuration parameters for Server ha-3:

ha-enabled true
ha-server ha-1@192.168.0.100
ha-server ha-2@192.168.0.105
ha-server ha-3@192.168.0.108
ha-server-key ha-pool-1
server-id ha-3
socket-type tcp
socket-address 192.168.0.108
socket-port 8088

In this configuration, all 3 servers will start waiting for an HA role.

It is expected that 1 will be assigned the HA active role and the other 2 servers will be assigned the HA standby role.

YP-HA Monitoring

The yumaworks-system module contains an RPC operation called <get-ha-status>. This operation can be invoked from a client session or from DB-API using the subrpc request. This operation can be used to determine the current server YP-HA state and configuration parameters. Refer to the <get-ha-status> operation for more details.

Configuration Templates

Configuration templates allow some parts of the configuration datastore to be pre-configured.

This can be done to pre-populate vendor or site-specific values, allowing the actual configuration to be simpler and more generic.

Configuration templates are stored in the running configuration in list “/templates/template”. There are only 3 fields in a template:

  • name: the name of the template (list key)

  • data-target: path of the container or list that matches the template

  • data: anydata wrapper for the configuration template data

A template is used by specifying the <with-template> parameter in the <edit-config> operation.

Multiple instances of this parameter can be present, allowing multiple templates to be applied or attempted.

If a template does not apply it is ignored.

If a template does apply, then the child nodes specified in the template are applied if they are not already present in the edit request. Templates are only applied to “create” operations. The values are expanded on first use of the configuration data indicated by the <data-target> field in the template. If this data represents a list entry, this this data must specify all key values.

If list keys are present in the configuration template then the template will only be applied if these values match the same key leaf value in the target data.

Refer to the yumaworks-templates.yang section for additional details on this YANG module.

Configuration Template Example: NACM group

Example template “t1”:

<templates xmlns="http://yumaworks.com/ns/yumaworks-templates">
  <template>
    <name>t1</name>
    <data-target>/nacm/groups/group</data-target>
    <data>
      <group xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm">
        <name>admin</name>
        <user-name>andy</user-name>
        <user-name>test1</user-name>
        <user-name>test2</user-name>
      </group>
    </data>
  </template>
</templates>

Example <edit-config> request using <with-template> parameter:

<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="8" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <edit-config>
     <target><candidate/></target>
     <config>
       <nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm">
        <groups>
          <group>
            <name>admin</name>
          </group>
        </groups>
       </nacm>
      </config>
      <with-template
        xmlns="http://yumaworks.com/ns/yumaworks-templates">t1</with-template>
   </edit-config>
</rpc>

The following data will be created after template “t1” is applied

<nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm">
  <groups>
    <group>
      <name>admin</name>
      <user-name>andy</user-name>
      <user-name>test1</user-name>
      <user-name>test2</user-name>
    </group>
  </groups>
</nacm>

NETCONF Over TLS

The NETCONF over TLS protocol is defined in RFC 7589

If the server image is built with the WITH_OPENSSL=1 parameter (or EVERYTHING=1 parameter) then NETCONF over TLS support will be available.

TLS Configuration

The following CLI and configuration parameters are available to support NETCONF over TLS sessions:

CLI Parameters for NETCONF over TLS

Parameter

Description

--cert-default-user

DEBUG only default user-name to use if no user-certmap found for an incoming NETCONF over TLS session

--cert-usermap

Map a client user-name to a X.509 fingerprint for the client certificate. Required for each user name to be used with NETCONF over TLS. Use yumaworks-cert-usermap.yang to configure X.509 cert-to-name entries at runtime.

--insecure-ok

DEBUG only option to accept client certificates that cannot be verified in the local truststore

--netconf-tls-address

The IP address to listen for NETCONF over TLS sessions. The default is 0.0.0.0

--netconf-tls-certificate

The public certificate file that must be provided to use NETCONF over TLS

--netconf-tls-key

The private certificate file that must be provided to use NETCONF over TLS

--netconf-tls-port

The TCP port to listen for NETCONF over TLS sessions. The default is 6513

--netconf-tls-trust-store

The file or directory to look for client certificates to determine if they are trusted

--with-netconf-tls

This flag must be set to true to enable NETCONF over TLS

YANG Module for NETCONF over TLS

The yumaworks-cert-usermap.yang module provides YANG configuration of the certificate to user name mappings. This YANG module implements the Client Identity procedures defined in section 6 of RFC 7589.

The 'cert-to-name' grouping defined in the ietf-x509-cert-to-name.yang module is adapted for use with NETCONF over TLS, even though RFC 7407 is defined for SNMP over TLS configuration. The TLS usage is the same in both protocols.

The Subject Alternate Name (SAN) fields described in RFC 7589 are supported. The Common Name (CN) field is supported but it is deprecated and SAN fields should be used instead.

Note

When checking a client X.509 certificate for a username mapping:

  • The server will check all --cert-usermap parameters first.

  • The server will then check all 'cert-to-name' list entries.

IETF Call Home

The IETF Call Home feature (RFC 8071) provides the following features:

  • Supports Call Home for NETCONF over SSH, and NETCONF over TLS, as defined in RFC 8071.

  • allows the server to initiate the TCP connection to 1 or more managers that implement IETF Call Home, called a “callhome server”.

  • allows NETCONF sessions to be started through firewalls

  • allows server discovery and bootstrap configuration

Call Home CLI Configuration

Call Home CLI Parameters

Parameter

Description

--callhome-reconnect

Specifies whether server will reconnect after client closes the session.

--callhome-retry-interval

Specifies the number of seconds to wait after a connect attempt to the callhome server has failed before attempting another connect attempt to that server.

--callhome-retry-max

Specifies the number of retry attempts the server should attempt to the callhome server before giving up.

--callhome-server

Specifies a callhome/SSH server that this server should attempt to initiate a callhome connection at boot-time.

--callhome-tls-server

Specifies a callhome/TLS server that this server should attempt to initiate a callhome connection at boot-time.

--callhome-sshd-command

Specifies the command used in Call Home to invoke the SSH server

--callhome-sshd-config

Specifies the filespec for the config file used in Call Home to invoke the SSH server

--callhome-subsys-command

Specifies the command used in Call Home to invoke the netconf subsystem

--with-callhome

Enable or disable the IETF Call Home protocol

Notes for NETCONF over SSH Call Home:

  • The CallHome over SSH port is called “netconf-ch-ssh” by IANA.

  • The default TCP port number is 4334.

  • The netconfd-pro server probably needs to be started with “s netconfd-pro u”

  • If the --with-callhome parameter is set to 'true' then the server will check if any --callhome-server parameters are provided. If not, then the Call Home feature will not be used on the server.

  • The server will fork a process for each callhome server that will attempt a TCP connection to one of the callhome servers configured on the netconfd-pro server.

  • If the TCP connection succeeds the SSH server will be called in “inetd” mode. The SSH server will wait for the client (callhome server) to initiate an SSH session to the netconfd-pro server.

  • If the client successfully initiates a NETCONF session, a new incoming session will be started on the server in the normal manner. The server will check if the incoming session was started by callhome, in order to skip the TCP port checks. The source port will not be 830 (or whatever is specified in the --port CLI parameter), but rather the source port used by the server to initiate the TCP connection.

../_images/callhome_graphic.png

In this example there are 3 separate systems, 1 netconfd-pro server and 2 callhome servers

Configuration parameters for the netconfd-pro server:

netconfd-pro {
  callhome-reconnect true
  callhome-retry-interval 30
  callhome-retry-max 10
  callhome-server ch1@192.168.0.44
  callhome-server ch2@192.168.1.1
  with-callhome true
}

Call Home YANG Configuration

The yumaworks-callhome module can be used to configure Call Home servers with YANG.

+--rw callhome
   +--rw server* [name]
      +--rw name        yang:yang-identifier
      +--rw address     inet:host
      +--rw port?       inet:port-number
      +--rw protocol    enumeration

The YANG module contains a list called “server”, which is a list of CallHome servers for connections. This configured list is used in addition to any bootstrap callhome servers created with CLI parameters. Entries can be created and deleted but not modified. If an entry is deleted then the CallHome session associated with the entry is not affected. Only the configuration is affected, which affects the sessions started on the next reboot..

  • name: This value must not be the same as any callhome server name used in a --callhome-server CLI parameter, in order to prevent confusing logging messages with duplicate names. A 'duplicate entry' error message will be returned in this case.

  • address: IP Address or host name for the callhome server. This must not be a loopback address, which would imply the client and server are running on the same host.

  • port: the TCP port number for the callhome server. If not present then the default port for the protocol will be used.

  • protocol: enumeration

    • netconf-ssh: Use a NETCONF over SSH Call Home connection

    • netconf-tls: Use a NETCONF over TLS Call Home connections

YANG Push

The YANG Push feature allow data to be sent to a client automatically, using NETCONF notifications.

A separate mechanism for managing dynamic subscriptions is used by YANG Push, which is intended to replace the existing <create-subscription> RPC operation defined in RFC 5277. This new set of RPC operations (defined in RFC 8639) is used for current event stream subscriptions. It is also used for new datastore subscriptions (defined in RFC8641).

../_images/yang-push-components.png

The YANG Push support will be provided in multiple phases:

  1. Dynamic subscriptions over NETCONF in XML

    1. Periodic subscriptions

    2. Conventional datastore On-Change subscriptions

    3. Simulated On-Change subscriptions for the Operational Datastore

    4. On-Change subscriptions for the Operational Datastore from subsystem events

  2. Dynamic subscriptions over RESTCONF in XML or JSON

  3. Configured subscriptions for Binary Push support

    1. gRPC for native protobuf files

    2. gNMI ONCHANGE subscriptions

    3. CBOR+SID encoding over UDP

RFCs and Features Supported

There are multiple ways to do the same thing in YANG Push, so not all of it is implemented at once.

  • The “dynamic subscriptions” functionality is implemented in phase 1.

    • phase 1.4 is not available in this release

  • The “configured subscriptions” functionality is not needed or relevant for subscriptions that use NETCONF sessions. It is intended for a binary push protocol that is expected to be standardized in the near future. This is planned for phase 4.

  • RFC 8639: Subscription to YANG Notifications

  • RFC 8640: Dynamic Subscription to YANG Events and Datastores over NETCONF

  • RFC 8641: Subscription to YANG Notifications for Datastore Updates

    • YANG Module: ietf-yang-push@2019-09-09.yang

    • Supported Features

      • on-change

    • Unsupported Objects

      • /subscriptions data node not available for NMDA access to <operational> values of dynamic subscriptions

      • anchor-time parameter is not implemented yet

Configuring YANG Push

There is no CLI parameter to turn YANG Push on or off. Instead, then “bundle” parameter is used.

  • A bundle named “yang-push” is used.

  • “yang-push” is a reserved library name in the server.

  • The SIL library (libyang-push.so) contains the RPC operation callbacks for YANG Push. The “agt” directory contains the server implementation code.

  • The server does not need to support or enable NMDA to use YANG Push. If the --with-nmda parameter is set to ‘false’ then the <operational> datastore will consist of config=false data nodes and their ancestor lists, list keys, and containers.

  • The source code must be built using WITH_YANG_PUSH=1 or EVERYTHING=1 make flag in order for the YANG Push code to be included in the target binaries.

netconfd-pro {
  bundle yang-push
}

YANG Push CLI Parameters

Parameter

Default

Description

--bundle=yang-push

not loaded

The bundle parameter is used to enable or disable the entire YANG Push feature

--push-max-operational

4

Specifies the maximum number of on-change push subscriptions that can be in use at once for the <operational> datastore

--push-max-periodic

16

Specifies the maximum number of periodic push subscriptions that can be in use at once

--push-min-dampening

100

Specifies the minimum value for the 'dampening-period' parameter that will be accepted for an on-change push subscription. (centiseconds)

--push-min-period

100

Specifies the minimum value for the 'period' parameter that will be accepted for a periodic push subscription. (centiseconds)

--push-simop-enabled

true

Specifies if the simulated on-change push subscriptions should be enabled for the <operational> datastore.

--push-simop-patch-update

true

Specifies the notification message that should be used for a simulated on-change push subscription.

--push-simop-period

500

Specifies the value for the 'period' parameter that will be used for simulated operational on-change push subscription.

Configuring Named Filters

The /filters container and /filters/stream-filter list are defined in RFC 8639.

+--rw filters
|  +--rw stream-filter* [name]
|  |  +--rw name                           string
|  |  +--rw (filter-spec)?
|  |     +--:(stream-subtree-filter)
|  |     |  +--rw stream-subtree-filter?   <anydata> {subtree}?
|  |     +--:(stream-xpath-filter)
|  |        +--rw stream-xpath-filter?     yang:xpath1.0 {xpath}?
|  +--rw yp:selection-filter* [filter-id]
|     +--rw yp:filter-id                         string
|     +--rw (yp:filter-spec)?
|        +--:(yp:datastore-subtree-filter)
|        |  +--rw yp:datastore-subtree-filter?   <anydata> {sn:subtree}?
|        +--:(yp:datastore-xpath-filter)
|           +--rw yp:datastore-xpath-filter?     yang:xpath1.0 {sn:xpath}?

Named filters are fully supported, using the /filters subtree:

  • An event stream subscription can use the “stream-filter” list

  • A datastore subscriptions can use the selection-filter list.

  • Even though the contents of each list are similar, the content of the filters is not.

  • A “stream-filter” is a notification filter, and the content is exactly like the <filter> element used in the “create-subscription” operation.

  • A “selection-filter” is a retrieval filter, and the content is exactly like the <filter> element used in the “get” operation.

Filter Configuration Restrictions

  • A filter can be created at any time.

  • A filter can be modified at any time. If any subscriptions are using the filter then they will updated to use the new filter as soon as possible. This is usually as soon as any current message on that session is completed.

    • If the new filter is not acceptable for a subscription using the filter then that subscription will be terminated. Use caution when modifying a filter that is in use.

  • A filter can only be deleted if no subscription is using it.

  • An empty filter is allowed, which means only a key leaf was provided and not a filter leaf. This allows placeholders to be used. It is not recommended to use this feature. An empty filter is the same as no filter, and if that is not allowed for a subscription, then it will be rejected (or deleted if already active).

  • Sending anydata for a subtree filter, or an xpath1.0 leaf for an XPath filter can be complex or even unsupported in the client. XPath filters will be accepted without prefixed identifiers. If prefixes are used, then they must be properly mapped to a module namespace URI using an “xmlns” attribute. If multiple nodes match the same local name then prefixes are required to pick only one of them.

Filter Examples

A subtree filter for an event stream that selects the “netconf-session-end” event:

<filters xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications">
  <stream-filter>
    <name>filter1</name>
    <stream-subtree-filter>
      <netconf-session-end xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-notifications" />
    </stream-subtree-filter>
  </stream-filter>
</filters>

An XPath filter for an event stream that selects the “netconf-session-start” event:

<filters xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications">
  <stream-filter>
    <name>filter2</name>
    <stream-xpath-filter xmlns:n="urn:ietf:params:xml:ns:yang:ietf-netconf-notifications"
       >/n:netconf-session-start</stream-xpath-filter>
  </stream-filter>
</filters>

A subtree filter for a datastore that selects the /nacm/groups subtree.

<filters xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications">
  <selection-filter xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-push">
    <filter-id>filter2</filter-id>
    <datastore-subtree-filter>
      <nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm">
        <groups />
      </nacm>
    </datastore-subtree-filter>
  </selection-filter>
</filters>

An XPath filter for a datastore that selects the /nacm/groups subtree:

<filters xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications">
  <selection-filter xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-push">
    <filter-id>filter3</filter-id>
    <datastore-xpath-filter
      xmlns:n="urn:ietf:params:xml:ns:yang:ietf-netconf-acm"
      >/n:nacm/n:groups</datastore-xpath-filter>
  </selection-filter>
</filters>

YANG Push RPC Operations

The following RPC Operations are supported

  • establish-subscription

  • modify-subscription

  • delete-subscription

  • kill-subscription

  • resync-subscription

YANG Push Notification Events

The following Notifications are supported:

  • push-update

  • push-change-update

  • replay-completed

  • subscription-modified

  • subscription-resumed

  • subscription-suspended

  • subscription-terminated

Periodic Subscriptions

A periodic push subscription request that is granted will cause the specified data to be pushed at a specified interval.

The data is sent whether it changed or not. Every interval, a push-update notification with the specified data will be sent to the subscription.

The --push-max-periodic CLI parameter controls the number of these push subscriptions that can be enabled at once. This is the server total, so one subscription could use up all the subscriptions. The server does not prevent a session from establishing multiple subscriptions.

Use the <establish-subscription> operation to start a periodic subscription. The “datastore”, and “period” parameters must be provided.

There are no filter restrictions for a periodic subscription. Any filter that is allowed for a <get> operation may be used for a periodic subscription. If a named filter is used then it can be modified while a periodic subscription is active. The subscription output will be updated as soon as possible after a filter reference in use is modified.

The datastore parameter can be set to “candidate”, “operational”, or “running”. It must be set to “operational” to monitor config=false data nodes.

Example: Retrieve the /interfaces-state/interface entry for interface “lo” every 30 seconds.

The client might send this request:

<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="2" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <establish-subscription xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications">
    <datastore xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-push"
      xmlns:ds="urn:ietf:params:xml:ns:yang:ietf-datastores">ds:operational</datastore>
    <datastore-subtree-filter xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-push">
      <interfaces-state xmlns="urn:ietf:params:xml:ns:yang:ietf-interfaces">
        <interface>
          <name>lo</name>
        </interface>
      </interfaces-state>
    </datastore-subtree-filter>
    <periodic xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-push">
      <period>3000</period>
    </periodic>
  </establish-subscription>
</rpc>

The server sends the subscription-id in the reply if the subscription was accepted.

This is important since multiple subscriptions per session are allowed. The <push-update> and <push-change-update> notifications each contain an <id> leaf that matches the value returned in the <rpc-reply> for the <establish-subscription> request.

<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="2" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <id xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications">1</id>
</rpc-reply>

The server will send an initial “push-update” notification right away, and then periodically every 30 seconds

<?xml version="1.0" encoding="UTF-8"?>
<notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
  <eventTime>2020-10-11T19:02:59Z</eventTime>
  <push-update xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-push">
    <id>1</id>
    <datastore-contents>
      <interfaces-state xmlns="urn:ietf:params:xml:ns:yang:ietf-interfaces">
        <interface>
          <name>lo</name>
          <type xmlns:ianaift="urn:ietf:params:xml:ns:yang:iana-if-type"
            >ianaift:softwareLoopback</type>
          <admin-status>up</admin-status>
          <oper-status>up</oper-status>
          <if-index>1</if-index>
          <phys-address>00:00:00:00:00:00</phys-address>
          <speed>0</speed>
          <statistics>
            <in-octets>163797125</in-octets>
            <in-unicast-pkts>866265</in-unicast-pkts>
            <in-multicast-pkts>0</in-multicast-pkts>
            <in-discards>0</in-discards>
            <in-errors>0</in-errors>
            <out-octets>163797125</out-octets>
            <out-unicast-pkts>866265</out-unicast-pkts>
            <out-discards>0</out-discards>
            <out-errors>0</out-errors>
          </statistics>
        </interface>
      </interfaces-state>
    </datastore-contents>
  </push-update>
</notification>

Conventional On-Change Subscriptions

A conventional on-change subscription request that is granted will cause the specified data to be pushed when the data has changed. The “candidate” and “running” datastores can be monitored.

There is no internal overhead such as polling to support this subscription type. The server will check these subscriptions when a successful commit to the target datastore has been completed. Error operations are not reported to the subscription.

If the sync-on-start option is selected then a <push-update> will be sent when the subscription starts. After that, only <push-change-update> events will usually be sent. The resync-subscription operation will cause a new <push-update> notification to be generated as soon as possible.

The “on-change” presence container must be provided, and a “dampening-period” parameter must be provided. This must be greater or equal to the --push-min-dampening CLI parameter value.

The filter parameter is restricted. Two modes of operation are provided:

  1. object monitoring mode: The filter must represent one configuration data node. All instances of that one object will be monitored.

  2. datastore replication mode: No filter at all is used

Example: Object Monitoring Mode

Retrieve the /nacm/groups/group entry from <running> if any group is edited

Assume the client has created a named filter called “nacm-group”

<config>
  <filters xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications">
    <selection-filter xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-push">
      <filter-id>nacm-group</filter-id>
      <datastore-xpath-filter
        xmlns:n="urn:ietf:params:xml:ns:yang:ietf-netconf-acm"
        >/n:nacm/n:groups/n:group</datastore-xpath-filter>
    </selection-filter>
  </filters>
</config>

The client might send this request using a “selection-filter-ref” instead of an inline filter:

The dampening period is set to 10 seconds in this example.

<rpc message-id="5" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <establish-subscription xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications">
    <datastore xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-push"
      xmlns:ds="urn:ietf:params:xml:ns:yang:ietf-datastores">ds:running</datastore>
    <selection-filter-ref
      xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-push">nacm-group</selection-filter-ref>
    <on-change xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-push">
      <dampening-period>1000</dampening-period>
      <excluded-change>move</excluded-change>
      <sync-on-start>true</sync-on-start>
    </on-change>
  </establish-subscription>
</rpc>

Assume the server sent an <id> response with a value of “1” like the example above.

If the “sync-on-start” parameter is set to “true” (the default) then the server will send a <push-update> notification as soon as the subscription starts:

<notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
  <eventTime>2020-10-11T19:39:21Z</eventTime>
  <push-update xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-push">
    <id>1</id>
    <datastore-contents>
      <nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm">
        <groups>
          <group>
            <name>test1</name>
          </group>
        </groups>
      </nacm>
    </datastore-contents>
  </push-update>
</notifications>

The server will send a <push-change-update> notification when the targeted entry is changed

<?xml version="1.0" encoding="UTF-8"?>
<notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
  <eventTime>2020-10-11T19:42:01Z</eventTime>
  <push-change-update xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-push">
    <id>1</id>
    <datastore-changes>
      <yang-patch xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-push">
        <patch-id>0</patch-id>
        <edit>
          <edit-id>E1</edit-id>
          <operation>create</operation>
          <target>/ietf-netconf-acm:nacm/groups/group=monitor</target>
          <value>
            <group xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm">
              <name>monitor</name>
              <user-name>admin1</user-name>
              <user-name>admin2</user-name>
            </group>
          </value>
        </edit>
      </yang-patch>
    </datastore-changes>
  </push-change-update>
</notification>

Example: Datastore Replication Mode

Retrieve the patch for <running> if any config is edited

The dampening period is set to 10 seconds in this example.

The client might send this request without any filter parameter:

<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="2" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <establish-subscription xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications">
    <datastore xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-push"
           xmlns:ds="urn:ietf:params:xml:ns:yang:ietf-datastores">ds:running</datastore>
     <on-change xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-push">
       <dampening-period>1000</dampening-period>
     </on-change>
  </establish-subscription>
</rpc>

The server sends an <rpc-reply> with a new subscription ID, since another is in progress:

<?xml version="1.0" encoding="UTF-8"?>
<rpc-reply message-id="2" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <id xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications">2</id>
</rpc-reply>

The server will send the initial <push-update> notification right away

<?xml version="1.0" encoding="UTF-8"?>
<notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
  <eventTime>2020-10-11T19:50:29Z</eventTime>
  <push-update xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-push">
    <id>2</id>
    <datastore-contents>
      <filters xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications">
        <selection-filter xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-push">
          <filter-id>nacm-group</filter-id>
          <datastore-xpath-filter xmlns:n="urn:ietf:params:xml:ns:yang:ietf-netconf-acm"
            >/n:nacm/n:groups/n:group</datastore-xpath-filter>
        </selection-filter>
      </filters>
      <nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm">
        <groups>
          <group>
            <name>test1</name>
          </group>
          <group>
            <name>monitor</name>
            <user-name>admin1</user-name>
            <user-name>admin2</user-name>
          </group>
        </groups>
      </nacm>
    </datastore-contents>
  </push-update>
</notification>

If the <running> datastore changes at all the server will send a <push-change-update> notification:

In this example the /nacm/rule-list entry is edited:

<?xml version="1.0" encoding="UTF-8"?>
<notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
  <eventTime>2020-10-11T20:03:37Z</eventTime>
  <push-change-update xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-push">
    <id>2</id>
    <datastore-changes>
      <yang-patch xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-push">
        <patch-id>1</patch-id>
        <edit>
          <edit-id>E1</edit-id>
          <operation>create</operation>
          <target>/ietf-netconf-acm:nacm/rule-list=allow-nacm-read</target>
          <value>
            <rule-list xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm">
              <name>allow-nacm-read</name>
              <group>monitor</group>
              <rule>
                <name>r1</name>
                <module-name>ietf-netconf-acm</module-name>
                <access-operations>read</access-operations>
                <action>permit</action>
                <comment>allow monitor group to read nacm</comment>
              </rule>
            </rule-list>
          </value>
        </edit>
      </yang-patch>
    </datastore-changes>
  </push-change-update>
</notification>

Simulated Operational On-Change Subscriptions

A simulated operational on-change subscription request that is granted will cause the specified data to be pushed when the data has changed. The “operational” datastore can be monitored. These subscriptions are only allowed if the --push-simop-enabled parameter is set to ‘true’.

There is an internal polling and processing overhead required o support this subscription type. The server will check these subscriptions when the --push-simop-period interval expires. If the “dampening-period” parameter is provided then the maximum of these two parameters is used for the internal polling interval, when dampening is required.

If the sync-on-start option is selected then a <push-update> will be sent when the subscription starts. After that, only <push-change-update> Event notifications will usually be sent. The <resync-subscription> operation will cause a new <push-update> Event notification to be generated as soon as possible.

The “on-change” presence container must be provided, and a “dampening-period” parameter must be provided. This must be greater or equal to the --push-min-dampening CLI parameter value.

There are no filter restrictions for a simulated operational subscription. Any filter that is allowed for a <get> operation may be used for a simulated operational subscription. If a named filter is used then it can be modified while a subscription is active. The subscription output will be updated as soon as possible after a filter reference in use is modified.

Example: Retrieve the /netconf-state/backup-files subtree if it changes

In this example the <datastore-xpath-filter> does not use any prefixes. The server will accept this filter and find the correct data nodes even if the prefixes are missing.

In this example the dampening period is 1 second.

<?xml version="1.0" encoding="UTF-8"?>
<rpc message-id="9" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
  <establish-subscription xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-notifications">
    <datastore xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-push"
      xmlns:ds="urn:ietf:params:xml:ns:yang:ietf-datastores">ds:operational</datastore>
    <datastore-xpath-filter xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-push"
      >/netconf-state/backup-files</datastore-xpath-filter>
    <on-change xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-push">
      <dampening-period>100</dampening-period>
    </on-change>
  </establish-subscription>
</rpc>

The server will send a <push-update> notification right away for this filter:

<notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
  <eventTime>2020-10-11T20:20:21Z</eventTime>
  <push-update xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-push">
    <id>4</id>
    <datastore-contents>
      <netconf-state xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring">
        <backup-files xmlns="http://yumaworks.com/ns/yumaworks-system">
          <backup-file>
            <name>push1.xml</name>
            <backup-time>2020-08-29T20:10:23Z</backup-time>
          </backup-file>
          <backup-file>
            <name>push2.xml</name>
            <backup-time>2020-08-29T20:50:35Z</backup-time>
          </backup-file>
        </backup-files>
      </netconf-state>
    </datastore-contents>
  </push-update>
</notification>

If any backup file changes then the entire <backup-files> container is returned in the <push-change-update> notification:

Note that the operation will always be “replace” for a simulated operational on-change subscription.

<?xml version="1.0" encoding="UTF-8"?>
<notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">
  <eventTime>2020-10-11T20:25:35Z</eventTime>
  <push-change-update xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-push">
    <id>4</id>
    <datastore-changes>
      <yang-patch xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-push">
        <patch-id>0</patch-id>
        <comment>simop</comment>
        <edit>
          <edit-id>E1</edit-id>
          <operation>replace</operation>
          <target>/</target>
          <value>
            <data xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
              <netconf-state xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring">
                <backup-files xmlns="http://yumaworks.com/ns/yumaworks-system">
                  <backup-file>
                    <name>push1.xml</name>
                    <backup-time>2020-08-29T20:10:23Z</backup-time>
                  </backup-file>
                  <backup-file>
                    <name>push2.xml</name>
                    <backup-time>2020-08-29T20:50:35Z</backup-time>
                  </backup-file>
                  <backup-file>
                    <name>test-snap.xml</name>
                    <backup-time>2020-10-11T20:25:34Z</backup-time>
                  </backup-file>
                </backup-files>
              </netconf-state>
            </data>
          </value>
        </edit>
      </yang-patch>
    </datastore-changes>
  </push-change-update>
</notification>

Operational On-Change Subscriptions

An operational on-change subscription request that is granted will cause the specified data to be pushed when the subsystem responsible for pushing object updates sends a push-update to the main server. This mode is not yet implemented.