YumaPro netconfd-pro Manual - Home - YumaWorks...YumaPro netconfd-pro Manual 3.31 --datapath.....247 3.32 --db-lock-retry

YumaPro netconfd-pro Manual

YANG-Based Unified Modular Automation Tools

Multi-Protocol Server

Version 19.10-12


Table of Contents1 Preface............................................................................................................................................10

1.1 Legal Statements.......................................................................................................................101.2 Additional Resources.................................................................................................................10

1.2.1 WEB Sites....................................................................................................................................101.2.2 Mailing Lists.................................................................................................................................11

1.3 Conventions Used in this Document............................................................................................112 netconfd-pro User Guide...................................................................................................................12

2.1 Introduction..............................................................................................................................132.1.1 Features........................................................................................................................................132.1.2 Setting the Server Profile................................................................................................................152.1.3 Loading YANG Modules................................................................................................................162.1.4 Unloading YANG Modules.............................................................................................................172.1.5 Starting netconfd-pro.....................................................................................................................182.1.6 Starting SIL-SA Subsystems with sil-sa-app.....................................................................................202.1.7 Stopping netconfd-pro....................................................................................................................212.1.8 Signal Handling.............................................................................................................................212.1.9 Starting netconfd-pro with ypwatcher program..................................................................................222.1.10 Signal Handling with ypwatcher program.......................................................................................232.1.11 Error Handling............................................................................................................................232.1.12 Module Summary........................................................................................................................252.1.13 Notification Summary..................................................................................................................272.1.14 Operation Summary.....................................................................................................................292.1.15 Configuration Parameter List........................................................................................................312.1.16 Editing CLI Parameters at Run-Time.............................................................................................382.1.17 Using logrotate to Manage Log Files..............................................................................................392.1.18 Evaluation Version Restrictions.....................................................................................................402.1.19 Maintenance Mode......................................................................................................................412.1.20 Disabling YumaWorks YANG Modules..........................................................................................422.1.21 DB-Config-Lock Mode................................................................................................................432.1.22 Deferred Configuration Load Mode...............................................................................................44

2.2 Capabilities...............................................................................................................................452.2.1 :base:1.0.......................................................................................................................................452.2.2 :base:1.1.......................................................................................................................................452.2.3 :candidate.....................................................................................................................................452.2.4 :config-id......................................................................................................................................452.2.5 :confirmed-commit........................................................................................................................452.2.6 :interleave.....................................................................................................................................462.2.7 :netconf-monitoring.......................................................................................................................462.2.8 :notification..................................................................................................................................462.2.9 :partial-lock..................................................................................................................................472.2.10 :rollback-on-error........................................................................................................................472.2.11 :schema-retrieval.........................................................................................................................472.2.12 :startup.......................................................................................................................................482.2.13 :validate......................................................................................................................................482.2.14 :url.............................................................................................................................................492.2.15 :with-defaults..............................................................................................................................502.2.16 :writable-running.........................................................................................................................502.2.17 :xpath.........................................................................................................................................512.2.18 :yang-library...............................................................................................................................51

2.3 Databases..................................................................................................................................52

Version 19.10-12 Page 2


2.3.1 Database Locking..........................................................................................................................532.3.2 Using the <candidate> Database......................................................................................................532.3.3 Using the <running> Database........................................................................................................532.3.4 Using the <startup> Database..........................................................................................................54

2.4 Sessions....................................................................................................................................552.4.1 User Names..................................................................................................................................552.4.2 Session ID....................................................................................................................................552.4.3 Server <hello> Message.................................................................................................................562.4.4 Client <hello> Message..................................................................................................................572.4.5 RPC Request Processing.................................................................................................................592.4.6 Session Termination.......................................................................................................................60

2.5 Error Reporting.........................................................................................................................612.5.1 <error-severity> Element................................................................................................................612.5.2 <error-tag> Element.......................................................................................................................612.5.3 <error-app-tag> Element................................................................................................................632.5.4 <error-path> Element.....................................................................................................................642.5.5 <error-message> Element...............................................................................................................652.5.6 <error-info> Element.....................................................................................................................652.5.7 Dynamic Error Messages................................................................................................................662.5.8 Using Annotations to Define Dynamic Error Messages......................................................................692.5.9 Replacing a Standard Error Message................................................................................................702.5.10 Multi-Language Error Messages....................................................................................................712.5.11 Instance-Required Error Example..................................................................................................732.5.12 Missing-Choice Error Example.....................................................................................................752.5.13 No-Matches Error Example..........................................................................................................772.5.14 not-in-range Error Example..........................................................................................................78

2.6 Protocol Operations...................................................................................................................802.6.1 <backup>......................................................................................................................................802.6.2 <cancel-commit>...........................................................................................................................822.6.3 <cancel-subscription>....................................................................................................................832.6.4 <close-session>.............................................................................................................................842.6.5 <commit>.....................................................................................................................................852.6.6 <copy-config>...............................................................................................................................872.6.7 <create-subscription>.....................................................................................................................912.6.8 <delete-backup>............................................................................................................................932.6.9 <delete-config>.............................................................................................................................952.6.10 <discard-changes>.......................................................................................................................972.6.11 <edit-config>..............................................................................................................................982.6.12 <get>........................................................................................................................................1002.6.13 <get-bulk>................................................................................................................................1032.6.14 <get-config>.............................................................................................................................1082.6.15 <get-data>.................................................................................................................................1122.6.16 <get-module-tags>.....................................................................................................................1162.6.17 <get-my-session>.......................................................................................................................1182.6.18 <get-schema>............................................................................................................................1202.6.19 <get-support-save>....................................................................................................................1222.6.20 <kill-session>............................................................................................................................1252.6.21 <load>......................................................................................................................................1272.6.22 <load-bundle>...........................................................................................................................1292.6.23 <lock>......................................................................................................................................1312.6.24 <no-op>....................................................................................................................................1332.6.25 <partial-lock>............................................................................................................................134



2.6.26 <partial-unlock>........................................................................................................................1362.6.27 <restart>...................................................................................................................................1382.6.28 <restore>..................................................................................................................................1392.6.29 <set-log-level>..........................................................................................................................1402.6.30 <set-my-session>.......................................................................................................................1422.6.31 <shutdown>..............................................................................................................................1442.6.32 <unload>..................................................................................................................................1452.6.33 <unload-bundle>........................................................................................................................1472.6.34 <unlock>..................................................................................................................................1492.6.35 <validate>.................................................................................................................................151

2.7 Access Control.........................................................................................................................1532.7.1 NACM Module Structure..............................................................................................................1542.7.2 Users and Groups.........................................................................................................................1552.7.3 Creating New Groups...................................................................................................................1552.7.4 Access Control Modes..................................................................................................................1552.7.5 Permissions.................................................................................................................................1562.7.6 Special YANG Extensions For Access Control................................................................................1562.7.7 Default Enforcement Behavior......................................................................................................1572.7.8 Access Control Algorithm.............................................................................................................1572.7.9 Passwords and crypt-hash.............................................................................................................1572.7.10 Using Module Tags with NACM.................................................................................................159

2.8 Using RESTCONF..................................................................................................................1612.8.1 Features......................................................................................................................................1612.8.2 Resource Types............................................................................................................................1632.8.3 RESTCONF Headers...................................................................................................................1642.8.4 RESTCONF Query Parameters......................................................................................................165

2.9 Using gNMI............................................................................................................................1712.9.1 Features......................................................................................................................................1712.9.2 Restrictions for gNMI Protocol......................................................................................................1712.9.3 Running Ypgnmi-app...................................................................................................................1722.9.4 Running gNMI Client Applications................................................................................................1722.9.5 Closing Ypgnmi-app.....................................................................................................................1752.9.6 gNMI GetRequest........................................................................................................................1752.9.7 gNMI SetRequest.........................................................................................................................1782.9.8 gNMI JSON_ietf_val...................................................................................................................1802.9.9 gNMI Error Messages..................................................................................................................180

2.10 Monitoring............................................................................................................................1812.10.1 Using Subtree Filters..................................................................................................................1822.10.2 Using XPath Filters....................................................................................................................1842.10.3 Using Time Filters.....................................................................................................................187

2.11 YANG-Library Monitoring.....................................................................................................1882.11.1 Using YANG-Library.................................................................................................................188

2.12 Notifications..........................................................................................................................1912.12.1 Enabling Notifications................................................................................................................1912.12.2 Using Custom Event Streams......................................................................................................1912.12.3 Subscriptions.............................................................................................................................1922.12.4 Notification Log........................................................................................................................1942.12.5 Using Event Filters....................................................................................................................1952.12.6 Using Notification Filters............................................................................................................1962.12.7 <notification> Element...............................................................................................................1962.12.8 Choosing System Notifications....................................................................................................196



2.12.9 <replayComplete> Event............................................................................................................1972.12.10 <notificationComplete> Event...................................................................................................1982.12.11 <sysStartup> Event..................................................................................................................1992.12.12 <netconf-session-start> Event....................................................................................................2002.12.13 <netconf-session-end> Event.....................................................................................................2012.12.14 <netconf-config-change> Event.................................................................................................2032.12.15 <netconf-capability-change> Event............................................................................................2062.12.16 <netconf-confirmed-commit> Event...........................................................................................2092.12.17 <yang-library-change> Event....................................................................................................211

2.13 High Availability (YP-HA).....................................................................................................2122.13.1 YP-HA Configuration.................................................................................................................213

2.14 Configuration Templates........................................................................................................2152.14.1 yumaworks-templates.yang.........................................................................................................2162.14.2 Configuration Template Example: NACM group...........................................................................219

2.15 NETCONF Over TLS............................................................................................................2202.15.1 TLS Configuration.....................................................................................................................220

2.16 IETF Call Home....................................................................................................................2212.16.1 Call Home Configuration............................................................................................................221

3 CLI Reference................................................................................................................................2233.1 --access-control.......................................................................................................................2233.2 --allow-leaflist-delete-all..........................................................................................................2243.3 --allow-list-delete-all................................................................................................................2253.4 --allowed-user.........................................................................................................................2253.5 --alt-names..............................................................................................................................2263.6 --annotation.............................................................................................................................2273.7 --audit-log...............................................................................................................................2283.8 --no-audit-log..........................................................................................................................2283.9 --audit-log-append...................................................................................................................2293.10 --audit-log-candidate..............................................................................................................2293.11 --audit-log-console-level........................................................................................................2303.12 --audit-log-events...................................................................................................................2313.13 --audit-log-level.....................................................................................................................2353.14 --autodelete-pdu-error............................................................................................................2363.15 --binary-display-maxlen.........................................................................................................2363.16 --bundle................................................................................................................................2363.17 --callhome-reconnect..............................................................................................................2373.18 --callhome-retry-interval........................................................................................................2383.19 --callhome-retry-max.............................................................................................................2383.20 --callhome-server...................................................................................................................2393.21 --callhome-sshd-command......................................................................................................2403.22 --callhome-sshd-config...........................................................................................................2403.23 --callhome-subsys-command..................................................................................................2413.24 --callhome-tls-server..............................................................................................................2423.25 --cert-default-user..................................................................................................................2433.26 --cert-usermap.......................................................................................................................2443.27 --confdir................................................................................................................................2453.28 --config.................................................................................................................................2463.29 --convert-subtree-filter...........................................................................................................2463.30 --create-empty-npcontainers...................................................................................................247



3.31 --datapath..............................................................................................................................2473.32 --db-lock-retry-interval...........................................................................................................2493.33 --db-lock-timeout...................................................................................................................2493.34 --default-style........................................................................................................................2503.35 --delete-empty-npcontainers...................................................................................................2513.36 --deviation.............................................................................................................................2523.37 --errmsg................................................................................................................................2533.38 --errmsg-lang.........................................................................................................................2543.39 --eventlog-size.......................................................................................................................2543.40 --event-stream.......................................................................................................................2553.41 --event-stream-map................................................................................................................2553.42 --factory-startup.....................................................................................................................2563.43 --feature-disable.....................................................................................................................2573.44 --feature-enable.....................................................................................................................2573.45 --feature-enable-default..........................................................................................................2583.46 --fileloc-fhs...........................................................................................................................2593.47 --ha-enabled..........................................................................................................................2603.48 --ha-initial-active...................................................................................................................2613.49 --ha-server.............................................................................................................................2623.50 --ha-server-key......................................................................................................................2633.51 --ha-sil-standby......................................................................................................................2633.52 --hello-timeout.......................................................................................................................2643.53 --help....................................................................................................................................2643.54 --help-mode...........................................................................................................................2653.55 --hide-module........................................................................................................................2663.56 --home..................................................................................................................................2673.57 --idle-timeout........................................................................................................................2683.58 --import-version-bestmatch.....................................................................................................2693.59 --indent.................................................................................................................................2703.60 --insecure-ok.........................................................................................................................2703.61 --library-mode.......................................................................................................................2713.62 --loadpath..............................................................................................................................2723.63 --log......................................................................................................................................2723.64 --log-append..........................................................................................................................2743.65 --log-backtrace......................................................................................................................2743.66 --log-backtrace-detail.............................................................................................................2753.67 --log-backtrace-level..............................................................................................................2753.68 --log-backtrace-stream...........................................................................................................2763.69 --log-console.........................................................................................................................2763.70 --log-event-drops...................................................................................................................2773.71 --log-header...........................................................................................................................2773.72 --log-level.............................................................................................................................2783.73 --log-mirroring......................................................................................................................2793.74 --log-pthread-level.................................................................................................................2793.75 --log-stderr............................................................................................................................2803.76 --log-syslog...........................................................................................................................2803.77 --log-syslog-level...................................................................................................................2813.78 --log-vendor..........................................................................................................................282



3.79 --log-vendor-level..................................................................................................................2823.80 --match-names.......................................................................................................................2833.81 --max-burst...........................................................................................................................2843.82 --max-cli-sessions..................................................................................................................2843.83 --max-getbulk........................................................................................................................2853.84 --max-sessions.......................................................................................................................2853.85 --max-strlen...........................................................................................................................2853.86 --message-indent....................................................................................................................2863.87 --modpath.............................................................................................................................2863.88 --module...............................................................................................................................2873.89 --module-tagmap...................................................................................................................2873.90 --netconf-capability................................................................................................................2893.91 --netconf-tls-address...............................................................................................................2893.92 --netconf-tls-certificate...........................................................................................................2903.93 --netconf-tls-key....................................................................................................................2903.94 --netconf-tls-port....................................................................................................................2913.95 --netconf-tls-trust-store...........................................................................................................2913.96 --no-config............................................................................................................................2923.97 --no-log.................................................................................................................................2923.98 --no-nvstore...........................................................................................................................2933.99 --no-startup...........................................................................................................................2933.100 --no-watcher........................................................................................................................2943.101 --port..................................................................................................................................2943.102 --protocols...........................................................................................................................2953.103 --restconf-capability.............................................................................................................2953.104 --restconf-default-encoding...................................................................................................2963.105 --restconf-server-url.............................................................................................................2963.106 --restconf-strict-headers........................................................................................................2973.107 --running-error.....................................................................................................................2983.108 --runpath.............................................................................................................................2993.109 --save-owners......................................................................................................................2993.110 --session-sync-mutex...........................................................................................................3003.111 --sil-delete-children-first.......................................................................................................3003.112 --sil-invoke-for-defaults........................................................................................................3013.113 --sil-missing-error................................................................................................................3013.114 --sil-prio-reverse-for-deletes.................................................................................................3023.115 --sil-root-check-first.............................................................................................................3033.116 --sil-skip-load......................................................................................................................3043.117 --sil-test-get-when................................................................................................................3043.118 --sil-validate-candidate.........................................................................................................3053.119 --simple-json-names.............................................................................................................3053.120 --socket-address...................................................................................................................3063.121 --socket-port........................................................................................................................3063.122 --socket-type.......................................................................................................................3073.123 --startup..............................................................................................................................3083.124 start choice..........................................................................................................................3093.125 --startup-error......................................................................................................................3103.126 --startup-factory-file.............................................................................................................311



3.127 --startup-prune-ok................................................................................................................3123.128 --startup-skip-validation.......................................................................................................3133.129 --subdirs..............................................................................................................................3143.130 --subsys-timeout..................................................................................................................3153.131 --superuser..........................................................................................................................3153.132 --system-notifications...........................................................................................................3163.133 --system-sorted....................................................................................................................3163.134 --target................................................................................................................................3173.135 --tls-crl-missing-ok..............................................................................................................3173.136 --tls-crl-mode......................................................................................................................3183.137 --trim-whitespace.................................................................................................................3183.138 --usexmlorder......................................................................................................................3203.139 --version.............................................................................................................................3203.140 --warn-error.........................................................................................................................3213.141 --warn-idlen........................................................................................................................3213.142 --warn-linelen......................................................................................................................3223.143 --warn-off............................................................................................................................3223.144 --warn-up............................................................................................................................3233.145 --watcher-interval................................................................................................................3233.146 --wildcard-keys....................................................................................................................3243.147 --with-callhome...................................................................................................................3243.148 --with-canonical...................................................................................................................3253.149 --with-config-id...................................................................................................................3263.150 --with-db-lock.....................................................................................................................3263.151 --with-gnmi.........................................................................................................................3273.152 --with-maintenance-mode.....................................................................................................3273.153 --with-modtags....................................................................................................................3283.154 --with-netconf......................................................................................................................3283.155 --with-netconf-tls.................................................................................................................3293.156 --with-nmda........................................................................................................................3293.157 --with-notifications..............................................................................................................3303.158 --with-restconf.....................................................................................................................3313.159 --with-rollback-on-error.......................................................................................................3313.160 --with-ocpattern...................................................................................................................3323.161 --with-startup.......................................................................................................................3323.162 --with-support-save..............................................................................................................3333.163 --with-term-msg...................................................................................................................3333.164 --with-url............................................................................................................................3343.165 --with-url-ftp.......................................................................................................................3353.166 --with-url-tftp......................................................................................................................3353.167 --with-validate.....................................................................................................................3363.168 --with-warnings...................................................................................................................3363.169 --with-yang-api....................................................................................................................3373.170 --with-yang11-hello.............................................................................................................3373.171 --with-yang-patch-running....................................................................................................3383.172 --with-yp-coap.....................................................................................................................3383.173 --with-yp-coap-dtls..............................................................................................................3393.174 --with-yp-shell.....................................................................................................................340



3.175 --with-yuma-system.............................................................................................................3403.176 --with-yuma-time-filter........................................................................................................3413.177 --with-yumaworks-config-change..........................................................................................3413.178 --with-yumaworks-event-filter..............................................................................................3423.179 --with-yumaworks-getbulk...................................................................................................3433.180 --with-yumaworks-ids..........................................................................................................3433.181 --with-yumaworks-system....................................................................................................3443.182 --with-yumaworks-templates................................................................................................3443.183 --yangapi-server-url.............................................................................................................3453.184 --yumapro-home..................................................................................................................3463.185 --yp-coap-address................................................................................................................3473.186 --yp-coap-dtls-port...............................................................................................................347



1 Preface

1.1 Legal Statements

Copyright 2009 – 2012, Andy Bierman, All Rights Reserved.

Copyright 2012 - 2020, YumaWorks, Inc., All Rights Reserved.

1.2 Additional Resources

This document assumes you have successfully set up the software as described in the printed document:

YumaPro Installation Guide

Other documentation includes:

YumaPro API Quickstart Guide

YumaPro Quickstart Guide

YumaPro User Manual

YumaPro yangcli-pro Manual

YumaPro yangdiff-pro Manual

YumaPro yangdump-pro Manual

YumaPro Developer Manual

YumaPro ypclient-pro Manual

YumaPro ypgnmi Guide

YumaPro yp-system API Guide

YumaPro yp-show API Guide

YumaPro Yocto Linux Quickstart Guide

YumaPro yp-snmp Manual

To obtain additional support you may contact YumaWorks technical support department:

[email protected]

1.2.1 WEB Sites

• YumaWorks

◦ https://www.yumaworks.com

◦ Offers support, training, and consulting for YumaPro.

• Netconf Central

◦ http://www.netconfcentral.org/

▪ Free information on NETCONF and YANG, tutorials, on-line YANG module validation and documentation database

• Yang Central

◦ http://www.yang-central.org


http://www.yang-central.org/

http://www.netconfcentral.org/

https://www.yumaworks.com/

mailto:[email protected]


◦ Free information and tutorials on YANG, free YANG tools for download

• NETCONF Working Group Wiki Page

◦ http://trac.tools.ietf.org/wg/netconf/trac/wiki

◦ Free information on NETCONF standardization activities and NETCONF implementations

• NETCONF WG Status Page

◦ http://tools.ietf.org/wg/netconf/

◦ IETF Internet draft status for NETCONF documents

• libsmi Home Page

◦ http://www.ibr.cs.tu-bs.de/projects/libsmi/

◦ Free tools such as smidump, to convert SMIv2 to YANG

1.2.2 Mailing Lists

• NETCONF Working Group

◦ https://mailarchive.ietf.org/arch/browse/netconf/

◦ Technical issues related to the NETCONF protocol are discussed on the NETCONF WG mailing list. Refer to the instructions on https://www.ietf.org/mailman/listinfo/netconf for joining the mailing list.

• NETMOD Working Group

◦ https://datatracker.ietf.org/wg/netmod/documents/

◦ Technical issues related to the YANG language and YANG data types are discussed on the NETMOD WG mailing list. Refer to the instructions on the WEB page for joining the mailing list.

1.3 Conventions Used in this Document

The following formatting conventions are used throughout this document:

Documentation Conventions

Convention Description

--foo CLI parameter foo

<foo> XML parameter foo

foo yangcli-pro command or parameter

$FOO Environment variable FOO

$$foo yangcli-pro global variable foo

some text Example command or PDU

some text Plain text


https://datatracker.ietf.org/wg/netmod/documents/

https://www.ietf.org/mailman/listinfo/netconf

https://mailarchive.ietf.org/arch/browse/netconf/

http://www.ibr.cs.tu-bs.de/projects/libsmi/

http://tools.ietf.org/wg/netconf/

http://trac.tools.ietf.org/wg/netconf/trac/wiki


2 netconfd-pro User Guide



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, theinterface 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:

• Complete implementation of NETCONF versions 1.0 and 1.1

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

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

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

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

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

• Supports the RESTCONF Protocol defined in RFC 8040

• Supports the YANG Patch Media Type defined in RFC 8072

• Supports the Network Management Datastore Architecture (NMDA)

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

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

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

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

• Complete XML 1.0 implementation with full support for XML Namespaces

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

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

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

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

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

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

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

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

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

• Automatic subtree and full XPath filtering

• Automatic confirmed-commit and rollback procedures



• Automatic database audit log and change notification support

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

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

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

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

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

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

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

• Full support for all YANG constructs, including deviations

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• gNMI Protocol support

• Maintenance Mode support

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

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



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:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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



2.1.3 Loading YANG Modules

Loading Modules at Boot-Time

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

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

Loading Modules at Run-Time

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

Loading Bundles at Boot-Time

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

Loading Bundles at Run-Time

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

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

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

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



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

2.1.4 Unloading YANG Modules

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

Modules imported by the module being unloaded are not unloaded.

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

Modules imported by the bundle are unloaded.

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

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

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

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



2.1.5 Starting netconfd-pro

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

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

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

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

The netconfd-pro program can be invoked several ways:

• To get the current version and exit:

netconfd-pro --version

• To get program help and exit:

netconfd-pro --helpnetconfd-pro --help --briefnetconfd-pro --help --full

• To start the server in the background, set the logging level to 'debug', and send logging messages to a log file

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

• To start the server interactively, and send all log messages to STDOUT:

netconfd-pro

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

netconfd-pro --log=mylogfile



• To start the server interactively, and append to an existing log file:

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

• To get parameters from a non-default configuration file:

netconfd-pro –config=/opt/conf/netconfd-pro.conf

• To run as root and use the FHS file locations:

netconfd-pro –fileloc-fhs=true



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

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

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

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

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

• --address=ip-addressThe IP address of the main server. The default is to use the server on the same system as the sil-sa-app process. If this parameter is used, then netconfd-pro must use the --socket-type=tcp parameter. If netconfd-pro uses the --socket-address parameter, then this parameter must match its value.

• --library=stringThe --library parameter keyword is optional. It specifies a SIL- SA library (module or bundle) that should be selected by this subsystem. If any --library parameters are present, then only those SIL-SA libraries will be loaded by this subsystem, if the main server indicates that the module or bundle is loaded. This option can be usedmultiple times, once for each selected module or bundle. If no --library parameters are present then the sil-sa-app will attempt to load all SIL-SA modules and bundles reported by the server. If the SIL-SA library is not found in the /usr/lib/yumapro directory then it will be skipped by the subsystem.

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

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

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

• --port=uint16The TCP port number to use, Ignored unless address is also present. The default is 2023. If this parameter is used, then netconfd-pro must use the --socket-type=tcp parameter. If netconfd-pro uses the --socket-port parameter, then this parameter must match its value.

• --subsys-id=stringThe subsystem identifier to use. The default is ‘subsys1’. This value must be unique among all the subsystems registered on the same server.

The SIL-SA libraries loaded depends on 2 factors:

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

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

Example: Start the server with a non-default socket

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

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



Example 2: Start 2 subsystems on the same host

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

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

2.1.7 Stopping netconfd-pro

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

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

2.1.8 Signal Handling

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

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

Signals Recognized by netconfd-pro

signal number description

SIGHUP (Hangup) 1 Restart the server.

SIGINT (Control-C) 2 Shutdown the server.

SIGQUIT 3 Shutdown the server.

SIGILL 4 Shutdown the server.

SIGTRAP 5 Shutdown the server.

SIGABRT 6 Shutdown the server.

SIGKILL 9 Kill the server process (No proper cleanup!)

SEGUSR1 10 Reload the server (Does a restart)

SEGUSR2 11 Logrotate (reopen log files)

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. In order to shutdown the server properly with the kill command, use “kill -TERM” not “kill -9”. Refer to the Unix man pages for more details.



2.1.9 Starting netconfd-pro with ypwatcher program

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

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

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

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

• To start the server interactively, with ypwatcher program:

netconfd-pro

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

netconfd-pro --no-watcher

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

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

netconfd-pro --watcher-interval=10



2.1.10 Signal Handling with ypwatcher program

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

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

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

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

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

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

Signals Recognized by ypwatcher

signal number description

SIGBUS 7 Bus error.

SIGFPE 8 Floating Point exception.

SIGKILL 9 Kill

SIGSEGV 11 Invalid memory reference

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

2.1.11 Error Handling

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

The following CLI parameters affect error handling:

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

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

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

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

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

• incoming PDU validation

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

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



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

• server instrumentation PDU validation

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

• database validation

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

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

◦ The specific conditions checked automatically are:

▪ referential integrity condition test failed (must)

▪ missing leaf (mandatory)

▪ missing choice (mandatory)

▪ extra container or leaf

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

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

▪ instance not unique (unique)

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

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

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

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

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

• server instrumentation database validation and activation

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

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

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



2.1.12 Module Summary

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

Pre-loaded YANG Modules

module description

ietf-datastores NMDA datastore meta-data

ietf-origin NMDA <operational> origin meta-data

ietf-inet-types standard data types

ietf-netconf-acm standard NETCONF access control model

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

ietf-netconf-nmda NMDA <get-data> operation for NETCONF

ietf-netconf-notifications standard NETCONF notifications for system events

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

ietf-netconf-with-defaults <with-defaults> extension

ietf-yang-types standard data types

ietf-yang-library standard NETCONF YANG Module Library that represent the current set of modules and submodules.

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.This module is deprecated. It is enabled by default, but can be removed using --with-yuma-system=false

yuma-time-filter Get only if datastore changed since a specified timestamp

yumaworks-app-common Common definitions used by yumapro modules

yumaworks-attrs Extensions to add last-modified and etag attributes

yumaworks-config-change Add edit data to the netconf-config-change notification

yumaworks-extensions YANG extensions for meta-data data tagging

yumaworks-event-filter Event filters to suppress generation of notifications for the specified events



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

yumaworks-ids Session type extensions for the standard monitoring module

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

yumaworks-sil-sa Internal SIL-SA message definitions for subsystem module access callbacks

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

yumaworks-ycontrol Internal Ycontrol protocol for server to subsystem communication

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

Optional YANG Modules

module description

ietf-restconf-monitoring Monitoring information for the RESTCONF protocol. Build variable: WITH_RESTCONF=1

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

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

yuma-interfaces Yuma interfaces table. Build variable: WITH_YUMA_INTERFACES=1

yumaworks-server Allows server CLI parameters to be edited at run-time



2.1.13 Notification Summary

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

CLI Paramters for Notifications

Parameter Description

--eventlog-size Size of the replay buffer for the NETCONF event stream

--event-stream Configure a notification event stream

--event-stream-map Configure a module to event stream mapping

--idle-timeout Has no affect if notification delivery is active

--log-event-drops Report dropped notifications in the server log

--max-burst Control number of notifications sent at once to a receiver

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

--with-notifications Must be set to true to enable notification delivery

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

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

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

Pre-loaded Notifications for RFC 5277 and RFC 7895

module event type description

nc-notifications <replayComplete> Notification replay has ended

nc-notifications <notificationComplete> Notification delivery has ended

ietf-yang-library <yang-library-change> Set of modules or submodules in the YANG Library has changed

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


ietf-netconf-notifications <netconf-session-start> NETCONF session has started

ietf-netconf-notifications <netconf-session-end> NETCONF session has ended

ietf-netconf-notifications <netconf-config-change> <running> configuration has changed

ietf-netconf-notifications <netconf-capability-change> Server capabilities have changed



ietf-netconf-notifications <netconf-confirmed-commit> Confirmed commit procedure event

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


yuma-system <sysStartup> server startup event

yuma-system <sysSessionStart> NETCONF session has started

yuma-system <sysSessionEnd> NETCONF session has ended

yuma-system <sysConfigChange> <running> configuration has changed

yuma-system <sysCapabilityChange> Server capabilities have changed

yuma-system <sysConfirmedCommit> Confirmed commit procedure event



2.1.14 Operation Summary

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

Pre-loaded Operations

module operation description

yumaworks-system <backup> Backup the running configuration to a file.

Ietf-netconf <cancel-commit> Cancel a confirmed-commit operation.

yumaworks-system <cancel-subscription> Cancel a notification subscription.

ietf-netconf <close-session> Terminate the current session.

ietf-netconf <commit> Activate edits in <candidate>.

ietf-netconf <copy-config> Copy an entire configuration.

notifications <create-subscription> Start receiving notifications.

yumaworks-system <delete-backup> Delete a backup configuration file.

ietf-netconf <delete-config> Delete a configuration.

ietf-netconf <discard-changes> Discard edits in <candidate>.

ietf-netconf <edit-config> Edit the target configuration.

ietf-netconf <get> Retrieve <running> or state data.

ietf-netconf <get-config> Retrieve all or part of a configuration.

ietf-netconf-nmda <get-data> Retrieve data from an NMDA datastore

yumaworks-getbulk <get-bulk> Retrieve N list entries at a time

yumaworks-system <get-module-tags> Retrieve the installed module-tags

yuma-mysession <get-my-session> Retrieve session customization parameters.

ietf-netconf-monitoring <get-schema> Retrieve a YANG or YIN module definition file.

ietf-netconf <kill-session> Terminate a NETCONF session.

yuma-system <load> Load a YANG module and its SIL code [DEPRECATED]

yumaworks-system <load> Load a YANG module and its SIL code

yumaworks-system <load-bundle> Load a SIL bundle (SIL code + modules)

ietf-netconf <lock> Lock a database.

yuma-system <no-op> No operation. [DEPRECATED]

ietf-netconf-partial-lock <partial-lock> Lock part of the <running> database

ietf-netconf-partial-lock <partial-unlock> Unlock part of the <running> database

yuma-system <restart> Restart the server. [DEPRECATED]

yumaworks-system <restore> Restore the <running> database from a backup

yuma-system <set-log-level> Set the logging verbosity level [DEPRECATED]



yumaworks-system <set-log-level> Set the logging verbosity level.

yuma-mysession <set-my-session> Set the session customization parameters.

yuma-system <shutdown> Shutdown the server [DEPRECATED]

yumaworks-system <unload> Unload a YANG module and its SIL code

yumaworks-system <unload-bundle> Unload a SIL bundle, and all its YANG modules and SIL code

ietf-netconf <unlock> Unlock a database.

ietf-netconf <validate> Validate a database



2.1.15 Configuration Parameter List

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

netconfd-pro CLI Parameters

parameter description

--access-control Specifies how access control will be enforced

--allow-leaflist-delete-all Allow delete-all operations on leaf-list objects

--allow-list-delete-all Allow delete-all operations on list objects

--allowed-user Limits sessions to specified user names

--alt-names Specifies whether the server will recognize the 'alt-name' YANG extensionwhich 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 loadis done.

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

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

--audit-log-candidate Record transactions on the candidate datastore or not

--audit-log-console-level Minimum debug level to generate console audit log messages

--audit-log-events Select which events are recorded in the audit log

--audit-log-level Minimum debug level to generate audit log messages

--autodelete-pdu-error Treat false when-stmts in the edit PDU as errors

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

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

--callhome-reconnect Specifies whether server will reconnect after client closes the session

--callhome-retry-interval Specifies the number of seconds to wait after a connect attempt to the callhome server has failed before attempting another conect attempt to thatserver.

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

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

--callhome-sshd-command Specifies the command used in Call Home to invoke the SSH server

--callhome-sshd-config Specifies the filespec for the config file used in Call Home to invoke the SSH server

--callhome-subsys-command Specifies the command used in Call Home to invoke the netconf subsystem

--callhome-tls-server Specifies a NETCONF over TLS CallHome server



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

--cert-usermap Specifies a user-name to certificate mapping

--confdir Specifies the directory for extra configuration parameter files

--config Specifies the configuration file to use for parameters

--convert-subtree-filter Convert subtree filters to XPath for internal processing

--create-empty-npcontainers Specifies that empty NP containers should be created or not

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

--db-lock-retry-interval Specifies the amount of time to wait before retrying a DB-Config-Lock

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

--default-style Specifies the default <with-defaults> behavior

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

--deviation Species a YANG module to load as a deviations module

--errmsg Specifies a language-specific error message

--errmsg-lang Specifies the error-message language to use

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

--event-stream Configure a notification event stream

--event-stream-map Configure a module to event stream mapping

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

--feature-disable Leaf list of features to disable

--feature-enable Specifies a feature that should be enabled

--feature-enable-default Specifies if a feature should be enabled or disabled by default

--fileloc-fhs Selects Filesystem Hierarchy Standard (FHS) directory locations

--ha-enabled Enable or disable the YP-HA feature

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

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

--ha-server-key Unique string identifying the YP-HA server pool

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

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

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

--hide-module Hide the specified module from clients

--home Overrides the $HOME environment variable

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

--import-version-bestmatch Enable import version best match feature

--indent Specifies the indent count to use when writing data



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

--library-mode Run the server in YANG library mode

--loadpath Sets the module load path

--log Specifies the log file to use instead of STDOUT. See the YumaPro User Manual for a general discussion of logging.

--log-append Controls whether a log file will be reused or overwritten.

--log-backtrace Append stack trace information to log messages.

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

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

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

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

--log-event-drops Indicates if log entry would be generated when a 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-cli-sessions Specifies the maximum number of concurrent CLI sessions allowed

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

--max-sessions Specifies the maximum number of concurrent sessions allowed

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

--message-indent Specifies the amount to indent in protocol messages

--modpath Sets the module search path

--module Specifies one or more YANG modules to load upon startup

--module-tagmap Specifies a module name to module-tag mapping

--netconf-capability Specifies a NETCONF capability URI to add to the server



--netconf-tls-address Specifies the IP address to listen for NETCONF over TLS sessions

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

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

--netconf-tls-port Specifies the TCP port to list for NETCONF over TLS sessions

--netconf-tls-trust-store Specifies the trust store file or directory for NETCONF over TLS

--no-config If present, ignore the default configuration file

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

--no-nvstore Disable internal NV-load and NV-store operations

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

--no-watcher Disable the ypwatcher program

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

--protocols Specifies which NETCONF protocol versions to enable

--restconf-capability Specifies a RESTCONF capability URI to add to the server

--restconf-default-encoding Specifies the default response message encoding for RESTCONF

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

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

--runpath Server instrumentation library (SIL) search path

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

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

--server-id String identifying the server in the YP-HA server pool

--session-sync-mutex If present, will force synchronous request processing (pthread version only)

--sil-delete-children-first Specifies that the SIL callbacks for child nodes should be called on delete operations

--sil-invoke-for-defaults Specifies whether SIL callbacks are invoked for loading defaults

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

--sil-prio-reverse-for-deletes Specifies whether the SIL callbacks are invoked in reserved order for deletes or not.

--sil-root-check-first Force the YANG validation checks to be done before the SIL validate callbacks

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

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



--sil-validate-candidate Controls whether SIL callbacks will be done for the candidate datastore

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

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

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

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

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

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

--startup-factory-file Specifies the YANG configuration to use as the factory default config

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

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

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

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

--superuser Specifies the user name to be given super user privileges. If ‘superuser’ is configured in your netconfd-pro.conf file, then that value will be overridenby your command line value.

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

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

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

--tls-crl-missing-ok Specifies whether missing CRL Distribution Point is an error

--tls-crl-mode Specifies how Certificate Revocation List processing is done

--trim-whitespace Specifies if leading and trailing XML whitespace should be trimmed

--usexmlorder Forces strict YANG XML ordering to be enforced

--version Prints the program version and exits

--warn-error Treat all warnings as errors

--warn-idlen Controls how identifier lengths are checked

--warn-linelen Controls how line lengths are checked

--warn-off Suppresses the specified warning number



--warn-up Elevates the specified warning number to an error

--watcher-interval Specifies the sleep interval between ypwatcher program attempts to checkavailability 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 keyleaf.

--with-callhome Enable or disable the IETF CallHome protocol

--with-canonical Enable or disable automatic conversion to canonical data type format

--with-config-id Enable or disable the :config-id capability URI

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

--with-gnmi Enable or disable the gNMI protocol

--with-maintenance-mode Enable or disable allowing maintenance mode to be used

--with-modtags Enable or disable module-tags feature

--with-netconf Enable or disable the NETCONF over SSH protocol

--with-netconf-tls Enable or disable the NETCONF over TLS protocol

--with-nmda Enable or disable NMDA support

--with-notifications Controls whether the server will support the :notifications and :interleave capabilities or not.

--with-ocpattern Controls whether OpenConfig pattern syntax will be checked

--with-restconf Enable or disable the RESTCONF protocol

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

--with-startup Enable or disable the <startup> database

--with-support-save Enable or disable the yumaworks-support-save YANG module

--with-term-msg Enable <term-msg> notification

--with-url Enable or disable the :url capability

--with-url-ftp Enable or disable FTP scheme in <url> parameter

--with-url-tftp Enable or disable TFTP scheme in <url> parameter

--with-validate Enable or disable the :validate capability

--with-warnings Enable or disable the error-severity field set to warning

--with-yang-api Enable or disable the YANG-API protocol

--with-tp-coap Enable the YP-COAP protocol

--with-tp-coap-dtls Enable the YP-COAP over DTLS protocol

--with-yp-shell Enable or disable the YP-SHELL protocol

--with-yuma-time-filter Enable or disable the yuma-time-filter YANG module

--with-yuma-system Enable or disable the yuma-system YANG module

--with-yumaworks-config-change

Enable or disable the yumaworks-config-change YANG module

--with-yumaworks-event-filter Enable or disable the yumaworks-event-filter YANG module



--with-yumaworks-getbulk Enable or disable the yumaworks-getbulk YANG module

--with-yumaworks-ids Enable or disable the yumaworks-ids YANG module

--with-yumaworks-system Enable or disable the yumaworks-system YANG module

--with-yumaworks-templates Enable or disable the yumaworks-templates YANG module

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

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

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

--yp-coap-dtls-port UDP port to use for YP-CoAP over DTLS protocol

--yp-coap-port UDP port to use for YP-CoAP protocol



2.1.16 Editing CLI Parameters at Run-Time

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

netconfd-pro {

module yumaworks-server

}

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

> merge /server/max-sessions value=10

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

• allowed-user

• eventlog-size

• hello-timeout:

• idle-timeout

• log-level

• max-burst

• max-cli-sessions: affects new sessions only

• max-getbulk

• max-sessions: affects new sessions only

• subsys-timeout

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

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

• The server has write permissions to rewrite the configuration file

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



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

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

2.1.17 Using logrotate to Manage Log Files

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

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

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

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

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

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

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

/var/log/netconfd-pro/*.log {size 1Mmissingokrotate 4compressdelaycompress

copytruncate notifempty

lastaction /bin/kill -USR2 `cat /var/run/netconfd-pro/netconfd-pro.pid`

endscript}



2.1.18 Evaluation Version Restrictions

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

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

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

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

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



2.1.19 Maintenance Mode

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

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

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



2.1.20 Disabling YumaWorks YANG Modules

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

CLI Parameter Modules Affected Description

--hide-module any Hide the specified module from client discovery. Does notaffect data returned to clients.

--with-support-save yumaworks-support-save

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

--with-term-msg yumaworks-term-msg <term-msg> notification used to support yp-shell terminaldiagnostic messages

--with-yuma-system yuma-systemyuma-app-commonyuma-typesyuma-ncx

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

--with-yuma-time-filter yuma-time-filter if-modified-since filter for <get> and <get-config>

--with-yumaworks-config-change

yumaworks-config-change

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

--with-yumaworks-event-filter

yumaworks-event-filteryuma-typesyuma-ncx

<event-filters> container to drop specific event types

--with-yumaworks-getbulk yumaworks-getbulkyumaworks-restconf

<get-bulk> operation to retrieve YANG list entries

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

--with-yumaworks-system yumaworks-systemyuma-app-commonyuma-ncxyuma-typesyumaworks-app-commonyumaworks-restconf

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

--with-yumaworks-templates

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



2.1.21 DB-Config-Lock Mode

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

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

• --with-db-lock=true required to use DB-Config-Lock.

• --db-lock-retry-interval, --db-lock-timeout, and --subsys-timeout affect how long the server will wait for a DB-Config-Lock.

The DB-Config-Lock is described in the YANG module yumaworks-db-api.yang. The following DB-API messages are used:

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

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

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

Configuration edits by all clients are affected by this lock.



2.1.22 Deferred Configuration Load Mode

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

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

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

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

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

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



2.2 Capabilities

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

2.2.1 :base:1.0

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

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

This capability is supported by default.

2.2.2 :base:1.1

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

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

This capability is supported by default.

2.2.3 :candidate

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

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

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

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

2.2.4 :config-id

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

2.2.5 :confirmed-commit

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

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

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

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



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

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

2.2.6 :interleave

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

2.2.7 :netconf-monitoring

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

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

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

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

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

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

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

2.2.8 :notification

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

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

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

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

The first notification in the log will be for the <sysStartup> event.

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

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



2.2.9 :partial-lock

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

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

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

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

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

There is no hard resource limit for:

• the number of total partial-locks

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

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

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

2.2.10 :rollback-on-error

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

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

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

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

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

2.2.11 :schema-retrieval

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

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

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

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

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



2.2.12 :startup

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

By default, this capability is not supported.

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

If this capability is supported:

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

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

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

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

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

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:

• validate:1.0

• validate:1.1

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

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

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

• validate the <running> database

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

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

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

• set: This option is not the default, but it is probably the desired behavior for the <candidate> database. In order to fully utilize the incremental editing capability of this database, the 'set' value should be used. This will prevent anyvalidation error messages unrelated to the current edit. The <validate> operation can be used before the <commit> is done, if desired. The same errors (if any) should be reported by <validate> or <commit>.

• test-then-set: This option is the default, and will cause a resource intensive validation procedure to be invoked every time the <candidate> database is edited. (The validation procedure is always invoked on every edit to the <running> configuration.) If any database validation errors are found (in addition to the requested edit), then they will be reported. Use the <error-path> field to determine which type of error is being reported by the server.



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:

• edit-config

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

• copy-config

◦ <url> accepted as a source parameter.

◦ <url> accepted as a target paramter.

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

• delete-config:

◦ <url> accepted as source to delete

• validate

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

Schemes:

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

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

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

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

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

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

The $YUMAPRO_DATAPATH environment variable or the $$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:

• <get>

• <get-config>

• <copy-config>

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

• report-all: all nodes are reported

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

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

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

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

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:

• the current() function from XPath 2.0 is supported

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

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

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

The server will normalize the XPath search results it returns:

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

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

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

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.

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

• <running>: configuration data in effect

• <startup>: configuration data for the next reboot

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

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

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

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

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

• :candidate



• :writable-running

• :startup

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

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

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

2.3.1 Database Locking

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

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

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

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

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

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

2.3.2 Using the <candidate> Database

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

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

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

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

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

2.3.3 Using the <running> Database

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

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

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



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

2.3.4 Using the <startup> Database

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

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

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

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



2.4 Sessions

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

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

2.4.1 User Names

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

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

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

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

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

2.4.2 Session ID

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

typedef SessionId { description "NETCONF Session Id"; type uint32 {

range "1..max"; }}

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



2.4.3 Server <hello> Message

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

The server will list all the capabilities it supports.

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

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

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

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

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

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

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

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

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

Example server <hello> Message:

<?xml version="1.0" encoding="UTF-8"?><hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <capabilities> <capability>urn:ietf:params:netconf:base:1.0</capability> <capability>urn:ietf:params:netconf:base:1.1</capability> <capability>urn:ietf:params:netconf:capability:candidate:1.0</capability> <capability>urn:ietf:params:netconf:capability:confirmed-commit:1.0</capability> <capability>urn:ietf:params:netconf:capability:confirmed-commit:1.1</capability> <capability>urn:ietf:params:netconf:capability:rollback-on-error:1.0</capability> <capability>urn:ietf:params:netconf:capability:validate:1.0</capability> <capability>urn:ietf:params:netconf:capability:validate:1.1</capability> <capability>urn:ietf:params:netconf:capability:url:1.0?scheme=file</capability> <capability>urn:ietf:params:netconf:capability:xpath:1.0</capability> <capability>urn:ietf:params:netconf:capability:notification:1.0</capability> <capability>urn:ietf:params:netconf:capability:interleave:1.0</capability> <capability>urn:ietf:params:netconf:capability:partial-lock:1.0</capability> <capability>urn:ietf:params:netconf:capability:with-defaults:1.0?basic-mode=explicit&also-supported=trim,report-all,report-all-tagged</capability> <capability>urn:yumaworks:params:xml:ns:netconf:config-id?id=127</capability> <capability>urn:ietf:params:xml:ns:netconf:base:1.0?module=ietf-netconf&revision=2011-06-01&features=candidate,confirmed-commit,rollback-on-error,validate,url,xpath</capability> <capability>urn:ietf:params:xml:ns:yang:iana-crypt-hash?module=iana-crypt-hash&revision=2014-08-06&features=crypt-hash-md5,crypt-hash-sha-256,crypt-hash-sha-512</capability> <capability>urn:ietf:params:xml:ns:yang:ietf-inet-types?module=ietf-inet-types&revision=2013-07-15</capability> <capability>urn:ietf:params:xml:ns:yang:ietf-netconf-acm?module=ietf-netconf-acm&revision=2018-02-14</capability>



<capability>urn:ietf:params:xml:ns:yang:ietf-netconf-monitoring?module=ietf-netconf-monitoring&revision=2010-10-04</capability> <capability>urn:ietf:params:xml:ns:yang:ietf-netconf-notifications?module=ietf-netconf-notifications&revision=2012-02-06</capability> <capability>urn:ietf:params:xml:ns:netconf:partial-lock:1.0?module=ietf-netconf-partial-lock&revision=2009-10-19</capability> <capability>urn:ietf:params:xml:ns:yang:ietf-netconf-with-defaults?module=ietf-netconf-with-defaults&revision=2011-06-01</capability> <capability>urn:ietf:params:xml:ns:yang:ietf-restconf?module=ietf-restconf&revision=2017-01-26</capability> <capability>urn:ietf:params:xml:ns:yang:ietf-restconf-monitoring?module=ietf-restconf-monitoring&revision=2017-01-26</capability> <capability>urn:ietf:params:xml:ns:yang:ietf-yang-library?module=ietf-yang-library&revision=2016-06-21</capability> <capability>urn:ietf:params:xml:ns:yang:ietf-yang-patch?module=ietf-yang-patch&revision=2017-02-22</capability> <capability>urn:ietf:params:xml:ns:yang:ietf-yang-types?module=ietf-yang-types&revision=2013-07-15</capability> <capability>urn:ietf:params:xml:ns:netmod:notification?module=nc-notifications&revision=2008-07-14</capability> <capability>urn:ietf:params:xml:ns:netconf:notification:1.0?module=notifications&revision=2013-03-15</capability> <capability>urn:ietf:params:xml:ns:yang:yang-data-ext?module=yang-data-ext&revision=2017-07-03</capability> <capability>http://netconfcentral.org/ns/yuma-app-common?module=yuma-app-common&revision=2017-07-25</capability> <capability>http://netconfcentral.org/ns/yuma-ncx?module=yuma-ncx&revision=2015-10-16</capability> <capability>http://netconfcentral.org/ns/yuma-system?module=yuma-system&revision=2013-07-15</capability> <capability>http://netconfcentral.org/ns/yuma-time-filter?module=yuma-time-filter&revision=2012-11-15</capability> <capability>http://netconfcentral.org/ns/yuma-types?module=yuma-types&revision=2019-11-29</capability> <capability>http://yumaworks.com/ns/yumaworks-app-common?module=yumaworks-app-common&revision=2019-05-22</capability> <capability>http://yumaworks.com/ns/yumaworks-event-filter?module=yumaworks-event-filter&revision=2014-02-09</capability> <capability>http://yumaworks.com/ns/yumaworks-extensions?module=yumaworks-extensions&revision=2019-01-04</capability> <capability>http://yumaworks.com/ns/yumaworks-getbulk?module=yumaworks-getbulk&revision=2018-04-06</capability> <capability>http://yumaworks.com/ns/yumaworks-ids?module=yumaworks-ids&revision=2014-07-12</capability> <capability>urn:ietf:params:xml:ns:yang:yumaworks-restconf?module=yumaworks-restconf&revision=2017-07-03</capability> <capability>urn:ietf:params:xml:ns:yang:yumaworks-support-save?module=yumaworks-support-save&revision=2017-07-27</capability> <capability>http://yumaworks.com/ns/yumaworks-system?module=yumaworks-system&revision=2019-01-22</capability> <capability>http://yumaworks.com/ns/yumaworks-templates?module=yumaworks-templates&revision=2017-02-20</capability> <capability>http://yumaworks.com/ns/yumaworks-term-msg?module=yumaworks-term-msg&revision=2019-05-05</capability> <capability>http://yumaworks.com/ns/yumaworks-types?module=yumaworks-types&revision=2018-05-03</capability> <capability>urn:ietf:params:netconf:capability:yang-library:1.0?revision=2016-06-21&module-set-id=3783</capability> </capabilities> <session-id>3</session-id></hello>

2.4.4 Client <hello> Message

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

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

The server can be configured with the --protocols CLI parameter to enable the 'base:1.0', and/or the 'base:1.1' NETCONF protocol versions. Both the client and server send the 'base:1.x' (where 'x' is '1' or '2') URIs they support (1 or 2 <capability> elements). The highest version in common determines the protocol version used for the session. If there are no common versions found, the session will be dropped. By default, the server will enable both protocol versions.

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

Client <hello> Server <hello> Outcome

[ none ] [ any combination ] Session dropped

[ base:1.0 ] [ base:1.0 ] base:1.0 session started

[ base:1.1 ] [ base:1.0 ] Session dropped

[ base:1.0 base:1.1] [ base:1.0 ] base:1.0 session started

[ base:1.0 ] [ base:1.1 ] Session dropped

[ base:1.1 ] [ base:1.1 ] base:1.1 session started

[ base:1.0 base:1.1] [ base:1.1 ] base:1.1 session started

[ base:1.0 ] [ base:1.0 base:1.1 ] base:1.0 session started

[ base:1.1 ] [ base:1.0 base:1.1 ] base:1.1 session started

[ base:1.0 base:1.1] [ base:1.0 base:1.1 ] base:1.1 session started



Example client <hello> Message:

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



2.4.5 RPC Request Processing

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

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

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

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

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

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

Access control will be enforced as follows:

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

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

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

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

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

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

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

The server does not generate inline <rpc-error> elements at this time, for any runtime exceptions that occur while retrievingdata 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:

• <close-session> operation invoked

• <kill-session> operation invoked

• SSH session terminated unexpectedly

• TCP connection terminated unexpectedly

When a session terminates, the server does the following:

• will release any locks the session had (if any)

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

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

• will generate a <sysSessionEnd> notification entry for the closed or killed session



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

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

<error-app-tag> Summary

error-app-tag description

data-incomplete the input parameters are incomplete

data-invalid one or more input parameters are invalid

data-not-unique unique statement violation (YANG, sec. 13.1)

duplicate-error trying to create a duplicate list or leaf-list entry

general-error no other description fits

instance-required missing mandatory node (YANG, sec. 13.5)

internal-error internal software error

io-error NETCONF session IO error

libxml2-error libxml2 internal error or parsing error

limit-reached some sort of defined limit was reached

malloc-error malloc function call failed

missing-choice mandatory choice not found (YANG, sec. 13.6)

missing-instance mandatory leaf not found (YANG, sec. 13.7)

must-violation must expression is false (YANG, sec. 13.4)

no-access access control violation

no-matches <get-schema> module or revision search failed

no-support operation or sub-operation not implemented

not-in-range YANG range test failed

not-in-value-set YANG enumeration or bits name is invalid

pattern-test-failed YANG pattern test failed

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

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

ssh-error SSH transport error



too-few-elements min-elements violation (YANG, sec. 13.3)

too-many-elements max-elements violation (YANG, sec. 13.2)

2.5.4 <error-path> Element

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

It is encoded as a YANG instance-identifier.

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

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

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

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

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

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



2.5.5 <error-message> Element

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

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

2.5.6 <error-info> Element

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

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

<error-info> Summary

child node description

<bad-attribute> name of the XML attribute that caused the error

<bad-element> name of the element that caused the error or contains the attribute that caused the error

<bad-value> value that caused the error

<error-number> internal error number for the error condition

<missing-choice> name of the missing mandatory YANG choice

<session-id> session number of the current lock holder



2.5.7 Dynamic Error Messages

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

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

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

The “errmsg” statement has 3 sub-statements:

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

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

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

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

errmsg Statements

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

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

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

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

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

Example:

leaf my-network-id { type int32;



ywx:errmsg 'Not a valid network ID for interface %s' { ywx:errmsg-parm '../../if:name'; ywx:errmsg-apptag 'network-error'; } }

"; argument basestr; }

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

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

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

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

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

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

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

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



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

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

module test-errmsg {

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

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

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

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

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

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



ywx:errmsg-parm "../test1"; ywx:errmsg-parm "."; ywx:errmsg-lang "fr"; } } } }

}

2.5.8 Using Annotations to Define Dynamic Error Messages

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

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

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

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

module errmsg-if {

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

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

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

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

} }

}



2.5.9 Replacing a Standard Error Message

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

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

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

The default error message is “invalid pattern”.

The errmsg parameter is a string with 3 fields: <errnum>:<lang>:<msg>.

where<errnum> is the error number

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

>msg> is the desired error message

To replace this default error message with the string “This is an invalid pattern specification”, use the errmsg parameter as follows:

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



2.5.10 Multi-Language Error Messages

The server can be configured to use error-message strings in a language other than English. The --errmsg parameter is a leaf-list that allows a static error message to be configured at boot-time. Each errmsg string contains an error number, language code, and error message. See the --errmsg CLI parameter for details.

This parameter must be used together with the --errmsg-lang parameter to select an error message language other than English. The Google Translate service is used to create the pre-configured language-specific errmsg configuration files (found in /usr/share/yumapro/util/errmsg-lang). The language codes used in this program correspond to the ISO-639-1 codes used by Google Translate:

https://cloud.google.com/translate/docs/languages

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

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

File Language

errmsg-cs.conf Czech

errmsg-da.conf Danish

errmsg-de.conf German

errmsg-en.conf English

errmsg-es.conf Spanish

errmsg-fr.conf French

errmsg-he.conf Hebrew

errmsg-hu.conf Hungarian

errmsg-it.conf Italian

errmsg-ja.conf Japanese

errmsg-ko.conf Korean

errmsg-nl.conf Dutch

errmsg-no.conf Norwegian

errmsg-pl.conf Polish

errmsg-ru.conf Russian

errmsg-sr.conf Serbian

errmsg-zh-CN.conf Chinese

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

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


https://cloud.google.com/translate/docs/languages


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

Example: Set up French error messages:

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

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

netconfd-pro { errmsg-lang fr

}



2.5.11 Instance-Required Error Example

The instance-required error-app-tag is generated when a YANG leaf is mandatory, but was not set. An error will be returnedright 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:

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

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

Example Error Reply:

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



<nc:error-path>/t:test2/t:a2</nc:error-path> <nc:error-message xml:lang="en">required value instance not found</nc:error-message> <nc:error-info> <ncx:error-number>310</ncx:error-number> </nc:error-info> </nc:rpc-error> </nc:rpc-reply>



2.5.12 Missing-Choice Error Example

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

missing-choice error

data description

error-tag data-missing

error-app-tag missing-choice

error-path identifies the parent of the missing choice

error-info <missing-choice>

error-number 296

Example Request:

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

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


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



<nc:error-message xml:lang="en">missing mandatory choice</nc:error-message> <nc:error-info> <y:missing-choice xmlns:y="urn:ietf:params:xml:ns:yang:1">musttest</y:missing-choice> <ncx:error-number>296</ncx:error-number> </nc:error-info> </nc:rpc-error> </nc:rpc-reply>



2.5.13 No-Matches Error Example

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

No Matches

data description

error-tag operation-failed

error-app-tag no-matches

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

error-info <bad-value>

error-number 365

Example Request:

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

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


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



2.5.14 not-in-range Error Example

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

not-in-range

data description

error-tag invalid-value

error-app-tag not-in-range

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

error-info <bad-value>

error-number 288

Example Request:

• create /int8.1 value=1000

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


<?xml version="1.0" encoding="UTF-8"?> <rpc-reply message-id="4" trace-id="4" xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns:t="http://netconfcentral.org/ns/test" xmlns:ncx="http://netconfcentral.org/ns/yuma-ncx" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">



<rpc-error> <error-type>protocol</error-type> <error-tag>invalid-value</error-tag> <error-severity>error</error-severity> <error-app-tag>not-in-range</error-app-tag> <error-path>/nc:rpc/nc:edit-config/nc:config/t:int8.1</error-path> <error-message xml:lang="en">value not in range</error-message> <error-info> <bad-value xmlns="http://netconfcentral.org/ns/yuma-ncx">1000</bad-value> <error-number xmlns="http://netconfcentral.org/ns/yuma-ncx">288</error-number> </error-info> </rpc-error> </rpc-reply>



2.6 Protocol Operations

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

Every protocol operation is defined with a YANG rpc statement.

All NETCONF operations and several proprietary operations are supported,

2.6.1 <backup>

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

Only local files are supported.

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

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

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

<backup> operation

Min parameters: 1

Max parameters: 2

Return type: status

YANG file: yumaworks-system.yang

Capabilities needed: none

Mandatory Parameters:

• filename:

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

Optional Parameters:

• overwrite:

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

Returns:

• <ok/>

Possible Operation Errors:

• none

Example Request:



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

Example Reply:

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



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


• none


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

Returns:

• <ok/>


• none

Example Request:

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

Example Reply:

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



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


• none


• none

Returns:

• <ok/>


• none

Example Request:

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

Example Reply:

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



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



• none


• none

Returns:

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


• none

Example Request:

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

Example Reply:




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:

• confirmed-commit:1.0

• confirmed-commit:1.1

<commit> operation

Min parameters: 0

Max parameters: 4

Return type: status


Capabilities needed: :candidate:confirmed-commit


• none


• confirmed:

◦ type: empty

◦ default: none

◦ capabilities needed: confirmed-commit

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

• confirm-timeout:

◦ type: number

◦ default: 600

◦ capabilities needed: confirmed-commit



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

• persist:

◦ type: string

◦ default: none

◦ capabilities needed: confirmed-commit and base:1.1

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

• persist-id:

◦ type: string

◦ default: none

◦ capabilities needed: confirmed-commit and base:1.1

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

Returns:

• <ok/>


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

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

• operation-failed

◦ must-violation: must statement is false

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

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

◦ data-not-unique: unique statement violation

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

Example Request:

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

Example Reply:




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.

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

• If the <target> is the <candidate> or <running> configuration, then the new configuration is applied as if the operation was an <edit-config> operation with a <default-operation> parameter set to 'replace'. All validation and access control procedures are followed.

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

<copy-config> operation

Min parameters: 2

Max parameters: 3

Return type: status



Capabilities optional: :candidate:writable-running:startup:url


• source

◦ type: container with 1 of N choice of leafs

◦ usage: mandatory

◦ default: none

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

◦ container contents: 1 of N:

▪ candidate

• type: empty



• capabilities needed: :candidate

▪ running

• type: empty

• capabilities needed: none

▪ startup

• type: empty

• capabilities needed: startup

▪ config:

• type: container (in-line configuration data)


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

▪ url:

• type: inet:uri

• capabilities need: :url

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

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

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

• target



◦ default: none

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


▪ candidate

• type: empty


▪ startup

• type: empty


▪ url:

• type: inet:uri

• capabilities need: :url

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

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



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


• with-defaults

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

◦ default: none

◦ capabilities needed: with-defaults

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

• with-owners

◦ type: empty

◦ default: not present (false)

◦ capabilities needed: none

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

• depth:

◦ type: union (uint32, ‘unbounded’)

◦ default: unbounded


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

Returns:

• <ok/> or <rp-error>


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

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

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

Example Request:

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



Example Reply:




2.6.7 <create-subscription>

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

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

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

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

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

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

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

<create-subscription> operation

Min parameters: 0

Max parameters: 4

Return type: status

YANG file: notifications.yang

Capabilities needed: :notification

Capabilities optional: :interleave


• none


• stream

◦ type: string

◦ default: 'NETCONF'

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

• filter

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

◦ default: none

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

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



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

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

• startTime

◦ type: yang:date-and-time

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

• stopTime

◦ type: yang:date-and-time

◦ usage: not allowed unless startTime is also present

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

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

Returns:

• <ok/>


• access-denied

• subscription already active

Example Request:

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

Example Reply:




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.



<delete-backup> operation

Min parameters: 1

Max parameters: 1

Return type: status




• filename:



• none

Returns:

• <ok/>


• none

Example Request:

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

Example Reply:

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






2.6.9 <delete-config>

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


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


Capabilities needed: :startup


• target


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

◦ container contents: 1 empty leaf value supported:

▪ startup


• none

Returns:

• <ok/>


• access-denied

• in-use: <startup> database is locked

Example Request:

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



</nc:target> </nc:delete-config> </nc:rpc>

Example Reply:




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


Capabilities needed: :candidate


• none


• none

Returns:

• <ok/>


• access-denied

Example Request:

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

Example Reply:

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



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


Capabilities needed: :candidate or :writable-running

Capabilities optional: :rollback-on-error:validate


• config

◦ type: anyxml

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

• target


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

◦ container contents: choice: 1 of N:

▪ candidate

• type: empty


▪ running

• type: empty

• capabilities needed: :writable-running


• default-operation



◦ type: enumeration (merge replace none)

◦ default: merge

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

• error-option

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

◦ default: stop-on-error

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

•

• test-option

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

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

Returns:

• <ok/>


• access-denied

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

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

Example Request:

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

Example Reply:




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

Return type: data



Capabilities optional: :candidate:startup:with-defaults


• none


• filter

◦ type='subtree'

▪ type: anyxml

▪ This parameter specifies the subset of the database that should be retrieved.

◦ type='xpath' select='expr'

▪ type: empty

▪ The unqualified select attribute is used to specify an XPath filter.

• with-defaults


◦ usage: --default-style configuration parameter used as the default if no value is provided

◦ This parameter controls how default leaf and leaf-list nodes are returned by the server.



• if-modified-since

◦ type: date-and-time

◦ usage: optional

◦ This parameter requests that configuration data only be returned if any of the running datastore contents have been modified since this value. Monitoring data (config = false) does not affect the datastore timestamp. If therunning datastore has not been modified since this timestamp, then an empty <data> element will be returned, and the request will not be processed.

• with-owners

◦ type: empty




• depth:





• module-tag:

◦ type: string

◦ default: none


◦ This parameter is used as a filter to include only data nodes from modules that match the module-tag value. Multiple module-tag parameters can be used, combined to form a logical OR expression. At least one module-tag must match or no data will be returned. This filter is combined with the XPath or subtree filter, if present.

Returns:

• <data> element


• access-denied

• invalid-value

Example subtree Filter Request:

<?xml version="1.0" encoding="UTF-8"?> <nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="4"> <nc:get> <nc:filter type="subtree"> <proc:proc xmlns:proc="http://netconfcentral.org/ns/proc"> <proc:cpuinfo>



<proc:cpu> <proc:cpu_MHz/> </proc:cpu> </proc:cpuinfo> </proc:proc> </nc:filter> </nc:get> </nc:rpc>

Equivalent XPath Filter Request:

<?xml version="1.0" encoding="UTF-8"?> <nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="4"> <nc:get> <nc:filter type="xpath" select="/proc/cpuinfo/cpu/cpu_MHz"/> </nc:get> </nc:rpc>]

Example Reply:

<?xml version="1.0" encoding="UTF-8"?> <nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" last-modified="2011-08-21T17:51:46Z" message-id="4"> <nc:data> <proc:proc xmlns:proc="http://netconfcentral.org/ns/proc"> <proc:cpuinfo> <proc:cpu> <proc:cpu_MHz>1600.000</proc:cpu_MHz> <proc:processor>0</proc:processor> </proc:cpu> <proc:cpu> <proc:cpu_MHz>2667.000</proc:cpu_MHz> <proc:processor>1</proc:processor> </proc:cpu> </proc:cpuinfo> </proc:proc> </nc:data> </nc:rpc-reply>



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.

The list-test parameter allows an XPath boolean expression to be used to test each list-target entry. It is used to select only asubset of the list entries to reduce the number of entries returned.


get-bulk> operation

Min parameters: 1

Max parameters: 8

Return type: data

YANG file: yumaworks-getbulk.yang

Capabilities needed: none (WITH_RESTCONF=1)



• list-target

◦ type: string (RESTCONF path URI)


◦ This parameter identifies the list object that is being retrieved. This must be a path expression used to representa list data node. It is formated like a RESTCONF path expression, except module names are not mandatory if they are unique.


• datastore

◦ type: enumeration (candidate running startup)

◦ usage: optional

◦ default: running

◦ This parameter specifies the name of the source database for the retrieval operation. It is ignored if the list-target specifies a non-configuration data node.

◦ enum: candidate



▪ capabilities needed: :candidate

◦ enum : running

▪ capabilities needed: none

◦ enum: startup

▪ capabilities needed: :startup

• count

◦ type: unint32

◦ usage: optional

◦ default: 1

◦ The maximum number of list entries to return.

• content

◦ type: enumeration

◦ usage: optional

◦ default: all

◦ This parameter specifies which type of content to include, exactly the same as the RESTCONF “content” query parameter

▪ enum: config

• Include only config=true descendant data nodes

▪ enum: nonconfig

• include only config=false descendant data nodes

▪ enum: all

• include all descendant data nodes

• depth

◦ type: uint32

◦ usage: optional


◦ This parameter is used as defined in the RESTCONF protocol. The value '1' is associated with the list-object node itself. This value can be used to simply test for the existence of any instances of the list-object.

• with-defaults




• last-keys

◦ type: container of leafs

◦ usage: optional

◦ default: start with the first list entry if this parameter not present



◦ This parameter contains the key values of a list entry to start the search from. Usually this is the same as the <last-keys> container returned from the previous call to <get-bulk>.. The leafs must be in the same order as defined in the YANG list, and all key leafs must be present.

• list-test

◦ type: leaf containing an XPath expression

◦ usage: optional

◦ default: return all selected list-target entries

◦ This parameter contains an XPath expression. The document root and the context node are set to the list instance being tested.The expression can only reference descendant-or-self nodesThe XPath result will be converted with the boolean() function if needed 'true' boolean result : include list instance 'false' boolean result: exclude list instance

Example yangcli-pro usage to get up to 10 'ietf' modules from the YANG library

> get-bulk count=10 list-target=/modules-state/module \ list-test=”starts-with(name, 'ietf')”

Returns:

• <bulk> element

◦ <data> element

▪ Contains the requested list entries. Each child element in this container will represent one instance of the list object requested by the list-target parameter.

◦ <last-keys> element

▪ Contains the key leafs from the last list entry in the <data> element. This container can be passed back to the server as the <last-keys> parameter to continue the retrieval at the entry after the one specified by the key leafs in this container.


• access-denied

• invalid-value

Example get-bulk Request:

<?xml version="1.0" encoding="UTF-8"?> <rpc message-id="1" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <get-bulk xmlns="http://yumaworks.com/ns/yumaworks-getbulk"> <list-target>/modules/module</list-target> <count>2</count> </get-bulk> </rpc>



Example Reply:

<rpc-reply message-id="1" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <bulk xmlns="http://yumaworks.com/ns/yumaworks-getbulk"> <data> <module xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-library"> <name>ietf-netconf</name> <revision>2011-06-01</revision> <namespace>urn:ietf:params:xml:ns:netconf:base:1.0</namespace> <feature>candidate</feature> <feature>confirmed-commit</feature> <feature>rollback-on-error</feature> <feature>validate</feature> <feature>url</feature> <feature>xpath</feature> <conformance>true</conformance> </module> <module xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-library"> <name>iana-crypt-hash</name> <revision>2014-08-06</revision> <schema> http://localhost/restconf/yang/iana-crypt-hash/2014-08-06</schema> <namespace>urn:ietf:params:xml:ns:yang:iana-crypt-hash</namespace> <feature>crypt-hash-md5</feature> <feature>crypt-hash-sha-256</feature> <feature>crypt-hash-sha-512</feature> <conformance>true</conformance> </module> </data> <last-keys xmlns="http://yumaworks.com/ns/yumaworks-getbulk"> <name xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-library">iana-crypt-hash</name> <revision xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-library">2014-08-06</revision> </last-keys> </bulk> </rpc-reply>

The client can then save the <last-keys> container to continue the retrieval with entry #3 and #4

<?xml version="1.0" encoding="UTF-8"?> <rpc message-id="2" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <get-bulk xmlns="http://yumaworks.com/ns/yumaworks-getbulk"> <list-target>/modules/module</list-target> <count>2</count> <last-keys> <name xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-library">iana-crypt-hash</name> <revision xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-library">2014-08-06</revision> </last-keys> </get-bulk> </rpc>



Example Reply:

<?xml version="1.0" encoding="UTF-8"?> <rpc-reply message-id="2" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <bulk xmlns="http://yumaworks.com/ns/yumaworks-getbulk"> <data> <module xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-library"> <name>ietf-inet-types</name> <revision>2013-07-15</revision> <schema>http://localhost/restconf/yang/ietf-inet-types/2013-07-15</schema> <namespace>urn:ietf:params:xml:ns:yang:ietf-inet-types</namespace> <conformance>false</conformance> </module> <module xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-library"> <name>ietf-netconf-acm</name> <revision>2012-02-22</revision> <schema>http://localhost/restconf/yang/ietf-netconf-acm/2012-02-22</schema> <namespace>urn:ietf:params:xml:ns:yang:ietf-netconf-acm</namespace> <conformance>true</conformance> </module> </data> <last-keys xmlns="http://yumaworks.com/ns/yumaworks-getbulk"> <name xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-library">ietf-netconf-acm</name> <revision xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-library">2012-02-22</revision> </last-keys> </bulk> </rpc-reply>



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.



<get-config> operation

Min parameters: 1

Max parameters: 7

Return type: data





• source



◦ This parameter specifies the name of the source database for the retrieval operation.


▪ candidate

• type: empty


▪ running

• type: empty


▪ startup

• type: empty





• filter

◦ type='subtree'

▪ type: anyxml

▪ This parameter specifies the subset of the database that should be retrieved.

◦ type='xpath' select='expr'

▪ type: empty

▪ The unqualified select attribute is used to specify an XPath filter.

• with-defaults




• if-modified-since

◦ type: date-and-time

◦ usage: optional

◦ This parameter requests that configuration data only be returned if any of the specified datastore contents have been modified since this value. If the specified datastore has not been modified since this timestamp, then an empty <data> element will be returned, and the request will not be processed.

• with-owners

◦ type: empty




• depth:





• module-tag:

◦ type: string

◦ default: none


◦ This parameter is used as a filter to include only data nodes from modules that match the module-tag value. Multiple module-tag parameters can be used, combined to form a logical OR expression. At least one module-tag must match or no data will be returned. This filter is combined with the XPath or subtree filter, if present.

Returns:



• <data> element


• access-denied

• invalid-value

Example subtree Filter Request:

<?xml version="1.0" encoding="UTF-8"?> <nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="3"> <nc:get-config> <nc:source> <nc:candidate/> </nc:source> <nc:filter type="subtree"> <nacm:nacm xmlns:nacm="http://netconfcentral.org/ns/nacm"> <nacm:rules> <nacm:moduleRule/> </nacm:rules> </nacm:nacm> </nc:filter> </nc:get-config> </nc:rpc>

Equivalent XPath Filter Request:

<?xml version="1.0" encoding="UTF-8"?> <nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="3"> <nc:get-config> <nc:source> <nc:candidate/> </nc:source> <nc:filter type="xpath" select="/nacm/rules/moduleRule"/> </nc:get-config> </nc:rpc>

Example Reply:

<?xml version="1.0" encoding="UTF-8"?> <nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" last-modified="2011-08-21T17:51:46Z" message-id="3"> <nc:data> <nacm:nacm xmlns:nacm="http://netconfcentral.org/ns/nacm"> <nacm:rules> <nacm:moduleRule> <nacm:moduleName>netconf</nacm:moduleName> <nacm:allowed-rights>read exec</nacm:allowed-rights>



<nacm:allowed-group>nacm:guest</nacm:allowed-group> </nacm:moduleRule> <nacm:moduleRule> <nacm:moduleName>netconfd-pro</nacm:moduleName> <nacm:allowed-rights>read write exec</nacm:allowed-rights> <nacm:allowed-group>nacm:admin</nacm:allowed-group> <nacm:comment>access to shutdown and restart rpcs</nacm:comment> </nacm:moduleRule> <nacm:moduleRule> <nacm:moduleName>netconf</nacm:moduleName> <nacm:allowed-rights>read write exec</nacm:allowed-rights> <nacm:allowed-group>nacm:admin</nacm:allowed-group> <nacm:allowed-group>nacm:monitor</nacm:allowed-group> </nacm:moduleRule> </nacm:rules> </nacm:nacm> </nc:data> </nc:rpc-reply>



2.6.15 <get-data>

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

To select only specific subsets of all available data, use subtree or XPath filtering by providing a <subtree-filter> or <xpath-filter> parameter. Namespace prefixes are optional to use in XPath expressions. The netconfd-pro will figure out the proper namespace, if possible. If prefixes are used, then they must be valid XML prefixes with a namespace properly declared in the PDU.



<get-data> operation

Min parameters: 1

Max parameters: 7

Return type: data

YANG file: ietf-netconf-nmda.yang



CLI Parameters Needed --with-nmda=true


• datastore

◦ type: leaf containing a datastore-ref


◦ This parameter specifies the name of the source NMDA datasotre for the retrieval operation.

◦ enumeration:

▪ candidate


▪ running


▪ startup


▪ operational





• subtree-filter

◦ type: anydata

◦ This parameter specifies the subset of the database that should be retrieved.

◦ Cannot be used if xpath-filter present

• xpath-filter

◦ type: XPath 1.0 string

◦ This parameter specifies the subset of the database that should be retrieved.

◦ Cannot be used if subtree-filter present

• config-filter:

◦ type boolean

◦ Specifies the type of data based on config-stmt. Retrieve all data if this parameter is not present. This is a top-down filter. It will not select nodes within a subtree if the ancestor nodes do not match the filter.

◦ Only relevant if the datastore parameter is ‘operational’.

◦ If set to ‘false’ for any datastore other than ‘operational’ then an empty <data> element will be returned.

• origin-filter:

◦ type: leaf-list of type origin-ref..

◦ This parameter will select data nodes with the specified origin. This is a top-down filter. It will not select nodeswithin a subtree if the ancestor nodes do not match the filter.

◦ Cannot be used if negated-origin-filter present

◦ Can only be used if the datastore parameter is ‘operational’

• negated-origin-filter:

◦ type: leaf-list of type origin-ref..

◦ This parameter will select data nodes if they do not have the specified origin. This is a top-down filter. It will not select nodes within a subtree if the ancestor nodes do not match the filter.

◦ Cannot be used if origin-filter present


• max-depth:





• with-origin

◦ type: empty

◦ This parameter will cause the origin attribute to be added to data nodes returned by the server.




• with-defaults




Example Request:

<?xml version="1.0" encoding="UTF-8"?><rpc message-id="3" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <get-data xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-nmda"> <datastore xmlns:ds="urn:ietf:params:xml:ns:yang:ietf-datastores">ds:operational</datastore> <subtree-filter> <addresses xmlns="http://www.yumaworks.com/ns/taddress"> <address/> </addresses> </subtree-filter> <with-origin/> </get-data></rpc>

Example Reply:

<?xml version="1.0" encoding="UTF-8"?><rpc-reply message-id="3" xmlns:or="urn:ietf:params:xml:ns:yang:ietf-origin" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <data xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-nmda"> <addresses xmlns="http://www.yumaworks.com/ns/taddress"> <address or:origin="or:system"> <last-name>adams</last-name> <first-name>fred</first-name> <street>123 elm st.</street> <city>anytown</city> <zipcode or:origin="or:learned">90024</zipcode> <counter> <i>1</i> <c1>41</c1> <c2>42</c2> </counter> <counter> <i>2</i> <c1>43</c1> <c2>44</c2> </counter> </address> <address or:origin="or:system"> <last-name>adams</last-name> <first-name>zed</first-name>



<street>900 first st.</street> <city>anytown</city> <zipcode or:origin="or:learned">90024</zipcode> <counter> <i>1</i> <c1>45</c1> <c2>46</c2> </counter> <counter> <i>2</i> <c1>47</c1> <c2>48</c2> </counter> </address> <address or:origin="or:system"> <last-name>flintstone</last-name> <first-name>fred</first-name> <street>1200 bc drive</street> <city>bedrock</city> <zipcode or:origin="or:learned">10204</zipcode> <counter> <i>1</i> <c1>49</c1> <c2>50</c2> </counter> <counter> <i>2</i> <c1>51</c1> <c2>52</c2> </counter> </address> </addresses> </data></rpc-reply>



2.6.16 <get-module-tags>

The <get-module-tags> operation is used to retrieve the installed module-tag configuration.

The module-tag and module names associated with each tag, are returned in the output.

rpc get-module-tags { description "Get the list of configured module-tags. The --module-tagmap parameter is used to configure a module-tag."; output { list module-tag { key tag; leaf tag { type string; description "The module-tag value"; } leaf-list module { type string; description "A module-name mapped to this module-tag"; } } } }

<get-module-tags> operation

Min parameters: 0

Max parameters: 0

Return type: data

YANG file: yumaworks-system



• none


• none

Returns:

• <module-tag>

◦ type: list

◦ Refer to YANG definition for details




• access-denied

Example Request:

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

Example Reply:

<?xml version="1.0" encoding="UTF-8"?><rpc-reply message-id="3" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <module-tag xmlns="http://yumaworks.com/ns/yumaworks-system"> <tag>netconf</tag> <module>ietf-netconf-monitoring</module> </module-tag> <module-tag xmlns="http://yumaworks.com/ns/yumaworks-system"> <tag>restconf</tag> <module>ietf-restconf-monitoring</module> </module-tag></rpc-reply>



2.6.17 <get-my-session>

The <get-my-session> operation is used to retrieve session customization data for the current session.

The session indent amount, line size, and default behavior for the with-defaults parameter can be controlled at this time.

The module yuma-mysession must be enabled in the server configuration file or CLI parameters for this operation to be available.

<get-my-session> operation

Min parameters: 0

Max parameters: 0

Return type: data

YANG file: yuma-mysession.yang



• none


• none

Returns:

• <indent>

◦ type: int8 (range 0 .. 9)

◦ This parameter specifies the desired logging indent amount for the session.

◦ default: 2

• <linesize>

◦ type: uint32 (range 40 .. 1024)

◦ This parameter specifies the desired line length for the session.

◦ default: 72

• <with-defaults>

◦ type: enumeration (report-all report-all-tagged trim explicit)

◦ This parameter specifies the desired default with-defaults behavior for the session. The server-wide default value is set with the --default-style configuration parameter.

◦ default: --defaults-style value

• <message-indent>

◦ type: int8 (range -1 .. 9)

◦ This parameter specifies the desired message indent amount for the session.

◦ default: -1




• access-denied

Example Request:

<?xml version="1.0" encoding="UTF-8"?> <nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="2"> <myses:get-my-session xmlns:myses="http://netconfcentral.org/ns/mysession"/> </nc:rpc>

Example Reply:

<?xml version="1.0" encoding="UTF-8"?> <nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="2"> <myses:indent xmlns:myses="http://netconfcentral.org/ns/mysession"> 3 </myses:indent> <myses:linesize xmlns:myses="http://netconfcentral.org/ns/mysession"> 72 </myses:linesize> <myses:with-defaults xmlns:myses="http://netconfcentral.org/ns/mysession"> report-all </myses:with-defaults> <myses:message-indent xmlns:myses="http://netconfcentral.org/ns/mysession"> -1 </myses:message-indent> </nc:rpc-reply>



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


Capabilities needed: :schema-retrieval


• identifier

◦ type: string

◦ This parameter specifies the name of the module to retrieve.

▪ Do not use any path specification of file extension; just the module name is entered.

▪ The name is case-sensitive, and must be specified exactly as defined.

• version

◦ type: string

◦ This parameter specifies the version of the module to retrieve.

▪ This will be the most recent YANG revision date string defined in a module revision statement.

▪ If any version is acceptable, or if the specific version is not known, then use the empty string.

• format

◦ type: enumeration (XSD YANG YIN RNG)

◦ This parameter specifies the format of the module to be retrieved. Only the YANG format is supported.

▪ YANG: RFC 6020

▪ YIN: RFC 6020

Returns:

• <data> element (contents of the YANG file)


• access-denied



Example Request:

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

Example Reply:

<?xml version="1.0" encoding="UTF-8"?> <nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="55"> <ns:data xmlns:ns="urn:ietf:params:xml:ns:netconf:state"> *** entire contents of YANG module would be here, no extra indenting *** </ns:data> </nc:rpc-reply>



2.6.19 <get-support-save>

The <get-support-save> operation is used to retrieve technical support information from the server.

The XML data that is returned can be saved in a file and used by the support-save-app program to extract some data to help reproduce software issues.

This operation is tagged as nacm:default-deny-all, so normal users cannot invoke this operation.

If NACM is enabled then an explicit NACM rule must be used or a superuser session must be used. Otherwise the server will return an access-denied error.

Only one support-save operation can be in progress at once. A ‘resource-denied’ error is returned if another support-save operation is already in progress.

No duplicate local-names are allowed in the top-level child nodes of the support-save-data anydata container.

<support-save-data> Contents

container support-save-data { container bundles { list bundle { leaf name { type string; } leaf-list deviation { type string; } leaf-list module { type string; } } }

container capabilities -> /ietf-netconf-monitoring:netconf-state/capabilities

container config-data { container *name* (e.g. candidate) { anydata config; } }

container datastores -> /ietf-netconf-monitoring:netconf-state/datastores

container modules-state -> /ietf-yang-library:modules-state

container modules-text { list module { leaf name { type string; } leaf revision { type string; } leaf source { type string; } leaf submodule { type empty; } leaf text { type string; } } }

container program { leaf name { type string; } leaf version { type string; } }

container sessions -> /ietf-netconf-monitoring:netconf-state/sessions



container sils { list sil { leaf name { type string; } leaf revision { type string; } leaf bundle { type empty; } leaf sil-sa { type empty; } } }

container system -> /yuma-system:system container }

<get-support-save> operation

Min parameters: 0

Max parameters: 0

Return type: data

YANG file: yumaworks-support-save.yang

Capabilities needed: None

Returns:

• <support-save-data> element


• access-denied

• resource-denied

Example Request:

<?xml version="1.0" encoding="UTF-8"?><rpc message-id="1" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <get-support-save xmlns="urn:ietf:params:xml:ns:yang:yumaworks-support-save"/></rpc>

Example Reply:

<rpc-reply message-id="1" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <support-save-data xmlns="urn:ietf:params:xml:ns:yang:yumaworks-support-save"> <program> <name>netconfd-pro</name> <version>tiger-andy-supportsave-2017-08-07.14.26</version> </program> <system xmlns="http://netconfcentral.org/ns/yuma-system"> … contents removed for example


http://netconfcentral.org/ns/yuma-system


</system> … contents removed for example </support-save-data></rpc-reply>



2.6.20 <kill-session>

The <kill-session> operation is used to force the termination of another NETCONF session. This is sometimes needed if anidle 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




• session-id

◦ type: uint32 (range: 1.. max)

◦ default: none

◦ This parameter specifies the session number of the currently active NETCONF session that should be terminated.


• none

Returns:

• <ok/>


• access-denied

Example Request:

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

Example Reply:






2.6.21 <load>

The <load> operation is used to load new YANG modules at run-time.

The module file must already be present in the module search path of the server.

There must not be any version of the module already loaded.

This operation is tagged as nacm:default-deny-all, so by default, only the super user account is allowed to use it.

This operation appears in 2 YANG modules:

• yuma-system: deprecated and disabled if --with-yuma-system is set to ‘false’

• yumaworks-system: current. Always enabled

<load> operation

Min parameters: 1

Max parameters: 3

Return type: data

YANG file: yuma-system.yangyumaworks-system.yang



• module

◦ The name of the YANG module to load


• revision

◦ The revision date of the module to load. If missing, then server can select the version to use.

• deviation

◦ The name of a deviation module to load before loading this module. Zero or more instances of this parameter can be entered. Duplicates will be ignored.

• save-config: Save a module configuration file this module so it will be loaded after a server reboot. The default is 'false'.

Returns:

• <mod-revision>

◦ The revision date of the module that was already loaded, or was just loaded.


• access-denied

• module not found

• version not found



• different version already loaded

• module parsing errors

• resource errors

Example Request:

<?xml version="1.0" encoding="UTF-8"?> <nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="52"> <nd:load xmlns:nd="http://netconfcentral.org/ns/netconfd"> <nd:module>test2</nd:module> </nd:load> </nc:rpc>

Example Reply:

<?xml version="1.0" encoding="UTF-8"?> <nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="52"> <nd:mod-revision xmlns:nd="http://netconfcentral.org/ns/netconfd"> 2008-10-15 </nd:mod-revision> </nc:rpc-reply>



2.6.22 <load-bundle>

The <load-bundle> operation is used to load new YANG modules at run-time, which are compiled together as a SIL bundle.

All modules in the SIL bundle must already be present in the module search path of the server.

There must not be any version of any modules in the bundle already loaded.

This operation is tagged as nacm:default-deny-all, so by default, only the super user account is allowed to use it.

<load> operation

Min parameters: 1

Max parameters: 3

Return type: status




• bundle

◦ The name of the SIL bundle to load


• deviation

◦ The name of a deviation module to load before loading this bundle. Zero or more instances of this parameter can be entered. Duplicates will be ignored.

• save-config: Save a module configuration file this bundle so it will be loaded after a server reboot. The default is 'false'.

Returns:

• status


• access-denied

• module not found

• SIL library not found

• module parsing errors

• resource errors

Example Request:

<?xml version="1.0" encoding="UTF-8"?> <rpc message-id="166" 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:




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



Capabilities optional: :candidate:startup


• target


◦ This parameter specifies the name of the target database to be locked.


▪ candidate

• type: empty


▪ running

• type: empty


▪ startup

• type: empty



• none

Returns:



• <ok/>


• access-denied

• lock-denied (lock already held by <session-id> in the <error-info>)

• resource-denied (candidate is dirty; <discard-changes> needed)

Example Request:

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

Example Reply:




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



• none


• none

Returns:

• <ok/>


• access-denied

Example Request:

<?xml version="1.0" encoding="UTF-8"?> <nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="63"> <nd:no-op xmlns:nd="http://netconfcentral.org/ns/netconfd"/> </nc:rpc>

Example Reply:




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


• <select>

◦ type: XPath 1.0 string

◦ This parameter contains an XPath expression for a node-set result, identifying the database nodes to lock.

◦ One of more instances of this parameter is required.

◦ The server allows relaxed XPath syntax. If prefixes are used, then a proper namespace declaration must be present in the request. If prefixes are not used, then any available namespace that matches the local name will be used.


• none

Returns:

• <lock-id>

◦ type: uint32 (range 1 .. MAX_UINT)

◦ This data identifies the lock ID to use when releasing the lock with the <partial-unlock> operation.

◦ There will be one of these elements in the reply.

• <locked-node>

◦ type: instance-identifier

◦ This data identifies a locked node as a result of the request.

◦ There will be one or more of these elements in the reply.


• access denied, in-use, resource-denied

Example Request:



<?xml version="1.0" encoding="UTF-8"?> <nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="260"> <pl:partial-lock xmlns:pl="urn:ietf:params:xml:ns:netconf:partial-lock:1.0"> <pl:select>//interface</pl:select> </pl:partial-lock> </nc:rpc>

Example Reply:

<?xml version="1.0" encoding="UTF-8"?> <nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="260" xmlns:if="http://netconfcentral.org/ns/yuma-interfaces"> <pl:lock-id xmlns:pl="urn:ietf:params:xml:ns:netconf:partial-lock:1.0">1</pl:lock-id> <pl:locked-node xmlns:pl="urn:ietf:params:xml:ns:netconf:partial-lock:1.0">/if:interfaces/if:interface[if:name='virbr0']</pl:locked-node> <pl:locked-node xmlns:pl="urn:ietf:params:xml:ns:netconf:partial-lock:1.0">/if:interfaces/if:interface[if:name='eth0']</pl:locked-node> <pl:locked-node xmlns:pl="urn:ietf:params:xml:ns:netconf:partial-lock:1.0">/if:interfaces/if:interface[if:name='lo']</pl:locked-node> </nc:rpc-reply>



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


• <lock-id>

◦ type: unit32 (1 .. MAX_UINT)

◦ This parameter contains the lock ID of the partial lock to release.

◦ One of more instances of this parameter is required.

◦ The server allows relaxed XPath syntax. If prefixes are used, then a proper namespace declaration must be present in the request. If prefixes are not used, then any available namespace that matches the local name will be used.


• none

Returns:

• <ok/>


• access denied, invalid-value

Example Request:

<?xml version="1.0" encoding="UTF-8"?> <nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="263"> <pl:partial-unlock xmlns:pl="urn:ietf:params:xml:ns:netconf:partial-lock:1.0"> <pl:lock-id>1</pl:lock-id> </pl:partial-unlock> </nc:rpc>



Example Reply:




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




• none


• none

Returns:

• none; session will be dropped upon success


• access denied

Example Request:

<?xml version="1.0" encoding="UTF-8"?> <nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="63"> <nd:restart xmlns:nd="http://netconfcentral.org/ns/netconfd"/> </nc:rpc>

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



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



<backup> operation

Min parameters: 1

Max parameters: 1

Return type: status




• filename:



• none

Returns:

• <ok/>


• none

Example Request:

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

Example Reply:




2.6.29 <set-log-level>

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

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

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

<set-log-level> operation

Min parameters: 1

Max parameters: 1

Return type: status

YANG file: yuma-system.yangyumaworks-system.yang


• <log-level>


◦ type: enumeration (off, error, warn, info, debug, debug2, debug3)

◦ default: none

◦ This parameter specifies the server logging verbosity level.


• none

Returns:

• <ok/>


• access-denied

Example Request:

<rpc message-id="2" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <set-log-level xmlns="http://netconfcentral.org/ns/yuma-system"> <log-level>debug2</log-level> </set-log-level> </rpc>

Example Reply:






2.6.30 <set-my-session>

The <set-my-session> operation is used to configure the session customization data for the current session.

The session indent amount, line size, and default behavior for the with-defaults parameter can be controlled at this time.

The module yuma-mysession must be enabled in the server configuration file or CLI parameters for this operation to be available.

<set-my-session> operation

Min parameters: 0

Max parameters: 4

Return type: status

YANG file: yuma-mysession.yang



• none


• <indent>

◦ type: uint32 (range 0 .. 9)

◦ default: 3 (can be changed with the --indent configuration parameter)

◦ This parameter specifies the desired indent amount for the session.

• <linesize>

◦ type: uint32 (range 40 .. 1024)

◦ default: 72

◦ This parameter specifies the desired line length for the session.

• <with-defaults>

◦ type: enumeration (report-all report-all-tagged trim explicit)

◦ default: report-all (can be changed with the --default-style configuration parameter)

◦ This parameter specifies the desired default with-defaults behavior for the session. The server-wide default value is set with the --default-style configuration parameter.

• <message-indent>

◦ type: int8 (range -1 .. 9)

◦ This parameter specifies the desired message indent amount for the session.

◦ default: -1

Returns:

• <ok/>




• access-denied

Example Request:

<?xml version="1.0" encoding="UTF-8"?> <nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="3"> <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:




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




• none


• none

Returns:

• none; session will be dropped upon success


• access denied

Example Request:

<?xml version="1.0" encoding="UTF-8"?> <nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="1"> <nd:shutdown xmlns:nd="http://netconfcentral.org/ns/netconfd"/> </nc:rpc>

Example Reply:

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



2.6.32 <unload>

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

• The YANG module and all its SIL code (if any) will be removed from the running server. They will not be deletedfrom disk.

• Remove any data nodes in the system from the module.

• Remove the module from the server capabilities and NETCONF monitoring data.

• Remove the module namespace from the system.

• Note: this operation does not remove the --module parameter from the server configuration file if it exists.

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

• The module is allowed to be unloaded. It is data-model and vendor specific whether a module can be

removed at run-time.

• There are no dependencies on the module being removed. No modules that import this module are also loaded.

• The module was loaded into the server, either via the <load> operation or the --module configuration parameter.

• No datastores are currently locked. The server will attempt to lock all datastores on behalf of the client

for the entire unload operation.

• The candidate datastore does not contain any edits that have not been committed.

• No confirmed-commit operation is in progress.

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

• The client does not have write privileges for all data being deleted. This includes any top-level data nodes and any nested augment nodes in other modules.

• The deletion of one or more nodes would cause the running datastore to fail any YANG validation tests in RFC 6020, sec. 8.3.3.

• Server resource errors occur

<unload> operation

Min parameters: 1

Max parameters: 2

Return type: status






• module

◦ type: string

◦ This parameter specifies the name of the YANG module to be unloaded.


• delete-config: Delete the module configuration file for this module so it will not be loaded after a server reboot. The default is 'false'.

Returns:

• <ok/>


• access denied

• validation errors

• resource 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:




2.6.33 <unload-bundle>

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

• All the YANG modules in the bundle and all their SIL code (if any) will be removed from the running server. They will not be deleted from disk.

• Remove any data nodes in the system from all the modules in the bundle.

• Remove all the modules from the server capabilities and NETCONF monitoring data.

• Remove all the module namespaces from the system.

• Note: this operation does not remove the --bundle parameter from the server configuration file if it exists.

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

• The bundle is allowed to be unloaded. It is data-model and vendor specific whether a bundle can be

removed at run-time.

• There are no dependencies on the modules being removed, from outside the bundle. No modules that import this module can be loaded after the bundle is unloaded.

• The bundle was loaded into the server, either via the <load-bundle> operation or the --bundle configuration parameter.

• No datastores are currently locked. The server will attempt to lock all datastores on behalf of the client

for the entire unload-bundle operation.

• The candidate datastore does not contain any edits that have not been committed.

• No confirmed-commit operation is in progress.

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

• The client does not have write privileges for all data being deleted. This includes any top-level data nodes and any nested augment nodes in other modules.

• The deletion of one or more nodes would cause the running datastore to fail any YANG validation tests in RFC 6020, sec. 8.3.3.

• Server resource errors occur

<unload-bundle> operation

Min parameters: 1

Max parameters: 2

Return type: status






• bundle

◦ type: string

◦ This parameter specifies the name of the YANG module to be unloaded.


• delete-config: Delete the module configuration file for this bundle so it will not be loaded after a server reboot. The default is 'false'.

Returns:

• <ok/>


• access denied

• validation errors

• resource 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:




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





• target


◦ This parameter specifies the name of the target database to be unlocked.


▪ candidate

• type: empty


▪ running

• type: empty


▪ startup

• type: empty



• none

Returns:

• <ok/>




• access denied

• no-access (database not locked)

• invalid-value (database not supported)

Example Request:

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

Example Reply:




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


Capabilities needed: :validate



• target


◦ This parameter specifies the name of the target database, or the in-line configuration data, that should be validated.


▪ candidate

• type: empty


▪ running

• type: empty


▪ startup

• type: empty


▪ config

• type anyxml



• none

Returns:

• <ok/>




• access denied

• <commit> validation errors

Example Request:

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

Example Reply:




2.7 Access Control

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

The nacm:default-deny-write and nacm:default-deny-all extensions also affect access control. If present in the YANG definition, then the default behavior (when no rule is found) is not followed. Instead, the super user account must be used to allow default access.

There are 3 types of access control rules that can be defined:

1. module rule

2. RPC operation rule

3. database rule

Rules apply to one or more groups. Each group contains zero or more user names. Database rules are applied top-down, at every level.

The user needs permission for the requested access (read or write) for all referenced nodes within the database. For example, if there was a leaf from module X that augments a container in module Y, the user would need permission to access the container from module Y, and then permission to access the leaf from module X.

The NACM data model can be used without any configuration at all. Refer to the section on access control modes for moredetails.

Normally, some configuration is required:

• groups: configure one or more administrative groups



• rules: configure one or more access control rules

The entire /nacm subtree is tagged as nacm:default-deny-all. By default, only the super-user account can read or write any of its contents. It is suggested that even read access to this data structure be controlled carefully at all times.

2.7.1 NACM Module Structure

The /nacm subtree is described below:

module: ietf-netconf-acm

+--rw nacm

+--rw enable-nacm? boolean

+--rw read-default? action-type

+--rw write-default? action-type

+--rw exec-default? action-type

+--rw enable-external-groups? boolean

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

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

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

+--rw groups

| +--rw group* [name]

| +--rw name group-name-type

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

+--rw rule-list* [name]

+--rw name string

+--rw group* union

+--rw rule* [name]

+--rw name string

+--rw module-name? union

+--rw (rule-type)?

| +--:(protocol-operation)

| | +--rw rpc-name? union

| +--:(notification)

| | +--rw notification-name? union

| +--:(data-node)

| +--rw path node-instance-identifier

+--rw access-operations? union

+--rw action action-type

+--rw comment? string



2.7.2 Users and Groups

Access rights in NACM are given to groups.

A group entry consists of a group identifier and a list of user names that are members of the group.

By default, there are no groups created. Each /nacm/groups/group entry must be created by the client. There is no user name table either. It is assumed that the operator will know which user names are valid within each managed device.

2.7.3 Creating New Groups

The <edit-config> operation can be used to create new group entries.

A user name can appear within the same group zero or one times.

A user name can appear in zero or more groups.

When a user is a member of multiple groups, all these groups will be used to match against rules, in a conceptual 'OR' expression. If any of these groups matches one of the <allowed-group> leaf-list nodes within one of the 3 rule types, then that rule will be the one that is used. Rules are always searched in the order they are entered, even the system-ordered lists.

The path to the group element is /nacm:nacm/nacm:groups/nacm:group.

The following <edit-config> example shows how a group can be defined. The group name is 'admi1',and the users 'user1' and 'user2' are the initial members of this group.

<?xml version="1.0" encoding="UTF-8"?><rpc message-id="1" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <edit-config> <target> <candidate/> </target> <default-operation>merge</default-operation> <test-option>set</test-option> <config> <nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm"> <groups> <group xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" nc:operation="merge"> <name>admin1</name> <user-name>user1</user-name> <user-name>user2</user-name> </group> </groups> </nacm> </config> </edit-config></rpc>

2.7.4 Access Control Modes

The --access-control configuration parameter is used to globally enable or disable the access control system. It cannot be changed at run-time, or through a NETCONF session.



• off: no access control enforcement is done at all.

• disabled: all nacm:default-deny-write and nacm:default-deny-all tagged objects will require the super user account to access, but no other access control enforcement will be done.

• permissive: all nacm:default-deny-all objects will require super user account to read. No other read access enforcement will be done. Write and exec access will be checked.

• enforcing: all access control enforcement will be checked. This is the default behavior.

2.7.5 Permissions

There are 3 types of access permissions defined:

1. read: retrieval of any kind

2. write: modification of any kind

3. exec: right to invoke an RPC operation

The <allowed-rights> object in each of the 3 access control rule entries is a 'bits' leaf, which is allowed to contain any of these string tokens, or none of them to deny all access to a set of groups.

When a rule is found which matches the current request, the <allowed-rights> leaf will be used to grant permission or not. If the bit for the requested operation is present, then the request is permitted. If the bit is not present, then the request is denied.

2.7.6 Special YANG Extensions For Access Control

There are 3 YANG language extensions defined that can be used to force access control behavior for specific data nodes in the configuration database.

1. nacm:default-deny-write (no parameter)

If present in a data node statement, this extension will cause the write default to be ignored, and any write access toinstances of this object will be rejected with an 'access-denied' error unless there is an explicit NACM rule allowingwrite access to the user session. If present in an 'rpc' statement, then exec access will be denied unless there is an explicit NACM rule granting exec access.

2. nacm:default-deny-all (no parameter)

If present in a data node statement, this extension will cause the read and write defaults to be ignored, and any write access to instances of this object will be rejected with an 'access-denied' error unless there is an explicit NACM rule allowing write access to the user session. Read access will be denied, which causes that data to be removed from the <rpc-reply>. If present in an 'rpc' statement, then exec access will be denied unless there is an explicit NACM rule granting exec access.

3. ncx:user-write (parameter: permitted, type: bits: create, update, delete)Used within database configuration data definition statements to control user write access to the database object containing this statement. The 'permitted' argument is a list of operations that users are permitted to invoke for the specified node. These permissions will over-ride all NACM access control rules, even if NACM is disabled.

To dis-allow all user access, provide an empty string for the 'permitted' parameter.



To allow only create and delete user access, provide the string 'create delete' for the parameter. Use this for YANGdatabase 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:

• read default: permit

• write default: deny

• exec default: permit

These defaults can be changed by the server developer, by modifying the YANG definitions in ietf-netconf-acm.yang. If the data node object definition contains the special YANG extensions described in the previous section, then the extension will define default access and the NACM default access rule will not be used.

2.7.8 Access Control Algorithm

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

2.7.9 Passwords and crypt-hash

The YANG extension “ncx:password” can be used in a YANG module to identify password fields.

The obj_is_password() function will be true for these objects, and any object that uses the “crypt-hash” typedef from the “iana-crypt-hash” module.

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

typedef crypt-hash { type string { pattern '$0$.*' + '|$1$[a-zA-Z0-9./]{1,8}$[a-zA-Z0-9./]{22}' + '|$5$(rounds=\d+$)?[a-zA-Z0-9./]{1,16}$[a-zA-Z0-9./]{43}' + '|$6$(rounds=\d+$)?[a-zA-Z0-9./]{1,16}$[a-zA-Z0-9./]{86}'; } description "The crypt-hash type is used to store passwords using a hash function. The algorithms for applying the hash function and encoding the result are implemented in various UNIX systems as the function crypt(3).

A value of this type matches one of the forms:

$0$<clear text password> $<id>$<salt>$<password hash> $<id>$<parameter>$<salt>$<password hash>

The '$0$' prefix signals that the value is clear text. When such a value is received by the server, a hash value is calculated, and the string '$<id>$<salt>$' or $<id>$<parameter>$<salt>$ is prepended to the result. This



value is stored in the configuration data store. If a value starting with '$<id>$', where <id> is not '0', is received, the server knows that the value already represents a hashed value and stores it 'as is' in the data store.

When a server needs to verify a password given by a user, it finds the stored password hash string for that user, extracts the salt, and calculates the hash with the salt and given password as input. If the calculated hash value is the same as the stored value, the password given by the client is accepted.

This type defines the following hash functions:

id | hash function | feature ---+---------------+------------------- 1 | MD5 | crypt-hash-md5 5 | SHA-256 | crypt-hash-sha-256 6 | SHA-512 | crypt-hash-sha-512

The server indicates support for the different hash functions by advertising the corresponding feature."; reference "IEEE Std 1003.1-2008 - crypt() function RFC 1321: The MD5 Message-Digest Algorithm FIPS.180-4.2012: Secure Hash Standard (SHS)"; }

Values of this datatype that match the “$0$” format will be converted and stored as a hash, according to the typedef specification.

• The agt_profile field agt_min_password_len field will be used to enforce a minimum password length for the crypt-hash data type. The default value is 8.

• The agt_profile field agt_crypt_hash_prefix field will be used to select the hash function that will be used for the conversion of $0$ format strings. The default value is SHA-512 ($6$).

• The obj_is_password() function will be true for any crypt-hash data node



2.7.10 Using Module Tags with NACM

There is an extension to NACM defined in yumaworks-system.yang:

augment /nacm:nacm/nacm:rule-list/nacm:rule/nacm:rule-type { case module-tags { uses ywapp:ModuleTagParm; } }

This extension adds a new rule-type called module-tags.

A list of module-tag strings can be used to select the modules that are mapped to the NACM rule.

It is similar to a data-rule which selects a path, except it selects all objects from the specified module(s) for RPC, notification, and data node access control.

Module-tags are more flexible than the module-name leaf provided in the NACM rule entry.

It is recommended that this field be set to the default ‘*’ if the module-tag parameter is used.

Example:

The following module-tag is used:

module-tagmap ietf-restconf-monitoring@restconf

The module ietf-restconf-monitoring is mapped to the module-tag “restconf”.

The following NACM configuration contains a module-tags rule:

<nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm"> <read-default>deny</read-default> <groups> <group> <name>g1</name> <user-name>netconf1</user-name> </group> </groups> <rule-list> <name>rl1</name> <group>g1</group> <rule> <name>r1</name> <module-name>*</module-name> <access-operations>*</access-operations> <action>permit</action>


mailto:ietf-restconf-monitoring@restconf


<comment/> <module-tag xmlns="http://yumaworks.com/ns/yumaworks-system">restconf</module-tag> </rule> </rule-list> </nacm>

This rule allows group “g1” all access to the modules tagged with the module-tag “restconf”.

An example <get> request returns only the data from the ietf-restconf-monitoring module.

netconf1@localhost> get

RPC Data Reply 3 for session 4 [default]:

rpc-reply { data { restconf-state { capabilities { capability urn:ietf:params:restconf:capability:depth:1.0 capability urn:ietf:params:restconf:capability:with-defaults:1.0 capability urn:ietf:params:restconf:capability:defaults:1.0?basic-mode=report-all capability urn:ietf:params:restconf:capability:fields:1.0 capability urn:ietf:params:restconf:capability:replay:1.0 capability urn:ietf:params:restconf:capability:filter:1.0 capability urn:ietf:params:restconf:capability:yang-patch:1.0 } streams { stream RESTCONF { name RESTCONF description 'default RESTCONF event stream' replay-support true replay-log-creation-time 2018-04-27T21:45:56Z access xml { encoding xml location http://localhost/restconf/stream } } } } }}



2.8 Using RESTCONF

WEB application developers have different tools and a resource-oriented data model which tends to keep them from adopting NETCONF over SSH as a programmatic interface.

The RESTCONF Protocol is defined in RFC 8040.

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

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

NOTE YANG-API users:

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

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

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

2.8.1 Features

The restconf program has the following features:

• Complete implementation of RESTCONF protocol, defined in RFC 8040

• Complete implementation of YANG Patch, defined in RFC 8072.

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

• Supports the complete HTTP/1.1 transport defined in RFC 7230.

• Complete XML 1.0 implementation with full support for XML Namespaces

• Complete JSON implementation

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

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

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

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

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

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

• Extend error handling

◦ HTTP status-lines are used to report success or failure for RESTCONF operations. Error information is returned for "4xx" class of status codes. This error information is adapted for use in RESTCONF.

• Complete RFC 5277 Notification support, including notification replay via SSE W3C Working Draft



• Complete RFC 7895 YANG Module Library support, including full support of the YANG modules schema retrieval from the server and support of server-specific identifier representing the current set of modules and submodules.

• Support new query parameters:

◦ he "depth" parameter is used to limit the number of levels of child resources that are returned by the server for a GET method request.

◦ The "content" parameter is used to select the type of data child resources (configuration or not configuration, or all data) that are returned by the server for a GET method request.

◦ The “with-defaults” parameter is used to select the type of data (report-all, report-all-tagged, trim, explicit) that are returned by the server for a GET method request.

• Support GET on /restconf/data

◦ This mandatory resource represents the combined configuration and operational data resources that can be accessed by a client. It cannot be created or deleted by the client.

• Support POST /restconf/operations

◦ This optional resource is a container that provides access to the data-model specific protocol operations supported by the server. The server may omit this resource if no data-model specific operations are advertised.

◦ Any data-model specific operations defined in the YANG modules advertised by the server may be available aschild nodes of this resource.

• RESTCONF capability support /restconf/data/restconf-state

◦ RESTCONF provides the YANG module capability information supported by the server, in case the client wants to use it. The URIs for custom protocol operations and datastore content are predictable, based on the YANG module definitions.

• Support for new POST and PUT/create operations

◦ Support POST/PUT Request based on query parameters and protocol

• Two "edit collision detection" mechanisms are provided in RESTCONF, for datastore and data resources.

◦ Timestamps

◦ Entity Tag

• Support full conformance

◦ Support Accept header validation

◦ Support .well-known. The root of the RESTCONF API configured on the HTTP server, discovered by getting the ".well-known/host-meta"

◦ Support ietf-restconf-monitoring

◦ Supports notifications that populate a stream resource for each notification delivery service access point. A RESTCONF client can retrieve the list of supported event streams from a RESTCONF server using the GET operation on the /restconf/data/restconf-state/streams list.

◦ Supports a new event stream resource. This resource represents an SSE (Server-Sent Events) event stream. Thecontent consists of text using the media type "text/event-stream", as defined by the HTML5 specification. Each event represents one <notification> message generated by the server. It contains a conceptual system or data-model specific event that is delivered within an event notification stream. Also called a "stream resource".



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.1Host: example.comAccept: application/xrd+xml

Response--------HTTP/1.1 200 OKContent-Type: application/xrd+xmlContent-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



Resource RESTCONF Entry points YANG-API Entry points Media Type


Data {+restconf}/data/node {+yang-api}/datastore/nodeapplication/yang-data+xml


ErrorsRESTCONF specific error handling

Not-supported, standard NETCONF-based error handling

application/yang-data+xml


Operation{+restconf}/operations/ <operation>

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



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



Name Description

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 the 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 mayapply if the parameter is missing. If vendors define additional query parameters, they should use a prefix (such as the enterprise or organization name) for query parameter names in order to avoid collisions with other parameters.

• Depth Query Parameter

In the RESTCONF implementation the "depth" parameter is used to limit the number of levels of child resources that are returned by the server for a GET method request.

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. Adepth 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 ofthe "depth" parameter is either an integer between 1 and 65535, or the string "unbounded". "unbounded" is the default.

This parameter is only allowed for GET methods on API, datastore, and data resources. A 400 Bad Request error is returned if it used for other methods or resource types.

By default, the server will include all sub-resources within a retrieved resource, which have the same resource type as the requested resource. Only one level of sub-resources with a different media type than the target resource will be returned.

If the "depth" query parameter URI is listed in the "capability" leaf-list, then the server supports the "depth" query parameter.

• Content Query Parameter

The "content" parameter is used to select the type of data child resources (configuration and/or not configuration) that are returned by the server for a GET method request.

The "content" parameter controls how descendant nodes of the requested data nodes will be processed in the reply.

The allowed values are:

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.

• Filter Query Parameter

Currently this parameter is not supported, it will be available in the next releases.



The "filter" parameter is used to indicate which subset of all possible events are of interest. If not present, all events not precluded by other parameters will be sent.

This parameter is only allowed for GET methods on a text/event-stream data resource. A 400 Bad Request error is returned if used for other methods or resource types.The format of this parameter is an XPath 1.0 expression, and is evaluated in the following context:

• The set of namespace declarations is the set of prefix and namespace pairs for all supported YANG modules, wherethe prefix is the YANG module name, and the namespace is as defined by the "namespace" statement in the YANG module. The function library is the core function library defined in XPath 1.0.

• The set of variable bindings is empty.

• The context node is the root node.

If the boolean result of the expression is true when applied to the conceptual "notification" document root, then the event notification is delivered to the client.

If the "filter" query parameter URI is listed in the "capability" leaf-list, then the server supports the "filter" query parameter.

The following URIs show some examples of notification filter specifications (lines wrapped for display purposes only):

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

// filter = /event/severity<=4 GET /mystreams/NETCONF?filter=%2Fevent%2Fseverity%3C%3D4

// filter = /*/reporting-entity/card!='Ethernet0' GET /mystreams/NETCONF? filter=%2F*%2Freporting-entity%2Fcard%21%3D'Ethernet0'

// filter = /*/email-addr[contains(.,'company.com')] GET /mystreams/critical-syslog? filter=%2F*%2Femail-addr[contains(.%2C'company.com')]

// Note: the module name is used as prefix. // filter = (/example-mod:event1/name='joe' and // /example-mod:event1/status='online') GET /mystreams/NETCONF? filter=(%2Fexample-mod%3Aevent1%2Fname%3D'joe'%20and %20%2Fexample-mod%3Aevent1%2Fstatus%3D'online')

• Fields Query Parameter

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

This section describes the gNMI (gRPC Network Management Interface) integration within the netconfd-pro server and ypgnmi-app application. The model-driven configuration and retrieval of operational data using the gNMI CAPABILITIES, GET and SET gRPCs. gNMI version 0.4.0 is supported.

Throughout this specification the following terminology is used:

• Telemetry - refers to streaming data relating to underlying characteristics of the device - either operational state or configuration

• Configuration - elements within the data schema which are read/write and can be manipulated by the client

• Target - the device within the protocol which acts as the owner of the data that is being manipulated or reported on. Typically this will be a netconfd-pro server that communicate with the client with help of ypgnmi-app application

• Client - the device or system using the protocol and the service described in this document to query/modify data onthe target, or act as a collector for streamed data. Typically this will be a network management system. The client will contact the ypgnmi-app application to query/modify data on the target

2.9.1 Features

The main gNMI service functionality contains the following requests (gRPC):

• Capabilities - used by the client and target as an initial handshake to exchange capability information

• Get - used to retrieve snapshots of the data on the target by the client

• Set - used by the client to modify the state of the target

• Subscribe - used to control subscriptions to data on the target by the client

Future revisions of the gNMI specification MAY result in additional services being introduced, and hence an implementation MUST NOT make assumptions that limit to a single service definition.

The ypgnmi-app application is capable of handling these requests and transferring them to the netconfd-pro server for further processing as well as handle replies from the netconfd-pro server and transmit them back to the gNMI clients. The following sections will describe in more details how these requests are handled internally in the netconfd-pro and how ypgnmi-app application transform original gNMI requests and how they are transmitted to and from the netconfd-pro.

2.9.2 Restrictions for gNMI Protocol

The YumaPro gNMI protocol has the following restrictions:

• Only JSON encoding options

• In a SetRequest, wildcards and all keys are not supported. Only fully-specified paths are supported

• In Subscribe, only supported mode is ONCE



2.9.3 Running Ypgnmi-app

Run the server with the setting --with-gnmi=true flag as follows:

mydir> netconfd-pro log-level=debug4 --with-gnmi=true

Start the ypgnmi-app application. Note that you have to provide your certificates to start the application:

mydir> man ypgnmi-appmydir> ypgnmi-app --cert ~/certs/server.crt \

--ca ~/certs/ca.crt \--key ~/certs/server.key

After this step the gNMI server starts to listen for any gNMI client requests and will process the requests to the netconfd-pro server and will transfer all the replies back.

2.9.4 Running gNMI Client Applications

The gNXI Tools, gRPC Network Management/Operations Interface Tools, provide basic applications to connect to the server and can be used to test the system. Install the gNXI Tools using the 'go get' and 'go install' tools. Refer to https://github.com/google/gnxi:

mydir> go get github.com/google/gnxi/gnmi_getmydir> go install github.com/google/gnxi/gnmi_getmydir> go get github.com/google/gnxi/gnmi_capabilitiesmydir> go install github.com/google/gnxi/gnmi_capabilitiesmydir> go get github.com/google/gnxi/gnmi_setmydir> go install github.com/google/gnxi/gnmi_set

To run the gnmi_capabilities client:

mydir> gnmi_capabilities \--target_addr 127.0.0.1:10161 \--key ~/certs/client.key \--cert ~/certs/client.crt \--ca ~/certs/ca.crt \--target_name your_target_name

To run the gnmi_get client:



mydir> gnmi_get \--target_addr 127.0.0.1:10161 \--key ~/certs/client.key \--cert ~/certs/client.crt \--ca ~/certs/ca.crt \--target_name your_target_name \--xpath "/country[name=usa]" \--xpath "person"

To run the gnmi_set client:

mydir> gnmi_set \--target_addr localhost:10161 \--key ~/certs/client.key \--cert ~/certs/client.crt \--ca ~/certs/ca.crt \--delete /system/openflow/agent/config/max-backoff \--delete /system/openflow/agent/config/max-backoff2 \--replace /system/clock:@clock-config.json \--update /system/clock/config/timezone-name::@clock-

config2.json

Where clock-config.json Input file to replace container “clock” should look as follows:

{ "clock": { "timezone-name": "Europe/Stockholm" }}

Where clock-config2.json Input file to update a lead “timezone-name” should look as follows:

{ "timezone-name": "ETZ"}

In addition you may use the following gNMI client for sending SET and Subscribe Requests.

Refer to https://github.com/openconfig/gnmi

To run the gnmi_cli gNMI client:

mydir> > gnmi_cli \


https://github.com/openconfig/gnmi


--address localhost:10161 \--client_crt ~/certs/client.crt \--ca_crt ~/certs/ca.crt \--client_key ~/certs/client.key \--server_name server.com \ --set --delete="/person"

mydir> > gnmi_cli \--address localhost:10161 \--client_crt ~/certs/client.crt \--ca_crt ~/certs/ca.crt \--client_key ~/certs/client.key \--server_name server.com \--query_type once \--query "/uint32.1"

Note that this gNMI client only sends Subscribe or Set requests, currently ypgnmi-app application accepts only Subscribe requests with ONCE mode. Meaning the Subscription will be terminated right after the reply is sent.



2.9.5 Closing Ypgnmi-app

The ypgnmi-app can be shut down by typing Ctrl-C in the window that started the application.

If the netconfd-pro server is not running when ypgnmi-app is started the application will terminate with an error message stating that the netconfd-pro server is not running.

If the netconfd-pro server is shut down then ypgnmi-app will also shutdown.

2.9.6 gNMI GetRequest

The gNMI GET RPC specifies how to retrieve one or more of the configuration attributes, state attributes, derived state attributes, or all attributes associated with a supported mode from a date tree. A GetRequest is sent from a client to the target to retrieve values from the data tree. A GetResponse is sent in response to a GetRequest.

The following example shows a Get Request on JSON structure:

XPath: /oc-if:interfaces/interface[name=Loopback111]++++++++ Sending get request: ++++++++path { elem { name: "oc-if:interfaces" } elem { name: "interface" key { key: "name" value: "Loopback111" } }}encoding: JSON_IETF++++++++ Recevied get response: ++++++++notification { timestamp: 1521699434792345469 update { path { elem { name: "oc-if:interfaces" } elem { name: "interface" key { key: "name" value: "\"Loopback111\"" } } } val { json_ietf_val: "{\n\t\"openconfig-interfaces:name\":\t\"Loopback111\",\n\t\ "openconfig-interfaces:config\":\t{\n\t\t\ "openconfig-interfaces:type\":\t\"ianaift:softwareLoopback\",\n\t\t\ "openconfig-interfaces:name\":\t\"Loopback111\",\n\t\t\ "openconfig-interfaces:enabled\":\t\"true\"\n\t},\n\t\ "openconfig-interfaces:state\":\t{\n\t\t\ "openconfig-interfaces:type\":\t\"ianaift:softwareLoopback\",\n\t\t\



"openconfig-interfaces:name\":\t\"Loopback111\",\n\t\t\ "openconfig-interfaces:enabled\":\t\"true\",\n\t\t\ "openconfig-interfaces:ifindex\":\t52,\n\t\t\ "openconfig-interfaces:admin-status\":\t\"UP\",\n\t\t\ "openconfig-interfaces:oper-status\":\t\"UP\",\n\t\t\ "openconfig-interfaces:last-change\":\t2018,\n\t\t\ "openconfig-interfaces:counters\":\t{\n\t\t\t\ "openconfig-interfaces:in-octets\":\t0,\n\t\t\t\ "openconfig-interfaces:in-unicast-pkts\":\t0,\n\t\t\t\ "openconfig-interfaces:in-broadcast-pkts\":\t0,\n\t\t\t\ "openconfig-interfaces:in-multicast-pkts\":\t0,\n\t\t\t\ "openconfig-interfaces:in-discards\":\t0,\n\t\t\t\ "openconfig-interfaces:in-errors\":\t0,\n\t\t\t\ "openconfig-interfaces:in-unknown-protos\":\t0,\n\t\t\t\ "openconfig-interfaces:out-octets\":\t0,\n\t\t\t\ "openconfig-interfaces:out-unicast-pkts\":\t0,\n\t\t\t\ "openconfig-interfaces:out-broadcast-pkts\":\t0,\n\t\t\t\ "openconfig-interfaces:out-multicast-pkts\":\t0,\n\t\t\t\ "openconfig-interfaces:out-discards\":\t0,\n\t\t\t\ "openconfig-interfaces:out-errors\":\t0,\n\t\t\t\ "openconfig-interfaces:last-clear\":\t2018\n\t\t},\n\t\t\ "openconfig-platform:hardware-port\":\t\"Loopback111\"\n\t},\n\t\ "openconfig-interfaces:subinterfaces\":\t{\n\t\t\ "openconfig-interfaces:index\":\t0,\n\t\t\ "openconfig-interfaces:config\":\t{\n\t\t\t\ "openconfig-interfaces:index\":\t0,\n\t\t\t\ "openconfig-interfaces:name\":\t\"Loopback111\",\n\t\t\t\ "openconfig-interfaces:enabled\":\t\"true\"\n\t\t},\n\t\t\ "openconfig-interfaces:state\":\t{\n\t\t\t\ "openconfig-interfaces:index\":\t0,\n\t\t\t\ "openconfig-interfaces:name\":\t\"Loopback111.0\",\n\t\t\t\ "openconfig-interfaces:enabled\":\t\"true\",\n\t\t\t\ "openconfig-interfaces:admin-status\":\t\"UP\",\n\t\t\t\ "openconfig-interfaces:oper-status\":\t\"UP\",\n\t\t\t\ "openconfig-interfaces:last-change\":\t2018,\n\t\t\t\ "openconfig-interfaces:counters\":\t{\n\t\t\t\t\ "openconfig-interfaces:in-octets\":\t0,\n\t\t\t\t\ "openconfig-interfaces:in-unicast-pkts\":\t0,\n\t\t\t\t\ "openconfig-interfaces:in-broadcast-pkts\":\t0,\n\t\t\t\t\ "openconfig-interfaces:in-multicast-pkts\":\t0,\n\t\t\t\t\ "openconfig-interfaces:in-discards\":\t0,\n\t\t\t\t\ "openconfig-interfaces:in-errors\":\t0,\n\t\t\t\t\ "openconfig-interfaces:out-octets\":\t0,\n\t\t\t\t\ "openconfig-interfaces:out-unicast-pkts\":\t0,\n\t\t\t\t\ "openconfig-interfaces:out-broadcast-pkts\":\t0,\n\t\t\t\t\ "openconfig-interfaces:out-multicast-pkts\":\t0,\n\t\t\t\t\ "openconfig-interfaces:out-discards\":\t0,\n\t\t\t\t\ "openconfig-interfaces:out-errors\":\t0,\n\t\t\t\t\ "openconfig-interfaces:last-clear\":\t2018\n\t\t\t}\n\t\t},\n\t\t\ "openconfig-if-ip:ipv6\":\t{\n\t\t\t\ "openconfig-if-ip:config\":\t\"false\",\n\t\t\t\ "openconfig-if-ip:state\":\t\"false\"\n\t\t}\n\t}\n}" } }}

The following example shows a GetRequest on a leaf on JSON structure:

XPath: /oc-if:interfaces/interface[name=Loopback111]/state/oper-status



++++++++ Sending get request: ++++++++path { elem { name: "oc-if:interfaces" } elem { name: "interface" key { key: "name" value: "Loopback111" } } elem { name: "state" } elem { name: "oper-status" }}encoding: JSON_IETF++++++++ Recevied get response: ++++++++notification { timestamp: 1521699326012374332 update { path { elem { name: "oc-if:interfaces" } elem { name: "interface" key { key: "name" value: "\"Loopback111\"" } } elem { name: "state" } elem { name: "oper-status" } } val { json_ietf_val: "\"UP\"" } }}



2.9.7 gNMI SetRequest

The Set RPC specifies how to set one or more configurable attributes associated with a supported model. A SetRequest is sent from a client to a target to update the values in the data tree.

Within an individual transaction (SetRequest) the order of operations is delete, replace, update.

In a SetRequest, only fully-specified (wildcards, and all keys-specified paths are not supported) paths, and only "json_ietf_val" or "json_val” TypedValue are supported. JSON keys must contain a YANG-prefix, in which the namespace of the following element differs from parent. The “routed-vlan” element derived from augmentation in openconfig-vlan.yang must be entered as “oc-vlan:routed-vlan”, because it is different from the namespace of the parent node (The parent node prefix is oc-if.).

The total set of deletes, replace, and updates contained in any one SetRequest is treated as a single transaction. If any subordinate element of the transaction fails; the entire transaction will be disallowed and rolled back. A SetResponse is sent back for a SetRequest.

In the case that any operation within the SetRequest message fails, then, the target MUST NOT apply any of the specified changes, and MUST consider the transaction as failed. The target SHOULD set the status code of the SetResponse message to Aborted (10), along with an appropriate error message, and MUST set the message field of theUpdateResult corresponding to the failed operation to an Error message indicating failure. In the case that the processed operation is not the only operation within the SetRequest the target MUST set the message field of the UpdateResultmessages for all other operations, setting the code field to Aborted (10).

The following example shows a SetRequest on JSON structure:

Creating UPDATE update for /oc-if:interfaces/interface[name=Loopback111]/config/XPath: /oc-if:interfaces/interface[name=Loopback111]/config/++++++++ Sending set request: ++++++++update { path { elem { name: "oc-if:interfaces" } elem { name: "interface" key { key: "name" value: "Loopback111" } } elem { name: "config" } } val { json_ietf_val: "{\"config\":{\"openconfig-interfaces:enabled\":\"false\"}}" }}++++++++ Recevied set response: ++++++++response { path { elem { name: "oc-if:interfaces" } elem {



name: "interface" key { key: "name" value: "Loopback111" } } elem { name: "config" } } op: UPDATE}timestamp: 1521699342123890045

The following example shows a SetRequest on leaf on JSON structure:

Creating UPDATE update for /oc-if:interfaces/interface[name=Loopback111]/config/descriptionXPath: /oc-if:interfaces/interface[name=Loopback111]/config/description++++++++ Sending set request: ++++++++update { path { elem { name: "oc-if:interfaces" } elem { name: "interface" key { key: "name" value: "Loopback111" } } elem { name: "config" } elem { name: "description" } } val { json_ietf_val: "{ \"description\":\"UPDATE DESCRIPTION\" }" }}++++++++ Recevied set response: ++++++++response { path { elem { name: "oc-if:interfaces" } elem { name: "interface" key { key: "name" value: "Loopback111" } } elem { name: "config" }



elem { name: "description" } } op: UPDATE}timestamp: 1521699342123890045

2.9.8 gNMI JSON_ietf_val

The JSON type indicates that the value is encoded as a JSON string as specified in RFC 7159. Additional types (such as, JSON_IETF) indicate specific additional characteristics of the encoding of the JSON data (particularly where they relate to serialization of YANG-modeled data).

The following is a sample JSON_ietf_val message:

val { json_ietf_val:"{ "oc-if:config": { "oc-if:description": "UPDATE DESCRIPTION" } }"}

2.9.9 gNMI Error Messages

When errors occur, gNMI server returns descriptive error messages. The following section displays some gNMI server errormessages.

The following sample error message is displayed when the path is invalid:

gNMI Error Response:

== getRequest:path: < elem: < name: "unknown-resource" >>encoding: JSON_IETF

Get failed: rpc error: code = Code(385) desc = unknown resource



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

module-tag filtering Use –module-tag parameter



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

• If there is no namespace in affect for a filter component, or the 'NETCONF' namespace is in effect, the server will attempt to find any top-level data node which matches.

• Namespaces within descendant nodes of the <filter> node children are inherited from their parent. If none is in effect, then the first matching child node for the current parent node will be used.

• Invalid namespace errors for the <filter> element are suppressed in the server. An invalid namespace or unknown element is simply a 'no-match' condition.

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

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

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

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

<?xml version="1.0" encoding="UTF-8"?> <nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="9"> <nc:get> <nc:filter type="subtree"> <if:interfaces xmlns:if="http://netconfcentral.org/ns/yuma-interfaces"> <if:interface> <if:name>eth0</if:name> </if:interface> </if:interfaces> </nc:filter> </nc:get> </nc:rpc>



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

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

Example Request:

<?xml version="1.0" encoding="UTF-8"?> <nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="10"> <nc:get> <nc:filter type="subtree"> <if:interfaces xmlns:if="http://netconfcentral.org/ns/yuma-interfaces"> <if:interface> <if:name>eth0</if:name> <if:counters> <if:inBytes/> <if:outBytes/> </if:counters> </if:interface> </if:interfaces> </nc:filter> </nc:get> </nc:rpc>

Example Reply:

<?xml version="1.0" encoding="UTF-8"?> <nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="10"> <nc:data> <if:interfaces xmlns:if="http://netconfcentral.org/ns/interfaces"> <if:interface> <if:name>eth0</if:name> <if:counters> <if:inBytes>290046042</if:inBytes> <if:outBytes>112808406</if:outBytes> </if:counters> </if:interface> </if:interfaces> </nc:data> </nc:rpc-reply>



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

• xget //name

<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="43"> <nc:get> <nc:filter type="xpath" select="//name"/> </nc:get> </nc:rpc>]]>]]>

Example Reply:

<?xml version="1.0" encoding="UTF-8"?> <nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="43"> <nc:data> <nacm:nacm xmlns:nacm="http://netconfcentral.org/ns/nacm"> <nacm:rules> <nacm:data-rule> <nacm:name>nacm-tree</nacm:name> </nacm:data-rule> <nacm:data-rule> <nacm:name>itf-1</nacm:name> </nacm:data-rule> </nacm:rules>



</nacm:nacm> <t:xpath.1 xmlns:t="http://netconfcentral.org/ns/test"> <t:name>barney</t:name> </t:xpath.1> <if:interfaces xmlns:if="http://netconfcentral.org/ns/interfaces"> <if:interface> <if:name>lo</if:name> </if:interface> <if:interface> <if:name>eth0</if:name> </if:interface> <if:interface> <if:name>virbr0</if:name> </if:interface> <if:interface> <if:name>pan0</if:name> </if:interface> </if:interfaces> <ns:netconf-state

xmlns:ns="urn:ietf:params:xml:ns:netconf:monitoring"> <ns:datastores> <ns:datastore> <ns:name> <ns:candidate/> </ns:name> </ns:datastore> <ns:datastore> <ns:name> <ns:running/> </ns:name> </ns:datastore> <ns:datastore> <ns:name> <ns:startup/> </ns:name> </ns:datastore> </ns:datastores> </ns:netconf-state> <manageEvent:netconf

xmlns:manageEvent="urn:ietf:params:xml:ns:netmod:notification"> <manageEvent:streams> <manageEvent:stream> <manageEvent:name>NETCONF</manageEvent:name> </manageEvent:stream> </manageEvent:streams> </manageEvent:netconf> </nc:data> </nc:rpc-reply>

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

Example Request:

• xget //if:name

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



message-id="44"> <nc:get> <nc:filter type="xpath" xmlns:if="http://netconfcentral.org/ns/interfaces" select="//if:name"/> </nc:get> </nc:rpc>

Example Reply:

<?xml version="1.0" encoding="UTF-8"?> <nc:rpc-reply xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0" message-id="44"> <nc:data> <if:interfaces xmlns:if="http://netconfcentral.org/ns/interfaces"> <if:interface> <if:name>lo</if:name> </if:interface> <if:interface> <if:name>eth0</if:name> </if:interface> <if:interface> <if:name>virbr0</if:name> </if:interface> <if:interface> <if:name>pan0</if:name> </if:interface> </if:interfaces> </nc:data> </nc:rpc-reply>



2.10.3 Using Time Filters

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

• Timestamps are specified in date-and-time format (from the ietf-yang-types.yang module).

• The timestamp parameter 'if-modified-since' is added to the <get> and <get-config> operations.

• The timestamp monitoring node 'last-modified' is added to the /netconf-state/datastores/datastore list.

• The XML attribute 'last-modified' is added to the <rpc-reply> element for replies to <get> and <get-config> operations.

• The per-datastore last modified timestamp is for the entire datastore contents. If the 'if-modified-since' parameter is present in the <get> or <get-config> request, the the server will check the corresponding 'last-modified' timestamp.

◦ If the 'last-modified' timestamp is more recent than the 'if-modified-since' value, then the <get> or <get-config> operation is processed as normal.

◦ If the 'last-modified' timestamp is not more recent than the 'if-modified-since' value, then the <get> or <get-config> operation is not processed. Instead, an empty <data> element is returned. The 'last-modified' XML attribute in the <rpc-reply> will indicate the last modification timestamp for the datastore.

Example Request:

<?xml version="1.0" encoding="UTF-8"?> <get-config xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <source> <running/> </source> <if-modified-since xmlns="http://netconfcentral.org/ns/yuma-time-filter"> 2011-08-21T21:51:46Z</if-modified-since> </get-config></rpc>

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>


http://netconfcentral.org/ns/yuma-time-filter


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

• name: The mandatory YANG module name is unique within a YANG library. All modules and submodules share the same namespace, including modules used for deviations.

• revision date: Each YANG module within the library has a revision date. This is derived from the most recent revision statement within the module or submodule.

• submodule list: The name and revision date of each submodule used by main module.

• feature list: The name of each YANG feature supported by the server.

• deviation list: The name of each YANG module used for deviation statements.

• conformance-type:

◦ If 'implement', then the server is claiming conformance to the YANG module identified in this entry.

◦ If 'import', then the server is not claiming any conformance for the YANG module identified by this entry. The module may be needed for reusable definitions, such as extensions, features, identifies, typedefs, or groupings.

• schema: Contains a URL that represents the YANG schema resource for the module or submodule. This leaf will only be present if there is a URL available for retrieval of the schema for this entry.

• namespace: The XML namespace identifier for this module.

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

• module-set-id: Contains a server-specific identifier representing the current set of modules and submodules. The server will change the value of this leaf if the information represented by the 'module' list instances has changed.

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

• sget /modules-state

<?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.1Host: example.comAccept: application/yang-data+json

The server might respond:



HTTP/1.1 200 OKDate: Mon, 25 Apr 2012 11:10:30 GMTServer: example-serverContent-Type: application/yang-data+json

{ "ietf-yang-library:schema":

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



2.12 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.12.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.12.2 Using Custom Event Streams

The NETCONF notification delivery system allows for multiple event streams. Each event stream has its own subscriptions and its own notification queue (replay buffer). The server will always setup the NETCONF event stream. The notifications defined in ietf-netconf-notifications.yang are sent to this event stream.

Event streams can be used to group notification events for different reasons, such as by topic, or frequency, or severity..

The --event-stream parameter is used to configure an additional event stream.

The --event-stream-map parameter is used to assign all notifications defined in a specific module to an event stream.

Example: create the ‘hardware’ event stream and 2 event-stream-map entries:

> netconfd-pro --event-stream=hardware \ --event-stream-map=ietf-hardware@hardware \ --event-stream-map=openconfig-platform@hardware

Normally an event generated by internal YANG instrumentation will be sent to the NETCONF event stream. There are two ways for notifications to be sent to a configured stream:

1. New Server API: The instrumentation can specify the event stream name. If this is configured it will be used for the queued notification. If the specified event stream is not found or no event stream is specified in the API call, then the server will check for an event-stream-map parameter for the module containing the notification.

2. --event-stream-map CLI parameter: The user can configure module to event stream mappings. If no event stream is specified by the event generator (e.g., SIL instrumentation) then the server will use the event-stream-map parameter to find a mapping. If no mapping is found then the default event stream NETCONF is used.

Event Stream Monitoring


mailto:--event-stream-map%3Dopenconfig-platform@hardware

mailto:--event-stream-map%3Dopenconfig-platform@hardware

mailto:--event-stream-map%3Dietf-hardware@hardware

mailto:--event-stream-map%3Dietf-hardware@hardware


The event streams that are enabled on the server can be monitored using the notification.yang module, which contains a top-level container called /netconf.

Example: /netconf/streams/stream list contains ‘NETCONF’ and ‘hardware’ streams.

andy@localhost> sget /netconf

Filling container /netconf:RPC Data Reply 2 for session 3 [default]:

rpc-reply { data { netconf { streams { stream NETCONF { name NETCONF description 'default NETCONF event stream' replaySupport true replayLogCreationTime 2019-08-30T00:20:32Z } stream hardware { name hardware description 'vendor event stream' replaySupport true replayLogCreationTime 2019-08-30T00:20:32Z } } } }}

2.12.3 Subscriptions

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

It can be used in 4 different modes:

• Get all or some of the stored notifications.

◦ <startTime> and <stopTime> parameters used; The stop time is in the past.

• Get all or some of the stored notifications, then receive live notifications until some point in the future.

◦ <startTime> and <stopTime> parameters used; The stop time is in the future.

• Get all or some of the stored notifications, then start receiving live notifications until the session is terminated.

◦ <startTime> parameter used, but <stopTime> parameter is not used

• Start receiving live notifications until the session is terminated

◦ neither <startTime> or <startTime> are used

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



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

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

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



2.12.4 Notification Log

Each system event is saved to the notification replay buffer for the NETCONF event stream.

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

Each event stream has its own replay buffer. The size of each replay buffer is controlled by the --eventlog-size configuration parameter.

The default size is 1000 events.

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

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

Each event in the replay buffer is assigned a sequential sequence ID, starting from 1. Each event stream has its own sequence ID counter. Values are only specific to one event stream and will be duplicated in each event stream.

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



2.12.5 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.12.6 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 contentin 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.12.7 <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.12.8 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. 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 (Default)

2. 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 (Deprecated)


http://netconfcentral.org/ns/system


2.12.9 <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.12.10 <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.12.11 <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.

The system-notifications parameter must include “yuma” for this event to be generated.

<sysStartup> notification

Description: The netconfd-pro server has started

Min parameters: 0

Max parameters: 2


Parameters:

• startupSource

◦ type: string

◦ usage: optional (will not be present if --no-startup was present)

◦ This parameter identifies the local file specification associated with the source of the startup configuration contents.

• bootError

◦ type: list (same structure as <rpc-error> element)

◦ usage: optional (will only be present if errors were recorded during boot)

◦ There will be one entry for each <rpc-error> encountered during the load config operation. The <rpc-error> fields are used directly.

◦ There is no particular order, so no key is defined.

◦ All fields except <error-info> will be present from the original <rpc-error> that was generated during the boot process.

Example:

<?xml version="1.0" encoding="UTF-8"?> <ncEvent:notification xmlns:ncEvent="urn:ietf:params:xml:ns:netconf:notification:1.0"> <ncEvent:eventTime>2009-07-29T17:21:13Z</ncEvent:eventTime> <sys:sysStartup xmlns:sys="http://netconfcentral.org/ns/system"> <sys:startupSource> /home/andy/swdev/yuma/trunk/netconf/data/startup-cfg.xml </sys:startupSource> </sys:sysStartup> <sys:sequence-id xmlns:sys="http://netconfcentral.org/ns/system">1 </sys:sequence-id> </ncEvent:notification>


http://netconfcentral.com/ns/system


2.12.12 <netconf-session-start> Event

The <netconf-session-start> notification is generated when a NETCONF session is started.

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

<netconf-session-start> notification

Description: A new NETCONF session has started.

Min parameters: 3

Max parameters: 3

YANG file: ietf-netconf-notifications.yang

Parameters:

• username

◦ type: string


◦ This parameter identifies the SSH user name that is associated with the session.

• session-id

◦ type: uint32 (range 1 to max)


◦ This parameter identifies the NETCONF session ID assigned to the session.

• source-host

◦ type: inet:ip-address


◦ This parameter identifies the remote host IP address that is associated with the session.

Example:

<?xml version="1.0" encoding="UTF-8"?> <notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0"> <eventTime>2018-04-20T18:38:08Z</eventTime> <netconf-session-start xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-notifications"> <username>andy</username> <session-id>4</session-id> <source-host>127.0.0.1</source-host> </netconf-session-start> </notification>



2.12.13 <netconf-session-end> Event

The <netconf-session-end> notification is generated when a NETCONF session is terminated.

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

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

<netconf-session-end> notification

Description: A NETCONF session has terminated.

Min parameters: 1

Max parameters: 5


Parameters:

• username

◦ type: string


◦ This parameter identifies the SSH user name that is associated with the session.

• session-id




• source-host




• killed-by


◦ usage: optional (will only be present if the terminationReason leaf is equal to 'killed'.

◦ This parameter identifies the session number of the session that issued the <kill-session> operation.

• termination-reason

◦ type: enumeration (closed, killed, dropped, timeout, bad-start, bad-hello, other)


◦ This parameter indicates why the session was terminated.



Example:

<?xml version="1.0" encoding="UTF-8"?> <notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0"> <eventTime>2018-04-20T18:41:01Z</eventTime> <netconf-session-end xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-notifications"> <username>andy</username> <session-id>4</session-id> <source-host>127.0.0.1</source-host> <killed-by>4</killed-by> <termination-reason>closed</termination-reason> </netconf-session-end> </notification>



2.12.14 <netconf-config-change> Event

The <netconf-config-change> notification is generated when the <running> configuration database is altered by a NETCONF session.

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

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

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

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

If multiple changes are made at once, then one <netconf-config-change> event will be generated for each change.

If the --with-yumaworks-config-change parameter is set to ‘true’ then the <new-value> and <old-value> fields will be added to each edit list entry as needed.

<netconf-config-change> notification

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

Min parameters: 4

Max parameters: 4


Parameters:

• changed-by:

◦ username

▪ type: string

▪ usage: mandatory

▪ This parameter identifies the SSH user name that is associated with the session.

◦ session-id

▪ type: uint32 (range 1 to max)


▪ This parameter identifies the NETCONF session ID assigned to the session.

◦ source-host

▪ type: inet:ip-address


▪ This parameter identifies the remote host IP address that is associated with the session.

• datastore

◦ type: string


◦ This parameter identifies the datastore that changed



• edit

◦ list (with no key) of edit operations performed, 1 entry for each edit:

▪ target

• type: instance-identifier

• usage: mandatory

• This parameter contains the absolute path expression of the database object node that was modified.

▪ operation

• type: enumeration (merge, replace, create, delete)


• This parameter identifies the nc:operation that was performed on the target node in the database.

▪ new-value

• type: anyxml

• usage: optional (if --with-yumaworks-config-change=true)

• This parameter contains the new value for the associated 'target' if the operation is not 'delete' or 'remove'. This object should represent a container with one child node specifying the new value used in the associated edit.

▪ old-value

• type: anyxml

• usage: optional (if --with-yumaworks-config-change=true)

• This parameter contains the old value for the associate 'target' that waschanged or deleted, if operation is not 'create', This object should represent a container with one child node specifying the current value used in the associated edit.

Example:

<?xml version="1.0" encoding="UTF-8"?> <notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0"> <eventTime>2018-04-20T19:31:44Z</eventTime> <netconf-config-change xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-notifications"> <changed-by> <username>andy</username> <session-id>3</session-id> <source-host>127.0.0.1</source-host> </changed-by> <datastore>running</datastore> <edit> <target xmlns:nacm="urn:ietf:params:xml:ns:yang:ietf-netconf-acm">/nacm:nacm</target> <operation>create</operation> </edit> </netconf-config-change> </notification>

Examples --with-yumaworks-config-change:



Create Operation:

<?xml version="1.0" encoding="UTF-8"?> <notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0"> <eventTime>2019-06-11T02:39:15Z</eventTime> <netconf-config-change xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-notifications"> <changed-by> <username>andy</username> <session-id>3</session-id> <source-host>127.0.0.1</source-host> </changed-by> <datastore>running</datastore> <edit> <target xmlns:t="http://netconfcentral.org/ns/test">/t:int8.1</target> <operation>create</operation> <new-value xmlns="http://yumaworks.com/ns/yumaworks-config-change"> <int8.1 xmlns="http://netconfcentral.org/ns/test">42</int8.1> </new-value> </edit> </netconf-config-change> </notification>

Modify Operation:

<?xml version="1.0" encoding="UTF-8"?> <notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0"> <eventTime>2019-06-11T02:42:19Z</eventTime> <netconf-config-change xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-notifications"> <changed-by> <username>andy</username> <session-id>3</session-id> <source-host>127.0.0.1</source-host> </changed-by> <datastore>running</datastore> <edit> <target xmlns:t="http://netconfcentral.org/ns/test">/t:int8.1</target> <operation>replace</operation> <new-value xmlns="http://yumaworks.com/ns/yumaworks-config-change"> <int8.1 xmlns="http://netconfcentral.org/ns/test">1</int8.1> </new-value> <old-value xmlns="http://yumaworks.com/ns/yumaworks-config-change"> <int8.1 xmlns="http://netconfcentral.org/ns/test">42</int8.1> </old-value> </edit> </netconf-config-change> </notification>

Delete Operation:



<?xml version="1.0" encoding="UTF-8"?> <notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0"> <eventTime>2019-06-11T02:42:51Z</eventTime> <netconf-config-change xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-notifications"> <changed-by> <username>andy</username> <session-id>3</session-id> <source-host>127.0.0.1</source-host> </changed-by> <datastore>running</datastore> <edit> <target xmlns:t="http://netconfcentral.org/ns/test">/t:int8.1</target> <operation>delete</operation> <old-value xmlns="http://yumaworks.com/ns/yumaworks-config-change"> <int8.1 xmlns="http://netconfcentral.org/ns/test">1</int8.1> </old-value> </edit> </netconf-config-change> </notification>

2.12.15 <netconf-capability-change> Event

The <netconf-capability-change> notification is generated when the set of active capabilities for the server has changed.

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

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

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

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

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

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

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

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

<netconf-capability-change> notification

Description: The set of currently active <capability> URIs has changed

Min parameters: 2

Max parameters: 5


Parameters:



• choice changed-by (server or by-user)

◦ server

▪ type: empty


▪ If this empty leaf is present, then the server caused the capability change.

◦ case by-user (if a NETCONF session caused the capability change)

▪ username

• type: string


• This parameter identifies the SSH user name that is associated with the session.

▪ session-id

• type: uint32 (range 1 to max)


• This parameter identifies the NETCONF session ID assigned to the session.

▪ source-host

• type: inet:ip-address


• This parameter identifies the remote host IP address that is associated with the session.

• added-capability

◦ type:leaf-list of capability URI strings

◦ usage: optional

◦ This parameter contains one entry for each capability that was just added

• deleted-capability

◦ type:leaf-list of capability URI strings

◦ usage: optional

◦ This parameter contains one entry for each capability that was just deleted.

Example:

<?xml version="1.0" encoding="UTF-8"?> <notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0"> <eventTime>2018-04-20T19:37:34Z</eventTime> <netconf-capability-change xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-notifications"> <changed-by> <username>andy</username> <session-id>3</session-id> <source-host>127.0.0.1</source-host> </changed-by> <added-capability>http://netconfcentral.org/ns/test4?module=test4&revision=2009-09-09</added-capability>



</netconf-capability-change> </notification>



2.12.16 <netconf-confirmed-commit> Event

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

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

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

• start: A confirmed-commit procedure has started.

◦ Sent once when the first <commit> operation is executed.

◦ This event starts the confirmed-commit procedure.

◦ If the <candidate> database is not altered, then the confirmed commit procedure will be skipped.

• cancel: A confirmed-commit procedure has been canceled

◦ Sent only if the original session is terminated.

◦ This event terminates the confirmed-commit procedure.

• timeout: A confirmed-commit procedure has timed out.

◦ Sent only if the confirm-timeout interval expires.


• extend: A confirmed-commit procedure has been extended.

◦ Sent if the 2nd to N-1th <confirm> operation contains a <confirmed/> parameter.

◦ This event restarts the confirm-timeout interval, but does not reset the backup database.

◦ Any new changes in the <candidate> database will be committed.

• complete: A confirmed-commit procedure has completed.

◦ Sent if the 2nd to Nth <commit> operation is executed before the confirm-timeout interval expires.


<netconf-confirmed-commit> notification

Description: The state of the confirmed-commit procedure has changed.

Min parameters: 1

Max parameters: 4


Parameters:

• username

◦ type: string




◦ This parameter identifies the SSH user name that is associated with the session that caused the confirmed-commit procedure state change.

• session-id




• source-host




• confirm-event

◦ type: enumeration (start, cancel, timeout, extend, complete)


◦ This parameter indicates why the confirmed-commit procedure changed state.

Examples:

<?xml version="1.0" encoding="UTF-8"?> <notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0"> <eventTime>2018-04-20T19:41:34Z</eventTime> <netconf-confirmed-commit xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-notifications"> <username>andy</username> <session-id>3</session-id> <source-host>127.0.0.1</source-host> <confirm-event>start</confirm-event> <timeout>10</timeout> </netconf-confirmed-commit> </notification>

<?xml version="1.0" encoding="UTF-8"?> <notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0"> <eventTime>2018-04-20T19:41:44Z</eventTime> <netconf-confirmed-commit xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-notifications"> <confirm-event>timeout</confirm-event> </netconf-confirmed-commit> </notification>



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

• leaf module-set-id

◦ type:leafref. Path: "/yanglib:modules-state/yanglib:module-set-id"


◦ Contains the module-set-id value representing the set of modules and submodules supported at the server at thetime the notification is generated

Example:

<?xml version="1.0" encoding="UTF-8"?> <notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0"> <eventTime>2016-11-15T18:03:29Z</eventTime> <yang-library-change xmlns="urn:ietf:params:xml:ns:yang:ietf-yang-library"> <module-set-id>6765</module-set-id> </yang-library-change> </notification>



2.13 High Availability (YP-HA)

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

• The configuration data on the active server can be replicated on multiple standby servers.

• The module and bundle configuration on the active server can be replicated on multiple standby servers, even if modules or bundles are loaded or unloaded at run-time.

• An HA server pool is configured through the CLI or configuration file. Only servers specified in the configuration are allowed to join the YP-HA server pool.

• Each HA server operates in a specific HA Role

◦ active: There is one active server in the HA pool providing full service and management features.

◦ standby: All but one server can be in Standby mode. Only superuser sessions are allowed in this mode. Notifications are disabled. The server will connect to the active server and participate in the YP-HA protocol.

◦ none: The server is waiting its HA role. It is not attempting to connect to any active server. Only superuser sessions are allowed in this mode. Notifications are disabled.

• The server HA Role (Active, Standby, or None) can be switched in several ways

◦ yp-system library init1 function callback (to set initial role)

◦ agt_timer callbacks at run-time

◦ DB-API subsystem using the <yp-ha-mode> subsystem event message

◦ yp-ha-app program

▪ yp-ha-app –go-active

▪ yp-ha-app –go-standby=new-active

▪ yp-ha-app –go-none

• Management sessions and notification processing are disabled if the server is in HA standby mode

◦ Management sessions are enabled for the “superuser” user name if configured

• SIL-SA and DB-API sessions are always allowed, even if YP-HA is in standby mode

• DB-API edit requests for system edits will be enabled in a future release

• DB-API edit requests for user edits are disabled if the server is in HA standby mode

• The –ha-sil-standby parameter can be used to enable edit callbacks (SIL, SIL-SA, HOOK) on a server running in HA standby mode. The server callback code must understand that YP-HA is enabled and the server is running in HA standby mode.

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

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

If the server boots waiting for its HA role, then an empty factory default configuration will be loaded in order to validate theYANG 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.13.1 YP-HA Configuration

YP-HA CLI Parameters


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

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

Configuration parameters for Server ha-1:



haenabled true haserver ha[email protected] haserver ha[email protected]server ha[email protected] haserverkey hapool1 serverid ha1 sockettype tcp socketaddress 192.168.0.100 socketport 8088


haenabled true haserver ha[email protected] haserver ha[email protected]server ha[email protected] haserverkey hapool1 serverid ha2sockettype tcp socketaddress 192.168.0.105socketport 8088


haenabled true haserver ha[email protected] haserver ha[email protected]server ha[email protected] haserverkey hapool1 serverid ha3sockettype tcp socketaddress 192.168.0.108socketport 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.






2.14 Configuration Templates

Configuration templates allow some parts of the configuration datastore to be pre-configured.

This can be done to pre-populate vendor or site-specific values, allowing the actual configuration to be simpler and more generic.

Configuration templates are stored in the running configuration in list “/templates/template”. There are only 3 fields in a template:

• name: the name of the template (list key)

• data-target: path of the container or list that matches the template

• data: anydata wrapper for the configuration template data

A template is used by specifying the <with-template> parameter in the <edit-config> operation.

Multiple instances of this parameter can be present, allowing multiple templates to be applied or attempted.

If a template does not apply it is ignored.

If a template does apply, then the child nodes specified in the template are applied if they are not already present in the edit request. Templates are only applied to “create” operations. The values are expanded on first use of the configuration data indicated by the <data-target> field in the template. If this data represents a list entry, this this data must specify all key values.

If list keys are present in the configuration template then the template will only be applied if these values match the same key leaf value in the target data.



2.14.1 yumaworks-templates.yang

module yumaworks-templates { yang-version 1.1; namespace "http://yumaworks.com/ns/yumaworks-templates";

prefix "ytemp"; import ietf-netconf { prefix nc; } import yuma-types { prefix yt; }

organization "YumaWorks, Inc.";

contact "Support <support at yumaworks.com>";

description "Configuration templates. These are used to pre-provision full or partial configuration subtrees that can be used like YANG defaults to provide missing values in actual configuration data.

A configuration template con be specified for a container or a list, at any depth in the YANG data model.

Configuration templates are only applied when a new instance of configuration data is created by a client with the <edit-config> operation, and only if the <with-template> parameter is used.

The template is expanded when the data is created in the candidate or running datastore. The SIL code and all validation is done post-expansion.

Configuration data is applied from the template to the data target node in the following manner:

* Only the child nodes of the data target node are compared for replacement. * If the corresponding child node already exists and not created by default, then the template child node is not copied. * If the template child node is defined within a YANG choice, then it will only be applied if no case is selected, or the same case is selected in the data target node.

The /templates configuration subtree is used to configure named templates that can be used with the <with-template> parameter added to the <edit-config> operation to apply named templates to configuration requests.

The with-template leaf-list parameter is added to the edit-config operation. Multiple templates can be applied to the same edit, if the template matches the edit.

A template can match the edit with 3 different tests.



Only test (1) and (2) are mandatory.

1) with-template=<name>, where <name> matches an instance of /templates/template/name 2) the template <data-target> identifies the same object as the new data node being created 3) if the template contains list keys then it will only be applied if the new data instance has the same key value, for each key leaf present in the template. A missing key leaf matches all instances of the data target.

Copyright (c) 2017 YumaWorks, Inc. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, is permitted pursuant to, and subject to the license terms contained in, the BSD 3-Clause License http://opensource.org/licenses/BSD-3-Clause.

";

revision 2017-02-20 { description "Initial version"; }

augment /nc:edit-config/nc:input { description "Add the <with-template> parameter to the edit-config operation"; leaf-list with-template { type yt:yang-identifier; // must match a template name ordered-by user; description "Identifies a configuration template to use for this edit operation. The 'target-path' parameter within the template will be matched to data in the configuration request. Templates will be checked in the order given, in case multiple templates for the same data node are provided."; } }

container templates { list template { key name;

leaf name { type yt:yang-identifier; description "Name of the template"; }

leaf data-target { type string; mandatory true; description "Identifies the configuration data object that corresponds to this template. This must be a data node path expression. It is formatted like a RESTCONF path expression, except module names are not mandatory if they are unique. Only the data nodes are specified. No list keys



can be provided for the template.

Example: /ietf-interfaces:interfaces/interface "; }

anydata data { mandatory true; description "Contains a single child element that corresponds to the data node identified by the data-target leaf. This subtree does not need to represent a complete data resource. It must contain well-formed YANG data node representations. YANG validation will only be attempted on real configuration data after the template data has been applied."; } } }

}



2.14.2 Configuration Template Example: NACM group

Example template “t1”:

<templates xmlns="http://yumaworks.com/ns/yumaworks-templates"> <template> <name>t1</name> <data-target>/nacm/groups/group</data-target> <data> <group xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm"> <name>admin</name> <user-name>andy</user-name> <user-name>test1</user-name> <user-name>test2</user-name> </group> </data> </template> </templates>

Example <edit-config> request using <with-template> parameter:

<?xml version="1.0" encoding="UTF-8"?><rpc message-id="8" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <edit-config> <target><candidate/></target> <config> <nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm"> <groups> <group> <name>admin</name> </group> </groups> </nacm> </config> <with-template xmlns="http://yumaworks.com/ns/yumaworks-templates">t1</with-template> </edit-config></rpc>

The following data will be created after template “t1” is applied

<nacm xmlns="urn:ietf:params:xml:ns:yang:ietf-netconf-acm"> <groups> <group> <name>admin</name> <user-name>andy</user-name> <user-name>test1</user-name> <user-name>test2</user-name> </group> </groups> </nacm>


http://yumaworks.com/ns/yumaworks-templates


2.15 NETCONF Over TLS

The NETCONF over TLS protocol is defined in RFC 7589

• https://www.ietf.org/rfc/rfc7589.txt

If the server image is built with the WITH_OPENSSL=1 parameter (or EVERYTHING=1 parameter) then NETCONF overTLS support will be available.

2.15.1 TLS Configuration

The following CLI and configuration parameters are available to support NETCONF over TLS sessions:

CLI Parameters for NETCONF over TLS


--cert-default-user DEBUG only default user-name to use if no user-certmap found for an incoming NETCONF over TLS session

--cert-usermap Map a client user-name to a X.509 fingerprint for the client certificate. Required for each user name to be used with NETCONF over TLS

--insecure-ok DEBUG only option to accept cleint certificates that cannot be verified in the local truststore

--netconf-tls-address The IP address to listen for NETCONF over TLS sessions.The default is 0.0.0.0

--netconf-tls-cerificate The public certificate file that must be provided to use NETCONF over TLS

--netconf-tls-key The private certificate file that must be provided to use NETCONF over TLS

--netconf-tls-port The TCP port to listen for NETCONF over TLS sessions.The default is 6513

--netconf-tls-trust-store The file or directory to look for client certificates to determine if they are trusted

--with-netconf-tls This flag must be set to true to enable NETCONF over TLS


https://www.ietf.org/rfc/rfc7589.txt


2.16 IETF Call Home

The IETF Call Home feature (RFC 8071) provides the following features:

• Supports Call Home for NETCONF over SSH, and NETCONF over TLS, as defined in RFC 8071.

• allows the server to initiate the TCP connection to 1 or more managers that implement IETF Call Home, called a “callhome server”.

• allows NETCONF sessions to be started through firewalls

• allows server discovery and bootstrap configuration

2.16.1 Call Home Configuration

Call Home CLI Parameters


--callhome-reconnect Specifies whether server will reconnect after client closes the session.

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

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

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

--callhome-tls-server Specifies a callhome/TLS server that this server should attempt to initiate a callhome connection at boot-time.

--callhome-sshd-command Specifies the command used in Call Home to invoke the SSH server

--callhome-sshd-config Specifies the filespec for the config file used in Call Home to invokethe SSH server

--callhome-subsys-command Specifies the command used in Call Home to invoke the netconf subsystem

--with-callhome Enable or disable the IETF Call Home protocol

Notes for N#ETCONF over SSH Call Home:

• The CallHome over SSH port is called “netconf-ch-ssh” by IANA.

• The default TCP port number is 4334.

• The netconfd-pro server probably needs to be started with “su”

• If the --with-callhome parameter is set to 'true' then the netconfd-pro server will check if any --callhome-server parameters are provided. If not, then the Call Home feature will not be used on the server.



• The server will fork a process for each callhome server that will attempt a TCP connection to one of the callhome servers configured on the netconfd-pro server.

• If the TCP connection succeeds the SSH server will be called in “inetd” mode. The SSH server will wait for the client (callhome server) to initiate an SSH session to the netconfd-pro server.

• If the client successfully initiates a NETCONF session, a new incoming session will be started on the server in the normal manner. The server will check if the incoming session was started by callhome, in order to skip the TCP port checks. The source port will not be 830 (or whatever is specified in the –port CLI parameter), but rather the source port used by the server to initiate the TCP connection.

In this example there are 3 separate systems, 1 netconfd-pro server and 2 callhome servers

Configuration parameters for the netconfd-pro server:

netconfd-pro {callhome-reconnect truecallhome-retry-interval 30 callhome-retry-max 10callhome-server [email protected] [email protected] true

}



3 CLI ReferenceThe netconfd-pro program uses command line interface (CLI) parameters to control program behavior.

The following sections document all the YumaPro CLI parameters relevant to this program, in alphabetical order.

3.1 --access-control

The --access-control parameter specifies how access control is enforced in the netconfd-pro program.

It is an enumeration with the following values:

• enforcing: All configured access control rules will be enforced.

• permissive: All configured access control rules will be enforced for write and execute requests. All read requests will be allowed, unless the requested object contains the nacm:default-deny-all extension. In that case, all configured access control rules will be enforced, and no default access will be allowed.

• disabled: All read, write, and execute requests will be allowed, unless the object contains the nacm:default-deny-write or nacm:default-deny-all extension.

◦ If the nacm:default-deny-write extension is in effect, then all configured access control rules will be enforcedfor write and execute requests.

◦ If the nacm:default-deny-all extension is in effect, then all configured access control rules will be enforced for all requests. Use this mode with caution.

• off: All access control enforcement is disabled. Use this mode with extreme caution.

--access-control parameter

Syntax enumeration: enforcing permissive disabled off

Default: enforcing

Min Allowed: 0

Max Allowed: 1

Supported by: netconfd-pro

Example: netconfd-pro \ --access-control=permissive



3.2 --allow-leaflist-delete-all

The –allow-leaflist-delete-all parameter controls whether the YumaPro extension “delete-all” operation should be allowed for leaf-list objects. If true, then the client can send nc:operation=”delete-all” or nc:operation=”remove-all”, and the server will accept the edit if the target node is a leaf-list object. Do not provide a value for the leaf-list.

These operations have the following meaning:

• delete-all: delete all instances of the leaf-listReturn a 'data-missing' error if there are no instances of the leaf-list

• remove-all: delete all instances of the leaf-listReturn 'OK' if there are no instances of the leaf-list

--allow-leaflist-delete-all parameter

Syntax boolean

Default: false

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro \ –allow-leaflist-delete-all=true



3.3 --allow-list-delete-all

The –allow-list-delete-all parameter controls whether the YumaPro extension “delete-all” operation should be allowed for list objects. If true, then the client can send nc:operation=”delete-all” or nc:operation=”remove-all”, and the server will accept the edit if the target node is a list object. The key leaf values should not be provided.

These operations have the following meaning:

• delete-all: delete all instances of the listReturn a 'data-missing' error if there are no instances of the list

• remove-all: delete all instances of the listReturn 'OK' if there are no instances of the list

--allow-list-delete-all parameter

Syntax boolean

Default: false

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro \ –allow-list-delete-all=true

3.4 --allowed-user

The --allowed-user parameter specifies a set of user names that are allowed to login and use the server.

• If none are configured then this parameter will have no affect on access control.

• If the “superuser” account name is configured, then logins to the superuser account will bypass access control and not be checked against the allowed-user list.

• If any allowed-user names are configured, then the user name for a new session must be in the configured allowed-user list. If not, then the session will be denied with an NCX_ERR_ACCESS_DENIED status code.

--allowed-user parameter

Syntax string (NcxName)

Default: none

Min Allowed: 0

Max Allowed: no limit


Example: netconfd-pro --allowed-user=fred \ allowed-user=barney \ allowed-user=admin



3.5 --alt-names

The --alt-names parameter 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. This defines the alternate name search mode that should be used when resolving YANG node names in leafs or leaf-lists using the UrlPath data type.

• If 'true' then nodes with an 'alt-name' defined will be considered a match if the YANG name or the alternative namematches the search string.

• If 'false' then only the YANG node name will be used in node name searches.";

The real name will be checked before the alt-name if it is used, so the alt-name extension cannot be used if there is a node already in the system with a real name that matches the alt-name.

--alt-names parameter

Syntax boolean

Default: true

Min Allowed: 0

Max Allowed: 1

Supported by: netconfd-proyangcli-pro

Example: netconfd-pro --alt-names=false



3.6 --annotation

The --annotation parameter is a leaf-list of modules that should be loaded automatically when the program starts, as a deviation module containing annotations. In this mode, only the deviation statements are parsed and then made available later when the module that contains the objects being deviated is parsed. The annotation file is not advertised to clients or shown in the YANG library.

The program will attempt to load each module in annotation parsing mode, in the order the parameters are entered. All deviation parameters will be processed, then all annotation parameters. An annotation module is just a YANG module that contains only 'deviation' statements with “deviate add” sub-statements.

The following example module shows how annotations could be added to the ietf-interfaces module

module devtest1-d {

namespace "http://netconfcentral.org/ns/devtest1-d"; prefix dt1-d; import ietf-interfaces { prefix if; } import yuma-ncx { prefix ncx; }

revision "2016-04-10"; deviation /if:interfaces { deviate add { ncx:sil-delete-chilren-first; } }

deviation /if:interfaces/if:interface { deviate add { ncx:sil-delete-chilren-first; } }

}

--annotation parameter

Syntax string

Default: none

Min Allowed: 0

Max Allowed: unlimited


Example: netconfd-pro –annotation=devtest1-d



3.7 --audit-log

The --audit-log parameter specifies the file path of the configuration edit audit log. If this parameter is present, then edits to the running database will cause an audit log entry to be created for each edit point. This is done in addition to normal logging, but it is not affected by the –log-level parameter. The –no-audit-log parameter cannot be present if this parameter is present. The –audit-log-events parameter selects the event types that are recorded in the audit log file.

--audit-log parameter

Syntax filespec

Default: none

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro \ --audit-log=/var/log/nc-audit.log&

3.8 --no-audit-log

The –no-audit-log parameter specifies that no default audit log will be created. This parameter is only relevant if –fileloc-fhs=true. The –audit-log parameter cannot be present if this parameter is present.

--no-audit-log parameter

Syntax empty

Default: none

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro –fileloc-fhs=true \ --no-audit-log



3.9 --audit-log-append

The --audit-log-append parameter specifies that the existing audit log file (if any) should be appended, instead of deleted. It is ignored unless the --audit-log parameter is present.

--audit-log-append parameter

Syntax empty

Default: none

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro \ --audit-log=/var/log/ncaudit.log \ --audit-log-append&

3.10 --audit-log-candidate

The --audit-log-candidate parameter specifies whether edit transactions on the candidate datastore are recorded in the auditlog or not. If true, then edits to the candidate datastore are recorded. If false, then edits to the candidate datastore are not recorded.

--audit-log-candidate parameter

Syntax boolean

Default: true

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro \ --audit-log=/var/log/ncaudit.log \ --audit-log-candidate=false&



3.11 --audit-log-console-level

The –audit-log-console-level parameter controls the minimum logging level needed to log datastore audit records to the server console log. This does not affect output to the audit log.

There are 7 settings that can be used:

• none: All logging is suppressed. Use with extreme caution!

• error: Error messages are printed, indicating problems that require attention.

• warn: Warning messages are printed, indicating problems that may require attention.

• info: Informational messages are printed, that indicate program status changes.

• debug: Debugging messages are printed that indicate program activity.

• debug2: Protocol debugging and trace messages are enabled.

• debug3: Very verbose debugging messages are enabled. This has an impact on resources and performance, and should be used with caution.

--audit-log-console-level parameter

Syntax enumeration: off error warn info debug debug2 debug3 debug4

Default: --debug

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro \ –audit-log-console-level=info



3.12 --audit-log-events

The –audit-log-events parameter controls the event types that are output to the audit log. It has no affect unless the audit-log is enabled.

This parameter uses the YANG “bits” type, so any combination of the following bit definitions are permitted:

• edit-candidate: Save candidate datastore edit events in the audit log. If the --audit-log-candidate parameter is set to true, or the <candidate> datastore is not present, then this bit will be ignored. By default, the --audit-log-candidate parameter is set to “true” so this event type will be present in the audit log by default. To remove these events, est --audit-log-candidate=false and do not set this bit.

Example audit log entry:

edit-transaction 9616: on session 3 by [email protected] time: 2018-09-04T20:44:44Z message-id: 2 trace-id: -- datastore: candidate operation: create target: /t:int16.1 comment: none

• edit-running: Save running datastore edit events in the audit log.


edit-transaction 9617: on session 3 by [email protected] time: 2018-09-04T20:44:47Z message-id: 3 trace-id: -- datastore: running operation: create target: /t:int16.1 comment: none

• update-startup: Save startup datastore update events in the audit log. If the <startup> datastore is not present thenthis bit will be ignored.


update-startup on session 3 by [email protected] time: 2018-09-04T20:44:52Z message-id: 5 sourcetype: datastore source: running



• client-session: Save client session start and end events in the audit log.

Example audit log entries (start-client-session and end-client-session)

start-client-session: time: 2018-09-04T20:44:31Z protocol: NETCONF transport: netconf-ssh username: andy peeraddr: 127.0.0.1 session ID: 3

end-client-session: time: 2018-09-04T20:50:23Z protocol: NETCONF 1.1 transport: netconf-ssh username: andy peeraddr: 127.0.0.1 session ID: 3 term reason: closed killed-by: 3

• control-session: Save YControl session start and end events in the audit log.

Example audit log entries (start-control-session and end-control-session)

start-control-session: time: 2018-09-04T20:53:59Z protocol: YControl transport: netconf-aflocal username: andy peeraddr: 127.0.0.1 session ID: 3

end-control-session: time: 2018-09-04T21:02:39Z protocol: YControl transport: netconf-aflocal username: andy peeraddr: 127.0.0.1 session ID: 3 term reason: dropped killed-by: 0

• acm-write-error: Save access control write access denied events in the audit log.




nacm-write-error: time: 2018-09-04T21:04:51Z username: andy operation: create leaf int32.1 path:: /t:int32.1

• acm-exec-error: Save access control execute access denied events in the audit log.


nacm-exec-error: time: 2018-09-04T21:08:54Z username: andy module name: yumaworks-system RPC name: load

• rpc-summary: Save RPC summary events in the audit log.


RPC <get> on session 3 by [email protected] start-time: 2019-12-12T01:35:47Z end-time: 2019-12-12T01:35:47Z message-id: 2 reply-type: data status: 0:ok

• edit-data: Add plain display output of the data that is being edited in an edit transaction. This bit has no affect unless the edit-candidate or edit-running bit is also set. Note that this added data could represent a security risk since it could expose sensitive configuration data contents. Use this option with caution.

◦ The ‘new value’ data will be added if the edit has a new value (create, modify).

◦ The ‘current value’ will be added if the edit has a current value (modify, delete)

Example audit log entries for create, modify and delete a leaf “uint16.1”:

edit-transaction 187: on session 3 by [email protected] time: 2020-06-06T01:19:52Z message-id: 3 trace-id: -- datastore: running operation: create target: /t:uint16.1 comment: none new value: t:uint16.1 10




edit-transaction 189: on session 3 by [email protected] time: 2020-06-06T01:21:11Z message-id: 5 trace-id: -- datastore: running operation: replace target: /t:uint16.1 comment: none new value: t:uint16.1 20 old value: t:uint16.1 10

edit-transaction 191: on session 3 by [email protected] time: 2020-06-06T01:21:24Z message-id: 7 trace-id: -- datastore: running operation: delete target: /t:uint16.1 comment: none old value: t:uint16.1 20

--audit-log-events parameter

Syntax bits: edit-candidate edit-running update-startup client-session control-session acm-write-error acm-exec-error rpc-summary edit-data

Default: edit-running

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro \ –audit-log-events=”edit-candidate edit-data edit-running client-session”



3.13 --audit-log-level

The –audit-log-level parameter controls the minimum logging level needed to log datastore audit records to the audit log. This does not affect debug logging to the server console log. This parameter has no affect unless the –audit-log parameter is also used.









--audit-log-level parameter


Default: --info

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro –audit-log-level=debug \ --audit-log=~/server-audit.log&



3.14 --autodelete-pdu-error

The –autodelete-pdu-error parameter specifies whether auto-deletion of a configuration parameter provided in an edit PDU is treated as an error or not. If true, then configuration nodes provided in the edit payload (e.g., <config> element) thatare conditional on 'when' statements must evaluate to true or else an operation-failed error will be returned. If false, then such 'false when' will be silently removed from the target datastore.

--autodelete-pdu-error parameter

Syntax boolean

Default: true

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro \ --autodelete-pdu-error=false

3.15 --binary-display-maxlen

The --binary-display-maxlen parameter specifies the maximum number of bytes to display when dumping the contents of a binary value. Normally a message will be displayed showing the name and length.

If this parameter is set to a value greater than zero then a standard 8-byte per line hex dump of the binary type will also be displayed for a maximum number of bytes set by this parameter.

--binary-display-maxlen parameter

Syntax uint32

Default: 0

Min Allowed: 0

Max Allowed: 1

Supported by: yangcli-pro, netconfd-pro

Example: netconfd-pro \ --binary-display-maxlen=100

3.16 --bundle

The --bundle parameter is a leaf-list of SIL bundle names that should be loaded automatically when the program starts.

The program will attempt to load each SIL bundle in the order the parameters were entered.



If any SIL bundle initialization callback functions return any error, then the program will terminate. There cannot be any errors in any of the YANG modules in the SIL bundle.

--bundle parameter

Syntax SIL bundle name

Default: none

Min Allowed: 0



Example: netconfd-pro --bundle=interfaces

3.17 --callhome-reconnect

The –callhome-reconnect parameter specifies whether server will reconnect after client closes the session. If 'true' the server will attempt to start a new callhome connection if the client closes the session. If 'false' the server will not attempt to start a new callhome session after the client closes the session.

Be careful that the server is running with proper permissions because a successful connection that fails during authentication will cause a reconnect loop if this parameter is set to 'true'.

--callhome-reconnect parameter

Syntax boolean

Default: false

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro –callhome-reconnect=true



3.18 --callhome-retry-interval

The –callhome-retry-interval parameter specifies the number of seconds to wait after a connect attempt to the callhome server has failed before attempting another connect attempt to that server.

--callhome-retry-interval parameter

Syntax uint16 [1..max]

Default: 60 seconds

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro –callhome-retry-interval=30

3.19 --callhome-retry-max

The –callhome-retry-max parameter specifies the number of retry attempts the server should attempt to the callhome server before giving up. The value 0 indicates the server should never give up.

--callhome-retry-max parameter

Syntax uint16

Default: 10

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro –callhome-retry-max=0



3.20 --callhome-server

The –callhome-server parameter specifies a callhome/SSH server that this server should attempt to initiate a callhome connection at boot-time. This is a leaf-list parameter and multiple entries are supported.

This string has the format:

<server-id> '@' <server-addr> [ ':' <port-num> ]

[email protected] [email protected]:12040

The server-id parameter is used for logging purposes.

This parameter is ignored if the --with-callhome parameter is set to 'false'.

--callhome-server parameter

Syntax string

Default: none

Min Allowed: 0



Example: netconfd-pro \ –[email protected]



3.21 --callhome-sshd-command

The –callhome-sshd-command parameter specifies the command string used to invoke the SSH server when a callhome session is initiated.

--callhome-sshd-command parameter

Syntax string

Default: /usr/sbin/sshd

Min Allowed: 0

Max Allowed: 1


Example: Netconfd-pro \ –callhome-sshd-command=/bin/sshd

3.22 --callhome-sshd-config

The –callhome-sshd-command parameter specifies the SSH server configuration file to use when invoking the SSH server when a callhome session is initiated. The default config file to use is a dynamic string using the pattern ch_sshd_config.<client>. It is located in the $HOME/.yumapro directory.

--callhome-sshd-config parameter

Syntax string

Default: NONE (dynamic default)

Min Allowed: 0

Max Allowed: 1


Example: Netconfd-pro \ –callhome-sshd-config=/etc/ssh/callhome_config



3.23 --callhome-subsys-command

The –callhome-subsys-command parameter specifies the netconf subsystem to use in the default ch_sshd_config files to specify the NETCONF subsystem for the incoming NETCONF session expected on the callhome session.

--callhome-subsys-command parameter

Syntax string

Default: /usr/sbin/netconf-subsystem-pro

Min Allowed: 0

Max Allowed: 1


Example: Netconfd-pro \ –callhome-subsys-command=/bin/netconf-subsystem-pro



3.24 --callhome-tls-server

The –callhome-tls-server parameter specifies a callhome/TLS server that this server should attempt to initiate a callhome connection at boot-time. This is a leaf-list parameter and multiple entries are supported.



[email protected] [email protected]:12040

The server-id parameter is used for logging purposes.

This parameter is ignored if the --with-callhome parameter is set to 'false'.

--callhome-tls-server parameter

Syntax string

Default: none

Min Allowed: 0



Example: netconfd-pro \ –[email protected]



3.25 --cert-default-user

The –cert-default-user parameter specifies a user-name that should be used if no certificate mapping is found for a NETCONF over TLS session. This is the username to use if no username mapping is found for a NETCONF over TLS session. This parameter is non-standard and should only be used for debugging. This parameter is not available unless image is built with DEBUG=1 parameter.

This parameter is ignored if the –with-netconf-tls parameter is set to 'false'.

--cert-default-user parameter

Syntax string

Default: none

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro –cert-default-user=admin



3.26 --cert-usermap

The –cert-usermap parameter specifies a user-name to certificate mapping.

Each entry specifies a certificate to user name mapping for NETCONF over TLS sessions. A mapping is a structured string using the form <user>@<fingerprint>.

The 'user' field is the case-sensitive user name for the mapping.

The 'fingerprint' field is a hex-string representation of the SHA-1 fingerprint for the X.509 certificate. It does not have to be complete. Usually 6 bytes should be sufficient to ensure uniqueness. The hex digits are not case-sensitive. At least 6 hex digits must be provided. A maximum of 20 hex digits can be provided.

Example: admin@60:C8:5C:08:82:55

A printable fingerprint can be generated with the openssl command:

\

> openssl x509 -noout -fingerprint -sha1 -inform pem \ -in [certificate-file.crt]'

This parameter is ignored if the --with-netconf-tls parameter is set to 'false'.

--cert-usermap parameter

Syntax string

Default: none

Min Allowed: 0



Example: netconfd-pro \ –cert-usermap=admin@60:C8:5C:08:82:55



3.27 --confdir

The --confdir parameter specifies the CLI parameter configuration directory to use for extra configuration files. The server will check this directory for files that end with the suffix '.conf' and process them similar to the main configuration file. Other files will be ignored. Sub-directories will not be checked.

This parameter is ignored if the –no-nvstore parameter is used.

Files will be processed in alphabetical order. The server will keep the first value set if a CLI leaf parameter is set multiple times.

The CLI parameters are set in the following order:

1) netconfd-pro command line 2) --config file or /etc/yumapro/netconfd-pro.conf 3) --confdir files or /etc/yumapro/netconfd-pro.d/

If the --no-config parameter is present in step (1) then steps (2) and (3) will be skipped, and this parameter will be ignored. If this parameter is encountered in step (3) it will be ignored.

Extra configuration files in step (3) have the exact same syntax as the configuration file used in step (2).

Example extra config file testmods.conf:

netconfd-pro { module acme-test1 module acme-test2 log-level debug2 message-indent 1 idle-timeout 0 }

Default "/etc/yumapro/netconfd-pro.d";

Refer to the 'Configuration Files' section for details on the format of configuration files.

--config parameter

Syntax string: complete directory specification of the directory to look for more configuration files

Default: /etc/yumapro/netconfd-pro.d

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro \ --confdir=/mnt/conf/device12



3.28 --config

The --config parameter specifies the name of a YumaPro configuration file that contains more parameters to process, in addition to the CLI parameters. The -no-config parameter can be used instead of this parameter to force the server to skip loading the default config file if it is present.

This parameter is ignored if the –no-nvstore parameter is used.

Refer to the 'Configuration Files' section for details on the format of this file.

--config parameter

Syntax string: complete file specification of the text fileto parse for more parameters.

Default: /etc/yumapro/<program-name>.conf

Min Allowed: 0

Max Allowed: 1

Supported by: netconfd-proyangcli-proyangdiff-proyangdump-pro

Example: netconfd-pro \ --config=~/testconf.conf

3.29 --convert-subtree-filter

The –convert-subtree-filter parameter specifies whether subtree filters will be converted to XPath filters for internal processing. If set to 'true' then subtree filters for retrieval operations might be converted to XPath expressions for processing.

The subtree filtering algorithm has a minor flaw which can cause subtree containment nodes to be printed in the output eventhough a nested selection filter does not match. A containment node should be completely pruned from the result no selection filters within it produce a match. This only affects data that needs to be retrieved by the server with a GET2 callback.

This issue has been fixed by converting a subtree filter to XPath and processing as if it were an XPath filter. If this parameter is set to 'true' then the conversion will be attempted. The conversion will be skipped if any of the following conditions are true:

• output format is not XML

• input format is not XML

• subtree filter contains any attribute match expressions

This bugfix is not enabled by default because it might change filter output which was previously incorrect, but a client might be relying on the incorrect output anyway.



--convert-subtree-filter parameter

Syntax boolean

Default: false

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro \ --convert-subtree-filter=true

3.30 --create-empty-npcontainers

The –create-empty-npcontainers parameter specifies whether empty NP container will be created by the server.

An empty non-presence container has no meaning in NETCONF/YANG so it may be created by the server. In particular, thepresence of the container node with no child nodes is semantically equivalent to the absence of the container node. This is the default style.

If this parameter is set to false, then the server will not create empty NP containers.

--create-empty-npcontainers parameter

Syntax boolean

Default: true

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro \ --create-empty-npcontainers=false

3.31 --datapath

The --datapath parameter specifies the directory search path to use while searching for data files. It consists of a colon (':') separated list of path specifications, commonly found in Unix, such as the $PATH environment variable.

This parameter overrides the $YUMAPRO_DATAPATH environment variable, if it is present.

--datapath parameter

Syntax string: list of directory specifications

Default: $YUMAPRO_DATAPATH environment variable

Min Allowed: 0



Max Allowed: 1


Example: netconfd-pro \ --datapath=”~/work2:~/data”



3.32 --db-lock-retry-interval

The --db-lock-retry-interval parameter specifies the number of milliseconds to wait before attempting to get a DB-Config-Lock from the DB-API subsystem. The server will wait this amount of time after a db-lock request fails.

--db-lock-retry-interval parameter

Syntax number: 10 .. 60000 milliseconds

Default: 500 milliseconds

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro \ --db-lock-retry-interval=1000

3.33 --db-lock-timeout

The --db-lock-timeout parameter specifies the the total number of seconds to wait before giving up on a DB-Config-Lock from the DB-API subsystem. The value zero indicates that no retries will be attempted if the lock is busy.

--db-lock-timeout parameter

Syntax number: 0 .. 3600 seconds

Default: 30 seconds

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro --db-lock-timeout=120



3.34 --default-style

The --default-style parameter specifies the way leafs with default values are returned from the server for data retrieval operations. This setting will be used as the default behavior when processing the operations that support the <with-defaults> extension, and no value is provided.

The values and their meanings are defined in ietf-with-defaults.yang. Here is a summary:

• report-all: Report all nodes as the default behavior. The will be the behavior used if this parameter is not specified.

• trim: Report only nodes that do not have the server-assigned value, as the default behavior. This includes all leafs with a YANG default and any other node created by the server.

• explicit: Report only nodes that have been set by client action, as the default behavior. Any node created via the <startup> configuration at boot-time is considered to be a client-created node. It does not matter what the actual values are, with respect to YANG defaults or server-supplied defaults. Any nodes created by the server are skipped.

--default-style parameter

Syntax enumeration: report-all trim explicit

Default: report-all

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro \ --default-style=trim



3.35 --delete-empty-npcontainers

The --delete-empty-npcontainers parameter is a boolean that indicates whether the server should keep or delete empty non-presence containers in the database.

If 'true', empty NP containers will be deleted. If 'false', they will not be deleted.

This parameter is obsolete!!! The server ignores this parameter!!! Do not use it!!!

The value 'false' is always used!!!

--delete-empty-npcontainers parameter

Syntax boolean

Default: FALSE

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro \ --delete-empty-npcontainers=true



3.36 --deviation

The --deviation parameter is a leaf-list of modules that should be loaded automatically when the program starts, as a deviation module. In this mode, only the deviation statements are parsed and then made available later when the module that contains the objects being deviated is parsed.

The deviations must be known to the parser before the target module is parsed.

This parameter is used to identify any modules that have deviation statements for the set of modules being parsed (e.g., --module and --subtree parameters).

A module can be listed with both the --module and --deviation parameters, but that is not needed unless the module contains external deviations. If the module only contains deviations for objects in the same module, then the --deviation parameter does not need to be used.

The program will attempt to load each module in deviation parsing mode, in the order the parameters are entered.

For the netconfd-pro program, If any modules have fatal errors then the program will terminate.

For the yangdump-pro and yangcli-pro programs, each module will be processed as requested.

--deviation parameter

Syntax module name or filespec

Default: none

Min Allowed: 0


Supported by: netconfd-proyangcli-proyangdump-pro

Example: netconfd-pro \ --deviation=test1_deviations



3.37 --errmsg

The --errmsg parameter specifies a language specific error message, for a specific error code

The 'num' component must match the <error-number> found in status_enum.h. New error enums are always added at the end of the list, so the numbers will not change.

The 'lang' component should use the ISO-639-1 code Max length is 7 characters.

The string has the format: '<num>:<lang>:error string' where: <num> = error number to use for error message <lang> = language code (en for English) error string = error string text

Example:

Replace error 117 (ERR_WB_WRITE_FAILED) 'db write failed'

errmsg='117:en:The database could not be written'

There are several pre-defined error message configuration files, found in directory:

/usr/share/yumapro/util/errmsg-lang

To use an error message configuration file, copy the file to the netconfd.d configuration directory:

The –errmsg-lang parameter must be set to the correct language code for the server to use this configuration file.

Example: Copy the Russian (ru) error codes to the configuration directory:

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

--errmsg parameter

Syntax string

Default: none

Min Allowed: 0



Max Allowed: unbounded


Example: netconfd-pro \ --errmsg=”117:en:Database write failed”

3.38 --errmsg-lang

The –errmsg-lang parameter specifies the language to use for <error-message> content.

The –errmsg parameter must be used to configure the language-specific error message strings.

This value should use the ISO-639-1 code for the language.

--errmsg-lang parameter

Syntax string

Default: none

Min Allowed: 0



Example: netconfd-pro --errmsg-lang=ru

3.39 --eventlog-size

The --eventlog-size parameter controls the maximum number of events that will be stored in the notification replay buffer by the netconfd-pro server.

If set to 0, then notification replay will be disabled, meaning that all requests for replay subscriptions will cause the <replayComplete> event to be sent right away, since there are no stored notifications.

The server will delete the oldest entry, when this limit is reached and a new event is added to the replay buffer.

No memory is actually set aside for the notification replay buffer, so memory limits may be reached before the maximum number of events is actually stored, at any given time.

--eventlog-size parameter

Syntax uint32

Default: 1000

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro --eventlog-size=20000



3.40 --event-stream

The --event-stream parameter specifies the name of a NETCONF event stream that should be created by the server..

Each event stream has its own subscriptions and notification replay buffer. Each event stream has the same replay buffer size, using the shared eventlog-size parameter. Each generated notification is sent to one event stream.

The YANG module instrumentation will select an event stream to use or the default event stream will be used. Copies of the same notification can be sent to multiple event streams. If the event-stream specified by the instrumentation is not available, then a warning will be generated in the log and the default event stream will be used instead.

The default event stream is named 'NETCONF'. It cannot be replaced or removed. No other event stream can have this name. The standard NETCONF notification events are always sent to this event stream, unless there is an event-stream-map assigning the module to a different event stream.

--event-stream parameter

Syntax NcxName (string)

Default: none

Min Allowed: 0



Example: netconfd-pro --event-stream=hardware \ --event-stream=routing

3.41 --event-stream-map

The --event-stream-map parameter specifies a module name to event-stream mapping for notification handling. A mappingis a structured string using the form <module-name>@<stream-name>.

The 'module-name' field is the case-sensitive module name for the mapping.

The 'stream-name' field is the case-sensitive stream name for the mapping. It must match an 'event-stream' parameter or the default 'NETCONF'. Note there is no need to define a mapping for the 'NETCONF' stream since it will be picked if no otherstream is selected.

The built-in notifications such as 'replayComplete' and 'notificationComplete' are subscription-specific and always sent only to the subscription, not the event stream. Therefore these notifications are not affected by this parameter.

--event-stream-map parameter

Syntax string

Default: none

Min Allowed: 0





Example: netconfd-pro \ --event-stream-map=ietf-hardware@hardware

3.42 --factory-startup

The --factory-startup CLI parameter forces the server to over-write the startup configuration file and replace it with the factory installed default configuration. Use this parameter with caution!!! Use the backup operation to save the current configuration first.

◦ factory-startup

▪ type: empty

▪ Force the system to use the factory configuration and delete the startup config file if it exists. Force the NV-storage startup to contain the factory default configuration.

▪

--factory-startup parameter

Syntax --factory-startup

Default: none

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro --factory-startup



3.43 --feature-disable

The --feature-disable parameter directs all programs to disable a specific feature.

This parameter is a formatted string containing a module name, followed by a colon ':', followed by a feature name, e.g.,

test:feature1

It is an error if a --feature-enable and --feature-disable parameter specify the same feature.

Parameters for unknown features will be ignored.

--feature-disable parameter

Syntax formatted string (module:feature

Default: none

Min Allowed: 0


Supported by: yangcli-proyangdiff-proyangdump-pronetconfd-pro

Example: netconfd-pro\ --feature-disable=test:feature1

3.44 --feature-enable

The --feature-enable parameter directs all programs to enable a specific feature.

This parameter is a formatted string containing a module name, followed by a colon ':', followed by a feature name, e.g.,

test:feature1

It is an error if a --feature-disable and --feature-enable parameter specify the same feature.

Parameters for unknown features will be ignored.

--feature-enable parameter

Syntax formatted string (module:feature

Default: none



Min Allowed: 0



Example: netconfd-pro --feature-enable=test:feature1

3.45 --feature-enable-default

The --feature-enable-default parameter controls how netconfd-pro will enabled YANG features in modules by default.

If 'true', then by default, features will be enabled.

If 'false', then by default, features will be disabled.

If a --feature-enable or --feature-disable parameter is present for a specific feature, then this parameter will be ignored forthat feature.

--feature-enable-default parameter

Syntax boolean (true or false)

Default: TRUE

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro \ --feature-enable-default=false



3.46 --fileloc-fhs

The –fileloc-fhs parameter is used to control where the server keeps its data files.

If -fileloc-fhs =true:

f true, then the server should use Filesystem Hierarchy Standard (FHS) directory locations to create and store server data. May need to run as root..

The FHS server log file will be created by default unless the 'log' parameter is used, then that location will be used instead. If the 'no-log' parameter is present then no log will be created.

The FHS audit log file will be created by default unless the 'audit-log' parameter is used, then that location will be used instead. If the 'no-audit-log' parameter is present then no audit log will be created.

File Type Example

server log /var/log/netconfd-pro/server.log

audit log /var/log/netconfd-pro/audit.log

config file /var/lib/netconfd-pro/startup-cfg.xml

TXID file /var/lib/netconfd-pro/startup-cfg-txid.txt

backups /var/lib/netconfd-pro/backups/backup1.xml

PID file /var/run/netconfd-pro/netconfd-pro.pid

AF socket /var/run/netconfd-pro/ncxserver.sock

If –fileloc-fhs =false:

If false then the server will use $HOME/.yumapro and other file locations to store server data.

File Type Example

server log STDOUT; no server log created by default

no output at all if --no-log used

audit log STDOUT; no audit log created by default

config file $HOME/.yumapro/startup-cfg.xml

TXID file $HOME/.yumapro/startup-cfg-txid.txt

backups $HOME/.yumapro/backups/backup1.xml

PID file $HOME/.yumapro/netconfd-pro.pid



AF socket /tmp/ncxserver.sock

--fileloc-fhs parameter


Default: FALSE

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro –fileloc-fhs=true

3.47 --ha-enabled

The –ha-enabled parameter is used to enable or disable the High Availability protocol (YP-HA). This allows redundant systems to stay up-to-date with all configuration changes, and other server state.

• If 'true', then YP-HA will be enabled

• If 'false', then YP-HA will be disabled.

If this parameter is enabled then the following parameters must be configured or the server will exit with an error:

• ha-server

• ha-server-key

• server-id

• socket-type=tcp

• socket-address

• socket-port

--ha-enabled parameter


Default: FALSE

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro –ha-enabled=true



3.48 --ha-initial-active

The –ha-initial-active parameter specifies the server name for the initial YP-HA active server. This is ignored unless --ha-enabled=true. There is no default.

This parameter is used to hardwire the initial High Availability roles instead of setting it in the yp-system init1 or init2 callback functions. If this parameter is the same as 'server-id' then this server will be the initial YP-HA active server.

This parameter is intended for debug mode only. The real operational mode should use signaling only to set the HA mode. Otherwise if the server reboots it will use the configured HA mode, which may not be correct if it has been changed during runtime.

--ha-initial-active parameter

Syntax string (NcxName)

Default: none

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro –ha-initial-active=ha-1



3.49 --ha-server

The –ha-server parameter specifies a server in the YP-HA server pool.

This parameter must be configured if the –ha-enabled parameter is set to true.



Examples:

[email protected]

[email protected]:12040

If no port number is used then the port '8088' is used.

The server-addr field must match the --socket-address parameter for the server.

The port-num field must match the --socket-port parameter for the server.

The server running with this configuration must be listed in the ha-server pool. The --server-id parameter must match the entry for this server.

There must be at least 2 entries present to configure an HA server pool.

--ha-server parameter

Syntax string

Default: none

Min Allowed: 0

Max Allowed: no limit


Example: netconfd-pro \ –[email protected] \ –[email protected]:8090


mailto:ha-server%[email protected]

mailto:ha-server%[email protected]


3.50 --ha-server-key

The –ha-server-key parameter specifies the string the standby server must present to the active server during registration. Used to prevent servers from going the wrong HA pool. If not set then the active server will reject the YP-HA connection. This parameter must be set if the ha-enabled parameter is set to 'true'. It is ignored unless --ha-enabled=true. There is no default.

--ha-server-key parameter

Syntax string

Default: none

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro \ –ha-server-key=ha-pool-1

3.51 --ha-sil-standby

The –ha-sil-standby parameter specifies whether the edit callbacks such as SIL, SIL-SA and HOOK instrumentation will be invoked if the server is operating in HA standby mode.

--ha-sil-standby parameter


Default: FALSE

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro –ha-sil-standby=true



3.52 --hello-timeout

The --hello-timeout parameter controls the maximum number of seconds that the netconfd-pro server will wait for a <hello> PDU, for each session.

If set to 0, then hello state timeouts will be disabled, meaning that no sessions will be deleted while waiting for a <hello> PDU.

It is strongly suggested that this parameter not be disabled, since a denial-of-service attack will be possible if sessions are allowed to remain in the 'hello wait' state forever. A finite number of SSH and NETCONF sessions are supported, so if an attacker simply opened lots of SSH connections to the netconf subsystem, the server would quickly run out of available sessions.

Sessions cannot be deleted manually via <kill-session> operation if no new sessions are being allocated by the server.

--hello-timeout parameter

Syntax uint32; 0 == disabled;range 10 .. 3600 seconds (1 hour max)

Default: 600 (10 minutes)

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro --hello-timeout=300

3.53 --help

The --help parameter causes program help text to be printed, and then the program will exit instead of running as normal.

This parameter can be combined with the --help-mode parameter to control the verbosity of the help text. Use --brief for less, and --full for more than the normal verbosity.

This parameter can be combined with the --version parameter in all programs. It can also be combined with the --show-errors parameter in yangdump-pro.

The program configuration parameters will be displayed in alphabetical order, not in schema order.

--help parameter

Syntax empty

Default: none

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro --help



3.54 --help-mode

The --help-mode parameter is used to control the amount of detail printed when help text is requested in some command. It is always used with another command, and makes no sense by itself. It is ignored unless used with the --help parameter.

--help-mode parameter

Syntax choice of 3 empty leafs --brief --normal --full

Default: normal

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro --help --brief

• default choice: normal

• choice help-mode

◦ brief

▪ type: empty

▪ This parameter specifies that brief documentation mode should be used.

◦ normal

▪ type: empty

▪ This parameter specifies that normal documentation mode should be used.

◦ full

▪ type: empty

▪ This parameter specifies that full documentation mode should be used.



3.55 --hide-module

The --hide-module parameter specifies the name of a module to hide from advertisements to client sessions. If the specifiedmodule name is loaded into the server, then this parameter will cause it to be omitted from the following data structures:

• YANG 1.0 <hello> message

• /netconf-state/schemas/schema list

• /modules-state/module list

This parameter will prevent the client from knowing about the hidden module. If an advertised module imports a hidden module then it is very likely a client will not be able to use the advertised module because of the missing imports.

This parameter can be dangerous! It does not prevent loading or enabling of the module. The SIL code is responsible for notreturning any data to a client using a hidden module.

Use of this parameter violates conformance to NETCONF, RESTCONF, and the YANG Library. Use with caution,

only for modules that are not accessible by clients.

--hide-module parameter

Syntax string: module name

Default: none

Min Allowed: 0



Example: netconfd-pro \ --hide-module=mysecretmod



3.56 --home

The --home parameter over-rides the $HOME environment variable, if it is set. File searches that use the user's home directory will use this path specification instead.

--home parameter

Syntax string: pathspec

Default: $HOME environment value

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro --home=/var/run/netconfd-pro



3.57 --idle-timeout

The --idle-timeout parameter controls the maximum number of seconds that the netconfd-pro server will wait for a <rpc> PDU, for each session.

If set to 0, then idle state timeouts will be disabled, meaning that no sessions will be deleted while waiting for a <rpc> PDU.

A session will never be considered idle while a notification subscription is active.

It is strongly suggested that this parameter not be disabled, since a denial-of-service attack will be possible if sessions are allowed to remain in the 'idle wait' state forever. A finite number of SSH and NETCONF sessions are supported, so if an attacker simply opened lots of SSH connections to the netconf subsystem, the server would quickly run out of available sessions.

This parameter will affect a <confirmed-commit> operation!

Make sure this timeout interval is larger than the value of the <confirm-timeout> parameter used in the confirmed commit procedure. Otherwise, it is possible that the session will be terminated before the confirm-timeout interval has expired, effectively replacing that timer with this one.

--idle-timeout parameter

Syntax uint32; 0 == disabled;range 30 .. 360000 seconds (100 hours max)

Default: 3600 (1 hour)

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro --idle-timeout=30000



3.58 --import-version-bestmatch

The --import-version-bestmatch parameter specifies if the bestmatch search feature should be used for import resolution when no revision-date field is specified in the import-stmt.

If 'true' then the server will scan the module search path during startup and determine the most recent revisions of each module. If a module is loaded or imported and no revision date is specified then the bestmatch revision will be used.

This feature requires some additional memory and bootup processing time. It should be avoided if possible. The module search path on the server should only contain the modules and revisions that are needed by the server.

If set to 'false', then the bestmatch feature will not be enabled. It is possible for the server to find and load the wrong versionof a module during imports processing.

For example, while loading module A, it imports module B. Then module B is loaded but a revision is specified (e.g., --module=B@2019-06-20). This can cause errors during callback registration such as 'definition not found' or 'segment not found', depending on how the module has changed.

--import-version-bestmatch parameter

Syntax boolean

Default: false

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro --import-version-bestmatch=true



3.59 --indent

The --indent parameter specifies the number of spaces that will be used to add to the indentation level, each time a child node is printed during program operation.

--indent parameter

Syntax uint32 (0 .. 9)

Default: 2

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro --indent=4

3.60 --insecure-ok

The –insecure-ok parameter specifies if insecure NETCONF over TLS should be allowed. If true then X.509 certificates will be accepted even if they cannot be verified. Used for debugging only!

This parameter is only available if the image was built with the DEBUG=1 parameter.

--insecure-ok parameter

Syntax boolean

Default: FALSE

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro –insecure-ok=true



3.61 --library-mode

The –library-mode parameter is used to run the server in YANG library mode.

leaf library-mode { description "If true, then the server will operate in YANG module library mode. It will find all the YANG modules and make them available for <get-schema> operations.

The following NETCONF operations are available when the server is operating in library mode:

ietf-netconf:get ietf-netconf:get-config ietf-netconf-monitoring:get-schema yuma-system:restart yuma-system:shutdown "; type boolean; default false; }

If library-mode is true, then the server will ignore all the –module, --deviation, and –bundle parameters. Instead of using these parameters to load modules, only the base modules loaded by default into the server will be used.

The server will scan the module search path and add all revisions of all modules it finds to the YANG library “module” list. Only one copy of each revision will be loaded in case the same file existing in multiple places in the module search path.

The YANG library will provide a “schema” leaf that can be used by RESTCONF to retrieve the YANG module.

The NETCONF <get-schema> operation will also support retrieval of the YANG modules found in the search path.

The server cannot be used for editing or normal operations if YANG library mode is activated.

--library-mode parameter

Syntax boolean

Default: false

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro –library-mode=true



3.62 --loadpath

The --loadpath parameter specifies the YANG module load path to use while loading YANG modules at boot-time. It consists of a colon (':') separated list of path specifications, commonly found in Unix, such as the $PATH environment variable.

This parameter overrides the $YUMAPRO_LOADPATH environment variable, if it is present.

--loadpath parameter


Default: $YUMAPRO_LOADPATH environment variable

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro \ --loadpath=”~/testmodules:~/modules:~/trunk/netconf/modules”

3.63 --log

The --log parameter specifies a file name to be used for logging program messages, instead of STDOUT. It can be used with the optional parameters below to control how the log file is written. (See also -–log-syslog which directs message output to a syslog daemon.)

If this string begins with a '~' character, then a username is expected to follow or a directory separator character. If it begins

with a '$' character, then an environment variable name is expected to follow.

If this parameter is used on the command line then the --log-append parameter must also be present on the command line if append mode is desired.

--log parameter

Syntax string: log file specification

Default: none

Min Allowed: 0

Max Allowed: 1




Example: netconfd-pro --log=~/server.log&



3.64 --log-append

The --log-append parameter specifies that the existing log file (if any) should be appended , instead of deleted. It is ignored unless the --log parameter is present.

--log-append parameter

Syntax empty

Default: none

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro --log-append \ --log=~/server.log&

3.65 --log-backtrace

The --log-backtrace parameter specifies that stack frame trace information be appended to selected log messages. By default, this information will be included in all enabled output streams (STDOUT, STDERR, log file, and/or syslog). Such output may be further modified by inclusion of any of the log-backtrace-xxx commands below.

--log-backtrace parameter

Syntax Max frame count: 0..200

Default: 0 means use internal default (20)

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro --log-backtrace=0



3.66 --log-backtrace-detail

The --log-backtrace-detail adds compiler/OS dependent information to the output of –-log-backtrace.

--log-backtrace-detail parameter

Syntax empty

Default: none

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro --log-backtrace=0 \ --log-backtrace-detail

3.67 --log-backtrace-level

The –log-backtrace-level parameter specifies that stack frame trace information be appended only to selected log message levels (see --log-level).

--log-backtrace-level parameter

Syntax Enumeration: error warn info debug debug2 debug3 debug4One or more enumeration(s) may be specified by enclosing the string in double quotes ('”') andseparating each member with a space.

Default: none

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro –log-backtrace=0 \ --log-backtrace-level=”error debug”



3.68 --log-backtrace-stream

The --log-backtrace-stream parameter specifies that stack frame trace information will be limited to output streams specified by the argument list. Possible arguments include logfile, stdout, stderr, syslog, and vendor.

--log-backtrace-stream parameter

Syntax Enumeration:logfilestdoutstderrsyslogvendorOne or more enumeration(s) may be specified by enclosing the string in double quotes ('”') andseparating each member with a space.

Default: none

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro --log-syslog \ --log=server.log \ --log-backtrace=0 \ --log-backtrace-stream=”logfile”

3.69 --log-console

The –log-console parameter directs that log output will be be sent to STDOUT, after being sent to the log file and/or local syslog daemon. (This assumes that –-log and/or --log-syslog are present).

--log-console parameter

Syntax empty

Default: none

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro –log=file --log-syslog \--log-console &



3.70 --log-event-drops

The –log-event-drops parameter indicates if a log entry would be generated when a notification is dropped because the specific notification events are disabled with an event-filter configuration entry.

Assumes that the --with-notifications CLI parameter is set to 'true'

--log-event-drops parameter

Syntax boolean

Default: FALSE

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro –log-event-drops=true

3.71 --log-header

The --log-header parameter specifies that additional information (date/time/level) will be included in the log stream output.Possible arguments to this command include custom (add date/time/level info) and localtime (express date/time in local terms).

--log-header parameter

Syntax Enumeration:customlocaltimeOne or more enumeration(s) may be specified by enclosing the string in double quotes ('”') andseparating each member with a space.

Default: none

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro --log-append \ --log=~/server.log \ --log-header=”custom localtime”&



3.72 --log-level

The --log-level parameter controls the verbosity level of messages printed to the log file or STDOUT, if no log file is specified.

The log levels are incremental, meaning that each higher level includes everything from the previous level, plus additional messages.









--log-level parameter


Default: --info

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro --log-level=debug \ --log=~/server.log&



3.73 --log-mirroring

The –log-mirroring parameter is a synonym for —log-console.

3.74 --log-pthread-level

The --log-pthread-level parameter controls the verbosity level of thread-specific messages printed to the log file or STDOUT, if no log file is specified. Note that this parameter is only effective in thread-based images.










--log-pthread-level parameter


Default: --info (--debug for DEBUG builds)

Min Allowed: 0

Max Allowed: 1


Example: Netconfd-pro \> --log-pthread-level=debug \ --log=~/server.log&



3.75 --log-stderr

The --log-stderr parameter directs that error level log output be directed to STDERR rather than STDOUT. (Note however that if –-log is present, all error level messages will be directed to the specified log file … –-log-stderr has no effect in this case.)

--log-stderr parameter

Syntax empty

Default: none

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro --log-stderr > logFile&! All log messages redirected to logFile except ...! Error level messages displayed on console

3.76 --log-syslog

The --log-syslog parameter directs log output to be sent to the local syslog daemon, rather than to STDOUT. See the –-log-console parameter for information on how log output may also be duplicated via STDOUT.

--log-syslog parameter

Syntax empty

Default: none

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro --log-syslog



3.77 --log-syslog-level

The --log-syslog-level parameter acts as a filter for the message level sent to the syslog or vendor output stream. The filter level is set by default to “info” if not specified.










--log-syslog-level parameter


Default: --info (--debug for DEBUG builds)

Min Allowed: 0

Max Allowed: 1


Example: Netconfd-pro –log-logfile \> --log-level=debug \> --log-syslog \> --log-syslog-level=info &



3.78 --log-vendor

The –-log-vendor parameter directs log output to be sent to a customer-written and registered callback function, rather than to STDOUT. This functionality is defined by an API specified in the YumaPro API Reference Manual. In the absence of a registered callback, this parameter will direct logging messages to syslog. See the –-log-console parameter for information on how log output may also be duplicated via STDOUT.

--log-vendor parameter

Syntax empty

Default: none

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro --log-vendor

3.79 --log-vendor-level

The –-log-vendor-level parameter sets the vendor debug logging level filter for output to the vendor-specific log output file stream for the program.

--log-vendor-level parameter


Default: --info

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro --log-vendor-level=debug



3.80 --match-names

The --match-names parameter specifies how names are matched when performing UrlPath searches.

The following values are supported::

• exact

The name must exactly match the node name for all characters in both name strings.

• exact-nocase

The name must match the node name for all characters in both name strings.

Strings are not case-sensitive.

• one

The name must exactly match the first N characters of just one node name, which must be the only partial name match found.

• one-nocase

The name must exactly match the first N characters of just one node name, which

must be the only partial name match found. Strings are not case-sensitive.

• first

The name must exactly match the first N characters of any node name. The first one

found will be used.

• first-nocase

The name must exactly match the first N characters of any node name. The first one

found will be used. Strings are not case-sensitive.

--match-names parameter

Syntax enum: exact exact-nocase one one-nocase first first-nocase

Default: one-nocase

Min Allowed: 0

Max Allowed: 1

Supported by: netconfd-pro yangcli-pro

Example: netconfd-pro --match-names=first



3.81 --max-burst

The --max-burst parameter specifies the maximum number of notifications to send in a burst, to one session. Even though TCP will control the transmission rate, this parameter can limit the memory usage due to buffering of notifications waiting to be sent.

The value zero means no limit will be used at all.

--max-burst parameter

Syntax uint32

Default: 10

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro --max-burst=100

3.82 --max-cli-sessions

The –max-cli-sessions parameter specifies the maximum number of concurrent CLI sessions to allow at any time.

The value zero means no artificial limit will be used at all. The –max-sessions parameter has precedence, so setting this parameter to a value larger than –max-sessions will have no effect.

--max-cli-sessions parameter


Default: 0

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro –max-cli-sessions=2



3.83 --max-getbulk

The --max-getbulk parameter specifies the maximum number of getbulk entries to request from a GET2 callback. This value will be used in the get2cb 'max_entries' field. The value 0 is used to indicate there is no max and the GET2 callback can return as many getbulk entries as desired. This is the default for leaf-list GET2 callbacks.

--max-getbulk parameter

Syntax uint32

Default: 10

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro --max-getbulk=100

3.84 --max-sessions

The --max-sessions parameter specifies the maximum number of concurrent sessions to allow at any time.

The value zero means no artificial limit will be used at all.

--max-sessions parameter


Default: 8

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro --max-sessions=10

3.85 --max-strlen

The --max-strlen parameter specifies the maximum number of bytes in length that will be accepted for a quoted string, by the internal token parser. This affects YANG and JSON input processing. Set this value to allow large binary leafs to be parsed by the server. This value includes 1 byte for the string termination character. The minimum size is 64 KBytes. The maximum is 2 billion bytes. The default is 256 KBytes.

--max-strlen parameter



Syntax int32 (65536 .. INT_MAX)

Default: 262144

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro --max-strlen=1000000

3.86 --message-indent

The --message-indent parameter specifies the number of spaces to indent for each level of output in a protocol message, e.g. NETCONF request. The value zero means no indent, just line feeds. The value -1 means no indent and no line feeds either. If --log-level=debug4 then this parameter will be set to at least the value ‘1’ (if the set value is less than 1).

--message-indent parameter

Syntax int32 (-1 .. 9)

Default: -1

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro --message-indent=2

3.87 --modpath

The --modpath parameter specifies the YANG module search path to use while searching for YANG files. It consists of a colon (':') separated list of path specifications, commonly found in Unix, such as the $PATH environment variable.

This parameter overrides the $YUMAPRO_MODPATH environment variable, if it is present.

--modpath parameter


Default: $YUMAPRO_MODPATH environment variable

Min Allowed: 0

Max Allowed: 1




Example: netconfd-pro \ --modpath=”~/testmodules:~/modules:~/trunk/netconf/modules”

3.88 --module

The --module parameter is a leaf-list of modules that should be loaded automatically when the program starts.

The program will attempt to load each module in the order the parameters were entered.

For the netconfd-pro program, If any modules have fatal errors then the program will terminate.

For the yangdump-pro program, each module will be processed as requested.

--module parameter

Syntax module name or filespec

Default: none

Min Allowed: 0



Example: netconfd-pro \ --module=test1 \ --module=test2

3.89 --module-tagmap

The –module-tagmap parameter is a leaf-list of module name to module-tag mappings.

Specifies a module tag mapping for use in module tags registry.

The format is <modname>@<tag-string>.

Strings should follow the format in the ietf-module-tags YANG module.

The <get> and <get-config> operations accept the –module-tag parameter which is used as a filter to include only data nodes from modules that match the specified module-tag.

Examples:

• ietf-system@ietf:system-management


mailto:ietf-system@ietf


• openconfig-system@vendor:openconfig:system-management

• example-system@vendor:example.com:system-management

--module-tagmap parameter

Syntax structured string

Default: none

Min Allowed: 0



Example: netconfd-pro \ --module-tagmap=test1@test \ --module-tagmap=test2@test


mailto:example-system@vendor

mailto:openconfig-system@vendor


3.90 --netconf-capability

The –netconf-capability parameter is a leaf-list of URI values that should be added to the server NETCONF <hello> message as a NETCONF <capability> URI and monitoring data in the /netconf-state/capabilities container.

--netconf-capability parameter

Syntax inet:uri

Default: none

Min Allowed: 0



Example: netconfd-pro \ --netconf-capability=urn:acme:test

3.91 --netconf-tls-address

The –netconf-tls-address parameter specifies the IP address to listen on for NETCONF over TLS messages.

This parameter is ignored if the –with-netconf-tls parameter is set to ‘false’.

--netconf-tls-address parameter

Syntax inet:ip-address

Default: 0.0.0.0

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro \ --netconf-tls-address=192.168.0.15



3.92 --netconf-tls-certificate

The –netconf-tls-certificate parameter contains the file path specification for the file containing the server SSL certificate, used for the NETCONF over TLS protocol.


--netconf-tls-certificate parameter

Syntax string

Default: $HOME/.ssl/netconfd-pro.crt

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro \ --netconf-tls-certificate=/etc/ssl/certs/mycert.crt

3.93 --netconf-tls-key

The –netconf-tls-key parameter contains the file path specification for the file containing the server SSL private key, used for the NETCONF over TLS protocol.


--netconf-tls-key parameter

Syntax string

Default: $HOME/.ssl/netconfd-pro.key

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro \ --netconf-tls-key=/etc/ssl/private/mycert.key



3.94 --netconf-tls-port

The –netconf-tls-port parameter specifies the TCP port number to listen on for NETCONF over TLS messages.


--netconf-tls-port parameter

Syntax inet:port-number

Default: 6513

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro --netconf-tls-port=10200

3.95 --netconf-tls-trust-store

The –netconf-tls-trust-store parameter contains the file path specification for the file containing the server SSL trust-store, or the path specification for the directory to use for finding trusted certificates. If the default value is used and the file is not found, then the default directory location '/etc/ssl/certs' will be used.


--netconf-tls-trust-store parameter

Syntax string

Default: $HOME/.ssl/trust-store.pem

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro \ –netconf-tls-trust-store=/opt/certs



3.96 --no-config

The --no-config parameter specifies that the default configuration file (/etc/yumapro/netconfd_pro.conf) should not be loaded, even if it is present.

--no-config parameter

Syntax empty

Default: none

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro --no-config

3.97 --no-log

The --no-log parameter specifies that no main log file will be created. This is usually only relevant if --fileloc-fhs is 'true'.

In this case the default log file will not be created. The --log-level parameter will be set to 'none'.

This parameter will be ignored if the --log parameter is set. This parameter has no affect on the audit-log or syslog logging.

--no-log parameter

Syntax empty

Default: none

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro --no-log --fileloc-fhs=true



3.98 --no-nvstore

If the –no-nvstore parameter is present, the server should not load or save using the normal APIs during transaction management.

• The 'start' choice will be ignored and the server will not attempt to load a startup-cfg.xml file.

• Transactions will not be saved to NV-storage at all.

• Any external NV-storage callbacks will be ignored.

The following operations are not affected by this parameter:

• <backup> operation

• <restore> operation

• confirmed-commit procedure will save backup-cfg.xml to use if the commit needs to be rolled back

Use this mode if NV-load and NV-storage are handled internally and not via the startup-cfg.xml file.

The default is not present.

--no-nvstore parameter

Syntax empty

Default: none

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro --no-nvstore

3.99 --no-startup

The --no-startup parameter specifies that the default startup configuration file (any startup-cfg.xml in the data search path) should not be loaded, even if it is present.

--no-startup parameter

Syntax empty

Default: none

Min Allowed: 0

Max Allowed: 1




Example: netconfd-pro --no-startup

3.100 --no-watcher

The –no-watcher parameter controls the ypwatcher program. With the parameter the server starts without launching the ypwatcher program.

--no-watcher parameter

Syntax empty

Default: none

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro --no-watcher

3.101 --port

The --port parameter specifies the TCP port number(S) that should be used for NETCONF sessions.

This parameter specifies the TCP port numbers to accept NETCONF session from. If any instances of this parameter are found, then the default (port 830) will not be added automatically. Up to 4 port parameter values can be entered.

--port parameter

Syntax uint32

Default: 830

Min Allowed: 0

Max Allowed: 4


Example: netconfd-pro --port=22 \ --port=830



3.102 --protocols

The --protocols parameter specifies which NETCONF protocol versions should be enabled.The base:1.0 (RFC 4741/4742) and base:1.1 (RFC 6241/6242) capabilities are controlled with this parameter.

--protocols parameter

Syntax bits

Default: netconf1.0 netconf1.1

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro –protocols=netconf1.0

3.103 --restconf-capability

The –restconf-capability parameter is a leaf-list of URI values that should be added to the server as monitoring data in the /restconf-state/capabilities container.

--restconf-capability parameter

Syntax inet:uri

Default: none

Min Allowed: 0



Example: netconfd-pro \ --restconf-capability=urn:acme:foo1



3.104 --restconf-default-encoding

The –restconf-default-encoding parameter specifies the default response encoding to use if the incoming request does not have an indication of preferred content type (e.g., no Content-Type header, no Accept header).

The values “xml” and “json” are supported.

--restconf-default-encoding parameter

Syntax enum (xml, json)

Default: json

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro \ --restconf-default-encoding=xml

3.105 --restconf-server-url

The --restconf-server-url parameter specifies the starting string for the server URL to use in Location header lines returnedby RESTCONF.

--restconf-server-url parameter

Syntax inet:uri

Default: http://localhost

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro \ --restconf-server-url= \ https://device1.example.com



3.106 --restconf-strict-headers

The --restconf-strict-headers parameter specifies how the RESTCONF server will validate Accept header entries.

If set to 'true' the server will only accept requests with normative Accept and Content-Type headers entries specified in the draft-ietf-netconf-restconf-18. The Accept header must not be empty; otherwise 'not acceptable' error will be returned.

Normative Accept header:

application/yang-data+xml,application/yang-data+json;q=0.9

Normative Content-Type header:


application/yang-patch+json

If set to 'false', the server will try to accept not normative header entries.

Acceptable not normative Accept header:

application/xml,application/json;q=0.9

Acceptable not normative Content-Type headers:

application/xml

application/json

text/xml

--restconf-strict-headers parameter

Syntax boolean

Default: FALSE

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro \ --restconf-strict-headers=true



3.107 --running-error

The --running-error parameter is an enumeration, specifying how the netconfd-pro server will treat errors encountered while validating the running database, when loaded from the non-volatile startup configuration at boot-time.

• leaf running-error

◦ type: enumeration (stop, continue, or fallback)

◦ Specifies if running configuration errors will be treated as fatal or recoverable errors.

◦ The value 'fallback' will cause the server to restart using the factory-default YANG configuration for the <running> datastore.

--running-error parameter

Syntax enum: stop continue fallback

Default: stop

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro \ --running-error=continue



3.108 --runpath

The --runpath parameter specifies the server instrumentation library (SIL) search path to use while searching for library files. It consists of a colon (':') separated list of path specifications, commonly found in Unix, such as the $PATH environment variable.

This parameter overrides the $YUMAPRO_RUNPATH environment variable, if it is present.If no path is specified or a SIL is not found, the directories /usr/lib/yumapro and /usr/lib64/yumapro (for 64-bit platforms) are checked.

--runpath parameter


Default: $YUMAPRO_RUNPATH environment variable

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro \ --runpath=”~/testsil:/yumapro/device”

3.109 --save-owners

The –save-owners parameter specifies whether owner names will be saved as meta-data with the configuration data.

--save-owners parameter

Syntax boolean

Default: FALSE

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro –save-owners=true



3.110 --session-sync-mutex

The --session-synch-mutex parameter, if present, will force synchronous request processing (pthread version only).

--session-sync-mutex parameter

Syntax empty

Default: not preset

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro --session-sync-mutex

3.111 --sil-delete-children-first

The –sil-delete-children-first parameter specifies how the server should handle data node deletions.

If 'true', the server default behavior will be to treat all data deletion operations as if the ncx:sil-delete-children-first extension is present. A child node will be checked for a SIL callback before it is deleted.

If 'false' the server default behavior will be to invoke SIL callbacks for deletion of child nodes only if the ncx:sil-delete-children-first extension is present. See also the ywx:no-sil-delete-children-first extension to override this parameter when itis set to ‘true’.

--sil-delete-children-first parameter

Syntax boolean

Default: false

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro \ –sil-delete-children-first=true



3.112 --sil-invoke-for-defaults

The –sil-invoke-for-defaults parameter specifies how the server should handle SIL callbacks for default data nodes.

If 'true' then when a SIL or SIL-SA callback will be invoked for default data nodes during the load and load_config operations.

If 'false' then a SIL or SIL-SA callback will not be invoked for default data nodes.

--sil-invoke-for-defaults parameter

Syntax boolean

Default: true

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro \ –sil-invoke-for-defaults=false

3.113 --sil-missing-error

The –sil-missing-error parameter indicates if a missing SIL library file will be treated as an error or not.

If 'true' then when a module is loaded, but the SIL library code for the module is not found, an error will be returned instead of a warning printed.

If 'false' then when a module is loaded, but the SIL library code for the module is not found, no error will be returned. Instead, only a warning will be printed.

--sil-missing-error parameter

Syntax boolean

Default: false

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro –sil-missing-error=true



3.114 --sil-prio-reverse-for-deletes

The –sil-prio-reverse-for-deletes parameter specifies whether edit transactions are validated by the regular SIL priority of should be reversed for DELETE edits. This parameter can be used to delete leafref nodes with referenced by node in reverseorder.

It is possible for the client to send several edits within a single <edit-config> request. Sometimes it is useful to make sure certain data structures are validated and processed before other data structures.

The "sil-priority" extension can be used to control the order of the edits and how they are processed.

In a case where you set "sil-priority" for multiple specific objects and want the order to be reversed during the DELETE operations there is a netconfd-pro configuration parameter "sil-prio-reverse-for-deletes".

If set to "true" the "sil-prio-reverse-for-deletes" parameter for netconfd-pro dictates that the SIL priority for DELETE operations will be reversed. This parameter can be used to delete leafref nodes with referenced by node in reverse order.If 'false' then the SIL priority will not be reversed. The default is "false".

When the parameter is set to "true" the server will invoke callbacks for the specific objects with "sil-prority" configured in reverse order.

The "sil-prio-reverse-for-deletes" parameter has following facts that should be noted:

• It will NOT change the "sil-priority" of the specific objects, it will instead reverse the "sil-priority" and the server will invoke the callbacks in reverse order

• This parameter will reverse "sil-priority" only if the edit operation is DELETE or REMOVE• The server will not reverse the "sil-priority" for EDIT2 MERGE mode with mixed edits (if there is delete and other

operations). Since the real operation is in the children objects and the server invokes a single callback for all the children edits at once.

Please note that the EDIT2 MERGE edits will not make any effect on the invocation order if the callbacks have mixed operations on children (if there are delete on one child and other edit operation on second child), they will not be reversed anyhow.

The EDIT2 MERGE mode combines multiple edits in one callback and the server invoke just one callback for all the edits. Hence, the server has no any control of when it should reverse the priority for this callback in case of mixed children operations.

The priority in this case will remain the same and the server will warn a user with following warning:

SIL priority for object 'uint16-leaf' set to 100.100Warning: Cannot reverse SIL priority for EDIT2 child 'test:uint16-leaf'

However, in case the EDIT2 MERGE mode has only delete or remove operations on children the priority for this callback will be reversed.

It is recommended to use EDIT1 callbacks to fully control the reverse priority behavior. Or as an alternative it is recommended to avoid the EDIT2 MERGE mode with mixed operations if you want to reverse the priority of the edits.

Also, the server will reverse the edits priorities in case the EDIT2 children edit is the edit to delete or remove the default node. And if there is no any other children edits with not equal to remove or delete, or merge edit operation in case of default node removal.

--sil-prio-reverse-for-deletes parameter



Syntax boolean

Default: false

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro \ --sil-prio-reverse-for-deletes=true

3.115 --sil-root-check-first

The –sil-root-check-first parameter is used to control the order of the YANG validation procedure during edit transaction processing. It affects the <edit-config> operation, but not the <commit> operation.

If 'true', the server will perform a YANG validation check before the SIL validate callbacks are invoked for an edit-config operation. This is always done for a load-config or commit operation.

If 'false', the server will invoke the SIL validate callbacks before performing a YANG validation check. Instead the validation will be done before the SIL apply callback. This is the only behavior in the 17.10 release train.

It is recommended that the default setting be used. This parameter is provided in case existing SIL callbacks depend on the order of the validation processing.

If the <edit-config> operation is used on the candidate datastore then no YANG validation is done unless the “test-option” used is “test-then-set”.

--sil-root-check-first parameter

Syntax boolean

default: TRUE

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro \ --sil-root-check-first=false



3.116 --sil-skip-load

The --sil-skip-load parameter is an empty leaf, specifying whether the SIL edit callback functions will be skipped during system initialization.

Normally the SIL callbacks are invoked when the running datastore is loaded from non-volatile storage. If this parameter ispresent these SIL callback functions will not be invoked during the load_running_config operation.

--sil-skip-load parameter

Syntax empty

default: none (not present)

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro --sil-skip-load

3.117 --sil-test-get-when

The –sil-test-get-when parameter specifies the global default for evaluating when-stmts on operational data nodes during retrieval operations. If 'true', the server will evaluate 'when' statements for GET2 callback requests for config=false nodes. If 'false' then the SIL or SIL-SA callback is expected to test the 'when' condition internally somehow and return a no-instance error if the condition is 'false'.

This parameter can be overridden by the ywx:sil-test-get-when YANG extension. If that extension is found for an operational data node then its value will be used instead of this parameter.

--sil-test-get-when parameter

Syntax boolean

default: false

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro \ --sil-test-get-when=true



3.118 --sil-validate-candidate

The –sil-validate-candidate parameter specifies whether edit transactions on the candidate datastore are validated by the object SIL callbacks or not. If true, then edits to the candidate datastore are validated by SIL callbacks. If false, then edits tothe candidate datastore are not validated by SIL callbacks..

The SIL callbacks will be invoked if an attempt to commit the candidate datastore to the running datastore is done. The onlySIL callbacks that would be skipped are the individual edits to the candidate datastore. If 'true' then the client might be informed of an error sooner. If 'false' then edit processing will be faster.

This parameter has no affect unless the –target parameter is set to “candidate”.

--sil-validate-candidate parameter

Syntax boolean

Default: true

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro \ --sil-validate-candidate=false \ --target=candidate

3.119 --simple-json-names

The –simple-json-names parameter specifies whether the server will output name of the module in which the data node is defined or not.

If false, a namespace-qualified member name will be used for all members of a top-level JSON object and then also whenever the namespaces of the data node and its parent node are different. In all other cases, the simple form of themember name will be used.

The default value is to use strict JSON encoding, based on RFC7951.

--simple-json-names parameter

Syntax boolean

Default: false

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro \ --simple-json-names=true



3.120 --socket-address

The --socket-address parameter specifies the IPv4 address to listen on when the --socket-type parameter is set to 'tcp'. It is ignored if the socket-type is 'aflocal'.

Note that this parameter specifies the IP address for internal <ncx-connect> protocol messages. The server will accept NETCONF sessions over SSH, as specified in the OpenSSH config file.

--socket-address parameter

Syntax inet:ipv4-address

default: 0.0.0.0

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro \ --socket-address=192.168.0.10 \ --socket-type=tcp

3.121 --socket-port

The --socket-port parameter specifies the TCP port number to listen on when the socket-type parameter is set to 'tcp'. Ignored if the socket-type is 'aflocal'.

Note that this parameter specifies the port number for internal <ncx-connect> protocol messages. The server will accept NETCONF sessions over SSH, specified with the 'port' parameter (e.g. 830).";

--socket-port parameter


default: 2023

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro \ --socket-port=8082 \ --socket-type=tcp



3.122 --socket-type

The --socket-type parameter specifies which type of socket the server should create for incoming <ncx-connect> protocol sessions. The “tcp” mode is useful for debugging the packets between thin client (e.g., netconf-subsystem-pro programs). This mode is also required to run sil-sa-app on a different platform than the netconfd-pro process.

This mode is not secure. You should use some system mechanism to control access to the --server-address and --server-port, if this mode is used.

Note that this parameter specifies the socket type for internal <ncx-connect> protocol messages. The server will use TCP connections for NETCONF sessions over SSH.

Two enumeration values are supported:

• aflocal

◦ An AF_LOCAL socket will be used for incoming sessions. The --socket-address and --socket-port parameters will be ignored.

• tcp

◦ An AF_INET socket will be used for incoming sessions. The --socket-address and --socket-port parameters will be used to create a TCP socket.

The “tcp mode” can also be used to distribute the components on different systems than the one running the netconfd-pro server. In this case follow these instructions on the host running the front-end application (e.g. the host running OpenSSH):

Manual configuration for distributed system

> echo IPADDR:PORT > /tmp/netconfd-pro-subsys-info.txt

where IPADDR is the IPv4 address and PORT is the TCP port number

Example using IP address 192.168.0.10 and port 2023:

> echo 192.168.0.10:2023 > /tmp/netconfd-pro-subsys-info.txt

--socket-type parameter

Syntax enumeration

default: aflocal

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro --socket-type=tcp



3.123 --startup

The --startup parameter specifies the file to use to load into the running configuration at boot-time.

The default is to check the data path for the file startup-cfg.xml.

◦ startup

▪ type: string

▪ Specifies the file name of the boot-time configuration. The server expects this to be an XML configuration file. Unless a path specification is included, the $YUMAPRO_DATAPATH environment variable or --datapath parameter will be used to search for the specified file name. No '.xml' extension willbe added. The exact file name will be used instead.

--startup parameter

Syntax filespec

Default: first startup-cfg.xml in the data path

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro \ --startup=$TESTDIR/testrun



3.124 start choice

The --start parameter is a choice, specifying how the netconfd-pro server will load the non-volatile startup configuration atboot-time. If no choice is made at all, then the server will check its data path for the file startup-cfg.xml.

• choice start

◦ no-startup

▪ type: empty

▪ Specifies that no configuration will be loaded at all at boot-time

◦ factory-startup

▪ type: empty

▪ Force the system to use the factory configuration and delete the startup config file if it exists. Force the NV-storage startup to contain the factory default configuration.

◦ startup

▪ type: string

▪ Specifies the file name of the boot-time configuration. The server expects this to be an XML configuration file. Unless a path specification is included, the $YUMAPRO_DATAPATH environment variable or --datapath parameter will be used to search for the specified file name. No '.xml' extension will be added. The exact file name will be used instead.

start choice

Syntax choice: --no-startup --factory-startup --startup=filespec

Default: first startup-cfg.xml in the data path

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro \ --startup=$TESTDIR/testrun



3.125 --startup-error

The --startup-error parameter is an enumeration, specifying how the netconfd-pro server will treat errors encountered while loading the non-volatile startup configuration at boot-time.

• leaf startup-error

◦ type: enumeration (stop or continue)

◦ Specifies if startup configuration errors will be treated as fatal or recoverable errors.

◦ The value 'fallback' will cause the server to restart using the factory-default YANG configuration for the <running> datastore.

--startup-error parameter

Syntax enum: stop continue fallback

Default: stop

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro \ --startup-error=fallback



3.126 --startup-factory-file

The --startup-factory-file parameter specifies the file to use to load into the running configuration at boot-time under the following conditions:

1. first-time boot and no configuration file found

2. --factory-startup CLI option used

3. server is in a factory default restart (--running-error=fallback or –startup-error=fallback)

The default is to check the data path for the file factory-startup-cfg.xml. Specifies the file name of the boot-time configuration. The server expects this to be an XML configuration file. Unless a path specification is included, the $YUMAPRO_DATAPATH environment variable or --datapath parameter will be used to search for the specified file name. No '.xml' extension will be added. The exact file name will be used instead.

If this parameter is set and the filespec is not found then the server will exit with an error. If the default filespec is not found then an empty datastore will be used to load the running configuration datastore at boot-time.

--startup-factory-file parameter

Syntax filespec

Default: first factory-startup-cfg.xml in the data path

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro \ --startup-factory-file=start1.xml



3.127 --startup-prune-ok

The –startup-prune-ok parameter specifies if unknown nodes can be skipped at boot-time.

If set to 'true' then the server will prune unknown data nodes from the startup configuration instead of treating this as an error. A log_info message will be printed. If other known data nodes depend on the pruned nodes, then an error may occur anyway. If so, the 'startup-error' parameter will determine how this is handled.

If set to 'false' then unknown data nodes found in the startup configuration will cause an error.

Unknown data nodes can occur if modules were previously loaded dynamically, or if a YANG feature is configured from enabled to disabled.

--startup-prune-ok parameter

Syntax boolean

Default: FALSE

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro --startup-prune-ok=true



3.128 --startup-skip-validation

The –startup-skip-validation parameter specifies if the YANG validation should be skipped when loading the startup configuration at boot-time.

If set to 'true' then the server will skip all YANG validation of the startup configuration when it is loaded into the running configuration at boot-time. This should make the server boot faster but it assumes the startup configuration is already valid. Only the initial startup load operation is affected by this parameter.

This parameter affects the 'root check' only. This includes the following datastore validation:

• must

• when (see note)

• leafref path

• unique

• min-elements

• max-elements

• mandatory

This parameter does not affect 'default' processing or 'when' statement processing for default nodes. It does affect 'when' statement processing for nodes provided in the startup configuration.

It is possible that any invalid configuration will need to be fixed before any edits can be made to the <running> datastore. The full datastore can be checked using the <validate> operation.

If the startup configuration is completely valid such that all validation tests would have passed, then this parameter should be safe to use. If the startup configuration contains data that does not pass the affected validation tests, then it may not be safe to use this parameter.

This is extremely dangerous and can lead to incorrect processing of datastore editing operations. The server does not validate the complete datastore unless the <validate> operation is used. Any <edit-config> and <commit> operations done on a datastore that contains invalid YANG data may produce incorrect results. It is possible that edits will fail because the server detects invalid nodes from the startup during processing of the requested edit.

The <restore> operation is not affected by this parameter. It is possible to save an invalid configuration that cannot be restored. Use the <validate> operation before using the <backup> operation to ensure a backup configuration can be restored later.

If set to 'false' then startup validation is not skipped.

--startup-skip-validation parameter

Syntax boolean

Default: FALSE

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro --startup-skip-validation=true



3.129 --subdirs

The --subdirs parameter controls whether sub-directories should be searched or not, if they are found during a module search.

If false, the file search paths for modules, scripts, and data files will not include sub-directories if they exist in the specified path.

--subdirs parameter

Syntax boolean

Default: TRUE

Min Allowed: 0

Max Allowed: 1

Supported by: netconfd-proyangdump-pro

Example: netconfd-pro \ --subdirs=false



3.130 --subsys-timeout

The –subsys-timeout parameter indicates the number of seconds to wait for a response from a sub-system before declaring a timeout. The value '0' indicates that no timeout should be used. The default is 30 seconds

--subsys-timeout parameter

Syntax uint16

Default: FALSE

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro --subsys-timeout=0

3.131 --superuser

The --superuser parameter specifies the user name that the netconfd-pro server will treat as the super-user account. The 'root' account should be used with caution. It is strongly suggested that root access be disabled in sshd, and a different account be used as the NETCONF super-user account.

Any NETCONF session started with this user name will be exempt from access control enforcement. This is especially useful if the current ietf-netcon-acm.yang configuration is preventing access to the <nacm> subtree itself. The super-user account can be used in this situation to repair the mis-configured access control rules.

By default, no user will be accepted as the super-user account, if no value is specified.

To disable all super-user account privileges, set this parameter to a zero-length string.

--superuser parameter

Syntax string

Default: none

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro --superuser=admin



3.132 --system-notifications

The --system-notifications parameter specifies the YANG module(s) the server should use for system events such as a new session, configuration change, or capability change.

If 'ietf' is present, then the system notifications from the ietf-netconf-notifications module in RFC 6470 will be generated. This module can be found at netconf/modules/ietf/ietf-netconf-notifications.yang.

If 'yuma' is present, then the system notifications from the yuma-system will be generated. This module can be found at netconf/modules/netconfcentral/iyuma-system.yang.

--system-notifications parameter

Syntax bits

Default: ietf

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro \ --system-notifications='ietf yuma'

3.133 --system-sorted

The --system-sorted parameter specifies whether the server will keep system-ordered lists and leaf-lists in sorted order.

If 'true', then lists and leaf-lists will be maintained in order, based on the list keys, or leaf-list value itself. If 'false', then system ordered entries will be kept in the order they were entered in the database.

All entries are maintained in schema-order (except list keys are ordered first).

THIS PARAMETER IS OBSOLETE. IT IS IGNORED BY THE SERVER.

--system-sorted parameter

Syntax boolean

Default: FALSE

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro --system-sorted=true



3.134 --target

The --target parameter specifies the name of the database that netconfd-pro will use as its edit target. There are two targets supported at this time:

• running: Edits will be written directly to the <running> configuration. The :startup capability will also be used in this mode. This means that a <copy-config> operation (from <running> to <startup>) must be used to save any edits to non-volatile storage, for use on the next reboot.

• candidate: Edits will be written to the <candidate> configuration. The <commit> operation must be used to save any edits in <candidate> configuration into the <running> configuration. The non-volatile storage is updated automatically in this mode, and the <startup> configuration will not be present.

--target parameter

Syntax enumeration: running candidate

Default: candidate

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro --target=running

3.135 --tls-crl-missing-ok

The –tls-crl-missing-ok parameter controls how a missing CRL Distribution Points section in a TLS certificate is handled.

If true then a missing CRL Distribution Points section within a client or CA certificate will be ignored. Not relevant unless tls-crl-mode is set to 'client' or 'ca'. If false, and CRL verification is enabled for the certificate, the TLS session will not be accepted.

Certificate revocation checking is still done, even if this parameter is set to ‘true’. If the ‘netconf-tls-trust-store’ parameter is set, then any ‘hash.rN’ will be loaded into the openssl library and used to reject sessions using a revoked certificate. ( E.g./etc/ssl/certs/5443e9e3.r0)

--tls-crl-missing-ok parameter

Syntax boolean

Default: FALSE

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro –tls-crl-missing-ok=true



3.136 --tls-crl-mode

The –tls-crl-mode parameter controls how Certificate Revocation Lists are checked for NETCONF over TLS sessions.

This has no affect unless --with-netconf-tls=true is set.

• off: Do not use CRL verification when verifying any certificates.

• client: Use CRL verification when verifying client certificates.

• ca: Use CRL verification when verifying client and CA certificates.

--tls-crl-mode parameter

Syntax enum

Default: off

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro –tls-crl-mode=ca

3.137 --trim-whitespace

The –trim-whitespace parameter specifies if whitespace should be trimmed.

If true, then trim leading and trailing whitespace from XML string nodes. If false, adhere to the standard and do not trim any leading or trailing whitespace.

The server previously would trim whitespace but no longer does this by default.

This leaf must be set to trim this whitespace now.

This should only be needed if the NETCONF client does not send XML leaf nodes correctly.

--trim-whitespace parameter

Syntax boolean

Default: FALSE

Min Allowed: 0

Max Allowed: 1




Example: netconfd-pro –trim-whitespace=true



3.138 --usexmlorder

The --usexmlorder parameter specifies that the netconfd-pro server should enforce XML ordering when applicable (such as YANG list key leafs entered first). The default is not to check for adherence to strict XML order, as defined by YANG.

--usexmlorder parameter

Syntax empty

Default: off

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro --usexmlorder

3.139 --version

The --version parameter causes the program version string to be printed, and then the program will exit instead of running as normal.

All YumaPro version strings use the same format:

DEBUG: <major>.<minor>.<svn-build-version>

or

NON-DEBUG: <major>.<minor>-<release>

An example version number that may be printed:

netconfd-pro 2.0-0

This parameter can be combined with the --help parameter.

--version parameter

Syntax empty

Default: none

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro –version



3.140 --warn-error

The --warn-error parameter controls whether all warnings are elevated to errors.

If ‘true’ then warnings that are enabled will be elevated to errors for reporting purporses.

If the –warn-off parameter is entered for a specific error, that warning is considered disabled, and will not be elevated to an error.

--warn-error parameter

Syntax boolean

Default: false

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro --warn-error=true

3.141 --warn-idlen

The --warn-idlen parameter controls whether identifier length warnings will be generated.

The value zero disables all identifier length checking. If non-zero, then a warning will be generated if an identifier is defined which has a length is greater than this amount.

--warn-idlen parameter

Syntax uint32: 0 to disable, or 8 .. 1023

Default: 64

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro --warn-idlen=50



3.142 --warn-linelen

The --warn-linelen parameter controls whether line length warnings will be generated.

The value zero disables all line length checking. If non-zero, then a warning will be generated if a YANG file line is entered which has a length is greater than this amount.

Tab characters are counted as 8 spaces.

--warn-linelen parameter

Syntax uint32: 0 to disable, or 40 .. 4095

Default: 72

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro --warn-linelen=79

3.143 --warn-off

The --warn-off parameter suppresses a specific warning number.

The error and warning numbers, and the default messages, can be viewed with the yangdump-pro program by using the --show-errors configuration parameter.

The specific warning message will be disabled for all modules. No message will be printed and the warning will not count towards the total for that module.

--warn-off parameter

Syntax uint32: 400 .. 899

Default: none

Min Allowed: 0

Max Allowed: 499


Example: netconfd-pro --warn-off=435# revision order not descending



3.144 --warn-up

The --warn-up parameter elevates a specific warning number to an error.

The error and warning numbers, and the default messages, can be viewed with the yangdump-pro program by using the --show-errors configuration parameter.

The specific warning message will be elevated for all modules. An error message will be printed and the warning will be counted towards the error total for that module.

--warn-up parameter

Syntax uint32: 1000 .. 1999

Default: none

Min Allowed: 0

Max Allowed: unlimied


Example: netconfd-pro --warn-up=1022

3.145 --watcher-interval

The –watcher-interval parameter specifies the sleep interval between ypwatcher program attempts to check availability ofthe server. Provided value is in seconds.

The server does not accept the value of 0 for this parameter. The minimal acceptable value is 1 second.

--watcher-interval parameter

Syntax uint32

Default: 10

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro –watcher-interval=60



3.146 --wildcard-keys

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

• Set to 'true' if UrlPath targets for GET operations are allowed to replace key values with the dash '-' character to indicate that all instances of that key are requested.

• Set to false to treat the '-' character as a plain character if entered as a key value in a UrlPath string.

--wildcard-keys parameter

Syntax boolean

Default: FALSE

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro --wildcard-keys=true

3.147 --with-callhome

The --with-callhome parameter controls whether the IETF CallHome over SSH protocol is enabled or not.

--with-callhome parameter

Syntax boolean

Default: FALSE

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro --with-callhome=true



3.148 --with-canonical

The --with-canonical parameter controls automatic conversion to canonical format for certain YANG data types.

If set to 'true', then the server will automatically convert XML and JSON input parameters to the canonical format for the YANG data type, if possible.

The following built-in YANG data types are affected:

• ipv6-address

• ipv6-address-no-zone

• domain-name

• phys-address

• mac-address

• hex-string

• uuid

Any canonical callbacks for user-defined data types are also affected by this parameter.

Internal values can be manually converted to canonical format using the val_set_canonical API.

--with-canonical parameter

Syntax boolean

Default: TRUE

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro --with-canonical=false



3.149 --with-config-id

The --with-config-id parameter controls whether the server will enable or disable the :config-id capability URI in NETCONF <hello> messages.

• If set to 'true', then the YumaWorks :config-id capability will be enabled. This is used to help cache device configurations. It is an enterprise capability URI, not a standard YANG module URI.

• If set to 'false', then the YumaWorks :config-id capability will be disabled.

--with-config-id parameter

Syntax boolean

Default: TRUE

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro \ --with-config-id=false

3.150 --with-db-lock

The –with-db-lock parameter specifies if the DB-Config-Lock mode will be used. If set to 'true', then the server will use the DB-API DB-Config-Lock service for all configuration edit transactions to the <running> datastore. All client edits will be require this lock be granted or it will fail.

The server will use the db-lock-retry-interval and db-lock-timeout CLI parameters to control how lock retries will be done.

If set to 'false', the DB-Config-Lock will not be used by the server.

--with-db-lock parameter

Syntax boolean

Default: FALSE

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro --with-db-lock=true



3.151 --with-gnmi

The --with-gnmi parameter controls whether the gNMI protocol is enabled or not.

--with-gnmi parameter

Syntax boolean

Default: FALSE

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro --with-gnmi=true

3.152 --with-maintenance-mode

The --with-maintenance-mode parameter enables or disables the maintenance mode feature. It does not cause maintenancemode to be active or inactive. If set to 'true', then allow the maintenance mode to be used. Otherwise, ignore all requests to place the server in maintenance mode.

Client protocols cannot activate maintenance mode. This parameter can prevent internal server instrumentation from working properly. Use with caution.

--with-maintenance-mode parameter

Syntax boolean

Default: TRUE

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro \ --with-maintenance-mode=false



3.153 --with-modtags

The --with-modtags parameter controls the module-tag filtering feature.

If set to 'true', then the module tags feature will be enabled. Otherwise, this feature will be disabled.

If disabled, the module-tagmap parameter will be ignored and the ietf-module-tags module will not be loaded.

Note: the ietf-module-tags module is not used yet and is not loaded into the server.

--with-modtags parameter

Syntax boolean

Default: TRUE

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro \ --with-modtags=false

3.154 --with-netconf

The --with-netconf parameter controls whether the server will enable the NETCONF over SSH protocol or not. The incoming NETCONF over SSH connection will be dropped if the protocol is disabled.

--with-netconf parameter

Syntax boolean

Default: TRUE

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro \ --with-netconf=false



3.155 --with-netconf-tls

The --with-netconf-tls parameter controls whether the server will enable the NETCONF over TLS protocol or not. The incoming NETCONF over TLS connection will be dropped if the protocol is disabled.

The default for this parameter is ‘false’ because the server will terminate if the server certificates are not found, but only if this parameter is set to ‘true’.

--with-netconf-tls parameter

Syntax boolean

Default: FALSE

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro \ --with-netconf-tls=true

3.156 --with-nmda

The --with-nmda parameter enables or disables NMDA functionality.

Currently the server fully supports the <get-data> operation from the ietf-netconf-nmda module.

If set to 'true', then NMDA operations and YANG modules will be enabled:

• ietf-datastores

• ietf-origin

• ietf-netconf-nmda

The server does not conform all the NMDA specifications at this time:

• ietf-yang-library module: The new YANG Library (RFC 853=25) is not yet implemented. This may be implemented in the future. It is not really needed until dynamic datastores are standardized and supported.

• <edit-data> operation: This operation has less functionality than <edit-config> and provides no useful features. It is not really needed until dynamic datastores are standardized and supported.

--with-nnda parameter

Syntax boolean

Default: FALSE

Min Allowed: 0



Max Allowed: 1


Example: netconfd-pro \ --with-netconf=false

3.157 --with-notifications

The --with-notifications parameter controls whether the server will support the :notifications and :interleave capabilities or not. To save memory and CPU processing, this parameter can be set to 'false' if notifications are not needed.

--with-notifications parameter

Syntax boolean

Default: TRUE

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro \ --with-notifications=false



3.158 --with-restconf

The --with-restconf parameter controls whether the server will disable the RESTCONF protocol or not. The incoming RESTCONF connection will be dropped if the protocol is disabled.

--with-restconf parameter

Syntax boolean

Default: TRUE

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro \ --with-restconf=false

3.159 --with-rollback-on-error

The --with-rollback-on-error parameter controls rollback during the <edit-config> operation. If set to 'true', then the NETCONF :rollback-on-error capability and feature will be enabled and advertised. Otherwise, this feature will not be enabled or advertised.

--with-rollback-on-error parameter

Syntax boolean

Default: TRUE

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro \ --with-rollback-on-error=false



3.160 --with-ocpattern

The --with-ocpattern parameter controls whether the server will support the OpenConfig usage of the YANG pattern statement.

• If true, then OpenConfig patterns with be checked

◦ If the module name starts with the string 'openconfig-' then all pattern statements within that module are treated as POSIX patterns, not YANG patterns.

◦ Otherwise the module pattern statements will be checked as YANG patterns.

• If false, then the pattern statements in all modules will be checked as YANG patterns.

--with-ocpattern parameter

Syntax boolean

Default: FALSE

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro --with-ocpattern=true

3.161 --with-startup

The --with-startup parameter controls whether the server will support the :startup capability or not. This is a memory intensive capability, and setting this parameter to 'false' will reduce memory usage during normal operations. The non-volatile copy of the <running> configuration will not be saved automatically if this capability is enabled. Instead, a <copy-config>operation from the <running> to <startup> configuration will be needed.

--with-startup parameter

Syntax boolean

Default: FALSE

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro --with-startup=true



3.162 --with-support-save

The --with-support-save parameter controls whether the yumaworks-support-save YANG module will be loaded by the server. If set to 'true', then the yumaworks-support-save module will be loaded and enabled. Otherwise, this module will not be loaded. Ignored if the server image is not built with the WITH_SUPPORT_SAVE=1 compile flag.

--with-support-save parameter

Syntax boolean

Default: TRUE

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro \ --with-support-save=false

3.163 --with-term-msg

The --with-term-msg parameter specifies if the <term-msg> notification should be supported. If set to 'true', then the yumaworks-term-msg module will be loaded and enabled. Otherwise, this module will not be loaded. The <term-msg> notification is used by yp-shell for displaying terminal diagnostic messages.

The server API function agt_make_term_msg can be used by SIL or SIL-SA code to generate a <term-msg> notification.

The yp-shell and yangcli-pro programs will automatically display the <term-msg> as a terminal message if the --with-term-msg parameter is also set to “true” for the client program.

--with-term-msg parameter

Syntax boolean

Default: TRUE

Min Allowed: 0

Max Allowed: 1

Supported by: netconfd-proyangcli-proyp-shell

Example: netconfd-pro \ --with-term-msg=false



3.164 --with-url

The --with-url parameter controls whether the server will support the :url capability or not. This capability requires file system storage.

--with-url parameter

Syntax boolean

Default: TRUE

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro --with-url=false



3.165 --with-url-ftp

The --with-url-ftp parameter controls whether the server will support FTP transfers. If set to 'true', then the 'ftp' protocol scheme will be enabled for the 'url' capability. Ignored if the 'with-url' parameter is false.

--with-url-ftp parameter

Syntax boolean

Default: FALSE

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro –with-url-ftp=true

3.166 --with-url-tftp

The --with-url-tftp parameter controls whether the server will support TFTP transfers. If set to 'true', then the 'tftp' protocol scheme will be enabled for the 'url' capability. Ignored if the 'with-url' parameter is false.

--with-url-tftp parameter

Syntax boolean

Default: FALSE

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro –with-url-tftp=true



3.167 --with-validate

The --with-validate parameter controls whether the server will support the :validate capability or not. This is a memory intensive capability, and setting this parameter to 'false' will reduce memory usage during <edit-config> operations.

--with-validate parameter

Syntax boolean

Default: TRUE

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro --with-validate=false

3.168 --with-warnings

The --with-warnings parameter controls whether the server will allow the <error-severity> field in an <rpc-error> to be set to the value “warning”. If set to 'true', then setting the error-severity field to warning (instead of error) will be enabled. Otherwise, the error-severity field will be set to error, even if the server code tries to set it to warning. This is not compliant with the NETCONF protocol and tools may reject rpc-error data sent with an error-severity value of warning.

--with-warnings parameter

Syntax boolean

Default: FALSE

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro --with-warnings=true



3.169 --with-yang-api

The --with-yang-api parameter controls whether the server will disable the YANG-API protocol or not. Any incoming YANG-API connection will be dropped if the protocol is disabled

--with-yang-api parameter

Syntax boolean

Default: TRUE

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro \ --with-yang-api=false

3.170 --with-yang11-hello

The –with-yang11-hello parameter control whether the NETCONF hello message should conform to the standard and leaveout YANG 1.1 modules.

--with-yang11-hello parameter

Syntax boolean

Default: FALSE

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro \ --with-yang11-hello=true



3.171 --with-yang-patch-running

The --with-yang-patch-running parameter control whether the the YANG-PATCH will be enabled whenthe server supports only the :writable-running capability.

If set to 'true', the YANG-PATCH will be enabled when the server supports only the :writable-running capability. If 'false' then the YANG-PATCH requests will be rejected.

-- with-yang-patch-running parameter

Syntax boolean

Default: FALSE

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro \ --with-yang-patch-running=true

3.172 --with-yp-coap

The --with-yp-coap parameter controls whether the server will disable the YP-CoAP protocol or not. Any incoming YP-CoAP request will be dropped if the protocol is disabled. This protocol is NOT SECURE. It should not be used.

The YP-CoAP protocol is only available in images built from sources, using the WITH_COAP=1 make parameter.

--with-yp-coap parameter

Syntax boolean

Default: FALSE

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro \ --with-yp-coap=true



3.173 --with-yp-coap-dtls

The --with-yp-coap-dtls parameter controls whether the server will disable the YP-CoAP over DTLS protocol or not. Any incoming YP-CoAP over DTLS request will be dropped if the protocol is disabled.

THIS PROTOCOL IS NOT IMPLEMENTED YET.

The YP-CoAP over DTLS protocol is only available in images built from sources, using the WITH_COAP=1 make parameter.

--with-yp-coap-dtls parameter

Syntax boolean

Default: FALSE

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro \ --with-yp-coap-dtls=true



3.174 --with-yp-shell

The --with-yp-shell parameter controls whether the server will disable the YP-SHELL protocol or not. The incoming YP-SHELL connection will be dropped if the protocol is disabled

--with-yp-shell parameter

Syntax boolean

Default: TRUE

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro \ --with-yp-shell=false

3.175 --with-yuma-system

The --with-yuma-system parameter controls whether the yuma-system YANG module will be enabled.

This parameter is default TRUE in 17.10 and FALSE in 18.10. This module is considered deprecated and has been replaced by ietf-system and yumaworks-system.

--with-yuma-system parameter

Syntax boolean

Default: FALSE

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro \ --with-yuma-system=true



3.176 --with-yuma-time-filter

The --with-yuma-time-filter parameter controls whether the yuma-time-filter YANG module will be enabled. This module adds the <if-modified-since> filter to <get> and <get-config> operations.

--with-yuma-time-filter parameter

Syntax boolean

Default: TRUE

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro \ --with-yuma-time-filter=false

3.177 --with-yumaworks-config-change

The --with-yumaworks-config-change parameter controls usage of the yumaworks-config-change YANG module.

If set to 'true', then the yumaworks-config-change module will be loaded and enabled. Otherwise, this module will not be loaded. This modules adds data to the 'netconf-config-change' notification.

This data represents a security risk since it is not subject to the same access control rules within a notification as within a datastore. NACM does not provide access control for the contents of a notification, only for the notification event type. Use this module with caution! Only allow a superuser administrator access to the 'netconf-config-change' notification if this module is used.

--with-yumaworks-config-change parameter

Syntax boolean

Default: FALSE

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro \ --with-yumaworks-config-change=true



3.178 --with-yumaworks-event-filter

The --with-yumaworks-event-filter parameter controls whether the yumaworks-event-filter YANG module will be enabled. This module adds configurable event type filtering for notification delivery.

--with-yumaworks-event-filter parameter

Syntax boolean

Default: TRUE

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro \ --with-yumaworks-event-filter=false



3.179 --with-yumaworks-getbulk

The --with-yumaworks-getbulk parameter controls whether the yumaworks-getbulk YANG module will be enabled. Thismodule provides the <get-bulk> operation for YANG list retrieval.

--with-yumaworks-getbulk parameter

Syntax boolean

Default: TRUE

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro \ --with-yumaworks-getbulk=false

3.180 --with-yumaworks-ids

The --with-yumaworks-ids parameter controls whether the yumaworks-ids YANG module will be enabled. This module provides additional YANG identities for the <transport> leaf in the <session> list in ietf-netconf-monitoring.yang. If disabled, extra sessions such as YControl sessions will not be stored in this list.

--with-yumaworks-ids parameter

Syntax boolean

Default: TRUE

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro \ --with-yumaworks-ids=false



3.181 --with-yumaworks-system

The --with-yumaworks-system parameter controls whether the yumaworks-system YANG module will be enabled. This module provides module/bundle load and unload operations, plus several augmentations to standard modules.

--with-yumaworks-system parameter

Syntax boolean

Default: TRUE

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro \ --with-yumaworks-system=false

3.182 --with-yumaworks-templates

The --with-yumaworks-templates parameter controls whether the yumaworks-templates YANG module will be enabled. This module provides configuration templates and the <with-template> parameter added to the <edit-config> operation.

--with-yumaworks-templates parameter

Syntax boolean

Default: TRUE

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro \ --with-yumaworks-templates=false



3.183 --yangapi-server-url

The --yangapi-server-url parameter specifies the starting string for the server URL to use in Location header lines returnedby YANG-API.

--yangapi-server-url parameter

Syntax inet:uri

Default: http://localhost

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro \ --yangapi-server-url= \ https://device1.example.com



3.184 --yumapro-home

The --yumapro-home parameter specifies the project directory root to use when searching for files.

If present, this directory location will override the '$YUMAPRO_HOME environment variable, if it is set. If this parameter is set to a zero-length string, then the $YUMAPRO_HOME environment variable will be ignored.

The following directories are searched when either the $YUMAPRO_HOME environment variable or this parameter is set:

• $YUMAPRO_HOME/modules

◦ This sub-tree is searched for YANG files.

• $YUMAPRO_HOME/data

◦ This directory is searched for data files.

• $YUMAPRO_HOME/scripts

◦ This directory is searched for yangcli-pro script files.

--yumapro-home parameter

Syntax string: directory specification

Default: $YUMAPRO_HOME environment variable

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro \ --yumapro-home=~/sw/netconf \ --log=~/server.log&



3.185 --yp-coap-address

The --yp-coap-address parameter specifies the IP address that the YP-CoAP protocol will use to listen for incoming requests. This will also be used as the source address in YP-CoAP packets sent by the server.

The YP-CoAP protocol is NOT SECURE. It should not be used.


--yp-coap-address parameter

Syntax inet:ip-address

Default: 0.0.0.0

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro \ --yp-coap-address=192.168.0.100

3.186 --yp-coap-dtls-port

The --yp-coap-dtls-port parameter specifies the UDP port number that the YP-CoAP over DTLS protocol will use to listen for incoming requests for CoAP over DTLS. This will also be used as the source port number in YP-CoAP packets sent by the server.

THIS PARAMETER IS NOT YET IMPLEMENTED!


--yp-coap-dtls-port parameter


Default: 5684

Min Allowed: 0

Max Allowed: 1


Example: netconfd-pro \ --yp-coap-dtls-port=12904


Documents

YumaPro netconfd-pro Manual - Home - YumaWorks...YumaPro netconfd-pro Manual 3.31 --datapath.....247 3.32 --db-lock-retry