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

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.

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.

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.

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.

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

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.

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.

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.

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=/etc/yumapro/netconfd-pro.conf

 

 

2.1.6  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 yuma-nacm.yang access control rules must be configured to allow any user except the 'superuser' account to invoke this operation.

 

 

 

 

 

2.1.7  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

Shutdown the server.

SEGUSER1

10

Reload the server

SIGPIPE

13

Handle I/O connection error.

SIGTERM

15

Shutdown the server.

 

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.8  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.9  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.10  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.

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

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

 

 

 

 

Pre-loaded YANG Modules

 

module

description

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

standard data types

ietf-yang-library

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

yuma-nacm

NETCONF Access Control Model

nc-notifications

standard replay notifications

netconfd-pro

Server CLI parameters

notifications

standard notification operations

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

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

YANG extensions for meta-data data tagging

yumaworks-event-filter

Event filters to suppress generation of notifications for the specified events

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

 

2.1.12  Notification Summary

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

 

Pre-loaded Notifications

 

module

event type

description

ietf-netconf-notifications

<netconf-session-start>

Standard version of <sysSessionStart> event

ietf-netconf-notifications

<netconf-session-end>

Standard version of <sysSessionEnd> event

ietf-netconf-notifications

<netconf-config-change>

Standard version of <sysConfigChange> event

ietf-netconf-notifications

<netconf-capability-change>

Standard version of <sysCapabilityChange> event

ietf-netconf-notifications

<netconf-confirmed-commit>

Standard version of <sysConfirmedCommit> event

nc-notifications

<replayComplete>

Notification replay has ended

nc-notifications

<notificationComplete>

Notification delivery has ended

yuma-system

<sysStartup>

server startup event

yuma-system

<sysSessionStart>

NETCONF session started

yuma-system

<sysSessionEnd>

NETCONF session ended

yuma-system

<sysConfigChange>

<running> configuration has changed

yuma-system

<sysCapabilityChange>

server capability added or deleted

yuma-system

<sysConfirmedCommit>

confirmed-commit procedure event

ietf-yang-library

<yang-library-change>

Set of modules or submodules in the YANG Library has changed

 

 

 

 

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

yumaworks-getbulk

<get-bulk>

Retrieve N list entries at a time

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.

netconfd-pro

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

ietf-netconf-partial-lock

<partial-lock>

Lock part of the <running> database

ietf-netconf-partial-lock

<partial-unlock>

Unlock part of the <running> database

yuma-system

<restart>

Restart the server.

yumaworks-system

<restore>

Restore the <running> database from a backup

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

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

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

Minimum debug level to generate audit log messages

--autodelete-pdu-error

Treat false when-stmts in the edit PDU as errors

--create-empty-npcontainers

Specifies that empty NP containers should be created or not

--bundle

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

--config

Specifies the configuration file to use for parameters

--datapath

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

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

--eventlog-size

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

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

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

--home

Overrides the $HOME environment variable

--idle-timeout

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

--indent

Specifies the indent count to use when writing data

--library-mode

Run the server in YANG library mode

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

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

--max-sessions

Specifies the maximum number of concurrent sessions allowed

--modpath

Sets the module search path

--module

Specifies  one or more YANG modules  to load upon startup

--netconf-capability

Specifies a NETCONF capability URI to add to the server

--no-config

If present, ignore the default configuration file

--no-startup

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

--no-nvstore

Disable internal NV-load and NV-store operations

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

--restconf-capability

Specifies a RESTCONF capability URI to add to the server

--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 or continue 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-missing-error

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

--sil-skip-load

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

--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 or continue if the startup configuration contains any recoverable errors (the bad configuration data can be removed)

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

--usexmlorder

Forces strict YANG XML ordering to be enforced

--version

Prints the program version and exits

--warn-idlen

Controls how identifier lengths are checked

--warn-linelen

Controls how line lengths are checked

--warn-off

Suppresses the specified warning number

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

Enable or disable the :config-id capability URI

--with-netconf

Enable or disable the NETCONF protocol

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

Enable or disable the <startup> database

--with-url

Enable or disable the :url capability

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

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

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.

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.

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.

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:

Only the 'file' scheme is supported at this time.

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.

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:

 

graphics5

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.

In order for access control to work properly, the sshd user name must also conform to the NacmUserName type definition:

 

 

 

typedef NacmUserName {

   description "General Purpose User Name string.";

   type string {

length "1..63";

pattern '[a-z,A-Z][a-z,A-Z,0-9]{0,62}';

   }

}

 

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:

 

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

         urn:ietf:params:netconf:capability:candidate:1.0

      </nc:capability>

      <nc:capability>

         urn:ietf:params:netconf:capability:confirmed-commit:1.0

      </nc:capability>

      <nc:capability>

         urn:ietf:params:netconf:capability:rollback-on-error:1.0

      </nc:capability>

      <nc:capability>

         urn:ietf:params:netconf:capability:validate:1.0

      </nc:capability>

      <nc:capability>

         urn:ietf:params:netconf:capability:xpath:1.0

      </nc:capability>

      <nc:capability>

         urn:ietf:params:netconf:capability:notification:1.0

      </nc:capability>

      <nc:capability>

         urn:ietf:params:netconf:capability:interleave:1.0

      </nc:capability>

      <nc:capability>

         urn:ietf:params:netconf:capability:with-defaults:1.0?basic=explicit&amp;supported=report-all:trim

      </nc:capability>

      <nc:capability>

         urn:ietf:params:netconf:capability:netconf-monitoring:1.0

      </nc:capability>

      <nc:capability>

         urn:ietf:params:netconf:capability:schema-retrieval:1.0

      </nc:capability>

      <nc:capability>

         urn:ietf:params:xml:ns:yang:inet-types?module=ietf-inet-types&amp;revision=2009-05-13

      </nc:capability>

      <nc:capability>

         urn:ietf:params:xml:ns:netconf:monitoring?module=ietf-netconf-monitoring&amp;revision=2009-06-16

      </nc:capability>

      <nc:capability>

         urn:ietf:params:netconf:capability:with-defaults:1.0?module=ietf-with-defaults&amp;revision=2009-07-01&amp;features=with-defaults

      </nc:capability>

      <nc:capability>

         urn:ietf:params:xml:ns:yang:yang-types?module=ietf-yang-types&amp;revision=2009-05-13

      </nc:capability>

      <nc:capability>

         http://netconfcentral.org/ns/yuma-interfaces?module=interfaces&amp;revision=2009-07-17

      </nc:capability>

      <nc:capability>

         http://netconfcentral.org/ns/yuma-mysession?module=yuma-mysession&amp;revision=2009-08-11

      </nc:capability>

      <nc:capability>

         http://netconfcentral.org/ns/yuma-nacm?module=yuma-nacm&amp;revision=2009-05-13

      </nc:capability>

      <nc:capability>

         urn:ietf:params:xml:ns:netmod:notification?module=nc-notifications&amp;revision=2008-07-14

      </nc:capability>

      <nc:capability>

         http://netconfcentral.org/ns/yuma-ncx?module=yuma-ncx&amp;revision=2009-06-12

      </nc:capability>

      <nc:capability>

         http://netconfcentral.org/ns/yuma-app-common?module=yuma-app-common&amp;revision=2009-04-10

      </nc:capability>

      <nc:capability>

         http://netconfcentral.org/ns/yuma-types?module=yuma-types&amp;revision=2008-07-20

      </nc:capability>

      <nc:capability>

         http://netconfcentral.org/ns/netconfd?module=netconfd&amp;revision=2009-05-28

      </nc:capability>

      <nc:capability>

         urn:ietf:params:xml:ns:netconf:notification:1.0?module=notifications&amp;revision=2008-07-14

      </nc:capability>

      <nc:capability>

         http://netconfcentral.org/ns/yuma-proc?module=yuma-proc&amp;revision=2009-07-17

      </nc:capability>

      <nc:capability>

         http://netconfcentral.org/ns/yuma-system?module=yuma-system&amp;revision=2009-06-04

      </nc:capability>

      <nc:capability>

         http://netconfcentral.org/ns/test?module=test&amp;revision=2009-06-10&amp;features=feature1,feature3,feature4

      </nc:capability>

   </nc:capabilities>

   <nc:session-id>1</nc:session-id>

</nc: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  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.8  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.9  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.10  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 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:

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

 

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.

Only the 'NETCONF' stream is supported by netconfd-pro.

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 tim (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  <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.11  <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.12  <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:

3

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

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:

7

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

4

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

<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.16  <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.17  <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.18  <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:secure, so by default, only the super user account is allowed to use it.

 

<load> operation

 

Min parameters:

1

Max parameters:

3

Return type:

data

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="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.19  <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:secure, so by default, only the super user account is allowed to use it.

 

<load> 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="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.20  <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.21  <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.22  <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.23  <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.24  <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.25  <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.26  <set-log-level>

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

 

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.

<set-log-level> operation

 

Min parameters:

1

Max parameters:

1

Return type:

status

YANG file:

yuma-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.27  <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.

<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.28  <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.29  <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:

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="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.30  <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:

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="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.31  <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.32  <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 yuma-nacm.yang.

The nacm:secure and nacm:very-secure 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:very-secure.  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 consists of 3 read-only leafs and 2 containers:

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.

A group is named with is a YANG identity, which has a base of 'nacmRoot':


identity nacmGroups {
   description
"Root of all NETCONF Administrative Groups";
}

 

There are 3 hard-wired group names that can be used:

Any module can define an extension identity for the 'nacmGroups' base type, and use it as a group name.  There are no special semantics associated with any particular group name.

 


import nacm { prefix nacm; }

identity mygroup {
   description
"My special administrator's group.";
base nacm:nacmGroups;
}

 

 

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.

Each group is identified only by its <groupIdentity> leaf.

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 'nacm:guest',and the users 'fred' and 'barney' are the initial members of this group.

 

 

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

<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"

   message-id="3">

   <nc:edit-config>

      <nc:target>

         <nc:candidate/>

      </nc:target>

      <nc:config>

         <nacm:nacm xmlns:nacm="http://netconfcentral.org/ns/yuma-nacm">

            <nacm:groups>

               <nacm:group  nc:operation="create">

                  <nacm:group-identity>nacm:guest</nacm:group-identity>

                  <nacm:user-name>fred</nacm:user-name>

                  <nacm:user-name>barney</nacm:user-name>

               </nacm:group>

            </nacm:groups>

         </nacm:nacm>

      </nc:config>

   </nc:edit-config>

</nc: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:secure (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:very-secure (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)


  4. 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 yuma-nacm.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 following logic represents the steps taken during access control enforcement.

 

Phase 1: RPC Operation Access

 

Phase 2a: Database Read and Notification Access

 

Phase 2b) Database Write Access

 

2.7.9  Module Access Control Rules

The /nacm/rules/module-rule data structure is used to configure access for any object or RPC operation from a specific YANG module.  If the module namespace URI is the same as the XML namespace used in the NETCONF PDU, then the module rule is considered a match.

Multiple instances can appear for a single module, as long as the <allowed-access> key leaf value is different in each entry.  This allows different groups to get different access to the same module (e.g., read vs. read and write).

There is no way to move <module-rule> entries around, once they are created.

If a group appears in multiple entries for the same module name, then the first one encountered will be used.  Entries are checked in the same order they are returned in a <get-config> reply message.

The following example shows an <edit-config> operation which creates 2 <moduleRule> entries, for the following configuration:

 

 

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

<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"

   message-id="4">

   <nc:edit-config>

      <nc:target>

         <nc:candidate/>

      </nc:target>

      <nc:config>

         <nacm:nacm xmlns:nacm="http://netconfcentral.org/ns/yuma-nacm">

            <nacm:rules>

               <nacm:module-rule  nc:operation="create">

                  <nacm:module-name>nacm</nacm:module-name>

                  <nacm:allowed-rights>read write</nacm:allowed-rights>

                  <nacm:allowed-group>nacm:admin</nacm:allowed-group>

               </nacm:module-rule>

               <nacm:module-rule  nc:operation="create">

                  <nacm:module-name>nacm</nacm:module-name>

                  <nacm:allowed-rights>read</nacm:allowed-rights>

                  <nacm:allowed-group>nacm:monitor</nacm:allowed-group>

               </nacm:module-rule>

            </nacm:rules>

         </nacm:nacm>

      </nc:config>

   </nc:edit-config>

</nc:rpc>

 

2.7.10  RPC Access Control Rules

The /nacm/rules/rpc-rule data structure is used to configure access for a specific RPC operation from a specific YANG module.  If the module namespace URI for the <rpc-module-name> value is the same as the XML namespace used in the NETCONF PDU,and the <rpc--name> value is the same as the RPC method name, then the RPC rule is considered a match.

Multiple instances can appear for a single RPC operation, as long as the <allowed-access> key leaf value is different in each entry.  This allows different groups to get different access to the same operation (e.g., exec vs. no access).

There is no way to move <rpc-rule> entries around, once they are created.

If a group appears in multiple entries for the same RPC operation, then the first one encountered will be used.  Entries are checked in the same order they are returned in a <get-config> reply message.

If the 'read' or 'write' access bits are set in the <allowed-rights> key leaf, then they will be ignored.  This will not cause an error, but it these bits have no effect within an RPC rule.

The following example shows an <edit-config> operation which creates 2 <module-rule> entries, for the following configuration:

 

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

<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"

   message-id="5">

   <nc:edit-config>

      <nc:target>

         <nc:candidate/>

      </nc:target>

      <nc:config>

         <nacm:nacm xmlns:nacm="http://netconfcentral.org/ns/yuma-nacm">

            <nacm:rules>

               <nacm:rpc-rule  nc:operation="create">

                  <nacm:rpc-module-name>netconf</nacm:rpc-module-name>

                  <nacm:rpc--name>get-config</nacm:rpc--name>

                  <nacm:allowed-rights>exec</nacm:allowed-rights>

                  <nacm:allowed-group>nacm:admin</nacm:allowed-group>

                  <nacm:allowed-group>nacm:monitor</nacm:allowed-group>

               </nacm:rpc-rule>

               <nacm:rpc-rule  nc:operation="create">

                  <nacm:rpc-module-name>netconf</nacm:rpc-module-name>

                  <nacm:rpc--name>get-config</nacm:rpc--name>

                  <nacm:allowed-rights/>

                  <nacm:allowed-group>nacm:guest</nacm:allowed-group>

               </nacm:rpc-rule>

            </nacm:rules>

         </nacm:nacm>

      </nc:config>

   </nc:edit-config>

</nc:rpc>

 

2.7.11  Data Access Control Rules

The /nacm/rules/data-rule data structure is used to configure access for a specific set of database nodes (or notification payload nodes).  If the requested node in contained within the node-set result of the <path> XPath path expression, then the data rule is considered a match.

Multiple instances of the same <path> expression (or equivalent expressions), can appear at any time, and in any order.

The <path> leaf is not allowed to contain an arbitrary XPath expression (at this time).  Instead, an ncx:schema-instance string is allowed.  This has the same syntax as a YANG instance-identifier built-in type, except that the key leaf predicates (e.g., [name='eth0']) are optional instead of mandatory.  A missing key leaf predicate indicates that all instances of that key leaf are going to match the data rule.

This is a user-created list, and the key leaf is the arbitrary <name> field.  Use the YANG 'insert' operation to add data rules in some order other than 'last'.  Entries are checked in the same order they are returned in a <get-config> reply message.

If a group appears in multiple entries, then the first one that produces a result node-set with a matching node wiill be used.  

If the 'exec' access bit is set in the <allowed-rights> key leaf, then it will be ignored.  This will not cause an error, but it this bit has no effect within a data rule.

The following example shows an <edit-config> operation which creates 3 <data-rule> entries, for the following configuration:

 

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

<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"

   message-id="3">

   <nc:edit-config>

      <nc:target>

         <nc:candidate/>

      </nc:target>

      <nc:default-operation>none</nc:default-operation>

      <nc:config>

         <nacm:nacm xmlns:nacm="http://netconfcentral.org/ns/yuma-nacm">

            <nacm:rules>

               <nacm:data-rule  nc:operation="create">

                  <nacm:name>itf-1</nacm:name>

                  <nacm:path

                     xmlns:if="http://netconfcentral.org/ns/yuma-interfaces">

                       /if:interfaces/if:interface

                  </nacm:path>

                  <nacm:allowed-rights>read write</nacm:allowed-rights>

                  <nacm:allowed-group>nacm:admin</nacm:allowed-group>

                  <nacm:comment>

                     let admin group read and write all interfaces

                  </nacm:comment>

               </nacm:data-rule>

               <nacm:data-rule  nc:operation="create">

                  <nacm:name>itf-2</nacm:name>

                  <nacm:path

                     xmlns:if="http://netconfcentral.org/ns/interfaces">

                       /if:interfaces/if:interface[if:name='eth0']

                  </nacm:path>

                  <nacm:allowed-rights>read</nacm:allowed-rights>

                  <nacm:allowed-group>nacm:monitor</nacm:allowed-group>

                  <nacm:comment>

                     let monitor group read interface 'eth0'

                  </nacm:comment>

               </nacm:data-rule>

               <nacm:data-rule  nc:operation="create">

                  <nacm:name>itf-3</nacm:name>

                  <nacm:path

                     xmlns:if="http://netconfcentral.org/ns/interfaces">

                       /if:interfaces

                  </nacm:path>

                  <nacm:allowed-rights/>

                  <nacm:allowed-group>nacm:guest</nacm:allowed-group>

                  <nacm:comment>

                     do not let guest group read any interfaces info

                  </nacm:comment>

               </nacm:data-rule>

            </nacm:rules>

         </nacm:nacm>

      </nc:config>

   </nc:edit-config>

</nc:rpc>

 

 

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

2.8.2  Resource Types

A RESTCONF client can determine the root of the RESTCONF API by getting the "/.well-known/host-meta" resource and using the <Link> element containing the "restconf" attribute:
 
 

 

Request

--------

GET /.well-known/host-meta HTTP/1.1

Host: example.com

Accept: application/xrd+xml

 

Response

--------

HTTP/1.1 200 OK

Content-Type: application/xrd+xml

Content-Length: nnn

 

<XRD xmlns='http://docs.oasis-open.org/ns/xri/xrd-1.0'>

   <Link rel='restconf' href='/restconf'/>

</XRD>

 

 

Once discovering the RESTCONF API root, the client must prepend it to any subsequent request to a RESTCONF resource. For instance, using the "/restconf" path discovered above, the client can now determine the operations supported by the server.

 

 

Request

--------

GET /restconf/operations HTTP/1.1

Host: example.com

  Accept: application/yang-data+xml

 

 

The RESTCONF resources are accessed via a set of URIs. The set of YANG modules supported by the server will determine the data model specific operations, top-level data node resources, and event notification messages supported by the server.

The RESTCONF protocol defines a set of application specific media types to identify each of the available resource types. The following resource types are defined in RESTCONF:

 

RESTCONF Resource Types
 

Resource

RESTCONF Entry points

YANG-API Entry points

Media Type

 API

{+restconf}

{+restconf}/operations

{+restconf}/version

{+restconf}/yang-library-version

{+yang-api}

application/yang-data+xml

application/yang-data+json

 Datastore

{+restconf}/data

{+yang-api}/datastore

application/yang-data+xml

application/yang-data+json

 Data

{+restconf}/data/node

{+yang-api}/datastore/node

application/yang-data+xml

application/yang-data+json

 Errors
RESTCONF specific error handling
Not-supported, standard NETCONF-based error handling 

application/yang-data+xml

application/yang-data+json

 Operation

{+restconf}/operations/ <operation>

{+yang-api}/operations/ <operation>

application/yang-data+xml

application/yang-data+json

 Schema

{+restconf}/yang

not-supported

application/yang

 Event Stream

{+restconf}/streams

{+yang-api}/events

text/event-stream

 

Note: Only RESTCONF protocol supports Accept header validation and media types utilization.
 

2.8.3  RESTCONF Headers

There are several HTTP header lines utilized in RESTCONF messages. Messages are not limited to the HTTP headers listed in this section.
 
HTTP defines which header lines are required for particular circumstances. There are some request headers that are used within RESTCONF, usually applied to data resources.  The following tables summarize the headers most relevant in RESTCONF message requests:
 
RESTCONF Request Headers
 

Name

Description

  Accept

Response Content-Types that are acceptable 
  Content-Type
The media type of the request body  
  Host 
The host address of the server   
  If-Match 
Only perform the action if the entity matches ETag  
  If-Modified-Since
Only perform the action if modified since time   
  If-Unmodified-Since
Only perform the action if unmodified since time 

 

The following tables summarize the headers most relevant in RESTCONF message responses:
 
RESTCONF Response Headers

Name

Description

   Allow

Valid actions when 405 error returned 
  Cache-Control
The cache control parameters for the response
  Content-Type 
The media type of the response message-body
  Date
The date and time the message was sent 
  ETag
An identifier for a specific version of a resource  
  Last-Modified
The last modified date and time of a resource 
  Location
The resource identifier for a newly created resource
 
 
--restconf-strict-headers is netconfd-pro parameter that specifies the server's validation rules for Accept and Content Type headers entries. If set to 'true' the server will only accept requests with normative header entries specified in RFC 8040. If set to 'false', the server will try to accept not normative header entries. The default is false. 
 

2.8.4   RESTCONF Query Parameters

Each RESTCONF operation allows zero or more query parameters to be present in the request URI. The specific parameters that are allowed depends on the resource type, and sometimes the specific target resource used, in the request.
 
				RESTCONF Query Parameters
 

Value

Methods

Description

  content

GET
Select config and/or non-config data resources
  depth 
GET
Request limited sub-tree depth in the 
  fields
GET
Return all descendant data nodes reply content  
  filter
GET
Boolean notification filter for event stream resources
  insert
POST/ PUT
Insertion mode for user-ordered data  resources
  point
POST/ PUT
Insertion point for user-ordered data  resources
  start-time
GET
Replay buffer start time for event stream resources  
  stop-time
GET
Replay buffer stop time for event  stream resources
  with-defaults
GET
Control retrieval of default values

 

 
Query parameters can be given in any order. Each parameter can appear at most once in a request URI.  A default value may apply if the parameter is missing.
 
If vendors define additional query parameters, they should use a prefix (such as the enterprise or organization name) for query parameter names in order to avoid collisions with other parameters.
 
 
In the RESTCONF implementation the "depth" parameter is used to limit the number of levels of child resources that are returned by the server for a GET method request. 
 
Yang definition:
 

 

    leaf depth {

      type union {

        type enumeration {

          enum unbounded;

        }

        type uint32 {

          range "1..max";

        }

      }

      default unbounded;   // set to 1 in draft-01!

      description "Resource retrieval depth requested";

    }

 
The start level is determined by the target resource for the operation.
 
The first nest-level consists of the requested data node itself.  Any child nodes which are contained within a parent node have a depth value that is 1 greater than its parent, so that a depth level of "1" includes just the target resource level itself.  A depth level of "2" includes the target resource level and its child nodes.
 
To retrieve all the child resources, the "depth" parameter is not present or set to the default value "unbounded". The value of the "depth" parameter is either an integer between 1 and 65535, or the string "unbounded".  "unbounded" is the default. 
 
This parameter is only allowed for GET methods on API, datastore, and data resources.  A 400 Bad Request error is returned if it used for other methods or resource types. 
 
By default, the server will include all sub-resources within a retrieved resource, which have the same resource type as the requested resource.  Only one level of sub-resources with a different media type than the target resource will be returned. 
 
If the "depth" query parameter URI is listed in the "capability" leaf-list, then the server supports the "depth" query parameter.
 
The "content" parameter is used to select the type of data child resources (configuration and/or not configuration) that are returned by the server for a GET method request.
 
The "content" parameter controls how descendant nodes of the requested data nodes will be processed in the reply.
 
The allowed values are:
 
 

Value

Description

  config

Return only configuration descendant data nodes 
  nonconfig 
Return only non-configuration descendant data nodes 
  all
Return all descendant data nodes

 

 

This parameter is only allowed for GET methods on datastore and data resources.  A 400 Bad Request error is returned if used for other methods or resource types. The default value is for the "content" parameter is "nonconfig".
 
To retrieve all the child resources, the "content" parameter is set  to "all". 
 
The client might send:
 

 

      GET /restconf/data/example-events:events?content=all

          HTTP/1.1

      Host: example.com

      Accept: application/yang-data+json

 

 
The server might respond:
 

 

     HTTP/1.1 200 OK

      Date: Mon, 23 Apr 2012 17:11:30 GMT

      Server: example-server

      Cache-Control: no-cache

      Pragma: no-cache

      Content-Type: application/yang-data+json

 

{

        "example-events:events" : {

          "event" : [

            {

              "name" : "interface-up",

              "description" : "Interface up notification count",

              "event-count" : 42

            },

            {

              "name" : "interface-down",

              "description" : "Interface down notification count",

              "event-count" : 4

            }

          ]

        }

      }

 

 

 
YANG definition:
 

container query {

    ncx:abstract;

    ncx:hidden;

    description "RESTCONF Query String Parameters";

 

    leaf content {

      type enumeration {

        enum config;

        enum nonconfig;

        enum all;

        }

      }

      description

        "controls how descendant nodes of the requested

         data nodes will be processed in the reply .";

    }

 
The content parameter is similar to the “config” YANG-API query parameter.
 
Currently this parameter is not supported, it will be available in the next releases.
The "filter" parameter is used to indicate which subset of all possible events are of interest. If not present, all events not precluded by other parameters will be sent. 
 
This parameter is only allowed for GET methods on a text/event-stream data resource.  A 400 Bad Request error is returned if used for other methods or resource types.
The format of this parameter is an XPath 1.0 expression, and is evaluated in the following context:
 
If the boolean result of the expression is true when applied to the conceptual "notification" document root, then the event notification is delivered to the client.
 
If the "filter" query parameter URI is listed in the "capability" leaf-list, then the server supports the "filter" query parameter.
 
The following URIs show some examples of notification filter specifications (lines wrapped for display purposes only):
 
 

      // filter = /event/event-class='fault'

      GET /mystreams/NETCONF?filter=%2Fevent%2Fevent-class%3D'fault'

 

      // filter = /event/severity<=4

      GET /mystreams/NETCONF?filter=%2Fevent%2Fseverity%3C%3D4

 

      // filter = /linkUp|/linkDown

      GET /mystreams/SNMP?filter=%2FlinkUp%7C%2FlinkDown

 

      // filter = /*/reporting-entity/card!='Ethernet0'

      GET /mystreams/NETCONF?

         filter=%2F*%2Freporting-entity%2Fcard%21%3D'Ethernet0'

 

      // filter = /*/email-addr[contains(.,'company.com')]

      GET /mystreams/critical-syslog?

         filter=%2F*%2Femail-addr[contains(.%2C'company.com')]

 

      // Note: the module name is used as prefix.

      // filter = (/example-mod:event1/name='joe' and

      //           /example-mod:event1/status='online')

      GET /mystreams/NETCONF?

        filter=(%2Fexample-mod%3Aevent1%2Fname%3D'joe'%20and

                %20%2Fexample-mod%3Aevent1%2Fstatus%3D'online')

 

 

 

 

Currently this parameter is not supported, it will be available in the next releases.
 
The "fields" query parameter is used to optionally identify datanodes within the target resource to be retrieved in a GET method. The client can use this parameter to retrieve a subset of all nodes in a resource. 
 
A value of the "fields" query parameter matches the following rule:
 

 

    fields-expr = path '(' fields-expr / ')' /

                   path ';' fields-expr /

                   path

     path = api-identifier [ '/' path ]

 

 
";" is used to select multiple nodes.  For example, to retrieve only the "genre" and "year" of an album, use:
 

 

    "fields=genre;year".

 

 
Parentheses are used to specify sub-selectors of a node. For example, to retrieve only the "label" and "catalog-number" of an album, use: 
 

 

    "fields=admin(label;catalogue-number)".

 

 
"/" is used in a path to retrieve a child node of a node. For example, to retrieve only the "label" of an album, use:
 

 

   "fields=admin/label".

 

 
This parameter is only allowed for GET methods on api, datastore, and data resources.  A 400 Bad Request error is returned if used for other methods or resource types. 
 
If the "fields" query parameter URI is listed in the "capability" leaf-list, then the server supports the "fields" parameter.
 
In this example the client is retrieving the API resource, but retrieving only the "name" and "revision" nodes from each module, in JSON format:
 

 

      GET /restconf/data?fields=modules-state/module(name;revision) HTTP/1.1

      Host: example.com

      Accept: application/yang-data+json

 

 
The server might respond as follows.

 HTTP/1.1 200 OK

      Date: Mon, 23 Apr 2012 17:01:00 GMT

      Server: example-server

      Content-Type: application/yang-data+json

 

      {

        "ietf-yang-library:modules-state": {

          "module": [

            {

              "name" : "example-jukebox",

              "revision" : "2015-06-04"

            },

            {

              "name" : "ietf-inet-types",

              "revision" : "2013-07-15"

            },

            {

              "name" : "ietf-restconf-monitoring",

              "revision" : "2015-06-04"

            },

            {

              "name" : "ietf-yang-library",

              "revision" : "2015-01-30"

            },

            {

              "name" : "ietf-yang-types",

              "revision" : "2013-07-15"

            }

 

          ]

        }

      }

 

2.9  Monitoring

The <get> and <get-config> operations are fully supported for retrieving data from the <candidate> and <running> configuration databases.

The <get-config> operation is not supported for the <startup> configuration.

The <copy-config> operation is only supported copying the <running> configuration to the <startup> configuration.

If the NACM access control policy denies permission to read a particular node, then that node is silently skipped in the output.  No error or warning messages will be generated.

client applications should be prepared to receive XML subtrees that have been pruned by access control.  The <data> element will always be present, so an empty <data/> element indicates that no data was returned, either because the <filter> did not match, or because access control pruned the requested nodes.

 

There are really five types of filters available for retrieval operations:

 

Filter Types

 

type

description

is_config()

Choose the <get>operation for all objects, or <get-config> for just config=true objects

is_default()

Set the <with-defaults> parameter to 'trim'

is_client_set()

Set the <with-defaults> parameter to 'explicit'

subtree filtering

Use

  <filter type="subtree">

      // some-xml-subtree

  </filter>

           to retrieve portions of the <candidate> or <running> configurations.

XPath filtering

Use

   <filter type="xpath"

        select="expr"/>

to retrieve portions of the <candidate> or <running> configurations.

 

2.9.1  Using Subtree Filters

The subtree filtering feature is fully supported.

The order of nodes within the <filter> element is not relevant.  Data returned in the <rpc-reply> should follow the same top-level order as the request, but this should not be relied on to always be the case.

Duplicate or overlapping subtrees within the request will be combined in the output, so the common ancestor nodes are not duplicated in the reply.

XML namespaces are optional to use:

For example, the following PDU would be valid, even though it is not technically valid XML:

 

 

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

<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"

   message-id="8">

   <nc:get>

      <nc:filter>

         <nacm>

           <rules/>

         </nacm>

      </nc:filter>

   </nc:get>

</nc:rpc>

 

 

Note that there is no default namespace in effect for the <nacm> subtree.  However, the server will accept this filter as if the yuma-nacm.yang module namespace was properly declared.

Subtree filters can select specific list entries using content match nodes.  The following example would return the entire contents of the <interface> entry for 'eth0':

 

 

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

<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"

   message-id="9">

   <nc:get>

      <nc:filter type="subtree">

         <if:interfaces xmlns:if="http://netconfcentral.org/ns/yuma-interfaces">

            <if:interface>

               <if:name>eth0</if:name>

            </if:interface>

         </if:interfaces>

      </nc:filter>

   </nc:get>

</nc:rpc>

 

 

To retrieve only specific nodes (such as counters) from a single list entry, use select nodes for the desired counter(s), and include a content match node for each key leaf.  A missing key leaf will match any entry for that key.

The following example request shows how just the <inBytes> and <outBytes> counters could be retrieved from the <interface> entry for 'eth0'.

 

Example Request:

 

 

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

<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"

   message-id="10">

   <nc:get>

      <nc:filter type="subtree">

         <if:interfaces xmlns:if="http://netconfcentral.org/ns/yuma-interfaces">

            <if:interface>

               <if:name>eth0</if:name>

               <if:counters>

                  <if:inBytes/>

                  <if:outBytes/>

               </if:counters>

            </if:interface>

         </if:interfaces>

      </nc:filter>

   </nc:get>

</nc:rpc>

 

 

Example Reply:

 

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

<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"

   message-id="10">

   <nc:data>

      <if:interfaces xmlns:if="http://netconfcentral.org/ns/interfaces">

         <if:interface>

            <if:name>eth0</if:name>

            <if:counters>

               <if:inBytes>290046042</if:inBytes>

               <if:outBytes>112808406</if:outBytes>

            </if:counters>

         </if:interface>

      </if:interfaces>

   </nc:data>

</nc:rpc-reply>

 

2.9.2  Using XPath Filters

The :xpath capability is fully supported, including the YANG extensions to this capability.

The XPath 2.0 rule for default XML namespace behavior is used, not XPath 1.0 rules, as specified by the YANG language.  This means that any module with a node with the same local-name, in the same position in the schema tree, will match a missing XML prefix.  This allows much simpler specification of XPath filters, but it may match more nodes than intended.  Remember that any nodes added via an external YANG augment statement may have the same local-name, even though they are bound to a different XML namespace.

If the XPath expression does not return a node-set result, then the empty <data/> element will be returned in the <rpc-reply>.

If no nodes in the node-set result exist in the specified target database, then an empty <data/> element will be returned in the <rpc-reply>.

If a node in the result node-set matches a node in the target database, then it is included in the <rpc-reply>,

If a node selected for retrieval are contained within a YANG list node, then all the key leaf nodes for the specific list entry will be returned in the response.

The powerful '//' operator (equivalent to "descendant-or-self::node()") can be used to construct really simple XPath expressions.

The following example shows how a simple filter like '//name' will return nodes from all over the database, yet they can all be fully identified because the path from root is part of the response data.

 

Example Request:

 

<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"

   message-id="43">

   <nc:get>

      <nc:filter type="xpath" select="//name"/>

   </nc:get>

</nc:rpc>]]>]]>

 

 

Example Reply:

 

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

<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"

   message-id="43">

   <nc:data>

      <nacm:nacm xmlns:nacm="http://netconfcentral.org/ns/nacm">

         <nacm:rules>

            <nacm:data-rule>

               <nacm:name>nacm-tree</nacm:name>

            </nacm:data-rule>

            <nacm:data-rule>

               <nacm:name>itf-1</nacm:name>

            </nacm:data-rule>

         </nacm:rules>

      </nacm:nacm>

      <t:xpath.1 xmlns:t="http://netconfcentral.org/ns/test">

         <t:name>barney</t:name>

      </t:xpath.1>

      <if:interfaces xmlns:if="http://netconfcentral.org/ns/interfaces">

         <if:interface>

            <if:name>lo</if:name>

         </if:interface>

         <if:interface>

            <if:name>eth0</if:name>

         </if:interface>

         <if:interface>

            <if:name>virbr0</if:name>

         </if:interface>

         <if:interface>

            <if:name>pan0</if:name>

         </if:interface>

      </if:interfaces>

      <ns:netconf-state   xmlns:ns="urn:ietf:params:xml:ns:netconf:monitoring">

         <ns:datastores>

            <ns:datastore>

               <ns:name>

                  <ns:candidate/>

               </ns:name>

            </ns:datastore>

            <ns:datastore>

               <ns:name>

                  <ns:running/>

               </ns:name>

            </ns:datastore>

            <ns:datastore>

               <ns:name>

                  <ns:startup/>

               </ns:name>

            </ns:datastore>

         </ns:datastores>

      </ns:netconf-state>

      <manageEvent:netconf xmlns:manageEvent="urn:ietf:params:xml:ns:netmod:notification">

         <manageEvent:streams>

            <manageEvent:stream>

               <manageEvent:name>NETCONF</manageEvent:name>

            </manageEvent:stream>

         </manageEvent:streams>

      </manageEvent:netconf>

   </nc:data>

</nc:rpc-reply>

 

 

In order to refine the previous filter to select nodes from just one module, the use the XML prefix in the node identifier.   The example below selects only the <name> nodes from the interfaces module.

 

Example Request:

 

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

<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"

   message-id="44">

   <nc:get>

      <nc:filter type="xpath"

         xmlns:if="http://netconfcentral.org/ns/interfaces"

         select="//if:name"/>

   </nc:get>

</nc:rpc>

 

 

Example Reply:


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

<nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"

   message-id="44">

   <nc:data>

      <if:interfaces xmlns:if="http://netconfcentral.org/ns/interfaces">

         <if:interface>

            <if:name>lo</if:name>

         </if:interface>

         <if:interface>

            <if:name>eth0</if:name>

         </if:interface>

         <if:interface>

            <if:name>virbr0</if:name>

         </if:interface>

         <if:interface>

            <if:name>pan0</if:name>

         </if:interface>

      </if:interfaces>

   </nc:data>

</nc:rpc-reply>

 

2.9.3  Using Time Filters

The module yuma-time-filter.yang defines a timestamp mechanism to help reduce polling overhead for a client.

 

 

Example Request:

 

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

 <get-config xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

    <source>

      <running/>

    </source>

    <if-modified-since
   xmlns="
http://netconfcentral.org/ns/yuma-time-filter">
     
2011-08-21T21:51:46Z</if-modified-since>

  </get-config>

</rpc>

 

Empty reply because datastore not modified since specified time:

 


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

<rpc-reply message-id="4"
  xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"

   last-modified="2011-08-21T17:51:46Z"

   xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

 <data></data>

</rpc-reply>

 

 

2.10  YANG-Library Monitoring

There is a need for standard mechanisms to identify the YANG modules and submodules that are in use by each server that utilizes YANG-based data abstraction. If a large number of YANG modules are utilized by the server, then the YANG library information needed can be relatively large.  This information changes very infrequently, so it is important that clients be able to cache the YANG library and easily identify if their cache is out-of-date.

The RFC 7895 YANG Module Library defines monitoring information about all the loaded YANG modules and submodules used by a server to represent management and protocol information.

The following information is used by the library (for each YANG module in the library) to fully utilize monitoring mechanism.

 

The following information is used in order to identify if the YANG-Library cache is out-of-date and if the set of modules have changed.

 

2.10.1  Using  YANG-Library

In order to retrieve the whole set of modules currently supported by the server the following command is used.

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

<get>

  <filter type="subtree">

   <modules-state xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-    library"/>

  </filter>

</get>

</rpc>

 

Example Reply:

 

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

<rpc-reply message-id="1" trace-id="1"

 xmlns:ncx="http://netconfcentral.org/ns/yuma-ncx"

 ncx:last-modified="2015-06-17T19:00:37Z"

 xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

 <data>

  <modules-state xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-library">

   <module>

    <name>ietf-inet-types</name>

    <revision>2013-07-15</revision>

    <namespace>urn:ietf:params:xml:ns:yang:ietf-inet-types</namespace>

    <schema>http://localhost/yang-api/yang/ietf-inet-types/2013-07-15</schema>

    <conformance-type>import</conformance-type>

   </module>

   <module>

    <name>yumaworks-system</name>

    <revision>2014-10-16</revision>

    <namespace>http://yumaworks.com/ns/yumaworks-system</namespace>

    <schema>http://localhost/yang-api/yang/yumaworks-system/2014-10-16</schema>

    <conformance-type>implement</conformance-type>

   </module>

   <module>

    <name>yumaworks-types</name>

    <revision>2014-09-06</revision>

    <namespace>http://yumaworks.com/ns/yumaworks-types</namespace>

    <schema>http://localhost/yang-api/yang/yumaworks-types/2014-09-06</schema>

    <conformance-type>import</conformance-type>

   </module>

   <module-set-id>3521</module-set-id>

  </modules-state>

 </data>

</rpc-reply>

 

 

Example RESTCONF Request:

 

GET /restconf/data/modules-state/module=example-jukebox,2014-07-03/schema HTTP/1.1

Host: example.com

Accept: application/yang-data+json

 

 
The server might respond:
 

 

HTTP/1.1 200 OK

Date: Mon, 25 Apr 2012 11:10:30 GMT

Server: example-server

Content-Type: application/yang-data+json

 

 

 

{

"ietf-yang-library:schema":

"https://example.com/mymodules/example-jukebox/2015-06-04"

}

 

 

2.11  Notifications

The netconfd-pro server supports all the capabilities of RFC 5277, and the notification monitoring portion of the ietf-netconf-monitoring.yang data model.  All standard NETCONF notifications are supported (RFC 5277 and RFC 6470). There are also some proprietary notifications defined in yuma-system.yang.

2.11.1  Enabling Notifications

The netconfd-pro server can be invoked with or without NETCONF notification support enabled.  Notifications are enabled by default.

The --with-notifications CLI parameter is used to control this feature.  This parameter only needs to be used to disable notifications.  The parameter value --with-notifications=false will prevent the notification YANG modules from being loaded, prevent the :notifications and :interleave capabilities from being advertised in the <hello> message, and there will not be any event history buffer maintained.

2.11.2  Subscriptions

The <create-subscription> operation is used to start receiving notification.

It can be used in 4 different modes:

Once a subscription is started, notifications may start arriving, after the <rpc-reply> for the <create-subscription> operation is sent.

If the <startTime> parameter is used, then zero or more stored notifications will be returned, followed by the <replayComplete> notification.

If the <stopTime> parameter is also used, then the <notificationComplete> notification will be sent when this stop time has passed.  After that, no more notifications will be sent to the session, and the subscription is terminated.  After this point, another subscription could be started.

Only one subscription can be active on a session at a time.  There is no way to terminate a subscription, other than to close the session.

2.11.3  Notification Log

Each system event is saved to the notification replay buffer.

The <replayComplete> and <notificationComplete> notifications are not saved to this buffer because they are subscription-specific events, and not system events.

The size of the replay buffer is controlled by the --eventlog-size configuration parameter.

The default size is 1000 events.

The oldest event will be deleted when a new event is added, when this limit is reached.

If --eventlog-size is set to zero, then there will be no replayed notifications available, and the <replayComplete> notification will be sent right away, if <startTIme> is present.

Each event in the replay buffer is assigned a sequential sequence ID, starting from 1.

The <sequence-id> leaf is an unsigned 32-bit integer, which is added to the <notification> element, after the event element.  This sequence can be used to debug filters by comparing the sequence IDs of the notifications that were delivered against the expected sequence IDs.  This leaf is only added to each notification if the agt_notif_sequence_id flag is set to 'true' in the agt_profile_t struct for the server.  By default, this flag is set to 'false'.

2.11.4  Using Event Filters

An event filter is a way to disable generation of specific notification event types from being added to the notification replay buffer.  This can be useful if some events are not of interest to the applications, so there is no reason to use replay buffer resources to store them.

The YANG module yumaworks-event-filter.yang contains the /event-filters definitions.

A client can configure event-filter list entries in the /event-filters/event-filter list to suppress generation of specific events.

Each entry is identified by the module name and the notification event name.

An entry does not have to reference a valid module and/or notification name.  This allows filters to be present before modules are loaded into the server. If a module is loaded at run-time with the <load> or <load-bundle> operation, then the event filters will be checked and applied as needed at that time.

For example, the foo-event1 notification in the acme-foo module might be defined as followed:

 

 

module acme-foo {

   namespace “http://acme.com/ns/foo”;

    prefix af;

 

   notification foo-event1 {

      leaf foo-count { type uint32; }

      leaf foo-msg { type string; }

   }

 

}

 

 

 

 

To create an event filter, the client may send an <edit-config> operation request as follows:

 

 

 

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

<rpc message-id="1" trace-id="3"

 xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">

 <edit-config>

  <target>

   <running/>

  </target>

  <default-operation>merge</default-operation>

  <test-option>set</test-option>

  <config>

   <event-filters xmlns="http://yumaworks.com/ns/yumaworks-event-filter">

    <event-filter

     xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"

     nc:operation="merge">

     <module>acme-foo</module>

     <event>foo-event1</event>

    </event-filter>

   </event-filters>

  </config>

 </edit-config>

</rpc>

 

 

Logging Event Drops

 

If the --log-event-drops CLI parameter is set to 'true' then a log entry will be generated each time an event is dropped because it is suppressed.  The default is 'false' (event drops due to an event filter are not logged).  Event drops due to other reasons are not affected by this CLI parameter.

 

2.11.5  Using Notification Filters

A notification filter is different than a <get> or <get-config> filter.

Instead of selecting sub-trees of the specified database, it is treated as a boolean expression.  If the filter matches the content in the notification, then the notification is sent to that subscription.  If the filter does not match the content, then the notification is not sent to that subscription.

A filter match for notification purposes means that the filter is conceptually applied, as if it were a <get> operation, and if any nodes are selected (non-empty result node-set), then the filter is a match.  If no content is selected (empty result node-set), then the filter is not a match.

The first node that can appear in the filter is the event type.  The <eventTime> and <sequence-id> nodes are siblings of the event type element, so they cannot be used in a notification filter.

2.11.6  <notification> Element

The notification element contains 2 or 3 child elements, in this order:

  1. eventTime: timestamp for the event.  The namespace URI for this element is "urn:ietf:params:xml:ns:netconf:notification:1.0"

  2. eventType: The real name will be the name of the YANG notification, such as 'sysStartup'.  The contents of this element will depend on the YANG notification definition.  The namespace URI for this element will be different for every event type.  It will be the same value as the YANG namespace statement in the module that defines the notification statement for the particular event type.

  3. sequence-id: The system event sequence ID.  Session or subscription specific events, such as 'replayComplete' and 'notficationComplete' do not have this element.  The namespace URI for this element is "http://netconfcentral.org/ns/system".  This leaf is only added to each notification if the agt_notif_sequence_id flag is set to 'true' in the agt_profile_t struct for the server.  By default, this flag is set to 'false'.

2.11.7  Choosing System Notifications

There are two different YANG modules available for system notification events. These modules are enabled individually using the --system-notifications CLI parameter. Zero,1 or both modules can be enabled using a 'bits' YANG leaf:

  1. yuma-system:  Original Yuma system notifications. The system-notifications bit name is 'yuma'. The YANG definitions can be found in netconf/modules/netconfcentral/yuma-system.yang

  2. ietf-netconf-notifications: Standard system notifications from RFC 6470, based on the yuma-system notifications. The system-notifications bit name is 'ietf'. The YANG definitions cab be found in netconf/modules/ietf/ietf-netconf-notifications.yang

 

2.11.8  <replayComplete> Event

The <replayComplete> event is generated on a subscription that requested notification replay (by supplying the <startTime> parameter). This event type cannot be filtered out.  The server will always attempt to deliver this notification event type when it is generated.

 

<replayComplete> notification

 

Description:

Buffered notification delivery has ended for a subscription

Min parameters:

0

Max parameters:

0

YANG file:

nc-notifications.yang

 

Example:

 

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

<ncEvent:notification
    xmlns:ncEvent="urn:ietf:params:xml:ns:netconf:notification:1.0">

   <ncEvent:eventTime>2009-07-29T17:21:37Z</ncEvent:eventTime>

   <manageEvent:replayComplete
     xmlns:manageEvent="urn:ietf:params:xml:ns:netmod:notification"/>

</ncEvent:notification>

 

 

 

 

 

2.11.9  <notificationComplete> Event

The <notificationComplete> event is generated on a subscription that requested notification replay, and requested that the notification delivery stop (i.e., terminate subscription), after a certain time, using the <stopTime> parameter.

This event type cannot be filtered out.  The server will always attempt to deliver this notification event type when it is generated.

<notificationComplete> notification

 

Description:

All notification delivery has ended, and the subscription is terminated.

Min parameters:

0

Max parameters:

0

YANG file:

nc-notifications.yang

 

Example:

 

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

<ncEvent:notification
    xmlns:ncEvent="urn:ietf:params:xml:ns:netconf:notification:1.0">

   <ncEvent:eventTime>2009-07-29T17:31:22Z</ncEvent:eventTime>

   <manageEvent:notificationComplete
     xmlns:manageEvent="urn:ietf:params:xml:ns:netmod:notification"/>

</ncEvent:notification>

 

2.11.10  <sysStartup> Event

The <sysStartup> event is the first notification generated when the server starts or restarts.  It contains the startup file source (if any) and lists any <rpc-error> contents that were detected at boot-time, during the copying of the startup configuration into the running configuration.

 

<sysStartup> notification

 

Description:

The netconfd-pro server has started

Min parameters:

0

Max parameters:

2

YANG file:

yuma-system.yang

 

Parameters:

 

Example:

 

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

<ncEvent:notification xmlns:ncEvent="urn:ietf:params:xml:ns:netconf:notification:1.0">

   <ncEvent:eventTime>2009-07-29T17:21:13Z</ncEvent:eventTime>

   <sys:sysStartup xmlns:sys="http://netconfcentral.org/ns/system">

      <sys:startupSource>

         /home/andy/swdev/yuma/trunk/netconf/data/startup-cfg.xml

      </sys:startupSource>

   </sys:sysStartup>

   <sys:sequence-id
     xmlns:sys="http://netconfcentral.org/ns/system">1
 </sys:sequence-id>

</ncEvent:notification>

 

2.11.11  <sysSessionStart> Event

The <sysSessionStart> notification is generated when a NETCONF session is started.

The username, remote address, and session ID that was assigned are returned in the event payload.

 

<sysSessionStart> notification

 

Description:

A new NETCONF session has started.

Min parameters:

3

Max parameters:

3

YANG file:

yuma-system.yang

 

Parameters:

 

Example:

 

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

<ncEvent:notification xmlns:ncEvent="urn:ietf:params:xml:ns:netconf:notification:1.0">

   <ncEvent:eventTime>2009-07-29T21:53:04Z</ncEvent:eventTime>

   <sys:sysSessionStart xmlns:sys="http://netconfcentral.org/ns/system">

      <sys:userName>andy</sys:userName>

      <sys:sessionId>2</sys:sessionId>

      <sys:remoteHost>192.168.0.6</sys:remoteHost>

   </sys:sysSessionStart>

   <sys:sequence-id
     xmlns:sys="http://netconfcentral.org/ns/system">4
  </sys:sequence-id>

</ncEvent:notification>

 

2.11.12  <sysSessionEnd> Event

The <sysSessionEnd> notification is generated when a NETCONF session is terminated.

The username, remote address, and session ID that was assigned are returned in the event payload.  The termination reason is also included.

If the session was terminated before it properly started, it is possible that there will not be a <sysSessionStart> notification event to match the <sysSessionEnd> event.  For example, if the initial SSH connection setup fails before the <hello> message is processed, then only a <sysSessionEnd> notification event will be generated.  In this case, the user name and other session information may not be available.

 

<sysSessionEnd> notification

 

Description:

A NETCONF session has terminated.

Min parameters:

1

Max parameters:

5

YANG file:

yuma-system.yang

 

Parameters:

Example:

 

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

<ncEvent:notification xmlns:ncEvent="urn:ietf:params:xml:ns:netconf:notification:1.0">

   <ncEvent:eventTime>2009-07-29T21:53:12Z</ncEvent:eventTime>

   <sys:sysSessionEnd xmlns:sys="http://netconfcentral.org/ns/system">

      <sys:userName>andy</sys:userName>

      <sys:sessionId>2</sys:sessionId>

      <sys:remoteHost>192.168.0.6</sys:remoteHost>

      <sys:terminationReason>closed</sys:terminationReason>

   </sys:sysSessionEnd>

   <sys:sequence-id
        xmlns:sys="http://netconfcentral.org/ns/system">5
  </sys:sequence-id>

</ncEvent:notification>

 

2.11.13  <sysConfigChange> Event

The <sysConfigChange> notification is generated when the <running> configuration database is altered by a NETCONF session.

If the :candidate capability is supported, then this event is generated when the <commit> operation completes.

If the :writable-running capability is supported instead, then this even is generated when the <edit-config> operation completes.

The user name, remote address, and session ID that made the change are reported.

A summary of the changes that were made is also included in the event payload.

If multiple changes are made at once, then one <sysConfigChange> event will be generated for each change.  There is no significance to the order that these events are generated.

<sysConfigChange> notification

 

Description:

The <running> configuration has been changed by a NETCONF session.

Min parameters:

4

Max parameters:

4

YANG file:

yuma-system.yang

Parameters:

Example:

 

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

<ncEvent:notification xmlns:ncEvent="urn:ietf:params:xml:ns:netconf:notification:1.0">

   <ncEvent:eventTime>2009-07-29T22:21:18Z</ncEvent:eventTime>

   <sys:sysConfigChange xmlns:sys="http://netconfcentral.org/ns/system">

      <sys:userName>andy</sys:userName>

      <sys:sessionId>3</sys:sessionId>

      <sys:remoteHost>192.168.0.6</sys:remoteHost>

      <sys:edit>

         <sys:target>

         /nd:config/nacm:nacm/nacm:groups/nacm:group[nacm:groupIdentity=nacm:admin]

         </sys:target>

         <sys:operation>create</sys:operation>

      </sys:edit>

   </sys:sysConfigChange>

   <sys:sequence-id
     xmlns:sys="http://netconfcentral.org/ns/system">7</sys:sequence-id>

</ncEvent:notification>

2.11.14  <sysCapabilityChange> Event

The <sysCapabilityChange> notification is generated when the set of active capabilities for the server has changed.

The most common way this notification is generated is after the <load> operation has been used to add a new YANG module to the system.

It is possible that this notification will be generated for removal of capabilities.  However, at this time, there are no NETCONF capabilities that can be removed from the running system.

The <added-capability> leaf list will contain the capability URI for each new capability that has just been added.

The <deleted-capability> leaf list will contain the capability URI for each existing capability that has just been deleted.

The <changedBy> container will identity whether the server or a NETCONF session caused the capability change.

If the change was made by the server, then this container will have an empty leaf named <server>.

If the change was made by a NETCONF session, the user name, remote address, and session ID for the session that caused the change are reported.

If multiple changes are made at once, then one <sysCapabilityChange> event will be generated for all the changes. There will be multiple instances of the <added-capability> or <deleted-capability> leaf-list elements in this case.

When this notification is generated, the ietf-netconf-monitoring data model <capabilities> data structure is updated to reflect the changes.

 

<sysCapabilityChange> notification

 

Description:

The set of currently active <capability> URIs has changed

Min parameters:

2

Max parameters:

5

YANG file:

yuma-system.yang

 

Parameters:

Example:

 

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

<ncEvent:notification xmlns:ncEvent="urn:ietf:params:xml:ns:netconf:notification:1.0">

   <ncEvent:eventTime>2009-07-29T23:03:06Z</ncEvent:eventTime>

   <sys:sysCapabilityChange xmlns:sys="http://netconfcentral.org/ns/system">

      <sys:changed-by>

         <sys:userName>andy</sys:userName>

         <sys:sessionId>3</sys:sessionId>

         <sys:remoteHost>192.168.0.61</sys:remoteHost>

      </sys:changed-by>

      <sys:added-capability>

         http://netconfcentral.org/ns/toaster?module=toaster&amp;revision=2009-06-23&amp;features=clock

      </sys:added-capability>

   </sys:sysCapabilityChange>

   <sys:sequence-id

      xmlns:sys="http://netconfcentral.org/ns/system">8

   </sys:sequence-id>

</ncEvent:notification>

 

2.11.15  <sysConfirmedCommit> Event

The <sysConfirmedCommit> notification is generated when the state of the confirmed-commit procedure has changed.

The confirmed-commit procedure is started when a <commit> operation with a <confirmed/> parameter is executed.

A <sysConfirmedCommit> notification is generated several times for a single confirmed-commit procedure.  One or more of the following sub-events will be generated:

 

<sysConfirmedCommit> notification

 

Description:

The state of the confirmed-commit procedure has changed.

Min parameters:

1

Max parameters:

4

YANG file:

yuma-system.yang

 

Parameters:

 

Example:

 

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

<ncEvent:notification xmlns:ncEvent="urn:ietf:params:xml:ns:netconf:notification:1.0">

   <ncEvent:eventTime>2009-08-29T23:03:06Z</ncEvent:eventTime>

   <sys:sysConfirmedCommit xmlns:sys="http://netconfcentral.org/ns/system">

      <sys:userName>andy</sys:userName>

      <sys:sessionId>3</sys:sessionId>

      <sys:remoteHost>192.168.0.61</sys:remoteHost>

      <sys:confirmEvent>start</sys:confirmEvent>

   </sys:sysConfirmedCommit>

   <sys:sequence-id

      xmlns:sys="http://netconfcentral.org/ns/system">9

   </sys:sequence-id>

</ncEvent:notification>

 

 

2.11.16  <yang-library-change> Event

The <yang-library-change> notification is generated when the set of modules and submodules supported by the server has changed.

The most common way this notification is generated is after the <load> or <unload> operation has been used to add a new YANG module to the system.

Note that for a NETCONF server that implements YANG 1.1, a change of the "module-set-id" value results in a new value for the :yang-library capability.  Thus, if such a server implements NETCONF notifications, and the notification <netconf-capability-change>, a <netconf-capability-change> and <yang-library-change> notifications are generated whenever the "module-set-id" changes.

 

<yang-library-change> notification

 

Description:

The module-set-id value has changed

Min parameters:

1

Max parameters:

1

YANG file:

Ietf-yang-library.yang

 

Parameters:

 

Example:

 

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

 <notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0">

  <eventTime>2016-11-15T18:03:29Z</eventTime>

  <yang-library-change xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-library">

   <module-set-id>6765</module-set-id>

  </yang-library-change>

 </notification>

 

 

 

 

 

2.12  High Availability (YP-HA)

The netconfd-pro server supports the following hardware-based high-availability features:

 

If YP-HA is enabled, then the server will wait for its HA role unless the –ha-initial-active CLI parameter is set. This parameter should only be used for debugging because if the server reboots it will use the assigned role.

In normal operation all YP-HA roles are set and changed by external code (external process of same process).

If the server boots waiting for its HA role, then an empty factory default configuration will be loaded in order to validate the YANG modules loaded.  If the server starts the HA active role, then the configuration will be loaded for real before management sessions and notifications are enabled.  If the server starts the HA standby role, then it will get its configuration from the active server.

 

2.12.1  YP-HA Configuration

YP-HA CLI Parameters

 

Parameter

Description

ha-enabled

Enabled the YP-HA feature

ha-initial-active

Set the HA role from the CLI at boot-time (for debugging only)

ha-server

Configure a server in the YP-HA server pool

ha-server-key

String identifying the HA server pool for the server

ha-sil-standby

Enable edit callbacks (SIL, SIL-SA, HOOK) in YP HA standby mode

server-id

Identifies a server within a YP-HA pool, default value is server1

socket-type=tcp

The YControl socket type must be set to “tcp”

socket-address

The YControl socket address must be set

socket-port

The YControl socket port number must be set

 

 

 

 

Image2

 

In this example there are 3 separate systems, each running netconfd-pro.

 

Configuration parameters for Server ha-1:

 

ha-enabled true

ha-server ha-1@192.168.0.100

ha-server ha-2@192.168.0.105

ha-server ha-3@192.168.0.108

ha-server-key ha-pool-1

server-id ha-1

socket-type tcp

socket-address 192.168.0.100

socket-port 8088

 

 

Configuration parameters for Server ha-2:

 

ha-enabled true

ha-server ha-1@192.168.0.100

ha-server ha-2@192.168.0.105

ha-server ha-3@192.168.0.108

ha-server-key ha-pool-1

server-id ha-2

socket-type tcp

socket-address 192.168.0.105

socket-port 8088

 

 

Configuration parameters for Server ha-3:

 

ha-enabled true

ha-server ha-1@192.168.0.100

ha-server ha-2@192.168.0.105

ha-server ha-3@192.168.0.108

ha-server-key ha-pool-1

server-id ha-3

socket-type tcp

socket-address 192.168.0.108

socket-port 8088

 

 

In this configuration, all 3 servers will start waiting for an HA role.

It is expected that 1 will be assigned the HA active role and the other 2 servers will be assigned the HA standby role.