2  netconfd-pro User Guide

Image1

2.1  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 server Developers Guide for details on adding YANG module instrumentation code to the netconfd-pro server.

2.1.1  Features

The netconfd-pro server has the following features:

 

2.1.2  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:

 

2.1.3  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) 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=true parameter is used 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=true parameter is used 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.";

        }

 

 

2.1.4  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=true parameter is used 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=true parameter is used 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.";

        }

 

2.1.5  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 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:

 

 

netconfd-pro --version

 

netconfd-pro --help

netconfd-pro --help --brief

netconfd-pro --help --full

 

 

netconfd-pro --log-level=debug --log=~/mylog &

 

 

netconfd-pro

 

 

netconfd-pro --log=mylogfile

 

 

 

netconfd-pro --log=mylogfile –log-append

 

 

 

netconfd-proconfig=/opt/conf/netconfd-pro.conf

 

 

 

netconfd-profileloc-fhs=true

 

 

2.1.6  Starting SIL-SA Subsystems with sil-sa-app

If the server is built using the WITH_YCONTROL=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:

              Example: --library=foo  (selects libfoo_sa.so)

The SIL-SA libraries loaded depends on 2 factors:

 

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

 

 

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

 

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

2.1.9  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:

 

 

netconfd-pro

 

 

 

netconfd-pro --no-watcher

 

 

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

 

 

netconfd-pro --watcher-interval=10

 

 

2.1.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. Ypwatcher 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.

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.

 

2.1.11  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:

 

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

 

2.1.12  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

NMDA datastore meta-data

ietf-origin

NMDA <operational> origin meta-data

ietf-inet-types

standard data types

ietf-netconf-acm

standard NETCONF access control model

ietf-netconf-monitoring

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

ietf-netconf-nmda

NMDA <get-data> operation for NETCONF

ietf-netconf-notifications

standard NETCONF notifications for system events

ietf-netconf-partial-lock

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

ietf-netconf-with-defaults

<with-defaults> extension

ietf-subscribed-notifications

Dynamic Notification Subscriptions from RFC 8639

ietf-yang-types

standard data types

ietf-yang-library

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

ietf-yang-push

Subscriptions to YANG Datastores from RFC 8641

nc-notifications

standard replay notifications

netconfd-pro

Server CLI parameters

notifications

standard notification operations

openconfig-extensions

Many OC extensions supported (used in other modules)

yuma-ncx

Yuma NETCONF extensions

yuma-app-common

Common CLI parameters

yuma-types

Yuma common data types

yuma-mysession

Get and Set session-specific parameters

yuma-system

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

Get only if datastore changed since a specified timestamp

yumaworks-app-common

Common definitions used by yumapro modules

yumaworks-attrs

Extensions to add last-modified and etag attributes

yumaworks-config-change

Add edit data to the netconf-config-change notification

yumaworks-extensions

YANG extensions for meta-data data tagging

yumaworks-event-filter

Event filters to suppress generation of notifications for the specified events

yumaworks-event-stream

NETCONF Event stream configuration

yumaworks-getbulk

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

yumaworks-ids

Session type extensions for the standard monitoring module

yumaworks-system

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

yumaworks-sil-sa

Internal SIL-SA message definitions for subsystem module access callbacks

yumaworks-term-msg

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

yumaworks-ycontrol

Internal Ycontrol protocol for server to subsystem communication

 

 

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

ietf-restconf-monitoring

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

yuma-arp

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

yuma-proc

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

yuma-interfaces

Yuma interfaces table. Build variable: WITH_YUMA_INTERFACES=1

yumaworks-server

Allows server CLI parameters to be edited at run-time

 

2.1.13  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>

Notification replay has ended

nc-notifications

<notificationComplete>

Notification delivery has ended

ietf-yang-library

<yang-library-change>

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>

NETCONF session has started

ietf-netconf-notifications

<netconf-session-end>

NETCONF session has ended

ietf-netconf-notifications

<netconf-config-change>

<running> configuration has changed

ietf-netconf-notifications

<netconf-capability-change>

Server capabilities have changed

ietf-netconf-notifications

<netconf-confirmed-commit>

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

<nreplay-complete>

subscription replay completed

ietf-subscribed-notifications

<subscription-modified>

subscription configuration modified

ietf-subscribed-notifications

<subscription-resumed>

subscription resumed

ietf-subscribed-notifications

<subscription-suspended>

subscription suspended

ietf-subscribed-notifications

<subscription-terminated>

subscription terminated

ietf-yang-push

<push-update>

YANG Push Complete Update

ietf-yang-push

<push-change-update>

YANG Push Patch Update

 

2.1.14  Operation Summary

The following protocol operations are built into the netconfd-pro server:

 

Pre-loaded Operations

 

module

operation

description

yumaworks-system

<backup>

Backup the running configuration to a file.

Ietf-netconf

<cancel-commit>

Cancel a confirmed-commit operation.

yumaworks-system

<cancel-subscription>

Cancel a notification subscription.

ietf-netconf

<close-session>

Terminate the current session.

ietf-netconf

<commit>

Activate edits in <candidate>.

ietf-netconf

<copy-config>

Copy an entire configuration.

notifications

<create-subscription>

Start receiving notifications.

yumaworks-system

<delete-backup>

Delete a backup configuration file.

ietf-netconf

<delete-config>

Delete a configuration.

ietf-netconf

<discard-changes>

Discard edits in <candidate>.

ietf-netconf

<edit-config>

Edit the target configuration.

ietf-netconf

<get>

Retrieve <running> or state data.

ietf-netconf

<get-config>

Retrieve all or part of a configuration.

ietf-netconf-nmda

<get-data>

Retrieve data from an NMDA datastore

yumaworks-getbulk

<get-bulk>

Retrieve N list entries at a time

yumaworks-system

<get-ha-status>

Retrieve YP-HA status information

yumaworks-system

<get-module-tags>

Retrieve the installed module-tags

yuma-mysession

<get-my-session>

Retrieve session customization parameters.

ietf-netconf-monitoring

<get-schema>

Retrieve a YANG or YIN module definition file.

ietf-netconf

<kill-session>

Terminate a NETCONF session.

yuma-system

<load>

Load a YANG module and its SIL code [DEPRECATED]

yumaworks-system

<load>

Load a YANG module and its SIL code

yumaworks-system

<load-bundle>

Load a SIL bundle (SIL code + modules)

ietf-netconf

<lock>

Lock a database.

yuma-system

<no-op>

No operation. [DEPRECATED]

ietf-netconf-partial-lock

<partial-lock>

Lock part of the <running> database

ietf-netconf-partial-lock

<partial-unlock>

Unlock part of the <running> database

yumaworks-system

<refresh-backup-dir>

Refresh the backup-files monitoring data

yuma-system

<restart>

Restart the server. [DEPRECATED]

yumaworks-system

<restore>

Restore the <running> database from a backup

yuma-system

<set-log-level>

Set the logging verbosity level [DEPRECATED]

yumaworks-system

<set-log-level>

Set the logging verbosity level.

yuma-mysession

<set-my-session>

Set the session customization parameters.

yuma-system

<shutdown>

Shutdown the server [DEPRECATED]

yumaworks-system

<unload>

Unload a YANG module and its SIL code

yumaworks-system

<unload-bundle>

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

ietf-netconf

<unlock>

Unlock a database.

ietf-netconf

<validate>

Validate a database

 

 

2.1.15  Configuration Parameter List

The following configuration parameters are used by netconfd-pro.  Refer to the 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 conect 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 Call Home to invoke the SSH server

--callhome-subsys-command

Specifies the command used in Call Home 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. See the YumaPro User Manual for a general discussion of logging.

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

--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 the user name to be given super user privileges. If ‘superuser’ is configured in your netconfd-pro.conf file, then that value will be overriden 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-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 :notifications 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 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-tp-coap

Enable the YP-COAP protocol

--with-tp-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-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

 

2.1.16  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:

 

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:

If the server cannot save the CLI parameters upon restart or shutdown, then a warning log message will be generated. If the yumaworks-server 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).

 

2.1.17  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

}

 

 

 

2.1.18  Evaluation Version Restrictions

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

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

    }

  }

}

 

 

 

2.1.19  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'.

 

2.1.20  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

 

CLI Parameter

Modules Affected

Description

--hide-module

any

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

--with-support-save

yumaworks-support-save

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

--with-term-msg

yumaworks-term-msg

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

--with-yuma-system

yuma-system

yuma-app-common

yuma-types

yuma-ncx

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

--with-yuma-time-filter

yuma-time-filter

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

--with-yumaworks-callhome

yumaworks-callhome

Run-time configuration or NETCONF CallHome connections.

--with-yumaworks-config-change

yumaworks-config-change

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

--with-yumaworks-event-filter

yumaworks-event-filter

yuma-types

yuma-ncx

<event-filters> container to drop specific event types

--with-yumaworks-event-stream

yumaworks-event-stream

yuma-ncx

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

--with-yumaworks-getbulk

yumaworks-getbulk

yumaworks-restconf

<get-bulk> operation to retrieve YANG list entries

--with-yumaworks-ids

yumaworks-ids

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

--with-yumaworks-system

yumaworks-system

yuma-app-common

yuma-ncx

yuma-types

yumaworks-app-common

yumaworks-restconf

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

--with-yumaworks-templates

yumaworks-templates

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

 

 

 

2.1.21  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:

 

Configuration edits by all clients are affected by this lock.

 

2.1.22  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:

 

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

2.2.1  :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.

2.2.2  :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.

2.2.3  :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 the superuser account can use the <delete-config> operation on the <candidate> configuration.

2.2.4  :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.

2.2.5  :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.

2.2.6  :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’.

2.2.7  :netconf-monitoring

The :netconf-monitoring capability indicates that the /ietf-netconf-monitoring data sub-tree is supported.

The netconfd-pro server supports all of the tables in this module, except partial-locking, because the :partial-lock capability is not supported at this time.

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.

2.2.8  :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 first notification in the log will be for the <sysStartup> event.

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

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

2.2.9  :partial-lock

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

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:

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.

2.2.10  :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.

2.2.11  :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.

2.2.12  :startup

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

By default, this capability is not supported.

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:

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

2.2.13  :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:

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:

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.

2.2.14  :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:

Schemes:

 

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 $$datapth system variable is used to find the file names specified in the <url> URI string.

Example:

 

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

 

2.2.15  :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.

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.

2.2.16  :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'.

2.2.17  :xpath

The :xpath capability indicates that XPath filtering is supported for the <get> and <get-config> operations.

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

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:

2.2.18  :yang-library

The :yang-library capability indicates that  the server supports YANG Library mechanism for announcing conformance information.
 
The server announces the modules it implements by implementing the YANG module "ietf-yang-library"
and listing all implemented modules in the "/modules-state/module" list.

 

The server also advertises the following capability in the <hello> message:

 

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

 

 
The parameter "revision" has the same value as the revision date of the "ietf-yang-library" module implemented by the server.
 
The parameter "module-set-id" has the same value as the leaf "/modules-state/module-set-id" from "ietf-yang-library".
If the value of this leaf changes, the server also generates a "yang-library-change" 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.
 
 

2.3  Databases

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

graphics5

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

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:

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

 

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

 

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

2.3.4  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 the superuser account is allowed to do this, by default.

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

2.4.1  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 program when it is called by sshd.

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

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

2.4.3  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 that 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>

 

 

2.4.4  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 will 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.  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.  If there are no common versions found, the session will be dropped.  By default, the server will enable both protocol versions.

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

Client <hello>

Server <hello>

Outcome

[ 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>

 

 

2.4.5  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 <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:

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.

 

2.4.6  Session Termination

A session can terminate for several reasons:

When a session terminates, the server does the following:

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

2.5.1  <error-severity> Element

The <error-severity> field will always be set to 'error'.  There are no warnings generated by netconfd-pro.

2.5.2  <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

operation-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

 

2.5.3  <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 occured, 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)

 

2.5.4  <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>

 

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

 

2.5.6  <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

 

2.5.7  Dynamic Error Messages

Dynamic error messages can include content from the configuration data, such as an interface name, or oither 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 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";

          }

        }

      }

    }

 

}

 

 

2.5.8  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";

          }

 

      }

    }

 

}

 

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

where
<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”

 

 

2.5.10  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 used by Google Translate:

 

 

https://cloud.google.com/translate/docs/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

}

 

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

 

instance-required

 

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:

 

<?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>

 

 

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

 

missing-choice error

 

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:

 

<?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>

 

 

 

 

2.5.13  No-Matches Error Example

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

 

No Matches

 

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:

 

<?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>

 

 

 

2.5.14  not-in-range Error Example

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

 

not-in-range

 

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:

 

<?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>

 

 

2.6  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,

2.6.1  <backup>

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

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 the superuser account is allowed to invoke this operation.

 

<backup> operation

 

Min parameters:

1

Max parameters:

2

Return type:

status

YANG file:

yumaworks-system.yang

Capabilities needed:

none

 

Mandatory Parameters:

Optional Parameters:

Returns:

Possible Operation Errors:

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>

 

 

 

2.6.2  <cancel-commit>

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

A <sysSessionEnd> notification with a <terminationReason> field set to 'closed' will be generated when this operation is invoked.

<cancel-commit> operation

 

Min parameters:

0

Max parameters:

1

Return type:

status

YANG file:

ietf-netconf.yang

Capabilities needed:

base:1.1

 

Mandatory Parameters:

Optional Parameters:

Returns:

Possible Operation 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="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>

 

 

2.6.3  <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/>.

 

<cancel-subscription> operation

 

Min parameters:

0

Max parameters:

0

Return type:

status

YANG file:

ietf-netconf.yang

Capabilities needed:

:notification, :interleave

 

Mandatory Parameters:

Optional Parameters:

Returns:

Possible Operation Errors:

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>

 

 

2.6.4  <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 <sysSessionEnd> notification with a <terminationReason> field set to 'closed' will be generated when this operation is invoked.

 

<close-session> operation

 

Min parameters:

0

Max parameters:

0

Return type:

status

YANG file:

yuma-netconf.yang

Capabilities needed:

none

 

Mandatory Parameters:

Optional Parameters:

Returns:

Possible Operation 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="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>

 

 

2.6.5  <commit>

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

The 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:

<commit> operation

 

Min parameters:

0

Max parameters:

4

Return type:

status

YANG file:

yuma-netconf.yang

Capabilities needed:

:candidate
:confirmed-commit

 

Mandatory Parameters:

Optional Parameters:

Returns:

Possible Operation 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="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>

 

2.6.6  <copy-config>

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

This is a destructive 'stop-on-error' operation.  It is not like <edit-config> or <commit>, which can be used in an 'all-or-nothing' manner.

A failed <copy-config> can leave the target of the operation in an unstable, invalid state.  This operation should be used with caution.

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.

 

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

 

<copy-config> operation

 

Min parameters:

2

Max parameters:

3

Return type:

status

YANG file:

yuma-netconf.yang

Capabilities needed:

none

Capabilities optional:

:candidate
:writable-running
:startup

:url

 

Mandatory Parameters:

Optional Parameters:

Returns:

Possible Operation 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="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>

 

 

2.6.7  <create-subscription>

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

The mandatory 'NETCONF' stream is supported by netconfd-pro. In addition, the --event-stream CLI parameter can be used to add additional event streams. The name used in the CLI parameter will also be the name used in the <create-subscription> operation.

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.

The :notification and :interleave capabilities are always supported by netconfd-pro.

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.

<create-subscription> operation

 

Min parameters:

0

Max parameters:

4

Return type:

status

YANG file:

notifications.yang

Capabilities needed:

:notification

Capabilities optional:

:interleave

 

Mandatory Parameters:

Optional Parameters:

Returns:

Possible Operation 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="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>

 

2.6.8  <delete-backup>

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

The agt_yumaworks_system boolean flag must be set to true in the agt_profile struct.

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

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

 

<delete-backup> operation

 

Min parameters:

1

Max parameters:

1

Return type:

status

YANG file:

yumaworks-system.yang

Capabilities needed:

none

 

Mandatory Parameters:

Optional Parameters:

Returns:

Possible Operation Errors:

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>

 

2.6.9  <delete-config>

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

By default, only the superuser account is 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

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

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

 

<delete-config> operation

 

Min parameters:

1

Max parameters:

1

Return type:

status

YANG file:

yuma-netconf.yang

Capabilities needed:

:startup

 

Mandatory Parameters:

Optional Parameters:

Returns:

Possible Operation 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="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>

 

 

 

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

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

 

       +---x delete-subscription

    |  +---w input

    |     +---w id    subscription-id

 

 

<delete-subscription> operation

 

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:

Optional Parameters:

Returns:

Possible Operation Errors:

 

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>

 

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

 

<discard-changes> operation

 

Min parameters:

0

Max parameters:

0

Return type:

status

YANG file:

yuma-netconf.yang

Capabilities needed:

:candidate

 

Mandatory Parameters:

Optional Parameters:

Returns:

Possible Operation 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="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>

 

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

If the nc:operation attribute is used, then it 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.

 

<edit-config> operation

 

Min parameters:

2

Max parameters:

5

Return type:

status

YANG file:

yuma-netconf.yang

Capabilities needed:

:candidate or :writable-running

Capabilities optional:

:rollback-on-error
:validate

 

Mandatory Parameters:

Optional Parameters:

Returns:

Possible Operation 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="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>

 

 

2.6.13  <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 option and the “yang-push” bundle is loaded.

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

 

 

    +---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}?

    |     +--ro rsn:uri?                      inet:uri

 

 

 

<establish-subscription> operation

 

Min parameters:

2

Max parameters:

 

Return type:

data (id)

YANG file:

ietf-subscribed-notifications.yang

ietf-yang-push.yang

Capabilities needed:

none (bundle yang-push required)

Capabilities optional:

none

 

 

Event Stream Subscription

 

Mandatory Parameters:

Optional Parameters:

 

Datastore Subscription

 

Mandatory Parameters:

Optional Parameters:

 

 

Returns:

 

Possible Operation Errors:

 

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>

2.6.14  <get>

The <get> operation is used to retrieve data from the <running> configuration, or non-configuration data available on the server.

The simple command (<get/>) will cause all available data to be retrieved from the server.  This may be generate a large response and waste resources.

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.

 

<get> operation

 

Min parameters:

0

Max parameters:

6

Return type:

data

YANG file:

yuma-netconf.yang

Capabilities needed:

none

Capabilities optional:

:candidate
:startup

:with-defaults

 

Mandatory Parameters:

Optional Parameters:

 

Returns:

Possible Operation Errors:

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>

 

2.6.15  <get-bulk>

The <get-bulk> operation is used to retrieve data any type of YANG data node from the NETCONF server.

This operation requires that WITH_RESTCONF=1 is used to build the server image, even though this is a NETCONF operation. This is due to the large amount of RESTCONF code used to implement this feature. (This is the default is all binary packages).

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.

 

get-bulk> operation

 

Min parameters:

1

Max parameters:

8

Return type:

data

YANG file:

yumaworks-getbulk.yang

Capabilities needed:

none (WITH_RESTCONF=1)

Capabilities optional:

:candidate
:startup

:with-defaults

 

Mandatory Parameters:

Optional Parameters:

 

 

Returns:

Possible Operation Errors:

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>

 

 

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

 

<get-config> operation

 

Min parameters:

1

Max parameters:

7

Return type:

data

YANG file:

yuma-netconf.yang

Capabilities needed:

none

Capabilities optional:

:candidate
:startup

:with-defaults

 

Mandatory Parameters:

Optional Parameters:

 

Returns:

Possible Operation Errors:

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>

 

 

 

 

 

 

 

 

 

2.6.17  <get-data>

The <get-data> operation is used to retrieve data from a NMDA datastore.

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.

 

<get-data> operation

 

Min parameters:

1

Max parameters:

7

Return type:

data

YANG file:

ietf-netconf-nmda.yang

Capabilities needed:

none

Capabilities optional:

:candidate
:startup

:with-defaults

CLI Parameters Needed

--with-nmda=true

 

Mandatory Parameters:

 

Optional Parameters:

 

 

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>

 

 

 

 

2.6.18 <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 of a server's

 

 

     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:

 

The yp-ha-app can be used to send HA controller commands to a netconfd-pro server. In order to change the active-server used by an HA standby server, the --go-none command must be used as follows:

 

 

> yp-ha-app --go-standby=ha1

> yp-ha-app --go-none

> yp-ha-app --go-standby=ha2

 

 

 

HA Status Grouping

 

Object Name

Type

Description

ha-built

boolean

Indicates the YP_HA code is built into the server image

ha-role-state

HaRoleState

The current HA role state for this server

ha-role-state-time

data-and-time

The timestamp when the ha-role-state changes

ha-enabled

boolean

Indicates the YP-HA feature is enabled

ha-sil-standby

boolean

Contains the --ha-sil-standby CLI parameter

ha-server

string

Leaf-list of ha-server CLI parameters

ha-server-key

string

Contains the ha-server-key CLI parameter

ha-initial-active

string

Contains the --ha-initial-active CLI parameter

socket-address

ip-address

Contains the --socket-address CLI parameter

socket-port

port-number

Contains the --socket-port CLI parameter

server-id

string

Contains the --server-id CLI parameter

config-id

uint64

Contains the config ID Etag of the <running> datastore

config-stamp

date-and-time

The timestamp when the config-id last changed

config-updates

counter64

The number of successful config updates sent or received.

config-failures

counter64

The number of unsuccessful config updates sent or received.

active-server

string

The HA active server according to this server

last-error-time

date-and-time

The timestamp when the last-error-msg changed

last-error-msg

string

The error message from the last failure

 

 

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-role-state-time {

        type yang:date-and-time;

        description

          "The timestamp when the ha-role-state object last changed value.";

      }

 

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

       }

 

       leaf config-updates {

         type yang:counter64;

         description

           "Number of config updates that this server has successfully

            processed since the current role (active or standby) was set.

            Each time the server resets or changes HA roles this counter

            will be reset.";

       }

 

       leaf config-failures {

         type yang:counter64;

         description

           "Number of config updates that this server has unsuccessfully

            processed since the current role (active or standby) was set.

            Each time the server resets or changes HA roles this counter

            will be reset.";

       }

 

       leaf active-server {

         type yt:NcxName;

         description

          "If this server is using the HA standby role, then the

           HA active server will be identified by this object.";

       }

 

       leaf last-error-time {

         type yang:date-and-time;

         description

          "The timestamp when the last error happened.

 

           For HA-Active servers, this object represents the time

           of the last config replication error, if any.

           This object is not cleared if a subsequent config

           update is successful.

 

           For HA-Standby servers, this object represents the time

           of the last failure to connect to the HA Active server.

           This only applies to the case where the server is

           reachable, but it is not the HA Active server, or not

           ready to accept datastore replication requests.

 

           If the HA Active server is unreachable then the YControl

           layer will attempt reconnections. These reconnections will

           not affect this timestamp.

 

           This object is cleared if the HA Standby role is established

           successfully. It is only present if errors have occurred

           on this HA server. Replication errors are not reported.";

       }

 

       leaf last-error-msg {

         type string;

         description

           "The error message for the last HA error code.

 

           For HA-Active servers, this object represents the error string

           of the last config replication error, if any.

           This object is not cleared if a subsequent config

           update is successful.

 

           For HA-Standby servers, this object represents the error string

           of the last failure to connect to the HA Active server.

           This only applies to the case where the server is

           reachable, but it is not the HA Active server, or not

           ready to accept datastore replication requests.

 

           This object is cleared if the HA Standby role is established

           successfully. It is only present if errors have occurred

           on this HA server. Replication errors are not reported.";

       }

 

    }

 

 

 

 

 

 

<get-ha-status> operation

 

Min parameters:

0

Max parameters:

0

Return type:

data

YANG file:

yumaworks-system

Capabilities needed:

none

 

Mandatory Parameters:

Optional Parameters:

Returns:

 

 

Possible Operation Errors:

 

<get-ha-status> Examples

 

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-role-state-time>2021-10-14T02:52:24Z</ha-role-state-time>

    <ha-enabled>true</ha-enabled>

    <ha-sil-standby>false</ha-sil-standby>

    <ha-server>host@192.168.0.174</ha-server>

    <ha-server>vm1@192.168.0.79</ha-server>

    <ha-server>vm2@192.168.0.90</ha-server>

    <ha-server-key>ha-pool1</ha-server-key>

    <socket-type>tcp</socket-type>

    <socket-address>0.0.0.0</socket-address>

    <socket-port>8088</socket-port>

    <server-id>host</server-id>

    <config-updates>0</config-updates>

    <config-failures>0</config-failures>

  </ha-status>

</rpc-reply>

 

 

Example Reply for a server just entered 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-role-state-time>2021-10-14T02:56:06Z</ha-role-state-time>

    <ha-enabled>true</ha-enabled>

    <ha-sil-standby>false</ha-sil-standby>

    <ha-server>host@192.168.0.174</ha-server>

    <ha-server>vm1@192.168.0.79</ha-server>

    <ha-server>vm2@192.168.0.90</ha-server>

    <ha-server-key>ha-pool1</ha-server-key>

    <socket-type>tcp</socket-type>

    <socket-address>0.0.0.0</socket-address>

    <socket-port>8088</socket-port>

    <server-id>host</server-id>

    <config-id>2714</config-id>

    <config-stamp>2021-10-14T02:56:06Z</config-stamp>

    <config-updates>0</config-updates>

    <config-failures>0</config-failures>

    <active-server>host</active-server>

  </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-role-state-time>2021-10-14T02:57:47Z</ha-role-state-time>

    <ha-enabled>true</ha-enabled>

    <ha-sil-standby>false</ha-sil-standby>

    <ha-server>host@192.168.0.174</ha-server>

    <ha-server>vm1@192.168.0.79</ha-server>

    <ha-server>vm2@192.168.0.90</ha-server>

    <ha-server-key>ha-pool1</ha-server-key>

    <socket-type>tcp</socket-type>

    <socket-address>0.0.0.0</socket-address>

    <socket-port>8088</socket-port>

    <server-id>vm1</server-id>

    <config-updates>1</config-updates>

    <config-failures>0</config-failures>

    <active-server>host</active-server>

  </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 esrver 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-role-state-time>2021-10-14T03:01:20Z</ha-role-state-time>

    <ha-enabled>true</ha-enabled>

    <ha-sil-standby>false</ha-sil-standby>

    <ha-server>host@192.168.0.174</ha-server>

    <ha-server>vm1@192.168.0.79</ha-server>

    <ha-server>vm2@192.168.0.90</ha-server>

    <ha-server-key>ha-pool1</ha-server-key>

    <socket-type>tcp</socket-type>

    <socket-address>0.0.0.0</socket-address>

    <socket-port>8088</socket-port>

    <server-id>vm1</server-id>

    <config-updates>1</config-updates>

    <config-failures>0</config-failures>

    <active-server>host</active-server>

    <last-error-time>2021-10-14T03:01:35Z</last-error-time>

    <last-error-msg>not found</last-error-msg>

  </ha-status>

</rpc-reply>

 

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

 

 

    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

 

Min parameters:

0

Max parameters:

0

Return type:

data

YANG file:

yumaworks-system

Capabilities needed:

none

 

Mandatory Parameters:

Optional Parameters:

Returns:

 

Possible Operation Errors:

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>

 

 

2.6.20  <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 must be enabled in the server configuration file or CLI parameters for this operation to be available.

 

<get-my-session> operation

 

Min parameters:

0

Max parameters:

0

Return type:

data

YANG file:

yuma-mysession.yang

Capabilities needed:

none

 

Mandatory Parameters:

Optional Parameters:

Returns:

 

Possible Operation 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="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>

 

 

 

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

 

<get-schema> operation

 

Min parameters:

3

Max parameters:

3

Return type:

data

YANG file:

yuma-netconf.yang

Capabilities needed:

:schema-retrieval

 

Mandatory Parameters:

Returns:

Possible Operation 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="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>

 

 

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

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

   }

 

 

<get-support-save> operation

 

Min parameters:

0

Max parameters:

0

Return type:

data

YANG file:

yumaworks-support-save.yang

Capabilities needed:

None

 

Returns:

Possible Operation Errors:

 

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>

 

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

 

<kill-session> operation

 

Min parameters:

1

Max parameters:

1

Return type:

status

YANG file:

yuma-netconf.yang

Capabilities needed:

none

 

Mandatory Parameters:

Optional Parameters:

Returns:

Possible Operation 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="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>

 

 

 

 

2.6.24  <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 option and the “yang-push” bundle is loaded.

 

       +---x kill-subscription

    |  +---w input

    |     +---w id    subscription-id

 

 

<kill-subscription> operation

 

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:

Optional Parameters:

Returns:

Possible Operation Errors:

 

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>

 

2.6.25  <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 the super user account is allowed to use it.

This operation appears in 2 YANG modules:

 

<load> operation

 

Min parameters:

1

Max parameters:

3

Return type:

data

YANG file:

yuma-system.yang

yumaworks-system.yang

Capabilities needed:

none

 

Mandatory Parameters:

Optional Parameters:

Returns:

Possible Operation 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>

 

2.6.26  <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 the super user account is allowed to use it.

 

<load> operation

 

Min parameters:

1

Max parameters:

3

Return type:

status

YANG file:

yumaworks-system.yang

Capabilities needed:

none

 

Mandatory Parameters:

Optional Parameters:

Returns:

Possible Operation Errors:

 

Example Request:

 

 

<?xml version="1.0" encoding="UTF-8"?>

<rpc message-id="166" trace-id="2"

 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>

 

 

 

 

2.6.27  <modify-subscription>

The <modify-subscription> operation is used to modify 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 option and the “yang-push” bundle is loaded.

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

 

Usage Restrictions:

 

    +---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

 

Min parameters:

2

Max parameters:

 

Return type:

status

YANG file:

ietf-subscribed-notifications.yang

ietf-yang-push.yang

Capabilities needed:

none (bundle yang-push required)

Capabilities optional:

none

 

 

Event Stream Subscription

 

Mandatory Parameters:

 

Optional Parameters:

Datastore Subscription

 

Mandatory Parameters:

 

Optional Parameters:

 

 

Returns:

 

 

Possible Operation Errors:

 

TBD: EXAMPLES

 

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

<lock> operation

 

Min parameters:

1

Max parameters:

1

Return type:

status

YANG file:

yuma-netconf.yang

Capabilities needed:

none

Capabilities optional:

:candidate
:startup

 

Mandatory Parameters:

Optional Parameters:

Returns:

Possible Operation 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="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>

 

 

2.6.29  <no-op>

The <no-op> operation is used for debugging and performance testing purposes.

This operation does not do anything.  It simply returns <ok/>, unless any parameters are provided.

 

<no-op> operation

 

Min parameters:

0

Max parameters:

0

Return type:

status

YANG file:

yuma-system.yang

Capabilities needed:

none

 

Mandatory Parameters:

Optional Parameters:

Returns:

Possible Operation 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="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>

 

 

2.6.30  <partial-lock>

The <partial-lock> operation is used to lock part of the <running> database.

Refer to RFC 5717 or the ietf-netconf-partial-lock.yang module for details on this operation.

 

<partial-lock> operation

 

Min parameters:

1

Max parameters:

1

Return type:

data

YANG file:

ietf-netconf-partial-lock.yang

Capabilities needed:

:partial-lock

 

Mandatory Parameters:

Optional Parameters:

Returns:

Possible Operation 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="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>

 

 

 

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

Refer to RFC 5717 or the ietf-netconf-partial-lock.yang module for details on this operation.

 

<partial-unlock> operation

 

Min parameters:

1

Max parameters:

1

Return type:

status

YANG file:

ietf-netconf-partial-lock.yang

Capabilities needed:

:partial-lock

 

Mandatory Parameters:

Optional Parameters:

Returns:

Possible Operation 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="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>

 

 

 

 

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

 

<refresh-backup-dir> operation

 

Min parameters:

0

Max parameters:

0

Return type:

ok

YANG file:

yumaworks-system.yang

Capabilities needed:

none

 

Mandatory Parameters:

Optional Parameters:

Returns:

Possible Operation Errors:

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>

 

 

2.6.33  <restart>

The <restart> operation is used to restart the netconfd-pro server.

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

If permission is granted, then the current NETCONF session will dropped, during the server restart.

 

<restart> operation

 

Min parameters:

0

Max parameters:

0

Return type:

none

YANG file:

yuma-system.yang

Capabilities needed:

none

 

Mandatory Parameters:

Optional Parameters:

Returns:

Possible Operation 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="63">

   <nd:restart xmlns:nd="http://netconfcentral.org/ns/netconfd"/>

</nc:rpc>

 

 

Example Reply: (none – server may send <ok/> before system shuts down.)

 

2.6.34  <restore>

The <restore> operation is used to load the running datgabase from a named configuration backup file on the server.

Only local files are supported.

The agt_yumaworks_system boolean flag must be set to true in the agt_profile struct.

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

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

<backup> operation

 

Min parameters:

1

Max parameters:

1

Return type:

status

YANG file:

yumaworks-system.yang

Capabilities needed:

none

 

Mandatory Parameters:

Optional Parameters:

Returns:

Possible Operation Errors:

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>

 

 

2.6.35  <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 option and the “yang-push” bundle is loaded.

 

    +---x resync-subscription {on-change}?

       +---w input

          +---w id    sn:subscription-id

 

<resync-subscription> operation

 

Min parameters:

1

Max parameters:

1

Return type:

status

YANG file:

ietf-subscribed-notifications.yang

ietf-yang-push.yang

Capabilities needed:

none (bundle yang-push required)

Capabilities optional:

none

 

Mandatory Parameters:

Optional Parameters:

Returns:

Possible Operation Errors:

 

Example Request:

 

 

Example Reply:

 

 

 

2.6.36   <set-log-level>

The <set-log-level> operation is used to configure the server logging verbosity level.

Only the designated superuser user can invoke this operation by default.

This operation is defined in two modules. Use the version in yumaworks-system.yang. The version is yuma-system.yang is deprecated.

 

<set-log-level> operation

 

Min parameters:

1

Max parameters:

1

Return type:

status

YANG file:

yuma-system.yang

yumaworks-system.yang

Capabilities needed:

none

 

 

Mandatory Parameters:

Optional Parameters:

Returns:

Possible Operation Errors:

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>

 

 

 

2.6.37  <set-my-session>

The <set-my-session> operation is used to configure the 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 must be enabled in the server configuration file or CLI parameters for this operation to be available.

 

<set-my-session> operation

 

Min parameters:

0

Max parameters:

4

Return type:

status

YANG file:

yuma-mysession.yang

Capabilities needed:

none

 

Mandatory Parameters:

Optional Parameters:

Returns:

Possible Operation 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="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>

 

 

2.6.38  <shutdown>

The <shutdown> operation is used to shut down the netconfd-pro server.

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

If permission is granted, then the current NETCONF session will dropped, during the server shutdown.

 

<shutdown> operation

 

Min parameters:

0

Max parameters:

0

Return type:

none

YANG file:

yuma-system.yang

Capabilities needed:

none

 

Mandatory Parameters:

Optional Parameters:

Returns:

Possible Operation 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="1">

   <nd:shutdown xmlns:nd="http://netconfcentral.org/ns/netconfd"/>

</nc:rpc>

 

 

Example Reply:

 

[no reply will be sent; session will be dropped instead.]

 

2.6.39  <unload>

The <unload> operation is used to remove a YANG module from the system:

 

The following conditions must be true for the unload to be attempted by the server:

 

             removed at run-time.

             for the entire unload operation.

 

If all these conditions are met then the server will attempt to unload the specified module.  The unload operation can fail for various reasons:

 

<unload> operation

 

Min parameters:

1

Max parameters:

2

Return type:

status

YANG file:

yumaworks-system.yang

Capabilities needed:

none

 

Mandatory Parameters:

Optional Parameters:

Returns:

Possible Operation Errors:

Example Request:

 

 

<?xml version="1.0" encoding="UTF-8"?>

<rpc message-id="66" trace-id="2"

 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>

 

 

2.6.40  <unload-bundle>

The <unload-bundle> operation is used to remove a SIL bundle (multiple YANG modules at once) from the system:

 

The following conditions must be true for the unload-bundle to be attempted by the server:

 

             removed at run-time.

             for the entire unload-bundle operation.

 

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:

 

<unload-bundle> operation

 

Min parameters:

1

Max parameters:

2

Return type:

status

YANG file:

yumaworks-system.yang

Capabilities needed:

none

 

Mandatory Parameters:

Optional Parameters:

Returns:

Possible Operation Errors:

Example Request::

 

 

<?xml version="1.0" encoding="UTF-8"?>

<rpc message-id="69" trace-id="2"

 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>

 

 

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

 

<unlock> operation

 

Min parameters:

1

Max parameters:

1

Return type:

status

YANG file:

yuma-netconf.yang

Capabilities needed:

none

Capabilities optional:

:candidate
:startup

 

Mandatory Parameters:

Optional Parameters:

Returns:

Possible Operation 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="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>

 

 

2.6.42  <validate>

The <validate> operation is used to perform the <commit> validation tests against a database or some in-line configuration data.

<validate> operation

 

Min parameters:

1

Max parameters:

1

Return type:

status

YANG file:

yuma-netconf.yang

Capabilities needed:

:validate

Capabilities optional:

:candidate
:startup

 

Mandatory Parameters:

Optional Parameters:

Returns:

Possible Operation 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>

 

 

 

 

2.7  Access Control

The netconfd-pro access control data model is defined in ietf-netcon-acm.yang.

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, the super user 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 section on access control modes for more details.

graphics11

Normally, some configuration is required:

The entire /nacm subtree is tagged as nacm:default-deny-all.  By default, only the super-user 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.

2.7.1  NACM Module Structure

The /nacm subtree is described below:

 

module: ietf-netconf-acm

  +--rw nacm

     +--rw enable-nacm?              boolean

     +--rw read-default?             action-type

     +--rw write-default?            action-type

     +--rw exec-default?             action-type

     +--rw enable-external-groups?   boolean

     +--ro denied-operations         yang:zero-based-counter32

     +--ro denied-data-writes        yang:zero-based-counter32

     +--ro denied-notifications      yang:zero-based-counter32

     +--rw groups

     |  +--rw group* [name]

     |     +--rw name         group-name-type

     |     +--rw user-name*   user-name-type

     +--rw rule-list* [name]

        +--rw name     string

        +--rw group*   union

        +--rw rule* [name]

           +--rw name                       string

           +--rw module-name?               union

           +--rw (rule-type)?

           |  +--:(protocol-operation)

           |  |  +--rw rpc-name?            union

           |  +--:(notification)

           |  |  +--rw notification-name?   union

           |  +--:(data-node)

           |     +--rw path                 node-instance-identifier

           +--rw access-operations?         union

           +--rw action                     action-type

           +--rw comment?                   string

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

 

2.7.3  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>

 

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

 

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

 

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

 

2.7.7  Default Enforcement Behavior

Each access type has a default behavior if no rule is found and no special YANG extensions apply:

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.

2.7.8  Access Control Algorithm

The access control enforcement procedures are defined in RFC 6536, section 3.4

 

2.7.9  Passwords and crypt-hash

The YANG extension “ncx:password” can be used in a YANG module 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” module.

Objects that are type “crypt-hash” will be processed by the server according to the following typedef:

 

 

  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.

 

2.7.10  Using Module Tags with NACM

There is an 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 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

          }

        }

      }

    }

  }

}

 

 

2.8  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 programmatic interface.

The RESTCONF Protocol is defined in RFC 8040.

The YANG Patch media type used by RESTCONF is defined in RFC 8072.

If the yumapro package is installed and the HTTP/REST protocol is used, then a WEB server is required.  It must support the FastCGI API, which is used by the restconf programs for REST access to the netconfd-pro server. Please refer to yumapro-installation-guide section 3.3.2 for installation instructions.

NOTE YANG-API users:

yang-api.conf virtual host configuration file has changed to support SSE and root resource discovery. Refer to installation-guide section 3.3.2.

Netconfd-pro server provides two HTTP-based programs, yang-api and restconf, that provides a programmatic interface for accessing data defined in YANG, using the datastores defined in NETCONF. These programs are FastCGI thin clients that connect to the netconfd-pro server to process HTTP requests.

They are installed by default at /var/www/yang-api.

2.8.1  Features

The restconf program has the following features: